cuemap 0.6.1__tar.gz

cuemap-0.6.1/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.6.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include cuemap *.py
+recursive-include examples *.py
+prune tests
+prune __pycache__
+global-exclude *.pyc

cuemap-0.6.1/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: cuemap
+Version: 0.6.1
+Summary: CueMap Python SDK - 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,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 Python SDK
+
+**High-performance temporal-associative memory store** that mimics the brain's recall mechanism.
+
+## Overview
+
+CueMap implements a **Continuous Gradient Algorithm** inspired by biological memory:
+
+1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
+2.  **Pattern Completion (Associative Recall)**: Automatically infers missing cues from co-occurrence history, enabling recall from partial inputs.
+3.  **Recency & Salience (Signal Dynamics)**: Balances fresh data with salient, high-signal events prioritized by the Amygdala-inspired salience module.
+4.  **Reinforcement (Hebbian Learning)**: Frequently accessed memories gain signal strength, staying "front of mind".
+5.  **Autonomous Consolidation**: Periodically merges overlapping memories into summaries, mimicking systems consolidation.
+
+## Installation
+
+```bash
+pip install cuemap
+```
+
+## Quick Start
+
+### 1. Start the Engine
+
+```bash
+docker run -p 8080:8080 cuemap/engine:latest
+```
+
+### 2. Basic Usage
+
+```python
+from cuemap import CueMap
+
+client = CueMap()
+
+# Add a memory (auto-cue generation by default using internal Semantic Engine)
+client.add("The server password is abc123")
+
+# Recall by natural language (resolves via Lexicon)
+results = client.recall("server credentials")
+print(results[0].content)
+# Output: "The server password is abc123"
+```
+
+## Core API
+
+### Add Memory
+
+```python
+# Manual cues
+client.add(
+    "Meeting with John at 3pm",
+    cues=["meeting", "john", "calendar"]
+)
+
+# Auto-cues (Semantic Engine)
+client.add("The payments service is down due to a timeout")
+```
+
+### Recall Memories
+
+```python
+# Natural Language Search (Brain-Inspired)
+results = client.recall(
+    "payments failure",
+    limit=10,
+    explain=True # See how the query was expanded
+)
+
+print(results[0].explain)
+# Shows normalized cues, expanded synonyms, etc.
+
+# Explicit Cue Search
+results = client.recall(
+    cues=["meeting", "john"],
+    min_intersection=2
+)
+```
+
+### Grounded Recall (Hallucination Guardrails)
+
+Get verifiable context for LLMs with a strict token budget.
+
+```python
+response = client.recall_grounded(
+    query="Why is the payment failing?",
+    token_budget=500
+)
+
+print(response["verified_context"])
+# [VERIFIED CONTEXT] ...
+print(response["proof"])
+# Cryptographic proof of context retrieval
+```
+
+### Context Expansion (v0.6.1)
+
+Explore related concepts from the cue graph to expand a user's query.
+
+```python
+response = client.context_expand("server hung 137", limit=5)
+# {
+#   "query_cues": ["server", "hung", "137"],
+#   "expansions": [
+#     { "term": "out_of_memory", "score": 25.0, "co_occurrence_count": 12 },
+#     { "term": "SIGKILL", "score": 22.0, "co_occurrence_count": 8 }
+#   ]
+# }
+```
+
+### Cloud Backup (v0.6.1)
+
+Manage project snapshots in the cloud (S3, GCS, Azure).
+
+```python
+# Upload current project snapshot
+client.backup_upload("default")
+
+# Download and restore snapshot
+client.backup_download("default")
+
+# List available backups
+backups = client.backup_list()
+```
+
+### Ingestion (v0.6+)
+
+Ingest content from various sources directly.
+
+```python
+# Ingest URL
+client.ingest_url("https://example.com/docs")
+
+# Ingest File (PDF, DOCX, etc.)
+client.ingest_file("/path/to/document.pdf")
+
+# Ingest Raw Content
+client.ingest_content("Raw text content...", filename="notes.txt")
+```
+
+### Lexicon Management (v0.6+)
+
+Inspect and wire the brain's associations manually.
+
+```python
+# Inspect a cue's relationships
+data = client.lexicon_inspect("service:payment")
+print(f"Synonyms: {data['outgoing']}")
+print(f"Triggers: {data['incoming']}")
+
+# Manually wire a token to a concept
+client.lexicon_wire("stripe", "service:payment")
+
+# Get synonyms via WordNet
+synonyms = client.lexicon_synonyms("payment")
+```
+
+### Job Status (v0.6+)
+
+Check the progress of background ingestion tasks.
+
+```python
+status = client.jobs_status()
+print(f"Ingested: {status['writes_completed']} / {status['writes_total']}")
+```
+
+### Advanced Brain Control
+
+Disable specific brain modules for deterministic debugging.
+
+```python
+results = client.recall(
+    "urgent issue",
+    disable_pattern_completion=True,    # No associative inference
+    disable_salience_bias=True,         # No emotional weighting
+    disable_systems_consolidation=True, # No gist summaries
+    disable_temporal_chunking=True      # No episodic grouping
+)
+```
+
+## Async Support
+
+```python
+from cuemap import AsyncCueMap
+
+async with AsyncCueMap() as client:
+    await client.add("Note")
+    await client.recall(["note"])
+```
+
+## Performance
+
+- **Write Latency**: ~2ms (O(1) complexity)
+- **Read Latency**: ~5-10ms (Raw vs Smart Recall)
+
+## License
+
+MIT

cuemap-0.6.1/README.md

@@ -0,0 +1,198 @@
+# CueMap Python SDK
+
+**High-performance temporal-associative memory store** that mimics the brain's recall mechanism.
+
+## Overview
+
+CueMap implements a **Continuous Gradient Algorithm** inspired by biological memory:
+
+1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
+2.  **Pattern Completion (Associative Recall)**: Automatically infers missing cues from co-occurrence history, enabling recall from partial inputs.
+3.  **Recency & Salience (Signal Dynamics)**: Balances fresh data with salient, high-signal events prioritized by the Amygdala-inspired salience module.
+4.  **Reinforcement (Hebbian Learning)**: Frequently accessed memories gain signal strength, staying "front of mind".
+5.  **Autonomous Consolidation**: Periodically merges overlapping memories into summaries, mimicking systems consolidation.
+
+## Installation
+
+```bash
+pip install cuemap
+```
+
+## Quick Start
+
+### 1. Start the Engine
+
+```bash
+docker run -p 8080:8080 cuemap/engine:latest
+```
+
+### 2. Basic Usage
+
+```python
+from cuemap import CueMap
+
+client = CueMap()
+
+# Add a memory (auto-cue generation by default using internal Semantic Engine)
+client.add("The server password is abc123")
+
+# Recall by natural language (resolves via Lexicon)
+results = client.recall("server credentials")
+print(results[0].content)
+# Output: "The server password is abc123"
+```
+
+## Core API
+
+### Add Memory
+
+```python
+# Manual cues
+client.add(
+    "Meeting with John at 3pm",
+    cues=["meeting", "john", "calendar"]
+)
+
+# Auto-cues (Semantic Engine)
+client.add("The payments service is down due to a timeout")
+```
+
+### Recall Memories
+
+```python
+# Natural Language Search (Brain-Inspired)
+results = client.recall(
+    "payments failure",
+    limit=10,
+    explain=True # See how the query was expanded
+)
+
+print(results[0].explain)
+# Shows normalized cues, expanded synonyms, etc.
+
+# Explicit Cue Search
+results = client.recall(
+    cues=["meeting", "john"],
+    min_intersection=2
+)
+```
+
+### Grounded Recall (Hallucination Guardrails)
+
+Get verifiable context for LLMs with a strict token budget.
+
+```python
+response = client.recall_grounded(
+    query="Why is the payment failing?",
+    token_budget=500
+)
+
+print(response["verified_context"])
+# [VERIFIED CONTEXT] ...
+print(response["proof"])
+# Cryptographic proof of context retrieval
+```
+
+### Context Expansion (v0.6.1)
+
+Explore related concepts from the cue graph to expand a user's query.
+
+```python
+response = client.context_expand("server hung 137", limit=5)
+# {
+#   "query_cues": ["server", "hung", "137"],
+#   "expansions": [
+#     { "term": "out_of_memory", "score": 25.0, "co_occurrence_count": 12 },
+#     { "term": "SIGKILL", "score": 22.0, "co_occurrence_count": 8 }
+#   ]
+# }
+```
+
+### Cloud Backup (v0.6.1)
+
+Manage project snapshots in the cloud (S3, GCS, Azure).
+
+```python
+# Upload current project snapshot
+client.backup_upload("default")
+
+# Download and restore snapshot
+client.backup_download("default")
+
+# List available backups
+backups = client.backup_list()
+```
+
+### Ingestion (v0.6+)
+
+Ingest content from various sources directly.
+
+```python
+# Ingest URL
+client.ingest_url("https://example.com/docs")
+
+# Ingest File (PDF, DOCX, etc.)
+client.ingest_file("/path/to/document.pdf")
+
+# Ingest Raw Content
+client.ingest_content("Raw text content...", filename="notes.txt")
+```
+
+### Lexicon Management (v0.6+)
+
+Inspect and wire the brain's associations manually.
+
+```python
+# Inspect a cue's relationships
+data = client.lexicon_inspect("service:payment")
+print(f"Synonyms: {data['outgoing']}")
+print(f"Triggers: {data['incoming']}")
+
+# Manually wire a token to a concept
+client.lexicon_wire("stripe", "service:payment")
+
+# Get synonyms via WordNet
+synonyms = client.lexicon_synonyms("payment")
+```
+
+### Job Status (v0.6+)
+
+Check the progress of background ingestion tasks.
+
+```python
+status = client.jobs_status()
+print(f"Ingested: {status['writes_completed']} / {status['writes_total']}")
+```
+
+### Advanced Brain Control
+
+Disable specific brain modules for deterministic debugging.
+
+```python
+results = client.recall(
+    "urgent issue",
+    disable_pattern_completion=True,    # No associative inference
+    disable_salience_bias=True,         # No emotional weighting
+    disable_systems_consolidation=True, # No gist summaries
+    disable_temporal_chunking=True      # No episodic grouping
+)
+```
+
+## Async Support
+
+```python
+from cuemap import AsyncCueMap
+
+async with AsyncCueMap() as client:
+    await client.add("Note")
+    await client.recall(["note"])
+```
+
+## Performance
+
+- **Write Latency**: ~2ms (O(1) complexity)
+- **Read Latency**: ~5-10ms (Raw vs Smart Recall)
+
+## License
+
+MIT

cuemap-0.6.1/cuemap/__init__.py

@@ -0,0 +1,36 @@
+"""
+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
+from .grounding import CueMapGroundingRetriever, AsyncCueMapGroundingRetriever
+
+__version__ = "0.2.0"
+__all__ = [
+    "CueMap",
+    "AsyncCueMap",
+    "Memory",
+    "RecallResult",
+    "CueMapError",
+    "ConnectionError",
+    "AuthenticationError",
+    "CueMapGroundingRetriever",
+    "AsyncCueMapGroundingRetriever",
+]