Networks

What is a network?

A network is a directed graph of nodes connected by routes. It is the primary unit of work in NodeFox - each network appears as a canvas tab where you design workflow behavior by placing nodes and drawing connections.

NodeFox graphs are intentionally not restricted to acyclic flow. Loops are supported when configured explicitly with guardrails (for example Decision Max limits, fallback routes, and quality gates). In production, looping behavior should always be bounded and observable.

Networks can be nested: a Network node inside one network can invoke a completely separate network as a sub-routine, passing data in through input variables and receiving results through output variables. This enables modular, composable design with multiple levels of nesting.

The design process

Building effective workflows follows a repeatable process. Start high-level, then work down to implementation.

1. Define the goal

Write one sentence: what does this network take in and what does it produce?

"This network takes customer support tickets, classifies them by urgency, drafts responses, and outputs a summary report."

2. Write plain steps

Describe the logic in plain English before thinking about nodes:

"Read the tickets. For each ticket, classify urgency. If urgent, draft an immediate response. Otherwise, queue for batch processing. Compile results into a report."

3. Translate to technical logic

Convert each step to operations:

"Read CSV → iterate rows → AI classification (schema output) → Decision routing → AI response generation → accumulate → AI report generation → write file."

4. Identify improvements

Look for places AI agents can optimize: quality gates (loop back if output is poor), self-correction chains, parallel processing opportunities, tool-augmented reasoning.

5. Map inputs and outputs

For each stage, define exactly what data enters and leaves. This maps directly to input/output slots. Think about data shapes — will you need schemas for structured output?

6. Identify schemas

Determine where structured output is needed. Any Conversation node whose output feeds into a Data or Decision node should have a schema to guarantee the JSON structure.

7. Create nodes

Translate each step to actual nodes: Reader for input, Conversation for AI, Data for extraction, Decision for routing, Writer for output. Choose the right variant for each.

8. Layout sections

Organize the visual graph. Group related nodes together. Use left-to-right flow for linear steps. Place parallel branches vertically. Label nodes clearly.

9. Create routes

Connect the nodes. Data routes carry data, Activation routes control execution timing. Set flags (Optional, Keep, Activated) as needed.

Common workflow patterns

Linear pipeline

The simplest pattern: data flows left to right through a sequence.

Reader → Conversation → Writer

Good for simple transformations, summaries, and single-pass processing.

Schema enrichment chain

Multiple Conversation nodes in sequence, each with its own schema. The first extracts basic information; subsequent nodes enrich with additional analysis.

Reader → Conversation (Schema A) → Data → Conversation (Schema B) → Data → Writer

Progressive enrichment produces more reliable results than asking one model to do everything at once.

Quality gate loop

A Conversation node produces output checked by a Decision node. If quality is insufficient, data loops back for another attempt. The Decision's Max setting prevents infinite loops.

Buffer → Conversation → Decision (Basic) → [pass: Writer] or [fail: back to Conversation]

Set Max to 2–3 retries. Use a schema with a quality_score field the Decision can evaluate numerically.

Parallel processing

Data fans out to multiple Conversation nodes simultaneously, each with a different system prompt or schema. Results merge downstream.

Buffer → [Conversation A, Conversation B, Conversation C] → Buffer (Combine)

Use the Combine variant of Buffer to merge results. Use blocking slots by default, and mark non-blocking inputs with Optional only where appropriate.

Iteration with Data (For)

A Reader or Conversation produces an array. A Data (For) node iterates over the array, emitting each element one at a time.

Conversation (produces array) → Data (For) → Conversation (processes each) → Buffer (Stack) → Writer

Use Buffer (Stack) to accumulate results. Use Keep flags on nodes that need to maintain context across iterations.

Human-in-the-loop approval

AI processes data, then a Decision (Options) node pauses execution and presents choices to the user.

Conversation → Decision (Options: Approve/Reject/Edit) → [Writer or Conversation or Loop]

Sub-network composition

A complex workflow is broken into reusable sub-networks invoked via Network nodes.

Reader → Network (Sub A) → Network (Sub B) → Writer

Sub-networks are independently testable — build and debug each on its own, then compose them in the parent.

API integration pipeline

Fetch from an external service, process with AI, send results back.

Reader (API: GET) → Code (transform) → Conversation → Code (format) → Writer (API: POST)

Store API keys in Settings and reference them via nodefox.apis.get() in Code nodes.

File path conventions

Reader and Writer nodes resolve paths according to these rules:

Running a network

Press ⌘+Enter or click Run in the toolbar. The network processes through its execution cycle, step by step. Press ⌘+Escape or click Stop to halt.

Watch the Logs panel (⌘+3) for real-time execution detail. Click any node during or after execution to inspect its current state and last output.

Ready-state and start conditions

If a workflow appears to "do nothing" on Run, check start conditions in this order:

1. Entry node has actual input payload.
2. Optional slots on the first executable stage are populated.
3. Activated nodes have matching activation edges.
4. Delay is not deferring the only eligible branch.
5. Slot mappings ($1 vs $2) are aligned with actual routes.

Teams often describe this as "make sure first node is Ready before start." In practice, you need at least one eligible entry path for the first cycle.

Slot mapping cheat sheet

• Canvas key 1 means slot 1.
• Canvas key 0 means bulk connect mode.
• $1 means slot 1 in templates/prompts/selectors.
• inputs.get(0) means slot 1 in Code node APIs.

Keeping this mapping explicit avoids most first-week misrouting bugs.

Common pitfalls and fixes