Files
skills/public/hip-0013.html

788 lines
44 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0013</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hip-0013.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0013">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0013.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hip-0013</h1><p class="lede">HIP-13: Workflow Execution Standard. Status Draft. Hanzo&#x27;s own standard — read this before implementing against it.</p><h1>HIP-0013: Workflow Execution Standard</h1>
<h2>Abstract</h2>
<p>This proposal defines the Workflow Execution Standard for Hanzo Flow, a visual DAG-based AI workflow builder forked from Langflow. Flow enables AI engineers to design, test, and deploy LangChain-based pipelines through a drag-and-drop canvas, then export production-ready Python or TypeScript artifacts. All workflow systems in the Hanzo ecosystem MUST implement the interfaces defined in this specification.</p>
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/flow">github.com/hanzoai/flow</a> <strong>Production</strong>: <a href="https://flow.hanzo.ai">flow.hanzo.ai</a> <strong>PyPI</strong>: <code>hanzoai-flow</code></p>
<h2>Motivation</h2>
<p>AI workflow development today suffers from three fundamental problems:</p>
<ol><li><strong>Code-only tooling excludes non-coders.</strong> LangChain is powerful but requires fluency in Python, prompt engineering patterns, and async programming. Product managers, domain experts, and junior engineers cannot participate in pipeline design.</li></ol>
<ol><li><strong>No single pane of glass.</strong> Teams use scattered notebooks, scripts, and ad-hoc APIs. There is no canonical representation of an AI pipeline that can be versioned, diffed, reviewed, and rolled back like source code.</li></ol>
<ol><li><strong>Provider lock-in.</strong> Most workflow tools call LLM providers directly. Switching models means rewriting integration code. There is no uniform abstraction for model selection, billing, and observability.</li></ol>
<ol><li><strong>No Hanzo integration.</strong> Existing tools lack first-class support for the Hanzo LLM Gateway (HIP-1), MCP tools (HIP-10), IAM authentication (HIP-26), and credit-based billing (HIP-18).</li></ol>
<ol><li><strong>Workflow vs. automation confusion.</strong> Teams conflate AI pipeline construction (prompt chains, RAG, agent loops) with business process automation (webhooks, schedules, CRM integrations). These are distinct concerns requiring distinct tools.</li></ol>
<p>Hanzo Flow solves all five by providing a visual DAG builder backed by LangChain, integrated with Hanzo infrastructure, and clearly scoped to AI pipeline construction.</p>
<h2>Specification</h2>
<pre><code class="lang-yaml">LLM:
- ChatModel # Conversational LLM (chat completions)
- CompletionModel # Text completion LLM
- ZenModelSelector # Zen model family picker (Hanzo-specific)
- ModelRouter # Route to different models based on input characteristics</code></pre>
<pre><code class="lang-yaml">Embeddings:
- OpenAIEmbeddings # Via Gateway
- HuggingFaceEmbeddings
- CohereEmbeddings # Via Gateway
- CustomEmbeddings # User-provided embedding function</code></pre>
<pre><code class="lang-yaml">VectorStores:
- Pinecone
- Weaviate
- Chroma
- pgvector # PostgreSQL with pgvector extension
- FAISS # In-memory, for prototyping
- Qdrant</code></pre>
<pre><code class="lang-yaml">Agents:
- ReActAgent # Reasoning + acting loop
- PlanAndExecute # Planning then sequential execution
- OpenAIFunctions # Function-calling agent
- HanzoAgent # Agent SDK (HIP-9) integration
- ConversationalAgent</code></pre>
<pre><code class="lang-yaml">Tools:
- MCPTool # Any Hanzo MCP tool (Hanzo-specific)
- SearchTool # Web search
- CalculatorTool
- PythonREPL # Sandboxed Python execution
- APITool # Call external APIs
- SQLTool # Query databases
- BrowserTool # Web browsing</code></pre>
<pre><code class="lang-yaml">Chains:
- LLMChain # Prompt template + LLM
- SequentialChain # Ordered chain of sub-chains
- RouterChain # Route input to different chains
- ConversationChain # Chat with memory
- RetrievalQA # RAG: retrieve then answer
- MapReduceChain # Process documents in parallel then combine
- SummarizeChain # Summarize long documents</code></pre>
<pre><code class="lang-yaml">Memory:
- ConversationBuffer # Full conversation history
- ConversationSummary # Summarized history
- ConversationWindow # Last N messages
- EntityMemory # Track entities mentioned
- VectorStoreMemory # Similarity-based recall</code></pre>
<pre><code class="lang-yaml">OutputParsers:
- JSONParser # Parse JSON from LLM output
- PydanticParser # Parse into Pydantic models
- ListParser # Parse comma/newline separated lists
- RegexParser # Extract via regex patterns
- StructuredOutputParser</code></pre>
<pre><code class="lang-yaml">IO:
- TextInput # User text input
- FileInput # Upload documents
- ChatInput # Conversational input
- TextOutput # Display text
- ChatOutput # Conversational output
- WebhookInput # Receive external triggers
- WebhookOutput # Send results externally</code></pre>
<pre><code class="lang-python"> openai_api_base=self.gateway_url,
temperature=self.temperature,
max_tokens=self.max_tokens,
)</code></pre>
<h4>MCP Tool Node</h4>
<p>Dynamically loads any of Hanzo&#x27;s 260+ MCP tools as a Flow component.</p>
<pre><code class="lang-python">class MCPToolNode(Component):
&quot;&quot;&quot;
Wraps a Hanzo MCP tool as a Flow node.
Tool schemas are loaded dynamically from the MCP registry.
&quot;&quot;&quot;
display_name = &quot;MCP Tool&quot;
inputs = [
DropdownInput(name=&quot;tool_name&quot;, display_name=&quot;Tool&quot;,
options_loader=load_mcp_tools,
info=&quot;Select from 260+ MCP tools&quot;),
DictInput(name=&quot;tool_params&quot;, display_name=&quot;Parameters&quot;,
info=&quot;Tool-specific parameters (auto-populated from schema)&quot;),
]
def build(self) -&gt; BaseTool:
schema = mcp_registry.get_schema(self.tool_name)
return MCPLangChainTool(
name=self.tool_name,
description=schema.description,
args_schema=schema.to_pydantic(),
mcp_client=self.get_mcp_client(),
)</code></pre>
<h4>Zen Model Selector</h4>
<p>Provides a rich model picker showing the Zen model family with metadata.</p>
<pre><code class="lang-python">class ZenModelSelector(Component):
&quot;&quot;&quot;
Model selector showing Zen family with parameter counts,
context windows, pricing per 1M tokens, and capability tags.
&quot;&quot;&quot;
display_name = &quot;Zen Model Selector&quot;
inputs = [
DropdownInput(name=&quot;model&quot;, display_name=&quot;Zen Model&quot;,
options=[
&quot;zen-1b | 1B params | 32K ctx | $0.10/1M&quot;,
&quot;zen-8b | 8B params | 128K ctx | $0.30/1M&quot;,
&quot;zen-72b | 72B params | 128K ctx | $1.00/1M&quot;,
&quot;zen-480b | 480B params | 256K ctx | $5.00/1M&quot;,
]),
FloatInput(name=&quot;temperature&quot;, display_name=&quot;Temperature&quot;, value=0.7),
]
def build(self) -&gt; ChatOpenAI:
model_id = self.model.split(&quot;|&quot;)[0].strip()
return ChatOpenAI(
model=model_id,
openai_api_key=self.get_iam_api_key(),
openai_api_base=&quot;https://llm.hanzo.ai&quot;,
temperature=self.temperature,
)</code></pre>
<h4>Credit Billing Hook</h4>
<p>Intercepts flow execution to meter token usage and debit credits.</p>
<pre><code class="lang-python">class CreditBillingHook(Component):
&quot;&quot;&quot;
Meters LLM token usage during flow execution and
creates billing transactions against the user&#x27;s Hanzo credit balance.
&quot;&quot;&quot;
display_name = &quot;Credit Billing&quot;
inputs = [
StrInput(name=&quot;org_id&quot;, display_name=&quot;Organization&quot;,
info=&quot;Hanzo organization to bill&quot;),
BoolInput(name=&quot;enforce_balance&quot;, display_name=&quot;Enforce Balance&quot;,
value=True, info=&quot;Reject execution if balance insufficient&quot;),
]
def build(self) -&gt; CallbackHandler:
return BillingCallbackHandler(
iam_client=self.get_iam_client(),
org_id=self.org_id,
enforce_balance=self.enforce_balance,
)</code></pre>
<h3>Flow Definition Schema</h3>
<p>A flow is a JSON document describing a directed acyclic graph of components.</p>
<pre><code class="lang-json">{
&quot;id&quot;: &quot;uuid-v4&quot;,
&quot;name&quot;: &quot;Customer Support RAG&quot;,
&quot;description&quot;: &quot;RAG pipeline for answering customer questions&quot;,
&quot;version&quot;: 3,
&quot;created_at&quot;: &quot;2025-06-15T10:30:00Z&quot;,
&quot;updated_at&quot;: &quot;2025-07-01T14:22:00Z&quot;,
&quot;created_by&quot;: &quot;user-uuid&quot;,
&quot;org_id&quot;: &quot;hanzo&quot;,
&quot;tags&quot;: [&quot;rag&quot;, &quot;support&quot;, &quot;production&quot;],
&quot;nodes&quot;: [
{
&quot;id&quot;: &quot;node-1&quot;,
&quot;type&quot;: &quot;TextInput&quot;,
&quot;position&quot;: {&quot;x&quot;: 100, &quot;y&quot;: 200},
&quot;data&quot;: {
&quot;input_value&quot;: &quot;&quot;,
&quot;display_name&quot;: &quot;User Question&quot;
}
},
{
&quot;id&quot;: &quot;node-2&quot;,
&quot;type&quot;: &quot;OpenAIEmbeddings&quot;,
&quot;position&quot;: {&quot;x&quot;: 300, &quot;y&quot;: 200},
&quot;data&quot;: {
&quot;model&quot;: &quot;text-embedding-3-small&quot;
}
},
{
&quot;id&quot;: &quot;node-3&quot;,
&quot;type&quot;: &quot;pgvector&quot;,
&quot;position&quot;: {&quot;x&quot;: 500, &quot;y&quot;: 200},
&quot;data&quot;: {
&quot;connection_string&quot;: &quot;${secrets.PG_VECTOR_URL}&quot;,
&quot;collection_name&quot;: &quot;support_docs&quot;,
&quot;search_type&quot;: &quot;similarity&quot;,
&quot;k&quot;: 5
}
},
{
&quot;id&quot;: &quot;node-4&quot;,
&quot;type&quot;: &quot;LLMGatewayNode&quot;,
&quot;position&quot;: {&quot;x&quot;: 500, &quot;y&quot;: 400},
&quot;data&quot;: {
&quot;model&quot;: &quot;zen-72b&quot;,
&quot;temperature&quot;: 0.3,
&quot;max_tokens&quot;: 2048
}
},
{
&quot;id&quot;: &quot;node-5&quot;,
&quot;type&quot;: &quot;RetrievalQA&quot;,
&quot;position&quot;: {&quot;x&quot;: 700, &quot;y&quot;: 300},
&quot;data&quot;: {
&quot;chain_type&quot;: &quot;stuff&quot;,
&quot;return_source_documents&quot;: true
}
}
],
&quot;edges&quot;: [
{&quot;source&quot;: &quot;node-1&quot;, &quot;target&quot;: &quot;node-2&quot;, &quot;sourceHandle&quot;: &quot;text&quot;, &quot;targetHandle&quot;: &quot;input&quot;},
{&quot;source&quot;: &quot;node-2&quot;, &quot;target&quot;: &quot;node-3&quot;, &quot;sourceHandle&quot;: &quot;embeddings&quot;, &quot;targetHandle&quot;: &quot;embeddings&quot;},
{&quot;source&quot;: &quot;node-1&quot;, &quot;target&quot;: &quot;node-5&quot;, &quot;sourceHandle&quot;: &quot;text&quot;, &quot;targetHandle&quot;: &quot;query&quot;},
{&quot;source&quot;: &quot;node-3&quot;, &quot;target&quot;: &quot;node-5&quot;, &quot;sourceHandle&quot;: &quot;retriever&quot;, &quot;targetHandle&quot;: &quot;retriever&quot;},
{&quot;source&quot;: &quot;node-4&quot;, &quot;target&quot;: &quot;node-5&quot;, &quot;sourceHandle&quot;: &quot;llm&quot;, &quot;targetHandle&quot;: &quot;llm&quot;}
]
}</code></pre>
<h3>DAG Execution Engine</h3>
<p>The execution engine processes flows as directed acyclic graphs.</p>
<p><strong>Topological sort.</strong> Before execution, the engine computes a topological ordering of nodes. Nodes with no incoming edges execute first. A node executes only after all its dependencies have completed.</p>
<p><strong>Parallel execution.</strong> Independent branches (nodes with no shared ancestry in the current frontier) execute concurrently. The engine uses Python&#x27;s <code>asyncio.gather</code> to run independent branches in parallel, bounded by a configurable concurrency limit.</p>
<p><strong>Streaming support.</strong> LLM nodes support streaming output via Server-Sent Events (SSE). When a flow contains a streaming-capable LLM node connected to an output node, the API returns a streaming response. Intermediate nodes buffer their output; only the final output node streams to the client.</p>
<p><strong>Error propagation.</strong> If a node fails, the engine marks all downstream nodes as <code>skipped</code> and returns a partial result containing outputs from all nodes that completed successfully, plus the error from the failed node.</p>
<pre><code class="lang-python">class DAGExecutor:
&quot;&quot;&quot;Executes a flow DAG with parallel branch support.&quot;&quot;&quot;
async def execute(self, flow: Flow, inputs: dict) -&gt; ExecutionResult:
graph = self.build_graph(flow)
order = topological_sort(graph)
levels = self.compute_levels(order, graph)
outputs = {}
for level in levels:
# All nodes in a level are independent -- execute in parallel
tasks = [
self.execute_node(node, outputs, inputs)
for node in level
]
results = await asyncio.gather(*tasks, return_exceptions=True)
for node, result in zip(level, results):
if isinstance(result, Exception):
return ExecutionResult(
status=&quot;failed&quot;,
outputs=outputs,
error={&quot;node&quot;: node.id, &quot;message&quot;: str(result)},
)
outputs[node.id] = result
return ExecutionResult(status=&quot;completed&quot;, outputs=outputs)</code></pre>
<h3>API Specification</h3>
<p>All API endpoints require OAuth2 bearer tokens from Hanzo IAM.</p>
<h4>Flow CRUD</h4>
<pre><code>GET /api/v1/flows # List flows (paginated, filterable)
POST /api/v1/flows # Create flow
GET /api/v1/flows/{flow_id} # Get flow by ID
PUT /api/v1/flows/{flow_id} # Update flow
DELETE /api/v1/flows/{flow_id} # Delete flow
GET /api/v1/flows/{flow_id}/versions # List flow versions
GET /api/v1/flows/{flow_id}/versions/{version} # Get specific version
POST /api/v1/flows/{flow_id}/rollback/{version} # Rollback to version</code></pre>
<h4>Flow Execution</h4>
<pre><code>POST /api/v1/run/{flow_id} # Execute flow (sync)
POST /api/v1/run/{flow_id}/stream # Execute flow (streaming SSE)
POST /api/v1/run/{flow_id}/async # Execute flow (async, returns job ID)
GET /api/v1/jobs/{job_id} # Poll async job status
GET /api/v1/jobs/{job_id}/result # Get async job result
DELETE /api/v1/jobs/{job_id} # Cancel async job</code></pre>
<h4>Templates</h4>
<pre><code>GET /api/v1/templates # List marketplace templates
GET /api/v1/templates/{template_id} # Get template
POST /api/v1/templates # Publish flow as template
POST /api/v1/flows/from-template/{template_id} # Create flow from template</code></pre>
<h4>Components</h4>
<pre><code>GET /api/v1/components # List available component types
GET /api/v1/components/{type} # Get component schema
GET /api/v1/components/mcp # List available MCP tools as components</code></pre>
<h4>Execution Request Format</h4>
<pre><code class="lang-json">POST /api/v1/run/{flow_id}
{
&quot;inputs&quot;: {
&quot;text_input&quot;: &quot;What is our refund policy?&quot;
},
&quot;tweaks&quot;: {
&quot;node-4&quot;: {
&quot;temperature&quot;: 0.1,
&quot;max_tokens&quot;: 1024
}
},
&quot;session_id&quot;: &quot;optional-session-for-memory&quot;
}</code></pre>
<h4>Execution Response Format</h4>
<pre><code class="lang-json">{
&quot;id&quot;: &quot;exec-uuid&quot;,
&quot;flow_id&quot;: &quot;flow-uuid&quot;,
&quot;status&quot;: &quot;completed&quot;,
&quot;duration_ms&quot;: 2340,
&quot;outputs&quot;: {
&quot;node-5&quot;: {
&quot;result&quot;: &quot;Our refund policy allows returns within 30 days...&quot;,
&quot;source_documents&quot;: [
{&quot;page_content&quot;: &quot;...&quot;, &quot;metadata&quot;: {&quot;source&quot;: &quot;refund-policy.pdf&quot;}}
]
}
},
&quot;usage&quot;: {
&quot;total_tokens&quot;: 1847,
&quot;prompt_tokens&quot;: 1203,
&quot;completion_tokens&quot;: 644,
&quot;cost_credits&quot;: 0.0018,
&quot;model&quot;: &quot;zen-72b&quot;
}
}</code></pre>
<h3>Versioning</h3>
<p>Flow definitions are versioned using an append-only snapshot model.</p>
<ul><li>Every save creates a new version. Versions are monotonically increasing integers.</li><li>Each version stores the complete flow JSON (not a diff). This simplifies rollback at the cost of storage.</li><li>The <code>GET /versions</code> endpoint returns version metadata (timestamp, author, description) without the full flow body.</li><li>Rollback creates a new version whose content matches the target version. History is never rewritten.</li><li>Diff is computed client-side by comparing two version snapshots. The UI highlights added/removed/modified nodes and edges.</li></ul>
<h3>Template Marketplace</h3>
<p>Pre-built flows for common patterns are available in the template marketplace.</p>
<p>| Template | Description | Components Used | |----------|-------------|-----------------| | <strong>RAG Chatbot</strong> | Conversational RAG with memory | TextInput, Embeddings, pgvector, RetrievalQA, ConversationBuffer | | <strong>Document Summarizer</strong> | Summarize uploaded documents | FileInput, SummarizeChain, MapReduce, TextOutput | | <strong>Code Assistant</strong> | Code generation with context | ChatInput, LLMGateway, PythonREPL, ChatOutput | | <strong>Classification Pipeline</strong> | Classify text into categories | TextInput, LLMChain, JSONParser, WebhookOutput | | <strong>Multi-Agent Research</strong> | Collaborative research agents | ChatInput, HanzoAgent, SearchTool, BrowserTool, ChatOutput | | <strong>Data Extraction</strong> | Extract structured data from text | FileInput, LLMChain, PydanticParser, APITool |</p>
<h3>Code Export</h3>
<p>Flows export to production-ready Python or TypeScript.</p>
<h4>Python Export</h4>
<pre><code class="lang-python"># Exported from Hanzo Flow: &quot;Customer Support RAG&quot;
# Version: 3 | Exported: 2025-07-01T14:30:00Z
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_community.vectorstores import PGVector
from langchain.chains import RetrievalQA
# LLM via Hanzo Gateway
llm = ChatOpenAI(
model=&quot;zen-72b&quot;,
openai_api_base=&quot;https://llm.hanzo.ai&quot;,
openai_api_key=os.environ[&quot;HANZO_API_KEY&quot;],
temperature=0.3,
max_tokens=2048,
)
# Embeddings via Hanzo Gateway
embeddings = OpenAIEmbeddings(
model=&quot;text-embedding-3-small&quot;,
openai_api_base=&quot;https://llm.hanzo.ai&quot;,
openai_api_key=os.environ[&quot;HANZO_API_KEY&quot;],
)
# Vector store
vectorstore = PGVector(
connection_string=os.environ[&quot;PG_VECTOR_URL&quot;],
collection_name=&quot;support_docs&quot;,
embedding_function=embeddings,
)
# RAG chain
chain = RetrievalQA.from_chain_type(
llm=llm,
chain_type=&quot;stuff&quot;,
retriever=vectorstore.as_retriever(search_kwargs={&quot;k&quot;: 5}),
return_source_documents=True,
)
def run(query: str) -&gt; dict:
return chain.invoke({&quot;query&quot;: query})
if __name__ == &quot;__main__&quot;:
import sys
result = run(sys.argv[1])
print(result[&quot;result&quot;])</code></pre>
<h4>TypeScript Export</h4>
<pre><code class="lang-typescript">// Exported from Hanzo Flow: &quot;Customer Support RAG&quot;
// Version: 3 | Exported: 2025-07-01T14:30:00Z
import { ChatOpenAI, OpenAIEmbeddings } from &quot;@langchain/openai&quot;;
import { PGVectorStore } from &quot;@langchain/community/vectorstores/pgvector&quot;;
import { RetrievalQAChain } from &quot;langchain/chains&quot;;
const llm = new ChatOpenAI({
modelName: &quot;zen-72b&quot;,
configuration: { baseURL: &quot;https://llm.hanzo.ai&quot; },
openAIApiKey: process.env.HANZO_API_KEY!,
temperature: 0.3,
maxTokens: 2048,
});
const embeddings = new OpenAIEmbeddings({
modelName: &quot;text-embedding-3-small&quot;,
configuration: { baseURL: &quot;https://llm.hanzo.ai&quot; },
openAIApiKey: process.env.HANZO_API_KEY!,
});
const vectorstore = await PGVectorStore.initialize(embeddings, {
postgresConnectionOptions: { connectionString: process.env.PG_VECTOR_URL! },
tableName: &quot;support_docs&quot;,
});
const chain = RetrievalQAChain.fromLLM(llm, vectorstore.asRetriever({ k: 5 }));
export async function run(query: string): Promise&lt;string&gt; {
const result = await chain.invoke({ query });
return result.text;
}</code></pre>
<h2>Implementation</h2>
<h3>Architecture</h3>
<pre><code> ┌──────────────────────────────┐
│ flow.hanzo.ai │
├───────────────┬──────────────┤
│ React + RF │ FastAPI │
│ (Canvas UI) │ (Backend) │
├───────────────┴──────────────┤
│ SQL │ KV │
│ (flows, │ (sessions, │
│ versions) │ job queue) │
└──────┬───────┴──────┬────────┘
│ │
┌──────────────┴──┐ ┌──────┴──────────┐
│ llm.hanzo.ai │ │ hanzo.id │
│ (LLM Gateway) │ │ (IAM / OAuth) │
└─────────────────┘ └─────────────────┘</code></pre>
<h3>Production Deployment</h3>
<ul><li><strong>URL</strong>: <code>flow.hanzo.ai</code></li><li><strong>Cluster</strong>: the cluster (<code>24.199.76.156</code>)</li><li><strong>Namespace</strong>: <code>hanzo</code></li><li><strong>Replicas</strong>: 2 (backend), 1 (worker pool)</li><li><strong>Resources</strong>: 2 CPU / 4Gi RAM per backend replica, 4 CPU / 8Gi RAM per worker</li></ul>
<h3>Frontend</h3>
<ul><li><strong>Framework</strong>: React 18 with TypeScript</li><li><strong>Canvas</strong>: React Flow (reactflow) for DAG visualization and editing</li><li><strong>State</strong>: Zustand for canvas state, React Query for API state</li><li><strong>Styling</strong>: Tailwind CSS with Hanzo design tokens</li><li><strong>Build</strong>: Vite, deployed as static assets behind CDN</li></ul>
<h3>Backend</h3>
<ul><li><strong>Framework</strong>: FastAPI (Python 3.11+)</li><li><strong>ORM</strong>: SQLAlchemy 2.0 with async support</li><li><strong>LangChain</strong>: langchain 0.2+, langchain-community, langchain-openai</li><li><strong>Task queue</strong>: Celery with KV broker for async flow execution</li><li><strong>Streaming</strong>: Server-Sent Events via Starlette StreamingResponse</li></ul>
<h3>Database Schema</h3>
<pre><code class="lang-sql">-- Flow definitions
CREATE TABLE flows (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
description TEXT,
org_id VARCHAR(128) NOT NULL,
created_by UUID NOT NULL,
is_public BOOLEAN DEFAULT FALSE,
tags TEXT[],
current_version INT DEFAULT 1,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- Flow version snapshots
CREATE TABLE flow_versions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
flow_id UUID REFERENCES flows(id) ON DELETE CASCADE,
version INT NOT NULL,
data JSONB NOT NULL, -- Complete flow JSON
description VARCHAR(500),
created_by UUID NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE (flow_id, version)
);
-- Execution history
CREATE TABLE flow_executions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
flow_id UUID REFERENCES flows(id),
flow_version INT NOT NULL,
status VARCHAR(20) NOT NULL, -- pending, running, completed, failed
inputs JSONB,
outputs JSONB,
error JSONB,
usage JSONB, -- token counts, cost
duration_ms INT,
session_id VARCHAR(128),
executed_by UUID NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Template marketplace
CREATE TABLE flow_templates (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
description TEXT,
category VARCHAR(64),
data JSONB NOT NULL,
author_id UUID NOT NULL,
org_id VARCHAR(128),
is_official BOOLEAN DEFAULT FALSE,
install_count INT DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_flows_org ON flows(org_id);
CREATE INDEX idx_executions_flow ON flow_executions(flow_id, created_at DESC);
CREATE INDEX idx_templates_category ON flow_templates(category);</code></pre>
<h3>Authentication</h3>
<p>All API requests require a valid OAuth2 bearer token from Hanzo IAM (<code>hanzo.id</code>).</p>
<pre><code class="lang-python">from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer
security = HTTPBearer()
async def get_current_user(token = Depends(security)):
user = await iam_client.validate_token(token.credentials)
if not user:
raise HTTPException(status_code=401, detail=&quot;Invalid token&quot;)
return user
async def check_flow_access(flow_id: str, user = Depends(get_current_user)):
flow = await get_flow(flow_id)
if flow.org_id not in user.organizations:
raise HTTPException(status_code=403, detail=&quot;Access denied&quot;)
return flow</code></pre>
<h3>Execution Workers</h3>
<p>Long-running flows execute on dedicated Celery workers to avoid blocking the API.</p>
<pre><code class="lang-python">from celery import Celery
app = Celery(&quot;flow&quot;, broker=os.environ[&quot;REDIS_URL&quot;])
@app.task(bind=True, max_retries=1, time_limit=300)
def execute_flow_task(self, flow_id: str, version: int, inputs: dict, user_id: str):
&quot;&quot;&quot;Execute a flow asynchronously on a worker.&quot;&quot;&quot;
flow = load_flow(flow_id, version)
executor = DAGExecutor(
billing_hook=CreditBillingHook(user_id=user_id),
timeout=300,
)
result = asyncio.run(executor.execute(flow, inputs))
store_execution_result(flow_id, version, inputs, result, user_id)
return result.to_dict()</code></pre>
<h2>Security</h2>
<h3>Sandboxed Code Execution</h3>
<p>Custom Python components (PythonREPL, custom nodes) execute in sandboxed environments.</p>
<ul><li><strong>Container isolation.</strong> Each code execution runs in a short-lived container with no network access (except explicitly whitelisted endpoints), no filesystem writes outside <code>/tmp</code>, and resource limits (CPU: 1 core, RAM: 512Mi, timeout: 30s).</li><li><strong>Import whitelist.</strong> Only approved Python packages are importable. The whitelist includes LangChain, NumPy, Pandas, and standard library modules. <code>os</code>, <code>subprocess</code>, <code>socket</code>, and <code>ctypes</code> are blocked.</li><li><strong>Output sanitization.</strong> All outputs from sandboxed execution are serialized to JSON and size-limited (max 1MB per node output) before returning to the DAG engine.</li></ul>
<h3>API Key Scoping</h3>
<p>Each flow can be assigned a scoped API key for external invocation.</p>
<pre><code class="lang-json">{
&quot;key_id&quot;: &quot;flow_key_xxxx&quot;,
&quot;flow_id&quot;: &quot;flow-uuid&quot;,
&quot;permissions&quot;: [&quot;execute&quot;],
&quot;rate_limit&quot;: &quot;100/hour&quot;,
&quot;ip_whitelist&quot;: [&quot;203.0.113.0/24&quot;],
&quot;expires_at&quot;: &quot;2026-01-01T00:00:00Z&quot;
}</code></pre>
<ul><li>Keys are created via <code>POST /api/v1/flows/{flow_id}/keys</code>.</li><li>Keys grant execute-only access to a single flow. They cannot read, modify, or delete the flow definition.</li><li>Keys are stored hashed (bcrypt) in SQL. The plaintext key is returned only once at creation.</li></ul>
<h3>Rate Limiting</h3>
<p>Flow execution is rate-limited at three levels:</p>
<ol><li><strong>Per-user</strong>: 100 executions per hour (configurable per plan).</li><li><strong>Per-flow</strong>: 1000 executions per hour (configurable per flow).</li><li><strong>Per-organization</strong>: 10,000 executions per hour (configurable per org).</li></ol>
<p>Rate limits are enforced in KV using sliding window counters. When a limit is exceeded, the API returns <code>429 Too Many Requests</code> with a <code>Retry-After</code> header.</p>
<h3>Audit Logging</h3>
<p>Every flow execution produces an immutable audit log entry.</p>
<pre><code class="lang-json">{
&quot;event&quot;: &quot;flow.executed&quot;,
&quot;flow_id&quot;: &quot;flow-uuid&quot;,
&quot;flow_version&quot;: 3,
&quot;user_id&quot;: &quot;user-uuid&quot;,
&quot;org_id&quot;: &quot;hanzo&quot;,
&quot;ip_address&quot;: &quot;203.0.113.42&quot;,
&quot;status&quot;: &quot;completed&quot;,
&quot;duration_ms&quot;: 2340,
&quot;tokens_used&quot;: 1847,
&quot;credits_charged&quot;: 0.0018,
&quot;timestamp&quot;: &quot;2025-07-01T14:30:00Z&quot;
}</code></pre>
<p>Audit logs are:</p>
<ul><li>Written to a dedicated <code>flow_audit_log</code> table in SQL.</li><li>Retained for 90 days (configurable per org).</li><li>Queryable via <code>GET /api/v1/audit?flow_id=...&amp;since=...&amp;until=...</code>.</li><li>Exportable in JSON Lines format for external SIEM integration.</li></ul>
<h3>Secret Management</h3>
<p>Flow definitions MUST NOT contain plaintext secrets. All secrets are referenced using <code>${secrets.KEY_NAME}</code> syntax and resolved at execution time from Hanzo KMS (HIP-27).</p>
<pre><code class="lang-json">{
&quot;type&quot;: &quot;pgvector&quot;,
&quot;data&quot;: {
&quot;connection_string&quot;: &quot;${secrets.PG_VECTOR_URL}&quot;
}
}</code></pre>
<p>The execution engine resolves secrets by calling KMS with the user&#x27;s IAM token. Secrets are injected into node configurations in memory and never persisted to the flow definition or execution logs.</p>
<h2>Interaction With Other HIPs</h2>
<p>| HIP | Relationship | |-----|--------------| | HIP-1 (LLM Gateway) | All LLM calls route through the Gateway. Flow never calls providers directly. | | HIP-9 (Agent SDK) | Flow can embed Agent SDK agents as nodes. Exported code can be deployed as Agent SDK components. | | HIP-10 (MCP) | MCP tools appear as first-class Flow nodes via dynamic schema loading. | | HIP-18 (Payments) | Credit billing hooks meter token usage and debit user balances. | | HIP-26 (IAM) | OAuth2/OIDC authentication for all API access. Organization-scoped flow ownership. | | HIP-27 (Secrets) | All secrets in flow definitions resolved from KMS at execution time. | | HIP-34 (Auto) | Auto can trigger Flow executions as steps in business process automations. Flow does not replace Auto. |</p>
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hip-0013.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div>
</body></html>