# Class LittleGhost::Graph

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Graph.html

Routes a request through named Assembly nodes and declared edges.

A Graph is an Assembly for flows whose allowed paths should be visible in
application code. A node may contain an Agent, Workflow, Swarm, or another
Graph. Edges declare which node may run next.

    class SupportFlowGraph < LittleGhost::Graph
      node :triage, TriageAgent
      node :ledger, LedgerResearchAgent
      node :policy, PolicyResearchAgent
      node :respond, CustomerSupportAgent

      start :triage
      edge :triage, :ledger
      edge :triage, :policy
      edge :ledger, :respond
      edge :policy, :respond
      finish :respond
    end

    SupportFlowGraph.validate!
    run = SupportFlowGraph.ask("Why is my transfer pending?")

Call a named Graph with [ask](Assembly.md#method-c-ask) for its
final Run, or the streaming
[entrypoint](Assembly.md#method-c-stream_ask) for routing and
final-response events.

Multiple unconditional edges from one source run in parallel and converge at
their first unambiguous common successor. Array endpoints declare an explicit
fan-out or wait-for-all fan-in. Parallel groups cannot nest. Conditions and
input mappers receive a read-only Graph::State. Nodes do not receive caller
history or application context unless their declaration opts in with
`history: true` or `context: true`. Validate the
topology before execution. Conditions and mappers are application callbacks
and can inspect copied input, history, context, and completed results.
`to_mermaid` renders the same definition as a flowchart.

## Inheritance

`LittleGhost::Graph < LittleGhost::Assembly`

## Class methods

<a id="method-c-edge"></a>
### `.edge`

```ruby
.edge(from, to, input: nil, max_concurrency: nil, **options, &condition)
```

Declares one route or one bounded parallel edge group.

`input` receives Graph::State and returns the value passed to the target node
or nodes. A scalar source and Array target fan out; an Array source and scalar
target wait for every listed predecessor. At most one conditional scalar or
grouped route may match from the current node; one unconditional route may act
as the fallback. Multiple unconditional scalar edges with the same source
infer one fan-out when no conditional route is present. Supply a condition
with `if:` or a block.

`max_concurrency` overrides Graph.max_concurrency for a scalar-to-Array
fan-out. The original request and complete source output cross to every branch
unless an input mapper replaces them. Array-to-Array edges, conditional fan-in
edges, and `max_concurrency` on other edge shapes raise ArgumentError.

<a id="method-c-error_edge"></a>
### `.error_edge`

```ruby
.error_edge(from, to, on:, input: nil)
```

Routes selected node errors after retries are exhausted.

`on` lists the exception classes this route accepts. An `input` mapper may
turn Graph::State, including `state.error`, into recovery input.

<a id="method-c-finish"></a>
### `.finish`

```ruby
.finish(name = nil)
```

Reads or assigns the terminal node.

<a id="method-c-max_concurrency"></a>
### `.max_concurrency`

```ruby
.max_concurrency(value = nil)
```

Reads or assigns the concurrency bound for parallel groups.

The default is 8. A scalar-to-Array edge may override it for one group.

<a id="method-c-max_steps"></a>
### `.max_steps`

```ruby
.max_steps(value = nil)
```

Reads or assigns the maximum node executions.

<a id="method-c-node"></a>
### `.node`

```ruby
.node(name, assembly, timeout: nil, retries: 0, retry_on: nil, retry_delay: 0,
        history: false, context: false, input: nil)
```

Declares an Assembly node and its optional execution policy.

An `input` mapper receives Graph::State and replaces the default input
whenever the selected edge or edge group does not declare its own mapper.
`history` and `context` opt this node into the corresponding caller data; both
default to `false`.

<a id="method-c-start"></a>
### `.start`

```ruby
.start(name = nil)
```

Reads or assigns the entry node.

<a id="method-c-to_mermaid"></a>
### `.to_mermaid`

```ruby
.to_mermaid()
```

Renders the validated topology as Mermaid flowchart text.

<a id="method-c-validate-21"></a>
### `.validate!`

```ruby
.validate!()
```

Validates the topology and returns this Graph class.

Raises ConfigurationError for undeclared or unreachable nodes, ambiguous
convergence, competing routes at an inferred branch boundary, and overlapping
or nested parallel groups.

## Instance methods

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

<a id="method-i-stream"></a>
### `#stream`

```ruby
#stream(input = nil, history: nil, context: nil,
      cancellation_token: Support::CancellationToken.new, deadline: nil,
      settings: nil, template_locals: nil, template_paths: nil,
      parent_operation_id: nil, checkpoint: nil, **_options)
```

Streams lifecycle events and the finish node's ordinary response events.