cuemap 0.4.1__py3-none-any.whl

cuemap/__init__.py

@@ -0,0 +1,33 @@
+"""
+CueMap: Redis for AI Agents
+
+A high-performance, temporal-associative memory store.
+You give us the cues, we give you the right memory at the right time.
+
+Example:
+    >>> from cuemap import CueMap
+    >>> 
+    >>> client = CueMap()
+    >>> 
+    >>> # Add a memory with cues
+    >>> client.add("The server password is abc123", cues=["server", "password"])
+    >>> 
+    >>> # Recall by cues
+    >>> results = client.recall(["server", "password"])
+    >>> print(results[0].content)
+"""
+
+from .client import CueMap, AsyncCueMap
+from .models import Memory, RecallResult
+from .exceptions import CueMapError, ConnectionError, AuthenticationError
+
+__version__ = "0.2.0"
+__all__ = [
+    "CueMap",
+    "AsyncCueMap",
+    "Memory",
+    "RecallResult",
+    "CueMapError",
+    "ConnectionError",
+    "AuthenticationError",
+]

cuemap/client.py

@@ -0,0 +1,336 @@
+"""Pure CueMap client - no magic, just speed."""
+
+import httpx
+from typing import List, Optional, Dict, Any
+
+from .models import Memory, RecallResult
+from .exceptions import CueMapError, ConnectionError, AuthenticationError
+
+
+class CueMap:
+    """
+    Pure CueMap client.
+    
+    No auto-cue extraction. No semantic matching. Just fast memory storage.
+    
+    Example:
+        >>> client = CueMap()
+        >>> client.add("Important note", cues=["work", "urgent"])
+        >>> results = client.recall(["work"])
+    """
+    
+    def __init__(
+        self,
+        url: str = "http://localhost:8080",
+        api_key: Optional[str] = None,
+        project_id: Optional[str] = None,
+        timeout: float = 30.0
+    ):
+        """
+        Initialize CueMap client.
+        
+        Args:
+            url: CueMap server URL
+            api_key: Optional API key for authentication
+            project_id: Optional project ID for multi-tenancy
+            timeout: Request timeout in seconds
+        """
+        self.url = url
+        self.api_key = api_key
+        self.project_id = project_id
+        
+        self.client = httpx.Client(
+            base_url=url,
+            timeout=timeout
+        )
+    
+    def _headers(self) -> Dict[str, str]:
+        """Get request headers."""
+        headers = {}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        if self.project_id:
+            headers["X-Project-ID"] = self.project_id
+        return headers
+    
+    def add(
+        self,
+        content: str,
+        cues: List[str],
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """
+        Add a memory.
+        
+        Args:
+            content: Memory content
+            cues: List of cues (tags) for retrieval
+            metadata: Optional metadata
+            
+        Returns:
+            Memory ID
+            
+        Example:
+            >>> client.add(
+            ...     "Meeting with John at 3pm",
+            ...     cues=["meeting", "john", "calendar"]
+            ... )
+        """
+        response = self.client.post(
+            "/memories",
+            json={
+                "content": content,
+                "cues": cues,
+                "metadata": metadata or {}
+            },
+            headers=self._headers()
+        )
+        
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API key")
+        elif response.status_code != 200:
+            raise CueMapError(f"Failed to add memory: {response.status_code}")
+        
+        return response.json()["id"]
+    
+    def recall(
+        self,
+        cues: List[str],
+        limit: int = 10,
+        auto_reinforce: bool = False,
+        min_intersection: Optional[int] = None,
+        projects: Optional[List[str]] = None
+    ) -> List[RecallResult]:
+        """
+        Recall memories by cues.
+        
+        Args:
+            cues: List of cues to search for
+            limit: Maximum results to return
+            auto_reinforce: Automatically reinforce retrieved memories
+            min_intersection: Minimum number of cues that must match (for strict AND logic)
+            projects: List of project IDs for cross-domain queries (multi-tenant only)
+            
+        Returns:
+            List of recall results
+            
+        Example:
+            >>> # OR logic (default): matches any cue
+            >>> results = client.recall(["meeting", "john"])
+            
+            >>> # AND logic: requires both cues
+            >>> results = client.recall(["meeting", "john"], min_intersection=2)
+            
+            >>> # Cross-domain query (multi-tenant)
+            >>> results = client.recall(["urgent"], projects=["sales", "support"])
+        """
+        payload = {
+            "cues": cues,
+            "limit": limit,
+            "auto_reinforce": auto_reinforce
+        }
+        
+        if min_intersection is not None:
+            payload["min_intersection"] = min_intersection
+        
+        if projects is not None:
+            payload["projects"] = projects
+        
+        response = self.client.post(
+            "/recall",
+            json=payload,
+            headers=self._headers()
+        )
+        
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to recall: {response.status_code}")
+        
+        results = response.json()["results"]
+        return [RecallResult(**r) for r in results]
+    
+    def reinforce(self, memory_id: str, cues: List[str]) -> bool:
+        """
+        Reinforce a memory on specific cue pathways.
+        
+        Args:
+            memory_id: Memory ID
+            cues: Cues to reinforce on
+            
+        Returns:
+            Success status
+        """
+        response = self.client.patch(
+            f"/memories/{memory_id}/reinforce",
+            json={"cues": cues},
+            headers=self._headers()
+        )
+        
+        return response.status_code == 200
+    
+    def get(self, memory_id: str) -> Memory:
+        """Get a memory by ID."""
+        response = self.client.get(
+            f"/memories/{memory_id}",
+            headers=self._headers()
+        )
+        
+        if response.status_code == 404:
+            raise CueMapError(f"Memory not found: {memory_id}")
+        elif response.status_code != 200:
+            raise CueMapError(f"Failed to get memory: {response.status_code}")
+        
+        return Memory(**response.json())
+    
+    def stats(self) -> Dict[str, Any]:
+        """Get server statistics."""
+        response = self.client.get(
+            "/stats",
+            headers=self._headers()
+        )
+        
+        return response.json()
+    
+    def close(self):
+        """Close the client."""
+        self.client.close()
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+class AsyncCueMap:
+    """
+    Async CueMap client.
+    
+    Example:
+        >>> async with AsyncCueMap() as client:
+        ...     await client.add("Note", cues=["work"])
+        ...     results = await client.recall(["work"])
+    """
+    
+    def __init__(
+        self,
+        url: str = "http://localhost:8080",
+        api_key: Optional[str] = None,
+        project_id: Optional[str] = None,
+        timeout: float = 30.0
+    ):
+        self.url = url
+        self.api_key = api_key
+        self.project_id = project_id
+        
+        self.client = httpx.AsyncClient(
+            base_url=url,
+            timeout=timeout
+        )
+    
+    def _headers(self) -> Dict[str, str]:
+        headers = {}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        if self.project_id:
+            headers["X-Project-ID"] = self.project_id
+        return headers
+    
+    async def add(
+        self,
+        content: str,
+        cues: List[str],
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """Add a memory (async)."""
+        response = await self.client.post(
+            "/memories",
+            json={
+                "content": content,
+                "cues": cues,
+                "metadata": metadata or {}
+            },
+            headers=self._headers()
+        )
+        
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API key")
+        elif response.status_code != 200:
+            raise CueMapError(f"Failed to add memory: {response.status_code}")
+        
+        return response.json()["id"]
+    
+    async def recall(
+        self,
+        cues: List[str],
+        limit: int = 10,
+        auto_reinforce: bool = False,
+        min_intersection: Optional[int] = None,
+        projects: Optional[List[str]] = None
+    ) -> List[RecallResult]:
+        """Recall memories (async)."""
+        payload = {
+            "cues": cues,
+            "limit": limit,
+            "auto_reinforce": auto_reinforce
+        }
+        
+        if min_intersection is not None:
+            payload["min_intersection"] = min_intersection
+        
+        if projects is not None:
+            payload["projects"] = projects
+        
+        response = await self.client.post(
+            "/recall",
+            json=payload,
+            headers=self._headers()
+        )
+        
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to recall: {response.status_code}")
+        
+        results = response.json()["results"]
+        return [RecallResult(**r) for r in results]
+    
+    async def reinforce(self, memory_id: str, cues: List[str]) -> bool:
+        """Reinforce a memory (async)."""
+        response = await self.client.patch(
+            f"/memories/{memory_id}/reinforce",
+            json={"cues": cues},
+            headers=self._headers()
+        )
+        
+        return response.status_code == 200
+    
+    async def get(self, memory_id: str) -> Memory:
+        """Get a memory by ID (async)."""
+        response = await self.client.get(
+            f"/memories/{memory_id}",
+            headers=self._headers()
+        )
+        
+        if response.status_code == 404:
+            raise CueMapError(f"Memory not found: {memory_id}")
+        elif response.status_code != 200:
+            raise CueMapError(f"Failed to get memory: {response.status_code}")
+        
+        return Memory(**response.json())
+    
+    async def stats(self) -> Dict[str, Any]:
+        """Get server statistics (async)."""
+        response = await self.client.get(
+            "/stats",
+            headers=self._headers()
+        )
+        
+        return response.json()
+    
+    async def close(self):
+        """Close the client."""
+        await self.client.aclose()
+    
+    async def __aenter__(self):
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

cuemap/exceptions.py

@@ -0,0 +1,16 @@
+"""Exceptions."""
+
+
+class CueMapError(Exception):
+    """Base exception."""
+    pass
+
+
+class ConnectionError(CueMapError):
+    """Connection failed."""
+    pass
+
+
+class AuthenticationError(CueMapError):
+    """Authentication failed."""
+    pass

cuemap/models.py

@@ -0,0 +1,25 @@
+"""Data models."""
+
+from typing import Dict, List, Any
+from pydantic import BaseModel, Field
+
+
+class Memory(BaseModel):
+    """A memory object."""
+    
+    id: str
+    content: str
+    cues: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class RecallResult(BaseModel):
+    """Result from a recall operation."""
+    
+    memory_id: str
+    content: str
+    score: float
+    intersection_count: int
+    recency_score: float
+    reinforcement_score: float
+    metadata: Dict[str, Any] = Field(default_factory=dict)

cuemap-0.4.1.dist-info/METADATA

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: cuemap
+Version: 0.4.1
+Summary: Redis for AI Agents - High-performance temporal-associative memory
+Author-email: CueMap Team <hello@cuemap.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/cuemap-dev/sdks
+Project-URL: Documentation, https://github.com/cuemap-dev/sdks/blob/main/python/README.md
+Project-URL: Repository, https://github.com/cuemap-dev/sdks
+Project-URL: Issues, https://github.com/cuemap-dev/sdks/issues
+Project-URL: Engine, https://github.com/cuemap-dev/engine
+Keywords: ai,memory,agents,redis,temporal,associative,llm,rag
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# CueMap: Redis for AI Agents
+
+**High-performance, temporal-associative memory store.**
+
+You give us the cues, we give you the right memory at the right time.
+
+## Why CueMap?
+
+Redis doesn't auto-serialize your data. It doesn't guess what you mean. It just stores keys and values **blazing fast**.
+
+CueMap is the same philosophy for AI agent memory:
+- ✅ **You control the cues** (tags)
+- ✅ **We handle the speed** (sub-millisecond)
+- ✅ **No magic** (predictable behavior)
+- ✅ **No dependencies** (5KB SDK)
+
+## Installation
+
+```bash
+pip install cuemap
+```
+
+That's it. No ML models. No transformers. Just pure speed.
+
+## Quick Start
+
+### 1. Start the Engine
+
+```bash
+docker run -p 8080:8080 cuemap/engine:latest
+```
+
+### 2. Use the SDK
+
+```python
+from cuemap import CueMap
+
+client = CueMap()
+
+# Add a memory with cues
+client.add(
+    "The server password is abc123",
+    cues=["server", "password", "credentials"]
+)
+
+# Recall by cues
+results = client.recall(["server", "password"])
+print(results[0].content)
+# Output: "The server password is abc123"
+```
+
+## Core API
+
+### Add Memory
+
+```python
+memory_id = client.add(
+    content="Meeting with John at 3pm",
+    cues=["meeting", "john", "calendar", "today"]
+)
+```
+
+### Recall Memories
+
+```python
+# OR logic (default): matches any cue
+results = client.recall(
+    cues=["meeting", "john"],
+    limit=10
+)
+
+for result in results:
+    print(f"{result.content} (score: {result.score})")
+
+# AND logic: requires all cues to match
+results = client.recall(
+    cues=["meeting", "john"],
+    min_intersection=2  # Both cues must match
+)
+
+# Cross-domain query (multi-tenant mode)
+results = client.recall(
+    cues=["urgent"],
+    projects=["sales", "support", "engineering"]
+)
+```
+
+### Reinforce Memory
+
+```python
+# Make a memory more accessible
+client.reinforce(memory_id, cues=["important", "urgent"])
+```
+
+## How It Works
+
+### Temporal-Associative Retrieval
+
+CueMap uses **Iterative Deepening Intersection**:
+
+1. **Intersection**: Memories matching multiple cues rank higher
+2. **Recency**: Recent memories are more accessible
+3. **Reinforcement**: Frequently accessed memories stay "front of mind"
+
+```python
+# Add memories
+client.add("Pizza recipe", cues=["food", "italian"])
+client.add("Pasta recipe", cues=["food", "italian"])
+client.add("Sushi recipe", cues=["food", "japanese"])
+
+# Query with multiple cues
+results = client.recall(["food", "italian"])
+# Returns: Pizza and Pasta (both match 2 cues)
+# Sushi is filtered out (only matches 1 cue)
+```
+
+### Performance (~1M memories)
+
+- **Write P99**: 0.33ms
+- **Read P99**: 0.37ms
+- **Throughput**: 2,900+ ops/sec
+- **Accuracy**: 100% (validated on 120 test scenarios)
+
+## Recipes
+
+### Recipe 1: Use with OpenAI
+
+```python
+from cuemap import CueMap
+import openai
+
+client = CueMap()
+
+def store_with_ai_tags(content: str):
+    # Let OpenAI extract the cues
+    response = openai.chat.completions.create(
+        model="gpt-4",
+        messages=[{
+            "role": "system",
+            "content": "Extract 3-5 search tags from the text. Return as JSON array."
+        }, {
+            "role": "user",
+            "content": content
+        }]
+    )
+    
+    cues = response.choices[0].message.content  # ["tag1", "tag2", ...]
+    
+    # Store in CueMap
+    return client.add(content, cues=cues)
+
+# Usage
+store_with_ai_tags("I need to buy groceries this weekend")
+# OpenAI extracts: ["shopping", "groceries", "weekend", "todo"]
+```
+
+### Recipe 2: Use with LangChain
+
+```python
+from cuemap import CueMap
+from langchain.memory import BaseMemory
+
+class CueMapMemory(BaseMemory):
+    def __init__(self, cue_extractor):
+        self.client = CueMap()
+        self.extract_cues = cue_extractor
+    
+    def save_context(self, inputs, outputs):
+        context = f"User: {inputs['input']}\nAI: {outputs['output']}"
+        cues = self.extract_cues(context)
+        self.client.add(context, cues=cues)
+    
+    def load_memory_variables(self, inputs):
+        cues = self.extract_cues(inputs['input'])
+        results = self.client.recall(cues, limit=5)
+        return {"history": "\n".join([r.content for r in results])}
+```
+
+### Recipe 3: Manual Cues (Production)
+
+```python
+# For production: explicit, predictable cues
+client.add(
+    "Deploy command: kubectl apply -f deployment.yaml",
+    cues=["deployment", "kubernetes", "commands", "devops"]
+)
+
+client.add(
+    "API endpoint: https://api.example.com/v1/users",
+    cues=["api", "endpoint", "users", "documentation"]
+)
+
+# Query with specific cues
+client.recall(["deployment", "kubernetes"])
+client.recall(["api", "users"])
+```
+
+## Running the Engine
+
+CueMap requires a running engine. Choose your deployment:
+
+### Option 1: Docker (Recommended)
+
+```bash
+docker run -p 8080:8080 cuemap/engine:latest
+```
+
+### Option 2: From Source
+
+```bash
+git clone https://github.com/cuemap-dev/engine
+cd engine
+cargo build --release
+./target/release/cuemap-rust --port 8080
+```
+
+## Configuration
+
+### Connect to Engine
+
+```python
+# Default (localhost)
+client = CueMap()
+
+# Custom URL
+client = CueMap(url="http://your-server:8080")
+
+# With authentication
+client = CueMap(
+    url="http://your-server:8080",
+    api_key="your-secret-key"
+)
+```
+
+### Multi-tenancy
+
+```python
+# Use project isolation
+client = CueMap(
+    url="http://your-server:8080",
+    project_id="my-project"
+)
+```
+
+### Async Support
+
+```python
+from cuemap import AsyncCueMap
+
+async with AsyncCueMap() as client:
+    await client.add("Note", cues=["work"])
+    results = await client.recall(["work"])
+```
+
+## Philosophy
+
+### What CueMap Does
+
+✅ **Fast storage** - Sub-millisecond retrieval
+✅ **Temporal ordering** - Recent memories prioritized
+✅ **Intersection scoring** - Multi-cue matching
+✅ **Reinforcement** - Move-to-front operation
+
+### What CueMap Doesn't Do
+
+❌ **Auto-tagging** - You provide the cues
+❌ **Semantic search** - Use your own embeddings
+❌ **LLM integration** - Bring your own model
+❌ **Magic** - Explicit and predictable
+
+## Why This Approach?
+
+**Redis Philosophy**: Don't guess what the user wants. Provide primitives. Let them build.
+
+**CueMap Philosophy**: Don't auto-extract cues. Don't auto-embed. Just store and retrieve **fast**.
+
+**Benefits**:
+- 🚀 **5KB SDK** (vs 500MB with ML models)
+- ⚡ **Instant install** (1 second vs 5 minutes)
+- 🎯 **Predictable** (no ML black boxes)
+- 🔧 **Flexible** (works with any LLM/embedding model)
+
+## Comparison
+
+| Feature | CueMap | Vector DBs |
+|---------|--------|------------|
+| **Speed** | 0.37ms P99 | 200-500ms |
+| **SDK Size** | 5KB | 500MB+ |
+| **Dependencies** | 2 | 50+ |
+| **Install Time** | 1 sec | 5 min |
+| **Cue Control** | Explicit | Auto (black box) |
+| **Temporal** | ✅ Built-in | ❌ None |
+
+## Documentation
+
+- [Engine Repository](https://github.com/cuemap-dev/engine)
+- [SDKs Repository](https://github.com/cuemap-dev/sdks)
+- [Examples](https://github.com/cuemap-dev/sdks/tree/main/python/examples)
+
+## License
+
+MIT

cuemap-0.4.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+cuemap/__init__.py,sha256=jy_21twtKaRLJq2AunVstNgFCIfe8QCjPpH5quxTz3c,817
+cuemap/client.py,sha256=HzLzPAYjHKPVJstBIH7G3QNZ3k_D5Obt_hPLKJPQ3rw,9819
+cuemap/exceptions.py,sha256=LPwk-pXDBWP-aA1m6w9BNqfM-zmT3-ZPZcyXdPDE9PE,245
+cuemap/models.py,sha256=YgnKNtWJLad_s02koDhCSbqdm1MuN7cp_ih98J6gojY,566
+cuemap-0.4.1.dist-info/licenses/LICENSE,sha256=XroXVr5iCchm6KhTUtnrjVAhcErBwmvhl7EwcjeI_yI,1063
+cuemap-0.4.1.dist-info/METADATA,sha256=v1VekU6uNZWyIwfB2gBIFLJNtGr1UZsDo2yLuC4ShXU,8461
+cuemap-0.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cuemap-0.4.1.dist-info/top_level.txt,sha256=bZ0CmDM_glT73Eeo0pHCyjpEThjesQ0Zx9r3D4_N9LU,7
+cuemap-0.4.1.dist-info/RECORD,,

cuemap-0.4.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cuemap-0.4.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CueMap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cuemap-0.4.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cuemap