cpersona 2.4.34__py3-none-any.whl

cpersona/__init__.py

@@ -0,0 +1 @@
+"""CPersona — persistent AI memory MCP server."""

cpersona/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m cpersona``."""
+
+from cpersona.server import run
+
+if __name__ == "__main__":
+    run()

cpersona/_vendored_mcp_common/__init__.py

@@ -0,0 +1,64 @@
+"""Common utilities shared across Magic Gateway Protocol (MGP) Python servers.
+
+Foundation layer (Phase 2 Step 2-α) ported from
+``cloto-mcp-servers/servers/common/``:
+
+- :mod:`mcp_common.validation` — graceful-degradation argument validators
+  (``validate_bool`` / ``validate_str`` / ``validate_int`` / ``validate_dict`` /
+  ``validate_float`` / ``validate_list``).
+- :mod:`mcp_common.isolation` — γ-semantics two-tier isolation helpers
+  shared by CPersona & CScheduler (``gamma_clause`` / ``coerce_for_*`` /
+  ``extract_axes_for_*``).
+- :mod:`mcp_common.no_persist` — session no-persist mode helpers
+  (``pause`` / ``resume`` / ``status`` / ``is_paused`` /
+  ``make_skipped_response``).
+- :mod:`mcp_common.mgp_utils` — MGP capability builder and stream-notification
+  emitters (``MgpCapabilities`` / ``send_mgp_stream_chunk`` /
+  ``write_mgp_*``).
+
+Network / cache layer (Phase 2 Step 2-β):
+
+- :mod:`mcp_common.embedding_client` — vector embedding client with TTL-based
+  LRU cache for single-text queries (``EmbeddingClient`` /
+  ``pack_embedding`` / ``unpack_embedding``).
+- :mod:`mcp_common.semantic_cache` — in-memory semantic cache that matches
+  cached results via embedding similarity (``SemanticCache``).
+- :mod:`mcp_common.search` — search provider abstraction with a SearXNG →
+  Tavily → DuckDuckGo fallback chain (``SearchProvider`` /
+  ``SearXNGProvider`` / ``TavilyProvider`` / ``DuckDuckGoProvider`` /
+  ``ChainProvider`` / ``create_search_provider``).
+
+MCP SDK tooling (Phase 2 Step 2-γ):
+
+- :mod:`mcp_common.mcp_utils` — decorator-based MCP tool registration
+  with auto-validated parameter extraction (``ToolRegistry`` /
+  ``ToolRegistry.tool`` / ``ToolRegistry.auto_tool`` /
+  ``run_mcp_server`` / ``install_mgp_validation_filter``).
+
+MGP streaming middleware (Phase 2 Step 2-δ):
+
+- :mod:`mcp_common.mcp_stream_interceptor` — async pump that sits between
+  the raw stdio read stream and the MCP ``ServerSession``, intercepting
+  the custom MGP §12.7 ``mgp/stream/cancel`` requests and §12.9
+  ``notifications/mgp.stream.gap`` notifications that would otherwise be
+  dropped by the SDK's closed Pydantic unions (``mgp_message_interceptor``
+  / ``_handle_mgp_cancel`` / ``_handle_mgp_gap``).
+
+LLM provider + streaming (Phase 2 Step 2-ε):
+
+- :mod:`mcp_common.llm_provider` — OpenAI-compatible HTTP client with
+  SSE streaming, MGP §12 stream support (``mgp/stream/cancel`` /
+  ``notifications/mgp.stream.gap`` retransmission), tool-call orchestration,
+  and the ``create_llm_mcp_server`` / ``run_server`` entry points
+  (``ProviderConfig`` / ``StreamState`` / ``LlmApiError`` /
+  ``call_llm_api_streaming`` / ``handle_think_with_tools`` /
+  ``handle_think_with_tools_streaming`` / ``load_llm_provider_config``).
+  This module owns the ``StreamState`` dataclass referenced by the
+  ``TYPE_CHECKING`` block in :mod:`mcp_common.mcp_stream_interceptor`;
+  the forward reference left in Step 2-δ now resolves cleanly.
+
+Phase 2 module migration from ``cloto-mcp-servers/servers/common/`` is
+complete with this sub-PR.
+"""
+
+__version__ = "0.5.1"

cpersona/_vendored_mcp_common/embedding_client.py

@@ -0,0 +1,183 @@
+"""Shared embedding client for cloto-mcp-servers.
+
+Extracted from cpersona/server.py:146-301 in CScheduler v0.2 to allow
+multiple MCP servers (CPersona, CScheduler, ...) to share a single
+embedding implementation while talking to the same embedding HTTP server
+(default port 8401) or an OpenAI-compatible API.
+
+Each server owns its own EmbeddingClient instance; configuration is
+injected via constructor arguments — env-var reading is the caller's
+responsibility so that BC fallbacks (e.g. CPERSONA_EMBEDDING_*) live in
+the relevant server's startup code.
+"""
+
+import hashlib
+import logging
+import struct
+import time
+from collections import OrderedDict
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CACHE_SIZE = 256
+DEFAULT_CACHE_TTL = 300  # seconds
+DEFAULT_TIMEOUT_SECS = 30
+
+
+class EmbeddingClient:
+    """Client for computing vector embeddings via HTTP or OpenAI-compatible API.
+
+    Includes a TTL-based LRU cache for single-text queries (recall dedup).
+    """
+
+    def __init__(
+        self,
+        mode: str,
+        http_url: str = "",
+        api_key: str = "",
+        api_url: str = "",
+        model: str = "",
+        cache_size: int = DEFAULT_CACHE_SIZE,
+        cache_ttl: int = DEFAULT_CACHE_TTL,
+        timeout: int = DEFAULT_TIMEOUT_SECS,
+    ):
+        self.mode = mode
+        self._http_url = http_url
+        self._api_key = api_key
+        self._api_url = api_url
+        self._model = model
+        self._client = None
+        # LRU cache: key=text_hash, value=(embedding, timestamp)
+        self._cache: OrderedDict[str, tuple[list[float], float]] = OrderedDict()
+        self._cache_size = cache_size
+        self._cache_ttl = cache_ttl
+        self._timeout = timeout
+        self.cache_hits = 0
+        self.cache_misses = 0
+
+    async def initialize(self):
+        """Create persistent HTTP client."""
+        self._client = httpx.AsyncClient(timeout=self._timeout)
+        logger.info(
+            "EmbeddingClient initialized (mode=%s, cache=%d, ttl=%ds, timeout=%ds)",
+            self.mode,
+            self._cache_size,
+            self._cache_ttl,
+            self._timeout,
+        )
+
+    async def close(self):
+        """Close HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    def _cache_key(self, text: str) -> str:
+        return hashlib.sha256(text.encode()).hexdigest()[:16]
+
+    def _cache_get(self, text: str) -> list[float] | None:
+        """Look up a single text in cache. Returns embedding or None."""
+        key = self._cache_key(text)
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        embedding, ts = entry
+        if time.monotonic() - ts > self._cache_ttl:
+            del self._cache[key]
+            return None
+        # Move to end (most recently used)
+        self._cache.move_to_end(key)
+        return embedding
+
+    def _cache_put(self, text: str, embedding: list[float]) -> None:
+        """Store a single text→embedding in cache."""
+        key = self._cache_key(text)
+        self._cache[key] = (embedding, time.monotonic())
+        self._cache.move_to_end(key)
+        while len(self._cache) > self._cache_size:
+            self._cache.popitem(last=False)
+
+    async def embed(self, texts: list[str]) -> list[list[float]] | None:
+        """Compute embeddings with LRU cache for single-text queries.
+
+        Cache is used only for single-text calls (the common recall path).
+        Batch calls bypass cache to avoid complexity.
+        """
+        if self.mode == "none" or not self._client:
+            return None
+
+        # Single-text cache path
+        if len(texts) == 1:
+            cached = self._cache_get(texts[0])
+            if cached is not None:
+                self.cache_hits += 1
+                return [cached]
+            self.cache_misses += 1
+
+        try:
+            if self.mode == "http":
+                result = await self._embed_via_http(texts)
+            elif self.mode == "api":
+                result = await self._embed_via_api(texts)
+            else:
+                logger.warning("Unknown embedding mode: %s", self.mode)
+                return None
+        except (httpx.RequestError, httpx.HTTPStatusError, ValueError, KeyError) as e:
+            logger.warning("Embedding request failed: %s", e)
+            return None
+
+        # Cache single-text results
+        if result and len(texts) == 1 and len(result) == 1:
+            self._cache_put(texts[0], result[0])
+
+        return result
+
+    async def _embed_via_http(self, texts: list[str]) -> list[list[float]] | None:
+        """Call the embedding server's HTTP endpoint."""
+        response = await self._client.post(
+            self._http_url,
+            json={"texts": texts},
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data.get("embeddings")
+
+    async def _embed_via_api(self, texts: list[str]) -> list[list[float]] | None:
+        """Call OpenAI-compatible embedding API directly."""
+        import numpy as np
+
+        response = await self._client.post(
+            self._api_url,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+            },
+            json={"model": self._model, "input": texts},
+        )
+        response.raise_for_status()
+        data = response.json()
+        embeddings = [item["embedding"] for item in data["data"]]
+
+        # L2-normalize for consistent cosine similarity via dot product
+        result = []
+        for emb in embeddings:
+            vec = np.array(emb, dtype=np.float32)
+            norm = np.linalg.norm(vec)
+            if norm > 1e-9:
+                vec = vec / norm
+            result.append(vec.tolist())
+
+        return result
+
+    @staticmethod
+    def pack_embedding(embedding: list[float]) -> bytes:
+        """Pack a float list into a BLOB (little-endian float32)."""
+        return struct.pack(f"<{len(embedding)}f", *embedding)
+
+    @staticmethod
+    def unpack_embedding(blob: bytes) -> list[float]:
+        """Unpack a BLOB into a float list."""
+        n = len(blob) // 4
+        return list(struct.unpack(f"<{n}f", blob))

cpersona/_vendored_mcp_common/isolation.py

@@ -0,0 +1,113 @@
+"""γ-semantics two-tier isolation helpers shared by CPersona & CScheduler.
+
+This module is the **single source of truth** for the per-axis isolation
+filter (project_id, agent_id, …) used to give each MCP server a
+two-bucket-aware view of its data:
+
+- Write side: a missing / non-string / empty value collapses to ``''``,
+  which we treat as the *global pool* — rows visible from every bucket
+  read query.
+- Read side: callers can pass
+
+  - ``None`` → no filter on this axis (return everything)
+  - ``''``   → match only the global pool (rows whose axis = ``''``)
+  - ``'X'``  → match the named bucket *plus* the global pool, i.e.
+    ``axis IN ('X', '')`` — the eponymous "γ" union.
+
+Each MCP server typically wires one or two axes (project_id alone for
+CPersona, project_id × agent_id for CScheduler). The functions here are
+axis-agnostic: pass any column name and any caller-supplied value, get
+back a SQL fragment plus parameter list ready to splat into
+``aiosqlite.Connection.execute``.
+
+Pure-Python, stdlib-only. Database backend agnostic — emits ``IN (?, ?)``
+or ``= ?`` placeholders that work with sqlite3, asyncpg, mysql, etc.
+
+Versioning: introduced in cloto-mcp-cscheduler 0.2.4 / cloto-mcp-cpersona
+2.4.18 as a refactor of the verbatim-duplicated logic from those two
+servers' v0.2.3 / v2.4.17 patches.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "gamma_clause",
+    "coerce_for_write",
+    "coerce_for_read",
+    "extract_axes_for_write",
+    "extract_axes_for_read",
+]
+
+
+def gamma_clause(column: str, value: str | None) -> tuple[str, list[Any]]:
+    """Build a SQL fragment + params for γ semantics on `column`.
+
+    - ``value is None``  → ``('', [])`` so the caller can skip the filter
+      entirely (= "return everything across all buckets").
+    - ``value == ''``    → ``('column = ?', [''])`` — match only the
+      global pool. Collapsed to a bare ``=`` so we don't double-bind the
+      same string into ``IN``.
+    - any other string   → ``('column IN (?, ?)', [value, ''])`` —
+      γ union of the named bucket and the global pool.
+
+    The column name is interpolated raw, so callers MUST pass a trusted
+    identifier (typed as ``project_id`` / ``t.agent_id`` etc., never
+    user-supplied input).
+    """
+    if value is None:
+        return ("", [])
+    if value == "":
+        return (f"{column} = ?", [""])
+    return (f"{column} IN (?, ?)", [value, ""])
+
+
+def coerce_for_write(value: Any) -> str:
+    """Coerce an isolation axis value for INSERT.
+
+    Strings are preserved verbatim (including ``''`` for the global
+    pool). Anything else (``None``, missing kwarg → ``None`` upstream,
+    ints, dicts, etc.) collapses to ``''``. This matches the "default
+    to global pool" semantic the schema column declares with
+    ``DEFAULT ''``.
+    """
+    if isinstance(value, str):
+        return value
+    return ""
+
+
+def coerce_for_read(value: Any) -> str | None:
+    """Coerce an isolation axis value for γ-filtered SELECT.
+
+    Strings (including ``''``) are preserved verbatim — the caller
+    distinguishes "global pool only" (``''``) from "no filter"
+    (``None``). Anything else collapses to ``None``, matching the
+    "absent kwarg → no filter" intuition for read paths.
+    """
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def extract_axes_for_write(arguments: dict, *axes: str) -> tuple[str, ...]:
+    """Bulk extract + coerce multiple isolation axes from an MCP
+    arguments dict for write paths. Returns a tuple of strings (one per
+    axis name in `axes`), each defaulting to ``''`` when missing.
+
+    Example::
+
+        project_id, agent_id = extract_axes_for_write(
+            arguments, "project_id", "agent_id"
+        )
+    """
+    return tuple(coerce_for_write(arguments.get(a)) for a in axes)
+
+
+def extract_axes_for_read(arguments: dict, *axes: str) -> tuple[str | None, ...]:
+    """Bulk extract + coerce multiple isolation axes from an MCP
+    arguments dict for read paths. Returns a tuple of ``Optional[str]``
+    (one per axis name), where ``None`` means "no filter on this axis"
+    and ``''`` means "global pool only" — see :func:`gamma_clause` for
+    the SQL semantics."""
+    return tuple(coerce_for_read(arguments.get(a)) for a in axes)