velarium 0.1.0__tar.gz

velarium-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Packaging / build
+build/
+dist/
+packages/*/dist/
+*.egg-info/
+*.egg
+.eggs/
+pip-wheel-metadata/
+share/python-wheels/
+
+# Hatch / setuptools
+.hatch/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local env / secrets
+.env
+.env.*
+!.env.example
+
+# Cursor / tooling (optional local state)
+*.log

velarium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) stubber contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

velarium-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: velarium
+Version: 0.1.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
+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. [**stubber**](../stubber/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); ecosystem context is in [docs/valarium.md](../../docs/valarium.md) and [docs/design.md](../../docs/design.md).
+
+## 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)

velarium-0.1.0/README.md

@@ -0,0 +1,32 @@
+# 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. [**stubber**](../stubber/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); ecosystem context is in [docs/valarium.md](../../docs/valarium.md) and [docs/design.md](../../docs/design.md).
+
+## 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)

velarium-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "velarium"
+dynamic = ["version"]
+description = "Velarium IR (ModelSpec): normalization, JSON codec, Python→IR extraction"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Velarium contributors" }]
+keywords = ["typing", "ir", "static-analysis", "modelspec"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "typing_extensions>=4.2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "ty>=0.0.29", "build>=1.0", "pytest-cov>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/eddiethedean/velarium"
+Repository = "https://github.com/eddiethedean/velarium"
+Documentation = "https://github.com/eddiethedean/velarium/blob/main/docs/README.md"
+Changelog = "https://github.com/eddiethedean/velarium/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "velarium/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["velarium", "README.md"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../LICENSE" = "LICENSE"
+
+[tool.hatch.build.targets.wheel]
+packages = ["velarium"]

velarium-0.1.0/velarium/__init__.py

@@ -0,0 +1,46 @@
+"""Velarium: ModelSpec IR, normalization, JSON codec, and Python→IR extraction."""
+
+from velarium.annotations import annotation_to_typespec, type_to_typespec
+from velarium.ir import (
+    FieldSpec,
+    ModelConfig,
+    ModelMetadata,
+    ModelSpec,
+    TypeKind,
+    TypeSpec,
+)
+from velarium.json_codec import (
+    dumps_model_spec,
+    loads_model_spec,
+    model_spec_from_dict,
+    model_spec_to_dict,
+)
+from velarium.modelspec_build import (
+    modelspec_from_dataclass,
+    modelspec_from_typed_dict,
+    typespec_from_object,
+)
+from velarium.normalize import normalize_typespec, normalize_union, optional_to_union
+
+__all__ = [
+    "annotation_to_typespec",
+    "type_to_typespec",
+    "FieldSpec",
+    "ModelConfig",
+    "ModelMetadata",
+    "ModelSpec",
+    "TypeKind",
+    "TypeSpec",
+    "dumps_model_spec",
+    "loads_model_spec",
+    "model_spec_from_dict",
+    "model_spec_to_dict",
+    "modelspec_from_dataclass",
+    "modelspec_from_typed_dict",
+    "typespec_from_object",
+    "normalize_typespec",
+    "normalize_union",
+    "optional_to_union",
+]
+
+__version__ = "0.1.0"

velarium-0.1.0/velarium/annotations.py

@@ -0,0 +1,200 @@
+"""Map Python typing objects to TypeSpec (MVP subset)."""
+
+from __future__ import annotations
+
+import datetime
+import typing
+from collections.abc import Callable as CallableABC
+from enum import Enum
+from types import UnionType
+from typing import Any, ForwardRef, TypeVar, Union, get_args, get_origin
+
+from velarium.ir import TypeKind, TypeSpec
+from velarium.normalize import normalize_typespec, optional_to_union
+
+
+def _none() -> TypeSpec:
+    return TypeSpec(kind=TypeKind.NONE)
+
+
+def _merge_optional(ts: TypeSpec, *, optional: bool) -> TypeSpec:
+    out = TypeSpec(
+        kind=ts.kind,
+        args=ts.args,
+        optional=optional or ts.optional,
+        nullable=ts.nullable,
+        default=ts.default,
+    )
+    return optional_to_union(out) if out.optional else out
+
+
+def type_to_typespec(
+    t: Any,
+    *,
+    optional: bool = False,
+) -> TypeSpec:
+    """Convert a runtime typing object or builtin type to TypeSpec."""
+    if t is type(None) or t is None:
+        return _merge_optional(_none(), optional=optional)
+
+    if t is Any or t is typing.Any:
+        return _merge_optional(TypeSpec(kind=TypeKind.ANY), optional=optional)
+
+    if isinstance(t, ForwardRef):
+        return _merge_optional(TypeSpec(kind=TypeKind.ANY), optional=optional)
+
+    if isinstance(t, str):
+        return _merge_optional(TypeSpec(kind=TypeKind.ANY), optional=optional)
+
+    origin = get_origin(t)
+    args = get_args(t)
+
+    if origin is typing.Literal:
+        parts: list[TypeSpec] = []
+        for a in args:
+            parts.append(TypeSpec(kind=TypeKind.LITERAL, default=a))
+        if len(parts) == 1:
+            u = parts[0]
+        else:
+            u = TypeSpec(kind=TypeKind.UNION, args=parts)
+        return _merge_optional(normalize_typespec(u), optional=optional)
+
+    if origin is UnionType or origin is Union:
+        parts = [type_to_typespec(a, optional=False) for a in args]
+        has_none = any(p.kind == TypeKind.NONE for p in parts)
+        u = TypeSpec(kind=TypeKind.UNION, args=parts)
+        u = normalize_typespec(u)
+        opt = optional or has_none
+        if has_none:
+            u.optional = True
+        return _merge_optional(u, optional=opt)
+
+    if origin is list or origin is typing.List:
+        inner = (
+            type_to_typespec(args[0], optional=False)
+            if args
+            else TypeSpec(kind=TypeKind.ANY)
+        )
+        return _merge_optional(
+            TypeSpec(kind=TypeKind.LIST, args=[inner]), optional=optional
+        )
+
+    if origin is dict or origin is typing.Dict:
+        k = (
+            type_to_typespec(args[0], optional=False)
+            if len(args) > 0
+            else TypeSpec(kind=TypeKind.ANY)
+        )
+        v = (
+            type_to_typespec(args[1], optional=False)
+            if len(args) > 1
+            else TypeSpec(kind=TypeKind.ANY)
+        )
+        return _merge_optional(
+            TypeSpec(kind=TypeKind.DICT, args=[k, v]), optional=optional
+        )
+
+    if origin is set or origin is typing.Set:
+        inner = (
+            type_to_typespec(args[0], optional=False)
+            if args
+            else TypeSpec(kind=TypeKind.ANY)
+        )
+        return _merge_optional(
+            TypeSpec(kind=TypeKind.SET, args=[inner]), optional=optional
+        )
+
+    if origin is tuple or origin is typing.Tuple:
+        if not args:
+            inner = TypeSpec(kind=TypeKind.ANY)
+            return _merge_optional(
+                TypeSpec(kind=TypeKind.TUPLE, args=[inner]), optional=optional
+            )
+        if len(args) == 2 and args[1] is Ellipsis:
+            inner = type_to_typespec(args[0], optional=False)
+            return _merge_optional(
+                TypeSpec(kind=TypeKind.TUPLE, args=[inner]), optional=optional
+            )
+        inners = [type_to_typespec(a, optional=False) for a in args]
+        return _merge_optional(
+            TypeSpec(kind=TypeKind.TUPLE, args=inners), optional=optional
+        )
+
+    if origin is typing.Callable or origin is CallableABC:
+        if args:
+            param_args, ret = args[0], args[1]
+            if (
+                get_origin(param_args) is list
+            ):  # pragma: no cover — rare Callable[..., T] shape; else path covers real callables
+                plist = get_args(param_args)
+                plist_ts = TypeSpec(
+                    kind=TypeKind.LIST,
+                    args=[type_to_typespec(p, optional=False) for p in plist],
+                )
+            else:
+                plist_ts = type_to_typespec(param_args, optional=False)
+            ret_ts = type_to_typespec(ret, optional=False)
+            return _merge_optional(
+                TypeSpec(kind=TypeKind.CALLABLE, args=[plist_ts, ret_ts]),
+                optional=optional,
+            )
+        return _merge_optional(
+            TypeSpec(kind=TypeKind.CALLABLE, args=None), optional=optional
+        )
+
+    if isinstance(t, TypeVar):
+        return _merge_optional(TypeSpec(kind=TypeKind.TYPE_VAR), optional=optional)
+
+    if origin is not None:
+        if args:
+            inner_args = [type_to_typespec(a, optional=False) for a in args]
+            return _merge_optional(
+                TypeSpec(kind=TypeKind.GENERIC, args=inner_args), optional=optional
+            )
+        return _merge_optional(
+            TypeSpec(kind=TypeKind.GENERIC, args=[]), optional=optional
+        )
+
+    if isinstance(t, type):
+        if t is int:
+            return _merge_optional(TypeSpec(kind=TypeKind.INT), optional=optional)
+        if t is float:
+            return _merge_optional(TypeSpec(kind=TypeKind.FLOAT), optional=optional)
+        if t is bool:
+            return _merge_optional(TypeSpec(kind=TypeKind.BOOL), optional=optional)
+        if t is str:
+            return _merge_optional(TypeSpec(kind=TypeKind.STR), optional=optional)
+        if t is bytes:
+            return _merge_optional(TypeSpec(kind=TypeKind.BYTES), optional=optional)
+        if t is datetime.datetime:
+            return _merge_optional(TypeSpec(kind=TypeKind.DATETIME), optional=optional)
+        if t is datetime.date:
+            return _merge_optional(TypeSpec(kind=TypeKind.DATE), optional=optional)
+        if t is datetime.time:
+            return _merge_optional(TypeSpec(kind=TypeKind.TIME), optional=optional)
+        if issubclass(t, Enum):
+            members = [TypeSpec(kind=TypeKind.LITERAL, default=m.value) for m in t]
+            u = (
+                TypeSpec(kind=TypeKind.ENUM, args=members)
+                if members
+                else TypeSpec(kind=TypeKind.ANY)
+            )
+            return _merge_optional(u, optional=optional)
+        return _merge_optional(TypeSpec(kind=TypeKind.ANY), optional=optional)
+
+    return _merge_optional(TypeSpec(kind=TypeKind.ANY), optional=optional)
+
+
+def annotation_to_typespec(
+    annotation: Any, *, globalns: dict[str, Any] | None = None
+) -> TypeSpec:
+    """Resolve string annotations and return TypeSpec."""
+    if isinstance(annotation, str):
+        if globalns is None:
+            return TypeSpec(kind=TypeKind.ANY)
+        try:
+            anno = eval(annotation, globalns, globalns)  # noqa: S307
+            return normalize_typespec(type_to_typespec(anno, optional=False))
+        except Exception:
+            return TypeSpec(kind=TypeKind.ANY)
+    return normalize_typespec(type_to_typespec(annotation, optional=False))

velarium-0.1.0/velarium/ir.py

@@ -0,0 +1,86 @@
+"""ModelSpec intermediate representation (see docs/modelspec-ir.md)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+
+class TypeKind(str, Enum):
+    # Primitives
+    INT = "int"
+    FLOAT = "float"
+    BOOL = "bool"
+    STR = "str"
+    BYTES = "bytes"
+
+    # Complex
+    LIST = "list"
+    TUPLE = "tuple"
+    DICT = "dict"
+    SET = "set"
+
+    # Special
+    UNION = "union"
+    LITERAL = "literal"
+    ENUM = "enum"
+    ANY = "any"
+    NONE = "none"
+
+    # Temporal
+    DATETIME = "datetime"
+    DATE = "date"
+    TIME = "time"
+    TIMESTAMP = "timestamp"
+
+    # Advanced
+    GENERIC = "generic"
+    CALLABLE = "callable"
+    TYPE_VAR = "typevar"
+
+
+@dataclass
+class TypeSpec:
+    kind: TypeKind
+    args: list[TypeSpec] | None = None
+    optional: bool = False
+    nullable: bool = False
+    default: Any | None = None
+
+
+@dataclass
+class ModelConfig:
+    frozen: bool = False
+    extra: Literal["allow", "forbid", "ignore"] = "forbid"
+    validate_assignment: bool = True
+    from_attributes: bool = True
+    strict: bool = False
+
+
+@dataclass
+class FieldSpec:
+    name: str
+    type: TypeSpec
+    required: bool
+    default: Any | None = None
+    alias: str | None = None
+    description: str | None = None
+    deprecated: bool = False
+
+
+@dataclass
+class ModelMetadata:
+    source_module: str | None = None
+    source_file: str | None = None
+    line_number: int | None = None
+    generated_by: str = "velarium"
+    version: str | None = None
+
+
+@dataclass
+class ModelSpec:
+    name: str
+    fields: dict[str, TypeSpec] = field(default_factory=dict)
+    config: ModelConfig | None = None
+    metadata: ModelMetadata | None = None

velarium-0.1.0/velarium/json_codec.py

@@ -0,0 +1,156 @@
+"""JSON serialization for ModelSpec IR (deterministic, round-trippable)."""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any
+
+from velarium.ir import (
+    FieldSpec,
+    ModelConfig,
+    ModelMetadata,
+    ModelSpec,
+    TypeKind,
+    TypeSpec,
+)
+
+
+def _typespec_from_dict(d: dict[str, Any]) -> TypeSpec:
+    args = d.get("args")
+    if args is not None:
+        args = [_typespec_from_dict(x) if isinstance(x, dict) else x for x in args]
+    return TypeSpec(
+        kind=TypeKind(d["kind"]),
+        args=args,
+        optional=d.get("optional", False),
+        nullable=d.get("nullable", False),
+        default=d.get("default", None),
+    )
+
+
+def _json_default_value(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    try:
+        json.dumps(value)
+    except TypeError:
+        return {"_velarium_repr": repr(value)}
+    return value
+
+
+def typespec_to_dict(ts: TypeSpec) -> dict[str, Any]:
+    out: dict[str, Any] = {"kind": ts.kind.value}
+    if ts.args is not None:
+        out["args"] = [typespec_to_dict(a) for a in ts.args]
+    if ts.optional:
+        out["optional"] = True
+    if ts.nullable:
+        out["nullable"] = True
+    if ts.default is not None:
+        out["default"] = _json_default_value(ts.default)
+    return out
+
+
+def typespec_from_dict(d: dict[str, Any]) -> TypeSpec:
+    return _typespec_from_dict(d)
+
+
+def model_spec_to_dict(m: ModelSpec) -> dict[str, Any]:
+    out: dict[str, Any] = {
+        "name": m.name,
+        "fields": {k: typespec_to_dict(v) for k, v in m.fields.items()},
+    }
+    if m.config is not None:
+        c = m.config
+        out["config"] = {
+            "frozen": c.frozen,
+            "extra": c.extra,
+            "validate_assignment": c.validate_assignment,
+            "from_attributes": c.from_attributes,
+            "strict": c.strict,
+        }
+    if m.metadata is not None:
+        md = m.metadata
+        out["metadata"] = {
+            "source_module": md.source_module,
+            "source_file": md.source_file,
+            "line_number": md.line_number,
+            "generated_by": md.generated_by,
+            "version": md.version,
+        }
+    return out
+
+
+def model_spec_from_dict(d: dict[str, Any]) -> ModelSpec:
+    fields_raw = d.get("fields") or {}
+    fields = {k: typespec_from_dict(v) for k, v in fields_raw.items()}
+    config = None
+    if "config" in d and d["config"] is not None:
+        c = d["config"]
+        config = ModelConfig(
+            frozen=c.get("frozen", False),
+            extra=c.get("extra", "forbid"),
+            validate_assignment=c.get("validate_assignment", True),
+            from_attributes=c.get("from_attributes", True),
+            strict=c.get("strict", False),
+        )
+    metadata = None
+    if "metadata" in d and d["metadata"] is not None:
+        md = d["metadata"]
+        metadata = ModelMetadata(
+            source_module=md.get("source_module"),
+            source_file=md.get("source_file"),
+            line_number=md.get("line_number"),
+            generated_by=md.get("generated_by", "velarium"),
+            version=md.get("version"),
+        )
+    return ModelSpec(
+        name=d["name"],
+        fields=fields,
+        config=config,
+        metadata=metadata,
+    )
+
+
+def field_spec_to_dict(f: FieldSpec) -> dict[str, Any]:
+    out: dict[str, Any] = {
+        "name": f.name,
+        "type": typespec_to_dict(f.type),
+        "required": f.required,
+        "default": f.default,
+        "alias": f.alias,
+        "description": f.description,
+        "deprecated": f.deprecated,
+    }
+    return {
+        k: v
+        for k, v in out.items()
+        if v is not None or k in ("name", "type", "required")
+    }
+
+
+def field_spec_from_dict(d: dict[str, Any]) -> FieldSpec:
+    return FieldSpec(
+        name=d["name"],
+        type=typespec_from_dict(d["type"]),
+        required=d["required"],
+        default=d.get("default"),
+        alias=d.get("alias"),
+        description=d.get("description"),
+        deprecated=d.get("deprecated", False),
+    )
+
+
+def dumps_model_spec(m: ModelSpec, *, indent: int | None = 2) -> str:
+    """Serialize ModelSpec to JSON with stable key ordering."""
+    return json.dumps(
+        model_spec_to_dict(m),
+        indent=indent,
+        sort_keys=True,
+        default=_json_default_value,
+    )
+
+
+def loads_model_spec(s: str) -> ModelSpec:
+    return model_spec_from_dict(json.loads(s))

velarium-0.1.0/velarium/modelspec_build.py

@@ -0,0 +1,101 @@
+"""Build ModelSpec from Python classes (dataclasses MVP)."""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import sys
+from typing import Any, get_type_hints
+
+from typing_extensions import is_typeddict
+
+from velarium.annotations import annotation_to_typespec, type_to_typespec
+from velarium.ir import ModelConfig, ModelMetadata, ModelSpec, TypeSpec
+from velarium.normalize import normalize_typespec
+
+
+def _module_globals(cls: type) -> dict[str, Any]:
+    mod = sys.modules.get(cls.__module__)
+    if mod is None:
+        return dict(vars(cls))
+    g = dict(vars(mod))
+    g.setdefault(cls.__name__, cls)
+    return g
+
+
+def modelspec_from_dataclass(cls: type, *, include_extras: bool = False) -> ModelSpec:
+    """Extract ModelSpec from a dataclass type."""
+    if not dataclasses.is_dataclass(cls):
+        raise TypeError(f"{cls!r} is not a dataclass")
+
+    globalns = _module_globals(cls)
+    try:
+        hints = get_type_hints(
+            cls, globalns=globalns, localns=None, include_extras=include_extras
+        )
+    except Exception:
+        hints = {}
+
+    fields: dict[str, TypeSpec] = {}
+    for f in dataclasses.fields(cls):
+        if not f.init:
+            continue
+        raw = hints.get(f.name, f.type if hasattr(f, "type") else Any)
+        ts = annotation_to_typespec(raw, globalns=globalns)
+        ts = normalize_typespec(ts)
+        if f.default is not dataclasses.MISSING:
+            ts = TypeSpec(
+                kind=ts.kind,
+                args=ts.args,
+                optional=ts.optional,
+                nullable=ts.nullable,
+                default=f.default,
+            )
+        fields[f.name] = ts
+
+    src_file = None
+    line_number = None
+    try:
+        src_file = inspect.getsourcefile(cls)
+        lines, start = inspect.getsourcelines(cls)
+        line_number = start
+    except (OSError, TypeError):
+        pass
+
+    meta = ModelMetadata(
+        source_module=cls.__module__,
+        source_file=src_file,
+        line_number=line_number,
+        generated_by="velarium",
+        version=None,
+    )
+    params = getattr(cls, "__dataclass_params__", None)
+    frozen = bool(getattr(params, "frozen", False)) if params is not None else False
+    cfg = ModelConfig(frozen=frozen, extra="forbid")
+
+    return ModelSpec(name=cls.__name__, fields=fields, config=cfg, metadata=meta)
+
+
+def modelspec_from_typed_dict(cls: type) -> ModelSpec:
+    """Extract ModelSpec from typing.TypedDict (total fields only for MVP)."""
+    if not is_typeddict(cls):
+        raise TypeError(f"{cls!r} is not a TypedDict")
+
+    globalns = _module_globals(cls)
+    try:
+        hints = get_type_hints(cls, globalns=globalns)
+    except Exception:
+        hints = {}
+
+    fields: dict[str, TypeSpec] = {}
+    for name, typ in getattr(cls, "__annotations__", {}).items():
+        ts = annotation_to_typespec(hints.get(name, typ), globalns=globalns)
+        fields[name] = normalize_typespec(ts)
+
+    meta = ModelMetadata(source_module=cls.__module__, generated_by="velarium")
+    return ModelSpec(name=cls.__name__, fields=fields, config=None, metadata=meta)
+
+
+def typespec_from_object(obj: Any) -> TypeSpec:
+    """Convenience: typing object or type -> TypeSpec."""
+    return normalize_typespec(type_to_typespec(obj, optional=False))

velarium-0.1.0/velarium/normalize.py

@@ -0,0 +1,98 @@
+"""Normalize TypeSpec unions per docs/modelspec-ir.md (flatten, dedupe, preserve order)."""
+
+from __future__ import annotations
+
+from velarium.ir import TypeKind, TypeSpec
+
+
+def normalize_union(ts: TypeSpec) -> TypeSpec:
+    """Flatten nested unions, remove duplicates, preserve first-seen order."""
+    if ts.kind != TypeKind.UNION:
+        return ts
+    flat: list[TypeSpec] = []
+    seen: list[str] = []
+
+    def json_key_obj(d: object) -> str:
+        import json
+
+        return json.dumps(d, sort_keys=True)
+
+    def key(x: TypeSpec) -> str:
+        from velarium.json_codec import typespec_to_dict
+
+        return json_key_obj(typespec_to_dict(x))
+
+    stack = list(ts.args or [])
+    while stack:
+        cur = stack.pop(0)
+        if cur.kind == TypeKind.UNION and cur.args:
+            stack = list(cur.args) + stack
+            continue
+        k = key(cur)
+        if k not in seen:
+            seen.append(k)
+            flat.append(cur)
+    if len(flat) == 1:
+        u = flat[0]
+        return TypeSpec(
+            kind=u.kind,
+            args=u.args,
+            optional=ts.optional or u.optional,
+            nullable=ts.nullable or u.nullable,
+            default=ts.default if ts.default is not None else u.default,
+        )
+    return TypeSpec(
+        kind=TypeKind.UNION,
+        args=flat,
+        optional=ts.optional,
+        nullable=ts.nullable,
+        default=ts.default,
+    )
+
+
+def normalize_typespec(ts: TypeSpec) -> TypeSpec:
+    """Recursively normalize unions and nested structures."""
+    args = ts.args
+    if args:
+        args = [normalize_typespec(a) for a in args]
+    out = TypeSpec(
+        kind=ts.kind,
+        args=args,
+        optional=ts.optional,
+        nullable=ts.nullable,
+        default=ts.default,
+    )
+    if out.kind == TypeKind.UNION:
+        return normalize_union(out)
+    return out
+
+
+def optional_to_union(ts: TypeSpec) -> TypeSpec:
+    """
+    Encode Optional[T] as Union[T, None] with optional=True per spec.
+    If ts already includes none, ensure optional flag is set.
+    """
+    if not ts.optional:
+        return ts
+    none = TypeSpec(kind=TypeKind.NONE)
+    if ts.kind == TypeKind.UNION and ts.args:
+        members = list(ts.args)
+        has_none = any(m.kind == TypeKind.NONE for m in members)
+        if not has_none:
+            members.append(none)
+        u = TypeSpec(
+            kind=TypeKind.UNION,
+            args=members,
+            optional=True,
+            nullable=ts.nullable,
+            default=ts.default,
+        )
+        return normalize_union(u)
+    u = TypeSpec(
+        kind=TypeKind.UNION,
+        args=[ts, none],
+        optional=True,
+        nullable=ts.nullable,
+        default=ts.default,
+    )
+    return normalize_union(u)