# Vainona

- [Introduction](https://docs.vainona.ai/index.md): A judgment layer for your data: typed judgments about your records, kept current, queryable and calibrated to your outcomes.
- [Quickstart](https://docs.vainona.ai/quickstart.md): From an API key to your first answers in five steps.
- [SDKs](https://docs.vainona.ai/sdks.md): Python and TypeScript clients, generated from the API contract.
- [System behavior](https://docs.vainona.ai/behavior.md): How the system is designed to behave, so you can build on it.
- [Tradeoffs](https://docs.vainona.ai/tradeoffs.md): What you give up for the cost structure, stated plainly.
- [Namespaces](https://docs.vainona.ai/concepts/namespaces.md): The unit of isolation, storage, caching, billing and scale.
- [Documents](https://docs.vainona.ai/concepts/documents.md): Records with filterable attributes and the state judgments are made about.
- [Judgments](https://docs.vainona.ai/concepts/judgments.md): Typed questions kept answered for every document.
- [Relations](https://docs.vainona.ai/concepts/relations.md): How a judgment reads other documents: the ones that point at it, or the one it points at.
- [Answers](https://docs.vainona.ai/concepts/answers.md): The current, queryable value of a judgment for a document.
- [Evaluations](https://docs.vainona.ai/concepts/evaluations.md): The immutable record of every computation, kept forever.
- [Freshness](https://docs.vainona.ai/concepts/freshness.md): Whether an answer reflects the document's current revision, and when answers are computed.
- [Composite judgments](https://docs.vainona.ai/guides/composite-judgments.md): Split a fuzzy yes/no question into narrow parts, combined by weights fitted on your labels, and measured on them before it answers.
- [Writing a context recipe](https://docs.vainona.ai/guides/context-recipes.md): Context size is the cost. Send the engine what it needs and nothing else.
- [Judge a document with its related documents](https://docs.vainona.ai/guides/related-documents.md): Judge an account with its tickets and invoices, a user with their posts or a conversation with its messages, and keep the answer current as any of them change.
- [Judge a document with the document it points at](https://docs.vainona.ai/guides/referenced-document.md): Judge an order line with its product, and control what re-judging costs when that product changes.
- [Choosing a freshness policy](https://docs.vainona.ai/guides/freshness-policies.md): Compute answers when documents change, when they are read, or on a schedule.
- [Measure, improve, tune](https://docs.vainona.ai/guides/measure-improve-tune.md): Find out how good a judgment is on your data, change it safely, and pick thresholds from your own outcomes.
- [Migrating from an LLM classification pipeline](https://docs.vainona.ai/guides/migrating-from-llm-classification.md): Move an existing classifier onto judgments: measure accuracy first, then cut over in a week.
- [Import existing data](https://docs.vainona.ai/guides/import-existing-data.md): Load your existing records in full batches, retry freely, and judge them once with the cost in front of you.
- [Keep your data in sync](https://docs.vainona.ai/guides/keep-data-in-sync.md): Copy every change from your database with whole-document upserts, never miss one with an outbox, and check the two agree.
- [Multi-tenant platforms](https://docs.vainona.ai/guides/multi-tenant-platforms.md): One namespace per tenant: isolated, independently billed, and free when idle.
- [Templates](https://docs.vainona.ai/guides/templates.md): Define a judgment once on a namespace prefix, and every tenant under it has it.
- [Engines](https://docs.vainona.ai/engines/index.md): Every engine version in the registry, with its limits and conformance results.
- [jev current](https://docs.vainona.ai/engines/jev-current.md): Limits, data handling and conformance results for jev current.
- [Pricing](https://docs.vainona.ai/pricing.md): Usage-based pricing: judgments, storage, writes, queries and pinning, with a monthly minimum.
- [Limits](https://docs.vainona.ai/limits.md): Every limit the API enforces.
- [List namespaces](https://docs.vainona.ai/api-reference/namespaces/list-namespaces.md)
- [Get namespace metadata, counts and budget](https://docs.vainona.ai/api-reference/namespaces/get-namespace-metadata-counts-and-budget.md)
- [Delete everything under the namespace](https://docs.vainona.ai/api-reference/namespaces/delete-everything-under-the-namespace.md): Deletes the namespace at once: when it returns, nothing of it is readable, and a write to the same name creates a new, empty namespace (§7.1.11). Starts a `namespace_delete` job that removes the deleted namespace's objects within 24 h (§7.10.11), and cancels the namespace's other open jobs, with `er…
- [Change budget, pinning and default engine](https://docs.vainona.ai/api-reference/namespaces/change-budget-pinning-and-default-engine.md): Settings are manifest fields (§7.2.8). Raising the budget clears `budget_paused` in the same commit.
- [Warm the namespace's caches](https://docs.vainona.ai/api-reference/namespaces/warm-the-namespaces-caches.md): Free and best-effort. Loads the manifest and the attribute and answer chunks into the preferred query node's caches (§7.5.9).
- [Write documents (upsert, patch, append, delete)](https://docs.vainona.ai/api-reference/documents/write-documents-upsert-patch-append-delete.md): Operations apply in the order upsert, patch, append, delete and commit atomically for the namespace. A request is never split across two commits. The namespace is created by its first write. See §6.4.
- [Get a document, its answers and optional history](https://docs.vainona.ai/api-reference/documents/get-a-document-its-answers-and-optional-history.md): Reading a document with `on_read` judgments triggers their evaluation; the first read returns them `pending` unless `wait_ms` is passed (§6.7, §7.5.7).
- [Get one evaluation record](https://docs.vainona.ai/api-reference/documents/get-one-evaluation-record.md): One evaluation of any document in the namespace, any incarnation and any judgment, with its compiled context and the engine's raw response (§6.7). Shadow evaluations are included, marked `shadow`. Unlike a document's history, it is found by id alone.
- [Filter, rank and page documents](https://docs.vainona.ai/api-reference/documents/filter-rank-and-page-documents.md): See §6.8. A query whose estimated scan exceeds 4 GB is refused with `too_large` and the estimate, and is not billed. Filtering or ranking on an `on_read` judgment is `invalid_request`.
- [List active judgments](https://docs.vainona.ai/api-reference/judgments/list-active-judgments.md): A namespace's list includes the judgments it inherits from templates, each marked with its `template`. On a prefix path it lists the template's own judgments (§7.7).
- [Create a judgment, or a new version of an existing name](https://docs.vainona.ai/api-reference/judgments/create-a-judgment-or-a-new-version-of-an-existing-name.md): Posting a name that exists creates version `n+1`; versions are immutable. The first version of a name is active on creation; a later version is inactive until activated, unless `activate: true`, which implies `force` and skips the shadow report (§6.5, §6.9).
- [Get all versions, the active version and thresholds](https://docs.vainona.ai/api-reference/judgments/get-all-versions-the-active-version-and-thresholds.md)
- [Deactivate a judgment](https://docs.vainona.ai/api-reference/judgments/deactivate-a-judgment.md): Answers and evaluations are retained. On a prefix path this deactivates the template for every namespace that inherits it. A namespace cannot delete a judgment it inherits (`conflict`); it can detach it first (§7.7).
- [Change freshness settings and thresholds without a new version](https://docs.vainona.ai/api-reference/judgments/change-freshness-settings-and-thresholds-without-a-new-version.md): Freshness settings and thresholds are not part of the definition, so this creates no version (§6.5).
- [Make a version the one new evaluations use](https://docs.vainona.ai/api-reference/judgments/make-a-version-the-one-new-evaluations-use.md): Existing answers keep their `judgment_version` until recomputed. Activating a version whose engine or definition differs from the active one without `force` returns a `shadow` job in `awaiting_confirm` (`202`). The job evaluates a random sample of 1,000 documents under the new version, never produci…
- [Estimate a backfill, or run it with confirm](https://docs.vainona.ai/api-reference/judgments/estimate-a-backfill-or-run-it-with-confirm.md): Without `confirm`, returns the estimate and does nothing. With `confirm: true`, starts a job. Backfills respect the namespace budget: an estimate that does not fit the remaining budget is refused (§6.9, §7.3.7). On a prefix path the backfill covers every namespace under the prefix, each within its o…
- [Detach an inherited judgment from its template](https://docs.vainona.ai/api-reference/judgments/detach-an-inherited-judgment-from-its-template.md): Turns a judgment the namespace inherits from a template into an ordinary judgment of the namespace, a copy of the current version (§7.7). The copy keeps the template's version numbers, up to and including the active version, which stays active, so existing answers still name a version the judgment h…
- [Suggest sub-questions for a composite judgment](https://docs.vainona.ai/api-reference/judgments/suggest-sub-questions-for-a-composite-judgment.md): Asks a general-purpose LLM for `count` narrow yes/no sub-questions (§6.5.1). It is given the judgment's `question` and `criteria` (of the newest version), and up to 30 of the namespace's labelled examples for the judgment, balanced between `true` and `false` and compiled with the judgment's context…
- [List templates](https://docs.vainona.ai/api-reference/judgments/list-templates.md): The organization's templates: every namespace prefix a judgment was created on (§7.7), in name order. A template stays listed after its judgments are deactivated, because it still decides which judgments the namespaces under it inherit. Manage a template's judgments on its prefix path (`/namespaces/…
- [Append observed outcomes or labelled examples](https://docs.vainona.ai/api-reference/outcomes/append-observed-outcomes-or-labelled-examples.md): Outcomes are append-only. Each is joined to its document's evaluation for the revision and incarnation that were current at `observed_at` minus the judgment's `horizon` (§6.10), so an evaluation that finishes after the outcome arrives still joins. An outcome that joins no successful evaluation is ke…
- [Get the calibration report for the active version](https://docs.vainona.ai/api-reference/outcomes/get-the-calibration-report-for-the-active-version.md): How well the active version's answers match the outcomes joined to its evaluations, per engine epoch, before and after calibration (§6.10). Calibration is fitted per judgment version and per engine epoch and refitted nightly: temperature (Platt) scaling from 100 outcomes, isotonic regression from 1,…
- [Recommend a threshold for a precision or recall target](https://docs.vainona.ai/api-reference/outcomes/recommend-a-threshold-for-a-precision-or-recall-target.md): The threshold on the raw `p` (bool) or raw `dist[option]` (choice) that meets the target on the active version's outcomes (§6.10). A document counts as predicted positive when the raw value is at least the threshold, and as positive when its outcome is `true` (bool) or equals `option` (choice).
- [Get progress, estimate and spend](https://docs.vainona.ai/api-reference/jobs/get-progress-estimate-and-spend.md)
- [Start a job in awaiting_confirm](https://docs.vainona.ai/api-reference/jobs/start-a-job-in-awaiting_confirm.md)
- [Pause a running job](https://docs.vainona.ai/api-reference/jobs/pause-a-running-job.md)
- [Resume a paused job](https://docs.vainona.ai/api-reference/jobs/resume-a-paused-job.md)
- [Cancel a job](https://docs.vainona.ai/api-reference/jobs/cancel-a-job.md)
- [List active engine versions](https://docs.vainona.ai/api-reference/engines/list-active-engine-versions.md): Active engine versions with their limits and conformance results (§7.4.5, §7.4.6). Never prices; judging is billed in judgment units whichever engine answers (§9).

## OpenAPI Specs

- [openapi](/api-reference/openapi.yaml)