Crate arc_agi_rs 

🕹️ ARC AGI RS

arc-agi-rs is a multi-language toolkit for interacting with the ARC-AGI-3 REST API. The core is written entirely in Rust and compiled to native extensions, so Python and Node.js callers enjoy the same performance and correctness guarantees as the Rust library 🗿.

🦀 Rust	🐍 Python	🟩 Node.js
Rust Guide	Python Guide	Node.js Guide
cargo add arc-agi-rs	pip install arc-agi-rs	npm install arc-agi-rs

🤔 What does this crate provide?

The library exposes the full ARC-AGI-3 client API:

• Environment discovery - list and inspect all available game environments.
• Scorecard management - open, retrieve, and close scored sessions.
• Game interaction - reset a game to its initial state and step through it action-by-action.
• Anonymous access - obtain an anonymous API key when no personal key is available.

A fluent builder API (mirroring the Python Arcade class) covers all client configuration: API key, base URL, cookie storage, and HTTP proxy.

🦀 Rust

The Rust crate is available on crates.io. It provides a high-performance, async-first interface for building ARC-AGI agents.

For a complete API reference, installation guide, and examples, visit the Rust Usage Guide.

🐍 Python

The Python bindings are published to PyPI as arc-agi-rs. They provide a native extension that operates a robust tokio runtime under the hood, ensuring top-tier performance with a simple synchronous API.

For installation instructions, configuration options, and full method signatures, see the Python usage guide.

🟩 Node.js

The Node.js bindings are published to npm as arc-agi-rs. Built with napi-rs, they offer extremely fast, native synchronous bindings that save you from deep async closures for one-off game calls.

For installation instructions, type definitions, and examples, read the Node.js usage guide.

⚙️ Configuration

All credentials can be supplied via environment variables as a fallback:

Variable	Description	Default
ARC_API_KEY	API key for authentication	(empty)
ARC_BASE_URL	Base URL of the ARC-AGI-3 server	https://three.arcprize.org

📄 License

Licensed under the MIT License.

⭐ Star us

If you find this library useful, please leave a star on GitHub! It helps others discover the project and keeps the momentum going ☕.

arc-agi-rs Rust Documentation 🦀

arc-agi-rs is a pure-Rust async client for the ARC-AGI-3 REST API. It is designed for seamless usage within the tokio ecosystem and exposes a fluent builder API mirroring the Python Arcade class.

📦 Installation

Add this to your Cargo.toml:

[dependencies]
arc-agi-rs = "0.1.0"
tokio = { version = "1", features = ["full"] }

🚀 Quick Start

use arc_agi_rs::client::Client;
use arc_agi_rs::params::{MakeParams, ScorecardParams};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::builder()
        .api_key("my-api-key")
        .cookie_store(true)
        .build()?;

    // Open a scored session
    let card_id = client
        .open_scorecard(Some(ScorecardParams::new().tags(vec!["agent".to_string()])))
        .await?;

    // Reset a game environment
    let frame = client
        .reset(MakeParams::new("ls20", &card_id).seed(42))
        .await?;

    println!("GUID: {:?}", frame.guid);
    println!("State: {}", frame.state);
    println!("Levels to complete: {}", frame.win_levels);

    // Close and retrieve the final score
    let result = client.close_scorecard(&card_id).await?;
    println!("Final score: {:.2}", result.score);

    Ok(())
}

🔧 Client Configuration

Use Client::builder() to configure the client before construction. All options fall back to environment variables when not set explicitly.

use arc_agi_rs::client::Client;

let client = Client::builder()
    .api_key("my-api-key")           // or set ARC_API_KEY env var
    .base_url("https://three.arcprize.org") // or set ARC_BASE_URL env var
    .cookie_store(true)              // required for session-based game flows
    .proxy("socks5://127.0.0.1:9050") // optional
    .build()
    .expect("failed to build client");

Environment Variable	Description	Default
ARC_API_KEY	API key for authenticated requests	(empty)
ARC_BASE_URL	Base URL of the ARC-AGI-3 server	https://three.arcprize.org

🎮 Game Flow

A typical agent run follows this sequence:

1. open_scorecard: create a scored session
2. list_environments: discover available game IDs
3. reset: initialise a game and receive the first frame
4. step (loop): send actions until the game ends
5. close_scorecard: finalise and retrieve scores

use arc_agi_rs::client::Client;
use arc_agi_rs::params::{MakeParams, StepParams};
use arc_agi_rs::serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::builder().cookie_store(true).build()?;

    let card_id = client.open_scorecard(None).await?;
    let envs = client.list_environments().await?;
    let game_id = &envs.first().expect("no environments available").game_id;

    let frame = client.reset(MakeParams::new(game_id, &card_id)).await?;
    let guid = frame.guid.expect("server always returns a guid on reset");

    // Step through an action
    let next = client
        .step(
            StepParams::new(game_id, &card_id, &guid, 1)
                .data(json!({"x": 0, "y": 0})),
        )
        .await?;

    println!("State after step: {}", next.state);

    let scorecard = client.close_scorecard(&card_id).await?;
    println!("Final score: {:.2}", scorecard.score);

    Ok(())
}

📖 API Reference

Client

The main HTTP client. Create with Client::new() (reads from env vars) or Client::builder().

Method	Description
get_anonymous_key()	Retrieve a temporary anonymous API key
list_environments()	List all game environments on the server
get_environment(id)	Get metadata for a single environment
open_scorecard(params)	Create a new scorecard and return its card_id
get_scorecard(card_id)	Retrieve an existing scorecard
close_scorecard(card_id)	Finalise a scorecard and return scores
reset(params)	Reset a game to its initial state
step(params)	Send one action and receive the next frame

Request Builders

Builder	Purpose
ClientConfig	API key, base URL, and operation mode
ScorecardParams	Tags, source URL, and competition mode for open_scorecard
MakeParams	Game ID, scorecard ID, seed, and GUID for reset
StepParams	Action ID, data payload, and reasoning for step

Domain Types

Type	Description
EnvironmentInfo	Metadata for a single game environment
FrameData	Full response from reset or step
GameState	Lifecycle state (NotPlayed, NotFinished, Win, GameOver)
OperationMode	Environment discovery strategy (Normal, Online, Offline, Competition)
EnvironmentScorecard	Final or intermediate scorecard data

Re-exports

pub use error::ArcAgiError;

pub use serde_json;

Modules

client

HTTP Client

error

Error Types

models

Data Models

params

Request Parameters

pythonpython

Python Bindings

response

API Response Types

scorecard

Scorecard Tracking

Type Aliases

Result