Subroutine

A subroutine owns a directed graph, its input and output types, parameters, and lexically nested definitions. Its graph combines features, agent resources, nodes, edges, and visits. A subroutine call executes the graph in the caller's process and Python environment.

Authored files

Boundary values

● impl.py is the type boundary seen by callers:

from dataclasses import dataclass

@dataclass(frozen=True, slots=True, kw_only=True)
class Count:
    value: int = 10

@dataclass(frozen=True, slots=True, kw_only=True)
class Params:
    pass

Input = Count
Output = Count

Params configures this definition and does not flow along edges. Input enters through the enter port; a value reaching the exit port must match Output.

Profiles and sessions may be defined locally or declared as resources that a caller must supply. A generated call-node declaration records the child parameter closure and maps those resource arguments.

Countdown example

The Countdown workflow wraps one subroutine:

Subroutine element	Countdown
ID	main (demo.countdown.main)
Input	Count
Output	Count
Params	Empty immutable dataclass
Example run	Count(value=10) → Count(value=0)
Owned graph	The counter feature, four executable nodes, and six edges

Files

Each subroutine directory contains a generated declaration, component registries, package markers for nested definitions, and an authored boundary module.

General subroutine structure

src/<package>/subroutines/<subroutine>/
├── ◆ __init__.py
├── ◆ workflows/__init__.py
├── ◆ subroutines/__init__.py
├── ◆ profiles/__init__.py
├── ◆ sessions/__init__.py
├── ◆ features/__init__.py
├── ◆ nodes/__init__.py
├── ◆ edges/__init__.py
└── ● impl.py

Nested subroutines repeat this complete layout under subroutines/<owner>/subroutines/<id>/.

File	Role
◆ __init__.py	Exposes boundary types, declares typed identifiers, and assembles ports and component registries in the cached definition() factory.
◆ workflows/__init__.py and ◆ subroutines/__init__.py	Empty package markers for nested definitions.
Other collection ◆ __init__.py files	Collect directly owned features, profiles, sessions, nodes, and edges.
● impl.py	Declares the immutable Params type and the subroutine's Input and Output types.

Generated files

See the generated declaration reference for the Python declarations and registries maintained by generation.