{"id":"685c9854-1d3e-4efa-9116-e423bd170b06","slug":"zauq","kind":"mcp","name":"Zauq","summary":"Agentic AI Discord assistant with MCP tool integration, multi-provider LLM routing, live web research, semantic memory, and optional sandboxed code execution. Built with FastAPI & discord.py.","owner":"Muhammad-Hassan12","repoUrl":"https://github.com/Muhammad-Hassan12/Zauq","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-01T16:26:23.000Z","addedAt":"2026-10-21T06:31:06.551Z","logoUrl":"https://avatars.githubusercontent.com/u/118466320?u=15af0a4eab200d8eff28dc5e3d136fd37be4222a&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","memory-knowledge","search"],"tags":["ai-agents","discord-py","docker-sandbox","fastapi","llm","llm-router","open-source","pgvector"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T00:37:33.497Z","sample":false,"url":"https://conduits.dev/tools/zauq","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n<img src=\"assets/Zauq_Logo.png\" alt=\"Zauq logo\" width=\"180\" />\n\n# Zauq (ذوق) v4\n\nAn MCP-powered agentic AI assistant for Discord with web research, coding tools, sandboxed execution, semantic memory, multi-provider LLM routing, and extensible tool use.\n\n[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12-3776AB?logo=python&logoColor=white)](#quick-start)\n[![FastAPI](https://img.shields.io/badge/Backend-FastAPI-009688?logo=fastapi&logoColor=white)](backend/main.py)\n[![Discord](https://img.shields.io/badge/Client-discord.py-5865F2?logo=discord&logoColor=white)](bot/client.py)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE)\n\nSelectable models · Bounded agents · Web research · Docker sandbox · Scoped MCP\n\nCreated by **Syed Muhammad Hassan / AgenticEra Systems**. [Apache 2.0](LICENSE).\n\n</div>\n\n<div align=\"center\">\n    \n[Features](#features) · [Architecture](#architecture) · [Models](#models-and-provider-routing) · [Quick start](#quick-start) · [Commands](#commands-and-examples) · [Deployment](DEPLOYMENT.md) · [Documentation](#documentation)\n\n</div>\n\n## Overview\n\n**Zauq (ذوق)** brings conversational AI and practical tools into Discord. Members can ask questions through mentions, replies, DMs or threads, attach documents and media, research current information, generate files and run permitted code snippets. Operators choose model providers, server preferences and the tools available to each community.\n\nv4 introduces a bounded agent runtime: a supported model can request selected tools, inspect their results and produce an answer within enforced budgets. Web research uses Serper, code runs through a separate Docker runner, and external integrations use operator-configured MCP servers. Mutating tools require signed, expiring approval before execution.\n\nThe project keeps the existing memory, lore, moderation, voice, media, XP and reminder features. Its deployment separates the Discord client, FastAPI backend and sandbox runner, without requiring Redis, Celery, a browser runtime or a local model. **Agent and MCP master flags default to off**, allowing operators to introduce them gradually.\n\n## Features\n\n| Area | Shipped behavior |\n| --- | --- |\n| Chat | Mentions, replies, DMs and thread conversations; Dev and Hangout personas |\n| Models | Direct Gemini, Claude, Qwen, DeepSeek and DigitalOcean clients; optional Ollama and Kaggle workers |\n| Research | Serper search with six categories; public-page fetching; bounded multi-query deep research |\n| Agent | Selected tools only, validated JSON arguments, resource budgets, duplicate-call detection and total deadlines |\n| Sandbox | Python, JavaScript and Bash; separate runner; no network in execution containers; explicit channel permissions |\n| MCP | Operator-configured stdio and Streamable HTTP servers; explicit tool grants, risk classifications and guild scope |\n| Approvals | Signed, expiring previews; initiating user or Discord administrator approval; atomic single-use execution claim |\n| Memory | Optional Supabase episodic facts and lore retrieval, with embeddings and decay |\n| Community | XP/rank, reminders, moderation, trivia, summarization, exports, memes, images and TTS |\n\nThinking, images, audio and native tool support depend on the selected model **and** its transport. Unsupported media may use Gemini OCR or audio transcription, so a local text model does not guarantee entirely local processing. Provider fallback is disclosed in response metadata. Model autocomplete is a suggestion list, not an account availability probe.\n\n### Conversation, memory and files\n\nDev and Hangout personas support technical and conversational use. Channel preferences inherit server defaults; optional Supabase storage adds episodic user facts, embeddings and server lore retrieval. Documents, images and voice notes can contribute context, and file-generation commands return sanitized downloads. Parsing and context size are bounded, so document ingestion is not guaranteed to be lossless.\n\n### Research and code verification\n\nQuick and deep research share one retrieval service, with category filters, bounded page fetching and source attribution. Failed pages are labeled as search snippets. Python, JavaScript and Bash snippets run in execution containers with networking disabled, resource limits and read-only code mounts. Automatic testing supports `off`, `auto` and `always`, independently of channel execution permission.\n\n### External tools with reviewable actions\n\nMCP supports stdio and Streamable HTTP. Operators configure servers, tool grants, risk classifications and guild access; chat users cannot install arbitrary servers. Write/destructive calls produce an argument preview with **Approve** and **Deny** buttons. Single-use claims prevent repeated clicks from starting the same action twice.\n\n### Community operations and observability\n\nThe command suite includes moderation, XP/rank, reminders, trivia, exports, summarization, TTS, images and memes. `/stats` reports provider volume, latency, tool counters, reported token usage and optional model-cost estimates. Durable metrics survive process restarts when Supabase is configured; the local fallback identifies its limited reporting window.\n\n## Architecture\n\n```mermaid\nflowchart TD\n    Discord[Discord: messages, commands, attachments] --> Bot[Bot: delivery and approval UI]\n    Bot --> Backend[FastAPI: context and chat orchestration]\n    Backend --> Models[Model router and provider adapters]\n    Backend --> Research[Serper search and safe page fetching]\n    Backend --> Agent[Bounded agent runtime]\n    Agent --> Models\n    Agent --> Tools[Tool executor: schema and policy checks]\n    Tools --> MCP[Operator-configured MCP servers]\n    Tools --> Runner[Separate sandbox runner]\n    Runner --> Docker[Docker execution containers]\n    Backend --> Database[Optional Supabase and pgvector]\n```\n\nThe backend resolves profiles and context, performs requested retrieval, then uses direct generation or the agent runtime according to the model and effective rollout settings. The executor validates tool arguments and permissions before dispatch. Mutating tools are staged for approval; approved execution rechecks current policy.\n\nOnly the runner receives Docker access in Compose. It transfers code through an explicit shared daemon-host spool. Component ownership, native provider continuation and policy resolution are documented in [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## Models and provider routing\n\n| Tier | Provider IDs | Configuration |\n| --- | --- | --- |\n| **1 — Cloud APIs** | `gemini`, `digitalocean`, `anthropic`, `qwen`, `deepseek` | Credentials for the selected provider; Qwen also needs its regional/workspace endpoint |\n| **2 — Local model server** | `ollama` | A reachable Ollama endpoint and an installed model |\n| **3 — GPU worker** | `kaggle` | A reachable configured worker/tunnel |\n\nSelection follows **channel override → server default → system default**. `/model set` changes the channel or server selection; `/model status` explains the effective choice. The provider catalog is centralized in [backend/models/catalog.py](backend/models/catalog.py), with model-specific behavior in [capabilities.py](backend/models/capabilities.py).\n\nNative tools, thinking and media support vary by model. Models without native tools retain direct generation and deterministic retrieval. Custom model IDs receive basic format validation; the provider checks actual account availability when called. See [model guidance](USER_GUIDE.md#model-and-mode-controls) for lifecycle caveats and fallback behavior.\n\n## Quick start\n\n### 1. Prepare the environment\n\nUse Python **3.11 or 3.12**, Git and a virtual environment. Basic Discord chat needs a bot token, an internal API key and access to a configured model provider. Supabase adds persistent profiles/memory; Serper adds search; Docker and the separate runner add code execution.\n\n```bash\ngit clone https://github.com/Muhammad-Hassan12/Zauq.git\ncd Zauq\npython3 -m venv venv\n. venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\n```\n\n### 2. Configure credentials\n\nGenerate an internal service key:\n\n```bash\nopenssl rand -hex 32\n```\n\nSet `INTERNAL_API_KEY` to that value in `.env`, add `DISCORD_BOT_TOKEN`, and configure the credentials/endpoint for your chosen provider. Gemini is the system default; another provider can be selected through the model controls after persistent settings are configured. Optional credentials may remain blank.\n\nFor persistent profiles, memory, approvals and metrics, configure Supabase using the fresh schema or ordered upgrades in [DEPLOYMENT.md](DEPLOYMENT.md#database-setup). Use the backend service-role key. Keep `.env` and the operator MCP config out of version control.\n\n### 3. Configure Discord\n\nCreate/configure your bot in the Discord Developer Portal, enable the **Message Content Intent**, and invite it with the `bot` and `applications.commands` scopes. Grant permissions for the features you enable, such as reading/sending messages, attaching files, moderation or voice access. The client requests message-content access for conversational behavior.\n\nThe bot syncs application commands on startup. The owner-only `!sync` command can refresh registration when needed.\n\n### 4. Start the services\n\nRun the backend and bot in separate terminals, with the virtual environment active in each:\n\n```bash\n# Terminal 1\npython -m uvicorn backend.main:app --host 127.0.0.1 --port 8002\n```\n\n```bash\n# Terminal 2\npython -m bot.client\n```\n\nCheck backend liveness, then use `/info` and `/model status` in Discord:\n\n```bash\ncurl --fail http://127.0.0.1:8002/health\n```\n\nMention the bot or reply to one of its messages to begin a conversation. A successful health check confirms backend liveness; the Discord/model checks exercise more of the configured setup.\n\n### 5. Add optional execution and deployment\n\nFor local sandbox execution, run the separate runner under a Docker-capable identity and set `SANDBOX_RUNNER_URL=http://127.0.0.1:8001`. The backend process should not need Docker privileges. Execution images must be pre-pulled; requests never pull them automatically.\n\nFor Docker Compose or supervised VPS processes, follow [DEPLOYMENT.md](DEPLOYMENT.md). Compose supplies the shared host spool, matching service keys and service addresses; it publishes the backend on loopback and keeps the runner inside its network. Enable agent/MCP tools first in a restricted test channel using the documented rollout procedure.\n\n## Configuration\n\nThe complete template is [.env.example](.env.example). Important settings are:\n\n| Setting | Purpose |\n| --- | --- |\n| `DISCORD_BOT_TOKEN` | Discord client authentication |\n| `INTERNAL_API_KEY` | Shared bot/backend/runner authentication and pending-action signing |\n| `GEMINI_API_KEY`, `DO_MODEL_ACCESS_KEY`, `ANTHROPIC_API_KEY`, `QWEN_API_KEY`, `DEEPSEEK_API_KEY` | Configure the providers you use |\n| `SUPABASE_URL`, `SUPABASE_KEY` | Persistent profiles, memory, approvals and telemetry |\n| `SERPER_API_KEY` | Search credentials; Serper is the implemented search provider |\n| `AGENT_RUNTIME_ENABLED`, `MCP_ENABLED` | Master switches; both default to `false` |\n| `AGENT_ALLOWED_GUILD_IDS`, `AGENT_ALLOWED_CHANNEL_IDS` | Operator restrictions on agent rollout |\n| `MCP_ALLOWED_GUILD_IDS`, `MCP_ALLOWED_CHANNEL_IDS` | Operator restrictions on MCP rollout; server tool scopes also apply |\n| `SANDBOX_RUNNER_URL` | Separate execution service endpoint |\n| `AUTO_CODE_TEST_DEFAULT` | Default auto-test policy: `off`, `auto` or `always` |\n| `MODEL_PRICING_JSON` | Optional per-provider/model input and output rates for cost estimates |\n\nSaved channel/server preferences cannot bypass a disabled master flag or operator allowlist. MCP server scope and tool grants add further restrictions. See [scoped rollout](DEPLOYMENT.md#scoped-rollout) and the disabled templates in [config/mcp_servers.example.json](config/mcp_servers.example.json).\n\nFor an isolated local backend experiment, `DEVELOPMENT_MODE=true` explicitly permits a blank internal key. Keep development bypass off for deployment; production startup requires a key.\n\n## Commands and examples\n\n| Command family | Purpose |\n| --- | --- |\n| `/info`, `/model status`, `/model set`, `/model reset` | Inspect the engine and choose channel/server models |\n| `/mode`, `/mode_reset`, `/thinking` | Set persona and supported native-reasoning preferences |\n| `/search` | Quick/deep research with `all`, `github`, `arxiv`, `docs`, `wikipedia` or `news` categories |\n| `/run`, `/sandbox status`, `/sandbox auto_mode` | Manual execution and automatic testing policy |\n| `/agent status`, `/agent tools`, `/agent enable` | Runtime status, registry and scoped preference |\n| `/mcp status`, `/mcp tools` | External server health and guild-visible tools |\n| `/file generate`, `/create_file`, `/export`, `/summarize` | Generate downloads, export or summarize context |\n| `/remember`, `/ingest_repo`, `/github pr`, `/github issue` | Lore ingestion and GitHub item summaries |\n| `/voice`, `/tts`, `/image`, `/meme`, `/trivia` | Voice, media and community activities |\n| `/remind`, `/rank`, `/leaderboard`, `/stats` | Reminders, participation and usage statistics |\n| `/moderation`, `/admin` | Server moderation and administrative controls |\n| `/forget`, `/privacy` | Delete existing episodic facts and inspect disclosure |\n\nExamples below show command options; use Discord's selector for choice fields:\n\n```text\n/search query:Python asyncio task cancellation deep:false category:docs\n/search query:Compare recent retrieval approaches deep:true category:arxiv\n/run code:print(sum([1, 2, 3])) language:Python 3\n/sandbox auto_mode mode:Auto (Test when helpful)\n/agent status\n/mcp tools\n```\n\n`/search` defaults to deep research; set `deep:false` for a quick lookup. `/run` requires channel execution permission. Automatic testing additionally needs an enabled agent and a native-tool model. Administrative commands enforce their own permissions. See [USER_GUIDE.md](USER_GUIDE.md) for complete command behavior and approval review.\n\n## Execution limits and accounting\n\n| Operation | Default or enforced ceiling |\n| --- | --- |\n| Normal/deep agent steps | Defaults of **4 / 6**; global ceiling of **8** |\n| Normal/deep request duration | Caps of **90 / 180 seconds**, including context, retrieval and fallback |\n| Explicit file generation | Separate **600-second** direct-generation cap |\n| Quick research | One query; up to two fetched pages |\n| Deep research | Up to three queries plus one empty-result fallback; five unique pages; 50,000-character evidence ceiling |\n| Sandbox execution | Default **8 seconds**; maximum **30 seconds**; one optional corrected retry |\n| Sandbox output | Default **12,000-character** combined stdout/stderr cap |\n| Sandbox concurrency | Default **one** execution at a time |\n\nPer-resource budgets additionally constrain search, fetch attempts, sandbox and MCP calls. Repeated identical calls are blocked. If a provider fails after tool activity, the runtime returns an incomplete result instead of replaying completed work under another model.\n\nSearch can incur Serper charges; inference, images, voice and other services follow the configured account's terms. Token totals reflect reported physical model responses. Optional `MODEL_PRICING_JSON` rates produce estimates, while missing usage/rates remain unknown. Search, TTS, embeddings, caching discounts and other external charges are outside the model estimate.\n\n## Security and privacy\n\nTool authorization is enforced by application policy rather than model instructions. Arguments are validated before dispatch, documents/tool output are treated as untrusted data, direct web fetches pin validated public IPs, and generated download bytes are sanitized alongside previews. Execution containers run without networking under a non-root identity; the runner itself remains a trusted Docker administrator.\n\nWrite/destructive actions require signed approval by the initiating user or a Discord administrator. Approvals expire within five minutes and are claimed once. A timeout or crash after claiming can leave the external outcome uncertain; verify the target system before staging a replacement action.\n\nPrompts, history, memories and attachments may reach configured external services. A local model does not automatically disable remote preprocessing, search or fallback. `/forget` deletes existing episodic facts; it does not delete Discord history, logs, lore or provider copies, and it is not a permanent extraction opt-out. [PRIVACY.md](PRIVACY.md) describes recipients, retention and operator responsibilities.\n\n## Development and validation\n\n```bash\npython -m pytest -q\npython -m compileall -q backend bot tests\npip check\n```\n\nTests disable local `.env` credentials and block external connections; real MCP stdio/HTTP fixtures use local transports. PostgreSQL/pgvector and Docker integration tests have explicit setup requirements described in [CONTRIBUTING.md](CONTRIBUTING.md). [CI](.github/workflows/ci.yml) requires those gates, image builds and Compose service/mount checks.\n\nBefore deployment, validate the configured providers, Supabase, Discord interactions and performance in staging. [DEPLOYMENT.md](DEPLOYMENT.md#required-release-checks) describes the release checks, including integration tests that require pgvector or Docker.\n\nThe HTTP `/api/chat/stream` endpoint buffers generation and chunks the completed sanitized answer, using the same tools, fallback and output checks as normal chat. Native provider streaming APIs remain available for direct integrations.\n\n### Repository layout\n\n```text\nbackend/\n  chat/          Context building and shared orchestration\n  agent/         Tool selection, budgets and bounded runtime\n  models/        Provider catalog, capabilities and adapters\n  tools/         Registry, argument validation and execution policy\n  search/        Serper, cache, fetching and evidence\n  mcp_client/    Configured transports, discovery and lifecycle\n  actions/       Signed approvals and single-use claims\n  sandbox/       Separate runner and Docker execution\n  memory/        Supabase helpers, embeddings, metrics and migrations\n  routers/       HTTP API endpoints\nbot/             Discord events, commands and approval UI\nconfig/          Operator MCP configuration example\ninfra/           Process supervision\ntests/           Regression and integration gates\n```\n\n## Documentation\n\n| Guide | What it covers |\n| --- | --- |\n| [User guide](USER_GUIDE.md) | Model/mode controls, research, execution, approvals and command behavior |\n| [Deployment](DEPLOYMENT.md) | Database migration, Compose/PM2, credentials, rollout, troubleshooting and recovery |\n| [Architecture](ARCHITECTURE.md) | Component ownership, provider continuation and policy resolution |\n| [Privacy](PRIVACY.md) | Data recipients, storage, retention and deletion scope |\n| [Contributing](CONTRIBUTING.md) | Development setup, integration gates and implementation invariants |\n\n## Contributing and support\n\nBug reports and feature proposals can be filed through the repository's [Issues](https://github.com/Muhammad-Hassan12/Zauq/issues). For a bug, include reproducible steps, relevant settings with secrets removed, and expected versus actual behavior. Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request; changes should preserve existing features and update documentation when behavior changes.\n\n## Maintainer and license\n\n<div align=\"center\">\nCreated and maintained by\n</div>\n\n<table align=\"center\">\n  <tr>\n    <td align=\"center\">\n      <img src=\"https://github.com/Muhammad-Hassan12.png\" width=\"120px;\" alt=\"Syed Muhammad Hassan\"/><br />\n      <sub><b>Syed Muhammad Hassan</b></sub><br />\n      <sub>Co-Founder/CTO & AI Architect @ AgenticEra Systems</sub><br /><br />\n      <a href=\"https://github.com/Muhammad-Hassan12\"><img src=\"https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white\"/></a>\n      <a href=\"https://www.linkedin.com/in/syed-muhammad-hassan-aa112928b/\"><img src=\"https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white\"/></a>\n    </td>\n  </tr>\n</table>\n\nSource code is licensed under the **Apache License 2.0**; see [LICENSE](LICENSE). Branding, attribution and third-party service notices are described in [NOTICE.md](NOTICE.md). Integrations require your own configured accounts and are subject to the applicable service terms.\n"}