334aa698fa
- Add FastAPI application with complete router structure - Implement search, articles, ask, feedback, and health endpoints - Add comprehensive Pydantic schemas for API requests/responses - Include stub service implementations for all business logic - Add full test suite with pytest-asyncio integration - Configure conventional commits enforcement via git hooks - Add project documentation and contribution guidelines - Support both OpenAI and Gemini LLM integration options
54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
<!-- OPENSPEC:START -->
|
|
# 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.
|
|
|
|
<!-- OPENSPEC:END -->
|
|
|
|
# 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 |