Metadata-Version: 2.4
Name: synapsor
Version: 0.1.1
Summary: Python SDK for Synapsor, the agent-native database for auditable AI applications
Author: Synapsor
License-Expression: MIT
Project-URL: Homepage, https://synapsor.ai
Project-URL: Documentation, https://synapsor.ai/docs
Project-URL: Source, https://github.com/sandeshtiwari/Synapsor
Keywords: synapsor,database,agents,sql,rag,audit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Synapsor Python SDK

The Synapsor Python SDK connects applications to hosted or local Synapsor
databases. Use it for SQL, branch workflows, agent contexts, capabilities,
evidence, memory, and safe write proposals from Python applications.

## Local Usage

```python
from synapsor import Synapsor

db = Synapsor("app.db", auto_start=True)
db.set_session({
    "tenant_id": "acme",
    "principal": "support_agent_17",
    "session_id": "agent_run_1",
})

db.execute("CREATE TABLE messages (id INT, body VARCHAR);")
db.execute("INSERT INTO messages VALUES (1, 'hello');")
rows = db.query("SELECT * FROM messages;")

proposal = db.propose_memory_fact(
    scope=("tenant", "acme"),
    subject=("preference", "answer_style"),
    claim="The operator prefers concise answers.",
    source=("turn", "msg_1"),
    trust="verified",
    approval="approved",
    reason="stable preference extracted from chat",
)
db.approve_memory_proposal(proposal["proposal"]["proposal_id"], "operator approved")
memory = db.recall_memory(scope=("tenant", "acme"), subject=("preference", "answer_style"))

db.close()
```

## Hosted Usage

Install from PyPI:

```bash
python -m pip install synapsor
```

```python
import os
from synapsor import Synapsor

db = Synapsor("https://dev-api.synapsor.ai", api_key=os.environ["SYNAPSOR_API_KEY"])
db.set_session({
    "tenant_id": "acme",
    "principal": "app_user_1",
    "session_id": "first_hosted_run",
})

print(db.query("SELECT 1;"))

ctx = db.invoke_agent_capability("chat.prepare_llm_context", {"question": "..."})
proposal = db.invoke_agent_capability(
    "support.propose_late_fee_waiver",
    {"fee_id": "FEE_3001", "reason": "card_update_failure"},
    mode="propose_only",
    auto_branch=True,
    response_envelope=True,
)
```

Use database-scoped API keys from the Synapsor control panel for hosted projects.

## API Surface

- `execute(sql)` and `query(sql)`
- `set_session({...})`
- `invoke_agent_capability(name, arguments, mode=None, auto_branch=None, response_envelope=None, include_audit_trail=None, settlement_policy=None)`
- `list_capabilities(query="...")`
- `remember_fact(...)`
- `propose_memory_fact(...)`
- `approve_memory_proposal(id, reason)`
- `reject_memory_proposal(id, reason)`
- `list_memory_proposals(...)`
- `recall_memory(...)`
- `retire_fact(...)` and `forget_fact(...)`
- `check_fact_for_action(...)`
- branch helpers: `create_branch`, `use_branch`, `diff_branch`, `merge_branch`, `drop_branch`
- write lifecycle helpers: `preview_write`, `approve_write`, `commit_write`, `reject_write`, `settle_write`
- `read_resource(uri)`

Errors from Synapsor become `SynapsorError` with `status` and `payload`.
