You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
46 lines
2.1 KiB
46 lines
2.1 KiB
# 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)
|
|
|