AGENTS.md

Project Map (AGENTS.md)

This file is a navigation map for agents. Durable knowledge lives in docs/.

Start Here

• Docs index: docs/README.md
• Architecture: docs/ARCHITECTURE.md
• Operations: docs/RUNBOOK.md
• Test: uv run pytest tests/ -v

System-of-Record Documents

Category	Location	Type	Purpose
Guides	docs/guides/README.md	how-to	Practical procedures
Design docs	docs/design-docs/index.md	explanation	Feature design, ADRs
References	docs/references/README.md	reference	External docs

Project Structure

This project follows the OpenEnv openenv init convention. The project root is the environment package — no envs/ nesting.

sql-env/                       # project root = environment package
├── __init__.py                # exports SQLAction, SQLObservation, SQLEnvClient
├── models.py                  # Pydantic models (action w/ tokens, observation w/ messages, state)
├── client.py                  # SQLEnvClient(EnvClient) — WebSocket client w/ tensor serialization
├── conftest.py                # pytest config (ignores __init__.py collection)
├── openenv.yaml               # OpenEnv manifest
├── pyproject.toml             # deps + package config (setuptools, torch, transformers)
├── .python-version            # pins Python 3.12
├── data/
│   ├── databases/
│   │   └── models.py          # SQLAlchemy ORM models (student_assessment)
│   └── questions/
│       └── student_assessment.json  # 30+ Spider Q&A pairs with gold SQL
├── server/
│   ├── app.py                 # FastAPI app (tokenizer factory, MockTokenizer fallback)
│   ├── sql_environment.py     # SQLEnvironment(Environment) — core logic + Ollama
│   ├── test_sql_env.py        # MockTokenizer (char-code encoding for dev/test)
│   ├── reward.py              # Reward computation (stub — Phase 3)
│   ├── verifier.py            # Answer comparison (stub — Phase 3)
│   ├── Dockerfile
│   ├── requirements.txt
│   └── install_deps.sh        # Docker setup script
├── scripts/
│   ├── download_spider_data.py       # Download Spider questions from HuggingFace
│   └── generate_models_from_schema.py # Auto-generate SQLAlchemy models
├── tests/
│   └── test_smoke.py          # 21 tests (models, env, actions, client, schema)
├── docs/                      # Design docs, architecture
└── AGENTS.md

Guardrails

• Testing: Use the package manager (uv run pytest ...), never bare pytest.
• Git safety: No destructive commands (reset --hard, push --force) unless explicit.
• Secrets: Never commit .env or credentials.

Quick Commands

Task	Command
Install	uv sync
Lint	uv run ruff check --fix .
Format	uv run ruff format .
Test	uv run pytest tests/ -v
Run server	uv run uvicorn server.app:app --reload
Validate env	uv run openenv validate --verbose
Build Docker	uv run openenv build
Push to HF	uv run openenv push

Development Workflow

• Run via package manager (uv run ...), never bare commands.
• List existing files before creating new ones (avoid naming drift).
• Prefer vertical slices over horizontal refactors.
• No premature abstraction until multiple use-cases require it.