# 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