# 🚀 MarketAgentHub: Marketplace-Ready Multi-Agent Suite

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](pyproject.toml)
[![License](https://img.shields.io/badge/license-Commercial%20%2F%20Apache--2.0-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
[![Tests](https://img.shields.io/badge/tests-17%20passed-success)](tests/)
[![Marketplace Ready](https://img.shields.io/badge/Marketplaces-AWS%20%7C%20Azure%20%7C%20GCP%20%7C%20Salesforce-orange)](marketagenthub/manifest.yaml)
[![A2A Compatible](https://img.shields.io/badge/protocol-A2A%201.0%20%7C%20MCP%201.0-purple)](marketagenthub/server.py)

**MarketAgentHub** is an institutional-grade, multi-agent artificial intelligence platform engineered for turnkey deployment, packaging, and monetization across the world's leading enterprise marketplaces:
- **AWS Marketplace** (Amazon Bedrock Agent Action Groups)
- **Google Cloud Marketplace** (Vertex AI Extensions)
- **Microsoft Azure Marketplace** (Azure AI Agent Service)
- **Salesforce AppExchange** (Agentforce Topics & Actions)

---

## 📑 Table of Contents
- [Architectural Overview](#-architectural-overview)
- [Core Agent Trio](#-core-agent-trio)
- [Multi-Marketplace Packaging & Adapters](#-multi-marketplace-packaging--adapters)
- [Monetization & Revenue Potential](#-monetization--revenue-potential)
- [A2A & MCP Protocol Interoperability](#-a2a--mcp-protocol-interoperability)
- [Quickstart & Local Installation](#-quickstart--local-installation)
- [Docker & Kubernetes Deployment](#-docker--kubernetes-deployment)
- [API Reference](#-api-reference)
- [Verification & Automated Tests](#-verification--automated-tests)
- [Arabic Documentation (التوثيق باللغة العربية)](#-arabic-documentation)

---

## 🏛️ Architectural Overview

MarketAgentHub executes an autonomous, regulated financial advisory pipeline. Each agent specializes in a distinct vertical while collaborating over a standardized **Agent-to-Agent (A2A)** event bus:

```mermaid
graph TD
    Client[Marketplace Subscriber / External System] --> Gateway[FastAPI Gateway / MCP Server]
    Gateway --> Metering[Marketplace Metering Engine]
    
    subgraph Multi-Agent Autonomous Pipeline
        Metering --> Portfolio[1. PortfolioAgent<br/>Quantitative Analytics & Rebalancing]
        Portfolio --> Compliance[2. ComplianceAgent<br/>SEC, FINRA, MiFID II, GDPR Audit]
        Compliance --> Engagement[3. ClientEngagementAgent<br/>Bilingual Executive Briefing EN / AR]
    end
    
    Engagement --> Output[Delivered Advisory Briefing + CRM Sync]
    
    subgraph Marketplace Adapters & Metering
        Gateway -.-> AWS[AWS Bedrock Action Groups]
        Gateway -.-> GCP[Google Vertex AI Extensions]
        Gateway -.-> Azure[Azure AI Agent Service]
        Gateway -.-> SFDC[Salesforce Agentforce Topics]
    end
```

---

## 🤖 Core Agent Trio

### 1. 📈 `PortfolioAgent`
- **Role**: Quantitative investment analysis, risk modeling, and asset rebalancing.
- **Capabilities**:
  - Calculates total portfolio valuation and percentage allocation by asset class and sector.
  - Estimates Sharpe ratios, daily Value at Risk (VaR 95%), and annualized volatility.
  - Evaluates client target risk profiles (`CONSERVATIVE`, `MODERATE`, `GROWTH`, `AGGRESSIVE`).
  - Generates automated capital rebalancing recommendations (e.g. trimming equity overconcentration, cash drag optimization).

### 2. 🛡️ `ComplianceAgent`
- **Role**: Real-time legal and regulatory auditing across major financial jurisdictions.
- **Capabilities**:
  - **SEC Reg-BI (Best Interest)**: Validates suitability and disclosure transparency.
  - **FINRA Rule 2111 & Rule 2210**: Enforces risk-tolerance alignment and senior investor protections.
  - **MiFID II Suitability**: Confirms institutional variance and diversification ceilings.
  - **GDPR Art. 17 & PII Scrubbing**: Redacts sensitive data (SSN, emails, accounts) before logging.
  - Issues cryptographic audit trail IDs (`AUDIT-SEC-XXXXXX`) and legally mandated disclaimers.

### 3. 💬 `ClientEngagementAgent`
- **Role**: Multilingual client communication and CRM synchronization.
- **Capabilities**:
  - Synthesizes executive briefings in **English** and pristine, native **Arabic** (`ar`).
  - Adapts tone for high-net-worth individuals, institutional boards, and retail investors.
  - Generates turnkey sync payloads for **Salesforce Financial Services Cloud (FSC)** and **HubSpot CRM**.

---

## 🌐 Multi-Marketplace Packaging & Adapters

MarketAgentHub includes production adapters for seamless listing and automated provisioning:

| Marketplace | Agent Artifact | Metering Dimension | Adapter Module |
| :--- | :--- | :--- | :--- |
| **AWS Marketplace** | Bedrock Action Group (OpenAPI 3.0) | `AgentTaskInvocations` | [`marketagenthub.adapters.aws`](marketagenthub/adapters/aws.py) |
| **Google Cloud Marketplace** | Vertex AI Extension Manifest | `marketagenthub.googleapis.com/invocations` | [`marketagenthub.adapters.gcp`](marketagenthub/adapters/gcp.py) |
| **Microsoft Azure Marketplace** | Azure AI Tool Functions | `StandardExecutionUnits` | [`marketagenthub.adapters.azure`](marketagenthub/adapters/azure.py) |
| **Salesforce AppExchange** | Agentforce Autonomous Topic & Actions | `ActiveSubscriberSeats` | [`marketagenthub.adapters.salesforce`](marketagenthub/adapters/salesforce.py) |

---

## 💰 Monetization & Revenue Potential

MarketAgentHub provides a multi-stream monetization model suitable for SaaS ISVs, consulting partners, and FinTech enterprises:

```
┌────────────────────────────────────────────────────────────────────────┐
│                        Monetization Strategy                           │
├────────────────────────────────────────────────────────────────────────┤
│ 1. SaaS Subscriptions:                                                 │
│    • Starter Tier:    $499 / month  (up to 2,500 advisory executions)   │
│    • Pro Tier:        $1,999 / month (up to 25,000 executions)          │
│    • Enterprise Tier: $4,999 / month (up to 100,000 executions + SLA)  │
│                                                                        │
│ 2. Usage-Based Metering (Overage):                                     │
│    • $0.15 per end-to-end multi-agent advisory run                     │
│    • $0.05 per standalone regulatory compliance audit                   │
│                                                                        │
│ 3. Marketplace Private Offers (AWS CPPO / Azure Private Plans):        │
│    • Custom multi-year enterprise contracts ($50k - $250k ARR)          │
│    • Drawdown against cloud customer pre-committed spend (MACC / EDP)   │
│                                                                        │
│ 4. White-Label & Resale:                                               │
│    • Reusable agent components embeddable into wealth management apps  │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 🔄 A2A & MCP Protocol Interoperability

All agents support the **Agent-to-Agent (A2A)** message envelope:
- **Discovery Endpoint**: `GET /.well-known/agent.json`
- **A2A Invocations**: `POST /api/v1/a2a/message`
- **Standardized Payloads**: JSON Schema contracts with cryptographic audit trails.

---

## ⚡ Quickstart & Local Installation

### Prerequisites
- Python `>=3.10`

### 1. Clone & Setup
```bash
git clone https://github.com/fintech-intel/marketagenthub.git
cd marketagenthub
pip install -r requirements.txt
```

### 2. Launch Local Server
```bash
uvicorn marketagenthub.server:app --reload --port 8000
```
Visit the interactive Swagger UI at: `http://localhost:8000/docs`

---

## 🐳 Docker & Kubernetes Deployment

### Run with Docker Compose
```bash
docker-compose up -d --build
```

### Deploy to Kubernetes with Helm
```bash
helm install marketagenthub ./helm -n agents --create-namespace
```

---

## 🔌 API Reference

### Health & Discovery
- `GET /healthz` - Health probe endpoint
- `GET /readyz` - Readiness probe endpoint
- `GET /.well-known/agent.json` - A2A Agent Discovery Manifest

### Cloud Marketplace Adapters
- `GET /api/v1/adapters/{cloud}` - Retrieve OpenAPI/Tool schema for `aws`, `azure`, `gcp`, or `salesforce`

### Multi-Agent Orchestration
- `POST /api/v1/orchestrate` - Execute complete advisory, compliance, and briefing pipeline.

**Example Request:**
```json
{
  "customer_id": "cust-enterprise-01",
  "client_profile": {
    "risk_tolerance": "MODERATE",
    "age": 42
  },
  "holdings": [
    {"symbol": "AAPL", "shares": 50, "price": 180.0, "sector": "Technology"},
    {"symbol": "BND", "shares": 100, "price": 75.0, "sector": "Fixed Income"},
    {"symbol": "USD", "shares": 1500, "price": 1.0, "sector": "Cash"}
  ],
  "language": "ar"
}
```

---

## 🧪 Verification & Automated Tests

Execute the complete pytest suite:
```bash
pytest tests/ -v
```
Output:
```
tests/test_agents.py::test_portfolio_agent_moderate PASSED
tests/test_agents.py::test_portfolio_agent_empty PASSED
tests/test_agents.py::test_compliance_agent_audit PASSED
tests/test_agents.py::test_compliance_pii_scrubbing PASSED
tests/test_agents.py::test_engagement_agent_english PASSED
tests/test_agents.py::test_engagement_agent_arabic PASSED
tests/test_marketplace.py::test_full_pipeline_flow_balanced PASSED
tests/test_marketplace.py::test_full_pipeline_flow_warnings PASSED
tests/test_marketplace.py::test_pipeline_unlicensed PASSED
tests/test_marketplace.py::test_metering_engine_quota PASSED
tests/test_marketplace.py::test_cloud_adapters_schemas PASSED
tests/test_server.py::test_healthz PASSED
tests/test_server.py::test_readyz PASSED
tests/test_server.py::test_a2a_manifest PASSED
tests/test_server.py::test_adapter_endpoint_aws PASSED
tests/test_server.py::test_orchestration_api PASSED
tests/test_server.py::test_a2a_message_endpoint PASSED
============================= 17 passed in 0.50s ==============================
```

---

## 🧭 Agentic AI Alignment

MarketAgentHub packages three cooperating specialists as one deployable unit:
- **Autonomy** — `PortfolioAgent`, `ComplianceAgent`, and `ClientEngagementAgent`
  each act on their own domain (rebalancing, audit, client comms) and hand off
  through the A2A/MCP pipeline without a human in the loop for every step.
- **Resilience** — `ComplianceAgent` scrubs PII before logging and issues
  cryptographic audit trail IDs for every decision, so a compliance review
  can always be reconstructed after the fact.
- **Adaptivity** — the same trio redeploys unmodified across AWS, Azure, GCP,
  and Salesforce marketplace adapters, and `ClientEngagementAgent` adapts
  tone and language (English/Arabic) per audience.

## 📈 Roadmap
- [ ] Add marketplace adapters beyond AWS / Azure / GCP / Salesforce
- [ ] Extend `ComplianceAgent` to further jurisdictions beyond SEC/FINRA/MiFID II/GDPR
- [ ] Deepen integration with the sibling agent repos (ContextX,
      GuardrailAI, WorkforceAI)

## 👨‍💻 Author
Built by **Asadullah Shafique**

🔗 Explore my portfolio showcasing Agentic AI projects and real-world applications:
[asadullahshafique-devunity.vercel.app](https://asadullahshafique-devunity.vercel.app)

---

## 🌍 Arabic Documentation

For full documentation in Arabic, see [`README.ar.md`](README.ar.md).