Cursor rule

1---
2globs:
3  - "packages/hermes-api/**/*.py"
4---
5 
6# Hermes API - Python/FastAPI Rules
7 
8## Python Version
9- Target Python 3.11+
10- Use modern Python features (match/case, type hints, etc.)
11 
12## Code Style
13 
14### Formatting (Black)
15- Line length: 88 characters (configured in `pyproject.toml`)
16- Let Black handle formatting automatically
17- Run: `black .` before committing
18 
19### Import Ordering (isort)
20- Profile: black (configured in `pyproject.toml`)
21- Order: standard library, third-party, local imports
22- Run: `isort .` before committing
23 
24### Type Hints (mypy)
25- All functions must have type hints for parameters and return values
26- Use `typing` module for complex types
27- Comply with mypy strict mode settings in `pyproject.toml`
28- Run: `mypy app` to check types
29 
30## FastAPI Patterns
31 
32### Async/Await
33- Use `async def` for all endpoint handlers
34- Use `await` for database operations and external API calls
35- Import `AsyncSession` for database operations
36 
37### Dependencies
38- Use FastAPI's dependency injection system
39- Define dependencies in `app/api/dependencies.py`
40- Common dependencies:
41  - `get_database_session()` - Database session
42  - `get_current_user_from_token()` - Authenticated user
43  - `get_current_user_optional()` - Optional authentication
44 
45### Error Handling
46- Use `HTTPException` for API errors
47- Include appropriate status codes from `fastapi.status`
48- Provide clear error messages in `detail` field
49- Log errors using structured logging
50 
51### Request/Response Models
52- Define Pydantic models in `app/models/pydantic/`
53- Use type validation and serialization
54- Include field descriptions for API documentation
55- Separate request models from response models
56 
57## Project Structure
58 
59```
60app/
61├── api/               # API routes and endpoints
62│   ├── dependencies.py
63│   └── v1/
64│       ├── endpoints/  # Individual endpoint files
65│       └── router.py   # Route registration
66├── core/              # Core configuration
67│   ├── config.py      # Settings and configuration
68│   ├── logging.py     # Logging setup
69│   └── security.py    # Auth/security utilities
70├── db/                # Database layer
71│   ├── base.py        # Base model
72│   ├── models.py      # SQLAlchemy models
73│   ├── repositories.py # Repository pattern
74│   └── session.py     # DB session management
75├── models/            # Data models
76│   └── pydantic/      # Pydantic models
77├── services/          # Business logic
78├── tasks/             # Celery tasks
79└── utils/             # Utility functions
80```
81 
82## Logging
83 
84Use structured logging via `structlog`:
85```python
86from app.core.logging import get_logger
87 
88logger = get_logger(__name__)
89logger.info("Operation completed", user_id=user_id, action="download")
90logger.error("Operation failed", error=str(e), error_type=type(e).__name__)
91```
92 
93## Configuration
94 
95- Use `pydantic-settings` for configuration management
96- Access settings via `app.core.config.settings`
97- Environment variables override default values
98- Never hardcode configuration values
99 
100## Testing
101 
102- Write tests in `tests/` directory
103- Use pytest with async support (`pytest-asyncio`)
104- Follow naming: `test_*.py` for files, `test_*` for functions
105- Use markers: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.slow`
106- Run: `pytest` or `python -m pytest`
107 
108## Dependencies
109 
110Manage dependencies with UV (following `pyproject.toml`):
111- Production dependencies in `[project.dependencies]`
112- Development dependencies in `[dependency-groups.dev]`
113- Pin versions for stability
114- Run: `uv pip compile` to update `uv.lock`
115