180 lines
4.7 KiB
Markdown
180 lines
4.7 KiB
Markdown
# AGENTS.md - Coding Guidelines for AI Agents
|
|
|
|
## Build / Test / Lint Commands
|
|
|
|
### Python Backend
|
|
```bash
|
|
# Install packages (editable mode)
|
|
pip install -e packages/shared
|
|
pip install -e packages/training
|
|
pip install -e packages/backend
|
|
|
|
# Run all tests
|
|
DB_PASSWORD=xxx pytest tests/ -q
|
|
|
|
# Run single test file
|
|
DB_PASSWORD=xxx pytest tests/path/to/test_file.py -v
|
|
|
|
# Run with coverage
|
|
DB_PASSWORD=xxx pytest tests/ --cov=packages --cov-report=term-missing
|
|
|
|
# Format code
|
|
black packages/ tests/
|
|
ruff check packages/ tests/
|
|
|
|
# Type checking
|
|
mypy packages/
|
|
```
|
|
|
|
### Frontend
|
|
```bash
|
|
cd frontend
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Development server
|
|
npm run dev
|
|
|
|
# Build
|
|
npm run build
|
|
|
|
# Run tests
|
|
npm run test
|
|
|
|
# Run single test
|
|
npx vitest run src/path/to/file.test.ts
|
|
|
|
# Watch mode
|
|
npm run test:watch
|
|
|
|
# Coverage
|
|
npm run test:coverage
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Python
|
|
|
|
**Imports:**
|
|
- Use absolute imports within packages: `from shared.pdf.extractor import PDFDocument`
|
|
- Group imports: stdlib → third-party → local (separated by blank lines)
|
|
- Use `from __future__ import annotations` for forward references when needed
|
|
|
|
**Type Hints:**
|
|
- All functions must have type hints (enforced by mypy)
|
|
- Use `| None` instead of `Optional[...]` (Python 3.10+)
|
|
- Use `list[str]` instead of `List[str]` (Python 3.10+)
|
|
|
|
**Naming:**
|
|
- Classes: `PascalCase` (e.g., `PDFDocument`, `InferencePipeline`)
|
|
- Functions/variables: `snake_case` (e.g., `extract_text`, `get_db_connection`)
|
|
- Constants: `UPPER_SNAKE_CASE` (e.g., `DEFAULT_DPI`, `DATABASE`)
|
|
- Private: `_leading_underscore` for internal use
|
|
|
|
**Error Handling:**
|
|
- Use custom exceptions from `shared.exceptions`
|
|
- Base exception: `InvoiceExtractionError`
|
|
- Specific exceptions: `PDFProcessingError`, `OCRError`, `DatabaseError`, etc.
|
|
- Always include context in exceptions via `details` dict
|
|
|
|
**Docstrings:**
|
|
- Use Google-style docstrings
|
|
- All public functions/classes must have docstrings
|
|
- Include Args/Returns sections for complex functions
|
|
|
|
**Code Organization:**
|
|
- Maximum line length: 100 characters (black config)
|
|
- Target Python: 3.10+
|
|
- Keep files under 800 lines, ideally 200-400 lines
|
|
|
|
### TypeScript / React Frontend
|
|
|
|
**Imports:**
|
|
- Use path alias `@/` for project imports: `import { Button } from '@/components/Button'`
|
|
- Group: React → third-party → local (@/) → relative
|
|
|
|
**Naming:**
|
|
- Components: `PascalCase` (e.g., `Dashboard.tsx`, `InferenceDemo.tsx`)
|
|
- Hooks: `camelCase` with `use` prefix (e.g., `useDocuments.ts`)
|
|
- Types/Interfaces: `PascalCase` (e.g., `DocumentListResponse`)
|
|
- API endpoints: `camelCase` (e.g., `documentsApi`)
|
|
|
|
**TypeScript:**
|
|
- Strict mode enabled
|
|
- Use explicit return types on exported functions
|
|
- Prefer `type` over `interface` for simple shapes
|
|
- Use enums for fixed sets of values
|
|
|
|
**React Patterns:**
|
|
- Functional components with hooks
|
|
- Use React Query for server state
|
|
- Use Zustand for client state (if needed)
|
|
- Props interfaces named `{ComponentName}Props`
|
|
|
|
**Styling:**
|
|
- Use Tailwind CSS exclusively
|
|
- Custom colors: `warm-*` theme (e.g., `bg-warm-text-secondary`)
|
|
- Component variants defined as objects (see Button.tsx pattern)
|
|
|
|
**Testing:**
|
|
- Use Vitest + React Testing Library
|
|
- Test files: `{name}.test.ts` or `{name}.test.tsx`
|
|
- Co-locate tests with source files when possible
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
packages/
|
|
shared/ # Shared utilities (PDF, OCR, storage, config)
|
|
training/ # Training service (GPU, CLI commands)
|
|
backend/ # Web API + inference (FastAPI)
|
|
frontend/ # React + TypeScript + Vite
|
|
tests/ # Test suite
|
|
migrations/ # Database SQL migrations
|
|
```
|
|
|
|
## Key Configuration
|
|
|
|
- **DPI:** 150 (must match between training and inference)
|
|
- **Database:** PostgreSQL (configured via env vars)
|
|
- **Storage:** Abstracted (Local/Azure/S3 via storage.yaml)
|
|
- **Python:** 3.10+ (3.11 recommended, 3.10 for RTX 50 series)
|
|
|
|
## Environment Variables
|
|
|
|
Required: `DB_PASSWORD`
|
|
Optional: `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `STORAGE_BASE_PATH`
|
|
|
|
## Common Patterns
|
|
|
|
### Python: Adding a New API Endpoint
|
|
1. Add route in `backend/web/api/v1/`
|
|
2. Define Pydantic schema in `backend/web/schemas/`
|
|
3. Implement service logic in `backend/web/services/`
|
|
4. Add tests in `tests/web/`
|
|
|
|
### Frontend: Adding a New Component
|
|
1. Create component in `frontend/src/components/`
|
|
2. Export from `frontend/src/components/index.ts` if shared
|
|
3. Add types to `frontend/src/api/types.ts` if API-related
|
|
4. Add tests co-located with component
|
|
|
|
### Error Handling
|
|
```python
|
|
from shared.exceptions import DatabaseError
|
|
|
|
try:
|
|
result = db.query(...)
|
|
except Exception as e:
|
|
raise DatabaseError(f"Failed to fetch document: {e}", details={"doc_id": doc_id})
|
|
```
|
|
|
|
### Database Access
|
|
```python
|
|
from shared.data.repositories import DocumentRepository
|
|
|
|
repo = DocumentRepository()
|
|
doc = repo.get_by_id(doc_id)
|
|
```
|