tunablex 0.0.0__tar.gz

tunablex-0.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+.pytest_cache/
+.mypy_cache/
+*.log
+.venv/
+.env

tunablex-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacques PAPPER - ICON Technology & Process Consulting SAS
+
+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.

tunablex-0.0.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: tunablex
+Version: 0.0.0
+Summary: Function-first tunables with auto JSON/YAML/TOML config & schema, per-executable composition (tags or trace), and runtime auto-injection.
+Project-URL: Homepage, https://github.com/jackpap/tunableX
+Project-URL: Issues, https://github.com/jackpap/tunableX/issues
+Author: Jacques Papper
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.4
+Provides-Extra: jsonargparse
+Requires-Dist: jsonargparse>=4.26; extra == 'jsonargparse'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0.1; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# tunablex
+
+Function-first **tunable parameters** for Python apps — with **automatic JSON & JSON Schema**, **per-executable** composition (via tags) or **dynamic** composition (via call-graph **tracing**), and **runtime auto-injection**.
+
+## Key API
+- `@tunable(...)` — declare which parameters are user-tunable (per function).
+- `schema_for_apps(*apps)` / `defaults_for_apps(*apps)` — by app tags.
+- `schema_by_trace(entrypoint)` / `make_app_config_for_entry(entrypoint)` — by tracing (no tags needed).
+- `use_config(cfg)` — injects sections into all decorated functions during the run.
+- `load_app_config(app, path)` / `load_config_for_entry(entry, path)` — validate JSON against the composed model.
+
+See `examples/` for:
+- argparse + app tags
+- argparse + tracing (no app)
+- jsonargparse + app tags
+- jsonargparse + tracing (no app)

tunablex-0.0.0/README.md

@@ -0,0 +1,16 @@
+# tunablex
+
+Function-first **tunable parameters** for Python apps — with **automatic JSON & JSON Schema**, **per-executable** composition (via tags) or **dynamic** composition (via call-graph **tracing**), and **runtime auto-injection**.
+
+## Key API
+- `@tunable(...)` — declare which parameters are user-tunable (per function).
+- `schema_for_apps(*apps)` / `defaults_for_apps(*apps)` — by app tags.
+- `schema_by_trace(entrypoint)` / `make_app_config_for_entry(entrypoint)` — by tracing (no tags needed).
+- `use_config(cfg)` — injects sections into all decorated functions during the run.
+- `load_app_config(app, path)` / `load_config_for_entry(entry, path)` — validate JSON against the composed model.
+
+See `examples/` for:
+- argparse + app tags
+- argparse + tracing (no app)
+- jsonargparse + app tags
+- jsonargparse + tracing (no app)

tunablex-0.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tunablex"                # PyPI name (normalized)
+version = "0.0.0"                # bump before each release
+description = "Function-first tunables with auto JSON/YAML/TOML config & schema, per-executable composition (tags or trace), and runtime auto-injection."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Jacques Papper" }]
+dependencies = ["pydantic>=2.4"]
+optional-dependencies = { jsonargparse = ["jsonargparse>=4.26"], yaml = ["PyYAML>=6.0.1"] }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+[project.urls]
+Homepage = "https://github.com/jackpap/tunableX"
+Issues = "https://github.com/jackpap/tunableX/issues"
+
+# Tell Hatch where your package lives (src/ layout)
+[tool.hatch.build.targets.wheel]
+packages = ["src/tunablex"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", "pyproject.toml"]

tunablex-0.0.0/src/tunablex/__init__.py

@@ -0,0 +1,17 @@
+from .decorators import tunable
+from .runtime import (
+    schema_for_apps, defaults_for_apps, schema_by_trace,
+    make_app_config_for, make_app_config_for_entry,
+    load_app_config, load_config_for_entry,
+    use_config, write_schema,
+)
+from .registry import REGISTRY
+
+__all__ = [
+    "tunable",
+    "schema_for_apps", "defaults_for_apps", "schema_by_trace",
+    "make_app_config_for", "make_app_config_for_entry",
+    "load_app_config", "load_config_for_entry",
+    "use_config", "write_schema",
+    "REGISTRY",
+]

tunablex-0.0.0/src/tunablex/cli.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import argparse
+import importlib
+import json
+import sys
+from .runtime import schema_for_apps, defaults_for_apps, schema_by_trace, write_schema
+
+def _import_modules(mods):
+    for m in mods: importlib.import_module(m)
+
+def _add_sys_paths(paths):
+    for p in paths or []:
+        if p not in sys.path:
+            sys.path.insert(0, p)
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="tunablex", description="Generate JSON Schema/defaults from @tunable functions.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("schema", help="Emit schema/defaults for one or more apps (by tags).")
+    s.add_argument("--apps", nargs="+", required=True)
+    s.add_argument("--import", dest="imports", nargs="+", required=True)
+    s.add_argument("--sys-path", dest="sys_paths", nargs="+", default=[],
+                   help="Paths to insert into sys.path before imports.")
+    s.add_argument("--out", default=None)
+
+    t = sub.add_parser("trace", help="Emit schema/defaults by tracing a module:function entrypoint.")
+    t.add_argument("--entry", required=True)
+    t.add_argument("--import", dest="imports", nargs="+", required=True)
+    t.add_argument("--sys-path", dest="sys_paths", nargs="+", default=[],
+                   help="Paths to insert into sys.path before imports.")
+    t.add_argument("--out", default=None)
+
+    args = p.parse_args(argv)
+    _add_sys_paths(args.sys_paths)
+    _import_modules(args.imports)
+
+    if args.cmd == "schema":
+        schema = schema_for_apps(*args.apps)
+        defaults = defaults_for_apps(*args.apps)
+        if args.out: write_schema(args.out, schema, defaults)
+        else: print(json.dumps({"schema": schema, "defaults": defaults}, indent=2))
+        return 0
+
+    if args.cmd == "trace":
+        modname, funcname = args.entry.split(":")
+        fn = getattr(importlib.import_module(modname), funcname)
+        schema, defaults, touched = schema_by_trace(fn)
+        if args.out: write_schema(args.out, schema, defaults)
+        else: print(json.dumps({"schema": schema, "defaults": defaults, "touched": sorted(touched)}, indent=2))
+        return 0
+
+    return 1
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tunablex-0.0.0/src/tunablex/cli_helpers.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+from typing import get_origin, get_args, Literal
+from pydantic import BaseModel
+from jsonargparse import ArgumentParser  # works with jsonargparse or argparse-compatible
+from .runtime import make_app_config_for, make_app_config_for_entry
+from .io import load_structured_config
+
+# Accepts yes/no/true/false/1/0/on/off/y/n (case-insensitive)
+def _parse_bool(value: str) -> bool:
+    v = str(value).strip().lower()
+    if v in {"1","true","t","yes","y","on"}:
+        return True
+    if v in {"0","false","f","no","n","off"}:
+        return False
+    raise ValueError(f"invalid boolean: {value!r} (expected yes/no/true/false/1/0)")
+
+def add_flags_from_model(parser: ArgumentParser, AppConfig) -> None:
+    """Create flags like --section.field for each tunable in the AppConfig model."""
+    for section_name, section_field in AppConfig.model_fields.items():
+        section_model = section_field.annotation
+        if not (isinstance(section_model, type) and issubclass(section_model, BaseModel)):
+            continue
+        grp = parser.add_argument_group(section_name)
+        for name, fld in section_model.model_fields.items():
+            ann = fld.annotation
+            flag = f"--{section_name}.{name}"
+            dest = f"TX__{section_name}__{name}"
+            if get_origin(ann) is Literal:
+                grp.add_argument(flag, choices=[*get_args(ann)], dest=dest)
+            elif ann is bool:
+                grp.add_argument(flag, type=_parse_bool, metavar="{yes|no}", dest=dest)
+            elif ann in (int, float, str):
+                grp.add_argument(flag, type=ann, dest=dest)
+            else:
+                grp.add_argument(flag, type=str, dest=dest)  # fallback; validated later
+
+def add_flags_by_app(parser: ArgumentParser, app: str) -> None:
+    AppConfig = make_app_config_for(app)
+    add_flags_from_model(parser, AppConfig)
+
+def add_flags_by_entry(parser: ArgumentParser, entrypoint, *args, **kwargs) -> None:
+    AppConfig = make_app_config_for_entry(entrypoint, *args, **kwargs)
+    add_flags_from_model(parser, AppConfig)
+
+def deep_update(base: dict, extra: dict) -> dict:
+    for k, v in (extra or {}).items():
+        if isinstance(v, dict) and isinstance(base.get(k), dict):
+            deep_update(base[k], v)
+        else:
+            base[k] = v
+    return base
+
+def collect_overrides(args, AppConfig) -> dict:
+    out = {}
+    for section_name, section_field in AppConfig.model_fields.items():
+        section_model = section_field.annotation
+        if not (isinstance(section_model, type) and issubclass(section_model, BaseModel)):
+            continue
+        for name in section_model.model_fields.keys():
+            dest = f"TX__{section_name}__{name}"
+            if hasattr(args, dest):
+                val = getattr(args, dest)
+                if val is not None:
+                    out.setdefault(section_name, {})[name] = val
+    return out
+
+def build_cfg_from_file_and_args(AppConfig, args, config_attr: str = "config") -> dict:
+    cfg = AppConfig().model_dump()
+    path = getattr(args, config_attr, None)
+    if path:
+        cfg = deep_update(cfg, load_structured_config(path))
+    overrides = collect_overrides(args, AppConfig)
+    cfg = deep_update(cfg, overrides)
+    return cfg

tunablex-0.0.0/src/tunablex/context.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+import contextvars
+
+# Trace context to collect namespaces touched during a dry-run
+_active_trace = contextvars.ContextVar("tunablex_trace", default=None)
+
+class trace_tunables:
+    def __init__(self, noop: bool = True):
+        self.namespaces = set()
+        self.noop = noop
+    def __enter__(self):
+        self._tok = _active_trace.set(self)
+        return self
+    def __exit__(self, et, e, tb):
+        _active_trace.reset(self._tok)
+
+# Active config context used at runtime for auto-injection
+_active_cfg = contextvars.ContextVar("tunablex_active_cfg", default=None)
+
+class use_config:
+    def __init__(self, cfg):
+        self.cfg = cfg
+    def __enter__(self):
+        self._tok = _active_cfg.set(self.cfg)
+        return self.cfg
+    def __exit__(self, et, e, tb):
+        _active_cfg.reset(self._tok)

tunablex-0.0.0/src/tunablex/decorators.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+from typing import Any, Iterable, Literal, get_type_hints
+import inspect
+import functools
+from pydantic import BaseModel, create_model
+from .registry import REGISTRY, TunableEntry
+from .context import _active_trace, _active_cfg
+from .naming import ns_to_field
+
+def tunable(*include: str, namespace: str|None=None, mode: Literal["include","exclude"]="include",
+            exclude: Iterable[str]|None=None, apps: Iterable[str]=()):
+    """Mark a function's selected parameters as user-tunable.
+    - include: names to include. If empty, include all params that have defaults
+               (unless mode='exclude' with an explicit exclude list).
+    - namespace: JSON section name; defaults to 'module.function'.
+    - apps: optional tags to group functions per executable/app.
+    """
+    include_set = set(include) if include else None
+    exclude_set = set(exclude or ())
+
+    def decorator(fn):
+        sig = inspect.signature(fn)
+        hints = get_type_hints(fn)
+        fields: dict[str, tuple[type[Any], Any]] = {}
+        for name, p in sig.parameters.items():
+            if p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD):
+                continue
+            if include_set is not None:
+                selected = name in include_set
+            elif mode == "exclude" and exclude_set:
+                selected = (p.default is not inspect._empty) and (name not in exclude_set)
+            else:
+                selected = (p.default is not inspect._empty)
+            if not selected:
+                continue
+            ann = hints.get(name, Any)
+            default = p.default if p.default is not inspect._empty else ...
+            fields[name] = (ann, default)
+
+        ns = namespace or f"{fn.__module__}.{fn.__name__}"
+        model_name = f"{ns.title().replace('.','').replace('_','')}Config"
+        Model = create_model(model_name, **fields)  # type: ignore
+
+        REGISTRY.register(TunableEntry(fn=fn, model=Model, sig=sig, namespace=ns, apps=set(apps)))
+
+        @functools.wraps(fn)
+        def wrapper(*args, cfg: BaseModel | dict | None = None, **kwargs):
+            tracer = _active_trace.get()
+            if tracer is not None:
+                tracer.namespaces.add(ns)
+                if tracer.noop:
+                    return None
+
+            if cfg is not None:
+                data = cfg if isinstance(cfg, dict) else cfg.model_dump()
+                filtered = {k: v for k, v in data.items() if k in sig.parameters}
+                return fn(*args, **filtered, **kwargs)
+
+            app_cfg = _active_cfg.get()
+            if app_cfg is not None:
+                section_attr = ns_to_field(ns)
+                if hasattr(app_cfg, section_attr):
+                    section = getattr(app_cfg, section_attr)
+                    if section is not None:
+                        data = section if isinstance(section, dict) else section.model_dump()
+                        filtered = {k: v for k, v in data.items() if k in sig.parameters}
+                        return fn(*args, **filtered, **kwargs)
+
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

tunablex-0.0.0/src/tunablex/io.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+def load_structured_config(path: str | Path) -> Dict[str, Any]:
+    """Load JSON or YAML (and TOML when '.toml') into a dict.
+    Tries by extension first; falls back to JSON then YAML.
+    """
+    p = Path(path)
+    text = p.read_text()
+    ext = p.suffix.lower()
+
+    if ext in {".yml", ".yaml"}:
+        try:
+            import yaml  # PyYAML
+        except ModuleNotFoundError as e:
+            raise RuntimeError(
+                "YAML file provided but PyYAML is not installed. "
+                "Install with: uv pip install '.[yaml]'"
+            ) from e
+        return yaml.safe_load(text) or {}
+
+    if ext == ".json":
+        return json.loads(text)
+
+    if ext == ".toml":
+        try:
+            import tomllib  # Python 3.11+
+        except ModuleNotFoundError:
+            import tomli as tomllib  # type: ignore[no-redef]
+        return tomllib.loads(text)  # type: ignore[attr-defined]
+
+    # Fallback: try JSON then YAML
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        try:
+            import yaml  # PyYAML
+            return yaml.safe_load(text) or {}
+        except Exception as e:
+            raise RuntimeError(f"Could not parse config file: {p}") from e

tunablex-0.0.0/src/tunablex/naming.py

@@ -0,0 +1,3 @@
+def ns_to_field(ns: str) -> str:
+    """Convert a dotted namespace to a valid attribute name on the AppConfig."""
+    return ns.replace('.', '__').replace('-', '_')

tunablex-0.0.0/src/tunablex/registry.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+import inspect
+from pydantic import BaseModel, Field, create_model
+from .naming import ns_to_field
+
+@dataclass
+class TunableEntry:
+    fn: Any
+    model: type[BaseModel]
+    sig: inspect.Signature
+    namespace: str
+    apps: set[str] = field(default_factory=set)
+
+class TunableRegistry:
+    def __init__(self):
+        self.by_namespace: dict[str, TunableEntry] = {}
+
+    def register(self, entry: TunableEntry):
+        self.by_namespace[entry.namespace] = entry
+
+    def namespaces_for_apps(self, apps: Iterable[str]) -> list[str]:
+        want = set(apps)
+        return [ns for ns, e in self.by_namespace.items() if e.apps & want]
+
+    def build_config(self, namespaces: Iterable[str]):
+        from typing import Optional as TypingOptional
+        fields: dict[str, tuple[type[BaseModel] | Any, Any]] = {}
+        for ns in sorted(set(list(namespaces))):
+            if ns not in self.by_namespace:
+                continue
+            entry = self.by_namespace[ns]
+            Model = entry.model
+            field_name = ns_to_field(ns)
+            try:
+                Model()  # no required fields
+                fields[field_name] = (Model, Field(default_factory=Model))
+            except Exception:
+                fields[field_name] = (TypingOptional[Model], None)
+        if not fields:
+            return create_model("AppConfigEmpty")  # type: ignore
+        return create_model("AppConfig", **fields)  # type: ignore
+
+REGISTRY = TunableRegistry()

tunablex-0.0.0/src/tunablex/runtime.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+from typing import Callable
+import json
+from pathlib import Path
+from pydantic import ValidationError
+from .io import load_structured_config
+from .registry import REGISTRY
+from .context import use_config, trace_tunables  # noqa: F401
+
+def schema_for_apps(*apps: str) -> dict:
+    AppConfig = REGISTRY.build_config(REGISTRY.namespaces_for_apps(apps))
+    return AppConfig.model_json_schema()
+
+def defaults_for_apps(*apps: str) -> dict:
+    AppConfig = REGISTRY.build_config(REGISTRY.namespaces_for_apps(apps))
+    try:
+        return AppConfig().model_dump()
+    except Exception:
+        return {}
+
+def schema_by_trace(run_callable: Callable, *args, **kwargs):
+    with trace_tunables(noop=True) as t:
+        run_callable(*args, **kwargs)
+    AppConfig = REGISTRY.build_config(t.namespaces)
+    try:
+        defaults = AppConfig().model_dump()
+    except Exception:
+        defaults = {}
+    return AppConfig.model_json_schema(), defaults, t.namespaces
+
+def write_schema(prefix: str, schema: dict, defaults: dict|None=None):
+    Path(f"{prefix}.schema.json").write_text(json.dumps(schema, indent=2))
+    if defaults is not None:
+        Path(f"{prefix}.json").write_text(json.dumps(defaults, indent=2))
+
+def make_app_config_for(app: str):
+    namespaces = REGISTRY.namespaces_for_apps([app])
+    return REGISTRY.build_config(namespaces)
+
+def load_app_config(app: str, json_path: str | Path):
+    AppConfig = make_app_config_for(app)
+    data = load_structured_config(json_path)
+    try:
+        return AppConfig.model_validate(data)
+    except ValidationError as e:
+        raise SystemExit(f"Invalid config for app '{app}':\n{e}") from None
+
+# Tracing-based (no app)
+def make_app_config_for_entry(entrypoint: Callable, *args, **kwargs):
+    with trace_tunables(noop=True) as t:
+        entrypoint(*args, **kwargs)
+    return REGISTRY.build_config(t.namespaces)
+
+def load_config_for_entry(entrypoint: Callable, json_path: str | Path, *args, **kwargs):
+    AppConfig = make_app_config_for_entry(entrypoint, *args, **kwargs)
+    data = load_structured_config(json_path)
+    try:
+        return AppConfig.model_validate(data)
+    except ValidationError as e:
+        raise SystemExit(f"Invalid config for traced entrypoint:\n{e}") from None