typebind 0.1.0a1__py3-none-any.whl

typebind/__init__.py

@@ -0,0 +1,37 @@
+"""Explicit, hierarchical discriminated models backed by Pydantic."""
+
+from ._behavior import BehaviorAdapter, Implementation, assemble
+from ._discovery import (
+    DiscoveredImplementation,
+    DiscoveredVariant,
+    discover,
+    discover_variants,
+    select_implementations,
+    select_variants,
+)
+from ._models import (
+    DiscriminatedModel,
+    IdentityDiscriminatedModel,
+    bind_variants,
+    build_adapter,
+    model,
+    tag_field,
+)
+
+__all__ = [
+    "BehaviorAdapter",
+    "Implementation",
+    "assemble",
+    "DiscoveredImplementation",
+    "discover",
+    "select_implementations",
+    "DiscoveredVariant",
+    "DiscriminatedModel",
+    "IdentityDiscriminatedModel",
+    "bind_variants",
+    "build_adapter",
+    "discover_variants",
+    "select_variants",
+    "tag_field",
+    "model",
+]

typebind/_behavior.py

@@ -0,0 +1,202 @@
+"""Assemble typed object adapters independently of model validation and discovery."""
+
+from collections.abc import Iterable
+from inspect import isabstract, signature
+from types import MappingProxyType, get_original_bases
+from typing import (
+    Any,
+    Protocol,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from typing_extensions import get_protocol_members, is_protocol
+
+from ._models import DiscriminatedModel, concrete_model, family_base
+
+
+def _name(cls: type[object]) -> str:
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+class Implementation[T: DiscriminatedModel]:
+    """Hold a model without copying or validating it; specialize with its concrete type.
+
+    Implement interfaces through ordinary explicit Protocol inheritance. The
+    read-only property preserves precise model types without modifying the model
+    class. Each adaptation creates a new implementation instance.
+    """
+
+    def __init__(self, model: T) -> None:
+        self._model = model
+
+    @property
+    def model(self) -> T:
+        """The original model, whose lifetime is shared with this adapter object."""
+        return self._model
+
+
+def _implementation_class(value: object) -> type[Implementation[Any]]:
+    if not isinstance(value, type) or not issubclass(value, Implementation):
+        raise TypeError(f"Expected an Implementation class; got {value!r}")
+    return cast(type[Implementation[Any]], value)
+
+
+def _implementation_model(implementation: type[Implementation[Any]]) -> type[DiscriminatedModel]:
+    """Resolve native generic bases, including type-variable forwarding through mixins."""
+    targets: set[type[DiscriminatedModel]] = set()
+
+    def visit(cls: type[object], substitutions: dict[TypeVar, object]) -> None:
+        for base in get_original_bases(cls):
+            origin: object = get_origin(base) or base
+            if not isinstance(origin, type):
+                continue
+            arguments = tuple(
+                substitutions.get(arg, arg) if isinstance(arg, TypeVar) else arg
+                for arg in get_args(base)
+            )
+            if origin is Implementation:
+                if len(arguments) != 1:
+                    raise TypeError(
+                        f"{_name(implementation)}: expected Implementation[ConcreteModel], "
+                        "not a bare base"
+                    )
+                targets.add(concrete_model(arguments[0]))
+            elif issubclass(origin, Implementation):
+                parent = cast(type[Implementation[Any]], origin)
+                parameters = cast(tuple[TypeVar, ...], getattr(parent, "__parameters__", ()))
+                visit(parent, dict(zip(parameters, arguments, strict=True)))
+
+    visit(implementation, {})
+    if len(targets) != 1:
+        raise TypeError(
+            f"{_name(implementation)}: expected exactly one concrete Implementation[Model] target"
+        )
+    return next(iter(targets))
+
+
+def _interface_family(interface: object) -> type[DiscriminatedModel]:
+    """Read the interface's native property annotation as the authoritative family."""
+    if not isinstance(interface, type) or not is_protocol(interface):
+        raise TypeError(f"Expected a Protocol interface; got {interface!r}")
+    member: object = getattr(interface, "model", None)
+    if not isinstance(member, property) or member.fget is None or member.fset is not None:
+        raise TypeError(
+            f"{_name(interface)}: declare a read-only model property returning a family"
+        )
+    try:
+        family: object = get_type_hints(member.fget).get("return")
+        return family_base(family)
+    except Exception as error:
+        error.add_note(f"Interface family: {_name(interface)}.model")
+        raise
+
+
+class BehaviorAdapter:
+    """An assembled scope, with exact-class lookup and fresh adapter objects.
+
+    Construct with assemble(). No model parsing, reflection, discovery, family
+    checking, or fallback search occurs on the successful adapt path. Interface
+    methods dispatch normally after adaptation. Unknown pairs raise LookupError.
+    """
+
+    def __init__(
+        self,
+        *,
+        variants: Iterable[type[DiscriminatedModel]],
+        implementations: Iterable[type[Implementation[Any]]],
+        required_interfaces: Iterable[type[object]] = (),
+    ) -> None:
+        models = dict.fromkeys(concrete_model(model) for model in variants)
+        families: dict[type[object], type[DiscriminatedModel]] = {}
+        required = tuple(dict.fromkeys(required_interfaces))
+        for interface in required:
+            families[interface] = _interface_family(interface)
+        factories: dict[
+            tuple[type[DiscriminatedModel], type[object]], type[Implementation[Any]]
+        ] = {}
+        for candidate in dict.fromkeys(implementations):
+            implementation = _implementation_class(candidate)
+            try:
+                model = _implementation_model(implementation)
+                if model not in models:
+                    continue
+                if isabstract(implementation):
+                    raise TypeError("Cannot assemble an abstract implementation")
+                # Do not execute constructors during assembly. They must accept
+                # one model; optional constructor dependencies remain possible.
+                signature(implementation).bind(object())
+                interfaces = tuple(base for base in implementation.__mro__ if is_protocol(base))
+                for interface in interfaces:
+                    # Only model-bound Protocols declare behavior interfaces.
+                    # Ordinary orthogonal Protocols may coexist on the object.
+                    if interface is Protocol or "model" not in get_protocol_members(interface):
+                        continue
+                    if interface not in families:
+                        families[interface] = _interface_family(interface)
+                    if not issubclass(model, families[interface]):
+                        raise TypeError(
+                            f"{_name(model)} is outside interface {_name(interface)} "
+                            f"family {_name(families[interface])}"
+                        )
+                    key = model, interface
+                    previous = factories.get(key)
+                    if previous is not None and previous is not implementation:
+                        raise ValueError(
+                            f"Duplicate implementation for {_name(model)} / "
+                            f"{_name(interface)}: {_name(previous)} and "
+                            f"{_name(implementation)}"
+                        )
+                    factories[key] = implementation
+            except Exception as error:
+                error.add_note(f"Behavior implementation: {_name(implementation)}")
+                raise
+        for model in models:
+            for interface in required:
+                if issubclass(model, families[interface]) and (model, interface) not in factories:
+                    raise ValueError(
+                        f"Missing implementation for {_name(model)} / {_name(interface)}"
+                    )
+        self._factories = MappingProxyType(factories)
+
+    def adapt[I](self, model: DiscriminatedModel, interface: type[I]) -> I:
+        """Bind an existing model to an interface; preserve the static interface type.
+
+        The heterogeneous table was checked at assembly. This local cast restores
+        its dependent result type; callers never need a cast. Plugins remain
+        trusted Python code, and their method signatures are checked statically.
+        """
+        try:
+            factory = self._factories[type(model), interface]
+        except KeyError:
+            raise LookupError(
+                f"No implementation in this scope for {_name(type(model))} / {interface!r}"
+            ) from None
+        return cast(I, factory(model))
+
+
+def assemble(
+    *,
+    variants: Iterable[type[DiscriminatedModel]],
+    implementations: Iterable[type[Implementation[Any]]],
+    required_interfaces: Iterable[type[object]] = (),
+) -> BehaviorAdapter:
+    """Build a scope snapshot and validate every applicable required interface.
+
+    Only exact targets in variants participate in dispatch/conflict/coverage
+    checks; other targets can coexist in the discovered sources. Repeated class
+    identities are harmless. Different implementations of the same pair fail,
+    regardless of publication order. Required interfaces apply to all selected
+    models in their family, including descendants of intermediate families.
+
+    A new scope requires a new assembly. There is no global registry, automatic
+    subclass fallback, object cache, or constructor execution during assembly.
+    """
+    return BehaviorAdapter(
+        variants=variants,
+        implementations=implementations,
+        required_interfaces=required_interfaces,
+    )

typebind/_discovery.py

@@ -0,0 +1,181 @@
+"""Discover published models once, then select explicit family and source scopes."""
+
+from collections.abc import Callable, Iterable, Iterator
+from importlib import metadata
+from itertools import chain
+from typing import Any, NamedTuple, cast
+
+from ._behavior import Implementation
+from ._models import DiscriminatedModel, family_base
+
+
+class DiscoveredVariant(NamedTuple):
+    """A loaded model and its native publication metadata, without derived tags."""
+
+    model: type[DiscriminatedModel]
+    entry_point: metadata.EntryPoint
+
+
+def _source(entry: metadata.EntryPoint) -> str:
+    """Describe an entry point without losing its providing distribution."""
+    distribution = entry.dist.metadata["Name"] if entry.dist is not None else "<unknown>"
+    return (
+        f"distribution={distribution!r}, group={entry.group!r}, "
+        f"name={entry.name!r}, value={entry.value!r}"
+    )
+
+
+def _group_names(groups: Iterable[str]) -> frozenset[str]:
+    """Consume a source scope once, rejecting accidental character scopes."""
+    if isinstance(groups, str):
+        raise TypeError(
+            "groups must be an iterable of group names, not a single string; use {name}"
+        )
+    return frozenset(groups)
+
+
+def discover_variants(
+    *,
+    groups: Iterable[str],
+    include: Callable[[metadata.EntryPoint], bool] | None = None,
+) -> tuple[DiscoveredVariant, ...]:
+    """Load model classes from selected installed entry point groups in one batch.
+
+    Enumerate metadata once; load each selected entry record once. ``include``
+    filters native metadata before loading, so excluded entries are not imported.
+    Groups may mix families. Preserve every source record, even when multiple
+    records publish the same class or use the same entry name. No global cache,
+    subclass scanning, instantiation, or tag validation is performed here.
+
+    Loading failures retain their original exception and gain a source-context
+    note; non-model exports raise TypeError. Predicate errors propagate unchanged.
+    Groups are consumed once; a single string raises TypeError before discovery.
+    Empty or absent groups yield an empty tuple. Loading executes plugin Python
+    code; a later selection cannot undo import side effects.
+    """
+    discovered: list[DiscoveredVariant] = []
+    for model, entry in _load_entries(groups, include, label="Model"):
+        if not isinstance(model, type) or not issubclass(model, DiscriminatedModel):
+            raise TypeError(
+                f"Model entry point must export a DiscriminatedModel class ({_source(entry)}); "
+                f"got {model!r}"
+            )
+        discovered.append(DiscoveredVariant(model, entry))
+    return tuple(discovered)
+
+
+class DiscoveredImplementation(NamedTuple):
+    """A behavior implementation and its unmodified publication metadata."""
+
+    implementation: type[Implementation[Any]]
+    entry_point: metadata.EntryPoint
+
+
+def _load_entries(
+    groups: Iterable[str],
+    include: Callable[[metadata.EntryPoint], bool] | None,
+    *,
+    label: str,
+) -> Iterator[tuple[object, metadata.EntryPoint]]:
+    selected_groups = _group_names(groups)
+    if not selected_groups:
+        return
+    for entry in metadata.entry_points():
+        if entry.group not in selected_groups or (include is not None and not include(entry)):
+            continue
+        try:
+            value: object = entry.load()
+        except Exception as error:
+            error.add_note(f"{label} entry point: {_source(entry)}")
+            raise
+        yield value, entry
+
+
+def discover(
+    *,
+    groups: Iterable[str],
+    include: Callable[[metadata.EntryPoint], bool] | None = None,
+) -> tuple[DiscoveredVariant | DiscoveredImplementation, ...]:
+    """Discover models and behavior implementations together in one metadata scan.
+
+    Groups may mix export kinds and families. Source filters run before loading.
+    Preserve all publications for subsequent scope selection, including duplicate
+    class exports. Loading failures keep their identity and gain a source note.
+    Declaration reflection, family checks, conflicts and coverage belong to
+    assembly, not discovery. Use discover_variants for model-only consumers.
+    """
+    found: list[DiscoveredVariant | DiscoveredImplementation] = []
+    for value, entry in _load_entries(groups, include, label="Plugin"):
+        if isinstance(value, type) and issubclass(value, DiscriminatedModel):
+            found.append(DiscoveredVariant(value, entry))
+        elif isinstance(value, type) and issubclass(value, Implementation):
+            found.append(DiscoveredImplementation(cast(type[Implementation[Any]], value), entry))
+        else:
+            raise TypeError(
+                f"Plugin entry point must export a DiscriminatedModel or Implementation class "
+                f"({_source(entry)}); got {value!r}"
+            )
+    return tuple(found)
+
+
+def select_implementations(
+    discovered: Iterable[DiscoveredVariant | DiscoveredImplementation],
+    *,
+    groups: Iterable[str] | None = None,
+    extra_implementations: Iterable[type[Implementation[Any]]] = (),
+) -> tuple[type[Implementation[Any]], ...]:
+    """Select behavior sources using the same group scope semantics as models.
+
+    Extras bypass source filters. Deduplicate class identities after filtering.
+    Target-model and interface-family resolution happen only during assembly,
+    where the selected variants define the data scope.
+    """
+    selected_groups = None if groups is None else _group_names(groups)
+    published = (
+        item.implementation
+        for item in discovered
+        if isinstance(item, DiscoveredImplementation)
+        and (selected_groups is None or item.entry_point.group in selected_groups)
+    )
+    selected: dict[int, type[Implementation[Any]]] = {}
+    for implementation in chain(published, extra_implementations):
+        selected.setdefault(id(implementation), implementation)
+    return tuple(selected.values())
+
+
+def select_variants(
+    discovered: Iterable[DiscoveredVariant | DiscoveredImplementation],
+    *,
+    family: type[DiscriminatedModel],
+    groups: Iterable[str] | None = None,
+    extra_variants: Iterable[type[DiscriminatedModel]] = (),
+) -> tuple[type[DiscriminatedModel], ...]:
+    """Select model descendants from published and explicitly supplied types.
+
+    ``groups=None`` accepts all discovered sources; an empty iterable accepts
+    none. A single string raises TypeError; other iterables are consumed once.
+    Source filtering does not apply to ``extra_variants``. Both sources
+    are filtered by native family ancestry and deduplicated by class identity.
+    Open views such as Family[Any] resolve to their native generic origin; this
+    is a family query, not a claim of static assignability to Family[str]. Named
+    classes and closed specializations keep their native issubclass constraints;
+    DiscriminatedModel selects every model. An open discriminator is not required.
+
+    Preserve first occurrence order, without giving it conflict precedence.
+    No metadata is read or plugins loaded. Empty matches are valid; tagged-leaf
+    and duplicate-tag checks belong to bind_variants/build_adapter. The input
+    snapshot and model declarations remain unchanged.
+    """
+    base = family_base(family)
+    selected_groups = None if groups is None else _group_names(groups)
+    published = (
+        item.model
+        for item in discovered
+        if isinstance(item, DiscoveredVariant)
+        and (selected_groups is None or item.entry_point.group in selected_groups)
+    )
+    selected: dict[int, type[DiscriminatedModel]] = {}
+    for model in chain(published, extra_variants):
+        if issubclass(model, base):
+            selected.setdefault(id(model), model)
+    return tuple(selected.values())

typebind/_models.py

@@ -0,0 +1,584 @@
+"""Generic/decorator declarations and explicit Pydantic discriminated unions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from inspect import isabstract
+from typing import Annotated, Any, ClassVar, Literal, Self, TypeVar, cast
+
+from pydantic import (
+    BaseModel,
+    Field,
+    GetCoreSchemaHandler,
+    GetPydanticSchema,
+    TypeAdapter,
+    create_model,
+    model_validator,
+)
+from pydantic.fields import FieldInfo
+from pydantic_core import CoreSchema, core_schema
+
+# A declaration-style marker, stored only on generated fields. Tag names and
+# values are still read exclusively from the finalized Pydantic model_fields.
+_DECORATED_TAG = object()
+
+
+def _decorated_field(field: FieldInfo) -> bool:
+    return any(item is _DECORATED_TAG for item in field.metadata)
+
+
+def _tag_default() -> object:
+    """Identify tag declarations; unchecked construction must supply tags itself."""
+    raise ValueError(
+        "Automatic tag defaults were not compiled. "
+        "When using model_construct(), supply tags explicitly. "
+        "If overriding __get_pydantic_core_schema__, preserve the "
+        "DiscriminatedModel schema hook by calling super()."
+    )
+
+
+def tag_field() -> Any:
+    """Declare this level's discriminator as a native frozen Pydantic field.
+
+    The private default factory identifies tag fields after native field merging
+    and generic substitution. Schema generation replaces it with a validated
+    native default for bound tags, or a required field for open tags.
+    DiscriminatedModel keeps native unset semantics; IdentityDiscriminatedModel
+    additionally marks bound tags as set through Pydantic's public validator API.
+
+    Like Pydantic's Field, this helper returns Any for assignment to a typed
+    field. The explicit annotation owns the field and constructor argument types;
+    the assigned default makes the argument optional to static type checkers.
+    """
+    return Field(default_factory=_tag_default, frozen=True)
+
+
+def _model_name(model: type[BaseModel]) -> str:
+    """Identify declarations unambiguously across extension packages."""
+    return f"{model.__module__}.{model.__qualname__}"
+
+
+def _tag_fields(model: type[DiscriminatedModel]) -> dict[str, FieldInfo]:
+    """Read marked fields after Pydantic's native merging and specialization."""
+    return {
+        name: field
+        for name, field in model.model_fields.items()
+        if field.default_factory is _tag_default
+    }
+
+
+def _is_open_tag(annotation: object) -> bool:
+    """Recognize the unbound field types supported by family views and consumers."""
+    return annotation is str or annotation is Any or isinstance(annotation, TypeVar)
+
+
+def _open_discriminator(model: type[DiscriminatedModel]) -> str | None:
+    """Read the open discriminator of an already checked model, if any."""
+    return next(
+        (name for name, field in _tag_fields(model).items() if _is_open_tag(field.annotation)),
+        None,
+    )
+
+
+def _bound_names(model: type[DiscriminatedModel]) -> tuple[str, ...]:
+    """Compile the identity field names from authoritative resolved fields."""
+    return tuple(
+        name for name, field in _tag_fields(model).items() if not _is_open_tag(field.annotation)
+    )
+
+
+def _literal_tag(model: type[DiscriminatedModel], name: str) -> str:
+    """Resolve the authoritative field through Pydantic at declaration/assembly time."""
+    annotation = model.model_fields[name].annotation
+    schema = TypeAdapter(cast(Any, annotation)).core_schema
+    if schema["type"] == "literal" and len(schema["expected"]) == 1:
+        value: object = schema["expected"][0]
+        if isinstance(value, str) and value:
+            return value
+    raise TypeError(
+        f"{_model_name(model)}.{name}: a tag must be a single non-empty string Literal; "
+        f"got {annotation!r}. Select a tag with Family[Literal['tag']]."
+    )
+
+
+def _with_tag_defaults(schema: CoreSchema, model: type[DiscriminatedModel]) -> CoreSchema:
+    """Compile defaults on this model's fields, preserving Pydantic's validator wrappers.
+
+    Copy only the model spine and marked fields during schema generation. Payload
+    schemas and referenced models retain their native definitions. Reference nodes
+    already point to schemas built by the referenced model's own hook.
+    """
+    if schema["type"] == "model-fields":
+        inner = schema
+        fields = dict(inner["fields"])
+        for name, field in _tag_fields(model).items():
+            original = fields[name]["schema"]
+            # Pydantic can hand the hook an existing schema when embedding a model.
+            if original["type"] != "default":
+                continue
+            default = cast(core_schema.WithDefaultSchema, original)
+            if default.get("default_factory") is not _tag_default:
+                continue
+            resolved = default["schema"]
+            if not _is_open_tag(field.annotation):
+                resolved = core_schema.with_default_schema(
+                    resolved, default=_literal_tag(model, name), validate_default=True
+                )
+            fields[name] = {**fields[name], "schema": resolved}
+        return {**inner, "fields": fields}
+    if schema["type"] == "model":
+        return {**schema, "schema": _with_tag_defaults(schema["schema"], model)}
+    if schema["type"] in ("function-before", "function-after", "function-wrap"):
+        wrapper = cast(
+            core_schema.BeforeValidatorFunctionSchema
+            | core_schema.AfterValidatorFunctionSchema
+            | core_schema.WrapValidatorFunctionSchema,
+            schema,
+        )
+        updated = wrapper.copy()
+        updated["schema"] = _with_tag_defaults(wrapper["schema"], model)
+        return updated
+    return schema
+
+
+class DiscriminatedModel(BaseModel):
+    """Declare model families with one discriminator per level.
+
+    A family declares a str-bound type parameter and marks its field with
+    ``tag_field()``. Subclasses select a tag through native
+    ``Family[Literal["tag"]]`` specialization and may introduce another family.
+    Alternatively, @model generates runtime-only tag fields.
+    The field declaration is the sole source of its name, type, and tag behavior.
+
+    These hooks validate declarations without storing a second tag definition;
+    Pydantic owns generic class creation and field substitution. Polymorphic dispatch is provided by
+    ``build_adapter``, not by direct validation of the family model. Omitted tag
+    defaults remain unset, as in BaseModel. Choose IdentityDiscriminatedModel at
+    the family root to retain bound tags in exclude_unset exports instead.
+    """
+
+    # Shared derived names for copy protection and optional identity marking.
+    _bound_tag_names: ClassVar[tuple[str, ...]] = ()
+
+    def model_copy(self, *, update: Mapping[str, Any] | None = None, deep: bool = False) -> Self:
+        """Copy using native semantics, rejecting updates to bound discriminator fields.
+
+        Even the same tag value is rejected. Other updates remain unvalidated,
+        as in BaseModel.model_copy; this is not a replacement for validation.
+        Only this copy operation checks updates; constructors and serializers
+        acquire no new callbacks or field scans.
+        """
+        if update:
+            for name in type(self)._bound_tag_names:
+                if name in update:
+                    raise ValueError(
+                        f"{_model_name(type(self))}.{name}: model_copy(update=...) cannot "
+                        "update a bound discriminator; omit it from update"
+                    )
+        return super().model_copy(update=update, deep=deep)
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source: type[BaseModel], handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        """Derive native defaults from specialized fields before schema compilation.
+
+        Pydantic owns validation, serialization, and generic substitution. Bound
+        defaults validate like explicit inputs; open tags remain required.
+        Omitted defaults retain native unset semantics. No marking validator or
+        runtime policy branch is registered by this base. The hook never mutates
+        model_fields or an already compiled validator/serializer.
+        """
+        schema = _with_tag_defaults(handler(source), cls)
+        cls._bound_tag_names = _bound_names(cls)
+        return schema
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        """Check native fields and inheritance without retaining a second tag definition.
+
+        Native specializations either bind one Literal tag or remain open views.
+        Named subclasses preserve fixed ancestor tags and optionally declare a
+        new tag_field. Invalid fields, inheritance, or tag declarations raise
+        TypeError. Remaining kwargs follow Pydantic's custom-hook contract; model
+        configuration has already been consumed.
+        """
+        super().__pydantic_init_subclass__(**kwargs)
+        # Also initialize deferred models, including explicit model_construct calls.
+        # Schema generation/rebuild refreshes this same derived tuple.
+        cls._bound_tag_names = _bound_names(cls)
+        parents = [base for base in cls.__bases__ if issubclass(base, DiscriminatedModel)]
+        if len(parents) != 1:
+            raise TypeError(
+                f"{_model_name(cls)}: exactly one DiscriminatedModel parent is supported; "
+                f"got {[_model_name(base) for base in parents]!r}. "
+                "Inherit from one family and use ordinary mixins for shared behavior."
+            )
+        parent = parents[0]
+        metadata = cls.__pydantic_generic_metadata__
+        origin = metadata["origin"]
+        if origin is not None:
+            # Native Pydantic owns field substitution and specialization caching.
+            assert issubclass(origin, DiscriminatedModel)
+            field_name = _open_discriminator(origin)
+            if field_name is None:
+                raise TypeError(
+                    f"{_model_name(cls)}: only an open discriminator family can be specialized; "
+                    f"{_model_name(origin)} has no open tag_field(). "
+                    "Specialize the family that declares the next discriminator."
+                )
+            annotation = cls.model_fields[field_name].annotation
+            if not _is_open_tag(annotation):
+                _literal_tag(cls, field_name)
+            return
+        parent_discriminator = _open_discriminator(parent)
+        if parent_discriminator is not None and not _decorated_field(
+            parent.model_fields[parent_discriminator]
+        ):
+            family = parent.__pydantic_generic_metadata__["origin"] or parent
+            raise TypeError(
+                f"{_model_name(cls)}.{parent_discriminator}: the inherited discriminator "
+                f"from {_model_name(family)} is still open. "
+                f"Inherit from {family.__name__}[Literal['tag']] to select its discriminator."
+            )
+        inherited_fields = _tag_fields(parent)
+        for name in inherited_fields:
+            if name not in cls.model_fields:
+                raise TypeError(
+                    f"{_model_name(cls)}.{name}: the inherited discriminator from "
+                    f"{_model_name(parent)} cannot be removed. Keep the inherited model field."
+                )
+            if _is_open_tag(parent.model_fields[name].annotation):
+                # Decorators run after class creation. Keep an inherited open
+                # decorator field pending until @model binds it. Assembly
+                # rejects any model whose discriminator is still open.
+                cls._check_tag_field(name)
+                annotation = cls.model_fields[name].annotation
+                if not _is_open_tag(annotation):
+                    _literal_tag(cls, name)
+                elif annotation is not str or not _decorated_field(cls.model_fields[name]):
+                    raise TypeError(f"{_model_name(cls)}.{name}: preserve the open family field")
+                continue
+            inherited_tag = _literal_tag(parent, name)
+            tag = _literal_tag(cls, name)
+            if tag != inherited_tag:
+                raise TypeError(
+                    f"{_model_name(cls)}.{name}: the inherited discriminator cannot be overridden; "
+                    f"{_model_name(parent)} fixes it to {inherited_tag!r}, got {tag!r}. "
+                    "Keep the inherited tag or specialize a different branch of its family."
+                )
+            cls._check_tag_field(name)
+        candidates = [name for name in _tag_fields(cls) if name not in inherited_fields]
+        if candidates and any(
+            _is_open_tag(cls.model_fields[name].annotation) for name in inherited_fields
+        ):
+            raise TypeError(
+                f"{_model_name(cls)}: bind the inherited discriminator before introducing "
+                "another family; use @model(tag='field', variant='value')"
+            )
+        if len(candidates) > 1:
+            raise TypeError(
+                f"{_model_name(cls)}: found new tag fields {candidates!r}. "
+                "Declare exactly one new tag_field per family; introduce another "
+                "discriminator in a child family."
+            )
+        discriminator = candidates[0] if candidates else None
+        if discriminator is not None:
+            parameters = metadata["parameters"]
+            field = cls.model_fields[discriminator]
+            if _decorated_field(field):
+                if parameters or field.annotation is not str:
+                    raise TypeError(
+                        f"{_model_name(cls)}.{discriminator}: a decorated family must "
+                        "introduce one non-generic string discriminator"
+                    )
+                cls._check_tag_field(discriminator)
+                return
+            if (
+                len(parameters) != 1
+                or cast(object, field.annotation) is not parameters[0]
+                or parameters[0].__bound__ is not str
+            ):
+                raise TypeError(
+                    f"{_model_name(cls)}.{discriminator}: Declare one str-bound type parameter "
+                    f"as the discriminator field; got annotation {field.annotation!r} "
+                    f"and type parameters {parameters!r}. Example: "
+                    f"class {cls.__name__}[Tag: str](...): {discriminator}: Tag = tag_field()"
+                )
+            cls._check_tag_field(discriminator)
+        elif metadata["parameters"]:
+            raise TypeError(
+                f"{_model_name(cls)}: a generic family must declare its discriminator "
+                f"with tag_field(); no marked field was found. Example: "
+                f"kind: {metadata['parameters'][0].__name__} = tag_field()"
+            )
+
+    @classmethod
+    def _check_tag_field(cls, name: str) -> None:
+        """Require a frozen tag field with our default factory and no alias/exclusion.
+
+        Raise TypeError for unsupported Field settings. Runtime freezing prevents
+        retagging; it does not impose covariance or a static read-only guarantee.
+        """
+        field = cls.model_fields[name]
+        unsupported = [
+            setting
+            for setting, invalid in (
+                ("default_factory", field.default_factory is not _tag_default),
+                ("frozen", field.frozen is not True),
+                ("alias", field.alias is not None),
+                ("validation_alias", field.validation_alias is not None),
+                ("serialization_alias", field.serialization_alias is not None),
+                ("exclude", bool(field.exclude)),
+                ("exclude_if", getattr(field, "exclude_if", None) is not None),
+            )
+            if invalid
+        ]
+        if unsupported:
+            raise TypeError(
+                f"{_model_name(cls)}.{name}: must use tag_field() without changing its factory, "
+                f"freezing, aliases, or exclusion. Unsupported settings: {', '.join(unsupported)}. "
+                "Remove those overrides or keep the inherited tag field."
+            )
+
+
+class IdentityDiscriminatedModel(DiscriminatedModel):
+    """Treat bound discriminator tags as set identity fields, even when omitted.
+
+    Choose this base when exclude_unset exports must retain routing tags. It adds
+    one after-validator using Pydantic's public API; ordinary defaults and other
+    exclusion options keep native semantics. Validator ordering follows Pydantic's native MRO.
+    The derived name tuple contains no tag values and is refreshed on schema
+    generation/rebuild; model_fields remains the authoritative declaration.
+    """
+
+    @model_validator(mode="after")
+    def _mark_bound_tags(self) -> Self:
+        """Mark type identity using public APIs; repeated nested validation is idempotent."""
+        self.model_fields_set.update(type(self)._bound_tag_names)
+        return self
+
+
+def _decorator_model(value: object) -> type[DiscriminatedModel]:
+    if not isinstance(value, type) or not issubclass(value, DiscriminatedModel):
+        raise TypeError(f"Decorators require a DiscriminatedModel class; got {value!r}")
+    if value.__pydantic_generic_metadata__["parameters"]:
+        raise TypeError(f"{_model_name(value)}: specialize explicit generic parameters first")
+    return value
+
+
+def _extend[T: DiscriminatedModel](model: type[T], fields: dict[str, Any]) -> type[T]:
+    """Use native inheritance so payload fields, methods and super() keep working."""
+    return create_model(
+        model.__name__,
+        __base__=model,
+        __module__=model.__module__,
+        __qualname__=model.__qualname__,
+        __doc__=model.__doc__,
+        **fields,
+    )
+
+
+def model[T: DiscriminatedModel](
+    *, tag: str | None = None, variant: str | None = None
+) -> Callable[[type[T]], type[T]]:
+    """Bind a parent variant, introduce a tag field, or do both at declaration time.
+
+    ``variant`` is the value of the inherited open discriminator; ``tag`` is the
+    name of a new open string field on this level. At least one is required.
+    Both together bind the parent first, then introduce the next family.
+
+    Ordinary fields and methods retain their static types. Generated tag fields
+    are runtime-only; no generic parameter, stub or whole-model Any is introduced.
+    Finalized fields own tags and defaults. Assembly checks cross-type conflicts;
+    construction performs no decorator reflection or routing work.
+    """
+    if tag is None and variant is None:
+        raise ValueError("@model requires at least one of tag or variant")
+    if tag is not None and (
+        not isinstance(cast(object, tag), str) or not tag or tag.startswith("_")
+    ):
+        raise ValueError("tag must be a non-empty field name without a leading underscore")
+    if variant is not None and (not isinstance(cast(object, variant), str) or not variant):
+        raise ValueError("variant must be a non-empty string")
+
+    def decorate(cls: type[T]) -> type[T]:
+        _decorator_model(cls)
+        inherited = _open_discriminator(cls)
+        fields: dict[str, Any] = {}
+        if variant is not None:
+            if inherited is None:
+                raise TypeError(
+                    f"{_model_name(cls)}: variant= requires an open family discriminator"
+                )
+            fields[inherited] = (cast(Any, Literal)[variant], cls.model_fields[inherited])
+        elif inherited is not None:
+            raise TypeError(
+                f"{_model_name(cls)}.{inherited}: bind the inherited discriminator "
+                "before introducing another family; supply variant= to @model"
+            )
+        if tag is not None:
+            if tag in cls.model_fields or hasattr(cls, tag):
+                raise TypeError(
+                    f"{_model_name(cls)}.{tag}: discriminator conflicts with "
+                    "an existing field or attribute"
+                )
+            field = cast(FieldInfo, tag_field())
+            field.metadata.append(_DECORATED_TAG)
+            fields[tag] = (str, field)
+        return _extend(cls, fields)
+
+    return decorate
+
+
+def _declared_discriminator(model: type[DiscriminatedModel]) -> str | None:
+    """Identify family owners, excluding pending subclasses that only inherit a tag."""
+    name = _open_discriminator(model)
+    if name is None:
+        return None
+    for parent in model.__bases__:
+        if issubclass(parent, DiscriminatedModel) and name in _tag_fields(parent):
+            return None
+    return name
+
+
+def _branches(
+    variants: Iterable[object],
+) -> dict[type[DiscriminatedModel], dict[str, type[DiscriminatedModel]]]:
+    """Build a local dispatch table from leaf fields and native inheritance.
+
+    Unspecialized ancestors identify the family boundaries. All tag values come
+    from the supplied leaf's resolved Pydantic fields, not generic arguments or
+    stored paths. Repeated classes are harmless; conflicting parent/tag claims
+    raise ValueError. Open families and untagged models raise TypeError.
+    """
+    branches: dict[type[DiscriminatedModel], dict[str, type[DiscriminatedModel]]] = {}
+    seen: set[type[DiscriminatedModel]] = set()
+    for variant in variants:
+        if not isinstance(variant, type) or not issubclass(variant, DiscriminatedModel):
+            raise TypeError(f"Expected a DiscriminatedModel variant class; got {variant!r}")
+        if variant in seen:
+            continue
+        seen.add(variant)
+        if _open_discriminator(variant) is not None or not _tag_fields(variant):
+            raise TypeError(f"{_model_name(variant)} must be a tagged leaf model")
+        families = [
+            base
+            for base in reversed(variant.__mro__)
+            if issubclass(base, DiscriminatedModel)
+            and base.__pydantic_generic_metadata__["origin"] is None
+            and _declared_discriminator(base) is not None
+        ]
+        for index, parent in enumerate(families):
+            name = _open_discriminator(parent)
+            assert name is not None
+            tag = _literal_tag(variant, name)
+            child = families[index + 1] if index + 1 < len(families) else variant
+            children = branches.setdefault(parent, {})
+            previous = children.get(tag)
+            if previous is not None and previous is not child:
+                raise ValueError(
+                    f"Duplicate tag {tag!r} for {_model_name(parent)}.{name}: "
+                    f"{_model_name(previous)} and {_model_name(child)} claim the same branch. "
+                    "Use distinct Literal tags or include only one of these branches in variants."
+                )
+            children[tag] = child
+    return branches
+
+
+def family_base(family: object) -> type[DiscriminatedModel]:
+    """Normalize open generic views while preserving concrete class ancestry.
+
+    Named classes and closed specializations retain their identity and bound
+    tags. Only open native views such as Family[Any] use their generic origin.
+    Require a model class; adapter construction separately requires an open tag.
+    """
+    if not isinstance(family, type) or not issubclass(family, DiscriminatedModel):
+        raise TypeError(f"family must be a DiscriminatedModel class; got {family!r}")
+    origin = family.__pydantic_generic_metadata__["origin"]
+    if origin is not None and _open_discriminator(family) is not None:
+        assert issubclass(origin, DiscriminatedModel)
+        return origin
+    return family
+
+
+def _union_for(
+    family: object,
+    branches: dict[type[DiscriminatedModel], dict[str, type[DiscriminatedModel]]],
+) -> Any:
+    """Assemble nested Annotated unions; let Pydantic generate all schemas.
+
+    Dynamic type-expression assembly is the only untyped boundary here. Each
+    leaf retains its model class; no model or compiled schema is modified.
+    """
+    if (
+        not isinstance(family, type)
+        or not issubclass(family, DiscriminatedModel)
+        or _open_discriminator(family) is None
+    ):
+        raise TypeError(
+            f"Expected an open DiscriminatedModel family; got {family!r}. "
+            "Apply the binding to the family itself: "
+            "use Annotated[Family[Any], binding] | None for an optional field."
+        )
+    origin = family_base(family)
+    discriminator = _open_discriminator(origin)
+    assert discriminator is not None
+    children = branches.get(origin)
+    if not children:
+        raise ValueError(f"No variants supplied for {_model_name(origin)}")
+    choices: list[Any] = [
+        _union_for(child, branches) if _open_discriminator(child) is not None else child
+        for child in children.values()
+    ]
+    union: Any = choices[0]
+    for choice in choices[1:]:
+        union = union | choice
+    return cast(Any, Annotated)[union, Field(discriminator=discriminator)]
+
+
+def bind_variants(variants: Iterable[type[DiscriminatedModel]]) -> GetPydanticSchema:
+    """Bind a variant snapshot explicitly to an Annotated family field.
+
+    Use ``Annotated[Family[Any], bind_variants(leaves)]`` in a model field or a
+    container annotation, then use ordinary Pydantic validation and serialization.
+    The static field type remains the declared family; runtime leaves do not
+    synthesize a static union. Known sets can instead use native Annotated unions.
+
+    Duplicate parent/tag mappings raise ValueError. Pydantic owns discriminator
+    schema generation and its native restrictions, including tag-field validators.
+    The snapshot is independent of subsequent changes to the input iterable.
+    """
+    branches = _branches(variants)
+
+    def schema(source: Any, handler: GetCoreSchemaHandler) -> CoreSchema:
+        return handler.generate_schema(_union_for(source, branches))
+
+    return GetPydanticSchema(schema)
+
+
+def build_adapter[T: DiscriminatedModel](
+    family: type[T], *, variants: Iterable[type[DiscriminatedModel]]
+) -> TypeAdapter[T]:
+    """Build a native TypeAdapter for one open family's nested union.
+
+    ``family`` supplies the static result type; its variant paths supply the
+    runtime union. Conflicting tags or missing branches raise ValueError. Closed
+    leaf models and enclosing containers are not family roots and raise TypeError.
+    Bind container fields with bind_variants and use TypeAdapter(Container) instead.
+
+    No adapter attributes are patched. Native rebuild, JSON Schema generation,
+    validation, and serialization operate on the actual union annotation.
+    """
+    return TypeAdapter[T](_union_for(family, _branches(variants)))
+
+
+def concrete_model(value: object) -> type[DiscriminatedModel]:
+    """Validate a concrete behavior target without compiling a data union."""
+    if not isinstance(value, type) or not issubclass(value, DiscriminatedModel):
+        raise TypeError(f"Expected a DiscriminatedModel class; got {value!r}")
+    if isabstract(value) or _open_discriminator(value) is not None:
+        raise TypeError(
+            f"{_model_name(value)}: expected a concrete model, not an open/abstract family"
+        )
+    return value

typebind-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: typebind
+Version: 0.1.0a1
+Summary: Typed Pydantic model families, plugin discovery, and scoped behavior adapters.
+Keywords: pydantic,discriminator,generics,plugins,adapters
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.11.2,<3
+Requires-Dist: typing-extensions>=4.15
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/nicholas-1vbw/typebind
+Project-URL: Repository, https://github.com/nicholas-1vbw/typebind
+Project-URL: Issues, https://github.com/nicholas-1vbw/typebind/issues
+Description-Content-Type: text/markdown
+
+# typebind
+
+Build extensible Pydantic model families with automatic discriminator tags and
+statically typed fields. Bind behavior implementations to models without mixing
+them into the data classes. Select variants explicitly, or optionally discover
+models and implementations supplied by installed plugin packages.
+
+## Install
+
+Python 3.12 or later is required. This project is preparing its first release and
+has not been published to PyPI. From a local checkout:
+
+```sh
+python -m pip install .
+```
+
+The supported Pydantic range and other runtime requirements are declared in
+[pyproject.toml](https://github.com/nicholas-1vbw/typebind/blob/main/pyproject.toml).
+
+## Quick start
+
+Declare a family and its variants, then build an adapter for the variants you accept:
+
+```python
+from typebind import DiscriminatedModel, build_adapter, model
+
+
+@model(tag="kind")
+class Message(DiscriminatedModel):
+    identifier: str
+
+
+@model(variant="query")
+class Query(Message):
+    expression: str
+
+
+@model(variant="ping")
+class Ping(Message):
+    pass
+
+
+adapter = build_adapter(Message, variants=(Query, Ping))
+query = Query(identifier="q", expression="hello")  # kind defaults to "query"
+wire = adapter.dump_json(query)
+assert adapter.validate_json(wire) == query
+assert type(adapter.validate_python({"kind": "ping", "identifier": "p"})) is Ping
+print(wire.decode())  # {"kind":"query","identifier":"q","expression":"hello"}
+```
+
+`build_adapter` returns a native Pydantic `TypeAdapter`. For nested model fields,
+use [`bind_variants`](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#consumer-types).
+Import public APIs from `typebind`; underscore-prefixed modules are internal.
+
+The [`@model` decorator](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#decorator-declarations)
+preserves static checking for declared fields such as `identifier` and `expression`.
+Generated tag attributes such as `kind` are runtime-only: Pyright does not see
+them or accept them as constructor keywords. Use explicit generics when your
+code needs statically typed `Literal` tags:
+
+<details>
+<summary>Explicit generics with statically typed tags</summary>
+
+This standalone example provides the same validation and JSON round trip:
+
+```python
+from typing import Any, Literal
+
+from typebind import DiscriminatedModel, build_adapter, tag_field
+
+
+class Message[Kind: str](DiscriminatedModel):
+    kind: Kind = tag_field()
+    identifier: str
+
+
+class Query(Message[Literal["query"]]):
+    expression: str
+
+
+class Ping(Message[Literal["ping"]]):
+    pass
+
+
+adapter = build_adapter(Message[Any], variants=(Query, Ping))
+query = Query(identifier="q", expression="hello")  # kind defaults to "query"
+wire = adapter.dump_json(query)
+assert adapter.validate_json(wire) == query
+assert type(adapter.validate_python({"kind": "ping", "identifier": "p"})) is Ping
+print(wire.decode())  # {"kind":"query","identifier":"q","expression":"hello"}
+```
+
+`Message[Any]` keeps common fields typed while allowing runtime-selected tags;
+concrete variants retain their `Literal` tags. For example, `query.kind` has the
+static type `Literal["query"]`.
+
+</details>
+
+## Usage notes
+
+- Constructors can omit fixed tags, but incoming data routed through an adapter
+  must contain them. Keep tags in persisted JSON and bind the reader's accepted variants.
+- Ordinary dumps retain tags. If you need `exclude_unset=True`, use
+  `IdentityDiscriminatedModel` to retain omitted tags. Explicit tag exclusions and
+  `exclude_defaults=True` can still remove them; see the
+  [serialization contract](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#json-serialization-contract).
+- Strict Pyright is verified. Discriminator aliases, additional payload type
+  parameters and multiple model-family parents are unsupported; see
+  [typing and compatibility boundaries](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#current-boundaries).
+
+## Documentation and examples
+
+- [Runnable examples](https://github.com/nicholas-1vbw/typebind/blob/main/examples/README.md): setup and commands for model families, manual behavior assembly, decorators and cross-package discovery.
+- [Models](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md): declarations, nested binding, serialization and copying.
+- [Behaviors](https://github.com/nicholas-1vbw/typebind/blob/main/docs/behaviors.md): typed interfaces, assembly and dispatch contracts.
+- [Discovery](https://github.com/nicholas-1vbw/typebind/blob/main/docs/discovery.md): package layout, entry points and scoped selection. Discovery is optional for all model and behavior APIs.
+
+## Contributing
+
+See [Contributing](https://github.com/nicholas-1vbw/typebind/blob/main/CONTRIBUTING.md)
+for development setup and checks, and
+[Releasing](https://github.com/nicholas-1vbw/typebind/blob/main/docs/releasing.md)
+for publishing. Report vulnerabilities through the
+[security policy](https://github.com/nicholas-1vbw/typebind/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/nicholas-1vbw/typebind/blob/main/LICENSE).

typebind-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,9 @@
+typebind/__init__.py,sha256=S_JmjKHSTuB-HPLRRV8zrBuUYIucEUpsPRlJ9VYM-lg,807
+typebind/_behavior.py,sha256=vR9oconNtZCv3r_VDN2rM4NiU3B0HJ1J_rP71KJbUUU,8922
+typebind/_discovery.py,sha256=K1CeEWmHVlTnnGHHtJkEjl4C1CsGQHi1IBkM8k77VBQ,7793
+typebind/_models.py,sha256=fUrowyS450ejnoumAlLar3V8QapS8TnDtddEZrvrdZw,27180
+typebind/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typebind-0.1.0a1.dist-info/licenses/LICENSE,sha256=XSIMPgjY97-adiNpJef7TvWCgIcxJBMhyhkfrHy3CvY,1078
+typebind-0.1.0a1.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+typebind-0.1.0a1.dist-info/METADATA,sha256=mZuSLgfQo2dpO3MzZCvb-u3KvxcioCktqqDp3sgDYOc,5943
+typebind-0.1.0a1.dist-info/RECORD,,

typebind-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.0
+Root-Is-Purelib: true
+Tag: py3-none-any

typebind-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typebind 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.