Sovereign Order Intelligence - Complete Documentation

AI-Powered Supply Chain & Vendor Management 100% Python • Local LLM Deployment • Zero Cloud Dependency

---

Table of Contents

1. Overview
2. Architecture
3. Installation
4. Configuration
5. Quick Start
6. API Reference
7. CLI Reference
8. Web UI Guide
9. Core Modules
10. LangGraph Workflow
11. Document Processing
12. Vendor Grading
13. Web Research
14. Testing
15. Docker Deployment
16. Troubleshooting

---

Overview

Sovereign Order Intelligence (SOI) is a production-ready supply chain AI platform that provides:

• 🔒 AI Sovereignty: All data stays local, GDPR compliant by design
• 🧠 Agentic RAG: Retrieve → Grade → Search → Generate workflow
• 📊 Explainable AI: Full reasoning traces for every decision
• 🌐 Real-Time Intel: Live market research via Tavily search
• 📄 Document Processing: Invoices, contracts, bids extraction
• ⚖️ Vendor Grading: Multi-criteria scoring with recommendations

Why SOI vs Competitors?

Feature	SAP Ariba	Coupa	Jaggaer	SOI
Annual Cost	50k+	100k+	Enterprise	$0
Data Location	Cloud	Cloud	Cloud	100% Local
Setup Time	Months	Weeks	Months	Hours
Reasoning Traces	❌	❌	❌	✅
Customizable	❌	Limited	Limited	100%
Web Search	❌	❌	❌	✅ Tavily

---

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        USER INTERFACES                           │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   Streamlit UI  │   REST API      │   CLI (soi)                 │
│   (Port 8501)   │   (Port 8000)   │                             │
└────────┬────────┴────────┬────────┴──────────────┬──────────────┘
         │                 │                       │
         └─────────────────┴───────────────────────┘
                           │
         ┌─────────────────┴─────────────────┐
         │      LangGraph Workflow           │
         │   ┌─────────────────────────┐     │
         │   │ 1. RETRIEVE (ChromaDB)  │     │
         │   │ 2. GRADE (LLM)          │     │
         │   │ 3. SEARCH (Tavily)      │     │
         │   │ 4. GENERATE (LLM)       │     │
         │   └─────────────────────────┘     │
         └─────────────────┬─────────────────┘
                           │
    ┌──────────────────────┼──────────────────────┐
    │                      │                      │
┌───▼───┐            ┌─────▼─────┐          ┌─────▼─────┐
│Ollama │            │ ChromaDB  │          │  Tavily   │
│LLM    │            │ Vectors   │          │  Search   │
│Qwen2.5│            │ (Local)   │          │  (API)    │
└───────┘            └───────────┘          └───────────┘

Tech Stack

Layer	Technology	Purpose
LLM	Ollama + Qwen2.5:7b	Local inference
Embeddings	Sentence Transformers	Vector embeddings
Vector DB	ChromaDB	Semantic search
Web Search	Tavily API	Real-time research
OCR	Pytesseract	Document extraction
Workflow	LangGraph	Agentic RAG loop
API	FastAPI	REST endpoints
UI	Streamlit	Web dashboard
CLI	Click + Rich	Command-line

---

🔐 AI Sovereignty: Your Private Knowledge Base

The core differentiator: Your sensitive data stays on your machine. Web search is only used for public information when local data isn't sufficient.

Data Flow Architecture

┌──────────────────────────────────────────────────────────────────┐
│                       YOUR QUERY                                  │
│    "What's our negotiated price with Supplier X?"                │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  STEP 1: VECTOR STORE (100% LOCAL - ChromaDB)                    │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐      │
│  │ Your Contracts │  │ Your Vendors   │  │ Your Documents │      │
│  │ (Confidential) │  │ (Private List) │  │ (Sensitive)    │      │
│  └────────────────┘  └────────────────┘  └────────────────┘      │
│                                                                   │
│  ✅ Found locally? → Use it → NEVER touches internet             │
│  ❌ Not found? → Continue to Step 2                              │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (Only if not found locally)
┌──────────────────────────────────────────────────────────────────┐
│  STEP 2: WEB SEARCH (Public Information Only)                    │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐      │
│  │ Serper/Google  │  │ Tavily Search  │  │ Page Scraping  │      │
│  │ (Public Web)   │  │ (AI Search)    │  │ (Product Info) │      │
│  └────────────────┘  └────────────────┘  └────────────────┘      │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  STEP 3: LOCAL LLM ANALYSIS (Ollama - DeepSeek/Qwen)             │
│  All processing happens on YOUR machine. No cloud LLM APIs.       │
└──────────────────────────────────────────────────────────────────┘

Why This Matters for Enterprise

Scenario	Without Sovereignty	With SOI
Vendor contract analysis	Data sent to OpenAI/Claude	Stays on your laptop
Pricing negotiations	Competitors could intercept	Never leaves your network
Supplier performance data	Exposed to third parties	100% private
Compliance documents	Cloud storage risks	Air-gapped if needed
Internal vendor ratings	Visible to cloud providers	Completely local

Building Your Private Knowledge Base

# Add vendors to your private database
soi vendors add "My Exclusive Supplier" \
  --description "Contract price $2.50/unit, exclusive until 2027" \
  --industry "Electronics"

# Add confidential documents (with OCR extraction)
soi docs process ./contracts/supplier_agreement.pdf --type contract
soi docs process ./pricing/2026_catalog.pdf --type catalog

# Bulk import from CSV
soi import vendors ./approved_vendors.csv

# Search ONLY your private data (never uses web search)
soi vendors search "exclusive pricing" --local-only
soi analyze "supplier renewal terms" --local-only

Data Storage Structure

./data/
├── chroma_db/                    # Vector database (your private knowledge)
│   ├── vendor_intelligence/      # Vendor profiles, capabilities, contracts
│   └── document_store/           # Ingested documents (OCR extracted text)
├── downloads/                    # Downloaded PDFs, datasheets from web
│   └── query_docs/               # Documents found via web search
└── reports/                      # Saved analysis reports (JSON)
    └── YYYYMMDD_query_name.json  # Timestamped report files

Privacy Guarantees

Component	Data Location	Cloud Exposure
LLM	Local Ollama	❌ None
Embeddings	Local Sentence Transformers	❌ None
Vector Store	Local ChromaDB	❌ None
Documents	Local filesystem	❌ None
Web Search	Serper/Tavily API	⚠️ Only query sent (no private data)

Save & Export Reports

# Analyze with verbose output and save report
soi analyze "ATmega328P pricing comparison" -v -s

# Report saved to: ./data/reports/20260207_ATmega328P_pricing_.json

Report contains:

{
  "query": "ATmega328P pricing comparison",
  "criteria": ["price", "quality", "reliability", "risk"],
  "timestamp": "2026-02-07T01:45:00",
  "result": {
    "overall_score": 82,
    "recommendation": "APPROVED",
    "breakdown": {...},
    "sources": {...}
  }
}

---

Installation

Prerequisites

• Python: 3.11 or higher
• RAM: 16GB+ recommended
• Ollama: For local LLM inference
• Tesseract: For OCR (system dependency)

Step 1: Install System Dependencies

# macOS
brew install tesseract poppler

# Ubuntu/Debian
sudo apt-get install tesseract-ocr poppler-utils

# Windows (via Chocolatey)
choco install tesseract poppler

Step 2: Install Ollama and Model

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama server
ollama serve

# Pull the model (in another terminal)
ollama pull qwen2.5:7b

Step 3: Install SOI

cd sovereign-order-intelligence

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install the package
pip install -e .

# Or install from requirements
pip install -r requirements.txt

Step 4: Configure Environment

# Copy example env
cp .env.example .env

# Edit with your Tavily API key
nano .env

---

Configuration

All configuration is done via environment variables in .env:

Core Settings

# Application
DEBUG=false
LOG_LEVEL=INFO

# Ollama LLM
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
OLLAMA_TIMEOUT=120

# Tavily Web Search
TAVILY_API_KEY=your-api-key-here
TAVILY_MAX_RESULTS=5

Grading Thresholds

# RAG Loop Control
RELEVANCE_THRESHOLD=0.7      # Min relevance to skip web search
CONFIDENCE_THRESHOLD=0.8     # Min confidence for auto-approval
MAX_WEB_SEARCHES=3           # Max search iterations

# Vendor Scoring Weights (must sum to 1.0)
WEIGHT_PRICE=0.30
WEIGHT_QUALITY=0.25
WEIGHT_RELIABILITY=0.25
WEIGHT_RISK=0.20

Storage Settings

# ChromaDB
CHROMA_PERSIST_DIR=./data/chroma_db
CHROMA_COLLECTION_NAME=vendor_intelligence

# Cache
CACHE_TTL_SECONDS=3600
BATCH_SIZE=10

API Settings

API_HOST=0.0.0.0
API_PORT=8000

---

Quick Start

Option 1: CLI

# Check system status
soi status

# Analyze a query
soi analyze "Find reliable electronic component suppliers under $10k"

# Grade a specific vendor
soi grade "Acme Corp" --web

# Add a vendor to knowledge base
soi vendors add "Acme Corp" -d "Electronic components supplier" -w "https://acme.com"

# Search vendors
soi vendors search "electronics supplier"

# Process a document
soi docs process invoice.pdf --type invoice

# Start the API server
soi serve

Option 2: API

# Start server
python -m src.api.server

# Test health
curl http://localhost:8000/health

# Analyze query
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"query": "Compare top suppliers for reliability"}'

# Add vendor
curl -X POST http://localhost:8000/vendors \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "description": "Electronics supplier"}'

Option 3: Streamlit UI

streamlit run src/ui/app.py
# Opens at http://localhost:8501

---

API Reference

Base URL

http://localhost:8000

Health Endpoints

GET /

Returns API info and available endpoints.

GET /health

System health check including Ollama, ChromaDB, and Tavily status.

Response:

{
  "status": "healthy",
  "components": {
    "ollama": {"status": "ok", "model": "qwen2.5:7b"},
    "tavily": {"status": "ok"},
    "vector_store": {"status": "ok", "stats": {...}}
  }
}

Analysis Endpoints

POST /analyze

Run the full Order Intelligence workflow.

Request:

{
  "query": "Compare electronic suppliers for price and reliability",
  "criteria": ["price", "quality", "reliability", "risk"]
}

Response:

{
  "query": "...",
  "analysis": {...},
  "final_answer": "Based on analysis...",
  "reasoning_chain": ["Step 1...", "Step 2..."],
  "sources": {
    "vendors": 3,
    "documents": 2,
    "web_results": 5
  }
}

POST /analyze/vendor

Analyze a specific vendor.

Request:

{
  "vendor_name": "Acme Corp",
  "criteria": ["price", "quality", "reliability", "risk"],
  "include_web_research": true
}

Vendor Endpoints

GET /vendors

List all vendors in knowledge base.

POST /vendors

Add a new vendor.

Request:

{
  "name": "Acme Corp",
  "description": "Leading electronics supplier",
  "website": "https://acme.com",
  "industry": "Electronics",
  "products": ["Capacitors", "Resistors", "ICs"]
}

GET /vendors/{vendor_id}

Get vendor by ID.

POST /vendors/search

Semantic search for vendors.

Request:

{
  "query": "reliable electronics supplier",
  "limit": 10
}

Document Endpoints

POST /documents/process

Upload and process a document.

Request: multipart/form-data

• file: PDF, PNG, JPG file
• doc_type: auto, invoice, contract, bid

Response:

{
  "document": {
    "id": "doc_abc123",
    "type": "invoice",
    "extracted_fields": {
      "vendor_name": {"value": "Acme Corp", "confidence": 0.95},
      "total_amount": {"value": 1500.00, "confidence": 0.92}
    },
    "confidence": 0.87,
    "validation_status": "valid"
  },
  "processing_time_ms": 1250
}

GET /documents

List processed documents.

Research Endpoints

POST /research/market

Market research using web search.

POST /research/vendor/{vendor_name}

Research a vendor online.

Stats Endpoint

GET /stats

System statistics.

---

CLI Reference

Global Commands

soi --help              # Show help
soi --version           # Show version
soi status              # Check system status
soi serve               # Start API server

Analyze Commands

# Basic analysis
soi analyze "your query here"

# With specific criteria
soi analyze "query" -c price -c quality -c reliability

# JSON output
soi analyze "query" -j

Grade Commands

# Grade with web research
soi grade "Vendor Name" --web

# Grade without web research
soi grade "Vendor Name" --no-web

# Custom criteria
soi grade "Vendor Name" -c price -c quality

Vendor Commands

# List vendors
soi vendors list
soi vendors list --limit 50

# Add vendor
soi vendors add "Name" -d "Description" -w "https://website.com" -i "Industry" -p "Product1" -p "Product2"

# Search
soi vendors search "query"

Document Commands

# Process with auto-detection
soi docs process document.pdf

# Specify type
soi docs process invoice.pdf --type invoice
soi docs process contract.pdf --type contract

Research Commands

# Research a vendor
soi research vendor "Vendor Name"

# Market research
soi research market "category"

# 🏢 Deep Company Research (Enhanced)
# Includes: executives, funding, market data, hiring, competitors
soi research company "Salesforce" -o salesforce.json -m salesforce_report.md

Company Research Output:

• 20 Serper queries for maximum coverage
• Executives with LinkedIn URLs
• Financials: funding, valuation, investors
• Market data: market share, TAM/SAM
• Hiring: open roles, tech stack, locations
• News tagged by type (funding/product/partnership)
• Data sources with real-time search proof

Server Command

# Default settings
soi serve

# Custom host/port
soi serve -h 0.0.0.0 -p 8080

# With auto-reload (development)
soi serve --reload

---

Web UI Guide

Access the Streamlit UI at http://localhost:8501

Pages

1. 🏠 Dashboard: Overview and quick actions
2. 🔍 Analyze Query: Full RAG workflow analysis
3. 📊 Vendor Grading: Grade and compare vendors
4. 📄 Document Processing: Upload and extract documents
5. 🌐 Web Research: Online vendor/market research
6. ⚙️ Settings: System status and configuration

Features

• Real-time Analysis: See reasoning chains as they happen
• Visual Scores: Progress bars and charts for scores
• Export Options: Download reports as JSON
• Dark Mode: Automatic theme support

---

Core Modules

src/llm/ - LLM Infrastructure

ollama_client.py

Async Ollama client with:

• Retry logic (3 attempts with exponential backoff)
• Streaming support
• Chat and generate modes
• Health checks

from src.llm.ollama_client import OllamaClient

client = OllamaClient()
response = await client.generate("Your prompt here")
await client.close()

embeddings.py

Local embeddings using Sentence Transformers:

• Model: all-MiniLM-L6-v2 (384 dimensions)
• Async support
• Cosine similarity utilities

from src.llm.embeddings import get_embeddings

embeddings = get_embeddings()
vector = embeddings.embed_query("search text")

prompts.py

Specialized system prompts:

• VENDOR_ANALYST_PROMPT: Vendor analysis
• DOCUMENT_EXTRACTOR_PROMPT: Document extraction
• GRADING_PROMPT: Scoring and recommendations
• RELEVANCE_GRADER_PROMPT: RAG relevance grading
• HALLUCINATION_DETECTOR_PROMPT: Grounding checks

src/storage/ - Data Layer

chroma_store.py

ChromaDB vector store with:

• Multiple collections (vendors, documents, market_intel)
• Async CRUD operations
• Metadata filtering
• Similarity search

from src.storage.chroma_store import get_vector_store

store = get_vector_store()
results = await store.similarity_search("query", k=5, collection="vendors")

cache.py

TTL-based query cache:

• File + memory hybrid caching
• Configurable TTL
• Auto-expiration

from src.storage.cache import get_cache

cache = get_cache()
result = await cache.get_or_compute("key", compute_fn, ttl=3600)

src/tools/ - Agent Tools

tavily_search.py

Web search integration:

• Vendor research
• Market trends
• Risk analysis

ocr.py

Document text extraction:

• Pytesseract (CPU-optimized)
• PDF and image support
• Confidence scoring

scraper.py

Website scraping:

• Email/phone extraction
• Social link discovery
• Playwright fallback for JS sites

src/models/ - Data Models

vendor.py

Vendor entity models:

• Vendor: Core vendor data
• VendorProfile: Extended profile
• VendorContact: Contact info

document.py

Document models:

• Document: Base document
• InvoiceData: Invoice fields
• ContractData: Contract fields
• ExtractedField: Field with confidence

analysis.py

Analysis models:

• VendorAnalysis: Grading results
• ScoreDetail: Per-criterion scores
• MarketIntelligence: Research results

---

LangGraph Workflow

The core Order Intelligence workflow implements an agentic RAG loop:

                    ┌─────────┐
                    │  START  │
                    └────┬────┘
                         │
                    ┌────▼────┐
                    │RETRIEVE │ ← Query ChromaDB for relevant data
                    └────┬────┘
                         │
                    ┌────▼────┐
                    │  GRADE  │ ← LLM evaluates relevance
                    └────┬────┘
                         │
              ┌──────────┴──────────┐
              │                     │
         score >= 0.7          score < 0.7
              │                     │
              │               ┌─────▼─────┐
              │               │WEB SEARCH │ ← Tavily API
              │               └─────┬─────┘
              │                     │
              └──────────┬──────────┘
                         │
                    ┌────▼────┐
                    │GENERATE │ ← Final analysis with reasoning
                    └────┬────┘
                         │
                    ┌────▼────┐
                    │   END   │
                    └─────────┘

Usage

from src.graphs.order_intelligence import analyze_query

result = await analyze_query(
    query="Compare top 3 suppliers for quality",
    criteria=["price", "quality", "reliability", "risk"]
)

print(result["final_answer"])
print(result["reasoning_chain"])

State Fields

class OrderIntelligenceState(TypedDict):
    query: str                      # User query
    criteria: list[str]             # Evaluation criteria
    vendors: list[dict]             # Retrieved vendors
    documents: list[dict]           # Retrieved documents
    web_results: list[dict]         # Web search results
    reasoning_steps: list[str]      # Accumulated reasoning
    analysis: Optional[dict]        # Final analysis
    final_answer: str               # Generated response
    iteration: int                  # Search iteration count

---

Document Processing

Supported Formats

• PDF: Digital and scanned
• Images: PNG, JPG, JPEG

Document Types

• Invoice: Vendor, amounts, line items, dates
• Contract: Parties, terms, obligations
• Bid: Pricing, specifications, delivery

Processing Pipeline

Document → OCR (Pytesseract) → Type Detection → LLM Extraction → Validation → Storage

Usage

from src.processors.document_processor import DocumentProcessor

processor = DocumentProcessor()
result = await processor.process("invoice.pdf", doc_type="auto")

print(result.document.extracted_fields)
print(result.document.confidence)

Field Extraction

The LLM extracts structured fields with confidence scores:

{
  "vendor_name": {"value": "Acme Corp", "confidence": 0.95},
  "total_amount": {"value": 1500.00, "confidence": 0.92},
  "due_date": {"value": "2025-03-01", "confidence": 0.88}
}

---

Vendor Grading

Scoring Criteria

Criterion	Weight	Description
Price	30%	Cost competitiveness
Quality	25%	Product/service quality
Reliability	25%	Delivery, consistency
Risk	20%	Financial, operational risks

Recommendations

Score Range	Recommendation
70-100	✅ APPROVED
50-69	⚠️ REVIEW
0-49	❌ REJECTED

Usage

from src.processors.vendor_grader import VendorGrader

grader = VendorGrader()
analysis = await grader.grade(
    vendor_name="Acme Corp",
    vendor_data={"name": "Acme Corp"},
    criteria=["price", "quality", "reliability", "risk"],
    web_research=None  # Optional web research data
)

print(f"Score: {analysis.overall_score}")
print(f"Recommendation: {analysis.recommendation}")

Explainability

Every analysis includes a reasoning chain:

analysis.reasoning_chain = [
    "Step 1: Analyzed pricing data from 3 sources",
    "Step 2: Found 95% on-time delivery rate",
    "Step 3: No significant risk factors identified",
    "Step 4: Overall assessment: Strong vendor with competitive pricing"
]

---

Web Research

Tavily Integration

SOI uses Tavily API for real-time web search:

from src.tools.tavily_search import TavilySearchTool

search = TavilySearchTool()

# General search
results = await search.search("electronic component suppliers 2025")

# Vendor research
info = await search.search_vendor_info("Acme Corp")

# Market trends
trends = await search.search_market_trends("semiconductors")

# Risk analysis
risks = await search.search_vendor_risks("Acme Corp")

Search Types

1. General Search: Any query
2. Vendor Research: Company overview, reviews, pricing
3. Market Trends: Industry outlook, pricing trends
4. Risk Analysis: Legal issues, complaints, financial problems

---

Testing

Run All Tests

pytest tests/ -v

Run Specific Tests

# Test grader
pytest tests/test_grader.py -v

# Test graph
pytest tests/test_graph.py -v

# Test API
pytest tests/test_api.py -v

Coverage Report

pytest tests/ --cov=src --cov-report=html

Test Structure

tests/
├── conftest.py       # Fixtures
├── test_grader.py    # Vendor grading tests
├── test_graph.py     # LangGraph workflow tests
└── test_api.py       # API endpoint tests

---

Docker Deployment

Quick Start

docker-compose up -d

Services

Service	Port	Description
ollama	11434	Local LLM
api	8000	REST API
ui	8501	Streamlit UI

Build Only API

docker build -t soi:latest .
docker run -p 8000:8000 -v $(pwd)/data:/app/data soi:latest

With GPU (NVIDIA)

docker-compose up -d ollama  # Uses GPU for Ollama

Health Checks

All services have health checks configured:

• Ollama: /api/tags
• API: /health

---

Troubleshooting

Ollama Not Connecting

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Restart Ollama
ollama serve

# Check model is downloaded
ollama list

OCR Not Working

# Check Tesseract installation
tesseract --version

# macOS
brew install tesseract

# Linux
sudo apt-get install tesseract-ocr

ChromaDB Errors

# Reset ChromaDB
rm -rf data/chroma_db

# Restart application

Memory Issues

With 16GB RAM:

• Use qwen2.5:7b (recommended)
• Avoid larger models (14b, 32b)
• Limit batch sizes in config

API Timeout

# Increase timeout in .env
OLLAMA_TIMEOUT=180

---

Support

For issues and feature requests, please open an issue on GitHub.

Built with ❤️ for supply chain professionals who value data sovereignty.