build handle lookup table for graph root, including local handles that can override standard handles based on scope.

build Graph Root node lookup allowing nodes to link across descendents/siblings to far away elements.

@spec description(graph_node :: GenAI.Types.Graph.graph_node()) ::
  GenAI.Types.result(GenAI.Types.description(), GenAI.Types.details())

Obtain the description of a graph node.

Examples

When Set

iex> node = %GenAI.Graph.Node{description: "B"}
...> GenAI.Graph.NodeProtocol.description(node)
{:ok, "B"}

When Not Set

iex> node = %GenAI.Graph.Node{description: nil}
...> GenAI.Graph.NodeProtocol.description(node)
{:error, {:description, :is_nil}}

@spec description(
  graph_node :: GenAI.Types.Graph.graph_node(),
  default :: GenAI.Types.description()
) ::
  GenAI.Types.result(GenAI.Types.description(), GenAI.Types.details())

Obtain the description of a graph node, or return a default value if the description is nil.

Examples

When Set

iex> node = %GenAI.Graph.Node{description: "B"}
...> GenAI.Graph.NodeProtocol.description(node, "default")
{:ok, "B"}

When Not Set

iex> node = %GenAI.Graph.Node{description: nil}
...> GenAI.Graph.NodeProtocol.description(node, "default")
{:ok, "default"}

@spec handle(graph_node :: GenAI.Types.Graph.graph_node()) ::
  GenAI.Types.result(GenAI.Types.handle(), GenAI.Types.details())

Obtain the handle of a graph node.

Examples

When Set

iex> node = %GenAI.Graph.Node{handle: :foo}
...> GenAI.Graph.NodeProtocol.handle(node)
{:ok, :foo}

When Not Set

iex> node = %GenAI.Graph.Node{handle: nil}
...> GenAI.Graph.NodeProtocol.handle(node)
{:error, {:handle, :is_nil}}

@spec handle(
  graph_node :: GenAI.Types.Graph.graph_node(),
  default :: GenAI.Types.handle()
) ::
  GenAI.Types.result(GenAI.Types.handle(), GenAI.Types.details())

Obtain the handle of a graph node, or return a default value if the handle is nil.

Examples

When Set

iex> node = %GenAI.Graph.Node{handle: :foo}
...> GenAI.Graph.NodeProtocol.handle(node, :default)
{:ok, :foo}

When Not Set

iex> node = %GenAI.Graph.Node{handle: nil}
...> GenAI.Graph.NodeProtocol.handle(node, :default)
{:ok, :default}

Return full handle record not just the handle name.

@spec id(graph_node :: GenAI.Types.Graph.graph_node()) ::
  GenAI.Types.result(GenAI.Types.Graph.graph_node_id(), GenAI.Types.details())

Obtain the id of a graph node.

Examples

When Set

iex> node = %GenAI.Graph.Node{id: UUID.uuid4()}
...> GenAI.Graph.NodeProtocol.id(node)
{:ok, node.id}

When Not Set

iex> node = %GenAI.Graph.Node{id: nil}
...> GenAI.Graph.NodeProtocol.id(node)
{:error, {:id, :is_nil}}

@spec inbound_links(
  graph_node :: GenAI.Types.Graph.graph_node(),
  graph :: GenAI.Types.Graph.graph(),
  options :: map()
) :: {:ok, [GenAI.Types.Graph.graph_link_id()]} | {:error, term()}

Obtain inbound links of a graph node.

@spec name(graph_node :: GenAI.Types.Graph.graph_node()) ::
  GenAI.Types.result(GenAI.Types.name(), GenAI.Types.details())

Obtain the name of a graph node.

Examples

When Set

iex> node = %GenAI.Graph.Node{name: "A"}
...> GenAI.Graph.NodeProtocol.name(node)
{:ok, "A"}

When Not Set

iex> node = %GenAI.Graph.Node{name: nil}
...> GenAI.Graph.NodeProtocol.name(node)
{:error, {:name, :is_nil}}

@spec name(
  graph_node :: GenAI.Types.Graph.graph_node(),
  default :: GenAI.Types.name()
) ::
  GenAI.Types.result(GenAI.Types.name(), GenAI.Types.details())

Obtain the name of a graph node, or return a default value if the name is nil.

Examples

When Set

iex> node = %GenAI.Graph.Node{name: "A"}
...> GenAI.Graph.NodeProtocol.name(node, "default")
{:ok, "A"}

When Not Set

iex> node = %GenAI.Graph.Node{name: nil}
...> GenAI.Graph.NodeProtocol.name(node, "default")
{:ok, "default"}

Obtain a node nested under current node,

@spec node_type(graph_node :: GenAI.Types.Graph.graph_node()) ::
  GenAI.Types.result(GenAI.Types.Graph.graph_node_id(), GenAI.Types.details())

Obtain the node type for a graph node.

Example

iex> node = %GenAI.Graph.Node{id: UUID.uuid4()}
...> GenAI.Graph.NodeProtocol.node_type(node)
{:ok, GenAI.Graph.Node}

Obtain direct children node of current node.

@spec outbound_links(
  graph_node :: GenAI.Types.Graph.graph_node(),
  graph :: GenAI.Types.Graph.graph(),
  options :: map()
) :: {:ok, [GenAI.Types.Graph.graph_link_id()]} | {:error, term()}

Obtain outbound links of a graph node.

Process graph to execute tasks or run inference.

@spec register_link(
  graph_node :: GenAI.Types.Graph.graph_node(),
  graph :: GenAI.Types.Graph.graph(),
  link :: GenAI.Types.Graph.graph_link(),
  options :: map()
) :: GenAI.Types.result(GenAI.Types.Graph.graph_node(), GenAI.Types.details())

Register a link with the graph node.

Examples

iex> n1 = UUID.uuid5(:oid, "node-1")
...> n2 = UUID.uuid5(:oid, "node-2")
...> n = %GenAI.Graph.Node{id: n1}
...> link = GenAI.Graph.Link.new(n1, n2)
...> link_id = link.id
...> {:ok, updated} = GenAI.Graph.NodeProtocol.register_link(n, %{}, link, nil)
...> updated
%GenAI.Graph.Node{outbound_links: %{default: [^link_id]}} = updated

@spec with_id(graph_node :: GenAI.Types.Graph.graph_node()) ::
  GenAI.Types.result(GenAI.Types.Graph.graph_node(), GenAI.Types.details())

Ensure the graph node has an id, generating one if necessary.

Examples

When Already Set

iex> node = %GenAI.Graph.Node{id: UUID.uuid4()}
...> {:ok, node2} = GenAI.Graph.NodeProtocol.with_id(node)
...> %{was_nil: is_nil(node.id), is_nil: is_nil(node2.id), id_change: node.id != node2.id}
%{was_nil: false, is_nil: false, id_change: false}

When Not Set

iex> node = %GenAI.Graph.Node{id: nil}
...> {:ok, node2} = GenAI.Graph.NodeProtocol.with_id(node)
...> %{was_nil: is_nil(node.id), is_nil: is_nil(node2.id), id_change: node.id != node2.id}
%{was_nil: true, is_nil: false, id_change: true}