Python SDK
/v1 routes and some wrappers are removed or reshaped (tenant administration, cluster operations, webhooks, dedup tokens, media embedding). See the SDK changes. Python, TypeScript and Go are the only supported SDKs.pip install relata-sdk — Python 3.11+. Hard deps: httpx, pydantic. Async extras: pyarrow, pandas, langgraph, boto3/aiobotocore (all optional — install only what you use). The SDK ships sync + async mirrors of every client (42 classes total) so the same code shape works in scripts and in asyncio servers.
See the SDK overview for the cross-language parity matrix. This page is the Python capability catalog.
Quickstart
pip install relata-sdkfrom relata import RelataClient
from relata.ingest import IngestClient
with RelataClient("http://localhost:9090", purpose="analytics") as client:
# /query is read-only (#782) — writes go through the governed ingest door.
IngestClient.from_client(client).bulk(
"Person", [{"id": "p1", "name": "Alice", "email": "a@x.com"}]
)
for row in client.query("SELECT * FROM Person LIMIT 5"):
print(row["name"], row["email"])Async is the same surface with an a-prefix: await client.aquery(...), await client.asearch(...), etc. Use async with RelataClient(...) for scoped lifecycles.
The query surface
| Path | Method | Returns |
|---|---|---|
| SQL | query(sql, purpose=None, dialect=None) / aquery | QueryResult (iterable) |
| Parameterized | query_params(sql, params, purpose=None) / aquery_params | QueryResult — ? auto-rewrites to $N |
| Arrow IPC | query_arrow(sql, purpose=None) | pyarrow.Table — zero-copy |
| Arrow Flight (gRPC) | query_flight(sql, flight_endpoint=None, ...) / aquery_flight | pyarrow.Table |
| GraphQL | graphql(query, variables=None, operation_name=None) / agraphql | dict — variables bound server-side (#3260) |
| SPARQL | sparql(query) | dict |
| Cypher | any MATCH-prefixed string via query() | auto-routed, governed |
| GQL (ISO 39075) | query(stmt, dialect="gql") | header-selected, governed (#3265) |
| Fluent builder | client.select(*cols).where(...).limit(10).execute() / .aexecute() | QueryResult |
from relata import select
result = (select("*").from_("Person")
.where("age > $1").where_param("age > $1", 25)
.order_by("name").limit(10)
.purpose("analytics").execute())Typed domain clients
Every domain client has sync + async mirrors and a .from_client(client) factory that inherits auth/tenant/purpose/timeout:
from relata import (
GovernanceClient, IdentityClient, ObjectClient, IngestClient,
VectorClient, SearchClient, StreamingClient, AuditClient,
TenantAdminClient, BackupClient, TokenClient, LogClient,
SystemClient, A2AClient, McpClient, Namespace,
)| Client | Key methods | Cross-ref |
|---|---|---|
GovernanceClient | rules CRUD, Sigma import, retention/WORM/legal-holds, breakglass, alerts, DSAR | Detection Rules |
IdentityClient | label, record_uncertainty, register_lookup/list_lookups/invoke_lookup, erase_subject | Identity (active learning) |
ObjectClient | upsert, typed_upsert, batch_upsert, get, delete | — |
IngestClient | bulk, bulk_csv, ingest_auto, ingest_cdr, otlp_traces/logs/metrics, ingest_iter | Ingestion |
VectorClient | knn_search, hybrid_search, similar_to, embed/embed_batch + embed_image/face/audio/video | Hybrid Search |
SearchClient | typed /search JSON door: query(namespace, text=..., rank_by=..., filters=..., limit=...) | Search reference |
StreamingClient | query_rows (NDJSON), query_arrow_raw, watch/watch_stream (SSE), alerts (SSE) | — |
AuditClient | count, entries(...), find_by_request_id, sign_receipt, export_pdf → bytes | — |
TenantAdminClient | tenant CRUD, quota, sharing, platform usage/license | Enterprise edition only; the open build has one tenant |
BackupClient | create, list, restore, restore_status, compact, wait_for_restore | Backup & Restore |
TokenClient | remember, check, revoke, stats (dedup tokens) | — |
LogClient | append, head, load_leaves (integrity log) | — |
SystemClient | LLM config/test, jobs/workflows, feeds, notifications, pipelines | — |
A2AClient | submit_task, get_task, checkpoints, agent_card | — |
McpClient | initialize, list_tools, call_tool + 68 typed tool wrappers | MCP Tools |
Namespace | client.namespace("Document") → query/write/get/delete_all/branch_from | Search reference |
Vectors & embeddings
vc = client.vector_client # or: VectorClient.from_client(client)
# Pure KNN over a named slot
vc.knn_search("Document", "embedding", [0.1, ...], k=10, ef_search=200)
# Hybrid: BM25 + vector + graph, RRF-fused
vc.hybrid_search("Document", query_text="graph retrieval", k=10,
rerank=True, weights=[0.2, 0.5, 0.3])
# Embedding (6 modalities) — uses server's CPU lexical default or GPU sidecar
emb = vc.embed("Alice Smith") # → {embedding, model, dim}
vc.embed_image(base64_bytes) # CLIP
vc.embed_face(base64_bytes) # ArcFace
vc.embed_audio(base64_bytes) # CLAP
vc.embed_video(base64_bytes) # CLIP keyframeGraph & intelligence operators
All on RelataClient directly — 10 graph algorithms + 10 AML/financial + 3 maritime:
client.graph_pagerank("Person", damping=0.85, max_iter=20)
client.graph_shortest_path("alice-id", "bob-id", max_hops=5)
client.graph_community("Person")
# Financial intelligence
client.sanctions_screen("Acme Holdings", threshold=0.85)
client.beneficial_ownership_chain("Acme Holdings", max_depth=6)
client.crypto_trace("0xabc...", purpose="compliance")
# Maritime
client.vessel_track(mmsi=123456789, window_secs=86400)
client.dark_fleet_detect(max_gap_hours=48)See Graph Analytics for the algorithm matrix and the SQL TVF / gds.* / traverse.* surfaces.
Agent memory — 10 cognitive verbs + recall-quality knobs
from relata import Memory
mem = Memory("http://localhost:9090", bearer_token="<token>", purpose="agent")
mid = mem.add("Alice prefers dark mode", confidence=0.9, memory_class="semantic")
# retrieval-quality operators — tune what comes back
results = mem.search(
"ui preferences", top_k=10,
min_confidence=0.6, # CONFIDENCE floor
recency_half_life_secs=259200, # 3-day decay (RECENCY)
budget_tokens=1500, # hard prompt budget (BUDGET)
cancel_threshold=0.92, # stop on a great match (CANCEL_WHEN)
)
detail = mem.search_detailed(...) # exposes recall_cost_tokens + cancelledThe full verb set: add, add_batch, search, search_detailed, get, update, forget, associate, episodes, justify, resolve, summarise. See Agent memory reference (recall knobs + the 5 operators).
Ecosystem (Python-only)
| Extra | Install | Surface |
|---|---|---|
| 7 framework adapters | relata_adapters (ships with the package) | RelataMemory for LangChain / LlamaIndex / CrewAI / AutoGen(+AG2) / Pydantic-AI / smolagents — duck-typed, install only your framework |
| LangGraph checkpointer (the 7th adapter) | pip install relata-sdk[langgraph] | RelataCheckpointer + AsyncRelataCheckpointer (real BaseCheckpointSaver subclasses; persist via the governed A2A door) |
| IPython / Jupyter magic | pip install relata-sdk[ipython] | %%relata --purpose analytics cell magic → results render as a pandas DataFrame |
| S3 door helper | pip install relata-sdk[s3] | S3Client.boto3() / AsyncS3Client.aio() / S3Client.httpx() — returns a configured boto3/aiobotocore/httpx client pointed at Relata's S3 door |
# Auto-detect which framework is installed and return the right adapter
from relata_adapters.registry import get_memory_adapter
Adapter = get_memory_adapter() # LangChain/LlamaIndex/CrewAI/... or None
mem = Adapter(relata_memory_backend) if Adapter else NoneAuthentication & multi-tenant
client = RelataClient(
"http://localhost:9090",
bearer_token="<token>",
purpose="analytics",
tenant="org-acme", # X-Relata-Tenant-Id on every request
acting_as="user-42", # X-Acting-As (delegation)
delegated_by="admin-1", # X-Delegated-By
timeout=30.0,
max_retries=3,
admin_base_url="http://admin.internal:9090", # /admin/* + /platform/* zero-trust split
)Examples
The SDK ships ~25 runnable examples in sdks/python/examples/. Run any with python -m examples.<name>:
RELATA_TOKEN=secret python -m examples.basic_query # minimal connect + SELECT
RELATA_TOKEN=secret python -m examples.ingest # bulk + CSV ingest
RELATA_TOKEN=secret python -m examples.advanced_query # filter + aggregate + Arrow
RELATA_TOKEN=secret python -m examples.governance # PURPOSE + audit + types
RELATA_TOKEN=secret python -m examples.memory_quickstart # add / search / forget
RELATA_TOKEN=secret python -m examples.multi_tenant # org isolation
RELATA_TOKEN=secret python -m examples.intelligence # sanctions / UBO / crypto / convoy / DNS
RELATA_TOKEN=secret python -m examples.face_search # FACE_SEARCH operator
RELATA_TOKEN=secret python -m examples.streaming # SSE watch + transparency log
RELATA_TOKEN=secret python -m examples.a2a # agent-to-agent + checkpoints
RELATA_TOKEN=secret python -m examples.bitemporal # AS OF + WITH PROVENANCEFull set: sdks/python/examples/.
Next steps
- Search and retrieval — typed
/search, multi-query batch + RRF - Agent memory reference — 10 verbs + recall-quality knobs
- Graph analytics — 10+ algorithms,
gds.*portability - Query cookbook
- Full Python SDK source