synapse-memory-engine 1.3.1__tar.gz → 1.4.0__tar.gz

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapse-memory-engine
-Version: 1.3.1
+Version: 1.4.0
 Summary: Production-grade active RAG & cognitive memory engine with multi-tenancy, pgvector HNSW indexing, semantic deduplication, decay-based pruning, and token-aware context packing.
 Home-page: https://github.com/721189/Synapse-Memory
 Author: Synapse Cognitive Systems
@@ -59,6 +59,8 @@ Python distribution for the Synapse Memory engine. The distribution name is `syn
 - **Semantic Deduplication**: Dual lexical Jaccard and dense cosine similarity detection to prevent node fragmentation.
 - **Hybrid Retrieval**: BM25 sparse lexical ranking fused with dense vector embeddings via Reciprocal Rank Fusion (RRF).
 - **Framework Integrations**: True drop-in adapters for LangChain (`BaseMemory`) and LlamaIndex (`BaseMemory`).
+- **Agent reliability runtime**: Opt-in run budgets, repeated failed-call blocking, versioned event serialization, and persistent tenant-scoped run traces.
+- **Opt-in agent run guard**: Bounded steps/tool calls, cooperative deadlines, repeated-failure blocking, and privacy-minimized in-memory events.
 
 ## Installation
 
@@ -87,6 +89,68 @@ with SynapseClient(
 
 The client automatically retries idempotent `GET`/`HEAD`/`OPTIONS` requests and honours `Retry-After`. It does not automatically replay `POST` requests (including `/query`, which updates access metadata) after an ambiguous failure; callers should reconcile the operation before manually retrying, or provide their own idempotency mechanism.
 
+## Opt-in Python run guard
+
+The runtime only guards tool calls explicitly routed through `SynapseRun`; it does not intercept arbitrary framework calls. Events stay in memory until the application exports or persists them. Event records contain tool names and keyed argument fingerprints, not raw arguments, prompts, tool results, or exception messages.
+
+```python
+from synapse_memory import RunPolicy, SynapseRun
+
+policy = RunPolicy(
+    max_steps=12,
+    max_tool_calls=8,
+    timeout_seconds=30,
+    max_repeated_failures=2,
+)
+
+with SynapseRun(policy=policy) as run:
+    customer = run.call_tool(
+        "lookup_customer",
+        {"customer_id": "cust_123"},
+        lookup_customer,  # callable accepts arguments as keyword arguments
+    )
+    run.record_step()  # account for non-tool work
+    print(customer)
+
+# Inspect metadata-only events after the context exits.
+for event in run.events:
+    print(event.event_type.value, event.reason, event.tool_fingerprint)
+```
+
+Limits are checked before admitting each step/tool call. The deadline is cooperative: a synchronous tool already in progress cannot be forcibly interrupted. A run guard is not a sandbox, does not authorize tools, does not intercept unwrapped calls, or enforce provider token/cost budgets. Repeated-call blocking applies after the configured number of consecutive failures for the same tool and equivalent JSON arguments; a successful call resets that failure count. No automatic retries are performed.
+
+## Persistent run traces and retrieval provenance
+
+Trace persistence is an explicit opt-in operation. The event contract is versioned (schema_version=1) and records only run lifecycle metadata, tool name/status, a per-run keyed argument fingerprint, typed failure reasons, and retrieval evidence. It does not record prompts, raw tool arguments, tool results, memory content, or the retrieval query. Retrieval evidence must be supplied by the application from its own retrieval/packing pipeline; Synapse does not silently instrument arbitrary framework calls or automatically attach every /query response to a run.
+
+To persist a completed SynapseRun, use a key with agent-runs:read and agent-runs:write scopes, plus agent-runs:delete only when deletion is needed:
+
+~~~python
+from synapse_memory import RunPolicy, SynapseClient, SynapseRun
+
+with SynapseRun(policy=RunPolicy(max_steps=12, max_tool_calls=8)) as run:
+    # The app can query Synapse or another retriever here.
+    candidates = [
+        {"id": "memory_01", "relevance_score": 0.91, "token_cost": 18},
+        {"id": "memory_02", "relevance_score": 0.43, "token_cost": 16},
+    ]
+    packed_ids = ["memory_01"]
+    run.record_memory_retrieval(candidates, packed_memory_ids=packed_ids)
+    answer = run.call_tool("lookup_customer", {"customer_id": "cust_123"}, lookup_customer)
+
+with SynapseClient(
+    "https://your-synapse-api",
+    api_key="syn_live_your_key",
+    tenant_id="your-tenant",
+) as client:
+    receipt = client.upload_agent_run(run)
+    print(receipt["events_inserted"], receipt["events_deduplicated"])
+~~~
+
+The client uploads the run's ordered events after the run ends. Stable event IDs make retrying a partially completed upload idempotent. Event records are tenant-bound by the authenticated API key; a caller-supplied tenant field in an event is rejected. Available endpoints are documented in the API contract (../../docs/api-reference.md). Each tenant can list and delete only its own trace records; event pages are bounded and ordered by sequence number.
+
+This first persistence layer is not yet a live streaming sink, a full observability dashboard, an outcome verifier, or a retention scheduler. Deployments must apply schema migration v6 before starting a PostgreSQL least-privilege runtime role. Use the API's deletion endpoint or a separately configured retention job to remove stored runs.
+
 ## Testing
 
 From the repository root:

synapse_memory_engine-1.4.0/README.md

@@ -0,0 +1,116 @@
+# Synapse Memory Python SDK
+
+Python distribution for the Synapse Memory engine. The distribution name is `synapse-memory-engine`; the import package is `synapse_memory`.
+
+## Features
+
+- **Encrypted SQLite Storage**: Fernet AES-128-CBC with HMAC-SHA256 authenticated encryption at rest.
+- **Dynamic Programming Knapsack Packing**: Exact 0/1 Knapsack optimizer for packing high-relevance memories into strict token envelopes.
+- **Ebbinghaus Decay Engine**: Continuous temporal decay with positive/negative reinforcement factors.
+- **Semantic Deduplication**: Dual lexical Jaccard and dense cosine similarity detection to prevent node fragmentation.
+- **Hybrid Retrieval**: BM25 sparse lexical ranking fused with dense vector embeddings via Reciprocal Rank Fusion (RRF).
+- **Framework Integrations**: True drop-in adapters for LangChain (`BaseMemory`) and LlamaIndex (`BaseMemory`).
+- **Agent reliability runtime**: Opt-in run budgets, repeated failed-call blocking, versioned event serialization, and persistent tenant-scoped run traces.
+- **Opt-in agent run guard**: Bounded steps/tool calls, cooperative deadlines, repeated-failure blocking, and privacy-minimized in-memory events.
+
+## Installation
+
+```bash
+pip install synapse-memory-engine          # from PyPI
+# or, from a checkout of this repository:
+pip install -e .
+```
+
+## REST client quick start
+
+Use `SynapseClient` when connecting an application to a running Synapse API:
+
+```python
+from synapse_memory import SynapseClient, SynapseError
+
+with SynapseClient(
+    "http://127.0.0.1:8008",
+    api_key="syn_live_your_key",
+    tenant_id="your-tenant",
+) as client:
+    created = client.create_memory("Customer selected the annual plan.", category="fact")
+    result = client.retrieve("Which plan did the customer select?")
+    print(created.id, result.fused_context)
+```
+
+The client automatically retries idempotent `GET`/`HEAD`/`OPTIONS` requests and honours `Retry-After`. It does not automatically replay `POST` requests (including `/query`, which updates access metadata) after an ambiguous failure; callers should reconcile the operation before manually retrying, or provide their own idempotency mechanism.
+
+## Opt-in Python run guard
+
+The runtime only guards tool calls explicitly routed through `SynapseRun`; it does not intercept arbitrary framework calls. Events stay in memory until the application exports or persists them. Event records contain tool names and keyed argument fingerprints, not raw arguments, prompts, tool results, or exception messages.
+
+```python
+from synapse_memory import RunPolicy, SynapseRun
+
+policy = RunPolicy(
+    max_steps=12,
+    max_tool_calls=8,
+    timeout_seconds=30,
+    max_repeated_failures=2,
+)
+
+with SynapseRun(policy=policy) as run:
+    customer = run.call_tool(
+        "lookup_customer",
+        {"customer_id": "cust_123"},
+        lookup_customer,  # callable accepts arguments as keyword arguments
+    )
+    run.record_step()  # account for non-tool work
+    print(customer)
+
+# Inspect metadata-only events after the context exits.
+for event in run.events:
+    print(event.event_type.value, event.reason, event.tool_fingerprint)
+```
+
+Limits are checked before admitting each step/tool call. The deadline is cooperative: a synchronous tool already in progress cannot be forcibly interrupted. A run guard is not a sandbox, does not authorize tools, does not intercept unwrapped calls, or enforce provider token/cost budgets. Repeated-call blocking applies after the configured number of consecutive failures for the same tool and equivalent JSON arguments; a successful call resets that failure count. No automatic retries are performed.
+
+## Persistent run traces and retrieval provenance
+
+Trace persistence is an explicit opt-in operation. The event contract is versioned (schema_version=1) and records only run lifecycle metadata, tool name/status, a per-run keyed argument fingerprint, typed failure reasons, and retrieval evidence. It does not record prompts, raw tool arguments, tool results, memory content, or the retrieval query. Retrieval evidence must be supplied by the application from its own retrieval/packing pipeline; Synapse does not silently instrument arbitrary framework calls or automatically attach every /query response to a run.
+
+To persist a completed SynapseRun, use a key with agent-runs:read and agent-runs:write scopes, plus agent-runs:delete only when deletion is needed:
+
+~~~python
+from synapse_memory import RunPolicy, SynapseClient, SynapseRun
+
+with SynapseRun(policy=RunPolicy(max_steps=12, max_tool_calls=8)) as run:
+    # The app can query Synapse or another retriever here.
+    candidates = [
+        {"id": "memory_01", "relevance_score": 0.91, "token_cost": 18},
+        {"id": "memory_02", "relevance_score": 0.43, "token_cost": 16},
+    ]
+    packed_ids = ["memory_01"]
+    run.record_memory_retrieval(candidates, packed_memory_ids=packed_ids)
+    answer = run.call_tool("lookup_customer", {"customer_id": "cust_123"}, lookup_customer)
+
+with SynapseClient(
+    "https://your-synapse-api",
+    api_key="syn_live_your_key",
+    tenant_id="your-tenant",
+) as client:
+    receipt = client.upload_agent_run(run)
+    print(receipt["events_inserted"], receipt["events_deduplicated"])
+~~~
+
+The client uploads the run's ordered events after the run ends. Stable event IDs make retrying a partially completed upload idempotent. Event records are tenant-bound by the authenticated API key; a caller-supplied tenant field in an event is rejected. Available endpoints are documented in the API contract (../../docs/api-reference.md). Each tenant can list and delete only its own trace records; event pages are bounded and ordered by sequence number.
+
+This first persistence layer is not yet a live streaming sink, a full observability dashboard, an outcome verifier, or a retention scheduler. Deployments must apply schema migration v6 before starting a PostgreSQL least-privilege runtime role. Use the API's deletion endpoint or a separately configured retention job to remove stored runs.
+
+## Testing
+
+From the repository root:
+
+```bash
+pip install -e "sdk/python[pgvector,langchain,llamaindex,dev]"
+PYTHONPATH=sdk/python pytest sdk/python/tests -v
+```
+
+Database-gated tests require a disposable PostgreSQL/pgvector database and explicitly documented environment flags. Passing the offline suite alone is not production verification.
+
+**Licence:** proprietary. Installation does not grant unrestricted usage or deployment rights; obtain written permission under [`../../LICENSE`](../../LICENSE) before using this package outside the permissions granted by the copyright holder.

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 # owned by an unrelated third-party project. Import package stays `synapse_memory`.
 # See docs/publishing.md.
 name = "synapse-memory-engine"
-version = "1.3.1"
+version = "1.4.0"
 authors = [{name = "Synapse Cognitive Systems", email = "singhshivam20009@gmail.com"}]
 description = "Production-grade active RAG & cognitive memory engine with multi-tenancy, pgvector HNSW indexing, semantic deduplication, decay-based pruning, and token-aware context packing."
 readme = "README.md"

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="synapse-memory-engine",
-    version="1.3.1",
+    version="1.4.0",
     description="Sovereign, active RAG & cognitive long-term memory engine for AI agents",
     author="Synapse Cognitive Systems",
     author_email="singhshivam20009@gmail.com",

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/synapse_memory/__init__.py

@@ -9,8 +9,23 @@ from synapse_memory.core.decay_engine import DecayEngine
 from synapse_memory.integrations.langchain import SynapseLangChainMemory
 from synapse_memory.integrations.llamaindex import SynapseLlamaIndexMemory
 from synapse_memory.client import SynapseClient, SynapseError, CreateResult, QueryResult
+from synapse_memory.runtime import (
+    RunPolicy,
+    RunStatus,
+    RunEventType,
+    RunEvent,
+    MemoryEvidence,
+    SynapseRun,
+    RunGuardError,
+    RunStateError,
+    RunLimitExceeded,
+    RunStepLimitExceeded,
+    RunToolCallLimitExceeded,
+    RunDeadlineExceeded,
+    RepeatedToolCallError,
+)
 
-__version__ = "1.3.1"
+__version__ = "1.4.0"
 __api_compat_version__ = "v1"
 
 __all__ = [
@@ -28,4 +43,17 @@ __all__ = [
     "SynapseError",
     "CreateResult",
     "QueryResult",
+    "RunPolicy",
+    "RunStatus",
+    "RunEventType",
+    "RunEvent",
+    "MemoryEvidence",
+    "SynapseRun",
+    "RunGuardError",
+    "RunStateError",
+    "RunLimitExceeded",
+    "RunStepLimitExceeded",
+    "RunToolCallLimitExceeded",
+    "RunDeadlineExceeded",
+    "RepeatedToolCallError",
 ]

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/synapse_memory/api/fastapi_server.py

@@ -5,10 +5,10 @@ import datetime
 import hashlib
 import logging
 import threading
-from typing import List, Dict, Any, Optional, Tuple
-from pydantic import BaseModel, ConfigDict, Field
+from typing import List, Dict, Any, Optional, Tuple, Literal
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 import uvicorn
-from fastapi import FastAPI, HTTPException, status, Header, Request, Depends
+from fastapi import FastAPI, HTTPException, status, Header, Request, Depends, Path
 from fastapi.middleware.cors import CORSMiddleware
 
 # Adjust path to enable absolute imports when running as standalone script
@@ -21,6 +21,10 @@ from synapse_memory.core.memory_manager import DEFAULT_MAX_RECORD_LIMIT, MemoryM
 from synapse_memory.core.knapsack_packer import KnapsackPacker
 from synapse_memory.core.decay_engine import DecayEngine
 from synapse_memory.core.hybrid_search import HybridSearch
+from synapse_memory.runtime import RunEventType, RunStatus
+from synapse_memory.core.run_trace_store import (
+    RunTraceStore, RunTraceError, RunNotFoundError, RunConflictError,
+)
 from synapse_memory.core.auth import (
     SecurityManager,
     APIKeyRecord,
@@ -106,6 +110,7 @@ else:
     ACTIVE_BACKEND = "sqlite"
 
 manager = MemoryManager(store=store, embedder=embedder, max_record_limit=DEFAULT_MAX_RECORD_LIMIT)
+run_trace_store = RunTraceStore(store)
 logger.info(
     f"MemoryManager capacity limit: {manager.max_record_limit} records "
     f"(override with SYNAPSE_MAX_RECORD_LIMIT; historical default is 50)"
@@ -233,7 +238,7 @@ def _rate_limit_principal(request: Request) -> str:
 app = FastAPI(
     title="SynapseMemory Enterprise Cognitive Gateway",
     description="Sovereign Active Long-Term Memory & Context Budgeting REST API with Multi-Tenancy and Database-Level RLS.",
-    version="1.3.1"
+    version="1.4.0"
 )
 
 
@@ -244,9 +249,11 @@ async def add_request_id_and_rate_limit(request: Request, call_next):  # type: i
     request_id = request.headers.get("X-Request-ID") or f"req_{_uuid.uuid4().hex[:12]}"
     start = time.time()
     # Rate-limit only mutating + heavy retrieval endpoints
-    if request.url.path.startswith(("/ingest", "/api/memories", "/query", "/api/retrieval")):
+    if request.url.path.startswith(("/ingest", "/api/memories", "/query", "/api/retrieval", "/api/agent-runs")):
+        # Avoid unbounded per-run limiter buckets: all run/event URLs share one bucket.
+        rate_route = "/api/agent-runs" if request.url.path.startswith("/api/agent-runs") else request.url.path
         try:
-            _check_rate_limit(f"{_rate_limit_principal(request)}:{request.url.path}")
+            _check_rate_limit(f"{_rate_limit_principal(request)}:{rate_route}")
         except HTTPException as e:
             from fastapi.responses import JSONResponse
 
@@ -455,6 +462,62 @@ class QueryResponse(SynapseAPIModel):
     active_storage_backend: str
 
 
+class RunCreateRequest(SynapseAPIModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    run_id: str = Field(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+    schema_version: Literal[1] = 1
+    tenant_id: Optional[str] = Field(
+        None, alias="tenantId", min_length=1, max_length=128,
+        pattern=r"^[A-Za-z0-9_\-\.]+$",
+    )
+
+
+class MemoryEvidenceRequest(SynapseAPIModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    memory_id: str = Field(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+    rank: int = Field(..., ge=1, le=10000)
+    score_components: Dict[str, float] = Field(default_factory=dict, max_length=8)
+    token_cost: int = Field(0, ge=0, le=100000)
+    packed: bool = False
+    created_at: Optional[float] = Field(None, ge=0, allow_inf_nan=False)
+    supersedes: Optional[str] = Field(None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+    superseded_by: Optional[str] = Field(None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+
+
+class AgentRunEventRequest(SynapseAPIModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    schema_version: Literal[1] = 1
+    event_id: str = Field(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+    run_id: str = Field(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+    event_type: RunEventType
+    timestamp: datetime.datetime
+    run_status: RunStatus
+    step_index: Optional[int] = Field(None, ge=1)
+    tool_call_index: Optional[int] = Field(None, ge=1)
+    tool_name: Optional[str] = Field(None, min_length=1, max_length=128, pattern=r"^[A-Za-z][A-Za-z0-9_.:-]*$")
+    tool_fingerprint: Optional[str] = Field(None, pattern=r"^[a-fA-F0-9]{64}$")
+    reason: Optional[str] = Field(None, min_length=1, max_length=128, pattern=r"^[a-z][a-z0-9_]*$")
+    error_type: Optional[str] = Field(None, min_length=1, max_length=128, pattern=r"^[A-Za-z][A-Za-z0-9_.:-]*$")
+    retrieval_id: Optional[str] = Field(None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$")
+    memory_evidence: List[MemoryEvidenceRequest] = Field(default_factory=list, max_length=100)
+
+    @field_validator("timestamp")
+    @classmethod
+    def timestamp_must_be_timezone_aware(cls, value: datetime.datetime) -> datetime.datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("timestamp must include a timezone")
+        return value
+
+    @model_validator(mode="after")
+    def retrieval_metadata_must_match_event_type(self):
+        if self.event_type is RunEventType.MEMORY_RETRIEVAL:
+            if not self.retrieval_id:
+                raise ValueError("memory.retrieval requires retrieval_id")
+        elif self.retrieval_id is not None or self.memory_evidence:
+            raise ValueError("retrieval metadata is only valid for memory.retrieval")
+        return self
+
+
 class FeedbackRequest(SynapseAPIModel):
     memory_id: str = Field(..., min_length=1, max_length=256, description="Memory node ID")
     feedback_type: str = Field(..., pattern=r"^(positive|negative)$", description="Must be either 'positive' (boost) or 'negative' (hallucination alert)")
@@ -791,6 +854,137 @@ def query_memory(
     )
 
 
+@app.post("/api/agent-runs", tags=["Agent Reliability"])
+def create_agent_run(
+    request: Request,
+    payload: RunCreateRequest,
+    principal: APIKeyRecord = Depends(require_scope("agent-runs:write")),
+):
+    """Create a tenant-bound run before streaming events (or before manual upload)."""
+    effective_tenant = resolve_tenant(principal, payload.tenant_id)
+    try:
+        result = run_trace_store.create_run(
+            effective_tenant, payload.run_id, schema_version=payload.schema_version,
+        )
+    except RunTraceError as exc:
+        raise HTTPException(status_code=503, detail="Agent trace storage unavailable.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return envelope(result, request)
+
+
+@app.post("/api/agent-runs/{run_id}/events", tags=["Agent Reliability"])
+def append_agent_run_event(
+    request: Request,
+    payload: AgentRunEventRequest,
+    run_id: str = Path(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$"),
+    tenant_id: Optional[str] = None,
+    principal: APIKeyRecord = Depends(require_scope("agent-runs:write")),
+):
+    """Append one versioned event; retries with the same event ID are idempotent."""
+    if payload.run_id != run_id:
+        raise HTTPException(status_code=422, detail="event run_id does not match the path run_id.")
+    effective_tenant = resolve_tenant(principal, tenant_id)
+    event = payload.model_dump(exclude_none=True)
+    event["event_type"] = payload.event_type.value
+    event["run_status"] = payload.run_status.value
+    event["memory_evidence"] = [
+        item.model_dump(exclude_none=True) for item in payload.memory_evidence
+    ]
+    try:
+        result = run_trace_store.append_event(effective_tenant, run_id, event)
+    except RunNotFoundError as exc:
+        raise HTTPException(status_code=404, detail="Run not found for the authenticated tenant.") from exc
+    except RunConflictError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except RunTraceError as exc:
+        raise HTTPException(status_code=503, detail="Agent trace storage unavailable.") from exc
+    except (ValueError, TypeError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return envelope(result, request)
+
+
+@app.get("/api/agent-runs", tags=["Agent Reliability"])
+def list_agent_runs(
+    request: Request,
+    tenant_id: Optional[str] = None,
+    limit: int = 50,
+    offset: int = 0,
+    principal: APIKeyRecord = Depends(require_scope("agent-runs:read")),
+):
+    """List recent run summaries for the authenticated tenant."""
+    effective_tenant = resolve_tenant(principal, tenant_id)
+    try:
+        runs = run_trace_store.list_runs(effective_tenant, limit=limit, offset=offset)
+    except RunTraceError as exc:
+        raise HTTPException(status_code=503, detail="Agent trace storage unavailable.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return envelope({"runs": runs, "limit": limit, "offset": offset}, request)
+
+
+@app.get("/api/agent-runs/{run_id}", tags=["Agent Reliability"])
+def get_agent_run(
+    request: Request,
+    run_id: str = Path(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$"),
+    tenant_id: Optional[str] = None,
+    principal: APIKeyRecord = Depends(require_scope("agent-runs:read")),
+):
+    """Fetch one run summary without returning event payloads by default."""
+    effective_tenant = resolve_tenant(principal, tenant_id)
+    try:
+        result = run_trace_store.get_run(effective_tenant, run_id)
+    except RunNotFoundError as exc:
+        raise HTTPException(status_code=404, detail="Run not found for the authenticated tenant.") from exc
+    except RunTraceError as exc:
+        raise HTTPException(status_code=503, detail="Agent trace storage unavailable.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return envelope(result, request)
+
+
+@app.get("/api/agent-runs/{run_id}/events", tags=["Agent Reliability"])
+def list_agent_run_events(
+    request: Request,
+    run_id: str = Path(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$"),
+    tenant_id: Optional[str] = None,
+    limit: int = 100,
+    offset: int = 0,
+    principal: APIKeyRecord = Depends(require_scope("agent-runs:read")),
+):
+    """Read a bounded, chronological metadata-only event page."""
+    effective_tenant = resolve_tenant(principal, tenant_id)
+    try:
+        events = run_trace_store.list_events(
+            effective_tenant, run_id, limit=limit, offset=offset,
+        )
+    except RunNotFoundError as exc:
+        raise HTTPException(status_code=404, detail="Run not found for the authenticated tenant.") from exc
+    except RunTraceError as exc:
+        raise HTTPException(status_code=503, detail="Agent trace storage unavailable.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return envelope({"run_id": run_id, "events": events, "limit": limit, "offset": offset}, request)
+
+
+@app.delete("/api/agent-runs/{run_id}", tags=["Agent Reliability"])
+def delete_agent_run(
+    request: Request,
+    run_id: str = Path(..., min_length=1, max_length=128, pattern=r"^[A-Za-z0-9._:-]+$"),
+    tenant_id: Optional[str] = None,
+    principal: APIKeyRecord = Depends(require_scope("agent-runs:delete")),
+):
+    """Delete a run and its events for data lifecycle/retention workflows."""
+    effective_tenant = resolve_tenant(principal, tenant_id)
+    try:
+        deleted = run_trace_store.delete_run(effective_tenant, run_id)
+    except RunTraceError as exc:
+        raise HTTPException(status_code=503, detail="Agent trace storage unavailable.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return envelope({"run_id": run_id, "status": "DELETED" if deleted else "NOT_FOUND"}, request)
+
+
 @app.post("/feedback", tags=["Reinforcement"])
 def submit_feedback(
     request: Request,

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/synapse_memory/client.py

@@ -7,6 +7,7 @@ retryable (429/5xx) failures, and the canonical {success, data} envelope.
 from __future__ import annotations
 
 import time
+import re
 from email.utils import parsedate_to_datetime
 from datetime import datetime, timezone
 from dataclasses import dataclass
@@ -16,7 +17,7 @@ import requests
 
 __all__ = ["SynapseClient", "SynapseError", "CreateResult", "QueryResult"]
 
-SDK_VERSION = "1.3.1"
+SDK_VERSION = "1.4.0"
 API_COMPAT_VERSION = "v1"
 
 
@@ -193,6 +194,55 @@ class SynapseClient:
     def feedback(self, memory_id: str, feedback_type: str) -> Dict[str, Any]:
         return self._request("POST", "/feedback", {"memory_id": memory_id, "feedback_type": feedback_type})
 
+    def create_agent_run(self, run_id: str) -> Dict[str, Any]:
+        """Create (idempotently) a tenant-bound persistent run trace."""
+        if not isinstance(run_id, str) or not re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", run_id):
+            raise ValueError("run_id must match [A-Za-z0-9._:-] and be 1–128 characters")
+        return self._request(
+            "POST", "/api/agent-runs", {"run_id": run_id, "schema_version": 1}, retry_safe=True
+        )
+
+    def append_agent_run_event(self, run_id: str, event: Any) -> Dict[str, Any]:
+        """Append one versioned event. Stable event IDs make retry safe."""
+        if not isinstance(run_id, str) or not re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", run_id):
+            raise ValueError("run_id must match [A-Za-z0-9._:-] and be 1–128 characters")
+        if hasattr(event, "to_dict") and callable(event.to_dict):
+            payload = event.to_dict()
+        elif isinstance(event, dict):
+            payload = dict(event)
+        else:
+            raise TypeError("event must be a RunEvent or JSON-compatible event dictionary")
+        if payload.get("run_id") != run_id:
+            raise ValueError("event run_id does not match run_id")
+        if not isinstance(payload.get("event_id"), str) or not payload["event_id"]:
+            raise ValueError("event must include a stable event_id")
+        return self._request(
+            "POST", f"/api/agent-runs/{run_id}/events", payload, retry_safe=True
+        )
+
+    def upload_agent_run(self, run: Any) -> Dict[str, Any]:
+        """Persist an in-memory SynapseRun after it finishes.
+
+        The API appends events in the run's original order. Re-uploading the same
+        run is idempotent because create-run and event IDs are stable. A partial
+        upload can be retried by calling this method again.
+        """
+        run_id = getattr(run, "run_id", None)
+        events = getattr(run, "events", None)
+        if not isinstance(run_id, str) or not run_id or events is None:
+            raise TypeError("run must expose run_id and events (for example, SynapseRun)")
+        summary = self.create_agent_run(run_id)
+        uploaded = []
+        for event in events:
+            uploaded.append(self.append_agent_run_event(run_id, event))
+        return {
+            "run": summary,
+            "events_submitted": len(uploaded),
+            "events_inserted": sum(1 for result in uploaded if not result.get("duplicate", False)),
+            "events_deduplicated": sum(1 for result in uploaded if result.get("duplicate", False)),
+            "last_sequence_number": uploaded[-1]["sequence_number"] if uploaded else 0,
+        }
+
     def health(self) -> Dict[str, Any]:
         return self._request("GET", "/health")
 

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/synapse_memory/core/auth.py

@@ -98,6 +98,9 @@ _KNOWN_SCOPES = frozenset({
     "memories:write",
     "memories:delete",
     "memories:list",
+    "agent-runs:read",
+    "agent-runs:write",
+    "agent-runs:delete",
 })
 
 

{synapse_memory_engine-1.3.1 → synapse_memory_engine-1.4.0}/synapse_memory/core/knapsack_packer.py

@@ -1,5 +1,6 @@
 from typing import List, Dict, Any, Optional
 import logging
+import math
 
 logger = logging.getLogger("KnapsackPacker")
 
@@ -62,9 +63,18 @@ class KnapsackPacker:
 
         n = len(memories)
         weights = [max(1, int(m.get("token_cost", 1))) for m in memories]
-        values = [max(0, int(float(m.get("relevance_score", 0.0)) * 1000)) for m in memories]
-
-        dp = [0] * (budget + 1)
+        values: List[float] = []
+        for memory in memories:
+            score = float(memory.get("relevance_score", 0.0))
+            # Non-finite values are not useful selection signals. Treat them as
+            # zero rather than allowing NaN/inf to poison DP comparisons.
+            values.append(max(0.0, score) if math.isfinite(score) else 0.0)
+
+        # Preserve score precision. Hybrid RRF scores are commonly around
+        # 0.01-0.03, with rank-to-rank differences below 0.001. Converting to
+        # int(score * 1000) collapses distinct scores into ties (or zero), so
+        # the chosen set can change when every score is rescaled.
+        dp = [0.0] * (budget + 1)
         items_included: List[List[int]] = [[] for _ in range(budget + 1)]
 
         for i in range(n):