memor-db 0.1.0__tar.gz

memor_db-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: memor-db
+Version: 0.1.0
+Summary: A local-first, embedded bitemporal memory engine for LLM agents.
+Author: Memor Contributors
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: groq>=0.11.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tenacity>=8.3.0
+Requires-Dist: rank_bm25>=0.2.2
+Requires-Dist: sentence-transformers>=2.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+
+<p align="center">
+  <img src="assets/logo.png" alt="Memor Logo" width="380"/>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Dilraj07/Memor/actions/workflows/ci.yml"><img src="https://github.com/Dilraj07/Memor/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg?style=flat-square" alt="Python Version"></a>
+  <a href="https://github.com/Dilraj07/Memor"><img src="https://img.shields.io/badge/architecture-local--first%20bitemporal-0ea5e9.svg?style=flat-square" alt="Architecture"></a>
+</p>
+
+---
+
+**Memor** is an embedded, local-first bitemporal memory and retrieval engine for LLM agents.
+
+Standard vector databases store static embeddings of chat chunks. Over time, as users change their location, job, or preferences, chunk-based retrieval suffers from temporal drift—returning stale or contradictory facts. Memor solves this by extracting structured Subject-Predicate-Object facts and storing them in a bitemporal SQLite engine that tracks exactly when every fact became true, when it was invalidated, and when it was recorded.
+
+## Key Capabilities
+
+- **Zero-Infrastructure Embedded Storage**: Runs entirely on a local SQLite file (`memory.db`) with Write-Ahead Logging (WAL). No vector database clusters or cloud services required.
+- **Bitemporal Fact Audit Log**: Tracks both world time (`valid_from` to `valid_to`) and system transaction time (`recorded_at`). Previous states are never silently overwritten.
+- **Dual-Path Contradiction Resolution**: Fast-path heuristics instantly update single-valued predicates (e.g., `lives_in`, `works_at`). Ambiguous updates route through an LLM judge to determine whether new facts replace or append to existing knowledge.
+- **Hybrid Retrieval Pipeline**: Combines BM25 lexical search, dense semantic embeddings (`sentence-transformers`), and entity overlap scoring.
+- **Recursive Multi-Hop Graph Traversal**: Automatically traverses relationship chains (e.g., `user -> brother -> Alex -> owns_pet -> dog`) using SQLite `WITH RECURSIVE` common table expressions (CTEs) without requiring an external graph database.
+- **Parallel LLM Reranking**: Reranks top candidates concurrently across thread pools for sub-second relevance refinement.
+- **Bounded Garbage Collection**: Includes explicit, batch-based pruning (`engine.prune(older_than_days=N)`) that safely archives expired records to an immutable `facts_archive` table before deletion.
+- **Strict Multi-Tenancy & Thread Safety**: All operations are strictly isolated by `user_id` and protected by thread locks and backpressure queues.
+
+---
+
+## Architecture Flow
+
+```mermaid
+graph TD
+    A[User Turn / Dialogue] --> B[Async Extractor<br/>Structured Pydantic Schema]
+    B --> C{Conflict Resolver}
+    
+    C -->|Single-Valued Predicate<br/>e.g. lives_in| D[Fast Path: Invalidate Old Row]
+    C -->|Ambiguous Predicate| E[Slow Path: LLM Judge]
+    
+    E -->|Contradiction Detected| D
+    E -->|Additive Fact| F[Insert New Fact<br/>valid_to = NULL]
+    D --> F
+    
+    F --> G[(Bitemporal SQLite Store<br/>memory.db WAL)]
+    
+    subgraph Retrieval Pipeline
+        H[Query Text] --> I[BM25 Lexical Score]
+        H --> J[Dense Vector Similarity]
+        H --> K[Entity Overlap Score]
+        G --> L[WITH RECURSIVE<br/>Multi-Hop Graph CTE]
+        L --> M[Candidate Fusion Engine]
+        I --> M
+        J --> M
+        K --> M
+        M --> N[Parallel ThreadPool Reranker]
+        N --> O[Top-K High-Precision Context]
+    end
+```
+
+---
+
+## Installation
+
+Install directly from the repository root or via pip:
+
+```bash
+git clone https://github.com/Dilraj07/Memor.git
+cd Memor
+pip install -e .
+```
+
+Set your API provider credentials in `.env` or as an environment variable:
+
+```bash
+export GROQ_API_KEY="gsk_your_api_key_here"
+```
+
+---
+
+## Quickstart
+
+```python
+import time
+from memor.engine import MemoryEngine
+
+# Initialize the embedded memory engine
+engine = MemoryEngine()
+user_id = "tenant_8842"
+
+# 1. Add dialogue asynchronously (zero latency overhead on chat loops)
+engine.add_memory(user_id, "I live in San Francisco and work as a kernel developer.")
+engine.add_memory(user_id, "My brother Alex recently adopted a golden retriever.")
+
+# 2. Add an update that supersedes a previous state
+engine.add_memory(user_id, "I just relocated to Seattle last weekend.")
+
+# 3. Flush pending background extraction queues before synchronous queries
+engine.flush(user_id)
+
+# 4. Retrieve precise context (automatically combines active facts & multi-hop chains)
+context = engine.query(user_id, "Where does the user live and what pet does their family own?", k=3)
+print(context)
+```
+
+**Output:**
+```text
+- user lives in Seattle (Relevance: 9.50)
+- user -> brother -> Alex -> adopted -> golden retriever (Relevance: 9.10)
+- user works as kernel developer (Relevance: 7.20)
+```
+
+---
+
+## How Bitemporal State Tracking Works
+
+When a user's state changes, overwriting the record destroys temporal context. Memor instead updates the previous fact's `valid_to` timestamp and inserts the new state:
+
+| `id` | `user_id` | `subject` | `predicate` | `object` | `valid_from` | `valid_to` | `status` |
+|---|---|---|---|---|---|---|---|
+| 101 | `tenant_8842` | `user` | `lives_in` | `San Francisco` | `2026-01-10T10:00:00Z` | `2026-07-11T14:30:00Z` | *Superceded* |
+| 102 | `tenant_8842` | `user` | `lives_in` | `Seattle` | `2026-07-11T14:30:00Z` | `NULL` | **Active** |
+
+Retrieval queries filter by `WHERE valid_to IS NULL` by default, ensuring immediate access to current truths while preserving the full historical timeline for auditing or time-travel queries.
+
+---
+
+## API Reference
+
+### `MemoryEngine`
+
+#### `add_memory(user_id: str, text: str, sync: bool = False) -> None`
+Submits natural language text for background fact extraction and bitemporal resolution.
+- `sync=False`: Non-blocking submission to the internal worker pool. Applies backpressure if queue depth exceeds 100 turns.
+- `sync=True`: Synchronous extraction and persistence.
+
+#### `flush(user_id: str) -> None`
+Blocks execution until all pending asynchronous extraction futures for `user_id` complete. Recommended before reading immediate read-after-write state.
+
+#### `query(user_id: str, query_text: str, k: int = 5) -> str`
+Runs multi-signal hybrid retrieval (lexical + dense embedding + graph traversal) and returns the top `k` reranked factual statements formatted for LLM prompt injection.
+
+#### `prune(older_than_days: int) -> int`
+Garbage collection utility. Moves invalidated records older than `older_than_days` into `facts_archive` and hard-deletes them from the active index in bounded transactional batches of 500.
+
+#### `shutdown() -> None`
+Gracefully terminates background thread pools and executor queues.
+
+---
+
+## Testing & Verification
+
+Run the automated test suite across extraction, bitemporal pruning, and retrieval benchmarks:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

memor_db-0.1.0/README.md

@@ -0,0 +1,157 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Memor Logo" width="380"/>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Dilraj07/Memor/actions/workflows/ci.yml"><img src="https://github.com/Dilraj07/Memor/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg?style=flat-square" alt="Python Version"></a>
+  <a href="https://github.com/Dilraj07/Memor"><img src="https://img.shields.io/badge/architecture-local--first%20bitemporal-0ea5e9.svg?style=flat-square" alt="Architecture"></a>
+</p>
+
+---
+
+**Memor** is an embedded, local-first bitemporal memory and retrieval engine for LLM agents.
+
+Standard vector databases store static embeddings of chat chunks. Over time, as users change their location, job, or preferences, chunk-based retrieval suffers from temporal drift—returning stale or contradictory facts. Memor solves this by extracting structured Subject-Predicate-Object facts and storing them in a bitemporal SQLite engine that tracks exactly when every fact became true, when it was invalidated, and when it was recorded.
+
+## Key Capabilities
+
+- **Zero-Infrastructure Embedded Storage**: Runs entirely on a local SQLite file (`memory.db`) with Write-Ahead Logging (WAL). No vector database clusters or cloud services required.
+- **Bitemporal Fact Audit Log**: Tracks both world time (`valid_from` to `valid_to`) and system transaction time (`recorded_at`). Previous states are never silently overwritten.
+- **Dual-Path Contradiction Resolution**: Fast-path heuristics instantly update single-valued predicates (e.g., `lives_in`, `works_at`). Ambiguous updates route through an LLM judge to determine whether new facts replace or append to existing knowledge.
+- **Hybrid Retrieval Pipeline**: Combines BM25 lexical search, dense semantic embeddings (`sentence-transformers`), and entity overlap scoring.
+- **Recursive Multi-Hop Graph Traversal**: Automatically traverses relationship chains (e.g., `user -> brother -> Alex -> owns_pet -> dog`) using SQLite `WITH RECURSIVE` common table expressions (CTEs) without requiring an external graph database.
+- **Parallel LLM Reranking**: Reranks top candidates concurrently across thread pools for sub-second relevance refinement.
+- **Bounded Garbage Collection**: Includes explicit, batch-based pruning (`engine.prune(older_than_days=N)`) that safely archives expired records to an immutable `facts_archive` table before deletion.
+- **Strict Multi-Tenancy & Thread Safety**: All operations are strictly isolated by `user_id` and protected by thread locks and backpressure queues.
+
+---
+
+## Architecture Flow
+
+```mermaid
+graph TD
+    A[User Turn / Dialogue] --> B[Async Extractor<br/>Structured Pydantic Schema]
+    B --> C{Conflict Resolver}
+    
+    C -->|Single-Valued Predicate<br/>e.g. lives_in| D[Fast Path: Invalidate Old Row]
+    C -->|Ambiguous Predicate| E[Slow Path: LLM Judge]
+    
+    E -->|Contradiction Detected| D
+    E -->|Additive Fact| F[Insert New Fact<br/>valid_to = NULL]
+    D --> F
+    
+    F --> G[(Bitemporal SQLite Store<br/>memory.db WAL)]
+    
+    subgraph Retrieval Pipeline
+        H[Query Text] --> I[BM25 Lexical Score]
+        H --> J[Dense Vector Similarity]
+        H --> K[Entity Overlap Score]
+        G --> L[WITH RECURSIVE<br/>Multi-Hop Graph CTE]
+        L --> M[Candidate Fusion Engine]
+        I --> M
+        J --> M
+        K --> M
+        M --> N[Parallel ThreadPool Reranker]
+        N --> O[Top-K High-Precision Context]
+    end
+```
+
+---
+
+## Installation
+
+Install directly from the repository root or via pip:
+
+```bash
+git clone https://github.com/Dilraj07/Memor.git
+cd Memor
+pip install -e .
+```
+
+Set your API provider credentials in `.env` or as an environment variable:
+
+```bash
+export GROQ_API_KEY="gsk_your_api_key_here"
+```
+
+---
+
+## Quickstart
+
+```python
+import time
+from memor.engine import MemoryEngine
+
+# Initialize the embedded memory engine
+engine = MemoryEngine()
+user_id = "tenant_8842"
+
+# 1. Add dialogue asynchronously (zero latency overhead on chat loops)
+engine.add_memory(user_id, "I live in San Francisco and work as a kernel developer.")
+engine.add_memory(user_id, "My brother Alex recently adopted a golden retriever.")
+
+# 2. Add an update that supersedes a previous state
+engine.add_memory(user_id, "I just relocated to Seattle last weekend.")
+
+# 3. Flush pending background extraction queues before synchronous queries
+engine.flush(user_id)
+
+# 4. Retrieve precise context (automatically combines active facts & multi-hop chains)
+context = engine.query(user_id, "Where does the user live and what pet does their family own?", k=3)
+print(context)
+```
+
+**Output:**
+```text
+- user lives in Seattle (Relevance: 9.50)
+- user -> brother -> Alex -> adopted -> golden retriever (Relevance: 9.10)
+- user works as kernel developer (Relevance: 7.20)
+```
+
+---
+
+## How Bitemporal State Tracking Works
+
+When a user's state changes, overwriting the record destroys temporal context. Memor instead updates the previous fact's `valid_to` timestamp and inserts the new state:
+
+| `id` | `user_id` | `subject` | `predicate` | `object` | `valid_from` | `valid_to` | `status` |
+|---|---|---|---|---|---|---|---|
+| 101 | `tenant_8842` | `user` | `lives_in` | `San Francisco` | `2026-01-10T10:00:00Z` | `2026-07-11T14:30:00Z` | *Superceded* |
+| 102 | `tenant_8842` | `user` | `lives_in` | `Seattle` | `2026-07-11T14:30:00Z` | `NULL` | **Active** |
+
+Retrieval queries filter by `WHERE valid_to IS NULL` by default, ensuring immediate access to current truths while preserving the full historical timeline for auditing or time-travel queries.
+
+---
+
+## API Reference
+
+### `MemoryEngine`
+
+#### `add_memory(user_id: str, text: str, sync: bool = False) -> None`
+Submits natural language text for background fact extraction and bitemporal resolution.
+- `sync=False`: Non-blocking submission to the internal worker pool. Applies backpressure if queue depth exceeds 100 turns.
+- `sync=True`: Synchronous extraction and persistence.
+
+#### `flush(user_id: str) -> None`
+Blocks execution until all pending asynchronous extraction futures for `user_id` complete. Recommended before reading immediate read-after-write state.
+
+#### `query(user_id: str, query_text: str, k: int = 5) -> str`
+Runs multi-signal hybrid retrieval (lexical + dense embedding + graph traversal) and returns the top `k` reranked factual statements formatted for LLM prompt injection.
+
+#### `prune(older_than_days: int) -> int`
+Garbage collection utility. Moves invalidated records older than `older_than_days` into `facts_archive` and hard-deletes them from the active index in bounded transactional batches of 500.
+
+#### `shutdown() -> None`
+Gracefully terminates background thread pools and executor queues.
+
+---
+
+## Testing & Verification
+
+Run the automated test suite across extraction, bitemporal pruning, and retrieval benchmarks:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

memor_db-0.1.0/memor/__init__.py

@@ -0,0 +1,12 @@
+import logging
+
+# Set up a generic logger for the memor library.
+# We attach a NullHandler so that by default, the library is completely silent.
+# Downstream applications (like chat.py) can attach their own handlers
+# (e.g., StreamHandler) and set the log level to INFO or DEBUG to see the logs.
+logger = logging.getLogger("memor")
+logger.addHandler(logging.NullHandler())
+
+from .engine import MemoryEngine
+
+__all__ = ["MemoryEngine"]

memor_db-0.1.0/memor/config.py

@@ -0,0 +1,56 @@
+"""
+Central config. Uses Groq's OpenAI-compatible client, but you can swap this for
+any provider (OpenAI, Anthropic, local Ollama via OpenAI-compat shim) without
+touching the rest of the engine — everything downstream just calls `chat()`.
+"""
+import os
+from dotenv import load_dotenv
+from groq import Groq
+
+load_dotenv()
+
+_client = None
+MODEL = os.environ.get("GROQ_MODEL", "llama-3.1-8b-instant")
+
+
+def get_client() -> Groq:
+    global _client
+    if _client is None:
+        api_key = os.environ.get("GROQ_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "GROQ_API_KEY is not set. Add it to your .env file or set it as an environment variable. "
+                "Get a free key at https://console.groq.com/keys"
+            )
+        _client = Groq(api_key=api_key)
+    return _client
+
+
+def chat(messages: list[dict], json_mode: bool = False, temperature: float = 0.0) -> str:
+    """Single entry point for all LLM calls in this project. Keep the rest of the
+    codebase provider-agnostic by routing everything through here."""
+    kwargs = {}
+    if json_mode:
+        kwargs["response_format"] = {"type": "json_object"}
+    client = get_client()
+    resp = client.chat.completions.create(
+        model=MODEL,
+        messages=messages,
+        temperature=temperature,
+        **kwargs,
+    )
+    return resp.choices[0].message.content
+
+def chat_stream(messages: list[dict], temperature: float = 0.7):
+    """Generator that yields streaming chunks for interactive chat."""
+    client = get_client()
+    resp = client.chat.completions.create(
+        model=MODEL,
+        messages=messages,
+        temperature=temperature,
+        stream=True,
+    )
+    for chunk in resp:
+        content = chunk.choices[0].delta.content
+        if content is not None:
+            yield content

memor_db-0.1.0/memor/engine.py

@@ -0,0 +1,124 @@
+import concurrent.futures
+import threading
+import queue
+from memor.store import init_db, get_active_facts, insert_fact, invalidate_fact, prune_history
+from memor.extractor import extract_facts
+from memor.resolver import resolve
+from memor.retriever import HybridRetriever
+import logging
+
+logger = logging.getLogger("memor")
+
+_MAX_QUEUE_SIZE = 100
+
+
+class MemoryEngine:
+    def __init__(self):
+        init_db()
+        self._executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+        self._retrievers: dict[str, HybridRetriever] = {}
+        self._retriever_lock = threading.Lock()
+        self._futures_lock = threading.Lock()
+        self._pending_futures: dict[str, list[concurrent.futures.Future]] = {}
+
+    def add_memory(self, user_id: str, text: str, sync: bool = False):
+        """
+        Adds a user message to the memory engine to be processed for durable facts.
+        By default, runs in the background. If sync=True, blocks until extraction is done.
+
+        NOTE: When sync=False (default), a subsequent query() call may return stale
+        results if the background extraction has not yet completed. Use sync=True or
+        call flush(user_id) before querying if you need read-after-write consistency.
+        """
+        if sync:
+            self._process_turn(user_id, text)
+        else:
+            with self._futures_lock:
+                pending = self._pending_futures.get(user_id, [])
+                # Clean up completed futures
+                pending = [f for f in pending if not f.done()]
+                if len(pending) >= _MAX_QUEUE_SIZE:
+                    logger.warning(f"Backpressure: dropping memory for user {user_id}, queue full ({_MAX_QUEUE_SIZE})")
+                    return
+                future = self._executor.submit(self._process_turn, user_id, text)
+                pending.append(future)
+                self._pending_futures[user_id] = pending
+
+    def flush(self, user_id: str):
+        """
+        Block until all pending background writes for this user are complete.
+        Call this before query() if you need read-after-write consistency.
+        """
+        with self._futures_lock:
+            pending = self._pending_futures.pop(user_id, [])
+        for f in pending:
+            f.result()  # blocks until done
+
+    def _process_turn(self, user_id: str, text: str):
+        try:
+            facts = extract_facts(text)
+            if not facts:
+                return
+
+            for fact in facts:
+                # Narrow to the specific predicate to avoid N unnecessary LLM judge calls
+                existing_rows = get_active_facts(user_id, fact.subject, fact.predicate)
+
+                decision, old_row = resolve(fact, existing_rows)
+                
+                if decision == "ADD":
+                    insert_fact(user_id, fact.subject, fact.predicate, fact.object, fact.source_text)
+                    logger.info(f"[WRITE] ADD -> {fact.predicate}={fact.object}")
+                    self._invalidate_cache(user_id)
+                elif decision == "UPDATE" and old_row:
+                    invalidate_fact(user_id, old_row["id"])
+                    insert_fact(user_id, fact.subject, fact.predicate, fact.object, fact.source_text)
+                    logger.info(f"[WRITE] UPDATE -> {fact.predicate}: '{old_row['object']}' -> '{fact.object}'")
+                    self._invalidate_cache(user_id)
+                else:
+                    logger.debug(f"[WRITE] DUPLICATE (no-op) -> {fact.predicate}={fact.object}")
+        except Exception as e:
+            logger.error(f"Background memory extraction failed: {e}", exc_info=True)
+
+    def _invalidate_cache(self, user_id: str):
+        with self._retriever_lock:
+            self._retrievers.pop(user_id, None)
+
+    def prune(self, older_than_days: int) -> int:
+        """
+        Archive and hard-delete all inactive facts older than N days.
+        Returns the number of facts archived.
+        """
+        return prune_history(older_than_days)
+
+    def query(self, user_id: str, query_text: str, k: int = 5) -> str:
+        """
+        Retrieves the top k most relevant facts for the query.
+        Returns a formatted string of context.
+
+        NOTE: If add_memory() was called with sync=False, results may be stale
+        if background extraction has not yet completed. Call flush(user_id) first
+        if you need read-after-write consistency.
+        """
+        with self._retriever_lock:
+            retriever = self._retrievers.get(user_id)
+        
+        if retriever is None:
+            retriever = HybridRetriever().fit(user_id)
+            with self._retriever_lock:
+                self._retrievers[user_id] = retriever
+        
+        results = retriever.retrieve(query_text, k=k)
+        
+        if not results:
+            return "No relevant context found."
+            
+        context_lines = []
+        for r in results:
+            context_lines.append(f"- {r.fact_text} (Relevance: {r.rerank_score or r.fused_score:.2f})")
+            
+        return "\n".join(context_lines)
+
+    def shutdown(self):
+        self._executor.shutdown(wait=True)
+

memor_db-0.1.0/memor/extractor.py

@@ -0,0 +1,66 @@
+"""
+Turns a raw conversation turn into structured, timestamped facts.
+
+This is the first place naive memory projects cut corners — they either skip
+extraction entirely (raw text -> embedding) or extract with no schema. Structured
+extraction is what makes conflict resolution and temporal queries possible later.
+"""
+import json
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+from tenacity import retry, wait_exponential, stop_after_attempt, retry_if_exception_type
+from memor.config import chat
+import groq
+
+EXTRACTION_PROMPT = """You extract durable facts about the user from a message.
+Return ONLY a JSON object matching this schema: {{"facts": [{{"subject": str, "predicate": str, "object": str}}]}}
+
+Rules:
+- NEVER extract facts from questions (e.g. "Where do I live?"). ONLY extract facts from declarative statements.
+- Extract all factual information about the user (preferences, hobbies, relationships, job, devices, colors, pets, location).
+- subject is usually "user" unless the fact is about someone else the user mentions.
+- predicate should be a short normalized relation, e.g. "lives_in", "works_at", "prefers", "has_role".
+- The object MUST contain the full context. For example, for "I have a dog named Max", the object must be "dog named Max", not just "Max".
+- If there are no durable facts, return {{"facts": []}}.
+
+Message: "{message}"
+"""
+
+
+class Fact(BaseModel):
+    subject: str
+    predicate: str
+    object: str
+    extracted_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    source_text: str = ""
+
+
+class ExtractionResult(BaseModel):
+    facts: list[Fact]
+
+
+@retry(
+    wait=wait_exponential(multiplier=1, min=2, max=10),
+    stop=stop_after_attempt(3),
+    retry=retry_if_exception_type((groq.APIConnectionError, groq.RateLimitError, json.JSONDecodeError, ValueError))
+)
+def extract_facts(message: str) -> list[Fact]:
+    raw = chat(
+        [{"role": "user", "content": EXTRACTION_PROMPT.format(message=message)}],
+        json_mode=True,
+    )
+    
+    # Let Pydantic validate the structured output. If it fails (ValueError),
+    # tenacity will automatically retry the LLM call up to 3 times.
+    try:
+        parsed = json.loads(raw)
+        result = ExtractionResult(**parsed)
+    except Exception as e:
+        # Re-raise to trigger tenacity retry
+        raise ValueError(f"Failed to parse or validate LLM output: {raw}") from e
+
+    # Annotate with source text
+    for f in result.facts:
+        f.source_text = message
+        
+    return result.facts