Introspection (Self-description spine)

machina.introspect is the framework's self-description spine — a single, code-derived description of what Machina can do (connectors × capabilities), how it is configured, and where its extension seams are. It is derived entirely from code (the Capability enum, the connector type registry, connector ClassVar declarations, the config schema, and the seam Protocols), imports no heavy optional dependency, and returns a fully deterministic (sorted) structure.

It is the neutral core that the generated capability artifacts (docs/capabilities.md and docs/capabilities.json) render from — so they cannot drift from the code (a CI drift gate enforces it). The hand-curated llms.txt is a stable index that points at those generated artifacts rather than being generated itself. The same core also backs the machina describe CLI and the machina://v1/capabilities MCP resource, so all of these surfaces serve one code-derived source.

describe

The single public entry point. A pure read: no connector instantiation, no connect_all, no I/O beyond imports. Safe on a bare pip install machina-ai. Two consecutive calls in one process return identical data.

describe

describe() -> Spine

Return a deterministic, code-derived self-description of Machina.

A pure read: no I/O beyond imports, no connector instantiation, no connect_all, no heavy optional-dependency import. Safe on a bare pip install machina-ai (core only). Two consecutive calls in one process return identical data (every collection is stably sorted).

Returns:

Name	Type	Description
A	Spine	class:Spine describing connectors x capabilities, the config
	Spine	schema shape, the extension seams, and known introspection gaps.

Spine

The complete code-derived self-description returned by describe.

Spine dataclass

Spine(connectors: tuple[ConnectorInfo, ...], capabilities: tuple[CapabilityInfo, ...], seams: Seams, config_schema: dict[str, Any] = dict(), gaps: Gaps = (lambda: Gaps(orphaned_capabilities=(), settings_note=''))())

The complete code-derived self-description of Machina.

Parameters:

Name	Type	Description	Default
connectors	tuple[ConnectorInfo, ...]	All registered connector types, sorted by type.	required
capabilities	tuple[CapabilityInfo, ...]	The full capability vocabulary, sorted by value.	required
seams	Seams	Protocol and convention extension seams.	required
config_schema	dict[str, Any]	MachinaConfig.model_json_schema() (shape only, never any configured values).	dict()
gaps	Gaps	Known introspection gaps.	(lambda: Gaps(orphaned_capabilities=(), settings_note=''))()

Connectors

ConnectorInfo dataclass

ConnectorInfo(type: str, class_name: str, dotted_path: str, requires_extra: str | None, extra_installed: bool | None, instance_computed: bool, capabilities: tuple[ConnectorCapability, ...] = (), degraded: bool = False, error: str = '')

A connector type known to the default factory registry.

Parameters:

Name	Type	Description	Default
type	str	Registry key (e.g. "opcua").	required
class_name	str	Connector class name (e.g. "OpcUaConnector").	required
dotted_path	str	Import path from _CONNECTOR_FACTORIES.	required
requires_extra	str | None	pip extra needed for full functionality, or None.	required
extra_installed	bool | None	Whether that extra's package is importable now (probed via find_spec, None when there is no extra).	required
instance_computed	bool	True when the capability set is computed at instance level (base set read from _BASE_CAPABILITIES).	required
capabilities	tuple[ConnectorCapability, ...]	Capabilities this connector provides, sorted by value.	()
degraded	bool	True when the class could not be imported/introspected (entry kept rather than dropped); error carries the reason.	False
error	str	Import/introspection failure message, empty when healthy.	''

ConnectorCapability dataclass

ConnectorCapability(capability: str, method: str, configurable: bool = False)

One capability a connector provides, with how it is provided.

Parameters:

Name	Type	Description	Default
capability	str	The capability value (stable wire string).	required
method	str	The connector method that backs it.	required
configurable	bool	True when the capability is only available under certain configuration (e.g. SQL writes need capabilities: read_write, calendar writes need a writable backend). Such capabilities are annotated, never resolved, because describe() runs without a :class:MachinaConfig.	False

Capabilities

CapabilityInfo dataclass

CapabilityInfo(value: str, method: str, provided_by: tuple[str, ...] = (), configurable_in: tuple[str, ...] = (), orphaned: bool = False, orphan_note: str = '')

A capability in the vocabulary, with which connectors provide it.

Parameters:

Name	Type	Description	Default
value	str	The capability value (stable wire string).	required
method	str	The backing method name from CAPABILITY_TO_METHOD (empty if the capability is unmapped — a coverage gap).	required
provided_by	tuple[str, ...]	Connector types that provide it (live), sorted.	()
configurable_in	tuple[str, ...]	Connector types where it is configuration-gated.	()
orphaned	bool	True when no factory-registered connector provides it (declared only by a connector absent from the registry, e.g. SimulatedSensorConnector).	False
orphan_note	str	Human-readable explanation when orphaned.	''

Extension seams

Seams dataclass

Seams(protocols: tuple[ProtocolSeam, ...], conventions: tuple[ConventionSeam, ...], add_connector_template: str = 'connectors/{category}/{name}.py')

The framework's extension seams.

Parameters:

Name	Type	Description	Default
protocols	tuple[ProtocolSeam, ...]	Reflectable Protocol seams, sorted by name.	required
conventions	tuple[ConventionSeam, ...]	Convention (non-Protocol) seams, sorted by name.	required
add_connector_template	str	Canonical location for a new connector.	'connectors/{category}/{name}.py'

ProtocolSeam dataclass

ProtocolSeam(name: str, location: str, doc: str, methods: tuple[SeamMethod, ...] = ())

A seam that is a reflectable Protocol.

Parameters:

Name	Type	Description	Default
name	str	Protocol class name.	required
location	str	Module path where it is defined.	required
doc	str	First line of the Protocol docstring.	required
methods	tuple[SeamMethod, ...]	Required methods, sorted by name.	()

ConventionSeam dataclass

ConventionSeam(name: str, note: str, location_template: str)

A seam that is a convention, not a Protocol (cannot be reflected).

Parameters:

Name	Type	Description	Default
name	str	Human name of the seam.	required
note	str	One-line description of what implementing it does.	required
location_template	str	Where the implementer adds code.	required

SeamMethod dataclass

SeamMethod(name: str, is_async: bool, doc: str = '')

A method on a seam Protocol, reflected via inspect.

Parameters:

Name	Type	Description	Default
name	str	Method name.	required
is_async	bool	Whether the method is declared async.	required
doc	str	First line of the method docstring (may be empty).	''

Gaps

Known introspection gaps surfaced to the consumer (orphaned capabilities with no registered provider, and the open per-connector settings dict that the config schema does not capture).

Gaps dataclass

Gaps(orphaned_capabilities: tuple[str, ...], settings_note: str, unmapped_capabilities: tuple[str, ...] = ())

Known introspection gaps surfaced to the consumer.

Parameters:

Name	Type	Description	Default
orphaned_capabilities	tuple[str, ...]	Capability values with no registered provider, sorted.	required
settings_note	str	Why per-connector settings are not in the schema.	required
unmapped_capabilities	tuple[str, ...]	Capability values absent from CAPABILITY_TO_METHOD (should be empty; a guard signal).	()