# Project Map (AGENTS.md)

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

## Start Here

- Docs index: [docs/README.md](docs/README.md)
- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Operations: [docs/RUNBOOK.md](docs/RUNBOOK.md)
- Test: `uv run pytest tests/ -v`

## System-of-Record Documents

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

## Project Structure

This project follows the [OpenEnv](https://github.com/meta-pytorch/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.

<!-- GUIDELINES-BEGIN -->

<!-- Managed by: opencode-ctx guidelines apply --packs python,testing,delivery-safety -->
<!-- Run the command above to populate this section -->

<!-- GUIDELINES-END -->