supermemory-agent 0.2.3__py3-none-any.whl

uall/memory/validator.py

@@ -0,0 +1,144 @@
+from uall_core.ports.storage import StoragePort
+from uall_core.providers.heuristic import HeuristicLLMProvider
+from uall_core.schemas.common import PolicyVersion
+from uall_core.schemas.lesson import CandidateLesson, ValidationResult
+
+
+class MemoryValidator:
+    def __init__(self, storage: StoragePort, llm: HeuristicLLMProvider | None = None):
+        self.storage = storage
+        self.llm = llm or HeuristicLLMProvider()
+        self.min_quality = 0.4
+
+    async def validate(self, candidate: CandidateLesson) -> ValidationResult:
+        quality = await self._score_quality(candidate)
+        policies = await self.storage.get_active_policies()
+
+        if not self._has_evidence(candidate):
+            return ValidationResult(
+                action="reject",
+                candidate=candidate,
+                quality_score=quality,
+                reason="No evidence in event payload",
+            )
+
+        for policy in policies:
+            if await self._contradicts_policy(candidate, policy):
+                return ValidationResult(
+                    action="reject",
+                    candidate=candidate,
+                    quality_score=quality,
+                    reason=f"Contradicts policy {policy.policy_id} v{policy.version}",
+                )
+
+        merge_id, sim = await self._find_duplicate(candidate)
+        if merge_id:
+            return ValidationResult(
+                action="merge",
+                candidate=candidate,
+                quality_score=quality,
+                merge_target_id=merge_id,
+                reason=f"Near-duplicate similarity {sim:.2f}",
+            )
+
+        conflict = await self._find_conflict(candidate)
+        if conflict:
+            return ValidationResult(
+                action="reject",
+                candidate=candidate,
+                quality_score=quality,
+                reason=f"Conflicts with lesson {conflict}",
+            )
+
+        if quality < self.min_quality:
+            return ValidationResult(
+                action="reject",
+                candidate=candidate,
+                quality_score=quality,
+                reason=f"Quality score {quality:.2f} below threshold",
+            )
+
+        if len(candidate.fix) < 20 or not any(
+            w in candidate.fix.lower() for w in ("verify", "check", "inspect", "validate", "use", "before", "first")
+        ):
+            rewritten = await self._rewrite(candidate)
+            return ValidationResult(
+                action="rewrite",
+                candidate=candidate,
+                quality_score=quality,
+                rewritten_fix=rewritten,
+                reason="Rewritten for clarity and actionability",
+            )
+
+        return ValidationResult(
+            action="approve",
+            candidate=candidate,
+            quality_score=quality,
+            reason="Passed all validation checks",
+        )
+
+    async def _score_quality(self, candidate: CandidateLesson) -> float:
+        score = 0.3
+        if candidate.failure:
+            score += 0.15
+        if candidate.root_cause and len(candidate.root_cause) > 10:
+            score += 0.2
+        if candidate.fix and len(candidate.fix) > 15:
+            score += 0.25
+        if candidate.evidence_payload:
+            score += 0.1
+        return min(1.0, score)
+
+    def _has_evidence(self, candidate: CandidateLesson) -> bool:
+        if candidate.event_ids:
+            return True
+        if candidate.failure and candidate.failure.strip():
+            return True
+        if candidate.fix and len(candidate.fix.strip()) > 10:
+            return True
+        payload = candidate.evidence_payload or {}
+        snippet = payload.get("snippet") or payload.get("after") or payload.get("intent")
+        return bool(snippet and str(snippet).strip())
+
+    async def _contradicts_policy(self, candidate: CandidateLesson, policy: PolicyVersion) -> bool:
+        fix_lower = candidate.fix.lower()
+        for rule in policy.rules:
+            rule_lower = rule.lower()
+            if "never expose secrets" in rule_lower and "secret" in fix_lower:
+                if "never" not in fix_lower and "don't" not in fix_lower:
+                    return True
+        return False
+
+    async def _find_duplicate(self, candidate: CandidateLesson) -> tuple[str | None, float]:
+        from uall_core.providers.heuristic import cosine_similarity
+
+        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 >= 0.92:
+            return best_id, best_sim
+        return None, best_sim
+
+    async def _find_conflict(self, candidate: CandidateLesson) -> str | None:
+        for lesson in await self.storage.list_lessons("active"):
+            if lesson.graph:
+                conflicts = lesson.graph.get_targets(
+                    __import__(
+                        "uall_core.schemas.graph", fromlist=["GraphEdgeType"]
+                    ).GraphEdgeType.CONFLICTS_WITH
+                )
+                if candidate.reflection_id in conflicts:
+                    return lesson.lesson_id
+        return None
+
+    async def _rewrite(self, candidate: CandidateLesson) -> str:
+        prompt = f"Rewrite this fix to be actionable: {candidate.fix}"
+        response = await self.llm.complete(prompt)
+        for line in response.splitlines():
+            if "FIX:" in line.upper():
+                return line.split(":", 1)[1].strip()
+        return f"Before acting: validate. {candidate.fix}"

uall/optimization/optimizers.py

@@ -0,0 +1,59 @@
+from uall_core.ports.storage import StoragePort
+
+
+class PromptOptimizer:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+
+    async def suggest(self, agent_id: str, step: str, current_prompt: str) -> dict:
+        from uall.recommendations.engine import RecommendationEngine
+
+        recs = RecommendationEngine(self.storage)
+        recommendations = await recs.get_recommendations(agent_id=agent_id)
+        additions = [r["text"] for r in recommendations if r.get("step") == step][:3]
+        if not additions:
+            additions = [r["text"] for r in recommendations[:2]]
+        suggested = current_prompt
+        if additions:
+            suggested += "\n\n[UALL Recommendations]\n" + "\n".join(f"- {a}" for a in additions)
+        return {
+            "agent_id": agent_id,
+            "step": step,
+            "current": current_prompt,
+            "recommended": suggested,
+            "additions": additions,
+            "confidence": recommendations[0]["confidence"] if recommendations else 0.0,
+        }
+
+
+class WorkflowOptimizer:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+
+    async def analyze(self, workflow_id: str) -> dict:
+        runs = await self.storage.list_runs()
+        step_failures: dict[str, int] = {}
+        for run in runs:
+            if run.get("workflow_id") != workflow_id:
+                continue
+            for evt in run.get("events", []):
+                if evt.get("event_type") == "failure":
+                    step = evt.get("stage", {}).get("step", "unknown")
+                    step_failures[step] = step_failures.get(step, 0) + 1
+        suggestions = []
+        if step_failures:
+            worst = max(step_failures, key=step_failures.get)
+            suggestions.append(
+                {
+                    "type": "workflow_reorder",
+                    "message": f"Add validation before '{worst}' step",
+                    "high_failure_step": worst,
+                    "failure_count": step_failures[worst],
+                }
+            )
+        return {
+            "workflow_id": workflow_id,
+            "step_failures": step_failures,
+            "health": "degraded" if step_failures else "healthy",
+            "suggestions": suggestions,
+        }

uall/promotion/queue.py

@@ -0,0 +1,107 @@
+import uuid
+from datetime import datetime
+
+from uall_core.ports.storage import StoragePort
+from uall_core.schemas.lesson import CandidateLesson, PendingLesson, ValidationResult
+from uall.distillation.distiller import KnowledgeDistiller
+from uall.memory.policies import PolicyManager
+from uall.memory.provenance import attach_provenance
+
+
+class PromotionQueue:
+    def __init__(self, storage: StoragePort, distiller: KnowledgeDistiller, policies: PolicyManager):
+        self.storage = storage
+        self.distiller = distiller
+        self.policies = policies
+
+    async def enqueue(self, candidate: CandidateLesson, validation: ValidationResult) -> str:
+        pending = PendingLesson(
+            pending_id=f"pending_{uuid.uuid4().hex[:8]}",
+            candidate=candidate,
+            validation_result=validation,
+            status="pending",
+        )
+        await self.storage.save_pending(pending)
+        return pending.pending_id
+
+    async def list_pending(self, status: str = "pending") -> list[PendingLesson]:
+        return await self.storage.list_pending(status)
+
+    async def process_queue(self, limit: int = 50) -> dict:
+        pending_list = (await self.storage.list_pending("pending"))[:limit]
+        promoted: list[str] = []
+        discarded: list[str] = []
+        merged: list[str] = []
+
+        for pending in pending_list:
+            pending.status = "evaluating"
+            await self.storage.update_pending(pending)
+            result, lesson_id = await self._process_one(pending)
+            if result == "promoted" and lesson_id:
+                promoted.append(lesson_id)
+            elif result == "merged" and lesson_id:
+                merged.append(lesson_id)
+            else:
+                discarded.append(pending.pending_id)
+
+        return {
+            "promoted": promoted,
+            "discarded": discarded,
+            "merged": merged,
+            "processed": len(pending_list),
+        }
+
+    async def _process_one(self, pending: PendingLesson) -> tuple[str, str | None]:
+        validation = pending.validation_result
+        candidate = pending.candidate
+
+        if validation.action == "reject":
+            pending.status = "discarded"
+            pending.processed_at = datetime.utcnow()
+            await self.storage.update_pending(pending)
+            return "discarded", None
+
+        if validation.action == "merge" and validation.merge_target_id:
+            await self.distiller.merge_into_lesson(validation.merge_target_id, candidate)
+            pending.status = "promoted"
+            pending.processed_at = datetime.utcnow()
+            await self.storage.update_pending(pending)
+            return "merged", validation.merge_target_id
+
+        if validation.action == "rewrite" and validation.rewritten_fix:
+            candidate.fix = validation.rewritten_fix
+
+        # Shadow test: simple heuristic — fix must be actionable
+        if not await self._shadow_test(candidate):
+            pending.status = "discarded"
+            pending.processed_at = datetime.utcnow()
+            await self.storage.update_pending(pending)
+            return "discarded", None
+
+        policy_version = await self.policies.get_active_version_string()
+        lesson = await self.distiller.candidate_to_lesson(
+            candidate,
+            policy_version=policy_version,
+            validator_action=validation.action,
+        )
+        lesson.quality_score = validation.quality_score
+        attach_provenance(
+            lesson,
+            run_id=candidate.run_id,
+            reflection_id=candidate.reflection_id,
+            event_ids=candidate.event_ids,
+            policy_version=policy_version,
+            validator_action=validation.action,
+        )
+        await self.storage.save_lesson(lesson)
+        pending.status = "promoted"
+        pending.processed_at = datetime.utcnow()
+        await self.storage.update_pending(pending)
+        return "promoted", lesson.lesson_id
+
+    async def _shadow_test(self, candidate: CandidateLesson) -> bool:
+        if len(candidate.fix) < 10:
+            return False
+        if not candidate.root_cause:
+            return False
+        return True

uall/recommendations/engine.py

@@ -0,0 +1,66 @@
+from collections import Counter
+
+from uall_core.ports.storage import StoragePort
+from uall_core.schemas.lesson import MemorySearchRequest
+
+
+class RecommendationEngine:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+
+    async def get_recommendations(
+        self,
+        agent_id: str | None = None,
+        workflow_id: str | None = None,
+        context: str | None = None,
+    ) -> list[dict]:
+        lessons = await self.storage.list_lessons("active")
+        recs = []
+        for lesson in lessons:
+            if lesson.occurrence_count < 1:
+                continue
+            if lesson.confidence.overall < 0.5:
+                continue
+            if workflow_id and lesson.stage.workflow and lesson.stage.workflow != workflow_id:
+                continue
+            if agent_id and lesson.stage.agent and lesson.stage.agent != agent_id:
+                continue
+            impact = lesson.occurrence_count * lesson.confidence.overall
+            recs.append(
+                {
+                    "type": "prompt_recommendation",
+                    "lesson_id": lesson.lesson_id,
+                    "text": lesson.fix,
+                    "confidence": lesson.confidence.overall,
+                    "observed_over": lesson.occurrence_count,
+                    "estimated_impact": f"Reduce failures by ~{int(impact * 3)}%",
+                    "workflow": lesson.stage.workflow,
+                    "step": lesson.stage.step,
+                }
+            )
+        recs.sort(key=lambda x: x["confidence"] * x["observed_over"], reverse=True)
+        return recs[:10]
+
+
+class PatternDetector:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+        self.threshold = 3
+
+    async def detect_patterns(self) -> list[dict]:
+        lessons = await self.storage.list_lessons("active")
+        causes = Counter()
+        for lesson in lessons:
+            key = lesson.root_cause[:80] if lesson.root_cause else lesson.failure[:80]
+            causes[key] += lesson.occurrence_count
+        patterns = []
+        for cause, count in causes.most_common():
+            if count >= self.threshold:
+                patterns.append(
+                    {
+                        "pattern": cause,
+                        "occurrences": count,
+                        "recommendation": f"Address recurring issue: {cause}",
+                    }
+                )
+        return patterns

uall/reflection/engine.py

@@ -0,0 +1,72 @@
+import re
+import uuid
+from datetime import datetime
+
+from uall_core.ports.storage import StoragePort
+from uall_core.providers.heuristic import HeuristicLLMProvider
+from uall_core.schemas.lesson import CandidateLesson, Reflection
+
+
+class ReflectionEngine:
+    def __init__(self, storage: StoragePort, llm: HeuristicLLMProvider | None = None):
+        self.storage = storage
+        self.llm = llm or HeuristicLLMProvider()
+
+    async def reflect(self, candidate: CandidateLesson) -> Reflection:
+        prompt = (
+            f"Analyze this agent failure and produce a lesson.\n"
+            f"FAILURE: {candidate.failure}\n"
+            f"CONTEXT: {candidate.evidence_payload}\n"
+            f"Provide FAILURE, ROOT_CAUSE, FIX, CONFIDENCE."
+        )
+        response = await self.llm.complete(prompt)
+        failure, root, fix, confidence = _parse_reflection(response, candidate)
+        reflection = Reflection(
+            reflection_id=f"reflection_{uuid.uuid4().hex[:8]}",
+            failure=failure,
+            root_cause=root,
+            fix=fix,
+            confidence=confidence,
+            memory_type=candidate.memory_type,
+            run_id=candidate.run_id,
+            event_ids=candidate.event_ids,
+        )
+        await self.storage.save_reflection(reflection.model_dump(mode="json"))
+        return reflection
+
+    async def reflect_from_candidate(self, candidate: CandidateLesson) -> CandidateLesson:
+        reflection = await self.reflect(candidate)
+        return CandidateLesson(
+            reflection_id=reflection.reflection_id,
+            failure=reflection.failure,
+            root_cause=reflection.root_cause,
+            fix=reflection.fix,
+            memory_type=reflection.memory_type,
+            stage=candidate.stage,
+            namespace=candidate.namespace,
+            confidence=reflection.confidence,
+            run_id=reflection.run_id,
+            event_ids=reflection.event_ids,
+            evidence_payload=candidate.evidence_payload,
+        )
+
+
+def _parse_reflection(response: str, candidate: CandidateLesson) -> tuple[str, str, str, float]:
+    failure = candidate.failure
+    root = candidate.root_cause or "Unknown root cause"
+    fix = candidate.fix or "Add validation step"
+    confidence = 0.8
+    for line in response.splitlines():
+        upper = line.upper()
+        if "FAILURE:" in upper:
+            failure = line.split(":", 1)[1].strip()
+        elif "ROOT_CAUSE:" in upper or "ROOT CAUSE:" in upper:
+            root = line.split(":", 1)[1].strip()
+        elif "FIX:" in upper:
+            fix = line.split(":", 1)[1].strip()
+        elif "CONFIDENCE:" in upper:
+            try:
+                confidence = float(re.findall(r"[\d.]+", line)[0])
+            except (IndexError, ValueError):
+                pass
+    return failure[:300], root[:300], fix[:300], min(max(confidence, 0.0), 1.0)

uall/rollback/manager.py

@@ -0,0 +1,49 @@
+from datetime import datetime
+
+from uall_core.ports.storage import StoragePort
+from uall_core.schemas.common import VersionRecord
+
+
+class RollbackManager:
+    def __init__(self, storage: StoragePort):
+        self.storage = storage
+
+    async def save_version(
+        self, resource_type: str, resource_id: str, version: str, content: dict, promoted: bool = False
+    ) -> str:
+        record = VersionRecord(
+            resource_type=resource_type,
+            resource_id=resource_id,
+            version=version,
+            content=content,
+            promoted=promoted,
+        )
+        return await self.storage.save_version(record)
+
+    async def rollback(self, resource_type: str, resource_id: str, target_version: str) -> dict:
+        versions = await self.storage.list_versions(resource_type, resource_id)
+        target = next((v for v in versions if v.version == target_version), None)
+        if not target:
+            raise ValueError(f"Version {target_version} not found for {resource_id}")
+        for v in versions:
+            v.promoted = v.version == target_version
+            await self.storage.save_version(v)
+        return {
+            "resource_type": resource_type,
+            "resource_id": resource_id,
+            "rolled_back_to": target_version,
+            "content": target.content,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+
+    async def list_versions(self, resource_type: str, resource_id: str) -> list[VersionRecord]:
+        return await self.storage.list_versions(resource_type, resource_id)
+
+    async def auto_rollback_on_regression(
+        self, resource_type: str, resource_id: str, current_version: str, previous_version: str
+    ) -> dict | None:
+        versions = await self.storage.list_versions(resource_type, resource_id)
+        current = next((v for v in versions if v.version == current_version), None)
+        if current and current.promoted:
+            return await self.rollback(resource_type, resource_id, previous_version)
+        return None