loom.ai.registry¶

Engine and provider resolution for the AI pillar.

Resolves the configured engine through loom.core.plugins.entrypoints (group loom.ai.engines, duplicates rejected — FR-021) and offers the two helpers engines use to fail fast on missing provider SDKs and settings.

This module never imports a concrete engine: the entry point is loaded by name and the handshake is a getattr on the loaded object, never an isinstance check, so the contract stays structural.

Module Attributes

`ENGINE_ENTRY_POINT_GROUP`	Entry-point group every engine distribution registers under.
`ENGINE_API_ATTRIBUTE`	Attribute a provider declares its handshake version on.
`SUPPORTED_ENGINE_APIS`	Handshake versions this release of loom accepts.

Functions

`_verify_engine_api`(name, provider)	Check the handshake attribute on the constructed provider, fail-closed.
`configure_engine_mcp_connect_timeout`(...)	Hand the deployment's published MCP handshake budget to the resolved engine.
`engine_client_factories`(provider)	Return the `(mcp, a2a)` live-client factories a provider supplies.
`engine_native_tool_support`(provider)	Return the oracle a provider supplies for provider-run tools.
`engine_supported_kinds`(provider, engine)	Return the capability kinds an engine can actually be trusted to serve.
`require_provider_sdk`(provider, module, extra)	Import a provider SDK module, failing with the extra to install.
`require_provider_setting`(provider, setting, ...)	Require a provider setting to be present and non-empty.
`resolve_engine_provider`(name)	Resolve the engine provider registered under `name`.

loom.ai.registry.ENGINE_ENTRY_POINT_GROUP = 'loom.ai.engines'¶: Entry-point group every engine distribution registers under.

loom.ai.registry.ENGINE_API_ATTRIBUTE = 'LOOM_AI_ENGINE_API'¶: Attribute a provider declares its handshake version on.

loom.ai.registry.SUPPORTED_ENGINE_APIS: frozenset[int] = frozenset({2})¶: Handshake versions this release of loom accepts.

loom.ai.registry.resolve_engine_provider(name)[source]¶

Resolve the engine provider registered under name.

Loads the entry point in group loom.ai.engines with duplicates rejected, instantiates it when it targets a class, and verifies the ENGINE_API_ATTRIBUTE handshake via getattr on the resulting object, so an engine declaring its version in __init__ is accepted.

Parameters:: name (str) – Entry-point name from ai.engine.
Returns:: The provider instance, handshake verified.
Raises:: AgentCompilationError – With ENGINE_NOT_FOUND (listing the installed engines), ENGINE_DUPLICATE (listing every claiming distribution) or ENGINE_API_MISMATCH (missing or unsupported handshake version).
Return type:: AgentEngineProvider

loom.ai.registry.require_provider_sdk(provider, module, extra)[source]¶

Import a provider SDK module, failing with the extra to install.

Parameters:

provider (str) – Provider identifier the error should name.
module (str) – Importable module path of the SDK.
extra (str) – Loom extra whose installation brings the SDK.

Returns:

The imported module.

Raises:

AgentCompilationError – With PROVIDER_NOT_INSTALLED naming the extra when the import fails.

Return type:

ModuleType

loom.ai.registry.require_provider_setting(provider, setting, value)[source]¶

Require a provider setting to be present and non-empty.

None and the empty string count as missing; any other value — including 0 and False — is accepted, since those can be legitimate settings.

Parameters:

provider (str) – Provider identifier the error should name.
setting (str) – Setting name the error should name.
value (object | None) – Resolved setting value.

Raises:

AgentCompilationError – With PROVIDER_SETTING_MISSING naming the setting when the value is absent.

Return type:

None

loom.ai.registry.engine_supported_kinds(provider, engine)[source]¶

Return the capability kinds an engine can actually be trusted to serve.

An engine advertising native without the oracle the compiler needs to check a grant against its model would let the grant through unchecked, so the kind is dropped and the artifact is refused for the right reason.

Parameters:

provider (object) – Engine provider resolved from the entry point group.
engine (str) – Engine name, for the warning that names the offender.

Returns:

The kinds the compiler may accept.

Return type:

frozenset[str]

loom.ai.registry.engine_native_tool_support(provider)[source]¶

Return the oracle a provider supplies for provider-run tools.

Read off the resolved provider with getattr, the same handshake shape as the client factories: the compiler learns what a model binding admits without importing an engine.

Parameters:: provider (object) – Engine provider resolved from the entry point group.
Returns:: The oracle, or None when the engine serves no native grant.
Return type:: Callable[[InferenceTarget], frozenset[str]] | None

Example:

support = engine_native_tool_support(resolve_engine_provider("pydantic-ai"))

loom.ai.registry.engine_client_factories(provider)[source]¶

Return the (mcp, a2a) live-client factories a provider supplies.

Read off the resolved provider, never imported from an engine package: the composition root importing loom.ai.engines.<engine> directly is what would make create_app fail on a deployment running a third-party engine without that one installed, undoing the entry-point seam the pillar exists for (FR-016, FR-051).

Optional by design and read with getattr, the same handshake shape as LOOM_AI_ENGINE_API: an engine that serves neither mcp nor a2a grants declares neither factory, and the compiler already refuses those grants through supported_capability_kinds.

Parameters:: provider (object) – Engine provider resolved from the entry point group.
Returns:: The MCP client factory and the A2A client factory, each None when the engine does not supply it.
Return type:: tuple[McpClientFactory | None, A2AClientFactory | None]

Example:

mcp, a2a = engine_client_factories(resolve_engine_provider("pydantic-ai"))

loom.ai.registry.configure_engine_mcp_connect_timeout(provider, seconds)[source]¶

Hand the deployment’s published MCP handshake budget to the resolved engine.

Read structurally with getattr, the same optional shape as engine_client_factories: an engine that declares no configure_mcp_connect_timeout method is silently left at its own default. resolve_engine_provider() constructs every provider with no arguments, so ai.startup_timeout_ms can only reach the engine after resolution, through this call (FR-051).

Parameters:

provider (object) – Engine provider resolved from the entry point group.
seconds (float) – ai.startup_timeout_ms converted to seconds.

Return type:

None