nirs4all.api.advanced_capabilities module

Fail-closed capability decisions for the advanced public API verbs.

Explicit native profiles remain strict. General synthesis selects the built-in scientific library host before execution: it does not use PipelineRunner or a legacy ML coordinator. Unknown plugins and execution-error retries are refused. Explanations use the captured complete predictor without training it again.

class nirs4all.api.advanced_capabilities.AdvancedApiCapabilityDecision(verb: Literal['explain', 'generate'], requested_engine: str | None, lane: Literal['native', 'plugin', 'legacy', 'refused'], executable: bool, contract: str | None, plugin: str | None, unsupported_capability: str | None, reason: str | None, mitigation: str | None)[source]

Bases: object

Side-effect-free API-005 routing decision.

contract: str | None

executable: bool

lane: Literal['native', 'plugin', 'legacy', 'refused']

mitigation: str | None

plugin: str | None

reason: str | None

requested_engine: str | None

require() → AdvancedApiCapabilityDecision[source]: Return this decision when executable, otherwise raise RtError.

to_dict() → dict[str, Any][source]: Return a JSON-native capability record for callers and Studio.

unsupported_capability: str | None

verb: Literal['explain', 'generate']

nirs4all.api.advanced_capabilities.advanced_api_capability_ledger() → dict[str, dict[str, dict[str, Any]]][source]: Return a detached copy of the API-005 capability ledger.

nirs4all.api.advanced_capabilities.preflight_advanced_api(verb: Literal['explain', 'generate'], *, engine: str | None = None, plugin: str | None = None, allow_fallback: bool = False) → AdvancedApiCapabilityDecision[source]

Decide one advanced verb without importing its Python implementation.

Only a named built-in adapter is executable. With no selector, general synthesis and explanation choose their installed adapters before touching inputs. Explicit native/legacy selectors remain unchanged; errors never retry.