Structure And Declarations

Last validated: 2026-05-14

This page defines top-level Scriptum file layout and declaration syntax.

Canonical File Order

Current parser order is:

1. Leading annotations (-- @...) before script
2. script "Name"
3. Optional free-text description lines
4. Optional version
5. Zero or more enum declarations
6. Optional input
7. Optional output
8. Optional stream
9. Optional import tools (or legacy tools)
10. Optional env
11. Optional legacy secrets block
12. Step body (do, each, decide, etc.)

Recommended skeleton:

-- @accepts_content_type image/*, application/pdf
-- @accepts_extension .png, .jpg, pdf

script "My Workflow"
  Optional human-readable description line.
  Additional description lines are allowed.

version "0.1.0"

enum Mode = Fast | Balanced | Thorough

input
  topic : text

output
  result : object

stream
  phase : text
  payload : object

import tools
  * from native
  web_search from mcp("search-server")

env
  LLM_API_KEY from "LLM_API_KEY"
  LLM_MODEL = "gpt-4o"

### Main Flow ###

emit "Init"
  phase = "start"

Script Header And Description

script "Detect MIME"
version "0.1.0"

version accepts quoted or bare numeric forms:

version "0.1.0"
version 0.1.0

Description lines can appear directly after script and before declaration keywords.

script "My Script"
  This line becomes script description.
  Additional lines are concatenated.
version "0.1.0"

Comments And Annotations

Line comments use --.

-- plain comment

Before script, the compiler recognizes:

• @accepts_content_type
• @accepts_extension

Example:

-- @accepts_content_type image/*, video/*
-- @accepts_extension .png, .jpg, mp4
script "Media Pipeline"

Section separators use ### and are parsed as section markers:

### Data Preparation ###

Input, Output, Stream Blocks

input, output, and stream are declaration blocks with typed fields.

input
  id : text
  top_k : number range(1, 1000) = 10

output
  status : text
  records : list<object>

stream
  item_id : text
  score : number

Use stream when your script emits intermediate values via yield.

Tool Imports

Preferred syntax:

import tools
  echo from native
  web_search from mcp("search-server")
  image_chunk from ignite("public")

Also supported:

tools
  echo from native

Supported source clauses after from:

• native
• ignite
• ignite("org-name")
• mcp("server-name")

If from ... is omitted, source is auto resolution.

Aliases are supported with as:

import tools
  vector_store_search as vbase_search

Wildcard import is supported:

import tools
  * from native

Env Block

env defines required/optional environment variables.

env
  LLM_API_KEY from "LLM_API_KEY"
  LLM_MODEL = "gpt-4o"
  EMBED_DIM : integer min(1) = 1024

Rules:

• NAME alone means required with no default.
• from "SOURCE_KEY" maps script name to stored key.
• = value provides default and marks variable non-required.
• Optional type and constraints are allowed after :.

Legacy secrets Block

The parser still accepts a top-level secrets block for backward compatibility, but current structured env handling should use env.

Indentation Rules

Scriptum structure is indentation-sensitive.

• Child step bodies must be indented deeper than parent step.
• decide branch labels must align to one branch column level.
• together lane grouping uses blank lines between lane groups.

Use consistent spaces for readability and stable parse behavior.

Unsupported Legacy Syntax To Avoid

Do not rely on script-file imports like:

import "lib/setup.scriptum" as setup

Current parser supports tool imports (import tools) and run-target identifiers (run some_identifier), not direct script file imports.