supermemory-agent 0.2.3__py3-none-any.whl

uall_python/client.py

@@ -0,0 +1,337 @@
+"""UALL Python SDK — local and remote modes."""
+
+import os
+import sys
+import uuid
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import httpx
+
+from storage.adapters.file import get_storage
+from uall.service import UALLService
+from uall_core.schemas.events import RunEnd, RunStart, StageMetadata
+from uall_core.schemas.lesson import MemorySearchRequest
+
+
+class RunContext:
+    def __init__(self, client: "UALLClient", run_id: str, workflow_id: str, stage: StageMetadata):
+        self.client = client
+        self.run_id = run_id
+        self.workflow_id = workflow_id
+        self.stage = stage
+        self._lessons_used: list[str] = []
+
+    def record_failure(self, snippet: str, tags: list[str] | None = None, **stage_kwargs) -> dict:
+        stage = self._merge_stage(stage_kwargs)
+        return self.client._record_failure(self.run_id, snippet, stage, tags)
+
+    def record_correction(
+        self, before: str, after: str, intent: str, **stage_kwargs
+    ) -> dict:
+        stage = self._merge_stage(stage_kwargs)
+        return self.client._record_correction(self.run_id, before, after, intent, stage)
+
+    def retrieve(self, query: str = "", step: str | None = None, max_tokens: int = 800) -> list[dict]:
+        stage = StageMetadata(
+            workflow=self.workflow_id,
+            step=step or self.stage.step,
+            agent=self.stage.agent,
+            namespace=self.stage.namespace,
+            namespace_id=self.stage.namespace_id,
+        )
+        results = self.client.retrieve(
+            query=query or f"{self.workflow_id} {step or self.stage.step}",
+            workflow=self.workflow_id,
+            step=step or self.stage.step,
+            namespace=self.stage.namespace,
+            namespace_id=self.stage.namespace_id,
+            max_tokens=max_tokens,
+        )
+        for r in results:
+            lid = r.get("lesson", {}).get("lesson_id")
+            if lid:
+                self._lessons_used.append(lid)
+        return results
+
+    def report_lesson_outcome(
+        self,
+        lesson_id: str,
+        *,
+        used: bool = True,
+        accepted: bool = False,
+        improved: bool | None = None,
+        telemetry_id: str | None = None,
+    ) -> dict:
+        return self.client.record_lesson_outcome(
+            lesson_id,
+            telemetry_id=telemetry_id,
+            run_id=self.run_id,
+            used=used,
+            accepted=accepted,
+            improved=improved,
+        )
+
+    def _merge_stage(self, kwargs: dict) -> StageMetadata:
+        data = self.stage.model_dump()
+        data.update({k: v for k, v in kwargs.items() if v is not None})
+        return StageMetadata(**data)
+
+    def end(self, success: bool, metrics: dict | None = None) -> dict:
+        return self.client._end_run(self.run_id, success, self._lessons_used, metrics)
+
+
+class UALLClient:
+    """SDK supporting local (in-process) and remote (HTTP) modes."""
+
+    def __init__(
+        self,
+        storage: str = "file",
+        data_dir: str | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ):
+        self.base_url = base_url
+        self.api_key = api_key or os.environ.get("UALL_API_KEY", "dev-key-change-me")
+        self._service: UALLService | None = None
+        if not base_url:
+            os.environ.setdefault("UALL_STORAGE_BACKEND", storage)
+            if data_dir:
+                os.environ["UALL_DATA_DIR"] = data_dir
+            self._storage = get_storage(storage, data_dir)
+            self._service = UALLService(self._storage)
+            self._initialized = False
+
+    async def _ensure_init(self):
+        if self._service and not self._initialized:
+            await self._service.init()
+            self._initialized = True
+
+    def _sync_init(self):
+        import asyncio
+
+        if self._service and not getattr(self, "_initialized", False):
+            asyncio.get_event_loop().run_until_complete(self._ensure_init())
+            self._initialized = True
+
+    @contextmanager
+    def run(
+        self,
+        workflow_id: str,
+        step: str | None = None,
+        agents: list[str] | None = None,
+        namespace: str | None = None,
+    ):
+        import asyncio
+
+        run_id = f"run_{uuid.uuid4().hex[:8]}"
+        ns_level, ns_id = ("project", "default")
+        if namespace and ":" in namespace:
+            ns_level, ns_id = namespace.split(":", 1)
+        stage = StageMetadata(
+            workflow=workflow_id,
+            step=step,
+            namespace=ns_level,
+            namespace_id=ns_id,
+        )
+        start = RunStart(
+            run_id=run_id,
+            workflow_id=workflow_id,
+            agents=agents or [],
+            stage=stage,
+        )
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                loop.run_until_complete(self._service.start_run(start))
+            finally:
+                loop.close()
+        else:
+            self._http_post("/runs/start", start.model_dump(mode="json"))
+
+        ctx = RunContext(self, run_id, workflow_id, stage)
+        try:
+            yield ctx
+        finally:
+            pass
+
+    def retrieve(self, **kwargs) -> list[dict]:
+        import asyncio
+
+        req = MemorySearchRequest(
+            query=kwargs.get("query", ""),
+            workflow=kwargs.get("workflow"),
+            step=kwargs.get("step"),
+            namespace=kwargs.get("namespace"),
+            namespace_id=kwargs.get("namespace_id"),
+            max_tokens=kwargs.get("max_tokens", 800),
+            top_k=kwargs.get("top_k", 5),
+        )
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                results = loop.run_until_complete(self._service.retrieve(req))
+                return [
+                    {
+                        "lesson": r.lesson.model_dump(mode="json"),
+                        "score": r.score,
+                        "telemetry_id": r.telemetry_id,
+                    }
+                    for r in results
+                ]
+            finally:
+                loop.close()
+        return self._http_post("/memory/search", req.model_dump(mode="json"))
+
+    def get_policies(self) -> list[dict]:
+        import asyncio
+
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                policies = loop.run_until_complete(self._service.get_policies())
+                return [p.model_dump(mode="json") for p in policies]
+            finally:
+                loop.close()
+        return self._http_get("/policies")
+
+    def get_recommendations(self, **kwargs) -> list[dict]:
+        import asyncio
+
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                return loop.run_until_complete(self._service.get_recommendations(**kwargs))
+            finally:
+                loop.close()
+        return self._http_post("/recommendations", kwargs)
+
+    def record_lesson_outcome(
+        self,
+        lesson_id: str,
+        telemetry_id: str | None = None,
+        run_id: str | None = None,
+        *,
+        used: bool = False,
+        accepted: bool = False,
+        improved: bool | None = None,
+    ) -> dict:
+        import asyncio
+
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                return loop.run_until_complete(
+                    self._service.record_lesson_outcome(
+                        lesson_id, telemetry_id, run_id, used, accepted, improved
+                    )
+                )
+            finally:
+                loop.close()
+        return self._http_post(
+            "/telemetry/lesson-outcome",
+            {
+                "lesson_id": lesson_id,
+                "telemetry_id": telemetry_id,
+                "run_id": run_id,
+                "used": used,
+                "accepted": accepted,
+                "improved": improved,
+            },
+        )
+
+    def experiment(self, prompt_id: str, variant_b: str, split: float = 0.1) -> dict:
+        import asyncio
+
+        payload = {
+            "resource_type": "prompt",
+            "resource_id": prompt_id,
+            "variant_a": "current",
+            "variant_b": variant_b,
+            "traffic_split": split,
+        }
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                exp = loop.run_until_complete(self._service.start_experiment(**payload))
+                return exp.model_dump(mode="json")
+            finally:
+                loop.close()
+        return self._http_post("/experiments/start", payload)
+
+    def _record_failure(self, run_id, snippet, stage, tags) -> dict:
+        import asyncio
+        from uall_core.schemas.events import Event, EventType
+
+        event = Event(
+            event_id=f"failure_{uuid.uuid4().hex[:8]}",
+            event_type=EventType.FAILURE,
+            run_id=run_id,
+            stage=stage,
+            tags=tags or [],
+            payload={"snippet": snippet[:500]},
+        )
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                return loop.run_until_complete(self._service.record_event(event))
+            finally:
+                loop.close()
+        return self._http_post("/runs/event", event.model_dump(mode="json"))
+
+    def _record_correction(self, run_id, before, after, intent, stage) -> dict:
+        import asyncio
+        from uall_core.schemas.events import Event, EventType
+
+        event = Event(
+            event_id=f"correction_{uuid.uuid4().hex[:8]}",
+            event_type=EventType.CORRECTION,
+            run_id=run_id,
+            stage=stage,
+            payload={"before": before[:300], "after": after[:300], "intent": intent},
+        )
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                return loop.run_until_complete(self._service.record_event(event))
+            finally:
+                loop.close()
+        return self._http_post("/runs/event", event.model_dump(mode="json"))
+
+    def _end_run(self, run_id, success, lessons_used, metrics) -> dict:
+        import asyncio
+
+        data = RunEnd(run_id=run_id, success=success, lessons_used=lessons_used, metrics=metrics or {})
+        if self._service:
+            loop = asyncio.new_event_loop()
+            try:
+                loop.run_until_complete(self._ensure_init())
+                return loop.run_until_complete(self._service.end_run(data))
+            finally:
+                loop.close()
+        return self._http_post("/runs/end", data.model_dump(mode="json"))
+
+    def _http_post(self, path: str, data: dict) -> Any:
+        with httpx.Client(base_url=self.base_url, headers={"X-UALL-Key": self.api_key}) as c:
+            r = c.post(path, json=data)
+            r.raise_for_status()
+            return r.json()
+
+    def _http_get(self, path: str) -> Any:
+        with httpx.Client(base_url=self.base_url, headers={"X-UALL-Key": self.api_key}) as c:
+            r = c.get(path)
+            r.raise_for_status()
+            return r.json()

uall_server/main.py

@@ -0,0 +1,284 @@
+import os
+import sys
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+# Ensure project root is on path for storage adapters
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from fastapi import Depends, FastAPI, Header, HTTPException
+from pydantic import BaseModel, Field
+
+from storage.adapters.file import get_storage
+from uall.service import UALLService
+from uall_core.schemas.common import PolicyVersion, Skill
+from uall_core.schemas.events import Event, Feedback, RunEnd, RunStart
+from uall_core.schemas.lesson import CandidateLesson, Lesson, MemorySearchRequest
+
+API_KEY = os.environ.get("UALL_API_KEY", "dev-key-change-me")
+service: UALLService | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global service
+    storage = get_storage()
+    service = UALLService(storage)
+    await service.init()
+    yield
+
+
+app = FastAPI(title="UALL — Universal Agent Learning Layer", version="0.1.0", lifespan=lifespan)
+
+
+def verify_key(x_uall_key: str = Header(default="")):
+    if x_uall_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+    return x_uall_key
+
+
+def get_service() -> UALLService:
+    assert service is not None
+    return service
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "service": "uall"}
+
+
+# --- Runs ---
+@app.post("/runs/start", dependencies=[Depends(verify_key)])
+async def runs_start(data: RunStart, svc: UALLService = Depends(get_service)):
+    return await svc.start_run(data)
+
+
+@app.post("/runs/event", dependencies=[Depends(verify_key)])
+async def runs_event(event: Event, svc: UALLService = Depends(get_service)):
+    return await svc.record_event(event)
+
+
+@app.post("/runs/end", dependencies=[Depends(verify_key)])
+async def runs_end(data: RunEnd, svc: UALLService = Depends(get_service)):
+    return await svc.end_run(data)
+
+
+@app.post("/feedback", dependencies=[Depends(verify_key)])
+async def feedback(data: Feedback, svc: UALLService = Depends(get_service)):
+    return await svc.record_feedback(data)
+
+
+# --- Reflection & validation ---
+class ReflectRequest(BaseModel):
+    candidate: CandidateLesson
+
+
+@app.post("/reflection", dependencies=[Depends(verify_key)])
+async def reflection(req: ReflectRequest, svc: UALLService = Depends(get_service)):
+    return await svc.reflect_and_queue(req.candidate)
+
+
+@app.post("/memory/validate", dependencies=[Depends(verify_key)])
+async def memory_validate(req: ReflectRequest, svc: UALLService = Depends(get_service)):
+    result = await svc.validate_lesson(req.candidate)
+    return result.model_dump(mode="json")
+
+
+@app.post("/memory/store", dependencies=[Depends(verify_key)])
+async def memory_store(lesson: Lesson, svc: UALLService = Depends(get_service)):
+    lid = await svc.store_lesson(lesson)
+    return {"lesson_id": lid}
+
+
+@app.post("/memory/search", dependencies=[Depends(verify_key)])
+async def memory_search(req: MemorySearchRequest, svc: UALLService = Depends(get_service)):
+    results = await svc.retrieve(req)
+    return [
+        {
+            "lesson": r.lesson.model_dump(mode="json"),
+            "score": r.score,
+            "telemetry_id": r.telemetry_id,
+        }
+        for r in results
+    ]
+
+
+@app.get("/memory/{lesson_id}/provenance", dependencies=[Depends(verify_key)])
+async def memory_provenance(lesson_id: str, svc: UALLService = Depends(get_service)):
+    prov = await svc.get_provenance(lesson_id)
+    if not prov:
+        raise HTTPException(404, "Lesson not found")
+    return prov
+
+
+@app.get("/memory/{lesson_id}/graph", dependencies=[Depends(verify_key)])
+async def memory_graph(lesson_id: str, svc: UALLService = Depends(get_service)):
+    graph = await svc.get_graph(lesson_id)
+    if not graph:
+        raise HTTPException(404, "Lesson not found")
+    return graph
+
+
+@app.post("/memory/prune", dependencies=[Depends(verify_key)])
+async def memory_prune(svc: UALLService = Depends(get_service)):
+    return await svc.prune_memory()
+
+
+# --- Promotion ---
+@app.get("/promotion/pending", dependencies=[Depends(verify_key)])
+async def promotion_pending(svc: UALLService = Depends(get_service)):
+    return await svc.list_pending()
+
+
+@app.post("/promotion/process", dependencies=[Depends(verify_key)])
+async def promotion_process(svc: UALLService = Depends(get_service)):
+    return await svc.process_promotion_queue()
+
+
+# --- Telemetry ---
+class TelemetryRequest(BaseModel):
+    lesson_id: str
+    telemetry_id: str | None = None
+    run_id: str | None = None
+    used: bool = False
+    accepted: bool = False
+    improved: bool | None = None
+
+
+@app.post("/telemetry/lesson-outcome", dependencies=[Depends(verify_key)])
+async def telemetry_outcome(req: TelemetryRequest, svc: UALLService = Depends(get_service)):
+    return await svc.record_lesson_outcome(
+        req.lesson_id, req.telemetry_id, req.run_id, req.used, req.accepted, req.improved
+    )
+
+
+# --- Policies ---
+@app.get("/policies", dependencies=[Depends(verify_key)])
+async def get_policies(svc: UALLService = Depends(get_service)):
+    policies = await svc.get_policies()
+    return [p.model_dump(mode="json") for p in policies]
+
+
+@app.post("/policies", dependencies=[Depends(verify_key)])
+async def create_policy(policy: PolicyVersion, svc: UALLService = Depends(get_service)):
+    pid = await svc.create_policy(policy)
+    return {"policy_id": pid}
+
+
+@app.get("/policies/versions", dependencies=[Depends(verify_key)])
+async def policy_versions(policy_id: str, svc: UALLService = Depends(get_service)):
+    versions = await svc.list_policy_versions(policy_id)
+    return [v.model_dump(mode="json") for v in versions]
+
+
+# --- Evaluation & analytics ---
+@app.post("/evaluate", dependencies=[Depends(verify_key)])
+async def evaluate(run_id: str, svc: UALLService = Depends(get_service)):
+    return await svc.evaluate(run_id)
+
+
+@app.get("/agent-score", dependencies=[Depends(verify_key)])
+async def agent_score(agent_id: str | None = None, svc: UALLService = Depends(get_service)):
+    return await svc.agent_score(agent_id)
+
+
+@app.get("/analytics", dependencies=[Depends(verify_key)])
+async def analytics(svc: UALLService = Depends(get_service)):
+    return await svc.get_analytics()
+
+
+@app.get("/workflow-health", dependencies=[Depends(verify_key)])
+async def workflow_health(workflow_id: str, svc: UALLService = Depends(get_service)):
+    return await svc.workflow_health(workflow_id)
+
+
+@app.get("/top-failures", dependencies=[Depends(verify_key)])
+async def top_failures(svc: UALLService = Depends(get_service)):
+    return await svc.top_failures()
+
+
+# --- Recommendations ---
+class RecommendationRequest(BaseModel):
+    agent_id: str | None = None
+    workflow_id: str | None = None
+    context: str | None = None
+
+
+@app.post("/recommendations", dependencies=[Depends(verify_key)])
+async def recommendations(req: RecommendationRequest, svc: UALLService = Depends(get_service)):
+    return await svc.get_recommendations(
+        agent_id=req.agent_id, workflow_id=req.workflow_id, context=req.context
+    )
+
+
+@app.post("/recommendations/patterns", dependencies=[Depends(verify_key)])
+async def recommendation_patterns(svc: UALLService = Depends(get_service)):
+    return await svc.detect_patterns()
+
+
+# --- Experiments ---
+class ExperimentStartRequest(BaseModel):
+    resource_type: str
+    resource_id: str
+    variant_a: str
+    variant_b: str
+    traffic_split: float = 0.1
+
+
+@app.post("/experiments/start", dependencies=[Depends(verify_key)])
+async def experiments_start(req: ExperimentStartRequest, svc: UALLService = Depends(get_service)):
+    exp = await svc.start_experiment(**req.model_dump())
+    return exp.model_dump(mode="json")
+
+
+@app.post("/experiments/end", dependencies=[Depends(verify_key)])
+async def experiments_end(experiment_id: str, svc: UALLService = Depends(get_service)):
+    exp = await svc.end_experiment(experiment_id)
+    return exp.model_dump(mode="json")
+
+
+@app.get("/experiments/{experiment_id}/results", dependencies=[Depends(verify_key)])
+async def experiment_results(experiment_id: str, svc: UALLService = Depends(get_service)):
+    exp = await svc.experiment_results(experiment_id)
+    if not exp:
+        raise HTTPException(404, "Experiment not found")
+    return exp.model_dump(mode="json")
+
+
+# --- Rollback ---
+class RollbackRequest(BaseModel):
+    resource_type: str
+    resource_id: str
+    target_version: str
+
+
+@app.post("/rollback", dependencies=[Depends(verify_key)])
+async def rollback(req: RollbackRequest, svc: UALLService = Depends(get_service)):
+    return await svc.rollback_resource(req.resource_type, req.resource_id, req.target_version)
+
+
+@app.get("/versions/{resource_type}/{resource_id}", dependencies=[Depends(verify_key)])
+async def versions(resource_type: str, resource_id: str, svc: UALLService = Depends(get_service)):
+    records = await svc.list_versions(resource_type, resource_id)
+    return [r.model_dump(mode="json") for r in records]
+
+
+# --- Skills ---
+@app.post("/skills", dependencies=[Depends(verify_key)])
+async def create_skill(skill: Skill, svc: UALLService = Depends(get_service)):
+    sid = await svc.create_skill(skill)
+    return {"skill_id": sid}
+
+
+@app.get("/skills/search", dependencies=[Depends(verify_key)])
+async def search_skills(query: str, svc: UALLService = Depends(get_service)):
+    skills = await svc.search_skills(query)
+    return [s.model_dump(mode="json") for s in skills]
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run("uall_server.main:app", host="0.0.0.0", port=8000, reload=False)