saral 0.1.0__py3-none-any.whl

saral/__init__.py

@@ -0,0 +1,7 @@
+"""Saral: a private, voice-first AI helper that runs at home.
+
+Design rule behind every job: extract facts deterministically, let the AI
+explain them, and let the human decide.
+"""
+
+__version__ = "0.1.0"

saral/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

saral/app.py

@@ -0,0 +1,129 @@
+"""The one-click app: what runs when someone double-clicks Saral.
+
+It starts the local server (reachable by paired phones on home Wi-Fi), starts the
+bundled AI engine when the model is present, and opens the browser on the setup
+screen the first time or on Saral itself afterwards. If Saral is already running,
+double-clicking just opens the window again.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import logging
+import socket
+import sys
+import threading
+import time
+import webbrowser
+
+import httpx
+
+from .config import Settings, data_dir
+
+DEFAULT_PORT = 8765
+log = logging.getLogger("saral")
+
+
+def _setup_logging() -> None:
+    # Windowed builds have no console: keep a small log file for troubleshooting.
+    log_path = data_dir() / "saral.log"
+    handlers: list[logging.Handler] = [logging.FileHandler(log_path, encoding="utf-8")]
+    if sys.stderr is not None:
+        handlers.append(logging.StreamHandler())
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s", handlers=handlers)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    if sys.stdout is None:
+        sys.stdout = open(log_path, "a", encoding="utf-8")  # noqa: SIM115
+    if sys.stderr is None:
+        sys.stderr = sys.stdout
+
+
+def saral_running(port: int) -> bool:
+    try:
+        r = httpx.get(f"http://127.0.0.1:{port}/api/health", timeout=1.0)
+        return r.status_code == 200 and "version" in r.json()
+    except (httpx.HTTPError, ValueError):
+        return False
+
+
+def port_free(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind(("0.0.0.0", port))
+        except OSError:
+            return False
+    return True
+
+
+def choose_port() -> int:
+    """Keep the same port across restarts so paired phones keep working."""
+    saved = data_dir() / "port"
+    with contextlib.suppress(ValueError, OSError):
+        port = int(saved.read_text().strip())
+        if port_free(port):
+            return port
+    for port in range(DEFAULT_PORT, DEFAULT_PORT + 20):
+        if port_free(port):
+            saved.write_text(str(port))
+            return port
+    raise OSError("No free port for Saral between 8765 and 8784.")
+
+
+def open_window(port: int, path: str) -> None:
+    webbrowser.open(f"http://127.0.0.1:{port}{path}")
+
+
+def run_app(background: bool = False) -> int:
+    _setup_logging()
+    saved = data_dir() / "port"
+    with contextlib.suppress(ValueError, OSError):
+        existing = int(saved.read_text().strip())
+        if saral_running(existing):
+            if not background:
+                open_window(existing, "/")
+            return 0
+
+    import uvicorn
+
+    from .server import create_app
+
+    settings = Settings.from_env()
+    settings.port = choose_port()
+    settings.host = "0.0.0.0"  # paired phones on home Wi-Fi; the token protects the API
+    app = create_app(settings)
+    rt = app.state.runtime
+    server = uvicorn.Server(
+        uvicorn.Config(app, host=settings.host, port=settings.port, log_level="warning")
+    )
+    rt.on_quit.append(lambda: setattr(server, "should_exit", True))
+
+    def open_when_ready() -> None:
+        for _ in range(100):
+            if server.started:
+                break
+            time.sleep(0.1)
+        if not background:
+            open_window(settings.port, "/" if rt.model_installed() else "/setup")
+
+    threading.Thread(target=open_when_ready, daemon=True).start()
+    log.info("Saral started on port %s (tier %s)", settings.port, rt.report.tier)
+    try:
+        server.run()
+    finally:
+        if rt.engine_manager:
+            rt.engine_manager.stop()
+        log.info("Saral stopped")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="saral-app")
+    parser.add_argument("--background", action="store_true", help="start without opening a window")
+    args, _ = parser.parse_known_args(argv)
+    return run_app(background=args.background)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

saral/autostart.py

@@ -0,0 +1,77 @@
+"""Start Saral when the computer turns on, so nobody has to remember to open it.
+
+Windows: a tiny script in the Startup folder. macOS: a LaunchAgent.
+Linux: an XDG autostart entry. All are per-user and easy to remove.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import plistlib
+import sys
+from pathlib import Path
+
+LABEL = "org.saral.app"
+
+
+def launch_command() -> list[str]:
+    """How to start Saral in the background (no browser window)."""
+    if getattr(sys, "frozen", False):
+        return [sys.executable, "--background"]
+    return [sys.executable, "-m", "saral", "app", "--background"]
+
+
+def _windows_path() -> Path:
+    appdata = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+    return appdata / "Microsoft" / "Windows" / "Start Menu" / "Programs" / "Startup" / "Saral.vbs"
+
+
+def _mac_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def _linux_path() -> Path:
+    base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / "autostart" / "saral.desktop"
+
+
+def entry_path() -> Path:
+    system = platform.system()
+    if system == "Windows":
+        return _windows_path()
+    if system == "Darwin":
+        return _mac_path()
+    return _linux_path()
+
+
+def is_enabled() -> bool:
+    return entry_path().exists()
+
+
+def enable() -> Path:
+    path = entry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    cmd = launch_command()
+    system = platform.system()
+    if system == "Windows":
+        # VBScript runs the app with no console window (style 0 = hidden).
+        quoted = " ".join(f'""{part}""' for part in cmd)
+        path.write_text(f'CreateObject("WScript.Shell").Run "{quoted}", 0, False\r\n')
+    elif system == "Darwin":
+        with path.open("wb") as fh:
+            plistlib.dump(
+                {"Label": LABEL, "ProgramArguments": cmd, "RunAtLoad": True, "KeepAlive": False},
+                fh,
+            )
+    else:
+        exec_line = " ".join(f'"{part}"' if " " in part else part for part in cmd)
+        path.write_text(
+            "[Desktop Entry]\nType=Application\nName=Saral\n"
+            f"Exec={exec_line}\nX-GNOME-Autostart-enabled=true\nNoDisplay=false\n"
+        )
+    return path
+
+
+def disable() -> None:
+    entry_path().unlink(missing_ok=True)

saral/binaries.py

@@ -0,0 +1,124 @@
+"""Find tools that ship inside the Saral installer (llama-server, Tesseract).
+
+Search order: an explicit environment variable, the folder bundled inside the
+installed app, Saral's data folder, then the system PATH (for developers).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .config import data_dir
+
+IS_WINDOWS = os.name == "nt"
+
+
+def app_root() -> Path:
+    """Folder of the installed app (PyInstaller) or the source package."""
+    frozen = getattr(sys, "_MEIPASS", None)
+    return Path(frozen) if frozen else Path(__file__).resolve().parent
+
+
+def bundled_dir() -> Path:
+    return app_root() / "bin"
+
+
+def is_frozen() -> bool:
+    return bool(getattr(sys, "frozen", False))
+
+
+def _exe(name: str) -> str:
+    return f"{name}.exe" if IS_WINDOWS else name
+
+
+def find_tool(name: str, env_var: str | None = None, subdir: str | None = None) -> Path | None:
+    if env_var and os.environ.get(env_var):
+        path = Path(os.environ[env_var])
+        return path if path.exists() else None
+    folders = [bundled_dir(), data_dir() / "bin"]
+    if subdir:
+        folders = [f / subdir for f in folders] + folders
+    for folder in folders:
+        candidate = folder / _exe(name)
+        if candidate.exists():
+            return candidate
+    found = shutil.which(name)
+    return Path(found) if found else None
+
+
+# Oldest llama.cpp build Saral trusts on the system PATH (Qwen3 + chat template options).
+MIN_LLAMA_BUILD = int(os.environ.get("SARAL_MIN_LLAMA_BUILD", "5300"))
+_version_cache: dict[tuple[str, float], int | None] = {}
+
+
+def llama_version(path: Path) -> int | None:
+    """llama.cpp build number from `llama-server --version`, or None if unknown."""
+    try:
+        key = (str(path), path.stat().st_mtime)
+    except OSError:
+        return None
+    if key not in _version_cache:
+        version = None
+        try:
+            out = subprocess.run(
+                [str(path), "--version"],
+                capture_output=True,
+                text=True,
+                timeout=15,
+                creationflags=0x08000000 if IS_WINDOWS else 0,
+            )
+            match = re.search(r"version:?\s*b?(\d+)", out.stdout + out.stderr)
+            version = int(match.group(1)) if match else None
+        except (OSError, subprocess.SubprocessError):
+            version = None
+        _version_cache[key] = version
+    return _version_cache[key]
+
+
+def _skip_system_flag() -> Path:
+    return data_dir() / "skip_system_engine"
+
+
+def mark_system_engine_bad(path: Path) -> None:
+    """Remember that the PATH llama-server failed, so Saral fetches its own next time."""
+    _skip_system_flag().write_text(str(path))
+
+
+def llama_server_info() -> tuple[Path | None, str]:
+    """The engine to use and where it came from: env | bundled | saral | system | none."""
+    if os.environ.get("SARAL_LLAMA_SERVER"):
+        path = Path(os.environ["SARAL_LLAMA_SERVER"])
+        return (path, "env") if path.exists() else (None, "none")
+    for source, folder in (("bundled", bundled_dir()), ("saral", data_dir() / "bin")):
+        for candidate in (folder / "llama" / _exe("llama-server"), folder / _exe("llama-server")):
+            if candidate.exists():
+                return candidate, source
+    found = shutil.which("llama-server")
+    if found:
+        path = Path(found)
+        skipped = _skip_system_flag()
+        if skipped.exists() and skipped.read_text().strip() == str(path):
+            return None, "none"
+        version = llama_version(path)
+        if version is not None and version < MIN_LLAMA_BUILD:
+            return None, "none"  # too old: Saral downloads its own instead
+        return path, "system"
+    return None, "none"
+
+
+def llama_server() -> Path | None:
+    return llama_server_info()[0]
+
+
+def tesseract() -> tuple[Path | None, Path | None]:
+    """Tesseract binary and, when bundled, its tessdata folder."""
+    binary = find_tool("tesseract", "SARAL_TESSERACT", subdir="tesseract")
+    if binary is None:
+        return None, None
+    tessdata = binary.parent / "tessdata"
+    return binary, (tessdata if tessdata.is_dir() else None)

saral/cli.py

@@ -0,0 +1,161 @@
+"""Command line: `saral doctor`, `saral serve`, `saral pull`, `saral eval`, `saral pair --reset`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .config import Settings
+
+
+def cmd_app(args: argparse.Namespace) -> int:
+    from .app import run_app
+
+    return run_app(background=args.background)
+
+
+def cmd_doctor(_: argparse.Namespace) -> int:
+    from . import binaries
+    from .models import CATALOG, choose_tier, installed, model_path
+    from .ocr import tesseract_available
+    from .probe import probe
+    from .speech import speech_available
+
+    report = probe()
+    tier, reason = choose_tier(report.ram_gb, report.gpu_vram_gb)
+    model = CATALOG[tier]
+    engine = binaries.llama_server()
+    print("Saral doctor (for developers; families use the setup screen)\n")
+    print(f"  Computer     {report.os}, {report.cpu_cores} cores, {report.ram_gb} GB memory")
+    print(f"  Disk free    {report.free_disk_gb} GB")
+    print(f"  GPU          {report.gpu or 'none (CPU is fine)'}")
+    why = {"chosen": "your choice", "disk": "smaller: low disk space", "hardware": "fits"}[reason]
+    print(f"  Model        {model.filename} ({model.size_gb} GB, {why})")
+    print(f"  AI engine    {engine or 'llama-server not found'}")
+    print(f"  AI model     {model_path(model) if installed(model) else 'not downloaded yet'}")
+    print(f"  Photo OCR    {'ready' if tesseract_available() else 'not installed'}")
+    print(f"  Voice input  {'ready' if speech_available() else 'not installed'}")
+    for warning in report.warnings:
+        print(f"\n  ! {warning}")
+    if engine is None:
+        print("\n  Developers: put llama.cpp's llama-server on PATH or set SARAL_LLAMA_SERVER.")
+    if not installed(model):
+        print("  Get the model with: saral pull   (or run `saral` and use the setup screen)")
+    return 0
+
+
+def cmd_pull(_: argparse.Namespace) -> int:
+    import time
+
+    from .engine_fetch import EngineStep
+    from .models import CATALOG, ModelInstaller, choose_tier
+    from .probe import probe
+
+    report = probe()
+    model = CATALOG[choose_tier(report.ram_gb, report.gpu_vram_gb)[0]]
+    print(f"Downloading {model.filename} (about {model.size_gb} GB). It resumes if interrupted.")
+    installer = ModelInstaller(model, before=EngineStep())  # also fetches the engine if missing
+    installer.start_download()
+    while installer.busy:
+        st = installer.state.to_dict()
+        print(f"\r  {st['status']:<11} {st['percent']:5.1f}%", end="", flush=True)
+        time.sleep(1)
+    print()
+    if installer.state.status != "done":
+        print(f"Failed: {installer.state.error}", file=sys.stderr)
+        return 1
+    print("Done.")
+    return 0
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    import uvicorn
+
+    from .pairing import get_or_create_token, lan_ip
+    from .server import create_app
+
+    settings = Settings.from_env()
+    if args.backend:
+        settings.backend = args.backend
+    if args.region:
+        settings.region = args.region.upper()
+    settings.port = args.port
+    settings.host = "0.0.0.0" if args.lan else "127.0.0.1"
+
+    app = create_app(settings)
+    print(f"\nSaral is running. On this computer open: http://127.0.0.1:{settings.port}")
+    if args.lan:
+        link = f"http://{lan_ip()}:{settings.port}/?pair={get_or_create_token()}"
+        print("\nOn your phone (same Wi-Fi), open this pairing link once:")
+        print(f"  {link}")
+        try:
+            import qrcode
+
+            qr = qrcode.QRCode(border=1)
+            qr.add_data(link)
+            qr.print_ascii(invert=True)
+        except ImportError:
+            print("  (pip install 'saral[qr]' to show a QR code here)")
+        print("Keep this link private. Run `saral pair --reset` to unpair all phones.\n")
+    uvicorn.run(app, host=settings.host, port=settings.port, log_level="warning")
+    return 0
+
+
+def cmd_pair(args: argparse.Namespace) -> int:
+    from .pairing import get_or_create_token, reset_token
+
+    token = reset_token() if args.reset else get_or_create_token()
+    print("All phones unpaired. New pairing token created." if args.reset else token)
+    return 0
+
+
+def cmd_eval(args: argparse.Namespace) -> int:
+    from .evals import run_all
+
+    report = run_all(backend_name=args.backend)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["gate"]["passed"] else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="saral", description="Saral: your private helper at home."
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    app = sub.add_parser("app", help="start Saral the easy way (default when no command)")
+    app.add_argument("--background", action="store_true", help="start without opening a window")
+    app.set_defaults(func=cmd_app)
+
+    sub.add_parser("doctor", help="check this computer and pick a model size").set_defaults(
+        func=cmd_doctor
+    )
+    sub.add_parser("pull", help="download the recommended model via Ollama").set_defaults(
+        func=cmd_pull
+    )
+
+    serve = sub.add_parser("serve", help="start Saral")
+    serve.add_argument("--lan", action="store_true", help="allow paired phones on home Wi-Fi")
+    serve.add_argument("--port", type=int, default=8765)
+    serve.add_argument("--backend", choices=["local", "ollama", "rules"])
+    serve.add_argument("--region", choices=["IN", "US", "in", "us"])
+    serve.set_defaults(func=cmd_serve)
+
+    pair = sub.add_parser("pair", help="show or reset the phone pairing token")
+    pair.add_argument("--reset", action="store_true", help="unpair every phone")
+    pair.set_defaults(func=cmd_pair)
+
+    ev = sub.add_parser("eval", help="run the eval sets and check the release gate")
+    ev.add_argument("--backend", choices=["rules", "ollama"], default="rules")
+    ev.set_defaults(func=cmd_eval)
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        # Double-click or plain `saral`: the one-click app.
+        return cmd_app(argparse.Namespace(background=False))
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

saral/config.py

@@ -0,0 +1,84 @@
+"""Settings, hardware tiers and supported languages."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Tier:
+    """A hardware tier and the model that runs well on it."""
+
+    name: str
+    min_ram_gb: float
+    model: str
+    approx_model_gb: float
+    note: str
+
+
+# Ordered from smallest to largest. The probe picks the largest tier that fits.
+# Qwen3 is Apache-2.0, trained on 119 languages, and ships in sizes for each tier.
+TIERS: tuple[Tier, ...] = (
+    Tier("lite", 0, "qwen3:1.7b", 1.4, "Works on 8 GB laptops. Short answers, slower."),
+    Tier("standard", 12, "qwen3:4b", 2.6, "16 GB laptop or mini-PC. All jobs at usable speed."),
+    Tier("plus", 24, "qwen3:8b", 5.2, "32 GB or a GPU. Long documents, better reasoning."),
+)
+
+
+@dataclass(frozen=True)
+class Language:
+    code: str
+    english_name: str
+    native_name: str
+
+
+LANGUAGES: dict[str, Language] = {
+    "en": Language("en", "English", "English"),
+    "hi": Language("hi", "Hindi", "हिन्दी"),
+    "te": Language("te", "Telugu", "తెలుగు"),
+    "es": Language("es", "Spanish", "Español"),
+}
+
+DEFAULT_LANGUAGE = "en"
+
+# Region changes date order (03/04 = 3 April in India, March 4 in the US)
+# and which emergency numbers we show.
+REGIONS = ("IN", "US")
+DEFAULT_REGION = "IN"
+
+
+def data_dir() -> Path:
+    """Where Saral keeps its small amount of local state (the pairing token)."""
+    root = os.environ.get("SARAL_HOME")
+    path = Path(root) if root else Path.home() / ".saral"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+@dataclass
+class Settings:
+    """Runtime settings. Everything defaults to local-only."""
+
+    # "local" = bundled llama.cpp engine (default, nothing extra to install),
+    # "ollama" = an existing Ollama install (for developers),
+    # "rules" = no model, deterministic output only.
+    backend: str = "local"
+    model: str | None = None  # None = pick from hardware tier
+    ollama_url: str = "http://127.0.0.1:11434"
+    allow_remote_model_host: bool = False  # refuse to send data off this machine
+    region: str = DEFAULT_REGION
+    host: str = "127.0.0.1"
+    port: int = 8765
+    require_token_for_lan: bool = True
+    extra: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        s = cls()
+        s.backend = os.environ.get("SARAL_BACKEND", s.backend)
+        s.model = os.environ.get("SARAL_MODEL") or None
+        s.ollama_url = os.environ.get("SARAL_OLLAMA_URL", s.ollama_url)
+        s.region = os.environ.get("SARAL_REGION", s.region).upper()
+        return s