supermemory-agent 0.2.3__py3-none-any.whl

uall_core/ports/storage.py

@@ -0,0 +1,71 @@
+from typing import Any, Protocol
+
+from uall_core.schemas.common import (
+    Experiment,
+    PolicyVersion,
+    RetrievalTelemetryEvent,
+    Skill,
+    VersionRecord,
+)
+from uall_core.schemas.events import Event, Feedback, RunEnd, RunStart
+from uall_core.schemas.lesson import Lesson, MemorySearchRequest, PendingLesson
+
+
+class StoragePort(Protocol):
+    """Pluggable storage interface for all UALL tiers."""
+
+    async def init(self) -> None: ...
+
+    # Runs & events
+    async def save_run_start(self, run: RunStart) -> None: ...
+    async def save_run_end(self, run: RunEnd) -> None: ...
+    async def save_event(self, event: Event) -> None: ...
+    async def get_event(self, event_id: str) -> dict[str, Any] | None: ...
+    async def save_feedback(self, feedback: Feedback) -> str: ...
+    async def get_run(self, run_id: str) -> dict[str, Any] | None: ...
+    async def list_runs(self) -> list[dict[str, Any]]: ...
+
+    # Lessons & memory
+    async def save_lesson(self, lesson: Lesson) -> str: ...
+    async def get_lesson(self, lesson_id: str) -> Lesson | None: ...
+    async def list_lessons(self, status: str = "active") -> list[Lesson]: ...
+    async def update_lesson(self, lesson: Lesson) -> None: ...
+    async def delete_lesson(self, lesson_id: str) -> None: ...
+    async def search_lessons(self, request: MemorySearchRequest) -> list[Lesson]: ...
+
+    # Pending promotion queue
+    async def save_pending(self, pending: PendingLesson) -> str: ...
+    async def get_pending(self, pending_id: str) -> PendingLesson | None: ...
+    async def list_pending(self, status: str = "pending") -> list[PendingLesson]: ...
+    async def update_pending(self, pending: PendingLesson) -> None: ...
+
+    # Policies
+    async def save_policy(self, policy: PolicyVersion) -> str: ...
+    async def get_active_policies(self) -> list[PolicyVersion]: ...
+    async def list_policy_versions(self, policy_id: str) -> list[PolicyVersion]: ...
+
+    # Skills
+    async def save_skill(self, skill: Skill) -> str: ...
+    async def get_skill(self, skill_id: str) -> Skill | None: ...
+    async def search_skills(self, query: str) -> list[Skill]: ...
+
+    # Telemetry
+    async def save_telemetry(self, event: RetrievalTelemetryEvent) -> str: ...
+    async def list_telemetry(self, lesson_id: str | None = None) -> list[RetrievalTelemetryEvent]: ...
+
+    # Experiments
+    async def save_experiment(self, experiment: Experiment) -> str: ...
+    async def get_experiment(self, experiment_id: str) -> Experiment | None: ...
+    async def update_experiment(self, experiment: Experiment) -> None: ...
+
+    # Versions (rollback)
+    async def save_version(self, record: VersionRecord) -> str: ...
+    async def list_versions(self, resource_type: str, resource_id: str) -> list[VersionRecord]: ...
+
+    # Reflections
+    async def save_reflection(self, data: dict[str, Any]) -> str: ...
+    async def get_reflection(self, reflection_id: str) -> dict[str, Any] | None: ...
+
+    # Metrics / analytics raw
+    async def save_metrics(self, name: str, data: dict[str, Any]) -> None: ...
+    async def get_metrics(self, name: str) -> dict[str, Any] | None: ...

uall_core/providers/heuristic.py

@@ -0,0 +1,58 @@
+"""Heuristic LLM provider — zero API keys required for local dev."""
+
+import hashlib
+import math
+import re
+
+
+class HeuristicLLMProvider:
+    async def complete(self, prompt: str, max_tokens: int = 500) -> str:
+        text = prompt.lower()
+        failure = _extract_field(prompt, "failure") or "unknown failure"
+        root = _extract_field(prompt, "root cause") or _infer_root(failure)
+        fix = _extract_field(prompt, "fix") or _infer_fix(failure, root)
+        return f"FAILURE: {failure}\nROOT_CAUSE: {root}\nFIX: {fix}\nCONFIDENCE: 0.85"
+
+    async def embed(self, text: str) -> list[float]:
+        tokens = re.findall(r"\w+", text.lower())
+        vec = [0.0] * 128
+        for tok in tokens:
+            h = int(hashlib.md5(tok.encode()).hexdigest(), 16)
+            for i in range(128):
+                vec[i] += math.sin(h * (i + 1) * 0.001)
+        norm = math.sqrt(sum(x * x for x in vec)) or 1.0
+        return [x / norm for x in vec]
+
+
+def _extract_field(prompt: str, label: str) -> str | None:
+    for line in prompt.splitlines():
+        if label.lower() in line.lower() and ":" in line:
+            return line.split(":", 1)[1].strip()[:200]
+    return None
+
+
+def _infer_root(failure: str) -> str:
+    if "ocr" in failure.lower():
+        return "Routing logic did not inspect PDF text layer before choosing OCR"
+    if "sql" in failure.lower() or "join" in failure.lower():
+        return "Schema relationships were not verified before generating SQL"
+    return "Insufficient validation before action"
+
+
+def _infer_fix(failure: str, root: str) -> str:
+    if "ocr" in failure.lower() or "pdf" in failure.lower():
+        return "Inspect PDF text layer first; use OCR only for scanned documents"
+    if "sql" in failure.lower():
+        return "Inspect foreign keys and schema before generating joins"
+    return f"Add validation step to prevent: {root[:80]}"
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)

uall_core/providers/llm.py

@@ -0,0 +1,6 @@
+from typing import Protocol
+
+
+class LLMProvider(Protocol):
+    async def complete(self, prompt: str, max_tokens: int = 500) -> str: ...
+    async def embed(self, text: str) -> list[float]: ...

uall_core/schemas/common.py

@@ -0,0 +1,73 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PolicyVersion(BaseModel):
+    policy_id: str
+    version: str
+    effective_at: datetime = Field(default_factory=datetime.utcnow)
+    rules: list[str] = Field(default_factory=list)
+    priority: int = 100
+
+
+class Skill(BaseModel):
+    skill_id: str
+    name: str
+    version: str = "1.0.0"
+    description: str = ""
+    steps: list[str] = Field(default_factory=list)
+    lesson_ids: list[str] = Field(default_factory=list)
+    tool_bindings: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class ExperimentMetrics(BaseModel):
+    success_rate: float = 0.0
+    retry_count: float = 0.0
+    cost: float = 0.0
+    correction_rate: float = 0.0
+    latency_p50: float = 0.0
+    latency_p95: float = 0.0
+    token_usage: float = 0.0
+    human_approval_rate: float = 0.0
+    rollback_frequency: float = 0.0
+    downstream_failure_rate: float = 0.0
+    sample_size: int = 0
+
+
+class Experiment(BaseModel):
+    experiment_id: str
+    resource_type: str  # prompt, workflow
+    resource_id: str
+    variant_a: str
+    variant_b: str
+    traffic_split: float = 0.1
+    status: str = "running"  # running, concluded, rolled_back
+    metrics_a: ExperimentMetrics = Field(default_factory=ExperimentMetrics)
+    metrics_b: ExperimentMetrics = Field(default_factory=ExperimentMetrics)
+    winner: str | None = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    concluded_at: datetime | None = None
+
+
+class RetrievalTelemetryEvent(BaseModel):
+    telemetry_id: str
+    lesson_id: str
+    run_id: str | None = None
+    retrieved: bool = True
+    used: bool = False
+    accepted: bool = False
+    outcome_improved: bool | None = None
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+
+class VersionRecord(BaseModel):
+    resource_type: str
+    resource_id: str
+    version: str
+    content: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    promoted: bool = False

uall_core/schemas/events.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+MAX_PAYLOAD_BYTES = 2048
+
+
+class EventType(str, Enum):
+    WORKFLOW_START = "workflow_start"
+    WORKFLOW_STEP = "workflow_step"
+    WORKFLOW_END = "workflow_end"
+    FAILURE = "failure"
+    CORRECTION = "correction"
+    SUGGESTION = "suggestion"
+    TOOL_OUTCOME = "tool_outcome"
+
+
+class StageMetadata(BaseModel):
+    workflow: str | None = None
+    step: str | None = None
+    tool: str | None = None
+    agent: str | None = None
+    domain: str | None = None
+    language: str | None = None
+    environment: str | None = None
+    namespace: str | None = None
+    namespace_id: str | None = None
+
+
+class Event(BaseModel):
+    event_id: str
+    event_type: EventType
+    run_id: str
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    stage: StageMetadata = Field(default_factory=StageMetadata)
+    tags: list[str] = Field(default_factory=list)
+    payload: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("payload")
+    @classmethod
+    def validate_payload_size(cls, v: dict) -> dict:
+        import json
+
+        if len(json.dumps(v, default=str)) > MAX_PAYLOAD_BYTES:
+            raise ValueError(f"Payload exceeds {MAX_PAYLOAD_BYTES} bytes")
+        return v
+
+
+class RunStart(BaseModel):
+    run_id: str
+    workflow_id: str
+    agents: list[str] = Field(default_factory=list)
+    workflow_graph: dict[str, Any] = Field(default_factory=dict)
+    stage: StageMetadata = Field(default_factory=StageMetadata)
+
+
+class RunEnd(BaseModel):
+    run_id: str
+    success: bool
+    metrics: dict[str, Any] = Field(default_factory=dict)
+    lessons_used: list[str] = Field(default_factory=list)
+    score: float | None = None
+
+
+class Feedback(BaseModel):
+    run_id: str | None = None
+    lesson_id: str | None = None
+    rating: str  # positive, negative, correction
+    comment: str | None = None
+    correction_before: str | None = None
+    correction_after: str | None = None
+    intent: str | None = None

uall_core/schemas/graph.py

@@ -0,0 +1,32 @@
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class GraphEdgeType(str, Enum):
+    CAUSED_BY = "caused_by"
+    FIXED_BY = "fixed_by"
+    SUPERSEDES = "supersedes"
+    RELATED_TO = "related_to"
+    DEPENDS_ON = "depends_on"
+    CONFLICTS_WITH = "conflicts_with"
+    DERIVED_FROM = "derived_from"
+    GENERALIZES = "generalizes"
+    SPECIALIZES = "specializes"
+
+
+class GraphEdge(BaseModel):
+    edge_type: GraphEdgeType
+    target_id: str
+
+
+class KnowledgeGraph(BaseModel):
+    lesson_id: str
+    edges: list[GraphEdge] = Field(default_factory=list)
+
+    def get_targets(self, edge_type: GraphEdgeType) -> list[str]:
+        return [e.target_id for e in self.edges if e.edge_type == edge_type]
+
+    def add_edge(self, edge_type: GraphEdgeType, target_id: str) -> None:
+        if not any(e.edge_type == edge_type and e.target_id == target_id for e in self.edges):
+            self.edges.append(GraphEdge(edge_type=edge_type, target_id=target_id))

uall_core/schemas/lesson.py

@@ -0,0 +1,109 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from uall_core.schemas.events import StageMetadata
+from uall_core.schemas.graph import KnowledgeGraph
+from uall_core.schemas.namespace import (
+    ConfidenceDimensions,
+    FreshnessMetrics,
+    MemoryType,
+    NamespaceRef,
+    Provenance,
+    TTLConfig,
+)
+
+
+class Reflection(BaseModel):
+    reflection_id: str
+    failure: str
+    root_cause: str
+    fix: str
+    confidence: float = 0.8
+    memory_type: MemoryType = MemoryType.FAILURE
+    run_id: str | None = None
+    event_ids: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class Lesson(BaseModel):
+    lesson_id: str
+    failure: str = ""
+    root_cause: str = ""
+    fix: str = ""
+    memory_type: MemoryType = MemoryType.FAILURE
+    stage: StageMetadata = Field(default_factory=StageMetadata)
+    namespace: NamespaceRef = Field(default_factory=NamespaceRef)
+    confidence: ConfidenceDimensions = Field(default_factory=ConfidenceDimensions)
+    freshness: FreshnessMetrics = Field(default_factory=FreshnessMetrics)
+    ttl: TTLConfig = Field(default_factory=TTLConfig)
+    provenance: Provenance = Field(default_factory=Provenance)
+    graph: KnowledgeGraph | None = None
+    occurrence_count: int = 1
+    quality_score: float = 0.5
+    embedding: list[float] | None = None
+    status: str = "active"  # active, archived, pending_revalidation
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_search_text(self) -> str:
+        return f"{self.failure} {self.root_cause} {self.fix}"
+
+
+class CandidateLesson(BaseModel):
+    """Pre-validation lesson from reflection/distillation."""
+    reflection_id: str
+    failure: str
+    root_cause: str
+    fix: str
+    memory_type: MemoryType = MemoryType.FAILURE
+    stage: StageMetadata = Field(default_factory=StageMetadata)
+    namespace: NamespaceRef = Field(default_factory=NamespaceRef)
+    confidence: float = 0.8
+    run_id: str | None = None
+    event_ids: list[str] = Field(default_factory=list)
+    evidence_payload: dict = Field(default_factory=dict)
+
+
+class MemorySearchRequest(BaseModel):
+    query: str
+    workflow: str | None = None
+    step: str | None = None
+    tool: str | None = None
+    agent: str | None = None
+    domain: str | None = None
+    namespace: str | None = None
+    namespace_id: str | None = None
+    max_tokens: int = 800
+    top_k: int = 5
+
+
+class MemorySearchResult(BaseModel):
+    lesson: Lesson
+    score: float
+    telemetry_id: str | None = None
+
+
+class ValidatorAction(str):
+    REJECT = "reject"
+    MERGE = "merge"
+    REWRITE = "rewrite"
+    APPROVE = "approve"
+
+
+class ValidationResult(BaseModel):
+    action: str
+    candidate: CandidateLesson
+    quality_score: float = 0.0
+    merge_target_id: str | None = None
+    rewritten_fix: str | None = None
+    reason: str = ""
+
+
+class PendingLesson(BaseModel):
+    pending_id: str
+    candidate: CandidateLesson
+    validation_result: ValidationResult
+    status: str = "pending"  # pending, evaluating, promoted, discarded
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    processed_at: datetime | None = None

uall_core/schemas/namespace.py

@@ -0,0 +1,76 @@
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class MemoryType(str, Enum):
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+    USER = "user"
+    ORGANIZATIONAL = "organizational"
+    FAILURE = "failure"
+    TOOL = "tool"
+
+
+class NamespaceLevel(str, Enum):
+    GLOBAL = "global"
+    ORGANIZATION = "organization"
+    TEAM = "team"
+    PROJECT = "project"
+    USER = "user"
+    SESSION = "session"
+
+
+NAMESPACE_PRIORITY = [
+    NamespaceLevel.ORGANIZATION,
+    NamespaceLevel.TEAM,
+    NamespaceLevel.PROJECT,
+    NamespaceLevel.USER,
+    NamespaceLevel.SESSION,
+    NamespaceLevel.GLOBAL,
+]
+
+
+class NamespaceRef(BaseModel):
+    level: NamespaceLevel = NamespaceLevel.PROJECT
+    namespace_id: str = "default"
+
+
+class ConfidenceDimensions(BaseModel):
+    evidence: float = 0.5
+    retrieval_success: float = 0.5
+    human_verified: bool = False
+    overall: float = 0.5
+
+    def recalculate_overall(self) -> float:
+        bonus = 1.0 if self.human_verified else 0.0
+        self.overall = round(
+            0.4 * self.evidence + 0.4 * self.retrieval_success + 0.2 * bonus, 4
+        )
+        return self.overall
+
+
+class TTLConfig(BaseModel):
+    expires_at: datetime | None = None
+    auto_revalidate_after_days: int | None = None
+
+
+class FreshnessMetrics(BaseModel):
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    last_used: datetime | None = None
+    last_confirmed: datetime | None = None
+    usage_count: int = 0
+    success_after_use: int = 0
+    failure_after_use: int = 0
+    staleness_score: float = 0.0
+
+
+class Provenance(BaseModel):
+    run_id: str | None = None
+    reflection_id: str | None = None
+    event_ids: list[str] = Field(default_factory=list)
+    policy_version: str | None = None
+    validator_action: str | None = None
+    promoted_at: datetime | None = None

uall_python/__init__.py

@@ -0,0 +1,3 @@
+from uall_python.client import UALLClient, RunContext
+
+__all__ = ["UALLClient", "RunContext"]