Skip to content

ontocast.api.schemas

Pydantic models for the OntoCast HTTP API.

Attributes

Classes

ConfigResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class ConfigResponse(BaseModel):
    version: str = __version__
    settings: dict[str, Any] = Field(
        description=(
            "Every setting the server was started with, keyed by environment "
            "variable, credentials redacted. Per-request parameters of "
            "/process and /process_unit override some of these for that "
            "request only."
        ),
    )
    chunking_mode: str = Field(
        description=(
            "Mode the chunker runs in: CHUNK_CHUNKING_MODE, or 'naive' when "
            "semantic chunking is unavailable in this environment."
        ),
    )

Attributes

chunking_mode = Field(description="Mode the chunker runs in: CHUNK_CHUNKING_MODE, or 'naive' when semantic chunking is unavailable in this environment.") class-attribute instance-attribute
settings = Field(description='Every setting the server was started with, keyed by environment variable, credentials redacted. Per-request parameters of /process and /process_unit override some of these for that request only.') class-attribute instance-attribute
version = __version__ class-attribute instance-attribute

FlushOkResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class FlushOkResponse(BaseModel):
    status: str = "success"
    message: str

Attributes

message instance-attribute
status = 'success' class-attribute instance-attribute

HealthErrorResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class HealthErrorResponse(BaseModel):
    status: str = "unhealthy"
    error: str

Attributes

error instance-attribute
status = 'unhealthy' class-attribute instance-attribute

HealthOkResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class HealthOkResponse(BaseModel):
    status: str = "healthy"
    version: str = __version__
    llm_provider: str | None = None

Attributes

llm_provider = None class-attribute instance-attribute
status = 'healthy' class-attribute instance-attribute
version = __version__ class-attribute instance-attribute

InfoResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class InfoResponse(BaseModel):
    name: str = "ontocast"
    version: str = __version__
    description: str = (
        "Agentic ontology assisted framework for semantic triple extraction"
    )
    capabilities: list[str] = Field(
        default_factory=lambda: ["text-to-triples", "ontology-extraction"]
    )
    input_types: list[str] = Field(
        default_factory=lambda: ["txt", "json", "pdf", "pptx"]
    )
    output_types: list[str] = Field(default_factory=lambda: ["turtle", "json"])
    llm_cache: dict | None = Field(
        default=None,
        description="In-memory and on-disk LLM cache statistics when available.",
    )
    max_concurrent_processes: int | None = Field(
        default=None,
        description="Configured cap on concurrent /process handlers, if any.",
    )

Attributes

capabilities = Field(default_factory=lambda: ['text-to-triples', 'ontology-extraction']) class-attribute instance-attribute
description = 'Agentic ontology assisted framework for semantic triple extraction' class-attribute instance-attribute
input_types = Field(default_factory=lambda: ['txt', 'json', 'pdf', 'pptx']) class-attribute instance-attribute
llm_cache = Field(default=None, description='In-memory and on-disk LLM cache statistics when available.') class-attribute instance-attribute
max_concurrent_processes = Field(default=None, description='Configured cap on concurrent /process handlers, if any.') class-attribute instance-attribute
name = 'ontocast' class-attribute instance-attribute
output_types = Field(default_factory=lambda: ['turtle', 'json']) class-attribute instance-attribute
version = __version__ class-attribute instance-attribute

OntologyDeleteResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class OntologyDeleteResponse(BaseModel):
    status: str = "success"
    iri: str

Attributes

iri instance-attribute
status = 'success' class-attribute instance-attribute

OntologyDiffResponse

Bases: BaseModel

Content triples added and removed between two versions.

Source code in ontocast/api/schemas.py
class OntologyDiffResponse(BaseModel):
    """Content triples added and removed between two versions."""

    status: str = "success"
    from_iri: str
    to_iri: str
    added: list[str]
    removed: list[str]
    added_count: int
    removed_count: int

Attributes

added instance-attribute
added_count instance-attribute
from_iri instance-attribute
removed instance-attribute
removed_count instance-attribute
status = 'success' class-attribute instance-attribute
to_iri instance-attribute

OntologyListResponse

Bases: BaseModel

Every ontology in the partition's catalog.

Source code in ontocast/api/schemas.py
class OntologyListResponse(BaseModel):
    """Every ontology in the partition's catalog."""

    status: str = "success"
    ontologies: list[OntologySummary]

Attributes

ontologies instance-attribute
status = 'success' class-attribute instance-attribute

OntologyMutationResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class OntologyMutationResponse(BaseModel):
    status: str = "success"
    iri: str
    ontology_id: str
    version: str
    version_iri: str

Attributes

iri instance-attribute
ontology_id instance-attribute
status = 'success' class-attribute instance-attribute
version instance-attribute
version_iri instance-attribute

OntologySummary

Bases: BaseModel

One catalog ontology with its head(s).

Source code in ontocast/api/schemas.py
class OntologySummary(BaseModel):
    """One catalog ontology with its head(s)."""

    iri: str
    ontology_id: str
    title: str
    description: str | None = None
    versions: int
    heads: list[OntologyVersionSummary]
    diverged: bool = False

Attributes

description = None class-attribute instance-attribute
diverged = False class-attribute instance-attribute
heads instance-attribute
iri instance-attribute
ontology_id instance-attribute
title instance-attribute
versions instance-attribute

OntologyVersionDeleteResponse

Bases: BaseModel

One version tombstoned; the ontology's new heads.

Source code in ontocast/api/schemas.py
class OntologyVersionDeleteResponse(BaseModel):
    """One version tombstoned; the ontology's new heads."""

    status: str = "success"
    version_iri: str
    heads: list[OntologyVersionSummary]

Attributes

heads instance-attribute
status = 'success' class-attribute instance-attribute
version_iri instance-attribute

OntologyVersionSummary

Bases: BaseModel

The header of one stored version.

Source code in ontocast/api/schemas.py
class OntologyVersionSummary(BaseModel):
    """The header of one stored version."""

    version_iri: str
    version: str
    prior_version_iris: list[str]
    created_at: datetime
    modified_at: datetime
    removed: bool = False

Attributes

created_at instance-attribute
modified_at instance-attribute
prior_version_iris instance-attribute
removed = False class-attribute instance-attribute
version instance-attribute
version_iri instance-attribute

OntologyVersionsResponse

Bases: BaseModel

The version DAG of one ontology, newest first.

Source code in ontocast/api/schemas.py
class OntologyVersionsResponse(BaseModel):
    """The version DAG of one ontology, newest first."""

    status: str = "success"
    iri: str
    ontology_id: str
    versions: list[OntologyVersionSummary]

Attributes

iri instance-attribute
ontology_id instance-attribute
status = 'success' class-attribute instance-attribute
versions instance-attribute

ProcessBatchResponse

Bases: BaseModel

/process and /process_unit: one result per document, in upload order.

Source code in ontocast/api/schemas.py
class ProcessBatchResponse(BaseModel):
    """``/process`` and ``/process_unit``: one result per document, in upload order."""

    results: list[ProcessItemResult]

Attributes

results instance-attribute

ProcessErrorResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class ProcessErrorResponse(BaseModel):
    status: Literal["error"] = "error"
    error: str
    error_type: str | None = None
    error_code: str | None = None
    error_details: dict | None = None

Attributes

error instance-attribute
error_code = None class-attribute instance-attribute
error_details = None class-attribute instance-attribute
error_type = None class-attribute instance-attribute
status = 'error' class-attribute instance-attribute

ProcessItemResult

Bases: BaseModel

One uploaded document's outcome.

Source code in ontocast/api/schemas.py
class ProcessItemResult(BaseModel):
    """One uploaded document's outcome."""

    filename: str
    status_code: int = Field(
        description="200 when the document was extracted, 422 when it could not "
        "be, 500 on an unexpected error."
    )
    outcome: ProcessOkResponse | ProcessErrorResponse = Field(discriminator="status")

Attributes

filename instance-attribute
outcome = Field(discriminator='status') class-attribute instance-attribute
status_code = Field(description='200 when the document was extracted, 422 when it could not be, 500 on an unexpected error.') class-attribute instance-attribute

ProcessOkResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class ProcessOkResponse(BaseModel):
    status: Literal["success"] = "success"
    data: ProcessResultData
    metadata: ProcessResultMetadata

Attributes

data instance-attribute
metadata instance-attribute
status = 'success' class-attribute instance-attribute

ProcessResultData

Bases: BaseModel

Source code in ontocast/api/schemas.py
class ProcessResultData(BaseModel):
    facts: str
    ontology: str | None = Field(
        default=None,
        deprecated=True,
        description=(
            "Deprecated singular ontology payload; always null. Use ontology_artifacts."
        ),
    )
    ontology_artifacts: list[dict] = Field(default_factory=list)

Attributes

facts instance-attribute
ontology = Field(default=None, deprecated=True, description='Deprecated singular ontology payload; always null. Use ontology_artifacts.') class-attribute instance-attribute
ontology_artifacts = Field(default_factory=list) class-attribute instance-attribute

ProcessResultMetadata

Bases: BaseModel

Source code in ontocast/api/schemas.py
class ProcessResultMetadata(BaseModel):
    status: str | None = None
    chunks_processed: int
    chunks_remaining: int
    budget: dict
    retrieval_metrics: dict = Field(default_factory=dict)
    unit_context_sources: dict[str, dict[int, list[str]]] = Field(
        default_factory=dict,
        description=(
            "Ontology IRIs each unit's prompt context was drawn from, by lane "
            "('ontology', 'facts') and unit index."
        ),
    )
    facts_repairs: dict[int, list[dict]] = Field(
        default_factory=dict,
        description=(
            "Deterministic machine repairs applied per content unit, keyed by "
            "unit index. Lets a consumer tell machine-altered triples from what "
            "the model asserted."
        ),
    )
    failed_units: list[dict] = Field(
        default_factory=list,
        description=(
            "Content units that produced no output, with the stage and reason. "
            "Empty on a fully successful run."
        ),
    )
    improvement_suggestions: list[str] = Field(
        default_factory=list,
        description=(
            "Advisory notes from the structural check and consistency critic "
            "(orphan terms, potential cross-ontology conflicts). Advisory only: "
            "nothing in the pipeline acts on them."
        ),
    )
    facts_conformance: dict = Field(
        default_factory=dict,
        description=(
            "Validation summary for the returned facts graph: whether SHACL "
            "ran and the graph conforms, counts by finding kind and by SHACL "
            "constraint component, and the LLM-free repairs applied. Set by "
            "/process and /process_unit alike; empty when the gate did not run."
        ),
    )
    facts_validation_findings: list[dict] = Field(
        default_factory=list,
        description=(
            "Residual findings behind the summary, after every repair stage. "
            "A consumer that needs to know *which* nodes are non-conformant "
            "reads these."
        ),
    )
    facts_gate_repairs: list[dict] = Field(
        default_factory=list,
        description=(
            "LLM-free repairs applied to the merged graph by the gate "
            "(shape-driven retyping, code resolution, placeholder pruning). "
            "Per-unit repairs are in facts_repairs."
        ),
    )
    ontology_versions: list[dict] = Field(
        default_factory=list,
        description=(
            "Ontology versions this run wrote (role 'created' or 'updated', "
            "with iri, version_iri, ontology_id, version, prior_version_iris) "
            "and read without changing (role 'read', with iri and version_iri)."
        ),
    )

Attributes

budget instance-attribute
chunks_processed instance-attribute
chunks_remaining instance-attribute
facts_conformance = Field(default_factory=dict, description='Validation summary for the returned facts graph: whether SHACL ran and the graph conforms, counts by finding kind and by SHACL constraint component, and the LLM-free repairs applied. Set by /process and /process_unit alike; empty when the gate did not run.') class-attribute instance-attribute
facts_gate_repairs = Field(default_factory=list, description='LLM-free repairs applied to the merged graph by the gate (shape-driven retyping, code resolution, placeholder pruning). Per-unit repairs are in facts_repairs.') class-attribute instance-attribute
facts_repairs = Field(default_factory=dict, description='Deterministic machine repairs applied per content unit, keyed by unit index. Lets a consumer tell machine-altered triples from what the model asserted.') class-attribute instance-attribute
facts_validation_findings = Field(default_factory=list, description='Residual findings behind the summary, after every repair stage. A consumer that needs to know *which* nodes are non-conformant reads these.') class-attribute instance-attribute
failed_units = Field(default_factory=list, description='Content units that produced no output, with the stage and reason. Empty on a fully successful run.') class-attribute instance-attribute
improvement_suggestions = Field(default_factory=list, description='Advisory notes from the structural check and consistency critic (orphan terms, potential cross-ontology conflicts). Advisory only: nothing in the pipeline acts on them.') class-attribute instance-attribute
ontology_versions = Field(default_factory=list, description="Ontology versions this run wrote (role 'created' or 'updated', with iri, version_iri, ontology_id, version, prior_version_iris) and read without changing (role 'read', with iri and version_iri).") class-attribute instance-attribute
retrieval_metrics = Field(default_factory=dict) class-attribute instance-attribute
status = None class-attribute instance-attribute
unit_context_sources = Field(default_factory=dict, description="Ontology IRIs each unit's prompt context was drawn from, by lane ('ontology', 'facts') and unit index.") class-attribute instance-attribute

ShapesDeleteResponse

Bases: BaseModel

Source code in ontocast/api/schemas.py
class ShapesDeleteResponse(BaseModel):
    status: str = "success"
    graph_uri: str

Attributes

graph_uri instance-attribute
status = 'success' class-attribute instance-attribute

ShapesListResponse

Bases: BaseModel

Named graphs held in the shapes partition, and their merged size.

Source code in ontocast/api/schemas.py
class ShapesListResponse(BaseModel):
    """Named graphs held in the shapes partition, and their merged size."""

    status: str = "success"
    graph_uris: list[str]
    triples: int

Attributes

graph_uris instance-attribute
status = 'success' class-attribute instance-attribute
triples instance-attribute

ShapesMutationResponse

Bases: BaseModel

One SHACL shapes document stored in the tenant's shapes partition.

Source code in ontocast/api/schemas.py
class ShapesMutationResponse(BaseModel):
    """One SHACL shapes document stored in the tenant's shapes partition."""

    status: str = "success"
    graph_uri: str
    triples: int

Attributes

graph_uri instance-attribute
status = 'success' class-attribute instance-attribute
triples instance-attribute

StatusErrorBody

Bases: BaseModel

Source code in ontocast/api/schemas.py
class StatusErrorBody(BaseModel):
    status: str = "error"
    error: str
    error_type: str | None = None
    error_code: str | None = None

Attributes

error instance-attribute
error_code = None class-attribute instance-attribute
error_type = None class-attribute instance-attribute
status = 'error' class-attribute instance-attribute