Use case
RAG & agent pipelines
A retrieval pipeline is a chain of effectful calls wrapped around pure ranking. bloccs scopes each model and database call to its own node, keeps the ranking pure and replayable, and puts the approval gate in the graph itself — so a human can stay in the loop before anything acts. Because every effect is a declared capability, you can see exactly which nodes reach the model, the vector store, or take an action.
The flow
Where this stands today
Where this stands today: retrieval over the DB effect, the routing in gate, and every outbound call are shipped in 0.8. The model calls (embed, generate) ride the generic HTTP effect for now, and gate branches on a decision in the message — a first-class model effect and a gate that suspends for live human approval are on the roadmap.
Source of truth
The manifest
The whole network is one TOML file. Drop it in, run mix bloccs.compile, and bloccs emits a
Broadway supervision tree from it — the compiler checks every edge, schema, and
declared effect first.
- Edges match ports by schema, or it won't compile.
- Effects are declared per node — nothing touches the outside world undeclared.
- Supervision and concurrency are part of the file, not an afterthought.
[network]
id = "rag"
version = "0.1.0"
runtime = "beam"
[nodes]
query = { use = "nodes/query.bloccs" }
embed = { use = "nodes/embed.bloccs" }
retrieve = { use = "nodes/retrieve.bloccs" }
rerank = { use = "nodes/rerank.bloccs" }
generate = { use = "nodes/generate.bloccs" }
gate = { use = "nodes/gate.bloccs" }
[[edges]]
from = "query.asked"
to = "embed.text"
[[edges]]
from = "embed.vector"
to = "retrieve.query"
[[edges]]
from = "retrieve.chunks"
to = "rerank.chunks"
[[edges]]
from = "rerank.ranked"
to = "generate.context"
[[edges]]
from = "generate.draft"
to = "gate.candidate"
[expose]
in = { ask = "query.asked" }
out = { act = "gate.approved", review = "gate.held" }
[supervision]
strategy = "one_for_one"
max_restarts = 10
max_seconds = 60
[deploy]
concurrency = { embed = 4, generate = 2 }
Anatomy
Node by node
Each node declares its kind and the capabilities it's allowed to use. Pure nodes touch nothing; effectful nodes carry a badge for exactly what they reach.
query
Source +HTTPTakes the user question off the wire as a typed Query@1.
embed
Transform +model roadmapCalls the embedding model. Today that's the generic HTTP effect; a first-class model capability is on the roadmap.
retrieve
Node +DBVector search over your store via the DB effect, emitting candidate Chunk@1s.
rerank
NodeReorders candidates by relevance. Pure scoring — no I/O, fully replayable in tests.
generate
Transform +model roadmapCalls the LLM with the ranked context over the HTTP effect to draft an answer.
gate
Split roadmapRoutes the draft to act or hold for review. Today it branches on a decision already in the message; suspending for a live human approval is on the roadmap.
