AI-Powered Organizational Knowledge Assistant
Built for PM workflows, designed for organization-wide intelligence
Product Oracle v2 is a sophisticated multi-agent AI system that helps organizations unlock insights trapped across disconnected business platforms. Through intelligent orchestration of specialized agents, it investigates complex questions by analyzing data from HubSpot, Slack, Jira, and Google Drive—delivering comprehensive, cross-platform insights in minutes instead of hours.
Core Capabilities:
- 🔍 Natural Language Investigation: Ask questions in Slack, get comprehensive cross-platform answers
- 🤖 Multi-Agent Orchestration: 4 specialized agents coordinate to gather and correlate insights
- 🧠 Intelligent Synthesis: AI supervisor builds context iteratively, discovering connections humans miss
- 📊 Professional Reports: Automatic PDF generation with citations and actionable recommendations
- 🔒 Read-Only Access: Secure, non-invasive access to business systems
- 💬 Slack-Native: Zero additional training, works where teams already collaborate
3-Phase Investigation Workflow:
- 🧠 Brainstorm Phase: AI validates query context and plans investigation strategy with human approval
- 🎯 Supervisor Phase: Sequential agent execution where each agent builds on previous findings
- 📊 Report Phase: Cross-platform synthesis with structured insights and recommendations
While originally built for product management workflows, Product Oracle's architecture delivers value across organizational functions:
- Feature Performance Analysis: Correlate customer feedback, team discussions, development status
- Data-Driven Prioritization: Rapid validation of product hypotheses across multiple sources
- Stakeholder Communication: Professional reports ready for immediate presentation
- Pre-Call Preparation: Instant access to customer history, product context, internal discussions
- Competitive Intelligence: Surface relevant conversations and documentation
- Deal Context: Understand cross-functional perspectives on accounts
- Knowledge Discovery: Self-service access to organizational information
- Faster Ramp-Up: Find relevant context without interrupting team members
- Cultural Learning: Understand how teams communicate and make decisions
- Institutional Memory: Surface historical decisions and their rationale
- Information Discovery: Find information users didn't know existed
- Cross-Team Visibility: Break down information silos
What Makes This Possible:
- Slack-native interface requires zero training
- Read-only access ensures security across teams
- Natural language removes technical barriers
- Modular architecture supports diverse workflows
Product Oracle addresses critical challenges in modern knowledge work:
Problem: Critical insights scattered across disconnected tools (HubSpot, Slack, Jira, Google Drive), requiring extensive manual aggregation and context switching.
Solution: Unified Slack interface consolidates all sources. AI agents automatically query systems, correlate findings, and synthesize insights in one place.
Impact: 70% reduction in investigation time, zero context switching
Problem: Hours spent manually gathering data, correlating patterns, and synthesizing findings from multiple business systems.
Solution: What previously required hours of manual work now takes 3-15 minutes. Ask natural language questions, review AI-generated plans, receive comprehensive PDF reports.
Impact: Knowledge workers reclaim time for high-value strategic work
3. Hidden Institutional Knowledge
Problem: Critical context buried in Slack threads, meeting notes, and legacy documentation—impossible to discover through traditional search.
Solution: AI agents surface relevant context from qualitative sources (meeting notes, research) alongside quantitative data (tickets, analytics), discovering connections that manual investigation would miss.
Impact: Complete picture with both "what's happening" and "why it matters"
Product Oracle's defining innovation: sequential agent execution where each agent builds on previous findings. Unlike traditional parallel orchestrators that prioritize speed, this architecture enables true cross-data intelligence.
How It Works:
- Supervisor acts as an intelligent investigator
- Agents execute sequentially based on discoveries
- Each agent receives context from all previous investigations
- Dynamic decision-making about what to investigate next
Why It Matters:
- Later agents make smarter decisions based on earlier discoveries
- Identifies correlations impossible with isolated parallel queries
- Adaptive investigation paths that mirror human reasoning
- Deeper insights through iterative investigation
The Trade-Off:
- ⏱️ Longer runtime (sequential vs parallel)
- 🧠 Significantly deeper cross-data analysis
- 📊 Higher quality insights and recommendations
User Feedback Validation: Based on feedback that data efficacy was more important than fast runtimes, v2 adopted this architecture—prioritizing investigation quality over raw speed.
Challenge: Multi-agent systems typically fail due to fragile string parsing and ambiguous outputs.
Solution: Every agent decision uses Pydantic-validated structured outputs. No string parsing, no ambiguity.
Impact: Eliminates fragility common in multi-agent systems, ensuring reliable coordination even with enterprise-scale complexity.
Challenge: Unpredictable data volumes (queries returning 10 or 10,000 results) can overflow context windows, causing crashes.
Solution: Universal pre-model hooks monitor and compress large tool outputs before they exceed the 200K token limit.
Impact: Handles real-world data unpredictability without crashes or truncation.
Challenge: Each business system has unique APIs, authentication, and data structures—creating integration complexity.
Solution: Standardized MCP architecture provides secure, read-only access with consistent patterns across all systems.
Impact:
- Rapid expansion to new data sources
- Maintains security boundaries
- Positions Product Oracle as a platform, not just a tool
- Community can contribute new MCP servers
The defining characteristic of Product Oracle v2 is its complete overhaul from v1's orchestrator architecture to a supervisor architecture—a strategic decision that prioritizes investigation quality over raw speed.
How it worked:
- Orchestrator determined which data sources to check
- All agents ran in parallel simultaneously
- Results were aggregated and packaged into a report
Pros: ⚡ Faster runtime due to parallel execution
Cons: 🔍 Limited cross-data analysis—agents couldn't build on each other's findings
How it works:
- Supervisor acts as an intelligent investigator
- Agents execute sequentially based on findings
- Each agent builds upon previous discoveries
- Dynamic decision-making about what to investigate next
Pros: 🧠 Stronger cross-data insights and investigation depth
Cons: ⏱️ Longer runtime due to sequential processing
Based on user feedback that data efficacy was more important than fast runtimes, Product Oracle v2 adopts the supervisor architecture to enable:
- Cross-agent intelligence: Later agents can use insights from earlier investigations
- Dynamic investigation paths: The AI chooses what to investigate next based on what it learns
- Deeper insights: Advanced iterative investigation capabilities
- Human-like reasoning: The system thinks and investigates like an experienced product manager
Purpose: Ensure proper investigation planning and scope alignment
Process:
- Analyzes user query for context and clarity
- Validates against product context and organizational information
- Collaboratively refines investigation plan with user
- Determines if sufficient context exists to proceed
Human Interaction: User approves or modifies the investigation plan before execution
Value: Ensures alignment with user and Product Oracle on investigation objective. Prevents wasted computation on misunderstood queries.
Purpose: Intelligent agent orchestration with cross-data insights
Process:
- Sequential agent execution based on investigation plan
- Dynamic decision-making about which agent to call next
- Each agent receives context from all previous investigations
- Builds comprehensive understanding through iterative discovery
Intelligence: Supervisor analyzes each agent's findings and strategically determines the next investigation step
Value: Discovers connections and correlations that parallel execution would miss
Purpose: Synthesize findings into structured, actionable insights
Process:
- Cross-platform data analysis and correlation
- Structured insight generation with clear hierarchies
- Actionable recommendations tailored for the user's context
- Executive summary with supporting evidence
Output: Comprehensive reports designed for immediate decision-making and stakeholder communication
Status: Deferred due to time constraints, but infrastructure exists
Purpose: Human-in-the-loop validation and refinement of final reports
Planned Features:
- User reviews synthesized findings and recommendations
- Request revisions or additional investigation
- Iterative refinement until approval
- Final report generation and archival
Why Deferred: Complex state flow with feedback loops required more sophisticated state management than MVP timeline allowed. Foundation exists (async queue, state preservation, context tracking)—primarily needs workflow orchestration updates.
Product Oracle coordinates four specialized agents, each expert in specific business systems:
- Purpose: CRM data, customer feedback, sales insights
- Tools: 21+ read-only MCP tools
- Expertise: Customer relationship analysis, support patterns, sales pipeline
- Data Type: Quantitative metrics and customer interactions
- Purpose: Internal communication analysis, team discussions
- Tools: 5 MCP tools with cache bypass for large workspaces
- Expertise: Team sentiment, internal feedback, discussion patterns
- Data Type: Qualitative team conversations and sentiment
- Technical Note: Implements cache bypass to handle 240K+ token cache files
- Purpose: Project management data, feature requests, bug tracking
- Tools: 25+ MCP tools
- Expertise: Development priorities, sprint analysis, workflow insights
- Data Type: Quantitative project management metrics
- Purpose: Qualitative document insights from internal documentation
- Tools: 3 core MCP tools (search, read files, read spreadsheets)
- Expertise: Meeting notes, stakeholder interviews, research findings, strategic context
- Data Type: Qualitative insights—the "why" behind the "what"
- Authentication: Service account-based (no OAuth required)
Google Drive's Unique Contribution:
- 📝 Direct quotes from stakeholder interviews and customer research
- 🎯 Strategic rationale and product context from planning documents
- 🔄 Historical patterns from meeting notes and retrospectives
- 📊 Research synthesis documents connecting multiple data sources
Unlike v1's parallel execution, the supervisor pattern enables:
- Contextual Investigation: Each agent receives insights from previous agents
- Strategic Prioritization: Supervisor determines optimal investigation order
- Cross-Source Correlation: Agents validate findings across different data sources
- Adaptive Scope: Investigation can expand or focus based on discoveries
- Qualitative + Quantitative: Complete picture of "what" and "why"
Product Oracle is delivered as a production-ready Slack bot providing:
- Natural Language Queries: Ask complex questions by mentioning
@ProductOracle - Real-Time Updates: Progress notifications throughout the investigation
- Interactive Approvals: Approve plans and reports via thread replies
- Professional PDF Reports: Automatic generation for comprehensive investigations (>6000 chars)
- Thread-Based Conversations: All context preserved in organized threads
- Concurrent Investigations: Multiple users can investigate simultaneously
- Rich Formatting: Beautiful Block Kit messages with sections, dividers, emojis
User: @ProductOracle What are customers saying about our new dashboard feature?
Product Oracle: 🔍 Starting investigation... [creates thread]
Product Oracle: 📋 Investigation Plan Review
Investigation Strategy:
1. HubSpot: Check support tickets and customer feedback
2. Slack: Analyze internal team discussions
3. Google Drive: Review user research and meeting notes
4. Jira: Look for related bug reports and feature requests
Data sources to investigate: HubSpot, Slack, Google Drive, Jira
✅ Reply 'approve' to proceed or provide feedback for changes
User: approve
[Agent execution with real-time updates...]
Product Oracle: 📊 Investigation Complete
PDF: investigation_report.pdf (attached)
Key Finding: High initial adoption (67%) but 23% abandonment after
first use. Performance issues driving abandonment. User research
reveals users value real-time updates over visual polish.
Recommendation: Prioritize performance optimization sprint before
investing in additional dashboard features. Focus on speed over
aesthetics based on stakeholder feedback.
Socket Mode Architecture
- Real-time WebSocket connection without webhooks or public URLs
- Secure behind-firewall deployment
- No exposed endpoints to manage
Async/Sync Bridge
- Seamlessly connects LangGraph's synchronous interrupts with Slack's async messaging
- asyncio.Queue for user input routing
- Thread-safe concurrent investigation management
PDF Generation System
- Full markdown support (headers, bold, italic, code, lists, tables)
- Hybrid font system (Helvetica + NotoEmoji) for emoji rendering
- Automatic triggering for large reports
- Multiple fallback mechanisms for reliability
Framework: LangGraph with shared state subgraph architecture
- Unified State Schema: Single
OverallStateacross all subgraphs for seamless data flow - Command Pattern Routing: Modern LangGraph routing with declarative decision-making
- Human-in-the-Loop: Production-ready
interrupt()pattern for approval workflows
Primary LLM: Claude Sonnet 4.5 (anthropic-2025-05-14) via Anthropic API
- Temperature: 0.1 for consistent, deterministic outputs
- Structured Output: Pydantic model enforcement for all LLM interactions
- Memory Management: LangMem
RunningSummaryfor intelligent context compression
Language & Package Management:
- Python 3.13+ with modern async/await patterns
- uv: Fast, reliable package management
- Pydantic: Type-safe data validation and structured outputs
Key Dependencies:
# Core Framework
langgraph = ">=0.6.3" # Primary workflow orchestration
langgraph-supervisor = ">=0.0.29" # Supervisor pattern implementation
langchain-anthropic = ">=0.3.18" # Claude model integration
langmem = ">=0.0.29" # Memory management and context compression
# Slack Bot Integration
slack-bolt = ">=1.21.4" # Slack app framework with Socket Mode
aiohttp = ">=3.11.11" # Async HTTP for Socket Mode
# PDF Generation
reportlab = ">=4.4.4" # Professional PDF generation
markdown2 = ">=2.5.4" # Markdown to HTML conversion
pillow = ">=11.3.0" # Image processing (reportlab dependency)Shared State Multi-Level Orchestration:
Main Graph (OverallState)
├── Brainstorm Subgraph (OverallState)
├── Supervisor Subgraph (OverallState)
├── Report Subgraph (OverallState)
└── Approval Subgraph (OverallState)Benefits:
- Single unified state schema eliminates transformation overhead
- Subgraphs directly read/write state fields
- No state transformation processing required
- Single source of truth for state structure
Graceful Degradation: System continues operation with reduced functionality when components fail
- MCP Connection Failures: Automatic retry with exponential backoff
- Agent Execution Errors: Structured error reporting with human intervention triggers
- Context Management: Automatic summarization prevents token limit issues
Want to deploy Product Oracle in your organization? I've created comprehensive installation guides covering every aspect from environment configuration to Slack app setup to MCP server configuration.
- Python 3.13+ with uv package manager
- Anthropic API key for Claude Sonnet 4
- Slack workspace admin access
- API credentials for: HubSpot, Jira
- (Optional) Google Drive service account for document analysis
Product Oracle requires configuration of multiple services. We've broken this down into step-by-step guides:
📘 Getting Started Guide - Start here for installation overview
📘 Prerequisites Checklist - Verify you have everything needed
📘 Local Installation - Install on your local machine
📘 Docker Installation - Deploy with containers
📘 Verification Guide - Test your installation
📘 Configuration Guides - Configure Slack bot and MCP servers
# Clone repository
git clone git@github.com:AsherJN/product-oracle.git
cd product-oracle
# Follow docs/INSTALLATION.md for complete environment setup
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
# Configure environment variables (see docs/API_KEYS.md)
cp .env.example .env
# Edit .env with your API keys and credentials
# Run the Slack bot
uv run python run_slack_bot.py# Run the main investigation system (direct/testing)
uv run python src/main.py
# Test individual components
uv run python -m src.subgraphs.brainstorm
uv run python -m src.agents.hubspot_agent
# Test PDF generation
uv run python tests/test_pdf_generation.pyFor detailed setup instructions, see the Installation Guide.
- ✅ Core Architecture: Shared state subgraph pattern with LangGraph
- ✅ Supervisor: Multi-agent orchestration with 4 active agents
- ✅ Slack Bot Interface: Socket Mode with @mention invocation
- ✅ PDF Report Generation: Professional reports with markdown support
- ✅ HubSpot Agent: 21+ MCP tools for CRM data access
- ✅ Jira Agent: 25+ MCP tools for project management data
- ✅ Slack Agent: 5 MCP tools with cache bypass solution
- ✅ Google Drive Agent: 3 core MCP tools for qualitative insights
- ✅ Memory Management: LangMem integration for context compression
- ✅ Concurrent Investigations: Thread-safe multi-user support
- ⏳ Brainstorm Subgraph: Investigation planning interface (85% complete)
- ⏳ Report Subgraph: Insight synthesis and recommendations (90% complete)
Deferred Features (foundation exists, needs workflow completion):
- Approval Phase / Report Feedback Workflow
Awaiting External Dependencies (no MCP tools available yet):
- Pendo Agent: Analytics integration
- FullStory Agent: Session replay analysis
Product Oracle v2 is production-ready with:
- 4 fully functional agents (HubSpot, Slack, Jira, Google Drive)
- Working Slack bot interface with @mention invocation
- Sequential supervisor orchestration
- Professional PDF report generation
- Human-in-the-loop approval workflows
- Concurrent investigation support
- Comprehensive error handling
Phase 2: Enhanced Intelligence
- Advanced cross-data correlation algorithms
- Enhanced visualization in reports (charts, graphs)
- Investigation history and pattern tracking
- Custom investigation templates
Phase 3: Platform Expansion
- Additional MCP integrations (Pendo, FullStory when available)
- Automated investigation triggers
- Proactive insight discovery
- Multi-investigation comparison and trending
This project uses a comprehensive Memory Bank documentation system to preserve context and architectural decisions:
projectbrief.md: Foundation document with core requirements and success criteriaproductContext.md: User experience goals, personas, and value propositionssystemPatterns.md: Technical architecture patterns and implementation decisionstechContext.md: Technology stack, dependencies, and development setupactiveContext.md: Current work focus, recent decisions, and next stepsprogress.md: Implementation status, milestones, and evolution tracking
- Understand Context: Read relevant Memory Bank files for complete project understanding
- Follow Patterns: Use established architectural patterns documented in
systemPatterns.md - Modular Development: Create independent, testable components following the subgraph structure
- Update Documentation: Update Memory Bank files with significant changes and learnings
- Test Integration: Validate components work correctly within the larger system
- Human-Centered Design: Include human validation at critical decision points
- Modular Architecture: Components develop independently while integrating seamlessly
- Documentation-Driven: Comprehensive context preservation for future development
- Safety First: Read-only operations with comprehensive error handling
- Incremental Enhancement: Add features systematically with thorough validation
- Qualitative + Quantitative: Combine hard data with strategic context
Product Oracle v2 is released under the MIT License.
Copyright (c) 2025 Joshua A. Nelson (AsherJN)
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.
See the LICENSE file for the full license text.
Repository: github.com/AsherJN/product-oracle
Author: Joshua A. Nelson (@AsherJN)
Status: Production Ready (BETA)
For questions, feedback, or contributions, please open an issue or submit a pull request on GitHub.
Product Oracle v2
Transforming organizational intelligence through AI-powered multi-agent investigation