CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Purpose

OpenEnv RL environment for the Meta OpenEnv Hackathon. Implements an intelligent meeting scheduling environment where AI agents learn to schedule meetings across multiple attendees by proposing time slots, rescheduling lower-priority conflicts, and balancing participant preferences.

Development Commands

# Run baseline inference (heuristic, no LLM needed)
python inference.py

# Start server locally
uvicorn server.app:app --reload

# Validate environment for submission
openenv validate

# Generate/update lock file (required by validator)
uv lock

# Deploy to Hugging Face Spaces
openenv push

# Build Docker image (Dockerfile must be in root)
docker build -t scheduling_env:latest .

Architecture

OpenEnv Interface (client-server pattern)

The environment follows OpenEnv's standard API:

• POST /reset — starts a new episode, accepts {"task_id": "task1_easy"}. Returns observation.
• POST /step — takes an action, returns observation with reward/done.
• GET /state — returns internal environment state.
• GET /health — health check.

Core Flow

server/app.py creates a SchedulingHTTPEnvServer (subclasses HTTPEnvServer) that wraps a persistent SchedulingEnvironment instance. The server registers custom /reset, /step, /state routes.

server/scheduling_env_environment.py — Main environment class implementing Environment. Loads JSON scenarios from server/scenarios/, processes 4 action types: propose_slot, reschedule_meeting, finalize, reject. Episode ends on finalize, reject, or timeout (20 steps).

server/scheduling_logic.py — Pure utility functions: conflict detection, preference scoring, reward calculation, free-slot search. All datetime handling uses timezone-aware ISO 8601 strings. Calendar format: Dict[str, List[List]] where each entry is [start_iso, end_iso, priority_int, summary_str].

models.py — Pydantic models (SchedulingAction, SchedulingObservation, SchedulingState) imported by both server and client.

client.py — SchedulingEnv extends EnvClient for WebSocket-based interaction.

inference.py — Heuristic baseline (no LLM). Greedy free-slot search + lowest-priority rescheduling. Must emit [START]/[STEP]/[END] stdout format.

Reward Design

Reward is multi-component, deducted from 1.0 (see calculate_final_reward in scheduling_logic.py):

• Preference penalty: violations of preferred hours (+50), max meetings/day (+30), back-to-back (+20)
• Rescheduling deduction: exponential penalty per meeting moved
• Time deduction: 0.015 per step taken

Step-level rewards: +0.5 (conflict-free proposal), +0.2 (reschedulable conflicts), -0.3 (non-reschedulable conflicts), -0.1/-0.2 (invalid actions).

Tasks (3 difficulty levels)

JSON scenarios in server/scenarios/:

• task1_easy — 2 attendees, free slot exists, no rescheduling needed. Expected score: 0.8–1.0
• task2_medium — 3 attendees, requires 1 rescheduling. Expected score: 0.5–0.8
• task3_hard — 4 attendees, multiple overlapping conflicts, cascading rescheduling. Expected score: 0.2–0.6

Key Constraint: Meeting IDs

Format is {attendee}_{start_iso} (e.g., user1_2025-04-07T09:00:00+00:00). Used by _find_meeting() to look up calendar entries for rescheduling.

Hackathon Submission Requirements

• openenv validate must pass
• Dockerfile in root directory (not /server)
• inference.py in root, uses [START]/[STEP]/[END] stdout format
• 3+ tasks with graders scoring 0.0–1.0 with diverse scores
• Runtime < 20 minutes on vcpu=2, memory=8GB
• Deploy via openenv push to HF Spaces

Environment Variables (for LLM-based inference)

Defined in .env (never commit):

API_BASE_URL    # HF Router endpoint (default: https://router.huggingface.co/v1)
MODEL_NAME      # Model identifier (default: Qwen/Qwen2.5-72B-Instruct)
HF_TOKEN        # Hugging Face API key