MESA Core · v0.9.3
Örnekler ve SDK iş akışı
Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.
Yerelde başlayın veya açık V4 istemcisini kullanın#
Otomatik kimlik bilgileri ve modeller kapalıyken BM25 veri alımı/araması için yerel hızlı başlangıcı izleyin. Yerel belge işlemlerinde Mesa() kullanın; aşağıdaki MesaV4Client oturum ve mutasyon denetimini açıkça gösterir. Bilgi çıkarımı ve anlamsal arama için modeller isteğe bağlıdır.
V4 ile ekleyin, tamamlanmasını bekleyin ve arayın#
Önkoşullar: combined süreci, erişim anahtarı, ajan izni ve erişim kimliğinin yazabildiği mevcut çalışma alanı/veri kümesi. Birbirinden bağımsız denemelerde yeni veri kümesi veya yeni belge/sürüm kimlikleri kullanın. Örnek, yayımlanan SDK’nın kullanımını gösterir; canlı kullanım veya gerçek sağlayıcı doğrulaması değildir.
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)Kaynağı ve işlem kimliğini koruyun#
Erişim kapsamını istemcinin gönderdiği ek bilgilerden çıkarmayın. Kaynağın tam metnini ve source_ref değerini koruyun. Tekrar denemelerde aynı yineleme anahtarını kullanın. v0.9.3’de senkron ve asenkron V4 ekleme yöntemleri isteğe bağlı legal_identity kabul eder; durum varsayılan olarak iki saniyede bir sorgulanır. HTTP istemcisini kapatmakla sunucudaki oturumu bitirmek farklı işlemlerdir. Zaman aşımından sonra yeniden denemeden önce işlemin durumuna bakın. Birden fazla parçadan oluşan sürümler için veri alımı, izinler için güvenlik rehberini okuyun.
Etkinleşmeyi bekleme ve kaynakla silme#
mesa add varsayılan olarak ACTIVE durumunu bekler. Etiketli v0.9.3 SDK’sında Mesa.add varsayılanı wait=False değeridir; ACTIVE durumunu beklemek için açıkça wait=True verin. Kabulden hemen sonra dönmek için mesa add document.txt --source file://document.txt --no-wait veya Mesa.add(..., wait=False) kullanın. Terminal parça hatası, mutation ID, durum ve hata sınıfıyla erken bildirilir. RETRY_PENDING terminal durum değildir.
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")Kimlikle silme korunur. Silme yine sahiplik kapsamını ve purge izinlerini gerektirir.
Kaynak belgedeki ilgili bölümler
Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.
V4 Python SDK#
Bu örnek, model-enabled V4 sunucu, provision edilmiş credential, mevcut
tenant-a/workspace-a/dataset-a kataloğu ve agent-a session izni varsayar.
Bunları da kuran örnek için Getting started kullanılır.
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 holds bounded receipts (IDs and states) 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().
Çok chunk'lı revision için ilk çağrılarda finalize_revision=False, son
çağrıda varsayılan True kullanılır. search ve get_context metotları
valid_at, valid_from ve valid_to parametrelerinin üçünü de destekler.
MesaV4Client ve AsyncMesaV4Client; capability, catalog, session, insert,
search, status, wait, replay, rollback, purge, context ve end işlemlerinin
yanında submit_rebuild, operation_status, cancel_operation ve
retry_operation control-plane metotlarını sunar. V3 istemcileri MesaClient
ve AsyncMesaClient olarak korunur. Dataset-bound MCP yüzeyi mutating global
rebuild aracı sunmaz.
