Metadata-Version: 2.5
Name: saral
Version: 0.1.1
Summary: Saral: a private, voice-first AI helper that runs at home. Explains papers, checks for scams, in your own language.
Project-URL: Homepage, https://github.com/Fullcountr/saral
Project-URL: Documentation, https://github.com/Fullcountr/saral/tree/main/docs
Project-URL: Issues, https://github.com/Fullcountr/saral/issues
Project-URL: Changelog, https://github.com/Fullcountr/saral/releases
Author: Harishwar Reddy Korpol
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: accessibility,local-ai,multilingual,ocr,offline,privacy,scam-detection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Natural Language :: Hindi
Classifier: Natural Language :: Spanish
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: pillow>=10.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.6
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: qrcode>=7.4
Requires-Dist: uvicorn>=0.29
Provides-Extra: all
Requires-Dist: faster-whisper>=1.0; extra == 'all'
Provides-Extra: build
Requires-Dist: pyinstaller>=6.6; extra == 'build'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: ocr
Provides-Extra: speech
Requires-Dist: faster-whisper>=1.0; extra == 'speech'
Description-Content-Type: text/markdown

# Saral

**A private AI helper that lives at home. Ask by voice, in your own language. Nothing leaves the house.**

*Saral* (सरल) means "simple." Saral is built for people who will never open a terminal: parents and grandparents, newcomers to a country, and small-business owners. It helps with the confusing moments that come up every week:

- **Is this a scam?** Forward or paste a suspicious SMS, WhatsApp message or email. Saral lists the warning signs in plain words and always tells you how to check safely.
- **What does this paper say?** Take a photo of a bill, notice or letter. Saral finds the amounts, dates and phone numbers exactly as written, and explains what it asks you to do.

Coming next: *help me reply*, *talk for me* (live translation) and *help me fill this form*. See the [roadmap](https://github.com/Fullcountr/saral/blob/main/docs/ROADMAP.md).

> **Status: v0.1 alpha.** The core loop works end to end. It is not yet ready for unsupervised use by vulnerable people. See [what v0.1 must prove](#what-v01-must-prove).

---

## The privacy promise

1. **Everything runs on your own computer.** The AI model, speech recognition and photo reading all run locally. The only internet use is downloading the AI model once, from Hugging Face, which sends none of your data.
2. **Saral refuses to send your data off the machine.** The model connection only accepts this computer or your home network, unless you explicitly change that.
3. **No content telemetry, ever.** Photos are processed in memory and not stored.
4. **Free and open source** under Apache 2.0. Anyone can read the code and check these claims.

## How it works

```
 Phone (web app, paired by QR)  ──home Wi-Fi──▶  Saral on a laptop or mini-PC
                                                   │
                                                   ├─ Read:   photo → text (Tesseract OCR)
                                                   ├─ Facts:  amounts, dates, phones, links (rules, not AI)
                                                   ├─ Think:  explanation in your language (Qwen3, bundled llama.cpp engine)
                                                   ├─ Guard:  no invented numbers, every point quoted from the paper
                                                   └─ Safety: fixed warnings, verification steps, emergency numbers
```

**The design rule: extract facts deterministically, let the AI explain them, and let the human decide.**

- Numbers and dates are pulled out by rules, never by the model, and shown exactly as written.
- Every explanation point must quote the paper. Points that can't be matched are dropped.
- If the model writes a number that isn't on the paper, the answer is rejected and retried; if it still fails, Saral shows only the exact facts.
- Scam warnings and "how to check safely" steps are written by people, in every language, and always shown. Saral never says a message is "safe."
- Emergency phrases ("chest pain", "can't breathe", self-harm) get a fixed response with the right phone numbers before any AI runs.

## Install (for families)

No terminal, no extra programs. Saral includes its own AI engine.

1. **Download** the installer for your computer from the [Releases page](https://github.com/Fullcountr/saral/releases): `Saral-Setup.exe` for Windows, the `.dmg` for a Mac.
2. **Double-click it.** A setup screen opens in your browser, in your language. It checks the computer and downloads Saral's AI once (1.3–5 GB, resumes if the internet drops). No internet? Use a Saral USB stick instead.
3. **Scan the code** on the screen with your phone's camera, then tap "Add to Home screen."

That's it. Saral starts by itself whenever the computer turns on.

> The first public installers will appear with the first release. Until they are code-signed, Windows may say "Windows protected your PC" (click **More info → Run anyway**), and on a Mac you right-click Saral and choose **Open** the first time. Windows may also ask to allow Saral on your network: choose **Allow**, so your phone can reach it.

**Best for elders:** a family member sets it up once, or uses a preloaded Saral box (planned), so the person using Saral never installs anything.

## Install with pip (for tech-comfortable users)

```bash
pip install saral
saral            # opens the setup screen; it downloads the AI engine and model for you
```

To read photos of papers, also install Tesseract: `brew install tesseract tesseract-lang` (Mac), `sudo apt install tesseract-ocr tesseract-ocr-hin tesseract-ocr-tel` (Ubuntu), or the [Windows installer](https://github.com/UB-Mannheim/tesseract/wiki). The setup screen reminds you if it's missing.

## For developers

```bash
git clone https://github.com/Fullcountr/saral.git
cd saral
pip install -e ".[dev,ocr]"

saral            # the same one-click app: opens the setup screen
saral doctor     # what this computer has and which model tier it gets
```

For AI answers during development, put llama.cpp's `llama-server` on your PATH (or set `SARAL_LLAMA_SERVER`). You can also use an existing Ollama install with `saral serve --backend ollama`, or run with no model at all: `saral serve --backend rules`.

Build the installer locally with `pip install -e ".[ocr,build]"`, then `python packaging/fetch_llama.py --platform <win-x64|macos-arm64|macos-x64|linux-x64>`, `python packaging/bundle_tesseract.py` and `python packaging/build.py`. Pushing a `v*` tag builds all installers in GitHub Actions ([release.yml](https://github.com/Fullcountr/saral/blob/main/.github/workflows/release.yml)).

## Hardware tiers

`saral doctor` measures the machine and picks a tier automatically.

| Tier | Typical machine | Model | Good for |
| --- | --- | --- | --- |
| Lite | 8 GB laptop, no GPU | `qwen3:1.7b` | Scam checks, short documents; slower |
| Standard | 16 GB laptop or mini-PC | `qwen3:4b` | Everything in v0.1 at usable speed |
| Plus | 32 GB, Apple Silicon or 12 GB+ GPU | `qwen3:8b` | Long documents, better explanations |

## Languages

v0.1 ships English, Hindi (हिन्दी), Telugu (తెలుగు) and Spanish. Safety text in Hindi, Telugu and Spanish **needs review by native speakers**; please help (see [CONTRIBUTING.md](https://github.com/Fullcountr/saral/blob/main/CONTRIBUTING.md)).

## Testing and evals

```bash
pytest                         # unit, API, safety and "no network" tests
saral eval --backend rules     # deterministic evals (runs in CI)
saral eval --backend ollama    # full evals with your local model
```

The eval sets in [`evals/`](https://github.com/Fullcountr/saral/blob/main/evals/) are the most valuable part of the project: real-world-style messages and documents per language with ground truth. Contributions of new (anonymized or synthetic) cases are very welcome.

## What v0.1 must prove

Before adding features, v0.1 has to pass its gate:

- Amounts and dates extracted exactly in ≥99% of eval documents, with zero changed digits in explanations.
- Zero outbound network connections during a full session (enforced by a test).
- Five real testers finish "is this a scam?" and "explain this paper" without help.

## Project docs

- [Architecture](https://github.com/Fullcountr/saral/blob/main/docs/ARCHITECTURE.md)
- [Edge cases and how Saral handles them](https://github.com/Fullcountr/saral/blob/main/docs/EDGE_CASES.md)
- [Roadmap](https://github.com/Fullcountr/saral/blob/main/docs/ROADMAP.md)
- [Third-party models and licenses](https://github.com/Fullcountr/saral/blob/main/docs/THIRD_PARTY.md)
- [Security policy](https://github.com/Fullcountr/saral/blob/main/SECURITY.md) · [Trademark policy](https://github.com/Fullcountr/saral/blob/main/TRADEMARK.md) · [Contributing](https://github.com/Fullcountr/saral/blob/main/CONTRIBUTING.md)

## License

Code: [Apache License 2.0](https://github.com/Fullcountr/saral/blob/main/LICENSE). The name "Saral" and its logo are covered by the [trademark policy](https://github.com/Fullcountr/saral/blob/main/TRADEMARK.md).

Saral explains and drafts; it does not give legal, medical or financial advice, and it never acts on your behalf.
