README.md

---
title: Adjudicator Environment Server
emoji: ⚖️
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv
---

# Adjudicator Environment

A debate training environment where an agent is given a topic and side, and must construct a compelling argument. Arguments are scored by an LLM judge on relevance, evidence, logic, and persuasiveness.

## Quick Start

The simplest way to use the Adjudicator environment is through the `AdjudicatorEnv` class:

```python
from client import AdjudicatorEnv
from models import DebateAction

try:
    # Create environment from Docker image
    env = AdjudicatorEnv.from_docker_image("adjudicator-env:latest")

    # Reset — receive a debate topic and side
    result = env.reset()
    obs = result.observation
    print(f"Topic: {obs.topic}")
    print(f"Side: {obs.side}")
    print(f"Difficulty: {obs.difficulty}")

    # Submit an argument
    action = DebateAction(
        argument="A 2018 MIT study found false news spreads 6x faster than true news on Twitter, directly damaging public health decisions and political discourse at unprecedented scale."
    )
    result = env.step(action)
    print(f"Reward: {result.observation.reward}")
    print(f"Feedback: {result.observation.feedback}")
    print(f"Scores: {result.observation.scores}")

finally:
    env.close()
```

## Building the Docker Image

```bash
# Generate debate data first
python debate_data.py

# Build from project root
docker build -t adjudicator-env:latest -f server/Dockerfile .
```

## Deploying to Hugging Face Spaces

```bash
# From the environment directory
openenv push

# With options
openenv push --namespace my-org --private
```

The `openenv push` command will:
1. Validate the environment structure
2. Prepare a Hugging Face Docker space build
3. Upload to Hugging Face

### Options

- `--directory`, `-d`: Directory containing the environment (defaults to current)
- `--repo-id`, `-r`: Repository ID in format `username/repo-name`
- `--base-image`, `-b`: Override Dockerfile base image
- `--private`: Deploy as private (default: public)

### Examples

```bash
openenv push
openenv push --repo-id my-org/adjudicator
openenv push --private
openenv push --repo-id my-org/adjudicator --private
```

After deployment, your space will be available at:
`https://huggingface.co/spaces/<repo-id>`

The deployed space includes:
- **Web Interface** at `/web` — Interactive UI for exploring the environment
- **API Documentation** at `/docs` — Full OpenAPI/Swagger interface
- **Health Check** at `/health` — Container health monitoring
- **WebSocket** at `/ws` — Persistent session endpoint for low-latency interactions

## Environment Details

### Action
**DebateAction**: The argument submitted by the agent
- `argument` (str) — The debate argument to be judged
- `metadata` (dict) — Optional metadata

### Observation
**DebateObservation**: Feedback from the judge after each step
- `done` (bool) — Whether the episode has ended
- `reward` (float) — Normalized score 0.0–1.0
- `topic` (str) — The debate topic
- `side` (str) — `"FOR"` or `"AGAINST"`
- `difficulty` (int) — Topic difficulty level (1–3)
- `attempts_remaining` (int) — Remaining attempts in the episode
- `feedback` (str) — One-sentence judge feedback
- `scores` (dict) — Breakdown: `relevance`, `evidence`, `logic`, `persuasiveness`, `total`
- `metadata` (dict) — Additional info

### Reward
Arguments are scored on four criteria (0–10 total), normalized to 0.0–1.0:

| Criterion | Max Points | Description |
|---|---|---|
| Relevance | 3 | Does it address the topic? |
| Evidence | 3 | Does it cite facts, studies, or examples? |
| Logic | 2 | Is the reasoning sound? |
| Persuasiveness | 2 | Would it convince a neutral observer? |

## Advanced Usage

### Connecting to an Existing Server

```python
from client import AdjudicatorEnv

env = AdjudicatorEnv(base_url="http://localhost:8000")
result = env.reset()
result = env.step(DebateAction(argument="Your argument here."))
```

### Using the Context Manager

```python
from client import AdjudicatorEnv
from models import DebateAction

with AdjudicatorEnv(base_url="http://localhost:8000") as env:
    result = env.reset()
    print(f"Topic: {result.observation.topic}")
    result = env.step(DebateAction(argument="Your argument here."))
    print(f"Reward: {result.observation.reward}")
```

### Running Locally

```bash
uvicorn server.app:app --reload
```

## Project Structure

```
Adjudicator/
├── __init__.py                   # Module exports
├── README.md                     # This file
├── openenv.yaml                  # OpenEnv manifest
├── pyproject.toml                # Project metadata and dependencies
├── uv.lock                       # Locked dependencies (generated)
├── client.py                     # AdjudicatorEnv client
├── models.py                     # DebateAction, DebateObservation, DebateState
├── judge.py                      # LLM judge (Claude Haiku)
├── debate_data.py                # Script to generate debate_data.json
├── debate_data.json              # Debate topics dataset
├── game_loop.py                  # Manual test loop
└── server/
    ├── __init__.py               # Server module exports
    ├── debate_environment.py     # Core environment logic
    ├── app.py                    # FastAPI application
    └── Dockerfile                # Container image definition
```