MESA Core · v0.9.3
Examples & SDK workflow
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
Start locally or use the explicit V4 client#
Follow local quickstart for automatic credentials and models-off BM25 ingestion/search. Use Mesa() for local document workflows; the explicit MesaV4Client below exposes session and mutation control. Models are optional for extraction and semantic search.
V4 insert, wait, search#
Prerequisites: a combined owner, provisioned credential/agent permission and an existing workspace/dataset writable by the principal. Use a new dataset or fresh document/revision IDs for each independent run. This snippet follows the released SDK contract; it is not a production or real-provider qualification result.
import os
from mesa_client import MesaV4Client
with MesaV4Client("http://127.0.0.1:18080", api_key=os.environ["MESA_API_KEY"]) as client:
session = client.start_session(
tenant_id="docs-tenant", workspace_id="docs-workspace",
dataset_ids=["docs-dataset"], agent_id="docs-agent",
)
accepted = client.insert(
session_id=session["session_id"], dataset_id="docs-dataset",
document_id="archive-hours", revision_id="revision-1", chunk_id="chunk-1",
title="Archive opening hours", source_ref="demo://archive-hours",
content="The archive opens at nine on weekdays.",
)
terminal = client.wait_until_committed(accepted["mutation_id"])
if terminal["state"] != "COMMITTED":
raise RuntimeError(terminal["state"])
results = client.search(session_id=session["session_id"], query="When does the archive open?")
print(results)Preserve the source contract#
Never infer scope from caller metadata. Keep exact content and source_ref; use stable idempotency keys for retries. Both synchronous and asynchronous V4 insert methods retain optional legal_identity. Default mutation polling is two seconds. End the server session separately from closing the HTTP client; on timeout inspect mutation status before retrying. Follow ingestion for multi-chunk finalization and security for grants.
Wait for activation and delete by source#
mesa add waits for ACTIVE by default. In the tagged v0.9.3 SDK, Mesa.add defaults to wait=False; pass wait=True explicitly to wait for ACTIVE. Use mesa add document.txt --source file://document.txt --no-wait or Mesa.add(..., wait=False) to return after admission. A terminal chunk failure is reported early with mutation ID, state and error class. RETRY_PENDING is not terminal.
mesa delete --source file://document.txt
mesa delete DOCUMENT_IDfrom mesa_client import Mesa
with Mesa() as mesa:
receipt = mesa.add("The archive opens at nine.", source="file://document.txt", wait=True)
admitted = mesa.add("Another document.", source="file://other.txt", wait=False)
mesa.delete(source="file://document.txt")ID-based deletion is retained. Deletion still requires the owning scope and purge permissions.
Source reference for this page
The sections of the upstream file that back this page, translated to English where the original mixes in Turkish. The GitHub link shows the exact original.
V4 Python SDK#
This example assumes a model-enabled V4 server, a provisioned credential, an existing
tenant-a/workspace-a/dataset-a catalog and session permission for agent-a.
For an example that also sets these up, use Getting started.
from mesa_client import MesaV4Client
with MesaV4Client("http://127.0.0.1:8000", api_key=credential) as client:
session = client.start_session(
tenant_id="tenant-a",
workspace_id="workspace-a",
dataset_ids=["dataset-a"],
agent_id="agent-a",
)
accepted = client.insert(
session_id=session["session_id"],
dataset_id="dataset-a",
document_id="doc-a",
revision_id="rev-1",
chunk_id="chunk-1",
title="Neutral source example",
source_ref="demo://source-a",
content="Exact source text",
)
terminal = client.wait_until_committed(accepted["mutation_id"])
if terminal["state"] != "COMMITTED":
raise RuntimeError(terminal["state"])
result = client.search(session_id=session["session_id"], query="Exact source")
for hit in result["results"]:
print(hit["assertion_id"])
for source in hit.get("provenance", []):
print(source["source_ref"], source["dataset_id"], source["chunk_id"])
context = client.get_context(session_id=session["session_id"], query="Exact source")
print(context["context"])
client.end_session(session_id=session["session_id"])accepted is durable admission, not finished retrieval. client.status(mutation_id)
exposes state, failure_class, rejection_reason, pipeline_run, artifacts
and projections. Wait for COMMITTED; REJECTED, DEAD_LETTER, BLOCKED and
ROLLED_BACK are terminal outcomes too. A wait timeout raises MesaNetworkError
and leaves the mutation running. Recheck status; for an uncertain insert retry
the same payload with an explicit, unchanged idempotency_key.
results=[] on a successful search means no matching visible evidence. Provider,
storage and authorization failures raise errors instead. Each hit's
assertion_id identifies a canonical claim; provenance links it to the source
and dataset/chunk. A score ranks evidence; it is not a truth probability.
Context returns packed text in context and structured evidence in
canonical_memories; mutations contains bounded ID/state receipts without raw evidence spans. Finish retrieval before end_session; closing the HTTP
client alone does not end the server session.
For async code use async with AsyncMesaV4Client(...) as client and await each
of these methods, including polling and end_session. Do not run the blocking
MesaV4Client inside an event loop. Async clients also support await client.aclose();
sync clients support client.close().
For a multi-chunk revision, use finalize_revision=False on the first calls and the
default True on the last call. The search and get_context methods
support all three of valid_at, valid_from and valid_to.
Besides capability, catalog, session, insert, search, status, wait, replay,
rollback, purge, context and end operations, MesaV4Client and AsyncMesaV4Client
offer the control-plane methods submit_rebuild, operation_status,
cancel_operation and retry_operation. The V3 clients are kept as MesaClient
and AsyncMesaClient. The dataset-bound MCP surface offers no mutating global
rebuild tool.
