neurocore.runtime.executor

Blueprint executor — wires skills into FlowEngine and runs them.

The executor is the bridge between NeuroCore’s skill system and FlowEngine’s execution engine. It:

1. Resolves skill names from the blueprint to Skill classes via the registry

2. Merges config: neurocore.yaml skills.<name> (base) + blueprint config (overlay)

3. Creates and initializes Skill instances

4. Builds a FlowEngine FlowConfig and component dict

5. Executes via FlowEngine (sync or async)

Usage:

from neurocore.runtime import execute_blueprint, load_and_run

# Low-level result = execute_blueprint(blueprint, registry, config)

# High-level (load + discover + execute) result = load_and_run(blueprint_path, project_root=Path(“.”))

# Streaming async for event in execute_blueprint_stream(bp, registry, cfg):

print(event.event_type, event.step_name)

Attributes

log

Functions

merge_skill_config(→ dict[str, Any])	Merge skill configuration from neurocore.yaml and blueprint.
execute_blueprint(→ flowengine.FlowContext)	Execute a blueprint. Supports both sync and async skills.
execute_blueprint_tracked(→ flowengine.FlowContext)	Execute a blueprint and persist a durable run record + step history.
resume_blueprint(→ flowengine.FlowContext)	Resume a suspended or failed run, optionally injecting resume_data.
execute_blueprint_stream(...)	Execute a blueprint, yielding FlowEvents as each step runs.
load_and_run(→ flowengine.FlowContext)	High-level function: load config, discover skills, execute blueprint.

Module Contents

neurocore.runtime.executor.log

neurocore.runtime.executor.merge_skill_config(neurocore_config: neurocore.config.schema.NeuroCoreConfig, skill_name: str, blueprint_config: dict[str, Any]) → dict[str, Any]

Merge skill configuration from neurocore.yaml and blueprint.

Priority (highest wins):

1. Blueprint component config (overlay)

2. neurocore.yaml skills.<name> (base)

Parameters:

• neurocore_config – The project’s NeuroCoreConfig.

• skill_name – The skill’s registered name (for neurocore.yaml lookup).

• blueprint_config – Config from the blueprint’s component definition.

Returns:

Merged config dict.

neurocore.runtime.executor.execute_blueprint(blueprint: neurocore.runtime.blueprint.Blueprint, registry: neurocore.skills.registry.SkillRegistry, neurocore_config: neurocore.config.schema.NeuroCoreConfig, *, initial_data: dict[str, Any] | None = None, _tracker: _Tracker | None = None, _base_context: flowengine.FlowContext | None = None, _skip: set[str] | None = None) → flowengine.FlowContext

Execute a blueprint. Supports both sync and async skills.

This is the core execution function. It: 1. Validates skill references 2. Creates and initializes skill instances with merged config 3. Detects async skills and chooses execution path 4. For sync-only blueprints, delegates to FlowEngine 5. For async blueprints, uses asyncio event loop

Parameters:

• blueprint – Parsed Blueprint.

• registry – SkillRegistry with discovered skills.

• neurocore_config – Project configuration.

• initial_data – Optional initial context data (key-value pairs).

Returns:

FlowContext with execution results.

Raises:

• BlueprintError – If validation or instantiation fails.

• ExecutionError – If execution fails.

The leading-underscore params are used internally by execute_blueprint_tracked() and resume_blueprint().

neurocore.runtime.executor.execute_blueprint_tracked(blueprint: neurocore.runtime.blueprint.Blueprint, registry: neurocore.skills.registry.SkillRegistry, neurocore_config: neurocore.config.schema.NeuroCoreConfig, *, initial_data: dict[str, Any] | None = None, run_store: neurocore.persistence.RunStore | None = None, run_id: str | None = None, blueprint_path: pathlib.Path | None = None) → flowengine.FlowContext

Execute a blueprint and persist a durable run record + step history.

Falls back to execute_blueprint() when persistence is disabled.

Returns:

The final FlowContext (may have metadata.suspended set if the run paused at a human-approval gate — resume with resume_blueprint()).

neurocore.runtime.executor.resume_blueprint(run_id: str, registry: neurocore.skills.registry.SkillRegistry, neurocore_config: neurocore.config.schema.NeuroCoreConfig, *, resume_data: dict[str, Any] | None = None, run_store: neurocore.persistence.RunStore | None = None) → flowengine.FlowContext

Resume a suspended or failed run, optionally injecting resume_data.

Suspended runs (e.g. paused at an approval gate) continue from where they stopped; failed runs re-run from the failed step (completed steps are skipped). Works for both the sync (flowengine checkpoint) and async/DAG (restored FlowContext) execution paths.

async neurocore.runtime.executor.execute_blueprint_stream(blueprint: neurocore.runtime.blueprint.Blueprint, registry: neurocore.skills.registry.SkillRegistry, config: neurocore.config.schema.NeuroCoreConfig, initial_data: dict[str, Any] | None = None) → collections.abc.AsyncIterator[Any]

Execute a blueprint, yielding FlowEvents as each step runs.

Usage:

async for event in execute_blueprint_stream(bp, registry, cfg):

print(event.event_type, event.step_name)

neurocore.runtime.executor.load_and_run(blueprint_path: pathlib.Path, *, project_root: pathlib.Path | None = None, initial_data: dict[str, Any] | None = None, track: bool = True) → flowengine.FlowContext

High-level function: load config, discover skills, execute blueprint.

Convenience wrapper that does everything: 1. Load neurocore.yaml config 2. Discover all skills (directory + entry points) 3. Load and parse the blueprint 4. Execute via FlowEngine, persisting run history (when track and

persistence are enabled)

Parameters:

• blueprint_path – Path to the blueprint YAML file.

• project_root – Optional project root (auto-detected if not provided).

• initial_data – Optional initial context data.

• track – Persist a run record + step history (default True).

Returns:

FlowContext with execution results.