💎 KAIRI

Autonomous Local-First AI Agent & Multi-LLM IDE v2.1

Kairi is a state-of-the-art, autonomous local AI programming and research companion.
Featuring dual-engine orchestration (Supervisor & Executor), interactive code editing, real-time news synthesis,
and zero-telemetry local memory persistence.

---

✨ Why Kairi?

Unlike monolithic SaaS coding assistants, Kairi puts you in total control of your data, models, and execution environment:

• 🧠 Dual-Agent Architecture (Supervisor & Executor): Seamlessly delegate strategic planning and code execution across top-tier LLMs (DeepSeek v4 Pro / Flash, Google Gemini 3.1 Pro, Anthropic Claude 3.7, OpenAI o3, or local models).
• 🛡️ 100% Local BYOK (Bring Your Own Key): Zero cloud proxy servers. Your API keys and conversation histories remain strictly on your local machine.
• 🔒 Strictly Scope-Filtered KV Memory (No Arbitrary Recall): Unlike conventional AI assistants that silently dump your entire memory or personal profile into every prompt, Kairi strictly filters long-term KV memory by topical scope. The AI never arbitrarily snoops on or recalls past memories unless directly relevant to your active request—preventing context pollution, hallucinations, and privacy leaks.
• 📡 On-Demand Primary News & Fact Engine: Fetches real-time primary press releases (PR Newswire, BusinessWire, AP News) directly with automated fallback search—eliminating AI hallucination and stale aggregator noise.
• 🖥️ All-In-One Desktop App Ready: Integrated SPA hosting inside FastAPI allows single-click desktop deployment (kairi_desktop.py) or compiled .exe packaging.
• 🔐 Supply-Chain Security Shield: Built-in --ignore-scripts enforcement and Human-In-The-Loop (HITL) approval gates protect your terminal from malicious packages.

---

🏗️ Architecture

graph TD
    User["👤 Developer / User"] -->|Interacts| UI["🖥️ Kairi Studio UI (React + Vite + Tailwind)"]
    UI <-->|REST API / WebSocket| Server["⚡ FastAPI Backend Engine (Python 3.11+)"]
    
    subgraph Core Orchestration
        Server --> Supervisor["🧠 Supervisor Agent (Planner / Strategy)"]
        Server --> Executor["🛠️ Executor Agent (Coder / Tools)"]
    end
    
    subgraph Multi-LLM BYOK Providers
        Supervisor & Executor --> DeepSeek["DeepSeek API"]
        Supervisor & Executor --> Gemini["Google Gemini API"]
        Supervisor & Executor --> Claude["Anthropic Claude API"]
        Supervisor & Executor --> OpenAI["OpenAI API"]
    end
    
    subgraph Zero-Telemetry Local Storage
        Server <--> KV["💾 kv_store.json (Scope-Filtered KV Memory - No Arbitrary Recall)"]
        Server <--> NewsCache["📰 30-min In-Memory News Cache"]
        Server <--> Workspace["📂 Local Code Filesystem"]
    end

Loading

---

🚀 Quick Start

Step 1: Clone Repository

First, clone the official Kairi repository from GitHub:

git clone https://github.com/EMMA019/kairi-AIchat.git
cd kairi-AIchat

Step 2: Build Frontend UI Bundle (First-Time Only)

Because production builds are lightweight, build the frontend UI once after cloning:

cd frontend
npm install
npm run build
cd ..

Option 1: Single-Click Desktop Launcher (Recommended)

Launch the entire backend + frontend studio with one command:

python kairi_desktop.py

This starts the local FastAPI server on port 8000 and opens Kairi Studio in your default browser.

---

Option 2: Manual Developer Setup

1. Backend Engine (FastAPI)

cd backend
python -m venv venv
# Windows: venv\Scripts\activate | macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

2. Frontend Studio (React + Vite)

In a new terminal window:

cd frontend
npm install
npm run dev

Navigate to http://localhost:5173 to explore your new autonomous workspace!

---

🔑 Configuration & BYOK

Click the ⚙️ Settings icon or the 🛡️ Security Shield in the bottom-left Activity Bar to configure your API keys:

• LLM Providers: Add your keys for Google Gemini, DeepSeek, Anthropic, or OpenAI.
• Search & News Engine: Optionally configure BRAVE_API_KEY, WORLD_NEWS_API_KEY, or NEWSDATA_API_KEY for advanced live data retrieval.

All credentials are saved via atomic file replacement directly to backend/storage/settings.json.

---

🛡️ Security & Privacy

Read our complete SECURITY.md policy for details on:

• Atomic Config Writes: Protection against power loss or file corruption.
• Supply-Chain Defense: Automatic --ignore-scripts flags on package installations.
• Zero Cloud Data Mining: Kairi never uploads your code or prompts to external telemetry services.
• No Arbitrary Memory Snooping: Strict dynamic scope-filtering guarantees the LLM cannot cross-reference or read stored personal KV memories without explicit topical relevance.

---

🤝 Contributing

We welcome contributions from developers worldwide! Check out our CONTRIBUTING.md to get started with pull requests, feature proposals, and bug reports.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

_{Built with ❤️ by the Kairi Autonomous AI Engineering Team}