feat(mindmodel): add manifest loader and tests
This commit is contained in:
@@ -0,0 +1,34 @@
|
||||
# Naming & Style Conventions
|
||||
|
||||
## Rules
|
||||
- Modules and files: snake_case.py. Evidence: pipeline/run_pipeline.py, database.py, ai_provider.py
|
||||
- Functions and methods: snake_case. Evidence: compute_svd_for_window (pipeline), _generate_windows (pipeline/run_pipeline.py)
|
||||
- Classes: PascalCase. Evidence: MotionDatabase (database.py)
|
||||
- Constants: UPPER_SNAKE_CASE. Evidence: VOTE_MAP, DATABASE_PATH (config inferred)
|
||||
- Imports order: stdlib, third-party, local; prefer absolute imports and grouped.
|
||||
- Use black, ruff, isort, mypy as the recommended toolchain; repository lacks config files (black, ruff, pyproject sections).
|
||||
|
||||
## Examples
|
||||
|
||||
### Function example (from pipeline/run_pipeline.py)
|
||||
```python
|
||||
def _generate_windows(start: date, end: date, granularity: str) -> List[Tuple[str, str, str]]:
|
||||
"""Return list of (window_id, start_str, end_str) tuples."""
|
||||
```
|
||||
|
||||
### Class example (from database.py)
|
||||
```python
|
||||
class MotionDatabase:
|
||||
def __init__(self, db_path: str = config.DATABASE_PATH):
|
||||
...
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
- Missing formatting configs (black, ruff, isort). Add pyproject.toml sections or dedicated config files.
|
||||
|
||||
## Remediations
|
||||
- Add pyproject.toml tool sections for black/ruff/isort and a pre-commit config. Run ruff/black CI lint step.
|
||||
|
||||
## Evidence pointers
|
||||
- pipeline/run_pipeline.py: function _generate_windows (lines ~1-120)
|
||||
- database.py: MotionDatabase class and methods (file database.py lines 1-400+)
|
||||
@@ -0,0 +1,74 @@
|
||||
# Database Schema (DuckDB) — extracted DDL
|
||||
|
||||
## Rules
|
||||
- Use DuckDB for persistent storage when available; fallback to JSON files when duckdb is not installed (database.py).
|
||||
- Keep schema migrations additive (ALTER TABLE ADD COLUMN IF NOT EXISTS used in database.py).
|
||||
|
||||
## Examples (DDL snippets extracted from database.py)
|
||||
|
||||
### motions table
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS motions (
|
||||
id INTEGER DEFAULT nextval('motions_id_seq'),
|
||||
title TEXT NOT NULL,
|
||||
description TEXT,
|
||||
date DATE,
|
||||
policy_area TEXT,
|
||||
voting_results JSON,
|
||||
winning_margin FLOAT,
|
||||
controversy_score FLOAT,
|
||||
layman_explanation TEXT,
|
||||
externe_identifier TEXT,
|
||||
body_text TEXT,
|
||||
url TEXT UNIQUE,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (id)
|
||||
)
|
||||
```
|
||||
|
||||
### mp_votes table
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS mp_votes (
|
||||
id INTEGER DEFAULT nextval('mp_votes_id_seq'),
|
||||
motion_id INTEGER NOT NULL,
|
||||
mp_name TEXT NOT NULL,
|
||||
party TEXT,
|
||||
vote TEXT NOT NULL,
|
||||
date DATE,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (id)
|
||||
)
|
||||
```
|
||||
|
||||
### embeddings / fused_embeddings
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS embeddings (
|
||||
id INTEGER DEFAULT nextval('embeddings_id_seq'),
|
||||
motion_id INTEGER NOT NULL,
|
||||
model TEXT,
|
||||
vector JSON NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (id)
|
||||
)
|
||||
|
||||
CREATE TABLE IF NOT EXISTS fused_embeddings (
|
||||
id INTEGER DEFAULT nextval('fused_embeddings_id_seq'),
|
||||
motion_id INTEGER NOT NULL,
|
||||
window_id TEXT NOT NULL,
|
||||
vector JSON NOT NULL,
|
||||
svd_dims INTEGER NOT NULL,
|
||||
text_dims INTEGER NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (id)
|
||||
)
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
- Broad try/except around duckdb import (database.py top) — acceptable for optional dependency but should log explicitly the missing dependency and document test behavior.
|
||||
|
||||
## Remediations
|
||||
- Add a simple migration/versioning table (schema_version) to track schema changes and apply migrations deterministically.
|
||||
- Add tests that exercise both duckdb-backed and JSON-fallback database paths. Evidence: database.py contains JSON fallback logic (lines ~1-80).
|
||||
|
||||
## Evidence pointers
|
||||
- database.py: DDL strings and sequences (file: database.py lines ~1-300 and further). See create table blocks for motions, mp_votes, embeddings, fused_embeddings.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Domain Glossary
|
||||
|
||||
## Rules
|
||||
- Use consistent domain terms across code and DB: Motion, MP, Party, embedding, window, svd_vector, fused_embedding, similarity_cache, session_id.
|
||||
|
||||
## Terms
|
||||
- Motion: parliamentary motion stored in `motions` table. Evidence: database.py CREATE TABLE motions (file: database.py lines ~40-110)
|
||||
- MP (Member of Parliament): individual with votes stored in `mp_votes`. Evidence: database.py CREATE TABLE mp_votes
|
||||
- Embedding: text embedding stored in `embeddings` table; fused vectors in `fused_embeddings`.
|
||||
- SVD vector: reduced-dimensional vectors stored in `svd_vectors` table.
|
||||
- Window: time window identifier (e.g., "2024-Q1") used across SVD/fusion pipelines. Evidence: pipeline/run_pipeline.py _generate_windows
|
||||
- Controversy score: derived field stored on motions as controversy_score. Evidence: database.py insert_motion sets controversy_score
|
||||
|
||||
## Examples / Usage
|
||||
- pipeline.run_pipeline._generate_windows produces window ids used when storing svd_vectors and fused_embeddings. Evidence: pipeline/run_pipeline.py lines ~1-120
|
||||
|
||||
## Evidence pointers
|
||||
- database.py: motions, mp_votes, embeddings, fused_embeddings tables (file: database.py)
|
||||
- pipeline/run_pipeline.py: window generation and pipeline phases (file: pipeline/run_pipeline.py)
|
||||
|
||||
## Anti-patterns
|
||||
- Inconsistent naming of domain terms across modules (e.g., `mp_vote_parties` vs `mp_votes` usage in database.insert_motion and pipeline extraction). Prefer canonical names matching DB columns and use small adapter functions when transitioning representations.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Code Clusters / Organization
|
||||
|
||||
## Rules
|
||||
- The repository organizes code into the following clusters (observed):
|
||||
- UI / Streamlit: Home.py, pages/, app.py, explorer.py
|
||||
- Database & persistence: database.py, config.py
|
||||
- ETL / pipeline: pipeline/ (run_pipeline.py, svd_pipeline, text_pipeline, fusion)
|
||||
- AI provider & summarization: ai_provider.py, pipeline/..., analysis/
|
||||
- Similarity & caching: similarity/*, similarity_cache table in DB
|
||||
- API client & scraping: api_client.py, pipeline/fetch_mp_metadata
|
||||
- Analysis & visualization: analysis/visualize.py, explorer.py
|
||||
- CLI & scheduler: scheduler.py, pipeline/run_pipeline.py
|
||||
- Tests & migrations: tests/ (pytest) and database reset helpers
|
||||
|
||||
## Examples
|
||||
|
||||
### Pipeline orchestrator (cluster: CLI & pipeline)
|
||||
```python
|
||||
from database import MotionDatabase
|
||||
db = MotionDatabase(db_path)
|
||||
# then phases: fetch_mp_metadata, extract_mp_votes, compute svd, ensure_text_embeddings, fuse_for_window
|
||||
```
|
||||
|
||||
## Remediations
|
||||
- Add a brief CONTRIBUTING.md describing where to add new pipeline stages and how to run tests locally. Include notes about optional duckdb dependency and JSON fallback for tests.
|
||||
|
||||
## Evidence pointers
|
||||
- pipeline/run_pipeline.py: orchestrator and cluster boundaries (file: pipeline/run_pipeline.py)
|
||||
- ai_provider.py: AI adapter for embeddings and chat (file: ai_provider.py)
|
||||
- analysis/visualize.py: visualization cluster (file: analysis/visualize.py)
|
||||
@@ -0,0 +1,46 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,24 @@
|
||||
# Anti-patterns, Issues and Recommended Fixes
|
||||
|
||||
## Rules
|
||||
- Flagged issues discovered in Phase 1 must be remediated with concrete actions.
|
||||
|
||||
## Issues
|
||||
- pytest is listed as a runtime dependency (pyproject.toml). This increases image size and may pull dev-only transitive deps into production. Evidence: pyproject.toml
|
||||
- openai is declared but static imports not found; may be unused. Evidence: pyproject.toml, ai_provider.py uses requests and env keys instead of openai imports.
|
||||
- Many dependencies use permissive ">=" version ranges; no lockfile present. This reduces reproducibility.
|
||||
- Missing formatting/linting configs (black, ruff, isort, mypy). Recommended to add config and CI steps.
|
||||
- Broad except Exception used in many places (database.py, ai_provider.py fallback logic, analysis/visualize.py). This can mask bugs and slow debugging.
|
||||
|
||||
## Remediations / Recommended fixes
|
||||
- Move pytest from runtime dependencies to dev-dependencies in pyproject.toml.
|
||||
- Suggested patch: under [project.optional-dependencies] or [tool.poetry.dev-dependencies] depending on toolchain.
|
||||
- Audit `openai` usage. If unused, remove from pyproject.toml. If dynamically imported in runtime, add a small shim or explicit lazy import with documented env var.
|
||||
- Pin critical dependencies or add upper bounds; generate lockfile (poetry.lock or pip-tools requirements.txt). Add CI job that fails on permissive ranges.
|
||||
- Add black/ruff/isort/mypy config blocks to pyproject.toml and enable pre-commit hooks. Add CI lint stage.
|
||||
- Replace broad except Exception with narrower catches and re-raise or log with traceback when unexpected. Example locations: database.py top import, insert_motion broad except, ai_provider fallback blocks.
|
||||
|
||||
## Evidence pointers
|
||||
- pyproject.toml: dependencies list (file: pyproject.toml lines 1-40)
|
||||
- database.py: multiple broad except blocks (file: database.py top and methods)
|
||||
- ai_provider.py: uses requests + env keys (file: ai_provider.py)
|
||||
@@ -0,0 +1,117 @@
|
||||
# Example Extractions
|
||||
|
||||
## Rules
|
||||
- Include concrete examples extracted from the codebase: function signatures with docstrings, SQL DDL snippets, and pytest stubs following repository conventions.
|
||||
|
||||
## (a) Function signatures with docstrings (5 examples)
|
||||
1) pipeline/run_pipeline.py::_generate_windows
|
||||
```python
|
||||
def _generate_windows(start: date, end: date, granularity: str) -> List[Tuple[str, str, str]]:
|
||||
"""Return list of (window_id, start_str, end_str) tuples.
|
||||
|
||||
window_id format:
|
||||
quarterly → "2024-Q1", "2024-Q2", …
|
||||
annual → "2024"
|
||||
"""
|
||||
```
|
||||
|
||||
2) database.py::append_audit_event
|
||||
```python
|
||||
def append_audit_event(
|
||||
self,
|
||||
actor_id: Optional[str],
|
||||
action: str,
|
||||
target_type: Optional[str] = None,
|
||||
target_id: Optional[str] = None,
|
||||
metadata: Optional[Dict] = None,
|
||||
) -> bool:
|
||||
"""Record an audit event. Tries DB then falls back to ledger file."""
|
||||
```
|
||||
|
||||
3) ai_provider.py::get_embedding
|
||||
```python
|
||||
def get_embedding(text: str, model: str | None = None) -> list[float]:
|
||||
"""Return an embedding vector for `text` using the configured provider.
|
||||
|
||||
Raises ProviderError for configuration or provider-side failures.
|
||||
"""
|
||||
```
|
||||
|
||||
4) ai_provider.py::get_embeddings_batch
|
||||
```python
|
||||
def get_embeddings_batch(
|
||||
texts: list[str], model: str | None = None, batch_size: int = 50
|
||||
) -> list[list[float]]:
|
||||
"""Return embedding vectors for multiple texts using batched API calls."""
|
||||
```
|
||||
|
||||
5) analysis/visualize.py::plot_umap_scatter
|
||||
```python
|
||||
def plot_umap_scatter(
|
||||
motion_ids: List[int],
|
||||
coords: List[List[float]],
|
||||
labels: Optional[List[int]] = None,
|
||||
window_id: Optional[str] = None,
|
||||
output_path: str = "analysis_umap.html",
|
||||
) -> str:
|
||||
"""Produce a 2D scatter plot of UMAP-reduced fused embeddings."""
|
||||
```
|
||||
|
||||
## (b) SQL / DDL snippets (3 examples inferred from database.py)
|
||||
1) motions table (see constraints/10-db-schema.yaml) — evidence: database.py CREATE TABLE motions (lines ~40-110)
|
||||
|
||||
2) mp_votes table (see constraints/10-db-schema.yaml) — evidence: database.py CREATE TABLE mp_votes
|
||||
|
||||
3) fused_embeddings table (see constraints/10-db-schema.yaml) — evidence: database.py CREATE TABLE fused_embeddings
|
||||
|
||||
## (c) Pytest stubs (4 sample tests matching conventions)
|
||||
Create tests under tests/ named test_*.py using fixtures in conftest.py. Examples below are stubs to add.
|
||||
|
||||
1) tests/test_database_basic.py
|
||||
```python
|
||||
def test_init_database_creates_tables(tmp_path):
|
||||
db_path = str(tmp_path / "motions.db")
|
||||
from database import MotionDatabase
|
||||
|
||||
db = MotionDatabase(db_path=db_path)
|
||||
# If duckdb not available, JSON fallback should create .embeddings.json
|
||||
assert db is not None
|
||||
```
|
||||
|
||||
2) tests/test_ai_provider.py
|
||||
```python
|
||||
def test_local_embedding_fallback():
|
||||
from ai_provider import _local_embedding
|
||||
|
||||
v = _local_embedding("hello world", dim=16)
|
||||
assert isinstance(v, list) and len(v) == 16
|
||||
```
|
||||
|
||||
3) tests/test_pipeline_windows.py
|
||||
```python
|
||||
from pipeline.run_pipeline import _generate_windows
|
||||
|
||||
def test_generate_quarterly_windows():
|
||||
from datetime import date
|
||||
|
||||
start = date(2024, 1, 1)
|
||||
end = date(2024, 3, 31)
|
||||
windows = _generate_windows(start, end, "quarterly")
|
||||
assert any(w[0].endswith("Q1") for w in windows)
|
||||
```
|
||||
|
||||
4) tests/test_visualize_plot.py
|
||||
```python
|
||||
def test_plot_umap_scatter_no_plotly(monkeypatch, tmp_path):
|
||||
# If plotly missing, function should raise ImportError with guidance
|
||||
import analysis.visualize as vis
|
||||
|
||||
try:
|
||||
vis._require_plotly()
|
||||
except ImportError:
|
||||
assert True
|
||||
```
|
||||
|
||||
## Evidence pointers
|
||||
- Function docstrings: pipeline/run_pipeline.py, ai_provider.py, analysis/visualize.py, database.py
|
||||
- DDL: database.py create table blocks
|
||||
@@ -0,0 +1,43 @@
|
||||
# Stack and Dependencies
|
||||
|
||||
## Rules
|
||||
- Primary language: Python >=3.13 (evidence: pyproject.toml requires-python = ">=3.13")
|
||||
- Application: Streamlit app (streamlit >=1.48.0). Entrypoint: Home.py (CMD: streamlit run Home.py). Evidence: Home.py, pages/1_Stemwijzer.py, pyproject.toml, Dockerfile
|
||||
- Database: DuckDB + Ibis (duckdb>=1.3.2, ibis-framework[duckdb]>=10.8.0). Evidence: pyproject.toml, database.py
|
||||
- ML: scikit-learn, umap-learn, scipy. Evidence: pyproject.toml, pipeline/svd.py, analysis/
|
||||
|
||||
## Examples
|
||||
|
||||
### pyproject dependencies (evidence: pyproject.toml)
|
||||
```toml
|
||||
dependencies = [
|
||||
"duckdb>=1.3.2",
|
||||
"ibis-framework[duckdb]>=10.8.0",
|
||||
"openai>=1.99.7",
|
||||
"scipy>=1.11",
|
||||
"umap-learn>=0.5",
|
||||
"plotly>=5.0",
|
||||
"pytest>=9.0.2",
|
||||
"requests>=2.32.4",
|
||||
"schedule>=1.2.2",
|
||||
"streamlit>=1.48.0",
|
||||
"scikit-learn>=1.8.0",
|
||||
"beautifulsoup4>=4.14.3",
|
||||
"lxml>=6.0.2",
|
||||
]
|
||||
```
|
||||
|
||||
## Anti-patterns / Notes
|
||||
- pytest is listed under runtime dependencies in pyproject.toml (line: dependencies). Move pytest to dev-dependencies to avoid shipping test runner in production images. Evidence: pyproject.toml
|
||||
- Many dependencies use permissive ">=" ranges. Recommend pinning or generating lockfile (poetry.lock/requirements.txt) and adding upper bounds for reproducibility.
|
||||
- openai appears declared but static imports not found; possible unused dependency (evidence: pyproject.toml, ai_provider.py uses requests and environment keys instead of openai).
|
||||
|
||||
## Remediations
|
||||
- Move test-only libs (pytest) to dev-dependencies in pyproject.toml.
|
||||
- Add lockfile and CI step to check for pinned dependencies.
|
||||
- Audit declared but unused packages (openai) and remove or confirm dynamic usage.
|
||||
|
||||
## Evidence pointers
|
||||
- pyproject.toml: full dependency list (lines 1-40)
|
||||
- Home.py: streamlit usage and app entry (file: Home.py)
|
||||
- database.py: duckdb table creation and connection (file: database.py lines ~1-350)
|
||||
@@ -0,0 +1,5 @@
|
||||
# Mindmodel constraints README
|
||||
|
||||
Files in .mindmodel/constraints/ are YAML-like constraint documents describing
|
||||
conventions, patterns and remediation steps. Use these to guide PR reviews and
|
||||
CI automation.
|
||||
Reference in New Issue
Block a user