README.md

---
title: VGTC Compliance API
emoji: 🌐
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: true
---

<div align="center">

# VGTC

### **AI Trade Compliance Platform**

**Automate import compliance. From document to audit trail in seconds.**

Upload a document or connect your ERP → Get HS codes, sanctions screening, and a compliance report with full audit trail.

[![Tests](https://img.shields.io/badge/tests-175%20passing-brightgreen?style=flat-square)]()
[![Python](https://img.shields.io/badge/python-3.11+-blue?style=flat-square)]()
[![License](https://img.shields.io/badge/license-Source%20Available-red?style=flat-square)]()
[![Backend](https://img.shields.io/badge/backend-Render.com-orange?style=flat-square)]()
[![Frontend](https://img.shields.io/badge/frontend-Cloudflare%20Pages-blue?style=flat-square)]()

[Try Live](https://vgtc.voraprotocol.com) • [API Docs](https://vgtc.onrender.com/docs) • [Contact](vedkumar755@gmail.com)

</div>

---

## The Problem

Import compliance takes 2-4 hours per document. Manual HS code lookups, sanctions checks, duty calculations. One misclassification = millions in penalties.

## The Solution

VGTC automates it end-to-end.

| Metric | Manual | VGTC |
|:-------|:------:|:----:|
| Time per document | 2-4 hours | **30 seconds** |
| Cost per check | $50-100 | **$0.50** |
| Setup time | 6-18 months | **10 minutes** |
| HS classification accuracy | ~70% | **75%+ (LLM-backed)** |
| Sanctions coverage | Partial | **OFAC SDN + EU Consolidated (local, free)** |

---

## Live Deployment

| Component | URL | Stack |
|:----------|:----|:------|
| Frontend | `https://vgtc.voraprotocol.com` | Next.js → Cloudflare Pages |
| Backend API | `https://vgtc.onrender.com` | FastAPI → Docker → Render |
| API Docs | `https://vgtc.onrender.com/docs` | Swagger UI |

---

## Workflow

```
1. Upload document / Connect ERP  → PDF, SAP S/4HANA, Odoo
2. AI extracts data                → Products, quantities, values, origins
3. HS code classification          → pyhscodes (6,940+ WCO) + DeepSeek LLM
4. Sanctions screening             → OFAC SDN + EU Consolidated (local, public domain)
5. Compliance report               → Full audit trail with SHA-256 hash chain
6. Human review                    → Dashboard with approve/reject workflow
```

---

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                        Cloudflare Pages                          │
│                   vgtc.voraprotocol.com (frontend)               │
└──────────────────────────┬───────────────────────────────────────┘
                           │ HTTPS
┌──────────────────────────▼───────────────────────────────────────┐
│                    Render.com (Docker)                            │
│                   vgtc.onrender.com (backend)                    │
├──────────────────────────────────────────────────────────────────┤
│  FastAPI Server (server.py)                                      │
│  ├── POST /api/v1/compliance/check    ← PDF upload pipeline     │
│  ├── POST /api/v1/integration/sap/trigger  ← SAP OData          │
│  ├── POST /api/v1/integration/odoo/trigger ← Odoo JSON-RPC      │
│  ├── GET  /api/v1/dashboard/queue     ← Review queue            │
│  └── POST /api/v1/dashboard/action    ← Approve/reject          │
├──────────────────────────────────────────────────────────────────┤
│  Core Engines                                                    │
│  ├── HS Classifier (1,405 lines)     ← pyhscodes + LLM hybrid   │
│  ├── Sanctions Engine (1,237 lines)  ← 8-layer phonetic match   │
│  ├── PDF Parser (807 lines)          ← pypdf extraction         │
│  ├── Dashboard Service (1,720 lines) ← PostgreSQL-backed queue  │
│  └── ERP Connector (726 lines)       ← SAP + Odoo integration   │
├──────────────────────────────────────────────────────────────────┤
│  Database: PostgreSQL (Render)                                   │
│  ├── compliance_review_items        ← Review items               │
│  └── compliance_audit_chain         ← SHA-256 hash chain         │
└──────────────────────────────────────────────────────────────────┘
```

---

## Core Engines

### HS Code Classifier (`hs_classifier.py` — 1,405 lines)

Hybrid classification engine with 3-tier caching:

| Tier | Source | Latency | Cost |
|:-----|:-------|:--------|:-----|
| 1 | In-memory LRU cache (2,048 entries) | ~0ms | Free |
| 2 | PostgreSQL ILIKE fuzzy match | ~5ms | Free |
| 3 | pyhscodes (6,940+ WCO codes) | ~10ms | Free (LGPL-2.1) |
| 4 | LLM (DeepSeek V4 Flash via OpenCode) | ~30-70s | Free tier |

**Enterprise features:**
- `classify_batch()` — async batch classification with `asyncio.Semaphore(5)` concurrency control
- Cross-validation between pyhscodes and LLM (LLM wins when confidence gap > 15%)
- Automatic dot/dash normalization in LLM responses
- Markdown code block stripping for raw LLM output
- Human review flagging for ambiguous terms

**Supported LLM providers:** DeepSeek, Qwen, OpenAI, Anthropic, Google Gemini

### Sanctions Engine (`sanctions.py` — 1,237 lines)

8-layer phonetic matching engine — no external API dependency:

| Layer | Method | Purpose |
|:------|:-------|:--------|
| 1 | Exact match | Perfect match |
| 2 | Normalized exact | Case/punctuation insensitive |
| 3 | Token sort | Word order variation |
| 4 | Partial match | Substring containment |
| 5 | Phonetic (Soundex) | Homophone matching |
| 6 | Phonetic (Metaphone) | Sound-alike matching |
| 7 | Levenshtein distance | Fuzzy spelling |
| 8 | Jaro-Winkler | Similarity scoring |

**Data sources:** OFAC SDN CSV + EU Consolidated XML (public domain, auto-downloaded)

### ERP Integration (`erp_connector.py` — 726 lines)

| ERP | Adapter | Lines | Protocol |
|:----|:--------|:------|:---------|
| SAP S/4HANA | `sap_adapter.py` | 891 | OData v2 |
| Odoo | `odoo_adapter.py` | 832 | JSON-RPC |

**Pipeline flow:** ERP → line items → async batch HS classification → sanctions screening → PostgreSQL persistence (ComplianceReviewItem + AuditChain)

**Mock mode:** Automatic when ERP credentials are missing — returns realistic sample data.

### Dashboard Service (`dashboard.py` — 1,720 lines)

PostgreSQL-backed review queue with:
- Tenant isolation (X-Tenant-ID header)
- Optimistic locking for concurrent updates
- SHA-256 hash chain audit trail
- In-memory fallback when database is unavailable

---

## Quick Start

```bash
# Clone
git clone https://github.com/mysterious75/VGTC.git
cd VGTC

# Install
pip install -e .

# Run demo (uses DeepSeek LLM — requires API key in .env)
python demo.py

# Run with your PDF
python demo.py --file your_invoice.pdf
```

### Configuration (`.env`)

```bash
# LLM — DeepSeek V4 Flash via OpenCode (free tier)
MODEL_PROVIDER=opencode
MODEL_API_KEY=sk-...
MODEL_NAME=deepseek-v4-flash
MODEL_BASE_URL=https://opencode.ai/zen/go/v1

# Database (Render PostgreSQL)
DATABASE_URL=postgresql+asyncpg://...

# Security
SECURITY_API_KEY=vgk_...
SECURITY_SECRET_KEY=...
```

---

## Tech Stack

| Layer | Technology |
|:------|:-----------|
| Language | Python 3.11+ |
| API Framework | FastAPI |
| HS Classification | pyhscodes (LGPL-2.1) + DeepSeek LLM |
| Phonetics | jellyfish (BSD-3) |
| PDF Parsing | pypdf (BSD-3) |
| Sanctions Data | OFAC SDN CSV + EU Consolidated XML |
| Database | PostgreSQL (SQLAlchemy async) |
| Frontend | Next.js 14 (Cloudflare Pages) |
| Backend Hosting | Docker → Render.com |
| DNS | Cloudflare |
| CI/CD | GitHub Actions |
| ERP Adapters | SAP S/4HANA (OData) + Odoo (JSON-RPC) |

---

## Project Structure

```
VGTC/
├── demo.py                          # One-command demo
├── src/hermes/
│   ├── tools/
│   │   ├── hs_classifier.py         # HS code classification (1,405 lines)
│   │   ├── sanctions.py             # Sanctions screening (1,237 lines)
│   │   ├── pdf_parser.py            # PDF extraction (807 lines)
│   │   ├── dashboard.py             # Review queue (1,720 lines)
│   │   ├── erp_connector.py         # SAP/Odoo bridge (726 lines)
│   │   ├── sanctions_scheduler.py   # 24h auto-refresh (197 lines)
│   │   └── __init__.py              # CompliancePipeline orchestrator
│   ├── api/
│   │   ├── server.py                # FastAPI server (1,114 lines)
│   │   └── routers/                 # API route modules
│   ├── database/
│   │   ├── models.py                # SQLAlchemy models (177 lines)
│   │   └── connection.py            # DB connection manager
│   ├── config/
│   │   └── settings.py              # Pydantic settings
│   ├── compliance/
│   │   ├── eu_ai_act.py             # EU AI Act compliance
│   │   └── gdpr.py                  # GDPR compliance
│   └── core/
│       ├── auth.py                  # Authentication
│       └── exceptions.py            # Exception hierarchy
├── mcp-servers/
│   ├── erp-gateway/
│   │   ├── sap_adapter.py           # SAP S/4HANA adapter (891 lines)
│   │   ├── odoo_adapter.py          # Odoo adapter (832 lines)
│   │   ├── models.py                # Shared Pydantic models
│   │   └── server.py                # MCP server
│   ├── government-portal/           # German gov integration
│   └── trade-solutions/             # Customs & logistics
├── tests/                           # 175 tests
│   ├── test_hs_classifier.py        # 37 tests
│   ├── test_sanctions.py            # 26 tests
│   ├── test_pdf_parser.py           # 33 tests
│   ├── test_dashboard.py            # 31 tests
│   ├── test_sanctions_scheduler.py  # 14 tests
│   └── test_erp_integrations.py     # 34 tests
├── frontend-nextjs/                 # Next.js 14 frontend
├── Dockerfile.vgtc                  # Multi-stage Docker build
├── .github/workflows/
│   └── keep-alive.yml               # Render keep-alive (every 25 min)
└── docs/
    ├── DEPLOYMENT_CLOUDFLARE_PAGES.md
    └── DEPLOYMENT_BACKEND_DOCKER.md
```

---

## API Endpoints

| Method | Path | Description | Auth |
|:-------|:-----|:------------|:-----|
| `POST` | `/api/v1/compliance/check` | Full pipeline (PDF → classify → screen) | Bearer + Tenant |
| `POST` | `/api/v1/integration/sap/trigger` | SAP order → compliance check | Bearer + Tenant |
| `POST` | `/api/v1/integration/odoo/trigger` | Odoo invoice → compliance check | Bearer + Tenant |
| `GET` | `/api/v1/dashboard/queue` | Review queue (paginated) | Bearer + Tenant |
| `POST` | `/api/v1/dashboard/action/{item_id}` | Approve/reject/request_info | Bearer + Tenant |
| `GET` | `/docs` | Swagger UI | None |
| `GET` | `/health` | Health check | None |

---

## Data Sources

| Source | Coverage | License | Cost |
|:-------|:---------|:--------|:-----|
| OFAC SDN | US Specially Designated Nationals | Public Domain | Free |
| EU Consolidated | EU Sanctions List | Open Data | Free |
| pyhscodes | 6,940+ WCO HS Codes | LGPL-2.1 | Free |
| UK HMT OFSI | UK Sanctions | Open Government | Free |
| UNSC | UN Security Council | UN Open Data | Free |

**Note:** OpenSanctions (CC BY-NC) is NOT used — commercial use requires paid license ($3,000+/year). All sanctions data is sourced directly from government databases (public domain).

---

## Development

```bash
# Run tests
python -m pytest tests/ -x -q

# Run specific engine tests
python -m pytest tests/test_hs_classifier.py -x -q
python -m pytest tests/test_sanctions.py -x -q
python -m pytest tests/test_erp_integrations.py -x -q

# Start dev server
uvicorn hermes.api.server:server --reload --port 8000
```

---

## Deployment

**Backend (Render):**
```bash
docker build -f Dockerfile.vgtc -t vgtc .
docker run -p 8000:8000 vgtc
```
- Auto-deployed from `main` branch
- Keep-alive via GitHub Actions (every 25 min)
- Auto-SSL, 512 MB RAM, shared CPU

**Frontend (Cloudflare Pages):**
- Static HTML from `frontend-nextjs/out/`
- Custom domain: `vgtc.voraprotocol.com`
- Global CDN, DDoS protection

---

## Roadmap

- [x] HS code classification (pyhscodes + LLM)
- [x] Sanctions screening (OFAC + EU local engine)
- [x] PDF parsing (pypdf, AGPL-free)
- [x] FastAPI server with auth
- [x] Compliance dashboard (PostgreSQL-backed)
- [x] SAP S/4HANA integration
- [x] Odoo integration
- [x] Async batch classification (Semaphore-5)
- [x] Semantic caching (memory + DB)
- [x] SHA-256 audit trail
- [x] Docker deployment
- [x] Cloudflare Pages frontend
- [x] Render.com backend
- [x] 175 tests passing
- [ ] PDF report generation
- [ ] EU TARIC live duty rates
- [ ] Multi-language support
- [ ] Webhook notifications
- [ ] SSO / SAML integration

---

## License

**Source Available License**

Code is visible for review. Commercial use requires written permission.

Built by [Ved Kumar](https://github.com/mysterious75) • vedkumar755@gmail.com

[![GitHub](https://img.shields.io/badge/GitHub-Medium-181717?style=for-the-badge&logo=github)](https://github.com/mysterious75/VGTC)

</div>