Benedwe/TradeNest-AI

TradeNest AI

Production-Ready AI Trade Intelligence Platform

TradeNest AI is a standalone AI trade intelligence platform that provides predictive analytics, clear business explanations, and visual insights (charts and graphs) for every analysis.

🎯 Core Philosophy

Every analytical response MUST return:

• ✅ Structured explanation (text)
• ✅ At least one graph
• ✅ At least one pie or distribution chart (when applicable)

No prediction is valid without visual support.

🏗️ Architecture

TradeNest AI
│
├── api/
│   └── routes.py              # API endpoints
├── core/
├── models/
├── preprocessing/
├── schemas/
│   ├── request_schemas.py     # Request validation
│   └── response_schemas.py     # Response models
├── services/
│   ├── prediction_service.py    # ML predictions
│   ├── explanation_service.py   # Business explanations
│   ├── visualization_service.py # Chart orchestration
│   └── web_data_service.py      # Optional web/data enrichment
├── visualizations/
│   ├── line_charts.py         # Line chart generation
│   ├── bar_charts.py          # Bar chart generation
│   └── pie_charts.py          # Pie chart generation
├── storage/
├── utils/
└── main.py                    # FastAPI application

📊 Visualization Pipeline

Technology Stack

• Matplotlib: Production-safe, backend-friendly visualization library
• Base64 Encoding: Charts returned as Base64 strings in JSON responses
• Non-interactive Backend: Uses Agg backend for server environments

Chart Types by Analysis

1️⃣ Demand Forecasting

• Line Graph: Historical sales vs predicted demand
• Pie Chart: Demand distribution by time period

2️⃣ Pricing Optimization

• Line Graph: Price vs sales volume (dual-axis)
• Pie Chart: Revenue contribution by price range

3️⃣ Sales Trend Analysis

• Bar Chart: Sales trend over time
• Pie Chart: Sales contribution by period or category

🚀 Quick Start

Installation

# Install dependencies
pip install -r requirements.txt

Run the Application

Option 1: FastAPI Backend Only

# Start the server
python main.py

# Or using uvicorn directly
uvicorn main:app --host 0.0.0.0 --port 8000

Option 2: Full Platform (FastAPI + Gradio)

# Run both backend and beautiful frontend
python run_platform.py

The applications will be available at:

• API: http://localhost:8000
• Gradio UI: http://localhost:7860
• API Docs: http://localhost:8000/docs

API Documentation

Interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🎨 Beautiful Gradio Interface

TradeNest AI features a stunning, user-friendly web interface built with Gradio:

Key Features

• 📊 Business Forecasting Dashboard: Interactive forecasting with visual charts
• 🌍 Country Intelligence: Detailed country information and analysis
• 🚢 Trade Analytics: Trade data visualization between countries
• 💹 Economic Indicators: IMF data integration with time-series charts
• 🎨 Modern UI: Gradient backgrounds, responsive cards, and professional styling

Interface Components

1. Business Forecasting Tab

   • Select business type (retail, manufacturing, tech, etc.)
   • Enter historical revenue data
   • Configure forecast horizon
   • View comprehensive forecasts with growth charts
   • Get business insights, risks, and opportunities

2. Country Intelligence Tab

   • Search by country code
   • View detailed country information
   • See flag and geographic data

3. Trade Analytics Tab

   • Analyze trade flows between countries
   • Filter by commodity and time period
   • View trade value and volume metrics

4. Economic Indicators Tab

   • Access IMF economic data
   • View time-series charts
   • Analyze GDP, inflation, unemployment, and more

📡 API Endpoints

POST /api/predict/demand

Forecast demand with visualizations.

Request:

{
  "historical_values": [100, 120, 110, 130, 125],
  "historical_dates": ["2024-01", "2024-02", "2024-03", "2024-04", "2024-05"],
  "periods_ahead": 4,
  "method": "moving_average"
}

Response:

{
  "insight_summary": "Strong growth expected: 15.2% increase in average demand",
  "explanation": "The line chart shows...",
  "predictions": {
    "values": [135.5, 138.2, 140.9, 143.6],
    "range": "135.50 - 143.60"
  },
  "confidence_level": "High",
  "visuals": {
    "line_chart": "base64_encoded_image...",
    "pie_chart": "base64_encoded_image..."
  }
}

POST /api/predict/price

Optimize price with visualizations.

Request:

{
  "prices": [10.0, 12.0, 11.0, 13.0, 12.5],
  "volumes": [1000, 800, 900, 700, 850],
  "target": "revenue"
}

Response:

{
  "insight_summary": "Optimal price identified: $12.00 for maximum revenue",
  "explanation": "The line chart displays the relationship...",
  "predictions": {
    "optimal_price": 12.0,
    "expected_volume": 800,
    "expected_revenue": 9600.0,
    "price_elasticity": 0.75,
    "recommendation": "Set price at $12.00 for maximum revenue"
  },
  "confidence_level": "Medium",
  "visuals": {
    "line_chart": "base64_encoded_image...",
    "pie_chart": "base64_encoded_image..."
  }
}

POST /api/analyze/trend

Analyze sales trend with visualizations.

Request:

{
  "values": [5000, 5500, 5200, 6000, 5800, 6200],
  "periods": ["Q1", "Q2", "Q3", "Q4", "Q5", "Q6"]
}

Response:

{
  "insight_summary": "Strong upward trend: 12.5% growth detected in sales performance",
  "explanation": "The trend chart provides a clear visual representation...",
  "predictions": {
    "trend_direction": "increasing",
    "growth_rate": 24.0,
    "trend_percentage": 12.5,
    "average": 5616.67,
    "volatility": 0.08,
    "range": "5000.00 - 6200.00"
  },
  "confidence_level": "High",
  "visuals": {
    "line_chart": "base64_encoded_image...",
    "pie_chart": "base64_encoded_image..."
  }
}

POST /api/country/info

Get detailed country information from Country API.

Request:

{
  "country_code": "TZ"
}

POST /api/country/search

Search for countries by name.

Request:

{
  "name": "Tanzania"
}

POST /api/trade/data

Get trade data between two countries.

Request:

{
  "reporter_code": "842",
  "partner_code": "156",
  "year": "2023",
  "commodity_code": "TOTAL",
  "trade_flow": "export"
}

POST /api/imf/indicator

Get IMF economic indicator data.

Request:

{
  "country_code": "US",
  "indicator": "NGDP_RPCH",
  "dataset": "IFS",
  "start_year": "2020",
  "end_year": "2024"
}

POST /api/forecast/business

Comprehensive business performance forecasting.

Request:

{
  "business_type": "retail",
  "country_code": "US",
  "historical_revenue": [100000, 120000, 115000, 130000, 140000, 135000],
  "forecast_horizon_months": 12,
  "include_external_factors": true
}

Response:

{
  "business_type": "retail",
  "country_code": "US",
  "country_name": "United States",
  "forecast_horizon_months": 12,
  "forecast": {
    "values": [145000, 150000, 155000, ...],
    "growth_rates": [5.2, 3.4, 3.3, ...],
    "cumulative_growth": 25.8
  },
  "insights": [
    "🚀 Strong growth expected: Average monthly growth of 4.2%",
    "🌍 Favorable macroeconomic environment: Country GDP growing at 2.1%"
  ],
  "risk_assessment": [
    "Moderate inflation creating cost pressures"
  ],
  "opportunities": [
    "E-commerce adoption still growing in emerging markets"
  ]
}

🔍 Response Format (MANDATORY)

Every endpoint returns JSON with this structure:

{
  "insight_summary": "Short business conclusion",
  "explanation": "Clear explanation referencing visible charts",
  "predictions": {
    "values": [...],
    "range": "numeric range"
  },
  "confidence_level": "High | Medium | Low",
  "visuals": {
    "line_chart": "base64_encoded_image",
    "pie_chart": "base64_encoded_image"
  }
}

No visuals → response is invalid.

📈 Visualization Details

Chart Generation Process

1. Data Validation: Input data is validated before chart generation
2. Chart Creation: Matplotlib generates charts with professional styling
3. Base64 Encoding: Charts are encoded as Base64 strings
4. Response Integration: Visuals are embedded in JSON responses

Chart Features

• Professional Styling: Seaborn-inspired color schemes
• High Resolution: 150 DPI for crisp visuals
• Clear Labels: Bold titles, axis labels, and legends
• Value Annotations: Data points labeled on charts
• Grid Lines: Subtle grid for easy reading

🧠 Explainability Rules

Explanations must:

• ✅ Reference what is visible in the charts
• ✅ Use business language (growth, decline, contribution)
• ✅ Avoid technical ML jargon
• ✅ Be quote-ready and structured

Example:

"The line chart shows consistent week-over-week growth, while the pie chart confirms that 60% of sales come from peak weeks."

🔒 Data Handling

• Strict Validation: Inputs validated using Pydantic schemas
• Error Handling: Clear error messages for insufficient data
• No Fabrication: Missing values are not fabricated
• Real Data Only: Charts reflect actual input data

🛠️ Development

Project Structure

• Services: Business logic and orchestration
• Visualizations: Chart generation utilities
• Schemas: Request/response validation
• API: FastAPI route handlers

Adding New Visualizations

1. Create chart function in appropriate module (line_charts.py, bar_charts.py, or pie_charts.py)
2. Add method to VisualizationService
3. Integrate into API endpoint
4. Update response schema if needed

📝 Example Usage

Python Client

import requests
import json
import base64
from PIL import Image
from io import BytesIO

# Make request
response = requests.post(
    "http://localhost:8000/api/predict/demand",
    json={
        "historical_values": [100, 120, 110, 130, 125],
        "periods_ahead": 4
    }
)

data = response.json()

# Decode and save charts
line_chart = base64.b64decode(data['visuals']['line_chart'])
pie_chart = base64.b64decode(data['visuals']['pie_chart'])

# Save images
with open('line_chart.png', 'wb') as f:
    f.write(line_chart)

with open('pie_chart.png', 'wb') as f:
    f.write(pie_chart)

print(data['insight_summary'])
print(data['explanation'])

cURL Example

curl -X POST "http://localhost:8000/api/predict/demand" \
  -H "Content-Type: application/json" \
  -d '{
    "historical_values": [100, 120, 110, 130, 125],
    "periods_ahead": 4
  }'

🎨 Visualization Pipeline Flow

Input Data
    ↓
Validation (Pydantic)
    ↓
Prediction Service
    ↓
Visualization Service
    ↓
Chart Generation (Matplotlib)
    ↓
Base64 Encoding
    ↓
Explanation Service
    ↓
JSON Response (with visuals)

⚠️ Important Notes

1. Visuals are Mandatory: Every response includes charts
2. No Notebooks: All code is production-ready Python
3. Backend-Safe: Uses non-interactive Matplotlib backend
4. Business Language: Explanations avoid technical jargon
5. Real Data Only: No synthetic data generation

📚 Dependencies

• fastapi: Web framework
• uvicorn: ASGI server
• pydantic: Data validation
• matplotlib: Visualization
• numpy: Numerical operations
• gradio: Beautiful web interface
• requests: API client
• pandas: Data manipulation

🚦 Status

✅ All core features implemented ✅ Visualization pipeline complete ✅ API endpoints functional ✅ Beautiful Gradio interface ready ✅ Country API integration ✅ Trade API integration ✅ IMF API integration ✅ Business forecasting engine ✅ Documentation ready

📄 License

MIT License

---

TradeNest AI shows its intelligence, not just says it.