velarium 0.8.0

Velarium IR (ModelSpec): normalization, JSON codec, Python→IR extraction

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).

PyPI	pypi.org/project/velarium
Repository	github.com/eddiethedean/velarium
Python	3.10+
Import	import velarium / from velarium.ir import ModelSpec, TypeSpec
Dependencies	typing_extensions only; optional velarium[pydantic], velarium[attrs], or velarium[sources]

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)

Area	Modules / entry points
IR types	velarium.ir — ModelSpec, TypeSpec, TypeKind, …
JSON	velarium.json_codec — dumps_model_spec, loads_model_spec, dict helpers; optional VELARIUM_JSON_MAX_DEPTH / VELARIUM_JSON_MAX_BYTES (see security.md)
Normalization	velarium.normalize — normalize_typespec, unions, optional handling; optional VELARIUM_NORMALIZE_BACKEND=native (falls back to Python; see performance.md)
Annotations	velarium.annotations — type_to_typespec, annotation_to_typespec
Builders	velarium.modelspec_build — modelspec_from_dataclass, modelspec_from_typed_dict, typespec_from_object; velarium.modelspec_pydantic / modelspec_from_pydantic_model (extra); velarium.modelspec_attrs / modelspec_from_attrs_class (extra)
Resolution	velarium.typing_resolve — get_resolved_hints, module_globals_for_class, evaluate_forward_ref (used by builders; re-export not required for typical use)

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.