synapsor 0.1.1

Python SDK for Synapsor, the agent-native database for auditable AI applications

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

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:

python -m pip install synapsor

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.