{"repo": "acadlab/arcade", "files": {"README.md": {"5f0526199cbbd82ce0269a6a81534fcbe8d0f86b": {"t": 1785747241.2107372, "n": 5229, "h": "272e0e7780038336", "c": "# ARCADE\n\n**A**utonomous **R**TL **C**reation with **A**gents, **D**iagnostics, and **E**rror memory — multi-agent approximate adder generation with closed-loop repair and retrieval-augmented error memory (RAEM).\n\n---\n\n## Overview\n\nARCADE is an LLM-driven framework for generating Verilog approximate adders from minimal specs (`bit_width`, `nmed_target`, `area_priority`). A **Design Agent** produces RTL; a **Verifier Agent** produces a black-box testbench from the same spec; a **golden Verilator harness** computes Normalized Mean Error Distance (NMED) vs exact addition and is the final judge. Passing designs can be wired into an OpenROAD flow for PPA (area, power, timing) evaluation.\n\n### Experiment modes (E1–E4)\n\n| Mode | Name | Description |\n|------|------|-------------|\n| **E1** | **ARCADE-Vanilla** | Single-shot generation with no repair loop and no retrieval memory, establishing the baseline capability of the underlying model. |\n| **E2** | **ARCADE-Repair** | Adds the closed-loop repair mechanism, feeding structured NMED failure diagnostics back to the Design Agent across up to five iterations. |\n| **E3** | **ARCADE-Memory** | Augments repair with RAEM retrieval, prepending the top-*k* historically similar failure contexts to each repair prompt. |\n| **E4** | **ARCADE-Full** | Same pipeline as E3; used for learning-curve analysis over the spec order (RAEM fills over a sequential run). |\n\nSpecs are defined in `configs/adder_specs.json` (13 specs: 8/16/32-bit, varying NMED and area priority). See **implementation.md** for pipeline details.\n\n---\n\n## Prerequisites\n\n- **Python 3.10+**\n- **uv** (or pip) for installing the package\n- **Verilator** — to compile and run the golden NMED harness\n- **API key** — at least one of: DeepSeek (default), Claude, OpenRouter, OpenAI\n- **OpenROAD flow** (optional) — only if you want PPA; e.g. Docker `openroad/orfs` or native orfs-build\n\n---\n\n## Setup\n\nUse **uv** to create the virtual environment and install in editable mode (recommended):\n\n```bash\ncd ARCADE\nuv venv && source .venv/bin/activate   # Windows: .venv\\Scripts\\activate\nuv pip install -e .\n```\n\nAlternatively, use `python -m venv .venv` and `pip install -e .`.\n\n### API keys (required for LLM calls)\n\nSet **environment variables** (recommended for security):\n\n- `DEEPSEEK_API_KEY` (default provider)\n- `ANTHROPIC_API_KEY` (for `--provider claude`)\n- `OPENROUTER_API_KEY`, `OPENAI_API_KEY` (if using those providers)\n\nAlternatively, you can use a **local keys file** in the repo root (gitignored): create `keys.txt` with PowerShell-style lines, e.g.:\n\n```text\n$env:DEEPSEEK_API = 'sk-...'\n$env:ANTHROPIC_API_KEY = '...'\n```\n\nDo **not** commit `keys.txt` or any file containing secrets.\n\n---\n\n## Directory layout\n\n```\nARCADE/\n├── configs/\n│   ├── adder_specs.json\n│   └── professor_papers.json\n├── harness/\n│   └── tb_adder.cpp          # Golden NMED harness (Verilator)\n├── src/\n│   ├── orchestrator.py        # Main entry: modes E1–E4, smoke\n│   ├── design_agent.py\n│   ├── verifier_agent.py\n│   ├── ppa_loop.py            # OpenROAD flow (Docker or native)\n│   ├── aptpu_integrator.py    # Injects passing adder into flow\n│   └── config.py              # Paths, API key loading\n├── results/                   # E1_results.json, E2_results.json, ... (gitignored)\n├── work/                      # Per-spec Verilator run dirs (gitignored)\n├── run_all_experiments.sh     # E1→E4 with --resume / --start-from\n├── implementation.md         # Framework and experiment details\n└── docs/\n    └── RUNNING_E1_E3_AND_PPA.md\n```\n\n---\n\n## Run\n\n### Quick test (single spec, one shot)\n\n```bash\npython -m src.orchestrator --mode E1 --spec-id A1 --limit 1\n```\n(Requires an API key and Verilator.)\n\n### Single mode, few specs (NMED only; no flow required)\n\n```bash\npython -m src.orchestrator --mode E1 --limit 3\npython -m src.orchestrator --mode E2 --limit 3 --provider deepseek\n```\n\n### Single mode with PPA (flow root required)\n\n```bash\npython -m src.orchestrator --mode E1 --limit 13 --flow-root /path/to/flow\n```\n\n### Full suite (E1 → E4) and resume\n\n```bash\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow\n# Resume after partial run:\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow --resume\n# Start from E3 only:\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow --resume --start-from E3\n```\n\n- **--resume:** Skips modes that already have `limit` results; for partial runs, runs only missing spec IDs and merges.\n- **--start-from E2|E3|E4:** Skips earlier modes.\n- **--workers N:** Parallel workers per mode (default 4).\n- **--with-ppa:** Run PPA inline (1 worker). By default PPA runs as a batch after all verification runs.\n\nResults are written to `results/E1_results.json`, `results/E2_results.json`, etc. Each entry includes `pass`, `nmed`, `ppa` (if flow was run), and `integration` when applicable.\n\n---\n\n## OpenROAD flow (optional)\n\nFor PPA you need a prepared flow directory (design RTL + config). See **docs/RUNNING_E1_E3_AND_PPA.md** for:\n\n- Docker-based flow with `openroad/orfs`\n- Native orfs-build\n- Preparing the APTPU design in the flow\n\n---\n\n## License and citation\n\nSee repository metadata. If you use ARCADE in research, please cite the accompanying paper.\n"}, "58f5f7c10a8947816a1c90deac485a176572808d": {"t": 1785771646.8393602, "n": 5229, "h": "272e0e7780038336", "c": "# ARCADE\n\n**A**utonomous **R**TL **C**reation with **A**gents, **D**iagnostics, and **E**rror memory — multi-agent approximate adder generation with closed-loop repair and retrieval-augmented error memory (RAEM).\n\n---\n\n## Overview\n\nARCADE is an LLM-driven framework for generating Verilog approximate adders from minimal specs (`bit_width`, `nmed_target`, `area_priority`). A **Design Agent** produces RTL; a **Verifier Agent** produces a black-box testbench from the same spec; a **golden Verilator harness** computes Normalized Mean Error Distance (NMED) vs exact addition and is the final judge. Passing designs can be wired into an OpenROAD flow for PPA (area, power, timing) evaluation.\n\n### Experiment modes (E1–E4)\n\n| Mode | Name | Description |\n|------|------|-------------|\n| **E1** | **ARCADE-Vanilla** | Single-shot generation with no repair loop and no retrieval memory, establishing the baseline capability of the underlying model. |\n| **E2** | **ARCADE-Repair** | Adds the closed-loop repair mechanism, feeding structured NMED failure diagnostics back to the Design Agent across up to five iterations. |\n| **E3** | **ARCADE-Memory** | Augments repair with RAEM retrieval, prepending the top-*k* historically similar failure contexts to each repair prompt. |\n| **E4** | **ARCADE-Full** | Same pipeline as E3; used for learning-curve analysis over the spec order (RAEM fills over a sequential run). |\n\nSpecs are defined in `configs/adder_specs.json` (13 specs: 8/16/32-bit, varying NMED and area priority). See **implementation.md** for pipeline details.\n\n---\n\n## Prerequisites\n\n- **Python 3.10+**\n- **uv** (or pip) for installing the package\n- **Verilator** — to compile and run the golden NMED harness\n- **API key** — at least one of: DeepSeek (default), Claude, OpenRouter, OpenAI\n- **OpenROAD flow** (optional) — only if you want PPA; e.g. Docker `openroad/orfs` or native orfs-build\n\n---\n\n## Setup\n\nUse **uv** to create the virtual environment and install in editable mode (recommended):\n\n```bash\ncd ARCADE\nuv venv && source .venv/bin/activate   # Windows: .venv\\Scripts\\activate\nuv pip install -e .\n```\n\nAlternatively, use `python -m venv .venv` and `pip install -e .`.\n\n### API keys (required for LLM calls)\n\nSet **environment variables** (recommended for security):\n\n- `DEEPSEEK_API_KEY` (default provider)\n- `ANTHROPIC_API_KEY` (for `--provider claude`)\n- `OPENROUTER_API_KEY`, `OPENAI_API_KEY` (if using those providers)\n\nAlternatively, you can use a **local keys file** in the repo root (gitignored): create `keys.txt` with PowerShell-style lines, e.g.:\n\n```text\n$env:DEEPSEEK_API = 'sk-...'\n$env:ANTHROPIC_API_KEY = '...'\n```\n\nDo **not** commit `keys.txt` or any file containing secrets.\n\n---\n\n## Directory layout\n\n```\nARCADE/\n├── configs/\n│   ├── adder_specs.json\n│   └── professor_papers.json\n├── harness/\n│   └── tb_adder.cpp          # Golden NMED harness (Verilator)\n├── src/\n│   ├── orchestrator.py        # Main entry: modes E1–E4, smoke\n│   ├── design_agent.py\n│   ├── verifier_agent.py\n│   ├── ppa_loop.py            # OpenROAD flow (Docker or native)\n│   ├── aptpu_integrator.py    # Injects passing adder into flow\n│   └── config.py              # Paths, API key loading\n├── results/                   # E1_results.json, E2_results.json, ... (gitignored)\n├── work/                      # Per-spec Verilator run dirs (gitignored)\n├── run_all_experiments.sh     # E1→E4 with --resume / --start-from\n├── implementation.md         # Framework and experiment details\n└── docs/\n    └── RUNNING_E1_E3_AND_PPA.md\n```\n\n---\n\n## Run\n\n### Quick test (single spec, one shot)\n\n```bash\npython -m src.orchestrator --mode E1 --spec-id A1 --limit 1\n```\n(Requires an API key and Verilator.)\n\n### Single mode, few specs (NMED only; no flow required)\n\n```bash\npython -m src.orchestrator --mode E1 --limit 3\npython -m src.orchestrator --mode E2 --limit 3 --provider deepseek\n```\n\n### Single mode with PPA (flow root required)\n\n```bash\npython -m src.orchestrator --mode E1 --limit 13 --flow-root /path/to/flow\n```\n\n### Full suite (E1 → E4) and resume\n\n```bash\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow\n# Resume after partial run:\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow --resume\n# Start from E3 only:\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow --resume --start-from E3\n```\n\n- **--resume:** Skips modes that already have `limit` results; for partial runs, runs only missing spec IDs and merges.\n- **--start-from E2|E3|E4:** Skips earlier modes.\n- **--workers N:** Parallel workers per mode (default 4).\n- **--with-ppa:** Run PPA inline (1 worker). By default PPA runs as a batch after all verification runs.\n\nResults are written to `results/E1_results.json`, `results/E2_results.json`, etc. Each entry includes `pass`, `nmed`, `ppa` (if flow was run), and `integration` when applicable.\n\n---\n\n## OpenROAD flow (optional)\n\nFor PPA you need a prepared flow directory (design RTL + config). See **docs/RUNNING_E1_E3_AND_PPA.md** for:\n\n- Docker-based flow with `openroad/orfs`\n- Native orfs-build\n- Preparing the APTPU design in the flow\n\n---\n\n## License and citation\n\nSee repository metadata. If you use ARCADE in research, please cite the accompanying paper.\n"}, "e2c3ece1bd38e1d3a01654bae5ea763f6e842aac": {"t": 1785771648.3203804, "n": 5018, "h": "0d7a77d2e033d4f8", "c": "# ARCADE\n\n**A**utonomous **R**TL **C**reation with **A**gents, **D**iagnostics, and **E**rror memory — multi-agent approximate adder generation with closed-loop repair and retrieval-augmented error memory (RAEM).\n\n---\n\n## Overview\n\nARCADE is an LLM-driven framework for generating Verilog approximate adders from minimal specs (`bit_width`, `nmed_target`, `area_priority`). A **Design Agent** produces RTL; a **Verifier Agent** produces a black-box testbench from the same spec; a **golden Verilator harness** computes Normalized Mean Error Distance (NMED) vs exact addition and is the final judge. Passing designs can be wired into an OpenROAD flow for PPA (area, power, timing) evaluation.\n\n### Experiment modes (E1–E4)\n\n| Mode | Name | Description |\n|------|------|-------------|\n| **E1** | **ARCADE-Vanilla** | Single-shot generation with no repair loop and no retrieval memory, establishing the baseline capability of the underlying model. |\n| **E2** | **ARCADE-Repair** | Adds the closed-loop repair mechanism, feeding structured NMED failure diagnostics back to the Design Agent across up to five iterations. |\n| **E3** | **ARCADE-Memory** | Augments repair with RAEM retrieval, prepending the top-*k* historically similar failure contexts to each repair prompt. |\n| **E4** | **ARCADE-Full** | Same pipeline as E3; used for learning-curve analysis over the spec order (RAEM fills over a sequential run). |\n\nSpecs are defined in `configs/adder_specs.json` (13 specs: 8/16/32-bit, varying NMED and area priority). See **implementation.md** for pipeline details.\n\n---\n\n## Prerequisites\n\n- **Python 3.10+**\n- **uv** (or pip) for installing the package\n- **Verilator** — to compile and run the golden NMED harness\n- **API key** — at least one of: DeepSeek (default), Claude, OpenRouter, OpenAI\n- **OpenROAD flow** (optional) — only if you want PPA; e.g. Docker `openroad/orfs` or native orfs-build\n\n---\n\n## Setup\n\n```bash\ncd ARCADE\nuv venv && source .venv/bin/activate   # Windows: .venv\\Scripts\\activate\nuv pip install -e .\n```\n\n### API keys (required for LLM calls)\n\nSet **environment variables** (recommended for security):\n\n- `DEEPSEEK_API_KEY` (default provider)\n- `ANTHROPIC_API_KEY` (for `--provider claude`)\n- `OPENROUTER_API_KEY`, `OPENAI_API_KEY` (if using those providers)\n\nAlternatively, you can use a **local keys file** in the repo root (gitignored): create `keys.txt` with PowerShell-style lines, e.g.:\n\n```text\n$env:DEEPSEEK_API = 'sk-...'\n$env:ANTHROPIC_API_KEY = '...'\n```\n\nDo **not** commit `keys.txt` or any file containing secrets.\n\n---\n\n## Directory layout\n\n```\nARCADE/\n├── configs/\n│   ├── adder_specs.json\n│   └── professor_papers.json\n├── harness/\n│   └── tb_adder.cpp          # Golden NMED harness (Verilator)\n├── src/\n│   ├── orchestrator.py        # Main entry: modes E1–E4, smoke\n│   ├── design_agent.py\n│   ├── verifier_agent.py\n│   ├── ppa_loop.py            # OpenROAD flow (Docker or native)\n│   ├── aptpu_integrator.py    # Injects passing adder into flow\n│   └── config.py              # Paths, API key loading\n├── results/                   # E1_results.json, E2_results.json, ... (gitignored)\n├── work/                      # Per-spec Verilator run dirs (gitignored)\n├── run_all_experiments.sh     # E1→E4 with --resume / --start-from\n├── implementation.md         # Framework and experiment details\n└── docs/\n    └── RUNNING_E1_E3_AND_PPA.md\n```\n\n---\n\n## Run\n\n### Smoke test (single spec)\n\n```bash\npython -m src.orchestrator --mode smoke --spec-id A1\n```\n\n### Single mode, few specs (NMED only; no flow required)\n\n```bash\npython -m src.orchestrator --mode E1 --limit 3\npython -m src.orchestrator --mode E2 --limit 3 --provider deepseek\n```\n\n### Single mode with PPA (flow root required)\n\n```bash\npython -m src.orchestrator --mode E1 --limit 13 --flow-root /path/to/flow\n```\n\n### Full suite (E1 → E4) and resume\n\n```bash\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow\n# Resume after partial run:\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow --resume\n# Start from E3 only:\n./run_all_experiments.sh --limit 13 --flow-root /path/to/flow --resume --start-from E3\n```\n\n- **--resume:** Skips modes that already have `limit` results; for partial runs, runs only missing spec IDs and merges.\n- **--start-from E2|E3|E4:** Skips earlier modes.\n- **--workers N:** Parallel workers per mode (default 4).\n- **--with-ppa:** Run PPA inline (1 worker). By default PPA runs as a batch after all verification runs.\n\nResults are written to `results/E1_results.json`, `results/E2_results.json`, etc. Each entry includes `pass`, `nmed`, `ppa` (if flow was run), and `integration` when applicable.\n\n---\n\n## OpenROAD flow (optional)\n\nFor PPA you need a prepared flow directory (design RTL + config). See **docs/RUNNING_E1_E3_AND_PPA.md** for:\n\n- Docker-based flow with `openroad/orfs`\n- Native orfs-build\n- Preparing the APTPU design in the flow\n\n---\n\n## License and citation\n\nSee repository metadata. If you use ARCADE in research, please cite the accompanying paper.\n"}}}}