Ecko

The language where ai is a keyword, not an import.

Ecko is a programming language for the AI era - built in Rust, designed for human-AI collaboration. It pairs expression-oriented syntax with first-class LLM primitives, pattern matching, pipelines, contracts, and share-nothing concurrency, all in one static binary.

# Call an LLM directly - no imports, no setup
result = ai "What is the capital of France?"
print(result)

# Typed output maps straight to your types
count = ai[Int] "Count the words in this text"
print(count)

# Pipe data through LLM calls
text = "Meet me on 12 March and again on 4 April."
dates = text |> ai "Extract all dates" |> ai "Format as ISO 8601"
print(dates)

Every ai call above runs offline in deterministic mock mode with no API key - so the whole program is runnable and testable before you configure a single provider.

It just works - one step, zero config, offline. Installing drops in a single binary with nothing to configure. Running is just ecko file.ecko - no project to set up, no package.json, no Cargo.toml. A file is a program. Without an API key, everything still runs in mock mode: typed calls return schema-valid values (ai[Int] -> 42), so your pipelines, contracts, and tool calls all keep working. The standard library is already there - import std.http gives you an HTTP server, import std.sql gives you SQLite - with no apt install, no pip install, no cargo add.

Quick start

Install Ecko - one command, a single binary, nothing to configure:

curl -fsSL https://ecko.sh/install | sh

The installer picks the right build for your machine, checks its checksum, and puts ecko on your PATH. Prebuilt binaries ship for:

platform
Linuxx86-64, arm64
macOSApple Silicon
Windowsx86-64

Intel Macs are not supported - an Apple Silicon binary cannot run on one.

Prefer a manual install? Download the archive for your platform and put the binary on your PATH:

https://ecko.sh/dl/latest/ecko-x86_64-linux.tar.gz
https://ecko.sh/dl/latest/ecko-aarch64-linux.tar.gz
https://ecko.sh/dl/latest/ecko-aarch64-macos.tar.gz
https://ecko.sh/dl/latest/ecko-x86_64-windows.zip

Each has a .sha256 beside it, so you can verify before unpacking:

curl -fsSLO https://ecko.sh/dl/latest/ecko-x86_64-linux.tar.gz
curl -fsSLO https://ecko.sh/dl/latest/ecko-x86_64-linux.tar.gz.sha256
shasum -a 256 -c ecko-x86_64-linux.tar.gz.sha256

To pin a version, swap latest for the tag - https://ecko.sh/dl/v0.9.5/...; https://ecko.sh/dl/latest.txt says which tag latest currently is.

Run a file, or start the REPL:

ecko examples/hello.ecko   # run a file
ecko                       # start the REPL (or `ecko repl`)

Your first program is one line:

print("Hello, AI World!")   # Hello, AI World!

And the ai keyword needs no setup - it runs in mock mode until you add a key:

# Typed output; runs offline in mock mode (a real key returns a real answer)
count = ai[Int] "Count the words in this sentence"
print(count)   # 42

Set ECKO_API_KEY for real responses, and ECKO_AI_PROVIDER to switch between openai (default), anthropic, and ollama. Configuration is always through

Start here

  • Installing? The one-liner is at the top of this page; the full set of

archives and checksums is on the download page.

  • Kicking the tyres? Every ai call runs offline in mock mode, so a

program is testable before you configure a provider.

are written in Ecko, capability-gated, and installed with ecko get.

Reference

Every page below is written. The documentation covers the language, the ai keyword, concurrency, the standard library, packages, the CLI and the runtime's architecture.

Getting started

Language

The ai keyword

  • ai and typed output - ai "...", ai[Int] / ai[Bool] / ai[Enum] / ai[Struct] / ai[json<...>], schema coercion
  • Mock mode - deterministic schema-valid values with no key; how tests stay offline
  • Contracts - @requires / @ensures, boolean and natural-language, self-correcting retries
  • Majority voting - ai[T] n "..." runs n samples and takes the mode
  • Tool calling - @tool("...") functions, ai[T] "..." using [f, g], the runtime tool loop
  • Sessions - session() and ai "..." with chat for multi-turn conversations
  • Multimodal / vision - ai "..." on img, image handles, provider serialization
  • Embeddings & RAG - embed, embed_all, cosine; std.db and std.rag
  • Streaming - ai "..." -> stream, live SSE tokens, consuming a stream
  • Token budgeting - tokens(text), cost(model, in, out), hard call caps
  • Retry - retry(n, f) with exponential backoff for any failing operation
  • Providers & configuration - OpenAI / Anthropic / Ollama, swap with one env var
  • Caching - content-addressed prompt cache, replayable, budget-free
  • Tracing - ECKO_TRACE JSONL: every call's provider, model, tokens, latency, retries

Concurrency and async

  • pmap - data-parallel map over a bounded worker pool
  • cell - shared state - cell, cell_get, cell_set, cell_update (atomic read-modify-write)
  • Async tasks - async fn / await, spawning tasks, error propagation, cancel
  • Channels - channel (bounded/unbounded), send, recv, try_recv, close, select
  • Streaming responses & SSE - HTTP handlers that stream from a channel
  • Background tasks - std.bg: spawn, status, result, after, every, join_all

Standard library

  • std.string - the full UTF-8 string toolkit (upper, split, replace, pad_*, trim, ...)
  • std.math - constants (pi, e, tau) and float functions (sin, sqrt, log, clamp, ...)
  • std.io - print and basic I/O
  • std.fmt - format (raw-string {} placeholders), pad_left, pad_right, truncate
  • std.uuid - v4 (random) and v7 (time-ordered) UUIDs
  • std.cli - declarative arg parsing: parse(spec, argv), help(spec)
  • std.random - seedable RNG plus a CSPRNG (bytes, token)
  • std.test - case, eq, ok, err, fail for the test runner
  • std.time - now, now_iso, monotonic, format, parse
  • std.re - regex: test, find, find_all, captures, split, replace
  • std.hash - sha256, hmac_sha256, sha1, and Argon2id password / verify
  • std.encoding - base64, hex, and URL encode/decode (*_decode_text variants)
  • std.term - colors, styles, cursor control, TTY info, key input (honors NO_COLOR)
  • std.debug - inspect (secret-safe), type, timer, elapsed
  • std.humanize - duration, size, relative, ordinal, plural
  • std.zlib - gzip, gunzip, deflate, inflate over bytes
  • std.fs - files and directories (read, write, list_dir, copy, rename, ...) - fs:read / fs:write
  • std.os - host environment and process: env, env_or, set_env, args, cwd, platform, exec, exit (env / exec gated)
  • std.json - encode, decode, read, write
  • std.csv - parse, stringify, read, write (rows as column-keyed maps)
  • std.toml - parse, stringify, read, write
  • std.yaml - parse, stringify, read, write
  • std.log - leveled logging with text/JSON sinks and file rotation (fs:write for file sinks)
  • std.image - decode / resize / crop / encode PNG & JPEG; backs ai ... on <image>
  • std.config - layered config (env > file > default), with secret fields - env + fs:read
  • std.defaults - the project's ecko.json, loaded automatically: defaults.<key> plus an environment block applied to the process - ungated
  • std.db - in-process vector store: add, search, save, load (net to embed, fs to persist)
  • std.http - HTTP client and server, streaming/SSE, TLS, WebSocket upgrade
  • std.web - a router over http.serve: routes, :params, middleware, static files (GET routes also answer HEAD)
  • std.ws - WebSocket client (connect, send, recv, close)
  • std.net - raw TCP/TLS sockets and DNS (connect, connect_tls, starttls, send, recv)
  • std.dns - DNS resolver (resolve, reverse, lookup; A/AAAA/CNAME/MX/TXT)
  • std.llm - low-level chat access to the provider layer
  • std.rag - retrieval-augmented generation: chunk, index, retrieve, answer
  • std.sql - embedded SQLite: open, exec, query, query_one, transaction; sql { ... } blocks (:memory: is pure, a file db needs fs:write)
  • Global builtins reference - the ~95 functions always in scope: collections (map, filter, reduce, sort, group_by, ...), conversions (int, string, bytes, ...), json_encode / json_decode, embed / tokens / cost / retry, secret / reveal, error / assert, cell / channel, and py(...) (Python FFI)

Packages

CLI and tooling

  • ecko run / a file - run a program (a bare ecko file.ecko works too)
  • ecko repl - the interactive REPL
  • ecko dev - hot-reload for servers and scripts
  • ecko fmt - the canonical formatter (one style, zero config; --check)
  • ecko check - static analysis: undefined names, arity, use-before-def, exhaustiveness, unwrapped credentials
  • ecko test - the test runner (mock mode forced); --generate scaffolds tests
  • ecko explain / lint / fix - explain a program, lint dead code, AI-assisted fixes (--migrate-bytes)
  • ecko doc - markdown documentation from ## comments
  • ecko lsp - the stdio language server for editors
  • Package commands - init / add / install / remove / update / pack / build
  • Global flags - --model, --provider, --key, --cache, --trace

Configuration

  • Environment variables - the complete reference. Grouped:
  • AI / LLM - ECKO_API_KEY, ECKO_AI_PROVIDER, ECKO_AI_MODEL, ECKO_AI_BASE_URL, ECKO_AI_EMBED_MODEL, ECKO_AI_MAX_RETRIES, ECKO_AI_MAX_CALLS, ECKO_AI_MAX_TOOL_ROUNDS, ECKO_AI_TOOL_TIMEOUT_MS, ECKO_AI_CACHE, ECKO_TRACE, ECKO_RETRY_BASE_MS
  • Concurrency - ECKO_MAX_PARALLEL, ECKO_MAX_TASKS
  • HTTP / WebSocket server - ECKO_HTTP_WORKERS, ECKO_HTTP_REQUEST_TIMEOUT_MS, ECKO_HTTP_MAX_BODY, ECKO_MAX_WS_CONNS
  • Runtime limits - ECKO_MAX_DEPTH, ECKO_MAX_PARSE_DEPTH, ECKO_MAX_STEPS
  • Logging - ECKO_LOG
  • Packages - ECKO_PKG_MAX_BYTES, ECKO_PKG_MAX_UNPACKED
  • Terminal - NO_COLOR, CLICOLOR_FORCE

Architecture

Official packages

Batteries that live outside the binary: each one is written in Ecko, versioned on its own, and deletable. ecko get vendors a package under vendor/ and pins a hash; what it is allowed to do is the grant you give it at the import, not what its manifest asks for.

Every reference below is generated from the ## comments in the package's own source, so it says what the code says.

  • cache - A general-purpose cache written in Ecko: in-memory LRU with TTL over an optional disk store. get/set/remember(key, ttl, fn).
  • cli - Command-line argument parsing for Ecko: typed flags, options, positionals, defaults, and generated usage. Pure - no capabilities.
  • cookies - Parse and serialize HTTP cookies for client sessions: read Set-Cookie headers into a jar, build the Cookie request header. Pure - no capabilities.
  • datetime - Calendar dates, times, and durations for Ecko: components, arithmetic, and formatting over Unix-ms timestamps. Pure - no capabilities.
  • deque - A double-ended queue for Ecko: push/pop/peek at both ends, amortized O(1). Immutable two-stack deque. Pure - no capabilities.
  • heap - A priority queue (min-heap) for Ecko: push/pop/peek, heapify, and top-k. Immutable skew heap. Pure - no capabilities.
  • html - A tolerant HTML parser for Ecko: parse to a node tree, extract text, and find elements. Great for feeding web content to ai. Pure - no capabilities.
  • ip - IPv4/IPv6 address parsing, validation, CIDR membership, and private-range checks for Ecko. Pure - no capabilities.
  • mysql - A MySQL/MariaDB client written in Ecko: classic protocol + mysql_native_password over std.net.
  • perf - Measure the performance of your own Ecko code: time, measure, and bench (best-of-N stats)
  • postgres - A PostgreSQL client written in Ecko: v3 wire protocol + SCRAM-SHA-256 over std.net.
  • redact - Sensitive-key detection and masking for safe logging: is_sensitive_key, mask, and recursive map_of. Pure - no capabilities.
  • redis - A Redis client (RESP2) written in Ecko, over std.net raw sockets + TLS.
  • smtp - An SMTP client (RFC 5321) written in Ecko, over std.net raw sockets + STARTTLS.
  • stats - Descriptive statistics for Ecko: mean, median, mode, variance, stdev, quantiles. Pure - no capabilities.
  • struct - Pack and unpack binary data with a struct-style format string, over the bytes type. Pure - no capabilities.
  • textwrap - Wrap, fill, indent, dedent, and shorten text for Ecko - prompt building and terminal output. Pure - no capabilities.
  • tui - Terminal UI composition for Ecko: width-aware pad/center/truncate, bordered boxes, and aligned tables over std.term.
  • url - URL parsing, query strings, and reference resolution for Ecko.
  • validate - A data/input validation library written in Ecko: composable validator functions, whole-object schemas, collect-all errors. Pure - no capabilities.
  • webkit - SaaS web-app batteries for Ecko: auto-escaping HTML templates, signed cookies, sessions, and CORS/security middleware.
  • xml - An XML parser for Ecko: parse to a node tree, query by tag or path, extract text, and rebuild. Pure - no capabilities.

Ecko v0.9 - built in Rust, runs everywhere. Home at ecko.sh; licensing at ecko.sh/enterprise.