File size: 3,895 Bytes
5dd1bb4 9e64e71 5dd1bb4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | # 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 -->
|