Ayoai ARC-AGI-3 Integration
Minimal agent framework for ARC-AGI-3 abstract reasoning games, stripped down to essentials for integration with ayoai.com.
What's Inside
This is a simplified version of the ARC-AGI-3 agent framework containing only:
- Game Loop Driver - Simple main.py that interacts with the ARC-AGI-3 API
- Random Action Picker - Basic random action selection for testing (to be replaced with ayoai.com)
- Core Data Structures - Pydantic models for game data (structs.py)
- Recording Utilities - Gameplay recording to JSONL files (recorder.py)
- Minimal Dependencies - Just 3 core packages (dotenv, pydantic, requests)
All LLM-related code, agent abstractions, multi-agent orchestration (Swarm), and optional features have been removed for clarity.
Basic Usage
- Basic usage:
uv run main.py --game ls20-fa137e247ce6
- With recording:
uv run main.py --game ls20-fa137e247ce6 --record
- With tags:
uv run main.py --game ls20-fa137e247ce6 --tags "experiment,v1.0"
Setup
1. Install uv
Install uv package manager if not already installed:
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
2. Install Dependencies
uv sync
3. Set API Key
Get an API key from the ARC-AGI-3 Website and set it as an environment variable:
export ARC_API_KEY="your_api_key_here"
Alternatively, create a .env file in the project root:
ARC_API_KEY=your_api_key_here
Running the Agent
Finding Available Game IDs
Game IDs include a unique hash suffix (e.g., ls20-fa137e247ce6). To see current game IDs, run:
uv run main.py --game test
The error message will show all available games:
Available games: ls20-fa137e247ce6, as66-821a4dcad9c2, vc33-6ae7bf49eea5, sp80-0605ab9e5b2a, lp85-d265526edbaa, ft09-b8377d4b7815
Common game prefixes:
ls20-* - Locksmith game (20 levels)as66-* - Another game (66 levels)vc33-* - Another game (33 levels)- etc.
Basic Usage
Run the game loop with random actions (for testing):
uv run main.py --game ls20-fa137e247ce6
The game currently uses a simple random action picker for testing the game loop. This will eventually be replaced with ayoai.com integration.
With Recording
Record gameplay to a JSONL file for later playback:
uv run main.py --game ls20-fa137e247ce6 --record
Recordings are saved to the recordings/ directory.
With Custom Tags
Add tags to track scorecard results:
uv run main.py --game ls20-fa137e247ce6 --tags "experiment,v1.0"
Command-Line Options
-g, --game Game ID to play (required). Example: "ls20-fa137e247ce6"
-r, --record Record gameplay to a JSONL file and keep a per-run copy of logs.log
(on by default; --no-record turns it off)
-t, --tags Comma-separated tags for scorecard (optional)
Note: Game IDs include unique hash suffixes. Run with an invalid game ID to see the list of available games.
Offline Play (no key, no network)
arc-agi 0.9.9 and arcengine 0.9.3 run games locally from environment_files/. Play one dev game through the local solver and print FPS, end state and levels_completed (held-out exam games in eval/heldout.json are refused):
.venv/bin/python offline_run.py --game ls20 --frame-out tests/fixtures/offline_frame_ls20.json
Measured on cc-03 (2026-09-24): ls20, 401 actions in 0.63 s = 640 FPS through the solver, 1853 FPS bare engine; NOT_FINISHED, levels_completed 0 of win_levels 7. Frames carry levels_completed and win_levels; there is no score field.
Where uv is not installed, the gate is .venv/bin/python -m pytest -q -p no:cacheprovider, .venv/bin/ruff check . and .venv/bin/mypy ..
Tests
Run the test suite from the repo root:
uv run python -m pytest
Use python -m pytest. The bare pytest script cannot collect this repo
(ModuleNotFoundError: structs; see conftest.py). The full suite ran 1600 passed and
16 skipped, measured 2026-09-28 at 2ee06f4 (see CLAUDE.md).
Integration with ayoai.com
The choose_random_action() function in main.py:41 is a placeholder that currently generates random actions for testing. This is where you'll integrate with ayoai.com:
def choose_random_action(frame: FrameData) -> GameAction:
"""
Simple random action picker for testing the game loop.
TODO: Replace this with ayoai.com integration:
- Send frame data to ayoai.com
- Receive action decision
- Return the chosen action
"""
# Reset if game not started or game over
if frame.state in [GameState.NOT_PLAYED, GameState.GAME_OVER]:
return GameAction.RESET
# Pick random action from available (exclude RESET)
actions = [a for a in GameAction if a != GameAction.RESET]
return random.choice(actions)
To integrate with ayoai.com, replace this function with API calls to your decision-making service.
Key API Integration Details
The send_action() function (main.py:59) handles communication with the ARC-AGI-3 API:
def send_action(
session: requests.Session,
game_id: str,
card_id: str,
action: GameAction,
guid: str | None = None
) -> FrameData | None:
Important: The guid parameter is required for all actions except RESET:
- When you send a RESET action, no guid is needed
- The API response includes a
guid in the returned FrameData
- This guid must be sent with all subsequent actions
- The guid maintains game state continuity between requests
Example flow:
- Send RESET (no guid) → API returns frame with guid
- Send ACTION1 with guid → API returns new frame with updated guid
- Send ACTION2 with new guid → continues...
The game loop (main.py:229) automatically passes the current frame's guid to each action:
new_frame = send_action(session, args.game, card_id, action, current_frame.guid)
Game States
The GameState enum in structs.py defines the possible game states:
NOT_PLAYED - Game hasn't been started yetNOT_FINISHED - Game is currently in progressWIN - Game was completed successfullyGAME_OVER - Game ended without winning
Your integration code should check for terminal states (WIN or GAME_OVER) to know when the game has ended.
Project Structure
├── tests/
│ └── unit/ # Unit tests
├── main.py # Game loop driver (entry point)
├── structs.py # Data structures (FrameData, GameAction, etc.)
├── recorder.py # Gameplay recording utilities
├── README.md # This file
└── pyproject.toml # Dependencies and configuration
Development
This project uses:
- uv for package management
- ruff for linting and formatting
- mypy for type checking
- pytest for testing
Set up pre-commit hooks:
pip install pre-commit
pre-commit install
License
This project contains code derived from the ARC-AGI-3-Agents repository.
If I get this error
- this error: """error: Project virtual environment directory
C:\ZakNoCloud\GitHub\Ayoai\Ayoai-ARC-AGI-3-Integration\.venv cannot be used because it is not a valid Python environment (no Python executable was found)"""
- then run these commans windown powershell:
- Go to the repo
- Set-Location "C:\ZakNoCloud\GitHub\Ayoai\Ayoai-ARC-AGI-3-Integration"
- Remove the WSL-created venv that lives on the Windows filesystem
- Remove-Item -Recurse -Force .venv -ErrorAction SilentlyContinue
- Install uv (current PowerShell session)
- Recreate the Windows-native venv and install deps uv will create .venv for the project and sync from pyproject/lock/requirements.*
