A production-ready, multi-tenant intelligence system powered by autonomous AI agents for content analysis, fact-checking, and cross-platform monitoring. Built with CrewAI orchestration, 31 specialized agents, 111 specialized tools, and a modern 3-layer architecture.
The Ultimate Discord Intelligence Bot provides:
- Autonomous Content Analysis: AI-powered deep analysis of videos, articles, and social media content
- Fact-Checking & Verification: Multi-source claim verification with confidence scoring
- Multi-Platform Intelligence: Monitors YouTube, TikTok, Twitter/X, Reddit, Instagram, and Discord
- Real-Time Processing: Live stream analysis and real-time content monitoring
- Advanced Memory Systems: Qdrant vector storage, Neo4j graph memory, Mem0/HippoRAG continual learning
- Quality Assurance: Content validation, consistency checking, and quality gates
- Trajectory Evaluation: LangSmith-powered scoring with RL feedback loops for model routing
- Performance Optimization: Multi-level caching, intelligent model routing, prompt compression
- OpenAI Integration: Structured outputs, function calling, streaming, multimodal analysis
- Multi-Tenant Architecture: Complete workspace and resource isolation
The system employs a clean 3-layer architecture following domain-driven design principles:
-
Platform Layer (
src/platform/): Infrastructure and cross-cutting concerns- Core protocols:
StepResultpattern for unified error handling - HTTP layer: Resilient HTTP client with circuit breakers, retries, and timeout management
- Cache layer: Multi-level caching (L1 in-memory, L2 Redis, L3 semantic)
- LLM layer: Provider-agnostic routing with quality/cost/latency policies
- RL layer: Reinforcement learning (contextual bandits) for adaptive model selection
- Observability: Prometheus metrics, Langfuse tracing, structured logging
- Security: Rate limiting, privacy controls, policy enforcement
- Core protocols:
-
Domain Layer (
src/domains/): Business logic organized by bounded contexts- Orchestration (
orchestration/): CrewAI agents, tasks, and crew management - Ingestion (
ingestion/): Multi-platform content providers- YouTube, TikTok, Twitter/X, Reddit, Instagram, Discord, Twitch
- Intelligence (
intelligence/): Analysis and verification- Analysis: Content processing, sentiment, fallacy detection, timeline construction
- Verification: Fact-checking, claim extraction, confidence scoring
- Memory (
memory/): Storage and retrieval systems- Vector: Qdrant integration for semantic search
- Graph: Neo4j knowledge graphs
- Continual: Mem0, HippoRAG for long-term learning
- Orchestration (
-
App Layer (
src/app/): Application entry points and interfaces- Discord bot (
discord/): Commands, events, and bot lifecycle management - Crew executor: Agent orchestration and task execution
- Configuration: Agent definitions (YAML), feature flags, runtime settings
- Main entry point (
main.py)
- Discord bot (
- CrewAI Framework: Orchestrates 31 specialized agents with role-based tool access across strategic, operational, and specialized domains
- 111 Tools: Comprehensive tool ecosystem organized across 9 categories
- Multi-Tenant Support: Complete tenant isolation and workspace management
- Advanced Memory: Vector stores, graph databases, and traditional storage
- Performance Optimization: Intelligent caching and model routing
- Quality Assurance: Comprehensive validation and consistency checking
- Observability Pipeline: Langfuse tracing, Prometheus metrics, and StepResult instrumentation
- Executive Supervisor: Strategic oversight, resource allocation, and mission success
- Workflow Manager: Task routing, dependency management, and load balancing across agent hierarchies
- Mission Orchestrator: End-to-end mission coordination, depth sequencing, and budget management
- Acquisition Specialist: Multi-platform content download with rate-limit handling and quality fallbacks
- Transcription Engineer: Audio/video transcription and searchable indexing
- Analysis Cartographer: Linguistic, sentiment, and thematic signal mapping
- Verification Director: Fact-checking, claim extraction, and defensible verdicts
- Risk Intelligence Analyst: Deception scoring, trust metrics, and longitudinal tracking
- Persona Archivist: Living dossiers with behavior, sentiment, and trust milestones
- Knowledge Integrator: Memory consolidation across vector, graph, and continual memory
- Signal Recon Specialist: Cross-platform discourse and sentiment tracking
- Trend Intelligence Scout: Emerging content detection and prioritization
- Community Liaison: Community Q&A with verified intelligence and context retrieval
- Argument Strategist: Steelman arguments, debate prep, and persuasive narratives
- Research Synthesist: Deep background briefs harmonizing multiple perspectives
- Intelligence Briefing Curator: Stakeholder-ready intelligence packets
- System Reliability Officer: Pipeline health, dashboards, and operational visibility
- Personality Synthesis Manager: Consistent tone, style, and persona alignment
- Visual Intelligence Specialist: Computer vision, image analysis, OCR, and visual fact-checking
- Audio Intelligence Specialist: Speaker diarization, emotion analysis, and acoustic classification
- Trend Intelligence Specialist: Real-time trend monitoring and long-term forecasting
- Content Generation Specialist: AI-powered content creation, adaptation, and optimization
- Cross-Platform Intelligence Specialist: Multi-platform correlation and propagation analysis
- Network Discovery Specialist: Social network mapping, collaboration patterns, and influence dynamics
- Deep Content Analyst: Multimodal long-form analysis and narrative arc tracking
- Guest Intelligence Specialist: Guest profiling, collaborator tracking, and monitoring recommendations
- Controversy Tracker Specialist: Drama detection, conflict tracking, and early warnings
- Insight Generation Specialist: Pattern synthesis and actionable intelligence delivery
- Quality Assurance Specialist: Output validation, consistency checks, and re-analysis triggers
- Conversational Response Agent: Natural, context-aware Discord responses
- Personality Evolution Agent: RL-based personality optimization from interaction feedback
After domains/ migration, use these import paths:
# Platform layer - infrastructure
from platform.core.step_result import StepResult, ErrorCategory
from platform.http.http_utils import resilient_get, resilient_post
from platform.cache.tool_cache_decorator import cache_tool_result
from platform.llm.llm_router import LLMRouter
# Tenancy - multi-tenant isolation
from ultimate_discord_intelligence_bot.tenancy.context import (
TenantContext,
with_tenant,
current_tenant,
require_tenant,
)
# Domain layer - business logic
from domains.intelligence.analysis.logical_fallacy_tool import LogicalFallacyTool
from domains.intelligence.verification.fact_check_tool import FactCheckTool
from domains.intelligence.acquisition.youtube_downloader_tool import YouTubeDownloaderTool
from domains.memory.vector_memory_tool import VectorMemoryTool
from domains.orchestration.crew.compat import CrewAICompatExecutor
# Observability
from ultimate_discord_intelligence_bot.obs.metrics import get_metricsDeprecated paths (pre-migration):
- β
from ultimate_discord_intelligence_bot.crew import ... - β
from ultimate_discord_intelligence_bot.tools import ... - β
Use
from domains.orchestration.crew import ...instead - β
Use
from domains.intelligence.* import ...for tools
The bot includes comprehensive OpenAI integration with advanced AI capabilities:
- Structured Outputs: Generate validated, structured responses using JSON schemas
- Function Calling: Enable AI models to call custom functions during analysis
- Streaming: Real-time streaming of AI responses for better user experience
- Voice Processing: Convert between text and speech using OpenAI's voice models
- Vision Analysis: Analyze images and visual content with advanced vision models
- Multimodal Analysis: Process content across multiple modalities (text, images, audio)
- OpenAIStructuredOutputsService: Generate structured, validated responses
- OpenAIFunctionCallingService: Enable function calling capabilities
- OpenAIStreamingService: Stream responses in real-time
- OpenAIVoiceService: Text-to-speech and speech-to-text conversion
- OpenAIVisionService: Image analysis and visual content processing
- MultimodalAnalysisService: Cross-modal content analysis
- OpenAIIntegrationService: Main service combining all capabilities
- OpenAICostMonitoringService: Track API usage and costs
!openai-health- Check OpenAI service health!openai-analyze-structured <content>- Perform structured analysis!openai-analyze-multimodal <prompt>- Analyze multimodal content!openai-voice-command- Process voice commands
The OpenAI capabilities are available as CrewAI tools:
- OpenAIEnhancedAnalysisTool: Enhanced analysis with OpenAI capabilities
- Integrated with analysis agents for advanced content processing
- Supports structured outputs, function calling, and multimodal analysis
For detailed documentation, see OpenAI Integration Features.
- Python 3.10+
- Docker and Docker Compose
- Discord Bot Token
- OpenAI/OpenRouter API Key
- Qdrant Vector Database
-
Clone the repository
git clone <repository-url> cd ultimate-discord-intelligence-bot
-
Set up environment
cp .env.example .env # Edit .env with your configuration -
Install dependencies
# Recommended for development pip install -e '.[dev]' # Minimal install (production) pip install -e . # Optional feature sets pip install -e '.[metrics]' # Prometheus metrics pip install -e '.[whisper]' # Whisper transcription pip install -e '.[vllm]' # VLLM inference pip install -e '.[mcp]' # Model Context Protocol
-
Start services
# Development compose docker compose -f config/docker/docker-compose.yml up -d -
Run the bot
# Ensure virtualenv is active; sitecustomize.py auto-adds src/ to PYTHONPATH when launched from repo root source .venv/bin/activate python -m app.main run # OR use explicit PYTHONPATH PYTHONPATH=src python -m app.main run # OR call the file directly python src/app/main.py run
Troubleshooting: If you see a Python error like "Could not find platform independent libraries " or sys.prefix shows "/install" and "No module named 'encodings'", your virtual environment is corrupted (often due to an external Python shim such as uv). Fix by recreating a clean venv with your system Python:
# from repo root deactivate || true rm -rf .venv python3 -m venv .venv source .venv/bin/activate pip install -U pip wheel setuptools pip install -e . # then: python -m app.main run
Note on stdlib platform module conflict: This repository contains a top-level
platform/package. Some environments ship a systemsitecustomize.pythat loads before project-level startup hooks, which can causefrom platform.core ...imports to resolve the stdlib module instead. We've implemented two safeguards:- Entry-point bootstrap:
app/main.pyandserver/app.pycall a tiny bootstrap (ultimate_discord_intelligence_bot.core.bootstrap.ensure_platform_proxy()) at process start to make the stdlibplatformmodule behave as a package exposing ourplatform/*submodules. - User customizations: a minimal
src/usercustomize.pyperforms the same augmentation on Python startup when supported by your environment.
With these in place, imports like
from platform.core.step_result import StepResultwork consistently across shells, venvs, and containers. - Entry-point bootstrap:
This project enforces automated compliance checks to maintain code quality and architectural standards:
- Local Development: Pre-commit hooks validate all changes before commit
- CI Pipeline: GitHub Actions workflow runs on every PR and push to main branches
- Merge Blocking: PRs cannot merge if compliance checks fail (when branch protection enabled)
- HTTP Wrapper Guard - Prevents direct
requests.*calls; enforces resilient HTTP wrappers with circuit breakers and retries - Tools Export Guard - Ensures all tools are registered in
__all__for dynamic discovery (112 tools validated) - Metrics Instrumentation Guard - Enforces consistent metric naming conventions and observability patterns
- Deprecated Directories Guard - Blocks new files in deprecated paths during architecture migration
- Dispatcher Usage Guard - Validates tenant context propagation in async/thread boundaries
# One-time setup: Install pre-commit hooks
make setup-hooks
# Manual execution: Run all guards
make guards
# Check specific guard
python scripts/validate_http_wrappers_usage.py
# Generate compliance report
python scripts/generate_guard_report.py --input <(make guards 2>&1) --output report.json --prettyFor critical hotfixes only:
# Bypass local hook (CI still enforces)
git commit --no-verify -m "hotfix: critical issue"Note: Bypassed commits still run in CI. Document bypass reason in commit message.
- Full Guide: docs/compliance-guards.md - 557 lines covering setup, troubleshooting, examples
- CI Workflow: .github/workflows/guards-ci.yml - Automated enforcement with PR comments
- Implementation: F011_F014_GUARD_CI_INTEGRATION_COMPLETE_2025-11-12.md
# Discord Bot
DISCORD_BOT_TOKEN=your_discord_bot_token
DISCORD_PRIVATE_WEBHOOK=your_private_webhook_url
# LLM Services
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
OPENAI_BASE_URL=https://api.openai.com/v1
# Vector Database
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_qdrant_api_keyConfigure the provider-agnostic router that selects the best model per request.
# Comma-separated provider allowlist used to build routing candidates
# Examples: openai,anthropic,google,openrouter,groq,together,cohere,mistral,fireworks,perplexity,xai,deepseek,azure_openai,bedrock
LLM_PROVIDER_ALLOWLIST=openai,anthropic,google,openrouter
# Router policy: quality_first | cost | latency
ROUTER_POLICY=quality_first
# Comma-separated task names that should force quality-first routing
QUALITY_FIRST_TASKS=analysis,reasoning,codingThese values are also available at runtime via get_config() from platform.config.configuration
as llm_provider_allowlist (parsed list) and router_policy.
# Core Features
ENABLE_DEBATE_ANALYSIS=true
ENABLE_FACT_CHECKING=true
ENABLE_MULTI_PLATFORM_MONITORING=true
# Advanced Features
ENABLE_UNIFIED_KNOWLEDGE=true
ENABLE_UNIFIED_METRICS=true
ENABLE_UNIFIED_ORCHESTRATION=true
ENABLE_UNIFIED_ROUTER=true
# Performance Features
ENABLE_CACHE_OPTIMIZATION=true
ENABLE_MODEL_ROUTING=true
ENABLE_PERFORMANCE_OPTIMIZATION=true
# OpenAI Integration Features
ENABLE_OPENAI_STRUCTURED_OUTPUTS=true
ENABLE_OPENAI_STREAMING=true
ENABLE_OPENAI_VOICE=false
ENABLE_OPENAI_VISION=false
ENABLE_OPENAI_MULTIMODAL=false
ENABLE_OPENAI_FUNCTION_CALLING=true
ENABLE_OPENAI_FALLBACK=true
# Evaluation & Observability
ENABLE_TRAJECTORY_EVALUATION=1 # Set to 1 to enable runtime scoring
ENABLE_TRAJECTORY_FEEDBACK_LOOP=0 # Set to 1 to push scores into RL router
RL_FEEDBACK_BATCH_SIZE=25 # Optional: number of feedback items processed per tick
RL_FEEDBACK_LOOP_INTERVAL_SECONDS=15 # Optional: delay (seconds) between feedback loop runs
ENABLE_LANGSMITH_EVAL=false
ENABLE_LANGFUSE_EXPORT=false# CrewAI Configuration
CREW_MAX_RPM=10
CREW_EMBEDDER_PROVIDER=openai
# Cache Settings
CACHE_TTL=3600
CACHE_MAX_SIZE=1000
# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_BURST_SIZE=10The codebase includes comprehensive performance analysis and optimization tools. See Performance Initiative Summary for details.
Quick Performance Check:
# Analyze performance issues
python3 scripts/performance_improvements.py --report
# Check for performance regressions
python3 -m ruff check src --select PERFDocumentation:
- Performance Improvement Recommendations - Comprehensive analysis of 258 performance issues
- Performance Best Practices - Best practices for high-performance Python code
- Performance Fixes Applied - Summary of automated fixes
Benchmarking:
# Run performance benchmarks
python3 benchmarks/performance_benchmarks.py
# Profile tool imports
python3 profile_tool_imports.py!analyze <url>- Analyze content from any supported platform!factcheck <claim>- Fact-check a specific claim!monitor <creator>- Start monitoring a creator!status- Get system status and metrics
!deep_analysis <url>- Comprehensive content analysis!verify_claims <url>- Extract and verify all claims!trend_analysis <topic>- Analyze trends for a topic!quality_assess <content>- Assess content quality
# Recommended: domain-based import
from domains.orchestration.crew import get_crew, UltimateDiscordIntelligenceBotCrew
# Factory pattern
crew_adapter = get_crew()
crew_obj = crew_adapter.crew()
result = crew_obj.kickoff(inputs={"url": "https://youtube.com/watch?v=example"})
# Or instantiate directly
crew_instance = UltimateDiscordIntelligenceBotCrew()
result = crew_instance.crew().kickoff(inputs={"url": "https://youtube.com/watch?v=example"})result = crew.crew().kickoff(inputs={
"claim": "The Earth is flat",
"context": "Scientific discussion"
})- Feature-gated exporter capturing traces and spans for every pipeline step via
LangfuseService - Configure with
ENABLE_LANGFUSE_EXPORT,LANGFUSE_PUBLIC_KEY,LANGFUSE_SECRET_KEY, and optionalLANGFUSE_BASE_URL - StepResult-aware sanitization ensures payload safety and tenant metadata tagging
- Validate instrumentation with
python run_observability_tests.pyor enable live export in staging
- Real-time performance metrics
- Agent execution statistics
- Tool usage analytics
- Error rates and success rates
- Structured logging with tenant isolation
- Performance tracing
- Error tracking and alerting
- Audit trails for compliance
- System health endpoints
- Service availability monitoring
- Resource usage tracking
- Automated alerting
# Run all tests
make test
# Run specific test categories
pytest tests/tools/ # Tool tests
pytest tests/agents/ # Agent tests
pytest tests/services/ # Service tests
pytest tests/integration/ # Integration tests- Validates LangSmith adapters and heuristic fallbacks.
- Execute
pytest tests_new/unit/eval/test_langsmith_adapter.pyfor focused coverage. - Enable
ENABLE_TRAJECTORY_EVALUATION=1andENABLE_TRAJECTORY_FEEDBACK_LOOP=1to exercise reinforcement feedback paths in integration environments.
make format # Code formatting
make lint # Linting
make type # Type checking
make test # Testing
make docs # Documentation validationFor detailed quality gate requirements, see docs/quality-gates.md.
# Build and deploy (production)
docker compose -f config/docker/docker-compose.prod.yml up -d
# Scale services
docker compose -f config/docker/docker-compose.prod.yml up -d --scale bot=3Kubernetes manifests are not included by default in this repository. If you maintain your own manifests, apply them in your deployment repository or ops layer.
config/docker/docker-compose.yml- Developmentconfig/docker/docker-compose.prod.yml- Production
src/
βββ platform/ # Platform layer: Infrastructure & cross-cutting concerns
β βββ core/ # Core protocols (StepResult, config)
β βββ http/ # Resilient HTTP client (circuit breakers, retries)
β βββ cache/ # Multi-level caching (memory, Redis, semantic)
β βββ llm/ # LLM providers, routing, structured outputs
β βββ rl/ # Reinforcement learning (contextual bandits)
β βββ observability/ # Metrics, tracing, logging
β βββ security/ # Security, privacy, rate limiting
β βββ prompts/ # Prompt engineering (DSPy)
β βββ rag/ # RAG capabilities (LlamaIndex)
β
βββ domains/ # Domain layer: Business logic by bounded context
β βββ orchestration/ # CrewAI agents, tasks, crew
β β βββ crewai/ # CrewAI-specific components
β β βββ legacy/ # Legacy orchestration code
β βββ ingestion/ # Multi-platform content ingestion
β β βββ pipeline/ # Ingestion pipeline orchestrator
β β βββ providers/ # Platform-specific providers
β βββ intelligence/ # Analysis & verification
β β βββ analysis/ # Content analysis tools
β β βββ verification/ # Fact-checking & verification
β βββ memory/ # Memory systems
β βββ vector/ # Vector storage (Qdrant)
β βββ graph/ # Graph memory (Neo4j)
β βββ continual/ # Continual learning (Mem0, HippoRAG)
β
βββ app/ # App layer: Application-specific code
β βββ main.py # Application entry point
β βββ crew_executor.py # CrewAI crew execution
β βββ discord/ # Discord bot integration
β β βββ bot.py # Bot implementation
β β βββ commands/ # Discord commands
β β βββ events/ # Event handlers
β βββ config/ # Application configuration
β βββ settings.py # Global settings
β βββ agents.yaml # Agent definitions
β
βββ ultimate_discord_intelligence_bot/ # Legacy: being migrated to domains/
βββ tools/ # 111 specialized tools (registry)
βββ pipeline_components/# Pipeline orchestrator
βββ tenancy/ # Multi-tenant context management
- Create tool class inheriting from
BaseTool - Implement
_runmethod returningStepResult - Add to
tools/__init__.pyexports - Register in
crew.pywith appropriate agent - Add comprehensive tests
- Define agent in
crew.pywith@agentdecorator - Specify role, goal, backstory, and tools
- Add to crew construction in
crew()method - Update agent documentation
- Fork the repository
- Create feature branch
- Implement changes with tests
- Run quality gates
- Submit pull request
- Follow PEP 8 and project formatting rules
- Include comprehensive type hints
- Write tests for all new functionality
- Update documentation for new features
- Use
StepResultfor all tool returns
- All quality gates must pass
- 100% test coverage for new code
- Documentation updates required
- No increase in MyPy error baseline
This project is licensed under the MIT License - see the LICENSE file for details.
- Check documentation for detailed guides
- Review troubleshooting guide
- Open an issue for bugs or feature requests
- Join our Discord server for community support
When reporting issues, please include:
- System information (OS, Python version)
- Error logs and stack traces
- Steps to reproduce
- Expected vs actual behavior
- Tool registration and organization
- Agent architecture implementation
- Basic functionality testing
- Quality assurance systems
- Performance optimization
- Enhanced MCP integration
- Complete system configuration
- Comprehensive testing
- Documentation updates
- Performance optimization
- Advanced monitoring
- Auto-scaling capabilities
- Advanced analytics
- Machine learning optimization
- 111 specialized tools across 9 categories (ingestion, analysis, verification, memory, observability, etc.)
- 31 autonomous AI agents with role-based tool access
- Multi-platform content ingestion (YouTube, TikTok, Twitter/X, Reddit, Instagram, Discord, Twitch)
- Advanced fact-checking with claim extraction and multi-source verification
- Multi-level memory systems (Qdrant vectors, Neo4j graphs, Mem0/HippoRAG continual learning)
- Quality assurance with validation, consistency checking, and quality gates
- Performance optimization with semantic caching, prompt compression, and model routing
- Multi-tenancy support with complete workspace and resource isolation
- Observability with Prometheus metrics, Langfuse tracing, and structured logging
- Reinforcement learning for adaptive model selection via contextual bandits
- Advanced analytics dashboard
- Real-time collaboration features
- Enhanced security features
- Advanced workflow automation
- Machine learning model training
- Advanced visualization tools
- Enterprise integrations
- Mobile applications
Built with β€οΈ using CrewAI, Discord.py, and modern Python technologies.