MABIS-Multi-Agent-Business-Intelligence-System/README.md

MABIS - Multi-Agent Business Intelligence System

##Business Context & Use Case

Scenario: Build an AI-powered business intelligence platform for a retail company that needs to analyze sales performance, competitor landscape, and market trends. The system handles complex analytical queries that require:

• Database analysis of sales/inventory data
• Competitive intelligence through web research
• Data visualization and trend analysis
• Multi-source data synthesis and insights

Example Query: "Show me our Q4 smartphone sales performance compared to competitors, identify market trends from recent news, and create visualizations showing our position vs Apple and Samsung pricing strategies."

This requires database querying, web research, visualization generation, and intelligent coordination between specialized agents.

Technical Architecture Requirements

Infrastructure Setup (Required)

1. SQLite Database Setup

Create and populate a mock retail database with:

Tables Required:

• products (id, name, category, brand, price, launch_date)
• sales (id, product_id, quantity, revenue, sale_date, region)
• inventory (id, product_id, stock_level, warehouse_location)
• competitors (id, company_name, product_name, price, market_share)

Sample Data: Include realistic data for smartphones, laptops, accessories with:

• Your company's products and sales data
• Competitor products (Apple, Samsung, Google, etc.)
• 6-12 months of sales history
• Multiple regions/markets

2. Multi-Agent System Architecture

Database Agent

• Purpose: Query SQLite database for sales, inventory, and product data
• Tools: SQL query execution, data aggregation, trend analysis
• Memory: Remember previous queries and results
• Implementation: SQLAlchemy/sqlite3 + query optimization

** Research Agent**

• Purpose: Web search for competitor intelligence and market trends
• Tools: Web search API integration (Tavily, SerpAPI, or Brave Search)
• Memory: Cache search results, track research topics
• Implementation: HTTP requests + result parsing

Visualization Agent

• Purpose: Create charts, graphs, and visual analytics
• Tools: Matplotlib, Plotly, or Seaborn for chart generation
• Memory: Remember chart preferences and previous visualizations
• Implementation: Dynamic chart generation based on data and requirements

Orchestrator Agent

• Purpose: Route queries, coordinate agent workflows, synthesize results
• Tools: Agent coordination, task decomposition, result aggregation
• Memory: Track conversation context and agent handoffs
• Implementation: LLM-powered routing with clear decision logic

Core Implementation Requirements

Phase 1: Database & Infrastructure

• SQLite database design and setup
• Sample data generation (realistic retail/tech data)
• Database connection and basic query functions
• Data validation and integrity checks

Phase 2: Agent Development

• Database Agent with SQL query capabilities
• Research Agent with web search integration
• Visualization Agent with chart generation
• Basic orchestrator for agent routing
• Memory management system for each agent

Phase 3: Integration & UI

• Agent coordination and workflow management
• Streamlit or FastAPI interface
• Error handling and validation
• Demo scenarios and testing

Required Python Tech Stack

Core Framework

# Database Layer
- SQLite3 / SQLAlchemy for database operations
- Pandas for data manipulation and analysis
- Faker for generating realistic sample data

# AI/LLM Integration  
- OpenAI API / Anthropic Claude for agent intelligence
- LangChain (optional) for agent orchestration
- Custom prompt engineering for each agent

# Web Search Integration
- requests for HTTP calls
- BeautifulSoup for HTML parsing
- One of: Tavily API, SerpAPI, Brave Search API

# Visualization Tools
- Matplotlib for static charts
- Plotly for interactive visualizations
- Seaborn for statistical plots

# Web Interface
- A single interface where user can query the agent
FastAPI + Jinja2 templates for more control

# Memory & Caching
- JSON files for simple persistence
- Redis (optional) for session management

Database Schema Example

-- Products table
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    brand TEXT NOT NULL,
    price DECIMAL(10,2),
    launch_date DATE,
    specifications JSON
);

-- Sales table  
CREATE TABLE sales (
    id INTEGER PRIMARY KEY,
    product_id INTEGER,
    quantity INTEGER,
    revenue DECIMAL(10,2),
    sale_date DATE,
    region TEXT,
    FOREIGN KEY (product_id) REFERENCES products (id)
);

-- Add other tables as specified above

Detailed Deliverables

1. Code Structure should be clean and modular(Required)

2. Documentation Requirements

README.md (Must Include)

• Project overview and business context
• Quick start guide (< 5 minutes to run)
• Environment setup and dependencies
• Example queries and expected outputs
• Architecture overview with diagrams
• API key setup instructions

ARCHITECTURE.md (Must Include)

• System design principles and decisions
• Agent responsibilities and interactions
• Database design rationale
• Tool integration architecture
• Memory management strategy
• Scalability considerations

SETUP.md (Must Include)

• Step-by-step installation guide
• Database initialization process
• API key configuration
• Troubleshooting common issues
• Development vs production setup

3. Visual Documentation (Required)

System Architecture Diagram

• Show agent interactions and data flow
• Include external APIs and database connections
• Illustrate memory management
• Tools: Draw.io, Lucidchart, or Mermaid

Agent Flow Diagram

• Visualize query routing logic
• Show agent handoff scenarios
• Include decision points and error handling
• Demonstrate the example query workflow

Database Schema Diagram

• Entity relationship diagram
• Table relationships and foreign keys
• Index strategy visualization
• Sample data distribution

Test Scenarios & Success Criteria

Primary Test Query

Input: "Show me our Q4 smartphone sales performance compared to competitors, identify market trends from recent news, and create visualizations showing our position vs Apple and Samsung pricing strategies."

Expected Workflow:

1. Orchestrator: Breaks down into database query + research + visualization tasks
2. Database Agent: Queries Q4 smartphone sales, calculates performance metrics
3. Research Agent: Searches for Apple/Samsung pricing news and market trends
4. Visualization Agent: Creates comparative charts and trend graphs
5. Orchestrator: Synthesizes results into comprehensive response

Secondary Test Queries

• "What are our top 5 performing products by region and how do inventory levels look?"
• "Find recent news about foldable phone market and show how our Galaxy competitor pricing compares"
• "Create a dashboard showing monthly sales trends with competitor market share analysis"

Evaluation Criteria

Technical Implementation

• Database Design: Proper schema, realistic data, efficient queries
• Code Architecture: Clean separation of concerns, proper error handling
• Agent Implementation: Well-defined responsibilities, effective tool usage
• Integration Quality: Smooth coordination between components

AI/LLM Integration

• Prompt Engineering: Effective agent instructions and context management
• Tool Usage: Proper SQL generation, web search optimization, chart creation
• Memory Management: Context preservation for agent interactions
• Intelligence: Smart routing and decision making

Data & Visualization

• Database Quality: Realistic, well-structured sample data
• Query Efficiency: Optimized SQL queries and data processing
• Visualization Design: Clear, informative charts and graphs
• Web Research: Relevant, current information retrieval

Documentation & Setup

• Code Documentation: Clear comments, docstrings, type hints
• Architecture Docs: Comprehensive design documentation
• Setup Process: Easy installation and configuration
• Diagrams: Clear visual representation of system design

Web Search APIs (Choose One)

• Tavily API: AI-optimized search, good for research tasks
• SerpAPI: Google search results, comprehensive data
• Brave Search API: Privacy-focused, good free tier

Sample Data Sources

• Use Faker library for realistic data generation
• Tech product datasets from Kaggle (for reference)
• Mock competitor pricing from public sources

LLM Services

• OpenAI GPT-4o-mini: Cost-effective for development
• Anthropic Claude 3.5 Haiku: Good alternative option
• Budget: ~$5-10 for entire assessment period

---

Good luck! We're excited to see your approach to building intelligent data-driven systems.