OpenCircuitLoop

简体中文 · Documentation · Contributing

OpenCircuitLoop is a hardware engineering toolkit for AI agents: describe circuits in CDLS, compare component facts with supplied evidence, run staged checks and SPICE scenarios, and return structured feedback for the next design iteration.

The repository contains the CDLS compiler and CLI and a Hardware Design plugin with five skills and a local MCP server. The CLI works independently of an AI assistant. The plugin exposes the workflow to an MCP-capable host.

Status: experimental, version 0.1.0. Evidence acquisition is not connected, electrical and protocol rules have partial coverage, and the KiCad adapter produces handoff JSON rather than a usable .kicad_sch. This is a foundation for engineering feedback loops; it does not implement an autonomous repair controller or certify physical hardware. See capabilities and limits.

What it does

• Structured design: Python-compatible .cdls source describes Product → Domain → Module → Component → Pin, local nets and interfaces.
• Inspectable compilation: lint and controlled execution produce versioned Design IR, diagnostics and a query index, preserving behavior and limits source.
• Evidence comparison: supplied component facts are checked against provenance-bearing records, with evidence locks and change reports.
• Explicit feedback: stages report PASS, FAIL, UNKNOWN or NOT_RUN. The default readiness gate blocks missing, failed and unknown stages.
• Separate backends: export EasyEDA ENET, run supported ngspice scenarios, or generate structured KiCad handoff IR.

Design requirements and external evidence
                  ↓
           CDLS source → Design IR
                          ↓
             Evidence / rules / SPICE / handoff
                          ↓
                 Structured feedback
                          ↓
             Engineer or agent revises source

The engineer or host agent controls the loop. How to interpret feedback and what remains to be built are described in feedback engineering.

Quick start

Install uv and use Python 3.11 or newer. Run these commands from the repository root:

uv sync --locked
uv run cdls lint examples/cdls/designs/cohesive-power-channel.cdls
uv run cdls check examples/cdls/designs/cohesive-power-channel.cdls
uv run cdls build examples/cdls/designs/cohesive-power-channel.cdls --out build/quickstart
uv run cdls query build/quickstart/query-index.json net PowerExample.POWER.CHANNEL.PROTECTED_VOUT

The build writes design.core.json, design.report.json and query-index.json. This example demonstrates structure; its example parts are not a verified BOM.

Export a SPICE deck without installing a simulator:

uv run cdls export-spice examples/cdls/designs/rlc-spice.cdls --config examples/cdls/simulations/rlc-spice.toml --scenario rlc --out build/spice

To execute the scenario, install ngspice and follow the simulation instructions.

Use the plugin

The plugin lives in plugins/hardware-design/; the repository marketplace is .agents/plugins/marketplace.json. Configure an absolute design workspace before starting the MCP server. From the repository root, in PowerShell:

$env:HARDWARE_DESIGN_WORKSPACE_ROOT = (Get-Location).Path
uv --directory plugins/hardware-design/mcp-server run hardware-design-mcp --stdio

This starts a stdio MCP server for a client to connect to; it is not an interactive shell command that prints a design report. See plugin setup and the MCP tool reference.

Repository map

Path	Purpose
src/cdls/	Language runtime, compiler, query, ENET and SPICE backends
plugins/hardware-design/	Distributable plugin, skills and MCP server
plugins/hardware-design/mcp-server/vendor/cdls/	Bundled copy of this repository's compiler
examples/cdls/	Modeling and simulation examples, including intentional risk fixtures
tests/	Compiler and SPICE regression tests
skills/cdls/	Standalone authoring and implementation reference skill
skills/jlceda-api-guide/	Optional EasyEDA API reference; not part of the plugin runtime
docs/	Setup, architecture, limits and historical design analyses

CableDivider is an intentionally problematic regression fixture, not a circuit to manufacture. Start with the example guide.

Development

uv run python -m unittest discover -s tests
uv --directory plugins/hardware-design/mcp-server run --with pytest pytest tests -q

Real ngspice tests may be skipped when its executable is unavailable. MCP contract tests do not establish real KiCad or hardware correctness. See contribution and validation instructions.

License

Licensed under the Apache License 2.0. See NOTICE for project attribution and third-party notices for bundled upstream material.

Source repository: Tobi1chi/open-circuit-loop.