<!-- Sema documentation — Builtins
     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/ -->

# Builtins

> Ambient constructors, tensor operations, and numeric builtins.

> Generated by `sema doc` from the compiler's authoritative native-signature registry.

# native builtins

Ambient constructors and tensor/embedding builtins — no import required.

# rational

## `QQ(value, denominator?) -> rational`

Exact rational constructor: canonical coprime form, positive denominator.

- domain: one finite number (exact binary-rational conversion for floats), or int numerator and nonzero int denominator
- shape: constructor
- returns: `rational`
- example: `QQ(1, 3)`

## `Rational(value, denominator?) -> rational`

Exact rational constructor: canonical coprime form, positive denominator.

- domain: one finite number (exact binary-rational conversion for floats), or int numerator and nonzero int denominator
- shape: constructor
- returns: `rational`
- example: `Rational(2, 4)`

## `rational(value, denominator?) -> rational`

Exact rational constructor: canonical coprime form, positive denominator.

- domain: one finite number (exact binary-rational conversion for floats), or int numerator and nonzero int denominator
- shape: constructor
- returns: `rational`
- example: `rational(0.5)`

# sets_logic

## `FiniteSet(items...) -> FiniteSet`

Construct a canonical finite set from explicit elements.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `FiniteSet(1, 2, 2)`

## `set(iterable?) -> FiniteSet`

Explicitly convert a list, tuple, or FiniteSet to FiniteSet.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `set([1, 2, 2])`

## `subset(left, right) -> bool`

Test extensional subset.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `bool`
- example: `subset({1}, {1, 2})`

## `proper_subset(left, right) -> bool`

Test strict extensional subset.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `bool`
- example: `proper_subset({1}, {1, 2})`

## `superset(left, right) -> bool`

Test extensional superset.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `bool`
- example: `superset({1, 2}, {1})`

## `union(left, right) -> FiniteSet`

Bounded finite-set union.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `union({1}, {2})`

## `intersection(left, right) -> FiniteSet`

Bounded finite-set intersection.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `intersection({1, 2}, {2, 3})`

## `set_difference(left, right) -> FiniteSet`

Bounded finite-set difference.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `set_difference({1, 2}, {2})`

## `symmetric_difference(left, right) -> FiniteSet`

Bounded symmetric difference.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `symmetric_difference({1, 2}, {2, 3})`

## `cartesian_product(left, right) -> FiniteSet`

Bounded Cartesian product as a set of tuples.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `cartesian_product({1}, {2})`

## `power_set(set) -> FiniteSet`

Power set for at most twelve input elements.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `power_set({1, 2})`

## `indexed_union(family) -> FiniteSet`

Union a bounded family of explicit finite sets.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `indexed_union([{1}, {2}])`

## `indexed_intersection(family) -> FiniteSet`

Intersect a nonempty bounded family of explicit finite sets.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `FiniteSet`
- example: `indexed_intersection([{1, 2}, {2}])`

## `indicator(set, value) -> int`

Exact 0/1 finite-set indicator.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `int`
- example: `indicator({1, 2}, 2)`

## `logical_not(value) -> Truth`

Strong-Kleene negation.

- domain: bool or explicit Truth; Unknown retains its reason and has no implicit bool conversion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `logical_not(Truth.unknown)`

## `logical_and(left, right) -> Truth`

Strong-Kleene conjunction.

- domain: bool or explicit Truth; Unknown retains its reason and has no implicit bool conversion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `logical_and(Truth.unknown, false)`

## `logical_or(left, right) -> Truth`

Strong-Kleene disjunction.

- domain: bool or explicit Truth; Unknown retains its reason and has no implicit bool conversion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `logical_or(Truth.unknown, true)`

## `logical_xor(left, right) -> Truth`

Three-valued exclusive-or.

- domain: bool or explicit Truth; Unknown retains its reason and has no implicit bool conversion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `logical_xor(true, false)`

## `implies(left, right) -> Truth`

Strong-Kleene implication.

- domain: bool or explicit Truth; Unknown retains its reason and has no implicit bool conversion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `implies(Truth.unknown, false)`

## `iff(left, right) -> Truth`

Strong-Kleene biconditional.

- domain: bool or explicit Truth; Unknown retains its reason and has no implicit bool conversion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `iff(true, true)`

## `forall(domain, predicate) -> Truth`

Universal quantification over an explicit FiniteSet.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `forall({1, 2}, lambda x: x > 0)`

## `exists(domain, predicate) -> Truth`

Existential quantification over an explicit FiniteSet.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `exists({1, 2}, lambda x: x == 2)`

## `exists_unique(domain, predicate) -> Truth`

Unique-existence quantification over an explicit FiniteSet.

- domain: explicit immutable finite sets, at most 4096 output elements; no tensor coercion
- shape: finite set / three-valued logic
- returns: `Truth`
- example: `exists_unique({1, 2}, lambda x: x == 2)`

# domain

## `complex(real?, imag?) -> complex`

Finite approximate complex scalar with checked arithmetic and C99 branch conventions.

- domain: zero to two finite f64-representable real components, or one complex value
- shape: constructor
- returns: `complex`
- example: `complex(1.5, -2.0)`

## `interval(lower, upper?) -> interval`

Certified closed f64 interval with outward-rounded arithmetic and transcendentals.

- domain: one finite real point or two ordered finite f64-representable endpoints
- shape: constructor
- returns: `interval`
- example: `interval(-0.1, 0.1)`

## `quaternion(w?, x?, y?, z?) -> quaternion`

Finite approximate Hamilton quaternion with checked algebra and rotation operations.

- domain: zero to four finite f64-representable Hamilton components, or one quaternion
- shape: constructor
- returns: `quaternion`
- example: `quaternion(1.0, 0.0, 0.0, 0.0)`

## `modint(value, modulus) -> modint`

Canonical exact residue class with checked same-modulus arithmetic, inverses, and powers.

- domain: exact integer value and modulus in 2..=2^63
- shape: constructor
- returns: `modint`
- example: `modint(10, 7)`

## `Modular(value, modulus) -> modint`

Canonical exact residue class with checked same-modulus arithmetic, inverses, and powers.

- domain: exact integer value and modulus in 2..=2^63
- shape: constructor
- returns: `modint`
- example: `Modular(10, 7)`

## `decimal(value) -> decimal`

Exact decimal input with an explicit bounded significant-digit arithmetic context.

- domain: decimal string or exact integer; precision 1..=4933; half_even or half_up
- shape: constructor
- returns: `decimal`
- keywords: `precision`, `rounding`
- example: `decimal("1.25", precision=28, rounding="half_even")`

## `rotate(rotation, vector) -> list[float]`

Rotate a three-vector by the orientation represented by a nonzero quaternion.

- domain: nonzero quaternion and a finite length-3 real vector
- shape: constructor
- returns: `list[float]`
- example: `rotate(quaternion(1.0), [1.0, 2.0, 3.0])`

## `slerp(start, end, t) -> quaternion`

Shortest-path normalized spherical interpolation between orientations.

- domain: two nonzero quaternions and finite t in [0, 1]
- shape: constructor
- returns: `quaternion`
- example: `slerp(quaternion(1.0), quaternion(0.0, 0.0, 0.0, 1.0), 0.5)`

# tensor

## `tensor(data) -> Tensor`

Build a typed Tensor from rectangular nested data.

- domain: uniform nested numeric or bool data with optional matching f64/bool dtype; bounded rank/elements
- shape: constructor
- returns: `Tensor`
- keywords: `dtype`
- example: `tensor([true, false], dtype="bool")`

## `matmul(a, b) -> Tensor`

Matrix product (or matrix·vector), shape-checked.

- domain: 2-D shapes (m,k)·(k,n), or matrix·vector; typed ShapeError otherwise
- shape: contraction
- returns: `Tensor`
- example: `matmul(eye(2), ones([2, 2]))`

## `dot(a, b) -> float`

Dot product of two vectors.

- domain: two equal-length 1-D vectors (bounded reduction work)
- shape: reduction
- returns: `float`
- example: `dot(tensor([1.0, 2.0]), tensor([3.0, 4.0]))`

## `zeros(shape) -> Tensor`

Tensor of zeros with the given shape.

- domain: nonnegative exact int or list/tuple of them (bounded elements)
- shape: constructor
- returns: `Tensor`
- example: `zeros([2, 3])`

## `ones(shape) -> Tensor`

Tensor of ones with the given shape.

- domain: nonnegative exact int or list/tuple of them (bounded elements)
- shape: constructor
- returns: `Tensor`
- example: `ones(3)`

## `eye(n) -> Tensor`

n×n identity matrix.

- domain: one nonnegative exact int dimension (bounded elements)
- shape: constructor
- returns: `Tensor`
- example: `eye(2)`

## `arange(stop) -> Tensor`

1-D tensor of 0.0..stop-1.

- domain: exact integer stop (negative yields an empty tensor; bounded elements)
- shape: constructor
- returns: `Tensor`
- example: `arange(4)`

## `shape(value) -> list[int]`

Dimensions of a tensor as a list of ints.

- domain: a Tensor/Embedding/list (scalars report [])
- shape: introspection
- returns: `list[int]`
- example: `shape(zeros([2, 3]))`

## `dtype(tensor) -> str`

Return the tensor dtype (`f64`, `bool`, or `complex`).

- domain: Tensor with an explicit runtime dtype
- shape: introspection
- returns: `str`
- example: `dtype(tensor([true, false]))`

## `where(condition, when_true, when_false) -> Tensor`

Select broadcast branch elements using a boolean tensor condition.

- domain: broadcastable bool condition and same-dtype f64, bool, or complex branches
- shape: elementwise (binary broadcast)
- returns: `Tensor`
- example: `where(tensor([true, false]), tensor([1.0, 2.0]), 0.0)`

# reduction

## `any(values) -> bool | Tensor`

Whether any element is true; bool tensors support axis reduction.

- domain: ordinary iterable, or bool Tensor with optional signed axis/keepdims
- shape: reduction
- returns: `bool | Tensor`
- keywords: `axis`, `keepdims`
- example: `any(tensor([true, false]))`

## `all(values) -> bool | Tensor`

Whether every element is true; bool tensors support axis reduction.

- domain: ordinary iterable, or bool Tensor with optional signed axis/keepdims
- shape: reduction
- returns: `bool | Tensor`
- keywords: `axis`, `keepdims`
- example: `all(tensor([true, false]))`

## `mean(values) -> int | rational | float | Tensor`

Mean; exact rational for exact inputs, float once any float enters, or deterministic complex tensor reduction.

- domain: non-empty iterable, or finite f64/complex tensor with optional integer axis/keepdims
- shape: reduction
- returns: `int | rational | float | Tensor`
- keywords: `axis`, `keepdims`
- example: `mean([1.0, 2.0, 4.0])`

## `sum(values, start?) -> int | rational | float | Tensor`

Sum; exact for exact inputs, float once any float enters, or deterministic complex tensor reduction.

- domain: iterable plus optional start, or finite f64/complex tensor with optional integer axis/keepdims
- shape: reduction
- returns: `int | rational | float | Tensor`
- keywords: `start`, `axis`, `keepdims`
- example: `sum([1, 2, 3], start=4)`

## `min(values...) -> float | Tensor`

Minimum value, with signed-axis tensor reduction support.

- domain: orderable values, or non-empty finite f64 Tensor
- shape: reduction
- returns: `float | Tensor`
- keywords: `axis`, `keepdims`
- example: `min([3, 1, 2])`

## `max(values...) -> float | Tensor`

Maximum value, with signed-axis tensor reduction support.

- domain: orderable values, or non-empty finite f64 Tensor
- shape: reduction
- returns: `float | Tensor`
- keywords: `axis`, `keepdims`
- example: `max([3, 1, 2])`

## `prod(tensor) -> float | Tensor`

Deterministic product over all elements or one signed axis.

- domain: finite f64/complex Tensor; empty products use the dtype's one identity
- shape: reduction
- returns: `float | Tensor`
- keywords: `axis`, `keepdims`
- example: `prod(tensor([2.0, 3.0, 4.0]))`

## `argmin(tensor) -> int | Tensor`

Index of the first minimum over all elements or one signed axis.

- domain: non-empty finite f64 Tensor; first index wins ties
- shape: reduction
- returns: `int | Tensor`
- keywords: `axis`, `keepdims`
- example: `argmin(tensor([3.0, 1.0, 2.0]))`

## `argmax(tensor) -> int | Tensor`

Index of the first maximum over all elements or one signed axis.

- domain: non-empty finite f64 Tensor; first index wins ties
- shape: reduction
- returns: `int | Tensor`
- keywords: `axis`, `keepdims`
- example: `argmax(tensor([3.0, 1.0, 2.0]))`

# embedding

## `embed(text) -> Tensor`

Embed text as a rank-1 tensor via the configured embedding seam.

- domain: any string (deterministic hash embedder unless a model is configured)
- shape: constructor
- returns: `Tensor`
- effects: `model.embed`
- example: `embed("sema native registry")`

# arithmetic

## `divmod(a, b) -> tuple[int | rational | float, int | rational | float]`

Python-compatible floored quotient/remainder pair (a//b, a%b); exact for exact operands.

- domain: numbers with a nonzero divisor
- shape: scalar
- returns: `tuple[int | rational | float, int | rational | float]`
- example: `divmod(9, 4)`