first commit

2025-07-25 21:01:01 +01:00
commit fcc9227d3a
1 changed files with 255 additions and 0 deletions
@@ -0,0 +1,255 @@
+# 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
+- Budget: ~$5-10 for entire assessment period
+
+---
+
+Good luck! We're excited to see your approach to building intelligent data-driven systems.
+