comemo 2.0.0__py3-none-any.whl

cognitivememory/__init__.py

@@ -0,0 +1,39 @@
+"""Cognitive Memory SDK - Python client for the Cognitive Memory API."""
+
+from .client import MemoryClient
+from .exceptions import (
+    AuthenticationError,
+    CognitiveMemoryError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    AddMemoryResult,
+    DeleteResult,
+    DetailedMemory,
+    DetailedRetrieveResult,
+    HealthResult,
+    Memory,
+    RetrieveResult,
+    RetrieveSummaryResult,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "MemoryClient",
+    "AddMemoryResult",
+    "DeleteResult",
+    "DetailedMemory",
+    "DetailedRetrieveResult",
+    "HealthResult",
+    "Memory",
+    "RetrieveResult",
+    "RetrieveSummaryResult",
+    "CognitiveMemoryError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ServerError",
+    "ValidationError",
+]

cognitivememory/client.py

@@ -0,0 +1,412 @@
+"""Cognitive Memory SDK client."""
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    CognitiveMemoryError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    AddMemoryResult,
+    DeleteResult,
+    DetailedMemory,
+    DetailedRetrieveResult,
+    HealthResult,
+    Memory,
+    RetrieveResult,
+    RetrieveSummaryResult,
+)
+
+
+class MemoryClient:
+    """Client for the Cognitive Memory API.
+
+    Args:
+        api_key: LLM API key (e.g. OpenAI key).
+        model: LLM model name (e.g. "gpt-4o-mini").
+        pinecone_api_key: Pinecone API key.
+        pinecone_index_name: Pinecone index name. Defaults to "cognitivememory".
+        neo4j_uri: Neo4j connection URI.
+        neo4j_user: Neo4j username.
+        neo4j_password: Neo4j password.
+        base_url: Base URL of the API. Defaults to "https://xvert.io".
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        pinecone_api_key: str,
+        neo4j_uri: str,
+        neo4j_user: str,
+        neo4j_password: str,
+        pinecone_index_name: str = "cognitivememory",
+        base_url: str = "https://xvert.io",
+        timeout: float = 30,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.pinecone_api_key = pinecone_api_key
+        self.pinecone_index_name = pinecone_index_name
+        self.neo4j_uri = neo4j_uri
+        self.neo4j_user = neo4j_user
+        self.neo4j_password = neo4j_password
+        self.timeout = timeout
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Content-Type": "application/json"},
+            timeout=timeout,
+        )
+
+    def _credential_fields(self) -> dict:
+        """Return all credential fields to include in request bodies."""
+        return {
+            "api_key": self.api_key,
+            "model": self.model,
+            "pinecone_api_key": self.pinecone_api_key,
+            "pinecone_index_name": self.pinecone_index_name,
+            "neo4j_uri": self.neo4j_uri,
+            "neo4j_user": self.neo4j_user,
+            "neo4j_password": self.neo4j_password,
+        }
+
+    def _credential_params(self) -> dict:
+        """Return credential fields as query params (for GET/DELETE endpoints)."""
+        return {
+            "pinecone_api_key": self.pinecone_api_key,
+            "pinecone_index_name": self.pinecone_index_name,
+            "neo4j_uri": self.neo4j_uri,
+            "neo4j_user": self.neo4j_user,
+            "neo4j_password": self.neo4j_password,
+        }
+
+    def _handle_response(self, response: httpx.Response) -> dict:
+        """Parse response and raise appropriate exceptions on errors."""
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                detail = body.get("detail", response.text)
+            except Exception:
+                detail = response.text
+
+            if response.status_code in (401, 403):
+                raise AuthenticationError(detail, response.status_code)
+            if response.status_code == 404:
+                raise NotFoundError(detail, response.status_code)
+            if response.status_code in (400, 422):
+                raise ValidationError(detail, response.status_code)
+            if response.status_code >= 500:
+                raise ServerError(detail, response.status_code)
+            raise CognitiveMemoryError(detail, response.status_code)
+
+        return response.json()
+
+    # ── Core Memory Operations ──────────────────────────────────────────
+
+    def add_memory(self, user_id: str, session_id: str, text: str) -> AddMemoryResult:
+        """Extract facts from text and store them as memories.
+
+        Args:
+            user_id: User ID for memory isolation.
+            session_id: Session ID for context grouping.
+            text: Input text to extract facts from.
+
+        Returns:
+            AddMemoryResult with status, action taken, memory_id, links created, and score.
+        """
+        data = self._handle_response(
+            self._client.post("/memory", json={
+                "user_id": user_id,
+                "session_id": session_id,
+                "input": text,
+                **self._credential_fields(),
+            })
+        )
+        return AddMemoryResult(
+            status=data.get("status", ""),
+            action=data.get("action", ""),
+            memory_id=data.get("memory_id"),
+            links_created=data.get("links_created", 0),
+            score=data.get("score", 0.0),
+        )
+
+    def delete_memory(self, memory_id: str) -> dict:
+        """Delete a single memory by ID.
+
+        Args:
+            memory_id: The memory identifier to delete.
+
+        Returns:
+            Dict with status, memory_id, and deleted flag.
+        """
+        return self._handle_response(
+            self._client.delete(f"/memory/{memory_id}", params=self._credential_params())
+        )
+
+    def delete_user_memories(self, user_id: str) -> DeleteResult:
+        """Delete all memories for a user.
+
+        Args:
+            user_id: The user whose memories to delete.
+
+        Returns:
+            DeleteResult with count of deleted memories.
+        """
+        data = self._handle_response(
+            self._client.delete("/memory", params={"user_id": user_id, **self._credential_params()})
+        )
+        return DeleteResult(
+            status=data.get("status", ""),
+            user_id=data.get("user_id", user_id),
+            memories_deleted=data.get("memories_deleted", 0),
+        )
+
+    def delete_session_memories(self, user_id: str, session_id: str) -> DeleteResult:
+        """Delete all memories for a specific session.
+
+        Args:
+            user_id: The user ID.
+            session_id: The session whose memories to delete.
+
+        Returns:
+            DeleteResult with count of deleted memories.
+        """
+        data = self._handle_response(
+            self._client.delete(f"/memory/session/{session_id}", params={"user_id": user_id, **self._credential_params()})
+        )
+        return DeleteResult(
+            status=data.get("status", ""),
+            user_id=data.get("user_id", user_id),
+            memories_deleted=data.get("memories_deleted", 0),
+        )
+
+    # ── Retrieval ───────────────────────────────────────────────────────
+
+    def retrieve(self, user_id: str, session_id: str, query: str, top_k: int = 5) -> RetrieveResult:
+        """Retrieve top memories matching a query (simple mode).
+
+        Args:
+            user_id: User ID for namespace isolation.
+            session_id: Current session ID.
+            query: Search query text.
+            top_k: Maximum number of results (1-50). Defaults to 5.
+
+        Returns:
+            RetrieveResult with query, expanded query, and list of memories.
+        """
+        data = self._handle_response(
+            self._client.post("/memories/retrieve", json={
+                "user_id": user_id,
+                "session_id": session_id,
+                "query": query,
+                "top_k": top_k,
+                **self._credential_fields(),
+            })
+        )
+        memories = [
+            Memory(memory_id=m["memory_id"], fact=m["fact"], score=m["score"])
+            for m in data.get("memories", [])
+        ]
+        return RetrieveResult(
+            query=data.get("query", query),
+            expanded_query=data.get("expanded_query", ""),
+            memories=memories,
+        )
+
+    def retrieve_advanced(
+        self,
+        user_id: str,
+        session_id: str,
+        query: str,
+        top_k: int = 10,
+        expand_context: bool = True,
+        expand_graph: bool = True,
+        min_score: float = 0.1,
+        reinforce: bool = False,
+    ) -> DetailedRetrieveResult:
+        """Retrieve memories with full scoring details and advanced options.
+
+        Args:
+            user_id: User ID for namespace isolation.
+            session_id: Current session ID.
+            query: Search query text.
+            top_k: Maximum number of results (1-50). Defaults to 10.
+            expand_context: Use session context for query expansion. Defaults to True.
+            expand_graph: Expand via Neo4j graph relationships. Defaults to True.
+            min_score: Minimum score threshold (0.0-1.0). Defaults to 0.1.
+            reinforce: Reinforce retrieved memories. Defaults to False.
+
+        Returns:
+            DetailedRetrieveResult with full scoring breakdown per memory.
+        """
+        data = self._handle_response(
+            self._client.post("/memory/retrieve", json={
+                "user_id": user_id,
+                "session_id": session_id,
+                "query": query,
+                "top_k": top_k,
+                "expand_context": expand_context,
+                "expand_graph": expand_graph,
+                "min_score": min_score,
+                "reinforce": reinforce,
+                **self._credential_fields(),
+            })
+        )
+        memories = [
+            DetailedMemory(
+                memory_id=m["memory_id"],
+                fact=m["fact"],
+                domain=m.get("domain", ""),
+                final_score=m.get("final_score", 0.0),
+                semantic_similarity=m.get("semantic_similarity", 0.0),
+                graph_relevance=m.get("graph_relevance", 0.0),
+                memory_strength=m.get("memory_strength", 0.0),
+                recency_score=m.get("recency_score", 0.0),
+                session_boost=m.get("session_boost", 0.0),
+                source=m.get("source", ""),
+                session_id=m.get("session_id", ""),
+            )
+            for m in data.get("memories", [])
+        ]
+        return DetailedRetrieveResult(
+            query=data.get("query", query),
+            expanded_query=data.get("expanded_query", ""),
+            user_id=data.get("user_id", user_id),
+            session_id=data.get("session_id", session_id),
+            memories=memories,
+            total_candidates=data.get("total_candidates", 0),
+            filtered_count=data.get("filtered_count", 0),
+            retrieval_time_ms=data.get("retrieval_time_ms", 0.0),
+        )
+
+    def retrieve_summary(
+        self, user_id: str, session_id: str, query: str, top_k: int = 5
+    ) -> RetrieveSummaryResult:
+        """Retrieve memories and get an LLM-generated summary.
+
+        Args:
+            user_id: User ID for namespace isolation.
+            session_id: Current session ID.
+            query: Search query text.
+            top_k: Number of memories to summarize (1-20). Defaults to 5.
+
+        Returns:
+            RetrieveSummaryResult with summary text and supporting memories.
+        """
+        data = self._handle_response(
+            self._client.post("/memories/retrieve-summary", json={
+                "user_id": user_id,
+                "session_id": session_id,
+                "query": query,
+                "top_k": top_k,
+                **self._credential_fields(),
+            })
+        )
+        memories = [
+            Memory(memory_id=m["memory_id"], fact=m["fact"], score=m["score"])
+            for m in data.get("supporting_memories", [])
+        ]
+        return RetrieveSummaryResult(
+            query=data.get("query", query),
+            summary=data.get("summary", ""),
+            supporting_memories=memories,
+        )
+
+    def list_memories(self, user_id: str, query: str, top_k: int = 10) -> RetrieveResult:
+        """List user memories across all sessions.
+
+        Args:
+            user_id: User ID.
+            query: Search query text.
+            top_k: Maximum number of results (1-50). Defaults to 10.
+
+        Returns:
+            RetrieveResult with matching memories across all sessions.
+        """
+        data = self._handle_response(
+            self._client.get("/memories", params={
+                "user_id": user_id,
+                "query": query,
+                "top_k": top_k,
+                **self._credential_params(),
+            })
+        )
+        memories = [
+            Memory(memory_id=m["memory_id"], fact=m["fact"], score=m["score"])
+            for m in data.get("memories", [])
+        ]
+        return RetrieveResult(
+            query=data.get("query", query),
+            expanded_query=data.get("expanded_query", ""),
+            memories=memories,
+        )
+
+    # ── Maintenance & Governance ────────────────────────────────────────
+
+    def run_maintenance(self, user_id: str = "") -> dict:
+        """Manually trigger all maintenance tasks (decay, forgetting, summarization).
+
+        Args:
+            user_id: Optional user ID to scope maintenance. Empty string for all users.
+
+        Returns:
+            Dict with job results for each maintenance task.
+        """
+        return self._handle_response(
+            self._client.post("/memory/governance/run-all", params={"user_id": user_id})
+        )
+
+    # ── System ──────────────────────────────────────────────────────────
+
+    def delete_all_memories(self, confirm: str = "DELETE_ALL_DATA") -> dict:
+        """Delete ALL memories from ALL users. Destructive and irreversible.
+
+        Args:
+            confirm: Must be exactly "DELETE_ALL_DATA" to confirm.
+
+        Returns:
+            Dict with status, message, and count of deleted memories.
+        """
+        return self._handle_response(
+            self._client.delete("/memory/all", params={"confirm": confirm, **self._credential_params()})
+        )
+
+    def scheduler_status(self) -> dict:
+        """Get current status of the maintenance scheduler.
+
+        Returns:
+            Dict with registered jobs, next run times, and recent history.
+        """
+        return self._handle_response(self._client.get("/scheduler/status"))
+
+    def health(self) -> HealthResult:
+        """Check API health and status.
+
+        Returns:
+            HealthResult with status, version, architecture, and scheduler info.
+        """
+        data = self._handle_response(self._client.get("/health"))
+        return HealthResult(
+            status=data.get("status", ""),
+            version=data.get("version", ""),
+            architecture=data.get("architecture", ""),
+            scheduler=data.get("scheduler", {}),
+        )
+
+    # ── Context Manager ─────────────────────────────────────────────────
+
+    def close(self):
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

cognitivememory/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions for the Cognitive Memory SDK."""
+
+
+class CognitiveMemoryError(Exception):
+    """Base exception for all SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, response: dict | None = None):
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        super().__init__(self.message)
+
+
+class AuthenticationError(CognitiveMemoryError):
+    """Raised when authentication fails (401/403)."""
+
+
+class NotFoundError(CognitiveMemoryError):
+    """Raised when a resource is not found (404)."""
+
+
+class ValidationError(CognitiveMemoryError):
+    """Raised when the request is invalid (400/422)."""
+
+
+class ServerError(CognitiveMemoryError):
+    """Raised when the server returns a 5xx error."""

cognitivememory/models.py

@@ -0,0 +1,83 @@
+"""Response models for the Cognitive Memory SDK."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AddMemoryResult:
+    """Result of adding a memory."""
+    status: str
+    action: str
+    memory_id: str | None
+    links_created: int
+    score: float
+
+
+@dataclass
+class Memory:
+    """A retrieved memory."""
+    memory_id: str
+    fact: str
+    score: float
+
+
+@dataclass
+class DetailedMemory:
+    """A retrieved memory with detailed scoring breakdown."""
+    memory_id: str
+    fact: str
+    domain: str
+    final_score: float
+    semantic_similarity: float
+    graph_relevance: float
+    memory_strength: float
+    recency_score: float
+    session_boost: float
+    source: str
+    session_id: str
+
+
+@dataclass
+class RetrieveResult:
+    """Result of a simple retrieval."""
+    query: str
+    expanded_query: str
+    memories: list[Memory]
+
+
+@dataclass
+class DetailedRetrieveResult:
+    """Result of an advanced retrieval with full scoring details."""
+    query: str
+    expanded_query: str
+    user_id: str
+    session_id: str
+    memories: list[DetailedMemory]
+    total_candidates: int
+    filtered_count: int
+    retrieval_time_ms: float
+
+
+@dataclass
+class RetrieveSummaryResult:
+    """Result of a retrieval with LLM summary."""
+    query: str
+    summary: str
+    supporting_memories: list[Memory]
+
+
+@dataclass
+class DeleteResult:
+    """Result of a delete operation."""
+    status: str
+    user_id: str
+    memories_deleted: int
+
+
+@dataclass
+class HealthResult:
+    """Health check result."""
+    status: str
+    version: str
+    architecture: str
+    scheduler: dict

comemo-2.0.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: comemo
+Version: 2.0.0
+Summary: Python SDK for Cognitive Memory
+Project-URL: Homepage, https://github.com/hasala/cognitive-memory-sdk
+Project-URL: Documentation, https://github.com/hasala/cognitive-memory-sdk#readme
+Project-URL: Issues, https://github.com/hasala/cognitive-memory-sdk/issues
+Author: Hasala
+License-Expression: MIT
+Keywords: ai,cognitive,memory,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# Cognitive Memory SDK
+
+Python SDK for Cognitive Memory — a multi-module hybrid memory system powered by Pinecone and Neo4j.
+
+## Installation
+
+```bash
+pip install comemo
+```
+
+## Quick Start
+
+```python
+from cognitivememory import MemoryClient
+
+client = MemoryClient(
+    api_key="sk-your-openai-key",
+    model="gpt-4o-mini",
+    pinecone_api_key="your-pinecone-key",
+    neo4j_uri="neo4j+s://your-instance.databases.neo4j.io",
+    neo4j_user="neo4j",
+    neo4j_password="your-neo4j-password",
+)
+```
+
+### Core Memory
+
+```python
+# Add a memory
+result = client.add_memory("john", "chat_01", "I work at Google as a software engineer")
+print(result.status)     # "success"
+print(result.action)     # "NEW"
+print(result.memory_id)  # "mem_abc123"
+
+# Clear all user memories
+client.delete_user_memories("john")
+
+# Clear session memories
+client.delete_session_memories("john", "chat_01")
+
+# Delete a single memory
+client.delete_memory("mem_abc123")
+```
+
+### Retrieval
+
+```python
+# Retrieve memories with graph expansion
+result = client.retrieve_advanced(
+    user_id="john",
+    session_id="chat_01",
+    query="career and hobbies",
+    top_k=10,
+    expand_context=True,
+    expand_graph=True,
+    min_score=0.3,
+    reinforce=True
+)
+for m in result.memories:
+    print(f"{m.fact} | semantic={m.semantic_similarity:.2f} graph={m.graph_relevance:.2f}")
+
+# List user memories
+result = client.list_memories("john", query="work", top_k=10)
+for m in result.memories:
+    print(f"{m.fact} (score: {m.score:.2f})")
+
+# Simple retrieve
+result = client.retrieve("john", "chat_01", "Where does John work?", top_k=5)
+for m in result.memories:
+    print(f"{m.fact} (score: {m.score:.2f})")
+
+# Retrieve with summary
+summary = client.retrieve_summary("john", "chat_01", "Tell me about John's career")
+print(summary.summary)
+for m in summary.supporting_memories:
+    print(f"  - {m.fact}")
+```
+
+### Maintenance & Governance
+
+```python
+# Run all maintenance tasks
+result = client.run_maintenance(user_id="john")
+```
+
+### System
+
+```python
+# Clear all memory
+client.delete_all_memories(confirm="DELETE_ALL_DATA")
+
+# Get scheduler status
+status = client.scheduler_status()
+
+# Health check
+health = client.health()
+print(health.status)   # "healthy"
+print(health.version)  # "5.1.0"
+```
+
+## Context Manager
+
+```python
+with MemoryClient(
+    api_key="sk-your-openai-key",
+    model="gpt-4o-mini",
+    pinecone_api_key="your-pinecone-key",
+    neo4j_uri="neo4j+s://your-instance.databases.neo4j.io",
+    neo4j_user="neo4j",
+    neo4j_password="your-neo4j-password",
+) as client:
+    client.add_memory("john", "chat_01", "My favorite color is blue")
+```
+
+## Error Handling
+
+```python
+from cognitivememory import MemoryClient, ValidationError, NotFoundError
+
+try:
+    client.retrieve("john", "chat_01", "")
+except ValidationError as e:
+    print(f"Bad request: {e.message}")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+```
+
+## All Methods
+
+### Core Memory
+
+| Method | Description |
+|---|---|
+| `add_memory(user_id, session_id, text)` | Add Memory |
+| `delete_user_memories(user_id)` | Clear User Memory |
+| `delete_session_memories(user_id, session_id)` | Clear Session Memory |
+| `delete_memory(memory_id)` | Delete Single Memory |
+
+### Retrieval
+
+| Method | Description |
+|---|---|
+| `retrieve_advanced(user_id, session_id, query, ...)` | Retrieve Memories |
+| `list_memories(user_id, query, top_k=10)` | List User Memories |
+| `retrieve(user_id, session_id, query, top_k=5)` | Simple Retrieve Memories |
+| `retrieve_summary(user_id, session_id, query, top_k=5)` | Retrieve With Summary |
+
+### Maintenance & Governance
+
+| Method | Description |
+|---|---|
+| `run_maintenance(user_id="")` | Run All Maintenance |
+
+### System
+
+| Method | Description |
+|---|---|
+| `delete_all_memories(confirm)` | Clear All Memory |
+| `scheduler_status()` | Get Scheduler Status |
+| `health()` | Health Check |
+
+## License
+
+MIT

comemo-2.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+cognitivememory/__init__.py,sha256=Fgh45ucvYK9FQKCa02zbbb1FKWeJ-A0Z5Jq2TqK-3SY,787
+cognitivememory/client.py,sha256=43Sfa9e9TrR9gXnlJn0tUsqIRXKXuiKcplrO5BCDHB8,15078
+cognitivememory/exceptions.py,sha256=FcJpqq3POiX4iSGQJlt8dbCvlDOmt0pqsPmopfV9nyI,779
+cognitivememory/models.py,sha256=KMlXMGOauCeb42Cyt0l0PzxIlyi65SOD1xQUsx42qrQ,1581
+comemo-2.0.0.dist-info/METADATA,sha256=62GO2OWNPiZJaWPFJwP2NDc1sbjCPoNja1tiMt4xR2Y,4849
+comemo-2.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+comemo-2.0.0.dist-info/RECORD,,

comemo-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any