(pkg-flow)=
# `rath.flow`

Workflow composition layer. Normal transforming workflows organize `Session -> Session` paths, `AgentParam` stores agent-side state, and `Selector` is the explicit routing exception that returns a workflow choice.

## Source
| Module | Source |
| --- | --- |
| `rath.flow.workflow` | `src/rath/flow/workflow.py` |
| `rath.flow.agent_param` | `src/rath/flow/agent_param.py` |
| `rath.flow.agent` | `src/rath/flow/agent.py` |
| `rath.flow.compressor` | `src/rath/flow/compressor.py` |
| `rath.flow.selector` | `src/rath/flow/selector.py` |
| `rath.flow.empty` | `src/rath/flow/empty.py` |
| `rath.flow.compile` | `src/rath/flow/compile.py` |

## Public contract
### `Workflow`

| Method | Returns | Behavior |
| --- | --- | --- |
| `forward(session)` | `Session` | Execution logic implemented by subclasses. |
| `__call__(session)` | `Session` | Calls `forward(session)`. |
| `named_agents()` | `tuple[tuple[str, AgentParam], ...]` | Returns agent params registered as attributes. |
| `named_children()` | `tuple[tuple[str, Workflow], ...]` | Returns directly registered nested workflows. |
| `modules()` | `list[Workflow]` | Returns this workflow and descendants in depth-first pre-order. |
| `to(target=None, *, provider=None, model=None)` | `Workflow` | Rebinds direct AgentParams only and returns `self`. |
| `compile()` | `CompiledWorkflow` | Builds a static resource snapshot without running a model. |

`Workflow(description="...")` stores an optional description used when the
workflow is offered to a `Selector`.

When an `AgentParam` is assigned to a workflow as an attribute, `Workflow.__setattr__` adds it to `_agents`.

### `AgentParam`

| Field | Type | Description |
| --- | --- | --- |
| `agent_session` | `Session` | Agent/system transcript. |
| `provider` | `Provider` | Model and request parameters. |
| `memory` | `MemoryStore \| None` | Optional memory store bound to the agent. |

`AgentParam.to(...)` accepts an explicit `Provider`, `provider="config-name"`,
or `model="..."`. A named provider is resolved immediately. There is no
`Provider.to()` method.

### Preset workflows
| Class | Constructor arguments | Behavior |
| --- | --- | --- |
| `Agent` | `system_prompt`, `provider=None`, `tools=None`, `model=None`, `on_event=None`, `memory=None`, `memory_inject=None`, `commit_on_forward=False`, `description=""` | Creates an agent session and stores provider/runtime options. `model=` is a shortcut for a default `Provider`; `memory=` attaches a `MemoryStore` or provider spec. `forward(...)` calls `run_session_loop(...)`. |
| `Compressor` | `compress_instruction`, `provider`, `on_event=None`, `description=""` | `forward(...)` calls `run_session_compress(...)`. |
| `Selector` | `provider`, `select_instruction=...`, `description=""`, `on_event=None` | `forward(session, *workflows)` returns the chosen `Workflow` or `EmptyWorkflow`. In v1.3.0 the stored `on_event` callback is not forwarded. |
| `EmptyWorkflow` | `description=""` | `forward(session)` returns the input session unchanged. |

`Agent.register_tool(tool)` adds tools and deduplicates by name. `Agent.unregister_tool(tool_name)` removes the tool with the same name.

### Dynamic routing

`Selector.forward(...)` intentionally does not follow the normal
`Session -> Session` return contract. It makes a routing decision; the caller
then dispatches the returned workflow.

| Result | Meaning |
| --- | --- |
| Candidate `Workflow` | The model selected its zero-based menu index. |
| `EmptyWorkflow` | No candidate, `-1`, missing integer, or out-of-range integer. |

Descriptions are the selector's routing surface. Empty descriptions are valid
but usually provide too little information for a reliable choice.

### Static compilation

```python
compiled = workflow.compile()
manifest = compiled.manifest
problems = compiled.validate()
```

| Type | Key members |
| --- | --- |
| `AgentResource` | `path`, `provider`, `has_memory`, `agent_session_id` |
| `DynamicNode` | `path`, `kind`, `reason` |
| `ResourceManifest` | `agents`, `dynamic_nodes`, `provider_models()`, `provider_kinds()` |
| `CompiledWorkflow` | `workflow`, `manifest`, `validate(...)`, callable/context-manager behavior |

The manifest is a snapshot. `validate()` checks only provider registration and
offline credential resolution. The compiled wrapper delegates execution to the
current workflow; context entry/exit manages distinct bound memory stores.

### Agent memory helpers
| Method | Behavior |
| --- | --- |
| `Agent.remember_memory(content, *, scope="user", category="preferences", wait=False)` | Writes an explicit memory entry through the attached store. |
| `Agent.recall_memory(query, *, top_k=4, target_uri=None)` | Retrieves relevant memory entries. |
| `Agent.commit_memory(session, *, wait=False)` | Commits the session transcript through the attached store. |
| `commit_on_forward=True` | Runs a best-effort commit after each forward call. |

### Runnable workflow examples
| Example | Path | Description |
| --- | --- | --- |
| Hello agent | `example/01_hello_agent.py` | Minimal provider and `Agent` call. |
| Session lineage | `example/02_session_lineage.py` | Key-free fork/detach/merge graph mechanics. |
| Memory | `example/09_memory.py` | Key-free local memory plus optional model-assisted commit. |
| Provider variation | `example/10_provider_variation.py` | Provider config, Anthropic, embeddings, and VLM setup. |
| Dynamic selector | `example/11_dynamic_selector.py` | Model-routed branching and bounded loops. |
| Workflow compile | `example/12_compile.py` | Key-free static manifest and lifecycle inspection. |

These examples use the public `Workflow`, `AgentParam`, `Provider`, and `run_session_loop(...)` APIs, so they are useful source references for multi-agent composition.

## Autodoc
```{eval-rst}
.. autoclass:: rath.flow.Workflow
   :members:

.. autoclass:: rath.flow.AgentParam
   :members:

.. autoclass:: rath.flow.Agent
   :members:

.. autoclass:: rath.flow.Compressor
   :members:

.. autoclass:: rath.flow.Selector
   :members:

.. autoclass:: rath.flow.EmptyWorkflow
   :members:

.. autoclass:: rath.flow.CompiledWorkflow
   :members:

.. autoclass:: rath.flow.ResourceManifest
   :members:

.. raw:: html

   <span id="rath.flow.AgentResource"></span>

.. autoclass:: rath.flow.compile.AgentResource
   :members:

.. raw:: html

   <span id="rath.flow.DynamicNode"></span>

.. autoclass:: rath.flow.compile.DynamicNode
   :members:
```

[← API Reference](index.md)