Getting Started with Mortgage-Lite¶

This guide will help you set up and run Mortgage-Lite for the first time.

Prerequisites¶

Required¶

Python 3.12+
Docker (for containerized deployment)
Ollama (for local LLM processing)

Optional¶

Claude CLI (for cloud-based compliance checking)
PostgreSQL (for production deployments)
Telegram Bot (for notifications)

Installation¶

Option 1: Local Development¶

1. Clone the Repository¶

git clone https://github.com/dkubeio/mortgage-lite.git
cd mortgage-lite

2. Install Dependencies¶

pip install -r requirements.txt

3. Set Up Environment Variables¶

Create a .env file in the project root:

# Database (SQLite for development)
DATABASE_URL=sqlite+aiosqlite:///./mortgage-lite.db

# Server Configuration
HOST=0.0.0.0
PORT=5300

# AI Configuration - Ollama (Local)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3.5:35b

# AI Configuration - Claude (Cloud)
CLAUDE_BIN=claude
CLAUDE_MODEL=sonnet
ANTHROPIC_API_KEY=your_key_here

# AI Configuration - SecureLLM (Local Inference)
# For Kubernetes (same namespace: dkubex-apps)
# Models are discovered automatically from the gateway
SECURELLM_BASE_URL=http://securellm/securellm/v1
SECURELLM_API_KEY=your_api_key_here

# API Keys (optional)
OPENAI_API_KEY=your_key_here

# Pipeline Configuration
DEFAULT_PIPELINE_TYPE=underwriting

# Features
ANONYMIZATION_ENABLED=true
ENABLE_OPTIMIZED_PIPELINE=false
ENABLE_PDF_VIEWER=true
ENABLE_SERVICING_PIPELINE=true
ENABLE_QC_PIPELINE=true

# DKubeX Integration (optional)
DKUBEX_BASE_PATH=

4. Install Ollama and Pull Models¶

# Install Ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Pull required models
ollama pull qwen3.5:35b

5. Initialize Database and Load Demo Data¶

# Generate demo data
python3 scripts/generate_demo_data.py

# Load demo applications
python3 scripts/load_demo.py

6. Start the Application¶

python3 -m uvicorn app.main:app --host 0.0.0.0 --port 5300 --reload

7. Access the Application¶

Open your browser and navigate to:

http://localhost:5300

Option 2: Docker Deployment¶

1. Build the Docker Image¶

docker build -t mortgage-lite:latest .

2. Run the Container¶

docker run -d \
  -p 5300:5300 \
  -v $(pwd)/uploads:/app/uploads \
  -e DATABASE_URL=sqlite+aiosqlite:///./mortgage-lite.db \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --name mortgage-lite \
  mortgage-lite:latest

3. Access the Application¶

http://localhost:5300

Option 3: Kubernetes Deployment¶

1. Install with Helm¶

helm repo add dkubeio https://dkubeio.github.io/helm-charts
helm repo update

helm install mortgage-lite dkubeio/mortgage-lite \
  --set image.tag=latest \
  --set env.OLLAMA_BASE_URL=http://ollama-service:11434

2. Access via Port Forward¶

kubectl port-forward svc/mortgage-lite 5300:5300

First Steps¶

1. Explore the Dashboard¶

The main dashboard shows:

Application statistics
Agent status (8 agents across 3 pipelines)
Recent activity
System metrics
Pipeline selector (Underwriting, Servicing, Quality Control)

2. Upload a Test Application¶

Click “Upload” in the navigation
Select pipeline type:
- Underwriting: For loan origination
- Servicing: For loan transfer validation
- Quality Control: For post-close audit
Fill in applicant details:
- Name: John Smith
- Loan Type: Purchase
- Loan Amount: $350,000
- Property Value: $450,000
Upload documents (W-2, bank statements, etc.)
Click “Submit Application”

3. Run the Pipeline¶

Navigate to “Applications”
Find your application in the Kanban board
Click “Run Pipeline” on the application card
Watch as agents process the application through each stage

4. Review Results¶

After processing completes:

Check “Anomalies” for any detected issues
Use “PDF Viewer” to inspect documents with highlighted fields
Review “Compliance” checks (underwriting pipeline)
View the “Report” with executive summary
Examine “Metrics” for performance data

5. Explore PDF Viewer¶

The anomaly inspector includes an inline PDF viewer:

Click on any anomaly in the list
Related documents appear in tabs
Navigate pages with Prev/Next buttons
Zoom in/out for detailed inspection
Flagged fields are highlighted with bounding boxes

Demo Mode¶

Mortgage-Lite includes three pre-configured demo applications:

Load Demo Data¶

python3 scripts/load_demo.py --reset

This creates three applications:

John Smith - Clean purchase loan (expected: APPROVED)
Catherine Vellotti - Refinance with 7 anomalies (expected: FLAGGED)
Maria Garcia - FHA loan with conditions (expected: CONDITIONALLY APPROVED)

Run Demo Pipeline¶

# Start the server
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 5300

# In the UI, click "Run Pipeline" on each demo application

Configuration¶

AI Model Selection¶

Local Models (Privacy-Safe)¶

Ollama

# Ana agent uses local models for PII processing
OLLAMA_MODEL=qwen3.5:35b

# Alternative models
OLLAMA_MODEL=nemotron:70b
OLLAMA_MODEL=llama3.1:70b

SecureLLM (Local Inference Server)

# Use SecureLLM for local inference with OpenAI-compatible API
# Kubernetes service DNS (same namespace: dkubex-apps)
SECURELLM_BASE_URL=http://securellm/securellm/v1
SECURELLM_API_KEY=your_api_key

# SecureLLM provides chat completions endpoint
# Compatible with OpenAI API format
# Available models are discovered automatically from the gateway
# Ana and Rex agents will use SecureLLM if models are available,
# otherwise fall back to Ollama

Cloud Models (Anonymized Data Only)¶

# Claire agent uses Claude for compliance
CLAUDE_MODEL=sonnet
CLAUDE_MODEL=opus
CLAUDE_MODEL=haiku

Anonymization¶

Enable/disable PII anonymization:

ANONYMIZATION_ENABLED=true

When enabled:

Local agents (Iris, Rex, Val, Ana) process raw data
Data is anonymized before Claire (cloud) processing
Results are deanonymized before Max (delivery)

Performance Tuning¶

# Parallel document processing
MAX_PARALLEL_DOCUMENTS=4

# Stage retry attempts
MAX_STAGE_RETRIES=3

# Enable optimized pipeline routing
ENABLE_OPTIMIZED_PIPELINE=true
OPTIMIZATION_ROLLOUT_PCT=50

Troubleshooting¶

Application Won’t Start¶

# Check Python version
python3 --version  # Should be 3.12+

# Verify dependencies
pip install -r requirements.txt

# Check database
rm -f mortgage-lite.db
python3 scripts/load_demo.py

Ollama Connection Failed¶

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

# Start Ollama
ollama serve

# Check model availability
ollama list

Pipeline Hangs¶

# Check agent status in UI
# Navigate to Dashboard → Agents

# Check logs
tail -f logs/mortgage-lite.log

# Reset application status
# In UI: Applications → Select app → Reset Pipeline

Claude CLI Not Found¶

# Install Claude CLI
npm install -g @anthropic-ai/claude-cli

# Or use API directly
ANTHROPIC_API_KEY=your_key_here

Next Steps¶

Read the Architecture Guide to understand system design
Explore the API Reference for integration
Check Deployment Guide for production setup

Support¶

For additional help:

Check the Troubleshooting Guide
Review Development Guide
Open an issue in the project repository