Saara

Saara is a local-first CLI for building ML datasets you can trust. It turns topics, web research and PDFs into training data, labels, validates and distills it, and exports it in the formats today's fine-tuning tools expect, all on your own machine with local models such as Gemma 4.

 research / PDFs ──► ingest ──► generate ──► label ──► validate ──► distill ──► export
 (Firecrawl-local)  (Docling +   (local LLM)                      (SFT / DPO)  (OpenAI, ShareGPT,
                     Gemma OCR)                                                 Alpaca, Vertex, ...)

Install
Quick start (5 minutes, no GPU)
Features
Exporting for training tools
Local models and privacy
saara-gemma: Saara's own fine-tuned model
Documentation
Contributing (Hacktoberfest welcome)

Install

pip install saara-ai                 # core CLI
pip install 'saara-ai[all]'          # + Parquet/Arrow/HF export, PDF ingestion, rich UI

From source:

git clone https://github.com/nikhil49023/Saara.git && cd Saara
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[all,dev]'
saara --version

Quick start (5 minutes, no GPU)

Every command below runs offline with --provider mock, a deterministic development provider. Swap in --provider ollama --model gemma4 (or vllm / openai-compatible) for real generation.

saara doctor                                   # check what is installed
saara generate topic "solar energy" --samples 20 --provider mock --output-dir runs/solar
saara validate runs/solar/datasets/solar-energy.jsonl
saara label runs/solar/datasets/solar-energy.jsonl --labels useful,noise --provider mock --output-dir runs/solar
saara distill runs/solar/datasets/solar-energy.jsonl --method dpo --provider mock --output-dir runs/solar
saara export runs/solar/datasets/solar-energy.jsonl --to jsonl --schema openai-chat \
    --split train=0.9,val=0.05,test=0.05 --out exports/solar

Prefer a guided flow? Run saara wizard. Running saara with no arguments shows the splash screen and help.

Features

Stage	Command	What it does
Research	`generate topic --research firecrawl`	Bounded research agent over Firecrawl-local (`search`, `scrape`); retrieved text is treated as data, not instructions
Ingest	`ingest pdf`	Docling layout parsing; PyMuPDF text; Gemma 4 vision OCR fallback for scanned or handwritten pages
Generate	`generate topic`	`finetuning`, `pretraining`, `reasoning` and `tool-calling` dataset types; configurable prompts
Label	`label`	Constrained label sets with a local model
Validate	`validate`	Schema checks, duplicates, label distribution; machine-readable report
Distill	`distill --method sft\|dpo`	SFT conversations, or DPO pairs with real negatives (another example's answer, or a truncated answer)
Export	`export`	7 storage formats × 8 training schemas, deterministic splits, sharding, checksums (details)
Workflows	`run config.json`	Declarative, repeatable pipelines (example)
Models	`models hardware\|setup\|list\|remove`	Hardware-tiered local Gemma setup, downloads only with consent

Every run records provenance (sources, run IDs, hashes) so a dataset can be traced back to where it came from.

Exporting for training tools

saara export data.jsonl --to jsonl   --schema sharegpt     --out exports/llamafactory   # + dataset_info.json
saara export data.jsonl --to jsonl   --schema openai-chat  --split train=0.9,test=0.1 --group-by metadata.source --out exports/openai
saara export data.jsonl --to parquet --schema chatml       --shard-size 50000 --out exports/chatml
saara export pairs.jsonl --to jsonl  --schema dpo          --out exports/dpo
saara export data.jsonl --to jsonl   --schema vertex-gemini --compress gzip --out exports/vertex

Schema	Use it with
`openai-chat`	OpenAI fine-tuning, Together, Fireworks, Azure OpenAI, Unsloth, TRL `SFTTrainer`
`sharegpt`	LLaMA-Factory, Axolotl (tool calls as `function_call` / `observation` turns)
`alpaca`	Instruction tuners expecting `instruction` / `input` / `output` (+ `history`)
`chatml`	Raw-text SFT trainers (`text` field with `<\|im_start\|>` markers)
`vertex-gemini`	Vertex AI / Gemini supervised tuning (`contents`, `parts`, `functionCall`)
`dpo`	TRL `DPOTrainer` and other preference trainers (`prompt` / `chosen` / `rejected`)
`text`	Pretraining / continued pretraining
`saara`	Saara's native rows, unchanged

Storage formats: jsonl, json, csv, tsv, parquet, arrow, hf (Hugging Face save_to_disk).

Each engine export (--schema, --split, --shard-size or --compress) writes:

<split>/<name>-00000-of-0000N.<ext>: data shards
export_manifest.json: counts, dropped rows with reasons, sha256 per file, group-leakage check
README.md: a Hugging Face dataset card
dataset_info.json: LLaMA-Factory registration (sharegpt and alpaca)

Splits are deterministic (seeded hashing), and --group-by keeps related rows (same document, same source) in one split so evaluation data never leaks into training. Rows that a schema cannot represent (for example tool calls in alpaca) are dropped and counted, or fail with --strict. Without engine options, saara export --to FORMAT --out FILE still writes a single file as before.

Local models and privacy

Saara never bundles model weights and never downloads a model without asking.

saara models hardware                     # RAM / VRAM / disk and a recommended tier
saara models setup --dry-run              # show what would be pulled
saara models setup                        # asks for consent, then pulls via Ollama
saara models setup --model-path ./model.gguf --model my-gemma   # offline / air-gapped
saara models remove gemma-4-e4b

Tier	Model	Download	RAM
Edge / CPU	`gemma-4-e2b`	~1.6 GB	4 GB
Laptop	`gemma-4-e4b`	~2.9 GB	8 GB
Workstation / GPU	`gemma-4-12b`	~7.8 GB	16 GB

Providers: mock (offline, deterministic), ollama (http://localhost:11434), vllm and openai-compatible (default http://localhost:8000/v1), and gemini for hosted Gemma 4 through the Gemini API (pip install 'saara-ai[gemini]', set GEMINI_API_KEY; default model gemma-4-26b-a4b-it, supports page images for OCR). Use --yes for non-interactive setup in CI.

saara-gemma: Saara's own fine-tuned model

experiments/saara-gemma/ contains a production-style pipeline to fine-tune Gemma 4 E4B for Saara's core skills: document OCR (including historical and degraded scans), cleaning noisy text, and multi-step tool workflows. It uses public datasets only: olmOCR-mix, Post-OCR-Correction, fineweb-edu, Toucan-1.5M, When2Call, Tulu-3.

The pipeline covers group-aware leak-free splits, a contamination guard, assistant-only loss, LoRA targets chosen from the loaded architecture, early stopping on a task metric, paired-bootstrap evaluation against base Gemma, and an auto-generated model card. It becomes Saara's default model only if it beats base Gemma on every skill. Status: pipeline built and tested; the training run is scheduled. See docs/saara-gemma.md.

Documentation

Installation · User guide · CLI reference
Export engine · Model runtime guide · saara-gemma training
Architecture · Changelog

Contributing

Contributions are welcome, including during Hacktoberfest 2026. Start with CONTRIBUTING.md, then pick an issue labelled good first issue or hacktoberfest. Please follow the Code of Conduct.

pip install -e '.[all,dev]'
python -m pytest -q

License

MIT, see LICENSE. Gemma models are released by Google under Apache 2.0; datasets keep their own licenses.

Metadata

Release files for saara-ai 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for saara-ai 1.8.0
File	Size	Uploaded	Provenance
saara_ai-1.8.0.tar.gz	76.1 kB	Oct 25, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for saara-ai 1.8.0
File	Interpreter	ABI	Platform	Reset
saara_ai-1.8.0-py3-none-any.whl 63.7 kB Oct 25, 2026 Without provenance	Python 3	none	any	Details

Total release size: 139.8 kB

Release files / saara_ai-1.8.0.tar.gz

Download URL	saara_ai-1.8.0.tar.gz
Size	76.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`3861013466ce9e10d9d5227a21b4ee3431d38cc5b2facf69f59d6abd8aea73d8`
BLAKE2b-256 checksum How to use checksums	`2c750551700c976f257930ecfb1c53ad68145f1b32a92acb311503ddd58417e9`
Upload date	Oct 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / saara_ai-1.8.0-py3-none-any.whl

Download URL	saara_ai-1.8.0-py3-none-any.whl
Size	63.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c9b8c1f593b4062895d9a0a90ac5b75e80442724f63b4ab1482bd88bf680d651`
BLAKE2b-256 checksum How to use checksums	`d3654dc98e827504e59055142ee386f8a711d521305e0c7439932aabd3f6ff7a`
Upload date	Oct 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Security for saara-ai 1.8.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.