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, ...)

Contents

• Install
• Quick start (5 minutes, no GPU)
• Features
• Exporting for training tools
• Local models and privacy
• saara-gemma (planned, not trained yet)
• 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

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

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

Download sizes are the Ollama gemma4 images (weights plus vision and audio encoders).

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 (planned, not trained yet)

No saara-gemma model has been trained or released. Saara uses base Gemma 4 models today.

experiments/saara-gemma/ contains the pipeline we will use 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, hermes-function-calling, When2Call, Tulu-3.

What exists today:

• data preparation with group-aware, leak-free splits and a contamination guard
• LoRA training with assistant-only loss and LoRA targets read from the loaded model
• evaluation against base Gemma with paired bootstrap tests, plus an auto-generated model card and release gate

How it was tested: end to end (data formatting, loss masking, 2 training steps, saving and merging) on a tiny random-weight model with Gemma 4's architecture (make_tiny_gemma4.py), not on the real 8B model.

What does not exist yet: a full training run on real hardware, measured results, or released weights. See docs/saara-gemma.md.

Documentation

• Installation · User guide · CLI reference
• Export engine · Model runtime guide · saara-gemma training plan
• 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.