README.md

metadata

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:

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

# 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

# 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

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

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

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

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