Metadata-Version: 2.4
Name: velarium
Version: 0.2.0
Summary: Velarium IR (ModelSpec): normalization, JSON codec, Python→IR extraction
Project-URL: Homepage, https://github.com/eddiethedean/velarium
Project-URL: Repository, https://github.com/eddiethedean/velarium
Project-URL: Documentation, https://github.com/eddiethedean/velarium/blob/main/docs/README.md
Project-URL: Changelog, https://github.com/eddiethedean/velarium/blob/main/CHANGELOG.md
Author: Velarium contributors
License: MIT
License-File: LICENSE
Keywords: ir,modelspec,static-analysis,typing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: typing-extensions>=4.2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ty>=0.0.29; extra == 'dev'
Description-Content-Type: text/markdown

# velarium

**Role in Velarium:** core **ModelSpec IR** — normalized types (`TypeSpec`, `TypeKind`, …), **`ModelSpec`**, JSON codec, union normalization, and builders that turn dataclasses and `TypedDict` into IR.

| | |
|---|---|
| **PyPI** | `velarium` |
| **Import** | `import velarium` / `from velarium.ir import ModelSpec, TypeSpec` |
| **Dependencies** | `typing_extensions` only |

Downstream packages (e.g. [**velotype**](../velotype/README.md)) consume this IR to emit `.pyi` stubs and other artifacts. The IR contract is specified in [docs/modelspec-ir.md](../../docs/modelspec-ir.md); how Python annotations map to the IR is in [docs/supported-annotations.md](../../docs/supported-annotations.md). Ecosystem context is in [docs/valarium.md](../../docs/valarium.md) and [docs/design.md](../../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 |
| Normalization | `velarium.normalize` — `normalize_typespec`, unions, optional handling |
| Annotations | `velarium.annotations` — `type_to_typespec`, `annotation_to_typespec` |
| Builders | `velarium.modelspec_build` — `modelspec_from_dataclass`, `modelspec_from_typed_dict`, `typespec_from_object` |
| 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

```bash
pip install velarium
```

From the monorepo root (with [uv](https://docs.astral.sh/uv/)):

```bash
uv sync --group dev
```

## Version

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

## See also

- [Repository README](../../README.md) — full package table and workspace setup  
- [Documentation index](../../docs/README.md)
