# Sema

> A Scheme-like Lisp with first-class LLM primitives, implemented in Rust.

**Coding agents: read [Sema for LLM agents](https://sema-lang.com/docs/for-agents.md) first** — every way Sema differs from other Lisps in one short page. The essentials:

- New functions are slash-namespaced (`file/read`, `string/split`, `regex/match?`); predicates end in `?`; conversions use `->`. Legacy Scheme string ops are kept (`string-append`).
- Only `#f` and `nil` are falsy — `0`, `""`, and the empty list are truthy.
- Lists are vector-backed (O(1) `nth`, O(n) `cons`); mutable state is `define` + `set!` (there is no `atom`/`swap!`).
- Clojure-style surface: `:keywords`, `{:k v}` maps, `[1 2 3]` vectors, `#(* % %)` lambdas, `f"...${x}"` strings, `#"regex"` literals.
- LLMs are language primitives: `llm/complete`, `deftool`/`agent/run`, `llm/extract`, cassettes, OpenTelemetry, vector store.

The table of contents below indexes the full docs — fetch only the specific `/docs/**/*.md` pages you need, on demand. Do not load `/llms-full.txt` (the full concatenation, ~200k tokens) into context.

## Table of Contents

### Standard Library Reference

- [Standard Library](https://sema-lang.com/docs/stdlib.md)

### Core Types

- [Math & Arithmetic](https://sema-lang.com/docs/stdlib/math.md)
- [Strings & Characters](https://sema-lang.com/docs/stdlib/strings.md)
- [Lists](https://sema-lang.com/docs/stdlib/lists.md)
- [Vectors](https://sema-lang.com/docs/stdlib/vectors.md)
- [Maps & HashMaps](https://sema-lang.com/docs/stdlib/maps.md)
- [Predicates & Type Checking](https://sema-lang.com/docs/stdlib/predicates.md)
- [Bytevectors](https://sema-lang.com/docs/stdlib/bytevectors.md)
- [Typed Arrays](https://sema-lang.com/docs/stdlib/typed-arrays.md)
- [Mutable Containers](https://sema-lang.com/docs/stdlib/mutable.md)

### File & Data Formats

- [File I/O & Paths](https://sema-lang.com/docs/stdlib/file-io.md)
- [PDF Processing](https://sema-lang.com/docs/stdlib/pdf.md)
- [CSV](https://sema-lang.com/docs/stdlib/csv.md)
- [TOML](https://sema-lang.com/docs/stdlib/toml.md)
- [Archives](https://sema-lang.com/docs/stdlib/archive.md)
- [Diff & Patch](https://sema-lang.com/docs/stdlib/diff.md)
- [Markdown & HTML](https://sema-lang.com/docs/stdlib/markup.md)

### Networking & Web

- [HTTP & JSON](https://sema-lang.com/docs/stdlib/http-json.md)
- [Web Server](https://sema-lang.com/docs/stdlib/web-server.md)

### System & Databases

- [System](https://sema-lang.com/docs/stdlib/system.md)
- [Processes & PTYs](https://sema-lang.com/docs/stdlib/process.md)
- [Git (read-only)](https://sema-lang.com/docs/stdlib/git.md)
- [SQLite](https://sema-lang.com/docs/stdlib/sqlite.md)
- [Key-Value Store](https://sema-lang.com/docs/stdlib/kv-store.md)
- [Serial Ports](https://sema-lang.com/docs/stdlib/serial.md)
- [Regex](https://sema-lang.com/docs/stdlib/regex.md)
- [Crypto & Encoding](https://sema-lang.com/docs/stdlib/crypto.md)
- [Secrets & Redaction](https://sema-lang.com/docs/stdlib/secret.md)
- [Reflection & Diagnostics](https://sema-lang.com/docs/stdlib/reflect.md)
- [Date & Time](https://sema-lang.com/docs/stdlib/datetime.md)
- [Context](https://sema-lang.com/docs/stdlib/context.md)
- [Terminal Styling](https://sema-lang.com/docs/stdlib/terminal.md)
- [Playground & WASM](https://sema-lang.com/docs/stdlib/playground.md)

### Concurrency & Streams

- [Streams](https://sema-lang.com/docs/stdlib/streams.md)
- [Concurrency](https://sema-lang.com/docs/stdlib/concurrency.md)
- [Records](https://sema-lang.com/docs/stdlib/records.md)
- [Text Processing](https://sema-lang.com/docs/stdlib/text-processing.md)

### LLM Essentials

- [LLM Primitives](https://sema-lang.com/docs/llm.md)
- [Completion & Chat](https://sema-lang.com/docs/llm/completion.md)
- [Tools & Agents](https://sema-lang.com/docs/llm/tools-agents.md)
- [Conversations](https://sema-lang.com/docs/llm/conversations.md)
- [Prompts & Messages](https://sema-lang.com/docs/llm/prompts.md)
- [Structured Extraction](https://sema-lang.com/docs/llm/extraction.md)

### Going Further

- [Provider Management](https://sema-lang.com/docs/llm/providers.md)
- [Cost Tracking & Budgets](https://sema-lang.com/docs/llm/cost.md)
- [Response Caching](https://sema-lang.com/docs/llm/caching.md)
- [Resilience & Retry](https://sema-lang.com/docs/llm/resilience.md)
- [Embeddings & Similarity](https://sema-lang.com/docs/llm/embeddings.md)
- [Vector Store & Math](https://sema-lang.com/docs/llm/vector-store.md)
- [Cassettes (Record & Replay)](https://sema-lang.com/docs/llm/cassettes.md)

### Observability

- [Tracing & Metrics](https://sema-lang.com/docs/llm/observability.md)
- [Backend Compatibility](https://sema-lang.com/docs/llm/otel-compat.md)

### Cookbook

- [Workflows](https://sema-lang.com/docs/llm/workflows.md)
- [RAG: retrieve, rerank, answer](https://sema-lang.com/docs/llm/rag.md): Build a retrieval-augmented generation pipeline in Sema — embeddings, vector search, cross-encoder reranking, and a grounded answer.

### Engine Internals

- [Architecture Overview](https://sema-lang.com/docs/internals/architecture.md)
- [Build a Bytecode VM (in Sema)](https://sema-lang.com/docs/internals/build-a-bytecode-vm.md)
- [Bytecode VM](https://sema-lang.com/docs/internals/bytecode-vm.md)
- [Bytecode File Format (`.semac`)](https://sema-lang.com/docs/internals/bytecode-format.md)
- [Bundled Executable Format](https://sema-lang.com/docs/internals/executable-format.md)
- [Evaluator Internals](https://sema-lang.com/docs/internals/evaluator.md)
- [Reader Internals](https://sema-lang.com/docs/internals/reader.md)
- [Fuzzing the VM](https://sema-lang.com/docs/internals/fuzzing.md)
- [Performance Internals](https://sema-lang.com/docs/internals/performance.md)
- [Lisp Dialect Benchmark](https://sema-lang.com/docs/internals/lisp-comparison.md)
- [Feature Comparison](https://sema-lang.com/docs/internals/feature-comparison.md)
- [Glossary](https://sema-lang.com/docs/internals/glossary.md)

### Sema Web

- [Sema Web](https://sema-lang.com/docs/web.md)
- [Getting Started](https://sema-lang.com/docs/web/getting-started.md)
- [Dev Server](https://sema-lang.com/docs/web/dev-server.md)
- [Building a Sema Web App](https://sema-lang.com/docs/web/building-apps.md)
- [Reactive State](https://sema-lang.com/docs/web/reactive-state.md)
- [Components](https://sema-lang.com/docs/web/components.md)
- [SIP Markup](https://sema-lang.com/docs/web/sip-markup.md)
- [DOM API](https://sema-lang.com/docs/web/dom-api.md)
- [Storage](https://sema-lang.com/docs/web/store.md)
- [Router](https://sema-lang.com/docs/web/routing.md)
- [Scoped CSS](https://sema-lang.com/docs/web/css.md)
- [HTTP & Streams](https://sema-lang.com/docs/web/http.md)
- [WebSockets](https://sema-lang.com/docs/web/websocket.md)
- [LLM Integration](https://sema-lang.com/docs/web/llm.md)
- [LLM Proxy](https://sema-lang.com/docs/web/llm-proxy.md)
- [Deployment](https://sema-lang.com/docs/web/deployment.md)
- [Examples](https://sema-lang.com/docs/web/examples.md)

### Getting Started

- [Getting Started](https://sema-lang.com/docs.md)
- [Quickstart](https://sema-lang.com/docs/quickstart.md)
- [Basic Syntax](https://sema-lang.com/docs/tutorial/basics.md)
- [Functions and Scope](https://sema-lang.com/docs/tutorial/functions.md)
- [Concurrency & Async](https://sema-lang.com/docs/tutorial/concurrency.md)

### Language Reference

- [Data Types](https://sema-lang.com/docs/language/data-types.md)
- [Special Forms](https://sema-lang.com/docs/language/special-forms.md)
- [Macros & Modules](https://sema-lang.com/docs/language/macros-modules.md)

### Tooling & Workspace

- [CLI Reference](https://sema-lang.com/docs/cli.md)
- [Formatter](https://sema-lang.com/docs/formatter.md)
- [Shell Completions](https://sema-lang.com/docs/shell-completions.md)
- [Editor Support](https://sema-lang.com/docs/editors.md)
- [Language Server (LSP)](https://sema-lang.com/docs/lsp.md)
- [Debugger (DAP)](https://sema-lang.com/docs/dap.md)
- [Model Context Protocol (MCP)](https://sema-lang.com/docs/mcp.md)
- [Notebook](https://sema-lang.com/docs/notebook.md)
- [Package Manager](https://sema-lang.com/docs/packages.md)

### Integration & Embedding

- [Embedding Sema](https://sema-lang.com/docs/embedding.md)
- [Embedding Sema (JavaScript)](https://sema-lang.com/docs/embedding-js.md)

### Sema Web

- [Sema Web](https://sema-lang.com/docs/web.md)
- [Getting Started](https://sema-lang.com/docs/web/getting-started.md)

### Other

- [Brand & Style Guide](https://sema-lang.com/brand.md)
- [Icon Manifest](https://sema-lang.com/icons.md)
- [Sema Agents & Tools — The Loop Is the Language](https://sema-lang.com/feature/agents.md): Define tools with schemas, build agents with system prompts and turn limits, and let the runtime handle the loop — retries, budgets, fallbacks, and cost tracking are language forms, not scaffolding you maintain.
- [Sema Build — Standalone Executables from Lisp](https://sema-lang.com/feature/build.md): Compile a Sema program into a self-contained binary. Trace imports, bundle assets, cross-compile for five platforms. No venv, no runtime, no dependencies on the target machine.
- [Sema Cassettes — Record & Replay LLM Calls](https://sema-lang.com/feature/cassettes.md): Record LLM responses once, replay them forever. Deterministic tests without API keys, offline demos that always work, and diffable tapes safe to commit.
- [Sema Embeddable — Put a Lisp in Your App](https://sema-lang.com/feature/embed.md): Embed Sema in Rust as a native scripting engine or in JavaScript via WASM in the browser. Same language, two host targets. Sandboxed by default, scriptable by design, with LLM primitives built in.
- [Sema Extraction — Unstructured Text In, Typed Data Out](https://sema-lang.com/feature/extraction.md): Pass a schema, get back a typed Sema map. The schema is both the instruction to the model and the validator for the response. When the output doesn't match, the LLM fixes its own mistake.
- [Sema for LLM Agents](https://sema-lang.com/docs/for-agents.md): Everything that differs from other Lisps, in one page — for AI coding agents.
- [Sema Notebook — Interactive LLM Development](https://sema-lang.com/feature/notebook.md): A Jupyter-inspired notebook for Sema. Write code in cells, evaluate inline, share environment state, and see LLM outputs with timing and token usage — all in the browser.
- [Sema Observability — OpenTelemetry Tracing for LLM Calls](https://sema-lang.com/feature/observability.md): Automatic OpenTelemetry tracing for every LLM call, tool execution, and agent run. One environment variable to turn on. GenAI semantic conventions. Works with Jaeger, Grafana, Langfuse, Datadog, and more.
- [Sema RAG — Retrieval Is a Language Feature, Not a Framework](https://sema-lang.com/feature/rag.md): Four primitives — embed, vector-store, rerank, complete — compose into the full RAG pipeline. No framework, no vector database to stand up, no orchestration library. Just functions that fit in one screen.
- [Sema Workflows — Journaled, Resumable Agent Pipelines](https://sema-lang.com/feature/workflows.md): Define multi-phase agent workflows as ordinary Sema code. Phases are markers, agents are LLM leaves, and every step is journaled to a frozen JSONL run directory — resume, replay, or fork without losing state.
- [What is Sema — A Lisp with LLM Primitives, in Rust](https://sema-lang.com/what-is-sema.md): Sema is a Scheme-like Lisp with a Clojure-flavored surface and first-class LLM/agent primitives, compiled to a NaN-boxed bytecode VM. Single-threaded, reference-counted, embeddable. Implemented in Rust.