Metadata-Version: 2.4
Name: verbai
Version: 0.1.0
Summary: A Haskell-flavored DSL for AI model orchestration.
Author-email: Gerald Enrique Nelson Mc Kenzie <lordxmen2k@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/lordxmen2k/verbai
Project-URL: Repository, https://github.com/lordxmen2k/verbai
Keywords: dsl,ai,llm,orchestration,haskell
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ollama
Provides-Extra: openai
Provides-Extra: anthropic
Provides-Extra: cloud
Provides-Extra: local
Provides-Extra: all
Dynamic: license-file

# 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`](https://github.com/lordxmen2k/verbai/blob/main/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

```bash
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:

```verbai
-- hello.verbai
Print "hello, world"
```

A recursive factorial:

```verbai
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:

```verbai
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

```bash
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`

```verbai
Print "hello, world"
```

Run it:

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

### 02 `02_constants.verbai`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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)*

```verbai
-- 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:

```bash
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

```bash
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](LICENSE).
