MESA Core · v0.9.3
Embedding & model providers
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
Supported providers at a glance#
| Role | Provider value | Example model | Dimension | Install extra |
|---|---|---|---|---|
| Embeddings · local (default) | sentence-transformers | BAAI/bge-m3, normalized | 1024 | ml |
| Embeddings · external | openai_compatible | text-embedding-3-small | 1536 | base |
| Embeddings · Nemotron-3 profile | openai_compatible | Nemotron-3, nemotron-qpass-v1 (query/passage) | 2048 | base |
| Extraction / validation LLM | openai_compatible | any chat model your endpoint serves, e.g. gpt-4o-mini | — | base |
| Extraction / validation LLM | claude | a Claude model | — | [adapters] |
| Extraction / validation LLM | ollama | a model already pulled on a running Ollama | — | base |
| Tests only | mock | returns no facts | — | — |
Extraction and embeddings are configured separately: choosing claude or ollama for extraction does not set up embeddings. Select MESA_LLM_MODEL and MESA_EMBEDDING_MODEL with explicit provider:model values. Changing provider, model, dimension or normalization starts a new embedding space and needs a reindex or a new storage root.
Representation must stay compatible#
Assertion vectors and query embeddings must share provider/model identity and dimension. The documented local default is local:BAAI/bge-m3 with 1024 dimensions; external text-embedding-3-small requires 1536. A settings edit is not an in-place representation migration. Rebuild/reindex under the documented identity rules.
Configured is not operational#
GET /v4/capability distinguishes runtime availability. A custom embedding provider remains non-operational until a successful embedding call. Expected vector/provider failure returns explicit 503; the runtime does not silently switch models. A combined consumer accepts V4 writes with models off and supports BM25. Enable extraction and embedding providers only when those capabilities are needed.
Bound provider access deliberately#
MESA_EXTERNAL_PROVIDER_ENABLED=false allows local Ollama/OpenAI-compatible endpoints and blocks cloud providers. Set it true and supply keys for cloud providers. It is not a complete air-gap or zero-cost guarantee. Model downloads, local provisioning and other process networking are separate concerns. The v0.9.1 DEV benchmark reports BGE retrieval and device latency under stated conditions; it does not measure cloud-provider token cost.
v0.9.3 operation#
Use MESA_LLM_MODEL=provider:model and MESA_EMBEDDING_MODEL=provider:model. BM25 ingestion/search works with models off. Local Ollama and OpenAI-compatible endpoints are allowed with the external-provider flag off; cloud providers require it on and need keys.
Source reference for this page
The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.
Providers and capacity#
MESA_CHUNKING=auto (default) splits new document revisions at Turkish article
headings when at least three occur at line starts. The preamble stays separate;
long articles use the existing paragraph/sentence splitting with a 512-token
limit. All slices preserve the exact source text. Other documents keep the same
plain chunks; MESA_CHUNKING=plain selects that plan for every document. Retrying
a pending upload preserves the plan matching its already admitted chunk texts,
even after restarting or changing this setting. Active revisions are unchanged.
If an admitted prefix fits two different plans, the retry returns 409 without
appending chunks, because the stored text cannot identify the original plan.
MESA_LEGAL_RULES_ENABLED=true enables Turkish legal rule processing. In auto
chunking mode, ordinary article chunks inherit the document's law number from
metadata.law_number or a Kanun Numarası, Kanunun Numarası or Kanun No.
header in the first 3,000 characters. Continuation pieces keep that article's
identity; preambles, GEÇİCİ/EK articles and plain plans receive none. Setting the
switch to false disables automatic identity assignment for new chunks. It also
disables legal processing during search, including citation resolution, the
exact-match slot, decision künye promotion, legal ranking factors and graph
citation parsing. Ordinary lexical, vector and graph retrieval still run.
Search ignores stored legal identities and item snapshots while the switch is
off and omits their legal result annotations; it does not erase them. Stored
identities are immutable on resume. Any 3–5 digit law number is accepted by the
typed identity API; known numbers retain their existing statute code (6098 →
TBK). Unknown law names and inconsistent number/code pairs are rejected.
Numbered queries such as 7201 sayılı Kanunun 21. maddesi use the existing
typed legal candidate lane and ranking factors. Document fallback assertions
keep their document subject, madde relation and chunk object; automatic
article identity changes only the typed columns.
Newly admitted chunks also keep versioned citation, decision-reference, date,
amount, duration and outcome items. Search returns them in
retrieval_provenance.legal_items as {version, items}. Item start/end
offsets refer to the original chunk, including when a result quotes a shorter
extracted fact. Items remain separate from SPO facts and do not enter fusion
scores. Decision references can use the bounded exact-match slot below.
Disabling the switch prevents new item snapshots and hides existing snapshots
from search results. Existing snapshots remain stored. Purging a document
erases these source quotes too.
An exact law-and-article query puts at most three matching chunks first, in
document order. Other results retain their fused order (or reranked order when
reranking is enabled). The match must exist in the authorized search scope.
A query's docket and decision numbers can also match a decision's own künye:
a stored decision_ref starting within the first 300 characters of chunk zero.
Its first chunk shares the same three-chunk limit with article matches, in
document order. Later quotations do not teach a decision's identity. The map
uses the same tenant, dataset, agent and time scope cache as law names; an
unmatched reference leaves result order unchanged.
The scope cache learns law names from titles and first-chunk law headers of
documents with trusted article identities; it never learns them from another
tenant, dataset, agent or time scope. Names accept case and Turkish ı/i variants,
possessive suffixes, and K. for Kanunu. The longest exact name from that scope
takes precedence over an overlapping ontology alias. Ambiguous store names
shared by different law numbers are ignored. No static law-name table is added.
MESA_RERANK_ENABLED=false keeps the existing fused ranking and does not import
ML packages. Enabling it requires pip install "mesa-memory[ml]"; startup checks
that the package is installed, and the model loads lazily on the first search.
MESA_RERANK_MODEL defaults to BAAI/bge-reranker-v2-m3 (Apache-2.0), with
MESA_RERANK_DEPTH=50 (range 1–50). The scorer uses authorized full chunk texts
after releasing the search connection, in a worker thread, then returns the
requested number of results. Tied scores retain fused order. Results keep their
fusion fields, including rrf_score and final_score, and add rerank_score.
The first search includes model-load latency; subsequent searches reuse it.
Model and external-provider flags default false. Validation defaults to
mode 0; mode 1 or 2 must be set explicitly via MESA_TIER3_MODE. Mode 2
needs distinct A/B validator identities. Extraction and validation are separate.
MESA_EMBEDDING_ENABLED defaults to MESA_MODEL_ENABLED; MESA_EXTRACTION_ENABLED
defaults to false (D46). A combined runtime accepts writes with both off and finds
them through BM25. Disabled VECTOR lanes end SKIPPED; enabling embedding later
backfills them at startup using the same embedding identity. Backfill failures
leave committed records searchable.
MESA_GRAPH_ENABLED defaults to true, independently of the model flags.
Set it to false to avoid opening Kùzu in the runtime and offline rebuild
runner. GRAPH lanes end SKIPPED, BM25 and enabled vector search still work,
search reports graph in degraded_sources, and capability reports no graph.
Enabling it again backfills skipped GRAPH lanes at combined startup. A rebuild
with graph disabled also marks previously completed GRAPH lanes SKIPPED at
cutover so the new generation can be backfilled later. Existing graph files and
retained generations are not erased by changing this flag.
Local identity defaults to BAAI/bge-m3 1024-d normalized (upgraded from
local:magibu/embeddingmagibu-200m 768-d; existing stores created before v0.9.3 must keep
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m and MESA_EMBEDDING_DIMENSION=768
unless rebuilt); external text-embedding-3-small
requires setting dimension to 1536. Do not enable external flag and keep an
unrelated dimension. Nemotron-3 profile requires 2048 and nemotron-qpass-v1,
with query/passage input types. Provider/model/revision/dimension/normalization
define a fenced embedding space; switch through reindex/rebuild, not live fallback.
Install optional ML/provider SDK extras for the selected backend. With models
disabled semantic generation is intentionally unavailable. MESA_ZERO_COST_MODE
selects local Ollama configuration but preserves validator settings and does
not prove an air gap. RAM budget precedence is explicit MAX_RAM_MB/MAX_MEMORY_BYTES,
cgroups, psutil, then 1 GiB safe fallback; this is not an RSS guarantee.
Queue per-tenant bounds must fit within global bounds. .env.example deliberately
uses smaller sample global and per-tenant bounds than code defaults.
Minimal V4 provider setup#
Start with the disposable root, key and grants from the
quickstart, with the server stopped.
For an external OpenAI-compatible extraction + embedding setup, install
uv sync --locked --python 3.11 --extra adapters (no local ML extra is needed).
Select models supported by your endpoint. The following is an example pairing,
not evidence of a real-provider run:
mkdir -p "$HOME/mesa-doc-demos"
export MESA_STORAGE_ROOT="$(mktemp -d "$HOME/mesa-doc-demos/v4-XXXXXX")"
export MESA_PRINCIPAL_ID=docs-principal
export MESA_API_KEY="$(.venv/bin/mesa-v4-admin issue-key --principal docs-principal)"
.venv/bin/mesa-v4-admin grant-role --principal docs-principal --tenant docs-tenant --role OWNER
.venv/bin/mesa-v4-admin grant-agent --principal docs-principal --agent docs-agent --permission SESSION_CREATE
export MESA_RUNTIME_PROFILE=combined
export MESA_LOAD_DOTENV=false
export MESA_MODEL_ENABLED=true
export MESA_EXTERNAL_PROVIDER_ENABLED=true
export MESA_TIER3_MODE=0
export MESA_LLM_MODEL=openai:gpt-4o-mini
export MESA_LLM_API_KEY="${OPENAI_API_KEY:?Supply the provider key privately first}"
export MESA_EMBEDDING_MODEL=openai:text-embedding-3-small
export MESA_EMBEDDING_BASE_URL=https://api.openai.com/v1
export MESA_EMBEDDING_API_KEY="$MESA_LLM_API_KEY"
export MESA_EMBEDDING_DIMENSION=1536
export MESA_EMBEDDING_NORMALIZED=true
export MESA_EMBEDDING_VERSION=v1A root without active vector artifacts adopts a changed embedding identity at
startup and backfills skipped VECTOR lanes. A root with active vectors requires
an explicit rebuild before changing identity. Keep MESA_API_KEY (MESA access) separate
from MESA_LLM_API_KEY / MESA_EMBEDDING_API_KEY (provider access). Modes 1/2 need
the validator A or A/B settings from the table below. Extraction is configured
separately and mode 0 still calls it.
AdapterFactory parses provider:model (ollama, openai, openai_compatible,
anthropic, mock). Embeddings support local sentence-transformers (ml extra) or
OpenAI-compatible endpoints (adapters extra); Claude/Ollama extraction does not
automatically configure embeddings. Native Ollama extraction requires a running
endpoint and an already available model; MESA does not provision it.
Select embeddings with MESA_EMBEDDING_MODEL=provider:model: local:...,
ollama:qwen3-embedding:4b, openai:text-embedding-3-small, or
openai_compatible:nvidia/nemotron-3-embed-1b. The second colon stays in the
model name. MESA_EMBEDDING_BASE_URL overrides the endpoint; Ollama otherwise
uses <MESA_OLLAMA_URL>/v1 and needs no key for a local server.
Local model servers and external providers (D31)#
An endpoint is considered local when its scheme is http or https and its host is localhost, 127.0.0.1, ::1, or host.docker.internal.
- With
MESA_EXTERNAL_PROVIDER_ENABLED=false(default): ollamaandopenai_compatible(for both LLM extraction and embedding) are allowed on local endpoints (e.g. Ollama on127.0.0.1:11434, or vLLM on127.0.0.1:8001/v1; MESA itself uses port 8000) and forbidden on non-local/remote endpoints.openai_compatibleon a local endpoint requires no API key (the client sendslocalautomatically).- External cloud providers (
openai,claude,anthropic,hosted) remain strictly forbidden regardless of endpoint URL. - With
MESA_EXTERNAL_PROVIDER_ENABLED=true: - Remote and cloud provider endpoints are allowed. Cloud providers and remote
openai_compatible endpoints require configured API keys (MESA_LLM_API_KEY,
MESA_EMBEDDING_API_KEY); local openai_compatible endpoints still default
to local, and Ollama keeps its existing key-free behavior.
Missing optional packages (P5-01)#
If an optional provider or model extra is selected but not installed, server startup halts with a clear one-line installation command:
- Ollama LLM, Ollama embedding, or OpenAI-compatible embedding:
pip install mesa-memory
- Local transformer embedding (
sentence-transformers):
pip install "mesa-memory[ml]"
Endpoint/key settings retain the MESA_LLM_BASE_URL / MESA_LLM_API_KEY fallbacks for those providers.
With embedding enabled and MESA_EMBEDDING_DIMENSION unset, the server and
rebuild runner embed one probe at startup and use its length for storage and
admission. Probe failure stops startup and names the model and URL. Setting the
dimension explicitly skips the probe; embedding disabled with no dimension
keeps 1024 and makes no embedding requests. The removed embedding provider,
external-model and local-model variables stop runtime startup with the
replacement setting. Nemotron still requires MESA_EMBEDDING_VERSION=nemotron-qpass-v1
and 2048 dimensions (explicit or detected).
The built-in mock adapter returns no extracted facts; it is not a source-backed
V4 demo. Contract tests inject deterministic fact and embedding providers
explicitly. Models-disabled startup, deterministic V4 tests and real-provider
V4 runs are different verification levels. V3 raw-memory processing requires
embeddings too; models-disabled boot does not demonstrate insert/search success.
