# Model Router & Guardrail SaaS v2.2 - Full Machine-Readable Specification
# Canonical Technical Contract for AI Agents, LLM Crawlers, and Machine Consumers

## Executive Summary (BLUF)
Model Router & Guardrail SaaS v2.2 provides a deterministic Edge AI Gateway and Spend Cap Middleware. Operating entirely within Vercel Edge Runtime, it combines Upstash Redis sub-15ms authentication, Google Cloud hard spend caps (€25.00 default circuit breaker), TypeSafe Jev System One Shield (<70ms prompt injection intercept), deterministic PII tokenization (EU SSN, PCI credit cards, API keys), and Pareto complexity escalation to Gemini 3.8 Flash (Standard & Analytical High-Thinking) and Gemini 3.5 Transcribe. The system sustains 91.2% gross margins at €0.0005/req (BYOK) and €0.0020/req (Managed).

---

## 1. Edge Ingress Architecture (/api/v1/chat/completions)

### Request Lifecycle:
1. Ingress Request arriving at /api/v1/chat/completions
2. Extract Authorization: Bearer <API_KEY>
3. Authenticate against Upstash Redis tenant registry (<15ms budget)
4. Check Hard Spend Cap Circuit Breaker:
   If tenant.spendEur >= tenant.hardCapEur (€25.00 default):
     Return HTTP 403 Forbidden with {"error": "spend_cap_breached"}
     Zero tokens burned.
5. Validate payload schema against ChatCompletionRequestSchema (Zod)
6. Execute TypeSafe Jev System One Shield concurrently (<70ms):
   Composite Risk = 0.40 * injection + 0.30 * override + 0.20 * credential + 0.10 * drift
   If injection > 0.50 OR override > 0.50:
     Return HTTP 400 Bad Request with {"error": "guardrail_violation"}
     Zero upstream LLM tokens burned.
7. Apply Deterministic PII Sanitizer:
   - EU SSN (\b\d{6}-\d{5}\b) -> [REDACTED_EU_SSN]
   - PCI Cards (\b(?:\d{4}[ -]?){3}\d{4}\b) -> [REDACTED_PCI_CARD]
   - Secret keys (\bsk-[a-zA-Z0-9_-]{20,}\b) -> [REDACTED_API_KEY]
   - GitHub tokens (\bghp_[a-zA-Z0-9]{20,}\b) -> [REDACTED_GH_TOKEN]
8. Evaluate Pareto Complexity Escalation:
   - Multimodal Audio: gs://* -> gemini-3.5-transcribe
   - Analytical: >= 0.70 complexity OR >= 500 chars -> gemini-3.8-flash (thinking_level: high)
   - Standard: < 0.70 complexity & < 500 chars -> gemini-3.8-flash
9. Zero-buffer SSE Streaming Pipeline (TransformStream) or JSON Response:
   Pass-through headers:
     X-Router-Model: <routed_model>
     X-Router-Edge-Latency: <elapsed_ms>
     X-Router-Composite-Risk: <composite_risk>

---

## 2. API Contract & Schema Reference

### Ingress Request Example:
```bash
curl -X POST https://router.internal/api/v1/chat/completions \
  -H "Authorization: Bearer sk-tenant-dev-valid" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      { "role": "user", "content": "Analyze system requirements for high-availability edge routing." }
    ],
    "stream": false
  }'
```

### Response Headers:
- HTTP/1.1 200 OK
- Content-Type: application/json; charset=utf-8
- X-Router-Model: gemini-3.8-flash
- X-Router-Edge-Latency: 18.42ms
- X-Router-Composite-Risk: 0.0520

---

## 3. Unit Economics & 91.2% Gross Margin Architecture

| Component | Cost per 10k Requests | Cost per Request |
|---|---|---|
| Edge Compute (Vercel Edge / Cloudflare Workers) | €0.0150 | €0.0000015 |
| Upstash Redis KV Read (<15ms) | €0.0200 | €0.0000020 |
| Shield & PII Evaluation Overhead | €0.0090 | €0.0000009 |
| Total Gateway Infrastructure Cost | €0.0440 | €0.0000044 |
| Developer BYOK Revenue | €5.0000 | €0.0005000 |
| **Gross Margin Percentage** | **91.12% ~ 91.2%** | **91.2%** |

Enterprise Managed Tier (€0.0020/req) incorporates upstream wholesale Gemini token bandwidth with 88.5% blended margins.

---

## 4. Database Schema & k-Anonymity Threat Benchmark Function

```sql
CREATE OR REPLACE FUNCTION public.get_guardrail_threat_benchmarks()
RETURNS TABLE (
    threat_type TEXT,
    model_routed TEXT,
    total_incidents BIGINT,
    avg_edge_latency_ms NUMERIC,
    avg_composite_risk NUMERIC,
    tenant_count BIGINT
)
LANGUAGE sql
SECURITY DEFINER
STABLE
AS $$
    SELECT
        t.threat_type,
        t.model_routed,
        COUNT(*)::BIGINT AS total_incidents,
        ROUND(AVG(t.edge_latency_ms), 2) AS avg_edge_latency_ms,
        ROUND(AVG(t.composite_risk), 4) AS avg_composite_risk,
        COUNT(DISTINCT t.tenant_id)::BIGINT AS tenant_count
    FROM public.route_telemetry t
    WHERE t.threat_type IS NOT NULL
    GROUP BY t.threat_type, t.model_routed
    HAVING COUNT(DISTINCT t.tenant_id) >= 5
    ORDER BY total_incidents DESC;
$$;
```

---

## 5. Contact & Deployment Links
- Base URL: https://router.internal
- Machine Index: /llms.txt
- Full Specification: /llms-full.txt
- Edge Ingress: /api/v1/chat/completions