telar-core/dev.deeptelar.telar

Package-level declarations

Types

data class Checkpoint<State>(val state: State, val nextNodes: List<String>, val step: Int = 0, val interruptedBefore: Boolean = false, val subgraphs: Map<String, SubgraphPosition> = emptyMap())

A saved point in a graph run.

CheckpointCorruptedException

class CheckpointCorruptedException(val threadId: String, message: String, cause: Throwable? = null) : TelarException

The stored checkpoint of threadId could not be read, for example because the file is damaged or was written in a newer format. Checkpointer implementations throw this from Checkpointer.load.

Checkpointer

interface Checkpointer<State>

Persists the checkpoints of each thread so a run can pause and resume later, even in a different process.

CheckpointNotFoundException

class CheckpointNotFoundException(val threadId: String) : TelarException

CompiledGraph.resume was called for threadId, but the checkpointer has no checkpoint for it.

CompiledGraph

class CompiledGraph<State>

An executable graph produced by StateGraph.compile. It is immutable and can be shared and run concurrently; each run is isolated by GraphConfig.threadId.

EdgeCondition

typealias EdgeCondition<State> = suspend (State) -> String

A routing function for a conditional edge: it inspects the current state and returns the name of the node to run next, or END to finish.

EdgeConditionException

class EdgeConditionException(val from: String, cause: Throwable) : TelarException

The condition of the conditional edge from from threw an exception. The original exception is available as cause. Cancellation is handled as for NodeExecutionException.

GraphAlreadyCompletedException

class GraphAlreadyCompletedException(val threadId: String) : TelarException

CompiledGraph.resume was called for threadId, but its last run already completed. Start a new run with CompiledGraph.invoke.

GraphConfig

data class GraphConfig<State>(val threadId: String = "default", val checkpointer: Checkpointer<State>? = null, val interruptBefore: Set<String> = emptySet(), val interruptAfter: Set<String> = emptySet(), val maxIterations: Int = DEFAULT_MAX_ITERATIONS)

Per-run settings for a CompiledGraph.

GraphEdge

data class GraphEdge(val from: String, val to: String, val isConditional: Boolean = false)

A transition from from to to. Either end can be START or END.

GraphEvent

sealed interface GraphEvent<out State>

A progress event emitted by CompiledGraph.stream and CompiledGraph.streamResume.

GraphResult

sealed interface GraphResult<out State>

The outcome of CompiledGraph.invoke or CompiledGraph.resume.

GraphTopology

data class GraphTopology(val nodes: List<String>, val edges: List<GraphEdge>, val dynamicRoutes: Set<String>, val subgraphs: Map<String, GraphTopology> = emptyMap())

The structure of a compiled graph: its nodes and the edges between them. Read it from CompiledGraph.topology to draw the graph or to check it in a test.

GraphValidationException

class GraphValidationException(message: String) : TelarException

The graph definition or its run configuration is invalid: for example an edge points at an unknown node, or a fan-out has no Reducer. Thrown while building or compiling the graph, or when a run starts. The only check that waits for a node to run is the one of interrupt, which needs a checkpointer.

InvalidRouteException

class InvalidRouteException(val from: String, val target: String) : TelarException

A conditional edge from from returned target, which is not a node of the graph or not one of the edge's declared targets.

MaxIterationsExceededException

class MaxIterationsExceededException(val maxIterations: Int) : TelarException

The graph ran more steps than GraphConfig.maxIterations allows, which usually means a cycle never routes to END.

MemoryCheckpointer

class MemoryCheckpointer<State>(maxHistory: Int = Int.MAX_VALUE) : Checkpointer<State>

A Checkpointer that keeps checkpoints in memory. Intended for tests and short-lived processes. Safe to share between coroutines and threads.

MergeRuleException

class MergeRuleException(message: String) : TelarException

A reducer built with mergeRules could not merge the states of a step: a node changed a property that has no rule, or two nodes changed a property in ways its rule cannot combine. It is the cause of the ReducerException the run fails with.

MergeRules

class MergeRules<State>

The rules of a mergeRules block.

NodeAction

typealias NodeAction<State> = suspend (State) -> State

The work a node performs: a suspending function that takes the current state and returns the updated state.

NodeExecutionException

class NodeExecutionException(val nodeName: String, cause: Throwable, val attempts: Int = 1) : TelarException

A node's action threw an exception. The original exception is available as cause.

NodeRef

class NodeRef

A reference to a node added with StateGraph.node. Use it with StateGraph.then and StateGraph.conditionalEdge to connect nodes without repeating their names, and read name where a node name is needed (for example in GraphConfig.interruptBefore).

NodeTimeoutException

class NodeTimeoutException(val timeout: Duration) : TelarException

A try of a node took longer than the timeout the node was added with, and was cancelled. It is the cause of the NodeExecutionException the run fails with, and what the retryOn of a Retry gets.

Reducer

fun interface Reducer<State>

Merges the states of nodes that ran in the same step and each returned a whole state.

ReducerException

class ReducerException(val nodes: List<String>, cause: Throwable) : TelarException

The Reducer threw an exception while it merged the results of nodes, the nodes of the failed step that each returned a whole state. The original exception is available as cause. Cancellation is handled as for NodeExecutionException.

Retry

class Retry(val attempts: Int = 3, val pause: Duration = 1.seconds, val factor: Double = 2.0, val maxPause: Duration = 30.seconds, val retryOn: (Throwable) -> Boolean = { true })

Says how often a node is tried again after it failed, and how long the engine waits between two tries. Give it to a node as retry:

StateGraph

class StateGraph<State>

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

StateSerializer

interface StateSerializer<State>

Converts a graph state to and from a string so a Checkpointer can persist it.

SubgraphPosition

data class SubgraphPosition(val nextNodes: List<String>, val step: Int = 0, val interruptedBefore: Boolean = false, val subgraphs: Map<String, SubgraphPosition> = emptyMap())

Where a run stands inside a subgraph that was added with StateGraph.subgraph. It is a Checkpoint without a state: the state of a subgraph is kept in the state of the graph around it.

TelarException

abstract class TelarException(message: String, cause: Throwable? = null) : RuntimeException

Base class for every error raised by Telar itself, so callers can catch the whole family with a single catch (e: TelarException). Integration modules and custom Checkpointers may add their own subclasses.

ThreadAlreadyExistsException

class ThreadAlreadyExistsException(val threadId: String) : TelarException

CompiledGraph.fork was asked to start the thread threadId, which already has a checkpoint. A fork starts a thread of its own, so that it cannot overwrite a run. Choose another id, or delete the thread first.

Properties

END

const val END: String

Represents the final state of the graph. Execution stops when this node is reached.

START

const val START: String

Represents the starting point of the graph.

Functions

interrupt

suspend fun <State> interrupt(state: State): Nothing

Pauses the run from inside a node and saves state. Use it when a node finds out in the middle of its work that it needs a person, for example to ask a question it only knows at run time.

isProgressCollected

suspend fun isProgressCollected(): Boolean

Returns true when this code runs in a node of a run that is collected with CompiledGraph.stream or CompiledGraph.streamResume, so that what it passes to reportProgress reaches a collector. A node can use it to skip work that only produces progress.

mergeRules

fun <State> mergeRules(block: MergeRules<State>.() -> Unit): Reducer<State>

Builds a Reducer from one rule for each property that nodes of the same step may change, in place of a reducer that merges whole states by hand:

reportProgress

suspend fun reportProgress(value: Any)

Reports value from a running node to whoever collects the run: it arrives as a GraphEvent.NodeProgress in the flow of CompiledGraph.stream or CompiledGraph.streamResume, before the node's GraphEvent.NodeCompleted. Use it for what a node produces while it works, such as the text a model writes or how far a download is.

StateGraph

fun <State> StateGraph(block: StateGraph<State>.() -> Unit): StateGraph<State>

DSL entry point for building a StateGraph.

states

fun <State> Flow<GraphEvent<State>>.states(): Flow<State>

Maps a stream of events to the state after each step, which is convenient for UI code that only renders the latest state (for example collectAsState in Compose).

withCheckpoint

fun <State> List<Checkpoint<State>>.withCheckpoint(checkpoint: Checkpoint<State>, maxHistory: Int = Int.MAX_VALUE): List<Checkpoint<State>>

Returns this history of a thread after checkpoint is saved, for a Checkpointer that keeps a history: the checkpoints with an earlier step, then checkpoint, and of those the last maxHistory.