{ "openapi": "3.1.0", "info": { "description": "The judging engine's service contract (v1). Bayesian is the system of record for judgments: definitions, norm verdicts with their condition decisions and as-of day, derivations, questions, presumptions and assumptions, and the journal of every change. The caller is the system of record for documents, rules and their review, geometry and the user-facing report; Bayesian judges the rules and provision texts the caller supplies and never re-extracts a reviewed rule.\n\nGenerated by `bayesian-admin openapi` from the Rust types (src/api.rs and the engine's); a test fails when this file differs from the generated one. Within v1 fields are only added.\n\nNorm status in a report (`ReportStatus.of`): meets → applies_meets; likely_not → applies_likely_not; cannot_tell → applies_cannot_tell (with the question that settles it); conditional → applies_meets_if (the open ways verbatim, what to ask the applicant for); not_applicable → not_applicable (with the condition decision). Every norm line carries the citation, the as-of day and its basis, `changed after …` flags, `condition_checks` and the norm's review state.\n\nConfidence of a norm line: the norm's review state approved or corrected → high, unvalidated → medium, read by a model or near (not verbatim) → low, never above what the verdict's `shown` label says.\n\nThe as-of day (`facts.as_of`): `filing` (the application's filing date), else `document` (the documentation's date) or `today`, both listed on each norm verdict as an assumption.\n\nCallbacks are optional; polling `GET /api/v1/jobs/{id}` with backoff is the default. A callback is `POST callback.url` with a `CallbackPayload`, headers `X-Bayesian-Signature: sha256=` and `X-Bayesian-Delivery: `, retried 3 times with backoff on a non-2xx answer. Responses carry `X-Request-Id`, `X-Bayesian-Build` and `X-Bayesian-Kb-Revision`. Bodies up to 1 MB. Request and result bodies are never logged: a log line carries the request id, the job id, the tenant and the organisation.", "title": "Bayesian API", "version": "1.0.0", "x-access": "API access is available to partners on request: info@geateh.si." }, "security": [ { "bearer": [] } ], "paths": { "/api/v1/account": { "get": { "description": "The account signed in (or the account whose tenant the key belongs to): the account, its tenant and scopes, its settings and the limits in force (`settings.own` what the admin set, the rest the server's defaults where it set nothing), today's research budget use (`budget`: day, used, limit, left), its open jobs, its tenant's keys by fingerprint (`current` the one its sessions act as) and its model credentials as `GET /api/v1/credentials` gives them (null when the server keeps none).", "operationId": "getAccount", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "type": "object" } } }, "description": "`{ account, tenant, scopes, settings, budget, jobs, keys, credentials, credentials_configured }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] }, { "session": [] } ], "summary": "Your account", "x-scope": "read" } }, "/api/v1/account/keys": { "post": { "description": "Signed in only (a key cannot replace itself): a new API key for your tenant with the scopes read, evaluate, facts:write and amend, shown this once; the key your sessions acted as is revoked at once. `{ key, fingerprint, revoked }`.", "operationId": "rotateKey", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "responses": { "201": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ key, fingerprint, revoked }`: the key is shown this once." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Limited" } }, "security": [ { "session": [] } ], "summary": "Rotate your key", "x-scope": "read" } }, "/api/v1/account/notices": { "get": { "description": "What the caller's account shows until they have seen it, newest first: `{ notices: [ { id, kind, created, body, seen } ] }`. `kind` is `rebase` (the shared base was refreshed; `body.summary` says what of theirs was carried over, `body.clashes` lists what was not carried as it was) or `promotion` (the admin took some of their work into the base; `body.targets`). None on a server without tenant copies.", "operationId": "accountNotices", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "notices": { "items": { "$ref": "#/components/schemas/Notice" }, "type": "array" } }, "type": "object" } } }, "description": "The notices." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "The account's notices", "x-scope": "read" } }, "/api/v1/account/notices/{id}/seen": { "post": { "description": "Marks one of the caller's notices seen. 404 for a notice that is not theirs.", "operationId": "accountNoticeSeen", "parameters": [ { "description": "The notice.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ id, seen: true }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Mark a notice seen", "x-scope": "read" } }, "/api/v1/accounts": { "get": { "description": "Every account, oldest first, with its settings, today's research budget use, its open jobs and live sessions; `defaults` the server's limits.", "operationId": "listAccounts", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ accounts: [ { account, settings, budget, jobs, sessions } ], defaults }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] }, { "session": [] } ], "summary": "The accounts (admin)", "x-scope": "admin" } }, "/api/v1/accounts/accept": { "post": { "description": "From the invite's link: `token` (from the link's fragment), the account holder's `name` and a `password` (10 to 256 characters). Makes the account, its tenant (`u-`) and the tenant's first API key (scopes read, evaluate, facts:write, amend), returned this once, and signs in: the answer sets the `bayesian_session` cookie. The password is kept only as its argon2id hash. 404 for an unknown invite, 400 for an expired one, 409 for a used one or an address with an account. Rate-limited per address.", "operationId": "acceptInvite", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "maxLength": 120, "type": "string" }, "password": { "maxLength": 256, "minLength": 10, "type": "string" }, "token": { "type": "string" } }, "required": [ "token", "name", "password" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account": { "$ref": "#/components/schemas/Account" }, "key": { "type": "string" }, "key_fingerprint": { "type": "string" } }, "type": "object" } } }, "description": "`{ account, key, key_fingerprint }`: the key is shown this once. Sets the session cookie.", "headers": { "Set-Cookie": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/Limited" } }, "security": [], "summary": "Accept an invite" } }, "/api/v1/accounts/{id}/disable": { "post": { "description": "The account signs in no more: its sessions end and its tenant's keys are revoked. Your own account cannot be disabled (409). `{ account, revoked_keys }`.", "operationId": "disableAccount", "parameters": [ { "description": "The account id (`a-…`).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "type": "object" } } }, "description": "`{ account, revoked_keys }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/InvalidRequest" } }, "security": [ { "bearer": [] }, { "session": [] } ], "summary": "Disable an account (admin)", "x-scope": "admin" } }, "/api/v1/accounts/{id}/settings": { "put": { "description": "The account's tenant's own limits: `daily_fill` (research sessions per UTC day), `rate_per_minute` (API requests), `max_concurrent_jobs` (queued or running at once). Each one absent or null leaves the server's default; all absent clears them. They hold for the tenant's keys and sessions together, from the next request.", "operationId": "putAccountSettings", "parameters": [ { "description": "The account id (`a-…`).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSettings" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "settings": { "$ref": "#/components/schemas/TenantSettings" } }, "type": "object" } } }, "description": "`{ account, tenant, settings }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] }, { "session": [] } ], "summary": "Set an account's limits (admin)", "x-scope": "admin" } }, "/api/v1/amend": { "post": { "description": "Set a status (active, superseded, stale, retracted, erroneous), retract, restore or purge items, rules or definitions, with a reason; journaled. A key may amend only what its tenant wrote unless it has `curate`.", "operationId": "amend", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The amendment report." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Amend knowledge", "x-scope": "amend" } }, "/api/v1/checks": { "post": { "description": "Check a text, or a parse from an earlier job, in a domain: its claims judged against the knowledge base and the caller's facts. For `si-building`: the site's norms in force on `as_of`, their conditions applied to the project, a norm block per claim; with `principles`, a derivation per claim. Returns a job; the result lists `questions` the caller can answer with `POST /api/v1/jobs/{id}/facts`.", "operationId": "createCheck", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/LlmCredential" }, { "$ref": "#/components/parameters/LlmPayer" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } }, "description": "Accepted: the job is queued. Poll `GET /api/v1/jobs/{id}` or wait for the callback." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Limited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "security": [ { "bearer": [] } ], "summary": "Start a check", "x-scope": "evaluate" } }, "/api/v1/coverage": { "get": { "description": "Per planning unit (EUP) the knowledge base knows and per factor of the domain: the plan's norms in force on `as_of` (today by default) by review state (`approved` by a planner or the supplier, `unvalidated` as extracted or read), their articles, the cells with none (`missing`), and `in_words_only`: factors that want a number held there only in words. National acts are not counted. The curation backlog for a planner's review.", "operationId": "coverage", "parameters": [ { "description": "The municipality's code (Juršinci: 42).", "in": "query", "name": "municipality", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "as_of", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "domain", "required": false, "schema": { "default": "si-building", "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ municipality, as_of, domain, factors, units: [ { eup, zone, land_use, factors: { : { status, approved, unvalidated, in_words, articles } } } ], totals, in_words_only }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "What a municipality's plan holds", "x-scope": "read" } }, "/api/v1/credentials": { "get": { "description": "The model keys your tenant stored, as far as they can be read back: provider, fingerprint, last four characters, when checked, whether research may use them. Never the key.", "operationId": "listCredentials", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ credentials: [ { provider, fingerprint, last4, allow_research, checked, created } ] }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "security": [ { "bearer": [] } ], "summary": "Your model credentials", "x-scope": "evaluate" } }, "/api/v1/credentials/{provider}": { "delete": { "description": "Your tenant's checks go back to the service's key.", "operationId": "deleteCredential", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ removed }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Remove your model key", "x-scope": "evaluate" }, "put": { "description": "Store your own key for `provider` (`anthropic`): your tenant's checks then run on it, the payer `user`, research only with `allow_research`. Checked live once with the smallest call; a key the provider refuses is not stored (400). Kept sealed at rest, never logged or journaled; the answer names it by fingerprint and its last four characters. 503 when the server keeps no credentials.", "operationId": "putCredential", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "anthropic" ], "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "allow_research": { "default": false, "description": "Whether checks may research (web search, paid on this key).", "type": "boolean" }, "key": { "description": "The provider's API key (Anthropic Console).", "type": "string" } }, "required": [ "key" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ provider, fingerprint, last4, allow_research, checked, created }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "security": [ { "bearer": [] } ], "summary": "Bring your own model key", "x-scope": "evaluate" } }, "/api/v1/definitions": { "get": { "description": "The definitions of a domain's concepts: analytic (with their composition and conditions, each with its provision) or operational; draft or accepted.", "operationId": "listDefinitions", "parameters": [ { "in": "query", "name": "domain", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The definitions." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "List definitions", "x-scope": "read" } }, "/api/v1/definitions/{predicate}": { "put": { "description": "Store a definition of a predicate (a new version when one exists), accepted; journaled.", "operationId": "putDefinition", "parameters": [ { "description": "The predicate key.", "in": "path", "name": "predicate", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The definition stored." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Define a concept", "x-scope": "curate" } }, "/api/v1/definitions/{predicate}/accept": { "post": { "description": "Mark the model's draft analysis of a predicate as reviewed and accepted; journaled.", "operationId": "acceptDefinition", "parameters": [ { "description": "The predicate key.", "in": "path", "name": "predicate", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The definition accepted." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Accept a draft definition", "x-scope": "curate" } }, "/api/v1/facts": { "post": { "description": "Store a card, plan acts and rules with their review states, or provision texts (each read into knowledge, its text kept verbatim) without a check. Journaled under the caller.", "operationId": "storeFacts", "parameters": [ { "description": "The domain profile the facts are kept under (`si-building`).", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/LlmCredential" }, { "$ref": "#/components/parameters/LlmPayer" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facts" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsStored" } } }, "description": "What was stored." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "security": [ { "bearer": [] } ], "summary": "Store facts ahead of checks", "x-scope": "facts:write" } }, "/api/v1/health": { "get": { "description": "200 while the process serves.", "operationId": "health", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Alive: `{ engine, kb, … }`." } }, "security": [], "summary": "Liveness" } }, "/api/v1/history": { "get": { "description": "Every change to knowledge, newest first, with its sequence number, time, actor, targets and reason; filtered by subject, predicate or actor; tenant-scoped.", "operationId": "history", "parameters": [ { "in": "query", "name": "subject", "schema": { "type": "string" } }, { "in": "query", "name": "predicate", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The events." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "The journal", "x-scope": "read" } }, "/api/v1/invites": { "get": { "description": "Every invite, newest first: its id (the first 8 hex digits of the token's hash), address, role, who made it, when it expires and whether it was used. Never a token.", "operationId": "listInvites", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "invites": { "items": { "$ref": "#/components/schemas/InviteView" }, "type": "array" } }, "type": "object" } } }, "description": "`{ invites: [Invite] }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] }, { "session": [] } ], "summary": "The invites (admin)", "x-scope": "admin" }, "post": { "description": "The demo is invite-only: make an invite for `email` with `role` (`user` by default, or `admin`) and get its link, `/accept#token=…`, shown this once (the token is kept only as its SHA-256; it rides in the fragment, so no server or proxy logs it). Valid for 7 days, once. The server sends no e-mail: pass the link on yourself. 409 when the address has an account, or on a server that started open (no key, account or invite); then make the first invite with `bayesian-admin accounts invite`.", "operationId": "createInvite", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "role": { "$ref": "#/components/schemas/Role" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "invite": { "$ref": "#/components/schemas/InviteView" }, "link": { "type": "string" } }, "type": "object" } } }, "description": "`{ link, invite }`: the link with the one-time token, and the invite as `GET` lists it." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/InvalidRequest" } }, "security": [ { "bearer": [] }, { "session": [] } ], "summary": "Invite someone (admin)", "x-scope": "admin" } }, "/api/v1/jobs": { "get": { "description": "The tenant's jobs, newest first; a key with an organisation sees its organisation's.", "operationId": "listJobs", "parameters": [ { "in": "query", "name": "org", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/JobStatus" } }, { "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } }, "description": "The jobs." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "List jobs", "x-scope": "read" } }, "/api/v1/jobs/{id}": { "get": { "description": "Its status; when done, `result` (the compact evaluation), `questions_open` and `run` (build, parameters, knowledge-base revision, prompts, model, usage, seconds).", "operationId": "getJob", "parameters": [ { "description": "The job id.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } }, "description": "The job." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Read a job", "x-scope": "read" } }, "/api/v1/jobs/{id}/explain/{claim}": { "get": { "description": "The claim's argument in prose: the rules that decided, their evidence, what was set aside and why.", "operationId": "explainClaim", "parameters": [ { "description": "The job.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The claim's position in `result.claims`.", "in": "path", "name": "claim", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The explanation: `{ text, verdict }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Explain a claim", "x-scope": "read" } }, "/api/v1/jobs/{id}/facts": { "post": { "description": "Supply facts that answer the job's `questions` (a norm for a factor, a provision's text with `about` copied from the question, a location card); a new job of kind `investigate` checks the same parse again with them.", "operationId": "answerJob", "parameters": [ { "description": "The job asked.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/LlmCredential" }, { "$ref": "#/components/parameters/LlmPayer" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobFacts" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } }, "description": "Accepted: the job is queued. Poll `GET /api/v1/jobs/{id}` or wait for the callback." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Limited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "security": [ { "bearer": [] } ], "summary": "Answer a job's questions", "x-scope": "facts:write" } }, "/api/v1/jobs/{id}/publish": { "post": { "description": "A permanent verdict page with versions; a later check of the same text adds a version.", "operationId": "publishJob", "parameters": [ { "description": "The job.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The verdict: `{ id, url, version }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Publish a job as a verdict", "x-scope": "publish" } }, "/api/v1/jobs/{id}/report": { "get": { "description": "From a finished check that carried the permit root (`principles: true`; 409 otherwise, never a guessed grouping): `kind=dopolnitev`, the open items under the GZ-1, 54. člen condition each blocks, with the provision that requires it; `kind=obrazlozitev`, per condition what was established (with its grounding), the provision applied as in force on the day, the norms set aside and the finding. `framing=pre_assessment` (the default; `authority_draft` only for an authority's key) titles it as a pre-assessment that needs professional sign-off, never an administrative act. `lang` sl or en; `text=1` adds the Markdown rendering. Provision references carry `rule_id` and `source_rule` as `considered[]` does. No model call: the render cache's renderings in `lang` are used, the rest stays as written (`untranslated`).", "operationId": "jobReport", "parameters": [ { "description": "The job.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "dopolnitev", "obrazlozitev" ], "type": "string" } }, { "in": "query", "name": "lang", "required": false, "schema": { "default": "en", "enum": [ "sl", "en" ], "type": "string" } }, { "in": "query", "name": "framing", "required": false, "schema": { "default": "pre_assessment", "enum": [ "pre_assessment", "authority_draft" ], "type": "string" } }, { "description": "`1` for the Markdown rendering.", "in": "query", "name": "text", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The report: `kind`, `framing`, `lang`, `title`, `notice`, `job_id`, `engine`, `kb_revision`, `job_kb_revision`, `generated`, `as_of`, `procedure`, `site`, `root`, `sections[]` (`condition`, `items[]` or `findings[]` with `established`, `applied_provision`, `set_aside`, `finding`), `contradictions`, `assumptions`, `text`, `untranslated`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "A permit check's document", "x-scope": "read" } }, "/api/v1/metrics": { "get": { "description": "Prometheus text: jobs by status, seconds per job, model calls, tokens, errors by code. Cluster-internal, or a key with `admin`.", "operationId": "metrics", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Prometheus exposition format." } }, "security": [ { "bearer": [] } ], "summary": "Metrics", "x-scope": "admin" } }, "/api/v1/norms/state": { "post": { "description": "A planner's review of norms (approved, corrected with the ways, rejected), so it reaches their weights: approved and corrected count 0.95, unvalidated 0.7; a rejected norm is withdrawn. Journaled with the reason.", "operationId": "reviewNorms", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormState" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "What changed: `{ op, rules, items }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Review norms", "x-scope": "curate" } }, "/api/v1/openapi.json": { "get": { "description": "This document as JSON.", "operationId": "openapi", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The OpenAPI 3.1 document." } }, "security": [], "summary": "The contract" } }, "/api/v1/ready": { "get": { "description": "200 when the store is reachable, the knowledge base loaded and the model backend configured; 503 otherwise, with the problems.", "operationId": "ready", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } }, "description": "Ready." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } }, "description": "Not ready." } }, "security": [], "summary": "Readiness" } }, "/api/v1/sessions": { "delete": { "description": "Ends the session of the cookie sent and clears the cookie. `{ signed_out }`: whether there was a live session.", "operationId": "signOut", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ signed_out }`; clears the cookie." } }, "security": [], "summary": "Sign out" }, "get": { "description": "`{ signed_in: true, account }` for a live session cookie, else `{ signed_in: false, accounts }` (`accounts`: whether this server signs in at all). Never an error.", "operationId": "currentSession", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ signed_in, account?, accounts? }`." } }, "security": [], "summary": "The current session" }, "post": { "description": "`email` and `password`; sets the `bayesian_session` cookie (HttpOnly, Secure, SameSite=Lax, Path=/; 14 days from its last use) and ends the session the browser had. 401 for a wrong address or password (the same answer for both), 403 for a disabled account; rate-limited per address and per e-mail address (429). A cookie is a second way to authenticate beside a key: a write it signs (POST, PUT, DELETE) needs `X-Requested-With: bayesian` or a same-origin `Origin`, or it is refused (403).", "operationId": "signIn", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/RequestedWith" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "type": "object" } } }, "description": "`{ account }`; sets the session cookie.", "headers": { "Set-Cookie": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Limited" } }, "security": [], "summary": "Sign in" } }, "/api/v1/tenants": { "get": { "description": "With tenant copies on (`BAYESIAN_TENANT_STORES`, the demo instance), every tenant reads and writes its own copy of the base, made from it on first use. Lists the copies (`tenant`, `location`, `created`, the base revision it was made from or last rebased on) and the engines in memory (`loaded`, `cap`, `engine_mb`, `reckoned_mb`, `evictions`). 404 without tenant copies.", "operationId": "listTenants", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "engines": { "$ref": "#/components/schemas/TenantStats" }, "tenants": { "items": { "$ref": "#/components/schemas/TenantStore" }, "type": "array" } }, "type": "object" } } }, "description": "`{ tenants: [TenantStore], engines: TenantStats }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "The tenants' copies", "x-scope": "admin" } }, "/api/v1/tenants/rebase": { "post": { "description": "After the base was refreshed: each copy (or the one `tenant` names) becomes the base as it is now, with everything its tenant wrote carried over: its terms, rules, items, definitions, choice points and contexts, the statuses it set on the base's items, and its gaps. Where both hold the same thing the base wins: a term or choice point of the base's stays and the tenant's is listed as a clash; a rule the base also has gets the tenant's items beside its own; a definition that rivals the base's accepted one comes as a draft beside it. One journaled change (`rebase`) per copy; each tenant gets a notice.", "operationId": "rebaseTenants", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "tenant": { "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ base_revision, rebased: [ { tenant, carried, clashes } | { tenant, error } ] }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Rebase the tenants' copies", "x-scope": "admin" } }, "/api/v1/tenants/{tenant}/promote": { "post": { "description": "Takes what `targets` name in the tenant's copy into the base (`rule:`: the rule, or the items of it the base lacks; `ev:`: one item; `term:`; `def:`), with a rule's class and a term's parents when the base lacks them. The items keep their provenance (who wrote them, in which tenant's copy) and get ids of the base; the promotion is journaled as the admin's (`promote`) with the reason. The tenant gets a notice. 400 when a target is not in the copy.", "operationId": "promote", "parameters": [ { "description": "The tenant.", "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "type": "string" }, "targets": { "items": { "type": "string" }, "type": "array" } }, "required": [ "targets", "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "report": { "$ref": "#/components/schemas/CarryReport" } }, "type": "object" } } }, "description": "`{ tenant, carried, report: CarryReport, revision }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Promote a tenant's work into the base", "x-scope": "admin" } }, "/api/v1/tenants/{tenant}/writes": { "get": { "description": "What the tenant wrote in its copy, by kind (`rules`, `items`, `terms`, `definitions`): the picking list for a promotion (`rule:`, `ev:`, `term:`, `def:`).", "operationId": "tenantWrites", "parameters": [ { "description": "The tenant.", "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{ tenant, revision, writes }`." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "What a tenant wrote", "x-scope": "admin" } }, "/api/v1/verdicts/{id}": { "get": { "description": "The published verdict, its latest version.", "operationId": "getVerdict", "parameters": [ { "description": "The verdict.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The verdict." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "Read a verdict", "x-scope": "read" } }, "/api/v1/verdicts/{id}/changes": { "get": { "description": "What changed between its versions and why (the journal's entries that changed its rules).", "operationId": "getVerdictChanges", "parameters": [ { "description": "The verdict.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The changes." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearer": [] } ], "summary": "A verdict's changes", "x-scope": "read" } } }, "components": { "parameters": { "IdempotencyKey": { "description": "A caller's key for a POST that creates work: the same key returns the same job; the same key with a different body is 409 `idempotency_conflict`. Kept 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "type": "string" } }, "LlmCredential": { "description": "Optional: an Anthropic API key used for this request's model calls only; never stored or logged. Luma does not send it: its checks run on the platform's key, and Luma charges its organisations from the job's `run.usage`.", "in": "header", "name": "X-Llm-Credential", "required": false, "schema": { "type": "string" } }, "LlmPayer": { "description": "Optional: who pays the model calls, recorded on the job's usage: `org` (with `X-Llm-Credential`) or `platform` (the default).", "in": "header", "name": "X-Llm-Payer", "required": false, "schema": { "$ref": "#/components/schemas/Payer" } }, "RequestId": { "description": "Echoed in the response and logged; generated when absent.", "in": "header", "name": "X-Request-Id", "required": false, "schema": { "maxLength": 200, "type": "string" } }, "RequestedWith": { "description": "`bayesian` on a write signed by the session cookie (or a same-origin `Origin`), against cross-site requests; a key needs neither.", "in": "header", "name": "X-Requested-With", "required": false, "schema": { "enum": [ "bayesian" ], "type": "string" } } }, "responses": { "ForbiddenScope": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`forbidden_scope`: the key lacks the operation's scope." }, "IdempotencyConflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`idempotency_conflict`: the same `Idempotency-Key` with a different body." }, "InvalidRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`invalid_request`: the body or a parameter is invalid." }, "Limited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`rate_limited` (with `Retry-After`) or `budget_exceeded` (the tenant's daily model budget)." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`not_found` (also for another tenant's or organisation's resource)." }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`unauthorized`: no key, or an unknown or revoked one." }, "Unavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`model_unavailable` (the model refused: a session or usage limit, no credential; nothing was stored) or `kb_schema_newer` (the store was written by a newer build)." } }, "schemas": { "Account": { "description": "An account as anyone may read it back: never its password.", "properties": { "created": { "type": "string" }, "disabled": { "description": "When it was disabled; a disabled account signs in no more.", "type": [ "string", "null" ] }, "email": { "description": "Lowercased; unique.", "type": "string" }, "id": { "description": "`a-` and 16 hex digits.", "type": "string" }, "key": { "description": "The fingerprint of its current API key: what its sessions act as.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/Role" }, "tenant": { "description": "`u-` and 16 hex digits; unique: the account's tenant, which its keys and jobs carry.", "type": "string" } }, "required": [ "id", "email", "name", "tenant", "role", "created" ], "type": "object" }, "Applies": { "description": "Whether the norm applies to the claim.", "enum": [ "yes", "no", "unclear" ], "type": "string" }, "AsOf": { "description": "The day a permit check is judged as of: the application's filing date,\nelse the documentation's date (an assumption). Later changes to the acts\nare flagged on the verdict but never decide it.", "properties": { "basis": { "$ref": "#/components/schemas/AsOfBasis" }, "date": { "description": "ISO date (`2023-03-15`).", "type": "string" } }, "required": [ "date", "basis" ], "type": "object" }, "AsOfBasis": { "description": "Why a permit check is judged as of its day.", "oneOf": [ { "const": "filing", "description": "The day the application was filed: the law in force then decides.", "type": "string" }, { "const": "document", "description": "The documentation's own date, the filing date being unknown: an assumption.", "type": "string" }, { "const": "today", "description": "Today, neither the filing date nor the documentation's date being known: an assumption.", "type": "string" } ] }, "Assumption": { "description": "One choice point at one value: what a rule, evidence item, definition\nor claim assumes, and what a context fixes.", "properties": { "point": { "description": "The choice point's id (`genocide_definition`).", "type": "string" }, "value": { "description": "One of its values (`broad_war_crimes`).", "type": "string" } }, "required": [ "point", "value" ], "type": "object" }, "AssumptionHow": { "description": "How a verdict used a choice point.", "oneOf": [ { "const": "fixed", "description": "The context (a named or explicit one, the text's own premises, a\nforced default) or the claim's own condition fixes the value: its\nrules decide and the other values' rules are left out.", "type": "string" }, { "const": "marginalised", "description": "Not fixed: the verdict is the prior-weighted mixture over the\npoint's values; the value listed is the default, with its prior.", "type": "string" }, { "const": "decisive_by_evidence", "description": "Not fixed and mixed, but every value of the point gives the same\nlabel: the evidence decides whichever value holds.", "type": "string" } ] }, "AssumptionUse": { "description": "A choice point a verdict rests on: \"assumes genocide_definition =\nconvention_intent (marginalised, prior 0.70)\".", "properties": { "how": { "$ref": "#/components/schemas/AssumptionHow" }, "point": { "type": "string" }, "prior": { "description": "The value's prior.", "format": "double", "type": "number" }, "value": { "description": "The value fixed; for a marginalised point, its default.", "type": "string" }, "where": { "default": [], "description": "Where the assumption enters the chain: rule ids, `definition '…'`,\n`indicator `, `claim #n`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "point", "value", "how", "prior" ], "type": "object" }, "Basis": { "description": "What a decision rests on.", "oneOf": [ { "const": "statute", "description": "A provision's own words, quoted.", "type": "string" }, { "const": "supplied", "description": "The project's facts as its documentation states them, or the place as given.", "type": "string" }, { "const": "assumption", "description": "Nothing given decides it: the usual case, to be confirmed.", "type": "string" } ] }, "Bound": { "description": "How a claimed quantity is meant: a threshold or requirement (\"the\nrequired 40,000 signatures\", \"at least\"), a ceiling (\"up to\"), or an\napproximation (\"about 1,000\").", "enum": [ "at_least", "at_most", "about" ], "type": "string" }, "Callback": { "description": "A URL to call when a job finishes, with the secret its body is signed with.", "properties": { "secret": { "description": "The HMAC-SHA256 key of `X-Bayesian-Signature: sha256=` over the raw body.", "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "secret" ], "type": "object" }, "CallbackDelivery": { "description": "A callback's delivery: tried `attempts` times, the receiver's last answer.", "properties": { "at": { "type": [ "string", "null" ] }, "attempts": { "format": "uint32", "minimum": 0, "type": "integer" }, "delivered": { "type": "boolean" }, "id": { "description": "`X-Bayesian-Delivery` of every attempt.", "type": "string" }, "last": { "description": "The receiver's last status, or why no answer came.", "type": [ "string", "null" ] } }, "required": [ "id", "delivered", "attempts" ], "type": "object" }, "CallbackPayload": { "description": "The body of a callback (`POST callback.url`).", "properties": { "job_id": { "type": "string" }, "result_url": { "description": "Where the job is read: `/api/v1/jobs/{id}`.", "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" } }, "required": [ "job_id", "status", "result_url" ], "type": "object" }, "CardAct": { "description": "An act in force at the place.", "properties": { "key": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "name" ], "type": "object" }, "CardMunicipality": { "properties": { "code": { "description": "The municipality's register code (RPE: 190 for Žalec).", "format": "uint32", "minimum": 0, "type": "integer" }, "name": { "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "CardParcel": { "properties": { "area_m2": { "format": "double", "type": [ "number", "null" ] }, "ko": { "format": "uint32", "minimum": 0, "type": "integer" }, "parcel": { "type": "string" } }, "required": [ "ko", "parcel" ], "type": "object" }, "CarryReport": { "description": "What a carry did.", "properties": { "choices": { "description": "Choice points and contexts carried.", "items": { "type": "string" }, "type": "array" }, "clashes": { "description": "What was not carried as it was, one line each.", "items": { "type": "string" }, "type": "array" }, "definitions": { "description": "Definitions carried, by predicate.", "items": { "type": "string" }, "type": "array" }, "items": { "description": "Items carried: (rule, id there, id here).", "items": { "maxItems": 3, "minItems": 3, "prefixItems": [ { "type": "string" }, { "type": "string" }, { "type": "string" } ], "type": "array" }, "type": "array" }, "lookups": { "description": "Gaps, sources, aliases and glosses carried (a rebase only).", "format": "uint", "minimum": 0, "type": "integer" }, "rules": { "description": "Rules carried whole (they were not here).", "items": { "type": "string" }, "type": "array" }, "statuses": { "description": "Statuses set on items both hold: the item ids.", "items": { "type": "string" }, "type": "array" }, "terms": { "items": { "type": "string" }, "type": "array" } }, "required": [ "lookups" ], "type": "object" }, "CaseCondition": { "description": "A condition of the single case that a statement about a kind leaves out.", "properties": { "condition": { "description": "The condition: a rule's condition term, or an analysis's condition (its predicate).", "type": "string" }, "provision": { "description": "The provision that sets it (\"ZON, 104. člen, (1)\").", "type": [ "string", "null" ] }, "words": { "description": "In words: the term's gloss, or the condition's description.", "type": "string" } }, "required": [ "condition", "words" ], "type": "object" }, "CheckRequest": { "description": "`POST /api/v1/checks`: check a text (or a stored parse) in a domain.", "properties": { "analysis_depth": { "description": "How many levels of analysis below a claim (default 3).", "format": "uint", "minimum": 0, "type": [ "integer", "null" ] }, "as_of": { "anyOf": [ { "$ref": "#/components/schemas/AsOf" }, { "type": "null" } ], "description": "The day the check is judged as of and why (the filing date, else the documentation's date)." }, "callback": { "anyOf": [ { "$ref": "#/components/schemas/Callback" }, { "type": "null" } ] }, "context": { "anyOf": [ { "$ref": "#/components/schemas/ContextSpec" }, { "type": "null" } ], "description": "A context fixing choice points (a named interpretation)." }, "domain": { "description": "The domain profile: `si-building` for a permit check.", "type": "string" }, "facts": { "anyOf": [ { "$ref": "#/components/schemas/Facts" }, { "type": "null" } ], "description": "The caller's facts: the location card, plan acts and rules with their review states, provision texts." }, "fill_gaps": { "description": "Web research sessions; 0, the default (si-building's knowledge comes from the caller). The service's model backend has no web tools: a value above 0 is answered `model_unavailable`.", "format": "uint", "minimum": 0, "type": [ "integer", "null" ] }, "label": { "description": "A label for the caller (a project id).", "type": [ "string", "null" ] }, "lang": { "description": "The language of the result's prose (`sl`, `en`); default the text's.", "type": [ "string", "null" ] }, "org": { "description": "The caller's organisation: the job, its verdict and what it derives about the project are scoped to it.", "type": [ "string", "null" ] }, "parsed": { "anyOf": [ { "$ref": "#/components/schemas/ParsedStatement" }, { "type": "null" } ], "description": "A parse returned by an earlier job (`result.parsed` of the verbose form), checked again without a parse." }, "principles": { "default": false, "description": "Reason from first principles: concepts analysed into their conditions, a derivation per claim.", "type": "boolean" }, "site": { "anyOf": [ { "$ref": "#/components/schemas/PlaceSpec" }, { "type": "null" } ], "description": "The site, when the caller does not supply its card in `facts`." }, "text": { "description": "The text to check: a DGD's relevant parts, a statement. One of `text` and `parsed`.", "type": [ "string", "null" ] } }, "required": [ "domain" ], "type": "object" }, "ChoiceKind": { "description": "What a choice point chooses between.", "oneOf": [ { "const": "definition", "description": "Which definition of a contested concept (\"genocide\": the Convention's\nintent requirement, or any grave war crime).", "type": "string" }, { "const": "reading", "description": "Which reading of a text or doctrine (Kant's idealism: two aspects or two worlds).", "type": "string" }, { "const": "proposition", "description": "Whether a substantive premise holds (\"synthetic a priori judgments exist\": yes or no).", "type": "string" } ] }, "ChoicePoint": { "description": "A choice the evidence does not settle, with its values.", "properties": { "default": { "default": "", "description": "The value the default context assumes. Absent when proposing a point:\nthe value with the highest prior.", "type": "string" }, "draft": { "description": "Proposed (by the parser from a text's premise, or by operationalize\nfor a contested predicate) and not yet accepted: listed, never used\nin a verdict. `add_choice_point` with the same id accepts it.", "type": "boolean" }, "forced": { "description": "The default context fixes the point at its default value (a legal\ndefault that applies unless a context says otherwise) instead of\nmarginalising over the values by prior.", "type": "boolean" }, "gloss": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "default": "", "description": "What is being chosen, in one line." }, "id": { "description": "snake_case id (`genocide_definition`); its term is `choice:`.", "type": "string" }, "kind": { "$ref": "#/components/schemas/ChoiceKind", "default": "definition" }, "values": { "description": "Mutually exclusive and exhaustive values, each with a prior.", "items": { "$ref": "#/components/schemas/ChoiceValue" }, "type": "array" } }, "required": [ "id", "values" ], "type": "object" }, "ChoiceValue": { "description": "One value of a choice point.", "properties": { "basis": { "description": "Where the prior comes from: \"scholarly acceptance, SEP 2024\", \"legal\ndefault\", \"stated\".", "type": [ "string", "null" ] }, "gloss": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "default": "", "description": "What the value means, in one line." }, "id": { "description": "snake_case id, unique within the point (`convention_intent`).", "type": "string" }, "prior": { "description": "Prior probability that this value is the right one (0 to 1). The\npriors of a point are normalised to sum to 1 when it is stored.", "format": "double", "type": "number" } }, "required": [ "id", "prior" ], "type": "object" }, "Claim": { "properties": { "assumes": { "description": "The values of known choice points (listed under \"Known choice\npoints\") this claim is made under, when the text attaches one to it\n(\"under the Convention's definition, …\"). Omit otherwise. On ingest\nthe claim's evidence counts only under these values; in evaluation\nthey are fixed only in the text's own context.", "items": { "$ref": "#/components/schemas/Assumption" }, "type": "array" }, "attributed_to": { "description": "For an attribution: term id of who said or believes it.", "type": [ "string", "null" ] }, "bound": { "anyOf": [ { "$ref": "#/components/schemas/Bound" }, { "type": "null" } ], "description": "For a quantity in the object: whether it is a bound or an approximation\nrather than an exact value." }, "conditions": { "default": [], "description": "Context ids under which the statement is made, e.g. `luxury_goods`.", "items": { "type": "string" }, "type": "array" }, "dated": { "description": "The day the text was read (ISO date), from [`ParsedStatement::dated`]:\na claim without a time of its own is judged as of that day, so \"the\npast 24 hours\" in an article keeps its day when the verdict is judged\nagain later.", "type": [ "string", "null" ] }, "depends_on": { "description": "Other claims of this text this one leans on.", "items": { "$ref": "#/components/schemas/Dependency" }, "type": "array" }, "force": { "$ref": "#/components/schemas/Force", "default": "generic" }, "framing": { "anyOf": [ { "$ref": "#/components/schemas/Framing" }, { "type": "null" } ], "description": "Set only when the wording frames the referent in a misleading way." }, "kind": { "$ref": "#/components/schemas/ClaimKind", "default": "fact" }, "null_result": { "description": "The statement reports that no significant effect or difference was\nfound (\"no significant reduction in stroke\"): absence of evidence of\nan effect, not evidence that there is none. Encode with positive=false.", "type": "boolean" }, "object": { "description": "Object or value of the predicate when it has one, e.g. `sweet` for\n`has_property`. Omit for intransitive predicates.", "type": [ "string", "null" ] }, "place": { "description": "Where the claim holds: ISO country code (`SI`), `CC-Name` for a place\ninside a country (`SI-Ljubljana`), or a region (`europe`, `eu`, `world`).\nResolved to a place term and added to `conditions`.", "type": [ "string", "null" ] }, "positive": { "default": true, "description": "false when the statement denies the proposition (\"mammals do not lay eggs\").", "type": "boolean" }, "predicate": { "description": "snake_case predicate, e.g. `lays_eggs`, `has_property`, `causes`.", "type": "string" }, "public_act": { "description": "The claim is that a public act took place: something was published,\nposted, said or announced in public, a vote cast, a document signed or\nfiled. The act's own record (the post, the transcript, the voting\nrecord) settles it, whatever the act's content says.", "type": "boolean" }, "quantifier": { "description": "The hedge or quantity as written: \"most\", \"rarely\", \"70%\", \"always\".", "type": [ "string", "null" ] }, "self_reference": { "description": "The claim is about the text itself or what its author does in it:\nits structure and sections (\"this paper has three sections\",\n\"section two addresses …\"), its aim, scope or method (\"I am concerned\nwith …\", \"I do not examine …\"). The text settles it, not outside\nsources, so it is not researched. Not for what the text says about\nthe world: \"in section two I show that X causes Y\" is the claim that\nX causes Y, without this flag.", "type": "boolean" }, "subject": { "description": "Term id of the subject in its resolved sense (an existing KB term id,\nor the id of a term proposed alongside the claim).", "type": "string" }, "text": { "description": "The span of the original text this claim came from.", "type": [ "string", "null" ] }, "time": { "anyOf": [ { "$ref": "#/components/schemas/TimeScope" }, { "type": "null" } ], "description": "The period the claim is about; none means the day the text was read\n(`dated`), else today (or timeless, for kinds)." }, "timeless": { "description": "Whether the claim's truth is independent of the date it is judged on\n(an interpretation, a definition, who first did something), so a\nnewer source is another reading, not an update. Omitted: an\nattribution or evaluation is timeless, any other kind is not.", "type": [ "boolean", "null" ] }, "value": { "anyOf": [ { "$ref": "#/components/schemas/Quantity" }, { "type": "null" } ], "description": "A number the claim states, with its unit (FZ 0.35 → 0.35 ratio; 9 m)." } }, "required": [ "subject", "predicate" ], "type": "object" }, "ClaimKind": { "description": "What sort of statement the author is making; decides how a missing\nverdict should be read.", "oneOf": [ { "const": "fact", "description": "Something that is or was the case and could be checked.", "type": "string" }, { "const": "prediction", "description": "About the future: \"the party will get 3-4%\".", "type": "string" }, { "const": "attribution", "description": "The author reports what someone else said or believes (see `attributed_to`);\nthe claim is the reported content.", "type": "string" }, { "const": "evaluation", "description": "The author's judgement: \"a disastrous policy\", \"the best candidate\".", "type": "string" }, { "const": "insinuation", "description": "Implied but not stated: suggested motives, loaded juxtapositions. The\nclaim is the implied proposition.", "type": "string" }, { "const": "sentiment", "description": "A feeling or attitude: \"I'm so glad it's out\", \"she is frustrated\".", "type": "string" }, { "const": "hypothetical", "description": "Conditional or counterfactual: \"if the law passes, prices will rise\",\n\"had they acted sooner, …\". Not researched as a fact.", "type": "string" } ] }, "CompactClaim": { "description": "One claim's verdict, without argument trees or glosses.", "properties": { "alternatives": { "description": "Under other readings: the verdict with one of those points at one of\nits values, each with its prior (not equally valid alternatives).", "items": { "$ref": "#/components/schemas/ContextVerdict" }, "type": "array" }, "assumptions": { "description": "The choice points the verdict above rests on, anywhere in its chain:\n\"genocide_definition = convention_intent (marginalised, prior 0.70)\",\nwith where each enters. The verdict above is the headline.", "items": { "$ref": "#/components/schemas/AssumptionUse" }, "type": "array" }, "conditions": { "description": "Conditions beyond the document setting.", "items": { "type": "string" }, "type": "array" }, "definition": { "description": "For an operationalised evaluation: the definition used.", "type": [ "string", "null" ] }, "domain": { "description": "The domain the claim was evaluated under.", "type": [ "string", "null" ] }, "flags": { "items": { "type": "string" }, "type": "array" }, "force": { "$ref": "#/components/schemas/Force" }, "framing": { "anyOf": [ { "$ref": "#/components/schemas/CompactFraming" }, { "type": "null" } ] }, "indicators": { "description": "For an operationalised evaluation: each indicator's verdict.", "items": { "$ref": "#/components/schemas/CompactIndicator" }, "type": "array" }, "kind": { "$ref": "#/components/schemas/ClaimKind" }, "label": { "description": "Overall label; \"misleading\" / \"possibly misleading\" for framed claims.", "type": "string" }, "literal_label": { "description": "How true the literal words are, when framing changed the overall label.", "type": [ "string", "null" ] }, "local": { "anyOf": [ { "$ref": "#/components/schemas/LocalClaim" }, { "type": "null" } ], "description": "The claim in the request language when it is not English: the label,\nhow it is shown, its flags and assumptions through the vocabulary, the\nsubject's gloss and the predicate's reading through the render cache." }, "norm": { "anyOf": [ { "$ref": "#/components/schemas/NormResult" }, { "type": "null" } ], "description": "For a claimed value at a site: the norm in force it was compared with\n([`crate::norm::NormResult`]), with the assumptions the verdict rests on." }, "null_result": { "description": "The claim reports that no significant effect was found (absence of evidence).", "type": "boolean" }, "only_if": { "description": "For a statement about a kind: the conditions of the single case it\nleaves out, under which it was judged (a universal statement is false\nfor leaving them out).", "items": { "$ref": "#/components/schemas/CaseCondition" }, "type": "array" }, "opinion": { "description": "[belief, disbelief, uncertainty]", "items": { "format": "double", "type": "number" }, "maxItems": 3, "minItems": 3, "type": "array" }, "params": { "description": "Fingerprint of the parameter set that produced the verdict.", "type": "string" }, "positive": { "type": "boolean" }, "predicate": { "description": "Canonical predicate key as evaluated.", "type": "string" }, "probability": { "format": "double", "type": "number" }, "public_act": { "description": "The claim is that a public act took place (a post published, a statement\nmade, a vote cast), checkable from the act's own record.", "type": "boolean" }, "root": { "description": "The domain's root claim (si-building: that the permit may be issued),\nwhich a first-principles check adds: its conditions are its\n`indicators`, and it has no norm block. A client mapping claims to\nits own lines skips it by this.", "type": "boolean" }, "rules": { "description": "Rules that decided the verdict.", "items": { "type": "string" }, "type": "array" }, "self_reference": { "description": "The claim is about the text itself (its sections, what its author\ndoes in it): judged on no evidence, not researched, not a decided fact.", "type": "boolean" }, "shown": { "$ref": "#/components/schemas/Shown", "description": "How to show the verdict to people: \"verified\" when the evidence is\nbeyond reasonable doubt (with the basis), otherwise the label with a\nrounded probability. `probability` stays as computed." }, "subject": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "time": { "description": "Period the claim is about, e.g. \"2026\", \"1970–\"; absent means now.", "type": [ "string", "null" ] }, "unless": { "description": "For a statement about a kind: the exceptions for the single case it\nleaves out, presumed not to apply.", "items": { "$ref": "#/components/schemas/CaseCondition" }, "type": "array" } }, "required": [ "subject", "predicate", "positive", "kind", "force", "label", "probability", "shown", "opinion", "rules", "params" ], "type": "object" }, "CompactEvaluation": { "description": "The compact result of `evaluate_statement`: one entry per claim.", "properties": { "added_terms": { "items": { "type": "string" }, "type": "array" }, "claims": { "items": { "$ref": "#/components/schemas/CompactClaim" }, "type": "array" }, "context": { "description": "The context the claims were judged in when not the default (\"legal\",\n\"text_own\", \"genocide_definition = broad_war_crimes\").", "type": [ "string", "null" ] }, "contradictions": { "description": "Pairs of the text's claims that cannot both be right as judged (a\nblanket compliance statement against a value that likely fails the\nact's norm; a conclusion judged false from a premise that holds),\nalso flagged on both claims ([`crate::document::contradictions`]).", "items": { "$ref": "#/components/schemas/Contradiction" }, "type": "array" }, "derivations": { "description": "First principles: one derivation per claim, at claim i's position\n([`crate::principles`]). Empty for other passes.", "items": { "$ref": "#/components/schemas/Derivation" }, "type": "array" }, "filled": { "description": "With fill_gaps: what each fill did, \"subject predicate: outcome\" (including failures).", "items": { "type": "string" }, "type": "array" }, "framing_checked": { "default": false, "description": "Whether the framing review ran and succeeded; without it, framings are the fast pass's guesses.", "type": "boolean" }, "gaps": { "description": "\"subject predicate (reason)\" for each gap still open.", "items": { "type": "string" }, "type": "array" }, "lang": { "description": "The language the request is answered in (ISO 639-1): the one asked\nfor, else the text's own. Labels and flags in `local` are in it.", "type": [ "string", "null" ] }, "marked_individual": { "items": { "type": "string" }, "type": "array" }, "notes": { "description": "What is normal but worth saying, unlike a warning (a corpus without\nstructured rules: the site's norms are read from the plan's articles).", "items": { "type": "string" }, "type": "array" }, "premises": { "description": "Premises the text states (not claims): the known choice point and\nvalue each fixes, or a proposed point.", "items": { "$ref": "#/components/schemas/PremiseProposal" }, "type": "array" }, "questions": { "description": "What the evaluation could not settle and what would settle it: a site\nto locate, a norm for a factor at a site, a provision or record for a\nstatement ([`crate::facts::Question`]). A client answers through\n`facts` (on `evaluate_statement`, `investigate`, `supply_facts`).", "items": { "$ref": "#/components/schemas/Question" }, "type": "array" }, "setting": { "description": "Context terms that scope the whole text; applied to every claim.", "items": { "type": "string" }, "type": "array" }, "stats": { "$ref": "#/components/schemas/TextStats" }, "summary": { "additionalProperties": { "format": "uint", "minimum": 0, "type": "integer" }, "description": "Claim count per label, e.g. {\"likely true\": 12, \"insufficient evidence\": 30}.", "type": "object" }, "summary_local": { "additionalProperties": { "format": "uint", "minimum": 0, "type": "integer" }, "description": "`summary` with the labels in the request language (not English only).", "type": "object" }, "warnings": { "description": "Coverage problems: parts of the text that could not be parsed, dropped stub claims.", "items": { "type": "string" }, "type": "array" } }, "required": [ "summary", "stats", "claims" ], "type": "object" }, "CompactFraming": { "properties": { "agreement": { "description": "How many framing reviews flagged it, e.g. \"1/2\".", "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/FramingKind" }, "reason": { "type": "string" }, "standard": { "type": [ "string", "null" ] }, "standard_label": { "description": "Verdict on the standard characterisation, when it was encoded.", "type": [ "string", "null" ] } }, "required": [ "kind", "reason" ], "type": "object" }, "CompactIndicator": { "properties": { "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "Text in English as a plain string. Only when it quotes or reproduces a source written in another language: an object with the original in `text`, its ISO 639-1 code in `lang` and an English rendering in `en`." }, { "type": "null" } ], "description": "What it measures and why it bears on the evaluation." }, "hedge": { "description": "The indicator's verdict rests on evidence about a body the subject\nbelongs to, or inferred, only: the \"collective evidence only\" flag.", "type": [ "string", "null" ] }, "id": { "type": "string" }, "label": { "type": "string" }, "measurement": { "type": [ "string", "null" ] }, "predicate": { "type": "string" }, "probability": { "format": "double", "type": "number" }, "sampled": { "description": "For a measured indicator: the sampled items behind its deciding rule\n(titles as published, the original first).", "items": { "$ref": "#/components/schemas/SampledItem" }, "type": "array" }, "supports": { "type": "boolean" }, "validity": { "format": "double", "type": "number" } }, "required": [ "id", "predicate", "supports", "validity", "label", "probability" ], "type": "object" }, "ConditionCheck": { "description": "A norm condition's decision as the norm block shows it.", "properties": { "basis": { "anyOf": [ { "$ref": "#/components/schemas/Basis" }, { "type": "null" } ] }, "cite": { "description": "What decides it, as cited, and its words.", "type": "string" }, "condition": { "description": "The condition, in the provision's words.", "type": "string" }, "holds": { "description": "Whether it holds (none: the reader could not tell).", "type": [ "boolean", "null" ] }, "norm": { "description": "The norm rule whose condition it is.", "type": "string" }, "quote": { "type": "string" }, "reason": { "type": "string" }, "rule": { "description": "The rule holding the decision.", "type": "string" } }, "required": [ "norm", "condition", "reason", "rule" ], "type": "object" }, "Confidence": { "enum": [ "high", "medium", "low" ], "type": "string" }, "ContextSpec": { "description": "The context to evaluate in. As JSON: `\"default\"`, a context id\n(`\"legal\"`), `\"text_own\"`, a list of assumptions, or the tagged forms\n`{\"named\": \"legal\"}`, `{\"explicit\": [{\"point\": …, \"value\": …}]}`.", "oneOf": [ { "additionalProperties": false, "description": "A named context (`kb.contexts`), or `default`: every point at its\ndefault, marginalised unless the default is forced.", "properties": { "named": { "type": "string" } }, "required": [ "named" ], "type": "object" }, { "additionalProperties": false, "description": "These assumptions, at most one per point.", "properties": { "explicit": { "items": { "$ref": "#/components/schemas/Assumption" }, "type": "array" } }, "required": [ "explicit" ], "type": "object" }, { "const": "text_own", "description": "The text's own stated premises, resolved to known choice points\n(`ParsedStatement.premises`), and each claim's own `assumes`.", "type": "string" } ] }, "ContextVerdict": { "description": "The verdict with one choice point fixed at one value (`Verdict.alternatives`).", "properties": { "assumptions": { "description": "The assumptions this alternative fixes: the context's, with the\npoint in question at the value in question.", "items": { "$ref": "#/components/schemas/Assumption" }, "type": "array" }, "delta": { "description": "Probability minus the headline's.", "format": "double", "type": "number" }, "label": { "type": "string" }, "point": { "description": "The choice point varied and its value.", "type": "string" }, "prior": { "description": "The value's prior: how much the alternative counts for.", "format": "double", "type": "number" }, "probability": { "format": "double", "type": "number" }, "shown": { "default": "", "description": "How it is shown (\"likely true, 0.82\", \"verified\").", "type": "string" }, "value": { "type": "string" } }, "required": [ "assumptions", "point", "value", "prior", "label", "probability", "delta" ], "type": "object" }, "Contradiction": { "description": "Two claims of one text that cannot both be right as judged.", "properties": { "claims": { "description": "Their positions in the text's claims, from 0: the general claim or\nthe premise first.", "items": { "format": "uint", "minimum": 0, "type": "integer" }, "maxItems": 2, "minItems": 2, "type": "array" }, "kind": { "$ref": "#/components/schemas/ContradictionKind" }, "note": { "description": "The pair in words, as both claims' flags give it.", "type": "string" } }, "required": [ "claims", "kind", "note" ], "type": "object" }, "ContradictionKind": { "oneOf": [ { "const": "blanket_compliance", "description": "The text states that the project complies with an act, and a value\nit gives likely fails one of that act's norms.", "type": "string" }, { "const": "does_not_follow", "description": "The text concludes one claim from another (`derives`): the premise\nholds, the conclusion is judged false.", "type": "string" } ] }, "DefinitionNature": { "description": "Where a definition's conditions come from.", "oneOf": [ { "const": "operational", "description": "Indicators chosen as observable proxies for the evaluation\n(`operationalize`): a measurement methodology.", "type": "string" }, { "const": "analytic", "description": "The concept's defining conditions from its authoritative sources\n(scholarship, law, lexicography), as first-principles reasoning\nanalyses them (`first_principles`, the `analyse` prompt).", "type": "string" } ] }, "Dependency": { "description": "Another claim of the same text that this one leans on.", "properties": { "claim": { "description": "The other claim's position in `claims`, from 0.", "format": "uint", "minimum": 0, "type": "integer" }, "relation": { "$ref": "#/components/schemas/Relation" } }, "required": [ "claim", "relation" ], "type": "object" }, "Derivation": { "description": "One claim's derivation from first principles.", "properties": { "claim": { "description": "The claim's position in the text's claims.", "format": "uint", "minimum": 0, "type": "integer" }, "depth": { "description": "Levels of analysis below the claim (0: not analysed).", "format": "uint", "minimum": 0, "type": "integer" }, "grounds": { "description": "The leaves settled by evidence, in tree order.", "items": { "$ref": "#/components/schemas/Ground" }, "type": "array" }, "judgements": { "description": "Concept-laden conditions left unanalysed, \"subject predicate\".", "items": { "type": "string" }, "type": "array" }, "negated": { "description": "The claim denies its predicate (\"projektni pogoji niso upravni\nakti\"): the tree analyses the predicate, and the claim holds when it\ndoes not.", "type": "boolean" }, "open": { "description": "Leaves nothing decides yet, \"subject predicate\".", "items": { "type": "string" }, "type": "array" }, "presumptions": { "description": "What the derivation presumes or assumes without evidence: each\npresumption of a provision it rests on (holds unless shown otherwise)\nand each condition a reader took as holding for want of a fact.", "items": { "type": "string" }, "type": "array" }, "rendering": { "description": "The derivation as indented text.", "type": "string" }, "reviews": { "description": "Draft analyses to review: a necessary condition the statute itself\ndecides does not hold, so the analysis, not the claim, may be wrong.", "items": { "type": "string" }, "type": "array" }, "root": { "$ref": "#/components/schemas/DerivationNode" }, "stipulations": { "description": "The choice points the derivation rests on (which definition, which reading).", "items": { "$ref": "#/components/schemas/AssumptionUse" }, "type": "array" }, "text": { "type": [ "string", "null" ] } }, "required": [ "claim", "root", "depth", "rendering" ], "type": "object" }, "DerivationDefinition": { "description": "The definition an analysed node used.", "properties": { "basis": { "description": "The sources the definition rests on.", "items": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "Text in English as a plain string. Only when it quotes or reproduces a source written in another language: an object with the original in `text`, its ISO 639-1 code in `lang` and an English rendering in `en`." }, "type": "array" }, "composition": { "description": "\"all conditions must hold\", \"at least 2 of 4 conditions must hold\", …", "type": "string" }, "draft": { "type": "boolean" }, "label": { "description": "\"'is_fascist' v1 (draft, analysis)\".", "type": "string" }, "nature": { "$ref": "#/components/schemas/DefinitionNature" } }, "required": [ "label", "nature", "composition", "draft" ], "type": "object" }, "DerivationNode": { "description": "One node of a derivation: the claim, or a condition at any depth.", "properties": { "children": { "items": { "$ref": "#/components/schemas/DerivationNode" }, "type": "array" }, "definition": { "anyOf": [ { "$ref": "#/components/schemas/DerivationDefinition" }, { "type": "null" } ], "description": "For an analysed node: the definition and composition used." }, "direct": { "anyOf": [ { "$ref": "#/components/schemas/Grounding" }, { "type": "null" } ], "description": "For an analysed node that rules on the claim itself also decide: what\ngrounds them. The verdict fuses them with the analysis, so it can\nstand while the conditions are open." }, "flags": { "description": "The node's own flags worth a reader's eye: an undefined concept, a cycle, a draft definition.", "items": { "type": "string" }, "type": "array" }, "grounding": { "$ref": "#/components/schemas/Grounding" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/ClaimKind" }, { "type": "null" } ], "description": "For a condition: `fact` (directly checkable) or `evaluation` (a\nconcept of its own)." }, "label": { "type": "string" }, "predicate": { "type": "string" }, "probability": { "format": "double", "type": "number" }, "provision": { "description": "For a condition: the provision it rests on, as the definition names it.", "type": [ "string", "null" ] }, "shown": { "description": "How the node is shown (\"verified\", \"likely true, 0.89\").", "type": "string" }, "sources": { "description": "For a ground, or an analysed node's direct rules: the deciding\nevidence, \"kind: source (date)\".", "items": { "type": "string" }, "type": "array" }, "subject": { "type": "string" }, "supports": { "description": "For a condition: whether it counts toward the concept applying\n(true) or against it (a disqualifier, false).", "type": [ "boolean", "null" ] } }, "required": [ "subject", "predicate", "label", "probability", "shown", "grounding" ], "type": "object" }, "DocumentInfo": { "description": "A document of a corpus: an act with its versions.", "properties": { "cite_as": { "description": "The act's name inside a citation (\"GZ-1\", \"Odlok o OPN Občine Žalec\").", "type": "string" }, "id": { "description": "The corpus's key (`gz-1`, `pa-1234`): stable, used in term ids (`act:`).", "type": "string" }, "kind": { "$ref": "#/components/schemas/DocumentKind" }, "municipality": { "description": "The municipality of a municipal act (RPE code); none for national acts.", "format": "uint32", "minimum": 0, "type": [ "integer", "null" ] }, "publication": { "description": "The gazette line (\"Uradni list RS, št. 64/13\").", "type": [ "string", "null" ] }, "role": { "description": "A municipal act's role: `base` (the plan), `amendment`, `other` (a detailed plan).", "type": [ "string", "null" ] }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "versions": { "default": [], "description": "Oldest first.", "items": { "$ref": "#/components/schemas/VersionInfo" }, "type": "array" } }, "required": [ "id", "title", "cite_as", "kind" ], "type": "object" }, "DocumentKind": { "description": "What kind of text a document is.", "oneOf": [ { "enum": [ "other" ], "type": "string" }, { "const": "statute", "description": "A statute (zakon).", "type": "string" }, { "const": "regulation", "description": "A government decree or ministerial rule (uredba, pravilnik).", "type": "string" }, { "const": "plan", "description": "A municipal spatial plan or another act of a municipality (OPN, OPPN, odlok).", "type": "string" } ] }, "DocumentationStage": { "description": "The stage of the project documentation (Pravilnik o projektni in drugi dokumentaciji).", "oneOf": [ { "const": "dpp", "description": "Dokumentacija za pridobitev projektnih in drugih pogojev.", "type": "string" }, { "const": "dgd", "description": "Dokumentacija za pridobitev gradbenega dovoljenja.", "type": "string" }, { "const": "pzi", "description": "Projekt za izvedbo.", "type": "string" }, { "const": "pid", "description": "Projekt izvedenih del.", "type": "string" } ] }, "ErrorBody": { "description": "The error envelope's body.", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "details": true, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ErrorCode": { "description": "An error's code.", "oneOf": [ { "const": "unauthorized", "description": "No key, or one that is unknown or revoked: 401.", "type": "string" }, { "const": "forbidden_scope", "description": "The key lacks the route's scope: 403.", "type": "string" }, { "const": "tenant_mismatch", "description": "The resource belongs to another tenant or organisation: 404 to the caller, logged as this.", "type": "string" }, { "const": "invalid_request", "description": "The body or a parameter is invalid: 400.", "type": "string" }, { "const": "idempotency_conflict", "description": "The same `Idempotency-Key` with a different body: 409.", "type": "string" }, { "const": "budget_exceeded", "description": "The tenant's daily model budget is spent: 429.", "type": "string" }, { "const": "rate_limited", "description": "Too many requests: 429, with `Retry-After`.", "type": "string" }, { "const": "model_unavailable", "description": "The model refused (a session or usage limit, no credential): 503; nothing was stored.", "type": "string" }, { "const": "kb_schema_newer", "description": "The store was written by a newer build: 503 until the service is upgraded.", "type": "string" }, { "const": "not_found", "description": "404.", "type": "string" }, { "const": "interrupted", "description": "A job that was running when its process stopped: check again (a failed job's error).", "type": "string" }, { "const": "internal", "description": "Anything else that went wrong on the service's side: 500.", "type": "string" }, { "const": "shutting_down", "description": "The service is shutting down and takes no new work: 503; retry (another replica takes it).", "type": "string" } ] }, "ErrorResponse": { "description": "Every error response: `{ \"error\": { \"code\", \"message\", \"details\"? } }`.", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "error" ], "type": "object" }, "EvidenceKind": { "oneOf": [ { "enum": [ "meta_analysis", "study", "expert", "report", "anecdote" ], "type": "string" }, { "const": "proven", "description": "A proof, a settled theorem, a definition: contradicting it needs a lot.", "type": "string" }, { "const": "official_record", "description": "Official records: registries, election results, court filings, statistics offices.", "type": "string" }, { "const": "measurement", "description": "A measured or published value with its tolerance: an instrument\nreading, a standard, a value ± error. Judged against a claimed\nquantity by its interval (see [`Evidence::measured_value`]).", "type": "string" }, { "const": "llm_recall", "description": "What a language model recalled when asked; cheap, unsourced, to be\ncorroborated or contradicted by real sources later.", "type": "string" } ] }, "ExtractionState": { "description": "A planner's review of an extracted rule.", "oneOf": [ { "enum": [ "approved", "corrected" ], "type": "string" }, { "const": "unvalidated", "description": "Extracted by a model, not reviewed: `corpus.extracted_rule_reliability.unvalidated`.", "type": "string" }, { "const": "rejected", "description": "Wrong: never ingested.", "type": "string" }, { "const": "read", "description": "Read from the provision by the model during a check, for one claim,\nits quoted words checked against the provision: `…reliability.read`.", "type": "string" } ] }, "Facts": { "description": "What a caller supplies to an evaluation.", "properties": { "as_of": { "anyOf": [ { "$ref": "#/components/schemas/AsOf" }, { "type": "null" } ], "description": "The day the check is judged as of and why: the filing date, else the\ndocumentation's date (an assumption). Every claim about the site is\njudged as of it; later versions of an act are flagged, never decide." }, "documents": { "description": "The acts the norms come from, with their versions (validity, status).\nA norm whose document is not listed gets a document made from its\nlocus (current version, valid from the norm's version's day unknown).", "items": { "$ref": "#/components/schemas/DocumentInfo" }, "type": "array" }, "luma_location": { "description": "Luma's own answer to `POST /v1/location/resolve`, as it came: mapped\nto the site's card the way Bayesian's Luma adapter maps it (register\nunits over derived ones, shares over the parcels' area, regimes with\ntheir basis). Used when `site_card` is not given." }, "luma_plan_acts": { "description": "Luma's answer to `GET /v1/plan-acts?ob=`: the acts as\ndocuments with their versions, the base plan the zones belong to, and\nthe acts' corpus keys for the card." }, "luma_plan_rules": { "description": "Luma's answer to `GET /v1/plan-rules?ob=…&eup=…`: the plan's rules,\nmapped to norms as the adapter maps them (paragraphs are not looked\nup: the locus names the article)." }, "norms": { "description": "The plan's rules as structured norms: factor, operator, value, unit,\ncondition, the requirement verbatim, its locus (act, version, article,\nparagraph, citation, link) and review state.", "items": { "$ref": "#/components/schemas/StructuredRule" }, "type": "array" }, "org": { "description": "The organisation the project belongs to: what is derived from its\nfacts (the reader's decisions on the site, the norm comparisons, the\nrules read from its records) holds under `org:` only, and the\ncheck's claims carry `org:`, so another organisation's check of\nthe same parcel never sees it. Set from the check's `org`.", "type": [ "string", "null" ] }, "procedure": { "anyOf": [ { "$ref": "#/components/schemas/Procedure" }, { "type": "null" } ], "description": "The procedure the check is for (act, instrument, documentation stage,\nwhere the caller has it from): a project fact for the reader that\napplies provisions to the project, an assumption when from a profile." }, "site_card": { "anyOf": [ { "$ref": "#/components/schemas/PlaceCard" }, { "type": "null" } ], "description": "The site's location card: municipality, parcels, planning units (EUP,\nPEUP, land use, share), regimes, acts in force, as of a date, with its\n`source`. Taken instead of Bayesian's own resolver for the site it names." }, "sources": { "description": "Provision texts and records, ingested before the check (one model call each).", "items": { "$ref": "#/components/schemas/SourceText" }, "type": "array" }, "supplier": { "description": "Who supplies them (\"Luma Intelligence\"), for the journal and the notes.", "type": [ "string", "null" ] } }, "type": "object" }, "FactsStored": { "description": "`POST /api/v1/facts`: what was stored.", "properties": { "stored": { "description": "One line per thing stored (a card, the norms of an act, a source read).", "items": { "type": "string" }, "type": "array" }, "warnings": { "default": [], "items": { "type": "string" }, "type": "array" } }, "required": [ "stored" ], "type": "object" }, "Force": { "description": "What kind of statement a claim is; decides how ingestion stores it.", "oneOf": [ { "const": "generic", "description": "\"Mammals don't lay eggs\": a default about a class, exceptions allowed.", "type": "string" }, { "const": "universal", "description": "\"All mammals have hair\": claimed without exception.", "type": "string" }, { "const": "statistical", "description": "\"70% of consumers compare prices\": a frequency in a population.", "type": "string" }, { "const": "particular", "description": "\"This platypus laid an egg\", \"Apple's revenue fell\": about one instance or event.", "type": "string" } ] }, "Framing": { "description": "The parser's account of a non-neutral framing.", "properties": { "kind": { "$ref": "#/components/schemas/FramingKind" }, "reason": { "description": "One line: why the wording misleads.", "type": "string" }, "standard": { "description": "How the referent is standardly characterised, in plain words\n(\"the siege and sack of Baghdad by Hülegü's army, 1258\").", "type": [ "string", "null" ] }, "standard_claim": { "anyOf": [ { "$ref": "#/components/schemas/Claim" }, { "type": "null" } ], "description": "The standard characterisation encoded as a claim, so the knowledge\nbase can check it (subject mongols, predicate sacked, object baghdad)." } }, "required": [ "kind", "reason" ], "type": "object" }, "FramingKind": { "description": "How a claim frames what it describes. A claim can be literally true and\nstill mislead through its framing.", "oneOf": [ { "enum": [ "neutral", "correlation_as_causation", "biased_sample" ], "type": "string" }, { "const": "euphemism", "description": "Sanitised wording for something worse (\"expanded business operations\" for a massacre).", "type": "string" }, { "const": "dysphemism", "description": "Loaded wording for something milder.", "type": "string" }, { "const": "category_error", "description": "Describes the referent as a kind of thing it is not.", "type": "string" }, { "const": "cherry_pick", "description": "A selected window or subset that reverses or exaggerates the overall picture.", "type": "string" }, { "const": "relative_risk_without_base_rate", "description": "\"Doubles the risk\" without saying the risk is 1 in 10,000.", "type": "string" }, { "const": "misleading_implicature", "description": "True words that invite a false inference.", "type": "string" } ] }, "Ground": { "description": "A leaf of the derivation settled by evidence.", "properties": { "grounding": { "$ref": "#/components/schemas/Grounding" }, "label": { "type": "string" }, "predicate": { "type": "string" }, "probability": { "format": "double", "type": "number" }, "sources": { "items": { "type": "string" }, "type": "array" }, "subject": { "type": "string" } }, "required": [ "subject", "predicate", "label", "probability", "grounding" ], "type": "object" }, "Grounding": { "description": "What settles a node of a derivation.", "oneOf": [ { "const": "analysis", "description": "Composed from the conditions of a definition (the node's children).", "type": "string" }, { "const": "statute", "description": "Decided by a provision's own text: a statute's, regulation's or\nplan's article (an item with a corpus locus, or an official record\nciting an article).", "type": "string" }, { "const": "supplied", "description": "Decided by a fact the caller supplied (a location card, a record), with its source and date.", "type": "string" }, { "const": "record", "description": "Decided by an official record or a proof.", "type": "string" }, { "const": "measurement", "description": "Decided by a measurement: a counted sample or a value with its tolerance.", "type": "string" }, { "const": "stated", "description": "A project's value as the applicant states it in the documentation,\ncompared with the norm: the requirement is the statute's, the value\nis neither measured nor recorded.", "type": "string" }, { "const": "sources", "description": "Decided by sources: studies, expert statements, reports.", "type": "string" }, { "const": "recall", "description": "Decided by model recall only.", "type": "string" }, { "const": "presumption", "description": "Held by a presumption of the provision (\"until the special acts are\naligned\"): it holds unless evidence rebuts it.", "type": "string" }, { "const": "assumption", "description": "A reader applied a provision to the project and found nothing that\ndecides it: taken as holding, an assumption to confirm.", "type": "string" }, { "const": "judgement", "description": "A concept-laden condition left unanalysed: the leaf is a judgement, not a checked fact.", "type": "string" }, { "const": "open", "description": "Nothing decides it yet: an open gap.", "type": "string" } ] }, "InviteView": { "description": "An invite as the admin reads it back: never its token.", "properties": { "account": { "type": [ "string", "null" ] }, "created": { "type": "string" }, "created_by": { "description": "Who made it: an account id, `key:` or `bayesian-admin`.", "type": "string" }, "email": { "type": "string" }, "expires": { "type": "string" }, "id": { "description": "The first 8 hex digits of the token's SHA-256.", "type": "string" }, "role": { "$ref": "#/components/schemas/Role" }, "used": { "description": "When it was accepted, and the account it made.", "type": [ "string", "null" ] } }, "required": [ "id", "email", "role", "created_by", "created", "expires" ], "type": "object" }, "Job": { "description": "`GET /api/v1/jobs/{id}`.", "properties": { "callback": { "anyOf": [ { "$ref": "#/components/schemas/CallbackDelivery" }, { "type": "null" } ], "description": "What became of the callback the job asked for, once it was tried." }, "created": { "type": "string" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "type": "null" } ], "description": "Why a failed job failed." }, "finished": { "type": [ "string", "null" ] }, "job_id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/JobKind" }, "label": { "type": [ "string", "null" ] }, "org": { "type": [ "string", "null" ] }, "parent": { "description": "The job whose questions this one answers.", "type": [ "string", "null" ] }, "questions_open": { "default": 0, "description": "How many of `result.questions` are still open: the caller answers them with `POST /api/v1/jobs/{id}/facts`.", "format": "uint", "minimum": 0, "type": "integer" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/CompactEvaluation" }, { "type": "null" } ], "description": "The compact evaluation: claims with labels, norm blocks with `condition_checks`, `questions`, `notes`, `warnings`, `derivations` when `principles`." }, "run": { "anyOf": [ { "$ref": "#/components/schemas/RunInfo" }, { "type": "null" } ] }, "started": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/JobStatus" } }, "required": [ "job_id", "kind", "status", "created" ], "type": "object" }, "JobAccepted": { "description": "The answer to a POST that creates work: 202.", "properties": { "estimate_seconds": { "description": "Seconds the job is expected to take, when known.", "format": "double", "type": [ "number", "null" ] }, "job_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" } }, "required": [ "job_id", "status" ], "type": "object" }, "JobFacts": { "description": "`POST /api/v1/jobs/{id}/facts`: answer a job's questions; a new job of kind `investigate`.", "properties": { "callback": { "anyOf": [ { "$ref": "#/components/schemas/Callback" }, { "type": "null" } ] }, "facts": { "$ref": "#/components/schemas/Facts" }, "fill_gaps": { "description": "Web research sessions for the new job; 0, the default (above 0: `model_unavailable`, as for a check).", "format": "uint", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "facts" ], "type": "object" }, "JobKind": { "description": "What a job does.", "oneOf": [ { "const": "check", "description": "A check of a text or a parse.", "type": "string" }, { "const": "investigate", "description": "A check again with the caller's answers to its questions (`parent` is the job asked).", "type": "string" } ] }, "JobList": { "description": "`GET /api/v1/jobs`.", "properties": { "jobs": { "items": { "$ref": "#/components/schemas/Job" }, "type": "array" } }, "required": [ "jobs" ], "type": "object" }, "JobStatus": { "description": "A job's state.", "enum": [ "queued", "running", "done", "failed" ], "type": "string" }, "LocalClaim": { "description": "One claim as a reader of the request language sees it ([`localize`]).", "properties": { "alternatives": { "items": { "type": "string" }, "type": "array" }, "assumptions": { "items": { "type": "string" }, "type": "array" }, "flags": { "items": { "type": "string" }, "type": "array" }, "gloss": { "description": "What the subject term means.", "type": [ "string", "null" ] }, "label": { "type": "string" }, "lang": { "type": "string" }, "literal_label": { "type": [ "string", "null" ] }, "norm": { "anyOf": [ { "$ref": "#/components/schemas/LocalNorm" }, { "type": "null" } ] }, "reading": { "description": "The predicate key in words.", "type": [ "string", "null" ] }, "shown": { "type": "string" } }, "required": [ "lang", "label", "shown" ], "type": "object" }, "LocalNorm": { "description": "A claim's norm as a reader of the request language sees it.", "properties": { "applies": { "type": "string" }, "applies_reason": { "type": "string" }, "assumptions": { "items": { "type": "string" }, "type": "array" }, "cite_as": { "type": "string" }, "cite_as_beside": { "type": [ "string", "null" ] }, "conditions": { "items": { "type": "string" }, "type": "array" }, "requirement": { "description": "The requirement as a reader of the language sees it: verbatim when\nthe corpus writes in that language; for an English reader the\nEnglish rendering; for anyone else the original (never a\ntranslation alone).", "type": "string" }, "requirement_beside": { "description": "What is shown beside it: the original (English reader), the English\n(a reader of a third language), none (the corpus's language).", "type": [ "string", "null" ] }, "review": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_text": { "description": "The status in a reviewer's words (\"izpolnjuje le, če: (a) …\").", "type": "string" } }, "required": [ "status", "requirement", "cite_as", "applies", "applies_reason" ], "type": "object" }, "Locus": { "description": "Where a piece of evidence stands in an authoritative text. Generic: a\nstatute's article and paragraph, a plan's annex row, later a page of a\nphilosophical work (A/B pagination) in the same fields.", "properties": { "cite_as": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "The citation as a reader expects it (\"2. odstavek 75. člena Odloka …\"):\nthe original in the corpus language, with its English rendering once\nmade (\"Article 75(2) of the … Decree\")." }, "corpus": { "description": "The corpus it came from (`luma`, `file`).", "type": "string" }, "document": { "description": "The document's key (`gz-1`, `pa-1234`).", "type": "string" }, "domain": { "description": "The domain profile the item was ingested under, whose reliabilities\noverride `corpus.*` ([`crate::domain`]).", "type": [ "string", "null" ] }, "item": { "description": "A row inside the unit: an annex row's unit code (`SSe`, `ŽA-1/3`).", "type": [ "string", "null" ] }, "paragraph": { "description": "The paragraph (\"(2)\" → `2`), split by the adapter.", "type": [ "string", "null" ] }, "state": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionState" }, { "type": "null" } ], "description": "For a rule extracted by a model: its review state (none: the\nprovision's own text, a statute at `corpus.statute_reliability`)." }, "support": { "anyOf": [ { "$ref": "#/components/schemas/Support" }, { "type": "null" } ], "description": "For an extracted rule: how its words were found in the provision." }, "unit": { "description": "The unit as the corpus numbers it (`75`, `12.a`, `priloga-1`).", "type": "string" }, "url": { "type": [ "string", "null" ] }, "version": { "description": "The version cited (`npb-5`, `2`).", "type": "string" } }, "required": [ "corpus", "document", "version", "unit", "cite_as" ], "type": "object" }, "MeasuredValue": { "description": "A measured value: the number, its unit and its tolerance (± in the unit).", "properties": { "tolerance": { "format": "double", "type": [ "number", "null" ] }, "unit": { "type": [ "string", "null" ] }, "value": { "format": "double", "type": "number" } }, "required": [ "value" ], "type": "object" }, "NormDecision": { "description": "What became of a norm considered for a claim ([`NormLine::decision`]).", "oneOf": [ { "const": "decisive", "description": "It decides (with others at the same specificity, the weakest reading).", "type": "string" }, { "const": "overridden", "description": "A more specific norm decides.", "type": "string" }, { "const": "not_in_force", "description": "Its period does not cover the check's day.", "type": "string" }, { "const": "never_law", "description": "A draft or an unofficial text.", "type": "string" }, { "const": "other_subject", "description": "It is about another subject than the claim's.", "type": "string" }, { "const": "implausible", "description": "Its number cannot be a requirement on the factor: read for another element.", "type": "string" }, { "const": "not_its_case", "description": "Its condition does not hold for the project, as a reader decided it.", "type": "string" }, { "const": "condition_undecided", "description": "Its condition is not decided for the project; norms whose conditions\nhold decide as well or stricter, so it would apply only if it holds.", "type": "string" }, { "const": "does_not_apply", "description": "A reader found it does not apply to the claim (a ban on changing use,\nread for a new building).", "type": "string" }, { "const": "other", "description": "Another reason, in `status` (and a line stored before this field).", "type": "string" } ] }, "NormLine": { "description": "One norm that was considered for the claim.", "properties": { "cite_as": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "Text in English as a plain string. Only when it quotes or reproduces a source written in another language: an object with the original in `text`, its ISO 639-1 code in `lang` and an English rendering in `en`." }, "decision": { "$ref": "#/components/schemas/NormDecision", "default": "other", "description": "What became of it, for a machine ([`NormDecision`]); `status` says it in words." }, "outcome": { "description": "meets, violates, within tolerance, needs comparison, …", "type": "string" }, "required": { "type": "string" }, "requirement": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "Text in English as a plain string. Only when it quotes or reproduces a source written in another language: an object with the original in `text`, its ISO 639-1 code in `lang` and an English rendering in `en`." }, "rule": { "type": "string" }, "share": { "format": "double", "type": "number" }, "source_rule": { "description": "The corpus's own id of the structured rule it was read from (Luma's rule id).", "type": [ "string", "null" ] }, "status": { "description": "decisive, overridden (a more specific norm decides), not in force, draft, not applicable.", "type": "string" }, "zone": { "description": "The zone it was considered for, and the site's share in it.", "type": "string" } }, "required": [ "rule", "zone", "share", "cite_as", "requirement", "required", "status", "outcome" ], "type": "object" }, "NormResult": { "description": "The norm block of a verdict ([`Verdict::norm`]).", "properties": { "applies": { "$ref": "#/components/schemas/Applies" }, "applies_reason": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "Why the norm applies or may not: written by the engine, so English\nis its original (shown in other languages through the vocabulary)." }, "as_of": { "description": "The day the norms were selected as in force.", "type": "string" }, "assumptions": { "description": "What the verdict rests on, in words: the version assumed in force, the\nmembership share when below 1, the extraction state when not approved,\nthe norm's condition when the claim does not say whether it holds.", "items": { "type": "string" }, "type": "array" }, "cite_as": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "Text in English as a plain string. Only when it quotes or reproduces a source written in another language: an object with the original in `text`, its ISO 639-1 code in `lang` and an English rendering in `en`." }, "condition_checks": { "description": "A reader's decision on each condition that shaped the verdict: the\ndeciding norm's, and those of norms set aside because their condition\ndoes not hold for the project, each with its basis ([`crate::project`]).", "items": { "$ref": "#/components/schemas/ConditionCheck" }, "type": "array" }, "conditions": { "description": "With status `conditional`: each way of the norm the claim does not\naddress but could meet, verbatim with its article and paragraph, then\nthe ways not open for the claimed value (marked not applicable).", "items": { "type": "string" }, "type": "array" }, "considered": { "items": { "$ref": "#/components/schemas/NormLine" }, "type": "array" }, "disagreement": { "description": "The stated and the measured value differ beyond the measurement's tolerance.", "type": [ "string", "null" ] }, "factor": { "type": "string" }, "locus": { "anyOf": [ { "$ref": "#/components/schemas/Locus" }, { "type": "null" } ] }, "requirement": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "The requirement verbatim (the original, with its English rendering)." }, "review": { "description": "A planner's review of the deciding norm: state, who, when, the note.", "type": [ "string", "null" ] }, "rule": { "description": "The deciding norm rule.", "type": "string" }, "state": { "description": "The deciding norm's state: `statute` (the provision's own text),\n`unvalidated`, `read`, `approved`, `corrected`.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/NormStatus" }, "status_text": { "description": "The status in a reviewer's words (\"meets only if: (a) …; (b) …\").", "type": "string" }, "url": { "type": [ "string", "null" ] }, "value_basis": { "anyOf": [ { "$ref": "#/components/schemas/ValueBasis" }, { "type": "null" } ], "description": "Where the compared value comes from: `stated` (the applicant's own, in\nthe documentation) or `measurement` (supplied, with its provenance)." }, "value_claimed": { "type": [ "string", "null" ] }, "value_measured": { "description": "The measurement compared, with its tolerance and provenance.", "type": [ "string", "null" ] }, "value_required": { "type": [ "string", "null" ] } }, "required": [ "factor", "requirement", "cite_as", "applies", "applies_reason", "status", "rule", "as_of" ], "type": "object" }, "NormState": { "description": "`POST /api/v1/norms/state`: a planner's review of norms, so it reaches their weights.", "properties": { "correction": { "description": "With `corrected`: the ways the provision is met, as the planner corrected them.", "items": { "$ref": "#/components/schemas/Way" }, "type": [ "array", "null" ] }, "norms": { "description": "The norm rules (as a job's `norm.rule` or `considered[].rule` names them), or the caller's structured rule ids.", "items": { "type": "string" }, "type": "array" }, "reason": { "description": "The planner's note; journaled.", "type": "string" }, "state": { "$ref": "#/components/schemas/ReviewState" } }, "required": [ "norms", "state", "reason" ], "type": "object" }, "NormStatus": { "description": "The reviewer's reading of the comparison (never a pass/fail score: the\nverdict's label and probability stay the engine's).", "oneOf": [ { "enum": [ "meets", "likely_not", "cannot_tell", "not_applicable" ], "type": "string" }, { "const": "conditional", "description": "Meets only if a way the claim does not address holds (a consent, a\nrequirement in words, a procedure): the claim fails or does not give\nthe number, and another way remains open.", "type": "string" } ] }, "Notice": { "description": "Something a tenant's account shows until they have seen it (a rebase's\nclashes, a promotion of their work).", "properties": { "body": { "description": "`summary` (a line, in English), `summaries` (by language: `en`, `sl`)\nand what the kind adds (`clashes`, `targets`)." }, "created": { "type": "string" }, "id": { "type": "string" }, "kind": { "description": "`rebase` or `promotion`.", "type": "string" }, "seen": { "type": "boolean" } }, "required": [ "id", "kind", "created", "body", "seen" ], "type": "object" }, "Operator": { "description": "How a requirement constrains its factor.", "oneOf": [ { "enum": [ "eq", "min", "max", "range" ], "type": "string" }, { "const": "in", "description": "One of the values listed (a building type, a use).", "type": "string" }, { "const": "text", "description": "A requirement in words only.", "type": "string" } ] }, "ParsedStatement": { "description": "Result of parsing a piece of text.", "properties": { "analyse": { "description": "Only when first-principles reasoning is asked for (the request says\nso under \"First-principles reasoning\"): the predicate keys of the\nclaims whose truth depends on what a concept means (fascist,\ndemocracy, genocide, perjury, British as a status), exactly as used\nin `claims`. Otherwise leave it out.", "items": { "type": "string" }, "type": "array" }, "claims": { "items": { "$ref": "#/components/schemas/Claim" }, "type": "array" }, "dated": { "description": "The day the text was read (ISO date), set when it was parsed and kept\nwith the stored parse: claims without a time are judged as of it.", "type": [ "string", "null" ] }, "language": { "description": "The language the text is written in (ISO 639-1).", "type": [ "string", "null" ] }, "notes": { "default": [], "description": "Reference resolutions and sense choices made, in plain words\n(\"they = apples\"; \"apple read as the fruit, not the company\").", "items": { "type": "string" }, "type": "array" }, "place": { "description": "The place the whole text is about, when it has one; claims without\ntheir own place inherit it.", "type": [ "string", "null" ] }, "predicate_readings": { "description": "When the request is not in English: a human reading of each claim's\npredicate key, in English and in the request language.", "items": { "$ref": "#/components/schemas/PredicateReading" }, "type": "array" }, "premises": { "description": "Premises the text states rather than asserts (\"if genocide means any\ngrave war crime\", \"assuming synthetic a priori judgments exist\"):\nthe known choice point and value each fixes, or a proposed point.\nA premise is never also a claim.", "items": { "$ref": "#/components/schemas/PremiseProposal" }, "type": "array" }, "proposed_terms": { "default": [], "items": { "$ref": "#/components/schemas/TermProposal" }, "type": "array" }, "renderings": { "description": "When the request is not in English: the prose written for this\nparse (glosses, notes, framing reasons), each with its rendering in\nthe request language. Kept in the render cache, not in the knowledge base.", "items": { "$ref": "#/components/schemas/Rendering" }, "type": "array" }, "setting": { "default": [], "description": "Context term ids that scope the whole text: the election, period, place\nor event it is about. They apply to every claim.", "items": { "type": "string" }, "type": "array" }, "time": { "anyOf": [ { "$ref": "#/components/schemas/TimeScope" }, { "type": "null" } ], "description": "The period the whole text is about, when it has one; claims without\ntheir own time inherit it." } }, "required": [ "claims" ], "type": "object" }, "Payer": { "description": "Who pays a job's model calls.", "oneOf": [ { "const": "org", "description": "The organisation's own credential (`X-Llm-Credential`).", "type": "string" }, { "const": "platform", "description": "The service's key.", "type": "string" }, { "const": "user", "description": "The user's own key, stored with the service (`PUT /api/v1/credentials/{provider}`): the\ndemo's bring-your-own-key.", "type": "string" } ] }, "PlaceCard": { "description": "What a resolver knows about a place.", "properties": { "acts": { "default": [], "items": { "$ref": "#/components/schemas/CardAct" }, "type": "array" }, "municipality": { "anyOf": [ { "$ref": "#/components/schemas/CardMunicipality" }, { "type": "null" } ] }, "parcels": { "default": [], "items": { "$ref": "#/components/schemas/CardParcel" }, "type": "array" }, "regimes": { "default": [], "items": { "$ref": "#/components/schemas/Regime" }, "type": "array" }, "request": { "$ref": "#/components/schemas/PlaceSpec" }, "resolved_at": { "description": "When the resolver made the card (ISO).", "type": "string" }, "snapshot": { "description": "The newest date of the layers it was made from.", "type": [ "string", "null" ] }, "snapshots": { "additionalProperties": { "type": "string" }, "description": "The date of each layer the resolver read (`parcels`, `units:nrp`,\n`regimes:natura`, …), as the source's card names them.", "type": "object" }, "source": { "default": "", "description": "The resolver (`luma:https://…/geo`), for the evidence item's citation.", "type": "string" }, "units": { "default": [], "items": { "$ref": "#/components/schemas/ZoneUnit" }, "type": "array" }, "url": { "description": "A link to the card, when the resolver has one.", "type": [ "string", "null" ] } }, "required": [ "request", "resolved_at" ], "type": "object" }, "PlaceSpec": { "description": "A place to resolve.", "oneOf": [ { "additionalProperties": false, "description": "A gazetteer notation (`SI-Žalec`): resolved without a card.", "properties": { "gazetteer": { "type": "string" } }, "required": [ "gazetteer" ], "type": "object" }, { "additionalProperties": false, "description": "A cadastral parcel: cadastral municipality (k.o.) code and parcel number (`796/14`).", "properties": { "parcel": { "properties": { "ko": { "format": "uint32", "minimum": 0, "type": "integer" }, "parcel": { "type": "string" } }, "required": [ "ko", "parcel" ], "type": "object" } }, "required": [ "parcel" ], "type": "object" }, { "additionalProperties": false, "description": "A point (WGS 84).", "properties": { "point": { "properties": { "lat": { "format": "double", "type": "number" }, "lon": { "format": "double", "type": "number" } }, "required": [ "lon", "lat" ], "type": "object" } }, "required": [ "point" ], "type": "object" }, { "additionalProperties": false, "description": "A GeoJSON polygon.", "properties": { "polygon": true }, "required": [ "polygon" ], "type": "object" } ] }, "Polarity": { "enum": [ "required", "allowed", "prohibited" ], "type": "string" }, "PredicateReading": { "description": "A human reading of a predicate key: in English, and in the request language.", "properties": { "en": { "description": "What it says in plain English, as a verb phrase about the subject\n(\"called on Israel to comply with humanitarian law in Gaza\").", "type": "string" }, "key": { "description": "The predicate key exactly as used (`called_for_humanitarian_law_compliance_in_gaza_by:israel`).", "type": "string" }, "text": { "description": "The same in the request language, when it is not English.", "type": [ "string", "null" ] } }, "required": [ "key", "en" ], "type": "object" }, "PremiseProposal": { "description": "A premise a text states rather than asserts (\"if genocide means any\ngrave war crime\", \"assuming synthetic a priori judgments exist\"): not a\nclaim and not a hypothetical claim, but the context the text's claims\nare made in.", "properties": { "new_point": { "anyOf": [ { "$ref": "#/components/schemas/ChoicePoint" }, { "type": "null" } ], "description": "When no known point fits: a proposed choice point (snake_case id,\ngloss, kind, two or more values with priors), with the premise's\nvalue named in `value`. Stored as a draft only when the caller asks." }, "point": { "description": "The known choice point it fixes, when one fits (its id).", "type": [ "string", "null" ] }, "text": { "description": "The span of the text that states the premise.", "type": "string" }, "value": { "description": "The value of that point it fixes.", "type": [ "string", "null" ] } }, "required": [ "text" ], "type": "object" }, "Procedure": { "description": "The procedure a permit check is for: the act, the instrument it issues,\nthe documentation's stage, and where the caller has it from. The reader\nthat applies provisions to the project takes it as a project fact.", "properties": { "act": { "description": "The act, as the registry names it (`gz-1`).", "type": "string" }, "basis": { "$ref": "#/components/schemas/ProcedureBasis" }, "kind": { "$ref": "#/components/schemas/ProcedureKind" }, "stage": { "anyOf": [ { "$ref": "#/components/schemas/DocumentationStage" }, { "type": "null" } ] }, "works": { "description": "The works the procedure is for, as GZ-1 names them (Luma reads them from the title page):\na project fact for every reader, so a change-of-use norm is read against a new building.", "items": { "$ref": "#/components/schemas/Works" }, "type": "array" } }, "required": [ "act", "kind", "basis" ], "type": "object" }, "ProcedureBasis": { "description": "Where the caller has the procedure from.", "oneOf": [ { "const": "material", "description": "Read from the documents (the title page, the designer's statement): a supplied fact.", "type": "string" }, { "const": "profile", "description": "The caller's product or profile for the run, not the documents: an assumption.", "type": "string" } ] }, "ProcedureKind": { "description": "The instrument a permit procedure under GZ-1 issues.", "oneOf": [ { "const": "gradbeno_dovoljenje", "description": "Gradbeno dovoljenje.", "type": "string" }, { "const": "integralno_gradbeno_dovoljenje", "description": "Integralno gradbeno dovoljenje (with the environmental impact assessment).", "type": "string" }, { "const": "sprememba_gradbenega_dovoljenja", "description": "Sprememba gradbenega dovoljenja.", "type": "string" }, { "const": "uporabno_dovoljenje", "description": "Uporabno dovoljenje.", "type": "string" }, { "const": "dovoljenje_za_objekt_daljsega_obstoja", "description": "Dovoljenje za objekt daljšega obstoja.", "type": "string" }, { "const": "odlocba_o_legalizaciji", "description": "Odločba o legalizaciji.", "type": "string" } ] }, "Quantity": { "description": "A claimed quantity: a number, its unit and how it is meant.", "properties": { "bound": { "anyOf": [ { "$ref": "#/components/schemas/Bound" }, { "type": "null" } ] }, "unit": { "type": [ "string", "null" ] }, "value": { "format": "double", "type": "number" } }, "required": [ "value" ], "type": "object" }, "Question": { "description": "Something an evaluation could not settle, with what would settle it.", "properties": { "about": { "description": "The statements an answer is for: copy them into the source's `about`.", "items": { "$ref": "#/components/schemas/Statement" }, "type": "array" }, "answer": { "description": "Where the answer goes: `facts.site_card`, `facts.norms`, `facts.sources`.", "type": "string" }, "ask": { "description": "The question in plain words.", "type": "string" }, "claims": { "description": "The claims (positions in the evaluation's claims) it blocks.", "items": { "format": "uint", "minimum": 0, "type": "integer" }, "type": "array" }, "factor": { "description": "The factor key (`fz`, `height_m`) of a norm question.", "type": [ "string", "null" ] }, "id": { "description": "Stable for the same question: `locate:site:373-798/7`, `norm:site:373-798/7:fz`,\n`source::`.", "type": "string" }, "kind": { "$ref": "#/components/schemas/QuestionKind" }, "municipality": { "description": "The municipality's register code, when known.", "format": "uint32", "minimum": 0, "type": [ "integer", "null" ] }, "needs": { "description": "The fields an answer must carry.", "items": { "type": "string" }, "type": "array" }, "predicate": { "type": [ "string", "null" ] }, "provision": { "description": "For a source question about a referenced provision: the provision by\nact and article, as the analysis names it (\"GZ-1, 141. člen, (2) 3.\").", "type": [ "string", "null" ] }, "site": { "description": "The site it is about, as a site spec string (`373/798/7`) and its term.", "type": [ "string", "null" ] }, "site_term": { "type": [ "string", "null" ] }, "subject": { "description": "The statement of a source question.", "type": [ "string", "null" ] }, "zones": { "description": "The planning units a norm question is about.", "items": { "$ref": "#/components/schemas/QuestionZone" }, "type": "array" } }, "required": [ "id", "kind", "ask", "needs", "answer", "claims" ], "type": "object" }, "QuestionKind": { "description": "What a question asks for.", "oneOf": [ { "const": "locate_site", "description": "Where the site lies: municipality, planning units, land use, regimes, acts in force.", "type": "string" }, { "const": "norm", "description": "The norm in force for a factor in the site's planning units.", "type": "string" }, { "const": "source", "description": "A provision or record that settles a statement the knowledge base has no rule for.", "type": "string" } ] }, "QuestionZone": { "description": "A planning unit a norm question is about.", "properties": { "code": { "description": "The EUP code as the plan writes it.", "type": "string" }, "land_use": { "type": [ "string", "null" ] }, "share": { "description": "The site's share in it.", "format": "double", "type": "number" }, "sub_code": { "type": [ "string", "null" ] } }, "required": [ "code", "share" ], "type": "object" }, "Readiness": { "description": "`GET /api/v1/ready`.", "properties": { "kb_revision": { "description": "The knowledge base is loaded, at this revision.", "format": "uint64", "minimum": 0, "type": "integer" }, "model": { "description": "The model's last probe, when the service probes it (`BAYESIAN_PROBE_MINUTES`):\n\"answers\", \"limited: …\" (ready all the same: calls are answered\n`model_unavailable` with Retry-After), \"the model credential is rejected: …\"\n(not ready), \"the probe failed: …\"; with when it ran.", "type": [ "string", "null" ] }, "model_backend": { "type": "boolean" }, "problems": { "items": { "type": "string" }, "type": "array" }, "ready": { "type": "boolean" }, "store": { "type": "boolean" }, "tenants": { "anyOf": [ { "$ref": "#/components/schemas/TenantStats" }, { "type": "null" } ], "description": "With tenant copies on (the demo): the tenants' engines in memory\nagainst the cap, and what they are reckoned to hold." } }, "required": [ "ready", "store", "kb_revision", "model_backend" ], "type": "object" }, "Regime": { "description": "A protective regime over the place (heritage, flood, a road's protection belt).", "properties": { "basis": { "anyOf": [ { "$ref": "#/components/schemas/Locus" }, { "type": "null" } ], "description": "Its legal basis (a road belt's article), when known." }, "class": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "name": { "type": "string" }, "share": { "description": "Share of the place's area under it.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "kind", "name" ], "type": "object" }, "Relation": { "description": "How a claim leans on another claim of the same text.", "enum": [ "presupposes", "derives", "attributes" ], "type": "string" }, "Rendering": { "description": "One text the model rendered: the English it wrote (or was given) and\nits rendering in the request language.", "properties": { "en": { "description": "The English text, exactly as written in the answer's field.", "type": "string" }, "text": { "description": "Its rendering in the request language.", "type": "string" } }, "required": [ "en", "text" ], "type": "object" }, "ReportStatus": { "description": "A norm line's status in Luma's report.", "oneOf": [ { "enum": [ "applies_meets", "applies_likely_not" ], "type": "string" }, { "const": "applies_cannot_tell", "description": "With the question that would settle it.", "type": "string" }, { "const": "applies_meets_if", "description": "Meets only if a way the project does not address holds: the ways verbatim (what to ask for).", "type": "string" }, { "const": "not_applicable", "description": "With the condition decision that sets it aside.", "type": "string" } ] }, "ReviewState": { "description": "A planner's review state of a norm.", "enum": [ "approved", "corrected", "rejected" ], "type": "string" }, "Role": { "description": "What an account may do: `admin` everything (every scope, the admin\nroutes, invites); `user` what its own tenant's key may.", "enum": [ "admin", "user" ], "type": "string" }, "RuleScope": { "description": "Where a structured rule applies.", "oneOf": [ { "const": "unit", "description": "A planning unit (EUP).", "type": "string" }, { "const": "sub_unit", "description": "A sub-unit (PEUP) inside a planning unit.", "type": "string" }, { "const": "land_use", "description": "A land-use class (SS applies to SSe).", "type": "string" }, { "const": "general", "description": "The whole act (its general implementation conditions).", "type": "string" }, { "const": "building_type", "description": "A building type, under the act's general conditions.", "type": "string" } ] }, "RuleValue": { "anyOf": [ { "format": "double", "type": "number" }, { "type": "string" } ], "description": "A rule's value: a number, or a value in words (\"P+1\", \"dvokapnica\")." }, "RunInfo": { "description": "How a job ran: what a result is reproducible from.", "properties": { "engine_build": { "type": "string" }, "kb_revision": { "description": "The knowledge base's revision the result was judged on.", "format": "uint64", "minimum": 0, "type": "integer" }, "model": { "type": "string" }, "params_fingerprint": { "type": "string" }, "prompts": { "additionalProperties": { "type": "string" }, "default": {}, "description": "Each prompt used, by its versioned name (`parse: parse:1cf8085b`).", "type": "object" }, "seconds": { "format": "double", "type": "number" }, "usage": { "$ref": "#/components/schemas/Usage", "default": { "cached_calls": 0, "input_tokens": 0, "model_calls": 0, "output_tokens": 0, "usd_estimate": 0.0 } } }, "required": [ "engine_build", "params_fingerprint", "kb_revision", "model", "seconds" ], "type": "object" }, "SampledItem": { "description": "One sampled item of a measurement.", "properties": { "published": { "type": [ "string", "null" ] }, "reason": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "default": "", "description": "One line: why this stance." }, "stance": { "$ref": "#/components/schemas/Stance" }, "title": { "anyOf": [ { "type": "string" }, { "properties": { "en": { "description": "English rendering.", "type": "string" }, "lang": { "description": "ISO 639-1 code of the original (never en).", "type": "string" }, "text": { "description": "The original, verbatim.", "type": "string" } }, "required": [ "en", "lang", "text" ], "type": "object" } ], "description": "The item's title as published (a Slovene headline keeps the\noriginal in `text` with `lang: sl`, `en` its rendering)." }, "url": { "type": [ "string", "null" ] } }, "required": [ "title", "stance" ], "type": "object" }, "Scope": { "description": "What a key may do.", "oneOf": [ { "const": "read", "description": "Jobs, verdicts, explanations, history.", "type": "string" }, { "const": "evaluate", "description": "Start checks.", "type": "string" }, { "const": "facts:write", "description": "Supply facts: cards, norms, provision texts.", "type": "string" }, { "const": "amend", "description": "Amend knowledge: statuses, retractions.", "type": "string" }, { "const": "publish", "description": "Publish a job as a permanent verdict.", "type": "string" }, { "const": "curate", "description": "Definitions, norm review states, base-layer writes.", "type": "string" }, { "const": "admin", "description": "Keys and tenants.", "type": "string" } ] }, "Shown": { "properties": { "basis": { "description": "Why it counts as verified: \"official record: …\" or \"4 independent sources\".", "type": [ "string", "null" ] }, "text": { "description": "What to show: \"verified\", \"verified false\", or the label with a\nrounded probability (\"likely true, 0.87\").", "type": "string" }, "verified": { "description": "Some(true) verified true, Some(false) verified false, None otherwise.", "type": [ "boolean", "null" ] } }, "required": [ "text" ], "type": "object" }, "SourceText": { "description": "A source text the caller supplies: a provision verbatim, a record, a\npublished finding. Its statements are ingested as rules with evidence\nciting it.", "properties": { "about": { "description": "The statements this text is supplied for (copied from the questions\nit answers): it is read with exactly these subjects and predicate keys,\nso what it says about them lands on the rules the evaluation judges.", "items": { "$ref": "#/components/schemas/Statement" }, "type": "array" }, "kind": { "$ref": "#/components/schemas/EvidenceKind", "default": "official_record", "description": "What kind of evidence it is; default `official_record` (a provision's own text)." }, "measured": { "anyOf": [ { "$ref": "#/components/schemas/MeasuredValue" }, { "type": "null" } ], "description": "With `kind: measurement` and `about` naming a factor at a site (`site:…\nheight_m`): the measured value, its unit and tolerance. The text, source,\nlink and date are its provenance. It is not parsed: the factor's claim\nis judged with it ([`Facts::date_site_claims`])." }, "published": { "description": "The day the text applies or was published (ISO).", "type": [ "string", "null" ] }, "source": { "description": "The citation: \"GZ-1, 141. člen\", \"Odlok o OPN Občine Juršinci, 52. člen\".", "type": "string" }, "text": { "description": "The text: the article verbatim, the record's content.", "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "text", "source" ], "type": "object" }, "Stance": { "enum": [ "favourable", "neutral", "unfavourable" ], "type": "string" }, "Statement": { "description": "A statement by its subject term and predicate key (`predicate:object`).", "properties": { "predicate": { "type": "string" }, "subject": { "type": "string" } }, "required": [ "subject", "predicate" ], "type": "object" }, "StructuredRule": { "description": "A requirement extracted from a provision into fields: what it constrains\n(`factor`, `subject`), how (`operator`, `polarity`, `value`, `unit`),\nwhen (`condition`), its words (`text`) and where it stands (`locus`),\nwith the extraction's confidence, support and review state.", "properties": { "condition": { "type": [ "string", "null" ] }, "confidence": { "$ref": "#/components/schemas/Confidence" }, "doc": { "type": "string" }, "factor": { "type": "string" }, "id": { "description": "The corpus's id; sync is idempotent on it.", "type": "string" }, "locus": { "$ref": "#/components/schemas/Locus" }, "municipality": { "format": "uint32", "minimum": 0, "type": [ "integer", "null" ] }, "operator": { "$ref": "#/components/schemas/Operator" }, "period": { "anyOf": [ { "$ref": "#/components/schemas/TimeScope" }, { "type": "null" } ], "description": "The rule's own period, when the corpus dates each rule (Luma's\n`period`, its `valid_to` exclusive, kept here as the last day): it\ndecides over its version's validity, so a rule changed by an amendment\nholds from the amendment's day whatever the version's `as_of`." }, "polarity": { "$ref": "#/components/schemas/Polarity" }, "scope": { "$ref": "#/components/schemas/RuleScope" }, "scope_key": { "description": "The unit, land-use or building-type code(s) as the act writes them.", "type": [ "string", "null" ] }, "state": { "$ref": "#/components/schemas/ExtractionState" }, "subject": { "type": [ "string", "null" ] }, "superseded_by": { "type": [ "string", "null" ] }, "support": { "$ref": "#/components/schemas/Support" }, "text": { "description": "The requirement verbatim.", "type": "string" }, "unit": { "type": [ "string", "null" ] }, "unit_keys": { "description": "The national unit codes the scope key resolves to (EUP, or PEUP with a `/`).", "items": { "type": "string" }, "type": "array" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/RuleValue" }, { "type": "null" } ] }, "value_max": { "format": "double", "type": [ "number", "null" ] }, "version": { "type": "string" } }, "required": [ "id", "doc", "version", "scope", "factor", "operator", "polarity", "text", "locus", "confidence", "support", "state" ], "type": "object" }, "Support": { "description": "How the extracted rule's text was found in the provision.", "oneOf": [ { "enum": [ "verbatim" ], "type": "string" }, { "const": "near", "description": "Close to the provision's words, not the same: counts at `corpus.near_support_factor`.", "type": "string" }, { "const": "unsupported", "description": "Not found in the provision: never ingested.", "type": "string" } ] }, "TenantSettings": { "additionalProperties": false, "description": "A tenant's own limits; each one absent leaves the server's default.", "properties": { "daily_fill": { "default": null, "description": "Research sessions (fill_gaps) per UTC day; the server's `BAYESIAN_FILL_BUDGET` without it.", "format": "uint", "minimum": 0, "type": [ "integer", "null" ] }, "max_concurrent_jobs": { "default": null, "description": "Jobs queued or running at once; without it only the server's `BAYESIAN_WEB_MAX_PENDING` holds.", "format": "uint", "minimum": 0, "type": [ "integer", "null" ] }, "rate_per_minute": { "default": null, "description": "API requests per minute; the server's `BAYESIAN_WEB_RATE` without it.", "format": "uint32", "minimum": 0, "type": [ "integer", "null" ] } }, "type": "object" }, "TenantStats": { "description": "What `/ready` and `/metrics` show.", "properties": { "cap": { "description": "At most this many.", "format": "uint", "minimum": 0, "type": "integer" }, "engine_mb": { "description": "What one is reckoned to hold, in MB.", "format": "uint", "minimum": 0, "type": "integer" }, "evictions": { "description": "Engines dropped to make room since the process started.", "format": "uint64", "minimum": 0, "type": "integer" }, "loaded": { "description": "Engines held in memory now.", "format": "uint", "minimum": 0, "type": "integer" }, "reckoned_mb": { "description": "`loaded × engine_mb`.", "format": "uint", "minimum": 0, "type": "integer" } }, "required": [ "loaded", "cap", "engine_mb", "reckoned_mb", "evictions" ], "type": "object" }, "TenantStore": { "description": "A tenant's copy, as the index holds it.", "properties": { "base_revision": { "description": "The base's revision it was made from or last rebased on.", "format": "uint64", "minimum": 0, "type": "integer" }, "created": { "type": "string" }, "location": { "description": "Its Postgres schema, or its file.", "type": "string" }, "rebased": { "type": [ "string", "null" ] }, "tenant": { "type": "string" } }, "required": [ "tenant", "location", "created", "base_revision" ], "type": "object" }, "TermProposal": { "description": "A term the parser wants added to the KB because no existing id fits.", "properties": { "gloss": { "description": "One line pinning down the sense.", "type": "string" }, "id": { "description": "snake_case id, e.g. `apple_fruit` when `apple` is taken by another sense.", "type": "string" }, "individual": { "default": false, "description": "true when the id names one specific person, organisation, place, event\nor instance; false for kinds and contexts.", "type": "boolean" }, "parents": { "default": [], "description": "Existing term ids this is a kind of.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "gloss" ], "type": "object" }, "TextStats": { "description": "Per-text figures for ranking sources; every key is always present.", "properties": { "by_kind": { "additionalProperties": { "format": "uint", "minimum": 0, "type": "integer" }, "type": "object" }, "by_label": { "additionalProperties": { "format": "uint", "minimum": 0, "type": "integer" }, "type": "object" }, "claims": { "format": "uint", "minimum": 0, "type": "integer" }, "decided_facts": { "description": "Factual claims the KB could decide (a rule applied); a claim about\nthe text itself is never one.", "format": "uint", "minimum": 0, "type": "integer" }, "disputed_values": { "format": "uint", "minimum": 0, "type": "integer" }, "framed": { "additionalProperties": { "format": "uint", "minimum": 0, "type": "integer" }, "description": "Framed claims per framing kind.", "type": "object" }, "framed_unanimous": { "description": "Framed claims every review sample agreed on.", "format": "uint", "minimum": 0, "type": "integer" }, "mean_probability_decided_facts": { "description": "Mean probability over decided factual claims, 3 decimals; null when none.", "format": "double", "type": [ "number", "null" ] }, "uncorroborated": { "description": "Claims whose deciding rule rests on a single non-official source.", "format": "uint", "minimum": 0, "type": "integer" }, "verified": { "default": 0, "description": "Claims shown as verified or verified false (settled beyond reasonable doubt).", "format": "uint", "minimum": 0, "type": "integer" } }, "required": [ "claims", "by_kind", "by_label", "framed", "framed_unanimous", "uncorroborated", "disputed_values", "decided_facts" ], "type": "object" }, "TimeScope": { "description": "The period a claim or rule is about. Dates are ISO at any precision;\n`from` missing means \"since always\", `to` missing means \"still\".\n\"in 2026\" is 2026–2026, \"since 1970\" is 1970–, \"in the 1950s\" 1950–1959.", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] } }, "type": "object" }, "UnitAct": { "description": "The act a zone's polygon belongs to.", "properties": { "key": { "description": "The corpus key (`pa-365`), when the resolver could tell.", "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "valid_from": { "type": [ "string", "null" ] } }, "type": "object" }, "UnitKind": { "description": "What a resolved unit is.", "oneOf": [ { "enum": [ "regime" ], "type": "string" }, { "const": "zone", "description": "A planning unit (EUP).", "type": "string" }, { "const": "sub_zone", "description": "A sub-unit (PEUP) inside a planning unit.", "type": "string" }, { "const": "land_use", "description": "Land use only (no planning unit is known).", "type": "string" } ] }, "Usage": { "description": "A job's model usage, for the caller's credits.", "properties": { "backend": { "description": "The model backend: `claude_cli` (a subscription token in the service),\n`anthropic_api` or `openai_api`. Tokens and `usd_estimate` (at list\nprices) mean the same on each.", "type": "string" }, "by_template": { "additionalProperties": { "$ref": "#/components/schemas/UsageLine" }, "description": "By prompt template (`parse_domain`, `compare_norm`, `apply_provisions`, …): where a\ncheck's calls, tokens and dollars went.", "type": "object" }, "cached_calls": { "default": 0, "description": "Readings answered from the read cache ([`crate::reads`]): no model call, no cost.\nAlways present, 0 included, so runs compare.", "format": "uint32", "minimum": 0, "type": "integer" }, "input_tokens": { "format": "uint64", "minimum": 0, "type": "integer" }, "model_calls": { "format": "uint32", "minimum": 0, "type": "integer" }, "output_tokens": { "format": "uint64", "minimum": 0, "type": "integer" }, "payer": { "anyOf": [ { "$ref": "#/components/schemas/Payer" }, { "type": "null" } ] }, "usd_estimate": { "description": "The estimated cost in US dollars at list prices.", "format": "double", "type": "number" } }, "required": [ "model_calls", "input_tokens", "output_tokens", "usd_estimate" ], "type": "object" }, "UsageLine": { "description": "The calls of one line of a usage breakdown (one model, one template).", "properties": { "cached": { "description": "Readings answered from the read cache, besides `calls`.", "format": "uint32", "minimum": 0, "type": "integer" }, "calls": { "format": "uint32", "minimum": 0, "type": "integer" }, "input_tokens": { "description": "Every input token, cached or not.", "format": "uint64", "minimum": 0, "type": "integer" }, "output_tokens": { "format": "uint64", "minimum": 0, "type": "integer" }, "usd_estimate": { "format": "double", "type": "number" } }, "required": [ "calls", "input_tokens", "output_tokens", "usd_estimate" ], "type": "object" }, "ValueBasis": { "description": "Where a norm block's compared value comes from ([`NormResult::value_basis`]).", "oneOf": [ { "const": "stated", "description": "The value the applicant states in the documentation: not measured, not a record.", "type": "string" }, { "const": "measurement", "description": "A measurement the caller supplied (`facts.sources` with `kind: measurement`).", "type": "string" } ] }, "VersionInfo": { "description": "One version of a document.", "properties": { "covers": { "description": "The publications the version's text consolidates, oldest first: the\nbase act and its amendments (\"Uradni list RS, št. 96/11\", …). A\ncitation names these, never a consolidated text's label.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The corpus's id of the version (`npb-5`, `2`).", "type": "string" }, "label": { "description": "How readers name it (\"NPB 5\", \"SD OPN 1\").", "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VersionStatus" }, "valid_from": { "description": "The day it applies from (ISO).", "type": [ "string", "null" ] }, "valid_to": { "description": "The last day it applied, when the corpus says; otherwise the product\ncomputes it from the next version's `valid_from`.", "type": [ "string", "null" ] } }, "required": [ "id", "label", "status" ], "type": "object" }, "VersionStatus": { "description": "Whether a version of a document is law.", "oneOf": [ { "const": "current", "description": "In force now.", "type": "string" }, { "const": "superseded", "description": "Was in force; a later version replaced it.", "type": "string" }, { "const": "draft", "description": "A proposal (a draft plan before the council): never law.", "type": "string" }, { "const": "unofficial", "description": "An unofficial consolidation of the text in force (the base act with its\namendments merged by someone other than the gazette): the current norm,\ncited by the base act and its amendments' publications.", "type": "string" } ] }, "Way": { "description": "One way a norm can be met ([`Norm::satisfied_by`]).", "properties": { "condition": { "description": "When it applies, as the provision says.", "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/WayKind" }, "operator": { "anyOf": [ { "$ref": "#/components/schemas/Operator" }, { "type": "null" } ], "description": "For a numeric way: `max`, `min`, `range` or `eq`." }, "paragraph": { "description": "The paragraph it stands in: the n of \"(n)\".", "type": [ "string", "null" ] }, "range": { "anyOf": [ { "$ref": "#/components/schemas/WayRange" }, { "type": "null" } ], "description": "The claimed values this way is open for, when the provision limits it." }, "text": { "description": "The provision's words that state this way, copied exactly.", "type": "string" }, "unit": { "description": "`m`, `m2`, `%`, `ratio`, `°`.", "type": [ "string", "null" ] }, "value": { "format": "double", "type": [ "number", "null" ] }, "value_max": { "format": "double", "type": [ "number", "null" ] } }, "required": [ "kind", "text" ], "type": "object" }, "WayKind": { "description": "How a way of meeting a norm is stated ([`Way::kind`]).", "oneOf": [ { "const": "numeric", "description": "A number to meet (\"najmanj 4 m\"): give `operator`, `value`, `unit`.", "type": "string" }, { "const": "qualitative", "description": "A requirement in words (\"tako, da ni motena sosednja posest\").", "type": "string" }, { "const": "consent", "description": "Someone's consent (the neighbours', the road's manager, the municipality).", "type": "string" }, { "const": "procedure", "description": "A justification, study or approval in the project.", "type": "string" } ] }, "WayRange": { "description": "The claimed values a way is open for, when the provision limits it\n(\"Če so odmiki stavb manjši od 1,5 m\" → `max` 1.5 m).", "properties": { "operator": { "$ref": "#/components/schemas/Operator", "description": "`max`, `min` or `range`." }, "unit": { "type": [ "string", "null" ] }, "value": { "format": "double", "type": "number" }, "value_max": { "format": "double", "type": [ "number", "null" ] } }, "required": [ "operator", "value" ], "type": "object" }, "Works": { "description": "A kind of works (GZ-1, 3. člen).", "oneOf": [ { "const": "gradnja_novega_objekta", "description": "Gradnja novega objekta.", "type": "string" }, { "const": "dozidava", "description": "Dozidava.", "type": "string" }, { "const": "nadzidava", "description": "Nadzidava.", "type": "string" }, { "const": "rekonstrukcija", "description": "Rekonstrukcija.", "type": "string" }, { "const": "sprememba_namembnosti", "description": "Sprememba namembnosti.", "type": "string" }, { "const": "odstranitev", "description": "Odstranitev.", "type": "string" }, { "const": "vzdrzevanje", "description": "Vzdrževanje.", "type": "string" } ] }, "ZoneUnit": { "description": "One planning unit the place lies in.", "properties": { "act": { "anyOf": [ { "$ref": "#/components/schemas/UnitAct" }, { "type": "null" } ] }, "area_m2": { "default": 0.0, "format": "double", "type": "number" }, "code": { "description": "The planning unit (EUP) code as the plan writes it: `ŽA-1`.", "type": "string" }, "id": { "description": "The resolver's id of the unit polygon.", "type": "string" }, "kind": { "$ref": "#/components/schemas/UnitKind" }, "label": { "description": "The land use in words.", "type": [ "string", "null" ] }, "land_use": { "description": "The detailed land use (podrobnejša namenska raba): `SSe`, `CU`.", "type": [ "string", "null" ] }, "oppn_status": { "description": "Detailed-plan (OPPN) status as the source states it.", "type": [ "string", "null" ] }, "share": { "description": "Share of the place's area in this unit (0 to 1).", "format": "double", "type": "number" }, "snapshot": { "description": "The date of the layer the unit came from.", "type": [ "string", "null" ] }, "sub_code": { "description": "The sub-unit (PEUP) code: `ŽA-1/1`.", "type": [ "string", "null" ] } }, "required": [ "id", "kind", "code", "share" ], "type": "object" } }, "securitySchemes": { "bearer": { "description": "A key of the tenant, optionally of an organisation, with scopes (`x-scope` on each operation names the one it needs). `X-Api-Key: ` is accepted until v2.", "scheme": "bearer", "type": "http" }, "session": { "description": "The demo's sign-in (`POST /api/v1/sessions`): an account's session, with its tenant and its role's scopes (`admin` every scope; `user` read, evaluate, facts:write, amend). Accepted wherever a key is, a key first when both come. A write it signs needs `X-Requested-With: bayesian` or a same-origin `Origin`.", "in": "cookie", "name": "bayesian_session", "type": "apiKey" } } } }