neurocore.runtime.executor
==========================

.. py:module:: neurocore.runtime.executor

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   neurocore.runtime.executor.log


Functions
---------

.. autoapisummary::

   neurocore.runtime.executor.merge_skill_config
   neurocore.runtime.executor.execute_blueprint
   neurocore.runtime.executor.execute_blueprint_tracked
   neurocore.runtime.executor.resume_blueprint
   neurocore.runtime.executor.execute_blueprint_stream
   neurocore.runtime.executor.load_and_run


Module Contents
---------------

.. py:data:: log

.. py:function:: 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)

   :param neurocore_config: The project's NeuroCoreConfig.
   :param skill_name: The skill's registered name (for neurocore.yaml lookup).
   :param blueprint_config: Config from the blueprint's component definition.

   :returns: Merged config dict.


.. py:function:: 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

   :param blueprint: Parsed Blueprint.
   :param registry: SkillRegistry with discovered skills.
   :param neurocore_config: Project configuration.
   :param initial_data: Optional initial context data (key-value pairs).

   :returns: FlowContext with execution results.

   :raises BlueprintError: If validation or instantiation fails.
   :raises ExecutionError: If execution fails.

   The leading-underscore params are used internally by
   :func:`execute_blueprint_tracked` and :func:`resume_blueprint`.


.. py:function:: 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 :func:`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 :func:`resume_blueprint`).


.. py:function:: 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.


.. py:function:: 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]
   :async:


   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)


.. py:function:: 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)

   :param blueprint_path: Path to the blueprint YAML file.
   :param project_root: Optional project root (auto-detected if not provided).
   :param initial_data: Optional initial context data.
   :param track: Persist a run record + step history (default True).

   :returns: FlowContext with execution results.