Hugging Face's logo

Spaces:
vora-sonnet
/
vgtc-api
Paused

App Files Community
vgtc-api / README.md
vora-sonnet's picture
vora-sonnet
Upload folder using huggingface_hub
0d3f7cc verified
preview code
|
Raw
History Blame Contribute Delete
14.7 kB
metadata 
title: VGTC Compliance API
emoji: 🌐
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: true

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 Python License Backend Frontend

Try Live • API Docs • Contact

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 

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

# 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 

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

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

  • HS code classification (pyhscodes + LLM)
  • Sanctions screening (OFAC + EU local engine)
  • PDF parsing (pypdf, AGPL-free)
  • FastAPI server with auth
  • Compliance dashboard (PostgreSQL-backed)
  • SAP S/4HANA integration
  • Odoo integration
  • Async batch classification (Semaphore-5)
  • Semantic caching (memory + DB)
  • SHA-256 audit trail
  • Docker deployment
  • Cloudflare Pages frontend
  • Render.com backend
  • 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 • vedkumar755@gmail.com

GitHub