cuemap 0.7.0__tar.gz → 0.7.2__tar.gz

{cuemap-0.7.0/cuemap.egg-info → cuemap-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuemap
-Version: 0.7.0
+Version: 0.7.2
 Summary: CueMap Python SDK - High-performance temporal-associative memory
 Author-email: Kaan Demirel <hello@cuemap.dev>
 License: MIT
@@ -42,14 +42,14 @@ Dynamic: license-file
 CueMap implements a **Continuous Gradient Algorithm** optimized for associative data structures:
 
 1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
-2.  **CuePack-Guided Intent Routing**: Uses compiled deterministic rules to add structural facets and weighted intent cues without runtime model calls.
+2.  **Local semantic reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile, for bounded semantic ranking inside the engine.
 3.  **Recency & Salience (Signal Dynamics)**: Balances fresh data with salient, high-signal events prioritized by an adaptive impact scoring module.
 4.  **Reinforcement (Access-based Learning)**: Frequently accessed memories gain signal strength, remaining highly accessible even as they age.
 5.  **Deterministic Facets & Intent Routing**: Extracts synchronous source, evidence, temporal, type, and entity facets, then uses sparse intent cues and reranking during recall.
 
-As of v0.7.0, CueMap's core path is deterministic and embedding-free. GloVe/Ollama cue generation, WordNet/POS expansion, semantic bridges, pattern completion, external lexicon graphs, context expansion/speculation endpoints, and autonomous consolidation have been removed from the core engine.
+As of v0.7.2, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `all-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
 
-v0.7.0 also uses numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
+v0.7.2 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
 
 Use this SDK to talk to the Rust engine from Python applications.
 
@@ -134,9 +134,9 @@ print(response["proof"])
 # Cryptographic proof of context retrieval
 ```
 
-### v0.7 Recall Controls
+### v0.7.2 Recall Controls
 
-CueMap v0.7 adds temporal query intent, CueBridge artifact expansion, and optional reconstruction passes for longer conversational/codebase context.
+CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
 
 ```python
 results = client.recall(
@@ -145,11 +145,23 @@ results = client.recall(
     ordered_reconstruction="auto",
     evidence_coverage="auto",
     parent_fusion="auto",
-    cuepacks=["default"],
+    semantic_mode="hybrid",
     explain=True,
 )
 ```
 
+Use `semantic_mode="lexical"` for a semantic-reranker-disabled comparison, `"semantic"` for vector candidate discovery, or `"hybrid"` (the engine default) to rerank lexical candidates. `query_embedding` supplies a precomputed vector when the application owns the embedding provider.
+
+Classify query or memory intent with the same local engine model. Returned scores are ranking signals, not calibrated probabilities:
+
+```python
+classification = client.classify_intent(
+    "What did we decide about auth retries?",
+    target="query",
+)
+print(classification["primary_intent"], classification["recall_eligible"])
+```
+
 ### Cloud Backup (v0.6.1)
 
 Manage project snapshots in the cloud (S3, GCS, Azure).
@@ -186,6 +198,20 @@ client.ingest_content(
 )
 ```
 
+When an application chunks content itself, pass exactly one vector per produced chunk with `embeddings=[[...], [...]]`.
+
+Preview and persist a repository ingestion scope:
+
+```python
+preview = client.preview_directory("/work/my-app", included_paths=["src"])
+client.set_project_watch_dir(
+    "repo-my-app",
+    "/work/my-app",
+    included_paths=["src", "README.md"],
+)
+scope = client.get_project_watch_dir("repo-my-app")
+```
+
 ### Lexicon Management (v0.6+)
 
 Inspect and wire the brain's associations manually.
@@ -208,19 +234,7 @@ 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_salience_bias=True,
-    disable_alias_expansion=True,
-    disable_cuebridge_artifacts=True,
-)
+print(f"Intent ready: {status.get('intent_ready', False)}")
 ```
 
 ## Async Support
@@ -233,11 +247,6 @@ async with AsyncCueMap() as client:
     await client.recall(cues=["note"])
 ```
 
-## Performance
-
-- **Write Latency**: ~2ms (O(1) complexity)
-- **Read Latency**: ~3ms (P99, 1M memories)
-
 ## License
 
 MIT

{cuemap-0.7.0 → cuemap-0.7.2}/README.md

@@ -7,14 +7,14 @@
 CueMap implements a **Continuous Gradient Algorithm** optimized for associative data structures:
 
 1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
-2.  **CuePack-Guided Intent Routing**: Uses compiled deterministic rules to add structural facets and weighted intent cues without runtime model calls.
+2.  **Local semantic reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile, for bounded semantic ranking inside the engine.
 3.  **Recency & Salience (Signal Dynamics)**: Balances fresh data with salient, high-signal events prioritized by an adaptive impact scoring module.
 4.  **Reinforcement (Access-based Learning)**: Frequently accessed memories gain signal strength, remaining highly accessible even as they age.
 5.  **Deterministic Facets & Intent Routing**: Extracts synchronous source, evidence, temporal, type, and entity facets, then uses sparse intent cues and reranking during recall.
 
-As of v0.7.0, CueMap's core path is deterministic and embedding-free. GloVe/Ollama cue generation, WordNet/POS expansion, semantic bridges, pattern completion, external lexicon graphs, context expansion/speculation endpoints, and autonomous consolidation have been removed from the core engine.
+As of v0.7.2, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `all-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
 
-v0.7.0 also uses numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
+v0.7.2 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
 
 Use this SDK to talk to the Rust engine from Python applications.
 
@@ -99,9 +99,9 @@ print(response["proof"])
 # Cryptographic proof of context retrieval
 ```
 
-### v0.7 Recall Controls
+### v0.7.2 Recall Controls
 
-CueMap v0.7 adds temporal query intent, CueBridge artifact expansion, and optional reconstruction passes for longer conversational/codebase context.
+CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
 
 ```python
 results = client.recall(
@@ -110,11 +110,23 @@ results = client.recall(
     ordered_reconstruction="auto",
     evidence_coverage="auto",
     parent_fusion="auto",
-    cuepacks=["default"],
+    semantic_mode="hybrid",
     explain=True,
 )
 ```
 
+Use `semantic_mode="lexical"` for a semantic-reranker-disabled comparison, `"semantic"` for vector candidate discovery, or `"hybrid"` (the engine default) to rerank lexical candidates. `query_embedding` supplies a precomputed vector when the application owns the embedding provider.
+
+Classify query or memory intent with the same local engine model. Returned scores are ranking signals, not calibrated probabilities:
+
+```python
+classification = client.classify_intent(
+    "What did we decide about auth retries?",
+    target="query",
+)
+print(classification["primary_intent"], classification["recall_eligible"])
+```
+
 ### Cloud Backup (v0.6.1)
 
 Manage project snapshots in the cloud (S3, GCS, Azure).
@@ -151,6 +163,20 @@ client.ingest_content(
 )
 ```
 
+When an application chunks content itself, pass exactly one vector per produced chunk with `embeddings=[[...], [...]]`.
+
+Preview and persist a repository ingestion scope:
+
+```python
+preview = client.preview_directory("/work/my-app", included_paths=["src"])
+client.set_project_watch_dir(
+    "repo-my-app",
+    "/work/my-app",
+    included_paths=["src", "README.md"],
+)
+scope = client.get_project_watch_dir("repo-my-app")
+```
+
 ### Lexicon Management (v0.6+)
 
 Inspect and wire the brain's associations manually.
@@ -173,19 +199,7 @@ 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_salience_bias=True,
-    disable_alias_expansion=True,
-    disable_cuebridge_artifacts=True,
-)
+print(f"Intent ready: {status.get('intent_ready', False)}")
 ```
 
 ## Async Support
@@ -198,11 +212,6 @@ async with AsyncCueMap() as client:
     await client.recall(cues=["note"])
 ```
 
-## Performance
-
-- **Write Latency**: ~2ms (O(1) complexity)
-- **Read Latency**: ~3ms (P99, 1M memories)
-
 ## License
 
 MIT

{cuemap-0.7.0 → cuemap-0.7.2}/cuemap/__init__.py

@@ -18,14 +18,17 @@ Example:
 """
 
 from .client import CueMap, AsyncCueMap
+from .embedded import EmbeddedCueMap, resolve_cuemap_binary
 from .models import Memory, RecallResult
 from .exceptions import CueMapError, ConnectionError, AuthenticationError
 from .grounding import CueMapGroundingRetriever, AsyncCueMapGroundingRetriever
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"
 __all__ = [
     "CueMap",
     "AsyncCueMap",
+    "EmbeddedCueMap",
+    "resolve_cuemap_binary",
     "Memory",
     "RecallResult",
     "CueMapError",

{cuemap-0.7.0 → cuemap-0.7.2}/cuemap/client.py

@@ -16,7 +16,8 @@ class CueMap:
     """
     Pure CueMap client.
     
-    No auto-cue extraction. No semantic matching. Just fast memory storage.
+    The engine performs deterministic cue extraction and can use its bundled
+    local MiniLM encoder for semantic retrieval when configured.
     
     Example:
         >>> client = CueMap()
@@ -65,7 +66,8 @@ class CueMap:
         metadata: Optional[Dict[str, Any]] = None,
         disable_temporal_chunking: bool = False,
         source_key: Optional[str] = None,
-        cuepacks: Optional[List[str]] = None,
+        event_time: Optional[float] = None,
+        embedding: Optional[List[float]] = None,
         async_ingest: bool = False,
         minimal_response: bool = False,
         trace_timing: bool = False,
@@ -77,6 +79,7 @@ class CueMap:
             content: Memory content
             cues: Optional list of cues (tags) for retrieval
             metadata: Optional metadata
+            event_time: Original event timestamp as Unix seconds. Defaults to ingestion time.
             
         Returns:
             Memory ID
@@ -95,7 +98,8 @@ class CueMap:
                 "metadata": metadata,
                 "disable_temporal_chunking": disable_temporal_chunking,
                 "source_key": source_key,
-                "cuepacks": cuepacks,
+                "event_time": event_time,
+                "embedding": embedding,
                 "async_ingest": async_ingest,
                 "minimal_response": minimal_response,
                 "trace_timing": trace_timing,
@@ -133,6 +137,21 @@ class CueMap:
             raise CueMapError(f"Failed to add memories: {response.text}")
 
         return response.json()
+
+    def classify_intent(
+        self,
+        text: str,
+        target: str = "query",
+    ) -> Dict[str, Any]:
+        """Classify query or memory intent with the engine's local model."""
+        response = self.client.post(
+            "/intent/classify",
+            json={"text": text, "target": target},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to classify intent: {response.text}")
+        return response.json()
     
     def recall(
         self,
@@ -149,7 +168,6 @@ class CueMap:
         disable_alias_expansion: bool = True,
         trace_timing: bool = False,
         expansion_depth: int = 1,
-        cuepacks: Optional[List[str]] = None,
         parent_fusion: str = "off",
         parent_fusion_limit: int = 80,
         parent_fusion_min_chunks: int = 2,
@@ -165,6 +183,8 @@ class CueMap:
         cuebridge_gap_limit: int = 6,
         disable_pattern_completion: Optional[bool] = None,
         disable_systems_consolidation: Optional[bool] = None,
+        semantic_mode: str = "hybrid",
+        query_embedding: Optional[List[float]] = None,
     ) -> List[RecallResult]:
         """
         Recall memories by cues or natural language.
@@ -209,6 +229,8 @@ class CueMap:
             "evidence_coverage_max_sessions": evidence_coverage_max_sessions,
             "disable_cuebridge_artifacts": disable_cuebridge_artifacts,
             "cuebridge_gap_limit": cuebridge_gap_limit,
+            "semantic_mode": semantic_mode,
+            "query_embedding": query_embedding,
         }
         if cues:
             payload["cues"] = cues
@@ -220,9 +242,6 @@ class CueMap:
             payload["min_intersection"] = min_intersection
         if projects:
             payload["projects"] = projects
-        if cuepacks:
-            payload["cuepacks"] = cuepacks
-
         response = self.client.post(
             "/recall",
             json=_clean_payload(payload),
@@ -251,7 +270,6 @@ class CueMap:
         disable_salience_bias: bool = False,
         disable_alias_expansion: bool = True,
         expansion_depth: int = 1,
-        cuepacks: Optional[List[str]] = None,
         disable_pattern_completion: Optional[bool] = None,
         disable_systems_consolidation: Optional[bool] = None,
     ) -> Dict[str, Any]:
@@ -275,7 +293,6 @@ class CueMap:
                 "disable_salience_bias": disable_salience_bias,
                 "disable_alias_expansion": disable_alias_expansion,
                 "expansion_depth": expansion_depth,
-                "cuepacks": cuepacks,
             }),
             headers=self._headers()
         )
@@ -365,12 +382,14 @@ class CueMap:
         watch_dir: str,
         ignored_patterns: Optional[List[str]] = None,
         ignored_extensions: Optional[List[str]] = None,
+        included_paths: Optional[List[str]] = None,
     ) -> Dict[str, Any]:
         """Set the self-learning agent watch directory for a project."""
         response = self.client.post(
             f"/projects/{project_id}/watch-dir",
             json=_clean_payload({
                 "watch_dir": watch_dir,
+                "included_paths": included_paths,
                 "ignored_patterns": ignored_patterns,
                 "ignored_extensions": ignored_extensions,
             }),
@@ -380,6 +399,38 @@ class CueMap:
             raise CueMapError(f"Failed to set project watch directory: {response.text}")
         return response.json()
 
+    def get_project_watch_dir(self, project_id: str) -> Dict[str, Any]:
+        """Read a project's persisted repository ingestion scope."""
+        response = self.client.get(
+            f"/projects/{project_id}/watch-dir",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to get project watch directory: {response.text}")
+        return response.json()
+
+    def preview_directory(
+        self,
+        watch_dir: str,
+        included_paths: Optional[List[str]] = None,
+        ignored_patterns: Optional[List[str]] = None,
+        ignored_extensions: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Preview supported repository files without ingesting content."""
+        response = self.client.post(
+            "/ingest/directory/preview",
+            json=_clean_payload({
+                "watch_dir": watch_dir,
+                "included_paths": included_paths,
+                "ignored_patterns": ignored_patterns,
+                "ignored_extensions": ignored_extensions,
+            }),
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to preview directory: {response.text}")
+        return response.json()
+
     def add_alias(self, from_cue: str, to_cue: str, weight: float = 1.0) -> bool:
         """Add an alias (manual cue mapping)."""
         response = self.client.post(
@@ -574,6 +625,7 @@ class CueMap:
         source_key: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         structural_cues: Optional[List[str]] = None,
+        embeddings: Optional[List[List[float]]] = None,
         segmenter: str = "sentence_window",
         segment_window_size: Optional[int] = None,
         segment_overlap: Optional[int] = None,
@@ -589,6 +641,7 @@ class CueMap:
                 "source_key": source_key,
                 "metadata": metadata,
                 "structural_cues": structural_cues,
+                "embeddings": embeddings,
                 "segmenter": segmenter,
                 "segment_window_size": segment_window_size,
                 "segment_overlap": segment_overlap,
@@ -624,7 +677,6 @@ class CueMap:
         metadata: Optional[Dict[str, Any]] = None,
         existing_cues: Optional[List[str]] = None,
         available_cues: Optional[List[str]] = None,
-        cuepacks: Optional[List[str]] = None,
         filename: Optional[str] = None,
         segmenter: str = "sentence_window",
         segment_window_size: Optional[int] = None,
@@ -641,7 +693,6 @@ class CueMap:
                 "metadata": metadata,
                 "existing_cues": existing_cues,
                 "available_cues": available_cues,
-                "cuepacks": cuepacks,
                 "filename": filename,
                 "segmenter": segmenter,
                 "segment_window_size": segment_window_size,
@@ -736,7 +787,8 @@ class AsyncCueMap:
         metadata: Optional[Dict[str, Any]] = None,
         disable_temporal_chunking: bool = False,
         source_key: Optional[str] = None,
-        cuepacks: Optional[List[str]] = None,
+        event_time: Optional[float] = None,
+        embedding: Optional[List[float]] = None,
         async_ingest: bool = False,
         minimal_response: bool = False,
         trace_timing: bool = False,
@@ -750,7 +802,8 @@ class AsyncCueMap:
                 "metadata": metadata,
                 "disable_temporal_chunking": disable_temporal_chunking,
                 "source_key": source_key,
-                "cuepacks": cuepacks,
+                "event_time": event_time,
+                "embedding": embedding,
                 "async_ingest": async_ingest,
                 "minimal_response": minimal_response,
                 "trace_timing": trace_timing,
@@ -788,6 +841,21 @@ class AsyncCueMap:
             raise CueMapError(f"Failed to add memories: {response.text}")
 
         return response.json()
+
+    async def classify_intent(
+        self,
+        text: str,
+        target: str = "query",
+    ) -> Dict[str, Any]:
+        """Classify query or memory intent with the engine's local model (async)."""
+        response = await self.client.post(
+            "/intent/classify",
+            json={"text": text, "target": target},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to classify intent: {response.text}")
+        return response.json()
     
     async def recall(
         self,
@@ -804,7 +872,6 @@ class AsyncCueMap:
         disable_alias_expansion: bool = True,
         trace_timing: bool = False,
         expansion_depth: int = 1,
-        cuepacks: Optional[List[str]] = None,
         parent_fusion: str = "off",
         parent_fusion_limit: int = 80,
         parent_fusion_min_chunks: int = 2,
@@ -820,6 +887,8 @@ class AsyncCueMap:
         cuebridge_gap_limit: int = 6,
         disable_pattern_completion: Optional[bool] = None,
         disable_systems_consolidation: Optional[bool] = None,
+        semantic_mode: str = "hybrid",
+        query_embedding: Optional[List[float]] = None,
     ) -> List[RecallResult]:
         """Recall memories (async)."""
         payload = {
@@ -844,6 +913,8 @@ class AsyncCueMap:
             "evidence_coverage_max_sessions": evidence_coverage_max_sessions,
             "disable_cuebridge_artifacts": disable_cuebridge_artifacts,
             "cuebridge_gap_limit": cuebridge_gap_limit,
+            "semantic_mode": semantic_mode,
+            "query_embedding": query_embedding,
         }
         if cues:
             payload["cues"] = cues
@@ -855,9 +926,6 @@ class AsyncCueMap:
             payload["min_intersection"] = min_intersection
         if projects:
             payload["projects"] = projects
-        if cuepacks:
-            payload["cuepacks"] = cuepacks
-
         response = await self.client.post(
             "/recall",
             json=_clean_payload(payload),
@@ -886,7 +954,6 @@ class AsyncCueMap:
         disable_salience_bias: bool = False,
         disable_alias_expansion: bool = True,
         expansion_depth: int = 1,
-        cuepacks: Optional[List[str]] = None,
         disable_pattern_completion: Optional[bool] = None,
         disable_systems_consolidation: Optional[bool] = None,
     ) -> Dict[str, Any]:
@@ -903,7 +970,6 @@ class AsyncCueMap:
                 "disable_salience_bias": disable_salience_bias,
                 "disable_alias_expansion": disable_alias_expansion,
                 "expansion_depth": expansion_depth,
-                "cuepacks": cuepacks,
             }),
             headers=self._headers()
         )
@@ -993,12 +1059,14 @@ class AsyncCueMap:
         watch_dir: str,
         ignored_patterns: Optional[List[str]] = None,
         ignored_extensions: Optional[List[str]] = None,
+        included_paths: Optional[List[str]] = None,
     ) -> Dict[str, Any]:
         """Set the self-learning agent watch directory for a project (async)."""
         response = await self.client.post(
             f"/projects/{project_id}/watch-dir",
             json=_clean_payload({
                 "watch_dir": watch_dir,
+                "included_paths": included_paths,
                 "ignored_patterns": ignored_patterns,
                 "ignored_extensions": ignored_extensions,
             }),
@@ -1008,6 +1076,38 @@ class AsyncCueMap:
             raise CueMapError(f"Failed to set project watch directory: {response.text}")
         return response.json()
 
+    async def get_project_watch_dir(self, project_id: str) -> Dict[str, Any]:
+        """Read a project's persisted repository ingestion scope (async)."""
+        response = await self.client.get(
+            f"/projects/{project_id}/watch-dir",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to get project watch directory: {response.text}")
+        return response.json()
+
+    async def preview_directory(
+        self,
+        watch_dir: str,
+        included_paths: Optional[List[str]] = None,
+        ignored_patterns: Optional[List[str]] = None,
+        ignored_extensions: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Preview supported repository files without ingesting content (async)."""
+        response = await self.client.post(
+            "/ingest/directory/preview",
+            json=_clean_payload({
+                "watch_dir": watch_dir,
+                "included_paths": included_paths,
+                "ignored_patterns": ignored_patterns,
+                "ignored_extensions": ignored_extensions,
+            }),
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to preview directory: {response.text}")
+        return response.json()
+
     async def add_alias(self, from_cue: str, to_cue: str, weight: float = 1.0) -> bool:
         """Add an alias (async)."""
         response = await self.client.post(
@@ -1187,6 +1287,7 @@ class AsyncCueMap:
         source_key: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         structural_cues: Optional[List[str]] = None,
+        embeddings: Optional[List[List[float]]] = None,
         segmenter: str = "sentence_window",
         segment_window_size: Optional[int] = None,
         segment_overlap: Optional[int] = None,
@@ -1202,6 +1303,7 @@ class AsyncCueMap:
                 "source_key": source_key,
                 "metadata": metadata,
                 "structural_cues": structural_cues,
+                "embeddings": embeddings,
                 "segmenter": segmenter,
                 "segment_window_size": segment_window_size,
                 "segment_overlap": segment_overlap,
@@ -1237,7 +1339,6 @@ class AsyncCueMap:
         metadata: Optional[Dict[str, Any]] = None,
         existing_cues: Optional[List[str]] = None,
         available_cues: Optional[List[str]] = None,
-        cuepacks: Optional[List[str]] = None,
         filename: Optional[str] = None,
         segmenter: str = "sentence_window",
         segment_window_size: Optional[int] = None,
@@ -1254,7 +1355,6 @@ class AsyncCueMap:
                 "metadata": metadata,
                 "existing_cues": existing_cues,
                 "available_cues": available_cues,
-                "cuepacks": cuepacks,
                 "filename": filename,
                 "segmenter": segmenter,
                 "segment_window_size": segment_window_size,

cuemap-0.7.2/cuemap/embedded.py

@@ -0,0 +1,186 @@
+"""Lifecycle management for a local CueMap engine process."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import socket
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Mapping, Optional
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+def _normalize_url(url: str) -> str:
+    return url.rstrip("/")
+
+
+def _inspect_engine(url: str, api_key: Optional[str] = None) -> str:
+    headers = {"X-API-Key": api_key} if api_key else {}
+    try:
+        with urlopen(Request(f"{_normalize_url(url)}/", headers=headers), timeout=0.75) as response:
+            payload = json.loads(response.read(16_384))
+        return "cuemap" if payload.get("name") == "CueMap Rust Engine" else "occupied"
+    except HTTPError:
+        return "occupied"
+    except (URLError, TimeoutError, OSError, ValueError, json.JSONDecodeError):
+        return "closed"
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
+        listener.bind(("127.0.0.1", 0))
+        return int(listener.getsockname()[1])
+
+
+def _platform_package() -> str:
+    operating_system = platform.system().lower()
+    machine = platform.machine().lower()
+    architecture = "arm64" if machine in {"arm64", "aarch64"} else "x64"
+    return f"@cuemap-dev/engine-{operating_system}-{architecture}"
+
+
+def _npm_global_binary() -> Optional[str]:
+    npm = shutil.which("npm")
+    if not npm:
+        return None
+    try:
+        root = subprocess.run(
+            [npm, "root", "--global"],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        ).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return None
+    binary_name = "cuemap.exe" if os.name == "nt" else "cuemap"
+    candidate = Path(root) / _platform_package() / "bin" / binary_name
+    return str(candidate) if candidate.is_file() else None
+
+
+def resolve_cuemap_binary(explicit_path: Optional[str] = None) -> str:
+    """Resolve an engine binary without downloading or mutating the machine."""
+
+    configured = explicit_path or os.environ.get("CUEMAP_BIN")
+    if configured:
+        path = Path(configured).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError(f"CueMap executable does not exist: {path}")
+        return str(path)
+
+    installed = shutil.which("cuemap")
+    if installed:
+        return installed
+
+    global_binary = _npm_global_binary()
+    if global_binary:
+        return global_binary
+
+    workspace = Path(__file__).resolve().parents[2] / "rust_engine" / "target"
+    binary_name = "cuemap.exe" if os.name == "nt" else "cuemap"
+    source_binaries = [
+        workspace / profile / binary_name
+        for profile in ("release", "debug")
+        if (workspace / profile / binary_name).is_file()
+    ]
+    if source_binaries:
+        return str(max(source_binaries, key=lambda candidate: candidate.stat().st_mtime))
+
+    raise FileNotFoundError(
+        "Could not find the CueMap engine. Set CUEMAP_BIN, install `cuemap` on PATH, "
+        f"or install the native npm package {_platform_package()}."
+    )
+
+
+@dataclass
+class EmbeddedCueMap:
+    """A verified engine connection and, when applicable, its owned process."""
+
+    url: str
+    owned: bool
+    _process: Optional[subprocess.Popen] = None
+    _shutdown_timeout: float = 5.0
+
+    @classmethod
+    def start(
+        cls,
+        *,
+        url: Optional[str] = None,
+        bin_path: Optional[str] = None,
+        port: int = 8080,
+        config_path: Optional[str] = None,
+        api_key: Optional[str] = None,
+        startup_timeout: float = 15.0,
+        shutdown_timeout: float = 5.0,
+        env: Optional[Mapping[str, str]] = None,
+        logger: Optional[Callable[[str], None]] = None,
+    ) -> "EmbeddedCueMap":
+        log = logger or (lambda _message: None)
+        if url:
+            normalized = _normalize_url(url)
+            if _inspect_engine(normalized, api_key) != "cuemap":
+                raise ConnectionError(f"No CueMap engine is reachable at {normalized}")
+            log(f"Attached to CueMap at {normalized}")
+            return cls(normalized, False, _shutdown_timeout=shutdown_timeout)
+
+        preferred_url = f"http://127.0.0.1:{port}"
+        status = _inspect_engine(preferred_url, api_key)
+        if status == "cuemap":
+            log(f"Attached to CueMap at {preferred_url}")
+            return cls(preferred_url, False, _shutdown_timeout=shutdown_timeout)
+
+        selected_port = _free_port() if status == "occupied" else port
+        selected_url = f"http://127.0.0.1:{selected_port}"
+        executable = resolve_cuemap_binary(bin_path)
+        arguments = [executable, "start", "--port", str(selected_port)]
+        if config_path:
+            arguments.extend(["--config", str(Path(config_path).expanduser())])
+        process_env = dict(os.environ)
+        if env:
+            process_env.update(env)
+        process_env["CUEMAP_PORT"] = str(selected_port)
+
+        log(f"Starting CueMap at {selected_url}")
+        process = subprocess.Popen(
+            arguments,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=process_env,
+        )
+        deadline = time.monotonic() + startup_timeout
+        while time.monotonic() < deadline:
+            return_code = process.poll()
+            if return_code is not None:
+                raise RuntimeError(f"CueMap exited before becoming ready (code={return_code})")
+            if _inspect_engine(selected_url, api_key) == "cuemap":
+                log(f"CueMap is ready at {selected_url}")
+                return cls(selected_url, True, process, shutdown_timeout)
+            time.sleep(0.1)
+
+        process.terminate()
+        raise TimeoutError(f"CueMap did not become ready within {startup_timeout:g}s")
+
+    def stop(self) -> None:
+        process = self._process
+        self._process = None
+        if not self.owned or process is None or process.poll() is not None:
+            return
+        process.terminate()
+        try:
+            process.wait(timeout=self._shutdown_timeout)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait(timeout=self._shutdown_timeout)
+
+    def __enter__(self) -> "EmbeddedCueMap":
+        return self
+
+    def __exit__(self, _exc_type, _exc_value, _traceback) -> None:
+        self.stop()

{cuemap-0.7.0 → cuemap-0.7.2/cuemap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuemap
-Version: 0.7.0
+Version: 0.7.2
 Summary: CueMap Python SDK - High-performance temporal-associative memory
 Author-email: Kaan Demirel <hello@cuemap.dev>
 License: MIT
@@ -42,14 +42,14 @@ Dynamic: license-file
 CueMap implements a **Continuous Gradient Algorithm** optimized for associative data structures:
 
 1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
-2.  **CuePack-Guided Intent Routing**: Uses compiled deterministic rules to add structural facets and weighted intent cues without runtime model calls.
+2.  **Local semantic reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile, for bounded semantic ranking inside the engine.
 3.  **Recency & Salience (Signal Dynamics)**: Balances fresh data with salient, high-signal events prioritized by an adaptive impact scoring module.
 4.  **Reinforcement (Access-based Learning)**: Frequently accessed memories gain signal strength, remaining highly accessible even as they age.
 5.  **Deterministic Facets & Intent Routing**: Extracts synchronous source, evidence, temporal, type, and entity facets, then uses sparse intent cues and reranking during recall.
 
-As of v0.7.0, CueMap's core path is deterministic and embedding-free. GloVe/Ollama cue generation, WordNet/POS expansion, semantic bridges, pattern completion, external lexicon graphs, context expansion/speculation endpoints, and autonomous consolidation have been removed from the core engine.
+As of v0.7.2, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `all-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
 
-v0.7.0 also uses numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
+v0.7.2 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
 
 Use this SDK to talk to the Rust engine from Python applications.
 
@@ -134,9 +134,9 @@ print(response["proof"])
 # Cryptographic proof of context retrieval
 ```
 
-### v0.7 Recall Controls
+### v0.7.2 Recall Controls
 
-CueMap v0.7 adds temporal query intent, CueBridge artifact expansion, and optional reconstruction passes for longer conversational/codebase context.
+CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
 
 ```python
 results = client.recall(
@@ -145,11 +145,23 @@ results = client.recall(
     ordered_reconstruction="auto",
     evidence_coverage="auto",
     parent_fusion="auto",
-    cuepacks=["default"],
+    semantic_mode="hybrid",
     explain=True,
 )
 ```
 
+Use `semantic_mode="lexical"` for a semantic-reranker-disabled comparison, `"semantic"` for vector candidate discovery, or `"hybrid"` (the engine default) to rerank lexical candidates. `query_embedding` supplies a precomputed vector when the application owns the embedding provider.
+
+Classify query or memory intent with the same local engine model. Returned scores are ranking signals, not calibrated probabilities:
+
+```python
+classification = client.classify_intent(
+    "What did we decide about auth retries?",
+    target="query",
+)
+print(classification["primary_intent"], classification["recall_eligible"])
+```
+
 ### Cloud Backup (v0.6.1)
 
 Manage project snapshots in the cloud (S3, GCS, Azure).
@@ -186,6 +198,20 @@ client.ingest_content(
 )
 ```
 
+When an application chunks content itself, pass exactly one vector per produced chunk with `embeddings=[[...], [...]]`.
+
+Preview and persist a repository ingestion scope:
+
+```python
+preview = client.preview_directory("/work/my-app", included_paths=["src"])
+client.set_project_watch_dir(
+    "repo-my-app",
+    "/work/my-app",
+    included_paths=["src", "README.md"],
+)
+scope = client.get_project_watch_dir("repo-my-app")
+```
+
 ### Lexicon Management (v0.6+)
 
 Inspect and wire the brain's associations manually.
@@ -208,19 +234,7 @@ 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_salience_bias=True,
-    disable_alias_expansion=True,
-    disable_cuebridge_artifacts=True,
-)
+print(f"Intent ready: {status.get('intent_ready', False)}")
 ```
 
 ## Async Support
@@ -233,11 +247,6 @@ async with AsyncCueMap() as client:
     await client.recall(cues=["note"])
 ```
 
-## Performance
-
-- **Write Latency**: ~2ms (O(1) complexity)
-- **Read Latency**: ~3ms (P99, 1M memories)
-
 ## License
 
 MIT

{cuemap-0.7.0 → cuemap-0.7.2}/cuemap.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ README.md
 pyproject.toml
 cuemap/__init__.py
 cuemap/client.py
+cuemap/embedded.py
 cuemap/exceptions.py
 cuemap/grounding.py
 cuemap/models.py

{cuemap-0.7.0 → cuemap-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cuemap"
-version = "0.7.0"
+version = "0.7.2"
 description = "CueMap Python SDK - High-performance temporal-associative memory"
 readme = "README.md"
 requires-python = ">=3.8"