loom.core.use_case.markers¶

Functions

`Agent`(name)	Factory returning the runtime marker for a named agent handle parameter.
`Caller`()	Factory returning the runtime marker for the caller-identity parameter.
`Exists`(entity_type, *[, from_param, ...])	Factory returning marker for boolean existence checks.
`Input`()	Factory returning the runtime marker for command payload parameters.
`Load`(entity_type, *[, from_param, ...])	Factory returning marker for preloaded entity parameters by field.
`LoadById`(entity_type, *[, by, profile, ...])	Factory returning marker for preloaded entity parameters by id.
`Mcp`(server, *, include)	Factory returning the runtime marker for a named MCP server handle parameter.

Classes

`LookupKind`(value)	Lookup strategy used by marker-driven prefetch.
`OnMissing`(value)	Policy applied when a marker lookup does not resolve an entity.
`SourceKind`(value)	Origin of a lookup value used by Load/Exists markers.
`_AgentMarker`(name)	Marks a parameter as a named agent handle bound to the verified caller.
`_CallerMarker`()	Marks a parameter as the verified identity running the execution.
`_ExistsMarker`(entity_type, *, from_kind, ...)	Marks a parameter as a boolean existence check.
`_InputMarker`()	Marks a parameter as the command payload input.
`_LoadByIdMarker`(entity_type, *[, by, ...])	Marks a parameter as a prefetched entity loaded by id.
`_LoadMarker`(entity_type, *, from_kind, ...)	Marks a parameter as a prefetched entity loaded by an arbitrary field.
`_McpMarker`(server, include)	Marks a parameter as a named MCP server handle bound to this execution.

class loom.core.use_case.markers.SourceKind(value)[source]¶

Bases: StrEnum

Origin of a lookup value used by Load/Exists markers.

class loom.core.use_case.markers.LookupKind(value)[source]¶

Bases: StrEnum

Lookup strategy used by marker-driven prefetch.

class loom.core.use_case.markers.OnMissing(value)[source]¶

Bases: StrEnum

Policy applied when a marker lookup does not resolve an entity.

loom.core.use_case.markers.Input()[source]¶

Factory returning the runtime marker for command payload parameters.

Returned value is intentionally typed as Any in overloads to avoid mypy default-argument incompatibility in signatures like: cmd: Command = Input().

Return type:: Any

loom.core.use_case.markers.Caller()[source]¶

Factory returning the runtime marker for the caller-identity parameter.

The executor injects the Identity the transport verified for this execution. It is a declaration, not an ambient read: the identity travels with the execution instead of hiding in a global.

Returned value is intentionally typed as Any in overloads to avoid mypy default-argument incompatibility in signatures like: caller: Identity = Caller().

Example:

async def execute(self, query: QuerySpec, caller: Identity = Caller()) -> Report:
    return await self._reports.for_owner(caller.require_subject(), query)

Return type:: Any

loom.core.use_case.markers.Agent(name)[source]¶

Factory returning the runtime marker for a named agent handle parameter.

The executor resolves name against the agents compiled for this deployment and injects an AgentHandle bound to this execution’s verified caller — the only way a use case reaches an agent (constructor injection is not offered for this resource). The output type the handle carries is read from the parameter’s own AgentHandle[...] annotation, never from this factory, and is checked at start-up against the named agent’s declared output.

Returned value is intentionally typed as Any in overloads to avoid mypy default-argument incompatibility in signatures like: triage: AgentHandle[SeverityAssessment] = Agent("incident-triage").

Parameters:: name (str) – Name of a compiled agent, as declared by its artifact.
Return type:: Any

Example:

async def execute(
    self,
    caller: Identity = Caller(),
    triage: AgentHandle[SeverityAssessment] = Agent("incident-triage"),
) -> IncidentReport:
    assessment = await triage.run("Assess this incident.")
    ...

loom.core.use_case.markers.Mcp(server, *, include)[source]¶

Factory returning the runtime marker for a named MCP server handle parameter.

The executor resolves server against the MCP servers compiled for this deployment and injects an McpHandle bound to this execution’s verified caller — the only way a use case reaches an MCP server (constructor injection is not offered for this resource). Names in include are globs, matched by the same select_names/admits the model’s own toolset filter uses; there is no exclude in this version because no caller has asked for one and a short allow-list already expresses every case on the table. Under ai.remote_clients: optional, a server tolerated unreachable at start-up still resolves to a handle — every call on it fails with TOOL_UNAVAILABLE instead.

Unlike Agent(), no output type is ever checked against the parameter’s annotation: McpHandle carries no type parameter, so there is no declared shape to compare it with. Both checks a Mcp() marker gets are already wired at start-up, aborting the boot rather than waiting for a first call: server is validated against ai.mcp_servers, naming the declaring use case and parameter when it is not configured, and include is checked against the server’s real tool list under the same startup_timeout_ms an agent’s own mcp filter is checked against. The second check needs a listing, so under ai.remote_clients: optional a server that never connected is skipped rather than failing: a tolerated outage means the filter goes unverified, not that it verified clean.

Returned value is intentionally typed as Any to avoid mypy default-argument incompatibility in signatures like: search: McpHandle = Mcp("docs-server", include=["search"]).

Parameters:

server (str) – Name of a configured MCP server, as declared under ai.mcp_servers.
include (Sequence[str]) – Glob patterns naming the tools this handle may call. Keyword-only and required: everywhere this include/exclude shape is used, an empty include means “every name” — the filter only narrows when it carries at least one pattern — so an empty sequence here would silently grant the entire server, not the handful of tools the signature names. Mcp() raises ValueError instead of widening the grant behind the caller’s back. A bare str is rejected the same way: str satisfies Sequence[str], so include="search" would type-check yet split into six single-character glob patterns at runtime.

Raises:

ValueError – If include is empty, or is a single string instead of a sequence of patterns.

Return type:

Any

Example:

async def execute(
    self,
    caller: Identity = Caller(),
    docs: McpHandle = Mcp("docs-server", include=["search", "fetch"]),
) -> Report:
    names = docs.tools()
    ...

loom.core.use_case.markers.LoadById(entity_type, *, by='id', profile='default', on_missing=OnMissing.RAISE)[source]¶

Factory returning marker for preloaded entity parameters by id.

Returned value is intentionally typed as Any in overloads to avoid mypy default-argument incompatibility in signatures like: entity: User = LoadById(User, by="id").

Parameters:

entity_type (type[EntityT]) – Domain entity type the repository should load.
by (str) – Name of the primitive parameter used as the lookup key. Defaults to "id".
profile (str) – Loading profile forwarded to repo.get_by_id. Defaults to "default".
on_missing (OnMissing) – Missing-entity policy. Defaults to OnMissing.RAISE.

Return type:

Any

loom.core.use_case.markers.Load(entity_type, *, from_param=None, from_command=None, against, profile='default', on_missing=OnMissing.RAISE)[source]¶

Factory returning marker for preloaded entity parameters by field.

Parameters:

entity_type (type[EntityT])
from_param (str | None)
from_command (str | None)
against (str)
profile (str)
on_missing (OnMissing)

Return type:

Any

loom.core.use_case.markers.Exists(entity_type, *, from_param=None, from_command=None, against, on_missing=OnMissing.RETURN_FALSE)[source]¶

Factory returning marker for boolean existence checks.

Parameters:

entity_type (type[EntityT])
from_param (str | None)
from_command (str | None)
against (str)
on_missing (OnMissing)

Return type:

Any