supypowers 0.1.0__tar.gz

supypowers-0.1.0/.env

@@ -0,0 +1,2 @@
+TWINE_USERNAME=__token__
+TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmcCJDA1OGE0M2UzLTM2ZmUtNDc2MS1iMmIyLWM2YzA5NDcwYWIwMQACKlszLCI0ZGE0ZTZiOS0xMzZmLTRkYTQtYjIxMC01MzA3YzdlMGUwZTEiXQAABiDnbNsTYypADQGQFOGx5F6Z3X6lSFvkmr6MP0ii47tQ3Q

supypowers-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Run tests
+        run: uv run python -m unittest discover -s tests -p "test_*.py" -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist+wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+

supypowers-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/supypowers
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+

supypowers-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+dist/
+build/
+*.egg-info/

supypowers-0.1.0/LICENSE

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

supypowers-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: supypowers
+Version: 0.1.0
+Summary: Run self-contained uv Python scripts as callable, schema-documented 'superpowers'.
+Project-URL: Homepage, https://github.com/ergodic-ai/supypowers
+Project-URL: Repository, https://github.com/ergodic-ai/supypowers
+Author: Andre
+License: MIT License
+        
+        Copyright (c) 2026 Andre
+        
+        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.
+        
+License-File: LICENSE
+Keywords: automation,cli,llm,pydantic,tools,uv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# supypowers
+
+Run self-contained Python scripts (with `uv` script dependencies) as callable, schema-documented functions.
+
+## Install
+
+```bash
+pip install supypowers
+```
+
+Note: the CLI expects [`uv`](https://github.com/astral-sh/uv) to be installed on your machine (it shells out to `uv run`).
+
+## Release to PyPI (recommended: GitHub Actions)
+
+- Create a PyPI project using **Trusted Publishing** for your GitHub repo.
+- Tag a release:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+The workflow in `.github/workflows/publish.yml` will build and publish `dist/*` to PyPI.
+
+## Run (no venv)
+
+From this repo root:
+
+```bash
+uv run supypowers examples docs
+uv run supypowers examples run exponents:compute_sqrt \"{'x': 9}\" --secrets .env --secrets API_KEY=abc
+```
+
+From anywhere:
+
+```bash
+uv run --project /Users/andre/ergodic/superpowers supypowers examples docs
+```
+
+## Install `supypowers` on your PATH (so you can run `supypowers ...`)
+
+Use `uv tool install`:
+
+```bash
+cd /Users/andre/ergodic/superpowers
+uv tool install --editable .
+uv tool update-shell
+```
+
+Then open a new shell (or reload your shell config) and run:
+
+```bash
+supypowers examples docs
+supypowers examples run exponents:compute_sqrt \"{'x': 9}\"
+```
+
+## Example scripts
+
+See `examples/` (uses `uv` script metadata + Pydantic models).
+
+## Notes
+
+- The CLI executes target scripts **only** via `uv run <script.py> ...` (no imports into the CLI process).

supypowers-0.1.0/README.md

@@ -0,0 +1,63 @@
+# supypowers
+
+Run self-contained Python scripts (with `uv` script dependencies) as callable, schema-documented functions.
+
+## Install
+
+```bash
+pip install supypowers
+```
+
+Note: the CLI expects [`uv`](https://github.com/astral-sh/uv) to be installed on your machine (it shells out to `uv run`).
+
+## Release to PyPI (recommended: GitHub Actions)
+
+- Create a PyPI project using **Trusted Publishing** for your GitHub repo.
+- Tag a release:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+The workflow in `.github/workflows/publish.yml` will build and publish `dist/*` to PyPI.
+
+## Run (no venv)
+
+From this repo root:
+
+```bash
+uv run supypowers examples docs
+uv run supypowers examples run exponents:compute_sqrt \"{'x': 9}\" --secrets .env --secrets API_KEY=abc
+```
+
+From anywhere:
+
+```bash
+uv run --project /Users/andre/ergodic/superpowers supypowers examples docs
+```
+
+## Install `supypowers` on your PATH (so you can run `supypowers ...`)
+
+Use `uv tool install`:
+
+```bash
+cd /Users/andre/ergodic/superpowers
+uv tool install --editable .
+uv tool update-shell
+```
+
+Then open a new shell (or reload your shell config) and run:
+
+```bash
+supypowers examples docs
+supypowers examples run exponents:compute_sqrt \"{'x': 9}\"
+```
+
+## Example scripts
+
+See `examples/` (uses `uv` script metadata + Pydantic models).
+
+## Notes
+
+- The CLI executes target scripts **only** via `uv run <script.py> ...` (no imports into the CLI process).

supypowers-0.1.0/examples/dates.py

@@ -0,0 +1,38 @@
+# /// script
+# dependencies = [
+#   "pydantic",
+# ]
+# ///
+
+from datetime import date, timedelta
+
+from pydantic import BaseModel, Field
+
+
+class AddDaysInput(BaseModel):
+    d: date = Field(..., description="Date (YYYY-MM-DD).")
+    days: int = Field(..., description="Days to add (can be negative).")
+
+
+class AddDaysOutput(BaseModel):
+    result: date = Field(..., description="Resulting date (YYYY-MM-DD).")
+
+
+def add_days(input: AddDaysInput) -> AddDaysOutput:
+    """Add (or subtract) a number of days from a date."""
+    return AddDaysOutput(result=input.d + timedelta(days=input.days))
+
+
+class DaysBetweenInput(BaseModel):
+    start: date = Field(..., description="Start date (YYYY-MM-DD).")
+    end: date = Field(..., description="End date (YYYY-MM-DD).")
+
+
+class DaysBetweenOutput(BaseModel):
+    days: int = Field(..., description="Number of days between end and start.")
+
+
+def days_between(input: DaysBetweenInput) -> DaysBetweenOutput:
+    """Compute the day delta between two dates (end - start)."""
+    return DaysBetweenOutput(days=(input.end - input.start).days)
+

supypowers-0.1.0/examples/exponents.py

@@ -0,0 +1,42 @@
+# /// script
+# dependencies = [
+#   "pydantic",
+# ]
+# ///
+
+import sys
+from math import sqrt
+from pydantic import BaseModel, Field
+
+
+class ComputeSqrtInput(BaseModel):
+    x: float = Field(..., description="The number to compute the square root of.")
+
+
+class ComputeSqrtOutput(BaseModel):
+    result: float = Field(..., description="The square root of the number.")
+
+
+def compute_sqrt(input: ComputeSqrtInput) -> ComputeSqrtOutput:
+    """This function computes the square root of a number."""
+    return ComputeSqrtOutput(result=sqrt(input.x))
+
+
+class ComputeDifferentPowerInput(BaseModel):
+    x: float = Field(..., description="The number to compute the different powers of.")
+    n: int = Field(..., description="The power to compute.")
+
+
+class ComputeDifferentPowerOutput(BaseModel):
+    result: float = Field(..., description="The different powers of the number.")
+
+
+def compute_different_power(
+    input: ComputeDifferentPowerInput,
+) -> ComputeDifferentPowerOutput:
+    """This function computes the different powers of a number."""
+    return ComputeDifferentPowerOutput(result=input.x**input.n)
+
+
+if __name__ == "__main__":
+    print(sys.argv)

supypowers-0.1.0/examples/misc.py

@@ -0,0 +1,19 @@
+# /// script
+# dependencies = [
+#   "pydantic",
+# ]
+# ///
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class EchoInput(BaseModel):
+    message: str = Field(..., description="Message to echo back.")
+
+
+def echo(input: EchoInput) -> str:
+    """Return a plain string (non-Pydantic output)."""
+    return input.message
+

supypowers-0.1.0/examples/strings.py

@@ -0,0 +1,37 @@
+# /// script
+# dependencies = [
+#   "pydantic",
+# ]
+# ///
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ReverseStringInput(BaseModel):
+    s: str = Field(..., description="String to reverse.")
+
+
+class ReverseStringOutput(BaseModel):
+    result: str = Field(..., description="The reversed string.")
+
+
+def reverse_string(input: ReverseStringInput) -> ReverseStringOutput:
+    """Reverse a string."""
+    return ReverseStringOutput(result=input.s[::-1])
+
+
+class CountVowelsInput(BaseModel):
+    s: str = Field(..., description="String to count vowels in.")
+
+
+class CountVowelsOutput(BaseModel):
+    count: int = Field(..., description="Number of vowels in the string.")
+
+
+def count_vowels(input: CountVowelsInput) -> CountVowelsOutput:
+    """Count vowels in a string."""
+    vowels = set("aeiouAEIOU")
+    return CountVowelsOutput(count=sum(1 for ch in input.s if ch in vowels))
+

supypowers-0.1.0/project.md

@@ -0,0 +1,34 @@
+# Supypowers
+
+1. What is a superpower?
+
+Supypowers are essentially tools for LLMs, we want to create a library of functions that:
+
+- are self contained within a python script
+- can be executed using a CLI
+- don't require a server to be open
+
+A superpower is a python script that has the following properties:
+
+- One (or more functions) that accept a documented set of inputs (validated using a serialization library such as Pydantic)
+- Validated and documented set of outputs
+- It can be run without any venv being defined using uv's dependencies
+
+for example, in examples/exponents.py we have an example of how I want these functions to look like.
+
+2. What do we need to build?
+
+a) a CLI like
+
+`supypowers <folder_name> run <script>:<function> <input_json> --secrets <env_file_or_secrets>`
+
+`supypowers examples run exponents:compute_sqrt "{a:1}" ` which executes the function in the script. It should use uv's dependencies using uv's scripts framework
+
+b) a way to get the documentation out of every function that's accessible within the folder.. essentially I want a context to pass to the LLM. Each function should come with:
+
+- function name
+- function description
+- input schema
+- (optional) output schema or any
+
+b) possible decorators that need to go into the scripts to make life simpler (like defining requirements, defining documentations, etc)

supypowers-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "supypowers"
+version = "0.1.0"
+description = "Run self-contained uv Python scripts as callable, schema-documented 'superpowers'."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Andre", email = "" }]
+keywords = ["uv", "cli", "pydantic", "llm", "tools", "automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "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",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ergodic-ai/supypowers"
+Repository = "https://github.com/ergodic-ai/supypowers"
+
+[project.scripts]
+supypowers = "supypowers.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.24.2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/supypowers"]
+

supypowers-0.1.0/src/supypowers/__init__.py

@@ -0,0 +1,4 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

supypowers-0.1.0/src/supypowers/cli.py

@@ -0,0 +1,402 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from supypowers.uv_exec import UVRunError, uv_run_python_code
+from supypowers.util import parse_secrets_args, resolve_script_path
+
+
+def app() -> None:
+    parser = argparse.ArgumentParser(prog="supypowers")
+    parser.add_argument("folder", type=Path, help="Folder containing scripts")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_p = sub.add_parser("run", help="Run a function in a script via `uv run`")
+    run_p.add_argument("target", type=str, help="script:function (script may omit .py)")
+    run_p.add_argument("input_data", type=str, help="Input data (JSON or Python-literal-ish)")
+    run_p.add_argument(
+        "--secrets",
+        action="append",
+        default=[],
+        help="Secrets as a .env path or inline KEY=VAL. May be provided multiple times.",
+    )
+
+    docs_p = sub.add_parser("docs", help="Emit docs JSON or Markdown for discovered functions")
+    docs_p.add_argument("--recursive", action="store_true", help="Recurse into subfolders")
+    docs_p.add_argument(
+        "--format",
+        choices=["json", "md"],
+        default="json",
+        help="Output format (json or md).",
+    )
+    docs_p.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Write output to a file instead of stdout.",
+    )
+    docs_p.add_argument(
+        "--require-marker",
+        action="store_true",
+        help="Only include functions explicitly marked (currently: decorator named `superpower`).",
+    )
+    docs_p.add_argument(
+        "--secrets",
+        action="append",
+        default=[],
+        help="Secrets as a .env path or inline KEY=VAL. May be provided multiple times.",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        _cmd_run(args.folder, args.target, args.input_data, args.secrets)
+        return
+    if args.command == "docs":
+        _cmd_docs(
+            args.folder,
+            args.recursive,
+            args.require_marker,
+            args.secrets,
+            args.format,
+            args.output,
+        )
+        return
+
+    parser.error("unknown command")
+
+
+def _cmd_run(folder: Path, target: str, input_data: str, secrets: list[str]) -> None:
+    if not folder.exists() or not folder.is_dir():
+        print(json.dumps({"ok": False, "error": f"folder not found: {folder}"}))
+        raise SystemExit(2)
+
+    script_name, _, func_name = target.partition(":")
+    if not script_name or not func_name:
+        print(json.dumps({"ok": False, "error": "target must be in the form script:function"}))
+        raise SystemExit(2)
+
+    script_path = resolve_script_path(folder, script_name)
+    env = parse_secrets_args(secrets or [])
+
+    payload = {
+        "script_path": str(script_path),
+        "function_name": func_name,
+        "input_data": input_data,
+    }
+
+    try:
+        out = uv_run_python_code(
+            script_path=script_path,
+            code=_RUNNER_CODE,
+            payload=payload,
+            extra_env=env,
+        )
+    except UVRunError as e:
+        if e.stderr:
+            sys.stderr.write(e.stderr + "\n")
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "error": e.message,
+                    "exit_code": e.exit_code,
+                    "uv_stdout": e.stdout,
+                    "uv_stderr": e.stderr,
+                }
+            )
+        )
+        raise SystemExit(e.exit_code)
+
+    try:
+        parsed = json.loads(out)
+    except Exception:
+        print(json.dumps({"ok": False, "error": "runner did not emit valid JSON", "raw": out}))
+        raise SystemExit(1)
+
+    print(json.dumps(parsed, ensure_ascii=False))
+    raise SystemExit(0 if parsed.get("ok") else 1)
+
+
+def _cmd_docs(
+    folder: Path,
+    recursive: bool,
+    require_marker: bool,
+    secrets: list[str],
+    out_format: str,
+    output_path: Path | None,
+) -> None:
+    if not folder.exists() or not folder.is_dir():
+        print(json.dumps({"ok": False, "error": f"folder not found: {folder}"}))
+        raise SystemExit(2)
+
+    env = parse_secrets_args(secrets or [])
+
+    scripts = (
+        sorted(p for p in folder.rglob("*.py") if p.is_file())
+        if recursive
+        else sorted(p for p in folder.glob("*.py") if p.is_file())
+    )
+
+    docs_out: list[dict] = []
+    for script_path in scripts:
+        payload = {"script_path": str(script_path), "require_marker": require_marker}
+        try:
+            out = uv_run_python_code(
+                script_path=script_path,
+                code=_DOCS_CODE,
+                payload=payload,
+                extra_env=env,
+            )
+            docs_out.append(json.loads(out))
+        except Exception as e:
+            docs_out.append({"script": str(script_path), "error": str(e), "functions": []})
+
+    if out_format == "json":
+        rendered = json.dumps(docs_out, ensure_ascii=False)
+    else:
+        rendered = _docs_to_markdown(docs_out)
+
+    if output_path is not None:
+        output_path.write_text(rendered + "\n", encoding="utf-8")
+    else:
+        print(rendered)
+
+
+def _docs_to_markdown(docs_out: list[dict]) -> str:
+    lines: list[str] = []
+    lines.append("## Supypowers\n")
+    for item in docs_out:
+        script = item.get("script", "")
+        err = item.get("error")
+        lines.append(f"### `{script}`\n")
+        if err:
+            lines.append(f"**Error:** `{err}`\n")
+            continue
+        fns = item.get("functions") or []
+        if not fns:
+            lines.append("_No supypowers found._\n")
+            continue
+        for fn in fns:
+            name = fn.get("name", "")
+            desc = (fn.get("description") or "").strip()
+            lines.append(f"#### `{name}`\n")
+            if desc:
+                lines.append(desc + "\n")
+            in_schema = fn.get("input_schema")
+            out_schema = fn.get("output_schema")
+            lines.append("**Input schema**\n")
+            lines.append("```json")
+            lines.append(json.dumps(in_schema, ensure_ascii=False, indent=2))
+            lines.append("```\n")
+            lines.append("**Output schema**\n")
+            lines.append("```json")
+            lines.append(json.dumps(out_schema, ensure_ascii=False, indent=2))
+            lines.append("```\n")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+_RUNNER_CODE = r"""
+import ast
+import importlib.util
+import inspect
+import json
+import sys
+import typing
+
+def _parse_input(s):
+    s = s.strip()
+    try:
+        return json.loads(s)
+    except Exception:
+        pass
+    # "YAML-ish" best-effort: accept Python literals (e.g. {'x': 1}, [1,2], True, None).
+    try:
+        return ast.literal_eval(s)
+    except Exception:
+        raise ValueError("input_data must be valid JSON or a Python-literal-ish value")
+
+def _load_module_from_path(path):
+    spec = importlib.util.spec_from_file_location("__supypowers_target__", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+def _is_pydantic_model(cls):
+    try:
+        from pydantic import BaseModel
+        return isinstance(cls, type) and issubclass(cls, BaseModel)
+    except Exception:
+        return False
+
+def _resolved_type_hints(fn, mod):
+    try:
+        return typing.get_type_hints(fn, globalns=vars(mod), localns=vars(mod))
+    except Exception:
+        return {}
+
+def _model_to_jsonable(obj):
+    # Pydantic v2: model_dump(); v1: dict()
+    if hasattr(obj, "model_dump"):
+        try:
+            return obj.model_dump(mode="json")
+        except Exception:
+            return obj.model_dump()
+    if hasattr(obj, "dict"):
+        return obj.dict()
+    return obj
+
+def main():
+    payload = json.loads(sys.stdin.read())
+    script_path = payload["script_path"]
+    fn_name = payload["function_name"]
+    input_data = payload["input_data"]
+
+    mod = _load_module_from_path(script_path)
+    fn = getattr(mod, fn_name, None)
+    if fn is None or not callable(fn):
+        print(json.dumps({"ok": False, "error": f"function not found: {fn_name}"}))
+        return 2
+
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+    if len(params) != 1:
+        print(json.dumps({"ok": False, "error": "function must accept exactly one parameter named `input`"}))
+        return 2
+
+    param = params[0]
+    if param.name != "input":
+        print(json.dumps({"ok": False, "error": "function parameter must be named `input`"}))
+        return 2
+
+    hints = _resolved_type_hints(fn, mod)
+    ann = hints.get(param.name, param.annotation)
+    raw = _parse_input(input_data)
+
+    try:
+        if not _is_pydantic_model(ann):
+            print(json.dumps({"ok": False, "error": "input must be a Pydantic BaseModel type annotation"}))
+            return 2
+        if not isinstance(raw, dict):
+            print(json.dumps({"ok": False, "error": "input_data must be an object mapping for the input model"}))
+            return 2
+        inp = ann.model_validate(raw) if hasattr(ann, "model_validate") else ann.parse_obj(raw)
+        result = fn(inp)
+        out = _model_to_jsonable(result)
+        try:
+            json.dumps(out)
+        except Exception:
+            out = str(out)
+        print(json.dumps({"ok": True, "data": out}, ensure_ascii=False))
+        return 0
+    except Exception as e:
+        print(json.dumps({"ok": False, "error": str(e)}, ensure_ascii=False))
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())
+"""
+
+
+_DOCS_CODE = r"""
+import ast
+import importlib.util
+import inspect
+import json
+import sys
+import typing
+
+def _load_module_from_path(path):
+    spec = importlib.util.spec_from_file_location("__supypowers_target__", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+def _is_pydantic_model(cls):
+    try:
+        from pydantic import BaseModel
+        return isinstance(cls, type) and issubclass(cls, BaseModel)
+    except Exception:
+        return False
+
+def _resolved_type_hints(fn, mod):
+    try:
+        return typing.get_type_hints(fn, globalns=vars(mod), localns=vars(mod))
+    except Exception:
+        return {}
+
+def _schema_for_model(model_cls):
+    try:
+        return model_cls.model_json_schema()
+    except Exception:
+        try:
+            return model_cls.schema()
+        except Exception:
+            return None
+
+def _has_superpower_decorator(script_path, fn_name):
+    try:
+        src = open(script_path, "r", encoding="utf-8").read()
+        tree = ast.parse(src)
+        for node in tree.body:
+            if isinstance(node, ast.FunctionDef) and node.name == fn_name:
+                for dec in node.decorator_list:
+                    if isinstance(dec, ast.Name) and dec.id == "superpower":
+                        return True
+                    if isinstance(dec, ast.Attribute) and dec.attr == "superpower":
+                        return True
+        return False
+    except Exception:
+        return False
+
+def main():
+    payload = json.loads(sys.stdin.read())
+    script_path = payload["script_path"]
+    require_marker = bool(payload.get("require_marker"))
+
+    mod = _load_module_from_path(script_path)
+
+    fns = []
+    for name, obj in sorted(vars(mod).items()):
+        if name.startswith("_"):
+            continue
+        if not callable(obj):
+            continue
+        try:
+            sig = inspect.signature(obj)
+        except Exception:
+            continue
+        params = list(sig.parameters.values())
+        if len(params) != 1:
+            continue
+        if params[0].name != "input":
+            continue
+        hints = _resolved_type_hints(obj, mod)
+        ann_in = hints.get(params[0].name, params[0].annotation)
+        if require_marker and not _has_superpower_decorator(script_path, name):
+            continue
+        if not _is_pydantic_model(ann_in):
+            continue
+
+        ann_out = hints.get("return", sig.return_annotation)
+        fns.append({
+            "name": name,
+            "description": inspect.getdoc(obj) or "",
+            "input_schema": _schema_for_model(ann_in) if _is_pydantic_model(ann_in) else None,
+            "output_schema": _schema_for_model(ann_out) if _is_pydantic_model(ann_out) else None,
+        })
+
+    print(json.dumps({"script": script_path, "functions": fns}, ensure_ascii=False))
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())
+"""
+
+
+if __name__ == "__main__":
+    app()
+

supypowers-0.1.0/src/supypowers/util.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Iterable
+
+
+def resolve_script_path(folder: Path, script_name: str) -> Path:
+    """
+    Resolve a script name (with or without .py) within a folder.
+    """
+    name = script_name if script_name.endswith(".py") else f"{script_name}.py"
+    p = (folder / name).resolve()
+    if not p.exists() or not p.is_file():
+        raise FileNotFoundError(f"Script not found: {p}")
+    return p
+
+
+def _parse_dotenv(text: str) -> Dict[str, str]:
+    env: Dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        k = k.strip()
+        v = v.strip().strip('"').strip("'")
+        if k:
+            env[k] = v
+    return env
+
+
+def parse_secrets_args(secrets_args: Iterable[str]) -> Dict[str, str]:
+    """
+    Accept secrets as either:
+    - a path to a dotenv file
+    - inline KEY=VAL
+    """
+    out: Dict[str, str] = {}
+    for s in secrets_args:
+        if "=" in s and not Path(s).exists():
+            k, v = s.split("=", 1)
+            out[k] = v
+            continue
+        p = Path(s)
+        if p.exists() and p.is_file():
+            out.update(_parse_dotenv(p.read_text(encoding="utf-8")))
+            continue
+        # Fall back: if it contains '=', treat as inline even if the path doesn't exist.
+        if "=" in s:
+            k, v = s.split("=", 1)
+            out[k] = v
+            continue
+        raise ValueError(f"--secrets value must be a .env path or KEY=VAL, got: {s}")
+    return out
+

supypowers-0.1.0/src/supypowers/uv_exec.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Optional
+
+from supypowers.uv_script_metadata import read_uv_script_dependencies
+
+
+@dataclass(frozen=True)
+class UVRunError(Exception):
+    message: str
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+def uv_run_python_code(
+    *,
+    script_path: Path,
+    code: str,
+    payload: dict,
+    extra_env: Optional[Dict[str, str]] = None,
+    quiet: bool = True,
+) -> str:
+    """
+    Execute `python -c <code>` in a uv environment built from `script_path` inline dependencies,
+    sending `payload` via stdin and returning stdout.
+    """
+    env = os.environ.copy()
+    if extra_env:
+        env.update(extra_env)
+
+    deps = read_uv_script_dependencies(script_path)
+
+    cmd = ["uv", "run", "--no-project"]
+    if quiet:
+        cmd.extend(["-q", "--no-progress"])
+    for dep in deps:
+        cmd.extend(["--with", dep])
+    cmd.extend(["python", "-c", code])
+
+    proc = subprocess.run(
+        cmd,
+        input=json.dumps(payload).encode("utf-8"),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+
+    stdout = proc.stdout.decode("utf-8", errors="replace").strip()
+    stderr = proc.stderr.decode("utf-8", errors="replace").strip()
+
+    if proc.returncode != 0:
+        raise UVRunError(
+            message=f"`uv run` failed with exit code {proc.returncode}",
+            exit_code=proc.returncode,
+            stdout=stdout,
+            stderr=stderr,
+        )
+
+    return stdout
+

supypowers-0.1.0/src/supypowers/uv_script_metadata.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import List
+
+
+def read_uv_script_dependencies(script_path: Path) -> List[str]:
+    """
+    Parse `uv` inline script metadata and return its dependency strings.
+
+    Supports the common form:
+
+    # /// script
+    # dependencies = [
+    #   "pydantic",
+    # ]
+    # ///
+    """
+    try:
+        text = script_path.read_text(encoding="utf-8")
+    except Exception:
+        return []
+
+    lines = text.splitlines()
+    start = None
+    end = None
+    for i, line in enumerate(lines):
+        if line.strip() == "# /// script":
+            start = i + 1
+            continue
+        if start is not None and line.strip() == "# ///":
+            end = i
+            break
+
+    if start is None or end is None or end <= start:
+        return []
+
+    # Strip leading comment markers.
+    meta_lines = []
+    for raw in lines[start:end]:
+        s = raw.lstrip()
+        if s.startswith("#"):
+            s = s[1:]
+            if s.startswith(" "):
+                s = s[1:]
+        meta_lines.append(s)
+
+    meta_src = "\n".join(meta_lines).strip()
+    if not meta_src:
+        return []
+
+    # Parse assignments in the metadata block.
+    try:
+        tree = ast.parse(meta_src, mode="exec")
+    except Exception:
+        return []
+
+    deps: List[str] = []
+    for node in tree.body:
+        if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+            continue
+        target = node.targets[0]
+        if not isinstance(target, ast.Name) or target.id != "dependencies":
+            continue
+        try:
+            value = ast.literal_eval(node.value)
+        except Exception:
+            continue
+        if isinstance(value, list):
+            for item in value:
+                if isinstance(item, str):
+                    deps.append(item)
+        break
+
+    return deps
+

supypowers-0.1.0/tests/test_cli.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLES = ROOT / "examples"
+
+
+def _run_uv_superpowers(*args: str) -> dict:
+    """
+    Run: uv run supypowers <args...>
+    and parse stdout as JSON.
+    """
+    if shutil.which("uv") is None:
+        raise unittest.SkipTest("uv not found on PATH")
+
+    cmd = ["uv", "run", "supypowers", *args]
+    proc = subprocess.run(
+        cmd,
+        cwd=str(ROOT),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=os.environ.copy(),
+        text=True,
+    )
+    out = proc.stdout.strip()
+    err = proc.stderr.strip()
+    if proc.returncode != 0:
+        raise AssertionError(f"command failed ({proc.returncode})\ncmd={cmd}\nstdout={out}\nstderr={err}")
+    try:
+        return json.loads(out)
+    except Exception as e:
+        raise AssertionError(f"stdout was not JSON\ncmd={cmd}\nstdout={out}\nstderr={err}\nerr={e}")
+
+
+class TestCLI(unittest.TestCase):
+    def test_docs_includes_exponents(self) -> None:
+        docs = _run_uv_superpowers(str(EXAMPLES), "docs")
+        # docs is a list of {"script": ..., "functions": [...]}
+        by_script = {Path(item["script"]).name: item for item in docs}
+        self.assertIn("exponents.py", by_script)
+        fn_names = {f["name"] for f in by_script["exponents.py"]["functions"]}
+        self.assertIn("compute_sqrt", fn_names)
+        self.assertIn("compute_different_power", fn_names)
+
+    def test_docs_markdown_renders(self) -> None:
+        # Just ensure it runs and produces markdown-like output.
+        cmd = ["uv", "run", "supypowers", str(EXAMPLES), "docs", "--format", "md"]
+        proc = subprocess.run(
+            cmd,
+            cwd=str(ROOT),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=os.environ.copy(),
+            text=True,
+        )
+        self.assertEqual(proc.returncode, 0, msg=f"stderr={proc.stderr}\nstdout={proc.stdout}")
+        self.assertIn("## Supypowers", proc.stdout)
+        self.assertIn("### `", proc.stdout)
+
+    def test_run_exponents_compute_sqrt(self) -> None:
+        out = _run_uv_superpowers(str(EXAMPLES), "run", "exponents:compute_sqrt", "{'x': 9}")
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["data"]["result"], 3.0)
+
+    def test_run_strings_reverse(self) -> None:
+        out = _run_uv_superpowers(str(EXAMPLES), "run", "strings:reverse_string", "{'s': 'abc'}")
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["data"]["result"], "cba")
+
+    def test_run_dates_add_days(self) -> None:
+        out = _run_uv_superpowers(
+            str(EXAMPLES),
+            "run",
+            "dates:add_days",
+            "{'d': '2025-01-01', 'days': 10}",
+        )
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["data"]["result"], "2025-01-11")
+
+    def test_run_non_pydantic_output_allowed(self) -> None:
+        out = _run_uv_superpowers(str(EXAMPLES), "run", "misc:echo", "{'message': 'hi'}")
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["data"], "hi")
+
+
+if __name__ == "__main__":
+    unittest.main()
+

supypowers-0.1.0/uv.lock

@@ -0,0 +1,7 @@
+version = 1
+requires-python = ">=3.10"
+
+[[package]]
+name = "supypowers"
+version = "0.1.0"
+source = { editable = "." }