clsplusplus 7.2.4__tar.gz → 7.3.0__tar.gz

{clsplusplus-7.2.4 → clsplusplus-7.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clsplusplus
-Version: 7.2.4
+Version: 7.3.0
 Summary: Brain-inspired, model-agnostic persistent memory for LLMs. Learn, recall, forget — like a brain. Works with OpenAI, Claude, Gemini, Llama.
 Author-email: AlphaForge AI Labs <contact@alphaforge.ai>
 Maintainer-email: Rajamohan Jabbala <contact@alphaforge.ai>
@@ -52,6 +52,15 @@ Requires-Dist: razorpay>=1.4.0; extra == "server"
 Requires-Dist: minio>=7.2.0; extra == "server"
 Requires-Dist: pyarrow>=14.0.0; extra == "server"
 Requires-Dist: posthog>=3.5.0; extra == "server"
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.0.0; extra == "crewai"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=1.0.0; extra == "langgraph"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.12.0; extra == "llamaindex"
+Provides-Extra: autogen
+Requires-Dist: autogen-core>=0.4.0; extra == "autogen"
+Requires-Dist: autogen-agentchat>=0.4.0; extra == "autogen"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

{clsplusplus-7.2.4 → clsplusplus-7.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clsplusplus"
-version = "7.2.4"
+version = "7.3.0"
 description = "Brain-inspired, model-agnostic persistent memory for LLMs. Learn, recall, forget — like a brain. Works with OpenAI, Claude, Gemini, Llama."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -63,6 +63,40 @@ server = [
     "pyarrow>=14.0.0",
     "posthog>=3.5.0",
 ]
+# CrewAI integration — pip install clsplusplus[crewai]
+# Provides clsplusplus.integrations.crewai.CLSMemoryStorage, a native CrewAI
+# external-memory backend. Floor is the CrewAI 1.x line that ships the stable
+# crewai.memory.storage.interface.Storage + ExternalMemory API this adapts to.
+crewai = [
+    "crewai>=1.0.0",
+]
+# LangGraph integration — pip install clsplusplus[langgraph]
+# Provides clsplusplus.integrations.langgraph.CLSMemoryStore, a native
+# subclass of langgraph.store.base.BaseStore (the long-term-memory store you
+# pass as store= to graph.compile). Floor is the LangGraph 1.x line; BaseStore
+# and its Op/Item/SearchItem types are re-exported from langgraph-checkpoint
+# and stable across the 1.x series.
+langgraph = [
+    "langgraph>=1.0.0",
+]
+# LlamaIndex integration — pip install clsplusplus[llamaindex]
+# Provides clsplusplus.integrations.llamaindex.CLSMemoryBlock, a native subclass
+# of llama_index.core.memory.BaseMemoryBlock (a pluggable memory_block you pass
+# to Memory.from_defaults). Floor is the 0.12 line that introduced the modern
+# Memory + BaseMemoryBlock API; verified against llama-index-core 0.14.x.
+llamaindex = [
+    "llama-index-core>=0.12.0",
+]
+# AutoGen integration — pip install clsplusplus[autogen]
+# Provides clsplusplus.integrations.autogen.CLSMemory, a native implementation
+# of Microsoft AutoGen's autogen_core.memory.Memory protocol (the object you
+# pass to AssistantAgent(memory=[...])). Floors target the new AutoGen line
+# (autogen-core / autogen-agentchat 0.4+); the Memory protocol + MemoryContent /
+# MemoryQueryResult / UpdateContextResult shapes are stable across 0.4 → 0.7.x.
+autogen = [
+    "autogen-core>=0.4.0",
+    "autogen-agentchat>=0.4.0",
+]
 dev = [
     "pytest>=7.4.0",
     "pytest-asyncio>=0.23.0",

{clsplusplus-7.2.4 → clsplusplus-7.3.0}/src/clsplusplus/api.py

@@ -25,6 +25,7 @@ from clsplusplus.user_service import UserService
 from clsplusplus.middleware import AuthMiddleware, HealthMetricsMiddleware, QuotaMiddleware, RateLimitMiddleware, RequestIdMiddleware, TracingMiddleware
 from clsplusplus.abuse_guard import AbuseGuardMiddleware
 from clsplusplus.tracer import tracer
+from clsplusplus import write_metrics
 from clsplusplus.models import (
     AdjudicateRequest,
     ApiKeyCreate,
@@ -1232,7 +1233,14 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
                 "store": "Setup",
                 "error": "Add CLS_REDIS_URL and CLS_DATABASE_URL in Render Dashboard.",
             }
-        return HealthResponse(status=h["status"], stores=stores)
+        wm = write_metrics.snapshot()
+        return HealthResponse(
+            status=h["status"],
+            stores=stores,
+            writes=wm["total_writes"],
+            degraded_writes=wm["degraded_writes"],
+            degraded_write_rate=wm["degraded_write_rate"],
+        )
 
     @app.get("/v1/health/score", response_model=HealthResponse)
     async def health_score():
@@ -2430,6 +2438,241 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
             logger.error("Admin user list error: %s: %s", type(e).__name__, e)
             raise HTTPException(status_code=500, detail="User data unavailable")
 
+    @app.get("/admin/integrations")
+    async def admin_integrations(request: Request):
+        """Per-integration release sync: LIVE published version of each
+        publishable artifact vs the current main release tag.
+
+        The "main release tag" is the single source of truth that every
+        integration is supposed to track (the rule: the release tag IS the
+        version for every artifact). We read it from the newest git tag; if
+        the deployed image has stripped `.git`, we fall back to the committed
+        package version. Each integration's `live_version` is read from its
+        own registry/manifest using the same checks the sync tooling uses.
+
+        Fully resilient: every external/registry probe degrades to a
+        `live_version` of None and `in_sync: false` rather than failing the
+        request. This endpoint NEVER returns 500.
+        """
+        _require_admin(request)
+
+        # --- main release tag: the source of truth every artifact tracks ---
+        def _read_main_tag() -> str:
+            # 1) newest git tag (release-of-record).
+            try:
+                import subprocess
+                repo_root = FilePath(__file__).resolve().parent.parent.parent
+                out = subprocess.run(
+                    ["git", "describe", "--tags", "--abbrev=0"],
+                    cwd=str(repo_root),
+                    capture_output=True,
+                    timeout=5,
+                )
+                if out.returncode == 0:
+                    tag = out.stdout.decode().strip()
+                    if tag:
+                        return tag
+            except Exception:
+                pass
+            # 2) committed package version (prod images often strip .git).
+            try:
+                pyproject = FilePath(__file__).resolve().parent.parent.parent / "pyproject.toml"
+                if pyproject.exists():
+                    for line in pyproject.read_text().splitlines():
+                        s = line.strip()
+                        if s.startswith("version") and "=" in s:
+                            v = s.split("=", 1)[1].strip().strip('"').strip("'")
+                            if v:
+                                return f"v{v}"
+            except Exception:
+                pass
+            # 3) last resort: in-package __version__.
+            try:
+                from clsplusplus import __version__ as _v
+                if _v:
+                    return f"v{_v}"
+            except Exception:
+                pass
+            return "unknown"
+
+        def _norm(v):
+            """Normalise a version for comparison: drop leading 'v', None-safe."""
+            if not v:
+                return None
+            return str(v).strip().lstrip("v") or None
+
+        def _http_json(url: str, timeout: float = 4.0):
+            """Best-effort HTTP GET -> parsed JSON; None on any failure."""
+            try:
+                import json as _json
+                import urllib.request
+                req = urllib.request.Request(url, headers={"User-Agent": "cls-admin-integrations"})
+                with urllib.request.urlopen(req, timeout=timeout) as resp:
+                    return _json.loads(resp.read().decode())
+            except Exception:
+                return None
+
+        # --- per-integration LIVE version probes (each isolated/best-effort) ---
+        def _npm_live() -> Optional[str]:
+            # registry.npmjs.org dist-tag latest (matches `npm view ... version`)
+            data = _http_json("https://registry.npmjs.org/clsplusplus")
+            if isinstance(data, dict):
+                latest = (data.get("dist-tags") or {}).get("latest")
+                if latest:
+                    return latest
+            return None
+
+        def _pypi_live() -> Optional[str]:
+            data = _http_json("https://pypi.org/pypi/clsplusplus/json")
+            if isinstance(data, dict):
+                return (data.get("info") or {}).get("version")
+            return None
+
+        def _mcp_registry_live() -> Optional[str]:
+            data = _http_json(
+                "https://registry.modelcontextprotocol.io/v0/servers"
+                "?search=io.github.rajamohan1950/cls-memory"
+            )
+            if isinstance(data, dict):
+                servers = data.get("servers") or data.get("data") or []
+                for s in servers if isinstance(servers, list) else []:
+                    name = s.get("name") if isinstance(s, dict) else None
+                    if name and "cls-memory" in name:
+                        # version may live at top level or nested under meta.
+                        return (
+                            s.get("version")
+                            or (s.get("version_detail") or {}).get("version")
+                            or (s.get("_meta") or {}).get("version")
+                        )
+            return None
+
+        def _extension_live() -> Optional[str]:
+            # The Chrome Web Store artifact == the committed manifest version.
+            try:
+                import json as _json
+                manifest = FilePath(__file__).resolve().parent.parent.parent / "extension" / "manifest.json"
+                if manifest.exists():
+                    return _json.loads(manifest.read_text()).get("version")
+            except Exception:
+                pass
+            return None
+
+        def _remote_mcp_live() -> Optional[str]:
+            # Live hosted MCP endpoint: serverInfo.version from initialize, if
+            # exposed; the metadata doc otherwise. Best-effort only.
+            doc = _http_json(
+                "https://www.clsplusplus.com/.well-known/oauth-protected-resource",
+                timeout=3.0,
+            )
+            if isinstance(doc, dict):
+                v = doc.get("version") or (doc.get("serverInfo") or {}).get("version")
+                if v:
+                    return v
+            return None
+
+        try:
+            # The version probes below each block on network I/O (urllib) or a
+            # `git` subprocess. Offload every blocking probe to a worker thread
+            # and run them concurrently so this async handler never stalls the
+            # event loop (previously up to ~15s of serial blocking). Each probe
+            # is already isolated/best-effort, so any failure degrades to None.
+            (
+                main_tag,
+                npm_live,
+                pypi_live,
+                mcp_registry_live,
+                extension_live,
+                remote_mcp_live,
+            ) = await asyncio.gather(
+                asyncio.to_thread(_read_main_tag),
+                asyncio.to_thread(_npm_live),
+                asyncio.to_thread(_pypi_live),
+                asyncio.to_thread(_mcp_registry_live),
+                asyncio.to_thread(_extension_live),
+                asyncio.to_thread(_remote_mcp_live),
+            )
+            rel = _norm(main_tag)
+
+            # Aggregate usage (best-effort; shared across artifacts).
+            usage = None
+            try:
+                usage = await _metrics.get_aggregate_metrics()
+            except Exception:
+                usage = None
+
+            # Static catalogue of publishable integrations + how to read each
+            # one's LIVE version and where it is published.
+            catalogue = [
+                {
+                    "name": "npm (clsplusplus JS/TS SDK)",
+                    "live_version": npm_live,
+                    "publish_url": "https://www.npmjs.com/package/clsplusplus",
+                    "tracks_main_tag": True,
+                },
+                {
+                    "name": "PyPI (clsplusplus Python SDK + server + MCP)",
+                    "live_version": pypi_live,
+                    "publish_url": "https://pypi.org/project/clsplusplus/",
+                    "tracks_main_tag": True,
+                },
+                {
+                    "name": "MCP Registry (io.github.rajamohan1950/cls-memory)",
+                    "live_version": mcp_registry_live,
+                    "publish_url": (
+                        "https://registry.modelcontextprotocol.io/v0/servers"
+                        "?search=io.github.rajamohan1950/cls-memory"
+                    ),
+                    "tracks_main_tag": True,
+                },
+                {
+                    "name": "Chrome Web Store (CLS++ Memory extension)",
+                    "live_version": extension_live,
+                    "publish_url": "https://chromewebstore.google.com/",
+                    # Extension is intentionally on its own 6.x track.
+                    "tracks_main_tag": False,
+                },
+                {
+                    "name": "Remote MCP server (clsplusplus.com/mcp)",
+                    "live_version": remote_mcp_live,
+                    "publish_url": "https://www.clsplusplus.com/mcp",
+                    # A running service tracks the deployed release.
+                    "tracks_main_tag": True,
+                },
+            ]
+
+            integrations = []
+            for entry in catalogue:
+                live = entry["live_version"]
+                if entry["tracks_main_tag"]:
+                    in_sync = bool(live) and rel is not None and _norm(live) == rel
+                else:
+                    # Decoupled track: "in sync" only means we could read it.
+                    in_sync = bool(live)
+                integrations.append({
+                    "name": entry["name"],
+                    "live_version": live,
+                    "main_tag": main_tag,
+                    "in_sync": in_sync,
+                    "publish_url": entry["publish_url"],
+                    "usage": usage,
+                })
+
+            return {"main_tag": main_tag, "integrations": integrations}
+        except Exception as e:
+            # Defensive: this endpoint must never 500. Degrade to a fully
+            # "unknown" report so the dashboard always renders.
+            logger.error("Admin integrations error: %s: %s", type(e).__name__, e)
+            tag = "unknown"
+            try:
+                tag = _read_main_tag()
+            except Exception:
+                pass
+            return {
+                "main_tag": tag,
+                "integrations": [],
+                "error": "integration data degraded",
+            }
+
     def _require_admin(request: Request):
         """Helper to enforce admin access on endpoints."""
         if not getattr(request.state, "is_admin", False):

{clsplusplus-7.2.4 → clsplusplus-7.3.0}/src/clsplusplus/config.py

@@ -114,6 +114,14 @@ class Settings(BaseSettings):
     # Embeddings (used by L1/L2/L3 tiers, not by phase engine)
     embedding_model: str = "all-MiniLM-L6-v2"
     embedding_dim: int = 384
+    # Embedding backend. "sentence-transformers" (default) keeps the local
+    # all-MiniLM-L6-v2 behavior unchanged. Set CLS_EMBEDDING_PROVIDER=openai to
+    # use the OpenAI embeddings API instead — openai is lazy-imported and is NOT
+    # a hard dependency; if it's missing the provider falls back to
+    # sentence-transformers. openai_api_key is read from the existing setting.
+    embedding_provider: str = "sentence-transformers"  # CLS_EMBEDDING_PROVIDER
+    openai_embedding_model: str = "text-embedding-3-small"  # CLS_OPENAI_EMBEDDING_MODEL
+    openai_embedding_dim: int = 1536                        # CLS_OPENAI_EMBEDDING_DIM
 
     # Plasticity coefficients (α, β, γ, λ, δ)
     alpha_salience: float = 1.0
@@ -136,6 +144,11 @@ class Settings(BaseSettings):
     similarity_threshold: float = 0.7
     conflict_threshold: float = 0.3
     quorum_threshold: float = 0.8
+    # Belief-revision-on-write: when ON, the normal write() path routes new
+    # facts through the ReconsolidationGate to detect contradictions against
+    # existing same-namespace items before storing. OFF by default so the
+    # current write behavior is unchanged.
+    belief_revision_on_write: bool = False  # CLS_BELIEF_REVISION_ON_WRITE
 
     # Working buffer
     l0_capacity_tokens: int = 4096

clsplusplus-7.3.0/src/clsplusplus/embeddings.py

@@ -0,0 +1,173 @@
+"""Embedding service for CLS++."""
+
+import logging
+from typing import Optional
+
+import numpy as np
+
+from clsplusplus.config import Settings
+from clsplusplus.models import MemoryItem
+
+logger = logging.getLogger(__name__)
+
+
+class BaseEmbeddingProvider:
+    """Interface for embedding backends.
+
+    A provider turns text into dense vectors. Implementations are lazy: the
+    underlying model/client is loaded on first use, never at construction.
+    """
+
+    name: str = "base"
+
+    @property
+    def dim(self) -> int:
+        """Dimensionality of the vectors this provider returns."""
+        raise NotImplementedError
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of texts. Returns one vector per input text.
+
+        On failure (model/client unavailable) returns empty vectors so callers
+        never break — same contract the service has always honored.
+        """
+        raise NotImplementedError
+
+
+class SentenceTransformerProvider(BaseEmbeddingProvider):
+    """Local sentence-transformers backend (default, unchanged behavior).
+
+    Wraps the original all-MiniLM-L6-v2 logic: lazy model load, returns empty
+    vectors when sentence-transformers is not installed.
+    """
+
+    name = "sentence-transformers"
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self._model = None
+
+    @property
+    def model(self):
+        """Lazy load the embedding model."""
+        if self._model is None:
+            try:
+                from sentence_transformers import SentenceTransformer
+                self._model = SentenceTransformer(self.settings.embedding_model)
+            except ImportError:
+                self._model = False  # sentinel: unavailable
+        return self._model
+
+    @property
+    def dim(self) -> int:
+        return self.settings.embedding_dim
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        if self.model is False:
+            return [[] for _ in texts]
+        return self.model.encode(texts, convert_to_numpy=True).tolist()
+
+
+class OpenAIProvider(BaseEmbeddingProvider):
+    """OpenAI embeddings backend.
+
+    Selected via CLS_EMBEDDING_PROVIDER=openai. openai is lazy-imported and is
+    NOT a hard dependency. If the client/key is unavailable the embed call
+    returns empty vectors; selection-time fallback to sentence-transformers is
+    handled by the service factory.
+    """
+
+    name = "openai"
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self._client = None
+
+    @property
+    def client(self):
+        """Lazy build the OpenAI client."""
+        if self._client is None:
+            try:
+                from openai import OpenAI
+                self._client = OpenAI(api_key=self.settings.openai_api_key)
+            except ImportError:
+                self._client = False  # sentinel: unavailable
+        return self._client
+
+    @property
+    def dim(self) -> int:
+        return self.settings.openai_embedding_dim
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        if self.client is False:
+            return [[] for _ in texts]
+        try:
+            resp = self.client.embeddings.create(
+                model=self.settings.openai_embedding_model,
+                input=texts,
+            )
+            return [d.embedding for d in resp.data]
+        except Exception as e:  # network / auth / quota — never break the caller
+            logger.warning("OpenAI embedding failed (returning empty vectors): %s", e)
+            return [[] for _ in texts]
+
+
+def _build_provider(settings: Settings) -> BaseEmbeddingProvider:
+    """Select the embedding provider from settings.
+
+    Default is sentence-transformers. CLS_EMBEDDING_PROVIDER=openai selects
+    OpenAI, but if the openai package is not installed we warn and fall back to
+    sentence-transformers so behavior degrades gracefully.
+    """
+    provider = (settings.embedding_provider or "").strip().lower()
+    if provider == "openai":
+        try:
+            import openai  # noqa: F401
+        except ImportError:
+            logger.warning(
+                "CLS_EMBEDDING_PROVIDER=openai but the openai package is not "
+                "installed; falling back to sentence-transformers."
+            )
+            return SentenceTransformerProvider(settings)
+        return OpenAIProvider(settings)
+    return SentenceTransformerProvider(settings)
+
+
+class EmbeddingService:
+    """Produces embeddings for memory items."""
+
+    def __init__(self, settings: Optional[Settings] = None):
+        self.settings = settings or Settings()
+        self.provider = _build_provider(self.settings)
+
+    @property
+    def model(self):
+        """Backward-compat accessor for the underlying sentence-transformers model.
+
+        Returns None for non-sentence-transformers providers.
+        """
+        return getattr(self.provider, "model", None)
+
+    def embed(self, text: str) -> list[float]:
+        """Embed a single text. Returns empty list if provider unavailable."""
+        out = self.provider.embed([text])
+        return out[0] if out else []
+
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Embed multiple texts. Returns empty lists if provider unavailable."""
+        if not texts:
+            return []
+        return self.provider.embed(texts)
+
+    def embed_item(self, item: MemoryItem) -> MemoryItem:
+        """Add embedding to a memory item."""
+        if not item.embedding:
+            item.embedding = self.embed(item.text)
+        return item
+
+    @staticmethod
+    def cosine_similarity(a: list[float], b: list[float]) -> float:
+        """Compute cosine similarity between two vectors."""
+        va = np.array(a)
+        vb = np.array(b)
+        return float(np.dot(va, vb) / (np.linalg.norm(va) * np.linalg.norm(vb) + 1e-9))

clsplusplus-7.3.0/src/clsplusplus/integrations/__init__.py

@@ -0,0 +1,46 @@
+"""Third-party framework integrations for CLS++.
+
+Each submodule adapts the CLS++ memory layer to a specific agent framework so
+that framework users can plug CLS++ in as their persistent memory backend
+without touching the HTTP client directly.
+
+Currently provided:
+
+    clsplusplus.integrations.crewai.CLSMemoryStorage
+        Implements CrewAI's ``crewai.memory.storage.interface.Storage``
+        contract (``save`` / ``search`` / ``reset``), delegating to the CLS++
+        ``Brain`` client. Wire it into a Crew via ``external_memory=``.
+
+    clsplusplus.integrations.langgraph.CLSMemoryStore
+        Subclasses LangGraph's ``langgraph.store.base.BaseStore`` (the
+        long-term-memory ``store=`` you pass to ``graph.compile``), delegating
+        to the CLS++ ``Brain`` client. Requires ``pip install
+        clsplusplus[langgraph]``.
+
+Integrations keep their framework imports lazy: importing ``clsplusplus`` (or
+``clsplusplus.integrations``) never requires the framework to be installed.
+"""
+
+from __future__ import annotations
+
+__all__ = ["CLSMemoryStorage", "CLSMemoryStore", "CLSMemoryBlock", "CLSMemory"]
+
+
+def __getattr__(name: str):
+    if name == "CLSMemoryStorage":
+        from clsplusplus.integrations.crewai import CLSMemoryStorage
+
+        return CLSMemoryStorage
+    if name == "CLSMemoryStore":
+        from clsplusplus.integrations.langgraph import CLSMemoryStore
+
+        return CLSMemoryStore
+    if name == "CLSMemoryBlock":
+        from clsplusplus.integrations.llamaindex import CLSMemoryBlock
+
+        return CLSMemoryBlock
+    if name == "CLSMemory":
+        from clsplusplus.integrations.autogen import CLSMemory
+
+        return CLSMemory
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")