> ## Documentation Index > Fetch the complete documentation index at: https://docs.brussle.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a document, its answers and optional history > Reading a document with `on_read` judgments triggers their evaluation; the first read returns them `pending` unless `wait_ms` is passed. ## OpenAPI ````yaml /api-reference/openapi.yaml get /namespaces/{ns}/documents/{id} openapi: 3.1.0 info: title: Brussle API version: '1' license: name: Proprietary identifier: LicenseRef-Proprietary description: | The `/v1` contract. It is locked: changes within `/v1` are additive only, and anything breaking is `/v2`. - **Base URL.** `https://api.brussle.com/v1`. - **Evolution.** Response objects may gain fields and enums may gain values. Clients must ignore what they do not know. Request objects reject unknown fields. - **Path segments.** Namespace names (`{ns}`) and document ids (`{id}`) may contain `/`. Send it percent-encoded as `%2F`, so that `acme/prod/tenant_123` is `acme%2Fprod%2Ftenant_123`. - **Templates.** The judgment routes also take a namespace prefix ending in `/*`, such as `acme%2Fprod%2F*`. A judgment created there is a template: every namespace under the prefix inherits it, including ones created later. The most specific matching prefix wins. - **Thresholds are settings.** Named thresholds belong to the judgment, not to a version. They are evaluated at read time against the raw fields, so a change applies at once to every answer, with no recompute and no new version. - **Entity judgments.** A judgment can read the documents that point at the judged one, through `context.related`, and apply only to documents matching `applies_to`. Its answers carry a `watermark`, and creating one that runs `on_change` returns a replay estimate of its monthly cost until you confirm. - **Referenced documents.** A relation can also read the one document the judged document points at, through `join: {theirs: "id", mine: "attributes."}`. A change to what the relation renders of that document re-judges the judged documents that point at it and are inside `freshness.fanout.scope`: a fan-out. - **Relations.** A relation can read plain judgments' answers (banded or cut, never summed), or be a blocking relation over the documents that share a key, which a `choice` can choose among with `options.from`. A recipe can read the document as the judgment last saw it (`context.previous`). A judgment that can fan out confirms its rolling limits once, at create; past them, work is deferred, reads `stale` with an event, and catches up on its own. Nothing waits for a confirm at runtime. Groups keep aggregates per key value for reporting. - **Idempotency.** Every write operation is idempotent by construction: a retried append adds nothing while its values are still in the array, and a retried upsert or patch sets the same content again. Every request that changes something also takes an `Idempotency-Key`, so that creates, activations, backfills, draws and the rest can be retried safely too: a retry with the key gets the first response back, verbatim and marked `Idempotent-Replayed: true`, instead of running again (see the parameter). - **Errors.** Every error is the `Error` envelope; the HTTP status follows the code (see each response). - **Rate limits.** Every response to a request whose key was accepted carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`, which count the key's requests a second; a request refused before its key is checked (`unauthorized`, or a route that does not exist) carries neither. A `rate_limited` response adds `Retry-After`, except a daily allowance that is used up, which says when it renews in `details.resets_at` instead. Every `503` carries `Retry-After` too. Reads of one namespace also have a concurrency limit: past 32 gets and queries in flight at once, one more is `rate_limited` with `Retry-After` and `details.concurrent_reads`, whatever the rate-limit headers show. - **Usage.** Every response that bills carries `usage`. Judging is billed per judgment, engine-neutral, by size class: one judgment answered counts by the tokens of its compiled context and its question together, 1 if standard (up to 2,000 tokens), 4 if large (up to 8,000) and 16 if extra-large (up to 32,000, the engine maximum). No response ever carries an engine's price. servers: - url: https://api.brussle.com/v1 security: - apiKey: [] tags: - name: Namespaces description: Namespaces, their settings and cache warming. - name: Documents description: Writes, point reads and queries. - name: Judgments description: >- Judgment definitions, versions, settings, activation, backfill and template detach. - name: Outcomes and calibration description: | Post what actually happened to judged documents, and read how well answers match it: the calibration report, calibrated answers and threshold recommendations. See [calibration](/concepts/calibration). - name: Groups description: > Groups keep aggregates per value of a key attribute, a group-by you declare for reporting; a template's tenant summary publishes each tenant's groups, banded, as a document the platform can judge. - name: Jobs description: >- Backfill, shadow, periodic, deletion, reference index, evaluation export, resync, group build, discovery and simulation jobs. - name: Engines description: The engine registry. - name: Organization description: | Settings of the whole organization: prefixes marked non-production, which the tenant fee and template calibration pools leave out. - name: Subscriptions description: | Saved queries that send an event when a document starts or stops matching: the query's filter grammar, on a namespace or a template prefix, with the fields each event carries. - name: Webhooks description: | Webhook endpoints, the events feed, the delivery log, redelivery and recovery. Every event type and its body is under `webhooks`. Events are delivered at least once, signed as Standard Webhooks, and kept for 30 days. Webhooks are on every plan, and deliveries are not billed; plans set how many endpoints an organization has. paths: /namespaces/{ns}/documents/{id}: parameters: - $ref: '#/components/parameters/Namespace' - name: id in: path required: true description: The document id, with any `/` sent as `%2F`. schema: $ref: '#/components/schemas/DocumentId' get: tags: - Documents summary: Get a document, its answers and optional history description: | Reading a document with `on_read` judgments triggers their evaluation; the first read returns them `pending` unless `wait_ms` is passed. operationId: getDocument parameters: - name: include in: query description: | `history` adds the evaluation records of the current incarnation, newest first. `context` adds each evaluation's compiled context and `raw` the engine's raw response; both are large and only apply with `history`. style: form explode: false schema: type: array uniqueItems: true items: type: string enum: - history - context - raw - name: history_limit in: query description: Maximum evaluation records returned with `include=history`. schema: type: integer minimum: 1 - name: all_incarnations in: query description: Include history from earlier lives of the same id. schema: type: boolean default: false - name: answers in: query description: Judgment names whose answers to return. style: form explode: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/Name' - name: wait_ms in: query description: >- How long to wait for `on_read` answers before returning them `pending`. schema: type: integer minimum: 0 maximum: 10000 responses: '200': description: The document. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/GetDocumentResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' components: parameters: Namespace: name: ns in: path required: true description: The namespace name, with any `/` sent as `%2F`. schema: $ref: '#/components/schemas/NamespaceName' schemas: DocumentId: type: string description: >- Up to 128 bytes. Never exactly `.` or `..`, which a URL path can't carry. pattern: ^(?!\.\.?$)[A-Za-z0-9._:/-]+$ minLength: 1 maxLength: 128 Name: type: string description: >- A judgment, attribute or threshold name. Names are path segments in field references, so they never contain `.`. pattern: ^[A-Za-z0-9_-]+$ minLength: 1 maxLength: 128 GetDocumentResponse: type: object required: - answers - usage allOf: - $ref: '#/components/schemas/Document' properties: answers: $ref: '#/components/schemas/Answers' history: type: array description: With `include=history`, evaluation records newest first. items: $ref: '#/components/schemas/Evaluation' usage: $ref: '#/components/schemas/Usage' NamespaceName: type: string description: >- Up to 256 bytes. `/` separates levels of the hierarchy, as in `acme/prod/tenant_123`. Never exactly `.` or `..`, which a URL path can't carry. pattern: ^(?!\.\.?$)[A-Za-z0-9._:/-]+$ minLength: 1 maxLength: 256 Document: type: object required: - id - revision - incarnation - attributes - state - created_at - updated_at properties: id: $ref: '#/components/schemas/DocumentId' revision: $ref: '#/components/schemas/Revision' description: >- The namespace sequence at which the document last changed. Monotonic, not contiguous. incarnation: $ref: '#/components/schemas/Revision' description: >- The sequence at which this document was created or re-created after a delete. attributes: $ref: '#/components/schemas/Attributes' state: $ref: '#/components/schemas/State' created_at: $ref: '#/components/schemas/Timestamp' description: >- When this incarnation was created, the time of the write that created it unless that write gave its own `created_at`. Relations order by it, and `window` and `freshness.fanout.scope` count from it. updated_at: $ref: '#/components/schemas/Timestamp' Answers: type: object description: Answers keyed by judgment name. propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/Answer' Evaluation: type: object description: An immutable record of one computation. required: - id - document_id - revision - incarnation - judgment - judgment_version - engine - engine_version - context_hash - context_tokens - context_truncated - output - status - error - shadow - replay_of - created_at properties: id: type: string document_id: $ref: '#/components/schemas/DocumentId' revision: $ref: '#/components/schemas/Revision' incarnation: $ref: '#/components/schemas/Revision' judgment: $ref: '#/components/schemas/Name' judgment_version: $ref: '#/components/schemas/JudgmentVersionNumber' engine: type: string engine_version: type: string context_hash: type: string pattern: ^sha256:[0-9a-f]{64}$ context_tokens: type: integer minimum: 0 context_truncated: type: boolean output: description: The engine's numbers. Null when the evaluation failed. oneOf: - $ref: '#/components/schemas/EvaluationOutput' - type: 'null' status: type: string enum: - success - failed error: description: Why the evaluation failed. Null on success. oneOf: - $ref: '#/components/schemas/EvaluationError' - type: 'null' shadow: type: boolean description: >- True for shadow evaluations from activation reports, which never produce answers. replay_of: description: | For a replay after a Jev drift, the evaluation whose stored context it judged again in the new epoch: its context is that evaluation's, so it has none of its own. Replays recalibrate the new epoch; they never produce answers and are never billed. Null for every other evaluation. oneOf: - type: string - type: 'null' created_at: $ref: '#/components/schemas/Timestamp' latency_ms: type: integer minimum: 0 description: >- How long the engine request that produced it took, retries excluded. Absent for evaluations recorded before it was measured. watermark: $ref: '#/components/schemas/Revision' description: Entity judgments only. The log position the context was read at. answers_generation: type: integer format: int64 minimum: 0 description: >- Entity judgments only. How far the context had read other judgments' answers and block changes, beside `watermark`, as on the answer. child_answers_stale: type: boolean description: >- Entity judgments only, beside `answers_generation`. True when a document whose answers the context read had a newer revision still `pending`, so its last answer was rendered. Wait it out rather than act on it, since that document's new answer re-judges this one if it changes what a relation shows. related_documents: type: array description: | Entity judgments only, with `include=history,context` or from `GET .../evaluations/{id}`. Every related document the context read, rendered or aggregated, with the revision it was read at. items: $ref: '#/components/schemas/RelatedDocument' previous_revision: $ref: '#/components/schemas/Revision' description: >- For a recipe with `previous`, the revision the previous rendering came from; absent with `first_revision`. first_revision: type: boolean description: >- For a recipe with `previous`, true when the context showed nothing under `previous`, such as a document's first evaluation in its incarnation or a re-created id, and then `previous_revision` is absent. Absent for a recipe without `previous`. context: type: object description: With `include=history,context`, the compiled context the engine saw. raw: description: >- With `include=history,raw`, the engine's answer to this judgment alone, in the shape of `output`. It never carries other judgments' answers or the engine's token counts. Usage: type: object description: What this response billed. minProperties: 1 properties: bytes_written: type: integer format: int64 minimum: 0 description: | The data the write stores, as compact JSON in UTF-8: its operations' ids and fields, or the outcomes posted. Whitespace and `\u` escapes of non-ASCII text in the request are not counted, nor are `wait_for` and `wait_timeout_ms`, so the same data counts the same however it was encoded. bytes_scanned: type: integer format: int64 minimum: 0 judgment_units: type: integer format: int64 minimum: 0 description: > Judgments billed, each counted by its size class: the tokens of its compiled context and its question together (the question's text, criteria and every option or level) make it standard (up to 2,000 tokens, counts 1), large (up to 8,000, counts 4) or extra-large (up to 32,000, counts 16). They are metered when the answer is recorded, so writes with `wait_for` and reads with `wait_ms` return the answers without their count; it appears in your usage. tokens_evaluated: type: integer format: int64 minimum: 0 deprecated: true description: Never reported. Judging is billed in `judgment_units`. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: type: object description: >- Code-specific detail, such as the scan estimate on a refused query. Every `internal` error has `request_id`. properties: reason: type: string description: > Why, where one code has more than one cause. On `forbidden`, `payment_overdue`: a payment has been unpaid for 14 days, so the organization's keys are read-only until it is paid; reads still work, and paying restores writes within a few minutes. A key that is read-only itself is `forbidden` without a `reason`. On the events feed's `invalid_request`, `cursor_expired`. suggested_context: description: >- On a create without a context recipe, the recipe suggested from the namespace's documents, or null when there are none. oneOf: - $ref: '#/components/schemas/SuggestedContext' - type: 'null' Revision: type: integer format: int64 minimum: 0 Attributes: type: object description: >- Flat, filterable and sortable. At most 64 keys. Not sent to engines unless a context recipe names them. maxProperties: 64 propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/AttributeValue' State: type: object description: >- The JSON content judgments are made about. At most 1 MB. Never filterable. Timestamp: type: string format: date-time description: RFC 3339, UTC. Answer: type: object description: | The current answer of one judgment for one document, discriminated on `type`. Only `type` and `freshness` are always present: numbers and provenance are absent when no evaluation has succeeded. oneOf: - $ref: '#/components/schemas/BoolAnswer' - $ref: '#/components/schemas/ChoiceAnswer' - $ref: '#/components/schemas/ScoreAnswer' discriminator: propertyName: type mapping: bool: $ref: '#/components/schemas/BoolAnswer' choice: $ref: '#/components/schemas/ChoiceAnswer' score: $ref: '#/components/schemas/ScoreAnswer' JudgmentVersionNumber: type: integer format: int32 minimum: 1 EvaluationOutput: type: object description: >- The engine's raw numbers, each read as the answer it produced reads it, before calibration and thresholds. `p` for a bool; `value`, `dist` and `escape_p` for a choice; `score` and `dist` for a score. A composite judgment's evaluation has `parts`, each part's `p`; its combined `p` is computed when answers are read. properties: p: $ref: '#/components/schemas/Probability' value: type: string dist: $ref: '#/components/schemas/Distribution' escape_p: $ref: '#/components/schemas/Probability' score: type: number parts: type: object propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/Probability' features: $ref: '#/components/schemas/FeatureValues' EvaluationError: type: object required: - class - message properties: class: type: string enum: - retryable - terminal message: type: string RelatedDocument: type: object required: - relation - document_id - revision properties: relation: $ref: '#/components/schemas/Name' document_id: $ref: '#/components/schemas/DocumentId' revision: $ref: '#/components/schemas/Revision' evaluations: type: object description: >- When the relation read this document's answers, the evaluation behind each judgment's answer, by judgment name. propertyNames: $ref: '#/components/schemas/Name' additionalProperties: type: string ErrorCode: type: string description: | HTTP status by code: `invalid_request` 400, `unauthorized` 401, `budget_exceeded` 402, `plan_required` 402, `forbidden` 403, `not_found` 404, `conflict` 409, `too_large` 413, `engine_version_unavailable` 422, `insufficient_labels` 422, `idempotency_key_reused` 422, `rate_limited` 429, `internal` 500, `engine_unavailable` 503, `unavailable` 503. enum: - invalid_request - unauthorized - forbidden - not_found - conflict - too_large - rate_limited - budget_exceeded - plan_required - engine_unavailable - engine_version_unavailable - unavailable - insufficient_labels - idempotency_key_reused - internal SuggestedContext: type: object description: | The recipe suggested for a create without `context`, in the refusal's `details.suggested_context`. From a sample of the documents the definition applies to: it keeps short text, numbers, booleans and small attributes, and leaves out ids, timestamps, links, binary-looking and very long values, and rarely present fields; `excluded` says why for each. `max_tokens` is set to keep the context in the standard size class, at most 2,000. The same documents always give the same recipe. required: - recipe - cost_per_answer - whole_state_cost_per_answer - sampled_documents - excluded properties: recipe: $ref: '#/components/schemas/ContextRecipe' cost_per_answer: type: - number - 'null' minimum: 0 description: >- Mean judgments per answer, counted by size class, over the sample with this recipe and the definition's question. The suggested `max_tokens` is at most 2,000, the standard ceiling, less the question's tokens, so a context that fills it stays standard with its question. whole_state_cost_per_answer: type: - number - 'null' minimum: 0 description: The same with the whole `state`. sampled_documents: type: integer minimum: 1 excluded: type: array description: >- Each path left out, and why, so you can put back what the question needs. items: type: object required: - path - reason properties: path: type: string reason: type: string enum: - id - timestamp - url - binary - long - rare - too_many AttributeValue: description: >- A string, number, boolean, string array or null. A number reads back as written; an integer is exact anywhere in the signed or unsigned 64-bit range, and a number with a fraction or exponent is a 64-bit float. `null` means no value, so the attribute is not stored. An upsert leaves it out, and a patch removes it. type: - string - number - boolean - array - 'null' items: type: string BoolAnswer: type: object description: A bool answer has no `value`; booleans come only from named thresholds. required: - type allOf: - $ref: '#/components/schemas/AnswerCommon' properties: type: const: bool p: $ref: '#/components/schemas/Probability' description: >- The engine's probability, or for a composite judgment the probability its combiner gives the parts. Thresholds, filters and ranking use it. calibrated: $ref: '#/components/schemas/BoolCalibration' parts: type: object description: Composite judgments only. Each part's raw `p` from the engine. propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/Probability' features: $ref: '#/components/schemas/FeatureValues' combiner: $ref: '#/components/schemas/CombinerUse' ChoiceAnswer: type: object required: - type allOf: - $ref: '#/components/schemas/AnswerCommon' properties: type: const: choice value: type: string description: >- The most probable option; ties go to the earlier option. For an `options.from` judgment, the matched candidate's document `id`, or `none_of_the_above`. dist: $ref: '#/components/schemas/Distribution' description: >- Probability per option. For an `options.from` judgment, a shortlist, not a ranking, listing only the candidates with any probability, and `none_of_the_above`. escape_p: $ref: '#/components/schemas/Probability' description: >- The probability of `none_of_the_above`. For an `options.from` judgment, the probability that no candidate matches; 1 when there were no candidates, with no engine call. calibrated: $ref: '#/components/schemas/ChoiceCalibration' ScoreAnswer: type: object required: - type allOf: - $ref: '#/components/schemas/AnswerCommon' properties: type: const: score score: type: number description: The probability-weighted mean of level values. dist: $ref: '#/components/schemas/Distribution' calibrated: $ref: '#/components/schemas/ScoreCalibration' Probability: type: number minimum: 0 maximum: 1 description: > Answers keep probabilities to about seven significant digits and return them as the shortest decimal that stands for the stored value, so an engine's 0.01 reads 0.01. Thresholds, query filters and threshold recommendations compare that decimal. Distribution: type: object description: Probability per option or level value. Sums to 1. additionalProperties: $ref: '#/components/schemas/Probability' FeatureValues: type: object description: >- Composite judgments with features only. Each feature's raw value, as rendered in the context; null when missing. propertyNames: $ref: '#/components/schemas/FeatureRef' additionalProperties: type: - number - 'null' ContextRecipe: type: object description: | What the engine sees. A create without it is refused with a suggested recipe, unless `use_context` asks for the suggestion or the whole `state`; a version with no recipe sends the whole `state`, subject to the engine limit. additionalProperties: false properties: fields: type: array description: Paths included verbatim, in order. items: type: string pattern: ^(state|attributes)(\.[^.]+)+$ last_n: type: object description: Per array path, keep the last n elements. additionalProperties: type: integer minimum: 1 window: type: object description: >- Per array path whose elements have a timestamp field `at`, keep elements within the window. additionalProperties: $ref: '#/components/schemas/Duration' max_tokens: type: integer minimum: 1 description: Hard cap; the compiler truncates from the end of the last field. related: type: object description: > Up to 4 relations, by name: documents in the same namespace that point at the judged one, or the one document it points at. Each renders as a `related.` entry after `fields`, and a write that changes what it renders makes the judged document's answer `pending` until it is judged again (for a referenced document, only inside the re-judge scope; outside it, the answer is `stale` with `stale_reason` `referenced_changed`). minProperties: 1 maxProperties: 4 propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/Relation' previous: $ref: '#/components/schemas/PreviousRecipe' AnswerCommon: type: object required: - freshness properties: freshness: $ref: '#/components/schemas/Freshness' stale_reason: $ref: '#/components/schemas/StaleReason' description: Present exactly when `freshness` is `stale`. revision: $ref: '#/components/schemas/Revision' description: The document revision the numbers were computed for. watermark: $ref: '#/components/schemas/Revision' description: > Entity judgments only: the log position the context was read at. Every write with a revision at or below it, to the document or its related documents, is reflected; a later one that touched the document makes the answer `pending` or `stale`. For a relation that reads a referenced document, it also says which version of that document the answer read. A later write to it that changes what the relation renders makes the answer `pending` when the document is inside the re-judge scope, and `stale` (`referenced_changed`) when it is outside, so a referenced document with a `revision` above the watermark shows the answer read an earlier version of it. Absent on a `failed` answer: its numbers are the last good ones, and the failed attempt's position does not describe them. answers_generation: type: integer format: int64 minimum: 0 description: | Entity judgments only: how far the context had read other judgments' answers and block changes, the second coordinate of the answer's position beside `watermark`. A child's answer or a block change after it makes the answer `pending` (`on_change`) or `stale` (`answers_changed`, or `document_changed` for a block) until it is judged again. Compare it only with other `answers_generation` values in the same namespace. Absent on a `failed` answer, like `watermark`. previous_revision: $ref: '#/components/schemas/Revision' description: >- For a recipe with `previous`, the revision the previous rendering came from. Absent when the context showed nothing under `previous`, as on a document's first evaluation. A `failed` answer keeps the last success's. referenced_changes: type: array description: | Get only, never in query rows. For a judgment with a relation that reads a referenced document: for each such relation, the newest write to the document the judged document points at now that changed what the relation renders, whether or not the document is inside the re-judge scope for it. A relation whose referenced document has never changed is left out, and so is the key when none has. A change at or below `watermark` is reflected in the answer. One above it makes the answer `pending` or `stale` when the document is inside the scope, and `stale` (`referenced_changed`) when it is outside. items: $ref: '#/components/schemas/AnswerReferencedChange' judgment_version: $ref: '#/components/schemas/JudgmentVersionNumber' engine: type: string engine_version: type: string evaluation_id: type: string description: | The evaluation that computed these numbers. When a change leaves the compiled context the same, the answer is reused for the new revision without calling the engine, and this still names the earlier evaluation, whose `revision` (and, for an entity judgment, `watermark`) is older than the answer's. evaluated_at: $ref: '#/components/schemas/Timestamp' thresholds: type: object description: >- The judgment's current thresholds (its setting, not the answer's version), evaluated at read time against the raw fields. propertyNames: $ref: '#/components/schemas/Name' additionalProperties: type: boolean BoolCalibration: type: object required: - p allOf: - $ref: '#/components/schemas/CalibrationCommon' properties: p: $ref: '#/components/schemas/Probability' CombinerUse: type: object description: | Composite judgments only: the combiner `p` came from, fitted on the judgment's outcomes per version and engine epoch. A composite's answer has no `calibrated` object. Being fitted to outcomes makes the combined `p` close to calibrated on data like its labels, not certainly; the calibration report's reliability curve is how to check. required: - outcomes - from_previous_epoch properties: outcomes: type: integer format: int64 minimum: 50 description: The labelled documents the combiner was fitted on. from_previous_epoch: type: boolean description: >- True after a Jev drift, while the answer's epoch has fewer than 50 outcomes, so the previous epoch's combiner applies. ChoiceCalibration: type: object required: - value - dist - escape_p allOf: - $ref: '#/components/schemas/CalibrationCommon' properties: value: type: string description: The most probable option under the calibrated distribution. dist: $ref: '#/components/schemas/Distribution' escape_p: $ref: '#/components/schemas/Probability' ScoreCalibration: type: object required: - score - dist allOf: - $ref: '#/components/schemas/CalibrationCommon' properties: score: type: number description: >- The probability-weighted mean of level values under the calibrated distribution. dist: $ref: '#/components/schemas/Distribution' Duration: type: string description: A whole number and a unit (`s`, `m`, `h` or `d`), such as `7d` or `1h`. pattern: ^[1-9][0-9]*[smhd]$ Relation: type: object description: | Documents that point at the judged document. They are ordered newest `created_at` first: `window` keeps those created within the window, then `last_n` keeps the newest n. At least one of `last_n` and `window` is required, and at least one of `fields` and `aggregate`. A relation reads at most the newest 1,000 documents. With `join: {theirs: "id", mine: "attributes."}` the relation reads the one document the judged document points at, its referenced document, and takes neither `last_n` nor `window`. With `join: {theirs: "attributes.", mine: "attributes."}` it is a blocking relation over the documents that share the judged document's key value. It needs `window`, takes `last_n` up to 254 (up to the `options.from` candidate limit when a `choice` chooses among it with `options.from`), and a change to its block re-judges the block's judged documents. `fields`, `aggregate` and `match` may read plain judgments' answers (`answers..`), banded or cut. additionalProperties: false required: - match - join allOf: - description: A relation renders fields or aggregates. if: not: required: - fields then: required: - aggregate - description: >- A relation over the documents that point at the judged one is bounded by `last_n` or `window`. if: properties: join: type: object properties: mine: const: id then: anyOf: - required: - last_n - required: - window - description: >- A relation that reads the referenced document takes neither `last_n` nor `window`. if: properties: join: type: object properties: theirs: const: id then: not: anyOf: - required: - last_n - required: - window - description: A blocking relation needs `window`, and reads at most 254 documents. if: properties: join: $ref: '#/components/schemas/BlockingJoin' then: required: - window properties: last_n: type: integer maximum: 254 properties: match: $ref: '#/components/schemas/RelationMatch' description: Which documents the relation reads. join: $ref: '#/components/schemas/RelationJoin' last_n: type: integer minimum: 1 maximum: 1000 description: >- Keep the newest n. Not on a relation that reads a referenced document; at most 254 on a blocking relation, and at most the `options.from` candidate limit (see Limits) when `options.from` chooses among it. window: $ref: '#/components/schemas/Duration' description: >- Keep documents created within this long before the later of the judged document's newest write and its newest related creation, at the answer's watermark. An edit to an old related document never moves the window. Not on a relation that reads a referenced document. fields: type: array description: >- Paths to include from each document, rendered under `records`, newest first. An entry may be a `BandedField`, which renders a number as its band. An entry may also be a plain judgment's `answers..value` and `answers..thresholds.` as they are, and its `.p`, `.score` and `.dist.