Metadata-Version: 2.3
Name: electrical-engineer
Version: 0.1.0
Summary: UG electrical engineering co-solver (Arc domain kernel)
Project-URL: Homepage, https://github.com/Vinayak-RZ/ARC
Project-URL: Repository, https://github.com/Vinayak-RZ/ARC
Project-URL: Issues, https://github.com/Vinayak-RZ/ARC/issues
Project-URL: Documentation, https://github.com/Vinayak-RZ/ARC/blob/main/docs/EXTENSIVE.md
Author: Vinayak-RZ
License: Apache-2.0
Keywords: arc,control-systems,education,electrical-engineering,mcp,spice
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: control>=0.9.4
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pyyaml>=6
Requires-Dist: scipy>=1.11
Requires-Dist: uvicorn>=0.32
Provides-Extra: control
Requires-Dist: control>=0.9.4; extra == 'control'
Requires-Dist: matplotlib>=3.8; extra == 'control'
Requires-Dist: numpy>=1.26; extra == 'control'
Requires-Dist: scipy>=1.11; extra == 'control'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pillow>=10; extra == 'dev'
Requires-Dist: playwright>=1.49; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: engines
Requires-Dist: control>=0.9.4; extra == 'engines'
Requires-Dist: matplotlib>=3.8; extra == 'engines'
Requires-Dist: numpy>=1.26; extra == 'engines'
Requires-Dist: pandapower>=2.14; extra == 'engines'
Requires-Dist: pyspice>=1.5; extra == 'engines'
Requires-Dist: schemdraw>=0.15; extra == 'engines'
Requires-Dist: scipy>=1.11; extra == 'engines'
Provides-Extra: power
Requires-Dist: numpy>=1.26; extra == 'power'
Requires-Dist: pandapower>=2.14; extra == 'power'
Provides-Extra: rag
Requires-Dist: pypdf>=5; extra == 'rag'
Provides-Extra: rag-multimodal
Requires-Dist: pypdf>=5; extra == 'rag-multimodal'
Provides-Extra: rag-ocr
Requires-Dist: ocrmypdf>=16; extra == 'rag-ocr'
Requires-Dist: pypdf>=5; extra == 'rag-ocr'
Provides-Extra: sim
Requires-Dist: numpy>=1.26; extra == 'sim'
Requires-Dist: pyspice>=1.5; extra == 'sim'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/brand/arc-lockup.png" width="680" alt="Arc, AI Electrical Engineer">
</p>

<p align="center">
  <strong>The first open-source, agentic electrical engineer.</strong>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-2ea043" alt="Apache License 2.0"></a>
  <a href=".github/workflows/ci.yml"><img src="https://github.com/Vinayak-RZ/ARC/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
</p>

<p align="center">
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="#domain-kernel"><b>Domain kernel</b></a> ·
  <a href="docs/DOMAIN_KERNEL_CAPABILITIES.md"><b>What Arc unlocks</b></a> ·
  <a href="docs/ON_THE_HARNESS.md"><b>On the harness</b></a> ·
  <a href="#try-these-prompts"><b>Try these prompts</b></a> ·
  <a href="docs/CANNOT_DO.md"><b>Cannot-do</b></a> ·
  <a href="LICENSE"><b>License</b></a>
</p>

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.**

```text
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:

```text
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`](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`](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.

```text
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.
```

```text
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.
```

```text
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.
```

```text
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.
```

```text
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.
```

```text
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.
```

```text
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.
```

```text
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`](docs/hosts/README.md). **12 EE specialists** in [`hosts/agents/`](hosts/agents/INDEX.md) 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`):

```bash
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`.

```bash
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`](docs/planning/R1_BOOT.md):

```bash
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
```

```bash
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`](skills/SKILL.md), then [`docs/hosts/README.md`](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`](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](https://docs.astral.sh/uv/), the same extras apply:

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

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

### Optional simulation engines

```bash
# 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`](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:

```bash
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:

```bash
./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/`:

```bash
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](docs/assets/readme/home-light.png) |
| Control Studio (block diagram + step) | ![Control Studio](docs/assets/readme/studio-hero-light.png) |
| Checked divider problem | ![Circuit problem](docs/assets/readme/problem-checked-light.png) |
| Visual kit gallery | ![Gallery](docs/assets/readme/gallery-light.png) |
| Reference library | ![Library](docs/assets/readme/library-light.png) |
| Studio (dark) | ![Studio dark](docs/assets/readme/studio-dark.png) |

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

## How it works

```mermaid
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`](docs/WORKFLOWS.md)
- **Host-spawned specialists.** 12 cards in [`hosts/agents/`](hosts/agents/INDEX.md). 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`](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`](docs/ON_THE_HARNESS.md) | What Arc adds on a coding assistant, in plain language |
| [`docs/EXTENSIVE.md`](docs/EXTENSIVE.md) | Concepts, runtime path, every package |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Kernel, capabilities, seams |
| [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md) | Named recipe catalog |
| [`docs/CANNOT_DO.md`](docs/CANNOT_DO.md) | Honest holes |
| [`docs/hosts/README.md`](docs/hosts/README.md) | Cursor, Claude Code, Codex, ChatGPT desktop |

## License

Apache-2.0. See [`LICENSE`](LICENSE).


## Kernel harden

- [`docs/CASE_STUDY_DOMAIN_KERNEL.md`](docs/CASE_STUDY_DOMAIN_KERNEL.md)
- [`docs/planning/AUDIT_KERNEL_HARDEN.md`](docs/planning/AUDIT_KERNEL_HARDEN.md)
- [`docs/integrations/UNAGENT.md`](docs/integrations/UNAGENT.md)
- [`docs/integrations/IMPROVENESS.md`](docs/integrations/IMPROVENESS.md)
- [`LEARNING.md`](LEARNING.md)
