Skip to content

node-connectivity-reference.md

Latest commit

 

History

History
354 lines (284 loc) · 16.4 KB

node-connectivity-reference.md

File metadata and controls

354 lines (284 loc) · 16.4 KB
Raw

NextFlow Node Connectivity & Input/Output Reference

This document serves as the definitive reference guide for node connectivity in NextFlow. It details how the node execution engine processes inputs and outputs, explains the "dynamic override" system, and provides step-by-step routing examples for every node type.

🔗 How Connectivity Works (Type-Safe Routing)

NextFlow workflows are built as a directed graph where data flows from output ports on the right side of a node to input circles (ports) on the left side of another node. To prevent runtime failures and invalid configurations, NextFlow enforces type safety at the canvas level.

🔄 Data Type Compatibility Matrix

Each connection must obey the following compatibility rules. A source data type can only connect to target data types listed under its compatible targets:

Source Output Type Compatible Target Input Types Description
TEXT TEXT, ANY Raw string or message.
IMAGE_URL IMAGE_URL, ANY Absolute URL to an image asset.
VIDEO_URL VIDEO_URL, ANY Absolute URL to a video asset.
DOCUMENT_URL DOCUMENT_URL, ANY Absolute URL to an uploaded file (PDF, DOCX, TXT).
CHUNK_ARRAY CHUNK_ARRAY, ANY An array of extracted document text segments.
EMBEDDING_VECTOR EMBEDDING_VECTOR, ANY High-dimensional numerical vectors.
RETRIEVAL_RESULT RETRIEVAL_RESULT, ANY Array of matched chunks retrieved from the vector store.
RANKED_RESULT RANKED_RESULT, RETRIEVAL_RESULT, ANY Re-scored chunks sorted by semantic relevance.
LLM_RESPONSE LLM_RESPONSE, TEXT, ANY Textual output generated by a language model.
COLLECTION_REF COLLECTION_REF, ANY Database identifier referencing a vector collection.
ANY All Types Universal fallback wildcard.

Note

Connections that violate this matrix are automatically rejected by the React Flow drag-and-drop canvas.

⚙️ Fallback & Override Mechanics (Internal Fields vs. Input Circles)

Many nodes possess internal UI controls (e.g., text boxes, dropdowns, and sliders). These controls behave as Static Fallbacks, whereas the input circles behave as Dynamic Overrides:

graph TD
    A[Is Input Circle Connected?] -->|No| B[Use static value configured in the Node's UI]
    A -->|Yes| C[Ignore static UI value & use data streaming from upstream node]
Loading
  1. Unconnected Input Circle: The node falls back to the static parameters typed directly into its UI panel.
  2. Connected Input Circle: The incoming data flowing through the edge completely overrides the corresponding UI configuration at runtime.

📚 Comprehensive Node Directory

Here is the exhaustive reference for all 12 nodes, specifying their categories, input circles, output ports, fallback rules, and complete operational examples.

1. Text Node (TEXT)

  • Category: INPUT
  • Description: Outputs a static string specified in the node text area.

Ports & Inputs

  • Input Circles (Inputs): None.
  • Output Ports (Outputs):
    • text-out (Type: TEXT): The configured string.

Example Scenario

graph LR
    TextNode["Text Node (static: 'Identify key themes')"] -->|text-out| LLMNode["Run LLM (user-message-in)"]
Loading
  • Setup: Add a Text Node and type: "Explain quantum computing in one sentence."
  • Wiring: Drag a connection from the text-out port of the Text Node to the user-message-in circle of a Run LLM node.
  • Result: The string is dynamically fed to the LLM as the user prompt.

2. Upload Image Node (UPLOAD_IMAGE)

  • Category: INPUT
  • Description: Allows users to upload an image, hosting it securely via Transloadit.

Ports & Inputs

  • Input Circles (Inputs): None.
  • Output Ports (Outputs):
    • image-url-out (Type: IMAGE_URL): The public URL of the uploaded image.

Example Scenario

graph LR
    ImgUpload["Upload Image Node"] -->|image-url-out| CropImage["Crop Image (image-in)"]
Loading
  • Setup: Drag the Upload Image Node onto the canvas and upload receipt.jpg.
  • Wiring: Connect image-url-out to the image-in input circle of the Crop Image node.
  • Result: The URL of receipt.jpg is passed downstream to the cropping task.

3. Upload Video Node (UPLOAD_VIDEO)

  • Category: INPUT
  • Description: Handles secure upload of video files for frame extraction.

Ports & Inputs

  • Input Circles (Inputs): None.
  • Output Ports (Outputs):
    • video-url-out (Type: VIDEO_URL): The URL of the uploaded video file.

Example Scenario

graph LR
    VidUpload["Upload Video Node"] -->|video-url-out| FrameNode["Extract Frame (video-in)"]
Loading
  • Setup: Upload lecture_recording.mp4 inside the node upload zone.
  • Wiring: Connect video-url-out to the video-in input circle of an Extract Frame node.
  • Result: The video path is forwarded to FFmpeg for frame isolation.

4. Run LLM Node (RUN_LLM)

  • Category: AI
  • Description: Dispatches a Trigger.dev task to run structured or freeform Gemini text/multimodal inference.

Ports & Inputs

  • Input Circles (Inputs):
    • system-prompt-in (Type: TEXT, Optional): System instructions that define the model's persona.
    • user-message-in (Type: TEXT, Required): The prompt query or core question.
    • context-in (Type: TEXT, Optional, Supports multiple connections): Documents, background context, or historical data.
    • image-in (Type: IMAGE_URL, Optional, Supports multiple connections): Multimodal image inputs.
  • Output Ports (Outputs):
    • llm-response-out (Type: LLM_RESPONSE): The generated model text response.

Dynamic Overrides

  • If system-prompt-in or user-message-in are connected, they override any static values configured in the node's UI text fields.
  • Additional parameters like Temperature and Max Output Tokens are managed strictly via the node's UI sliders and cannot be overridden by ports.

Example Scenario

graph LR
    SysPrompt["Text Node (Persona)"] -->|text-out| LLM["Run LLM"]
    UserQuery["Text Node (Question)"] -->|text-out| LLM
    ImgSrc["Upload Image Node"] -->|image-url-out| LLM
    LLM -->|llm-response-out| LLMOutput["Response Output UI"]
Loading
  • Setup:
    • Text Node A (System Prompt): "You are a pirate."
    • Text Node B (User Message): "What is this photo?"
    • Upload Image Node: Upload treasure_map.png.
  • Wiring: Connect A to system-prompt-in, B to user-message-in, and the Image Node to image-in.
  • Result: Gemini evaluates the image using the pirate persona and generates a descriptive response.

5. Crop Image Node (CROP_IMAGE)

  • Category: PROCESSING
  • Description: Uses FFmpeg to crop an image to specified coordinate dimensions.

Ports & Inputs

  • Input Circles (Inputs):
    • image-in (Type: IMAGE_URL, Required): The source image.
    • crop-params-in (Type: TEXT, Optional): Dynamic coordinate parameters in JSON format, e.g., {"w": 200, "h": 200, "x": 50, "y": 50}.
  • Output Ports (Outputs):
    • image-url-out (Type: IMAGE_URL): The URL to the cropped image asset.

Dynamic Overrides

  • If crop-params-in is unconnected, the node crops based on the static values defined in the internal Width, Height, X, and Y UI text boxes.
  • Connecting a JSON string to crop-params-in overrides all static coordinates.

Example Scenario

graph LR
    SourceImg["Upload Image Node"] -->|image-url-out| CropNode["Crop Image Node"]
    Coords["Text Node ('{w: 300, h: 300, x: 0, y: 0}')"] -->|text-out| CropNode
    CropNode -->|image-url-out| LLM["Run LLM (image-in)"]
Loading
  • Setup: Connect receipt.png to image-in. Configure static UI coordinates x: 100, y: 150, width: 400, height: 250 (or wire them dynamically).
  • Wiring: Connect image-url-out to the image-in port of Run LLM for optical character recognition on the cropped segment.
  • Result: The image is cropped to the specified boundary by FFmpeg, and the result is forwarded to the LLM.

6. Extract Frame Node (EXTRACT_FRAME)

  • Category: PROCESSING
  • Description: Invokes FFmpeg to extract a single high-quality frame from a video at a designated timestamp.

Ports & Inputs

  • Input Circles (Inputs):
    • video-in (Type: VIDEO_URL, Required): The target video source.
    • timestamp-in (Type: TEXT, Optional): The timestamp (e.g. 00:02:15.500 or seconds 135.5).
  • Output Ports (Outputs):
    • image-url-out (Type: IMAGE_URL): The extracted static frame image.

Dynamic Overrides

  • The timestamp-in connection overrides the static timestamp text field in the UI.

Example Scenario

graph LR
    VidSrc["Upload Video Node"] -->|video-url-out| FrameNode["Extract Frame Node"]
    TimeSrc["Text Node ('00:00:45')"] -->|text-out| FrameNode
Loading
  • Setup: Connect video-url-out to video-in.
  • Wiring: Wire a Text node containing "00:05:00" to timestamp-in.
  • Result: The worker extracts a frame exactly 5 minutes into the video, outputting a high-res image.

7. Upload Document Node (UPLOAD_DOCUMENT)

  • Category: RAG
  • Description: Accepts document uploads (.pdf, .docx, .txt) and extracts raw text.

Ports & Inputs

  • Input Circles (Inputs): None.
  • Output Ports (Outputs):
    • doc-url-out (Type: DOCUMENT_URL): The URL of the uploaded document file.
    • raw-content-out (Type: TEXT): The full raw parsed text content extracted from the file.

Example Scenario

graph LR
    DocUpload["Upload Document Node"] -->|doc-url-out| ChunkNode["Chunk & Embed (doc-url-in)"]
Loading
  • Setup: Upload insurance_policy.pdf.
  • Wiring: Connect doc-url-out to the doc-url-in circle of a Chunk & Embed node.
  • Result: The PDF is prepared for document parsing and text chunking.

8. Chunk & Embed Node (CHUNK_EMBED)

  • Category: RAG
  • Description: Splits document text into manageable segments and generates high-dimensional embeddings using Gemini.

Ports & Inputs

  • Input Circles (Inputs):
    • doc-url-in (Type: DOCUMENT_URL, Required): The URL of the file to ingest.
    • raw-content-in (Type: TEXT, Optional): Raw string content (if you want to bypass URL parsing).
  • Output Ports (Outputs):
    • chunks-out (Type: CHUNK_ARRAY): An array of the generated text chunks.
    • embeddings-out (Type: EMBEDDING_VECTOR): An array of vectors representing the chunks.

Dynamic Overrides

  • If raw-content-in is provided, it takes priority over doc-url-in for text processing.
  • Internal fields for Chunk Size (default: 512) and Chunk Overlap (default: 64) govern the chunking algorithm.

Example Scenario

graph LR
    DocNode["Upload Document Node"] -->|doc-url-out| ChunkNode["Chunk & Embed Node"]
    ChunkNode -->|chunks-out| StoreNode["Vector Store (chunks-in)"]
    ChunkNode -->|embeddings-out| StoreNode["Vector Store (embeddings-in)"]
Loading
  • Setup: Set Chunk Size to 256 and Overlap to 32 in the UI.
  • Wiring: Connect doc-url-out to doc-url-in, and route the outputs (chunks-out and embeddings-out) to the Vector Store node.
  • Result: The document is split into 256-character passages with vectors generated for each.

9. Vector Store Node (VECTOR_STORE)

  • Category: RAG
  • Description: Upserts text chunks and high-dimensional embeddings into PostgreSQL utilizing the pgvector extension.

Ports & Inputs

  • Input Circles (Inputs):
    • chunks-in (Type: CHUNK_ARRAY, Required): The text segments to index.
    • embeddings-in (Type: EMBEDDING_VECTOR, Required): The vectors corresponding to those text segments.
  • Output Ports (Outputs):
    • collection-ref-out (Type: COLLECTION_REF): An identifier referencing the targeted database collection.

Required UI Fields

  • Collection Name: A static string in the UI defining the database index. (This name is used to isolate RAG collections between different workflows).

Example Scenario

graph LR
    ChunkNode["Chunk & Embed Node"] -->|chunks-out| Store["Vector Store (Collection: 'finance_docs')"]
    ChunkNode -->|embeddings-out| Store
    Store -->|collection-ref-out| Retrieval["Retriever (collection-ref-in)"]
Loading
  • Setup: Connect chunks-out and embeddings-out from Chunk & Embed to the respective inputs. Set the Collection Name to "user_guide_collection".
  • Wiring: Connect collection-ref-out to the collection-ref-in circle of a Retriever node.
  • Result: Document vectors are committed to the pgvector database under the "user_guide_collection" namespace.

10. Retriever Node (RETRIEVER)

  • Category: RAG
  • Description: Performs a K-nearest-neighbor semantic query search in pgvector.

Ports & Inputs

  • Input Circles (Inputs):
    • query-in (Type: TEXT, Required): The query vector search term.
    • collection-ref-in (Type: COLLECTION_REF, Required): The database collection to query.
  • Output Ports (Outputs):
    • retrieval-out (Type: RETRIEVAL_RESULT): The array of relevant chunks found.

Dynamic Overrides

  • The Top K slider in the UI determines the number of results to fetch (e.g. top 5 matches).

Example Scenario

graph LR
    SearchTerm["Text Node ('What is our PTO limit?')"] -->|text-out| RetrieverNode["Retriever Node"]
    StoreRef["Vector Store"] -->|collection-ref-out| RetrieverNode
    RetrieverNode -->|retrieval-out| Grounded["Grounded Response (context-in)"]
Loading
  • Setup: Set Top K to 4.
  • Wiring: Wire a Text node containing "How do I configure OAuth?" to query-in and the Vector Store collection to collection-ref-in.
  • Result: Searches PostgreSQL for the 4 most semantically similar text chunks related to OAuth.

11. Reranker Node (RERANKER)

  • Category: RAG
  • Description: Optimizes retrieval precision by re-evaluating retrieved chunks using an LLM relevance scoring logic.

Ports & Inputs

  • Input Circles (Inputs):
    • retrieval-in (Type: RETRIEVAL_RESULT, Required): The initial matches from the Retriever.
    • query-in (Type: TEXT, Required): The original query to evaluate chunks against.
  • Output Ports (Outputs):
    • ranked-out (Type: RANKED_RESULT): The prioritized chunks sorted by high-to-low relevance.

Example Scenario

graph LR
    RetrieverNode["Retriever"] -->|retrieval-out| RerankerNode["Reranker Node"]
    QuerySrc["Text Node"] -->|text-out| RerankerNode
    RerankerNode -->|ranked-out| Grounded["Grounded Response (ranked-context-in)"]
Loading
  • Setup: Take the search question from a Text node and connect it to query-in. Connect the output of the Retriever to retrieval-in.
  • Result: The node ranks the paragraphs, discarding low-quality noise and returning the best context blocks.

12. Grounded Response Node (GROUNDED_RESPONSE)

  • Category: AI
  • Description: Generates an answer strictly constrained to context paragraphs, preventing hallucination.

Ports & Inputs

  • Input Circles (Inputs):
    • system-prompt-in (Type: TEXT, Optional): System constraints (e.g. "Reply only in bullet points.").
    • query-in (Type: TEXT, Required): The query question to answer.
    • context-in (Type: RETRIEVAL_RESULT, Required): Chunks from the Retriever or a Reranker.
    • ranked-context-in (Type: RANKED_RESULT, Optional): Prioritized chunks from a Reranker. (If connected, the node will prioritize these over context-in).
    • image-in (Type: IMAGE_URL, Optional, Supports multiple connections): Supporting images for multimodal grounded reasoning.
  • Output Ports (Outputs):
    • llm-response-out (Type: LLM_RESPONSE): The finalized text response grounded strictly in the provided sources.

UI Settings

  • The UI allows configuring fallback prompts, temperature, and tokens.

Example Scenario

graph LR
    UserQuery["Text Node ('What is our pet policy?')"] -->|text-out| Grounded["Grounded Response"]
    RerankedContext["Reranker"] -->|ranked-out| Grounded
    Grounded -->|llm-response-out| OutputUI["Rendered Grounded Answer"]
Loading
  • Setup: Connect the original search text to query-in and the re-ranked chunks to ranked-context-in.
  • Result: The Gemini LLM synthesizes a clean, direct answer relying solely on the verified document facts, completely ignoring external knowledge.