From fcc9227d3a7abc44be53855cc379e276a7970cc8 Mon Sep 17 00:00:00 2001 From: OwusuBlessing Date: Fri, 25 Jul 2025 21:01:01 +0100 Subject: [PATCH] first commit --- README.md | 255 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..65a52db --- /dev/null +++ b/README.md @@ -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. +