Stability¶
From 1.0, openodke follows semantic versioning. What it covers, how long a deprecated name lives and what "provisional" allows are written once, in DECISIONS #48. This page says which parts of the package are which.
Public¶
A name is public when a public module lists it in __all__. A module is public
unless a part of its path starts with _. A public function, class or method is
public by the names and kinds of its parameters too, and a model by its fields.
The odke command is public by its commands, flags and exit statuses;
openodke.cli is not a Python API. The run config is public by its keys and the
short names use: takes. A test pins all of it, so none of it changes by
accident.
Provisional¶
Public and documented, but may change in a minor release, with a CHANGELOG line. Each module, or each name in a frozen module, says so at the top of its docstring.
| Module | Why |
|---|---|
openodke.corroborate.judge, and the resolver's normalize_batch and embed |
The pair judge and batch normalisation are off by default until their calibration card (DECISIONS #34, #43) |
openodke.eval.equivalence |
The fact-equivalence judge's lenient score is unvalidated until its calibration card (DECISIONS #39) |
openodke.eval.datasets |
The benchmark adapters follow the datasets' own releases |
openodke.interop.langchain, .langextract, .graphrag |
They read other libraries' objects, which change with those libraries |
openodke.reextract |
The re-extract hook is off by default, with one extractor behind it |
openodke.calibration |
Calibration cards: the format and the bars settle with the first cards (DECISIONS #54) |
openodke.infer |
Ontology inference is parked (DECISIONS #24): most of it is undocumented, and it moves when it is picked up again |
Initiator, Retriever and Router, in openodke.stages |
Stage Protocols nothing real implements yet (DECISIONS #9): the first two have no implementation, Pipeline keeps a retriever without calling it, and routers are pass-throughs |
The OpenTelemetry spans' names and attributes are provisional too, and so is which version of a registered prompt a stage sends. The keys themselves are never edited or removed.
Formats¶
Each format a reader outside Python depends on names its version, and its JSON Schema ships in the package. A minor version adds optional fields; a reader refuses another major version by name. A reader reads a later minor for the fields it knows, at every level, and leaves the rest; in a document of its own version or an older one, a field it does not know is refused, since there it is a typo (DECISIONS #52).
| Format | Version field | Now | Schema |
|---|---|---|---|
| Triples input | schema_version, on each row, optional |
1.0 | openodke/interop/triples.schema.json |
Run report, ValidationReport |
schema_version |
1.1 | openodke/validation_report.schema.json |
| Eval report | schema_version |
1.4 | openodke/eval/eval_report.schema.json |
| Run manifest | manifest_version |
1 | openodke/manifest.schema.json |
odke run's stats |
schema_version |
1.0 | |
odke ground's summary, GroundSummary |
schema_version |
1.0 |
Deprecated¶
Each still works, warns with a DeprecationWarning that names what to use, and
is removed in 2.0.0. Python shows such a warning only in a script's own code
and under a test runner; python -W default::DeprecationWarning shows every
one. odke run prints a deprecated config key's warning itself.
| Deprecated | Use |
|---|---|
openodke.VerdictValidator, openodke.validators.VerdictValidator |
openodke.VerdictGate |
openodke.stages.Validator, openodke.pipeline.Validator |
openodke.Gate |
openodke.stages.PassThroughValidator, openodke.pipeline.PassThroughValidator |
openodke.stages.PassThroughGate |
Pipeline(validator=...), Pipeline.validator |
Pipeline(gate=...), Pipeline.gate |
Built.pipeline(validator=...), StagesConfig.validator |
gate |
validator: under stages in a run config |
gate: |
openodke.sinks.neo4j.cardinality_scope(predicate) |
predicate.scope_keys |
openodke.ValidationVerdict, openodke.types.ValidationVerdict |
openodke.GateVerdict |
openodke.eval.ValidationLabel, openodke.eval.formats.ValidationLabel |
openodke.eval.GateLabel |
openodke.eval.evaluate_validation, openodke.eval.validation.evaluate_validation |
openodke.eval.evaluate_gate |
odke eval validate |
odke eval gate; its labels, report and items keep the stage's name, validate |
openodke.ground.llm.SYSTEM_PROMPT |
openodke.prompts.get("ground.span").text |
None of these is in an __all__, so from openodke import * never warns.
openodke.Validator named the gate in 0.2 and is the Validator, the whole
layer, from 1.0 (DECISIONS #26).