spendsignal 0.3.0__py3-none-any.whl

spendsignal/__init__.py

@@ -0,0 +1,48 @@
+"""SpendSignal - log line-item purchases with your own retrospective outcomes.
+
+A small local-first library. Retrieval over your own past, not prediction.
+See https://github.com/YemaneSG/SpendSignal for the full description.
+"""
+
+from spendsignal.aggregate import summarize
+from spendsignal.models import (
+    Abstention,
+    AxisDistribution,
+    BoolFeedbackValue,
+    CategoricalFeedbackValue,
+    Contradiction,
+    Coverage,
+    EvidenceSummary,
+    ExternalRef,
+    FeedbackEvent,
+    FeedbackValue,
+    Likert5FeedbackValue,
+    LineItem,
+    PurchaseEvent,
+    Query,
+    ReflectionExposure,
+    TargetRef,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "Abstention",
+    "AxisDistribution",
+    "BoolFeedbackValue",
+    "CategoricalFeedbackValue",
+    "Contradiction",
+    "Coverage",
+    "EvidenceSummary",
+    "ExternalRef",
+    "FeedbackEvent",
+    "FeedbackValue",
+    "Likert5FeedbackValue",
+    "LineItem",
+    "PurchaseEvent",
+    "Query",
+    "ReflectionExposure",
+    "TargetRef",
+    "__version__",
+    "summarize",
+]

spendsignal/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""Adapters that feed the SpendSignal evidence engine.
+
+See `ADR-0005` for the architecture rules. Each adapter lives in its own
+module, defines its own local pydantic types, and must not modify the
+four core event schemas or the `summarize` API.
+
+Available adapters:
+
+- `match_deterministic` - deterministic receipt-to-transaction matcher.
+  No runtime deps beyond stdlib. [match extra]
+- `retrieve_nn` - nearest-neighbor retrieval over comparison_keys.
+  Calls `spendsignal.aggregate.summarize` for each matched subject.
+  No runtime deps beyond stdlib. [retrieval extra]
+- `extract` - receipt text → PurchaseEvent. Mock + TextParser (stdlib).
+  Invoice2DataProvider optional under [extract] extra.
+- `mcp_server` - MCP server exposing summarize, retrieve, match as tools.
+  [mcp] extra. Run via `spendsignal serve`.
+- `actual_budget` - pulls BankTransaction records from Actual Budget.
+  MockActualProvider (no creds). ActualBudgetProvider under [actual] extra.
+"""

spendsignal/adapters/actual_budget.py

@@ -0,0 +1,179 @@
+"""Actual Budget adapter.
+
+Pulls transactions from a running Actual Budget instance and converts them
+to SpendSignal `BankTransaction` records for use with the matching adapter.
+
+Two providers:
+
+- `MockActualProvider` - returns the fixture transactions. No credentials,
+  no Actual Budget instance required. Default for CI and demos.
+- `ActualBudgetProvider` - wraps `actualpy` to pull from a real Actual Budget
+  server. Install with `pip install spendsignal[actual]`.
+
+Per ADR-0005 / D-007 this adapter does not modify core schemas or summarize.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from typing import Protocol, runtime_checkable
+
+from spendsignal.adapters.match_deterministic import BankTransaction
+
+
+@runtime_checkable
+class ActualProvider(Protocol):
+    """Protocol for Actual Budget data sources."""
+
+    def get_transactions(
+        self,
+        account_id: str | None = None,
+        since_date: str | None = None,
+    ) -> list[BankTransaction]:
+        """Return bank transactions as SpendSignal BankTransaction records."""
+        ...
+
+
+class MockActualProvider:
+    """Returns the four committed fixture transactions. No credentials needed."""
+
+    def get_transactions(
+        self,
+        account_id: str | None = None,
+        since_date: str | None = None,
+    ) -> list[BankTransaction]:
+        from datetime import datetime
+
+        del account_id, since_date  # mock ignores filters
+        return [
+            BankTransaction(
+                source_ref="actual-mock-txn-2026-01-16-costco",
+                occurred_at=datetime(2026, 1, 16, tzinfo=UTC),
+                amount_minor_units=9966,
+                currency="USD",
+                merchant_hint="COSTCO WHOLESALE #123",
+            ),
+            BankTransaction(
+                source_ref="actual-mock-txn-2026-06-15-costco",
+                occurred_at=datetime(2026, 6, 15, tzinfo=UTC),
+                amount_minor_units=9405,
+                currency="USD",
+                merchant_hint="COSTCO WHSE",
+            ),
+            BankTransaction(
+                source_ref="actual-mock-txn-2026-08-15-costco",
+                occurred_at=datetime(2026, 8, 15, tzinfo=UTC),
+                amount_minor_units=4999,
+                currency="USD",
+                merchant_hint="COSTCO",
+            ),
+            BankTransaction(
+                source_ref="actual-mock-txn-2026-03-02-shell",
+                occurred_at=datetime(2026, 3, 2, tzinfo=UTC),
+                amount_minor_units=4523,
+                currency="USD",
+                merchant_hint="SHELL OIL #12345",
+            ),
+        ]
+
+
+class ActualBudgetProvider:
+    """Wraps `actualpy` to pull transactions from a live Actual Budget server.
+
+    Install with: pip install spendsignal[actual]
+
+    Usage:
+        provider = ActualBudgetProvider(
+            server_url="http://localhost:5006",
+            password="your-password",
+            budget_id="your-budget-id",
+        )
+        txns = provider.get_transactions()
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        password: str,
+        budget_id: str,
+        encryption_password: str | None = None,
+    ) -> None:
+        try:
+            import actualpy  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise ImportError(
+                "actualpy is not installed. Install it with: pip install spendsignal[actual]"
+            ) from exc
+        self._actual_cls = actualpy.Actual
+        self._server_url = server_url
+        self._password = password
+        self._budget_id = budget_id
+        self._encryption_password = encryption_password
+
+    def get_transactions(
+        self,
+        account_id: str | None = None,
+        since_date: str | None = None,
+    ) -> list[BankTransaction]:
+        from datetime import datetime
+
+        with self._actual_cls(
+            base_url=self._server_url,
+            password=self._password,
+            file=self._budget_id,
+            encryption_password=self._encryption_password,
+        ) as actual:
+            actual.download_budget()
+            raw_txns = actual.session.query(actual.get_transactions()).all()
+
+        result: list[BankTransaction] = []
+        for t in raw_txns:
+            if account_id and str(getattr(t, "account_id", "")) != account_id:
+                continue
+            date_val = getattr(t, "date", None)
+            if since_date and date_val and str(date_val) < since_date:
+                continue
+            amount = getattr(t, "amount", 0) or 0
+            if isinstance(date_val, str):
+                occurred_at = datetime.fromisoformat(date_val).replace(tzinfo=UTC)
+            elif date_val is not None:
+                occurred_at = datetime(date_val.year, date_val.month, date_val.day, tzinfo=UTC)
+            else:
+                occurred_at = datetime.now(UTC)
+            payee = str(
+                getattr(t, "payee_name", None) or getattr(t, "imported_payee", None) or "unknown"
+            )
+            result.append(
+                BankTransaction(
+                    source_ref=str(getattr(t, "id", f"actual-{len(result)}")),
+                    occurred_at=occurred_at,
+                    # Actual stores amounts in milliunits (1/1000 of currency unit).
+                    # Convert to minor units (cents/pence): divide by 10.
+                    amount_minor_units=abs(int(amount)) // 10,
+                    currency="USD",
+                    merchant_hint=payee[:512],
+                )
+            )
+        return result
+
+
+def load_actual_transactions(
+    provider: ActualProvider | None = None,
+    account_id: str | None = None,
+    since_date: str | None = None,
+) -> list[BankTransaction]:
+    """Pull transactions from Actual Budget (or the mock by default).
+
+    Returns SpendSignal BankTransaction records ready for the matching adapter.
+    """
+    if provider is None:
+        provider = MockActualProvider()
+    return provider.get_transactions(account_id=account_id, since_date=since_date)
+
+
+__all__ = [
+    "ActualBudgetProvider",
+    "ActualProvider",
+    "MockActualProvider",
+    "load_actual_transactions",
+]

spendsignal/adapters/extract.py

@@ -0,0 +1,272 @@
+"""Receipt extraction adapter.
+
+Converts raw receipt text (pre-extracted from an image or PDF by the caller)
+into a SpendSignal `PurchaseEvent` via a swappable `ExtractionProvider`.
+
+The adapter ships two providers:
+
+- `MockExtractionProvider` - deterministic. Returns a pre-built PurchaseEvent
+  from template data. No deps, no network, CI-safe by default.
+- `Invoice2DataProvider` - wraps `invoice2data` using template YAML files.
+  Install with `pip install spendsignal[extract]`.
+
+Design (ADR-0005 / D-007): adapter-local types only. Does not modify core
+schemas or the `summarize` API.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from spendsignal.models import ExternalRef, LineItem, PurchaseEvent
+
+# --- Adapter-local types -----------------------------------------------------
+
+
+@runtime_checkable
+class ExtractionProvider(Protocol):
+    """Protocol for receipt text → PurchaseEvent converters."""
+
+    def extract(self, text: str, source_ref: str) -> PurchaseEvent:
+        """Convert raw receipt text to a PurchaseEvent.
+
+        `source_ref` is an opaque caller-supplied ID for the external_ref.
+        """
+        ...
+
+
+# --- Mock provider -----------------------------------------------------------
+
+
+class MockExtractionProvider:
+    """Deterministic mock for use in tests and CI.
+
+    Returns a realistic PurchaseEvent without parsing anything. The returned
+    event contains the Costco basket from the committed fixtures so tests have
+    a stable reference to assert against.
+    """
+
+    def extract(self, text: str, source_ref: str) -> PurchaseEvent:
+        del text  # mock ignores content; output is deterministic
+        return PurchaseEvent(
+            event_id=f"mock-{source_ref}",
+            occurred_at=datetime(2026, 1, 15, tzinfo=UTC),
+            external_ref=ExternalRef(source="mock-extractor", id=source_ref),
+            total_minor_units=9966,
+            currency="USD",
+            merchant_hint="COSTCO",
+            line_items=[
+                LineItem(
+                    line_id="pp",
+                    name="Protein powder",
+                    amount_minor_units=4999,
+                    comparison_key="protein-powder",
+                ),
+                LineItem(
+                    line_id="vt",
+                    name="Vitamins",
+                    amount_minor_units=2850,
+                    comparison_key="vitamins",
+                ),
+                LineItem(
+                    line_id="ck",
+                    name="Chicken",
+                    amount_minor_units=2117,
+                    comparison_key="chicken",
+                ),
+            ],
+        )
+
+
+# --- Regex text parser (stdlib, no extra deps) --------------------------------
+
+
+_LINE_PATTERN = re.compile(
+    r"(?P<name>[A-Za-z][A-Za-z0-9 &/,'-]{1,80}?)\s+"
+    r"\$?(?P<amount>\d{1,6}(?:\.\d{2})?)\s*$",
+    re.MULTILINE,
+)
+_TOTAL_PATTERN = re.compile(
+    r"(?:total|amount due|balance due|subtotal)[^\d]*\$?(?P<amount>\d{1,6}(?:\.\d{2})?)",
+    re.IGNORECASE,
+)
+_DATE_PATTERNS = [
+    re.compile(r"(\d{1,2})[/\-](\d{1,2})[/\-](\d{2,4})"),
+    re.compile(r"(\d{4})[/\-](\d{1,2})[/\-](\d{1,2})"),
+]
+
+
+def _parse_amount(raw: str) -> int:
+    """Convert a decimal dollar string to integer minor units."""
+    return round(float(raw.replace(",", "")) * 100)
+
+
+def _parse_date(text: str) -> datetime:
+    """Best-effort date extraction from receipt text. Falls back to now."""
+    for pat in _DATE_PATTERNS:
+        m = pat.search(text)
+        if m:
+            groups = m.groups()
+            try:
+                if len(groups[0]) == 4:  # YYYY-MM-DD
+                    return datetime(int(groups[0]), int(groups[1]), int(groups[2]), tzinfo=UTC)
+                y = int(groups[2])
+                if y < 100:
+                    y += 2000
+                return datetime(y, int(groups[0]), int(groups[1]), tzinfo=UTC)
+            except ValueError:
+                continue
+    return datetime.now(UTC)
+
+
+def _slug(name: str) -> str:
+    """Lowercase hyphenated slug from a display name."""
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")[:64]
+
+
+class TextParserProvider:
+    """Stdlib-only regex parser for plain-text receipt content.
+
+    Best-effort. Works well on machine-printed receipts with consistent
+    formatting (one item per line: name + price). Misses hand-written or
+    highly irregular receipts gracefully (produces fewer line items or
+    abstains on total).
+    """
+
+    def extract(self, text: str, source_ref: str) -> PurchaseEvent:
+        occurred_at = _parse_date(text)
+
+        lines_raw = _LINE_PATTERN.findall(text)
+        line_items = []
+        for i, (name, amount_str) in enumerate(lines_raw):
+            name = name.strip()
+            if not name or len(name) < 2:
+                continue
+            line_items.append(
+                LineItem(
+                    line_id=f"l{i}",
+                    name=name,
+                    amount_minor_units=_parse_amount(amount_str),
+                    comparison_key=_slug(name),
+                )
+            )
+
+        total_match = _TOTAL_PATTERN.search(text)
+        total_minor = (
+            _parse_amount(total_match.group("amount"))
+            if total_match
+            else sum(li.amount_minor_units for li in line_items)
+        )
+
+        first_line = text.strip().splitlines()[0] if text.strip() else "unknown"
+        merchant = first_line[:64].strip()
+
+        return PurchaseEvent(
+            event_id=f"text-parsed-{source_ref}",
+            occurred_at=occurred_at,
+            external_ref=ExternalRef(source="text-parser", id=source_ref),
+            total_minor_units=total_minor or 0,
+            currency="USD",
+            merchant_hint=merchant or "unknown",
+            line_items=line_items or None,
+        )
+
+
+# --- Invoice2Data provider (optional dep) ------------------------------------
+
+
+class Invoice2DataProvider:
+    """Wraps `invoice2data` for template-based PDF/text extraction.
+
+    Install with: `pip install spendsignal[extract]`.
+
+    Templates are YAML files that define patterns for known merchants. See
+    the invoice2data documentation for the template format. A templates_dir
+    of None uses invoice2data's bundled templates.
+    """
+
+    def __init__(self, templates_dir: str | Path | None = None) -> None:
+        try:
+            from invoice2data import extract_data  # type: ignore[import-not-found]
+            from invoice2data.extract.loader import read_templates  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise ImportError(
+                "invoice2data is not installed. Install it with: pip install spendsignal[extract]"
+            ) from exc
+        self._extract_data = extract_data
+        self._templates = read_templates(str(templates_dir)) if templates_dir else read_templates()
+
+    def extract(self, text: str, source_ref: str) -> PurchaseEvent:
+        import tempfile
+
+        with tempfile.NamedTemporaryFile(suffix=".txt", mode="w", delete=False) as tmp:
+            tmp.write(text)
+            tmp_path = tmp.name
+
+        result = self._extract_data(tmp_path, templates=self._templates)
+        Path(tmp_path).unlink(missing_ok=True)
+
+        if not result:
+            return TextParserProvider().extract(text, source_ref)
+
+        occurred_at = datetime.now(UTC)
+        if "date" in result and isinstance(result["date"], datetime):
+            occurred_at = (
+                result["date"].replace(tzinfo=UTC)
+                if result["date"].tzinfo is None
+                else result["date"]
+            )
+
+        items = result.get("lines", []) or []
+        line_items = [
+            LineItem(
+                line_id=f"l{i}",
+                name=str(item.get("description", f"item-{i}")),
+                amount_minor_units=round(float(item.get("price", 0)) * 100),
+                comparison_key=_slug(str(item.get("description", f"item-{i}"))),
+            )
+            for i, item in enumerate(items)
+        ]
+
+        total_raw = result.get("amount", result.get("total", 0)) or 0
+        return PurchaseEvent(
+            event_id=f"invoice2data-{source_ref}",
+            occurred_at=occurred_at,
+            external_ref=ExternalRef(source="invoice2data", id=source_ref),
+            total_minor_units=round(float(total_raw) * 100),
+            currency=str(result.get("currency", "USD")).upper(),
+            merchant_hint=str(result.get("issuer", "unknown"))[:512],
+            line_items=line_items or None,
+        )
+
+
+# --- Main entry point --------------------------------------------------------
+
+
+def extract(
+    text: str,
+    source_ref: str,
+    provider: ExtractionProvider | None = None,
+) -> PurchaseEvent:
+    """Extract a PurchaseEvent from receipt text using the given provider.
+
+    Defaults to `MockExtractionProvider` so CI never needs real credentials.
+    Pass `TextParserProvider()` for stdlib-only best-effort parsing.
+    Pass `Invoice2DataProvider()` for template-based extraction (requires
+    `pip install spendsignal[extract]`).
+    """
+    if provider is None:
+        provider = MockExtractionProvider()
+    return provider.extract(text, source_ref)
+
+
+__all__ = [
+    "ExtractionProvider",
+    "Invoice2DataProvider",
+    "MockExtractionProvider",
+    "TextParserProvider",
+    "extract",
+]