Migration Guide to v0.1.17.1¶

This guide helps you migrate from NetIntel-OCR v0.1.17 to v0.1.17.1, which introduces modular installation and enhanced version display.

What's New in v0.1.17.1¶

1. Modular Installation¶

Reduced base size: From 2.5GB to 500MB
Optional features: Install only what you need
7 modules available: kg, vector, api, mcp, performance, dev, all

2. Enhanced Version Display¶

Comprehensive status: Shows all installed and available modules
Connection status: Real-time status of services (FalkorDB, Milvus, Ollama)
Installation hints: Shows exact commands to add missing features

Before You Upgrade¶

Check Your Current Setup¶

First, understand what features you're currently using:

# Check current version
netintel-ocr --version

# If on v0.1.17, check what you're using:
# Check if using Knowledge Graph
ls ~/.netintel-ocr/kg/ 2>/dev/null && echo "Using KG"

# Check if using Milvus
docker ps | grep milvus && echo "Using Milvus"

# Check if using API server
ps aux | grep "netintel-ocr.*--api" && echo "Using API"

Backup Your Data¶

# Backup configuration
cp -r ~/.netintel-ocr ~/.netintel-ocr.backup

# Backup any custom templates
cp -r ~/netintel-templates ~/netintel-templates.backup

# If using FalkorDB, backup graph data
docker exec falkordb redis-cli --rdb /data/dump.rdb

Migration Paths¶

Path 1: Minimal User (Just OCR)¶

If you only use basic OCR features:

# Uninstall old version
pip uninstall netintel-ocr

# Install base package only (500MB)
pip install netintel-ocr==0.1.17.1

# Verify
netintel-ocr --version

Path 2: Knowledge Graph User¶

If you use Knowledge Graph features:

# Uninstall old version
pip uninstall netintel-ocr

# Install with KG support (2GB total)
pip install "netintel-ocr[kg]==0.1.17.1"

# Verify KG is available
netintel-ocr --version | grep "Knowledge Graph"

Path 3: Production User¶

If you use NetIntel-OCR in production:

# Uninstall old version
pip uninstall netintel-ocr

# Install production features (KG + Vector + API + Performance)
pip install "netintel-ocr[production]==0.1.17.1"

# Verify all features
netintel-ocr --version --detailed

Path 4: Full Installation User¶

If you want everything (equivalent to v0.1.17):

# Uninstall old version
pip uninstall netintel-ocr

# Install all features (2.5GB)
pip install "netintel-ocr[all]==0.1.17.1"

# Verify
netintel-ocr --version

Command Changes¶

CLI Commands (No Changes)¶

The hierarchical CLI structure from v0.1.17 remains the same:

# Old syntax (pre-v0.1.17) - Still deprecated
netintel-ocr document.pdf

# Current syntax (v0.1.17+) - Still works
netintel-ocr process pdf document.pdf

New Version Command Features¶

# Basic version (shows modules)
netintel-ocr --version

# Detailed version info
netintel-ocr --version --detailed

# JSON output for scripts
netintel-ocr --version --json

# Check for updates
netintel-ocr --version --check-updates

Feature-Specific Migration¶

Knowledge Graph Features¶

If KG commands fail after upgrade:

# Check if KG is installed
netintel-ocr --version | grep "kg"

# If not installed, add it
pip install "netintel-ocr[kg]"

# Verify KG works
netintel-ocr kg init

Vector Store Features¶

If Milvus/vector features fail:

# Check if vector module is installed
netintel-ocr --version | grep "vector"

# If not installed, add it
pip install "netintel-ocr[vector]"

# Test connection
netintel-ocr db stats

API Server¶

If API server doesn't start:

# Check if API module is installed
netintel-ocr --version | grep "api"

# If not installed, add it
pip install "netintel-ocr[api]"

# Start server
netintel-ocr server api

Troubleshooting¶

Module Not Found Errors¶

# Error: ImportError: No module named 'pykeen'
# Solution: Install KG module
pip install "netintel-ocr[kg]"

# Error: ImportError: No module named 'fastapi'
# Solution: Install API module
pip install "netintel-ocr[api]"

# Error: ImportError: No module named 'pymilvus'
# Solution: Install vector module
pip install "netintel-ocr[vector]"

Check What's Missing¶

# Run version command to see what's missing
netintel-ocr --version

# Look for "Available for Install" section
# It shows exact commands to install missing features

Performance Issues¶

If processing is slower after upgrade:

# Install performance optimizations
pip install "netintel-ocr[performance]"

# Check C++ core is enabled
netintel-ocr --version | grep "C++ Core"

Docker Migration¶

Update Docker Image¶

# Old Dockerfile (v0.1.17)
FROM python:3.11-slim
RUN pip install netintel-ocr==0.1.17

# New Dockerfile (v0.1.17.1) - Choose what you need
FROM python:3.11-slim

# Option 1: Minimal
RUN pip install netintel-ocr==0.1.17.1

# Option 2: With KG
RUN pip install "netintel-ocr[kg]==0.1.17.1"

# Option 3: Production
RUN pip install "netintel-ocr[production]==0.1.17.1"

Docker Compose Update¶

# docker-compose.yml
services:
  netintel-ocr:
    image: netintel/netintel-ocr:0.1.17.1
    environment:
      # No changes to environment variables
      - OLLAMA_HOST=ollama:11434
      - FALKORDB_HOST=falkordb:6379

Configuration Files¶

No Changes Required¶

Configuration files from v0.1.17 work without changes: - ~/.netintel-ocr/config.yml - Template files - Environment variables

Rollback Plan¶

If you need to rollback to v0.1.17:

# Uninstall v0.1.17.1
pip uninstall netintel-ocr

# Reinstall v0.1.17
pip install netintel-ocr==0.1.17

# Restore backup if needed
mv ~/.netintel-ocr.backup ~/.netintel-ocr

Benefits After Migration¶

Storage Savings¶

Installation Type	v0.1.17	v0.1.17.1	Savings
Minimal (OCR only)	2.5GB	500MB	2GB (80%)
With KG	2.5GB	2GB	500MB (20%)
Production	2.5GB	2.3GB	200MB (8%)
Everything	2.5GB	2.5GB	0

Better Visibility¶

Know exactly what's installed
See what features are available
Get installation commands instantly
Check service connections

Faster Installation¶

Base install: 5x faster
Incremental upgrades: Add features as needed
Reduced dependency conflicts

Getting Help¶

Check Installation Status¶

# See comprehensive status
netintel-ocr --version --detailed

Report Issues¶

GitHub: https://github.com/VisionMLNet/NetIntelOCR/issues
Discord: https://discord.gg/netintel-ocr