py-context-graph 0.1.0__py3-none-any.whl

decision_graph/__init__.py

@@ -0,0 +1,8 @@
+"""Decision graph / cross-conversation decision intelligence flow."""
+
+from decision_graph.core.config import LLMConfig
+from decision_graph.core.interfaces import LLMAdapter
+from decision_graph.graph import DecisionGraph
+from decision_graph.llm import LiteLLMAdapter
+
+__all__ = ["DecisionGraph", "LLMAdapter", "LLMConfig", "LiteLLMAdapter"]

decision_graph/backends/firestore/__init__.py

@@ -0,0 +1,41 @@
+"""Simple Firestore backend for decision_graph.
+
+Usage::
+
+    from google.cloud import firestore
+    from decision_graph.backends.firestore import FirestoreBackend
+
+    client = firestore.Client()
+    backend = FirestoreBackend(client=client, collection_prefix="myapp_")
+"""
+
+from decision_graph.backends.firestore.stores import (
+    FirestoreClusterStore,
+    FirestoreEnrichmentStore,
+    FirestoreLinkStore,
+    FirestoreProjectionStore,
+)
+from decision_graph.core.registry import StorageBackend
+
+
+class FirestoreBackend(StorageBackend):
+    """Standalone Firestore backend — requires only a ``google.cloud.firestore.Client``."""
+
+    def __init__(self, *, client, collection_prefix: str = ""):
+        self._client = client
+        self._prefix = collection_prefix
+
+    def _col(self, name: str) -> str:
+        return f"{self._prefix}{name}"
+
+    def enrichment_store(self):
+        return FirestoreEnrichmentStore(self._client, self._col("decision_enrichments"))
+
+    def projection_store(self):
+        return FirestoreProjectionStore(self._client, self._col("decision_projections"))
+
+    def cluster_store(self):
+        return FirestoreClusterStore(self._client, self._col("decision_clusters"))
+
+    def link_store(self):
+        return FirestoreLinkStore(self._client, self._col("decision_links"))

decision_graph/backends/firestore/stores.py

@@ -0,0 +1,254 @@
+"""Simple Firestore implementations of the decision graph store protocols.
+
+No BaseDAO, no Singleton, no encryption. Just a Firestore client and collection names.
+Users provide their own ``google.cloud.firestore.Client`` instance.
+"""
+
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from decision_graph.core.interfaces import (
+    ClusterStore,
+    EnrichmentStore,
+    LinkStore,
+    ProjectionStore,
+)
+
+
+class FirestoreEnrichmentStore(EnrichmentStore):
+    def __init__(self, client, collection_name: str):
+        self._client = client
+        self._collection_name = collection_name
+
+    def _col(self):
+        return self._client.collection(self._collection_name)
+
+    def find_by_id(self, decision_id: str) -> Optional[dict]:
+        snap = self._col().document(decision_id).get()
+        return snap.to_dict() if snap.exists else None
+
+    def find_by_ids(self, ids: List[str]) -> Dict[str, dict]:
+        if not ids:
+            return {}
+        refs = [self._col().document(did) for did in ids]
+        result = {}
+        for snap in self._client.get_all(refs):
+            if snap.exists:
+                result[snap.id] = snap.to_dict()
+        return result
+
+    async def find_by_ids_async(self, ids: List[str]) -> Dict[str, dict]:
+        return self.find_by_ids(ids)
+
+    def save(self, decision_id: str, data: dict) -> None:
+        self._col().document(decision_id).set(data)
+
+    def upsert(self, decision_id: str, data: dict) -> None:
+        self._col().document(decision_id).set(data, merge=True)
+
+    def query(
+        self,
+        filters: List[Tuple[str, str, Any]],
+        order_by: Optional[List[Tuple[str, str]]] = None,
+        limit: int = 200,
+    ) -> List[dict]:
+        in_filters = [(f, v) for f, op, v in filters if op == "in"]
+        regular_filters = [(f, op, v) for f, op, v in filters if op != "in"]
+
+        if in_filters:
+            all_rows: List[dict] = []
+            for field, values in in_filters:
+                for i in range(0, len(values), 30):
+                    chunk = values[i : i + 30]
+                    q = self._col()
+                    for rf, rop, rv in regular_filters:
+                        q = q.where(rf, rop, rv)
+                    q = q.where(field, "in", chunk)
+                    if order_by:
+                        for ob_field, ob_dir in order_by:
+                            q = q.order_by(ob_field, direction=ob_dir)
+                    q = q.limit(limit)
+                    all_rows.extend(doc.to_dict() for doc in q.stream())
+            return all_rows[:limit]
+
+        q = self._col()
+        for f, op, v in filters:
+            q = q.where(f, op, v)
+        if order_by:
+            for ob_field, ob_dir in order_by:
+                q = q.order_by(ob_field, direction=ob_dir)
+        q = q.limit(limit)
+        return [doc.to_dict() for doc in q.stream()]
+
+
+class FirestoreProjectionStore(ProjectionStore):
+    def __init__(self, client, collection_name: str):
+        self._client = client
+        self._collection_name = collection_name
+
+    def _col(self):
+        return self._client.collection(self._collection_name)
+
+    def find_by_id(self, pid: str) -> Optional[dict]:
+        snap = self._col().document(pid).get()
+        return snap.to_dict() if snap.exists else None
+
+    def find_by_ids(self, ids: List[str]) -> Dict[str, dict]:
+        if not ids:
+            return {}
+        refs = [self._col().document(pid) for pid in ids]
+        result = {}
+        for snap in self._client.get_all(refs):
+            if snap.exists:
+                result[snap.id] = snap.to_dict()
+        return result
+
+    def find_by_conv_ids(self, cids: List[str], proj_type: str) -> List[dict]:
+        cid_set = set(cids)
+        q = self._col().where("proj_type", "==", proj_type).where("valid", "==", True)
+        return [doc.to_dict() for doc in q.stream() if doc.to_dict().get("cid") in cid_set]
+
+    async def find_by_filters(
+        self,
+        *,
+        gids: List[str],
+        proj_type: str,
+        last_n_days: Optional[int] = None,
+        limit: Optional[int] = None,
+        before_ts: Optional[float] = None,
+    ) -> List[dict]:
+        q = self._col().where("proj_type", "==", proj_type).where("valid", "==", True)
+        rows = []
+        gid_set = set(gids)
+        for doc in q.stream():
+            data = doc.to_dict()
+            if data.get("gid") not in gid_set:
+                continue
+            rows.append(data)
+
+        if last_n_days is not None:
+            cutoff = time.time() - (last_n_days * 86400)
+            rows = [r for r in rows if (r.get("updated_at") or r.get("created_at") or 0) >= cutoff]
+        if before_ts is not None:
+            rows = [r for r in rows if (r.get("updated_at") or r.get("created_at") or 0) < before_ts]
+        rows.sort(key=lambda r: r.get("updated_at") or r.get("created_at") or 0, reverse=True)
+        if limit:
+            rows = rows[:limit]
+        return rows
+
+    def query(
+        self,
+        filters: List[Tuple[str, str, Any]],
+        order_by: Optional[List[Tuple[str, str]]] = None,
+        limit: int = 200,
+    ) -> List[dict]:
+        q = self._col()
+        for f, op, v in filters:
+            q = q.where(f, op, v)
+        if order_by:
+            for ob_field, ob_dir in order_by:
+                q = q.order_by(ob_field, direction=ob_dir)
+        q = q.limit(limit)
+        return [doc.to_dict() for doc in q.stream()]
+
+    def invalidate(self, pid: str) -> None:
+        self._col().document(pid).update({"valid": False})
+
+    def save(self, *, pid: str, gid: str, cid: str, proj_type: str, projection: dict, msg_ts: int) -> bool:
+        doc_ref = self._col().document(pid)
+        snap = doc_ref.get()
+        if snap.exists:
+            return False
+        doc_ref.set(
+            {
+                "pid": pid,
+                "gid": gid,
+                "cid": cid,
+                "proj_type": proj_type,
+                "projection": projection,
+                "created_at": msg_ts,
+                "updated_at": msg_ts,
+                "valid": True,
+            }
+        )
+        return True
+
+    def update(self, *, pid: str, projection: dict, update_type: str, msg_ts: int) -> dict:
+        doc_ref = self._col().document(pid)
+        doc_ref.update({"projection": projection, "updated_at": msg_ts})
+        snap = doc_ref.get()
+        return snap.to_dict() if snap.exists else {}
+
+
+class FirestoreClusterStore(ClusterStore):
+    def __init__(self, client, collection_name: str):
+        self._client = client
+        self._collection_name = collection_name
+
+    def _col(self):
+        return self._client.collection(self._collection_name)
+
+    def create(self, data: dict) -> str:
+        cluster_id = data.get("cluster_id", "")
+        self._col().document(cluster_id).set(data)
+        return cluster_id
+
+    def update(self, cluster_id: str, updates: dict) -> None:
+        self._col().document(cluster_id).update(updates)
+
+    def find_by_id(self, cluster_id: str) -> Optional[dict]:
+        snap = self._col().document(cluster_id).get()
+        return snap.to_dict() if snap.exists else None
+
+    def find_by_ids(self, cluster_ids: List[str]) -> List[dict]:
+        if not cluster_ids:
+            return []
+        refs = [self._col().document(cid) for cid in cluster_ids]
+        return [snap.to_dict() for snap in self._client.get_all(refs) if snap.exists]
+
+
+
+class FirestoreLinkStore(LinkStore):
+    def __init__(self, client, collection_name: str):
+        self._client = client
+        self._collection_name = collection_name
+
+    def _col(self):
+        return self._client.collection(self._collection_name)
+
+    def save_batch(self, links: List[dict]) -> int:
+        if not links:
+            return 0
+        for link in links:
+            decision_id = link.get("decision_id", "")
+            self._col().document(decision_id).set(link)
+        return len(links)
+
+    def find_by_decision_id(self, decision_id: str) -> Optional[dict]:
+        snap = self._col().document(decision_id).get()
+        return snap.to_dict() if snap.exists else None
+
+    def find_by_cluster_id(self, cluster_id: str) -> List[dict]:
+        q = self._col().where("cluster_id", "==", cluster_id)
+        return [doc.to_dict() for doc in q.stream()]
+
+    def find_by_decision_ids(self, decision_ids: List[str]) -> Dict[str, dict]:
+        if not decision_ids:
+            return {}
+        refs = [self._col().document(did) for did in decision_ids]
+        return {snap.id: snap.to_dict() for snap in self._client.get_all(refs) if snap.exists}
+
+    def find_cluster_ids_by_gids(self, gids: List[str]) -> List[str]:
+        if not gids:
+            return []
+        gid_set = set(gids)
+        cluster_ids = set()
+        for doc in self._col().stream():
+            data = doc.to_dict()
+            if data.get("gid") in gid_set and data.get("cluster_id"):
+                cluster_ids.add(data["cluster_id"])
+        return list(cluster_ids)
+
+    def find_cluster_id_for_decision(self, decision_id: str) -> Optional[str]:
+        link = self.find_by_decision_id(decision_id)
+        return link.get("cluster_id") if link else None

decision_graph/backends/memory/__init__.py

@@ -0,0 +1,30 @@
+from decision_graph.backends.memory.stores import (
+    InMemoryClusterStore,
+    InMemoryEnrichmentStore,
+    InMemoryLinkStore,
+    InMemoryProjectionStore,
+    InMemoryVectorIndex,
+)
+from decision_graph.core.registry import StorageBackend
+
+
+class InMemoryBackend(StorageBackend):
+    """Fully in-memory backend. Useful for testing and as a reference implementation."""
+
+    def __init__(self):
+        self._enrichment_store = InMemoryEnrichmentStore()
+        self._projection_store = InMemoryProjectionStore()
+        self._cluster_store = InMemoryClusterStore()
+        self._link_store = InMemoryLinkStore()
+
+    def enrichment_store(self):
+        return self._enrichment_store
+
+    def projection_store(self):
+        return self._projection_store
+
+    def cluster_store(self):
+        return self._cluster_store
+
+    def link_store(self):
+        return self._link_store

decision_graph/backends/memory/stores.py

@@ -0,0 +1,323 @@
+"""In-memory implementations of the decision graph store protocols."""
+
+import math
+import re
+import time
+from collections import Counter
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+
+from decision_graph.core.interfaces import (
+    ClusterStore,
+    EnrichmentStore,
+    LinkStore,
+    ProjectionStore,
+)
+from decision_graph.ingestion import breakdown_hydrated_clusters
+
+
+def _get_nested(data: dict, field_path: str) -> Tuple[bool, Any]:
+    cur = data
+    for part in field_path.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return False, None
+        cur = cur[part]
+    return True, cur
+
+
+def _matches_filter(row: dict, field: str, op: str, value: Any) -> bool:
+    exists, field_value = _get_nested(row, field)
+    if not exists:
+        return False
+    if op == "==":
+        return field_value == value
+    if op == "!=":
+        return field_value != value
+    if op == "in":
+        return field_value in (value or [])
+    if op == "array_contains":
+        return isinstance(field_value, list) and value in field_value
+    if op == ">=":
+        return field_value >= value
+    if op == ">":
+        return field_value > value
+    if op == "<=":
+        return field_value <= value
+    if op == "<":
+        return field_value < value
+    raise ValueError(f"Unsupported filter op: {op}")
+
+
+def _apply_query(
+    data: Dict[str, dict],
+    filters: List[Tuple[str, str, Any]],
+    order_by: Optional[List[Tuple[str, str]]] = None,
+    limit: int = 200,
+) -> List[dict]:
+    rows = list(data.values())
+    for field, op, value in filters:
+        rows = [r for r in rows if _matches_filter(r, field, op, value)]
+    if order_by:
+        for ob_field, ob_dir in reversed(order_by):
+            reverse = ob_dir.upper() == "DESCENDING"
+            rows = sorted(
+                rows,
+                key=lambda r, f=ob_field: (r.get(f) is None, r.get(f)),
+                reverse=reverse,
+            )
+    return rows[:limit]
+
+
+class InMemoryEnrichmentStore(EnrichmentStore):
+    def __init__(self):
+        self._data: Dict[str, dict] = {}
+
+    def find_by_id(self, decision_id: str) -> Optional[dict]:
+        return self._data.get(decision_id)
+
+    def find_by_ids(self, ids: List[str]) -> Dict[str, dict]:
+        return {did: self._data[did] for did in ids if did in self._data}
+
+    async def find_by_ids_async(self, ids: List[str]) -> Dict[str, dict]:
+        return self.find_by_ids(ids)
+
+    def save(self, decision_id: str, data: dict) -> None:
+        self._data[decision_id] = dict(data)
+
+    def upsert(self, decision_id: str, data: dict) -> None:
+        existing = self._data.get(decision_id, {})
+        existing.update(data)
+        self._data[decision_id] = existing
+
+    def query(
+        self,
+        filters: List[Tuple[str, str, Any]],
+        order_by: Optional[List[Tuple[str, str]]] = None,
+        limit: int = 200,
+    ) -> List[dict]:
+        return _apply_query(self._data, filters, order_by, limit)
+
+
+class InMemoryProjectionStore(ProjectionStore):
+    def __init__(self):
+        self._data: Dict[str, dict] = {}
+
+    def find_by_ids(self, ids: List[str]) -> Dict[str, dict]:
+        return {pid: self._data[pid] for pid in ids if pid in self._data}
+
+    def find_by_conv_ids(self, cids: List[str], proj_type: str) -> List[dict]:
+        cid_set = set(cids)
+        return [
+            doc
+            for doc in self._data.values()
+            if doc.get("cid") in cid_set and doc.get("proj_type") == proj_type and doc.get("valid", True)
+        ]
+
+    async def find_by_filters(
+        self,
+        *,
+        gids: List[str],
+        proj_type: str,
+        last_n_days: Optional[int] = None,
+        limit: Optional[int] = None,
+        before_ts: Optional[float] = None,
+    ) -> List[dict]:
+        gid_set = set(gids)
+        rows = [
+            doc
+            for doc in self._data.values()
+            if doc.get("gid") in gid_set and doc.get("proj_type") == proj_type and doc.get("valid", True)
+        ]
+        if last_n_days is not None:
+            cutoff = time.time() - (last_n_days * 86400)
+            rows = [r for r in rows if (r.get("updated_at") or r.get("created_at") or 0) >= cutoff]
+        if before_ts is not None:
+            rows = [r for r in rows if (r.get("updated_at") or r.get("created_at") or 0) < before_ts]
+        rows.sort(key=lambda r: r.get("updated_at") or r.get("created_at") or 0, reverse=True)
+        if limit:
+            rows = rows[:limit]
+        return rows
+
+    def find_by_id(self, pid: str) -> Optional[dict]:
+        return self._data.get(pid)
+
+    def query(
+        self,
+        filters: List[Tuple[str, str, Any]],
+        order_by: Optional[List[Tuple[str, str]]] = None,
+        limit: int = 200,
+    ) -> List[dict]:
+        return _apply_query(self._data, filters, order_by, limit)
+
+    def invalidate(self, pid: str) -> None:
+        if pid in self._data:
+            self._data[pid]["valid"] = False
+
+    def save(self, *, pid: str, gid: str, cid: str, proj_type: str, projection: dict, msg_ts: int) -> bool:
+        is_new = pid not in self._data
+        if is_new:
+            self._data[pid] = {
+                "pid": pid,
+                "gid": gid,
+                "cid": cid,
+                "proj_type": proj_type,
+                "projection": projection,
+                "created_at": msg_ts,
+                "updated_at": msg_ts,
+                "valid": True,
+            }
+        return is_new
+
+    def update(self, *, pid: str, projection: dict, update_type: str, msg_ts: int) -> dict:
+        if pid in self._data:
+            self._data[pid]["projection"] = projection
+            self._data[pid]["updated_at"] = msg_ts
+        return self._data.get(pid, {})
+
+
+class InMemoryClusterStore(ClusterStore):
+    def __init__(self):
+        self._data: Dict[str, dict] = {}
+
+    def create(self, data: dict) -> str:
+        cluster_id = data.get("cluster_id", "")
+        self._data[cluster_id] = dict(data)
+        return cluster_id
+
+    def update(self, cluster_id: str, updates: dict) -> None:
+        if cluster_id in self._data:
+            self._data[cluster_id].update(updates)
+
+    def find_by_id(self, cluster_id: str) -> Optional[dict]:
+        return self._data.get(cluster_id)
+
+    def find_by_ids(self, cluster_ids: List[str]) -> List[dict]:
+        return [self._data[cid] for cid in cluster_ids if cid in self._data]
+
+
+class InMemoryLinkStore(LinkStore):
+    def __init__(self):
+        self._data: Dict[str, dict] = {}
+
+    def save_batch(self, links: List[dict]) -> int:
+        for link in links:
+            decision_id = link.get("decision_id", "")
+            self._data[decision_id] = dict(link)
+        return len(links)
+
+    def find_by_decision_id(self, decision_id: str) -> Optional[dict]:
+        return self._data.get(decision_id)
+
+    def find_by_cluster_id(self, cluster_id: str) -> List[dict]:
+        return [d for d in self._data.values() if d.get("cluster_id") == cluster_id]
+
+    def find_by_decision_ids(self, decision_ids: List[str]) -> Dict[str, dict]:
+        return {did: self._data[did] for did in decision_ids if did in self._data}
+
+    def find_cluster_ids_by_gids(self, gids: List[str]) -> List[str]:
+        gid_set = set(gids)
+        cluster_ids = set()
+        for link in self._data.values():
+            if link.get("gid") in gid_set and link.get("cluster_id"):
+                cluster_ids.add(link["cluster_id"])
+        return list(cluster_ids)
+
+    def find_cluster_id_for_decision(self, decision_id: str) -> Optional[str]:
+        link = self._data.get(decision_id)
+        return link.get("cluster_id") if link else None
+
+
+_STOP_WORDS = frozenset(
+    "a an the is are was were be been being have has had do does did will would "
+    "shall should may might can could i you he she it we they me him her us them "
+    "my your his its our their this that these those in on at to for with by from "
+    "of and or not no but if so as up out about into over after".split()
+)
+
+
+def _tokenize(text: str) -> List[str]:
+    return [w for w in re.findall(r"[a-z0-9]+", text.lower()) if w not in _STOP_WORDS and len(w) > 1]
+
+
+def _tfidf_vector(tokens: List[str], idf: Dict[str, float]) -> Dict[str, float]:
+    tf = Counter(tokens)
+    total = len(tokens) or 1
+    return {t: (c / total) * idf.get(t, 1.0) for t, c in tf.items()}
+
+
+def _cosine(a: Dict[str, float], b: Dict[str, float]) -> float:
+    keys = set(a) & set(b)
+    if not keys:
+        return 0.0
+    dot = sum(a[k] * b[k] for k in keys)
+    mag_a = math.sqrt(sum(v * v for v in a.values()))
+    mag_b = math.sqrt(sum(v * v for v in b.values()))
+    if mag_a == 0 or mag_b == 0:
+        return 0.0
+    return dot / (mag_a * mag_b)
+
+
+class InMemoryVectorIndex:
+    """TF-IDF cosine similarity vector index. No external dependencies."""
+
+    def __init__(self):
+        self._docs: List[Dict[str, Any]] = []
+        self._idf: Dict[str, float] = {}
+
+    def add(self, *, pid: str, text: str, gid: str, cid: str):
+        tokens = _tokenize(text)
+        self._docs.append({"pid": pid, "tokens": tokens, "gid": gid, "cid": cid})
+        self._rebuild_idf()
+
+    def _rebuild_idf(self):
+        n = len(self._docs)
+        df: Dict[str, int] = {}
+        for doc in self._docs:
+            for t in set(doc["tokens"]):
+                df[t] = df.get(t, 0) + 1
+        self._idf = {t: math.log((n + 1) / (c + 1)) + 1 for t, c in df.items()}
+
+    def get_top_n_matches(self, *, query: str, query_filter: Optional[dict], top_n: int) -> pd.DataFrame:
+        if not self._docs:
+            return pd.DataFrame()
+
+        query_tokens = _tokenize(query)
+        query_vec = _tfidf_vector(query_tokens, self._idf)
+
+        allowed_gids = None
+        if query_filter and "$in" in (query_filter.get("gid") or {}):
+            allowed_gids = set(query_filter["gid"]["$in"])
+
+        results = []
+        for doc in self._docs:
+            if allowed_gids and doc["gid"] not in allowed_gids:
+                continue
+            doc_vec = _tfidf_vector(doc["tokens"], self._idf)
+            score = _cosine(query_vec, doc_vec)
+            results.append({"pid": doc["pid"], "score": score, "gid": doc["gid"], "cid": doc["cid"]})
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        return pd.DataFrame(results[:top_n]) if results else pd.DataFrame()
+
+
+class InMemoryGraphStore:
+    """In-memory graph store that materializes hydrated clusters into graph arrays."""
+
+    def __init__(self):
+        self._hydrated_clusters: List[Dict[str, Any]] = []
+        self._graph_arrays: Dict[str, list] = {}
+
+    def ingest(self, hydrated_clusters: List[Dict[str, Any]]) -> None:
+        self._hydrated_clusters.extend(hydrated_clusters)
+        arrays = breakdown_hydrated_clusters(hydrated_clusters)
+        for key, items in arrays.items():
+            self._graph_arrays.setdefault(key, []).extend(items)
+
+    @property
+    def hydrated_clusters(self) -> List[Dict[str, Any]]:
+        return self._hydrated_clusters
+
+    @property
+    def graph_arrays(self) -> Dict[str, list]:
+        return self._graph_arrays