reqm 0.1.0__tar.gz

reqm-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

reqm-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true

reqm-0.1.0/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  }
+}

reqm-0.1.0/CLAUDE.md

@@ -0,0 +1,256 @@
+# CLAUDE.md — reqm development guide
+
+This file is for AI coding agents working **on** the reqm library itself.
+For guidance on using reqm in your own project, see `llms.txt` or `README.md`.
+
+---
+
+## Tech debt policy
+
+Any consciously taken shortcut or design caveat **must** be recorded in `TECH_DEBT.md`
+before the code is committed. Each entry must include:
+- What was skipped or compromised
+- Why (the constraint that forced it)
+- The concrete action needed to repay it
+
+Tech debt that is not recorded does not exist — and will bite us later.
+Reviewing and repaying `TECH_DEBT.md` items is a normal part of the workflow,
+not an afterthought.
+
+---
+
+## What reqm is
+
+`reqm` (Ridiculously Easy Quant Manager) is a directory-based config management
+and object factory built on Hydra's `instantiate`. It eliminates "Hydra ceremony"
+(context managers, `@hydra.main`, etc.) while keeping Hydra's config composition
+power. A `QuantManager` takes an importable Python config module (a directory with
+`__init__.py` and YAML files) and provides a uniform API to list, validate, load,
+and build objects from those configs.
+
+---
+
+## Core abstractions
+
+### Quant
+The unit reqm builds and manages. An abstract base class that users subclass.
+
+Requirements:
+- Must be callable (`__call__`)
+- Must implement `dummy_inputs() -> dict` returning example inputs
+- Constructor args are defined in YAML config, not hardcoded
+
+The factory calls each Quant with its own `dummy_inputs()` at build time.
+This makes Quants **auditable** — not just interface-compliant, but provably runnable.
+
+### QuantManager
+Directory-based config manager. Takes an importable Python module whose
+directory contains YAML config files and treats it as the Hydra config root.
+
+Key methods:
+- `list_configs()` — list all YAML configs in the module
+- `validate()` — check that all configs have `# @package _global_`
+- `get_config(name)` — load and resolve a config as OmegaConf DictConfig
+- `get_raw_config(name)` — load and resolve a config as a YAML string
+- `build(name)` — instantiate the `_target_` object from a config
+
+All methods accept optional `config_overrides` (dict) and `param_overrides`
+(Hydra CLI-style strings) for runtime customization.
+
+See `docs/config_management.md` for detailed design rationale.
+
+---
+
+## Architecture decisions (do not violate)
+
+1. **No framework ownership.** reqm must never require `@hydra.main`,
+   `hydra.initialize()`, or any context manager at the user's call site.
+   reqm handles all Hydra plumbing internally.
+
+2. **Fail fast.** `dummy_inputs` is called at build/get time, not at inference.
+   Errors surface early and loudly, not silently in production.
+
+3. **Minimal public API.** The surface users touch is:
+   - `Quant` (base class to subclass)
+   - `QuantManager(config_module)` (config management and object building)
+   Keep everything else internal.
+
+4. **Declarative over imperative.** Config files express what to build.
+   Python code expresses the interface contract. Never mix them.
+
+5. **Directory-based, not registry-based.** Config modules are importable
+   Python packages containing YAMLs. No global registry, no eager imports.
+   Every YAML must declare `# @package _global_` for explicit composition.
+
+6. **Generic instantiation.** `QuantManager.build()` instantiates whatever
+   `_target_` points to — it does not enforce that the result is a Quant.
+
+---
+
+## Code conventions
+
+### Docstrings
+Every public class, method, and function must have a Google-style docstring
+with an `Examples:` section containing runnable code. Small LLMs helping users
+will rely on these.
+
+```python
+def build(self, config_name: str, *, ...) -> object:
+    """Build an object from a config via hydra.utils.instantiate.
+
+    Loads the config, applies overrides, resolves interpolations, and
+    passes the result to Hydra's recursive instantiation.
+
+    Args:
+        config_name: Config name (relative path, no .yaml extension).
+
+    Returns:
+        The instantiated object.
+
+    Raises:
+        FileNotFoundError: If config_name does not exist.
+        hydra.errors.InstantiationException: If instantiation fails.
+
+    Examples:
+        >>> import my_configs
+        >>> from reqm import QuantManager
+        >>> QM = QuantManager(my_configs)
+        >>> model = QM.build("summarizer/prod")
+        >>> result = model(text="Hello world")
+    """
+```
+
+### Type annotations
+All public APIs must be fully type-annotated. Internal helpers should be
+annotated where it aids clarity.
+
+### Error messages
+Errors must be actionable. Always tell the user what alias, config path, or
+interface was involved and what to do next.
+
+```python
+# Good
+raise FileNotFoundError(
+    f"Config '{config_name}' not found in config module at {self._config_dir}. "
+    f"Available configs: {self.list_configs()}"
+)
+
+# Bad
+raise FileNotFoundError(f"Config not found: {config_name}")
+```
+
+### No magic
+Avoid metaclass magic, import hooks, or decorators that alter behavior invisibly.
+If something happens, it should be traceable by reading the call stack.
+
+---
+
+## File layout
+
+```
+src/reqm/
+├── __init__.py          # public API exports: Quant, QuantManager
+├── quant.py             # Quant ABC definition
+├── quant_manager.py     # QuantManager, ConfigValidationError
+└── overrides_ext.py     # @override / @allow_any_override support
+
+examples/
+└── estimators/          # end-to-end example project
+    ├── __init__.py      # QM = QuantManager(configs) — single construction point
+    ├── filters/         # non-Quant configurable dependencies
+    │   ├── api.py       # Filter base class
+    │   ├── no_filter.py, outlier.py, top_k.py
+    ├── quants/          # Estimator Quant subclasses
+    │   ├── api.py       # Estimator(Quant) base class
+    │   ├── mean.py, median.py, trimmed_mean.py, ensemble.py
+    ├── scripts/         # uniform call site demos (import QM from parent)
+    │   ├── evaluate.py, inspect_config.py, compare.py
+    │   ├── validate_configs.py, sweep.py
+    └── configs/         # config module for QuantManager
+        ├── filters/     # filter configs (non-Quant)
+        ├── *.yaml       # estimator configs (compose filters via defaults)
+        └── ensemble/    # ensemble configs (compose estimators via defaults)
+└── torch_models/        # PyTorch integration example (requires torch)
+    ├── __init__.py      # QM = QuantManager(configs)
+    ├── torch_quant.py   # TorchQuant bridge (copy into your project)
+    ├── models/          # Regressor(TorchQuant) subclasses
+    ├── configs/         # model configs
+    └── scripts/         # evaluate.py, audit.py
+```
+
+---
+
+## What to build next
+
+Completed:
+1. ~~`quant.py` — `Quant` ABC with `dummy_inputs` abstract method~~
+2. ~~`overrides_ext.py` — `@override` / `@allow_any_override` support~~
+3. ~~`quant_manager.py` — `QuantManager` class + `ConfigValidationError`~~
+
+4. ~~`__init__.py` — wire up public API exports (`Quant`, `QuantManager`)~~
+5. ~~`examples/` — estimators example project with eval script~~
+
+Remaining:
+6. Integration tests with Quant + QuantManager together
+
+---
+
+## Testing
+
+Run tests with:
+```bash
+uv run pytest
+```
+
+### Write tests abundantly
+
+Tests are first-class documentation here. Write as many as are appropriate —
+they double as concrete, runnable usage examples that LLMs and humans can learn from.
+
+Rules:
+- Every public API must have multiple tests covering: happy path, edge cases, error cases
+- Test names must be descriptive sentences: `test_get_returns_correct_quant_instance`,
+  not `test_get`
+- Each test should be self-contained and readable in isolation — no shared mutable state
+- Tests that demonstrate usage patterns are as valuable as tests that catch bugs
+- When a new feature is added, write tests before or alongside (not after) the implementation
+
+### Quant ABC signature override
+
+`Quant.__call__` is defined as `**kwargs` and decorated with `@allow_any_override`.
+This is intentional. Subclasses narrow the signature to their specific API.
+The `@allow_any_override` marker tells type checkers and linters that the
+signature change is deliberate, not a mistake.
+
+```python
+# Base — accepts anything
+class Quant(EnforceOverrides):
+    @abstractmethod
+    @allow_any_override
+    def __call__(self, **kwargs) -> Any: ...
+
+# Subclass — narrows to specific API (correct and intended)
+class Summarizer(Quant):
+    @override
+    def __call__(self, text: str, max_tokens: int = 512) -> str: ...
+```
+
+### Two-level signature narrowing (TorchQuant pattern)
+
+`TorchQuant.forward` has `@allow_any_override` so domain base classes can
+narrow it. But the domain base class must **not** use `@allow_any_override`
+on its own `forward` — this locks the signature for all concrete models:
+
+```
+TorchQuant        → forward(**kwargs)           @allow_any_override (open)
+  Regressor       → forward(x: Tensor)          NO @allow_any_override (locked)
+    LinearModel   → forward(x: Tensor)          must match Regressor exactly
+    BadModel      → forward(a, b)               REJECTED at class definition time
+```
+
+This pattern is critical for uniform call sites. Without the domain base
+locking the signature, each concrete model could use a different `forward`
+signature, breaking evaluation scripts at runtime instead of at definition time.
+
+Always create a domain base class between TorchQuant and concrete models.
+See `docs/torch_integration.md` for the full explanation.

reqm-0.1.0/LICENSE

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

reqm-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: reqm
+Version: 0.1.0
+Summary: Ridiculously Easy Quant Manager — config-based aliased object factory with enforced interfaces
+Project-URL: Homepage, https://github.com/jkvc/reqm
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: hydra-core>=1.3
+Requires-Dist: overrides>=7.7.0
+Description-Content-Type: text/markdown
+
+# reqm
+
+**R**idiculously **E**asy **Q**uant **M**anager
+
+Directory-based config management and object factory built on [Hydra](https://hydra.cc).
+
+---
+
+## The problem
+
+Hydra is excellent for config-driven instantiation. But using it as a general object factory requires ceremony:
+
+```python
+# You have to do all of this just to instantiate one object
+with hydra.initialize(config_path="conf"):
+    cfg = hydra.compose(config_name="my_model")
+    model = hydra.utils.instantiate(cfg.model)
+```
+
+This ceremony means Hydra stays in the lab. It's awkward in a notebook, verbose in a service, and doesn't belong in production call sites.
+
+`reqm` gives you Hydra's power — config-driven instantiation, composable overrides, recursive object graphs — with none of the ceremony:
+
+```python
+from reqm import QuantManager
+import my_configs
+
+QM = QuantManager(my_configs)
+model = QM.build("summarizer_prod")
+```
+
+Same call in a notebook, a FastAPI endpoint, a test, or a batch job.
+
+---
+
+## Core concept: the Quant
+
+A **Quant** is the unit reqm builds and manages. It is:
+
+- **Callable** — invoked directly with its inputs
+- **Config-driven** — constructor arguments defined in YAML, no hardcoding
+- **Auditable** — implements `dummy_inputs()`, example inputs the factory uses to verify it actually runs
+
+```python
+from reqm import Quant
+from reqm.overrides_ext import override
+
+class Summarizer(Quant):
+    def __init__(self, model_name: str, max_tokens: int):
+        self.model = load_model(model_name)
+        self.max_tokens = max_tokens
+
+    @override
+    def dummy_inputs(self) -> list[dict]:
+        return [{"text": "The quick brown fox jumps over the lazy dog."}]
+
+    @override
+    def __call__(self, text: str) -> str:
+        return self.model.summarize(text, max_tokens=self.max_tokens)
+```
+
+The `dummy_inputs` contract is what separates a Quant from a plain ABC. reqm can call each Quant with its own dummy inputs at build time — if it fails, it fails early and loudly, not silently in production.
+
+---
+
+## Config modules and QuantManager
+
+A **config module** is any importable Python package containing YAML files:
+
+```
+my_configs/
+├── __init__.py
+├── summarizer_prod.yaml
+├── summarizer_fast.yaml
+└── serving/
+    └── prod.yaml
+```
+
+Each YAML config declares what to build:
+
+```yaml
+# @package _global_
+_target_: myproject.models.Summarizer
+model_name: gpt-4o
+max_tokens: 512
+```
+
+`QuantManager` takes the config module and gives you a uniform API. Construct it once in the `__init__.py` next to your configs directory, then import `QM` everywhere:
+
+```python
+# myproject/__init__.py (next to configs/)
+import myproject.configs as configs
+from reqm import QuantManager
+
+QM = QuantManager(configs)
+```
+
+```python
+# Any call site — notebook, script, service, test
+from myproject import QM
+
+QM.list_configs()          # ["serving/prod", "summarizer_fast", "summarizer_prod"]
+QM.validate()              # check all configs have # @package _global_
+cfg = QM.get_config("summarizer_prod")   # resolved OmegaConf DictConfig
+obj = QM.build("summarizer_prod")        # instantiated object
+```
+
+Configs can compose other configs via Hydra defaults lists:
+
+```yaml
+# @package _global_
+defaults:
+  - /base_model@child
+  - _self_
+_target_: myproject.models.Ensemble
+weight: 0.6
+```
+
+---
+
+## The uniform call site
+
+The core value proposition: ONE script, swap the config name, get different experimental results. No code changes, no if/else chains, no factory functions.
+
+Construct `QM` once in the `__init__.py` right next to your configs directory:
+
+```python
+# myproject/__init__.py (lives next to configs/)
+import myproject.configs as configs
+from reqm import QuantManager
+
+QM = QuantManager(configs)
+```
+
+Then every script just imports it:
+
+```python
+import sys
+from myproject import QM
+
+model = QM.build(sys.argv[1])       # <-- only this string changes
+result = model(text="Hello world")
+```
+
+```bash
+python evaluate.py summarizer_prod
+python evaluate.py summarizer_fast
+python evaluate.py summarizer_experiment_v3
+```
+
+---
+
+## Runnable example
+
+The repo includes a complete example project at `examples/estimators/` that demonstrates Quant subclasses, non-Quant configurable dependencies (Filters), Hydra config composition, and multiple scripts sharing a single `QM` instance defined in `examples/estimators/__init__.py`:
+
+```bash
+# Evaluate a single estimator config
+uv run python -m examples.estimators.scripts.evaluate mean_simple
+
+# Inspect the fully resolved config YAML
+uv run python -m examples.estimators.scripts.inspect_config ensemble/mean_median
+
+# Compare multiple configs side by side
+uv run python -m examples.estimators.scripts.compare mean_simple mean_outlier median_simple
+
+# Validate all configs
+uv run python -m examples.estimators.scripts.validate_configs
+
+# Sweep all configs and rank by performance
+uv run python -m examples.estimators.scripts.sweep
+```
+
+---
+
+## PyTorch integration
+
+reqm does not depend on PyTorch, but its primary use case is config-driven model experimentation with `nn.Module`. The repo includes a `TorchQuant` bridge class that resolves the `__call__` vs `forward()` conflict — subclass it instead of plain `Quant` when your model is an `nn.Module`:
+
+Don't subclass TorchQuant directly for every model — create a **domain base class** that locks the `forward` signature for your use case:
+
+```python
+from myproject.torch_quant import TorchQuant  # copy from examples/
+
+# Domain base — locks forward(self, x: Tensor) -> Tensor for all regressors
+class Regressor(TorchQuant):
+    in_features: int
+
+    @override
+    @abc.abstractmethod
+    def forward(self, x: torch.Tensor) -> torch.Tensor: ...
+
+    @override
+    def dummy_inputs(self) -> list[dict]:
+        return [{"x": torch.randn(4, self.in_features)}]
+
+
+# Concrete model — must match the Regressor signature
+class LinearRegressor(Regressor):
+    def __init__(self, in_features: int):
+        super().__init__()
+        self.in_features = in_features
+        self.linear = nn.Linear(in_features, 1)
+
+    @override
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.linear(x)
+```
+
+`TorchQuant.forward` uses `@allow_any_override` so domain bases can narrow freely. Once the domain base locks the signature (without `@allow_any_override`), all concrete models must match — enforced at class definition time, not runtime.
+
+See `docs/torch_integration.md` for the full explanation, and `examples/torch_models/` for a runnable example:
+
+```bash
+uv run python -m examples.torch_models.scripts.evaluate linear_simple
+uv run python -m examples.torch_models.scripts.evaluate mlp_small
+uv run python -m examples.torch_models.scripts.audit
+```
+
+---
+
+## Why not just Hydra?
+
+Hydra is framework-first. It expects to own your program's entry point. `reqm` is library-first — it has no opinion about your application structure and works wherever Python runs.
+
+| | Hydra | reqm |
+|---|---|---|
+| Object instantiation | yes | yes |
+| Config composition | yes | yes (via Hydra) |
+| Auditability (`dummy_inputs`) | no | yes |
+| Works in notebooks | limited | yes |
+| CLI ceremony required | yes | no |
+
+---
+
+## Name
+
+`reqm` is also a nod to [Rue Esquermoise](https://en.wikipedia.org/wiki/Rue_Esquermoise), one of the oldest streets in Lille, France, dating to the 13th century. Its etymology traces to the Flemish *eskelm* — "frontier." A fitting name for a library that sits at the frontier between research and production.
+
+---
+
+## Status
+
+Core API implemented: `Quant`, `QuantManager`, config composition, and override support all work. See `examples/estimators/` for a complete working project.