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
```python
# 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
```sql
-- 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

---

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