169 lines
4.9 KiB
Markdown
169 lines
4.9 KiB
Markdown
# SCHEMETA
|
|
|
|
AI-Native schematic compiler and visual teaching workspace.
|
|
|
|
This version includes:
|
|
- Deterministic JSON validation, ERC, topology extraction
|
|
- Auto-generic symbol synthesis for unknown components/pins (deterministic fallback)
|
|
- Auto-template synthesis for common passives/connectors (`R/C/L/D/LED/J/P`)
|
|
- Constraint-aware placement, orthogonal routing, net-stub schematic mode
|
|
- SVG rendering with bus grouping, tie symbols, junctions, and legend
|
|
- Workspace UI for navigation, drag/lock placement, isolate/highlight, diagnostics focus, and direct graph editing
|
|
- JSON power tools: validate, format, sort keys, copy minimal repro
|
|
- REST + MCP integration (compile/analyze + UI bundle metadata)
|
|
|
|
## Run
|
|
|
|
```bash
|
|
npm run start
|
|
```
|
|
|
|
Open:
|
|
- Workspace: `http://localhost:8787/`
|
|
- Health: `http://localhost:8787/health`
|
|
- MCP UI bundle descriptor: `http://localhost:8787/mcp/ui-bundle`
|
|
|
|
Version metadata:
|
|
- REST and MCP tool responses include `api_version` and `schema_version`.
|
|
- Current values: `api_version=0.3.0`, `schema_version=1.0.0`.
|
|
- Compatibility policy (current): additive, backward-compatible fields may be introduced in the same API minor version.
|
|
|
|
Operational limits:
|
|
- `MAX_BODY_BYTES` (default `2097152`) limits request payload size.
|
|
- `MAX_REQUESTS_PER_MINUTE` (default `120`) applies per-client throttling for POST API endpoints.
|
|
- `SCHEMETA_AUTH_TOKEN` (optional) enforces bearer/API-key auth for POST API endpoints.
|
|
- send either `Authorization: Bearer <token>` or `x-api-key: <token>`
|
|
|
|
Docs:
|
|
- `docs/release-checklist.md`
|
|
- `docs/operations-runbook.md`
|
|
|
|
CI:
|
|
- `.gitea/workflows/ci.yml` runs syntax checks + full test suite on push/PR.
|
|
|
|
## REST API
|
|
|
|
### `POST /compile`
|
|
Input:
|
|
```json
|
|
{
|
|
"payload": { "...": "SJM" },
|
|
"options": {
|
|
"render_mode": "schematic_stub",
|
|
"show_labels": true,
|
|
"generic_symbols": true
|
|
}
|
|
}
|
|
```
|
|
|
|
`payload` can also be posted directly (backward compatible).
|
|
|
|
Output includes:
|
|
- `errors`, `warnings` with `id` + `suggestion`
|
|
- `focus_map` for issue-to-canvas targeting
|
|
- `layout` (resolved placements)
|
|
- `layout_metrics` (crossings, overlaps, label collisions, tie points, bus groups)
|
|
- `bus_groups`
|
|
- `render_mode_used`
|
|
- `svg`
|
|
|
|
### `POST /analyze`
|
|
Input: same payload model format
|
|
Output: ERC + topology summary (power domains, clock source/sink, buses, paths)
|
|
|
|
`generic_symbols` defaults to `true`. When enabled, missing symbols or missing pins on generic symbols are synthesized from net usage and surfaced as warnings:
|
|
- `auto_template_symbol_created` (for recognized common parts like resistor/capacitor/etc.)
|
|
- `auto_template_symbol_hydrated` (template shorthand expanded to full runtime symbol)
|
|
- `auto_generic_symbol_created`
|
|
- `auto_generic_symbol_hydrated` (generic shorthand expanded to full runtime symbol)
|
|
- `auto_generic_pin_created`
|
|
|
|
Shorthand symbols are supported for concise AI output:
|
|
|
|
```json
|
|
{
|
|
"symbols": {
|
|
"r_std": { "template_name": "resistor" },
|
|
"x_generic": { "category": "generic" }
|
|
}
|
|
}
|
|
```
|
|
|
|
`symbol_id`, `category`, `body`, and `pins` are auto-filled as needed during compile/analyze.
|
|
|
|
Instance-level built-in parts are also supported (no symbol definition required):
|
|
|
|
```json
|
|
{
|
|
"instances": [
|
|
{
|
|
"ref": "R1",
|
|
"part": "resistor",
|
|
"properties": { "value": "10k" },
|
|
"placement": { "x": null, "y": null, "rotation": 0, "locked": false }
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Supported `part` values: `resistor`, `capacitor`, `inductor`, `diode`, `led`, `connector`, `generic`.
|
|
|
|
Per-pin editor hints are supported through instance properties:
|
|
|
|
```json
|
|
{
|
|
"instances": [
|
|
{
|
|
"ref": "R1",
|
|
"part": "resistor",
|
|
"properties": {
|
|
"value": "10k",
|
|
"pin_ui": {
|
|
"1": { "show_net_label": true },
|
|
"2": { "show_net_label": false }
|
|
}
|
|
},
|
|
"placement": { "x": null, "y": null, "rotation": 0, "locked": false }
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### `POST /layout/auto`
|
|
Computes fresh placement (ignores current locks), returns:
|
|
- updated `model`
|
|
- compiled result in `compile`
|
|
|
|
### `POST /layout/tidy`
|
|
Computes placement tidy while respecting locks, returns:
|
|
- updated `model`
|
|
- compiled result in `compile`
|
|
|
|
## MCP
|
|
|
|
Start stdio MCP server:
|
|
|
|
```bash
|
|
npm run mcp
|
|
```
|
|
|
|
Tools:
|
|
- `schemeta_compile`
|
|
- `schemeta_analyze`
|
|
- `schemeta_ui_bundle`
|
|
|
|
## Workspace behavior highlights
|
|
|
|
- Fit-to-view default on load/import/apply
|
|
- Space + drag pan, wheel zoom, fit button
|
|
- Net/component/pin selection with dimming + isolate toggles
|
|
- Selected panel editors for component properties, full pin properties, full symbol body/pin editing, and net connect/disconnect operations
|
|
- Click diagnostics to jump/flash focused net/component/pin
|
|
- Auto Layout and Auto Tidy actions
|
|
- Keyboard shortcuts:
|
|
- `Ctrl/Cmd+Z` undo
|
|
- `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y` redo
|
|
- `Space` rotate selected components (or pan when no selection)
|
|
- `Alt+Enter` apply current selection editor (component/pin/net)
|
|
- `Alt+C` connect selected pin to chosen net
|