Metadata-Version: 2.4
Name: saara-ai
Version: 0.1.4
Summary: End-to-end ML pipeline: PDF→JSON datasets, synthetic data, fine-tuning, evaluation, and edge deployment with Gradio GUI
Author-email: Kilani Sai Nikhil <nikhil49023@gmail.com>
Maintainer-email: Kilani Sai Nikhil <nikhil49023@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/nikhil49023/saara-ai
Project-URL: Repository, https://github.com/nikhil49023/saara-ai
Project-URL: Documentation, https://saara-ai.readthedocs.io
Keywords: saara,ml,llm,fine-tuning,synthetic-data,pdf,vllm,gradio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ollama>=0.1.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: pdfplumber>=0.10.0
Requires-Dist: pynvml>=11.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: gradio>=4.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: providers
Requires-Dist: vllm>=0.2.0; extra == "providers"
Requires-Dist: llama-cpp-python>=0.2.0; extra == "providers"
Provides-Extra: training
Requires-Dist: torch>=2.1.0; extra == "training"
Requires-Dist: transformers>=4.36.0; extra == "training"
Requires-Dist: accelerate>=0.25.0; extra == "training"
Requires-Dist: datasets>=2.14.0; extra == "training"
Requires-Dist: unsloth>=2024.1; extra == "training"
Requires-Dist: trl>=0.7.0; extra == "training"
Requires-Dist: peft>=0.7.0; extra == "training"
Requires-Dist: bitsandbytes>=0.41.0; extra == "training"
Provides-Extra: evaluation
Requires-Dist: torch>=2.1.0; extra == "evaluation"
Requires-Dist: lm-eval>=0.4.0; extra == "evaluation"
Requires-Dist: lighteval>=0.4.0; extra == "evaluation"
Requires-Dist: codecarbon>=2.0.0; extra == "evaluation"
Provides-Extra: export
Requires-Dist: torch>=2.1.0; extra == "export"
Requires-Dist: autoawq>=0.2.0; extra == "export"
Requires-Dist: auto-gptq>=0.5.0; extra == "export"
Requires-Dist: onnx>=1.15.0; extra == "export"
Requires-Dist: gguf>=0.1.0; extra == "export"
Provides-Extra: edge
Requires-Dist: torch>=2.1.0; extra == "edge"
Requires-Dist: onnx>=1.15.0; extra == "edge"
Requires-Dist: tensorrt>=8.6.0; extra == "edge"
Requires-Dist: onnxruntime-gpu>=1.16.0; extra == "edge"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-book-theme>=1.0.0; extra == "docs"
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: vllm>=0.2.0; extra == "all"
Requires-Dist: llama-cpp-python>=0.2.0; extra == "all"
Requires-Dist: torch>=2.1.0; extra == "all"
Requires-Dist: transformers>=4.36.0; extra == "all"
Requires-Dist: accelerate>=0.25.0; extra == "all"
Requires-Dist: datasets>=2.14.0; extra == "all"
Requires-Dist: unsloth>=2024.1; extra == "all"
Requires-Dist: trl>=0.7.0; extra == "all"
Requires-Dist: peft>=0.7.0; extra == "all"
Requires-Dist: bitsandbytes>=0.41.0; extra == "all"
Requires-Dist: lm-eval>=0.4.0; extra == "all"
Requires-Dist: lighteval>=0.4.0; extra == "all"
Requires-Dist: codecarbon>=2.0.0; extra == "all"
Requires-Dist: autoawq>=0.2.0; extra == "all"
Requires-Dist: auto-gptq>=0.5.0; extra == "all"
Requires-Dist: onnx>=1.15.0; extra == "all"
Requires-Dist: gguf>=0.1.0; extra == "all"
Requires-Dist: tensorrt>=8.6.0; extra == "all"
Requires-Dist: onnxruntime-gpu>=1.16.0; extra == "all"
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-cov>=4.0.0; extra == "all"
Requires-Dist: black>=23.0.0; extra == "all"
Requires-Dist: ruff>=0.1.0; extra == "all"
Requires-Dist: mypy>=1.0.0; extra == "all"
Requires-Dist: sphinx>=7.0.0; extra == "all"
Requires-Dist: sphinx-book-theme>=1.0.0; extra == "all"
Requires-Dist: mkdocs>=1.5.0; extra == "all"
Requires-Dist: mkdocs-material>=9.0.0; extra == "all"
Dynamic: license-file

# SAARA

SAARA is a Python package for building local LLM workflows around data creation, fine-tuning, evaluation, export, and visualization.

It is aimed at a practical teacher-student workflow:

1. extract text from PDFs or raw text
2. generate synthetic supervision with a stronger local model
3. fine-tune a smaller model
4. evaluate quality, speed, memory, and optional teacher agreement
5. export and quantize for deployment
6. inspect the workflow through CLI or Gradio

## Features

- PDF to text extraction with `PyMuPDF` and `pdfplumber`
- synthetic dataset generation for factual, reasoning, conversational, instruction, code, and creative tasks
- local provider abstraction for `Ollama`, `vLLM`, and `llama.cpp`
- fine-tuning helpers for LoRA and QLoRA workflows
- evaluation helpers for custom datasets, benchmarks, and teacher-student comparison
- export helpers for `safetensors`, `GGUF`, `AWQ`, `GPTQ`, `ONNX`, `TensorRT`, and PyTorch formats
- Gradio dashboard and CLI entrypoints

## Install

From PyPI:

```bash
pip install saara-ai
```

Common installs:

```bash
pip install "saara-ai[training]"
pip install "saara-ai[export]"
pip install "saara-ai[providers,training,evaluation,export]"
```

From source:

```bash
git clone https://github.com/nikhil49023/saara-ai.git
cd saara-ai
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Optional extras:

```bash
pip install -e ".[dev]"
pip install -e ".[edge]"
pip install -e ".[providers,training,evaluation,export]"
```

Base `saara-ai` intentionally keeps the install lighter. Heavy native stacks such as `auto-gptq`, `autoawq`, `llama-cpp-python`, `vllm`, and training toolchains are opt-in extras.

Note: a virtual environment is strongly recommended.

## Quick Start

### 1. Start a local model provider

For Ollama:

```bash
ollama pull mistral
ollama serve
```

### 2. Build a dataset from a PDF

```python
from saara import DatasetBuilder
from saara.dataset.types import DataType
from saara.providers.ollama_provider import OllamaProvider, ProviderConfig

provider = OllamaProvider(
    ProviderConfig(model="mistral", base_url="http://localhost:11434")
)

builder = DatasetBuilder(provider)
samples = builder.from_pdf(
    "document.pdf",
    data_types=[DataType.INSTRUCTION, DataType.FACTUAL],
    pairs_per_type=5,
    min_quality=0.65,
)

builder.save(samples, "dataset.jsonl")
```

### 3. Launch the GUI

```bash
saara gui
```

## Core Workflow

### Dataset creation

```python
from saara import DatasetBuilder
from saara.dataset.types import DataType

builder = DatasetBuilder(provider)
samples = builder.from_text(
    "Transformers use attention mechanisms for sequence modeling.",
    data_types=[DataType.FACTUAL, DataType.INSTRUCTION],
    pairs_per_type=3,
)
```

### Fine-tuning

```python
from saara import FineTuner
from saara.training.config import TrainingConfig

config = TrainingConfig(
    model_name="mistralai/Mistral-7B-v0.1",
    num_train_epochs=3,
    use_lora=True,
)

finetuner = FineTuner(config)
finetuner.train("dataset.jsonl")
finetuner.save("./output/models/my-finetune")
```

### Evaluation

```python
from saara import ModelEvaluator
from saara.providers.ollama_provider import OllamaProvider, ProviderConfig

student = OllamaProvider(ProviderConfig(model="mistral-7b-finetuned"))
teacher = OllamaProvider(ProviderConfig(model="llama-3-70b"))

evaluator = ModelEvaluator(student, teacher)
metrics = evaluator.evaluate(
    "test.jsonl",
    run_benchmarks=True,
    benchmark_names=["mmlu", "gsm8k"],
)

print(metrics.summary())
```

### Export and quantization

```python
from saara import ModelExporter
from saara.export.formats import ExportFormat
from saara.export.quantization import QuantizationConfig

exporter = ModelExporter(
    model="./output/models/my-finetune",
    config=QuantizationConfig(bits=4),
)

results = exporter.export(
    "./output/exports",
    formats=[ExportFormat.GGUF, ExportFormat.AWQ, ExportFormat.ONNX],
    quantize=True,
)
```

## CLI

```bash
saara dataset from-pdf document.pdf -o ./output --data-types instruction factual
saara train finetune dataset.jsonl --model mistralai/Mistral-7B-v0.1 --epochs 3
saara eval model test.jsonl --model mistral --teacher llama-3-70b --benchmarks mmlu gsm8k
saara export model ./models/final --formats gguf awq --quantize --bits 4
saara gui --port 7860
```

## Documentation

- User guide: [USER_GUIDE.md](USER_GUIDE.md)
- Package structure: [PACKAGE_STRUCTURE.md](PACKAGE_STRUCTURE.md)
- Examples: [`examples/`](examples)

## Examples

- `examples/01_pdf_to_dataset.py`
- `examples/02_synthetic_data.py`
- `examples/03_finetune.py`
- `examples/04_evaluate.py`
- `examples/05_export.py`
- `examples/06_complete_pipeline.py`
- `examples/07_gui.py`
- `examples/08_saara_demo_notebook.ipynb`
- `examples/09_edge_ai_solutions_gemma_vllm.ipynb`

## Recommended Starting Point

If you're trying SAARA for the first time, start with:

- `OllamaProvider`
- one small PDF or a short text file
- LoRA or QLoRA fine-tuning
- `GGUF` and `safetensors` export first

## Development

```bash
pytest tests/
black saara/
ruff check saara/
mypy saara/
```

## PyPI

`https://pypi.org/project/saara-ai/`

## License

MIT. See [LICENSE](LICENSE).
