Metadata-Version: 2.4
Name: tigerflow-ml
Version: 0.1.0
Summary: ML task library for TigerFlow
Project-URL: Repository, https://github.com/princeton-ddss/tigerflow-ml
Project-URL: Documentation, https://princeton-ddss.github.io/tigerflow-ml/latest
Author-email: Colin Swaney <colinswaney@princeton.edu>, Sangyoon Park <sp8538@princeton.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: <3.14,>=3.10
Requires-Dist: accelerate>=1.13.0
Requires-Dist: langdetect>=1.0.9
Requires-Dist: opencv-python-headless
Requires-Dist: pillow
Requires-Dist: protobuf
Requires-Dist: pydantic>=2.0
Requires-Dist: pymupdf>=1.27.1
Requires-Dist: sentencepiece
Requires-Dist: soundfile>=0.12
Requires-Dist: soxr>=0.3
Requires-Dist: tigerflow<0.4,>=0.3.1
Requires-Dist: timm
Requires-Dist: torch<3,>=2.0
Requires-Dist: transformers<6,>=4.51
Provides-Extra: vllm
Requires-Dist: vllm<0.22,>=0.19.1; extra == 'vllm'
Description-Content-Type: text/markdown

# tigerflow-ml

[![CI](https://github.com/princeton-ddss/tigerflow-ml/actions/workflows/ci.yml/badge.svg)](https://github.com/princeton-ddss/tigerflow-ml/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/tigerflow-ml)](https://pypi.org/project/tigerflow-ml/)
[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://princeton-ddss.github.io/tigerflow-ml/)

ML tasks for [TigerFlow](https://github.com/princeton-ddss/tigerflow) — private cloud ML APIs on HPC infrastructure.

## Installation

```bash
pip install tigerflow-ml
```

If using a task that relies on `vllm` (chat, OCR, or translation), install with:

```bash
pip install tigerflow-ml[vllm]
```


## Tasks

| Task             | Description                           | Entry Point                       |
|------------------|---------------------------------------|-----------------------------------|
| OCR              | Extract text from images and PDFs     | `ocr` / `ocr-local`               |
| Translation      | Translate text documents              | `translate` / `translate-local`   |
| Chat             | Apply a chat prompt to images or text | `chat` / `chat-local`             |
| Transcription    | Transcribe audio to text              | `transcribe` / `transcribe-local` |
| Object Detection | Detect objects in images and videos   | `detect` / `detect-local`         |

Each task provides both a Slurm variant (for HPC) and a Local variant (for development).

## Usage

After installation, tasks are automatically discoverable via:

```bash
tigerflow tasks list
```

Run a task directly:

```bash
python -m tigerflow_ml.text.ocr.slurm --help
python -m tigerflow_ml.text.translate.slurm --help
python -m tigerflow_ml.text.chat.slurm --help
python -m tigerflow_ml.audio.transcribe.slurm --help
python -m tigerflow_ml.image.detect.slurm --help
```

## Container

A GPU image with all tasks (including the `vllm` extra) is published to GHCR on
each release:

```bash
docker pull ghcr.io/princeton-ddss/tigerflow-ml:latest
```

The image bundles its own CUDA libraries, so only the host NVIDIA driver is
needed at runtime — pass `--gpus all` (Docker) or `--nv` (Apptainer). Models are
fetched on first use; mount a cache at `/cache` to persist them.

The entrypoint is `tigerflow`, so arguments are passed straight to the CLI:

```bash
# Run a pipeline (config file + input/output directories)
docker run --gpus all -v "$PWD/cache:/cache" -v "$PWD:/data" \
  ghcr.io/princeton-ddss/tigerflow-ml:latest \
  run /data/pipeline.yaml /data/input /data/output

# List available tasks
docker run ghcr.io/princeton-ddss/tigerflow-ml:latest tasks list

# Run a single task module directly (override the entrypoint)
docker run --gpus all -v "$PWD/cache:/cache" -v "$PWD:/data" \
  --entrypoint python ghcr.io/princeton-ddss/tigerflow-ml:latest \
  -m tigerflow_ml.audio.transcribe.local --help
```

On HPC, convert to a Singularity/Apptainer image:

```bash
apptainer build tigerflow-ml.sif docker://ghcr.io/princeton-ddss/tigerflow-ml:latest
apptainer run --nv -B ./cache:/cache tigerflow-ml.sif run pipeline.yaml input output
apptainer exec --nv tigerflow-ml.sif python -m tigerflow_ml.audio.transcribe.local --help
```

## Development

```bash
uv sync --group dev
uv run pre-commit run --all-files
uv run pytest tests
```
