A typed declarative IR for Agentic Computation Graphs (ACGs) that compiles to a Broadway supervision tree on the BEAM.
See Bloccs.Manifest.Node, Bloccs.Manifest.Network, Bloccs.Parser,
Bloccs.Validator, and Bloccs.Compiler for the v0.1 surface.
Request/response
A network is otherwise fire-and-forget: a message goes in and side effects come
out, but the caller gets nothing back. call/4 and cast/4 add request/response
on top — without making the pipeline synchronous — by correlating a reply
back to the caller via the message trace_id (Bloccs.Lineage, Bloccs.Collector).
To use them, a terminal node must be declared reply = true in its manifest and
emit the response on an out-port:
[node]
id = "price"
kind = "transform"
reply = trueThen:
{:ok, %{"total" => 42}} = Bloccs.call(:checkout, :request, %{"items" => [...]})call/4 blocks until that node reports (or the timeout fires); cast/4 returns
the trace_id immediately and, with send_result: true, later messages the
caller {:bloccs_reply, trace_id, result}. Both target an exposed input port
([expose].in in the network manifest). See Bloccs.Collector for limitations
(first-wins aggregation; correlation does not survive a [batch]/[join]).
Summary
Functions
Push payload into the exposed input port in_port of running network
network_id and block until a reply = true node responds.
Push payload into the exposed input port in_port of running network
network_id and return immediately with {:ok, trace_id} — the correlation id
for the request.
Returns the current bloccs library version.
Types
@type network_id() :: atom()
Functions
@spec call(network_id(), atom(), term(), keyword()) :: {:ok, term()} | {:error, Bloccs.EffectError.t() | term()}
Push payload into the exposed input port in_port of running network
network_id and block until a reply = true node responds.
Returns {:ok, reply_payload} on success, or {:error, reason} where reason
is one of:
%Bloccs.EffectError{}— a node on the request's trace failed terminally (bad inbound schema, the node raised / returned{:error, _}/ timed out, or downstream delivery failed). The struct names the node and phase.:timeout— no reply and no error within:timeoutms (default5_000), e.g. the request was filtered/dropped before reaching the reply node.:no_producer|:unknown_network|{:unknown_port, in_port}— the request could not be admitted.
The network keeps running asynchronously; only the calling process waits.
@spec cast(network_id(), atom(), term(), keyword()) :: {:ok, Bloccs.Lineage.id()} | {:error, term()}
Push payload into the exposed input port in_port of running network
network_id and return immediately with {:ok, trace_id} — the correlation id
for the request.
With send_result: true, the calling process is later sent
{:bloccs_reply, trace_id, result} where result is {:ok, payload},
{:error, %Bloccs.EffectError{}}, or {:error, :timeout} (after :timeout ms,
default 5_000). Without it, the request is fire-and-forget and the returned
trace_id is useful only for correlating telemetry / traces.
@spec version() :: String.t()
Returns the current bloccs library version.
Examples
iex> is_binary(Bloccs.version())
true