{ "markdown": "
\n\n\"Sema\"\n\n# Sema\n\n**A Lisp where LLM agents are language primitives, not an SDK** — compiled to a fast bytecode VM, shipped as a single binary.\n\n[![Playground](https://img.shields.io/badge/try_it-sema.run-c8a855?style=flat)](https://sema.run)\n[![Docs](https://img.shields.io/badge/docs-sema--lang.com-c8a855?style=flat)](https://sema-lang.com/docs/)\n[![Version](https://img.shields.io/github/v/tag/sema-lisp/sema?label=version&color=c8a855&style=flat)](https://github.com/sema-lisp/sema/releases/latest)\n[![Coverage](https://codecov.io/gh/sema-lisp/sema/graph/badge.svg)](https://codecov.io/gh/sema-lisp/sema)\n[![License](https://img.shields.io/badge/license-MIT-c8a855?style=flat)](LICENSE)\n\n[**Docs**](https://sema-lang.com/docs/) ·\n[**Playground**](https://sema.run) ·\n[**For Agents**](https://sema-lang.com/docs/for-agents) ·\n[**Examples**](https://github.com/sema-lisp/sema/tree/main/examples) ·\n[**Issues**](https://github.com/sema-lisp/sema/issues)\n\n
\n\n**Stop rewriting the agent loop.** Every LLM script grows the same scaffolding — retries, caching, cost caps, rate limits, tool dispatch, conversation state. Sema makes that scaffolding the runtime: your script stays the size of its idea, ships as a single binary, and your coding agent already speaks the language.\n\nSema is a Scheme-like Lisp where **prompts are s-expressions**, **conversations are persistent data structures**, and **LLM calls are just another form of evaluation** — with Clojure-style keywords (`:foo`), map literals (`{:key val}`), and vector literals (`[1 2 3]`).\n\n## What It Looks Like\n\nA coding agent with file tools, safety checks, and budget tracking — in ~40 lines:\n\n```scheme\n;; Define tools the LLM can call\n(deftool read-file\n \"Read a file's contents\"\n {:path {:type :string :description \"File path\"}}\n (lambda (path)\n (if (file/exists? path) (file/read path) \"File not found\")))\n\n(deftool edit-file\n \"Replace text in a file\"\n {:path {:type :string} :old {:type :string} :new {:type :string}}\n (lambda (path old new)\n (file/write path (string/replace (file/read path) old new))\n \"Done\"))\n\n(deftool run-command\n \"Run a shell command\"\n {:command {:type :string :description \"Shell command to run\"}}\n (lambda (command) (:stdout (shell \"sh\" \"-c\" command))))\n\n;; Create an agent with tools, system prompt, and spending limit\n(defagent coder\n {:system (format \"You are a coding assistant. Working directory: ~a\" (sys/cwd))\n :tools [read-file edit-file run-command]\n :max-turns 20}) ; no :model → uses the configured default provider\n\n;; Run it — budget is scoped, automatically restored after the block\n(llm/with-budget {:max-cost-usd 0.50} (lambda ()\n (define result (agent/run coder \"Add error handling to src/main.rs\"))\n (println (:response result))\n (println (format \"Cost: $~a\" (:spent (llm/budget-remaining))))))\n```\n\n## Key Features\n\n```scheme\n;; Simple completion\n(llm/complete \"Explain monads in one sentence\")\n\n;; Structured data extraction — returns a map, not a string\n(llm/extract\n {:vendor {:type :string} :amount {:type :number} :date {:type :string}}\n \"Bought coffee for $4.50 at Blue Bottle on Jan 15\")\n;; => {:amount 4.5 :date \"2025-01-15\" :vendor \"Blue Bottle\"}\n\n;; Classification\n(llm/classify (list :positive :negative :neutral) \"This product is amazing!\")\n;; => :positive\n\n;; Multi-turn conversations as immutable data\n(define conv (conversation/new {:model \"claude-haiku-4-5-20251001\"}))\n(define conv (conversation/say conv \"The secret number is 7\"))\n(define conv (conversation/say conv \"What's the secret number?\"))\n(conversation/last-reply conv) ;; => \"The secret number is 7.\"\n\n;; Streaming\n(llm/stream \"Tell me a story\" {:max-tokens 500})\n\n;; Batch — all prompts sent concurrently\n(llm/batch (list \"Translate 'hello' to French\"\n \"Translate 'hello' to Spanish\"\n \"Translate 'hello' to German\"))\n\n;; Vision — extract structured data from images\n(llm/extract-from-image\n {:text :string :background_color :string}\n \"assets/logo.png\")\n;; => {:background_color \"white\" :text \"Sema\"}\n\n;; Multi-modal chat — send images in messages\n(define img (file/read-bytes \"photo.jpg\"))\n(llm/chat (list (message/with-image :user \"Describe this image.\" img)))\n\n;; Cost tracking\n(llm/set-budget 1.00)\n(llm/budget-remaining) ;; => {:limit 1.0 :spent 0.05 :remaining 0.95}\n\n;; Response caching — avoid duplicate API calls during development\n(llm/with-cache (lambda ()\n (llm/complete \"Explain monads\")))\n\n;; Cassettes — record real responses once, replay them in CI (no keys, no network)\n(llm/with-cassette \"fixtures/run.jsonl\" {:mode :auto} (lambda ()\n (llm/complete \"Explain monads\")))\n\n;; Fallback chains — automatic provider failover\n(llm/with-fallback [:anthropic :openai :groq]\n (lambda () (llm/complete \"Hello\")))\n\n;; In-memory vector store for semantic search (RAG)\n(vector-store/create \"docs\")\n(vector-store/add \"docs\" \"id\" (llm/embed \"text\") {:source \"file.txt\"})\n(vector-store/search \"docs\" (llm/embed \"query\") 5)\n\n;; Cross-encoder reranking — the retrieve-many → rerank-to-a-few RAG move\n(llm/rerank \"how do I read a file?\"\n [\"file/read returns a string\" \"http/get fetches a URL\"]\n {:top-k 3})\n;; => ({:index 0 :score 0.98 :document \"file/read returns a string\"} ...)\n\n;; Text chunking for LLM pipelines\n(text/chunk long-document {:size 500 :overlap 100})\n\n;; Prompt templates\n(prompt/render \"Hello {{name}}\" {:name \"Alice\"})\n; => \"Hello Alice\"\n\n;; Persistent key-value store\n(kv/open \"cache\" \"cache.json\")\n(kv/set \"cache\" \"key\" {:data \"value\"})\n(kv/get \"cache\" \"key\")\n```\n\n## Supported Providers\n\nAll providers are auto-configured from environment variables — just set the API key and go.\n\n| Provider | Chat | Stream | Tools | Embeddings | Vision |\n| --------------------- | ---- | ------ | ----- | ---------- | ------ |\n| **Anthropic** | ✅ | ✅ | ✅ | — | ✅ |\n| **OpenAI** | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Google Gemini** | ✅ | ✅ | ✅ | — | ✅ |\n| **Ollama** | ✅ | ✅ | ✅ | — | ✅ |\n| **Groq** | ✅ | ✅ | ✅ | — | — |\n| **xAI** | ✅ | ✅ | ✅ | — | — |\n| **Mistral** | ✅ | ✅ | ✅ | — | — |\n| **Moonshot** | ✅ | ✅ | ✅ | — | — |\n| **Jina** | — | — | — | ✅ | — |\n| **Voyage** | — | — | — | ✅ | — |\n| **Cohere** | — | — | — | ✅ | — |\n| **Any OpenAI-compat** | ✅ | ✅ | ✅ | — | ✅ |\n| **Custom (Lisp)** | ✅ | — | ✅ | — | — |\n\n## It's Also a Real Lisp\n\nHundreds of built-in functions, tail-call optimization, macros, modules, error handling — not a toy.\n\n```scheme\n;; Closures, higher-order functions, TCO\n(define (fibonacci n)\n (let loop ((i 0) (a 0) (b 1))\n (if (= i n) a (loop (+ i 1) b (+ a b)))))\n(fibonacci 50) ;; => 12586269025\n\n;; Full R7RS numeric tower — bignums, exact rationals, complex numbers\n(expt 2 100) ;; => 1267650600228229401496703205376\n(+ 1/2 1/3) ;; => 5/6\n(sqrt -1) ;; => 0+1i\n\n;; Maps, keywords-as-functions, f-strings\n(define person {:name \"Ada\" :age 36 :langs [\"Lisp\" \"Rust\"]})\n(:name person) ;; => \"Ada\"\n(println f\"${(:name person)} knows ${(length (:langs person))} languages\")\n\n;; Destructuring\n(let (({:keys [name age]} person))\n (println f\"${name} is ${age}\"))\n\n;; Pattern matching with guards\n(define (classify n)\n (match n\n (x when (> x 100) \"big\")\n (x when (> x 0) \"small\")\n (_ \"non-positive\")))\n\n;; Functional pipelines\n(->> (range 1 100)\n (filter even?)\n (map #(* % %))\n (take 5))\n;; => (4 16 36 64 100)\n\n;; Nested data access\n(define config {:db {:host \"localhost\" :port 5432}})\n(get-in config [:db :host]) ;; => \"localhost\"\n\n;; Macros\n(defmacro unless (test . body)\n `(if ,test nil (begin ,@body)))\n\n;; Modules\n(module utils (export square)\n (define (square x) (* x x)))\n\n;; HTTP, JSON, regex, file I/O, crypto, CSV, datetime...\n(define data (json/decode (http/get \"https://api.example.com/data\")))\n```\n\n> 📖 Full language reference, stdlib docs, and more examples at **[sema-lang.com/docs](https://sema-lang.com/docs/)**\n\n## Try It Now\n\n> **[sema.run](https://sema.run)** — Browser-based playground with 20+ example programs.\n> No install required. Runs entirely in WebAssembly.\n\n## Teach Your Coding Agent Sema in One Line\n\nSema is new, so your agent hasn't seen it. Fix that in one command — append the\nagent crib sheet to your repo's `AGENTS.md` (and point `CLAUDE.md` at it):\n\n```bash\ncurl -fsSL https://sema-lang.com/docs/for-agents.md >> AGENTS.md\nln -s AGENTS.md CLAUDE.md # Claude Code, Cursor, etc. read this\n```\n\n[`for-agents.md`](https://sema-lang.com/docs/for-agents) is a compact working guide for\nan LLM that already knows a Lisp. It covers the rules most likely to cause incorrect\ngenerated code and links to [`/llms.txt`](https://sema-lang.com/llms.txt), a machine index\nof every doc page. The agent can fetch only the page it needs (for example,\n`/docs/llm/tools-agents.md`) instead of loading the whole manual. Every doc URL also\nserves raw Markdown: append `.md` to a `sema-lang.com/docs/...` link to get the source.\n\n## Installation\n\nInstall pre-built binaries (no Rust required):\n\n```bash\n# macOS / Linux\ncurl -fsSL https://sema-lang.com/install.sh | sh\n\n# Windows (PowerShell)\npowershell -ExecutionPolicy ByPass -c \"irm https://github.com/sema-lisp/sema/releases/latest/download/sema-lang-installer.ps1 | iex\"\n\n# Homebrew (macOS / Linux)\nbrew install helgesverre/tap/sema-lang\n```\n\nOr install from [crates.io](https://crates.io/crates/sema-lang):\n\n```bash\ncargo install sema-lang\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/sema-lisp/sema\ncd sema && cargo build --release\n# Binary at target/release/sema\n```\n\n```bash\nsema # REPL (with tab completion)\nsema script.sema # Run a file\nsema -e '(+ 1 2)' # Evaluate expression\nsema --no-llm script.sema # Run without LLM (faster startup)\nsema build app.sema -o myapp # Build standalone executable\n./myapp # Run without sema installed\n```\n\n### Shell Completions\n\nGenerate tab-completion scripts for your shell:\n\n```bash\n# Zsh (macOS / Linux)\nmkdir -p ~/.zsh/completions\nsema completions zsh > ~/.zsh/completions/_sema\n\n# Bash\nmkdir -p ~/.local/share/bash-completion/completions\nsema completions bash > ~/.local/share/bash-completion/completions/sema\n\n# Fish\nsema completions fish > ~/.config/fish/completions/sema.fish\n```\n\n> 📖 Full setup instructions for all shells: **[sema-lang.com/docs/shell-completions](https://sema-lang.com/docs/shell-completions)**\n\n> 📖 Full CLI reference, flags, and REPL commands: **[sema-lang.com/docs/cli](https://sema-lang.com/docs/cli)**\n\n### Editor Support\n\nEach editor plugin lives in its own repo under the [`sema-lisp`](https://github.com/sema-lisp) org:\n\n| Editor | Repository | Install |\n| ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |\n| **VS Code** | [`vscode-sema`](https://github.com/sema-lisp/vscode-sema) | `ext install sema-lang.sema-lang` |\n| **Zed** | [`zed-sema`](https://github.com/sema-lisp/zed-sema) | Extensions → search **Sema** |\n| **IntelliJ** | [`intellij-sema`](https://github.com/sema-lisp/intellij-sema) | JetBrains Marketplace → **Sema** |\n| **Neovim** | [`sema.nvim`](https://github.com/sema-lisp/sema.nvim) | `{ \"sema-lisp/sema.nvim\" }` |\n| **Vim** | [`sema.vim`](https://github.com/sema-lisp/sema.vim) | `Plug 'sema-lisp/sema.vim'` |\n| **Emacs** | [`emacs-sema`](https://github.com/sema-lisp/emacs-sema) | MELPA → `sema-mode` |\n| **Helix** | [`helix-sema`](https://github.com/sema-lisp/helix-sema) | clone + `./install.sh` |\n| **Sublime Text** | [`sublime-sema`](https://github.com/sema-lisp/sublime-sema) | Package Control → **Sema** |\n\nAll plugins provide syntax highlighting; VS Code, Zed, IntelliJ, Neovim, Emacs, Helix, and Sublime also wire up the built-in **language server** (`sema lsp`), and several (VS Code, Zed, IntelliJ, Neovim, Helix) add **debugging** (`sema dap`) — some also register the **MCP server** (`sema mcp`). Zed, Helix, and Neovim highlight via the shared [`tree-sitter-sema`](https://github.com/sema-lisp/tree-sitter-sema) grammar; the others ship their own.\n\n> 📖 Full installation instructions and per-editor feature lists: **[sema-lang.com/docs/editors](https://sema-lang.com/docs/editors)**\n\n### Notebook\n\nSema includes a Jupyter-inspired notebook interface with a browser UI:\n\n```bash\nsema notebook new my-notebook.sema-nb # Create a notebook\nsema notebook serve my-notebook.sema-nb # Open in browser (localhost:8888)\nsema notebook run my-notebook.sema-nb # Run all cells headlessly\nsema notebook export my-notebook.sema-nb # Export to Markdown\n```\n\nCells share a persistent environment — definitions in earlier cells are visible in later ones. Notebooks are saved as `.sema-nb` JSON files.\n\n> 📖 Full notebook documentation: **[sema-lang.com/docs/notebook](https://sema-lang.com/docs/notebook)**\n\n### Language Tooling\n\nA full toolchain ships in the box — no plugins to assemble:\n\n```bash\nsema fmt script.sema # Canonical code formatter\nsema lsp # Language Server (completions, hover, go-to-def, rename)\nsema dap # Debug Adapter (breakpoints, stepping, variable inspection)\nsema mcp # Model Context Protocol server for LLM clients\n```\n\nThe **MCP server** lets LLM clients (Claude Desktop, Cursor, Claude Code) compile, format, evaluate, and build Sema code — and call your own `deftool` Lisp tools — directly in your environment.\n\n> 📖 [Formatter](https://sema-lang.com/docs/formatter) · [LSP](https://sema-lang.com/docs/lsp) · [Debugger](https://sema-lang.com/docs/dap) · [MCP](https://sema-lang.com/docs/mcp)\n\n## Example Programs\n\nThe [`examples/`](https://github.com/sema-lisp/sema/tree/main/examples) directory has 50+ programs:\n\n| Example | What it does |\n| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |\n| [`coding-agent.sema`](https://github.com/sema-lisp/sema/blob/main/examples/ai-tools/coding-agent.sema) | Full coding agent with file editing, search, and shell tools |\n| [`review.sema`](https://github.com/sema-lisp/sema/blob/main/examples/ai-tools/review.sema) | AI code reviewer for git diffs |\n| [`commit-msg.sema`](https://github.com/sema-lisp/sema/blob/main/examples/ai-tools/commit-msg.sema) | Generate conventional commit messages from staged changes |\n| [`summarize.sema`](https://github.com/sema-lisp/sema/blob/main/examples/ai-tools/summarize.sema) | Summarize files or piped input |\n| [`game-of-life.sema`](https://github.com/sema-lisp/sema/blob/main/examples/game-of-life.sema) | Conway's Game of Life |\n| [`brainfuck.sema`](https://github.com/sema-lisp/sema/blob/main/examples/brainfuck.sema) | Brainfuck interpreter |\n| [`mandelbrot.sema`](https://github.com/sema-lisp/sema/blob/main/examples/mandelbrot.sema) | ASCII Mandelbrot set |\n| [`json-api.sema`](https://github.com/sema-lisp/sema/blob/main/examples/json-api.sema) | Fetch and process JSON APIs |\n| [`test-vision.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-vision.sema) | Vision extraction and multi-modal chat tests |\n| [`test-extract.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-extract.sema) | Structured extraction and classification |\n| [`test-batch.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-batch.sema) | Batch/parallel LLM completions |\n| [`test-pipeline.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-pipeline.sema) | Caching, budgets, rate limiting, retry, fallback chains |\n| [`test-text-tools.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-text-tools.sema) | Text chunking, prompt templates, document abstraction |\n| [`test-vector-store.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-vector-store.sema) | In-memory vector store with similarity search |\n| [`test-kv-store.sema`](https://github.com/sema-lisp/sema/blob/main/examples/llm/test-kv-store.sema) | Persistent JSON-backed key-value store |\n| [`expr-evaluator.sema`](https://github.com/sema-lisp/sema/blob/main/examples/expr-evaluator.sema) | Mini calculator using `match` on tagged vectors |\n| [`shape-geometry.sema`](https://github.com/sema-lisp/sema/blob/main/examples/shape-geometry.sema) | Shape areas/perimeters with map pattern matching |\n| [`http-router.sema`](https://github.com/sema-lisp/sema/blob/main/examples/http-router.sema) | HTTP router with `match` on nested maps and guards |\n| [`destructuring.sema`](https://github.com/sema-lisp/sema/blob/main/examples/destructuring.sema) | Comprehensive destructuring showcase (vector, map, lambda) |\n| [`demo.sema-nb`](https://github.com/sema-lisp/sema/blob/main/examples/notebook/demo.sema-nb) | Interactive notebook demo (run with `sema notebook serve`) |\n\n## Why Sema?\n\nThe pitch in one line: **no LangChain, no provider SDK, no agent framework, no glue\nscript** — the agent loop, retries, caching, budgets, tracing, and tool dispatch are the\nlanguage runtime, and the whole thing is one binary you can `scp` to a box.\n\n- **LLMs as language primitives** — prompts, messages, conversations, tools, and agents are first-class data types, not string templates bolted on\n- **Multi-provider** — swap between Anthropic, OpenAI, Gemini, Ollama, any OpenAI-compatible endpoint, or define your own provider in Sema\n- **Pipeline-ready** — response caching, fallback chains, rate limiting, retry with backoff, text chunking, prompt templates, vector store, and a persistent KV store\n- **Cost-aware** — built-in budget tracking with a bundled pricing snapshot ([models.dev](https://models.dev)), updated per release\n- **Observable** — every LLM/agent run is auto-traced with OpenTelemetry (GenAI semantic conventions): tokens, cost, latency, and the full `invoke_agent → chat → execute_tool` tree, exportable to Jaeger, Grafana, Datadog, Langfuse, Arize Phoenix, and more — zero manual instrumentation, off by default\n- **Practical Lisp** — closures, TCO, macros, modules, error handling, HTTP, file I/O, regex, JSON, and a comprehensive stdlib\n- **Standalone executables** — `sema build` compiles programs into self-contained binaries with auto-traced imports and bundled assets\n- **Embeddable** — [a Rust crate](https://crates.io/crates/sema-lang) with a builder API, or [`@sema-lang/sema`](https://www.npmjs.com/package/@sema-lang/sema) to run Sema client-side in JS via WebAssembly\n- **Full toolchain** — formatter, language server (LSP), debugger (DAP), and an MCP server for LLM clients, all built in\n- **Package manager** — `sema pkg` pulls dependencies from git or the live registry at [pkg.sema-lang.com](https://pkg.sema-lang.com), pinned by a `sema.lock` for reproducible installs\n- **Developer-friendly** — REPL with tab completion, structured error messages with hints, and 50+ example programs\n\n### Why Not Sema?\n\n- No continuations (`call/cc`) or fully hygienic macros (`syntax-rules`) — has auto-gensym (`foo#`) for preventing variable capture\n- Single-threaded — `Rc`-based, no cross-thread sharing of values\n- No JIT — bytecode compiler + stack-based VM, no native code generation\n- Young language — solid but not battle-tested at scale\n\n## Architecture\n\n```\ncrates/\n sema-core/ NaN-boxed Value type, errors, environment\n sema-reader/ Lexer and s-expression parser\n sema-vm/ Bytecode compiler and virtual machine\n sema-eval/ Trampoline-based evaluator, special forms, modules\n sema-stdlib/ Built-in functions across many modules\n sema-io/ Process-wide async I/O pool (tokio) behind the core seam\n sema-llm/ LLM provider trait + multi-provider clients\n sema-workflow/ Dynamic-workflow runtime — journaled runs, bounded fan-out, --resume\n sema-otel/ OpenTelemetry tracing (GenAI semantic conventions)\n sema-docs/ Canonical builtin docs (powers LSP hover + REPL apropos)\n sema-lsp/ Language Server Protocol implementation\n sema-dap/ Debug Adapter Protocol server\n sema-fmt/ Source code formatter\n sema-mcp/ Model Context Protocol server\n sema-notebook/ Jupyter-inspired notebook interface with browser UI\n sema-wasm/ WebAssembly build for sema.run playground\n sema/ CLI binary: REPL + file runner + standalone builder\n```\n\n> 🔬 Deep-dive into the internals: [Architecture](https://sema-lang.com/docs/internals/architecture) · [Evaluator](https://sema-lang.com/docs/internals/evaluator) · [Lisp Comparison](https://sema-lang.com/docs/internals/lisp-comparison)\n\n## License\n\nMIT — see [LICENSE](https://github.com/sema-lisp/sema/blob/main/LICENSE).\n", "bytes": 22309, "sha": "f0454844fcf50bcae8b7a39b6ced9422ba68849bb6cc54258252c2695883f3d0", "repo_slug": "sema-lisp/sema", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_sema_lang_sema_26d32622/readme" }