Drop‑in JSON firewall for AI & partner data pipelines
Turns noisy / malformed / risky JSON into clean, validated, policy‑compliant, metered objects — only bills when an LLM rescue is truly needed.
Think of every incoming JSON blob (from an LLM, partner feed, or user) as a “cell” entering your system.
AIS behaves like a lightweight immune system:
| Immune Concept | AIS Step | Purpose (Plain Language) |
|---|---|---|
| Innate barrier | Fast parse + deterministic repair | Instantly fix obvious cuts & scrapes (typos, stray commas) for free. |
| Pattern check (PAMPs) | JSON Schema validation | Reject shapes that don’t belong before they spread. |
| Redaction (masking) | Sensitive field stripping | Hide secrets before deeper inspection so they never leak. |
| Adaptive response | Guarded LLM fallback | Only call the “specialist” (LLM) if the quick defenses failed. |
| Antibodies | Re‑validation of LLM output | Ensure the specialist’s result really fits the schema. |
| Quarantine | REJECT / QUARANTINE decision | Isolate stuff that cannot be safely repaired. |
| Immune memory | Canonical hash + provenance | Remember exactly what was seen & how it was fixed. |
| Vital signs | Metrics & logs | Observe health: how many infections (repairs), how many escalations (LLM). |
| Energy budget | Metered billing per fallback | You only “spend calories” when adaptive response triggers. |
Plain version: AIS quietly fixes most broken JSON instantly. Only when that fails does it (optionally) escalate to an LLM under strict rules and then double‑checks the result. You get clean, safe objects or a clear, contained rejection — plus a receipt of what happened.
Why this matters:
- Prevents ad‑hoc regex & scattered validation drift.
- Cuts LLM spend by handling the easy 80–90% deterministically.
- Reduces risk: sensitive data is removed before model calls.
- Gives you audit trails & usage-based cost alignment.
You pay (metered) only when the adaptive layer (LLM fallback) actually succeeds and returns value.
Pipeline
- Parse & deterministic repair (jsonrepair)
- Schema validate (JSON Schema 2020-12 + custom keywords)
- Conditional LLM fallback (guarded: temp=0, JSON-only, redacted)
- Re‑validate & provenance stamp (CID / optional signature)
Security & Policy
Field & wildcard redaction, host allow‑lists via Rego/OPA, prompt residue scrubbing, signature-ready provenance.Billing & Quotas
Per‑tenant free quota + metered Stripe usage (fallback successes only), overrideable per tenant.Observability
Prometheus metrics, structured redacted logs, repair provenance trail.DX
CLI (`ais`), Python client (`pip install ais-client`), simple REST endpoints, minimal env surface.Click the Codespaces badge above or this link to launch a pre-configured dev container (installs deps & builds automatically).
When it opens:
npm run devVisit: https://YOUR-CODESPACE-URL-8088.app.github.dev/healthz
git clone https://github.com/Maverick0351a/ai-immune-system.git
cd ai-immune-system
cp .env.example .env
echo "TEST_API_KEY=demokey-123" >> .env
npm i
npm run init-db
npm run dev &
# Deterministic repair (no LLM spend)
curl -s http://127.0.0.1:8088/v1/immune/run \
-H "X-API-Key: demokey-123" -H "Content-Type: application/json" \
-d '{"schema":{"type":"object","properties":{"amount":{"type":"number"}},"required":["amount"]},"json":"{amount: \"42\"}"}' | jqdocker run --rm -p 8088:8088 ghcr.io/maverick0351a/ai-immune-system:latestThen:
curl -s http://127.0.0.1:8088/healthznpx degit Maverick0351a/ai-immune-system my-ais
cd my-ais && npm i && npm run devAdd an OpenAI key in .env to enable fallback: OPENAI_API_KEY=sk-...
curl -s http://127.0.0.1:8088/v1/immune/run \
-H "X-API-Key: demokey-123" -H "Content-Type: application/json" \
-d '{"schema":{"type":"object","properties":{"amount":{"type":"number"}},"required":["amount"]},"json":"{amount: '42'}"}'from ais_client import AISClient
client = AISClient(api_key="demokey-123", base_url="http://127.0.0.1:8088")
res = client.run(
schema={"type":"object","properties":{"amount":{"type":"number"}},"required":["amount"]},
data={"amount": "42"}
)
print(res.ok, res.data)const resp = await fetch("http://127.0.0.1:8088/v1/immune/run", {
method: "POST",
headers: {"Content-Type":"application/json","X-API-Key":"demokey-123"},
body: JSON.stringify({
schema: { type: "object", properties: { amount: { type: "number" } }, required: ["amount"] },
json: "{amount: '42'}"
})
});
console.log((await resp.json()).final.amount);| Tier | Included | Overages (example config) |
|---|---|---|
| Free | Unlimited deterministic + 25 LLM fallbacks/mo | – |
| Pay‑as‑you‑go | + On‑demand fallbacks | $0.008 / fallback |
| Pro (sample) | 1,000 fallbacks / mo | $0.006 thereafter |
Metering counts only successful LLM repairs after deterministic + schema attempts fail. You own product & price configuration in Stripe.
Headers: X-API-Key: <tenant>, Content-Type: application/json
Request (minimal):
Example response:
{
"decision": "ACCEPT_WITH_REPAIRS",
"repairs": ["jsonrepair"],
"final": {"amount": 42},
"cid": "sha256:...",
"usage": {"llmFallbacksBilled": 0}
}Failure modes: REJECT, QUARANTINE, or ERROR if unrecoverable.
| Variable | Purpose |
|---|---|
| OPENAI_API_KEY | Enables guarded LLM fallback |
| OPENAI_MODEL / OPENAI_FALLBACK_MODEL | Primary / secondary model IDs |
| OPENAI_TIMEOUT_MS | Hard timeout for LLM request |
| LLM_DEBUG | Verbose fallback logging when set (e.g. "1") |
| STRIPE_API_KEY / STRIPE_METERED_PRICE_ID | Enable usage metering to Stripe |
| FREE_TIER_FALLBACKS | Override global free fallback quota |
| ADMIN_TOKEN | Protects admin endpoints |
| TEST_API_KEY | Seed tenant key during init |
Incoming JSON / Partner Feed / LLM Output
│
Parse + Deterministic Repair
│ (fast, free)
JSON Schema Validate
│ │
│ success │ fail
│ ▼
│ Redact Sensitive Fields
│ │
│ Guarded LLM Fallback (temp=0, JSON-only)
│ │
└───────────┴─► Re-Validate
│
Provenance (CID + optional signature)
│
Usage Meter (if LLM used)
│
Response
- Tiered pricing helper scripts
- Webhook-driven subscription state sync
- Optional local model fallback mode
- Extended secret classification plugins
Minimal steps:
- Install Fly CLI:
curl -L https://fly.io/install.sh | sh fly launch --no-deploy(accept existing fly.toml)- Create volume:
fly volumes create data --size 1 --region iad - Set secrets:
fly secrets set OPENAI_API_KEY=... STRIPE_API_KEY=... STRIPE_METERED_PRICE_ID=... ADMIN_TOKEN=... TEST_API_KEY=demokey-123
- Deploy:
fly deploy
fly.toml sets DATABASE_URL=file:/data/ais.db and mounts the volume at /data. SQLite runs in WAL mode; single instance recommended initially. Scale later after migrating to a network database.
Prometheus metrics exposed at /metrics; health at /healthz.
Hardening checklist:
- Rotate ADMIN_TOKEN regularly.
- Restrict inbound with Fly IP allow lists or an auth proxy if multi-tenant external exposure.
- Migrate rate limiting + cache to Redis/Turso if scaling >1 instance.
- Add HTTPS-only forward policies with POLICY_PROFILE=rego.
- Enable off-site backups: e.g. schedule
fly ssh console+sqlite3 /data/ais.db .backup /data/backup/ais-$(date +%F).dband sync to object storage (Litestream or LiteFS for continuous replication when ready).
Metrics additions:
rate_limited_requests_totalfor 429 monitoring.- Existing
requests_total,llm_fallback_total,repair_duration_seconds.
PRs welcome. For major extensions (new policy engines, billing providers) open an issue first. Keep security-impacting diffs tight & well documented.
Apache 2.0
© 2025 Odin Secure / AI Immune System
{ "schema": {"type":"object","properties":{"amount":{"type":"number"}},"required":["amount"]}, "json": "{amount: '42'}" }