Metadata-Version: 2.4
Name: synaptic-core
Version: 0.3.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

`synaptic-core` v0.3 ships a clean canonical API for graph memory:
- Clients: `AsyncSynaptic` and `Synaptic`
- Core methods: `remember`, `recall`, `set`, `get`, `find`, `connect`, `related`
- Session-first helpers: `client.session("...")`
- Structured errors: `SynapticError { code, message, hint }`

## Install

```bash
pip install synaptic-core
```

## Happy Path (Async, Session-First)

```python
import asyncio

from synaptic_core import AsyncSynaptic, SynapticError
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) % 257) / 257.0,
    ]


async def main() -> None:
    client = AsyncSynaptic(db_path="synaptic.db", embedding_fn=embed)
    session = client.session("chat-42")

    await session.remember("Customer asked for monthly usage CSV export")
    recall = await session.recall("How do I export monthly usage as CSV?", top_k=5)

    if recall.nodes:
        await session.feedback(
            recall.query_id,
            outcome=OutcomeSignalType.EXPLICIT_POSITIVE,
            provider="app",
        )

    print("nodes", [str(node.id) for node in recall.nodes])
    print("stats", await client.stats())


try:
    asyncio.run(main())
except SynapticError as exc:
    print(exc.as_dict())
```

## Canonical API

- `remember(content, *, session_id="default", memory_type=None, external_id=None, source_type=None, metadata=None) -> Node`
- `recall(query, *, session_id="default", top_k=None) -> RetrievalResult`
- `feedback(query_id, outcome, *, session_id=None, agent_response=None, user_next_message=None, dwell_time_ms=None, active_nodes=None, corrected_nodes=None, provider="unknown") -> CompositeOutcome`
- `set(key, value, *, namespace=None, metadata=None, ttl=None) -> None`
- `get(key, *, namespace=None) -> Any | None`
- `find(query, *, namespace=None, limit=10, filters=None) -> list[dict]`
- `connect(node_a_id, node_b_id, *, weight=0.3, connection_type="excitatory", formation_trigger="explicit", is_cross_tier=None) -> dict`
- `related(node_id, *, limit=None) -> list[dict]`
- `stats() -> dict`
- `graph_status() -> dict`
- `sessions_recent(limit=20) -> list[dict]`
- `queries_recent(session_id=None, limit=20) -> list[dict]`
- `outcomes_recent(session_id=None, limit=20) -> list[dict]`

## Session-First Helpers

- `client.session(session_id).remember(...)`
- `client.session(session_id).recall(...)`
- `client.session(session_id).feedback(...)`
- `client.session(session_id).summary()`
- `client.session(session_id).queries_recent(limit=20)`
- `client.session(session_id).outcomes_recent(limit=20)`

## CLI

```bash
synaptic doctor --db-path synaptic.db
synaptic stats --db-path synaptic.db --json
synaptic graph status --db-path synaptic.db --json
synaptic sessions recent --db-path synaptic.db --limit 20 --json
synaptic queries recent --db-path synaptic.db --session-id chat-42 --limit 20 --json
synaptic migrate-api /path/to/codebase --write
```

## Migration

Strict migration steps and breaking changes are documented in:
- `docs/migration-v0.2-to-v0.3.md`

