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
| Operation | Description |
|---|
survey(topic, count?) | Explore a topic and identify key elements — positions, factors, perspectives |
ground(claim, extract?) | Connect a claim to concrete evidence, facts, or experience |
Argument — reason and challenge
| Operation | Description |
|---|
assert(thesis, based_on?) | State a position with reasoning |
doubt(target) | Problematize a claim — find weaknesses, hidden assumptions, edge cases |
contrast(target, with?) | Find or construct the strongest opposing position or counterexample |
analogy(target, from?) | Transfer understanding from another domain to reveal hidden structure |
Synthesis — combine and transform
| Operation | Description |
|---|
synthesize(sources, method?) | Combine multiple findings into emergent insight (not just a summary) |
reframe(target, lens?) | Reformulate a problem in different terms, change the analytical lens |
Meta — reflect and steer
| Operation | Description |
|---|
assess(scale?) | Reflective pause — evaluate the current state of reasoning (open/converging/stuck) |
pivot(reason) | Explicitly change reasoning strategy when the current approach is insufficient |
scope(narrow|wide) | Control analytical zoom — from specific mechanisms to systemic connections |
Output
| Operation | Description |
|---|
conclude { ... } | Define the structure and format of the final result |
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:
- Provide the language spec and system prompt as context — together they define the full operation semantics, control flow rules, and output format
- Pass a
.zobr script as the task
- The LLM executes operations step by step, tracking variables and following control flow
- 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 automaticallyzs_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:
| Model | Composite Score | Structural Compliance | Content Quality | Generation Quality |
|---|
| Claude Opus 4.6 | 9.4 / 10 | 9.8 | 9.4 | 9.0 |
| Claude Sonnet 4.6 | 9.3 / 10 | 9.7 | 9.3 | 9.0 |
| Claude Haiku 4.5 | 7.9 / 10 | 9.3 | 7.0 | 7.5 |
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
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.
