<!-- Sema documentation — std.overview
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.49.12.246.95.sslip.io/llms-full.txt
     Install language support: https://sema.49.12.246.95.sslip.io/install-skill/ -->

# std.overview

> How the Sema standard library works — written in Sema, embedded in the compiler, imported via from std.<module> import ….

The Sema standard library is a small set of neurosymbolic building blocks —
calibrated confidence, memoization, structured reports, agentic loops, usage
accounting, provenance, and collection helpers. What makes it unusual is what it
is *made of*: **the standard library is written in Sema.** Every module you see
here has a `.sema` source file that you can read, and the logic in it — a Beta
prior, a token price, a render layout — is expressed in the language, not buried
in the runtime.

## How it works

Each module lives in `stdlib/sema/<module>.sema` and ships **embedded in the
compiler** (injected via `crates/sema-runtime/src/stdlib.rs`). There is nothing
to install. Any project can bring a module in with an explicit import:

```sema
from std.belief import Belief, prior
from std.cache import memoize
from std.document import Report, render
from std.agent_loop import loop_until
```

Sema draws a clean line between two kinds of dependency (spec §5.35). **Effect
capabilities** — `fs`, `net`, `model`, `memory`, … — are authorized by the
`!{...}` effect row on a function and stay ambient. **Standard-library modules**
are APIs you call, so they must be named in an explicit `import`, exactly as in
Python. Using a `std` module without importing it is a `NameError` with an
actionable hint, never a silent fallback.

:::note[The stdlib is a native Sema package]
The `std` package is a *native Sema package* (spec §5.46) — a directory of
`src/*.sema` — that happens to ship inside the compiler rather than in
`.sema/packages/`. Because its components are expressed in Sema, their parameters
and logic are changeable in the language, and **a user module of the same stem
shadows the stdlib one**. If you define your own `belief` module in your project,
your version wins.
:::

## Why it exists

Each module replaces code that AI applications otherwise hand-roll again and
again — a bespoke confidence tracker, a pickle-path cache, regex repair of
freeform model markdown, a 300-line while loop, `(result, usage)` tuple
threading, citation-id bookkeeping. Standardizing these as small, verified,
readable Sema components makes the neurosymbolic parts of a program legible and
reusable instead of copy-pasted.

## The seven modules

| Module | What it gives you | Narrative | Generated API |
|---|---|---|---|
| `belief` | Beta-Bernoulli calibrated confidence | [std.belief](/stdlib/belief/) | [API](/reference/stdlib-api/belief/) |
| `cache` | Memoization decorators (in-run + on-disk) | [std.cache](/stdlib/cache/) | [API](/reference/stdlib-api/cache/) |
| `collections` | Small pure list/string helpers | [std.collections](/stdlib/collections/) | [API](/reference/stdlib-api/collections/) |
| `document` | Typed report IR + deterministic render | [std.document](/stdlib/document/) | [API](/reference/stdlib-api/document/) |
| `agent_loop` | The agentic loop as a combinator | [std.agent_loop](/stdlib/agent_loop/) | [API](/reference/stdlib-api/agent_loop/) |
| `usage` | Model usage accounting + pricing | [std.usage](/stdlib/usage/) | [API](/reference/stdlib-api/usage/) |
| `provenance` | Citation-id mapping + rewrite | [std.provenance](/stdlib/provenance/) | [API](/reference/stdlib-api/provenance/) |

## Narrative pages vs. the API reference

Every module has two pages. The **narrative page** (this section, `/stdlib/…`)
motivates the module, shows the key types and functions with usage, and gives you
the import line. The **generated API reference** (`/reference/stdlib-api/…`) is
emitted by `sema doc` directly from the `.sema` source — it is the exact,
never-drifting signature list (params, return types, effect rows, struct fields).
Read the narrative to learn the module; consult the API for the precise surface.

:::tip[Everything here is verified]
Every `std` module is imported, compiled, and run — the `examples/neurosymbolic-port/*`
programs drive the stdlib and are proven equivalent to the reference Python
implementations these modules replace.
:::