### PORT Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the PORT environment variable.

```bash
export PORT="8001"   # Standard
export PORT="443"    # HTTPS
```

--------------------------------

### BFS Solver Tuning Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of instantiating the BFSSolver with tuning parameters.

```python
BFSSolver(src, cls_name, scan_timeout=5, bfs_timeout=180)
```

--------------------------------

### start_recording() example usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of starting recording and accessing the recorder filename.

```python
agent.start_recording()
print(f"Recording to: {agent.recorder.filename}")
```

--------------------------------

### SCHEME Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the SCHEME environment variable.

```bash
export SCHEME="https"
```

--------------------------------

### RECORDINGS_DIR Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the RECORDINGS_DIR environment variable and creating the directory.

```bash
export RECORDINGS_DIR="/kaggle/working/recordings"
mkdir -p $RECORDINGS_DIR
```

--------------------------------

### HOST Examples

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Examples of setting the HOST environment variable for different environments.

```bash
export HOST="gateway"  # Kaggle competition
export HOST="api.example.com"
```

--------------------------------

### get() Method Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of retrieving recorded events and printing their timestamps and data.

```python
events = recorder.get()
for event in events:
    timestamp = event["timestamp"]
    data = event["data"]
    print(f"{timestamp}: {data}")
```

--------------------------------

### OPERATION_MODE Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the OPERATION_MODE environment variable.

```bash
export OPERATION_MODE="online"
```

--------------------------------

### get_recordings_dir() Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of how to get the recordings directory.

```python
rec_dir = get_recordings_dir()
print(f"Recordings go to: {rec_dir}")
```

--------------------------------

### Development .env File Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example content for a .env file used for local development.

```bash
SCHEME=http
HOST=localhost
PORT=8001
ARC_API_KEY=dev-key-123
ARC_BASE_URL=http://localhost:8001/
OPERATION_MODE=offline
RECORDINGS_DIR=/tmp/recordings
DEBUG=False
```

--------------------------------

### MyAgent Constructor Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/myagent.md

An example of how to instantiate the MyAgent class.

```python
agent = MyAgent(
    card_id="card-001",
    game_id="locksmith",
    agent_name="myagent",
    ROOT_URL="http://localhost:8001",
    record=True,
    arc_env=Arcade().make("locksmith"),
    tags=["forge", "v19"],
)
```

--------------------------------

### ARC_API_KEY Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the ARC_API_KEY environment variable and running the agent.

```bash
export ARC_API_KEY="your-api-key-here"
python main.py --agent myagent
```

--------------------------------

### Agent CLI Parameter Example: myagent

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Bash command-line examples for selecting the 'myagent' agent.

```bash
python main.py --agent myagent
python main.py --agent "locksmith.myagent.0.abc123.recording.jsonl"
```

--------------------------------

### Install ARC AGI Dependencies

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Installs the necessary ARC AGI libraries and dependencies using pip. Ensure you are in an environment where these packages can be installed.

```python
!pip install -q --no-index --find-links \
    /kaggle/input/competitions/arc-prize-2026-arc-agi-3/arc_agi_3_wheels \
    arc-agi python-dotenv
```

--------------------------------

### torch.nn.Module Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of initializing and using a PyTorch Module like ForgeNet.

```python
net = ForgeNet(in_channels=26)
net = net.to(device)
net.train()  # Enable dropout
out = net(tensor_input)
```

--------------------------------

### Listing Recordings

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of listing all recordings and extracting game ID and GUID.

```python
from agents.recorder import Recorder

recordings = Recorder.list()
for rec in recordings:
    game_id = Recorder.get_prefix_one(rec)
    guid = Recorder.get_guid(rec)
    print(f"Game: {game_id}, GUID: {guid}")
```

--------------------------------

### GameState Usage Examples

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Examples showing how to check the current game state.

```python
if latest_frame.state is GameState.WIN:
    return True  # Agent done

if latest_frame.state in [GameState.NOT_PLAYED, GameState.GAME_OVER]:
    return GameAction.RESET
```

--------------------------------

### AGENTOPS_API_KEY Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the AGENTOPS_API_KEY environment variable for AgentOps tracing.

```bash
export AGENTOPS_API_KEY="..."
python main.py --agent myagent
```

--------------------------------

### OPENAI_API_KEY Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the OPENAI_API_KEY environment variable for LLM-based agents.

```bash
export OPENAI_API_KEY="sk-..."
python main.py --agent llm
```

--------------------------------

### EnvironmentScorecard Usage Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of how to use the EnvironmentScorecard after closing a scorecard.

```python
# In Swarm.main()
scorecard = swarm.close_scorecard(card_id)
print(f"Total score: {scorecard.total_score}")
for game_record in scorecard.games:
    print(f"  {game_record.game_id}: {game_record.levels_completed} levels")
```

--------------------------------

### Recorder Constructor Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Examples of creating a Recorder instance for new recordings and for playback.

```python
# For a new recording
recorder = Recorder(prefix="locksmith.myagent.0")
# Creates: /recordings_dir/locksmith.myagent.0.{uuid}.recording.jsonl

# For playback
recorder = Recorder(
    prefix="locksmith.myagent.0",  # Unused in playback
    filename="locksmith.myagent.0.abc123-def456.recording.jsonl"
)
```

--------------------------------

### Arcade Usage Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of initializing the Arcade environment and making a game environment.

```python
# In Swarm.__init__()
self._arc = Arcade()

# In Swarm.main()
arc_env = self._arc.make("locksmith", scorecard_id=card_id)
agent = MyAgent(..., arc_env=arc_env)
```

--------------------------------

### _scan_actions Example Usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Shows an example of calling _scan_actions and the expected return format for actionable steps.

```python
actions = solver._scan_actions(game, initial_frame, 0)
# Returns: [(1, None), (2, None), (6, {"x": 3, "y": 5, "game_id": "bfs"}), ...]
```

--------------------------------

### File Naming Convention Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of the file naming convention for recordings.

```text
locksmith.myagent.0.abc123de-f456-789g-hijk-lmnopqrstuv.recording.jsonl
```

--------------------------------

### main() example usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of how to instantiate and run the main agent loop.

```python
agent = MyAgent(...)
agent.main()  # Blocks until game finished
print(f"Completed {agent.levels_completed} levels in {agent.seconds}s")
```

--------------------------------

### DEBUG Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the DEBUG environment variable to enable DEBUG-level logging.

```bash
export DEBUG="True"
python main.py --agent myagent 2>&1 | tee debug.log
```

--------------------------------

### BFSSolver Integration Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Demonstrates how to initialize and use the BFSSolver within the MyAgent framework, including loading the solver, solving a level, and preparing for solution execution.

```python
# Initialization (first level only)
self._bfs = BFSSolver(src, cls_name, scan_timeout=5, bfs_timeout=180)
self._bfs.load()

# Per-level solving
solution = self._bfs.solve_level(level_idx, prev_solution=self._bfs.solutions.get(level_idx-1))

# Solution execution
if solution:
    self._bfs_solution = solution
    self._bfs_step = 0
    # Later, execute actions one by one in main choose_action loop
```

--------------------------------

### Example Execution

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/myagent.md

Illustrates different scenarios of level detection and solution attempts.

```python
# Level 0 detected, attempt BFS
# BFS finds 5-action solution in 2.3s -> Execute and win level

# Level 1 detected, attempt BFS
# BFS times out after 120s, no solution found
# Initialize CNN with pre-trained weights
# Inject 5 expert demos from level 0 solution
# Run 80 actions with ε-greedy CNN policy
# If solved: win level
# If timeout: end with best attempt
```

--------------------------------

### BFSSolver Constructor Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Demonstrates how to instantiate the BFSSolver class with required and optional parameters.

```python
solver = BFSSolver(
    game_path="/path/to/locksmith.py",
    game_class_name="Locksmith",
    scan_timeout=5,
    bfs_timeout=180,
)
```

--------------------------------

### Agent CLI Parameter Example: Tags

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Bash command-line example for setting scorecard tags and the resulting Python list of tags.

```bash
python main.py --agent myagent --tags "experiment,v19,with_aem"
# Resulting tags:
python main.py --agent myagent --tags "experiment,v19,with_aem"
```

--------------------------------

### Recorder.list() Class Method Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of listing available recording files and using them for playback.

```python
recordings = Recorder.list()
# Returns: [
#     "locksmith.myagent.0.abc123.recording.jsonl",
#     "puzzle.random.0.def456.recording.jsonl",
#     ...
# ]

# Use for playback
for rec_file in recordings:
    swarm = Swarm(agent=rec_file, ...)
```

--------------------------------

### DEBUG Log Level Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/errors.md

Example of a detailed debug log message.

```python
logger.debug(f"BFS L{level_idx}: state_hash={state_hash}")
```

--------------------------------

### GameAction Usage Examples

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Examples demonstrating how to use GameAction for simple and complex actions, and how to convert from an ID.

```python
# Simple action
action = GameAction.ACTION1
return_value = agent.take_action(action)

# Complex action with data
action = GameAction.ACTION6
action.set_data({"x": 32, "y": 32})
return_value = agent.take_action(action)

# By ID
action = GameAction.from_id(6)
action.set_data({"x": 0, "y": 0})
```

--------------------------------

### MyAgent Usage Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/myagent.md

Example of how to instantiate and run MyAgent using the Swarm class.

```python
from agents import Swarm

# Run MyAgent on all games
swarm = Swarm(
    agent="myagent",
    ROOT_URL="http://gateway:8001",
    games=["locksmith", "puzzle", "maze"],
    tags=["forge", "v19"],
)

scorecard = swarm.main()
print(f"Final score: {scorecard.total_score}")
```

--------------------------------

### Swarm Class Initialization Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/swarm.md

Example of how to initialize the Swarm class with agent, root URL, games, and optional tags.

```python
from agents import Swarm

swarm = Swarm(
    agent="myagent",
    ROOT_URL="http://localhost:8001",
    games=["locksmith", "puzzle"],
    tags=["experiment", "v1"],
)
```

--------------------------------

### BFSSolver load() Method Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Shows how to use the load() method to load the game class and check for success.

```python
if solver.load():
    print(f"Loaded {solver.class_name}")
else:
    print("Failed to load game class")
```

--------------------------------

### ActionEffectAttention Example Usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/neural-network.md

Example of how to instantiate and use the ActionEffectAttention module.

```python
aem = ActionEffectAttention(feat_dim=64, mem_dim=32)

cnn_feat = torch.randn(4, 64)  # CNN features from current frame
mem_diffs = torch.randn(4, 10, 1, 64, 64)  # 10 recent difference maps
mem_actions = torch.tensor([[0, 1, 2, 1, 0, 3, 4, 2, 1, 3]])  # Action history
mem_rewards = torch.tensor([[0.5, 1.5, 0.2, 1.0, 0.3, 0.8, 1.5, 0.1, 0.7, 1.2]])

logits = aem(cnn_feat, mem_diffs, mem_actions, mem_rewards)
```

--------------------------------

### Agent CLI Parameter Example: Game Filter

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Bash command-line examples for filtering games using the --game parameter.

```bash
python main.py --agent myagent --game locksmith
python main.py --agent myagent --game "locksmith,puzzle"
```

--------------------------------

### Kaggle Notebook: pip install

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Bash command to install project dependencies within a Kaggle notebook using local wheels.

```bash
!pip install -q --no-index --find-links \
    /kaggle/input/competitions/arc-prize-2026-arc-agi-3/arc_agi_3_wheels \
    arc-agi python-dotenv
```

--------------------------------

### Open Scorecard Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/swarm.md

Example of how to open a scorecard using the open_scorecard method.

```python
card_id = swarm.open_scorecard()
print(f"Scorecard ID: {card_id}")
```

--------------------------------

### WARNING Log Level Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/errors.md

Example of a warning log message for a recoverable error.

```python
logger.warning(f"BFS: Failed to load game class: {e}")
```

--------------------------------

### INFO Log Level Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/errors.md

Example of an informational log message for a solved level.

```python
logger.info(f"BFS L{level_idx}: SOLVED in {len(sol)} actions")
```

--------------------------------

### choose_action Simple Action Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of choosing a simple action like ACTION1.

```python
return GameAction.ACTION1
```

--------------------------------

### record() Method Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example usage of the record method to log different types of events.

```python
recorder.record({"type": "action", "action": "ACTION1"})
recorder.record({"type": "frame", "levels_completed": 1})
recorder.record({"type": "reset"})
```

--------------------------------

### Playback Agent Initialization

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of how the Playback agent initializes with a Recorder.

```python
class Playback(Agent):
    def __init__(self, ...):
        super().__init__(...)
        self.recording = Recorder(..., filename=filename)
        self.actions = self.filter_actions()
        self.action_idx = 0
    
    def choose_action(self, frames, latest_frame):
        if self.action_idx < len(self.actions):
            action_data = self.actions[self.action_idx]
            self.action_idx += 1
            return GameAction.from_data(action_data)
        return GameAction.RESET
```

--------------------------------

### _state_hash Example Usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Illustrates how to use the _state_hash method for simple pixel-only hashing and for full state hashing including hidden fields.

```python
# Simple hash: pixels only
h1 = solver._state_hash(game, frame)  # "a3b2c1d4e5f6g7h8"

# Full hash: pixels + hidden fields
h2 = solver._state_hash(game, frame, ["_counter", "_phase"])
# "a3b2c1d4e5f6g7h8|_counter=5|_phase=2"
```

--------------------------------

### choose_action Action with Reasoning Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of setting reasoning for an action, useful for logging.

```python
action.reasoning = "clicked suspicious area"
return action
```

--------------------------------

### Agent Constructor Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

An example demonstrating how to instantiate an Agent subclass (Random) with necessary parameters.

```python
from agents.agent import Agent
from arc_agi import Arcade

agent = Random(
    card_id="abc123",
    game_id="locksmith",
    agent_name="random",
    ROOT_URL="http://localhost:8001",
    record=True,
    arc_env=Arcade().make("locksmith", scorecard_id="abc123"),
    tags=["baseline", "v1"],
)
```

--------------------------------

### Pandas DataFrame Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of creating a Pandas DataFrame for submission and saving it as a parquet file.

```python
import pandas as pd

submission = pd.DataFrame(
    data=[['1_0', '1', True, 1]],
    columns=['row_id', 'game_id', 'end_of_game', 'score']
)
submission.to_parquet('/kaggle/working/submission.parquet', index=False)
```

--------------------------------

### _probe_hidden_fields Example Usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Provides an example of calling _probe_hidden_fields and the expected output format.

```python
fields = solver._probe_hidden_fields(game, [(1, None), (6, {...})])
# Returns: ["_turn_count", "_phase"]
```

--------------------------------

### EnvironmentWrapper Usage Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of using the EnvironmentWrapper's step method within an agent's action handling.

```python
# In MyAgent.do_action_request()
data = action.action_data.model_dump()
raw_frame = self.arc_env.step(action, data=data, reasoning=...)
```

--------------------------------

### take_action() example usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of taking an action and processing the returned frame.

```python
action = GameAction.ACTION1
frame = agent.take_action(action)
if frame:
    print(f"New levels_completed: {frame.levels_completed}")
```

--------------------------------

### is_done Method Example Implementation

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

An example implementation of the 'is_done' method, checking for a win state.

```python
def is_done(self, frames: list[FrameData], latest_frame: FrameData) -> bool:
    return latest_frame.state is GameState.WIN
```

--------------------------------

### _try_transfer Example Usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Demonstrates how _try_transfer adjusts a previous solution's click coordinates for a new level.

```python
prev_sol = [(1, None), (6, {"x": 30, "y": 30}), (2, None)]
new_sol = solver._try_transfer(game, 1, prev_sol, current_frame)
# Might return: [(1, None), (6, {"x": 33, "y": 28})]
# (adjusted click position for level 1)
```

--------------------------------

### get() Method Behavior

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Demonstrates how the get method reads and parses all JSONL lines from the file.

```python
events = []
with open(self.filename, "r") as f:
    for line in f:
        line = line.strip()
        if line:
            events.append(json.loads(line))
return events
```

--------------------------------

### collections.deque Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of initializing a deque with a maximum length and appending entries, followed by random sampling.

```python
from collections import deque

self.buf = deque(maxlen=50000)  # Max 50K elements
self.buf.append({'s': state, 'a': action, 'r': reward})

# Random sampling
indices = np.random.choice(len(self.buf), batch_size)
batch = [self.buf[i] for i in indices]
```

--------------------------------

### Running an Agent

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example demonstrating how to instantiate and run a custom agent using the Arcade environment.

```python
from agents.agent import Agent
from arc_agi import Arcade

agent = SimpleAgent(
    card_id="card-001",
    game_id="locksmith",
    agent_name="simple",
    ROOT_URL="http://localhost:8001",
    record=True,
    arc_env=Arcade().make("locksmith"),
    tags=["test"],
)

agent.main()  # Blocks until done
print(f"Levels: {agent.levels_completed}, Time: {agent.seconds}s, FPS: {agent.fps}")
```

--------------------------------

### Get GUID

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Extracts the GUID segment from a recording filename.

```python
guid = Recorder.get_guid("locksmith.myagent.0.abc123.recording.jsonl")
# Returns: "abc123"
```

--------------------------------

### Swarm Main Method Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/swarm.md

Example of how to use the main method of the Swarm class to run the orchestration and retrieve the scorecard.

```python
swarm = Swarm("myagent", "http://localhost:8001", ["game1", "game2"])
scorecard = swarm.main()
print(f"Total score: {scorecard.total_score}")
print(f"Games completed: {scorecard.games_completed}")
```

--------------------------------

### FrameData Usage Examples

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Examples demonstrating how to access pixel data, check game state, and iterate through available actions from a FrameData object.

```python
# Accessing pixel data
frame = latest_frame
pixel_array = np.array(frame.frame[-1], dtype=np.int64)  # Current frame

# Checking state
if frame.state is GameState.WIN:
    print(f"Won! Completed {frame.levels_completed} levels")

# Available actions
for action in frame.available_actions:
    print(f"Can do: {action.name}")
```

--------------------------------

### Deployment Checklist

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/INDEX.md

A checklist of steps for deploying an agent.

```markdown
□ Read [Configuration](configuration.md)
□ Set ARC_API_KEY
□ Set RECORDINGS_DIR if desired
□ Verify API connectivity
□ Check game list available
□ Review [Swarm](api-reference/swarm.md) for multi-game runs
□ Monitor [errors.md](errors.md) during execution
```

--------------------------------

### Example Usage of BFS Solver

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/bfs-solver.md

Demonstrates how to call the BFS solver for a specific level and process the returned solution.

```python
solution = solver.solve_level(0, max_states=500000)
if solution:
    print(f"Found {len(solution)}-action solution")
    for i, (act_id, data) in enumerate(solution):
        print(f"  {i}: ACTION{act_id} {data}")
else:
    print("No solution found in time")
```

--------------------------------

### choose_action Complex Action Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of choosing a complex action (e.g., click) and setting its data.

```python
action = GameAction.ACTION6
action.set_data({"x": 32, "y": 32})
return action
```

--------------------------------

### Kaggle Notebook: Environment Setup

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Python code to set an environment variable for triggering submission mode in Kaggle.

```python
import os
os.environ["KAGGLE_IS_COMPETITION_RERUN"] = "True"
```

--------------------------------

### Recording a Game

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of using Swarm to automatically record a game session.

```python
from agents import Swarm

# Swarm automatically records when record=True in agent creation
swarm = Swarm(
    agent="myagent",
    ROOT_URL="http://localhost:8001",
    games=["locksmith"],
)

scorecard = swarm.main()
# Creates: /recordings_dir/locksmith.myagent.0.uuid.recording.jsonl
```

--------------------------------

### Loading Events Programmatically

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of loading and iterating through events from a specific recording file.

```python
from agents.recorder import Recorder

recorder = Recorder(
    prefix="locksmith.myagent.0",
    filename="locksmith.myagent.0.abc123.recording.jsonl"
)

events = recorder.get()
for event in events:
    timestamp = event["timestamp"]
    data = event["data"]
    
    if "levels_completed" in data:
        print(f"{timestamp}: Level {data['levels_completed']}")
```

--------------------------------

### choose_action Method - Exploration Strategy: Heuristic Phase

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/myagent.md

Example code for heuristic actions during the initial steps.

```python
# Try direction actions
if step < 4: return directional_action
# Then systematically click colored objects by size
if 6 in available: return click_action
if 5 in available: return action_5
```

--------------------------------

### Kaggle Competition Setup Script

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

This Python script configures the environment for running the agent within the Kaggle competition. It downloads necessary files, copies agent code, and sets up environment variables.

```python
import os
if os.getenv('KAGGLE_IS_COMPETITION_RERUN'):
    !curl --fail --retry 999 --retry-all-errors --retry-delay 5 --retry-max-time 600 http://gateway:8001/api/games
    !cp -r /kaggle/input/competitions/arc-prize-2026-arc-agi-3/ARC-AGI-3-Agents /kaggle/working/ARC-AGI-3-Agents
    !cp /kaggle/working/my_agent.py /kaggle/working/ARC-AGI-3-Agents/agents/templates/my_agent.py
    with open('/kaggle/working/ARC-AGI-3-Agents/agents/__init__.py','w') as f:
        f.write("""from typing import Type
from dotenv import load_dotenv
from .agent import Agent, Playback
from .swarm import Swarm
from .templates.random_agent import Random
from .templates.my_agent import MyAgent
load_dotenv()
AVAILABLE_AGENTS: dict[str, Type[Agent]] = {\"random\": Random, \"myagent\": MyAgent}
""")
    with open('/kaggle/working/ARC-AGI-3-Agents/.env','w') as f:
        f.write("""SCHEME=http
HOST=gateway
PORT=8001
ARC_API_KEY=test-key-123
ARC_BASE_URL=http://gateway:8001/
OPERATION_MODE=online
RECORDINGS_DIR=/kaggle/working/server_recording
""")
    !cd /kaggle/working/ARC-AGI-3-Agents && MPLBACKEND=agg python main.py --agent myagent
```

--------------------------------

### New Agent Implementation Checklist

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/INDEX.md

A checklist for implementing a new agent.

```markdown
□ Read [Agent Base Class](api-reference/agent.md)
□ Implement is_done()
□ Implement choose_action()
□ Add to AVAILABLE_AGENTS
□ Test with [Swarm](api-reference/swarm.md)
□ Review [types.md](types.md) for data structures
□ Check [errors.md](errors.md) for exception handling
```

--------------------------------

### MyAgent Initialization

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Initializes the MyAgent with game state, random seeds, device configuration, and data structures for training and BFS solving. Sets up parameters for experience replay, frame history, and exploration.

```python
class MyAgent(Agent):
    MAX_ACTIONS = float('inf')
    _MAX_FRAMES = 10

    def __init__(s, *a, **kw):
        super().__init__(*a, **kw)
        seed = int(time.time()*1e6) + hash(s.game_id) % 1000000
        random.seed(seed); np.random.seed(seed%(2**32-1)); torch.manual_seed(seed%(2**32-1))
        s.start_time = time.time()
        s.device = torch.device('cuda' if torch.cuda.is_available() else ('mps' if torch.backends.mps.is_available() else 'cpu'))
        s.G=64; s.IN=26
        s.net=None; s.opt=None
        s.buf=deque(maxlen=50000); s.buf_h=set()
        s.bsz=64; s.tfreq=10
        s.pt=None; s.pai=None; s.pr=None; s.ph=None
        s.cl=-1; s.fhist=deque(maxlen=6); s.la=0
        s.al=[GameAction.ACTION1,GameAction.ACTION2,GameAction.ACTION3,GameAction.ACTION4,GameAction.ACTION5]
        s._wd=False; s._bg=0; s._wm=None
        s._aem_diffs=deque(maxlen=256); s._aem_actions=deque(maxlen=256); s._aem_rewards=deque(maxlen=256)
        s._ckpt_hash=None; s._unproductive=0; s._undo_avail=False
        s._eps=0.15; s._eps_min=0.03; s._eps_decay=0.9997
        s._prev_objs=None; s._obj_moved=0
        # FIX 1: Initialize _visited_hashes so _reward() deduplication works correctly
        s._visited_hashes = set()
        # BFS solver
        s._bfs = None
        s._bfs_solution = None
        s._bfs_step = 0
        s._bfs_tried = False
```

--------------------------------

### Recorder.get_prefix() Class Method Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of extracting the prefix from a recording filename.

```python
prefix = Recorder.get_prefix("locksmith.myagent.0.abc123.recording.jsonl")
# Returns: "locksmith.myagent.0"
```

--------------------------------

### CBAM Example Usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/neural-network.md

Example of how to instantiate and use the CBAM module.

```python
cbam = CBAM(channels=256)
x = torch.randn(4, 256, 64, 64)
y = cbam(x)  # (4, 256, 64, 64)
```

--------------------------------

### ERROR Log Level Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/errors.md

Example of an error log message for an unrecoverable error.

```python
logger.error("An Agent must be specified")
```

--------------------------------

### Recording Format Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/recorder.md

Example of a single JSON object within a recording file.

```json
{
  "timestamp": "2025-01-15T14:23:45.123456Z",
  "data": {
    "type": "frame",
    "game_id": "locksmith",
    "levels_completed": 1,
    "state": "IN_PROGRESS",
    "available_actions": [1, 2, 3, 4, 5, 6, 7],
    "frame": [[0, 1, 2, ...], [3, 4, 5, ...], ...]
  }
}
```

--------------------------------

### Initialize BFSSolver

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Initializes the BFSSolver with game path, class name, and timeouts. The game class is loaded lazily.

```python
class BFSSolver:
    """Offline BFS solver using direct game class instantiation."""

    def __init__(self, game_path, game_class_name, scan_timeout=3, bfs_timeout=120):
        self.game_path = game_path
        self.class_name = game_class_name
        self.scan_timeout = scan_timeout
        self.bfs_timeout = bfs_timeout
        self.game_cls = None
        self.solutions = {}  # level_idx → action list
```

--------------------------------

### start_recording() method signature

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Initializes a Recorder and logs the recording filename. Called by __init__ if record=True.

```python
def start_recording(self) -> None
```

--------------------------------

### append_frame() example usage

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/agent.md

Example of appending a frame after taking an action.

```python
frame = agent.take_action(action)
agent.append_frame(frame)
```

--------------------------------

### Close Scorecard Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/swarm.md

Example of how to close a scorecard and print its model dump.

```python
scorecard = swarm.close_scorecard(card_id)
if scorecard:
    print(scorecard.model_dump())
```

--------------------------------

### Sample Action from Logits with Availability Masking

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Samples an action from provided logits, considering available actions and optional learned weights. Handles both basic actions and complex actions (like moving to coordinates).

```python
al=logits[:5].clone();cl=logits[5:5+4096].clone()
if avail is not None and len(avail)>0:
    mask=torch.full_like(al,float('-inf'));a6=False
    for a in avail:
        aid=a.value if hasattr(a,'value') else int(a)
        if 1<=aid<=5:mask[aid-1]=0.0
        elif aid==6:a6=True
    al=al+mask
    if not a6:cl=cl+torch.full_like(cl,float('-inf'))
if s._wm is not None:cl=cl+torch.log(s._wm.to(s.device).clamp(min=0.01))
ap=torch.sigmoid(al/temp);cp=torch.sigmoid(cl/temp)/(s.G*s.G)
allp=torch.cat([ap,cp]);sm=allp.sum()
if sm<1e-8:allp=torch.ones_like(allp)/len(allp)
else:allp=allp/sm
idx=np.random.choice(len(allp),p=allp.cpu().numpy())
if idx<5:return idx,None
ci=idx-5;return 5,(ci//s.G,ci%s.G)
```

--------------------------------

### ForgeNet Example Usage - Single Frame Inference

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/neural-network.md

Example of performing single-frame inference with ForgeNet.

```python
net = ForgeNet(in_channels=26, grid_size=64)
net = net.to(device)

# Single frame inference
frame_tensor = torch.randn(1, 26, 64, 64)  # From MyAgent._tensor()
logits = net(frame_tensor)  # (1, 4101)
```

--------------------------------

### Initialize BFS Solver

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Initializes the Breadth-First Search (BFS) solver by finding the game source and class. Attempts to load the solver if it exists, logging success or failure.

```python
def _init_bfs(s):
        """Initialize BFS solver on first call."""
        src, cls = find_game_source_and_class(s.game_id, s.arc_env)
        if src:
            s._bfs = BFSSolver(src, cls, scan_timeout=5, bfs_timeout=180)
            if s._bfs.load():
                logger.info(f"BFS: loaded {cls} from {src}")
            else:
                s._bfs = None
                logger.warning(f"BFS: failed to load game class")
        else:
            logger.warning(f"BFS: game source not found for {s.game_id}")
```

--------------------------------

### Exploration Strategy Formula

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Python code demonstrating the formula for epsilon decay in exploration strategy and its effect over steps.

```python
eps_new = max(eps_min, eps * (decay ** step))
# With decay=0.9997:
#   step 100: eps ≈ 0.14
#   step 500: eps ≈ 0.13
#   step 1000: eps ≈ 0.11
```

--------------------------------

### BFS Solver - Level Initialization and Action Scanning

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Initializes the game level, performs reset actions, and scans for effective actions. Includes a warm-up unlock mechanism for specific level types.

```python
game.set_level(level_idx)
game.perform_action(ActionInput(id=GameAction.RESET), raw=True)

r0 = game.perform_action(ActionInput(id=GameAction.RESET), raw=True)
if not r0.frame:
    return None
f0 = np.array(r0.frame[-1])
bg = int(np.bincount(f0.flatten(), minlength=16).argmax())

# Try solution transfer from previous level first
if prev_solution and level_idx > 0:
    transfer_result = self._try_transfer(game, level_idx, prev_solution, f0)
    if transfer_result:
        return transfer_result

# Phase 1: Scan for effective actions
actions = self._scan_actions(game, f0, bg)

# Warm-up unlock for locked initial states (sc25-type)
if not actions:
    avail = game._available_actions
    for warmup_id in [a for a in avail if a <= 4]:
        g_warmup = copy.deepcopy(game)
        try:
            g_warmup.perform_action(ActionInput(id=GameAction.from_id(warmup_id)), raw=True)
            f_after = np.array(g_warmup.get_pixels(0, 0, 64, 64))
            warmup_actions = self._scan_actions(g_warmup, f_after, bg)
            if warmup_actions:
                logger.info(f"BFS L{level_idx}: UNLOCKED with ACTION{warmup_id}! {len(warmup_actions)} actions")
                game = g_warmup; f0 = f_after; actions = warmup_actions
                break
        except:
            pass

logger.info(f"BFS L{level_idx}: {len(actions)} effective actions")
if not actions:
    return None
```

--------------------------------

### ARC_BASE_URL Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Example of setting the ARC_BASE_URL environment variable to override the full API base URL.

```bash
export ARC_BASE_URL="http://gateway:8001/"
```

--------------------------------

### Performance Tuning: Better Solutions

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Configuration options to improve the quality of solutions, potentially at the cost of completion speed.

```bash
# More BFS time
bfs_timeout=300

# More CNN training
tfreq=5   # Train every 5 actions
bsz=128   # Larger batches

# Better exploration
_eps_init=0.20
_eps_decay=0.9995  # Slower decay
```

--------------------------------

### ForgeNet Example Usage - With Action Effect Memory

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/neural-network.md

Example of using ForgeNet with action effect memory.

```python
# With action effect memory
mem_diffs = torch.randn(1, 10, 1, 64, 64)
mem_actions = torch.tensor([[0, 1, 2, 1, 0, 3, 4, 2, 1, 3]])
mem_rewards = torch.ones(1, 10) * 0.5
logits = net(frame_tensor, mem_diffs, mem_actions, mem_rewards)
```

--------------------------------

### NumPy ndarray Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of creating a NumPy array from frame data, performing a binary operation, and summing the result.

```python
frame = np.array(frame_data.frame[-1], dtype=np.int64)  # (64, 64)
binary = frame == 5  # (64, 64) bool
pixels = np.sum(binary)  # Count pixels
```

--------------------------------

### Performance Tuning: Fast Completion

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/configuration.md

Configuration options to prioritize fast completion of tasks, potentially at the expense of solution quality.

```bash
# Skip BFS, use CNN immediately
# Edit MyAgent.solve_level(): set bfs_timeout=0 or skip call

# Increase exploration
bfs_timeout=30
_eps_decay=0.99  # Slower decay

# Reduce training overhead
tfreq=50  # Train every 50 actions
bsz=32    # Smaller batches
```

--------------------------------

### Agent Action Choice Logic

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/submission.ipynb

Handles level changes, initializes BFS solver and CNN fallback, loads pre-trained weights, and resets agent parameters. It also injects expert demonstrations from previous levels into the replay buffer.

```python
def choose_action(s, frames, lf):
        try:
            lvl = s._lvl(lf)

            # ===== LEVEL CHANGE =====
            if lvl != s.cl:
                # Init BFS solver on first level
                if not s._bfs_tried:
                    s._bfs_tried = True
                    s._init_bfs()

                # Try BFS for this level
                s._bfs_solution = None
                s._bfs_step = 0
                if s._bfs:
                    s._try_bfs_solve(lvl)

                # Init CNN fallback
                s.buf.clear(); s.buf_h.clear()
                s.net = ForgeNet(s.IN, s.G).to(s.device)
                for wp in ['/kaggle/input/forge-pretrained-weights/pretrained_weights.pt',
                           'pretrained_weights.pt']:
                    try:
                        if os.path.exists(wp):
                            state=torch.load(wp,map_location=s.device,weights_only=True)
                            ms=s.net.state_dict()
                            for k in list(state.keys()):
                                if k in ms and state[k].shape==ms[k].shape:ms[k]=state[k]
                            s.net.load_state_dict(ms);break
                    except: pass
                s.opt = optim.Adam(s.net.parameters(), lr=0.0003)
                s.pt=None;s.pai=None;s.pr=None;s.ph=None
                s.cl=lvl;s.fhist.clear();s.la=0
                s._wd=False;s._wm=None
                s._aem_diffs.clear();s._aem_actions.clear();s._aem_rewards.clear()
                s._prev_objs=None;s._obj_moved=0;s._ckpt_hash=None;s._unproductive=0
                # FIX 1: Reset visited hashes on every level change
                s._visited_hashes = set()
                # FIX 4: Only reset epsilon if BFS didn't solve this level.
                # If BFS solved it, keep current eps so CNN fallback (if needed)
                # benefits from accumulated exploration knowledge.
                if not s._bfs_solution:
                    s._eps = 0.15

                # CLTI — inject BFS demos from previous level into CNN replay buffer
                # FIX 2: Use perform_action frame[-1] consistently with _raw(),
                # instead of get_pixels() which returns a different format.
                if lvl > 0 and s._bfs and s._bfs.solutions.get(lvl - 1):
                    prev_sol = s._bfs.solutions[lvl - 1]
                    try:
                        replay_game = s._bfs.game_cls()
                        replay_game.set_level(lvl - 1)
                        replay_game.perform_action(ActionInput(id=GameAction.RESET), raw=True)
                        r0 = replay_game.perform_action(ActionInput(id=GameAction.RESET), raw=True)
                        if r0.frame:
                            # Start from the post-reset frame, consistent with _raw()
                            prev_frame = np.array(r0.frame[-1], dtype=np.int64)
                            for act_id, data in prev_sol:
                                ai = ActionInput(id=GameAction.from_id(act_id), data=data) if data else ActionInput(id=GameAction.from_id(act_id))
                                result = replay_game.perform_action(ai, raw=True)
                                action_idx = (act_id - 1) if act_id <= 5 else (
                                    5 + data.get('y', 0) * 64 + data.get('x', 0) if data else 0)
                                s.buf.append({'s': prev_frame.copy(), 'a': action_idx, 'r': 2.0})
                                # Advance prev_frame using the action result, not get_pixels()
                                if result.frame:
                                    prev_frame = np.array(result.frame[-1], dtype=np.int64)
                            if len(s.buf) >= s.bsz:
                                for _ in range(min(20, len(s.buf) // s.bsz)):
                                    s._train()
                                logger.info(f"CLTI: injected {len(prev_sol)} expert demos from L{lvl-1}")
                    except Exception as e:
                        logger.warning(f"CLTI failed: {e}")

            # ===== RESET =====
            if lf.state in [GameState.NOT_PLAYED, GameState.GAME_OVER]:
                s.pt=None;s.pai=None;s.pr=None;s.ph=None
                a=GameAction.RESET;a.reasoning="reset";return a

            # ===== BFS SOLUTION EXECUTION =====
            if s._bfs_solution and s._bfs_step < len(s._bfs_solution):
                act_id, data = s._bfs_solution[s._bfs_step]
                s._bfs_step += 1
```

--------------------------------

### _sample method

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/api-reference/myagent.md

Samples action from logits with temperature scaling and availability masking.

Returns: (action_idx_0_4, click_coords_or_None)

```python
def _sample(logits, avail=None, temp=1.0):
    # ... implementation details ...
    return (action_idx_0_4, click_coords_or_None)
```

--------------------------------

### Solution Sequence Type Alias Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of the structure for a solution sequence, which is a list of tuples containing an integer and an optional dictionary.

```python
solution: list[tuple[int, Optional[dict]]]
# Example:
# [(1, None), (6, {"x": 32, "y": 32}), (2, None)]
```

--------------------------------

### State Hash Type Alias Example

Source: https://github.com/johnlikescarrot/arc-prize-2026-arc-agi-3/blob/main/_autodocs/types.md

Example of the structure for a state hash, which can be a 16-character MD5 string or include hidden state information.

```python
hash: str
# "a3b2c1d4e5f6g7h8" (16-char MD5)
# or "a3b2c1d4e5f6g7h8|_field=value" with hidden state
```