Concepts

Enscrive is built around three concepts that work together. Understanding how they relate is the key to using the platform effectively.

Tenant (your organization)
└── Environment (isolation boundary: dev, staging, production, …)
    ├── Corpus (documents + embedding vectors, bound to one model)
    └── Voice (chunking + retrieval configuration, model-agnostic)

Environments

An Environment is an isolation boundary inside your tenant. Corpora, voices, and API keys all live inside exactly one environment. Nothing you do in dev can affect production.

• Every tenant gets one default environment at creation time.
• Admins can create additional environments (for example dev, staging, production, experiment-q3).
• API keys are minted against a single environment — a dev key cannot read or write production data.

Typical workflow: experiment in dev, validate in staging, serve from production. Voice configurations can be promoted between environments once they pass their eval gates; corpora stay separate in each environment.

Corpora

A corpus is a searchable store of documents and their embeddings.

• Each corpus lives in a single environment.
• The embedding model is bound to the corpus at creation time and cannot be changed later. Switching models means creating a new corpus.
• The vector dimensions are set at creation time too, either to the model’s default or — for MRL-capable models like text-embedding-3-large — to an explicit truncation (for example 1024 out of 3072).
• Documents you ingest are split into chunks (see Ingest), embedded, and written to the corpus as vectors.

What lives on a corpus, beyond the obvious name and description: document_count, embedding_count (chunks, which is usually higher than document count), dimensions, model, pending_count (documents that have been staged but not yet committed), and dirty (true when there are pending changes).

The full corpus API is documented in Corpora. The distinction worth keeping close to hand:

The corpus holds the results of embedding. The voice decides how the embedding happens.

Voices

A Voice is a reusable configuration for chunking and retrieval. It is model-agnostic — the voice controls how documents are split and how search results are filtered and ranked, but the embedding model itself lives on the corpus.

A voice has three concerns:

1. Chunking. How documents are split before embedding. The default strategy is baseline — fixed-size token chunks with overlap, configurable via min_tokens / max_tokens / overlap parameters. Specialized strategies (story_beats, tone_segments) are available for narrative or mixed-tone content; see Chunking.

2. Retrieval. What happens at query time. Voice-tuned search (POST /v1/voices/search, or the CLI subcommand) applies the voice’s score_threshold, default_limit, and other retrieval tuning to the query. Raw search (POST /v1/search) does not.

3. Templates. LLM-driven segmentation voices can reference a segmentation template (template_id) that encodes an editorial prompt for how documents should be cut. See Segmentation.

The same corpus can be searched by different voices and produce different results — higher recall, stricter precision, narrower filtering — without touching the underlying embeddings. The voice compare endpoint runs the same query through two voices side-by-side so you can see the delta.

How they work together

Ingest

Document → (voice.chunking) → Chunks → (corpus.model) → Vectors → Corpus

You pick a corpus (where to store) and optionally a voice (how to chunk). Chunks get embedded with the corpus’s model and written to the corpus. If no voice is specified, the corpus’s default_voice_id is used; if there is no default, baseline chunking is applied.

Search

Query → (corpus.model) → Query vector → Corpus → (voice.retrieval) → Results

The query is embedded with the corpus’s model (the query’s embedding has to live in the same vector space as the stored chunks). The voice’s retrieval configuration then filters and ranks the results.

Promotion

dev (experiment) → staging (validate) → production (serve)

Voice configurations — not embeddings, not corpora — are promoted between environments. A production voice is an exact copy of a staging voice that passed its gates. The corpora in each environment remain independent; promotion is a configuration-copy, not a data-copy.

Quick reference