supermemory-agent 0.2.3__py3-none-any.whl

uall/distillation/distiller.py

@@ -0,0 +1,80 @@
+import uuid
+
+from uall_core.ports.storage import StoragePort
+from uall_core.providers.heuristic import HeuristicLLMProvider, cosine_similarity
+from uall_core.schemas.graph import GraphEdgeType, KnowledgeGraph
+from uall_core.schemas.lesson import CandidateLesson, Lesson
+from uall_core.schemas.namespace import ConfidenceDimensions, FreshnessMetrics, Provenance
+
+
+class KnowledgeDistiller:
+    def __init__(self, storage: StoragePort, llm: HeuristicLLMProvider | None = None):
+        self.storage = storage
+        self.llm = llm or HeuristicLLMProvider()
+        self.merge_threshold = 0.92
+
+    async def find_merge_target(self, candidate: CandidateLesson) -> tuple[str | None, float]:
+        emb = await self.llm.embed(f"{candidate.root_cause} {candidate.fix}")
+        best_id, best_sim = None, 0.0
+        for lesson in await self.storage.list_lessons("active"):
+            lesson_emb = lesson.embedding or await self.llm.embed(lesson.to_search_text())
+            sim = cosine_similarity(emb, lesson_emb)
+            if sim > best_sim:
+                best_sim, best_id = sim, lesson.lesson_id
+        if best_sim >= self.merge_threshold:
+            return best_id, best_sim
+        return None, best_sim
+
+    async def merge_into_lesson(self, lesson_id: str, candidate: CandidateLesson) -> Lesson:
+        lesson = await self.storage.get_lesson(lesson_id)
+        if not lesson:
+            raise ValueError(f"Lesson {lesson_id} not found")
+        lesson.occurrence_count += 1
+        lesson.confidence.evidence = min(1.0, lesson.confidence.evidence + 0.02)
+        lesson.confidence.recalculate_overall()
+        lesson.freshness.last_confirmed = lesson.freshness.created_at
+        await self.storage.update_lesson(lesson)
+        return lesson
+
+    async def candidate_to_lesson(
+        self,
+        candidate: CandidateLesson,
+        policy_version: str | None = None,
+        validator_action: str = "approve",
+    ) -> Lesson:
+        embedding = await self.llm.embed(f"{candidate.root_cause} {candidate.fix}")
+        lesson_id = f"lesson_{uuid.uuid4().hex[:8]}"
+        confidence = ConfidenceDimensions(
+            evidence=candidate.confidence,
+            retrieval_success=0.5,
+            human_verified=False,
+        )
+        confidence.recalculate_overall()
+        graph = KnowledgeGraph(lesson_id=lesson_id)
+        for eid in candidate.event_ids:
+            if eid.startswith("failure"):
+                graph.add_edge(GraphEdgeType.CAUSED_BY, eid)
+            if eid.startswith("correction"):
+                graph.add_edge(GraphEdgeType.FIXED_BY, eid)
+        return Lesson(
+            lesson_id=lesson_id,
+            failure=candidate.failure,
+            root_cause=candidate.root_cause,
+            fix=candidate.fix,
+            memory_type=candidate.memory_type,
+            stage=candidate.stage,
+            namespace=candidate.namespace,
+            confidence=confidence,
+            freshness=FreshnessMetrics(),
+            provenance=Provenance(
+                run_id=candidate.run_id,
+                reflection_id=candidate.reflection_id,
+                event_ids=candidate.event_ids,
+                policy_version=policy_version,
+                validator_action=validator_action,
+                promoted_at=__import__("datetime").datetime.utcnow(),
+            ),
+            graph=graph,
+            embedding=embedding,
+            quality_score=0.7,
+        )

uall/evaluation/engine.py

@@ -0,0 +1,38 @@
+from uall_core.ports.storage import StoragePort
+
+
+class EvaluationEngine:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+
+    async def evaluate_run(self, run_id: str) -> dict:
+        run = await self.storage.get_run(run_id)
+        if not run:
+            return {"error": "run not found"}
+        events = run.get("events", [])
+        failures = sum(1 for e in events if e.get("event_type") == "failure")
+        corrections = sum(1 for e in events if e.get("event_type") == "correction")
+        success = run.get("success", False)
+        score = 1.0 if success else 0.0
+        score -= failures * 0.15
+        score -= corrections * 0.1
+        score = max(0.0, min(1.0, score))
+        return {
+            "run_id": run_id,
+            "score": round(score, 3),
+            "success": success,
+            "failures": failures,
+            "corrections": corrections,
+            "retry_count": failures,
+            "human_intervention": corrections > 0,
+        }
+
+    async def agent_score(self, agent_id: str | None = None) -> dict:
+        runs = await self.storage.list_runs()
+        scores = []
+        for run in runs:
+            ev = await self.evaluate_run(run.get("run_id", ""))
+            if "score" in ev:
+                scores.append(ev["score"])
+        avg = sum(scores) / len(scores) if scores else 0.0
+        return {"agent_id": agent_id, "average_score": round(avg, 3), "run_count": len(scores)}

uall/experiments/manager.py

@@ -0,0 +1,83 @@
+import uuid
+from datetime import datetime
+
+from uall_core.ports.storage import StoragePort
+from uall_core.schemas.common import Experiment, ExperimentMetrics
+
+
+class ExperimentManager:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+        self.min_sample_size = 30
+
+    async def start(
+        self,
+        resource_type: str,
+        resource_id: str,
+        variant_a: str,
+        variant_b: str,
+        traffic_split: float = 0.1,
+    ) -> Experiment:
+        exp = Experiment(
+            experiment_id=f"exp_{uuid.uuid4().hex[:8]}",
+            resource_type=resource_type,
+            resource_id=resource_id,
+            variant_a=variant_a,
+            variant_b=variant_b,
+            traffic_split=traffic_split,
+        )
+        await self.storage.save_experiment(exp)
+        return exp
+
+    async def record_run_metrics(
+        self, experiment_id: str, variant: str, metrics: dict
+    ) -> Experiment:
+        exp = await self.storage.get_experiment(experiment_id)
+        if not exp:
+            raise ValueError(f"Experiment {experiment_id} not found")
+        target = exp.metrics_b if variant == "b" else exp.metrics_a
+        target.sample_size += 1
+        if metrics.get("success"):
+            target.success_rate = (
+                target.success_rate * (target.sample_size - 1) + 1
+            ) / target.sample_size
+        else:
+            target.success_rate = (
+                target.success_rate * (target.sample_size - 1)
+            ) / target.sample_size
+        target.retry_count = metrics.get("retry_count", target.retry_count)
+        target.cost = metrics.get("cost", target.cost)
+        target.latency_p50 = metrics.get("latency_p50", target.latency_p50)
+        target.latency_p95 = metrics.get("latency_p95", target.latency_p95)
+        target.token_usage = metrics.get("token_usage", target.token_usage)
+        target.human_approval_rate = metrics.get("human_approval_rate", target.human_approval_rate)
+        target.downstream_failure_rate = metrics.get(
+            "downstream_failure_rate", target.downstream_failure_rate
+        )
+        await self.storage.update_experiment(exp)
+        return exp
+
+    async def conclude(self, experiment_id: str) -> Experiment:
+        exp = await self.storage.get_experiment(experiment_id)
+        if not exp:
+            raise ValueError(f"Experiment {experiment_id} not found")
+        if exp.metrics_b.sample_size < self.min_sample_size:
+            exp.status = "running"
+            exp.winner = None
+        elif exp.metrics_b.success_rate > exp.metrics_a.success_rate:
+            guardrail_ok = (
+                exp.metrics_b.latency_p95 <= exp.metrics_a.latency_p95 * 1.2
+                and exp.metrics_b.downstream_failure_rate
+                <= exp.metrics_a.downstream_failure_rate + 0.05
+            )
+            exp.winner = "b" if guardrail_ok else None
+            exp.status = "concluded" if guardrail_ok else "rolled_back"
+        else:
+            exp.winner = "a"
+            exp.status = "concluded"
+        exp.concluded_at = datetime.utcnow()
+        await self.storage.update_experiment(exp)
+        return exp
+
+    async def get_results(self, experiment_id: str) -> Experiment | None:
+        return await self.storage.get_experiment(experiment_id)

uall/memory/confidence.py

@@ -0,0 +1,36 @@
+from uall_core.schemas.lesson import Lesson
+from uall_core.schemas.namespace import ConfidenceDimensions
+
+
+def recalculate_overall(confidence: ConfidenceDimensions) -> float:
+    return confidence.recalculate_overall()
+
+
+def update_from_telemetry(
+    lesson: Lesson, used: bool, accepted: bool, improved: bool | None
+) -> Lesson:
+    if used:
+        lesson.freshness.usage_count += 1
+        from datetime import datetime
+
+        lesson.freshness.last_used = datetime.utcnow()
+    if improved is True:
+        lesson.freshness.success_after_use += 1
+        lesson.confidence.retrieval_success = min(1.0, lesson.confidence.retrieval_success + 0.01)
+    elif improved is False:
+        lesson.freshness.failure_after_use += 1
+        lesson.confidence.retrieval_success = max(0.0, lesson.confidence.retrieval_success - 0.03)
+    if accepted:
+        lesson.confidence.human_verified = True
+        from datetime import datetime
+
+        lesson.freshness.last_confirmed = datetime.utcnow()
+    lesson.confidence.recalculate_overall()
+    return lesson
+
+
+def update_from_human_confirmation(lesson: Lesson) -> Lesson:
+    lesson.confidence.human_verified = True
+    lesson.confidence.evidence = min(1.0, lesson.confidence.evidence + 0.05)
+    lesson.confidence.recalculate_overall()
+    return lesson

uall/memory/freshness.py

@@ -0,0 +1,28 @@
+from datetime import datetime, timedelta
+
+from uall_core.schemas.lesson import Lesson
+
+
+def compute_staleness(lesson: Lesson) -> float:
+    f = lesson.freshness
+    if f.usage_count == 0:
+        age_days = (datetime.utcnow() - f.created_at).days
+        return min(0.5, age_days / 365)
+
+    success_rate = f.success_after_use / max(f.usage_count, 1)
+    staleness = 1.0 - success_rate
+
+    if f.last_used:
+        days_since = (datetime.utcnow() - f.last_used).days
+        staleness += min(0.3, days_since / 180)
+
+    if f.last_confirmed:
+        days_since_confirm = (datetime.utcnow() - f.last_confirmed).days
+        staleness -= min(0.2, days_since_confirm / 90)
+
+    return round(max(0.0, min(1.0, staleness)), 4)
+
+
+def freshness_weight(lesson: Lesson) -> float:
+    lesson.freshness.staleness_score = compute_staleness(lesson)
+    return 1.0 - lesson.freshness.staleness_score

uall/memory/graph.py

@@ -0,0 +1,24 @@
+from uall_core.schemas.graph import GraphEdgeType, KnowledgeGraph
+from uall_core.schemas.lesson import Lesson
+
+
+def get_lesson_graph(lesson: Lesson) -> KnowledgeGraph:
+    if lesson.graph:
+        return lesson.graph
+    return KnowledgeGraph(lesson_id=lesson.lesson_id)
+
+
+def add_edge(lesson: Lesson, edge_type: GraphEdgeType, target_id: str) -> Lesson:
+    graph = get_lesson_graph(lesson)
+    graph.add_edge(edge_type, target_id)
+    lesson.graph = graph
+    return lesson
+
+
+def graph_to_dict(lesson: Lesson) -> dict:
+    graph = get_lesson_graph(lesson)
+    result: dict[str, list[str]] = {}
+    for edge in graph.edges:
+        key = edge.edge_type.value
+        result.setdefault(key, []).append(edge.target_id)
+    return {"lesson_id": lesson.lesson_id, "edges": result}

uall/memory/namespaces.py

@@ -0,0 +1,40 @@
+from uall_core.schemas.namespace import NAMESPACE_PRIORITY, NamespaceLevel, NamespaceRef
+
+
+def parse_namespace(namespace: str | None) -> NamespaceRef | None:
+    if not namespace:
+        return None
+    if ":" in namespace:
+        level_str, ns_id = namespace.split(":", 1)
+        try:
+            level = NamespaceLevel(level_str)
+        except ValueError:
+            level = NamespaceLevel.PROJECT
+        return NamespaceRef(level=level, namespace_id=ns_id)
+    return NamespaceRef(namespace_id=namespace)
+
+
+def namespace_match_score(lesson_ns: NamespaceRef, query_ns: NamespaceRef | None) -> float:
+    if query_ns is None:
+        return 0.5
+    if lesson_ns.namespace_id == query_ns.namespace_id and lesson_ns.level == query_ns.level:
+        return 1.0
+    try:
+        lesson_pri = NAMESPACE_PRIORITY.index(lesson_ns.level)
+        query_pri = NAMESPACE_PRIORITY.index(query_ns.level)
+        if lesson_pri <= query_pri:
+            return 0.7
+    except ValueError:
+        pass
+    return 0.3
+
+
+RETRIEVAL_PRIORITY = [
+    "policies",
+    NamespaceLevel.ORGANIZATION,
+    NamespaceLevel.TEAM,
+    NamespaceLevel.PROJECT,
+    NamespaceLevel.USER,
+    NamespaceLevel.SESSION,
+    NamespaceLevel.GLOBAL,
+]

uall/memory/policies.py

@@ -0,0 +1,44 @@
+from uall_core.ports.storage import StoragePort
+from uall_core.schemas.common import PolicyVersion
+from uall_core.schemas.lesson import Lesson
+
+
+class PolicyManager:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+
+    async def get_active(self) -> list[PolicyVersion]:
+        policies = await self.storage.get_active_policies()
+        if not policies:
+            default = PolicyVersion(
+                policy_id="security_policy",
+                version="v1",
+                rules=[
+                    "Never expose secrets in output",
+                    "Prefer inspecting document structure before OCR",
+                ],
+            )
+            await self.storage.save_policy(default)
+            return [default]
+        return policies
+
+    async def create_policy(self, policy: PolicyVersion) -> str:
+        return await self.storage.save_policy(policy)
+
+    async def list_versions(self, policy_id: str) -> list[PolicyVersion]:
+        return await self.storage.list_policy_versions(policy_id)
+
+    async def get_active_version_string(self) -> str:
+        policies = await self.get_active()
+        if policies:
+            return f"{policies[0].policy_id}:{policies[0].version}"
+        return "none"
+
+    async def flag_lessons_for_revalidation(self, old_version: str) -> list[str]:
+        flagged = []
+        for lesson in await self.storage.list_lessons("active"):
+            if lesson.provenance.policy_version == old_version:
+                lesson.status = "pending_revalidation"
+                await self.storage.update_lesson(lesson)
+                flagged.append(lesson.lesson_id)
+        return flagged

uall/memory/provenance.py

@@ -0,0 +1,23 @@
+from uall_core.schemas.lesson import Lesson
+from uall_core.schemas.namespace import Provenance
+
+
+def attach_provenance(
+    lesson: Lesson,
+    run_id: str | None = None,
+    reflection_id: str | None = None,
+    event_ids: list[str] | None = None,
+    policy_version: str | None = None,
+    validator_action: str | None = None,
+) -> Lesson:
+    from datetime import datetime
+
+    lesson.provenance = Provenance(
+        run_id=run_id or lesson.provenance.run_id,
+        reflection_id=reflection_id or lesson.provenance.reflection_id,
+        event_ids=event_ids or lesson.provenance.event_ids,
+        policy_version=policy_version or lesson.provenance.policy_version,
+        validator_action=validator_action or lesson.provenance.validator_action,
+        promoted_at=datetime.utcnow(),
+    )
+    return lesson

uall/memory/pruning.py

@@ -0,0 +1,55 @@
+from uall_core.ports.storage import StoragePort
+from uall_core.providers.heuristic import cosine_similarity, HeuristicLLMProvider
+from uall.memory.freshness import compute_staleness
+
+
+class MemoryPruner:
+    def __init__(self, storage: StoragePort, llm: HeuristicLLMProvider | None = None):
+        self.storage = storage
+        self.llm = llm or HeuristicLLMProvider()
+
+    async def prune(self) -> dict:
+        merged = await self._merge_duplicates()
+        archived = await self._archive_stale()
+        removed = await self._remove_low_value()
+        return {"merged": merged, "archived": archived, "removed": removed}
+
+    async def _merge_duplicates(self) -> int:
+        lessons = await self.storage.list_lessons("active")
+        count = 0
+        seen: set[str] = set()
+        for i, a in enumerate(lessons):
+            if a.lesson_id in seen:
+                continue
+            for b in lessons[i + 1 :]:
+                if b.lesson_id in seen:
+                    continue
+                emb_a = a.embedding or await self.llm.embed(a.to_search_text())
+                emb_b = b.embedding or await self.llm.embed(b.to_search_text())
+                if cosine_similarity(emb_a, emb_b) > 0.95:
+                    a.occurrence_count += b.occurrence_count
+                    await self.storage.update_lesson(a)
+                    b.status = "archived"
+                    await self.storage.update_lesson(b)
+                    seen.add(b.lesson_id)
+                    count += 1
+        return count
+
+    async def _archive_stale(self) -> int:
+        count = 0
+        for lesson in await self.storage.list_lessons("active"):
+            lesson.freshness.staleness_score = compute_staleness(lesson)
+            if lesson.freshness.staleness_score > 0.8 and lesson.freshness.usage_count < 3:
+                lesson.status = "archived"
+                await self.storage.update_lesson(lesson)
+                count += 1
+        return count
+
+    async def _remove_low_value(self) -> int:
+        count = 0
+        for lesson in await self.storage.list_lessons("active"):
+            if lesson.quality_score < 0.3 and lesson.freshness.usage_count == 0:
+                lesson.status = "archived"
+                await self.storage.update_lesson(lesson)
+                count += 1
+        return count

uall/memory/retrieval.py

@@ -0,0 +1,98 @@
+import uuid
+from datetime import datetime
+
+from uall_core.ports.storage import StoragePort
+from uall_core.providers.heuristic import HeuristicLLMProvider, cosine_similarity
+from uall_core.schemas.common import PolicyVersion, RetrievalTelemetryEvent
+from uall_core.schemas.lesson import Lesson, MemorySearchRequest, MemorySearchResult
+from uall.memory.freshness import freshness_weight
+from uall.memory.namespaces import namespace_match_score, parse_namespace
+from uall.memory.ttl import is_expired, ttl_weight
+
+
+class MemoryRetriever:
+    """Hybrid multi-stage retrieval pipeline."""
+
+    def __init__(self, storage: StoragePort, llm: HeuristicLLMProvider | None = None):
+        self.storage = storage
+        self.llm = llm or HeuristicLLMProvider()
+
+    async def retrieve(self, request: MemorySearchRequest) -> list[MemorySearchResult]:
+        # Stage 1: policies (injected first, not ranked)
+        policies = await self.storage.get_active_policies()
+        policy_text = self._format_policies(policies)
+
+        # Stage 2: namespace + metadata filter via storage
+        candidates = await self.storage.search_lessons(request)
+
+        # Stage 3: vector similarity scoring
+        query_emb = await self.llm.embed(request.query)
+        query_ns = parse_namespace(request.namespace)
+
+        scored: list[tuple[float, Lesson]] = []
+        for lesson in candidates:
+            if is_expired(lesson):
+                continue
+            emb = lesson.embedding or await self.llm.embed(lesson.to_search_text())
+            semantic = cosine_similarity(query_emb, emb)
+            stage_boost = self._stage_boost(lesson, request)
+            ns_boost = namespace_match_score(lesson.namespace, query_ns)
+            fresh_w = freshness_weight(lesson)
+            ttl_w = ttl_weight(lesson)
+            conf_w = lesson.confidence.overall
+            final = semantic * stage_boost * ns_boost * fresh_w * ttl_w * conf_w
+            scored.append((final, lesson))
+
+        # Stage 4: rerank top candidates (lightweight sort)
+        scored.sort(key=lambda x: x[0], reverse=True)
+        top = scored[: request.top_k]
+
+        results = []
+        token_budget = request.max_tokens
+        policy_tokens = len(policy_text.split())
+        token_budget -= policy_tokens
+
+        for score, lesson in top:
+            text = f"- {lesson.fix}"
+            tokens = len(text.split())
+            if token_budget <= 0:
+                break
+            tid = f"tel_{uuid.uuid4().hex[:8]}"
+            await self.storage.save_telemetry(
+                RetrievalTelemetryEvent(
+                    telemetry_id=tid,
+                    lesson_id=lesson.lesson_id,
+                    retrieved=True,
+                )
+            )
+            results.append(MemorySearchResult(lesson=lesson, score=score, telemetry_id=tid))
+            token_budget -= tokens
+
+        if policy_text and results:
+            # Attach policy context to first result metadata
+            results[0].lesson.metadata["policy_prefix"] = policy_text
+
+        return results
+
+    def _stage_boost(self, lesson: Lesson, request: MemorySearchRequest) -> float:
+        boost = 0.1
+        if request.step and lesson.stage.step == request.step:
+            boost = 1.0
+        elif request.workflow and lesson.stage.workflow == request.workflow:
+            boost = 0.6
+        elif request.domain and lesson.stage.domain == request.domain:
+            boost = 0.3
+        if request.tool and lesson.stage.tool == request.tool:
+            boost = max(boost, 0.8)
+        if request.agent and lesson.stage.agent == request.agent:
+            boost = max(boost, 0.9)
+        return boost
+
+    def _format_policies(self, policies: list[PolicyVersion]) -> str:
+        if not policies:
+            return ""
+        lines = ["[ORG POLICIES]"]
+        for p in policies:
+            for rule in p.rules:
+                lines.append(f"- {rule}")
+        return "\n".join(lines)

uall/memory/ttl.py

@@ -0,0 +1,22 @@
+from datetime import datetime, timedelta
+
+from uall_core.schemas.lesson import Lesson
+
+
+def is_expired(lesson: Lesson) -> bool:
+    if lesson.ttl.expires_at and lesson.ttl.expires_at < datetime.utcnow():
+        return True
+    if lesson.ttl.auto_revalidate_after_days:
+        cutoff = lesson.freshness.created_at + timedelta(days=lesson.ttl.auto_revalidate_after_days)
+        if datetime.utcnow() > cutoff and not lesson.freshness.last_confirmed:
+            lesson.status = "pending_revalidation"
+            return True
+    return False
+
+
+def ttl_weight(lesson: Lesson) -> float:
+    if is_expired(lesson):
+        return 0.0
+    if lesson.status == "pending_revalidation":
+        return 0.1
+    return 1.0