# leonguertler/textarena architecture

> Architecture diagram of the GitHub repository leonguertler/textarena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leonguertler/textarena
- Repository: https://github.com/leonguertler/textarena

## Overview

##### Project type and purpose
- TextArena is a Python SDK/framework (packaged via `pyproject.toml`/`setup.py`) that provides an OpenAI-Gym–style interface for training, evaluating, and benchmarking models (LLMs or RL agents) in text-based games.
- It is not a web frontend/backend service, but a local library with optional online competition integration.

##### File structure
- Top-level:
- `textarena/` – the core Python package
– `api.py` – factory methods (`make`, `make_online`, `register_online_model`)
– `core.py` – base `Env` definitions, registry logic
– `registration.py` – dynamic environment registration
– `envs/…` – individual game environments (each with its own `env.py` and optional `renderer.py`)
– `agents/…` – built-in agent implementations (e.g., `OpenRouterAgent`)
– `wrappers/…` – Gym-style wrappers for observations, actions, rendering
– `utils/…` – shared utilities (e.g., data loaders, jury logic)
- Examples: `offline_play_example.py`, `online_play_example.py`, `samples/…`
- Packaging/config: `pyproject.toml`, `requirements.txt`, `.github/`, `setup.py`, `MANIFEST.in`

##### README for architectural insights
- Core features: offline play loop, online play loop via remote HTTP API to textarena.ai
- Dependencies: external LLM APIs (OpenRouter, Claude, etc.), JSONL data for eval envs

##### Main components & interactions (
– textarena.api (user’s entrypoint: `make()`, `make_online()`)
– textarena.core (Env base classes, step/reset semantics)
– textarena.envs.<GameID>
- env.py (game logic, state transitions)
- renderer.py (text‐based view)
- static data (e.g., prompts, word lists, JSONL data)
– ObservationWrappers (e.g., `LLMObservationWrapper`)
– ActionWrappers (e.g., formatting wrappers)
– RenderWrappers (e.g., simple console rendering)
– textarena.agents
- LLM agents (e.g., `OpenRouterAgent` making HTTP calls to external LLM APIs)
- Basic/random agents
– textarena.ai remote service (HTTP endpoints for model registration, online environments, leaderboard)
– On-disk JSONL/CSV assets under `textarena/envs/.../data` and `textarena/utils/data`

Interaction flow (offline):
User Script → textarena.api.make() → EnvFactory → Env Instance
Env.reset()
loop:
Env.get_observation() → ObservationWrapper → Agent(observation) → External LLM API → action
Env.step(action) → reward, done
Env.close()

Interaction flow (online):
User Script → textarena.api.make_online() → HTTP POST to textarena.ai → remote Env Instance
loop:
HTTP GET observation → Agent → HTTP POST action → remote Env.step → HTTP GET reward/done
HTTP POST close → remote logging/leaderboard

##### Architectural patterns and design principles
- Plugin/registry pattern: dynamic discovery of new envs via `registration.py`
- Decorator/wrapper pattern: modular, chainable wrappers for observations, actions, rendering
- Separation of concerns:
- Env logic (game rules)
- Wrappers (format conversion)
- Agents (decision making)
- API vs Core

##### Relevant technologies, frameworks, libraries
- Python 3.x, standard library
- Requests or httpx (for LLM calls and online HTTP API)
- OpenRouter/Anthropic/OpenAI client libraries
- JSONL for dataset storage
- PyPI packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserScript["User Script"]:::user

    subgraph "SDK/API Layer"
        API["textarena.api\n(make, make_online, register_online_model)"]:::sdk
    end
    click API "https://github.com/leonguertler/textarena/blob/main/textarena/api.py"

    subgraph "Core Layer"
        Core["textarena.core\n(Env base, step, reset)"]:::core
        Reg["textarena.registration\n(dynamic env registry)"]:::core
    end
    click Core "https://github.com/leonguertler/textarena/blob/main/textarena/core.py"
    click Reg "https://github.com/leonguertler/textarena/blob/main/textarena/registration.py"

    subgraph "Environment Layer"
        EnvReg["textarena/envs/registration.py"]:::env
        ChessEnv["Chess/env.py"]:::env
        ChessRend["Chess/renderer.py"]:::env
        StaticData["Static Data\n(prompts, JSONL)"]:::data
    end
    click EnvReg "https://github.com/leonguertler/textarena/blob/main/textarena/envs/registration.py"
    click ChessEnv "https://github.com/leonguertler/textarena/blob/main/textarena/envs/Chess/env.py"
    click ChessRend "https://github.com/leonguertler/textarena/blob/main/textarena/envs/Chess/renderer.py"

    subgraph "Wrappers Layer"
        OW1["LLMObservationWrapper"]:::wrap
        OW2["ClassicalReasoningEvalObservationWrapper"]:::wrap
        AW1["ActionFormattingWrapper"]:::wrap
        AW2["ClipActionWrapper"]:::wrap
        RW["SimpleRenderWrapper"]:::wrap
    end
    click OW1 "https://github.com/leonguertler/textarena/blob/main/textarena/wrappers/ObservationWrappers/llm_observation_wrapper.py"
    click OW2 "https://github.com/leonguertler/textarena/blob/main/textarena/wrappers/ObservationWrappers/classical_reasoning_eval_observation_wrapper.py"
    click AW1 "https://github.com/leonguertler/textarena/blob/main/textarena/wrappers/ActionWrappers/action_formatting_wrapper.py"
    click AW2 "https://github.com/leonguertler/textarena/blob/main/textarena/wrappers/ActionWrappers/clip_action_wrapper.py"
    click RW "https://github.com/leonguertler/textarena/blob/main/textarena/wrappers/RenderWrappers/SimpleRenderWrapper/render.py"

    subgraph "Agent Layer"
        AgentsCore["basic_agents"]:::agent
        AgentsWrap["agents.wrappers"]:::agent
        LLMExt["External LLM API"]:::external
    end
    click AgentsCore "https://github.com/leonguertler/textarena/blob/main/textarena/agents/basic_agents.py"
    click AgentsWrap "https://github.com/leonguertler/textarena/blob/main/textarena/agents/wrappers.py"

    subgraph "Data Store"
        Data1["Env JSONL/CSV"]:::data
        Data2["Utils Data\n(en.aff, en_GB.dic, en_US.dic)"]:::data
    end
    click Data1 "https://github.com/leonguertler/textarena/tree/main/textarena/envs/ClassicalReasoningEvals/data/"
    click Data2 "https://github.com/leonguertler/textarena/blob/main/textarena/utils/data/en.aff"

    subgraph "Online Service"
        TAService["textarena.ai HTTP API"]:::online
    end

    UserScript -->|"calls make()/make_online()"| API
    API --> Core
    API --> Reg
    Core -->|"EnvFactory"| EnvFactory["EnvFactory"]:::core
    EnvFactory -->|"create Env instance"| EnvInst["Env Instance"]:::core
    EnvInst -->|"reset()"| EnvInst
    EnvInst -->|"get_observation()"| OW1
    OW1 -->|"formatted obs"| AgentsCore
    AgentsCore -->|"action"| EnvInst
    EnvInst -->|"step(action)"| EnvInst
    EnvInst -->|"close()"| EnvInst

    Reg --> EnvReg
    EnvReg --> ChessEnv
    EnvReg --> ChessRend
    StaticData -.-> ChessEnv

    ChessEnv --> OW1
    ChessEnv --> AW1
    ChessEnv --> RW
    ChessEnv --> Data1

    OW1 --> AgentsCore
    AW1 --> AgentsCore
    RW --> AgentsCore
    AgentsCore --> LLMExt

    API -->|"HTTP POST /make_online"| TAService
    TAService -->|"GET /observation"| AgentsCore
    AgentsCore -->|"HTTP POST /action"| TAService
    TAService -->|"HTTP GET /reward_done"| AgentsCore
    TAService -->|"HTTP POST /close"| TAService

    classDef user fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef sdk fill:#d0e6ff,stroke:#0366d6,stroke-width:2px
    classDef core fill:#b3d4fc,stroke:#025aa5,stroke-width:2px
    classDef env fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef wrap fill:#ffe5b4,stroke:#e65c00,stroke-width:2px
    classDef agent fill:#fff3b0,stroke:#b58900,stroke-width:2px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,stroke-dasharray: 5 5
    classDef online fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef data fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
```
