You can deploy this model and start earning money today!

Benedwe/
TradeNest-AI

Views

No views yet

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

bash

# Install dependencies
pip install -r requirements.txt

Run the Application

Option 1: FastAPI Backend Only

bash

# 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)

bash

# 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

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
Country Intelligence Tab
- Search by country code
- View detailed country information
- See flag and geographic data
Trade Analytics Tab
- Analyze trade flows between countries
- Filter by commodity and time period
- View trade value and volume metrics
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:

json

{
  "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:

json

{
  "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:

json

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

Response:

json

{
  "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:

json

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

Response:

json

{
  "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:

json

{
  "country_code": "TZ"
}

POST `/api/country/search`

Search for countries by name.

Request:

json

{
  "name": "Tanzania"
}

POST `/api/trade/data`

Get trade data between two countries.

Request:

json

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

POST `/api/imf/indicator`

Get IMF economic indicator data.

Request:

json

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

POST `/api/forecast/business`

Comprehensive business performance forecasting.

Request:

json

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

Response:

json

{
  "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:

json

{
  "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

Data Validation: Input data is validated before chart generation
Chart Creation: Matplotlib generates charts with professional styling
Base64 Encoding: Charts are encoded as Base64 strings
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

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

📝 Example Usage

Python Client

python

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

bash

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

Visuals are Mandatory: Every response includes charts
No Notebooks: All code is production-ready Python
Backend-Safe: Uses non-interactive Matplotlib backend
Business Language: Explanations avoid technical jargon
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.

Benedwe/TradeNest-AI

TradeNest AI

🎯 Core Philosophy

🏗️ Architecture

📊 Visualization Pipeline

Technology Stack

Chart Types by Analysis

1️⃣ Demand Forecasting

2️⃣ Pricing Optimization

3️⃣ Sales Trend Analysis

🚀 Quick Start

Installation

Run the Application

Option 1: FastAPI Backend Only

Option 2: Full Platform (FastAPI + Gradio)

API Documentation

🎨 Beautiful Gradio Interface

Key Features

Interface Components

📡 API Endpoints

POST /api/predict/demand

POST /api/predict/price

POST /api/analyze/trend

POST /api/country/info

POST /api/country/search

POST /api/trade/data

POST /api/imf/indicator

POST /api/forecast/business

🔍 Response Format (MANDATORY)

📈 Visualization Details

Chart Generation Process

Chart Features

🧠 Explainability Rules

🔒 Data Handling

🛠️ Development

Project Structure

Adding New Visualizations

📝 Example Usage

Python Client

cURL Example

🎨 Visualization Pipeline Flow

⚠️ Important Notes

📚 Dependencies

🚦 Status

📄 License

Benedwe/
TradeNest-AI

POST `/api/predict/demand`

POST `/api/predict/price`

POST `/api/analyze/trend`

POST `/api/country/info`

POST `/api/country/search`

POST `/api/trade/data`

POST `/api/imf/indicator`

POST `/api/forecast/business`