README.md

---
title: README
emoji: 📚
colorFrom: red
colorTo: indigo
sdk: static
pinned: false
---

# UV Scripts

**Ready-to-run ML tools powered by UV - zero setup, maximum power**

Run state-of-the-art ML workflows with a single command. From OCR to classification, all scripts work instantly with `uv run`.

## What are UV scripts?

UV scripts are self-contained Python scripts that use [inline metadata](https://docs.astral.sh/uv/guides/scripts/) to specify dependencies. Just `uv run script.py` and everything installs automatically.

Perfect for:
- 🚀 **GPU workflows** on [HF Jobs](https://huggingface.co/docs/hub/spaces-gpu-jobs)
- 💻 **Local processing** on your machine  
- 🔄 **Reproducible pipelines** that work anywhere

## 🚀 Quick Example

```bash
# Extract text from images with state-of-the-art OCR
uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/nanonets-ocr.py \
  your-image-dataset \
  your-extracted-text

# Or run on GPU with HF Jobs (no local GPU needed!)
hf jobs uv run --flavor l4x1 \
  https://huggingface.co/datasets/uv-scripts/ocr/raw/main/nanonets-ocr.py \
  your-images your-text
```

## 📚 Browse Scripts

| Script Collection | Description | GPU Required |
|-------------------|-------------|--------------|
| [ocr](https://huggingface.co/datasets/uv-scripts/ocr) | Extract text from images with VLMs (LaTeX, tables, forms) | ✅ |
| [classification](https://huggingface.co/datasets/uv-scripts/classification) | Text classification with guaranteed valid outputs | ✅ |
| [dataset-creation](https://huggingface.co/datasets/uv-scripts/dataset-creation) | Create datasets from PDFs and files | ❌ |
| [vllm](https://huggingface.co/datasets/uv-scripts/vllm) | High-performance inference with vLLM | ✅ |

## 🎯 Why UV Scripts?

### Zero Setup
No virtual environments, no dependency conflicts, no installation steps. UV handles everything automatically when you run the script.

### Production Ready
These aren't demos - they're production-quality tools used by the community for real ML workflows.

### GPU Optimized
Seamlessly run on local GPUs or scale to cloud with HF Jobs. Same script, different compute.

### Community Driven
Browse scripts, contribute your own, and learn from the best practices of the ML community.

## 🌟 Featured Scripts

### OCR Any Document Dataset
Extract text from images with state-of-the-art accuracy:
```bash
# Handles LaTeX, tables, forms, handwriting
uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/nanonets-ocr.py \
  your-images extracted-text
```

### Classify with Guaranteed Valid Outputs  
Text classification that always returns valid labels:
```bash
# Uses vLLM's structured generation - no invalid outputs!
uv run https://huggingface.co/datasets/uv-scripts/classification/raw/main/classify-dataset.py \
  --input-dataset imdb --column text \
  --labels "positive,negative" --output-dataset imdb-classified
```

## 🚀 Getting Started

1. **Install UV** (one-time setup):
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. **Run any script**:
   ```bash
   uv run https://huggingface.co/datasets/uv-scripts/[collection]/raw/main/[script].py
   ```

3. **Or use HF Jobs** (no local GPU needed):
   ```bash
   hf jobs uv run --flavor l4x1 [script-url] [args]
   ```

## 🤝 Contributing

We welcome scripts that:
- Solve real ML problems
- Include clear documentation
- Follow UV best practices
- Work on both local and cloud

Submit your scripts as PRs to the relevant collection or propose a new collection!

## 📖 Learn More

- [UV Documentation](https://docs.astral.sh/uv/)
- [HF Jobs Guide](https://huggingface.co/docs/hub/spaces-gpu-jobs)
- [Script Examples](https://github.com/astral-sh/uv/tree/main/scripts)

---

*UV Scripts is a community project showcasing the power of [UV](https://github.com/astral-sh/uv) for ML workflows.*