REAP Cognitive ARC Solver

Author: Daniel Madden

Overview

REAP is a research-grade toolkit for the Abstraction and Reasoning Challenge (ARC). The project combines a deterministic program synthesis engine with cognition-inspired telemetry, an HTTP API, and a browser dashboard. The goal is to enable reproducible ARC experiments, controlled solver sweeps, and live monitoring during the ARC Prize seasons.

Key features

• Deterministic symbolic search with guarded pruning for explainable ARC solutions.
• Adaptive meta-controller that tunes beam search depth, branching, and revision cadence at runtime.
• Flask API with Server-Sent Events telemetry for job state, entropy trends, and revision metrics.
• Optional neural guidance hooks and natural language summarisation for candidate programs.
• React and Tailwind dashboard served by Flask for Run All, Reset, and replay workflows.

Typical use cases

• Running batch solver sweeps against published ARC datasets with consistent seeding.
• Capturing telemetry streams for offline analysis of solver behaviour.
• Extending the search heuristics or program library while keeping reproducibility constraints.
• Hosting a local dashboard for lab sessions, competitions, or classroom demonstrations.

Documentation

Additional design notes and references are available in the repository root and docs/ directory:

• ARCHITECTURE.md summarises solver components and the telemetry pipeline.
• API_REFERENCE.md documents REST endpoints.
• DEVELOPER_GUIDE.md covers local development workflows.
• docs/ROADMAP.md archives historical planning notes.

Repository layout

reap/                Package source for solver, cognition modules, and Flask UI shell
reap/ui/static/react Front-end source managed via Vite and npm
scripts/             Maintenance scripts for datasets and solver automation
tests/               Pytest suites exercising solver, API, and telemetry contracts
docs/                Extended documentation, guides, and screenshots

Dependency overview

reap
 ├── cognition/            → heuristic scoring, rule confidence tracking, and metrics helpers
 ├── search/               → beam search, parameter synthesis, and revision scheduling
 ├── solver.py             → task orchestration and candidate evaluation entry points
 ├── ui/                   → Flask blueprint, SSE telemetry endpoints, and dashboard templates
 ├── cli.py                → command-line harness for batch experiments
 └── neural_guidance.py    → optional PyTorch hooks for learned guidance

tests
 ├── test_program_execution.py → execution and solver regression coverage
 ├── test_ui_api.py            → API contract and dataset enumeration validation
 └── test_run_all_tasks.py     → end-to-end batch run smoke checks

tools
 └── ui_validate.py           → UI build and smoke-test automation

Installation

The project targets Python 3.9 through 3.13. Create an isolated environment and install the package with optional extras as needed.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .[dev,ui]

To include neural guidance utilities, install the optional extra:

pip install -e .[neural]

Front-end dependencies

The dashboard code lives under reap/ui/static/react. Install Node.js 18+ and use npm to build the assets:

npm install --prefix reap/ui/static/react
npm run build --prefix reap/ui/static/react

Quick start

1. Configure the Python environment and install dependencies as described above.
2. Initialise the dataset directory (datasets/) with ARC JSON files if not already present.
3. Build the dashboard assets (optional for API-only use cases).
4. Launch the API and dashboard with python run_ui.py.
5. Open http://localhost:5000 to monitor solver telemetry.

Example usage

Command-line batch run

python -m reap.cli \
  --infile datasets/arc-agi_evaluation_challenges.json \
  --outfile runs/eval_submission.json \
  --time-budget 30 \
  --max-workers 4 \
  --revisions

REST API invocation

curl -X POST http://localhost:5000/run \
  -H "Content-Type: application/json" \
  -d '{
        "dataset": "arc-agi_evaluation_challenges.json",
        "tasks": ["*"],
        "search_modes": ["beam"],
        "time_budget_s": 30,
        "beam_size": 320,
        "max_depth": 8,
        "exploration_temp": 0.6,
        "enable_revisions": true,
        "seed": 1337
      }'

Troubleshooting and support

• Ensure the virtual environment uses Python 3.9 or newer to avoid dependency resolution issues.
• Bandwidth-heavy Playwright installations may require the PLAYWRIGHT_BROWSERS_PATH=0 environment variable in constrained CI.
• The Flask server defaults to 0.0.0.0; adjust REAP_UI_HOST and reverse-proxy settings before exposing to untrusted networks.
• For UI build issues, clean reap/ui/static/react/node_modules and rerun npm install.

Report issues or request support by opening a discussion or issue in the repository tracker.

License

This project is released under the MIT License. See LICENSE for details.

Credits

REAP and the accompanying documentation were created by Daniel Madden for ARC Prize research workflows.