See it work

Architecture -- deterministic core, AI agents on top

The rule that shaped every decision in this codebase: never let a model guess at something that can be proven mechanically.

Schematic PDF / KiCad project
        │
        ▼
┌───────────────────┐   deterministic -- no AI, hand-verified against real boards
│  Parser            │   Altium's embedded netlist tokens, or KiCad .net/.kicad_pcb
│  Graph + geometry   │   MST wire routing, power-rail classification, pin bounding boxes
└─────────┬──────────┘
          ▼
┌───────────────────────────────────────────────────────────┐  AI agents, narrowly scoped,
│  Part Identity  │  Region Explainer  │  Datasheet Digest    │  every output verifiable
│  (skips passives) │ (per section)    │  (quote + page cite)  │  against a mechanical check
└─────────┬─────────────────┬──────────────────┬─────────────┘
          ▼                 ▼                  ▼
   ┌─────────────────────────────────────────────────┐
   │  Supervisor -- cost budgets, spend tracking,     │
   │  thread-safe, hard caps on every model call      │
   └─────────────────────────────────────────────────┘
          │
          ▼
┌────────────────────────────────────────────────────────────────────┐
│  Graph API (tool layer, zero AI)  →  Chat Agent (tool-calling, memory) │
│  Mate Proposer (human-gated)      →  Hardware Map / Firmware Starter   │
│  Design Checks (mechanical + heuristic, tier-labeled)                 │
└────────────────────────────────────────────────────────────────────┘
          │
          ▼
   Interactive canvas · grounded chat · exports for a coding agent

1. Netlist extraction (deterministic). Altium's PDF export embeds invisible text at every pin and component location -- PI<refdes><pin>, CO<refdes>, NL<netname> -- meant for interactive net-highlighting in a PDF viewer. schemantic/parser/netlist.py reads it directly. Every connection is parsed fact, verified by hand against real schematics (e.g., a sensor's SDA pin lands on the SDA bus exactly as drawn; an IMU has exactly the pin count its real package has).
2. Part identification (AI, narrow scope). Generic resistors/capacitors never reach the model -- nothing to identify. Only ICs, connectors, and named transistors go through schemantic/agents/part_identity.py, each result carrying reasoning, confidence, and deterministic search links.
3. Region explanation (AI). Plain-English summaries of what each labeled subcircuit does, grounded only in the parts identified within it.
4. Graph + geometry (deterministic). The parse becomes a drawable connectivity graph: real pin bounding boxes, and per-net wires as a minimum spanning tree over real pin coordinates. Topology is exact and test-enforced; the specific wire paths are synthetic, not the original routes -- stated plainly, not glossed over.
5. Datasheet grounding (AI extracts, mechanics verify). Every fact ships with a verbatim quote and page number; the quote is re-checked against the actual fetched PDF page, and anything that fails is dropped and counted, never shown.
6. Multi-board workspaces (AI proposes, human confirms). Connector matings can't be parsed -- they're physical harness decisions in neither schematic -- so an agent proposes candidates with pin-level evidence, every proposal is mechanically validated against the real connectors before storage, and only human-confirmed links become traversable.
7. Chat agent (tool-calling, grounded, with memory). Can only answer through deterministic tool calls over the parsed graph -- every claim traces to a query, shown in the UI as provenance. Persistent semantic memory means conversations survive restarts and reworded questions still find prior answers.
8. Supervisor. Every model call anywhere in the system runs through a thread-safe cost-budget layer with hard spend caps -- no agent, however deep in a tool loop, can run unmetered.

Built and verified across three real, independently-sourced boards

The second and third boards needed zero parser code changes -- the whole point of building on a deterministic core.

Honesty log -- real bugs found by reading actual output, not assumed away

This is the part of the codebase I'm most willing to defend under questioning. A running list of mistakes caught by actually inspecting live output against ground truth, and exactly how each was fixed:

• A schema-ordering bug that let a model contradict itself. Early on, a verdict field was requested before the reasoning meant to justify it -- structured-output APIs fill fields in declaration order, so the model was committing to an answer before thinking it through. Fixed by putting reasoning first everywhere in the schema.
• A substring-matching bug mistook a section title for a component value (10-DOF-IMU-Sensor-D matched as a capacitor value because M is a substring of IMU). Fixed with a proper anchored pattern; regression-tested.
• A naive "any power rail counts as a pull-up" check would have missed I2C buses with only a pull-down to GND -- caught by reading the actual resistor-to-net mapping on a real board (one resistor really was GND-tied, for an unrelated reason) before trusting the check's silence.
• A voltage-range check false-flagged the board's own microcontroller -- its datasheet says "3.0 to 3.6 V," but substring-matching only caught the upper bound "3.6," which doesn't textually appear in a "3V3" rail name even though 3.3V is well inside the real range. Fixed with actual numeric range containment.
• The netlist format was misattributed to EasyEDA by assumption. Checking PDF creator metadata across every sample settled it: every token-carrying PDF says creator='Altium Designer'. Corrected everywhere, including error messages users see.
• A stricter token filter (fixing a KiCad false-positive) silently exposed a day-one bug: an active-low enable net's token had been rejected by an overly loose check since the very first version, silently merging its pins into an unrelated net. Both reference boards were re-verified and locked in with regression tests after the fix.

Every one of these was found by generating real output and reading it critically, not by assuming the pipeline was correct -- and each fix is now guarded by a test that reproduces the original failure.

Tech stack

Python · FastAPI · OpenAI (structured outputs, tool-calling, embeddings) · SQLite (semantic vector memory) · PyMuPDF · vanilla JS + SVG (the canvas -- no framework, no build step) · pytest (81 tests, almost all running against real enriched board data, not mocks)

Run it

# .env with OPENAI_API_KEY must exist in the project root (see .env.example)
python -m venv .venv
./.venv/Scripts/pip install -e ".[dev]"
./.venv/Scripts/pytest -q
./.venv/Scripts/python -m uvicorn schemantic.web.app:app --reload

Open http://127.0.0.1:8000/. First load runs the full pipeline (~1 min, a few cents against a new board) and caches by content hash; every later load is instant. Upload any Altium PDF or KiCad .net/.zip via "Analyze a board."

Not yet built

• Eagle/OrCAD support, and KiCad PDF exports specifically (no embedded netlist in KiCad's PDF -- the source-file route is what's supported).
• Scanned/rasterized schematics with no embedded text layer -- needs real computer-vision symbol recognition, a fundamentally different problem, out of scope for now.
• Multi-page schematics -- the parser currently expects a single-page export.

Repo layout

schemantic/
  parser/           deterministic PDF/KiCad → components, pins, nets
  graph.py          connectivity graph + wire geometry (MST)
  graph_api.py       tool layer the chat agent queries (zero AI)
  agents/           part identity, region explainer, datasheet digest,
                    chat, mate proposer, firmware starter
  datasheets.py     fetch + mechanical quote verification
  chat_memory.py    persistent semantic memory (SQLite + embeddings)
  workspace.py      multi-board store, mechanical mate validation
  design_checks.py  pre-fab checks, mechanical + heuristic tiers
  hardwaremap.py    coding-agent export
  supervisor/       cost budgets, thread-safe, hard caps
  web/              FastAPI app + canvas UI (vanilla JS/SVG)
tests/              81 tests, mostly against real enriched board payloads

Updated Nov 10, 2026