{"id":51539392,"url":"https://github.com/chuprinadaria/jeeves","last_synced_at":"2026-07-09T12:00:51.180Z","repository":{"id":350439313,"uuid":"1206788218","full_name":"ChuprinaDaria/jeeves","owner":"ChuprinaDaria","description":"Self-hosted AI assistant platform. RAG, MCP tools, 5 messaging channels, admin dashboard. Django 5 + React 19. Open source. WIP — PRs welcome.","archived":false,"fork":false,"pushed_at":"2026-06-10T07:25:04.000Z","size":6061,"stargazers_count":1,"open_issues_count":23,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T08:22:17.678Z","etag":null,"topics":["ai","ai-assistant","chatbot","django","mcp","open-source","rag","react","self-hosted"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChuprinaDaria.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-10T08:55:06.000Z","updated_at":"2026-05-27T15:54:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ChuprinaDaria/jeeves","commit_stats":null,"previous_names":["chuprinadaria/jeeves"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChuprinaDaria/jeeves","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChuprinaDaria%2Fjeeves","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChuprinaDaria%2Fjeeves/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChuprinaDaria%2Fjeeves/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChuprinaDaria%2Fjeeves/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChuprinaDaria","download_url":"https://codeload.github.com/ChuprinaDaria/jeeves/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChuprinaDaria%2Fjeeves/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35298222,"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-07-09T02:00:07.329Z","response_time":57,"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":["ai","ai-assistant","chatbot","django","mcp","open-source","rag","react","self-hosted"],"created_at":"2026-07-09T12:00:49.929Z","updated_at":"2026-07-09T12:00:51.165Z","avatar_url":"https://github.com/ChuprinaDaria.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jeeves — Self-Hosted AI Assistant Platform\n\n[![Tests](https://github.com/ChuprinaDaria/jeeves/actions/workflows/main-tests.yml/badge.svg)](https://github.com/ChuprinaDaria/jeeves/actions/workflows/main-tests.yml)\n[![CodeQL](https://github.com/ChuprinaDaria/jeeves/actions/workflows/codeql.yml/badge.svg)](https://github.com/ChuprinaDaria/jeeves/actions/workflows/codeql.yml)\n[![Security Scan](https://github.com/ChuprinaDaria/jeeves/actions/workflows/security-scan.yml/badge.svg)](https://github.com/ChuprinaDaria/jeeves/actions/workflows/security-scan.yml)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ChuprinaDaria/jeeves/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ChuprinaDaria/jeeves)\n[![License: ELv2](https://img.shields.io/badge/License-ELv2-blue.svg)](LICENSE)\n\n\u003e Your own AI butler. Doesn't judge. Doesn't sleep. Occasionally hallucinates — but so does your best employee.\n\nMulti-tenant AI concierge with RAG knowledge base, MCP tools, 5 messaging channels, and a full admin dashboard. Built on Django 5 + React 19. Fully open source, self-hosted, no license keys, no paywalls.\n\n### Status\n\n**Work in progress.** The project is functional but not finished. Bugs exist, some features are rough around the edges, and the documentation may lie to you. If something breaks — congratulations, you found a feature request. PRs, issues, and constructive complaints are very welcome.\n\n---\n\n## What It Does\n\nJeeves is a white-label AI assistant platform. Deploy it on your server, connect a knowledge base, plug in messaging channels (WhatsApp, Telegram, Email, Web Widget, Voice), and get an AI concierge that answers questions from your docs, captures leads, and escalates to humans when needed.\n\n**Target audience:** agencies, service businesses, SaaS operators who need a customizable AI assistant without building one from scratch.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Tech Stack](#tech-stack)\n- [Project Structure](#project-structure)\n- [Quick Start](#quick-start)\n- [Dual-Agent Architecture](#dual-agent-architecture)\n- [MCP Tool Servers](#mcp-tool-servers)\n- [RAG Knowledge Base](#rag-knowledge-base)\n- [Messaging Channels](#messaging-channels)\n- [Admin Dashboard](#admin-dashboard)\n- [API Reference](#api-reference)\n- [Background Tasks](#background-tasks)\n- [Privacy \u0026 Data](#privacy--data)\n- [Security](#security)\n- [Environment Variables](#environment-variables)\n- [CI/CD](#cicd)\n- [Contributing](#contributing)\n\n---\n\n## Features\n\n### Core\n\n- **RAG Knowledge Base** — upload documents (PDF, DOCX, TXT, CSV, JSON, images), automatic chunking + embedding + vector search\n- **Dual-Agent System** — Assistant (full-power sandbox) + Consultant (customer-facing, lead-optimized)\n- **9 MCP Tool Servers** — RAG search, email, leads, escalation, memory, coaching, sales intel, Excel generation, sequential thinking\n- **5 Messaging Channels** — WhatsApp (Meta API + bridge), Telegram bot, Email (SMTP/IMAP), Web Widget (iframe), Voice/Telephony\n- **HITL Escalation** — route unanswered questions to live managers via Telegram, with timeout and auto-close\n- **Lead Capture** — automatic contact extraction, interest scoring (1-5), LLM-powered qualification\n- **Multi-Tenant Hierarchy** — Branch \u003e Specialization \u003e Client, each with isolated documents and embeddings\n- **Admin Dashboard** — full platform management with 37+ pages across owner admin and client portal\n\n### Additional\n\n- **Multi-Language UI** — 8 languages: English, German, French, Spanish, Italian, Dutch, Danish, Ukrainian\n- **Automatic Language Detection** — AI responds in the customer's language\n- **Chrome Extension** — embed assistant in any webpage, semantic search over page content, sales intelligence scraping\n- **Web Chat Widget** — embeddable iframe chat for client websites, configurable appearance (light/dark), custom CSS\n- **QR Code Generation** — dynamic QR codes per client for WhatsApp/Telegram linking\n- **Conversation Analytics** — top questions, sentiment detection, recent activity, statistics\n- **Conversation Ratings** — 1-5 star rating with automatic follow-up email on negative reviews\n- **Conversation Notes** — manual notes per conversation for manager reference\n- **Word Cloud** — trending terms from conversations\n- **Image Analysis** — upload images to chat for vision-powered analysis\n- **Custom Prompts** — per-client system prompt customization with prompt library and voting\n- **Knowledge Blocks** — organize documents into logical groups\n- **Web Parsing** — scrape URLs and ingest content into knowledge base\n- **Daily Digest** — automated email summary of last 24h conversations (17:00 Europe/Kyiv)\n- **Feature Flags** — per-client feature rollout (off / selected / all) with caching\n- **Auto-Reply Rules** — per-channel auto-reply configuration (WhatsApp, Telegram, Email)\n- **API Documentation** — auto-generated per client\n- **News Feed** — in-app news/updates\n- **Usage Tracking** — per-operation token + cost tracking, synced to external platform\n- **Pixel Dashboard** — pixel event tracking status\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Backend | Django 5, Django REST Framework, Python 3.12 |\n| Frontend | React 19, Vite 7, Tailwind CSS 3 |\n| Database | PostgreSQL 16 + pgvector |\n| Vector Search | Qdrant (primary), pgvector (fallback) |\n| Queue | Celery + Redis |\n| AI / LLM | OpenAI, Anthropic (Claude), Ollama (local), Kimi (Moonshot) |\n| Embeddings | OpenAI, Cohere, Hugging Face, Ollama (local) |\n| MCP | FastMCP 2.0 (stdio transport) |\n| Infrastructure | Docker Compose, Nginx, Gunicorn |\n| Auth | JWT (SimpleJWT), API Key, Client Token |\n| Encryption | Fernet (EncryptedJSONField for credentials) |\n| i18n | i18next (frontend), per-agent language config (backend) |\n| CI/CD | GitHub Actions |\n\n---\n\n## Project Structure\n\n```\n.\n├── backend/\n│   ├── Jeeves/                      # Django project root\n│   │   ├── accounts/                # Users (4 roles: admin, owner, manager, client), JWT auth\n│   │   ├── agents/                  # AgentConfig, AgentSession, AgentLog, MCP orchestrator\n│   │   ├── api/                     # Client-facing REST endpoints, bootstrap provisioning\n│   │   ├── branches/                # Org hierarchy Level 1 + documents + embeddings\n│   │   ├── specializations/         # Org hierarchy Level 2 + documents + embeddings\n│   │   ├── clients/                 # Tenants, channels (WA/TG/Email/Widget), HITL, leads, QR codes\n│   │   ├── concierge_platform/      # PlatformDefaults, FeatureFlag, SystemMessage\n│   │   ├── EmbeddingModel/          # AI model registry (EmbeddingModel, LLMProvider, ModelPair)\n│   │   ├── mcp_hub/                 # MCP server management + SSE streaming + tool execution\n│   │   ├── processing/              # Document parsing, chunking, embedding, UsageStats, Celery tasks\n│   │   ├── rag/                     # RAG engine: vector search, context builder, LLM client\n│   │   └── tools/                   # ToolCard catalog, ToolConnection, EdgeMiddleware, InstalledMCPServer\n│   ├── mcp_servers/                 # 9 standalone FastMCP servers (stdio)\n│   │   ├── rag/                     # Semantic search over knowledge base\n│   │   ├── escalation/              # HITL escalation to live managers\n│   │   ├── email/                   # Send/read/search emails (SMTP/IMAP)\n│   │   ├── leads/                   # Lead capture + qualification\n│   │   ├── memory/                  # Persistent conversational memory (Qdrant + Cohere)\n│   │   ├── coaching/                # AI coaching + gap analysis\n│   │   ├── sales_intel/             # Website scraping + tech stack detection\n│   │   ├── xlsx/                    # Excel generation with formulas (LibreOffice)\n│   │   └── common/                  # Shared Django ORM bootstrap\n│   ├── chrome_extension/            # Browser extension source (content + background scripts)\n│   ├── docker-compose.yml\n│   ├── Dockerfile\n│   └── requirements.txt\n├── frontend/\n│   ├── src/\n│   │   ├── pages/                   # 37+ pages (owner admin + client portal + setup wizard)\n│   │   ├── components/              # UI components (layout, forms, chat, integrations, tools)\n│   │   ├── api/                     # Axios clients (auth, owner, client, agent, tools, embedding)\n│   │   ├── context/                 # AuthContext, ThemeContext, BootstrapContext\n│   │   ├── locales/                 # 8 language translation files (en/de/fr/es/it/nl/da/uk)\n│   │   └── modules/                 # Experimental modules (pixel dashboard)\n│   ├── docker-compose.yml\n│   └── Dockerfile\n├── docs/                            # Development plans + specs\n├── CLAUDE.md                        # Instructions for Claude Code\n├── SETUP.md                         # Full installation guide\n└── .github/workflows/               # CI/CD (pytest + eslint + build)\n```\n\n---\n\n## Quick Start\n\nSee [SETUP.md](SETUP.md) for the full installation guide.\n\n```bash\n# 1. Clone and configure\ngit clone https://github.com/ChuprinaDaria/jeeves.git\ncd jeeves\nmake setup                # copies .env.example files\n# Edit backend/.env — set SECRET_KEY, FIELD_ENCRYPTION_KEY, OPENAI_API_KEY\n\n# 2. Start all services\nmake up                   # docker compose up -d\nmake migrate              # run database migrations\nmake superuser            # create admin account\n\n# 3. Open dashboard\n# http://localhost:3000\n```\n\nOr manually:\n\n```bash\ncp backend/.env.example backend/.env\ncp frontend/.env.example frontend/.env\ncd backend \u0026\u0026 docker compose up -d\ndocker compose exec web python manage.py migrate\ndocker compose exec web python manage.py createsuperuser\ncd ../frontend \u0026\u0026 docker compose up -d\n```\n\n### Docker Services\n\n| Service | Port | Description |\n|---------|------|-------------|\n| `postgres` | 5433 | PostgreSQL 16 + pgvector |\n| `redis` | 6380 | Cache + Celery broker |\n| `web` | 8000 | Django API (Gunicorn) |\n| `celery_worker` | — | Async task processing |\n| `celery_beat` | — | Scheduled tasks (digest, escalation timeouts, session cleanup) |\n| `qdrant` | 6333 | Vector search (optional, enabled via `USE_QDRANT`) |\n| `nginx` | 80 | Reverse proxy + static files |\n\n---\n\n## Dual-Agent Architecture\n\nJeeves runs two agent personas with different capabilities:\n\n### Assistant (Sandbox)\n\nFull-power agent for business owners. Available in the dashboard Sandbox.\n\n- Access to all MCP tools (RAG, email, leads, memory, coaching, sales intel, xlsx)\n- Business operations focus\n- Full conversation context\n\n### Consultant / Concierge (Messengers)\n\nCustomer-facing agent optimized for lead capture. Runs on WhatsApp, Telegram, Web Widget.\n\n- Limited tool scope (RAG, escalation, leads, memory)\n- Passive/Warm/Hot lead engagement strategies\n- Natural lead qualification without being pushy\n- Automatic escalation to human managers\n\n### Orchestrator Flow\n\n```\nUser message → Build system prompt + history\n             → LLM call with available MCP tools (OpenAI function schema)\n             → If tool call returned: execute via MCP → feed result back → repeat\n             → If final text: return response\n             → Log everything to AgentLog\n             → Max 10 iterations (prevents infinite loops)\n```\n\nAuto-injected parameters (hidden from LLM): `client_id`, `session_id`, `user_id`.\n\n### AgentConfig (per-client)\n\nEach client gets an `AgentConfig` with customizable settings:\n\n- `language` — conversation language\n- `temperature` — creativity (0-1)\n- `max_tokens` — response length limit\n- `system_prompt` — custom prompt (falls back to `PlatformDefaults`)\n- LLM provider + embedding model selection\n\n---\n\n## MCP Tool Servers\n\n9 FastMCP servers running as stdio subprocesses. Each bootstraps Django ORM through `mcp_servers.common.django_setup`.\n\n| Server | Scope | Tools | Description |\n|--------|-------|-------|-------------|\n| `rag` | assistant, manager | `search_knowledge_base` | Semantic search over the knowledge base (Qdrant or pgvector) |\n| `escalation` | assistant, manager | `escalate_to_manager`, `check_escalation_status` | Route unanswered questions to live managers via Telegram |\n| `email` | assistant | `send_email`, `read_emails`, `search_emails`, `analyze_emails` | Send/read/search emails via client SMTP/IMAP |\n| `leads` | manager, leads | `capture_lead`, `qualify_lead`, `update_lead` | Lead capture, qualification, interest scoring |\n| `memory` | assistant, manager | `save_memory`, `search_memory`, `clear_memory` | Persistent conversational memory (Qdrant + Cohere embeddings) |\n| `coaching` | assistant | `analyze_gaps`, `generate_coaching_plan` | AI coaching, gap analysis, skill development |\n| `sales_intel` | assistant | `scrape_website`, `detect_tech_stack`, `research_company` | Website scraping and company research |\n| `xlsx` | assistant | `generate_xlsx`, `add_worksheet`, `add_formula` | Excel generation with formulas (uses LibreOffice for recalc) |\n| `sequential-thinking` | assistant | `think` | Chain-of-thought reasoning (npm: `@modelcontextprotocol/server-sequential-thinking`) |\n\n**Scopes** control which tools are available to which agent:\n- `assistant` — full tools in Sandbox\n- `manager` — limited tools for customer-facing Consultant\n- `leads` — lead-specific tools only\n\nConfigured in `settings.py` under `MCP_SERVERS` and `MCP_TOOL_SCOPES`.\n\n---\n\n## RAG Knowledge Base\n\n### Document Processing Pipeline\n\n1. **Upload** — PDF, DOCX, TXT, CSV, JSON, JPG, PNG, GIF, WEBP\n2. **Parsing** — pdfplumber (PDF), python-docx (DOCX), standard parsers (CSV/JSON), Vision API (images)\n3. **Chunking** — recursive token-based splitter (default 512 tokens, 128 overlap), metadata preserved\n4. **Embedding** — via configurable provider (OpenAI, Cohere, Hugging Face, Ollama)\n5. **Storage** — Qdrant (primary) or pgvector (fallback)\n6. **Indexing** — Celery tasks with rate limiting (10/min)\n\n### Multi-Level Search\n\nDocuments are organized in a three-level hierarchy with weighted search:\n\n| Level | Weight | Description |\n|-------|--------|-------------|\n| Client | 0.8 | Client-specific documents (highest priority) |\n| Specialization | 0.5 | Domain-specific shared docs |\n| Branch | 0.3 | Regional shared docs |\n\n- Similarity threshold: 0.1 (configurable)\n- Max results: 5 per level\n- Context window: max 2000 tokens (fits 4096 token limit with prompt + response)\n- Optional Cohere reranking for better relevance\n\n### Vector Search Backends\n\n**Qdrant** (primary, `USE_QDRANT=true`):\n- Collection: `jeeves_embeddings`\n- Metadata filtering by client_id, level, etc.\n- Payload storage, snapshot backup\n\n**pgvector** (fallback):\n- Cosine distance similarity\n- IVFFlat or HNSW indexing\n\n### Knowledge Organization\n\n- **Knowledge Blocks** — group documents into logical collections\n- **Web Parsing** — scrape URLs and ingest content automatically\n- **Reindexing** — full reindex or incremental (new docs only)\n\n---\n\n## Messaging Channels\n\n### WhatsApp (Meta Business API)\n\n- **Webhook**: `POST /api/whatsapp/meta/webhook/`\n- **Security**: X-Hub-Signature-256 (HMAC-SHA256) verification\n- Message handling (text + media), conversation tracking\n- QR code linking to clients, auto-reply rules\n- Sentiment detection with negative rating escalation\n- Lead capture, RAG-powered responses, HITL escalation\n- Zero-touch configuration (`ClientZeroConfig`)\n- Legacy Twilio bridge support\n\n### Telegram\n\n- **Webhook**: `POST /api/clients/telegram/webhook/`\n- **Security**: X-Telegram-Bot-Api-Secret-Token verification\n- `/start` command (welcome + QR linking), `/start2` (custom linking)\n- Callback queries (inline button handling)\n- Manager replies via forwarding\n- Conversation history, sentiment analysis, lead capture\n\n### Email (SMTP/IMAP)\n\n- Send emails via client SMTP (encrypted credentials)\n- Read + search emails via IMAP\n- Analyze email sentiment/intent via LLM\n- Daily digest (automated at 17:00 Europe/Kyiv, or manual trigger)\n- Negative rating follow-up emails\n\n### Web Widget\n\n- **Script**: `/widget/chat.js` (inject into any page)\n- **Iframe**: `/widget/chat` (embedded chat)\n- Configurable domain restriction, light/dark mode, custom CSS\n- Conversation history (localStorage), image upload + analysis\n- Lead capture, RAG-powered responses\n\n### Voice / Telephony\n\n- Voice configuration per client\n- Multiple voice providers + voice selection\n- HITL escalation for complex calls\n- Endpoints: `/api/clients/telephony/*`\n\n---\n\n## Admin Dashboard\n\n### Owner Portal (`/owner/*`)\n\nPlatform-wide administration. Protected by `BootstrapGate` (checks setup completion).\n\n| Page | What it does |\n|------|-------------|\n| Dashboard | Platform statistics, overview |\n| Clients | CRUD clients, stats per client, API key generation |\n| Branches | Manage org hierarchy Level 1 |\n| Specializations | Manage org hierarchy Level 2 |\n| AI Providers \u003e LLM | Configure LLM providers (OpenAI, Anthropic, Ollama, Kimi) + test connections |\n| AI Providers \u003e Embeddings | Configure embedding models (OpenAI, Cohere, HF, Ollama) + test connections |\n| AI Providers \u003e Pairs | Assign LLM + embedding model pairs |\n| Tools | Tool catalog management, discovery, URL import |\n| MCP Servers | MCP server configuration |\n| Feature Flags | Per-client feature toggles (off / selected / all) |\n| System Messages | Multi-language system prompts (default, assistant, consultant) |\n| Settings | Platform defaults (temperature, max_tokens, language, etc.) |\n| Setup Wizard | First-time setup: owner account creation |\n\n### Client Portal (`/l/:tag/*`)\n\nPer-client management. Authenticated via `X-Client-Token` header.\n\n| Page | What it does |\n|------|-------------|\n| Dashboard | Stats, top questions, recent activity, web conversations |\n| History | Conversation browser with date/channel filter, search, sentiment |\n| Tools | Connected tools, flow canvas visual editor, edge middleware |\n| Integrations | WhatsApp QR, Telegram token, Email SMTP config, Widget config |\n| Leads | Lead list, detail view, scoring, qualification status |\n| Training | Prompt library, create/edit prompts, vote on suggestions |\n| Sandbox | Test RAG queries, upload files, image analysis, live chat |\n| Settings | Language, theme, profile, logo upload |\n\n---\n\n## API Reference\n\nFull documentation: [`backend/docs/API_DOCUMENTATION.md`](backend/docs/API_DOCUMENTATION.md)\n\n### Authentication Modes\n\n| Mode | Header | Used by |\n|------|--------|---------|\n| JWT Bearer | `Authorization: Bearer \u003ctoken\u003e` | Owner/Admin dashboard |\n| Client Token | `X-Client-Token: \u003ctag\u003e` | Client portal, web widget |\n| API Key | `X-API-Key: \u003ckey\u003e` | External API clients, webhooks |\n\n### Key Endpoints\n\n#### Auth\n- `POST /api/accounts/register/` — register user\n- `POST /api/accounts/login/` — JWT login\n- `POST /api/accounts/refresh/` — refresh JWT\n- `GET /api/accounts/me/` — current user profile\n\n#### RAG \u0026 Chat\n- `POST /api/rag/query/` — query knowledge base\n- `POST /api/rag/chat/` — RAG chat (supports image analysis)\n- `POST /api/mcp/chat/` — MCP chat (SSE streaming, full agent orchestration)\n- `POST /api/rag/upload/` — upload document\n\n#### Client Management\n- `GET /api/clients/conversations/` — list conversations\n- `GET /api/clients/conversations/statistics/` — aggregated stats\n- `GET /api/clients/top-questions/` — most asked questions\n- `GET /api/clients/leads/` — list captured leads\n- `GET /api/clients/documents/` — list documents\n- `GET /api/clients/knowledge-blocks/` — list knowledge blocks\n- `POST /api/clients/reports/daily-digest/send/` — trigger daily digest\n\n#### Owner Admin\n- `GET /api/owner/dashboard/stats/` — platform statistics\n- `CRUD /api/owner/clients/` — manage clients\n- `CRUD /api/owner/branches/` — manage branches\n- `CRUD /api/owner/specializations/` — manage specializations\n- `CRUD /api/owner/ai-providers/llm/` — manage LLM providers\n- `CRUD /api/owner/ai-providers/embeddings/` — manage embedding models\n- `CRUD /api/owner/ai-providers/pairs/` — manage model pairs\n- `CRUD /api/owner/tools/` — manage tool catalog\n- `CRUD /api/owner/feature-flags/` — manage feature flags\n- `CRUD /api/owner/system-messages/` — manage system messages\n- `GET|PUT /api/owner/settings/defaults/` — platform defaults\n\n#### Channel Config\n- `GET|POST|PATCH /api/clients/whatsapp/meta/config/` — WhatsApp Meta config\n- `GET|POST|PATCH /api/clients/telegram/config/` — Telegram config\n- `GET|POST /api/clients/email-smtp/config/` — Email SMTP config\n- `GET|POST|PATCH /api/clients/web-widget/config/` — Web Widget config\n- `GET|POST /api/clients/hitl/config/` — HITL escalation config\n- `CRUD /api/clients/telephony/` — voice/telephony config\n- `GET|PUT /api/clients/channel-auto-reply/\u003cchannel\u003e/` — auto-reply rules\n\n#### Tools\n- `GET /api/tools/catalog/` — tool catalog\n- `POST /api/tools/\u003cslug\u003e/connect/` — connect tool\n- `POST /api/tools/\u003cslug\u003e/disconnect/` — disconnect tool\n- `GET /api/tools/my/` — connected tools\n- `CRUD /api/tools/flow/connections/` — flow canvas connections\n- `CRUD /api/tools/flow/edges/\u003cconn_id\u003e/middleware/` — edge middleware\n\n#### Setup\n- `POST /api/setup/owner/` — create first owner account\n- `POST /api/setup/complete/` — mark setup complete\n\n200+ total endpoints. See [`backend/docs/API_DOCUMENTATION.md`](backend/docs/API_DOCUMENTATION.md) for the complete list.\n\n---\n\n## Background Tasks\n\n### Periodic (Celery Beat)\n\n| Task | Schedule | Description |\n|------|----------|-------------|\n| `check_inactive_chat_sessions` | Every 60 seconds | Detect + clean up idle conversations |\n| `send_daily_digest` | Daily at 17:00 (Europe/Kyiv) | Email summary of last 24h to client contacts |\n| `check_escalation_timeouts` | Every 5 minutes | Auto-close expired HITL escalations |\n\n### Document Processing (Celery Worker)\n\n| Task | Description |\n|------|-------------|\n| `process_client_document` | Parse + chunk + embed client document |\n| `process_branch_document` | Parse + chunk + embed branch document |\n| `process_specialization_document` | Parse + chunk + embed specialization document |\n\nRate limited: 10 tasks/minute per model type. Cost tracked in `UsageStats`.\n\n---\n\n## Privacy \u0026 Data\n\nJeeves is designed for **complete data sovereignty**. When you self-host Jeeves, your data stays on your server — period.\n\n- **Zero telemetry** — no analytics, no tracking pixels, no phone-home calls, no usage reporting\n- **Zero external dependencies at runtime** — the only outbound connections are to services **you** explicitly configure (your LLM provider, your email server, your messaging channels)\n- **No license validation** — no activation servers, no periodic checks, no \"calling home\"\n- **Full source audit** — the codebase is open. Search for `fetch`, `requests.post`, `axios` — every external call is user-configured\n- **Automated security scanning** — CodeQL (SAST) and Dependabot run on every PR via GitHub Actions\n\nYour AI provider (OpenAI, Anthropic, Cohere, etc.) will receive the queries and documents you send to their API — that's inherent to using any LLM. If this concerns you, use a local model via Ollama (fully supported).\n\n---\n\n## Security\n\n### Authentication\n\n- **JWT** — access (24h) + refresh (7d) tokens with rotation\n- **API Key** — per-client `ClientAPIKey` model, `X-API-Key` header\n- **Client Token** — tag-based auth for portal + widget\n\n### Role-Based Access Control\n\n4 roles with view-level permission checks:\n\n| Role | Access |\n|------|--------|\n| `ADMIN` | Full platform access |\n| `OWNER` | Platform admin dashboard, all clients |\n| `MANAGER` | HITL escalation, assigned clients |\n| `CLIENT` | Own portal only |\n\n### Webhook Security\n\n- **WhatsApp Meta**: X-Hub-Signature-256 (HMAC-SHA256 with `META_APP_SECRET`)\n- **Telegram**: X-Telegram-Bot-Api-Secret-Token header\n- **Bootstrap**: X-Bootstrap-Signature (HMAC-SHA256, 5-minute validity)\n\n### Data Protection\n\n- **EncryptedJSONField** — Fernet encryption for tool credentials, API configs, SMTP passwords\n- **Field encryption key** — `FIELD_ENCRYPTION_KEY` env var (base64-encoded Fernet key)\n- `.env` files never committed to git\n\n---\n\n## Environment Variables\n\n### Required\n\n| Variable | Description |\n|----------|------------|\n| `SECRET_KEY` | Django secret key (generate: `python -c \"import secrets; print(secrets.token_urlsafe(50))\"`) |\n| `FIELD_ENCRYPTION_KEY` | Fernet key for credential encryption (generate: `python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"`) |\n| `OPENAI_API_KEY` | OpenAI API key (or configure another LLM provider) |\n\n### Database\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DB_NAME` | `admin_db` | PostgreSQL database name |\n| `DB_USER` | `admin_user` | Database user |\n| `DB_PASS` | — | Database password |\n| `DB_HOST` | `postgres` | Database host |\n| `DB_PORT` | `5432` | Database port |\n\n### AI Providers\n\n| Variable | Description |\n|----------|------------|\n| `ANTHROPIC_API_KEY` | Anthropic Claude API |\n| `COHERE_API_KEY` | Cohere embeddings + reranking |\n| `HUGGINGFACE_API_KEY` | Hugging Face models |\n| `KIMI_API_KEY` | Kimi (Moonshot) API |\n\n### Vector Search\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `USE_QDRANT` | `True` | Enable Qdrant vector search |\n| `QDRANT_HOST` | `qdrant` | Qdrant hostname |\n| `QDRANT_COLLECTION` | `jeeves_embeddings` | Qdrant collection name |\n| `QDRANT_PORT` | `6333` | Qdrant port |\n\n### Security\n\n| Variable | Description |\n|----------|------------|\n| `FIELD_ENCRYPTION_KEY` | Base64 Fernet key for credential encryption |\n| `BOOTSTRAP_SECRET` | HMAC secret for bootstrap webhook verification |\n\n### Messaging\n\n| Variable | Description |\n|----------|------------|\n| `META_WABA_ID` | WhatsApp Business Account ID |\n| `META_APP_ID` | Meta app ID |\n| `META_APP_SECRET` | Meta app secret (webhook signature verification) |\n| `META_ACCESS_TOKEN` | Meta access token |\n| `TWILIO_ACCOUNT_SID` | Twilio SID (legacy WhatsApp) |\n| `TWILIO_AUTH_TOKEN` | Twilio auth token |\n\n### Infrastructure\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CELERY_BROKER_URL` | `redis://redis:6379/0` | Celery broker |\n| `CELERY_RESULT_BACKEND` | `redis://redis:6379/0` | Celery results |\n| `CORS_ALLOWED_ORIGINS` | — | Frontend origins (comma-separated) |\n| `CSRF_TRUSTED_ORIGINS` | — | Trusted origins for CSRF |\n| `ALLOWED_HOSTS` | `localhost,127.0.0.1,web,nginx` | Django allowed hosts |\n| `DEBUG` | `True` | Debug mode (set `False` in production) |\n\n---\n\n## CI/CD\n\nGitHub Actions (`.github/workflows/main-tests.yml`):\n\n- **Backend**: pytest with PostgreSQL (pgvector) + Redis services\n- **Frontend**: ESLint + production build\n- Runs on push/PR to `main`\n\n### Production Checklist\n\n- [ ] Set `DEBUG=False`\n- [ ] Generate fresh `SECRET_KEY`\n- [ ] Configure `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`, `CORS_ALLOWED_ORIGINS`\n- [ ] Set up HTTPS (Nginx + Let's Encrypt or Caddy)\n- [ ] Enable automated PostgreSQL backups\n- [ ] Generate `FIELD_ENCRYPTION_KEY`\n- [ ] Rotate all API keys\n\n---\n\n## LLM Providers\n\n### Supported\n\n| Provider | Type | Default Model |\n|----------|------|---------------|\n| OpenAI | `openai` | gpt-4o-mini |\n| Anthropic | `anthropic` | Claude family |\n| Ollama (main) | `ollama_main` | qwen2.5:7b |\n| Ollama (light) | `ollama_light` | qwen2.5:1.5b |\n| Kimi (Moonshot) | `kimi` | Advanced reasoning |\n\n### Configuration Priority\n\n1. `client.llm_provider_model` (FK to LLMProvider) — preferred\n2. `client.llm_provider` + `client.llm_model_name` — legacy\n3. `LLM_CONFIG` default — fallback\n\n### Embedding Models\n\n| Provider | Models |\n|----------|--------|\n| OpenAI | text-embedding-3-small, text-embedding-3-large |\n| Ollama | bge-m3, nomic-embed-text |\n| Hugging Face | Via transformers |\n| Cohere | embed-multilingual-v3.0 (reranking support) |\n\n---\n\n## Contributing\n\nJeeves is free forever and actively developed. Pull requests, bug reports, and feature ideas are welcome.\n\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to set up, code style, PR process\n- **[SETUP.md](SETUP.md)** — local development setup\n- **[SECURITY.md](SECURITY.md)** — reporting vulnerabilities\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** — community standards\n\nFound a bug? [Open an issue.](https://github.com/ChuprinaDaria/jeeves/issues)\n\n---\n\n## License\n\nElastic License 2.0 — See [LICENSE](LICENSE) for full terms.\n\n**In short:**\n- **Free forever** — use, deploy, modify for yourself or your organization\n- **Don't sell it** — you may not provide Jeeves as a hosted/managed service to third parties\n- **Keep the branding** — the \"Jeeves\" name and attribution footer must remain intact\n\nJeeves — by Daria Chuprina \u0026 open-source community. Forever free.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchuprinadaria%2Fjeeves","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchuprinadaria%2Fjeeves","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchuprinadaria%2Fjeeves/lists"}