Module blueprint

Expand description

Blueprint runner — glue that executes a flow.ir AST (mlua_flow_ir::Node) through the engine. Each Step.ref is run as a single task via start_task + dispatch_attempt_with, and the resulting Pass Value is written back to Step.out.

Fully-async chain. Uses mlua_flow_ir::eval_async and AsyncDispatcher; block_on and spawn_blocking are never mixed in, so the whole stack stays consistent with the engine’s tokio async world.

§Usage

let dispatcher = EngineDispatcher::with_spawner(engine.clone(), op_token, spawner);
let bp: mlua_flow_ir::Node = serde_json::from_str(BP_JSON)?;
let final_ctx = mlua_flow_ir::eval_async(&bp, init_ctx, &dispatcher).await?;

§Schema types (the IF crate)

Blueprint / AgentDef / AgentKind and friends live in the mlua_swarm_schema crate and are re-exported from here. The struct/enum set that used to live directly in src/blueprint.rs has been moved into the IF crate to support extension discipline, versioning, and external consumers.

Modules§

compiler: Blueprint Compiler, CompiledAgentTable, and the three default SpawnerFactory implementations.
loader: Blueprint loader (Phase B). Loads a Blueprint from a JSON / YAML file and recursively expands the internal {"$file": "..."} refs.
store: BlueprintStore — the Blueprint VCS abstraction.

Structs§

AgentDef: Maps an agent name to a Worker IMPL kind and its configuration. Referenced from flow.ir Step.ref by name.
AgentMeta: Agent / Operator level metadata (description / version / tags).
AgentProfile: Agent persona information. Orthogonal to the backend kind (Shell / InProc / Operator).
Blueprint: Unified package of flow.ir + Swarm extension layers. The entry-point type of Swarm.
BlueprintMetadata: Blueprint-level metadata (description / origin / tags / ttl / version label / alias).
CompilerHints: Per-agent overrides / hints. Interpreted by the Compiler / SpawnerFactory; not required.
CompilerStrategy: Compiler behavior rules. Controls strict / lenient handling and default fallback.
EngineDispatcher: Bridges mlua_flow_ir::AsyncDispatcher to the engine’s start_task + dispatch_attempt_with pair. Holds one Operator session token and one spawner, and spins up a fresh task per Step.ref, using it as the agent name.
OperatorDef: Design-time definition of an Operator role (first-class).
SpawnerHints: Set of capability hint keys for the SpawnerLayer required by a Blueprint.

Enums§

AgentKind: SoT of the Worker IMPL axis. A closed enum managed inside Swarm and extended by variant addition through explicit maintenance. String lookup / escape hatches are deliberately not adopted.
BlueprintOrigin: Provenance record of a Blueprint.
SchemaOperatorKind: The schema-side OperatorKind (see crate::core::ctx::OperatorKind for the runtime duplicate consumed by Engine). Re-exported under an explicit alias so callers reading Blueprint.operators[].kind / Blueprint.default_operator_kind do not have to reach into mlua_swarm_schema directly. Kind axis of an Operator role (= “in which mode does this Operator run”). Corresponds 1:1 with the engine’s runtime OperatorKind. Kept as a schema duplicate so that BPs can be authored while depending only on this crate.

Constants§

CURRENT_SCHEMA_VERSION: Current Blueprint schema version. Tied to this crate’s semver.

Functions§

current_schema_version: Blueprint construction helper: returns the semver of the current schema version. Callers can write schema_version: current_schema_version(),.
default_global_agent_kind: Global default AgentKind at the Schema impl Default layer. Bottom of the 4-layer cascade.