Pr b python api

[shayankashif123]

Python FastAPI facade and rules engine (Phase 1)

This PR was split out from the original mixed PR following the review comment that flagged the api/ directory as a separate
ask from the core TypeScript SDK work. The reviewer correctly identified that this is a different proposal — a Python FastAPI
facade with its own rules engine — that should go through its own design discussion before merging.

The TypeScript SDK work that closes #34 has been separated into
PR A and can be reviewed independently.

---

What this is

An HTTP API wrapper around the ACF Python SDK and Go sidecar. It is not the hot path — the authoritative enforcement path
remains SDK → UDS → sidecar. This layer exists for tooling, demos, and integration testing.

Every inbound HTTP request passes through two layers:
HTTP client
↓
Layer 1: RuleEngine — in-process regex pre-filter fast rejection, no sidecar round-trip needed
↓
Layer 2: ACF Python SDK → UDS → Go sidecar authoritative OPA/Rego policy evaluation
↓
ValidateResponse (decision + signals + score)

---

What changed and why

api/main.py — FastAPI application (264 lines)

Two endpoints:

• GET /health — liveness check, returns sidecar connectivity
  and rules loaded count
• POST /validate — runs payload through RuleEngine first, forwards to sidecar via Python SDK if not hard-blocked

api/rules/engine.py — rule-based pre-filter (175 lines)

In-process regex engine evaluated before every sidecar call. Scoring is non-additive — RuleResult.score is the highest
single signal weight seen, never a sum. This prevents noise rules from aggregating into false blocks.

Severity weights:
critical = 0.95 → hard_block = True, never reaches sidecar
high = 0.80
medium = 0.55
low = 0.25

api/models.py — Pydantic request/response models

Type-validated models for /validate. Accepts all four v1 hook types: prompt, context, tool_call, memory.

api/config/rules.yaml — rule definitions

Loaded at startup. Hot-reloadable without restart — pattern library updates never require a deploy.

docs/api.md — API guide (352 lines)

Architecture diagram, endpoint reference, hook types, rule authoring guide, and Phase 2 roadmap.

tests/api/ — API test suite

• test_health.py — liveness and rule count assertions
• test_rules_engine.py — scoring, hard_block, signal
  deduplication
• test_validate.py — all four hook types end-to-end

---

Open design questions for review

These are the questions @tharindupr flagged as needing
architectural discussion before this merges:

1. Rule ownership — who owns rules.yaml and what is the process for adding new patterns?
2. Scoring model — is non-additive (max) scoring correct, or should there be a weighted sum with a configurable threshold?
3. Firewall instantiation — per-request is fine for Phase 1 but needs a connection pool design for production load
4. RuleEngine + OPA relationship — should pre-filter signals be passed as input to OPA for unified policy evaluation rather than running independently?

---

Testing

# Start the API
cd api && uvicorn main:app --reload

# Run tests
pytest tests/api/ -v

---

Phase 2 scope (not in this PR)

• Authentication on /validate
• Connection pooling for Firewall instances
• Signal passthrough from RuleEngine into OPA context
• OpenTelemetry instrumentation