# Design Patterns & Code Patterns

## Rules
- Use repository-style DB wrapper: MotionDatabase encapsulates DuckDB access and schema management.
- AI provider adapter pattern: ai_provider.py exposes get_embedding(s) and chat_completion with retry/backoff and local fallback.
- Pipeline orchestration: run_pipeline.py uses phases, ThreadPoolExecutor for parallel SVD computation with careful DuckDB connection handling (collect results before writes).

## Examples

### Repository pattern (database.py MotionDatabase)
```python
class MotionDatabase:
    def __init__(self, db_path: str = config.DATABASE_PATH):
        self.db_path = db_path
        self._init_database()

    def insert_motion(self, motion_data: Dict) -> bool:
        """Insert a new motion into database"""
        # uses duckdb.connect and parameterized queries
```

### Provider adapter with retries (ai_provider.py)
```python
def _post_with_retries(path: str, json: dict[str, Any], retries: int = 3) -> requests.Response:
    # Implements retries/backoff, handles 429 with Retry-After and 5xx responses
```

### Pipeline parallelism pattern (run_pipeline)
```python
with ThreadPoolExecutor(max_workers=max_workers) as pool:
    for window_id, w_start, w_end in windows:
        fut = pool.submit(compute_svd_for_window, db.db_path, window_id, w_start, w_end, args.svd_k)
        futures[fut] = window_id
# wait then write sequentially to DuckDB
```

## Anti-patterns
- Broad excepts used in several places (database.py top-level try/except on duckdb import, many generic excepts around DB operations) — can hide real errors.

## Remediations
- Replace broad except Exception with targeted exceptions and explicit logging. Where fallback is intended (e.g., optional duckdb), log at INFO/DEBUG with clear message and include guidance in CONTRIBUTING.md.

## Evidence pointers
- ai_provider.py: _post_with_retries, get_embedding(s), _local_embedding (file: ai_provider.py lines ~1-300)
- pipeline/run_pipeline.py: ThreadPoolExecutor usage and duckdb connection handling (file: pipeline/run_pipeline.py lines ~120-260)
- database.py: MotionDatabase methods (file: database.py)