velarium

Role in Velarium: core ModelSpec IR — normalized types (TypeSpec, TypeKind, …), ModelSpec, JSON codec, union normalization, and builders that turn dataclasses, TypedDict, Pydantic BaseModel, and attrs classes into IR (see model-sources.md).

Downstream packages (e.g. velotype on PyPI) consume this IR to emit .pyi stubs and other artifacts. The IR contract is in docs/modelspec-ir.md; JSON format_version and migration notes are in docs/migration-ir.md; the hand-maintained public symbol list is docs/api-reference.md; pre-1.0 stability expectations are in docs/stability.md. How Python annotations map to the IR is in docs/supported-annotations.md; stub consumer guarantees are summarized in docs/stub-compatibility.md; builders and optional extras are in docs/model-sources.md. Ecosystem context is in docs/valarium.md and docs/design.md.

Public API (high level)

Install

pip install velarium
# Optional: Pydantic v2 / attrs builders
pip install velarium[pydantic]   # or velarium[attrs] / velarium[sources]

From the monorepo root (with uv):

uv sync --group dev

Version

__version__ lives in velarium/__init__.py (Hatch reads it from that package’s pyproject.toml).

See also

• Repository README — full package table and workspace setup
• Documentation index
• API reference — supported public imports
• Security — JSON deserialization limits, trust boundaries for builders
• Roadmap
• Changelog

License

MIT — see LICENSE.