API reference#

Everything on this page is imported from pyxel_config_core directly, for example from pyxel_config_core import validate_config.

Checking configs#

pyxel_config_core.validate_config(config: dict[str, Any] | str, deep: bool = False, trusted: bool = False) → ValidationResult[source]#

Validate against the bundled schema; deep also runs pyxel.load().

trusted lets the deep check run text Pyxel evaluates as Python (and import user model modules) without reading it first; leave it False for any config that did not come from you.

Parameters:

config (dict or str) – The config as a mapping, or the raw YAML text of a .yaml file.
deep (bool, default False) – Also hand the config to pyxel.load() (see deep_check), so what Pyxel enforces only in its code is reported too. Needs Pyxel installed.
trusted (bool, default False) – Let the deep check load the config without reading the values Pyxel evaluates as Python first.

Returns:

valid is False when any finding is an error. Text that cannot be read as a config is reported as a finding rather than raised.

Return type:

ValidationResult

Examples

>>> from pyxel_config_core import validate_config
>>> result = validate_config(open("my_config.yaml").read())
>>> for d in result.diagnostics:
...     print(d.severity, d.path, d.message)

pyxel_config_core.explain_config(config: dict[str, Any] | str, deep: bool = False, trusted: bool = False) → Explanation[source]#

validate_config, plus a one-sentence summary and a next step per finding.

Parameters:

config (dict or str) – The config as a mapping, or the raw YAML text of a .yaml file.
deep (bool, default False) – Also hand the config to pyxel.load(), as validate_config does.
trusted (bool, default False) – Let the deep check load the config without reading the values Pyxel evaluates as Python first.

Returns:

The same findings as validate_config, each with a next_step, under a summary a person can read first.

Return type:

Explanation

pyxel_config_core.deep_check(config: dict[str, Any] | str, trusted: bool = False) → tuple[list[Diagnostic], bool][source]#

Run the config through pyxel.load() itself.

The schema is a description of Pyxel; Pyxel is the thing. Bounds it only enforces in code (readout times out of order pass the schema and fail here) are caught by handing the YAML to its own loader. Returns (diagnostics, whether the loader actually ran).

Loading runs part of the config: Pyxel evaluates some text as Python, unpickles binary data, imports the module each model names and opens a few files (see expressions.py). Unless the caller says the config is trusted, every such value is read first and the loader is not run if any of them is more than plain data or a known harmless call.

Parameters:

config (dict or str) – The config as a mapping, or the raw YAML text of a .yaml file.
trusted (bool, default False) – Load the config without reading those values first. Only for a config you wrote yourself.

Returns:

What the loader reported, and whether it actually ran. It does not run when Pyxel is missing or cannot be imported, or when a value is refused; the findings then say why.

Return type:

tuple of (list of Diagnostic, bool)

pyxel_config_core.autofix(config: dict[str, Any] | str) → FixResult[source]#

Repair mistyped and misplaced model names in a config.

A mistyped func is renamed to its closest valid model, and a valid model in the wrong stage is moved to the stage it belongs to. Only func names change: required arguments are never invented, so any that are still missing appear in remaining_diagnostics. The config that is passed in is never modified.

Parameters:: config (dict or str) – The config as a mapping, or the raw YAML text of a .yaml file.
Returns:: The corrected config, each change made, what could not be repaired, and the full validation findings for the corrected config. Text that cannot be read as a config comes back unresolved, with an empty config.
Return type:: FixResult

Models and tutorials#

pyxel_config_core.list_models(stage: str | None = None) → ModelCatalog[source]#

List the models the bundled schema accepts.

Parameters:: stage (str, optional) – One pipeline stage, such as "charge_generation". Leave it out to list every stage. A stage the schema does not have lists nothing.
Returns:: Each model with its stage and the full func path to write in a config.
Return type:: ModelCatalog

pyxel_config_core.model_parameters(model: str, stage: str | None = None) → ModelParameters | None[source]#

Look up a model’s arguments, as the bundled Pyxel schema describes them.

Every model the schema accepts is covered. Each argument carries its type, whether Pyxel requires it, Pyxel’s own default when it has one, and the example value Pyxel’s example configs use for it, where there is one. The example is not a default: a step that leaves an argument out gets Pyxel’s default, which for an argument such as simple_conversion’s quantum_efficiency is the detector’s own value.

Parameters:

model (str) – The model’s short name, such as "load_image".
stage (str, optional) – The pipeline stage, for a name two stages share (simple_collection). Without it, the first stage in Pyxel’s run order is taken.

Returns:

The stage the model belongs to and each of its arguments, or None when the schema has no such model (in that stage).

Return type:

ModelParameters or None

pyxel_config_core.find_tutorial(group: str, model: str) → Tutorial | None[source]#

Fetch the tutorial for one model.

Parameters:

group (str) – The pipeline stage the model belongs to, such as "charge_generation". The tutorial file prefix, such as "ChargeGeneration", works too.
model (str) – The model’s short name, such as "dark_current".

Returns:

The whole tutorial as Markdown, or None when the catalog has no tutorial for that model.

Return type:

Tutorial or None

pyxel_config_core.search_tutorials(query: str, limit: int = 5, semantic: bool | None = None) → list[Tutorial][source]#

Whole tutorials matching a query.

semantic picks the engine: True ranks with the vector index, False matches on keywords, and None (the default) uses the index only when one has already been built. Whichever is asked for, a missing index or a missing extra degrades to keywords rather than failing; callers who need to know which engine answered use semantic_search_with_fallback.

Parameters:

query (str) – What to look for, in plain words.
limit (int, default 5) – The most tutorials to return.
semantic (bool or None, default None) – Which engine to use, as above.

Returns:

The best matches first; empty when nothing matches.

Return type:

list of Tutorial

pyxel_config_core.semantic_search(query: str, limit: int = 5) → list[SemanticMatch][source]#

Rank tutorial passages by meaning, with the local vector index.

Needs the rag extra and an index built by build_index or pyxel-config index, and raises an error when either is missing. To fall back to keyword matching instead, use semantic_search_with_fallback.

Parameters:

query (str) – What to look for, in plain words.
limit (int, default 5) – The most passages to return.

Returns:

The closest passages first.

Return type:

list of SemanticMatch

pyxel_config_core.semantic_search_with_fallback(query: str, limit: int = 5) → TutorialSearchResult[source]#

Search tutorial passages by meaning, and say which engine answered.

The vector index answers when it has been built. When it has not, or the rag extra is missing or fails, keyword matching answers instead and the result is marked as degraded, so a caller always gets matches and never an exception.

Parameters:

query (str) – What to look for, in plain words.
limit (int, default 5) – The most passages to return.

Returns:

The matches, the engine that found them, and the reason whenever keyword matching stood in.

Return type:

TutorialSearchResult

pyxel_config_core.build_index(force: bool = True) → int[source]#

Build the local vector index of tutorial passages.

Needs the rag extra, and downloads the embedding model on first use. The index is written to ~/.cache/pyxel-config-core/qdrant, or to the folder the PYXEL_CONFIG_CORE_INDEX environment variable names.

Parameters:: force (bool, default True) – Delete any existing index and build it afresh. When False, an existing index is updated in place.
Returns:: How many passages were indexed.
Return type:: int

Model names#

pyxel_config_core.find_unknown_funcs(config: object, known: KnownFuncs | None = None) → list[Finding][source]#

Find the pipeline steps whose func is not a model of their stage.

A model of the user’s own, outside the pyxel. namespace, is left alone: Pyxel imports it at run time.

Parameters:

config (object) – A parsed config. Anything without a pipeline mapping has no findings.
known (KnownFuncs, optional) – The models to check against. By default, the ones the bundled schema defines.

Returns:

One per step, each with its reason ("unknown" for a name no stage has, "wrong-stage" for a model placed in another stage), the owning_stage of a misplaced model, a suggestion for a likely typo, and the valid_funcs of the step’s stage.

Return type:

list of Finding

pyxel_config_core.suggest_func(bad_func: str, candidates: Iterable[str]) → str | None[source]#

Suggest the valid model a mistyped func most likely meant.

Names are compared by edit distance, both on the last part of the dotted path and on the whole path. A candidate is only suggested when it is within two edits, or two in five characters of that last part for a longer name, so a name that is nothing like any model gets no suggestion.

Parameters:

bad_func (str) – The func value as written in the config.
candidates (iterable of str) – The valid func paths to choose from.

Returns:

The closest candidate, or None when none is close enough.

Return type:

str or None

The bundled schema#

pyxel_config_core.schema_version() → str[source]#: The Pyxel release the bundled schema was generated from, e.g. “3.0.2”.

pyxel_config_core.schema_sha256() → str[source]#: Digest of the schema file as shipped, for comparing against the manifest.

Result types#

Every result is a Pydantic model, so it can be read as attributes, turned into a dict with model_dump(), or into JSON with model_dump_json().

class pyxel_config_core.ValidationResult(*, valid: bool, diagnostics: list[~pyxel_config_core.models.Diagnostic], pyxel_version: str = <factory>, deep_checked: bool = False, deep_pyxel_version: str | None = None)[source]#

The verdict on one config, from validate_config.

valid: bool#: True when no finding is an error.

diagnostics: list[Diagnostic]#: Every finding, whatever its severity.

pyxel_version: str#: The Pyxel release the bundled schema was generated from, so every verdict names the contract that judged it.

deep_checked: bool#: True only when pyxel.load() itself was run on the config as well.

deep_pyxel_version: str | None#: The installed Pyxel release whose loader ran, when it did; it can differ from pyxel_version, which names the bundled schema’s release.

class pyxel_config_core.Explanation(*, valid: bool, summary: str, diagnostics: list[~pyxel_config_core.models.Diagnostic], pyxel_version: str = <factory>, deep_checked: bool = False, deep_pyxel_version: str | None = None)[source]#

The verdict from explain_config: a summary, and a next step on each finding.

valid: bool#: True when no finding is an error.

summary: str#: One plain-English sentence a person can read before the list.

diagnostics: list[Diagnostic]#: Every finding, each with its next_step filled in.

pyxel_version: str#: The Pyxel release the bundled schema was generated from.

deep_checked: bool#: True only when pyxel.load() itself was run on the config as well.

deep_pyxel_version: str | None#: The installed Pyxel release whose loader ran, when it did.

class pyxel_config_core.Diagnostic(*, severity: Literal['error', 'warning', 'info'], path: str, message: str, hint: str | None = None, suggestion: str | None = None, valid_options: list[str] | None = None, next_step: str | None = None, category: Literal['schema', 'func', 'shape', 'advisory', 'pyxel-rule', 'pyxel-load', 'yaml'] = 'schema')[source]#

One finding about a config: what is wrong, where, and how much it matters.

severity: Severity#: "error" makes the config invalid; "warning" and "info" do not.

path: str#: Where the finding is, as a JSON pointer into the config, such as /pipeline/charge_generation/0/func. Empty for the config as a whole.

message: str#: What is wrong, in one sentence.

hint: str | None#: Further advice on putting it right, when there is any.

suggestion: str | None#: The value most likely meant, such as the closest valid model for a typo.

valid_options: list[str] | None#: Values that would be accepted here, such as the valid models of a stage.

next_step: str | None#: One concrete thing to do about it, phrased as an instruction. Filled in by explain_config; validate_config leaves it empty.

category: Category#: The check that raised it, which is also its SARIF rule id and its Code Quality check name.

class pyxel_config_core.FixResult(*, changed: bool, changes: list[ConfigFix], unresolved: list[Diagnostic], remaining_diagnostics: list[Diagnostic], config: dict)[source]#

What autofix did to a config.

changed: bool#: True when at least one change was made.

changes: list[ConfigFix]#: Every change that was made.

unresolved: list[Diagnostic]#: What autofix found but could not repair.

remaining_diagnostics: list[Diagnostic]#: The full validation findings for the corrected config.

config: dict#: The corrected config. The config that was passed in is never modified.

class pyxel_config_core.ConfigFix(*, path: str, action: Literal['rename_func', 'move_stage'], before: str, after: str, detail: str)[source]#

One change autofix made to a config.

path: str#: The step that was changed, as a JSON pointer to its func before the change.

action: Literal['rename_func', 'move_stage']#: "rename_func" when a mistyped model was renamed, "move_stage" when a model was moved to the stage it belongs to.

before: str#: The func name before a rename, or the stage before a move.

after: str#: The func name after a rename, or the stage after a move.

detail: str#: The change, in one sentence.

class pyxel_config_core.ModelCatalog(*, stage: str | None = None, count: int, models: list[ModelInfo])[source]#

The models the bundled schema accepts, from list_models.

stage: str | None#: The stage that was asked for, or None for every stage.

count: int#: How many models are listed.

models: list[ModelInfo]#: The models, sorted by stage and then by func.

class pyxel_config_core.ModelInfo(*, stage: str, func: str)[source]#

One model the bundled schema accepts.

stage: str#: The pipeline stage it belongs to.

func: str#: The full func path to write in a config.

class pyxel_config_core.ModelParameters(*, stage: str, model: str, parameters: list[ParameterInfo])[source]#

A model’s arguments, from model_parameters.

stage: str#: The pipeline stage the model belongs to.

model: str#: The model’s short name, such as load_image.

parameters: list[ParameterInfo]#: Each argument, with its type and default.

class pyxel_config_core.ParameterInfo(*, name: str, type: str, required: bool = False, has_default: bool = False, default: object = None, example: object = None)[source]#

One argument of a model, as the bundled Pyxel schema describes it.

name: str#: The argument’s name.

type: str#: Its type as Python spells it, such as float or list[int] | null.

required: bool#: True when Pyxel needs the argument written in the step.

has_default: bool#: True when the schema records a default for it (which can be null).

default: object#: Pyxel’s own default, which a step that leaves the argument out gets. A null default often means “from the detector” (quantum_efficiency).

example: object#: The value Pyxel’s example configs use, when they use one. An example, not a default: writing it overrides Pyxel’s own default.

class pyxel_config_core.Tutorial(*, group: str, model: str, title: str, body_markdown: str)[source]#

One tutorial from the bundled catalog.

group: str#: The pipeline stage it was found under, such as charge_generation.

model: str#: The model it covers.

title: str#: Its first heading, or the model’s name when it has none.

body_markdown: str#: The whole tutorial, as Markdown.

class pyxel_config_core.TutorialSearchResult(*, mode: Literal['semantic', 'keyword'], degraded: bool, message: str | None = None, matches: list[SemanticMatch])[source]#

The answer to a tutorial search, naming the engine that gave it.

mode: Literal['semantic', 'keyword']#: "semantic" when the vector index answered, "keyword" when keyword matching did.

degraded: bool#: True when keyword matching stood in for a vector index that could not be used.

message: str | None#: Why the result is degraded, when it is.

matches: list[SemanticMatch]#: The matching passages, best first.

class pyxel_config_core.SemanticMatch(*, group: str, model: str, title: str, section: str, score: float, snippet: str)[source]#

One tutorial passage returned by a search.

group: str#: The pipeline stage of the tutorial the passage comes from.

model: str#: The model that tutorial covers.

title: str#: The tutorial’s title.

section: str#: The heading of the passage within the tutorial.

score: float#: How close the passage is to the query; higher is closer. Keyword results carry 0.

snippet: str#: A short extract of the passage.