Content
<div align="center">
# HERMES - AI for GTC
### *Global Trade Compliance*
**AI for GTC** — Autonomous AI agents for global trade compliance.
**AI agents that automate compliance research, ERP integration, and regulatory reporting — saving enterprises 1000s of hours and preventing million-dollar penalties.**
[]()
[]()
[]()
[]()
[Website](https://mysterious75.github.io/HERMES-AI-for-GTC/) • [Documentation](#quick-start) • [API Reference](#api-endpoints) • [Contact](#contact)
</div>
---
## The Problem
Global trade compliance is broken. Every day, compliance teams manually:
- Track tariff changes across **190+ countries**
- Verify HS code classifications against ERP data
- Generate customs declarations and audit reports
- Monitor EU AI Act, GDPR, and sanctions compliance
**One misclassification costs millions.** Rules change weekly. Manual tracking is impossible at scale.
## The Solution
Hermes replaces this manual work with **LLM-driven AI agents** that research, verify, and report — with full audit trails.
<div align="center">
| Metric | Before Hermes | After Hermes |
|:-------|:-------------:|:------------:|
| **Time per shipment** | 4-6 hours | **~30 seconds** |
| **Accuracy** | Human error | **AI-assisted verification** |
| **Cost per check** | $50-200 | **Near zero** |
| **Country coverage** | 1-2 max | **Multi-country support** |
| **Audit documentation** | Manual | **Auto-generated** |
| **Availability** | Business hours | **24/7** |
</div>
---
## Who This Is For
<table>
<tr>
<td width="33%">
**Import/Export Companies**
Tariff classification, duty optimization
Manual HS code lookups across 190+ countries
</td>
<td width="33%">
**Customs Brokers**
Declaration prep, compliance checks
High-volume document verification
</td>
<td width="33%">
**Manufacturers**
Supply chain compliance, origin verification
Multi-country regulatory tracking
</td>
</tr>
<tr>
<td>
**Compliance Consultancies**
Client advisory, audit prep
Research-intensive, time-consuming
</td>
<td>
**ERP System Integrators**
SAP/Odoo compliance modules
Bridging ERP data with regulatory requirements
</td>
<td>
**Government/Regulatory Bodies**
Compliance monitoring, enforcement
Processing thousands of declarations
</td>
</tr>
</table>
---
## Target Use Cases
<table>
<tr>
<td width="50%">
**German Automotive Exporter**
Auto-check shipments against EU dual-use regulations, SAP inventory, and destination country tariffs.
</td>
<td width="50%">
**Vietnamese Electronics Manufacturer**
Monitor US tariff changes on HS 8542 (semiconductors) and get alerts before shipments are affected.
</td>
</tr>
<tr>
<td>
**UK Customs Brokerage**
Pre-fill customs declarations by cross-referencing ERP data with HMRC requirements.
</td>
<td>
**EU Trade Compliance Firm**
Generate EU AI Act compliance reports for clients deploying high-risk AI systems.
</td>
</tr>
</table>
---
## Core Capabilities
<table>
<tr>
<td width="50%">
### Autonomous Research
Multi-step research across connected data sources. Agents navigate complex workflows with minimal human intervention.
</td>
<td width="50%">
### ERP Integration
SAP S/4HANA (OAuth2, V2/V4 OData) and Odoo (JSON-RPC) adapters with mock + live modes. Pull inventory, verify orders, cross-reference compliance data.
</td>
</tr>
<tr>
<td>
### Trade Documentation
HS code lookup, sanctions screening, export compliance validation, and automated customs declaration generation.
</td>
<td>
### Compliance Enforcement
EU AI Act risk classification, human oversight management, GDPR PII detection/redaction, consent management, retention enforcement, and SHA-256 audit trails.
</td>
</tr>
<tr>
<td>
### MCP Protocol
Model Context Protocol — the industry standard for tool access. Connect any MCP server for ERP, government portals, or custom integrations.
</td>
<td>
### Persistent Memory
Agents store findings from past queries for reuse. Vector search across your compliance knowledge base via Qdrant (optional).
</td>
</tr>
</table>
---
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ CLI • API • Web UI • Streamlit │
└─────────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────────┐
│ FASTAPI SERVER │
│ Security Middleware • Auth • Rate Limiting │
└─────────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────────┐
│ ORCHESTRATOR AGENT │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐ │
│ │ Research │ │ Code │ │ Security │ │ Planning │ │Report│ │
│ │ Agent │ │ Analysis │ │ Agent │ │ Agent │ │Agent │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────┘ │
└─────────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────────┐
│ MCP PROTOCOL (JSON-RPC 2.0) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ERP Gateway │ │ Government │ │ Trade │ │
│ │ SAP • Odoo │ │ ELSTER • API │ │ Customs │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────────┐
│ MEMORY (Qdrant → Redis → JSON) • OBSERVABILITY (OpenTelemetry)│
└─────────────────────────────────────────────────────────────────┘
```
---
## Quick Start
```bash
# Clone the repository
git clone https://github.com/mysterious75/HERMES-AI-for-GTC.git
cd HERMES-AI-for-GTC
# Configure environment
cp .env.example .env
# Edit .env — add your LLM API key (OpenRouter, OpenAI, or Anthropic)
# Run with Docker (recommended)
docker-compose up
# Or run locally
pip install -e .
hermes serve # API on :8000
streamlit run app.py # Web UI on :8501
python chat.py # Interactive CLI
```
---
## API Endpoints
| Method | Endpoint | Description |
|:------:|:---------|:------------|
| `GET` | `/health` | Health check |
| `GET` | `/metrics` | Observability metrics |
| `POST` | `/api/v1/research` | Execute compliance research query |
| `POST` | `/api/v1/analyze-repo` | Analyze code repository |
| `POST` | `/api/v1/security-scan` | Security vulnerability scan |
| `POST` | `/api/v1/run-agent` | Run agent with strategy (react/debate/swarm) |
| `GET` | `/api/v1/agents` | List available agents |
| `POST` | `/api/v1/mcp/tools/list` | List MCP tools |
| `POST` | `/api/v1/mcp/tools/call` | Call MCP tool directly |
---
## Enterprise Integration
<table>
<tr>
<td>
**ERP Systems**
| System | Protocol | Status |
|:-------|:---------|:------:|
| SAP S/4HANA | OData v2/v4 | ✅ Beta |
| Odoo ERP | JSON-RPC | ✅ Beta |
| Oracle NetSuite | REST | 🔜 Planned |
| Microsoft Dynamics | OData | 🔜 Planned |
</td>
<td>
**Government Portals**
| Portal | Protocol | Status |
|:-------|:---------|:------:|
| ELSTER (Germany) | SOAP/REST | 🔄 Demo |
| BundesAPI (Germany) | REST | 🔄 Demo |
| US CSL | REST API | 🔜 Planned |
| EU TARIC | Open Data | 🔜 Planned |
</td>
<td>
**Compliance Frameworks**
| Framework | Status |
|:----------|:------:|
| EU AI Act | ✅ Enforcement |
| GDPR | ✅ Enforcement |
| OFAC Sanctions | ✅ Screening |
| UFLPA (Forced Labor) | 🔜 Planned |
| CBAM (Carbon Border) | 🔜 Planned |
</td>
</tr>
</table>
---
## Tech Stack
<table>
<tr>
<td>
**Runtime**
- Python 3.11+
- FastAPI + Uvicorn
- React + Vite + Tailwind
</td>
<td>
**AI & ML**
- OpenAI / Anthropic / OpenRouter
- 100+ models via OpenRouter
- 6 reasoning patterns
</td>
<td>
**Data & Storage**
- Qdrant (vector search)
- Redis (cache)
- PostgreSQL
</td>
</tr>
<tr>
<td>
**Protocol**
- MCP (JSON-RPC 2.0)
- 3 demo MCP servers
- 8 default tools
</td>
<td>
**Infrastructure**
- Docker Compose
- Kubernetes
- Terraform (AWS)
</td>
<td>
**Observability**
- OpenTelemetry
- /metrics endpoint
- Distributed tracing
</td>
</tr>
</table>
---
## Security
<table>
<tr>
<td width="50%">
| Category | Protection |
|:---------|:-----------|
| Authentication | API key via Bearer header, `secrets.compare_digest()` |
| RCE Prevention | Python executor: `__import__` blocked, 18 modules nullified |
| Path Traversal | `Path.relative_to()` checks in all file operations |
| Prompt Injection | `[USER_QUERY]` boundary markers + instruction guard |
</td>
<td width="50%">
| Category | Protection |
|:---------|:-----------|
| Info Disclosure | Generic error messages, no credential leak |
| Security Headers | HSTS, X-Frame-Options, X-Content-Type-Options |
| Rate Limiting | Sliding window (configurable) |
| MCP Whitelist | Safe tools only — dangerous tools blocked |
</td>
</tr>
</table>
---
## Test Suite
```bash
pip install -e ".[dev]"
python -m pytest tests/ -v
```
**257 tests** across 15 test files — **100% passing**.
<table>
<tr>
<td>
| Suite | Tests |
|:------|:-----:|
| API Integration | 33 |
| Security | 23 |
| Workflow E2E | 21 |
| MCP Protocol | 26 |
</td>
<td>
| Suite | Tests |
|:------|:-----:|
| Agents | 9 |
| Unit Tests | 145 |
| **Total** | **257** |
</td>
</tr>
</table>
---
## Deployment
<table>
<tr>
<td width="33%">
### Docker Compose
```bash
docker-compose up
```
Spins up: Hermes Agent, PostgreSQL, Redis, Qdrant, 3 MCP servers, Temporal, OpenTelemetry.
</td>
<td width="33%">
### Kubernetes
Manifests in `infrastructure/kubernetes/` — namespace, deployments, services, HPA, NetworkPolicy.
</td>
<td width="33%">
### Terraform (AWS)
Production infrastructure in `infrastructure/terraform/` — VPC, RDS, ElastiCache, GPU instances for vLLM.
</td>
</tr>
</table>
---
## Roadmap
- [ ] Real-time tariff tracker (government API integration)
- [ ] Compliance risk scoring per shipment
- [ ] Audit trail visualization dashboard
- [ ] Slack/Teams integration for alerts
- [ ] Multi-tenant architecture
- [ ] Additional ERP connectors (Microsoft Dynamics, NetSuite)
- [ ] Customs API integrations (ACE, ICS2, Zoll)
- [ ] CBAM carbon border reporting
- [ ] UFLPA forced labor screening
---
## Contact
**Hermes Platform** — Built for global trade compliance.
[](https://github.com/mysterious75/HERMES-AI-for-GTC)
[](https://mysterious75.github.io/HERMES-AI-for-GTC/)
---
<div align="center">
**MIT License** • Built with precision.
</div>
