ouroboros-memory 1.0.0__py3-none-any.whl

ouroboros/__init__.py

@@ -0,0 +1,36 @@
+"""Ouroboros: lifelong private memory for large language models.
+
+This package is the public entry point. The heavy lifting is done by
+submodules; importing :mod:`ouroboros` is cheap and side-effect free.
+
+    >>> from ouroboros import OuroborosMind, MindConfig
+    >>> mind = OuroborosMind()
+    >>> reply = mind.chat("My name is Tony. I like dark mode.")
+    >>> reply
+    'Noted, Tony. I have crystallized your preference for dark mode.'
+
+The full system architecture is documented in ``docs/architecture.md``.
+"""
+
+from ouroboros.config.schema import MindConfig, PrivacyConfig
+from ouroboros.mind import OuroborosMind
+from ouroboros.version import __version__
+
+__all__ = [
+    "MindConfig",
+    "OuroborosMind",
+    "PrivacyConfig",
+    "__version__",
+]
+
+
+def main() -> None:  # pragma: no cover - CLI entry point
+    """Lazy entry point for ``python -m ouroboros``.
+
+    The CLI module is imported lazily to keep ``import ouroboros``
+    cheap and to avoid forcing the optional Typer/Rich stack to be
+    installed in every environment that just wants the core engine.
+    """
+    from ouroboros.cli.main import app
+
+    app()

ouroboros/__main__.py

@@ -0,0 +1,27 @@
+"""Allow ``python -m ouroboros`` to launch the CLI.
+
+The actual CLI implementation lives in :mod:`ouroboros.cli.main` and
+is imported lazily so the package is usable in environments where
+Typer / Rich are not installed.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:  # pragma: no cover - CLI entry point
+    """Entry point for ``python -m ouroboros``."""
+    try:
+        from ouroboros.cli.main import app
+    except ImportError as exc:
+        sys.stderr.write(
+            f"ouroboros: the CLI module is not available ({exc}).\n"
+            "Install the optional CLI dependencies to use the command line.\n"
+        )
+        sys.exit(1)
+    app()
+
+
+if __name__ == "__main__":
+    main()

ouroboros/api/__init__.py

@@ -0,0 +1,11 @@
+"""FastAPI server and WebSocket streaming for the Ouroboros HTTP API.
+
+Use :func:`create_app` to build a :class:`fastapi.FastAPI` instance
+and mount it on any ASGI server (uvicorn, hypercorn, ...).
+"""
+
+from __future__ import annotations
+
+from ouroboros.api.server import ChatRequest, ChatResponse, RestoreRequest, create_app
+
+__all__ = ["ChatRequest", "ChatResponse", "RestoreRequest", "create_app"]

ouroboros/api/middleware/__init__.py

@@ -0,0 +1,4 @@
+"""HTTP middleware: CORS, auth, logging, error handling.
+
+The middleware modules are implemented in Phase 6.
+"""

ouroboros/api/routes/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API route modules.
+
+The route modules (``chat``, ``config``, ``memory``, ...) are
+implemented in Phase 6. This package marker is empty for now.
+"""

ouroboros/api/server.py

@@ -0,0 +1,553 @@
+"""FastAPI server exposing the Ouroboros mind over HTTP.
+
+The server exposes a REST surface and a WebSocket endpoint for
+streaming chat. It is created via :func:`create_app` so tests can
+mount the app on :class:`fastapi.testclient.TestClient` without having
+to bind a real port.
+
+REST endpoints
+--------------
+
+- ``GET  /health``                          - liveness probe.
+- ``GET  /version``                         - installed version.
+- ``GET  /config``                          - resolved :class:`MindConfig`.
+- ``POST /config``                          - update a dotted key in memory.
+- ``GET  /llm``                             - current LLM provider info.
+- ``GET  /llm/models``                      - list models known to the provider.
+- ``POST /llm/switch``                      - swap the active LLM at runtime.
+- ``GET  /llm/ping``                        - liveness probe of the daemon.
+- ``POST /chat``                            - one-shot chat.
+- ``WS   /ws/chat``                         - streaming chat.
+- ``GET  /inspect``                         - status snapshot.
+- ``POST /dream``                           - run a single dream pass.
+- ``GET  /memory/concepts``                 - paginated concept summaries.
+- ``GET  /memory/facts``                    - paginated raw facts.
+- ``POST /memory/search``                   - top-K relevant concepts.
+- ``GET  /memory/narrative``                - recent narrative log.
+- ``POST /memory/clear``                    - reset the in-memory mind.
+- ``POST /backup``                          - download a JSON snapshot.
+- ``POST /restore``                         - restore from a JSON snapshot.
+
+The application also serves the built Svelte GUI from
+``src/ouroboros/gui/dist`` when present.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, ConfigDict, Field
+
+from ouroboros import __version__
+from ouroboros.config import load_config, save_config
+from ouroboros.mind import OuroborosMind
+from ouroboros.storage import StorageManager
+
+# ----------------------------------------------------------------------
+# Request / response models
+# ----------------------------------------------------------------------
+
+
+class ChatRequest(BaseModel):
+    """Body for :http:post:`/chat`.
+
+    The documented contract uses ``message``; ``text`` is also
+    accepted for backwards compatibility with earlier clients.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    message: str | None = Field(default=None, min_length=1, max_length=8192)
+    text: str | None = Field(default=None, min_length=1, max_length=8192)
+
+
+class ChatResponse(BaseModel):
+    """Body returned by :http:post:`/chat`.
+
+    Mirrors the documented contract in ``docs/user_guide.md`` §7.2:
+    a top-level ``reply`` field and a few provenance fields.
+    """
+
+    text: str
+    reply: str
+    context: list[str] = Field(default_factory=list)
+    facts_learned: int = 0
+    status: dict[str, Any] = Field(default_factory=dict)
+
+
+class RestoreRequest(BaseModel):
+    """Body for :http:post:`/restore`."""
+
+    payload: dict[str, Any]
+
+
+class LLMSwitchRequest(BaseModel):
+    """Body for :http:post:`/llm/switch`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str = Field(..., min_length=1, max_length=64)
+    model: str = Field(default="", max_length=256)
+    base_url: str = Field(default="", max_length=512)
+    api_key: str = Field(default="", max_length=512)
+    timeout: float = Field(default=60.0, gt=0.0, le=600.0)
+
+
+class MemorySearchRequest(BaseModel):
+    """Body for :http:post:`/memory/search`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    query: str = Field(..., min_length=1, max_length=1024)
+    k: int = Field(default=8, ge=1, le=64)
+
+
+class ConfigUpdateRequest(BaseModel):
+    """Body for :http:post:`/config`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    key: str = Field(..., min_length=1, max_length=128)
+    value: str = Field(..., max_length=4096)
+
+
+# ----------------------------------------------------------------------
+# App factory
+# ----------------------------------------------------------------------
+
+
+_GUI_DIST = Path(__file__).resolve().parent.parent / "gui" / "dist"
+
+
+def _storage_path() -> Path:
+    cfg = load_config()
+    return Path(str(cfg.memory.persistence_path)).expanduser() / "mind.json"
+
+
+def _build_mind(load_from_disk: bool = True) -> OuroborosMind:
+    """Construct a :class:`OuroborosMind` wired to the configured LLM.
+
+    Parameters
+    ----------
+    load_from_disk:
+        When ``True`` (the default) any persisted state at the
+        configured storage path is loaded into the mind before it is
+        returned.  Tests set this to ``False`` to keep state isolated.
+    """
+    from ouroboros.llm import get_provider
+
+    cfg = load_config()
+    path = _storage_path()
+    manager = StorageManager(path=path)
+    mind: OuroborosMind
+    try:
+        provider_kwargs: dict[str, Any] = {
+            "model": cfg.llm.model,
+            "timeout": cfg.llm.timeout,
+        }
+        kind = cfg.llm.provider.value
+        if kind in ("ollama", "ollama-cloud", "local-ollama"):
+            provider_kwargs["host"] = cfg.llm.base_url
+        elif kind in ("openai", "gpt"):
+            provider_kwargs["base_url"] = cfg.llm.base_url
+            if cfg.llm.api_key:
+                provider_kwargs["api_key"] = cfg.llm.api_key
+        elif kind in ("vllm",):
+            provider_kwargs["base_url"] = cfg.llm.base_url
+        elif kind in ("anthropic", "claude", "gemini", "google"):
+            if cfg.llm.api_key:
+                provider_kwargs["api_key"] = cfg.llm.api_key
+        provider = get_provider(kind, **provider_kwargs)
+        mind = OuroborosMind(provider=provider)
+    except Exception:
+        mind = OuroborosMind()
+    # Apply privacy configuration.
+    if cfg.privacy.forbid_cloud or cfg.privacy.level.value == "MAXIMUM":
+        mind.set_privacy(cfg.privacy)
+    if load_from_disk and manager.exists():
+        payload = manager.load()
+        if payload is not None:
+            mind.load_state(payload)
+    return mind
+
+
+def _save_mind(mind: OuroborosMind) -> None:
+    path = _storage_path()
+    manager = StorageManager(path=path)
+    manager.save_mind(mind)
+
+
+def _set_dotted(d: dict[str, Any], dotted: str, value: str) -> bool:
+    """Set ``d['a']['b'] = coerced(value)`` for a dotted key path."""
+    parts = dotted.split(".")
+    cur: Any = d
+    for part in parts[:-1]:
+        if part not in cur or not isinstance(cur[part], dict):
+            cur[part] = {}
+        cur = cur[part]
+    last = parts[-1]
+    coerced: Any = value
+    if value.lower() in ("true", "false"):
+        coerced = value.lower() == "true"
+    else:
+        try:
+            coerced = int(value)
+        except ValueError:
+            try:
+                coerced = float(value)
+            except ValueError:
+                pass
+    cur[last] = coerced
+    return True
+
+
+def _llm_list_models(mind: OuroborosMind) -> list[str]:
+    """Return a list of model names available for the active provider."""
+    provider = mind._provider  # type: ignore[attr-defined]
+    if provider is None:
+        return []
+    list_fn = getattr(provider, "list_models", None)
+    if callable(list_fn):
+        try:
+            models = list_fn()
+        except Exception:
+            return []
+        return [str(m) for m in models if m]
+    return [str(getattr(provider, "model", ""))] if getattr(
+        provider, "model", ""
+    ) else []
+
+
+def create_app() -> FastAPI:
+    """Build the FastAPI application.
+
+    The returned app holds a single :class:`OuroborosMind` instance
+    per process. For multi-worker deployments each worker would have
+    its own mind; production users would put a single-worker
+    deployment behind a reverse proxy.
+    """
+    cfg = load_config()
+    app = FastAPI(
+        title="Ouroboros Mind",
+        version=__version__,
+        description="Lifelong private memory for large language models.",
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cfg.server.cors_origins or ["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # ---- health & meta ------------------------------------------------
+
+    @app.get("/health", tags=["meta"])
+    def health() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    @app.get("/version", tags=["meta"])
+    def version() -> dict[str, str]:
+        return {"version": __version__}
+
+    # ---- config ------------------------------------------------------
+
+    @app.get("/config", tags=["config"])
+    def get_config() -> dict[str, Any]:
+        return load_config().model_dump(mode="json")
+
+    @app.post("/config", tags=["config"])
+    def update_config(req: ConfigUpdateRequest) -> dict[str, Any]:
+        cfg = load_config()
+        data: dict[str, Any] = cfg.model_dump()
+        _set_dotted(data, req.key, req.value)
+        cfg = type(cfg).model_validate(data)
+        save_config(cfg)
+        return {"status": "ok", "key": req.key, "value": req.value, "config": cfg.model_dump(mode="json")}
+
+    # ---- LLM ---------------------------------------------------------
+
+    @app.get("/llm", tags=["llm"])
+    def llm_info() -> dict[str, Any]:
+        mind = _build_mind()
+        info = mind.llm_info()
+        info["models"] = _llm_list_models(mind)
+        return info
+
+    @app.get("/llm/models", tags=["llm"])
+    def llm_models() -> list[str]:
+        mind = _build_mind()
+        return _llm_list_models(mind)
+
+    @app.get("/llm/ping", tags=["llm"])
+    def llm_ping() -> dict[str, Any]:
+        mind = _build_mind()
+        info = mind.llm_info()
+        return {"ok": bool(info.get("available")), "info": info}
+
+    @app.post("/llm/switch", tags=["llm"])
+    def llm_switch(req: LLMSwitchRequest) -> dict[str, Any]:
+        mind = _build_mind()
+        kwargs: dict[str, Any] = {"timeout": float(req.timeout)}
+        if req.base_url:
+            kwargs["base_url" if req.provider in ("openai", "vllm", "gpt") else "host"] = req.base_url
+        if req.api_key:
+            kwargs["api_key"] = req.api_key
+        if req.model:
+            kwargs["model"] = req.model
+        try:
+            provider = mind.switch_llm(req.provider, **kwargs)
+        except Exception as exc:
+            raise HTTPException(status_code=400, detail=f"could not switch LLM: {exc}") from exc
+        info = mind.llm_info()
+        info["models"] = _llm_list_models(mind)
+        return {
+            "status": "ok",
+            "provider": getattr(provider, "name", ""),
+            "model": getattr(provider, "model", ""),
+            "info": info,
+        }
+
+    # ---- chat --------------------------------------------------------
+
+    @app.post("/chat", response_model=ChatResponse, tags=["chat"])
+    def chat(req: ChatRequest) -> ChatResponse:
+        # Accept both ``message`` (documented) and ``text`` (legacy).
+        text = req.message or req.text
+        if not text:
+            raise HTTPException(status_code=422, detail="`message` (or `text`) is required")
+        mind = _build_mind()
+        facts_before = int(mind.status().get("facts", 0))
+        try:
+            reply = mind.chat(text)
+        finally:
+            _save_mind(mind)
+        snap = mind.status()
+        facts_after = int(snap.get("facts", facts_before))
+        # Capture the names of the highest-ranked concepts as a
+        # transparent "context" hint for callers that want to know
+        # which facts were used.
+        context: list[str] = []
+        try:
+            ranked = mind.ranker.rank(query=text, k=4)
+            context = [r.node.name for r in ranked]
+        except Exception:
+            context = []
+        return ChatResponse(
+            text=reply,
+            reply=reply,
+            context=context,
+            facts_learned=max(0, facts_after - facts_before),
+            status=snap,
+        )
+
+    # ---- inspect -----------------------------------------------------
+
+    @app.get("/inspect", tags=["meta"])
+    def inspect() -> dict[str, Any]:
+        mind = _build_mind()
+        return mind.status()
+
+    # ---- dream -------------------------------------------------------
+
+    @app.post("/dream", tags=["cognition"])
+    def dream() -> dict[str, Any]:
+        mind = _build_mind()
+        report = mind.dream()
+        try:
+            data = (
+                report.to_dict()
+                if hasattr(report, "to_dict")
+                else {"raw": str(report)}
+            )
+        except Exception:
+            data = {"raw": str(report)}
+        if "summary" not in data and hasattr(report, "summary"):
+            data["summary"] = report.summary()
+        if "facts_consolidated" not in data:
+            data["facts_consolidated"] = (
+                int(data.get("insights_logged", 0))
+                + int(data.get("contradictions_weakened", 0))
+            )
+        _save_mind(mind)
+        return data
+
+    # ---- memory browser ----------------------------------------------
+
+    @app.get("/memory/concepts", tags=["memory"])
+    def memory_concepts(limit: int = 200, offset: int = 0) -> dict[str, Any]:
+        mind = _build_mind()
+        return {
+            "items": mind.list_concepts(limit=limit, offset=offset),
+            "total": len(mind.crystal),
+        }
+
+    @app.get("/memory/facts", tags=["memory"])
+    def memory_facts(
+        limit: int = 200,
+        offset: int = 0,
+        subject: str | None = None,
+        relation: str | None = None,
+    ) -> dict[str, Any]:
+        mind = _build_mind()
+        items = mind.list_facts(
+            limit=limit, offset=offset, subject=subject, relation=relation
+        )
+        return {
+            "items": items,
+            "total": mind.crystal.total_facts(),
+        }
+
+    @app.post("/memory/search", tags=["memory"])
+    def memory_search(req: MemorySearchRequest) -> dict[str, Any]:
+        mind = _build_mind()
+        return {"items": mind.search_memory(req.query, k=req.k)}
+
+    @app.get("/memory/narrative", tags=["memory"])
+    def memory_narrative(limit: int = 50) -> dict[str, Any]:
+        mind = _build_mind()
+        return {"items": mind.narrative_log(limit=limit)}
+
+    @app.get("/memory/items", tags=["memory"])
+    def memory_items(
+        limit: int = 100, subject: str | None = None
+    ) -> dict[str, Any]:
+        """List the raw memory items (the verbatim text the user typed).
+
+        Newest first.  This is the topic-agnostic mirror: every
+        utterance the LLM could draw from, regardless of whether the
+        parser produced a structured triple for it.
+        """
+        mind = _build_mind()
+        return {
+            "items": mind.list_memory_items(limit=limit, subject=subject),
+            "total": mind.crystal.total_memory_items(),
+        }
+
+    @app.post("/memory/items/search", tags=["memory"])
+    def memory_items_search(req: MemorySearchRequest) -> dict[str, Any]:
+        """Search the raw memory items by token overlap with a query."""
+        mind = _build_mind()
+        return {"items": mind.search_memory_items(req.query, k=req.k)}
+
+    @app.post("/memory/clear", tags=["memory"])
+    def memory_clear() -> dict[str, Any]:
+        mind = _build_mind(load_from_disk=False)
+        mind.clear()
+        _save_mind(mind)
+        return {"status": "ok", "status_snapshot": mind.status()}
+
+    # ---- backup / restore --------------------------------------------
+
+    @app.post("/backup", tags=["persistence"])
+    def backup(target: Path | None = None) -> dict[str, Any]:
+        """Return the snapshot.
+
+        Behaviour matches the documented contract in
+        ``docs/user_guide.md`` §7.2: the body is a JSON object with a
+        ``path`` and a ``size`` (in bytes). For convenience we also
+        include the full snapshot under ``payload`` so clients that
+        want to keep the data inline do not need a second call.
+        """
+        mind = _build_mind()
+        snap = mind.to_dict()
+        text = json.dumps(snap, ensure_ascii=False, default=str)
+        size = len(text.encode("utf-8"))
+        out_path = target or _storage_path()
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(text, encoding="utf-8")
+        return {
+            "path": str(out_path),
+            "size": size,
+            "payload": snap,
+        }
+
+    @app.post("/restore", tags=["persistence"])
+    def restore(req: RestoreRequest) -> dict[str, Any]:
+        payload = req.payload
+        if not isinstance(payload, dict):
+            raise HTTPException(status_code=400, detail="payload must be an object")
+        mind = _build_mind(load_from_disk=False)
+        try:
+            mind.load_state(payload)
+        except Exception as exc:
+            raise HTTPException(status_code=400, detail=f"could not load: {exc}") from exc
+        _save_mind(mind)
+        return {"status": "ok", **mind.status()}
+
+    # ---- websocket streaming ----------------------------------------
+
+    @app.websocket("/ws/chat")
+    async def ws_chat(ws: WebSocket) -> None:
+        await ws.accept()
+        try:
+            while True:
+                raw = await ws.receive_text()
+                try:
+                    payload = json.loads(raw)
+                except json.JSONDecodeError:
+                    payload = {"message": raw}
+                # Accept both ``message`` (documented) and ``text`` (legacy).
+                text = str(payload.get("message", "") or payload.get("text", ""))
+                if not text:
+                    await ws.send_json({"error": "empty text"})
+                    continue
+                mind = _build_mind()
+                reply = mind.chat(text)
+                _save_mind(mind)
+                await ws.send_json({"text": reply, "reply": reply, "status": mind.status()})
+        except WebSocketDisconnect:
+            return
+
+    # ---- GUI static assets -------------------------------------------
+
+    if _GUI_DIST.is_dir() and (_GUI_DIST / "index.html").is_file():
+        assets_dir = _GUI_DIST / "assets"
+
+        @app.get("/", include_in_schema=False)
+        def gui_index() -> Any:
+            return FileResponse(_GUI_DIST / "index.html")
+
+        @app.get("/favicon.svg", include_in_schema=False)
+        def gui_favicon() -> Any:
+            favicon = _GUI_DIST / "favicon.svg"
+            if favicon.is_file():
+                return FileResponse(favicon)
+            raise HTTPException(status_code=404)
+
+        if assets_dir.is_dir():
+            app.mount(
+                "/assets",
+                StaticFiles(directory=str(assets_dir), check_dir=False),
+                name="gui-assets",
+            )
+
+        @app.get("/{full_path:path}", include_in_schema=False)
+        def gui_spa(full_path: str) -> Any:
+            # Don't shadow API routes.
+            if full_path.startswith("api/") or full_path.startswith("ws/"):
+                raise HTTPException(status_code=404)
+            candidate = _GUI_DIST / full_path
+            if candidate.is_file():
+                return FileResponse(candidate)
+            return FileResponse(_GUI_DIST / "index.html")
+
+    return app
+
+
+__all__ = [
+    "ChatRequest",
+    "ChatResponse",
+    "ConfigUpdateRequest",
+    "LLMSwitchRequest",
+    "MemorySearchRequest",
+    "RestoreRequest",
+    "create_app",
+]

ouroboros/cli/__init__.py

@@ -0,0 +1,23 @@
+"""Command-line interface (Typer).
+
+The CLI is the simplest way to run Ouroboros: it provides a terminal
+REPL, a server launcher, an interactive configuration wizard, and
+import/export/backup commands. The Typer application is exposed
+through :data:`app`; the import is performed lazily to keep the
+top-level ``import ouroboros`` cheap.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def __getattr__(name: str) -> Any:  # pragma: no cover - simple dispatch
+    if name == "app":
+        from ouroboros.cli.main import app
+
+        return app
+    raise AttributeError(f"module 'ouroboros.cli' has no attribute {name!r}")
+
+
+__all__ = ["app"]