loom.ai.describe

Public projection of compiled agents (US7).

The AI pillar’s contribution to describe_app(): it turns each compiled AgentPlan into the subset of itself that is safe to publish.

The projection is an explicit allow-list per capability kind, not a dump of the compiled struct. A grant carries the resolved handle next to the public name — the SQL connection config next to its name, the MCP URL next to its server — so publishing “everything but a deny-list” would leak the moment a new field appears. A kind with no registered projection is therefore an error, never a guess.

Excluded at agent level (FR-054): instructions, the resolved inference target, the built output.decoder and the author’s free-form metadata.

Module Attributes

AGENTS_SECTION	Section the agent descriptions appear under in the application document.
AGENTS_CONTRIBUTOR	module:callable reference resolving to describe_agents().

Functions

_a2a_settings(capability)
_as_builtin(value)	Convert the read-only mappings a compiled schema carries into plain dicts.
_describe_capability(capability)
_describe_policies(policies)	Project policies onto JSON-encodable values, on the wire's own terms.
_mcp_settings(capability)
_native_settings(capability)	Publish the provider tool granted, which is the whole of the grant.
_python_settings(capability)
_skills_settings(capability)
_sql_settings(capability)
_usecase_settings(capability)
describe_agent(plan)	Project one compiled plan into its public description.
describe_agents(subject, /)	Describe a sequence of compiled plans, as the AI pillar's contribution.

Classes

AgentCapabilityDescription(*, kind, settings)	One granted capability, reduced to its publishable settings.
AgentDescription(*, name, description, ...)	Public description of one compiled agent.

loom.ai.describe.AGENTS_SECTION = 'agents'

Section the agent descriptions appear under in the application document.

loom.ai.describe.AGENTS_CONTRIBUTOR = 'loom.ai.describe:describe_agents'

module:callable reference resolving to describe_agents().

class loom.ai.describe.AgentCapabilityDescription(*, kind, settings)

Bases: LoomFrozenStruct

One granted capability, reduced to its publishable settings.

Parameters:

• kind (str)

• settings (Mapping[str, Any])

kind

Capability kind, as declared in the artifact.

Type:

str

settings

Allow-listed settings of that kind; never a resolved handle.

Type:

collections.abc.Mapping[str, Any]

class loom.ai.describe.AgentDescription(*, name, description, spec_version, output_schema, capabilities, policies, source_path)

Bases: LoomFrozenStruct

Public description of one compiled agent.

Parameters:

• name (str)

• description (str)

• spec_version (int)

• output_schema (Mapping[str, Any])

• capabilities (tuple[AgentCapabilityDescription, ...])

• policies (Mapping[str, int | float | str | None])

• source_path (str | None)

name

Unique agent name within the application.

Type:

str

description

The author’s public sentence about the agent.

Type:

str

spec_version

Artifact format the agent compiled from.

Type:

int

output_schema

JSON Schema of the agent’s structured answer.

Type:

collections.abc.Mapping[str, Any]

capabilities

Described grants, in the order the plan carries them.

Type:

tuple[loom.ai.describe.AgentCapabilityDescription, …]

policies

Validated execution limits. An absent optional cap (FR-042) is published as None. max_usd is published as a JSON number, matching the published schema’s own policies.max_usd (type: number) — never as the string msgspec would otherwise encode a Decimal to.

Type:

collections.abc.Mapping[str, int | float | str | None]

source_path

Artifact the agent was compiled from, when known.

Type:

str | None

loom.ai.describe.describe_agent(plan)

Project one compiled plan into its public description.

Parameters:

plan (AgentPlan) – Compiled agent to describe.

Returns:

The publishable subset of the plan.

Raises:

IntrospectionError – When the plan grants a capability kind with no registered projection.

Return type:

AgentDescription

Example:

describe_agent(plan).capabilities[0].kind
# 'usecase'

loom.ai.describe.describe_agents(subject, /)

Describe a sequence of compiled plans, as the AI pillar’s contribution.

This is the callable describe_app() resolves AGENTS_CONTRIBUTOR to.

Parameters:

subject (Any) – Compiled plans, in the order they were compiled.

Returns:

One JSON-encodable mapping per plan, in that same order.

Raises:

IntrospectionError – When a plan grants a capability kind with no registered projection.

Return type:

list[dict[str, Any]]

Example:

describe_agents(plans)[0]["name"]
# 'triage'