pybolo 0.1.0__py3-none-any.whl

bolo/__init__.py

@@ -0,0 +1,13 @@
+"""BoloPipe: a lightweight registry for verified HuggingFace inference pipelines."""
+
+from ._version import __version__
+from .api import list_params, create_a_venv, pipeline, remove_venv, fetch_templates
+
+__all__ = [
+    "__version__",
+    "list_params",
+    "create_a_venv",
+    "pipeline",
+    "remove_venv",
+    "fetch_templates",
+]

bolo/_version.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+__templates_version__ = "0.1.0" 

bolo/api.py

@@ -0,0 +1,317 @@
+import os
+import re
+import ast
+import json
+import shutil
+import subprocess
+import tarfile
+import urllib.request
+from pathlib import Path
+from jinja2 import Environment, StrictUndefined
+
+from ._version import __version__, __templates_version__
+
+_TEMPLATES_RELEASE_URL = (
+    "https://github.com/illinoisdata/bolo-templates/releases/download/"
+    "v{version}/templates.tar.gz"
+)
+
+
+class InferClient:
+    _instance = None
+    _torch_cu128_url = "https://download.pytorch.org/whl/cu128"
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        if getattr(self, "_initialized", False):
+            return
+
+        self.db_dir = self._ensure_templates()
+        self.supported_models = set()
+
+        for rid_dir in self.db_dir.iterdir():
+            if rid_dir.is_dir():
+                repo_name = rid_dir.name
+                repo_id = "/".join(repo_name.split('__SEP__'))
+                self.supported_models.add(repo_id)
+
+        self._initialized = True
+
+    @staticmethod
+    def _ensure_templates() -> Path:
+        env_path = os.environ.get("BOLO_TEMPLATES_DIR")
+        if env_path:
+            return Path(env_path).expanduser()
+
+        local = Path(__file__).parent / "templates"
+        if local.exists() and any(local.iterdir()):
+            return local
+
+        cache_root = Path.home() / ".cache" / "bolo" / "templates"
+        cache = cache_root / __templates_version__
+        if cache.exists() and any(cache.iterdir()):
+            return cache
+
+        url = _TEMPLATES_RELEASE_URL.format(version=__templates_version__)
+        print(f"fetching bolo templates v{__templates_version__} from {url} ...", flush=True)
+
+        cache_root.mkdir(parents=True, exist_ok=True)
+        tmp = cache_root / f".tmp.{__templates_version__}"
+        if tmp.exists():
+            shutil.rmtree(tmp)
+        tmp.mkdir()
+
+        try:
+            with urllib.request.urlopen(url) as resp, tarfile.open(fileobj=resp, mode="r|gz") as tar:
+                tar.extractall(tmp)
+            tmp.rename(cache)
+        except Exception:
+            shutil.rmtree(tmp, ignore_errors=True)
+            raise
+
+        return cache
+
+    @staticmethod
+    def _bolo_install_args() -> list[str]:
+        """Args to pass to `uv pip install` when seeding bolo into a model venv."""
+        project_root = Path(__file__).resolve().parent.parent.parent
+        if (project_root / "pyproject.toml").exists():
+            return ["-e", str(project_root)]
+        return ["bolo"]
+            
+    def query_a_repo(self, repo_id: str):
+        if repo_id not in self.supported_models:
+            print(f"bolo does not support {repo_id}")
+            return False
+        
+        return True
+    
+    def create_venv(self, repo_id: str, venv_path: str | Path | None = None):
+        repo_name = "__SEP__".join(repo_id.split('/'))
+        
+        if not venv_path:
+            venv_path = self.db_dir / "tmp_venv" / repo_name
+            print(f"you do not specify the venv path for {repo_id}, we create by default at {venv_path}")
+        
+        if venv_path.exists():
+            print(f"ven for {repo_id} has been already existed")
+            return venv_path / "bin" / "python", True
+        
+        os.makedirs(venv_path, exist_ok=True)
+        
+        req_txt = self.db_dir / repo_name / "requirements.txt"
+        
+        cmd1 = ['uv', 'venv', str(venv_path), '--python', '3.13']
+        try:
+            subprocess.run(cmd1, check=True, text=True, capture_output=True)
+        except Exception as e:
+            print(f"failed to create uv venv for {repo_id}, due to the following error : ")
+            print(e.stderr)
+            return "", False
+        
+        python_bin = venv_path / "bin" / "python"
+        cmd2 = ['uv', 'pip', 'install', '-r', str(req_txt), '--python', str(python_bin), '--extra-index-url', self._torch_cu128_url]
+        try:
+            subprocess.run(cmd2, check=True, text=True, capture_output=True)
+        except subprocess.CalledProcessError as e:
+            print(f"failed to install requirements.txt for {repo_id}, due to the following error : ")
+            print(e.stderr)
+            return "", False
+
+        cmd3 = ['uv', 'pip', 'install', *self._bolo_install_args(), '--python', str(python_bin)]
+        try:
+            subprocess.run(cmd3, check=True, text=True, capture_output=True)
+        except subprocess.CalledProcessError as e:
+            print(f"failed to install bolo into the venv for {repo_id}, due to the following error : ")
+            print(e.stderr)
+            return "", False
+
+        print(f"installed requirements.txt and bolo in a venv : {python_bin}!")
+        return python_bin, True
+    
+    def remove_venv(self, repo_id: str, venv_path: str | Path | None = None):
+        repo_name = "__SEP__".join(repo_id.split('/'))
+        if not venv_path:
+            venv_path = self.db_dir / "tmp_venv" / repo_name
+        shutil.rmtree(venv_path, ignore_errors=True)
+            
+    def render_template(self, repo_id: str, params: dict):
+        rid_name = "__SEP__".join(repo_id.split('/'))
+        template_path = self.db_dir / rid_name / "template.j2"
+        
+        params["repo_id"] = repo_id
+        
+        with open(template_path, 'r', encoding="utf-8") as f:
+            template = f.read().strip()
+            
+        try:
+            rendered_script = Environment(undefined=StrictUndefined).from_string(template).render(**params)
+        except Exception as e:
+            print(f"failed to render template for {repo_id}m due to the following error : ")
+            print(e)
+            return "", False
+        
+        return rendered_script, True
+    
+    def list_params(self, repo_id: str):
+        rid_name = "__SEP__".join(repo_id.split('/'))
+        template_path = self.db_dir / rid_name / "template.j2"
+        
+        with open(template_path, 'r', encoding="utf-8") as f:
+            template = f.read().strip()
+        
+        set_pattern = re.compile(r'^\s*\{\%\s*set\s+([a-zA-Z_]\w*)\s*=\s*(.*?)\s*\%\}\s*$')
+        lines = template.splitlines()
+        params = []
+        started = False
+        
+        for line in lines:
+            matched = set_pattern.match(line)
+            if matched:
+                started = True
+                name = matched.group(1)
+                raw_default = matched.group(2).strip()
+                
+                lowered = raw_default.lower()
+                if lowered == "true":
+                    default = True
+                elif lowered == "false":
+                    default = False
+                elif lowered in {"none", "null"}:
+                    default = None
+                else:
+                    try:
+                        default = ast.literal_eval(raw_default)
+                    except Exception:
+                        default = raw_default
+                
+                if name == "repo_id" or name == "output_dir":
+                    continue
+                
+                params.append(
+                    {
+                        "name": name,
+                        "default": default,
+                        "type": type(default).__name__,
+                        "raw_default": raw_default,
+                    }
+                )
+                continue
+            
+            if started:
+                break
+        
+        if not any(p["name"] == "device" for p in params):
+            params.insert(0, {
+                "name": "device",
+                "default": "<required>",
+                "type": "str",
+                "raw_default": "<required>",
+            })
+
+        result = {
+            "num_params": len(params),
+            "params": params,
+        }
+
+        def _to_display(v):
+            if isinstance(v, (dict, list)):
+                return json.dumps(v, ensure_ascii=False)
+            return str(v)
+
+        headers = ["name", "type", "default", "raw_default"]
+        rows = [
+            [p["name"], p["type"], p["default"], p["raw_default"]]
+            for p in params
+        ]
+        widths = [len(h) for h in headers]
+        for row in rows:
+            for i, cell in enumerate(row):
+                widths[i] = max(widths[i], len(_to_display(cell)))
+
+        print(f"repo_id: {_to_display(repo_id)}")
+        print(f"num_params: {_to_display(len(params))}")
+        if not rows:
+            print("(no top-level Jinja set variables found)")
+            return result
+        
+        sep = " | "
+        header_line = sep.join(headers[i].ljust(widths[i]) for i in range(len(headers)))
+        divider = "-+-".join("-" * widths[i] for i in range(len(headers)))
+        print(header_line)
+        print(divider)
+        for row in rows:
+            print(sep.join(_to_display(row[i]).ljust(widths[i]) for i in range(len(headers))))
+        
+        return result
+    
+    def run_inference(self, code: str):
+        try:
+            ns = {"__name__": "__api__"}
+            exec(code, ns, ns)
+            if "RESULT" not in ns:
+                raise RuntimeError("RESULT not defined")
+            return ns["RESULT"]
+        except Exception:
+            raise
+        
+        
+def list_params(repo_id: str):
+    client = InferClient()
+    
+    is_exist = client.query_a_repo(repo_id)
+    if not is_exist:
+        raise ValueError(f"bolo does not support {repo_id}")
+    
+    _ = client.list_params(repo_id)
+        
+        
+def create_a_venv(repo_id: str, venv_path: str | Path | None = None):
+    client = InferClient()
+    
+    is_exist = client.query_a_repo(repo_id)
+    if not is_exist:
+        raise ValueError(f"bolo does not support {repo_id}")
+    
+    if venv_path is not None and os.path.exists(venv_path):
+        print(f"already created venv at : {venv_path}")
+        return venv_path
+    
+    venv_path, staus = client.create_venv(repo_id, venv_path)
+    
+    if not staus:
+        raise RuntimeError(f"failed to create venv for {repo_id}")
+    
+    return venv_path
+    
+    
+def pipeline(repo_id: str, **kwargs):
+    client = InferClient()
+    
+    is_exist = client.query_a_repo(repo_id)
+    if not is_exist:
+        raise ValueError(f"bolo does not support {repo_id}")
+    
+    _ = client.list_params(repo_id)
+    
+    code, is_success = client.render_template(repo_id, kwargs)
+    if not is_success:
+        raise RuntimeError(f"failed to render template for {repo_id}")
+
+    return client.run_inference(code)
+    
+    
+def remove_venv(repo_id: str):
+    client = InferClient()
+    client.remove_venv(repo_id)
+
+
+def fetch_templates() -> Path:
+    """Pre-populate the bolo templates cache (downloads from the GitHub release if needed)."""
+    path = InferClient._ensure_templates()
+    print(f"templates available at : {path}")
+    return path

bolo/cli.py

@@ -0,0 +1,78 @@
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .api import InferClient, create_a_venv, pipeline, remove_venv, fetch_templates
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bolopipe", description="Inspect BoloPipe registry records")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    create_venv_parser = sub.add_parser("create-venv", help="Create a venv for a model")
+    create_venv_parser.add_argument("repo_id", help="HuggingFace repository id")
+    create_venv_parser.add_argument("--venv-path", default=None, help="Path to create the venv")
+
+    run_parser = sub.add_parser("run", help="Run inference for a model")
+    run_parser.add_argument("repo_id", help="HuggingFace repository id")
+    run_parser.add_argument("params", nargs="*", metavar="KEY=VALUE", help="Template parameters")
+
+    remove_venv_parser = sub.add_parser("remove-venv", help="Remove the venv for a model")
+    remove_venv_parser.add_argument("repo_id", help="HuggingFace repository id")
+
+    sub.add_parser("fetch-templates", help="Download the bolo templates cache for this version")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "create-venv":
+        create_a_venv(args.repo_id, args.venv_path)
+        return 0
+
+    if args.command == "run":
+        client = InferClient()
+        repo_name = "__SEP__".join(args.repo_id.split("/"))
+        venv_dir = client.db_dir / "tmp_venv" / repo_name
+        venv_python = venv_dir / "bin" / "python"
+        venv_bolo = venv_dir / "bin" / "bolo"
+
+        if not venv_python.exists():
+            parser.error(
+                f"no venv found at {venv_dir}; "
+                f"run `bolo create-venv {args.repo_id}` first"
+            )
+
+        if Path(sys.executable).resolve() != venv_python.resolve():
+            return subprocess.call([str(venv_bolo), "run", args.repo_id, *args.params])
+
+        kwargs = {}
+        for item in args.params:
+            if "=" not in item:
+                parser.error(f"invalid parameter {item!r}, expected KEY=VALUE")
+            k, _, v = item.partition("=")
+            kwargs[k] = v
+        result = pipeline(args.repo_id, **kwargs)
+        if result is not None:
+            print(result)
+        return 0
+
+    if args.command == "remove-venv":
+        remove_venv(args.repo_id)
+        return 0
+
+    if args.command == "fetch-templates":
+        fetch_templates()
+        return 0
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

pybolo-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pybolo
+Version: 0.1.0
+Summary: A lightweight library of verified inference pipelines for HuggingFace models.
+Author: Illinois CreateLab
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/illinoisdata/Bolo
+Project-URL: Repository, https://github.com/illinoisdata/Bolo
+Project-URL: Issues, https://github.com/illinoisdata/Bolo/issues
+Keywords: huggingface,inference,pipeline,verified,curated,model-registry,llm-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.0
+Provides-Extra: hf
+Requires-Dist: transformers>=4.40; extra == "hf"
+Requires-Dist: torch>=2.0; extra == "hf"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+    <a href="https://github.com/illinoisdata/bolo/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/illinoisdata/bolo.svg?color=blue"></a>
+    <a href="https://github.com/illinoisdata/bolo-templates/releases"><img alt="bolo-templates release" src="https://img.shields.io/github/v/release/illinoisdata/bolo-templates?include_prereleases&label=templates"></a>
+    <a href="https://pypi.org/project/pybolo"><img alt="PyPI" src="https://img.shields.io/pypi/v/pybolo.svg"></a>
+</p>
+
+<p align="center">
+  <img src="assets/logo.png" alt="bolo logo" width="180">
+</p>
+
+<h1 align="center">Bolo: Curated, Verified, and Ready-to-run Inference Pipelines for HuggingFace Models</h1>
+
+**Bolo** is a lightweight Python library that gives you curated, verified, and ready-to-run inference pipelines for HuggingFace models with ZERO efforts.
+
+📦 **Curated templates**: every supported model ships with a tested Jinja2 inference template maintained by the Illinois CreateLab team.
+
+🔒 **Isolated venvs**: each model runs inside its own `uv`-managed virtual environment, so dependency conflicts between models are impossible.
+
+⚡ **One-call API**: `bolo.pipeline(repo_id, device="cuda", ...)` conducts inference in one API call, simpler than HuggingFace two-stages `pipeline` API.
+
+🖥️ **CLI included**: a `bolo` command lets you manage venvs and run inference directly from the shell.
+
+🌐 **Auto-fetching templates**: template bundles are downloaded on first use from the [bolo-templates](https://github.com/illinoisdata/bolo-templates) GitHub release and cached locally — no manual setup needed.
+
+## Quick demo
+
+Install bolo:
+
+```bash
+pip install pybolo
+```
+
+Run inference with two lines of Python:
+
+```python
+import bolo
+
+result = bolo.pipeline("<REPO_ID>", device="cuda:0")
+print(result)
+```
+
+Before running inference you can inspect what parameters the template accepts:
+
+```python
+bolo.list_params("<REPO_ID>")
+```
+
+And manage venvs explicitly:
+
+```python
+python_bin = bolo.create_a_venv("<REPO_ID>")
+# ... activate the created venv and do inference ...
+bolo.remove_venv("<REPO_ID>")
+```
+
+## CLI
+
+The `bolo` command mirrors the Python API from your shell.
+
+**Create an isolated venv for a model:**
+```bash
+bolo create-venv <REPO_ID>
+bolo create-venv <REPO_ID> --venv-path /path/to/venv
+# then activate the venv
+```
+
+**Run inference:**
+```bash
+bolo run <REPO_ID> device=cuda:0
+```
+
+**Pre-download the templates cache (optional, useful on air-gapped machines):**
+```bash
+bolo fetch-templates
+```
+
+## How does bolo work?
+
+bolo separates *what to run* (the Jinja2 template) from *where to run it* (the model's isolated venv).
+
+```mermaid
+flowchart LR
+    A[User calls bolo.pipeline] --> B[Fetch / load templates]
+    B --> C[Render Jinja2 template\nwith user params]
+    C --> D[Execute rendered script\ninside model venv]
+    D --> E[Return RESULT]
+```
+
+1. **Templates** — stored in the [bolo-templates](https://github.com/illinoisdata/bolo-templates) release bundle. Each model folder contains a `template.j2` (the inference script template) and a `requirements.txt` (the model's exact dependencies). Templates are downloaded once and cached at `~/.cache/bolo/templates/`.
+
+2. **Venvs** — created with `uv venv` + `uv pip install -r requirements.txt`. Every model gets its own venv so you can safely use models with conflicting PyTorch or CUDA versions side-by-side.
+
+3. **Rendering** — template parameters are collected from the leading `{% set key = default %}` blocks in each `template.j2`. `bolo list_params` shows you every knob with its type and default value.
+
+4. **Execution** — the rendered script is executed and its `RESULT` variable is returned to the caller.
+
+## Install from source
+
+```bash
+git clone https://github.com/illinoisdata/Bolo.git
+cd Bolo
+pip install -e .
+```
+
+## Custom templates directory
+
+Set `BOLO_TEMPLATES_DIR` to point bolo at your own templates folder:
+
+```bash
+export BOLO_TEMPLATES_DIR=/path/to/my/templates
+```
+
+## Platforms
+`bolo` is developed and tested on Red Hat Enterprise Linux, with CUDA version 12.8. So all dependencies (`torch`-related) assume the `cu128`.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/illinoisdata/bolo/issues).
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+## Acknowledgement
+- Thanks Jojo and her sister for designing the mascot.

pybolo-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bolo/__init__.py,sha256=aPfnAYYRXnYiV-yf9cAPmHDz3yxH10jzlVm9ppZ8F3w,336
+bolo/_version.py,sha256=VDUvW59hnYcAuAz1kbw-UXv87xOenI0dQSaQL-6fRg0,54
+bolo/api.py,sha256=mVOHlSaydeb3YjdbVlKVqPjtLmvx9ZbpA9O5-9dqay0,10826
+bolo/cli.py,sha256=ZQXpOSR4vgHv8g9bGdbNJFYAiftnyk5fJ76kUiyEWg0,2728
+bolo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pybolo-0.1.0.dist-info/licenses/LICENSE,sha256=BI8sbF3C8lnlNsDNTMxeW1lMtEZwBfyiGMVIUJj44ho,1075
+pybolo-0.1.0.dist-info/METADATA,sha256=uSfqTKc6zUc6ZDYHE4m1RhNgJREJW-TE4QujE4W3PSI,5658
+pybolo-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pybolo-0.1.0.dist-info/entry_points.txt,sha256=MMy8Nkni80Qkc9B3gfxKsdAoIbLLQjb2y8swdh6JSzE,39
+pybolo-0.1.0.dist-info/top_level.txt,sha256=XJPzoQx5ssYSgfFMdT-AEW5NgpSX-S_oQFv0kRv7Rwc,5
+pybolo-0.1.0.dist-info/RECORD,,

pybolo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pybolo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bolo = bolo.cli:main

pybolo-0.1.0.dist-info/licenses/LICENSE

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

pybolo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bolo