Sparky

Your private AI assistant. 100% local.
Chat, see images, generate pictures and videos with sound, build apps, ask your documents, dictate and listen —
everything runs on your own PC. Nothing is sent to the internet unless you turn it on.

🎬 The Studio — every video here was generated on the PC, with its sound, by LTX-2.5.

• 🔒 Like ChatGPT, offline — history, plus 👻 temporary chats that are never saved.
• ✏️ Edit any message, 🔁 regenerate or ➡️ continue an answer, and flip between versions (‹ 2/3 ›).
• 🧠 Adjustable thinking — Off, Light, Normal or Deep, and see how the model reasoned.
• 📝 Rich answers — tables, LaTeX formulas, Mermaid diagrams, task lists, syntax-highlighted code (all offline).
• 👁️ Vision — drop photos, screenshots or scans: the assistant sees and analyses them.
• 📎 Attach any file — PDF, Word, PowerPoint, Excel, text, code, audio and video (transcribed offline).
• 🗂️ Organize your chats — full-text search, rename, 📌 pin, 📁 folders, export (JSON / Markdown) and import.

• 📄 Ask your documents (RAG) — collections of PDFs, Office files, text, code… indexed on your PC, answers with numbered sources [1] [2].
• 🌐 Web search, when you want it — turn on Web: the assistant searches (DuckDuckGo or your SearXNG), reads pages and the links you paste, and cites them. Off by default.
• 🧑‍💼 Assistants — a role, its documents and web access, reusable in one click.
• ⚡ Prompt library — type / to insert a saved prompt with {{variables}}; standing instructions for every chat or just one.

• 🎬 Studio: images & videos — a gallery of everything you generated, with a Grok-Imagine-like prompt bar: text → image, text → video, image → video ("Animate"). Videos come with synchronized sound 🔊 (LTX-2.5), and your idea is expanded into a detailed prompt first.
• 🖼️ Images — generate and edit by asking ("make it snow", "remove the bottle"); the agent checks its own result and retries.
• 🧩 Code & apps panel — games, pages, tools and scripts written live next to the chat, with a running preview.
• 🏗️ Multi-file projects — websites (index.html + css/ + js/), Python or Node.js programs; the assistant makes the pictures, then Sparky tests the project automatically (headless browser, npm install, run) and the model fixes the errors until it works. ▶ Run anytime, download as ZIP.

• 🎤 Dictation, offline — click the mic, talk, stop: Whisper writes it in the input box.
• 🔊 Read aloud — on any answer, offline Piper voices (English, French, German, Spanish, Italian).

• 💻 Computer mode — Sparky can look at and act on your PC: browse folders and the desktop, read and search files (PDF and Office too), take a screenshot, write, copy, move, send to the Recycle Bin, open files and apps, run PowerShell commands. You choose the security level for each chat: Off, Read only, Read freely & ask before changes (recommended), Ask for everything or Full access; actions that need your OK show an approval card (Allow / Always in this chat / Deny).
• 🔌 MCP tools — plug any Model Context Protocol server (same config as Claude Desktop: files, GitHub, databases…).
• ⏰ Scheduled tasks — "every morning at 8, summarize the tech news": the answer lands in a new chat.
• 🔗 OpenAI-compatible API — use Sparky's model from Continue, VS Code extensions or scripts at http://127.0.0.1:7860/v1. Off by default.
• 🤖 Sparky Bot (beta) — a companion that remembers you and learns your style, with a memory you can see and edit (details).

• 🩺 System scan — checks your GPU, memory and disk, then recommends the models that fit your machine.
• 📦 Model library — one-click installs, fast parallel resumable downloads, speed / quality / memory indicators for your hardware.
• ♻️ Models already on your PC — LM Studio, Ollama, Hugging Face cache, Jan, GPT4All, other ComfyUI installs… used in one click.
• ☁️ Cloud models, if you want — OpenRouter, Claude, OpenAI, Gemini, Mistral… Off by default.
• ✅ Only official models — "uncensored", "abliterated" or NSFW variants are excluded from the catalog and the Hugging Face search.
• 🌗 Light or dark theme, 🇬🇧 English or 🇫🇷 French interface, ⬆️ one-click updates.

💻 Computer mode — Sparky reads your files, then asks before writing	📦 Model library — assistants, images, videos, voice
🎬 Studio — your images and videos, with their sound	🎞️ Video viewer — balloons over Cappadocia, made on the PC in 2 minutes
✨ Image → video — pick a picture, describe the motion and the sounds	🌐 Web search — the assistant searches, reads and cites its sources
📄 Documents — answers from your files, with numbered sources	📝 Rich answers — tables, LaTeX, Mermaid, versions of an answer
📚 Workspace — document collections indexed on your PC	🧑‍💼 Assistants — a role, documents and web access, reusable
⚡ Prompt library — type / to insert a saved prompt	🔌 Tools (MCP) — plug any MCP server
⏰ Scheduled tasks — prompts that run by themselves	🌗 Light theme — or dark, or follow Windows
🖼️ Images — generate, then edit by instruction	🧠 Thinking — see how the model reasoned
⚙️ Settings — language, theme, system, models, context	📦 All models — speed, quality and memory for your PC
🩺 First launch — system scan and recommended models	🔀 Model menu — switch models, pick a thinking level

🧩 A Breakout game written live in the side panel, then played.

Offline voice dictation: live level bars, then the text lands in the input box.

Status: in active development. Sparky Bot ships as a beta inside Sparky (sidebar → Sparky Bot). It works today, but the memory engine and the personality system are still being tuned and may change.

Sparky Bot is a friend-like companion that remembers you, learns your style and grows with you — in the spirit of OpenAI's Dots and Grok's companions, but 100% local and with a memory you can actually see and edit.

Memory — every fact it learned, grouped, editable, pinnable	Journal — it reflects between conversations and remembers to follow up

How the memory works

• Learns after every message — a background pass extracts durable facts about you (who you are, tastes, projects, people, goals, events) and decides to add, update or forget, Mem0-style.
• Guard-rails in code, not just in the prompt — one fact per memory; an update must be about the same fact (checked by meaning) or it becomes a new memory instead of overwriting; near-duplicates are ignored; a new memory must come from your words, never from the bot's own reply.
• Smart retrieval — before each reply it picks the memories that matter now: meaning (local multilingual embeddings, multilingual-e5-small), importance, recency, plus pinned facts.
• Time-aware — "next Tuesday" is stored as a real date, and past events are updated with what happened.
• Learns your style — tone, length, formality, humor, language.
• Reflects when idle — merges duplicates, writes a short journal, updates its summary of your relationship and prepares what to ask next time ("How did the meetup go?").
• Relationship level — from Just met to Close friends as you talk over days. Always a friend: never romantic, never clingy.
• You stay in control — see, edit, pin or delete any memory, turn learning off, or Forget everything in one click. Nothing leaves your PC.

Roadmap

• Persistent memory with add / update / forget, guard-rails and semantic search
• Style profile, journal, follow-ups, relationship level, 4 personalities
• Animated avatar, bilingual UI (English / French)
• Voice conversations (Whisper in, local text-to-speech out; read-aloud already works in the main chat)
• Proactive check-ins (optional notifications)
• Memory import / export, per-memory "why do you know this?" with the source message
• Larger evaluation set for the memory engine across models

One line, in PowerShell:

irm https://raw.githubusercontent.com/anisayari/sparky/main/install.ps1 | iex

Or download the project (Code > Download ZIP), unzip it and double-click install.bat.

The installer walks you through 7 simple steps:

1. choose your language (English / Français) and check your machine,
2. pick the install folder (default %LOCALAPPDATA%\Sparky),
3. install Python 3.12 if needed (via winget),
4. install PyTorch for your GPU and the image engine ComfyUI,
5. install the AI engine llama.cpp (CUDA build for NVIDIA GPUs, x64 or ARM64),
6. scan your hardware and show the models recommended for it (nothing is downloaded yet),
7. create a Sparky shortcut on the desktop and in the Start menu, then open Sparky in your browser.

Sparky then opens at http://127.0.0.1:7860 on its welcome screen: pick your language, see the system scan, use the models already on your PC in one click, or install the recommended ones (or any other from See all models). Nothing is downloaded without your click.

Next times, double-click the shortcut (or start.bat). To stop everything: stop.bat.

Installer options: -Lang en|fr, -Dir <folder>, -Yes (no questions), -Models (also download the recommended models from the terminal), -NoLaunch. For the one-line install, use the environment variables SPARKY_LANG, SPARKY_DIR, SPARKY_YES, SPARKY_MODELS, SPARKY_NOLAUNCH.

The system scan picks automatically among these.

Speeds measured on an RTX Spark N1X (Q4, full power); Sparky adapts them to your GPU.

All of them can think before answering (adjustable level). Vision can be added in one click when it is missing.

Video models are big: during a video, Sparky pauses the local assistant to give the whole GPU memory to the video model (about 5× faster), then reloads it.

* includes the IP-Adapter files (≈ 4 GB, shared by all SDXL models) used to reuse a character or a style.

Every model keeps its own license (Apache 2.0, Gemma Terms of Use, NVIDIA Open Model License, etc.): check its Hugging Face page before any commercial use.

Create a config.json file at the project root to reuse your folders:

{
  "python": "D:\\ai\\venv\\Scripts\\python.exe",
  "comfy_dir": "D:\\ai\\ComfyUI",
  "llama_server": "D:\\ai\\llama\\llama-server.exe",
  "llm_dir": "D:\\ai\\models",
  "mmproj_dir": "D:\\ai\\mmproj"
}

Other keys: voice_dir, data_dir, app_port (7860), llm_port (8080), comfy_port (8188). The SPARKY_CONFIG environment variable can point to another config file.

runtime\venv\Scripts\python.exe app\syscheck.py                  # system scan (add --lang=fr for French)
runtime\venv\Scripts\python.exe app\models_cli.py --list         # catalog
runtime\venv\Scripts\python.exe app\models_cli.py --recommended  # install the recommended models
runtime\venv\Scripts\python.exe app\models_cli.py qwen359        # install one model

• Update: Sparky checks GitHub once an hour. When a new version is out, a message offers to install the update: Sparky runs git pull and restarts by itself. If files were modified locally, it lists them and gives the command to put them aside first; for an install made from the ZIP, it gives the install command to run again. The current version is in Settings > Version (and in the VERSION file).
• Uninstall: stop.bat, then delete the install folder (%LOCALAPPDATA%\Sparky by default) and the shortcuts.

Sparky is 100% local by default. If you want, Settings > Cloud models lets you add a key for OpenRouter, Anthropic (Claude), OpenAI, Google Gemini, Mistral, Groq, DeepSeek, xAI, or any OpenAI-compatible server (LM Studio, vLLM, a company proxy...). Pick a model in the provider's list: it appears in the model menu with a ☁, and switching to it frees your GPU.

• Keys stay on your PC (data\cloud.json) and are never sent back to the page.
• While a cloud model is active, the footer says so: your messages, images and attached files then go to that provider.
• Claude goes through the official anthropic SDK (adaptive thinking, effort, refusal fallback); the others through their OpenAI-compatible API.

Everything runs on your machine: conversations, documents, images and models stay in the install folder (data\, models\). The only outgoing connections download the tools and models (GitHub, PyPI, Hugging Face, the Piper voices), search the model library, check for updates (the VERSION file on GitHub), and — only when you turn them on — search the web and read pages (Web chip of a chat, scheduled tasks), run MCP tools that reach the internet, or talk to a cloud provider.

The local API only answers the Sparky page itself: requests from other websites (cross-site or DNS rebinding) are refused, and the projects the assistant writes run on their own origin (port 7861), so their code cannot drive Sparky. The OpenAI-compatible API (/v1) is off by default; when on, it requires its key and still only listens on 127.0.0.1. Web reading refuses private and local addresses.

Off by default. Pick a level with the Computer chip under the message box (it applies to that chat):

Whatever the level: Windows, Program Files, ProgramData and Sparky's own folder can never be modified, a deletion always goes to the Recycle Bin, commands stop after 2 minutes, and the model is told that file contents are data, never instructions. "Always in this chat" only lasts until you change the level.

Turn it on in Workspace > API, then point any OpenAI client at Sparky's active model:

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:7860/v1", api_key="sk-sparky-...")  # key shown in Workspace > API
print(client.chat.completions.create(model="sparky", messages=[{"role": "user", "content": "Hello!"}]).choices[0].message.content)

Workspace > Tools (MCP) takes the same JSON as Claude Desktop, for example:

{"mcpServers": {
  "files":  {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\me\\Documents"]},
  "remote": {"url": "https://example.com/mcp", "headers": {"Authorization": "Bearer ..."}}
}}

Servers start with Sparky (the bundled Node.js provides npx); their tools are offered to the assistant in every chat.

runtime\venv\Scripts\python.exe -m pip install pytest ruff
runtime\venv\Scripts\python.exe -m ruff check app tests
runtime\venv\Scripts\python.exe -m pytest

The tests need no model, GPU or network: they run Sparky on throw-away folders, with scripted models and fake cloud providers (tests/mocks.py). GitHub Actions runs them on Windows (Python 3.10 and 3.13) and Linux, and checks that the PowerShell scripts parse in Windows PowerShell 5.1.

L'interface et l'installeur existent aussi en français : choisis Français au début de l'installation, ou change la langue dans Paramètres.

app/
  server.py     web server + model management
  harness.py    agent: assistant <-> image tools loop, artifacts
  catalog.py    catalog, downloads, indicators
  syscheck.py   system scan and recommendations
  attach.py     attached files -> text (PDF, Office, code, audio/video transcription)
  localscan.py  finds the models already on the PC (LM Studio, Ollama, Hugging Face...)
  updater.py    version check and one-click update (git pull)
  cloud.py      optional cloud providers (OpenRouter, Claude, OpenAI-compatible...)
  checker.py    automatic project tests (headless browser, Python, Node.js)
  stt.py        offline voice dictation (Whisper)
  tts.py        offline read-aloud (Piper voices through onnxruntime + espeak-ng)
  computer.py   computer mode: file / app / command tools, security levels, protected folders
  studio.py     Studio: media library, image / video / image-to-video jobs (LTX-2.5, Wan 2.2)
  rag.py        document collections: extraction, chunking, embeddings, search with citations
  web.py        web search and page reading (DuckDuckGo / Bing / SearXNG), private addresses blocked
  mcp.py        Model Context Protocol client (stdio and Streamable HTTP)
  workspace.py  assistants and prompt library
  scheduler.py  scheduled tasks
  openai_api.py OpenAI-compatible API (/v1)
  vendor/       Markdown libraries served locally (marked, DOMPurify, KaTeX, highlight.js, Mermaid)
  companion.py  Sparky Bot: persona, learning, reflection, journal (beta)
  memory.py     Sparky Bot memory: SQLite store + hybrid semantic retrieval
  index.html    interface (English / French)
install.ps1     step-by-step installer
VERSION         current version
requirements.txt  Sparky's own Python packages
tests/          regression tests (pytest), run by .github/workflows/ci.yml
start.ps1 / stop.ps1
docs/           screenshots and demos

Code under the MIT license. ComfyUI (GPL-3.0) and llama.cpp (MIT) are downloaded separately during install.