hermes.stages

Stages

apply_stages walks a fixed tuple. Each function takes the draft and returns a query. Replacing a function is how a later technique enters the pipeline.

Contract

def stage(sparql, *, ontology, context):
    return sparql

STAGES = (guardrails, query_guided, context_guided, chase_backchase)

sparql is the draft string after extraction and modifier lifting. ontology is the vocabulary dict from load_vocabulary, not the file path. context is the Context passed to generate.

generate calls apply_stages on the first draft, and again on the repair draft if the first query does not parse. A replacement should return a string. It should not assume it is the last step: validation still runs after the tuple.

Source: stages.py.

Guardrails later

Reject or rewrite a query that leaves the ontology vocabulary. The intended check is the prefixes, classes, and properties already loaded for the prompt. The function does not inspect them yet.

Query guided later

Steer a draft using a target query shape or a previous SPARQL query. The prompt already shows one fixed shape. This stage is where a caller-supplied shape, or an earlier query, would revise the draft after generation.

Context guided later

Retrieve and place example questions, beyond stuffing them into the prompt. Examples today are only the JSONL rows the caller passed, copied verbatim into the prompt. This stage is where retrieval over a larger pool would choose and place them.

Chase and backchase later

Reformulate the query with ontology constraints, then minimize it. The function documents that intent and does not implement the algorithm. Constraints would come from the same Turtle file the vocabulary was loaded from. Minimization would drop triples the constraints make redundant.