# OpenSpec Instructions These instructions are for AI assistants working in this project. Always open `@/openspec/AGENTS.md` when the request: - Mentions planning or proposals (words like proposal, spec, change, plan) - Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work - Sounds ambiguous and you need the authoritative spec before coding Use `@/openspec/AGENTS.md` to learn: - How to create and apply change proposals - Spec format and conventions - Project structure and guidelines Keep this managed block so 'openspec update' can refresh the instructions. # Development Commands ## Build/Test/Lint - **Install deps**: `uv sync` (in apps/api/) - **Run tests**: `uv run pytest` (all) or `uv run pytest tests/test_main.py::test_healthz` (single test) - **Run app**: `uv run uvicorn news_api.main:app --reload` - **Build**: `uv build` (in apps/api/) ## Code Quality - Run tests before commits: `uv run pytest` - No linting/formatting tools configured yet # Code Style Guidelines ## Python Conventions - **Imports**: stdlib → third-party → local (blank lines between groups) - **Types**: Use type hints everywhere, Pydantic for schemas - **Naming**: snake_case functions/variables, PascalCase classes, UPPER_CASE constants - **Docstrings**: Required for all public functions/classes - **Error handling**: pytest treats warnings as errors (`filterwarnings = ["error:::news_api.*"]`) ## FastAPI Patterns - Use `response_model` for all endpoints - Router prefix `/v1`, tags for grouping - Async endpoints with httpx.AsyncClient for testing ## Architecture - Service layer separation (routers → services → schemas) - Stub implementations until real DB/workers integrated - Pydantic models for all request/response data # Project Context - FastAPI news aggregator API with hybrid search - Currently stubbed responses, PostgreSQL/pgvector planned - Tech: FastAPI, Pydantic, httpx, pytest, uv, hatchling