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

synapse_memory_engine-1.4.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: synapse-memory-engine
+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
+Author-email: Synapse Cognitive Systems <singhshivam20009@gmail.com>
+Project-URL: Homepage, https://github.com/721189/Synapse-Memory
+Project-URL: Bug Tracker, https://github.com/721189/Synapse-Memory/issues
+Project-URL: Documentation, https://github.com/721189/Synapse-Memory#readme
+Project-URL: Repository, https://github.com/721189/Synapse-Memory.git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: urllib3>=2.8.0
+Provides-Extra: local-models
+Requires-Dist: sentence-transformers>=5.0.0; extra == "local-models"
+Provides-Extra: pgvector
+Requires-Dist: psycopg2-binary>=2.9.9.1; extra == "pgvector"
+Requires-Dist: pgvector>=0.4.0; extra == "pgvector"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.13.0; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: sentence-transformers>=5.0.0; extra == "all"
+Requires-Dist: psycopg2-binary>=2.9.9.1; extra == "all"
+Requires-Dist: pgvector>=0.4.0; extra == "all"
+Requires-Dist: langchain-core>=0.3.0; extra == "all"
+Requires-Dist: llama-index-core>=0.13.0; extra == "all"
+Requires-Dist: redis>=5.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.13.0; extra == "dev"
+Requires-Dist: bandit>=1.8.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: types-requests>=2.32.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# 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.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.0 → 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.0"
+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.0 → synapse_memory_engine-1.4.0}/setup.py

@@ -2,10 +2,10 @@ from setuptools import setup, find_packages
 
 setup(
     name="synapse-memory-engine",
-    version="1.2.0",
+    version="1.4.0",
     description="Sovereign, active RAG & cognitive long-term memory engine for AI agents",
     author="Synapse Cognitive Systems",
-    author_email="synapse-memory@users.noreply.github.com",
+    author_email="singhshivam20009@gmail.com",
     url="https://github.com/721189/Synapse-Memory",
     license="All Rights Reserved",
     packages=find_packages(include=["synapse_memory*"]),
@@ -16,6 +16,7 @@ setup(
         "uvicorn>=0.34.0",
         "cryptography>=42.0.0",
         "requests>=2.31.0",
+        "urllib3>=2.8.0",
         "numpy>=1.26.0",
     ],
     extras_require={
@@ -29,13 +30,13 @@ setup(
             "pgvector>=0.4.0",
             "langchain-core>=0.3.0",
             "llama-index-core>=0.13.0",
+            "redis>=5.0.0",
         ],
         "dev": [
             "flake8>=7.0.0",
             "mypy>=1.13.0",
             "bandit>=1.8.0",
             "pytest>=8.0.0",
-            "types-cryptography>=42.0.0",
             "types-requests>=2.32.0",
         ],
     },

{synapse_memory_engine-1.3.0 → 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.0"
+__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",
 ]