Skip to main content

Arc, AI Electrical Engineer

The first open-source, agentic electrical engineer.

Apache License 2.0 CI

Quick start · Domain kernel · What Arc unlocks · On the harness · Try these prompts · Cannot-do · License

Turn your AI coding assistant into an undergraduate electrical engineer. 10 undergraduate packs, 12 host-spawned specialists, 42 named lab recipes.

Arc is built for agents. Clone the repo, install, run electrical-engineer hosts install, then paste a job brief into Cursor, Claude Code, Codex, or ChatGPT desktop. The assistant picks named recipes, runs simulators when they exist, and labels anything it did not verify as unchecked in the saved run.

Arc is a local lab you clone and run. It is not a general coding agent that also does circuits. Primary interface: an agent (or you) pasting a prompt after install. Rule: if a number was not verified, Arc labels it unverified.

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
electrical-engineer eval --pack circuits
PASS mna-ladder-01 recipe=solve-circuit-problem
31/31 passed

If python -m venv fails (common on Debian/Ubuntu without python3-venv), install the python3-venv package or use a user install instead:

pip install --user -e ".[dev]"
electrical-engineer eval --pack circuits

That circuits pack check is 31/31. Full electrical-engineer eval (no --pack) is 60 gold tasks across 10 packs. Circuit golds are ngspice oracles (see scripts/capture_circuit_oracle.py); mna-ladder-01 checks a resistor ladder node voltage against SPICE, not derive() alone.

Domain kernel

A domain kernel is what enables a general agentic harness to have expertise in a specific domain.

Arc is that kernel for undergraduate electrical engineering. Cursor, Claude Code, Codex, and ChatGPT desktop stay general assistants. This kernel holds what they load: named lab recipes, simulators when they exist, gates, saved runs, and an unverified label when a number was not checked. The assistant still writes the viva. The ohms come from a deterministic check, or they are labeled unverified.

Arc is a working example of a domain kernel. It is what enables a general assistant to have expertise in electrical engineering, including the determinism a chat loop does not have on its own.

Plain-language walkthrough (what Arc adds, why numbers stay deterministic, how Arc mediates MATLAB): docs/ON_THE_HARNESS.md.

What the domain kernel unlocks

A coding agent can derive formulas from a PDF and still hand in the wrong stage of a power-angle curve, the wrong sign on a tie flow, or an economic dispatch that violates a generator limit. Arc loads skills, trap notes, and checked engines so those answers are verified against lab goldens or marked unchecked.

  • Transient stability: critical clearing angle 79.53° (not a single-Pmax shortcut that ablation tests miss by ~177°).
  • Clearing time: CCT ≈ 0.3097 s tied to Exp 6 data, not ode45 when the sheet forbids it.
  • Two-area AGC: primary droop Δf ≈ −0.16 Hz, ΔP12 ≈ −45 MW; integral AGC recenters frequency and load share.
  • Economic dispatch: at 500 MW demand, Unit 2 sits on 150 MW limit with correct λ (not an unconstrained λ solve).

Full before/after table and commands: docs/DOMAIN_KERNEL_CAPABILITIES.md.

Try these prompts

Paste into Cursor or Claude after you clone Arc and install. Each block is a real homework ask (2–3 lines). Open the local UI at 127.0.0.1:8765 to see schematics, diagrams, and plots for each run.

Series RLC: 10 V step, R = 1 kΩ, L = 1 mH, C = 1 µF.
Plot capacitor voltage for the first 10 ms and explain the overdamped/underdamped case.
Control tutorial: G(s) = 10/(s+1) in unity negative feedback with H = 1.
I need Bode plots and the step response, plus phase margin in plain words.
Compensator design: plant 10/(s+1), unity feedback, sketch the loop you used.
Compare open-loop vs closed-loop bandwidth before I submit the lab report.
Power systems assignment: LG fault on a 3-bus equivalent, Z1 = Z2 = 0.1 pu, Z0 = 0.3 pu.
Find fault current in pu and show bus voltages after the fault.
DC machine lab: 120 V armature, Ra = 1 Ω, torque constant 0.5 N·m/A, load 5 N·m.
What steady-state speed should I expect? Include the back-emf relation in the write-up.
Power systems lab: SMIB with H = 5, Pm = 0.9 pu, pre/fault/post Pmax 2.0 / 0.5 / 1.5 pu.
Find δ0, critical clearing angle, and critical clearing time for the given data.
Three-unit economic dispatch: quadratic costs as in the assignment table, PD = 500 MW.
Dispatch with limits and show λ and each unit output; Unit 2 must respect its maximum.
Two-area AGC: 100 MW load step in Area 1 at t = 1 s. Compare primary droop vs AGC (K = 0.3):
steady frequency, tie flow, and who carries the load at the end.

Host adapters: docs/hosts/README.md. 12 EE specialists in hosts/agents/ for large worksheets (host spawns at most two).

Quick start

You need Python 3.11+. An AI coding assistant is the primary interface; the CLI is complete without one.

Consumer install (wheel / PyPI)

When a release is on PyPI (or you have a local wheel from scripts/build_release_wheel.py):

pip install electrical-engineer
# or one-shot without a permanent env:
uvx electrical-engineer workflows

Optional simulators: pip install "electrical-engineer[engines]". The wheel ships recipes, host packs, and a prebuilt UI (ui/dist); no repo clone required for workflows, hosts doctor, or ui.

Until the package is published, build locally: npm run build in ui/, then uv run --with build python scripts/build_release_wheel.py, then pip install dist/electrical_engineer-*.whl. Smoke: uv run python scripts/smoke_wheel_install.py.

Contributor clone (editable)

Node is only needed if you change the UI and rebuild ui/dist.

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
electrical-engineer workflows

Then paste a prompt above, or boot the same commands recorded in docs/planning/R1_BOOT.md:

electrical-engineer --help
electrical-engineer run solve-circuit-problem
electrical-engineer mcp
electrical-engineer hosts install --into /tmp/ee-hw --host all
EE_NO_BROWSER=1 electrical-engineer ui
electrical-engineer run solve-circuit-problem
EE_NO_BROWSER=1 electrical-engineer ui
electrical-engineer mcp
electrical-engineer eval --pack circuits
./scripts/validate.sh

Put a problem.json in the working directory for numeric tasks (see eval/gold/circuits/mna-ladder-01/fixtures/problem.json).

If you are an agent reading this: load skills/SKILL.md, then docs/hosts/README.md. Do not invent a kind of check. Do not present a fluent number as verified.

Maintainers compiling UG method notes (not the RAG index): knowledge/README.md. Inventory: python scripts/check_knowledge_tree.py.

The workspace is electrical-engineer ui on 127.0.0.1:8765 only.

Optional: uv

If you use uv, the same extras apply:

uv sync --extra dev
uv run electrical-engineer workflows

CI uses uv internally; user-facing docs stay pip-first.

Optional simulation engines

# Linux: ngspice system binary + Python extras
sudo apt-get install -y ngspice libngspice0
pip install -e ".[engines,dev]"
Domain Recipe Engine
RLC / netlist simulate-circuit ngspice + PySpice
Bode / step solve-control-problem control (python-control)
Block diagram → plant control-diagram-to-model compose blocks + control
Digital z-domain solve-digital-control-problem discrete TF / ZOH sample
Fault / load flow simulate-power-fault pandapower + sequence networks
Protection (study) study-protection-setting CT, pickup, distance zone math
Drives (UG intro) solve-drives-problem OSS DC / IM slip steady-state

Boot details: docs/planning/R1_BOOT_SHIP.md.

Visual Kit (engine-bound figures)

Arc ships a design-system Visual Kit: every annotation comes from kernels (smib_swing, agc_two_area, ed_lambda, pandapower, ngspice, python-control), not from the chat.

Figure Golden path
SMIB equal-area (pre/fault/post, $A_1$, $A_2$) artifacts/visual-goldens/swing/power.swing_equal_area.png
Two-area AGC ($f_1$, $f_2$, $P_{12}$) artifacts/visual-goldens/agc/power.agc_trace.png
Economic dispatch IC curves artifacts/visual-goldens/ed/power.dispatch_curve.png
Rotor swing animation artifacts/visual-goldens/swing/power.swing_animation.gif
Pandapower one-line artifacts/visual-goldens/oneline/power.oneline_bus.png
Control block diagram artifacts/visual-goldens/control/control.block_diagram.png

Regenerate goldens locally:

uv run python scripts/regenerate_visual_goldens.py
uv run pytest -q tests/visual

Open the gallery tab in the local UI (127.0.0.1:8765, sidebar Visuals) or GET /api/visual-kit.

Frontier scorecard (Nov 2026 branch)

Measured on cursor/frontier-execution-7a2f (see docs/planning/SCORECARD.md):

Check Result
Full electrical-engineer eval 60 gold tasks (see docs/planning/SCORECARD.md for branch-era scores)
eval --pack circuits 31/31
eval --pack power 9 items (PSA + recipe golds)
pytest 255+ PASS (includes visual regression)
Scripted trap pass^k 1.0 (no API keys)
LIVE A/B blocked until OPENAI_API_KEY + ANTHROPIC_API_KEY (docs/planning/LIVE_AB.md)

One-command frontier validation:

./scripts/validate_frontier.sh

Product UI (localhost shell)

2× device captures at 1440×900 (deviceScaleFactor: 2) from 127.0.0.1:8765. Regenerate after npm run build in ui/:

pip install playwright pngquant-bin
playwright install chromium
EE_NO_BROWSER=1 electrical-engineer ui &
python scripts/capture_readme_showcase.py
View Screenshot
Home (recipes + recent runs) Arc home
Control Studio (block diagram + step) Control Studio
Checked divider problem Circuit problem
Visual kit gallery Gallery
Reference library Library
Studio (dark) Studio dark

Legacy domain window shots (1280×900) remain under docs/media/.

How it works

sequenceDiagram
  participant H as You or coding assistant
  participant K as Arc
  participant P as Simulators
  participant UI as Local window
  H->>K: homework in plain language
  K->>P: run an allowed check
  P-->>K: a number, or labeled unverified
  K-->>UI: saved evidence
  UI-->>H: numbers plus explanation, confirm photos
  • Named lab recipes. 42 saved workflows. The assistant picks one (or proposes an allowed graph). Arc runs it. A free agent loop can skip the simulator. Limit: Arc never invents a new recipe in chat. docs/WORKFLOWS.md
  • Host-spawned specialists. 12 cards in hosts/agents/. Cursor, Codex, or Claude starts at most two on a large assignment. Limit: Arc never starts those children. Cloud /in-cloud spawn is off.
  • Deterministic checks. The recipe runner and the simulators do not sample. Same netlist, same Vout. Limit: the explanation can still vary. The ohms cannot, unless they are labeled unverified. docs/ON_THE_HARNESS.md
  • Unverified numbers are labeled. If SPICE, python-control, or pandapower is missing, Arc does not guess. Limit: a verified number needs a simulator or a numeric check, not a fluent paragraph.
  • Local window. On 127.0.0.1:8765 only. Limit: not on the internet, no chat loop in the browser.
  • Tools for the coding assistant. List recipes, look up a citation, open the window, run a short simulation, propose allowed checks, read the labeled result, replay a recipe. Limit: the chat never waits on you.

Go deeper

Doc What it is
docs/ON_THE_HARNESS.md What Arc adds on a coding assistant, in plain language
docs/EXTENSIVE.md Concepts, runtime path, every package
docs/ARCHITECTURE.md Kernel, capabilities, seams
docs/WORKFLOWS.md Named recipe catalog
docs/CANNOT_DO.md Honest holes
docs/hosts/README.md Cursor, Claude Code, Codex, ChatGPT desktop

License

Apache-2.0. See LICENSE.

Kernel harden

Metadata

Release files for electrical-engineer 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for electrical-engineer 0.1.0
File Size Uploaded Provenance Actions
electrical_engineer-0.1.0.tar.gz 218.5 kB Without provenance Details for electrical_engineer-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for electrical-engineer 0.1.0
File Interpreter ABI Platform Actions
electrical_engineer-0.1.0-py3-none-any.whl Python 3 none any Details for electrical_engineer-0.1.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / electrical_engineer-0.1.0.tar.gz

Download URL electrical_engineer-0.1.0.tar.gz
Size 218.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a6495dfa087629aec4fb831f8cbefcbb05ef6c3969c0871e8a27e234873645cf
BLAKE2b-256 checksum
How to use checksums
75e1bd7cdb12a95c8ed8eaeddf1da7233c02200d90e08570b139c3f7a56a9e11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / electrical_engineer-0.1.0-py3-none-any.whl

Download URL electrical_engineer-0.1.0-py3-none-any.whl
Size 910.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d034bb1a222dce79cf7d7b3cf1104715a9253f5538bff529458d5ffe982d9482
BLAKE2b-256 checksum
How to use checksums
7134bfebb021d64228b4ec0f69f48b3cde198eb8ac791d44d75dfc8ff69a2287
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for electrical-engineer 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page