synapsor 0.1.0

Python client for Synapsor HTTP/JSON APIs

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

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:

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. 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.