nanobrain-from-config

name

nanobrain-from-config

description

How to create nanobrain components correctly via the mandatory `from_config` pattern. Read this FIRST before authoring any nanobrain code (steps, workflows, agents, tools, data units, links, triggers, executors). Covers the call sequence inside `from_config()`, configuration file path resolution, the four supported input shapes (str/Path/dict/Pydantic), the `class:` auto-delegation trick, the `_allow_direct_instantiation` backdoor, and the verbatim error messages the framework raises on violations.

nanobrain-from-config

Why this skill exists

The nanobrain framework enforces configuration-driven component creation. Direct constructors (Class(name="x")) are not just discouraged — they are forbidden by the framework, which raises RuntimeError from __init__. Every component you author must inherit from FromConfigBase and must be created via Class.from_config(config). This skill is the contract.

Adjacent silent-failure to be aware of: the from_config path can succeed while every DirectLink in the loaded workflow is a runtime no-op (default auto_transfer=False). See nanobrain-data-units-triggers-links for the warning. from_config is necessary, not sufficient, for a working workflow.

Wrong-Python failure looks like missing deps. A ModuleNotFoundError at from_config time is almost always wrong-Python (system anaconda picked over .venv/bin/python). See nanobrain-testing-debugging § Wrong Python interpreter for diagnosis.

File:line ground truth (cite when in doubt)

Concern	File	Approx. line
FromConfigBase class	nanobrain/nanobrain/core/component_base.py	134
from_config() method body	nanobrain/nanobrain/core/component_base.py	287–675
__init__ prohibition	nanobrain/nanobrain/core/component_base.py	860–865
_resolve_config_file_path	nanobrain/nanobrain/core/component_base.py	700–791
validate_config_schema	nanobrain/nanobrain/core/component_base.py	793–809
extract_component_config (default)	nanobrain/nanobrain/core/component_base.py	811–820
resolve_dependencies (default)	nanobrain/nanobrain/core/component_base.py	822–830
create_instance (uses __new__)	nanobrain/nanobrain/core/component_base.py	832–839
_init_from_config (default)	nanobrain/nanobrain/core/component_base.py	841–853
ConfigBase (file-path-only)	nanobrain/nanobrain/core/config/config_base.py	~700–760

Line numbers may drift across framework versions; if an exact line doesn't match, search by symbol name. The semantics below are stable.

Mental model

Class.from_config(config) runs six phases in order:

1. Normalize input to a dict (file path → YAML load; dict → use as-is; Pydantic model → .model_dump()).
2. Class auto-detection. If the YAML has a top-level class: "module.path.ClassName" field and that path differs from the called class, the call is delegated — target_class.from_config(config_path, **kwargs) is invoked and the original class is bypassed entirely. This is intentional but easy to miss.
3. Config object creation. Calls cls._get_config_class() (which the subclass MUST implement) and instantiates it via its own from_config method (or constructor for legacy classes).
4. Schema validation. validate_config_schema(config_object) checks that REQUIRED_CONFIG_FIELDS are present.
5. Dependency resolution. extract_component_config() then resolve_dependencies() produce the kwargs the instance needs.
6. Instance creation via __new__. create_instance(...) calls cls.__new__(cls) to bypass __init__ (which would otherwise raise), then calls _init_from_config(config, component_config, dependencies). Finally, _post_config_initialization() is the last hook.

The four supported config shapes

# 1) YAML file (recommended for production)
agent = ConversationalAgent.from_config('config/agent.yml')

# 2) pathlib.Path object
from pathlib import Path
agent = ConversationalAgent.from_config(Path('config/agent.yml'))

# 3) Inline dict (testing / smoke tests only — see exception below)
agent = ConversationalAgent.from_config({'name': 'test', 'model': 'gpt-4'})

# 4) Pydantic config model (advanced)
config_obj = AgentConfig.from_config('config/agent.yml')
agent = ConversationalAgent.from_config(config_obj)

Exception for inline dicts: ConfigBase-derived configs reject inline dicts with the error ❌ FRAMEWORK VIOLATION: {ClassName}.from_config ONLY accepts file paths. The classes that do accept inline dicts are DataUnit, Link, Trigger (and their subclasses) — the framework whitelists them in _is_inline_config_supported (config_base.py ~line 1115). For everything else, use a YAML file.

Path resolution order (relative paths)

_resolve_config_file_path tries strategies in this order until one exists:

1. Absolute path — used as-is (raises FileNotFoundError if it doesn't exist).
2. Calling-class directory — inspect.getfile(cls) parent + relative path.
3. Calling-class parent directory — one level up from #2 (lets you put shared configs adjacent to the package, not inside it).
4. Current working directory — Path.cwd() + relative path.
5. Workflow base directory — only if the relative path contains workflows/, search nanobrain/library/workflows, library/workflows, workflows.

If all strategies fail, the framework raises ❌ CONFIGURATION FILE RESOLUTION FAILED: {config_file} with every searched path enumerated. Read the message — it tells you exactly which directories were checked.

Worked example. MyStep.from_config('config/data_step.yml') where MyStep is defined at nanobrain/library/steps/my_step.py:

1. Tries nanobrain/library/steps/config/data_step.yml (class dir).
2. Tries nanobrain/library/config/data_step.yml (class parent dir).
3. Tries <cwd>/config/data_step.yml.
4. Tries workflow base only if path contained workflows/ (it didn't).
5. Raises with all three attempts listed.

What you implement in a subclass

Mandatory. Your subclass must define:

@classmethod
def _get_config_class(cls):
    """Return the Pydantic config class for this component type."""
    return MyComponentConfig

If you forget, the framework raises:

NotImplementedError: Subclass {YourClass} must implement _get_config_class()
to specify which config class to use. This is the ONLY component-specific
method required.

Optional overrides. Each has the same signature across all components:

@classmethod
def extract_component_config(cls, config) -> Dict[str, Any]:
    # Default extracts: name, description, timeout, enable_logging
    base = super().extract_component_config(config)
    base['my_field'] = config.my_field
    return base

@classmethod
def resolve_dependencies(cls, component_config, **kwargs) -> Dict[str, Any]:
    # Default returns: enable_logging, debug_mode, framework_version
    deps = super().resolve_dependencies(component_config, **kwargs)
    deps['executor'] = kwargs.get('executor') or LocalExecutor.from_config('config/local.yml')
    return deps

def _init_from_config(self, config, component_config, dependencies) -> None:
    super()._init_from_config(config, component_config, dependencies)
    self.executor = dependencies['executor']
    self.my_state = {}

def _post_config_initialization(self) -> None:
    # Last hook — runs after _init_from_config. No-op by default.
    self.nb_logger.info(f"{self.name} ready")

Do not override __init__. If you must run code at construction time, put it in _init_from_config or _post_config_initialization.

The class: auto-delegation trick

If a YAML file declares its target class:

# config/my_step.yml
class: "nanobrain.library.steps.specialized.MySpecializedStep"
name: my_step
description: ...

…then any call like BaseStep.from_config('config/my_step.yml') will delegate to MySpecializedStep.from_config(...) and never invoke BaseStep's own _init_from_config. This is how factory-style loading works in nanobrain.

Implication: when authoring a config file, decide whether you want this delegation. If yes, put class: at the top. If no (you want to control which class loads it), omit class: and call the right class explicitly in code.

The _allow_direct_instantiation backdoor (do not use)

__init__ raises RuntimeError unless cls._allow_direct_instantiation is truthy. The framework sets this flag temporarily inside ConfigBase._create_validated_instance and immediately resets it. Setting this flag persistently on a subclass to bypass the framework is a violation of workspace policy. If you find code doing this, treat it as a bug.

Verbatim error messages (recognize these)

When you see one of these, search this skill first — the fix is usually a config-shape mistake.

RuntimeError: Direct instantiation of {ClassName} is prohibited.
Use: {ClassName}.from_config(config_file_or_object)

You called ClassName(...). Replace with ClassName.from_config('path.yml').

❌ FRAMEWORK VIOLATION: {ClassName}.from_config ONLY accepts file paths.
   GIVEN: <class 'dict'>
   REQUIRED: str or Path object pointing to YAML configuration file
   NOTE: Only DataUnit, Link, Trigger classes support inline dict config

You passed a dict to a ConfigBase subclass that requires a file. Save the dict to a YAML file and pass its path.

❌ CONFIGURATION FILE RESOLUTION FAILED: {config_file}
   CALLING CLASS: {module.ClassName}
   SEARCHED PATHS:
      1. ...
      2. ...

Read the searched paths. Either move the file to one of them or pass an absolute path.

ComponentConfigurationError: {ClassName} missing required configuration fields:
['field_a', 'field_b']

Add the listed fields to your YAML.

NotImplementedError: Subclass {YourClass} must implement _get_config_class()
to specify which config class to use.

Add @classmethod def _get_config_class(cls): return YourConfig to your subclass.

Common pitfalls

1. Class auto-delegation surprise. A YAML loaded by BaseStep.from_config() silently delegates to a different class because of a class: field at the top. The original class's extract_component_config and resolve_dependencies are never called. If you need them, drop the class: field or call the declared class directly.
2. Path-resolution race. If the same config filename exists in both the class directory and the cwd, the class directory wins. Duplicate config files in two places is a foot-gun.
3. Inline dict to ConfigBase. Easy to do in tests, blows up at runtime with ONLY accepts file paths. Either save the dict to a temp YAML or use a class that allows inline dicts (DataUnit, Link, Trigger).
4. Forgot _get_config_class. The error is descriptive; just add the classmethod returning your Config class.
5. Tried to use __init__ for setup. Move the work to _init_from_config or _post_config_initialization.

Checklist before you commit

• No Class(...) for any FromConfigBase subclass — only Class.from_config(...).
• Every component config lives in a YAML file (or is a dict, only if the class is DataUnit/Link/Trigger).
• _get_config_class is defined on every subclass you authored.
• No __init__ override.
• Relative config paths resolve through one of the documented strategies; if tests run from a different cwd, prefer the class-directory strategy (place configs next to the class).
• No _allow_direct_instantiation set to True on your code.

New from_config-compatible primitives (2026-05-09 -> 2026-05-11)

The eval_03 Tier 0-4 chain shipped 14+ new framework primitives that all follow the standard from_config pattern. Quick reference:

Need	Class	Module
Per-run provenance recorder	ProvenanceContext	nanobrain.core.provenance
Skeleton → runnable workflow	Workflow.from_skeleton (G9-completion classmethod)	nanobrain.core.workflow
Local Python-callable tool dispatch	LocalParslAdapter (G11-completion)	nanobrain.library.tools.local_parsl_adapter
Generic HTTP tool dispatch	HTTPBackendAdapter (G38)	nanobrain.library.tools.http_backend_adapter
Deferred human approval gate	DeferredHITLStep (G27)	nanobrain.library.steps.deferred_hitl_step
Approval persistence	InMemoryApprovalStore / FileApprovalStore (G27)	nanobrain.library.runtime.approval_store
Workflow cost cap enforcement	CostTracker (G26)	nanobrain.core.cost_envelope
Versioned data-source manifest	DataSourceRegistry (G24)	nanobrain.library.runtime.data_source_registry
Prompt regression harness	PromptRegressionHarness (G25)	nanobrain.library.testing.prompt_regression
Per-run scope (run_id + tokens + namespace)	WorkflowRunContext (G13+G28)	nanobrain.library.orchestration.run_context
Workspace-root locator	locate_workflow_root (G40)	nanobrain.library.runtime.workspace_root

Each follows the standard pattern: Component.from_config(path) OR Component.from_config(dict) (when the class permits inline-dict admission). Specialized primitives override from_config to admit pluggable runtime kwargs (e.g., ApprovalStore, http_callable) that cannot be loaded from YAML alone — these are passed as from_config(path, kwarg=...).