Skip to content

Pipeline and server

What a run does, how wide it fans out, and where the server listens.

Run

HOST

Default: 127.0.0.1 · Type: str

Interface the server binds to. Defaults to loopback: the server has no authentication and exposes a destructive /flush, so binding every interface must be a deliberate choice. Set to 0.0.0.0 for containers.

PORT

Default: 8999 · Type: int

Port the server listens on.

MAX_VISITS_PER_NODE

Default: 1 · Type: int · Also read from MAX_VISITS

Render attempts per content unit, counting the first, when a render fails outright (unparseable response, provider error); 1 makes no retry. A render that succeeds is not repeated; improving it is the critic's job (FACTS_CRITIC_PASSES, ONTOLOGY_CRITIC_PASSES).

RENDER_MODE

Default: ontology_and_facts · Type: one of ontology, facts, ontology_and_facts

Rendering mode: ontology, facts, or ontology_and_facts.

LLM_GRAPH_FORMAT

Default: turtle · Type: one of turtle, jsonld

Format the LLM writes RDF graphs in: 'turtle' (Turtle strings) or 'jsonld' (compact JSON-LD objects). Turtle spends fewer tokens per triple and cannot write an IRI object as a string by accident; 'jsonld' suits providers whose structured output handles long strings worse than nested objects.

LLM_OUTPUT_LAYOUT

Default: compact · Type: one of free, compact

Whitespace the LLM is asked to use in its structured responses: 'compact' asks for minified JSON and one-line-per-subject Turtle without indentation; 'free' gives no instruction (models typically indent JSON). Indentation counts as output tokens and carries nothing the parser reads. Applies to every call that emits a graph payload.

ONTOLOGY_CHAPTER_FORMAT

Default: auto · Type: one of auto, inherit, turtle, term_sheet

Syntax of the ontology chapter in the facts render and critic prompts. 'inherit' follows LLM_GRAPH_FORMAT; 'turtle' always uses Turtle, which is shorter than JSON-LD; 'term_sheet' lists one line per term (name, labels, type, hierarchy, domain and range, usage) and is the shortest. 'auto' picks 'term_sheet'. The ontology loop is not affected: it always reads its chapter in LLM_GRAPH_FORMAT, because it patches the statements in it. Only the prompt context changes; the model's output keeps LLM_GRAPH_FORMAT. Part of the LLM cache key for facts calls.

ONTOLOGY_TEXT_MAX_CHARS_NAMING

Default: unset · Type: int

Character cap on each rdfs:label, skos:prefLabel and skos:altLabel in the ontology chapter; unset disables it. Long names are clipped at a word boundary with a visible marker, so the model can tell a clipped name from a complete one. Part of the LLM cache key.

ONTOLOGY_TEXT_MAX_CHARS_CONTRACT

Default: unset · Type: int

Character cap on skos:scopeNote / skos:definition, the statements saying when a term applies. Worth clipping rather than dropping: a scope note's first sentence usually carries the contract and the rest elaborates. Joins the LLM cache key. None disables the cap.

ONTOLOGY_TEXT_MAX_CHARS_PROSE

Default: unset · Type: int

Character cap on rdfs:comment and the remaining SKOS notes -- description aimed at someone browsing the ontology rather than at an extractor. Joins the LLM cache key. None disables the cap.

ONTOLOGY_TEXT_TOTAL_BUDGET

Default: unset · Type: int

Ceiling on the total length of all text literals in one ontology chapter, for catalogs with very many short terms. Over budget, literals are shortened, never removed: prose first, then usage contracts, then names, each to the largest cap that meets the budget, down to a floor; a chapter that still does not fit is used as is. Reported in budget.counters as chapter/text_chars_before, chapter/text_chars_after, chapter/literals_clipped and chapter/text_over_budget. Part of the LLM cache key.

ONTOLOGY_CONTEXT_MODE

Default: selected_single_ontology · Type: one of selected_single_ontology, selected_vector_search_ontology, fixed_single_ontology

Per-unit ontology context: selected_single_ontology (LLM-picked catalog; costs one extra LLM call per content unit), selected_vector_search_ontology (vector-store stitched ensemble; Qdrant or LanceDB), or fixed_single_ontology (catalog ontology_id; requires ontology_context_fixed_ontology_id).

ONTOLOGY_CONTEXT_FIXED_ONTOLOGY_ID

Default: empty · Type: str

Catalog ontology (IRI, ontology_id or author prefix) used in fixed_single_ontology mode, by ontocast process and by HTTP requests that name none. Setting it does not change the mode.

ONTOLOGY_MAX_TRIPLES

Default: unset · Type: int

Runaway-growth backstop on the per-unit ontology working graph: an update whose result would exceed this is skipped with a warning, all-or-nothing. Not a prompt bound -- use ontology_context_max_triples for context size. None (default) disables it.

ONTOLOGY_CONTEXT_REQUIRED

Default: false · Type: bool

Fail the run when a facts unit's ontology context is empty, instead of extracting without a catalog. With no context the renderer falls back on generic vocabulary and SHACL has nothing to check, so the run would report a meaningless pass. Turn it on when extracting against a curated catalog. Off by default because the default render mode builds ontologies as it goes. Never applies to ontology units, for which an empty context means 'create a new ontology'.

ONTOLOGY_CONTEXT_SCOPE

Default: unit · Type: one of unit, document

Resolve the ontology chapter per content unit ('unit') or once per document ('document'). Per-unit chapters are smaller but all different, so no call shares a prompt prefix with another. 'document' shows every unit the union of the per-unit contexts: larger, but identical across the document, so a provider's prefix cache serves every call after the first. Each unit still sees every term its own retrieval chose, plus its siblings'. Takes effect only in facts-only runs: after an ontology stage, facts units already share one merged document context. Pair it with FANOUT_WARMUP_UNITS.

FANOUT_WARMUP_UNITS

Default: 0 · Type: int

Content units to complete before the rest are run concurrently, in the ontology and the facts fan-outs; 0 runs all at once. A provider's prefix cache is filled by a completed request, so calls sent together all miss it. Useful when the units of a document share a prompt prefix, as they do when their ontology chapters agree; costs the time of the warm-up units.

ONTOLOGY_CONTEXT_MAX_TRIPLES

Default: 4000 · Type: int

Triple budget for the ontology context serialized into a prompt, in every ontology_context_mode. Over budget, the least load-bearing triples are dropped first (header/list noise, then redundant structure, then comments and definitions); labels, types, hierarchy and domain/range are never dropped, so this is best-effort and a graph that cannot fit is passed through with a warning. In selected_vector_search_ontology with unit scope, VECTOR_STORE_INDUCED_SUBGRAPH_MAX_TOTAL_TRIPLES caps the context first. None disables condensing.

PARALLEL_WORKERS

Default: 16 · Type: int

Maximum content units processed at once within one document. A unit makes one LLM call at a time, so this is also the concurrency one document puts on the provider. LLM_MAX_INFLIGHT caps calls across all documents and is the one to lower when a provider rate-limits. If a stage's loop_lag_total in budget.node_durations is a large share of its wall-clock time, more workers will slow it down.

MAX_INPUT_TOKENS_PER_DOCUMENT

Default: unset · Type: int

Stop processing a document once its provider calls have used this many input tokens. Checked before each call, so calls already in flight finish. Responses replayed from the LLM cache do not count. Applies to ontocast process, the server routes and make_ontocast_node, unless the caller binds its own RunMeter. None means unlimited.

MAX_OUTPUT_TOKENS_PER_DOCUMENT

Default: unset · Type: int

Output-token counterpart of MAX_INPUT_TOKENS_PER_DOCUMENT; reasoning tokens count as output. None means unlimited.

MAX_CONCURRENT_PROCESSES

Default: unset · Type: int

When set, limit concurrent /process and /process_unit document runs. Runs beyond the limit queue until a slot frees up; they are not rejected.

MAX_FILES_PER_REQUEST

Default: 20 · Type: int

Most files one /process or /process_unit request may upload. The documents run one after another, so a request holds its connection for all of them.

MAX_TENANCY_SCOPES

Default: 16 · Type: int

How many tenant/project ToolBoxes to keep resident. Each holds a triple store connection and an ontology catalog; the expensive tools (LLM client, converter, embedding model) are shared across all of them. Least-recently-used scopes are evicted and closed. Bounded because scopes come from request parameters.

Process

LOGGING_LEVEL

Default: unset · Type: str

Log level for OntoCast: debug, info, warning or error. Other libraries log one level higher. Unset leaves logging as Python configures it.

CLEAN

Default: false · Type: bool

When true, ontocast process batch mode flushes the triple store (configured datasets) before loading ontologies.

Domain

CURRENT_DOMAIN

Default: https://growgraph.dev · Type: str · Also read from CURRENT_DOMAIN

IRI stem document and ontology IRIs are minted under: an absolute http(s) IRI with no fragment, query or trailing slash. A catalog ontology under it is owned and extended in place; any other is external and gets an extension ontology. Used by AgentState when no explicit value is supplied.