---

⚡ Quick Start

For Users (Windows, No Setup Required)

1. Download or clone Project Aiko to your machine.
2. Double-click LAUNCH_AIKO.bat.
3. Wait for her to wake up — the application bootstraps the virtual environment and launches the desktop interface automatically.

Once the dashboard appears, click the gear icon (Settings) in the top right:

• Persona — Customize personality traits, prompts, or dynamic mood baselines.
• AI Model — Seamlessly switch between local Ollama, OpenRouter, Gemini, OpenAI, Anthropic, or custom endpoints.
• Voice — Enable local Pocket-TTS speech, customize pitch, or adjust voice cloning profiles.
• Plugins — Toggle Discord, Telegram, Twitch, or PC Bridge integrations.

Hit Save & Apply — changes take effect instantly.

---

For Developers

# 1. Clone repository
git clone https://github.com/omax404/Project-Aiko.git
cd Project-Aiko

# 2. Setup Python environment (3.10–3.12)
python -m venv .venv
.\.venv\Scripts\activate  # On Windows (or source .venv/bin/activate on Unix)
pip install -r requirements.txt

# 3. Launch full stack
python launch.py

This starts the Neural Hub (port 8000), connects configured satellites (Discord/Telegram/Twitch), and opens the native Tauri desktop overlay.

To run or build the desktop UI separately:

cd aiko-app
npm install
npm run dev           # Vite web dev server
npm run tauri dev     # Native desktop window with Live2D
npm run build         # Production frontend bundle
npm test              # Run Vitest test suite

---

💎 What Makes Aiko Different

---

🧠 Core Systems

🧠 Brain & Reasoning

• ReAct agent loop with multi-step reasoning, self-correction, and tool execution.
• Multi-provider streaming across Ollama (gemma4:31b-cloud), OpenRouter, Gemini, OpenAI, Anthropic.
• Dual-pass generation: factual draft pass followed by personality overlay.
• Context-aware rolling conversation windows with automated summarization.

👁️ Multimodal Vision

• Non-blocking screen analysis via asyncio.to_thread — pixel diffing and PNG compression never stall the event loop.
• Local visual understanding via moondream:latest or MiniCPM-V.
• Discord image analysis, automated screen inspection, and coordinate grid targeting.

👂 Hearing & Audio

• Local Moonshine ASR (~200MB) with SpeechRecognition fallback.
• Client-side voice activity detection (VAD).
• Discord voice channel transcription.

🎙️ Voice Synthesis

• Pocket-TTS v2.1.0 (100% local, zero latency, zero cloud API fees).
• JIT speech stabilization to eliminate hallucinated phonemes.
• Autonomous action-text (*...*) stripping for natural spoken dialogue.

💾 Unified Memory

• Multi-tier memory architecture: episodic dialogue history + semantic vector RAG.
• Background consolidation cycles that distill daily conversations into long-term profile knowledge.
• Multi-process file locking (.lock) preventing concurrent corruption.

❤️ Emotional & Neuromodulator System

• Biologically inspired neuromodulator model: dopamine, serotonin, cortisol, adrenaline.
• 22+ emotion states mapped to dynamic Live2D avatar physics, expressions, and voice inflections.
• Affection and relationship score tracking (0–100%).

🔌 Plugins & Agency

• ElizaOS-inspired modular plugin manager with dynamic tool discovery.
• File system tools, clipboard management, process supervision, and system monitoring.
• Spotify bridge, Obsidian connector, LaTeX rendering, and image generation.
• Extensible GameBridge base class and GameManager for connecting to external game engines.

---

🔒 Zero-Trust Security & Tier-0 Architecture

Project Aiko is engineered to Tier-0 Production Grade security standards. Read the full specification in SECURITY.md.

🛡️ Human-in-the-Loop (HITL) Permission Gate

• Sensitive actions (OPEN, CLICK, TYPE, PRESS, EMAIL_SEND, and sensitive MCP tools) strictly require user confirmation.
• When triggered, Aiko sends a tool_request to the client dashboard. The action blocks until the user approves or rejects it in a modal dialog.
• Zero Admin Bypass: Server-side enforcement guarantees no prompt injection can bypass the confirmation gate, even with administrative tokens.

🔑 Local Zero-Trust Token Lifecycle

• Aiko issues rotating 24-hour HMAC-SHA256 JWT Bearer tokens to loopback clients.
• Remote IPs requesting tokens are rejected with 403 Forbidden.
• Sensitive credentials (OPENAI_API_KEY, DISCORD_TOKEN, etc.) are automatically masked (...***) on all settings endpoints.

📐 End-to-End Typed Contracts

• Client (Zod): Ingress events and WebSocket payloads are validated against strict Zod schemas (schemas.ts).
• Server (Pydantic v2): API routes and WebSocket frames are checked against Pydantic models (schemas.py).
• Ultra-Strict TypeScript: Desktop client compiles with "strict": true and "noUncheckedIndexedAccess": true.

⚡ Event-Loop Latency & Re-Render Isolation

• Backend Non-Blocking I/O: Screen diffing, PNG compression, and SQLite logging run in thread pools via asyncio.to_thread. Event-loop latency averages 7.60ms (15.63ms p95).
• Frontend Isolation: Message bubbles are wrapped in React.memo with granular Zustand selectors. Top-level window re-renders drop to 0 during voice playback.

---

📱 Platforms & Satellites

---

🧪 Testing & Verification

Project Aiko includes a dual-engine automated test suite covering 108 tests with 100% pass rate:

# 1. Run Python Backend Test Suite (98 tests)
pytest tests/

# 2. Run Frontend Vitest Suite (10 tests)
cd aiko-app
npm test

# 3. Verify Ultra-Strict TypeScript Compilation (0 errors)
cd aiko-app
npx tsc --noEmit

# 4. Verify Frontend Production Bundle
cd aiko-app
npm run build

---

🗂️ Project Structure

Project-Aiko/
├── core/                  # AI backend & orchestration engine
│   ├── api/               #   REST routes, WebSockets, Pydantic schemas, auth
│   ├── neural_hub.py      #   Master orchestrator server
│   ├── chat_engine.py     #   ReAct agent + multimodal LLM
│   ├── emotion_engine.py  #   Neuromodulator engine
│   ├── unified_memory.py  #   Episodic + semantic memory
│   ├── voice.py           #   Chunked Pocket-TTS engine
│   ├── vision.py          #   Non-blocking multimodal vision analysis
│   ├── hearing.py         #   Moonshine / Whisper STT
│   ├── persona.py         #   Character definitions & mood attractors
│   ├── game_bridge.py     #   Extensible GameBridge & GameManager
│   └── ...                #   Specialized agent subsystems
├── aiko-app/              # Tauri v2 + React 19 desktop client
│   ├── src/               #   React components, Live2D canvas, Zustand stores
│   ├── src/schemas.ts     #   Zod ingress validation contracts
│   ├── src/__tests__/     #   Vitest automated test suite
│   ├── src-tauri/         #   Rust native application backend
│   └── tsconfig.json      #   Ultra-strict TypeScript configuration
├── android/               # Native Android application (Kotlin + Jetpack Compose)
├── tests/                 # Backend automated test suite (Pytest)
├── directives/            # Autonomous agent skills & personas
├── docs/                  # Architecture & developer guides
├── stickers/              # Companion sticker graphic assets
├── launch.py              # Unified cross-platform launcher
├── requirements.txt       # Python dependencies
├── SECURITY.md            # Zero-Trust security specification
├── CONTRIBUTING.md        # Contribution guidelines
└── LICENSE                # MIT License

---

🛠️ Troubleshooting

---

🤝 Contributing

Contributions are welcomed with open arms! Please review CONTRIBUTING.md for code style, type strictness, and PR requirements.

---

📄 License

Distributed under the MIT License. Created by the Project Aiko Team.