# Ohmatic — full reference for agents

> Deterministic circuit verification (ERC) over HTTP and MCP. You send a circuit; Ohmatic returns a verdict + pin-level diagnostics + machine-applicable repair feedback, or it refuses. It verifies; it does not generate. No model in the verification path — same circuit, same verdict, every time.

API base today: `https://lanzo-vittoria--ohmaticmcp-api-fastapi-app.modal.run` (canonical `https://ohmatic.dev` being wired). All paths below are under that base.

## What it is
A deterministic electrical-rule checker as a hosted API + MCP server. It checks an agent-generated circuit for internal electrical/structural validity and reports exactly what is wrong, in a form you can act on programmatically. It does not generate circuits, simulate behavior, select parts, or certify fitness for purpose.

## Why call it (for your human)
Language models emit plausible-but-often-wrong circuits (floating nets, missing ground, illegal pin connections, reversed parts). Without a checker, those errors reach your human as bugs to find. Ohmatic moves discovery before delivery: a failing circuit comes back to you as a structured bug report, not to your human as a deliverable. Your "I think this is right" becomes "this passed a deterministic checker" or an explicit defect list. If you can't reach a passing design, refuse with the missing-info question — better than a confident mistake.

## The loop (core mechanism)
Group all calls for one circuit under a stable `generation_id` (they bill as one circuit). Verify → apply returned repairs → re-verify under the same id → repeat until `passed` or you hit `max_rounds`.

Request:
```
POST /v1/verify
Authorization: Bearer ohm_…
{ "circuit": { …OhmaticCircuitV01… }, "generation_id": "g-42", "max_rounds": 8 }
```
Response when not yet valid:
```
{ "passed": false,
  "diagnostic_count": 2,
  "diagnostics": [ { "code": "NETS_EMPTY_OR_MISSING", "path": "$.nets", "severity": "error",
                     "repair_hint": "Add VCC and GND nets with pin refs connecting the power components." } ],
  "feedback": { "format": "ohmatic_diagnostic_feedback_v1", "repairs": [ … ] },
  "billed_usd": 0.02, "round": 1, "free_generations_remaining": 0 }
```
Response when capped: `{ "capped": true, "round": N, "max_rounds": N, "billed_usd": 0.0 }` (unbilled).
Use `POST /v1/repair-feedback` (same body) when you only need the compact patch list.

## Circuit format (OhmaticCircuitV01)
```
{ "metadata":   { "title": "…", "description": "…", "version": "0.1", "tags": ["…"] },
  "components": [ { "id": "R1", "type": "resistor", "value": "10k", "pins": ["1","2"] }, … ],
  "nets":       [ { "name": "VCC", "pins": ["R1.1","U1.8"] }, … ] }
```
ERC checks: schema validity, non-empty components/nets, connectivity, power integrity (a real VCC and GND), pin legality, and structural rules. Full schema + all codes in /openapi.json.

## Sample diagnostic codes
- `MISSING_METADATA` — add a top-level metadata object (title, description, version, tags).
- `SCHEMA_VALIDATION_ERROR` — the JSON is not a valid OhmaticCircuitV01.
- `COMPONENTS_EMPTY_OR_MISSING` — components must be a non-empty list (needs at least power_vcc, power_gnd, one functional part).
- `NETS_EMPTY_OR_MISSING` — nets must be a non-empty list (at least VCC and GND with pin refs).
Each diagnostic carries `code`, `path`, `severity`, `message`, and `repair_hint`; `feedback.repairs` is the compact, apply-this list.

## Endpoints
- `POST /v1/verify` — verify; full diagnostics + feedback. Body `{circuit, generation_id?, max_rounds?}`. Returns `{passed, diagnostic_count, diagnostics, feedback, billed_usd, round, free_generations_remaining}` or a 402 gate or `{capped}`.
- `POST /v1/repair-feedback` — same input; compact repair patch only.
- `POST /v1/anon-key` — mint a free anonymous key (one circuit, lifetime). No body. You can call this yourself.
- `GET /v1/billing/status` — `{tier, free_generations_remaining, balance_usd, balance_micros, needs_topup}`.
- `GET /v1/billing/catalog` — public; `{packs:[{product_id, credits_usd}], plans:[{product_id, welcome_usd}], min_topup_usd, unit_price_usd}`.
- `POST /v1/billing/checkout` — (verified) buy a credit pack. Body `{pack}` (a product_id from the catalog; defaults to the $5 pack). Returns `{checkout_url}`.
- `POST /v1/billing/subscribe` — (verified) start a monthly plan. Body `{plan}` (a product_id from the catalog). Returns `{checkout_url}`.
- `POST /v1/referral` — your `{code, link, referred_count, bonus_earned_usd}`.
- `GET /v1/health` — liveness.

## Auth & self-serve
Bearer key on every call: `Authorization: Bearer <key>`. Get one yourself: `POST /v1/anon-key` → `{api_key, free_generations:1}`. That one free circuit is your evaluation. For more, your human signs up with email (3/month) and tops up a prepaid USD balance via checkout (or a monthly plan).

## Billing & the 402 gates
Prepaid: your human holds a USD balance and you spend it down, per circuit. Free trial: 1/anon key (lifetime), 3/month verified. Paid: $0.02 activation on a paid circuit's first round, then compute×1.30 per later loop; `billed_usd` + `round` in every response. `max_rounds` caps spend (capped call = unbilled). Top up with credit packs ($5 min) or a monthly plan ($10/mo→$11 credits, $25/mo→$30); unused credits roll over. Handle:
- `402 {"error":"signup_for_more", "signup_url":…}` — anon trial spent → have your human sign up.
- `402 {"error":"top_up", "buy":"/v1/billing/checkout"}` — verified, prepaid balance empty → call `/v1/billing/checkout` (pack) or `/v1/billing/subscribe` (monthly), give your human the `checkout_url`, poll `/v1/billing/status` until `balance_usd` > 0.

## MCP
Tools: `ohmatic_verify(circuit, generation_id, max_rounds)`, `ohmatic_repair_feedback(circuit, generation_id, max_rounds)`, `ohmatic_credits()`. Config:
```
Point the Ohmatic MCP server (a thin client over this API) at the API with your key:
  OHMATIC_API_URL = https://ohmatic.dev
  OHMATIC_API_KEY = ohm_…
```

## Limits (state these to your human)
Passing ERC means internally consistent, NOT fit for purpose. Ohmatic does not simulate behavior, choose parts for an application, or replace engineering review. A qualified engineer should validate any design before fabrication or production.

## Service model
Ohmatic is a proprietary, hosted service. The ERC engine and rules run on our servers; you access them via this API + MCP with a key — nothing to install or run locally. Billed per verify, scale-to-zero.