The first open-source, agentic electrical engineer.
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
ode45when 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) | |
| Control Studio (block diagram + step) | |
| Checked divider problem | |
| Visual kit gallery | |
| Reference library | |
| 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-cloudspawn 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:8765only. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.