◆ Genie Installer

An offline-voice-driven, agentic software deployment system for Windows desktops.

Speak a software name. Genie transcribes it locally, resolves an installation strategy, orchestrates the install, and streams the result back in real time — no cloud speech API, no manual downloads, no babysitting the installer.

Architecture · How It Works · Tech Stack · Project Structure · Setup · Status

💡 Why Genie?

Installing developer or enterprise software the traditional way means the same repetitive manual loop every time:

Search software → Find website → Download installer → Run installer
      → Configure options → Fix errors → Set PATH → Verify installation

Genie collapses that loop behind a single spoken command. You say "install Python," and the system takes over: it transcribes the request entirely on-device, sends it to a Python execution engine, and orchestrates acquisition and installation while streaming progress back to a live dashboard — without you touching a browser, a download button, or an installer wizard.

🏗 System Architecture

Genie is built as a decoupled, hybrid-desktop system with a strict separation between presentation, orchestration, and offline AI inference — deliberately avoiding a monolithic GUI-does-everything design.

flowchart TD
    A[User: Voice Command] --> B["Presentation Layer<br/>Next.js 14 + React 18 (Tauri shell)"]
    B -->|Web Audio API, 48kHz| C["Browser-side DSP<br/>Downsample to 16kHz PCM"]
    C -->|Tauri invoke| D["Rust IPC Bridge<br/>src-tauri"]
    D -->|spawns| E["whisper-cli.exe<br/>ggml-base.en.bin (offline)"]
    E -->|transcript| D
    D --> B
    B -->|REST: POST /install| F["Execution Engine<br/>FastAPI (Genie_Engine)"]
    F --> G["Core Orchestration Logic<br/>core/"]
    G --> H["Acquisition & Automation Tools<br/>tools/"]
    G --> I["State Store<br/>SQLite + memorystore.json"]
    F -.->|WebSocket telemetry| B

Presentation Layer (Tauri + Next.js): A lightweight desktop host wrapping a React 18 / TypeScript SPA. It behaves as an event-driven state machine — it visualizes telemetry and captures voice input, but does not itself execute install logic.
Desktop Bridge (Tauri / Rust): Handles native OS access the browser sandbox can't — spawning the Whisper CLI process, reading temp files, and invoking backend calls.
Execution Engine (Python FastAPI — Genie_Engine): The authoritative backend. Owns installation orchestration, process state, and telemetry streaming.

Dual-protocol communication

Protocol	Purpose
REST over HTTP	Deterministic state changes — initiating an install, health checks
WebSockets (full-duplex)	Real-time `stdout` log streaming and install progress, without polling

⚙️ End-to-End Workflow

sequenceDiagram
    participant U as User
    participant FE as React UI
    participant RS as Rust (Tauri)
    participant W as whisper-cli.exe
    participant BE as FastAPI (Genie_Engine)

    U->>FE: Speaks "Install Python"
    FE->>FE: Capture @48kHz, downsample to 16kHz PCM, write WAV (manual RIFF header)
    FE->>RS: invoke whisper_transcribe_wav(path)
    RS->>RS: Copy WAV to safe path (avoid spaces-in-path failures)
    RS->>RS: Sleep 500ms (avoid Windows Defender file-lock race)
    RS->>W: Spawn whisper-cli.exe (-f, -m, -l en, -nt, -np, --prompt)
    W-->>RS: Raw transcript
    RS->>RS: Filter hallucinated tokens ("you", ".", "subtitles")
    RS-->>FE: Cleaned transcript
    FE->>BE: POST /install { software: "python" }
    BE->>BE: Spawn background task, run acquisition + install
    BE-->>FE: WebSocket: live stdout / progress
    FE-->>U: Real-time status

Four engineering problems worth calling out explicitly, because they're the actual substance of this project rather than boilerplate:

1. Browser-native audio has to become a Whisper-safe 16kHz WAV

AudioContext captures raw audio at the system's native rate (typically 48kHz) as Float32Array data. Whisper C++ expects 16kHz. The frontend performs manual decimation (48000 / 16000 = a 3:1 reduction) and writes the RIFF/WAVE header fields directly via DataView, rather than relying on a library, so the resulting file is guaranteed to match what whisper-cli.exe expects.

2. Windows Defender locks the temp file before Rust can read it

The moment the WAV blob lands in the Windows temp directory, Defender grabs it for a scan. If Rust tries to open it immediately, the read fails. The bridge inserts a short, explicit wait before touching the file to let the OS release the lock.

3. Paths with spaces break the CLI invocation

Usernames like Md Asif Khan produce paths the Whisper CLI can mis-handle. Rust copies the temp audio file into the app's own execution directory under a fixed, space-free filename before invoking the CLI.

4. Whisper hallucinates on silence/background noise

Without a VAD (Voice Activity Detection) stage, short or noisy captures produce junk tokens like "you" or "subtitles." The Rust layer filters known hallucination patterns out of stdout before the transcript ever reaches the UI, and a --prompt flag constrains the model toward expected vocabulary (software names).

🧩 Core Capabilities

Voice & Edge AI

Fully offline speech-to-text via quantized Whisper C++ (ggml-base.en.bin)
Custom in-browser audio pipeline (capture → downsample → WAV encode)
Local hallucination filtering — no cloud STT dependency, no audio leaves the device

Orchestration Engine

FastAPI backend as the single source of truth for install state
REST endpoint for triggering installs; WebSocket channel for live telemetry
Modular core/ orchestration logic separate from tools/ acquisition logic

Software Acquisition Tooling (in development — presence confirmed, internal implementation not fully verified)

Site discovery / classification (site_discovery.py, site_classifier.py)
Download link resolution (web_scraper.py, link_resolver.py)
Domain allow-listing (domain_whitelist.py)
Binary acquisition (downloader.py)
Security validation hooks (security.py)

These tools exist in the repository's module structure. Their exact runtime behavior (verification method, retry logic, etc.) wasn't confirmed in the source material, so this README doesn't claim specifics it can't back up.

📡 Backend Architecture

Framework: Python, FastAPI, served via Uvicorn.

uvicorn main:app --reload --port 8000

Genie_Engine/core/ — orchestration and state

agent.py — install task orchestration
installer.py — OS-level install execution
error_solver.py — failure-path handling
state_manager.py / memorystore.py — session state

Genie_Engine/tools/ — acquisition and environment

env_manager.py, path_manager.py — environment/PATH handling
installer_type_handler.py — differentiates .exe / .msi / scripted installs
security.py, domain_whitelist.py — binary and source validation
site_discovery.py, site_classifier.py, web_scraper.py, link_resolver.py, downloader.py — acquisition pipeline

Genie_Engine/gui/ — Python-native UI (app.py, config_popup.py), separate from the Tauri desktop client.

backend/ — legacy/alternative REST routes (routes/install.py), superseded by Genie_Engine as the primary engine.

🖥 Frontend Architecture

Framework: Next.js 14, React 18, TypeScript, Tailwind CSS.

app/installer/page.tsx — voice capture UI + WebSocket listener
lib/genieBridge.ts — builds and sends sanitized REST payloads to FastAPI
UI layer includes animated visual components (gradient/particle/blur effects) for the live telemetry display
src-tauri/ — Rust bridge exposing native invokers (main.rs), bundling the whisper-cli.exe sidecar and the ggml-base.en.bin model

🔧 Tech Stack

Layer	Technology	Purpose
Frontend UI	Next.js 14, React 18, TypeScript, Tailwind CSS	Desktop SPA / telemetry dashboard
Desktop Bridge	Tauri, Rust	Native IPC, process spawning, file access
Voice / Edge AI	Whisper C++ CLI, quantized `ggml-base.en.bin` (~148MB)	Fully offline transcription
Backend Engine	Python, FastAPI, Uvicorn	Install orchestration, REST + WebSocket API
State / Storage	SQLite (`genie_memory.db`), JSON (`memorystore.json`)	Session and install state persistence
Version Control	Git, GitHub	Source control

📂 Project Structure

Reconstructed from the confirmed project layout — nothing here is invented.

AUTO_GENIE/
├── frontend/                     # Presentation & Bridge Layer
│   ├── app/                       # Next.js 14 route components
│   ├── components/                # UI components (shadcn-style + visual effects)
│   ├── lib/                       # genieBridge.ts — REST client
│   └── src-tauri/                 # Rust IPC bridge
│       ├── bin/                   # whisper-cli.exe (sidecar binary)
│       ├── models/                # ggml-base.en.bin (not tracked in git)
│       └── src/main.rs            # Core Rust invokers
│
├── Genie_Engine/                  # Execution & Orchestration Layer
│   ├── core/                      # agent.py, installer.py, error_solver.py, state_manager.py
│   ├── gui/                       # Python-native UI (app.py, config_popup.py)
│   ├── tools/                     # acquisition, PATH/env, security tooling
│   ├── data/                      # genie_memory.db, memorystore.json
│   ├── utils/                     # system_info.py, retry_guard.py
│   ├── main.py                    # FastAPI entry point
│   └── requirements.txt
│
├── backend/                       # Legacy/alternative routes (routes/install.py)
└── run_backend.py                 # Global bootstrapper script

Note on the AI model: ggml-base.en.bin exceeds GitHub's file size limits and is not tracked in the repo. It must be downloaded separately and placed in frontend/src-tauri/models/.

🔐 Security & Configuration Notes

Secrets are not committed. API keys live in Genie_Engine/core/api_key.py, which is .gitignored; the repo instead ships api_key.example.py so reviewers can see the expected shape without exposing live credentials. The key file was explicitly untracked via git rm --cached after being identified.
Voice data stays local. Because transcription runs entirely through the offline Whisper C++ binary, no audio is sent to a third-party speech API.
Acquisition safety tooling is present but its guarantees are not yet fully documented (security.py, domain_whitelist.py) — see the caveat under Core Capabilities above.

# Backend (Genie_Engine)
OPENAI_API_KEY=your_api_key
OTHER_SERVICE_KEY=your_service_key

Only variables confirmed by the project source are listed. If your local setup requires additional keys for the acquisition tooling, document them in api_key.example.py.

🚀 Running Locally

Prerequisites

Python 3.x
Node.js + npm
Windows (required for OS-level process orchestration and the Whisper CLI sidecar)
The ggml-base.en.bin model, downloaded manually (see note above)

1. Boot the execution engine (backend)

cd Genie_Engine
python -m venv env
source env/Scripts/activate    # Windows
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

2. Boot the desktop client (frontend)

cd frontend
npm install
npm run tauri dev

👤 What This Project Demonstrates

Cross-language systems integration (TypeScript ↔ Rust ↔ Python ↔ C++)
Real-time, full-duplex frontend-backend architecture (REST + WebSocket)
Offline/edge AI inference and the practical engineering problems that come with it (audio format handling, OS file-locking races, path sanitization, model hallucination)
Desktop application architecture using Tauri instead of a browser-only or Electron approach
Secret hygiene in a public repository (.gitignore, example key files, git rm --cached)

🎬 Demo

The compiled application isn't distributed directly in this repository — enterprise reviewer environments generally can't run an arbitrary .exe. Instead, this README plus the linked demo video are the primary way to evaluate the project.

Navigation Menu

Repository files navigation

◆ Genie Installer

💡 Why Genie?

🏗 System Architecture

Dual-protocol communication

⚙️ End-to-End Workflow

🧩 Core Capabilities

Voice & Edge AI

Orchestration Engine

Software Acquisition Tooling (in development — presence confirmed, internal implementation not fully verified)

📡 Backend Architecture

🖥 Frontend Architecture

🔧 Tech Stack

📂 Project Structure

🔐 Security & Configuration Notes

🚀 Running Locally

Prerequisites

1. Boot the execution engine (backend)

2. Boot the desktop client (frontend)

👤 What This Project Demonstrates

🎬 Demo

📄 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Genie_Engine		Genie_Engine
backend		backend
data		data
frontend		frontend
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
run_backend.py		run_backend.py

Latest commit

History

Folders and files

Repository files navigation

◆ Genie Installer

💡 Why Genie?

🏗 System Architecture

Dual-protocol communication

⚙️ End-to-End Workflow

🧩 Core Capabilities

Voice & Edge AI

Orchestration Engine

Software Acquisition Tooling (in development — presence confirmed, internal implementation not fully verified)

📡 Backend Architecture

🖥 Frontend Architecture

🔧 Tech Stack

📂 Project Structure

🔐 Security & Configuration Notes

🚀 Running Locally

Prerequisites

1. Boot the execution engine (backend)

2. Boot the desktop client (frontend)

👤 What This Project Demonstrates

🎬 Demo

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages