economize 0.3.0__py3-none-any.whl

economize/__init__.py

@@ -0,0 +1,120 @@
+"""economize: composable efficiency techniques for Hugging Face causal language models.
+
+    import economize
+    from transformers import AutoModelForCausalLM
+
+    base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B")
+    model = economize.apply(base, economize.JumpConfig(target_layer=12, source_layer=18))
+    ...                                     # train the added parameters, or load trained ones:
+    model = economize.from_pretrained("path/to/checkpoint")
+    out = model.generate(input_ids, max_new_tokens=128, decoding=economize.DecodeConfig(cycle_length=4))
+
+The root holds the technique-independent API (``apply``, ``EfficientModel``, decoding, errors, registries). The
+configuration of each technique lives in its subpackage (``from economize.techniques.quant import QuantConfig``), with
+one deliberate exception: :class:`~economize.techniques.jump.JumpConfig`, economize's own method and the subject of the
+quick starts, is re-exported here as ``economize.JumpConfig``. It is the only one, so a new technique never edits this
+module (``tests/unit/test_root_api.py`` guards both rules).
+"""
+
+from __future__ import annotations
+
+# Imported for their side effects: they register the built-in techniques, formats, exporters and backends.
+from . import _wiring, compat, techniques  # noqa: F401
+from ._version import __version__
+from .core import (
+    FORMATS,
+    TECHNIQUES,
+    AttachContext,
+    Capability,
+    Checkpoint,
+    CheckpointFormat,
+    EfficientModel,
+    Technique,
+    TechniqueConfig,
+    apply,
+    attach,
+    from_pretrained,
+    load,
+    read_checkpoint,
+    register_technique,
+    save,
+    teacher_fingerprint,
+)
+from .decoding import (
+    POLICIES,
+    VERIFIERS,
+    CostLog,
+    CycleDecoder,
+    DecodeConfig,
+    DecodeResult,
+    Draft,
+    Drafter,
+    DraftPolicy,
+    DraftRequest,
+    GreedySelector,
+    TokenSelector,
+    TopPSampler,
+    Verifier,
+    VerifyEvent,
+)
+from .errors import (
+    CheckpointFormatError,
+    ConfigError,
+    DuplicateNameError,
+    EconomizeError,
+    IncompatibleTechniquesError,
+    TeacherMismatchWarning,
+    UnknownNameError,
+    UnregisteredNameError,
+    UnsupportedModelError,
+)
+from .runtime import current_phase, phase
+from .techniques.jump import JumpConfig  # the one technique config at the root (see the module docstring)
+
+__all__ = [
+    "FORMATS",
+    "POLICIES",
+    "TECHNIQUES",
+    "VERIFIERS",
+    "AttachContext",
+    "Capability",
+    "Checkpoint",
+    "CheckpointFormat",
+    "CheckpointFormatError",
+    "ConfigError",
+    "CostLog",
+    "CycleDecoder",
+    "DecodeConfig",
+    "DecodeResult",
+    "Draft",
+    "DraftPolicy",
+    "DraftRequest",
+    "Drafter",
+    "DuplicateNameError",
+    "EconomizeError",
+    "EfficientModel",
+    "GreedySelector",
+    "IncompatibleTechniquesError",
+    "JumpConfig",
+    "TeacherMismatchWarning",
+    "Technique",
+    "TechniqueConfig",
+    "TokenSelector",
+    "TopPSampler",
+    "UnknownNameError",
+    "UnregisteredNameError",
+    "UnsupportedModelError",
+    "Verifier",
+    "VerifyEvent",
+    "__version__",
+    "apply",
+    "attach",
+    "current_phase",
+    "from_pretrained",
+    "load",
+    "phase",
+    "read_checkpoint",
+    "register_technique",
+    "save",
+    "teacher_fingerprint",
+]

economize/_deprecation.py

@@ -0,0 +1,59 @@
+"""Deprecation warnings for names that moved or were renamed (layer 0: imports nothing of economize).
+
+A module that keeps old names alive sets its module-level ``__getattr__`` to :func:`moved_getattr`. The ``load``
+function it passes imports the new home explicitly inside the shim module, so that the layering test sees the edge.
+"""
+
+from __future__ import annotations
+
+import sys
+import warnings
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+__all__ = ["moved_getattr", "warn_moved"]
+
+
+def warn_moved(old: str, new: str, *, stacklevel: int = 3) -> None:
+    """Warn that ``old`` (a dotted name) is deprecated in favour of ``new``.
+
+    The default ``stacklevel`` points at the caller of the shim that calls this function (the module
+    ``__getattr__`` or the deprecated method).
+    """
+    warnings.warn(f"{old} is deprecated; use {new} instead", DeprecationWarning, stacklevel=stacklevel)
+
+
+def moved_getattr(
+    module: str,
+    moved: Mapping[str, str] | Iterable[str],
+    new_home: str | None = None,
+    load: Callable[[], object] | None = None,
+) -> Callable[[str], Any]:
+    """A module ``__getattr__`` (PEP 562) that resolves deprecated names with a :class:`DeprecationWarning`.
+
+    Args:
+        module: the shim module's ``__name__``.
+        moved: old name -> name in the new home, or an iterable of names that kept their name.
+        new_home: dotted name of the new home, used in the warning (default: ``module`` itself, for renames).
+        load: imports and returns the new home (default: ``module`` itself).
+
+    Unknown names raise :class:`AttributeError` as usual. Usage::
+
+        def _tskip() -> ModuleType:
+            from ...compat import tskip
+
+            return tskip
+
+        __getattr__ = moved_getattr(__name__, {"OldName": "NewName"}, "economize.compat.tskip", _tskip)
+    """
+    names = dict(moved) if isinstance(moved, Mapping) else {name: name for name in moved}
+    home = new_home or module
+
+    def _getattr(name: str) -> Any:
+        if name not in names:
+            raise AttributeError(f"module {module!r} has no attribute {name!r}")
+        target = load() if load is not None else sys.modules[module]
+        warn_moved(f"{module}.{name}", f"{home}.{names[name]}")
+        return getattr(target, names[name])
+
+    return _getattr

economize/_version.py

@@ -0,0 +1,4 @@
+"""The version of economize. The single source of the version: ``economize.__version__`` re-exports it, the core records
+it in every checkpoint, and ``pyproject.toml`` reads it at build time (``[tool.hatch.version]``). Imports nothing."""
+
+__version__ = "0.3.0"

economize/_wiring.py

@@ -0,0 +1,22 @@
+"""The composition root: it connects the lower layers to implementations that live in higher ones.
+
+A layer imports only layers below it (``docs/ARCHITECTURE.md``, Section 2.1). Where a lower layer needs behaviour
+from a higher one, it exposes a registry and the package root registers the implementation here, importing the
+higher module on first use so that ``import economize`` stays light.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .core.model import GENERATE_IMPLEMENTATIONS
+
+__all__: list[str] = []
+
+
+@GENERATE_IMPLEMENTATIONS.register("transformers")
+def _transformers_generate(model: Any, inputs: Any = None, **kwargs: Any) -> Any:
+    """:func:`economize.integrations.generate.generate`, imported on the first ``EfficientModel.generate`` call."""
+    from .integrations.generate import generate
+
+    return generate(model, inputs, **kwargs)

economize/arch/__init__.py

@@ -0,0 +1,63 @@
+"""Architecture adapters (one per model family, looked up by ``config.model_type``)."""
+
+from __future__ import annotations
+
+from .base import (
+    ARCHITECTURES,
+    SUPPORTED_ATTENTION,
+    ArchAdapter,
+    adapter_for,
+    module_device,
+    register_adapter,
+)
+from .config import (
+    PER_LAYER_CONFIG_FIELDS,
+    config_value,
+    is_heterogeneous,
+    kept_below,
+    layer_overrides,
+    renumbered,
+    set_layer_overrides,
+    text_config,
+)
+from .spec import (
+    LAYER_KINDS,
+    AttentionSpec,
+    HeadGeometry,
+    LayerKind,
+    PassContext,
+    StateKind,
+    layer_kind_of,
+    register_layer_kind,
+)
+from .standard import SoftcappedLogitsMixin, SparseStepMoeMixin, StandardDecoderAdapter
+
+__all__ = [
+    "ARCHITECTURES",
+    "LAYER_KINDS",
+    "PER_LAYER_CONFIG_FIELDS",
+    "SUPPORTED_ATTENTION",
+    "ArchAdapter",
+    "AttentionSpec",
+    "HeadGeometry",
+    "LayerKind",
+    "PassContext",
+    "SoftcappedLogitsMixin",
+    "SparseStepMoeMixin",
+    "StandardDecoderAdapter",
+    "StateKind",
+    "adapter_for",
+    "config_value",
+    "is_heterogeneous",
+    "kept_below",
+    "layer_kind_of",
+    "layer_overrides",
+    "module_device",
+    "register_adapter",
+    "register_layer_kind",
+    "renumbered",
+    "set_layer_overrides",
+    "text_config",
+]
+
+from . import families  # noqa: F401  (registers every family adapter)