module-runner 0.1.0__tar.gz

module_runner-0.1.0/LICENSE

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

module_runner-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: module-runner
+Version: 0.1.0
+Summary: Lightweight helper that prepares Python environments and executes standalone modules.
+Author: Leo Jaimesson
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Module Runner
+
+Module Runner sits in the gap between ad-hoc scripts and heavyweight orchestration frameworks. It gives each module a predictable, isolated environment without asking you to bolt on extra infrastructure, schedulers, or workflow engines. The project stays intentionally lightweight and focuses on two responsibilities:
+
+1. Detect the proper execution strategy (system Python, `venv`, or `uv`).
+2. Launch the module with an optional JSON payload, returning the `subprocess.CompletedProcess` so you can decide how to consume `stdout`, `stderr`, or exit codes.
+
+Any higher-level orchestration (pipelines, RPC, shared storage, etc.) is an application concern, keeping this library small and predictable.
+
+## Features
+
+- ⚙️ **Automatic environment discovery**: detects `pyproject.toml` or `requirements.txt` (→ `uv` when available, `venv` as fallback), or falls back to the current interpreter.
+- 📦 **Per-module dependencies**: each module lives in its own folder with its own toolchain, avoiding cross-contamination.
+- 🧱 **Opinionated boundary**: no implicit payload chaining—what a module prints, writes, or exposes is entirely up to you.
+- 🪪 **Clear error surface**: `RunnerExecutionError` captures module failures while missing tooling raises descriptive `RuntimeError`s, keeping debugging straightforward.
+- 🔍 **Built-in logging**: uses Python's standard `logging` module under the `module_runner` logger — enable `DEBUG` to see the resolved strategy, every setup command, and the final execution command.
+
+## Logging
+
+Module Runner emits `INFO`-level log records under the `module_runner` logger. To see them:
+
+```python
+import logging
+logging.getLogger("module_runner").setLevel(logging.INFO)
+logging.basicConfig()
+```
+
+Example output:
+```
+[normalize] strategy=pip  (requirements.txt detected, uv unavailable — fallback to venv+pip)
+[normalize] creating venv: /usr/bin/python3 -m venv .venv
+[normalize] installing deps: .venv/bin/python -m pip install -r requirements.txt
+[normalize] executing: .venv/bin/python main.py {"text": " Hello World "}
+```
+
+## Why This Exists
+
+Module Runner is the missing middle layer between one-off helper scripts and enterprise orchestrators. It gives you just enough structure to keep automation tidy while remaining lightweight, infrastructure-free, and dependency-light.
+
+## When to Use
+
+Use Module Runner when you:
+
+- Need simple local automation or scripting glue with a lightweight footprint
+- Have dependency conflicts between scripts and want per-module isolation
+- Want predictable, sequential execution you can reason about
+- Prefer to stay container-free for lightweight tasks
+- Do not need a workflow engine or task scheduler
+
+## When Not to Use
+
+Reach for other tooling if you require:
+
+- Complex DAG dependencies or branching workflows
+- Scheduling, cron-style orchestration, or SLAs
+- Distributed workers or autoscaling fleets
+- Monitoring dashboards, retries, or alerting UI
+- Enterprise workflow/orchestration guarantees
+
+## Philosophy
+
+- Small, explicit, predictable, and lightweight
+- Infrastructure-free: relies on the Python already on your machine
+- Focused on one problem—launching modules in clean environments
+
+It is not meant to be a workflow engine; it simply keeps isolated scripts manageable.
+
+## Installation
+
+```bash
+# using pip
+pip install module_runner
+
+# using uv
+uv add module_runner
+
+```
+
+You only need Python 3.9+ and whichever tooling your modules request (e.g., `uv`, `venv`, system packages).
+
+## Quick Start
+
+```python
+from module_runner import Runner
+
+runner = Runner(module_path="modules/normalize_text")
+
+process = runner.run(
+    payload={"text": " Hello World "},
+)
+
+print(process.stdout)  # or json.loads(process.stdout)
+```
+
+Your module layout needs a `main.py` entry point. Any payload you pass is serialized as JSON and delivered as the last CLI argument. How you emit results (stdout, files, sockets) is entirely your call.
+
+## Environment Selection
+
+| Signal in module folder | Mode used     | Requirement |
+| ----------------------- | ------------- | ----------- |
+| `pyproject.toml`        | `uv run ...`  | `uv` available in `PATH` |
+| `pyproject.toml` (no `uv`) | `python -m venv` + `pip install .` | `venv` module available |
+| `requirements.txt`      | `uv venv` + `uv pip install -r requirements.txt` | `uv` available in `PATH` |
+| `requirements.txt` (no `uv`) | `python -m venv` + `pip install -r requirements.txt` | `venv` module available |
+| none of the above       | current interpreter (`sys.executable`) | none |
+
+- Auto-detection always checks whether the required tooling is installed. When `uv` is available it is preferred for both `pyproject.toml` and `requirements.txt` modules. If `uv` is not available, both `pyproject.toml` and `requirements.txt` modules fall back to `venv`/`pip`.
+- If a module signals that it needs `uv` or `venv` but the corresponding tooling is missing, Module Runner raises a descriptive `RuntimeError` explaining what needs to be installed.
+- Runtime failures propagate as `RunnerExecutionError`, exposing the module name, exit code, captured `stderr`, captured `stdout`, and the exact `cmd` list that was executed — making it straightforward to reproduce or log failures.
+
+## Sandbox Playground
+
+The [sandbox](sandbox/README.md) directory ships with two toy modules (`normalize` and `stats`) that showcase:
+
+- How `requirements.txt` triggers a module-specific virtual environment.
+- How `pyproject.toml` causes execution via `uv run`.
+- How you can manually chain modules by parsing the `stdout` from the first run and feeding it into the next.
+
+Run everything with:
+
+```bash
+python sandbox/run_examples.py
+```
+
+Use this folder as a template to create your own modules or to test different deployment scenarios.
+
+## Development
+
+```bash
+git clone https://github.com/<seu-usuario>/module_runner.git
+cd module_runner
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Feel free to open issues or pull requests with improvements. The scope intentionally stays small: reliable environment setup and process execution.
+
+## License
+
+Module Runner is released under the MIT License. See [LICENSE](LICENSE) for details.

module_runner-0.1.0/README.md

@@ -0,0 +1,140 @@
+# Module Runner
+
+Module Runner sits in the gap between ad-hoc scripts and heavyweight orchestration frameworks. It gives each module a predictable, isolated environment without asking you to bolt on extra infrastructure, schedulers, or workflow engines. The project stays intentionally lightweight and focuses on two responsibilities:
+
+1. Detect the proper execution strategy (system Python, `venv`, or `uv`).
+2. Launch the module with an optional JSON payload, returning the `subprocess.CompletedProcess` so you can decide how to consume `stdout`, `stderr`, or exit codes.
+
+Any higher-level orchestration (pipelines, RPC, shared storage, etc.) is an application concern, keeping this library small and predictable.
+
+## Features
+
+- ⚙️ **Automatic environment discovery**: detects `pyproject.toml` or `requirements.txt` (→ `uv` when available, `venv` as fallback), or falls back to the current interpreter.
+- 📦 **Per-module dependencies**: each module lives in its own folder with its own toolchain, avoiding cross-contamination.
+- 🧱 **Opinionated boundary**: no implicit payload chaining—what a module prints, writes, or exposes is entirely up to you.
+- 🪪 **Clear error surface**: `RunnerExecutionError` captures module failures while missing tooling raises descriptive `RuntimeError`s, keeping debugging straightforward.
+- 🔍 **Built-in logging**: uses Python's standard `logging` module under the `module_runner` logger — enable `DEBUG` to see the resolved strategy, every setup command, and the final execution command.
+
+## Logging
+
+Module Runner emits `INFO`-level log records under the `module_runner` logger. To see them:
+
+```python
+import logging
+logging.getLogger("module_runner").setLevel(logging.INFO)
+logging.basicConfig()
+```
+
+Example output:
+```
+[normalize] strategy=pip  (requirements.txt detected, uv unavailable — fallback to venv+pip)
+[normalize] creating venv: /usr/bin/python3 -m venv .venv
+[normalize] installing deps: .venv/bin/python -m pip install -r requirements.txt
+[normalize] executing: .venv/bin/python main.py {"text": " Hello World "}
+```
+
+## Why This Exists
+
+Module Runner is the missing middle layer between one-off helper scripts and enterprise orchestrators. It gives you just enough structure to keep automation tidy while remaining lightweight, infrastructure-free, and dependency-light.
+
+## When to Use
+
+Use Module Runner when you:
+
+- Need simple local automation or scripting glue with a lightweight footprint
+- Have dependency conflicts between scripts and want per-module isolation
+- Want predictable, sequential execution you can reason about
+- Prefer to stay container-free for lightweight tasks
+- Do not need a workflow engine or task scheduler
+
+## When Not to Use
+
+Reach for other tooling if you require:
+
+- Complex DAG dependencies or branching workflows
+- Scheduling, cron-style orchestration, or SLAs
+- Distributed workers or autoscaling fleets
+- Monitoring dashboards, retries, or alerting UI
+- Enterprise workflow/orchestration guarantees
+
+## Philosophy
+
+- Small, explicit, predictable, and lightweight
+- Infrastructure-free: relies on the Python already on your machine
+- Focused on one problem—launching modules in clean environments
+
+It is not meant to be a workflow engine; it simply keeps isolated scripts manageable.
+
+## Installation
+
+```bash
+# using pip
+pip install module_runner
+
+# using uv
+uv add module_runner
+
+```
+
+You only need Python 3.9+ and whichever tooling your modules request (e.g., `uv`, `venv`, system packages).
+
+## Quick Start
+
+```python
+from module_runner import Runner
+
+runner = Runner(module_path="modules/normalize_text")
+
+process = runner.run(
+    payload={"text": " Hello World "},
+)
+
+print(process.stdout)  # or json.loads(process.stdout)
+```
+
+Your module layout needs a `main.py` entry point. Any payload you pass is serialized as JSON and delivered as the last CLI argument. How you emit results (stdout, files, sockets) is entirely your call.
+
+## Environment Selection
+
+| Signal in module folder | Mode used     | Requirement |
+| ----------------------- | ------------- | ----------- |
+| `pyproject.toml`        | `uv run ...`  | `uv` available in `PATH` |
+| `pyproject.toml` (no `uv`) | `python -m venv` + `pip install .` | `venv` module available |
+| `requirements.txt`      | `uv venv` + `uv pip install -r requirements.txt` | `uv` available in `PATH` |
+| `requirements.txt` (no `uv`) | `python -m venv` + `pip install -r requirements.txt` | `venv` module available |
+| none of the above       | current interpreter (`sys.executable`) | none |
+
+- Auto-detection always checks whether the required tooling is installed. When `uv` is available it is preferred for both `pyproject.toml` and `requirements.txt` modules. If `uv` is not available, both `pyproject.toml` and `requirements.txt` modules fall back to `venv`/`pip`.
+- If a module signals that it needs `uv` or `venv` but the corresponding tooling is missing, Module Runner raises a descriptive `RuntimeError` explaining what needs to be installed.
+- Runtime failures propagate as `RunnerExecutionError`, exposing the module name, exit code, captured `stderr`, captured `stdout`, and the exact `cmd` list that was executed — making it straightforward to reproduce or log failures.
+
+## Sandbox Playground
+
+The [sandbox](sandbox/README.md) directory ships with two toy modules (`normalize` and `stats`) that showcase:
+
+- How `requirements.txt` triggers a module-specific virtual environment.
+- How `pyproject.toml` causes execution via `uv run`.
+- How you can manually chain modules by parsing the `stdout` from the first run and feeding it into the next.
+
+Run everything with:
+
+```bash
+python sandbox/run_examples.py
+```
+
+Use this folder as a template to create your own modules or to test different deployment scenarios.
+
+## Development
+
+```bash
+git clone https://github.com/<seu-usuario>/module_runner.git
+cd module_runner
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Feel free to open issues or pull requests with improvements. The scope intentionally stays small: reliable environment setup and process execution.
+
+## License
+
+Module Runner is released under the MIT License. See [LICENSE](LICENSE) for details.

module_runner-0.1.0/module_runner/__init__.py

@@ -0,0 +1,7 @@
+from .runner import Runner
+from .exceptions import RunnerExecutionError
+from .environment import EnvironmentMode
+
+__version__ = "0.1.0"
+
+__all__ = ["Runner", "RunnerExecutionError", "EnvironmentMode", "__version__"]

module_runner-0.1.0/module_runner/environment/__init__.py

@@ -0,0 +1,4 @@
+from .mode import EnvironmentMode
+from .manager import EnvironmentManager
+
+__all__ = ["EnvironmentMode", "EnvironmentManager"]

module_runner-0.1.0/module_runner/environment/constants.py

@@ -0,0 +1,4 @@
+PYPROJECT_TOML = "pyproject.toml"
+REQUIREMENTS_TXT = "requirements.txt"
+MAIN_PY = "main.py"
+VENV_DIR = ".venv"

module_runner-0.1.0/module_runner/environment/manager.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+import sys
+
+from .mode import EnvironmentMode
+from .resolver import resolve_mode
+from .pip_env import ensure_pip_environment
+from .uv_env import ensure_uv_environment
+
+
+class EnvironmentManager:
+
+    def __init__(self, module_path: Path, mode: EnvironmentMode | str = EnvironmentMode.AUTO):
+        self.module_path = module_path
+        self.module_name = module_path.name
+        self.mode = self._coerce_mode(mode)
+
+    def _coerce_mode(self, mode: EnvironmentMode | str) -> EnvironmentMode:
+        if isinstance(mode, EnvironmentMode):
+            return mode
+
+        try:
+            return EnvironmentMode(mode)
+        except ValueError as exc:
+            raise RuntimeError(
+                f"Unsupported environment mode '{mode}' for module '{self.module_name}'"
+            ) from exc
+
+    def resolve(self) -> EnvironmentMode:
+        return resolve_mode(self.module_path, self.mode, self.module_name)
+
+    def ensure(self) -> Path:
+        env_type = self.resolve()
+
+        if env_type is EnvironmentMode.UV:
+            return ensure_uv_environment(self.module_path, self.module_name)
+
+        if env_type is EnvironmentMode.PIP:
+            return ensure_pip_environment(self.module_path, self.module_name)
+
+        return Path(sys.executable)

module_runner-0.1.0/module_runner/environment/mode.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class EnvironmentMode(str, Enum):
+    AUTO = "auto"
+    UV = "uv"
+    PIP = "pip"
+    SYSTEM = "system"

module_runner-0.1.0/module_runner/environment/pip_env.py

@@ -0,0 +1,60 @@
+import importlib.util
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+from .constants import PYPROJECT_TOML, REQUIREMENTS_TXT, VENV_DIR
+from .utils import venv_python
+from .mode import EnvironmentMode
+
+logger = logging.getLogger("module_runner")
+
+
+def ensure_pip_environment(module_path: Path, module_name: str) -> Path:
+    """Provision and return the Python interpreter inside a venv."""
+    if importlib.util.find_spec("venv") is None:
+        detail = "pip mode requires the standard library venv module, but it is unavailable"
+        raise RuntimeError(
+            f"Environment '{EnvironmentMode.PIP.value}' is unavailable for module '{module_name}': {detail}"
+        )
+
+    venv_path = module_path / VENV_DIR
+    python_bin = venv_python(venv_path)
+
+    if not venv_path.exists():
+        create_cmd = [sys.executable, "-m", "venv", str(venv_path)]
+        logger.info("[%s] creating venv: %s", module_name, " ".join(create_cmd))
+        _run_checked(create_cmd, module_path, module_name, "create virtual environment")
+
+        pyproject = module_path / PYPROJECT_TOML
+        req = module_path / REQUIREMENTS_TXT
+
+        if pyproject.exists():
+            install_cmd = [str(python_bin), "-m", "pip", "install", "."]
+            logger.info("[%s] installing deps: %s", module_name, " ".join(install_cmd))
+            _run_checked(install_cmd, module_path, module_name, "install dependencies from pyproject.toml")
+        elif req.exists():
+            install_cmd = [str(python_bin), "-m", "pip", "install", "-r", str(req)]
+            logger.info("[%s] installing deps: %s", module_name, " ".join(install_cmd))
+            _run_checked(install_cmd, module_path, module_name, "install requirements")
+    else:
+        logger.info("[%s] reusing existing venv at %s", module_name, venv_path)
+
+    return python_bin
+
+
+def _run_checked(cmd: list[str], module_path: Path, module_name: str, action: str) -> None:
+    try:
+        subprocess.run(
+            cmd,
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=str(module_path),
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip() if exc.stderr else str(exc)
+        raise RuntimeError(
+            f"Environment '{EnvironmentMode.PIP.value}' failed to {action} for module '{module_name}': {stderr}"
+        ) from exc

module_runner-0.1.0/module_runner/environment/resolver.py

@@ -0,0 +1,50 @@
+import importlib.util
+import logging
+import shutil
+from pathlib import Path
+
+from .constants import PYPROJECT_TOML, REQUIREMENTS_TXT
+from .mode import EnvironmentMode
+
+logger = logging.getLogger("module_runner")
+
+
+def resolve_mode(module_path: Path, requested: EnvironmentMode, module_name: str) -> EnvironmentMode:
+    """Determine which environment mode should be used for the module."""
+    if requested is not EnvironmentMode.AUTO:
+        return requested
+
+    has_pyproject = (module_path / PYPROJECT_TOML).exists()
+    has_requirements = (module_path / REQUIREMENTS_TXT).exists()
+    uv_available = shutil.which("uv") is not None
+    pip_available = importlib.util.find_spec("venv") is not None
+
+    if has_pyproject:
+        if uv_available:
+            logger.info("[%s] strategy=uv  (pyproject.toml detected, uv available)", module_name)
+            return EnvironmentMode.UV
+
+        if pip_available:
+            logger.info("[%s] strategy=pip  (pyproject.toml detected, uv unavailable — fallback to venv+pip)", module_name)
+            return EnvironmentMode.PIP
+
+        detail = f"{PYPROJECT_TOML} detected but neither uv nor venv is available"
+        raise RuntimeError(
+            f"Environment setup failed for module '{module_name}': {detail}"
+        )
+
+    if has_requirements:
+        if uv_available:
+            logger.info("[%s] strategy=uv  (requirements.txt detected, uv available)", module_name)
+            return EnvironmentMode.UV
+        if pip_available:
+            logger.info("[%s] strategy=pip  (requirements.txt detected, uv unavailable — fallback to venv+pip)", module_name)
+            return EnvironmentMode.PIP
+
+        detail = f"{REQUIREMENTS_TXT} detected but pip is unavailable"
+        raise RuntimeError(
+            f"Environment '{EnvironmentMode.PIP.value}' is unavailable for module '{module_name}': {detail}"
+        )
+
+    logger.info("[%s] strategy=system  (no dependency file found, using current interpreter)", module_name)
+    return EnvironmentMode.SYSTEM

module_runner-0.1.0/module_runner/environment/utils.py

@@ -0,0 +1,9 @@
+import sys
+from pathlib import Path
+
+
+def venv_python(venv_path: Path) -> Path:
+    """Return the Python interpreter path inside a virtual environment."""
+    if sys.platform.startswith("win"):
+        return venv_path / "Scripts" / "python.exe"
+    return venv_path / "bin" / "python"

module_runner-0.1.0/module_runner/environment/uv_env.py

@@ -0,0 +1,60 @@
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+
+from .constants import PYPROJECT_TOML, REQUIREMENTS_TXT, VENV_DIR
+from .utils import venv_python
+from .mode import EnvironmentMode
+
+logger = logging.getLogger("module_runner")
+
+
+def ensure_uv_environment(module_path: Path, module_name: str) -> Path:
+    """Ensure uv is available and provision dependencies in the module directory."""
+    uv_bin = shutil.which("uv")
+    if uv_bin is None:
+        raise RuntimeError(
+            f"Environment '{EnvironmentMode.UV.value}' is unavailable for module '{module_name}': uv executable not found in PATH"
+        )
+
+    requirements_path = module_path / REQUIREMENTS_TXT
+    pyproject_path = module_path / PYPROJECT_TOML
+
+    if requirements_path.exists() and not pyproject_path.exists():
+        venv_path = module_path / VENV_DIR
+        python_bin = venv_python(venv_path)
+        if not venv_path.exists():
+            create_cmd = [uv_bin, "venv"]
+            logger.info("[%s] creating venv: %s", module_name, " ".join(create_cmd))
+            _run_uv_checked(create_cmd, module_path, module_name, "create virtual environment")
+        else:
+            logger.info("[%s] reusing existing venv at %s", module_name, venv_path)
+        install_cmd = [uv_bin, "pip", "install", "-r", str(requirements_path)]
+        logger.info("[%s] installing deps: %s", module_name, " ".join(install_cmd))
+        _run_uv_checked(install_cmd, module_path, module_name, "install dependencies from requirements.txt")
+        return python_bin
+
+    logger.info("[%s] using uv run for pyproject.toml-based module", module_name)
+    return Path("uv")
+
+
+def _run_uv_checked(
+    cmd: list[str],
+    module_path: Path,
+    module_name: str,
+    action: str,
+) -> None:
+    try:
+        subprocess.run(
+            cmd,
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=str(module_path),
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip() if exc.stderr else str(exc)
+        raise RuntimeError(
+            f"Environment '{EnvironmentMode.UV.value}' failed to {action} for module '{module_name}': {stderr}"
+        ) from exc

module_runner-0.1.0/module_runner/exceptions.py

@@ -0,0 +1,33 @@
+from typing import Optional
+
+
+class RunnerExecutionError(Exception):
+    def __init__(
+        self,
+        module: str,
+        exit_code: int,
+        stderr: str,
+        stdout: str = "",
+        cmd: Optional[list[str]] = None,
+    ):
+        self.module = module
+        self.exit_code = exit_code
+        self.stderr = stderr
+        self.stdout = stdout
+        self.cmd = cmd
+
+        parts = [f"Module '{module}' failed with exit code {exit_code}"]
+
+        if cmd:
+            parts.append(f"  command : {' '.join(cmd)}")
+
+        if stderr.strip():
+            parts.append(f"  stderr  : {stderr.strip()}")
+
+        if stdout.strip():
+            parts.append(f"  stdout  : {stdout.strip()}")
+
+        if not stderr.strip() and not stdout.strip():
+            parts.append("  (no output captured)")
+
+        super().__init__("\n".join(parts))

module_runner-0.1.0/module_runner/runner.py

@@ -0,0 +1,60 @@
+import json
+import logging
+import subprocess
+from pathlib import Path
+from subprocess import CompletedProcess
+from typing import Optional
+
+from .exceptions import RunnerExecutionError
+from .environment import EnvironmentManager, EnvironmentMode
+from .environment.constants import MAIN_PY
+
+logger = logging.getLogger("module_runner")
+
+
+class Runner:
+
+    def __init__(self, module_path: str | Path, environment: EnvironmentMode | str = EnvironmentMode.AUTO) -> None:
+        self.module_path = Path(module_path).resolve()
+        self.environment = environment
+        self.module_name = self.module_path.name
+
+    def run(
+        self,
+        payload: Optional[dict] = None,
+    ) -> CompletedProcess[str]:
+        script_path = self.module_path / MAIN_PY
+
+        if not script_path.exists():
+            raise FileNotFoundError(f"Module '{self.module_name}' does not contain {MAIN_PY}")
+
+        env_manager = EnvironmentManager(self.module_path, self.environment)
+        executor = env_manager.ensure()
+
+        if str(executor) == "uv":
+            cmd = ["uv", "run", "--project", str(self.module_path), "python", str(script_path)]
+        else:
+            cmd = [str(executor), str(script_path)]
+
+        if payload is not None:
+            cmd.append(json.dumps(payload))
+
+        logger.info("[%s] executing: %s", self.module_name, " ".join(cmd))
+
+        process: CompletedProcess[str] = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=str(self.module_path),
+        )
+
+        if process.returncode != 0:
+            raise RunnerExecutionError(
+                module=self.module_name,
+                exit_code=process.returncode,
+                stderr=process.stderr,
+                stdout=process.stdout,
+                cmd=cmd,
+            )
+
+        return process

module_runner-0.1.0/module_runner.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: module-runner
+Version: 0.1.0
+Summary: Lightweight helper that prepares Python environments and executes standalone modules.
+Author: Leo Jaimesson
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Module Runner
+
+Module Runner sits in the gap between ad-hoc scripts and heavyweight orchestration frameworks. It gives each module a predictable, isolated environment without asking you to bolt on extra infrastructure, schedulers, or workflow engines. The project stays intentionally lightweight and focuses on two responsibilities:
+
+1. Detect the proper execution strategy (system Python, `venv`, or `uv`).
+2. Launch the module with an optional JSON payload, returning the `subprocess.CompletedProcess` so you can decide how to consume `stdout`, `stderr`, or exit codes.
+
+Any higher-level orchestration (pipelines, RPC, shared storage, etc.) is an application concern, keeping this library small and predictable.
+
+## Features
+
+- ⚙️ **Automatic environment discovery**: detects `pyproject.toml` or `requirements.txt` (→ `uv` when available, `venv` as fallback), or falls back to the current interpreter.
+- 📦 **Per-module dependencies**: each module lives in its own folder with its own toolchain, avoiding cross-contamination.
+- 🧱 **Opinionated boundary**: no implicit payload chaining—what a module prints, writes, or exposes is entirely up to you.
+- 🪪 **Clear error surface**: `RunnerExecutionError` captures module failures while missing tooling raises descriptive `RuntimeError`s, keeping debugging straightforward.
+- 🔍 **Built-in logging**: uses Python's standard `logging` module under the `module_runner` logger — enable `DEBUG` to see the resolved strategy, every setup command, and the final execution command.
+
+## Logging
+
+Module Runner emits `INFO`-level log records under the `module_runner` logger. To see them:
+
+```python
+import logging
+logging.getLogger("module_runner").setLevel(logging.INFO)
+logging.basicConfig()
+```
+
+Example output:
+```
+[normalize] strategy=pip  (requirements.txt detected, uv unavailable — fallback to venv+pip)
+[normalize] creating venv: /usr/bin/python3 -m venv .venv
+[normalize] installing deps: .venv/bin/python -m pip install -r requirements.txt
+[normalize] executing: .venv/bin/python main.py {"text": " Hello World "}
+```
+
+## Why This Exists
+
+Module Runner is the missing middle layer between one-off helper scripts and enterprise orchestrators. It gives you just enough structure to keep automation tidy while remaining lightweight, infrastructure-free, and dependency-light.
+
+## When to Use
+
+Use Module Runner when you:
+
+- Need simple local automation or scripting glue with a lightweight footprint
+- Have dependency conflicts between scripts and want per-module isolation
+- Want predictable, sequential execution you can reason about
+- Prefer to stay container-free for lightweight tasks
+- Do not need a workflow engine or task scheduler
+
+## When Not to Use
+
+Reach for other tooling if you require:
+
+- Complex DAG dependencies or branching workflows
+- Scheduling, cron-style orchestration, or SLAs
+- Distributed workers or autoscaling fleets
+- Monitoring dashboards, retries, or alerting UI
+- Enterprise workflow/orchestration guarantees
+
+## Philosophy
+
+- Small, explicit, predictable, and lightweight
+- Infrastructure-free: relies on the Python already on your machine
+- Focused on one problem—launching modules in clean environments
+
+It is not meant to be a workflow engine; it simply keeps isolated scripts manageable.
+
+## Installation
+
+```bash
+# using pip
+pip install module_runner
+
+# using uv
+uv add module_runner
+
+```
+
+You only need Python 3.9+ and whichever tooling your modules request (e.g., `uv`, `venv`, system packages).
+
+## Quick Start
+
+```python
+from module_runner import Runner
+
+runner = Runner(module_path="modules/normalize_text")
+
+process = runner.run(
+    payload={"text": " Hello World "},
+)
+
+print(process.stdout)  # or json.loads(process.stdout)
+```
+
+Your module layout needs a `main.py` entry point. Any payload you pass is serialized as JSON and delivered as the last CLI argument. How you emit results (stdout, files, sockets) is entirely your call.
+
+## Environment Selection
+
+| Signal in module folder | Mode used     | Requirement |
+| ----------------------- | ------------- | ----------- |
+| `pyproject.toml`        | `uv run ...`  | `uv` available in `PATH` |
+| `pyproject.toml` (no `uv`) | `python -m venv` + `pip install .` | `venv` module available |
+| `requirements.txt`      | `uv venv` + `uv pip install -r requirements.txt` | `uv` available in `PATH` |
+| `requirements.txt` (no `uv`) | `python -m venv` + `pip install -r requirements.txt` | `venv` module available |
+| none of the above       | current interpreter (`sys.executable`) | none |
+
+- Auto-detection always checks whether the required tooling is installed. When `uv` is available it is preferred for both `pyproject.toml` and `requirements.txt` modules. If `uv` is not available, both `pyproject.toml` and `requirements.txt` modules fall back to `venv`/`pip`.
+- If a module signals that it needs `uv` or `venv` but the corresponding tooling is missing, Module Runner raises a descriptive `RuntimeError` explaining what needs to be installed.
+- Runtime failures propagate as `RunnerExecutionError`, exposing the module name, exit code, captured `stderr`, captured `stdout`, and the exact `cmd` list that was executed — making it straightforward to reproduce or log failures.
+
+## Sandbox Playground
+
+The [sandbox](sandbox/README.md) directory ships with two toy modules (`normalize` and `stats`) that showcase:
+
+- How `requirements.txt` triggers a module-specific virtual environment.
+- How `pyproject.toml` causes execution via `uv run`.
+- How you can manually chain modules by parsing the `stdout` from the first run and feeding it into the next.
+
+Run everything with:
+
+```bash
+python sandbox/run_examples.py
+```
+
+Use this folder as a template to create your own modules or to test different deployment scenarios.
+
+## Development
+
+```bash
+git clone https://github.com/<seu-usuario>/module_runner.git
+cd module_runner
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Feel free to open issues or pull requests with improvements. The scope intentionally stays small: reliable environment setup and process execution.
+
+## License
+
+Module Runner is released under the MIT License. See [LICENSE](LICENSE) for details.

module_runner-0.1.0/module_runner.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+module_runner/__init__.py
+module_runner/environments.py
+module_runner/exceptions.py
+module_runner/runner.py
+module_runner.egg-info/PKG-INFO
+module_runner.egg-info/SOURCES.txt
+module_runner.egg-info/dependency_links.txt
+module_runner.egg-info/top_level.txt
+module_runner/environment/__init__.py
+module_runner/environment/constants.py
+module_runner/environment/manager.py
+module_runner/environment/mode.py
+module_runner/environment/pip_env.py
+module_runner/environment/resolver.py
+module_runner/environment/utils.py
+module_runner/environment/uv_env.py

module_runner-0.1.0/module_runner.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

module_runner-0.1.0/module_runner.egg-info/top_level.txt

@@ -0,0 +1 @@
+module_runner

module_runner-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "module-runner"
+version = "0.1.0"
+description = "Lightweight helper that prepares Python environments and executes standalone modules."
+authors = [{name = "Leo Jaimesson"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.setuptools.packages.find]
+include = ["module_runner*"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

module_runner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+