pycontextdb 0.1.0__py3-none-any.whl

contextdb/core/models.py

@@ -0,0 +1,151 @@
+"""Core data models for ContextDB.
+
+Every persisted object in ContextDB is modeled here. These Pydantic v2 types
+are the canonical representation used across storage, graphs, and the public
+API — so please keep them backwards-compatible when amending.
+
+Design notes:
+
+* All timestamps are timezone-aware UTC (``datetime.now(tz=timezone.utc)``).
+  Storing naive times is a recipe for silent drift between nodes.
+* Enums inherit from ``str`` so that ``model_dump()`` and SQL round-trips
+  produce human-readable values.
+* Default-factory is used for all mutable defaults (dict / list) — never bare
+  ``= {}`` or ``= []`` — so shared-state bugs cannot appear.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+GraphType = Literal["semantic", "temporal", "causal", "entity"]
+
+
+def _utcnow() -> datetime:
+    """Return the current UTC time as a timezone-aware :class:`datetime`."""
+    return datetime.now(tz=timezone.utc)
+
+
+class MemoryType(str, Enum):
+    """High-level category a :class:`MemoryItem` belongs to."""
+
+    FACTUAL = "FACTUAL"
+    EXPERIENTIAL = "EXPERIENTIAL"
+    WORKING = "WORKING"
+
+
+class MemoryStatus(str, Enum):
+    """Lifecycle state of a memory item."""
+
+    ACTIVE = "ACTIVE"
+    ARCHIVED = "ARCHIVED"
+    DELETED = "DELETED"
+
+
+class PIIType(str, Enum):
+    """Recognized PII categories. ``CUSTOM`` is an escape hatch for users."""
+
+    NAME = "NAME"
+    EMAIL = "EMAIL"
+    PHONE = "PHONE"
+    ADDRESS = "ADDRESS"
+    SSN = "SSN"
+    CREDIT_CARD = "CREDIT_CARD"
+    CUSTOM = "CUSTOM"
+
+
+class PIIAnnotation(BaseModel):
+    """A single PII span detected within ``MemoryItem.content``.
+
+    ``start`` and ``end`` are character offsets (half-open, Python slice
+    semantics) into the **original** content — not the redacted form.
+    """
+
+    pii_type: PIIType
+    start: int = Field(ge=0, description="Character offset (inclusive).")
+    end: int = Field(ge=0, description="Character offset (exclusive).")
+    original: str = Field(description="Original text that was flagged.")
+    redacted: str = Field(description="Replacement text (e.g., '[NAME]').")
+
+
+class Edge(BaseModel):
+    """A directed edge between two memory items in one of four graphs."""
+
+    source_id: str
+    target_id: str
+    graph_type: GraphType
+    weight: float = 1.0
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=_utcnow)
+
+
+class Entity(BaseModel):
+    """A named entity extracted from one or more memories."""
+
+    name: str
+    entity_type: str = Field(description="e.g., PERSON, ORG, PRODUCT, LOCATION.")
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    memory_ids: list[str] = Field(
+        default_factory=list,
+        description="IDs of memories that mention this entity.",
+    )
+
+
+class RetentionPolicy(BaseModel):
+    """Declarative retention rules applied by the retention enforcer.
+
+    Each ``*_ttl`` field may be ``None`` to disable expiry for that class of
+    memory. The default policy is chosen to match common privacy expectations:
+    long for factual, unbounded for experiential, short for working.
+    """
+
+    default_ttl: timedelta | None = timedelta(days=730)
+    factual_ttl: timedelta | None = timedelta(days=1825)
+    experiential_ttl: timedelta | None = None
+    working_ttl: timedelta | None = timedelta(hours=24)
+    right_to_erasure: bool = True
+
+
+class MemoryItem(BaseModel):
+    """The canonical unit of memory in ContextDB.
+
+    A :class:`MemoryItem` carries its content, vector embedding, lifecycle
+    metadata, privacy annotations, and back-references to entities and tags.
+    Graph relationships live in :class:`Edge` objects, not on the item
+    directly, so a memory can participate in multiple graphs without
+    schema churn.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    content: str
+    embedding: list[float] | None = None
+    memory_type: MemoryType = MemoryType.FACTUAL
+    source: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    event_time: datetime | None = Field(
+        default=None,
+        description="When the event occurred (valid-time). Distinct from ingestion_time.",
+    )
+    ingestion_time: datetime = Field(
+        default_factory=_utcnow,
+        description="When ContextDB stored the memory (system-time).",
+    )
+
+    pii_annotations: list[PIIAnnotation] = Field(default_factory=list)
+    retention_policy: RetentionPolicy | None = None
+
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    access_count: int = 0
+    last_accessed: datetime | None = None
+    confidence: float = 1.0
+    status: MemoryStatus = MemoryStatus.ACTIVE
+
+    entity_mentions: list[str] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)

contextdb/dynamics/__init__.py

@@ -0,0 +1,25 @@
+"""Dynamics layer — formation, evolution, retrieval of memories over time."""
+
+from __future__ import annotations
+
+from contextdb.dynamics.evolution import AutoLinker, Consolidator, Pruner
+from contextdb.dynamics.formation import (
+    FormationPipeline,
+    MemoryCompressor,
+    MemoryExtractor,
+    Segmenter,
+)
+from contextdb.dynamics.retrieval import QueryClassifier, RetrievalEngine, RetrievalFuser
+
+__all__ = [
+    "AutoLinker",
+    "Consolidator",
+    "FormationPipeline",
+    "MemoryCompressor",
+    "MemoryExtractor",
+    "Pruner",
+    "QueryClassifier",
+    "RetrievalEngine",
+    "RetrievalFuser",
+    "Segmenter",
+]

contextdb/dynamics/evolution.py

@@ -0,0 +1,168 @@
+"""Evolution engine — auto-linking, consolidation, and pruning.
+
+* :class:`AutoLinker` mirrors a new memory into every configured graph's
+  ``add_node`` hook so edges appear as memories are written.
+* :class:`Consolidator` finds dense semantic clusters and replaces them with
+  a single summary memory, pruning the originals (archive, not delete).
+* :class:`Pruner` applies decay / age / redundancy strategies to drop stale
+  memories — the operator chooses the strategy per call.
+
+The consolidator is intentionally conservative: it only touches memories
+that have multiple neighbors above the semantic threshold, so a single
+outlier never triggers a merge.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+from contextdb.core.models import MemoryItem, MemoryStatus, MemoryType
+
+if TYPE_CHECKING:
+    from contextdb.graphs.base import BaseGraph
+    from contextdb.graphs.semantic import SemanticGraph
+    from contextdb.store.sqlite_store import SQLiteStore
+    from contextdb.utils.llm import LLMProvider
+
+
+class AutoLinker:
+    """Forward newly-added nodes to each graph's ``add_node`` hook."""
+
+    def __init__(self, graphs: dict[str, BaseGraph]) -> None:
+        self.graphs = graphs
+
+    async def link(self, memory_id: str, data: dict[str, Any]) -> None:
+        for graph in self.graphs.values():
+            try:
+                await graph.add_node(memory_id, data)
+            except Exception:  # noqa: BLE001
+                # One graph failing must not block the others. Auto-linking
+                # is best-effort; hard failures surface on explicit calls.
+                continue
+
+
+class Consolidator:
+    """Merge dense semantic clusters into a single summary memory."""
+
+    def __init__(
+        self,
+        store: SQLiteStore,
+        semantic_graph: SemanticGraph,
+        llm: LLMProvider,
+        summary_prompt: str | None = None,
+    ) -> None:
+        self.store = store
+        self.semantic = semantic_graph
+        self.llm = llm
+        self.summary_prompt = summary_prompt or (
+            "Summarize these related memories into one coherent statement. "
+            "Preserve every entity and date.\n\n{memories}"
+        )
+
+    async def consolidate(self, min_cluster_size: int = 5) -> list[MemoryItem]:
+        """Walk active memories in 500-row pages, merging dense clusters."""
+        visited: set[str] = set()
+        summaries: list[MemoryItem] = []
+        async for memory in self.store.iter_memories(batch_size=500):
+            if memory.id in visited or memory.status != MemoryStatus.ACTIVE:
+                continue
+            neighbors = await self.semantic.get_neighbors(
+                memory.id, depth=1, max_results=min_cluster_size * 2
+            )
+            cluster_ids = [memory.id] + [nid for nid, _ in neighbors]
+            cluster_ids = [cid for cid in cluster_ids if cid not in visited]
+            if len(cluster_ids) < min_cluster_size:
+                continue
+            cluster_items: list[MemoryItem] = []
+            for cid in cluster_ids:
+                item = await self.store.get_raw(cid)
+                if item is None or item.status != MemoryStatus.ACTIVE:
+                    continue
+                cluster_items.append(item)
+            if len(cluster_items) < min_cluster_size:
+                continue
+
+            summary = await self._summarize([m.content for m in cluster_items])
+            if not summary:
+                continue
+            new_item = MemoryItem(
+                content=summary,
+                embedding=cluster_items[0].embedding,
+                memory_type=MemoryType.FACTUAL,
+                source="consolidator",
+                metadata={"consolidated_from": [m.id for m in cluster_items]},
+            )
+            stored = await self.store.add(new_item)
+            summaries.append(stored)
+            for m in cluster_items:
+                await self.store.update(m.id, status=MemoryStatus.ARCHIVED)
+                visited.add(m.id)
+            visited.add(stored.id)
+        return summaries
+
+    async def _summarize(self, contents: list[str]) -> str:
+        joined = "\n".join(f"- {c}" for c in contents)
+        prompt = self.summary_prompt.replace("{memories}", joined)
+        response = await self.llm.generate(prompt, temperature=0.0, max_tokens=400)
+        return response.strip()
+
+
+class Pruner:
+    """Drop stale memories by strategy.
+
+    Strategies:
+    * ``decay`` — access-count-weighted age; below ``threshold`` is archived.
+    * ``age`` — hard cutoff by ``older_than`` timedelta.
+    * ``redundancy`` — archive memories whose semantic neighbor count exceeds
+      ``max_neighbors`` (i.e., already well-represented).
+    """
+
+    def __init__(self, store: SQLiteStore) -> None:
+        self.store = store
+
+    async def prune(self, strategy: str = "decay", **kwargs: Any) -> int:
+        strategy = strategy.lower()
+        if strategy == "decay":
+            threshold = float(kwargs.get("threshold", 0.1))
+            return await self._prune_decay(threshold)
+        if strategy == "age":
+            older_than = kwargs.get("older_than", timedelta(days=365))
+            assert isinstance(older_than, timedelta)
+            return await self._prune_age(older_than)
+        if strategy == "redundancy":
+            semantic = kwargs.get("semantic_graph")
+            max_neighbors = int(kwargs.get("max_neighbors", 10))
+            if semantic is None:
+                return 0
+            return await self._prune_redundancy(semantic, max_neighbors)
+        raise ValueError(f"Unknown pruning strategy: {strategy}")
+
+    async def _prune_decay(self, threshold: float) -> int:
+        now = datetime.now(tz=timezone.utc)
+        pruned = 0
+        async for memory in self.store.iter_memories(batch_size=500):
+            age_days = max(1.0, (now - memory.created_at).total_seconds() / 86400.0)
+            score = (memory.access_count + 1) / age_days
+            if score < threshold:
+                await self.store.update(memory.id, status=MemoryStatus.ARCHIVED)
+                pruned += 1
+        return pruned
+
+    async def _prune_age(self, older_than: timedelta) -> int:
+        now = datetime.now(tz=timezone.utc)
+        pruned = 0
+        async for memory in self.store.iter_memories(batch_size=500):
+            if now - memory.created_at > older_than:
+                await self.store.update(memory.id, status=MemoryStatus.ARCHIVED)
+                pruned += 1
+        return pruned
+
+    async def _prune_redundancy(self, semantic: SemanticGraph, max_neighbors: int) -> int:
+        pruned = 0
+        async for memory in self.store.iter_memories(batch_size=500):
+            neighbors = await semantic.get_neighbors(memory.id, max_results=max_neighbors + 1)
+            if len(neighbors) > max_neighbors:
+                await self.store.update(memory.id, status=MemoryStatus.ARCHIVED)
+                pruned += 1
+        return pruned

contextdb/dynamics/formation.py

@@ -0,0 +1,193 @@
+"""Memory formation pipeline.
+
+Turns a raw conversation or document into a list of ready-to-store
+:class:`~contextdb.core.models.MemoryItem` objects. The steps are:
+
+1. :class:`Segmenter` — split into coherent conversational turns.
+2. :class:`MemoryExtractor` — LLM pulls atomic facts + entities from a turn.
+3. :class:`MemoryCompressor` — LLM compresses a cluster into a single summary.
+4. PII detection + embedding generation happen on the output items.
+
+Every step is optional at the call site — the pipeline short-circuits to
+the raw text if the LLM returns nothing usable.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING, Any
+
+from contextdb.core.models import MemoryItem, MemoryType
+
+if TYPE_CHECKING:
+    from contextdb.privacy.pii_detector import PIIDetector
+    from contextdb.utils.embeddings import EmbeddingProvider
+    from contextdb.utils.llm import LLMProvider
+
+
+_EXTRACT_PROMPT = """Extract atomic facts and named entities from the text.
+Return strict JSON.
+
+Schema:
+{"facts": [{"content": "string", "type": "FACTUAL|EXPERIENTIAL", "entities": ["string"]}]}
+
+Rules:
+- Each fact must be self-contained (understandable without context).
+- Skip small talk; keep substantive information only.
+- Aim for 1-5 facts per turn.
+
+Text: "{text}"
+"""
+
+_COMPRESS_PROMPT = """Summarize the following related memories into one concise
+statement. Preserve all named entities and dates. Return plain text, no JSON.
+
+Memories:
+{memories}
+"""
+
+
+def _safe_json(text: str) -> dict[str, Any]:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        text = "\n".join(line for line in lines if not line.startswith("```"))
+    try:
+        loaded = json.loads(text)
+        return loaded if isinstance(loaded, dict) else {}
+    except json.JSONDecodeError:
+        start = text.find("{")
+        end = text.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            try:
+                loaded = json.loads(text[start : end + 1])
+                return loaded if isinstance(loaded, dict) else {}
+            except json.JSONDecodeError:
+                return {}
+        return {}
+
+
+class Segmenter:
+    """Split raw text into turns / coherent chunks.
+
+    The baseline rule: newlines separate turns, and speaker prefixes
+    (``User:``, ``Agent:``) are preserved. Anything shorter than ``min_chars``
+    is merged into the next chunk so we don't emit fragments.
+    """
+
+    def __init__(self, min_chars: int = 20) -> None:
+        self.min_chars = min_chars
+
+    def segment(self, text: str) -> list[str]:
+        raw = [
+            chunk.strip()
+            for chunk in re.split(r"\n{2,}|(?<=[.!?])\s{2,}", text)
+            if chunk.strip()
+        ]
+        merged: list[str] = []
+        buffer = ""
+        for chunk in raw:
+            candidate = f"{buffer} {chunk}".strip() if buffer else chunk
+            if len(candidate) < self.min_chars:
+                buffer = candidate
+                continue
+            merged.append(candidate)
+            buffer = ""
+        if buffer:
+            if merged:
+                merged[-1] = f"{merged[-1]} {buffer}".strip()
+            else:
+                merged.append(buffer)
+        return merged
+
+
+class MemoryExtractor:
+    """LLM-driven fact + entity extraction per turn."""
+
+    def __init__(self, llm: LLMProvider) -> None:
+        self.llm = llm
+
+    async def extract(self, turn: str) -> list[dict[str, Any]]:
+        response = await self.llm.generate(_EXTRACT_PROMPT.replace("{text}", turn))
+        payload = _safe_json(response)
+        out: list[dict[str, Any]] = []
+        for raw in payload.get("facts", []) or []:
+            content = str(raw.get("content", "")).strip()
+            if not content:
+                continue
+            mem_type = str(raw.get("type", "FACTUAL")).upper()
+            if mem_type not in {"FACTUAL", "EXPERIENTIAL", "WORKING"}:
+                mem_type = "FACTUAL"
+            entities = [str(e).strip() for e in raw.get("entities", []) or [] if e]
+            out.append({"content": content, "memory_type": mem_type, "entities": entities})
+        return out
+
+
+class MemoryCompressor:
+    """LLM-driven cluster summarization.
+
+    Given a list of memory contents, produce a single condensed statement
+    that preserves entities and temporal markers. If the LLM returns an empty
+    string, we fall back to naïve concatenation so the caller never loses
+    data.
+    """
+
+    def __init__(self, llm: LLMProvider) -> None:
+        self.llm = llm
+
+    async def compress(self, memories: list[str]) -> str:
+        if not memories:
+            return ""
+        if len(memories) == 1:
+            return memories[0]
+        joined = "\n".join(f"- {m}" for m in memories)
+        response = await self.llm.generate(_COMPRESS_PROMPT.replace("{memories}", joined))
+        summary = response.strip()
+        return summary or " | ".join(memories)
+
+
+class FormationPipeline:
+    """Glue the formation steps into a single async entry point."""
+
+    def __init__(
+        self,
+        segmenter: Segmenter,
+        extractor: MemoryExtractor,
+        compressor: MemoryCompressor,
+        pii: PIIDetector,
+        embedder: EmbeddingProvider,
+    ) -> None:
+        self.segmenter = segmenter
+        self.extractor = extractor
+        self.compressor = compressor
+        self.pii = pii
+        self.embedder = embedder
+
+    async def process(self, text: str, source: str = "") -> list[MemoryItem]:
+        turns = self.segmenter.segment(text)
+        all_facts: list[dict[str, Any]] = []
+        for turn in turns:
+            facts = await self.extractor.extract(turn)
+            if not facts:
+                # Fallback: store the turn verbatim as a FACTUAL memory.
+                facts = [{"content": turn, "memory_type": "FACTUAL", "entities": []}]
+            all_facts.extend(facts)
+
+        items: list[MemoryItem] = []
+        contents = [fact["content"] for fact in all_facts]
+        embeddings = await self.embedder.embed(contents) if contents else []
+        for fact, embedding in zip(all_facts, embeddings, strict=False):
+            content = fact["content"]
+            processed, pii_annotations = self.pii.process(content)
+            items.append(
+                MemoryItem(
+                    content=processed,
+                    embedding=embedding,
+                    memory_type=MemoryType(fact["memory_type"]),
+                    source=source,
+                    pii_annotations=pii_annotations,
+                    entity_mentions=list(fact.get("entities", [])),
+                )
+            )
+        return items

contextdb/dynamics/retrieval.py

@@ -0,0 +1,130 @@
+"""Multi-graph retrieval — query classification + reciprocal-rank fusion.
+
+The engine runs the query against each configured graph (plus a raw vector
+search against the store) and fuses results using Reciprocal Rank Fusion
+(Cormack et al., 2009) with the classic ``k=60`` smoothing. RRF is
+parameter-light, ignores raw score scales, and tends to beat linear
+combination for heterogeneous retrievers — ideal when one retriever scores in
+cosine space and another in edge-weight space.
+
+The :class:`QueryClassifier` is intentionally rule-based. An LLM classifier
+would be more accurate but would add latency to every query; the regex
+heuristics below get ~80% of the signal for zero cost.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from contextdb.core.models import MemoryItem
+
+if TYPE_CHECKING:
+    from contextdb.graphs.base import BaseGraph
+    from contextdb.store.sqlite_store import SQLiteStore
+
+
+_TEMPORAL_MARKERS = re.compile(
+    r"\b(when|before|after|yesterday|today|tomorrow|last|next|since|until|during|ago)\b",
+    re.IGNORECASE,
+)
+_CAUSAL_MARKERS = re.compile(
+    r"\b(why|because|caused|leads? to|due to|resulted? in|reason|so that)\b",
+    re.IGNORECASE,
+)
+_ENTITY_MARKERS = re.compile(
+    r"\b(who|whose|which person|what company|what product)\b",
+    re.IGNORECASE,
+)
+
+
+class QueryClassifier:
+    """Classify a natural-language query into graph-weighting hints.
+
+    Returns a ``dict[graph_name, weight]`` that sums roughly to 1.0. Callers
+    use these as mixing weights when fusing per-graph rankings.
+    """
+
+    def classify(self, query: str) -> dict[str, float]:
+        weights: dict[str, float] = {"semantic": 1.0}
+        if _TEMPORAL_MARKERS.search(query):
+            weights["temporal"] = 1.2
+        if _CAUSAL_MARKERS.search(query):
+            weights["causal"] = 1.4
+        if _ENTITY_MARKERS.search(query):
+            weights["entity"] = 1.1
+        total = sum(weights.values())
+        return {k: v / total for k, v in weights.items()}
+
+
+class RetrievalFuser:
+    """Reciprocal Rank Fusion over per-graph candidate lists."""
+
+    def __init__(self, k: int = 60) -> None:
+        self.k = k
+
+    def fuse(
+        self,
+        rankings: dict[str, list[tuple[str, float]]],
+        weights: dict[str, float],
+    ) -> list[tuple[str, float]]:
+        scores: dict[str, float] = {}
+        for graph_name, ranking in rankings.items():
+            w = weights.get(graph_name, 0.0)
+            if w == 0.0 or not ranking:
+                continue
+            for rank, (memory_id, _) in enumerate(ranking, start=1):
+                scores[memory_id] = scores.get(memory_id, 0.0) + w * (1.0 / (self.k + rank))
+        return sorted(scores.items(), key=lambda kv: kv[1], reverse=True)
+
+
+class RetrievalEngine:
+    """Coordinate vector + graph retrieval and return ranked memories."""
+
+    def __init__(
+        self,
+        store: SQLiteStore,
+        graphs: dict[str, BaseGraph],
+        classifier: QueryClassifier,
+        fuser: RetrievalFuser,
+    ) -> None:
+        self.store = store
+        self.graphs = graphs
+        self.classifier = classifier
+        self.fuser = fuser
+
+    async def search(
+        self,
+        query: str,
+        query_embedding: list[float],
+        top_k: int = 10,
+    ) -> list[MemoryItem]:
+        weights = self.classifier.classify(query)
+        seed_items = await self.store.search_by_embedding(query_embedding, top_k=top_k * 2)
+        semantic_ranking = [(item.id, 1.0 / (rank + 1)) for rank, item in enumerate(seed_items)]
+        rankings: dict[str, list[tuple[str, float]]] = {"semantic": semantic_ranking}
+
+        seed_ids = [item.id for item in seed_items[: max(1, top_k)]]
+        for name, graph in self.graphs.items():
+            if name == "semantic":
+                continue
+            if weights.get(name, 0.0) <= 0.0:
+                continue
+            expanded: dict[str, float] = {}
+            for sid in seed_ids:
+                neighbors = await graph.get_neighbors(sid, max_results=top_k)
+                for nid, weight in neighbors:
+                    expanded[nid] = max(expanded.get(nid, 0.0), weight)
+            rankings[name] = sorted(expanded.items(), key=lambda kv: kv[1], reverse=True)
+
+        fused = self.fuser.fuse(rankings, weights)
+        ordered_ids = [mid for mid, _ in fused[:top_k]]
+        if not ordered_ids:
+            return seed_items[:top_k]
+
+        items: list[MemoryItem] = []
+        for mid in ordered_ids:
+            item = await self.store.get_raw(mid)
+            if item is not None:
+                items.append(item)
+        return items

contextdb/graphs/__init__.py

@@ -0,0 +1,17 @@
+"""Graph views over memories: semantic, temporal, causal, entity."""
+
+from __future__ import annotations
+
+from contextdb.graphs.base import BaseGraph
+from contextdb.graphs.causal import CausalGraph
+from contextdb.graphs.entity import EntityGraph
+from contextdb.graphs.semantic import SemanticGraph
+from contextdb.graphs.temporal import TemporalGraph
+
+__all__ = [
+    "BaseGraph",
+    "CausalGraph",
+    "EntityGraph",
+    "SemanticGraph",
+    "TemporalGraph",
+]