comemo 1.0.0__tar.gz

comemo-1.0.0/.gitignore

@@ -0,0 +1,77 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Database
+chroma_db/
+*.db
+*.sqlite
+*.sqlite3
+
+# Graph files
+*.gpickle
+
+# Data
+data/
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+logs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+

comemo-1.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: comemo
+Version: 1.0.0
+Summary: Python SDK for CoMemo
+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
+
+# CoMemo SDK
+
+Python SDK for [CoMemo](https://github.com/hasala/cognitive-memory) — a multi-module hybrid memory system powered by Pinecone and Neo4j.
+
+## Installation
+
+```bash
+pip install comemo
+```
+
+## Quick Start
+
+```python
+from comemo import MemoryClient
+
+# Default (uses server-side LLM config)
+client = MemoryClient()
+
+# With your own LLM API key and model
+client = MemoryClient(
+    api_key="sk-your-openai-key",
+    model="gpt-4o-mini"
+)
+```
+
+### 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"
+```
+
+## Configuration
+
+```python
+# With LLM API key and model
+client = MemoryClient(api_key="sk-your-openai-key", model="gpt-4o-mini")
+```
+
+## Context Manager
+
+```python
+with MemoryClient() as client:
+    client.add_memory("john", "chat_01", "My favorite color is blue")
+```
+
+## Error Handling
+
+```python
+from comemo 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-1.0.0/README.md

@@ -0,0 +1,164 @@
+# CoMemo SDK
+
+Python SDK for [CoMemo](https://github.com/hasala/cognitive-memory) — a multi-module hybrid memory system powered by Pinecone and Neo4j.
+
+## Installation
+
+```bash
+pip install comemo
+```
+
+## Quick Start
+
+```python
+from comemo import MemoryClient
+
+# Default (uses server-side LLM config)
+client = MemoryClient()
+
+# With your own LLM API key and model
+client = MemoryClient(
+    api_key="sk-your-openai-key",
+    model="gpt-4o-mini"
+)
+```
+
+### 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"
+```
+
+## Configuration
+
+```python
+# With LLM API key and model
+client = MemoryClient(api_key="sk-your-openai-key", model="gpt-4o-mini")
+```
+
+## Context Manager
+
+```python
+with MemoryClient() as client:
+    client.add_memory("john", "chat_01", "My favorite color is blue")
+```
+
+## Error Handling
+
+```python
+from comemo 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-1.0.0/comemo/__init__.py

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

comemo-1.0.0/comemo/client.py

@@ -0,0 +1,383 @@
+"""CoMemo SDK client."""
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    ComemoError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    AddMemoryResult,
+    DeleteResult,
+    DetailedMemory,
+    DetailedRetrieveResult,
+    HealthResult,
+    Memory,
+    RetrieveResult,
+    RetrieveSummaryResult,
+)
+
+
+class MemoryClient:
+    """Client for the CoMemo API.
+
+    Args:
+        base_url: Base URL of the CoMemo API. Defaults to "https://xvert.io".
+        api_key: Optional LLM API key (e.g. OpenAI key). Sent with requests that use LLM.
+        model: Optional LLM model name (e.g. "gpt-4o-mini"). Sent with requests that use LLM.
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://xvert.io",
+        api_key: str | None = None,
+        model: str | None = None,
+        timeout: float = 30,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.timeout = timeout
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Content-Type": "application/json"},
+            timeout=timeout,
+        )
+
+    def _llm_fields(self) -> dict:
+        """Return api_key/model fields to include in request bodies."""
+        fields = {}
+        if self.api_key:
+            fields["api_key"] = self.api_key
+        if self.model:
+            fields["model"] = self.model
+        return fields
+
+    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 ComemoError(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._llm_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}")
+        )
+
+    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})
+        )
+        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})
+        )
+        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._llm_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._llm_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._llm_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,
+            })
+        )
+        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})
+        )
+
+    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()

comemo-1.0.0/comemo/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions for the CoMemo SDK."""
+
+
+class ComemoError(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(ComemoError):
+    """Raised when authentication fails (401/403)."""
+
+
+class NotFoundError(ComemoError):
+    """Raised when a resource is not found (404)."""
+
+
+class ValidationError(ComemoError):
+    """Raised when the request is invalid (400/422)."""
+
+
+class ServerError(ComemoError):
+    """Raised when the server returns a 5xx error."""

comemo-1.0.0/comemo/models.py

@@ -0,0 +1,83 @@
+"""Response models for the CoMemo 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-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "comemo"
+version = "1.0.0"
+description = "Python SDK for CoMemo"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Hasala" },
+]
+keywords = ["memory", "cognitive", "ai", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["comemo"]
+
+[project.urls]
+Homepage = "https://github.com/hasala/cognitive-memory-sdk"
+Documentation = "https://github.com/hasala/cognitive-memory-sdk#readme"
+Issues = "https://github.com/hasala/cognitive-memory-sdk/issues"