ZS (Zobr Script)

A cognitive scripting language for structured reasoning with LLMs

ZS provides formal constructs for describing reasoning processes — not as rigid instructions, but as composable cognitive operations with variables, control flow, and result formatting.

Think of it as SQL for thinking: you define what cognitive steps to take, the LLM decides how to execute them.

Scripts are executed by an LLM as interpreter: the model reads a .zobr file, executes operations step by step, tracks variables, follows control flow, and produces structured output.

Quick Example

task: "Evaluate risks of AI in education"

risks = survey("main risks of AI in education", count: 4)
evidence = for r in risks {
  concrete = ground(r, extract: [examples, studies])
  yield { risk: r, evidence: concrete }
}
overview = synthesize(evidence, method: "rank by severity")

result = conclude {
  top_risks: list
  most_critical: string
  recommendation: string
  confidence: low | medium | high
}

12 Built-in Cognitive Operations

Operations are organized into five categories:

Discovery — explore and extract

Argument — reason and challenge

Synthesis — combine and transform

Meta — reflect and steer

Output

Plus: variables, for/if/loop control flow, user-defined functions (define), yield, import, @last/@N references.

zobr-check — Static Validator

The package includes a CLI tool for static validation of .zobr scripts:

# Install from source
git clone https://github.com/docxi-org/zobr-script.git
cd zobr-script
npm install && npm run build

# Validate a script
node dist/cli.js script.zobr

The validator checks:

• Syntax correctness (PEG grammar)
• Undefined variable references
• Correct operation signatures (positional/named argument counts)
• Unused variables (warnings)
• Reserved word misuse

How It Works

In the current version, a ZS script is executed by an LLM as interpreter:

1. Provide the language spec and system prompt as context — together they define the full operation semantics, control flow rules, and output format
2. Pass a .zobr script as the task
3. The LLM executes operations step by step, tracking variables and following control flow
4. Output is structured according to the conclude block

MCP Server

Connect ZS to Claude, Claude Desktop, or any MCP client — no installation needed.

MCP endpoint: https://zobr-script-mcp.docxi-next.workers.dev/mcp

In claude.ai: Settings → Connectors → Add custom connector → paste the URL above.

Tools provided:

• zs_execute — feed a script, get full spec + interpreter context injected automatically
• zs_validate — full PEG parser + semantic validation (same as zobr-check)
• zs_operations — quick reference for all 12 operations

Also available on Smithery.

Benchmark Results

Tested with three Claude models across 5 tasks of increasing complexity:

Key findings:

• Structure compresses the capability gap: Sonnet achieves near-parity with Opus (9.3 vs 9.4) — when reasoning structure is provided by the script, the model's job shifts from organizing thought to filling containers with content
• Even the smallest model follows scripts with 93% structural fidelity: ZS is a reasoning amplifier, not a capability test
• All models generate valid scripts: Task 05 (script generation) produced 0 syntax errors across all models

Full results: benchmark report ・ infographic ・ на русском ・ инфографика

Use Cases

• Repeatable analysis patterns — encode your best analytical workflow once as a .zobr script, apply it to any new input
• Quality assurance for AI reasoning — auditable operations with visible variable flow, not black-box responses
• Cost optimization via model routing — use smaller models for structural tasks, larger models only where depth matters
• Knowledge capture — distill exceptional AI reasoning into reusable .zobr artifacts
• Education & critical thinking — externalize the structure of rigorous thinking: survey before asserting, doubt your own claims, contrast with the strongest counter
• Multi-agent cognitive workflows — scripts as shared protocols between agents

What ZS Is Not

• Not a prompt template engine (see POML)
• Not an LLM orchestration framework (see DSPy, LangChain)
• Not chain-of-thought prompting

ZS operates at a different level: it formalizes cognitive operations themselves as first-class language constructs.

Documentation

• Language Specification v0.1
• System Prompt for LLM Interpreter
• Test Tasks
• Benchmark Report ・ на русском

Status

Spec v0.1. Benchmark complete (3 models × 5 tasks). Static validator shipped.

License

Apache License 2.0 — see LICENSE

Part of the Black Zobr ecosystem.