albert-einstein-09/codedark

1# CodeDark2 3**OpenEnv-compatible multi-turn data analytics environment for RL agent training.**4 5Train AI agents to be data scientists, not just code executors. CodeDark features real business analytics tasks with pandas/numpy, multi-metric reward shaping, and skill-based curriculum.6 7## Quick Start8 9### Server10 11```bash12# Install13pip install -e .14 15# Run server16python -m codedark.server.app17# Server runs at http://localhost:800018```19 20### Client21 22```python23from codedark import CodeDarkEnv24 25env = CodeDarkEnv("http://localhost:8000")26 27# Reset for new episode28obs = env.reset()29print(f"Task: {obs['question']}")30 31# Execute Python code32obs = env.run_python("result = df.shape")33print(f"Shape: {obs['stdout']}")34 35# Explore the data36obs = env.run_python("result = df.columns.tolist()")37print(f"Columns: {obs['stdout']}")38 39# Calculate and submit answer40obs = env.run_python("result = df['y'].mean() * 100")41obs = env.submit_answer(11.26)42print(f"Reward: {obs['reward']}")43```44 45### Docker46 47```bash48# Build49docker build -t codedark:latest -f server/Dockerfile .50 51# Run52docker run -p 8000:8000 codedark:latest53```54 55## Tools56 57Agents have access to 5 tools:58 59| Tool            | Description                                                     |60| --------------- | --------------------------------------------------------------- |61| `run_python`    | Execute Python/pandas code. Store output in `result` variable.  |62| `read_notes`    | Read all saved notes from previous turns.                       |63| `save_note`     | Save observations for later recall. Notes persist across turns. |64| `clarify`       | Ask clarifying questions about the task (max 2 per episode).    |65| `submit_answer` | Submit final answer. Ends episode.                              |66 67## Reward Structure68 69Total reward is computed from three components (max 1.0):70 71| Component   | Weight | Description                                     |72| ----------- | ------ | ----------------------------------------------- |73| Correctness | 80%    | Binary correct/incorrect with numeric tolerance |74| Efficiency  | 10%    | Fewer turns = better score                      |75| Token Cost  | 10%    | Lower token usage = better score                |76 77## Datasets78 79### Bank Marketing80 81- **Records**: 750,000 customers82- **Target**: Term deposit subscription (y = 0/1)83- **Features**: age, job, marital, education, balance, housing, loan, contact, day, month, duration, campaign, pdays, previous, poutcome84 85### Road Safety86 87- **Records**: 500,000 road segments88- **Target**: Accident risk (continuous)89- **Features**: road_type, num_lanes, curvature, speed_limit, lighting, weather, road_signs_present, time_of_day, num_reported_accidents90 91## Task Difficulty92 93| Level | Complexity      | Example                                      |94| ----- | --------------- | -------------------------------------------- |95| L4    | Quartile/binned | "Subscription rate in Q1 balance?"           |96| L5    | Multi-condition | "Rate for month='may' AND job='management'?" |97| L6    | Nested extrema  | "In lowest subscription month, avg day?"     |98 99## API Endpoints100 101| Endpoint    | Method | Description           |102| ----------- | ------ | --------------------- |103| `/health`   | GET    | Health check          |104| `/reset`    | POST   | Reset for new episode |105| `/step`     | POST   | Execute action        |106| `/state`    | GET    | Current state         |107| `/metadata` | GET    | Environment metadata  |108| `/schema`   | GET    | Type schemas          |109 110## Benchmark Results111 112Pre-benchmarked on 11+ models with 1,844 completions:113 114| Model            | Accuracy | Cost/Task |115| ---------------- | -------- | --------- |116| Claude Opus 4.5  | 77.3%    | $0.89     |117| Qwen3 Max        | 46.7%    | $0.12     |118| Mistral Large    | 45.3%    | $0.18     |119| Llama 4 Maverick | 38.7%    | $0.08     |120 121## Environment Variables122 123| Variable              | Default                           | Description               |124| --------------------- | --------------------------------- | ------------------------- |125| `CODEDARK_DATA_DIR`   | `data/`                           | Path to CSV files         |126| `CODEDARK_TASKS_PATH` | `data/tasks/final_25_tasks.jsonl` | Path to tasks file        |127| `CODEDARK_MAX_TURNS`  | `10`                              | Maximum turns per episode |128| `HOST`                | `0.0.0.0`                         | Server host               |129| `PORT`                | `8000`                            | Server port               |130 131## Project Structure132 133```134codedark/135├── __init__.py          # Package exports136├── models.py            # Action, Observation, State dataclasses137├── client.py            # HTTP client138├── openenv.yaml         # OpenEnv manifest139├── pyproject.toml       # Package config140├── server/141│   ├── app.py           # FastAPI application142│   ├── environment.py   # Core environment logic143│   ├── tools.py         # Tool implementations144│   ├── scoring.py       # Reward computation145│   ├── Dockerfile       # Container spec146│   └── requirements.txt # Dependencies147├── data/148│   ├── bank.csv         # Bank marketing dataset149│   ├── road.csv         # Road safety dataset150│   └── tasks/151│       └── final_25_tasks.jsonl152└── tests/153```154 155## OpenEnv Compatibility156 157CodeDark follows the [OpenEnv specification](https://huggingface.co/openenv):158 159- Gymnasium-style `reset()` / `step()` API160- Pydantic models for Action, Observation, State161- FastAPI server with standard endpoints162- Docker containerization for isolated execution163- HTTP + WebSocket transport164 165## License166 167MIT168 169## Author170 171Vijay Athithya172 173- GitHub: [vj-09](https://github.com/vj-09)174- LinkedIn: [vijay-athithya](https://www.linkedin.com/in/vijay-athithya/)175