ModelWorks Fundamentals

In this section, we introduce the core building blocks of ModelWorks circuits. You will learn how to define a circuit, structure its inputs and steps, use adapters, and handle outputs. By the end of this guide, you'll be able to create and run your first circuit.

Circuit Structure

A circuit is defined in a declarative JSON or YAML format and consists of the following primary sections:

name & description: Human-readable identifiers.
document_type & engine_version: Metadata for platform validation.
pricing: Pricing entries (flat or token-based) used to bill each execution.
secrets: Secrets (e.g., API keys) referenced by steps via ${{ secrets.* }}.
inputs: Parameters passed into the circuit at runtime.
steps: Ordered list of operations (fetching data, embedding, etc.).
adapters: Connectors for streaming, push, or custom protocols.
outputs: Exposed results of your circuit logic.

Below is a minimal example illustrating name, description, and steps:

JSON

{
  "name": "hello_world",
  "description": "A simple demo circuit",
  "document_type": "circuit",
  "engine_version": "1.0",
  "pricing": [{ "type": "FLAT", "cost": 1 }],
  "inputs": [
    { "name": "url", "description": "Endpoint to fetch", "value": "${{ input.url }}", "type": "string", "required": true }
  ],
  "steps": [
    {
      "name": "fetch_message",
      "function": "circuit.core.fetch",
      "input": { "url": "${{ input.url }}", "method": "GET" }
    }
  ],
  "adapters": [{ "type": "MODELWORKS_SSE" }],
  "outputs": [
    { "name": "response", "description": "Fetched response body", "value": "${{ fetch_message.output.json_body }}" }
  ]
}

Inputs and Validation

Inputs allow circuits to accept dynamic parameters:

name: Identifier
description: Purpose
value: Expression or ${{ input.foo }}
type: string, number, array, object, boolean
required: Enforce presence
default_value: Fallback if omitted

JSON

"inputs": [
  {
    "name": "messages",
    "description": "Conversation history",
    "value": "${{ input.messages }}",
    "type": "array",
    "required": true
  }
]

Steps and Operations

Each step is an atomic operation:

name: Unique within the circuit
function: Built-in or custom (e.g., circuit.core.fetch, circuit.core.embed)
input: Configuration for that step
description (optional): Documentation

Sample Step: OpenAI Embed

JSON

{
  "name": "openai_query_extend",
  "function": "circuit.core.embed",
  "input": {
    "query": {
      "context": { "version": "01e03926..." },
      "input": { "messages": "${{ messages }}" }
    }
  }
}

Adapters

Adapters let you stream or push results to external clients:

JSON

"adapters": [
  { "type": "OPEN_AI_SSE" },
  { "type": "MODELWORKS_SSE" }
]

Use adapters to integrate chat UIs, dashboards, or third-party event systems.

Outputs

Define which variables become circuit results:

JSON

"outputs": [
  {
    "name": "chat_completion_output",
    "description": "Generated text stream",
    "value": "${{ chat_completion_response.output.stream_accumulators.delta_accumulator }}"
  }
]

Example Circuits

Runway Gen-3 Video Generation

JSON

{
  "name": "runway_gen_3_video_generation",
  "description": "Runway Gen-3 Video Generation Service",
  "pricing": [{ "type": "FLAT", "cost": 20 }],
  "secrets": [
    { "key": "api_key", "description": "Runway API key used for the Authorization Bearer header" }
  ],
  "inputs": [
    { "name": "promptText", "type": "string", "required": true },
    { "name": "duration", "type": "number", "default_value": 10 }
  ],
  "steps": [
    { "name": "runway_video_generation", "function": "circuit.core.fetch", "input": { /* ... */ } },
    { "name": "runway_job_watch", "function": "circuit.core.http_watch", "input": { /* ... */ } }
  ],
  "adapters": [{ "type": "MODELWORKS_SSE" }],
  "outputs": [ { "name": "video_url", "description": "URL of the generated video", "value": "${{ runway_video_url }}" } ]
}

Open-Meteo Weather Fetch

JSON

{
  "name": "Current Weather Data",
  "description": "Fetches current weather observations from Open-Meteo",
  "pricing": [{ "type": "FLAT", "cost": 1 }],
  "inputs": [
    { "name": "latitude", "type": "number", "required": true },
    { "name": "longitude", "type": "number", "required": true }
  ],
  "steps": [
    { "name": "fetch_weather_data", "function": "circuit.core.fetch", "input": { "url": "https://api.open-meteo.com/v1/forecast?latitude=${{ latitude }}&longitude=${{ longitude }}&current=temperature_2m", "method": "GET" } }
  ],
  "adapters": [{ "type": "MODELWORKS_SSE" }],
  "outputs": [ { "name": "weather_data", "description": "Current weather observations", "value": "${{ fetch_weather_data.output.json_body }}" } ]
}

Next Steps

Try it Out: Copy one of the example circuits into your workspace.
Run: Execute on-demand or schedule via triggers.
Extend: Add adapters or custom steps to fit your use case.
Automate: Integrate with event sources (webhooks, queues).

Up next: Namespaces & Scheduling!

Fundamentals

On this page