Metadata-Version: 2.4
Name: synaptic-core
Version: 0.2.0
Summary: Synaptic Core foundation and persistence layer for graph-backed memory.
Author-email: Xavier Hillman <xhillman13@gmail.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic<2.12.0,>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: real-embedding
Requires-Dist: sentence-transformers<4.0.0,>=3.0.0; extra == "real-embedding"
Provides-Extra: proof-magic
Requires-Dist: faiss-cpu>=1.13.0; extra == "proof-magic"
Requires-Dist: chromadb>=1.5.0; extra == "proof-magic"
Requires-Dist: rank-bm25>=0.2.2; extra == "proof-magic"
Requires-Dist: scikit-learn>=1.4.0; extra == "proof-magic"

# synaptic-core

Graph-backed memory runtime for production AI applications.

`synaptic-core` provides an async memory engine with hybrid retrieval, associative activation, feedback-driven learning, and durable observability.

## Why synaptic-core

- Hybrid retrieval: combines keyword, semantic, and graph activation signals.
- Tiered memory: supports short-term and long-term memory with automatic graduation.
- Feedback learning: updates graph associations based on user/agent outcomes.
- Operational visibility: includes graph health, per-session summaries, and weekly digest reporting.
- Local-first default: ships with a SQLite backend and stable persistence semantics.

## Installation

Requirements:

- Python `3.10+`

Install from source:

```bash
python -m pip install .
```

Optional extras:

```bash
python -m pip install ".[real_embedding]"
```

## Quick Start

```python
import asyncio

from synaptic_core import SynapticMemory
from synaptic_core.types import OutcomeSignalType


def embed(text: str) -> list[float]:
    normalized = text.lower().strip()
    return [
        float(len(normalized.split())),
        float(len(normalized)) / 100.0,
        float(sum(ord(ch) for ch in normalized) % 97) / 100.0,
    ]


async def main() -> None:
    memory = SynapticMemory(
        db_path="synaptic.db",
        embedding_fn=embed,
        deployment_id="prod-us-east-1",
    )

    await memory.store(
        "Customer requested monthly usage report with CSV export.",
        metadata={"tenant": "acme", "channel": "support"},
    )

    retrieval = await memory.retrieve(
        "How does Acme get their monthly usage report?",
        session_id="chat-42",
        top_k=5,
    )

    outcome = await memory.feedback(
        retrieval.query_id,
        outcome=OutcomeSignalType.EXPLICIT_POSITIVE,
        active_nodes=[node.id for node in retrieval.nodes],
        provider="assistant-api",
    )

    status = await memory.graph_status()
    session = await memory.session_summary("chat-42")
    digest = await memory.weekly_digest()

    print(retrieval.nodes[0].content if retrieval.nodes else "no matches")
    print(outcome.composite_score, status["graph_confidence"], session["query_count"], digest["summary"])


asyncio.run(main())
```

## Core API

- `store(content, ...) -> Node`
- `retrieve(query, ...) -> RetrievalResult`
- `activate(node_ids, initial_energy=1.0, ...) -> RetrievalResult`
- `feedback(query_id, outcome, ...) -> CompositeOutcome`
- `graph_status() -> dict`
- `session_summary(session_id) -> dict`
- `weekly_digest(...) -> dict`
- `stats() -> dict`
- `delete(node_id) -> None`
- `link(node_a_id, node_b_id, ...) -> dict`
- `neighbors(node_id, limit=None) -> list[dict]`
- `recent_queries(session_id=None, limit=20) -> list[dict]`
- `recent_sessions(limit=20) -> list[dict]`
- `recent_outcomes(session_id=None, limit=20) -> list[dict]`
- `kv_set(key, value, metadata=None, ttl=None, namespace=None) -> None`
- `kv_get(key, namespace=None) -> Any | None`
- `kv_search(query, limit=10, namespace=None, filters=None) -> list[KeyValueItem]`
- `kv_delete(key, namespace=None) -> bool`
- `kv_clear(namespace=None) -> int` (supports namespace `"*"` for global clear)
- `store_session(session) -> session` (optimistic version checks)
- `retrieve_session(session_id) -> session | dict | None`
- `update_session(session) -> session`

## Production Notes

- `embedding_fn` is required for `store` and `retrieve`; it may be sync or async.
- Use stable `session_id` values to get accurate session analytics.
- Use stable `deployment_id` values to keep telemetry attribution consistent.
- Telemetry and background hardening paths are designed to be failure-isolated from hot request paths.
- The default SQLite backend is appropriate for single-node/local deployments.

## Extensibility

- Backend abstraction is defined by `MemoryBackend` in `src/synaptic_core/backends/base.py`.
- You can supply a custom backend by passing `backend=...` to `SynapticMemory`.
- Framework adapters are intentionally external to this package.
- Axis interoperability is supported through the external `AXIS-MEMORY-PROVIDER-V1` contract implemented by Axis-owned adapter code.
