Metadata-Version: 2.4
Name: synapsor
Version: 0.1.0
Summary: Python client for Synapsor HTTP/JSON APIs
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 Adapter

The Python adapter is a thin client over `synapsor_server` HTTP/JSON APIs. It
does not run query planning, memory filtering, capability execution, or policy
logic in Python. Those stay in the C++ DBMS.

## 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 after the package is published:

```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.
The cloud gateway pins those keys to the database runtime branch before forwarding
requests to the single-node runtime.

## 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)`
- `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`
- `read_resource(uri)`

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