verbai

Visibly Enhanced Reasoning Blocks for AI. A Haskell-flavored DSL for AI model orchestration.

verbai is a scripting language and PyPI package for composing and orchestrating AI model calls — local and cloud, text and multi-modal. It is text-based, has a hybrid syntax (declarative tasks + procedural body), and treats every integration as a pluggable provider: Ollama, OpenAI, Anthropic, Gemini, Mistral, xAI, DeepSeek, Cohere, HuggingFace, OpenRouter, AWS Bedrock, Azure OpenAI, Vertex AI, Groq, Together.ai, Fireworks.ai, Replicate, MiniMax, MCP servers, HTTP APIs, webhooks, WebSockets, and more.

Status

🚧 Pre-alpha. v0.1 is being built. The full language design spec is at docs/specs/2026-10-01-verbai-language-design.md. The language core, parser, interpreter, stdlib, and 14 example programs that you can run cold-start all ship in the package.

Quickstart

pip install verbai
verbai run examples/01_hello.verbai

You should see:

hello, world

The examples/ directory comes bundled inside the wheel, so pip install verbai is enough — no extra git clone needed.

A taste of verbai

The smallest possible script:

-- hello.verbai
Print "hello, world"

A recursive factorial:

let factorial n =
    if n <= 1 then
        1
    else
        n * (factorial (n - 1))
    end

Print (factorial 10)

A real model call against MiniMax's hosted M3:

do
    reply <- Run { provider = "minimax" ; model = "MiniMax-M3" ; input = "Say hi in 5 words or fewer." }
    Print reply
end

CLI

verbai --version                 # print version
verbai run <file.verbai>         # execute a script
verbai check <file.verbai>       # parse + structurally check, no execution
verbai fmt <file.verbai>         # format to stdout
verbai fmt <file.verbai> --write # rewrite the file in place

Exit codes: 0 success, 1 runtime error or missing file, 2 parse error.

Installation

pip install verbai                # base (Mock provider only)
pip install verbai[cloud]         # + MiniMax (more providers in v0.2)
pip install verbai[local]         # + every local runtime (v0.2)
pip install verbai[all]           # everything

The provider ABC + registry are stable, so adding a new provider is a single register_provider(MyProvider()) call.

---

The example programs

All 14 example scripts ship inside the installed examples/ directory. Each one is self-contained — copy-paste the body into a .verbai file on your machine and run it.

01 01_hello.verbai

Print "hello, world"

Run it:

$ verbai run examples/01_hello.verbai
hello, world

02 02_constants.verbai

let PI = 3.14
let NAME = "verbai"
let MAX_TOKENS = 4096
Print PI
Print NAME
Print MAX_TOKENS

$ verbai run examples/02_constants.verbai
3.14
verbai
4096

03 03_variables.verbai

-- 03_variables.verbai
-- `let` at module scope is an immutable binding.
-- Inside a `do` block, `<-` shadows with a local value.

let global = 100

do
    local <- 50
    Print (global + local)
    Print local
end

Print global

$ verbai run examples/03_variables.verbai
150
50
100

04 04_expressions.verbai

-- 04_expressions.verbai
Print (1 + 2 * 3)
Print ((1 + 2) * 3)
Print (10 - 4)
Print (10 / 3)
Print ("Hello, " + "world!")
Print (5 == 5)
Print (5 < 10)

$ verbai run examples/04_expressions.verbai
7
9
6
3.3333333333333335
Hello, world!
True
True

Important: verbai calls are explicit-paren'd. Print (10 - 4) is unambiguous; Print 10 - 4 parses as Print(10) - 4 and fails at runtime. Wrap binary expressions in parens.

05 05_types.verbai

-- 05_types.verbai
-- Primitive types and how they print.

Print 42                                  -- Int
Print 3.14                                -- Float
Print "hello"                             -- Text
Print True                                -- Bool
Print False                               -- Bool
Print nil                                 -- Nil
Print ([1, 2, 3])                         -- List of Int
Print ({ name = "verbai" ; version = 0 }) -- Object

$ verbai run examples/05_types.verbai
42
3.14
hello
True
False
Nil
[1, 2, 3]
{name = verbai, version = 0}

Object literals use semicolon between entries; commas are for lists. To pass a list or object as a single argument, wrap it in parens.

06 06_conditionals.verbai

-- 06_conditionals.verbai
let x = 5
if x > 0 then
    Print "positive"
else
    Print "non-positive"
end

let y = -3
if y > 0 then
    Print "positive"
else
    Print "non-positive"
end

$ verbai run examples/06_conditionals.verbai
positive
non-positive

07 07_loops.verbai

-- 07_loops.verbai
ForEach [1, 2, 3, 4, 5] (x -> Print x)

$ verbai run examples/07_loops.verbai
1
2
3
4
5

08 08_functions.verbai

-- 08_functions.verbai
let double x = x * 2
let add3 a b c = a + b + c

Print (double 21)
Print (add3 1 2 3)

$ verbai run examples/08_functions.verbai
42
6

09 09_recursion.verbai

-- 09_recursion.verbai
let factorial n =
    if n <= 1 then
        1
    else
        n * (factorial (n - 1))
    end

Print (factorial 5)
Print (factorial 10)

$ verbai run examples/09_recursion.verbai
120
3628800

10 10_lists.verbai

-- 10_lists.verbai
let xs = [10, 20, 30, 40]
Print xs
Print (xs[0])
Print (xs[2])

ForEach xs (x -> Print (x * 2))

$ verbai run examples/10_lists.verbai
[10, 20, 30, 40]
10
30
20
40
60
80

11 11_objects.verbai

-- 11_objects.verbai
let config = { host = "api.example.com" ; port = 443 ; retries = 3 }
Print config.host
Print config.port

do
    msg <- Run { provider = "mock" ; model = "echo" ; input = "ping" }
    Print msg
end

$ verbai run examples/11_objects.verbai
api.example.com
443
echo: 'ping'

12 12_errors.verbai

-- 12_errors.verbai
do
    out <- try
        do
            x <- Run { provider = "mock" ; model = "fail-once" ; input = "boom" }
            Print x
        end
    catch err ->
        Print "recovered from error"
    end
    Print out
end

do
    msg <- Run { provider = "mock" ; model = "echo" ; input = "hello" }
    Print msg
end

$ verbai run examples/12_errors.verbai
fail-once: 'boom'
Nil
echo: 'hello'

The try ... catch err -> ... end form binds the error to err and runs the catch body. Use _ instead of err if you don't need the error value. The err binding also works as a kind filter (catch DivisionByZeroError -> ...).

13 13_first_inference.verbai

-- 13_first_inference.verbai
do
    result <- Run { provider = "mock" ; model = "echo" ; input = "hi" }
    Print result
end

$ verbai run examples/13_first_inference.verbai
echo: 'hi'

14 14_minimax_pong.verbai (requires real API key)

-- 14_minimax_pong.verbai
do
    reply <- Run { provider = "minimax" ; model = "MiniMax-M3" ; input = "Reply with exactly one short sentence." }
    Print reply
end

This one hits the real network:

export MINIMAX_API_KEY=sk-cp-...
verbai run examples/14_minimax_pong.verbai
unset MINIMAX_API_KEY          # unset when you're done

Disable the API key on your provider dashboard as soon as you're done testing. The MiniMax provider reads MINIMAX_API_KEY from your environment; verbai never stores it.

---

Running the tests

pip install -e ".[dev]"
pytest                          # 169 passing (real-API examples skipped)
pytest --cov=verbai --cov-fail-under=85   # coverage gate (≥ 85 %)
pytest -m real_api              # opt-in: runs example 14 against a real MiniMax endpoint

Design philosophy

verbai is an octopus with tentacles: a small, tight language core that reaches out to anything reachable from the runtime. The core handles language semantics, multi-modal types, error recovery, and capability checks; the tentacles are integrations — AI providers, MCP servers, HTTP APIs, webhooks, WebSockets, local processes, databases, env vars, and the file system. Every tentacle is implemented as a stdlib verb or a first-party provider; everything composes with everything else, in any order, in one script.

What's next

• v0.2: examples 15–31 from the spec curriculum (multi-modal, MCP, HTTP, webhooks, more providers).
• v0.2: formal type checker (capability checks stay as the v0.1 substitute).
• v0.3: LSP server, syntax highlighting, REPL.

License

Apache 2.0. See LICENSE.