README
E
GraphBuildError
E
GraphRuntimeError
E
GraphValidationError
E
IdError
E
ResourceStoreError
E
RunConfigurationError
- ::entryCompiledGraph::entry
- ::get_nodeCompiledGraph::get_node
- ::get_routerCompiledGraph::get_router
- ::snapshotCompiledGraph::snapshot
T
CompiledGraphSnapshot
T
CompiledNodeSnapshot
- ::DeclaredRouteDeclaredRoute::DeclaredRoute
- ::DeclaredRouteMetadataDeclaredRouteMetadata::DeclaredRouteMetadata
- ::EventSinkEventSink::EventSink
- ::discardEventSink::discard
- ::try_emitEventSink::try_emit
- ::GraphDefinitionGraphDefinition::GraphDefinition
- ::add_nodeGraphDefinition::add_node
- ::compileGraphDefinition::compile
- ::set_entryGraphDefinition::set_entry
- ::set_routerGraphDefinition::set_router
T
GraphEvent
- ::GraphRuntimeGraphRuntime::GraphRuntime
- ::fresh_run_idGraphRuntime::fresh_run_id
- ::invokeGraphRuntime::invoke
- ::NodeNode::Node
- ::NodeCompletionNodeCompletion::NodeCompletion
- ::NodeContextNodeContext::NodeContext
- ::NodeIdNodeId::NodeId
- ::to_stringNodeId::to_string
T
NodeKind
- ::NodeMetadataNodeMetadata::NodeMetadata
- ::NodeOutputNodeOutput::NodeOutput
- ::ReducerReducer::Reducer
- ::ResourceKeyResourceKey::ResourceKey
- ::to_stringResourceKey::to_string
T
ResourceScope
- ::ResourceStoreResourceStore::ResourceStore
- ::acquire_resourceResourceStore::acquire_resource
- ::close_allResourceStore::close_all
- ::finalizeResourceStore::finalize
- ::getResourceStore::get
- ::release_nodeResourceStore::release_node
- ::removeResourceStore::remove
- ::setResourceStore::set
T
Route
T
Router
- ::RouterMetadataRouterMetadata::RouterMetadata
T
RunFailure
- ::RunIdRunId::RunId
- ::to_stringRunId::to_string
- ::RunOptionsRunOptions::RunOptions
T
RunResult
T
StoredResourceCleanup
V
resource_closed_event
V
resource_opened_event
V
resource_opening_event
V
router
V
run_completed_event
V
run_started_event

workgraph-core

Runtime-independent asynchronous graph compiler and runtime

agent

graph

runtime

moonbit

Download zip

Author

totto2727

Version

0.1.4

License

MIT

Repository

github.com/totto2727-org/workgraph

Last updated

2 months ago

Downloads

#moonbit: import: - path: moonbitlang/async@0.21.0 alias: async - path: totto2727/workgraph-core@0.1.4 alias: core backend: native

#workgraph-core

workgraph-core owns Workgraph's typed graph definitions, validation, sequential runtime, reducers, lifecycle events, identifiers, and scoped resources. For shared installation and the overall runtime flow, see the root Setup and Usage.

#Usage

Compile a graph and inspect its callback-free structure before execution:

///|
test "workgraph-core compile usage" {
  let entry = @core.NodeId::NodeId("plan")
  let definition = @core.GraphDefinition::GraphDefinition(
    @core.Reducer::Reducer(fn(state : Int, _patch : Unit) { state }),
  )
  definition.add_node(
    @core.Node::Node(
      entry,
      @core.NodeMetadata::NodeMetadata(
        name="Plan",
        description=None,
        kind=@core.Function,
        tags=[],
      ),
      async fn(_context, _state) {
        @async.pause()
        @core.NodeOutput::NodeOutput(None, None)
      },
    ),
  )
  definition.set_router(
    entry,
    @core.router([], fn(_state, _completion) { @core.End }),
  )
  definition.set_entry(entry)
  let compiled = definition.compile()
  inspect(compiled.entry().to_string(), content="plan")
  inspect(compiled.snapshot().nodes.length(), content="1")
}

The checked core example demonstrates multi-node execution, invocation-scoped resources, JSON state, and step reporting.

#API

This README was generated from the share-artifact skill and README template.

GraphBuildError

source

pub suberror GraphBuildError {
  DuplicateNode(NodeId)
  DuplicateRouter(NodeId)
  InvalidId(String)
} derive(@moonbitlang/core/debug.Debug
Debug)

GraphRuntimeError

source

pub suberror GraphRuntimeError {
  NodeTimedOut(node_id~ : NodeId, step~ : Int, timeout_ms~ : Int)
  NodeFailed(node_id~ : NodeId, step~ : Int, cause~ : Error)
  ReduceFailed(node_id~ : NodeId, step~ : Int, cause~ : Error)
  RouteFailed(node_id~ : NodeId, step~ : Int, cause~ : Error)
  RouteContractViolated(from~ : NodeId, to~ : NodeId)
  StepLimitExceeded(limit~ : Int)
  ExplicitFailure(node_id~ : NodeId, message~ : String)
  ResourceCleanupFailed(failure~ : RunFailure)
  NodeNotFound(NodeId)
  RouterNotFound(NodeId)
} derive(@moonbitlang/core/debug.Debug
Debug)

GraphValidationError

source

pub suberror GraphValidationError {
  MissingEntry
  UnknownEntry(NodeId)
  MissingRouter(NodeId)
  UnknownRouterSource(NodeId)
  UnknownDestination(from~ : NodeId, to~ : NodeId)
  UnreachableNode(NodeId)
} derive(@moonbitlang/core/debug.Debug
Debug)

IdError

source

pub suberror IdError {
  EmptyId(kind~ : String)
} derive(@moonbitlang/core/debug.Debug
Debug)

ResourceStoreError

source

pub suberror ResourceStoreError {
  NodeOwnerRequired(ResourceKey)
  InvalidCleanupTimeout(Int)
  CleanupTimedOut(Int)
  CloseFailed(errors~ : ReadOnlyArray[Error])
} derive(@moonbitlang/core/debug.Debug
Debug)

RunConfigurationError

source

pub suberror RunConfigurationError {
  MaxStepsMustBePositive(Int)
  NodeTimeoutMustBePositive(Int)
  CleanupTimeoutMustBePositive(Int)
} derive(@moonbitlang/core/debug.Debug
Debug)

CompiledGraph

source

pub struct CompiledGraph[S, P] {
  reducer : Reducer[S, P]
  nodes : @moonbitlang/core/immut/hashmap.HashMap
HashMap[NodeId, Node[S, P]]
  routers : @moonbitlang/core/immut/hashmap.HashMap
HashMap[NodeId, Router[S]]
  entry : NodeId
}

CompiledGraph::entry

source

fn[S, P] CompiledGraph::entry(self : CompiledGraph[S, P]) -> NodeId

CompiledGraph::get_node

source

fn[S, P] CompiledGraph::get_node(self : CompiledGraph[S, P], id : NodeId) -> Node[S, P] raise GraphRuntimeError

CompiledGraph::get_router

source

fn[S, P] CompiledGraph::get_router(self : CompiledGraph[S, P], id : NodeId) -> Router[S] raise GraphRuntimeError

CompiledGraph::snapshot

source

fn[S, P] CompiledGraph::snapshot(self : CompiledGraph[S, P]) -> CompiledGraphSnapshot

Returns a deterministic, callback-free snapshot for inspection and tooling.

CompiledGraphSnapshot

source

pub struct CompiledGraphSnapshot {
  entry : NodeId
  nodes : ReadOnlyArray[CompiledNodeSnapshot]
} derive(@moonbitlang/core/debug.Debug
Debug)

Contains the callback-free static structure of a compiled graph.

CompiledNodeSnapshot

source

pub struct CompiledNodeSnapshot {
  id : NodeId
  metadata : NodeMetadata
  router_metadata : RouterMetadata
  declared_routes : ReadOnlyArray[DeclaredRoute]
} derive(@moonbitlang/core/debug.Debug
Debug)

Describes one node in a compiled graph without exposing its callbacks.

DeclaredRoute

source

pub struct DeclaredRoute {
  target : NodeId
  metadata : DeclaredRouteMetadata
} derive(@moonbitlang/core/debug.Debug
Debug)

Declares one possible runtime destination and its optional metadata.

DeclaredRoute::DeclaredRoute

source

fn DeclaredRoute::DeclaredRoute(target : NodeId, metadata? : DeclaredRouteMetadata) -> DeclaredRoute

Declares a possible runtime destination.

DeclaredRouteMetadata

source

pub struct DeclaredRouteMetadata {
  label : String?
} derive(@moonbitlang/core/debug.Debug
Debug)

Contains optional display metadata for one statically declared route.

DeclaredRouteMetadata::DeclaredRouteMetadata

source

fn DeclaredRouteMetadata::DeclaredRouteMetadata(label? : String) -> DeclaredRouteMetadata

Creates display metadata for a statically declared route.

EventSink

source

pub struct EventSink {
  emit : (GraphEvent) -> Unit raise
}

EventSink::EventSink

source

fn EventSink::EventSink(emit : (GraphEvent) -> Unit raise) -> EventSink

EventSink::discard

source

fn EventSink::discard() -> EventSink

EventSink::try_emit

source

fn EventSink::try_emit(self : EventSink, event : GraphEvent) -> Unit

GraphDefinition

source

pub struct GraphDefinition[S, P] {
  reducer : Reducer[S, P]
  nodes : Map[NodeId, Node[S, P]]
  routers : Map[NodeId, Router[S]]
  entry : NodeId?
}

GraphDefinition::GraphDefinition

source

fn[S, P] GraphDefinition::GraphDefinition(reducer : Reducer[S, P]) -> GraphDefinition[S, P]

GraphDefinition::add_node

source

fn[S, P] GraphDefinition::add_node(self : GraphDefinition[S, P], node : Node[S, P]) -> Unit raise GraphBuildError

GraphDefinition::compile

source

fn[S, P] GraphDefinition::compile(self : GraphDefinition[S, P]) -> CompiledGraph[S, P] raise GraphValidationError

GraphDefinition::set_entry

source

fn[S, P] GraphDefinition::set_entry(self : GraphDefinition[S, P], entry : NodeId) -> Unit raise GraphBuildError

GraphDefinition::set_router

source

fn[S, P] GraphDefinition::set_router(self : GraphDefinition[S, P], from : NodeId, value : Router[S]) -> Unit raise GraphBuildError

GraphEvent

source

pub enum GraphEvent {
  RunStarted(RunId)
  RunCompleted(run_id~ : RunId, steps~ : Int)
  RunFailed(run_id~ : RunId, cause~ : Error)
  RunCancelled(RunId)
  NodeStarted(run_id~ : RunId, node_id~ : NodeId, step~ : Int)
  NodeCompleted(run_id~ : RunId, node_id~ : NodeId, step~ : Int, completion~ : NodeCompletion)
  NodeFailed(run_id~ : RunId, node_id~ : NodeId, step~ : Int, cause~ : Error)
  StateUpdated(run_id~ : RunId, node_id~ : NodeId, step~ : Int)
  RouteSelected(run_id~ : RunId, from~ : NodeId, route~ : Route)
  ResourceOpening(run_id~ : RunId, key~ : ResourceKey)
  ResourceOpened(run_id~ : RunId, key~ : ResourceKey)
  ResourceClosed(run_id~ : RunId, key~ : ResourceKey)
} derive(@moonbitlang/core/debug.Debug
Debug)

GraphRuntime

source

pub struct GraphRuntime[S, P] {
  graph : CompiledGraph[S, P]
  events : EventSink
  ids : @moonbitlang/core/random.Rand
Rand
}

GraphRuntime::GraphRuntime

source

fn[S, P] GraphRuntime::GraphRuntime(graph : CompiledGraph[S, P], events? : EventSink) -> GraphRuntime[S, P]

GraphRuntime::fresh_run_id

source

fn[S, P] GraphRuntime::fresh_run_id(self : GraphRuntime[S, P]) -> RunId

GraphRuntime::invoke

source

async fn[S, P] GraphRuntime::invoke(self : GraphRuntime[S, P], initial_state : S, options? : RunOptions) -> RunResult[S]

Node

source

pub struct Node[S, P] {
  id : NodeId
  metadata : NodeMetadata
  execute : async (NodeContext, S) -> NodeOutput[P]
}

Node::Node

source

fn[S, P] Node::Node(id : NodeId, metadata : NodeMetadata, execute : async (NodeContext, S) -> NodeOutput[P]) -> Node[S, P]

NodeCompletion

source

pub struct NodeCompletion {
  node_id : NodeId
  value : Json?
} derive(@moonbitlang/core/debug.Debug
Debug)

NodeCompletion::NodeCompletion

source

fn NodeCompletion::NodeCompletion(node_id : NodeId, value : Json?) -> NodeCompletion

Creates the completion value passed to a router.

NodeContext

source

pub struct NodeContext {
  run_id : RunId
  node_id : NodeId
  step : Int
  deadline_ms : Int64?
  task_group : @moonbitlang/async.TaskGroup
TaskGroup[Unit]
  events : EventSink
  resources : ResourceStore
}

NodeContext::NodeContext

source

fn NodeContext::NodeContext(run_id : RunId, node_id : NodeId, step : Int, task_group : @moonbitlang/async.TaskGroup
TaskGroup[Unit], events? : EventSink, resources? : ResourceStore, deadline_ms? : Int64) -> NodeContext

NodeId

source

pub struct NodeId {
  value : String
} derive(Eq, Hash)

impl Debug for NodeId

NodeId::NodeId

source

fn NodeId::NodeId(value : String) -> NodeId raise IdError

NodeId::to_string

source

fn NodeId::to_string(self : NodeId) -> String

NodeKind

source

pub(all) enum NodeKind {
  Function
  Llm
  CodingAgent
  Custom(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

NodeMetadata

source

pub struct NodeMetadata {
  name : String
  description : String?
  kind : NodeKind
  tags : ReadOnlyArray[String]
} derive(@moonbitlang/core/debug.Debug
Debug)

NodeMetadata::NodeMetadata

source

fn NodeMetadata::NodeMetadata(name~ : String, description~ : String?, kind~ : NodeKind, tags~ : ReadOnlyArray[String]) -> NodeMetadata

Creates metadata describing a graph node.

NodeOutput

source

pub struct NodeOutput[P] {
  patch : P?
  value : Json?
} derive(@moonbitlang/core/debug.Debug
Debug)

NodeOutput::NodeOutput

source

fn[P] NodeOutput::NodeOutput(patch : P?, value : Json?) -> NodeOutput[P]

Creates the output produced by a graph node.

Reducer

source

pub struct Reducer[S, P] {
  apply : (S, P) -> S raise
}

Reducer::Reducer

source

fn[S, P] Reducer::Reducer(apply : (S, P) -> S raise) -> Reducer[S, P]

Creates a state reducer from its transition function.

ResourceKey

source

pub struct ResourceKey {
  value : String
} derive(Eq, Hash)

impl Debug for ResourceKey

ResourceKey::ResourceKey

source

fn ResourceKey::ResourceKey(value : String) -> ResourceKey raise IdError

ResourceKey::to_string

source

fn ResourceKey::to_string(self : ResourceKey) -> String

ResourceScope

source

pub(all) enum ResourceScope {
  Node
  Run
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

ResourceStore

source

pub struct ResourceStore {
  values : @totto2727/any-collection.AnyMutableMap
AnyMutableMap[ResourceKey]
  cleanups : Array[StoredResourceCleanup]
}

ResourceStore::ResourceStore

source

fn ResourceStore::ResourceStore() -> ResourceStore

ResourceStore::acquire_resource

source

async fn[T] ResourceStore::acquire_resource(self : ResourceStore, reference : @totto2727/any-collection.AnyRef
AnyRef[ResourceKey, T], scope : ResourceScope, open : async () -> T, cleanup : async (T) -> Unit, owner? : NodeId) -> T

Acquires any typed resource and records its cleanup independently of the resource's concrete type.

ResourceStore::close_all

source

async fn ResourceStore::close_all(self : ResourceStore) -> Unit

ResourceStore::finalize

source

async fn ResourceStore::finalize(self : ResourceStore, timeout_ms : Int) -> Unit

ResourceStore::get

source

fn[T] ResourceStore::get(self : ResourceStore, reference : @totto2727/any-collection.AnyRef
AnyRef[ResourceKey, T]) -> T? raise

Returns an invocation-local value through its typed resource reference.

A missing key returns None; reusing a key with a different value type raises the conversion error from AnyRef.

ResourceStore::release_node

source

async fn ResourceStore::release_node(self : ResourceStore, node_id : NodeId) -> Unit

ResourceStore::remove

source

fn[T] ResourceStore::remove(self : ResourceStore, reference : @totto2727/any-collection.AnyRef
AnyRef[ResourceKey, T]) -> Unit

Removes the invocation-local value selected by reference.

ResourceStore::set

source

fn[T] ResourceStore::set(self : ResourceStore, reference : @totto2727/any-collection.AnyRef
AnyRef[ResourceKey, T], value : T) -> Unit

Stores an invocation-local value through a typed resource reference.

Route

source

pub(all) enum Route {
  To(NodeId)
  End
  Fail(String)
} derive(@moonbitlang/core/debug.Debug
Debug)

Router

source

pub struct Router[S] {
  metadata : RouterMetadata
  declared_routes : ReadOnlyArray[DeclaredRoute]
  evaluate : (S, NodeCompletion) -> Route raise
}

RouterMetadata

source

pub struct RouterMetadata {
  description : String?
} derive(@moonbitlang/core/debug.Debug
Debug)

Contains optional display metadata for a router.

RouterMetadata::RouterMetadata

source

fn RouterMetadata::RouterMetadata(description? : String) -> RouterMetadata

Creates display metadata for a router.

RunFailure

source

pub struct RunFailure {
  primary : Error
  cleanup : ReadOnlyArray[Error]
} derive(@moonbitlang/core/debug.Debug
Debug)

RunId

source

pub struct RunId {
  value : String
} derive(Eq, Hash)

impl Debug for RunId

RunId::RunId

source

fn RunId::RunId(value : String) -> RunId raise IdError

RunId::to_string

source

fn RunId::to_string(self : RunId) -> String

RunOptions

source

pub struct RunOptions {
  max_steps : Int
  node_timeout_ms : Int?
  cleanup_timeout_ms : Int
} derive(@moonbitlang/core/debug.Debug
Debug)

RunOptions::RunOptions

source

fn RunOptions::RunOptions(max_steps? : Int, node_timeout_ms? : Int, cleanup_timeout_ms? : Int) -> RunOptions raise RunConfigurationError

RunResult

source

pub struct RunResult[S] {
  run_id : RunId
  final_state : S
  steps : Int
} derive(@moonbitlang/core/debug.Debug
Debug)

StoredResourceCleanup

source

type StoredResourceCleanup

resource_closed_event

source

fn resource_closed_event(run_id : RunId, key : ResourceKey) -> GraphEvent

Creates the event emitted after a runtime resource is closed.

resource_opened_event

source

fn resource_opened_event(run_id : RunId, key : ResourceKey) -> GraphEvent

Creates the event emitted after a runtime resource is opened.

resource_opening_event

source

fn resource_opening_event(run_id : RunId, key : ResourceKey) -> GraphEvent

Creates the event emitted before a runtime resource is opened.

router

source

fn[S] router(declared_routes : ReadOnlyArray[DeclaredRoute], evaluate : (S, NodeCompletion) -> Route raise, metadata? : RouterMetadata) -> Router[S]

run_completed_event

source

fn run_completed_event(run_id : RunId, steps : Int) -> GraphEvent

Creates the event emitted when a run completes.

run_started_event

source

fn run_started_event(run_id : RunId) -> GraphEvent

Creates the event emitted when a run starts.

Source Files

Site source Report issue Packages Build queue Skills Statistics

workgraph-core

#moonbit: import: - path: moonbitlang/async@0.21.0 alias: async - path: totto2727/workgraph-core@0.1.4 alias: core backend: native

#workgraph-core

#Usage

#API

#GraphBuildError

#GraphRuntimeError

#GraphValidationError

#IdError

#ResourceStoreError

#RunConfigurationError

#CompiledGraph

#CompiledGraph::entry

#CompiledGraph::get_node

#CompiledGraph::get_router

#CompiledGraph::snapshot

#CompiledGraphSnapshot

#CompiledNodeSnapshot

#DeclaredRoute

#DeclaredRoute::DeclaredRoute

#DeclaredRouteMetadata

#DeclaredRouteMetadata::DeclaredRouteMetadata

#EventSink

#EventSink::EventSink

#EventSink::discard

#EventSink::try_emit

#GraphDefinition

#GraphDefinition::GraphDefinition

#GraphDefinition::add_node

#GraphDefinition::compile

#GraphDefinition::set_entry

#GraphDefinition::set_router

#GraphEvent

#GraphRuntime

#GraphRuntime::GraphRuntime

#GraphRuntime::fresh_run_id

#GraphRuntime::invoke

#Node

#Node::Node

#NodeCompletion

#NodeCompletion::NodeCompletion

#NodeContext

#NodeContext::NodeContext

#NodeId

#NodeId::NodeId

#NodeId::to_string

#NodeKind

#NodeMetadata

#NodeMetadata::NodeMetadata

#NodeOutput

#NodeOutput::NodeOutput

#Reducer

#Reducer::Reducer

#ResourceKey

#ResourceKey::ResourceKey

#ResourceKey::to_string

#ResourceScope

#ResourceStore

#ResourceStore::ResourceStore

#ResourceStore::acquire_resource

#ResourceStore::close_all

#ResourceStore::finalize

#ResourceStore::get

#ResourceStore::release_node

#ResourceStore::remove

#ResourceStore::set

#Route

#Router

#RouterMetadata

#RouterMetadata::RouterMetadata

#RunFailure

#RunId

#RunId::RunId

#RunId::to_string

#RunOptions

#RunOptions::RunOptions

#RunResult

#StoredResourceCleanup

#resource_closed_event

#resource_opened_event

GraphBuildError

GraphRuntimeError

GraphValidationError

IdError

ResourceStoreError

RunConfigurationError

CompiledGraph

CompiledGraph::entry

CompiledGraph::get_node

CompiledGraph::get_router

CompiledGraph::snapshot

CompiledGraphSnapshot

CompiledNodeSnapshot

DeclaredRoute

DeclaredRoute::DeclaredRoute

DeclaredRouteMetadata

DeclaredRouteMetadata::DeclaredRouteMetadata

EventSink

EventSink::EventSink

EventSink::discard

EventSink::try_emit

GraphDefinition

GraphDefinition::GraphDefinition

GraphDefinition::add_node

GraphDefinition::compile

GraphDefinition::set_entry

GraphDefinition::set_router

GraphEvent

GraphRuntime

GraphRuntime::GraphRuntime

GraphRuntime::fresh_run_id

GraphRuntime::invoke

Node

Node::Node

NodeCompletion

NodeCompletion::NodeCompletion

NodeContext

NodeContext::NodeContext

NodeId

NodeId::NodeId

NodeId::to_string

NodeKind

NodeMetadata

NodeMetadata::NodeMetadata

NodeOutput

NodeOutput::NodeOutput

Reducer

Reducer::Reducer

ResourceKey

ResourceKey::ResourceKey

ResourceKey::to_string

ResourceScope

ResourceStore

ResourceStore::ResourceStore

ResourceStore::acquire_resource

ResourceStore::close_all

ResourceStore::finalize

ResourceStore::get

ResourceStore::release_node

ResourceStore::remove

ResourceStore::set

Route

Router

RouterMetadata

RouterMetadata::RouterMetadata

RunFailure

RunId

RunId::RunId

RunId::to_string

RunOptions

RunOptions::RunOptions

RunResult

StoredResourceCleanup

resource_closed_event

resource_opened_event

resource_opening_event

router

run_completed_event

run_started_event