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