| # 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 --> |
|
|
