SDK/Python

Python SDK

The official Python SDK for Vouchstone. Build powerful AI agents with persistent memory in Python.

Installation

Install the Vouchstone Python SDK using pip:

pip install vouchstone-sdk

Or using Poetry:

poetry add vouchstone-sdk

Install with optional extras for specific backends:

pip install vouchstone-sdk[all]    # All backends (Redis, ChromaDB, Neo4j)
pip install vouchstone-sdk[redis]  # Redis for working memory
pip install vouchstone-sdk[vector] # ChromaDB + Qdrant for semantic memory
pip install vouchstone-sdk[graph]  # Neo4j for procedural memory

Requirements

Python 3.10 or higher
A Vouchstone API key (get one from your Profile)

Quick Start

Initialize the Client

from vouchstone_sdk import VouchstoneClient

# api_key and control_plane_url are both required -- there is no default
# control plane URL, point it at your own instance.
client = VouchstoneClient(
    api_key="your-api-key",
    control_plane_url="https://your-control-plane-host.example.com",
)

Build an Agent

Agents are built locally by subclassing Agent and implementing run() — there is no server-side "create agent" call.VouchstoneClient is only used for control-plane sync (fetching specs, reporting status/metrics, replaying the ledger).

from vouchstone_sdk import Agent, AgentConfig, Message, AgentResponse, MemoryContext

class SupportAgent(Agent):
    async def run(self, message: Message, context: MemoryContext) -> AgentResponse:
        # context.semantic_entities / context.procedural_skills carry retrieved memory
        response = await self.llm.complete(
            system=self.config.system_prompt,
            messages=[{"role": "user", "content": message.content}],
        )
        return AgentResponse(content=response)

config = AgentConfig(
    name="Support Agent",
    model="claude-sonnet-4-20250514",
    temperature=0.7,
    system_prompt="You are a helpful and professional support agent.",
)
agent = SupportAgent(config)
await agent.initialize(agent_id="agent-123")

Send a Message

# process() prepares memory context, calls run(), then persists the turn
response = await agent.process(Message(content="How do I reset my password?"))

print(response.content)
print(f"Prompt tokens: {response.usage.get('prompt_tokens')}")

Core Concepts

Agents

Agents are the core building block. Each instance owns its ownMemoryPipeline (five layers) and configuration.VouchstoneClient exposes read/status operations against the control plane:

# List agents registered for this tenant
agents = await client.list_agents()

# Get a specific agent's control-plane definition
agent_def = await client.get_agent("agent-id")

# Report status/metrics back to the control plane
await client.report_status("agent-id", {"state": "healthy"})
await client.report_metrics({"turns_processed": 42})

Memory Operations

Each memory layer is a real class on agent.pipeline — access it from inside run(), where it's available as self.pipeline:

class PolicyAgent(Agent):
    async def run(self, message: Message, context: MemoryContext) -> AgentResponse:
        # Store a fact in semantic memory
        await self.pipeline.semantic.store(
            "Our refund policy allows returns within 30 days.",
            metadata={"category": "policy", "source": "faq"},
        )

        # Search semantic memory
        results = await self.pipeline.semantic.search("refund policy", top_k=5)
        for r in results:
            print(f"Score: {r.score}, Content: {r.content}")

        return AgentResponse(content="...")

Error Handling

The SDK doesn't define custom exception classes today — memory backends fail loudly with a clear MemoryBackendUnavailableError when an explicitly configured backend (Redis, ChromaDB, Neo4j) is unreachable, rather than silently degrading to fake in-memory state:

from vouchstone_sdk.memory import MemoryBackendUnavailableError

try:
    await agent.initialize(agent_id="agent-123", redis_url="redis://localhost:6379")
except MemoryBackendUnavailableError as e:
    print(f"Memory backend unavailable: {e}")

Configuration

from vouchstone_sdk import VouchstoneClient

# api_key and control_plane_url are both required; tenant_id is optional
client = VouchstoneClient(
    api_key="your-api-key",
    control_plane_url="https://your-control-plane-host.example.com",
    tenant_id="your-tenant-id",
)

Full API Reference

See the complete API reference for all available methods and options.

API Reference GitHub Repository