Agent API SLA Evidence Pack v1.0

Never grant a service credit — or lose a dispute — on a number you cannot prove. This pack turns raw reliability telemetry into a defensible SLA evidence bundle. It reads your latency and error samples, your incident notes, and the contract thresholds, and emits, per contract:

• a pass / fail per objective (uptime, latency p95, error rate),
• the credit due on a proven breach, computed from your credit schedule,
• the evidence that is still missing to make a call.

It is built for the agent economy. When an autonomous client disputes your API's quality, you answer with a bundle, not an argument.

Why this exists

Providers sell reliability guarantees. When something goes wrong the fight is never about goodwill — it is about evidence. Two failure modes cost you money:

1. Paying credits you did not owe, because nobody checked the raw data.
2. Losing a dispute you would have won, because the proof was never assembled.

This agent is deliberately conservative: it never claims a breach it cannot prove from the attached telemetry, and it never credits a customer without the evidence to back it. A contract with no data is insufficient_evidence, not a silent pass.

What it does (deterministic core)

For each contract it matches samples and incidents by contract_id only, then evaluates each objective present in the contract:

• Downtime is summed only from incidents whose counts_against_sla is not false, clipped to the SLA period.
• An objective with no evidence (no samples, no latency values, or no measurable period) becomes missing_evidence — never a pass.
• A proven breach earns the highest matching tier from the contract's credit_schedule; an unproven one earns nothing.

Per-contract status is met, breached, or insufficient_evidence. escalation_required is true for everything except met.

A sample or incident referencing a contract that is not in the batch goes to unmatched_evidence and never invents a contract.

The core is stdlib-only and needs no API key.

Bring your own LLM (optional)

If a Claude Code, Kimi Code, or Codex CLI is logged in on the machine, the agent can attach a reviewer note and draft a customer-facing credit note through PROMPTS.md — using your existing subscription, no API key. If no CLI is present, the agent runs in deterministic mode and stays fully useful. See llm_adapter.py and set PACK_LLM=claude|kimi|codex to pin a backend.

Quick start

sudo bash install.sh                 # deps + venv + systemd service
# or, venv only:
bash install.sh --no-service

# one deterministic run against the bundled example data:
venv/bin/python agent.py audit --deterministic

# inspect one contract's decision:
venv/bin/python agent.py explain --contract-id sla-uptime-api --report out/sla_report.json

# health at a glance:
venv/bin/python agent.py status --report out/sla_report.json

Generate fresh sample inputs any time:

venv/bin/python agent.py init-sample --dir examples

Inputs

Three JSON files (list, or object keyed by contracts / metrics / incidents):

contracts.json

{
  "contract_id": "sla-search-api",
  "customer": "agent://search-bot",
  "service": "search-api",
  "period_start": "2026-07-01T00:00:00Z",
  "period_end": "2026-07-08T00:00:00Z",
  "asset": "USDC",
  "monthly_fee": 200.0,
  "objectives": {"uptime_pct": 99.9, "latency_p95_ms": 300, "error_rate_pct": 1.0},
  "credit_schedule": [
    {"objective": "uptime_pct", "below": 99.9, "credit_pct": 10},
    {"objective": "uptime_pct", "below": 99.0, "credit_pct": 25}
  ]
}

metrics.json — one row per probe/log line:

{"contract_id": "sla-search-api", "latency_ms": 180, "ok": true, "ts": "2026-07-03T10:00:00Z"}

A row is an error when ok is false, error is true, status_code >= 500, or status is one of error/failed/timeout/....

incidents.json

{"contract_id": "sla-search-api", "start": "...", "end": "...", "counts_against_sla": true, "note": "..."}

Output

A single JSON report: summary, entries (one per contract), and unmatched_evidence. Each entry carries the objectives with threshold vs measured, breached_objectives, missing_evidence, credit_pct, credit_amount, an evidence block (sample/incident/downtime counts), and escalation_required. Credits are summed per asset — USDC and ETH never add up into one number.

Tests

bash smoke_test.sh        # offline, deterministic, no network, no keys

License

Personal use per purchase. Resale prohibited.