| title | Agentic Tool-Call Firewall |
|---|---|
| emoji | 🛡️ |
| colorFrom | indigo |
| colorTo | gray |
| sdk | gradio |
| sdk_version | 5.29.0 |
| app_file | app.py |
| pinned | true |
| license | apache-2.0 |
| short_description | Blocks hallucinated LLM tool calls before DB write |
A deterministic supervisor that sits between an autonomous LLM agent and enterprise APIs.
The AI thinks. This engine decides whether that thought becomes action.
Built for Fortune 500 AI Governance. The "adult supervision" for the AI gold rush.
Every enterprise considering agentic AI faces the same blocker:
"We cannot let an LLM autonomously close QMS deviations, execute ERP transactions, or update patient records — because LLMs hallucinate function parameters."
A single hallucinated foreign key closing the wrong manufacturing deviation triggers a federal audit.
A type coercion bug in a financial trade execution costs millions.
There is no undo button on a corrupted LIMS database.
LLM Agent Output (JSON Tool Call)
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ engine.py (AgenticFirewall) │
│ │
│ LAYER 1 — JSON Syntax Check │
│ Catches: truncated JSON, unclosed brackets, escape errors │
│ │
│ LAYER 2 — Pydantic Schema Validation │
│ Catches: wrong types (string→bool), missing required fields, │
│ invalid ID format, tool not in allowlist │
│ │
│ LAYER 3 — Deterministic Business Logic │
│ Rule A: Referential integrity — does the DB record exist? │
│ Rule B: State machine — valid state transition? │
│ Rule C: Cross-field logic — CAPA dependency satisfied? │
│ Rule D: RCA attestation — root cause analysis complete? │
│ │
│ All rules evaluated in < 5ms. Zero probabilistic logic. │
└──────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
EXECUTE_API_CALL BLOCK_AND_RETURN_ERROR_TO_LLM
(downstream DB write) (structured error → LLM context)
│ │
└──────────┬───────────────────┘
▼
AgenticAuditTrail (JSON)
→ SIEM / 21 CFR Part 11 DB
| Failure Mode | Example | Layer | Consequence if Unchecked |
|---|---|---|---|
| Hallucinated foreign key | DEV-2026-9999 doesn't exist in QMS |
L3-A | Phantom record creation / silent no-op |
| State machine violation | Close an already-CLOSED deviation | L3-B | Duplicate closure event, audit finding |
| Cross-field logic conflict | capa_required=true but capa_id=null |
L3-C | CAPA orphaned, regulatory gap |
| Type coercion | "root_cause_identified": "yes" |
L2 | Silent boolean cast, attestation bypassed |
| Malformed JSON | Truncated output, unclosed bracket | L1 | Raw string written to DB field |
{
"schema_version": "1.0",
"firewall_version": "1.0.0",
"execution_id": "f4a2c819-...",
"timestamp_utc": "2026-05-13T18:00:00+00:00",
"ai_agent_id": "gpt-4o-qms-agent-v2",
"tool_name_requested": "close_qms_deviation",
"raw_llm_payload_sha256": "a3f9c12e...",
"schema_validation": "VALID",
"business_logic_evaluations": [
{"rule_id": "L3A_REFERENTIAL_INTEGRITY", "result": "PASS", "details": "Record DEV-2026-0101 confirmed."},
{"rule_id": "L3B_STATE_MACHINE", "result": "PASS", "details": "State transition valid: OPEN → CLOSED."},
{"rule_id": "L3C_LOGIC_DEPENDENCY", "result": "FAIL", "details": "capa_required=True but capa_id is null. Logic conflict."},
{"rule_id": "L3D_RCA_ATTESTATION", "result": "PASS", "details": "Root cause analysis attested as complete."}
],
"terminal_status": "BLOCK_AND_RETURN_ERROR_TO_LLM",
"error_returned_to_llm": "capa_required=True but capa_id is null. Logic conflict.",
"execution_metadata": {"runtime_ms": 1.847, "peak_ram_mb": 52.3}
}| Document | Description | Framework |
|---|---|---|
IQ_Report.md |
Installation Qualification — dependencies, schema hash, smoke test | GAMP 5 IQ |
OQ_AI_Hallucination_Interception.csv |
OQ matrix — 5 failure mode categories, block/pass verification | GAMP 5 OQ |
GAMP5_AI_Validation_Trace.md |
Full GAMP 5 Appendix D11 alignment — validates the boundaries around the LLM | GAMP 5 / 21 CFR |
git clone https://github.com/j-arndt/certified-agentic-firewall
cd certified-agentic-firewall
pip install -r requirements.txt
pip install "gradio>=5.0.0" # managed by sdk_version on HF Spaces
# CLI: run all 4 test scenarios
python engine.py
# UI
python app.py
# → http://localhost:7860pydantic>=2.9.0
psutil>=5.9.8
Gradio managed via sdk_version: 5.29.0 on HuggingFace Spaces.
Python >= 3.10 | No GPU | No external APIs | Runs air-gapped
You cannot validate a probabilistic LLM. You validate the deterministic boundaries surrounding it. — GAMP 5 Second Edition, Appendix D11 (AI/ML Systems)
| Concern | Direct LLM → API | This Firewall |
|---|---|---|
| Hallucinated IDs executed? | Yes | Never — L3A blocks |
| Type coercion silently passed? | Yes | Never — L2 blocks |
| State machine violations? | Yes | Never — L3B blocks |
| Audit trail for regulators? | None | Full 21 CFR Part 11 JSON |
| Latency overhead | 0ms (no check) | < 5ms |
| Regulatory defensibility | Zero | IQ/OQ documented |
Apache 2.0 — see LICENSE
18+ years GxP / CSV / QA | 10 years Lancaster General Health / Penn Medicine
GitHub