{"id":50718878,"url":"https://github.com/danish-mar/kokomi","last_synced_at":"2026-06-09T22:00:15.550Z","repository":{"id":353652493,"uuid":"1204783234","full_name":"danish-mar/kokomi","owner":"danish-mar","description":"🌊 Kokomi AI: A premium multi-agent orchestration platform featuring isolated Docker sandboxing, Model Context Protocol (MCP) integration, real-time voice/chat capabilities, and automated workflow scheduling.","archived":false,"fork":false,"pushed_at":"2026-06-09T20:17:01.000Z","size":6405,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T21:20:49.550Z","etag":null,"topics":["agentic-workflows","ai-agents","apple-hig","fastapi","gemini","groq","langchain","mcp","python","qdrant","rag","whatsapp-bot"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danish-mar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-08T10:26:55.000Z","updated_at":"2026-06-09T20:17:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danish-mar/kokomi","commit_stats":null,"previous_names":["danish-mar/kokomi"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/danish-mar/kokomi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danish-mar%2Fkokomi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danish-mar%2Fkokomi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danish-mar%2Fkokomi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danish-mar%2Fkokomi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danish-mar","download_url":"https://codeload.github.com/danish-mar/kokomi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danish-mar%2Fkokomi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34127345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai-agents","apple-hig","fastapi","gemini","groq","langchain","mcp","python","qdrant","rag","whatsapp-bot"],"created_at":"2026-06-09T22:00:13.972Z","updated_at":"2026-06-09T22:00:15.538Z","avatar_url":"https://github.com/danish-mar.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌊 Kokomi AI: Divine Strategist OS\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Powered%20By-Groq-orange?style=for-the-badge\" alt=\"Groq\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Architecture-FastAPI-009688?style=for-the-badge\u0026logo=fastapi\" alt=\"FastAPI\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Database-Qdrant-red?style=for-the-badge\u0026logo=qdrant\" alt=\"Qdrant\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Integration-WhatsApp-25D366?style=for-the-badge\u0026logo=whatsapp\" alt=\"WhatsApp\"\u003e\n\u003c/p\u003e\n\nKokomi AI is a high-fidelity, autonomous agentic platform designed to orchestrate complex AI interactions across multiple channels. From deep, context-aware WhatsApp conversations to multi-agent task execution, Kokomi provides a sophisticated environment for digital personas to live, learn, and act.\n\n---\n\n## 🚀 Core Features \u0026 Minute Details\n\n### 👤 Advanced Character Engine\n\n- **Dynamic Personas**: Characters are defined by multi-layered system prompts that include core personality, speaking style, and goal-oriented behaviors.\n- **Case-Insensitive Multi-Agent Lookup**: Agents can refer to and deploy each other by name or ID (e.g., \"Kokomi\" vs \"kokomi\") without failures.\n- **Context Persistence**: Conversations are saved as structured JSON objects, preserving message history, role-play states, and internal AI thoughts.\n- **Autonomous Deployment**: A primary agent can trigger `deploy_agent` to create a child process for a secondary agent (like Nahida or Yae), who handles a sub-task and returns the result to the caller.\n\n### 📱 Seamless WhatsApp Bridge\n\n- **Direct REST Architecture**: Unlike discovery-heavy protocols, Kokomi uses a direct `httpx` based REST pipeline to communicate with a dedicated WhatsApp-MCP bridge, reducing latency to milliseconds.\n- **Thinking Mode (Reasoning Visibility)**:\n  - Captured `\u003cthought\u003e` and `\u003cthink\u003e` tags from models like Qwen-2.5-32B are processed separately.\n  - The bridge can be configured to either forward these thoughts to your phone or keep them purely in the WebUI.\n- **Secret Admin Commands**: Modify agent behavior on-the-fly directly from your WhatsApp chat:\n  - `thinking_show=true`: Enables transmission of the AI's internal reasoning process.\n  - `thinking_show=false`: Disables thoughts for a more immersion-focused conversation.\n- **Real-time Tool Feedback**: When an agent decides to use a tool or deploy a sub-agent, you get a \"confirmation message\" on WhatsApp immediately, so you aren't left waiting during long-running tasks.\n\n### 🛠️ Advanced Tool Orchestration\n\n- **Invisible Browser Redirection**:\n  - The AI can now trigger `redirect_url` to programmatically open links, movie players, or music streams in new browser tabs.\n  - **Auto-Execution**: If you ask it to \"play\" something, it won't just give you a link; it will immediately open the tab for you.\n- **Natural Language Tool Status**:\n  - Say goodbye to cryptic function names like `search_and_play`.\n  - The AI now generates human-readable status messages (e.g., _\"Searching and playing All of us are dead...\"_) which appear in the UI during execution.\n- **Custom MCP Server Icons**:\n  - Configure unique FontAwesome icons for each of your tool servers in the Integrations settings.\n  - The chat UI dynamically renders these icons in the tool pills, providing instant visual recognition.\n\n### 📊 Workflow Canvas \u0026 Visualization\n\n- **Live Mermaid.js Rendering**: Click on any workflow log in the WebUI to open a full-screen interactive graph.\n- **Traceability**: Each node represents a distinct action (User Message → Trigger → Deployment → Tool Call → Final Response).\n- **PNG Export**: High-resolution export of your AI's decision trees for auditing or archiving.\n\n### 📦 Premium Artifacts \u0026 Multimodal Attachments\n\n- **Inline Code Anchoring**: Artifacts are now dynamically injected into the conversation stream using a robust placeholder system, maintaining their exact context.\n- **Real-time Previews**: Artifact cards feature automatic syntax-highlighted previews and state-aware \"generating\" indicators.\n- **Multimodal File Engine (New)**:\n  - **Vision Support**: Native integration for image attachments (`.jpg`, `.png`, `.webp`). Encodes images into Base64 for vision-capable models like Gemini to analyze.\n  - **PDF Extraction**: Automated text extraction from all pages of uploaded PDFs using `pypdf`, enabling deep document reasoning.\n  - **Smart Previews**: Visual thumbnails for images and clean metadata chips for text/code files.\n  - **Paste-to-Attach**: Support for `Ctrl+V` pasting of screenshots and files directly into the chat bar.\n- **Cinematic UI DNA**: Seamless cross-fade transitions between the Welcome Screen and active chats, powered by Alpine.js for a fluid OS-like experience.\n\n### 📁 Multi-Agent Document \u0026 Slide Deck Exporter Suite (New)\n\n- **Universal Document Compiler**: Integrated tools (`pdf_export`, `docx_export`, `pptx_export`, `excel_export`) to compile rich research reports into publication-grade assets including PDFs, Word Documents, PowerPoint slide decks, and Excel spreadsheets.\n- **Apple HIG Inline Bold-Text Parser**: Converts raw double asterisks (`**bold**`) dynamically into native styled bold text runs inside PowerPoint and Word documents instead of dump-pasting raw markdown text decorators.\n- **Thread-Safe Workspace Isolation**: All compiled documents are saved dynamically inside the active workflow storage folder (`active_storage_dir`) for a clean project structure rather than general common uploads.\n- **Dynamic Allowed Tools UI**: Added a dynamically populated router system that decouples Alpine.js templates from hardcoded lists, automatically fetching active Model Context Protocol (MCP) server tools on load.\n\n### 🛒 Integrated App \u0026 Persona Store (New)\n\n- **One-Click Installation**: Discover, install, toggle, and uninstall advanced tools and characters directly from a remote GitHub app catalog.\n- **MCP App Bridge**: Stdio-based MCP server wrapper (`app/mcp_app_bridge.py`) that reads schemas from local app manifests (`manifest.json`) and exposes them dynamically to the LLM.\n- **Inline Confirmation Workflows**: Sleek, iOS-style bin-to-confirm pattern for clean uninstallation.\n- **Auto-Avatar Scraper**: Downloads profile images directly from remote repos, falling back seamlessly to visual glyphs if missing.\n\n\n### 📚 RAG \u0026 Knowledge Spaces\n\n- **Vector Orchestration**: Documents are automatically chunked and vectorized using `gemini-embedding-2` and stored in **Qdrant**.\n- **Smart Retrieval**: Characters proactively query their assigned \"Spaces\" using semantic search to provide grounded, fact-based answers.\n- **Multi-File Support**: Handles PDFs, Markdowns, TXT, and Word documents with automated extraction.\n\n### 🧠 Neural Memory Explorer \u0026 Long-Term Memory\n\n- **Perplexity-Style Context RAG**: Distills chats at the end of each conversation into concise, persistent \"Memory Atoms\" and vectorizes them into Qdrant.\n- **Sub-Second Parallel Vector Retrieval**: Concurrently queries memory points for all active group participants using `asyncio.gather` on session start.\n- **Gemini Embedding Cache**: Leverages a global model singleton cache to bypass cold-start model initialization latency, reducing RAG search times by 95%.\n- **Dedicated macOS-style Memory Explorer Page**: A full-featured `/memories` dashboard that displays stored memory points per character:\n  - **Live Text Search \u0026 Filtering**: Filters stored facts in real-time as you type.\n  - **Manual Fact Insertion Modal**: Feed custom memory atoms directly into Qdrant without waiting for conversational summarization.\n  - **Individual \u0026 Bulk Erase**: Forget specific details or completely wipe out a character's long-term memories in one click.\n  - **Incognito Memory Toggles**: Granular settings to disable/enable memory capabilities individually per AI character.\n\n---\n\n## 💻 Technical Architecture\n\n### Tech Stack Breakdown\n\n| Component         | Technology           | Detail                                                               |\n| :---------------- | :------------------- | :------------------------------------------------------------------- |\n| **Backend**       | FastAPI              | High-performance Python async framework.                             |\n| **Inference**     | Groq / LangChain     | Utilizing Qwen-2.5 and Llama 3 for ultra-fast reasoning.             |\n| **Database**      | SQLite + SQLAlchemy  | Async-native relational database (WAL mode) replacing blocking JSON. |\n| **Vector Store**  | Qdrant               | Used for RAG knowledge spaces and long-term memory retrieval.        |\n| **Frontend**      | Alpine.js + Tailwind | Lightweight, reactive UI with premium Apple-inspired styling.        |\n| **Deployment**    | Docker + UV          | Containerized environment with Astral's `uv` for 10x faster builds.  |\n| **Communication** | REST / SSE           | Real-time streaming to WebUI and RESTful bridge to WhatsApp.         |\n\n### Environment Configuration (`.env`)\n\n| Variable           | Description                       | Default                 |\n| :----------------- | :-------------------------------- | :---------------------- |\n| `GROQ_API_KEY`     | Your Groq Cloud API key.          | Required                |\n| `GOOGLE_API_KEY`   | Used for Gemini Embeddings.       | Required                |\n| `WHATSAPP_API_URL` | Endpoint for the WhatsApp bridge. | `http://localhost:3013` |\n| `DATA_DIR`         | Path to persistent storage.       | `./data`                |\n\n---\n\n## 📂 Project Structure\n\n```text\nkokomi/\n├── app/                  # Main Backend Logic\n│   ├── routers/          # API \u0026 Page Routes (Chat, WhatsApp, Prefs, etc.)\n│   ├── db.py             # SQLite Async Database \u0026 Table Definitions (New)\n│   ├── migration.py      # Automated Legacy JSON Migration Task (New)\n│   ├── llm.py            # LLM Factory \u0026 Model Providers\n│   ├── storage.py        # Persistence Layer (SQLite \u0026 JSON)\n│   └── mcp.py            # Tool \u0026 MCP Integration Logic\n├── templates/            # Premium WebUI (Jinja2)\n├── scripts/              # Developer CLI Utilities (New)\n│   └── migrate_json_to_sqlite.py\n├── data/                 # Persistent Data\n│   ├── database/         # SQLite DB files (kokomi.db)\n│   ├── json/             # User Preferences and backups\n│   └── ...\n├── Dockerfile            # Multi-stage optimized build\n└── docker-compose.yml    # Full stack (App + Qdrant) orchestration\n```\n\n---\n\n## 🛠️ Installation \u0026 Setup\n\n### Option 1: Docker (Fastest)\n\n```bash\ndocker compose up --build -d\n```\n\n\u003e [!NOTE]\n\u003e The default `docker-compose.yml` mounts the host Docker socket (`/var/run/docker.sock:/var/run/docker.sock`) into the application container. This socket access is strictly used to spin up sandboxed, isolated ephemeral containers for the code execution worker task, preventing any malicious or runaway scripts from affecting your host system.\n\n### Option 2: Local Development\n\n1. **Install uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n2. **Setup environment**: `uv sync`\n3. **Configure keys**: Create `.env` with your API keys.\n4. **Launch**: `uv run main.py`\n\n---\n\n## 🎨 Design Philosophy\n\nKokomi follows a \"Premium Aesthetic\" mantra. The UI is designed to feel like a high-end OS, utilizing:\n\n- **Glassmorphism**: 20px blur with 180% saturation for a frosted-glass feel.\n- **Squircle Geometry**: Continuous curves (not simple rounded corners) for all cards and modals.\n- **Dark Mode DNA**: Deep indigo and obsidian gradients tailored for professional desktop environments.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ci\u003e\"A strategist does not just predict the future—she prepares for it.\"\u003c/i\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanish-mar%2Fkokomi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanish-mar%2Fkokomi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanish-mar%2Fkokomi/lists"}