diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5c4a734 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 JorahOne, LLC + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 9f1272d..2b55ada 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ -# J1 Helpdesk Agent +# CommandDesk -**Self-hosted AI helpdesk with multi-platform ticketing, WhatsApp chat, email-to-ticket, knowledge base, Freshdesk MCP, and a plug-in agent architecture.** +> Self-hosted AI helpdesk agent with multi-platform ticketing and live cost tracking. -100% local and free. Compatible with Hermes Agent and the broader agent-skills ecosystem. +![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge) +![Status](https://img.shields.io/badge/status-active-%23FFB300?style=for-the-badge) +![Language](https://img.shields.io/badge/language-Python-informational?style=for-the-badge) +![Platform](https://img.shields.io/badge/platform-linux-informational?style=for-the-badge) -![Admin Dashboard](https://v3b.fal.media/files/b/0a9f159d/EQkpV4ZcXRrZthURYu5rA_Pz09bZEi.png) - -## Features +CommandDesk is an enterprise-grade, ops-precise platform built for VIDE and SMB operations. Run it solo. Deliver results. - ๐Ÿค– **AI Helpdesk Agent** โ€” Answers customer questions, searches tickets, updates status - ๐Ÿ“ฑ **WhatsApp Integration** โ€” Customers chat with your bot on WhatsApp @@ -53,254 +54,39 @@ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` -## WhatsApp Chat - -![WhatsApp Chat](https://v3b.fal.media/files/b/0a9f159f/nPYhqAeYe-YSlZYmuChyA_beG9ouMO.png) - -Customers can message your WhatsApp number and the AI agent will: - -1. **Greet** them with a welcome message and menu -2. **Search tickets** โ€” asks for email, shows their existing tickets -3. **Create tickets** โ€” collects details, creates via osTicket/Freshdesk -4. **Human takeover** โ€” queues them and notifies you to take over - -When a customer requests a human: -- ๐Ÿ”” You get a WhatsApp notification -- ๐Ÿค– Bot pauses for that customer -- ๐Ÿ‘ค You take over the conversation manually -- ๐Ÿ”„ Resume bot anytime via admin endpoint - -## Security Model - -| Layer | Protection | -|-------|-----------| -| **Rate Limiting** | 50 requests/session/hour (configurable) | -| **Session Duration** | 2-hour max per session | -| **Message Length** | 4000 chars max | -| **Content Filter** | Blocks password/credit_card/SSN in responses | -| **Audit Log** | All requests logged to PostgreSQL | -| **Network** | Internal services bound to 127.0.0.1 | -| **Admin Agent** | IP-whitelisted (Docker network only) | -| **Nginx** | Security headers, request size limits, rate zones | -| **WhatsApp** | HMAC signature verification | +| Layer | Stack | +|---|---| +| Runtime | Python | +| Environment | Linux | +| VCS | Git + GitHub | -**End users CANNOT create tickets via the AI agent.** Tickets are created via: -- Email (IMAP polling) -- osTicket web portal -- Freshdesk web portal -- WhatsApp (collected details โ†’ adapter) - -## Quick Start +## Quickstart ```bash -# 1. Clone git clone https://github.com/OneByJorah/CommandDesk.git cd CommandDesk - -# 2. Run setup -./scripts/setup.sh - -# 3. Configure -cp .env.example .env -# Edit .env with your IMAP credentials and ticket platform settings - -# 4. Start docker compose up -d - -# 5. Index knowledge base -docker compose exec helpdesk-agent python3 scripts/index_kb.py - -# 6. Open -# Dashboard: http://localhost/dashboard/ -# Helpdesk API: http://localhost/helpdesk/health -# Admin API: http://localhost/admin/health -# n8n: http://localhost:5678 -# Widget UI: http://localhost:8484 ``` +Verify at `http://`. ## Configuration -### Environment Variables - -See `.env.example` for all variables. Key ones: - -| Variable | Default | Description | -|----------|---------|-------------| -| `RATE_LIMIT_PER_SESSION` | 50 | Max requests per session | -| `MAX_SESSION_DURATION` | 7200 | Max session duration (seconds) | -| `IMAP_HOST` | โ€” | IMAP server for email-to-ticket | -| `OSTICKET_API_KEY` | โ€” | osTicket API key | -| `FRESHDESK_API_KEY` | โ€” | Freshdesk API key | -| `FRESHDESK_DOMAIN` | โ€” | Freshdesk subdomain | -| `WHATSAPP_TOKEN` | โ€” | WhatsApp Business API token | -| `WHATSAPP_PHONE_NUMBER_ID` | โ€” | WhatsApp phone number ID | -| `ADMIN_PHONE_NUMBER` | โ€” | Your WhatsApp for takeover notifications | -| `LLM_MODEL` | qwen2.5-7b-instruct | LLM model name | - -### WhatsApp Setup - -1. Set up WhatsApp Business API (via Meta or a provider like 360dialog) -2. Configure webhook URL: `https://your-server.com/webhook/whatsapp` -3. Set `WHATSAPP_TOKEN` and `WHATSAPP_PHONE_NUMBER_ID` in `.env` -4. Set `ADMIN_PHONE_NUMBER` to your personal WhatsApp -5. Start: `docker compose up -d whatsapp-webhook` - -### Freshdesk MCP - -The Freshdesk MCP server (NeuraLegion/freshdesk_mcp) provides 41 tools: - -- **Tickets**: list, view, create, search, update -- **Conversations**: list, reply, add notes -- **Contacts**: list, view, create, update, search -- **Companies**: list, view, create, update, search -- **Agents**: list, view, groups -- **KB**: categories, folders, articles, search -- **Time tracking**: list, create, toggle timer -- **Canned responses**: folders, list, view - -Configure in `config/mcp-config.yaml` with your Freshdesk domain and API key. - -### Plug-in with Main Hermes - -To connect this helpdesk agent to your main Hermes Agent: - -```yaml -# In your main Hermes config -bridges: - helpdesk-agent: - url: "http://helpdesk-agent:8080" - triggers: ["ticket", "helpdesk", "support", "my issue"] - admin-agent: - url: "http://admin-agent:8082" - triggers: ["admin", "manage tickets", "cost analytics"] -``` - -## Ticket Platforms +| Variable | Description | Required | Default | +|----------|-------------|----------|---------| +| (see Environment Variables) | โ€” | โ€” | โ€” | -| Platform | Status | Method | -|----------|--------|--------| -| osTicket | โœ… Full | REST API adapter | -| Freshdesk (free) | โœ… Full | MCP server (41 tools) | -| Zammad | โœ… Full | REST API adapter | -| Email (IMAP) | โœ… Full | IMAP polling โ†’ adapter | +For full details, see the in-repo [Environment Variables](#environment-variables) section. -## API Endpoints +## Roadmap -### Helpdesk Agent (port 8080) +- Feature parity with production requirements +- Observability and alerting expansions +- Community feedback integration -``` -POST /chat โ€” Send a message (session_id optional for new sessions) -GET /health โ€” Health check -GET /session/{id} โ€” Session info -``` - -### Admin Agent (port 8082) - -``` -POST /chat โ€” Full access to all tools -GET /health โ€” Health check -GET /tickets โ€” List all tickets (paginated) -GET /costs โ€” Cost analytics -GET /system โ€” System health -``` - -### WhatsApp Webhook (port 9090) - -``` -GET /webhook/whatsapp โ€” Webhook verification -POST /webhook/whatsapp โ€” Receive WhatsApp messages -POST /admin/takeover/{phone} โ€” Take over conversation -POST /admin/resume/{phone} โ€” Re-enable bot -GET /admin/queue โ€” View human support queue -``` - -## Adding Knowledge Base Articles - -1. Place `.md` or `.txt` files in `knowledge-base/` -2. Run: `docker compose exec helpdesk-agent python3 scripts/index_kb.py` -3. Agent will automatically find and cite them - -## Monitoring - -- **Admin Dashboard**: `http://localhost/dashboard/` -- **Tools UI / Widget Config**: `http://localhost:8484` -- **n8n Workflows**: `http://localhost:5678` -- **Health Monitor**: Metrics stored in Redis every 30s -- **Logs**: `docker compose logs -f helpdesk-agent` - -## Makefile Commands - -```bash -make start # Start all services -make stop # Stop all services -make logs # View all logs -make health # Check service health -make index-kb # Index knowledge base -make dev # Start in development mode -make shell # Open shell in agent container -make psql # Open PostgreSQL shell -make test-api # Test agent API -``` - -## Resource Requirements - -| Service | RAM Limit | CPU | -|---------|-----------|-----| -| llama.cpp (7B Q4) | 7GB | 6 cores | -| Helpdesk Agent | 2GB | 2 cores | -| Admin Agent | 2GB | 2 cores | -| ChromaDB | 2GB | 2 cores | -| PostgreSQL | 1GB | 1 core | -| Redis | 300MB | 1 core | -| WhatsApp Webhook | 500MB | 1 core | -| Others | ~2GB | shared | -| **Total** | **~16GB** | **6 cores** | - -## File Structure +## License -``` -CommandDesk/ -โ”œโ”€โ”€ docker-compose.yml # Full stack definition -โ”œโ”€โ”€ Dockerfile # Main agent container -โ”œโ”€โ”€ Dockerfile.whatsapp # WhatsApp webhook container -โ”œโ”€โ”€ Makefile # Common commands -โ”œโ”€โ”€ requirements.txt # Python dependencies -โ”œโ”€โ”€ .env.example # Environment template -โ”œโ”€โ”€ .github/workflows/ci.yml # CI pipeline -โ”œโ”€โ”€ config/ -โ”‚ โ”œโ”€โ”€ hermes-config.yaml # Helpdesk agent config -โ”‚ โ”œโ”€โ”€ admin-agent-config.yaml # Admin agent config -โ”‚ โ”œโ”€โ”€ agent-bridge.yaml # Delegation rules -โ”‚ โ”œโ”€โ”€ mcp-config.yaml # Freshdesk MCP config -โ”‚ โ”œโ”€โ”€ nginx.conf # Reverse proxy -โ”‚ โ”œโ”€โ”€ searxng-settings.yml # Search config -โ”‚ โ””โ”€โ”€ system-prompt.md # Agent persona -โ”œโ”€โ”€ ticket_platforms/ -โ”‚ โ”œโ”€โ”€ base.py # Abstract adapter -โ”‚ โ”œโ”€โ”€ registry.py # Platform registry -โ”‚ โ”œโ”€โ”€ email.py # Email-to-ticket -โ”‚ โ”œโ”€โ”€ osticket.py # osTicket adapter -โ”‚ โ”œโ”€โ”€ freshdesk.py # Freshdesk REST adapter -โ”‚ โ””โ”€โ”€ zammad.py # Zammad adapter -โ”œโ”€โ”€ scripts/ -โ”‚ โ”œโ”€โ”€ agent_server.py # FastAPI agent server -โ”‚ โ”œโ”€โ”€ whatsapp_webhook.py # WhatsApp integration -โ”‚ โ”œโ”€โ”€ rate_limiter.py # Rate limiting -โ”‚ โ”œโ”€โ”€ session_manager.py # Session management -โ”‚ โ”œโ”€โ”€ health_monitor.py # Health checks -โ”‚ โ”œโ”€โ”€ email_fetcher.py # IMAP polling -โ”‚ โ”œโ”€โ”€ index_kb.py # Knowledge base indexer -โ”‚ โ”œโ”€โ”€ init-db.sql # Database schema -โ”‚ โ””โ”€โ”€ setup.sh # Setup script -โ”œโ”€โ”€ admin/ -โ”‚ โ””โ”€โ”€ admin-dashboard.html # Monitoring dashboard -โ”œโ”€โ”€ tools-ui/ -โ”‚ โ”œโ”€โ”€ index.html # Widget config UI -โ”‚ โ””โ”€โ”€ Dockerfile # Nginx container -โ”œโ”€โ”€ knowledge-base/ # Place .md/.txt files here -โ””โ”€โ”€ workflows/ # n8n workflow JSONs -``` +MIT โ€” Copyright JorahOne, LLC. See [LICENSE](LICENSE) for details. -## License +--- -MIT +[OneByJorah](https://github.com/OneByJorah) ยท [JorahOne-Services](https://github.com/JorahOne-Services)