telar-core/dev.deeptelar.telar/StateGraph

StateGraph

Builder for a graph of nodes and edges over an immutable State.

val graph = StateGraph<AgentState> {
    node("research") { state -> state.copy(notes = search(state.question)) }
    node("write") { state -> state.copy(answer = draft(state.notes)) }

    edge(START, "research")
    conditionalEdge("research", targets = setOf("write", END)) { state ->
        if (state.notes.isEmpty()) END else "write"
    }
    edge("write", END)
}.compile()

Execution starts at START and ends when every active branch reaches END. A node with no outgoing edge routes to END.

node returns a NodeRef. Using the references with then and conditionalEdge instead of repeating node names lets the compiler catch typos:

val graph = StateGraph<AgentState> {
    val research = node("research") { ... }
    val write = node("write") { ... }

    START then research
    conditionalEdge(research, targets = setOf(write, NodeRef.END)) { state ->
        if (state.notes.isEmpty()) NodeRef.END else write
    }
    write then END
}.compile()

Constructors

StateGraph

constructor()

Functions

compile

fun compile(reducer: Reducer<State>? = null): CompiledGraph<State>

Validates the graph and returns an executable CompiledGraph.

conditionalEdge

@JvmName(name = "conditionalEdgeToRefs")

fun conditionalEdge(from: NodeRef, targets: Set<NodeRef>, condition: suspend (State) -> NodeRef)

Adds a conditional edge that works with references instead of names: condition returns one of targets, so a misspelled node is a compiler error.

fun conditionalEdge(from: NodeRef, targets: Set<String>? = null, condition: EdgeCondition<State>)

Adds a conditional edge from the node referenced by from. See the overload taking a node name.

@JvmName(name = "conditionalEdgeToRefs")

fun conditionalEdge(from: String, targets: Set<NodeRef>, condition: suspend (State) -> NodeRef)

Adds a conditional edge that works with references, from the node named from, usually START. See the overload taking a node reference.

fun conditionalEdge(from: String, targets: Set<String>? = null, condition: EdgeCondition<State>)

Adds a conditional edge: after from finishes, condition picks the next node from the state.

edge

fun edge(from: String, to: String)

Adds a static edge: after from finishes, to runs. Several static edges from the same node fan out and run their targets in parallel. See compile for when that needs a Reducer.

node

fun node(name: String, action: NodeAction<State>): NodeRef

Adds a node named name that runs action and returns a reference to it for use with then.

fun <Result> node(name: String, work: suspend (State) -> Result, update: suspend (State, Result) -> State): NodeRef

Adds a node whose job is split in two, so that it can run next to other nodes without a Reducer. work does the slow part, such as a call to a model or a service, and returns a result. update writes that result into the state.

fun node(name: String, retry: Retry? = null, timeout: Duration? = null, action: NodeAction<State>): NodeRef

Adds a node that is tried again when it fails, that has a time limit, or both.

fun <Result> node(name: String, work: suspend (State) -> Result, retry: Retry? = null, timeout: Duration? = null, update: suspend (State, Result) -> State): NodeRef

Adds a node with a work and an update that is tried again when it fails, that has a time limit, or both. See the overload of a node that returns a whole state for what retry and timeout do.

subgraph

fun subgraph(name: String, graph: CompiledGraph<State>): NodeRef

Adds a node that runs another graph with the same state type, a subgraph. It receives the state of this graph and its result is the next state, like a node that returns a whole state.

fun <Child> subgraph(name: String, graph: CompiledGraph<Child>, state: suspend (State) -> Child, update: suspend (State, Child) -> State): NodeRef

Adds a node that runs another graph, a subgraph, on a state of its own type.

then

infix fun NodeRef.then(to: NodeRef): NodeRef

Adds a static edge from this node to to and returns to, so edges can be chained: START then research then write then END.

infix fun NodeRef.then(to: String): String

Adds a static edge from this node to the node named to, usually END.

infix fun String.then(to: NodeRef): NodeRef

Adds a static edge from the node named by this string, usually START, to to.