FHE Document Comparison System

A proof-of-concept implementation of privacy-preserving document comparison using Fully Homomorphic Encryption (FHE).

Project Status

✅ Validation Complete - FHE proven to work with real encryption
🚧 CLI Implementation - Simple command-line interface for the use case

Repository Structure

min-fhe/
├── validation_tests/     # Comprehensive test suite that proved FHE works
│   ├── core/            # Essential validation tests
│   ├── enhancement/     # Additional performance and accuracy tests
│   └── results/         # Test results and findings
├── cli/                 # Command-line implementation
│   ├── inventor.py      # Inventor (document owner) operations
│   ├── system.py        # System (comparison service) operations
│   ├── cli.py          # Main CLI entry point
│   └── shared/         # Shared utilities
├── .artifacts/         # Build artifacts
└── requirements.txt    # Python dependencies

Quick Start - Running from Claude Code

Easy Method: Run Demo Directly in Claude Code

If you're using Claude Code, you can run the demo without leaving the app:

1. Ask Claude to run the demo:

   "Please run the FHE demo at /Users/creed/projects/min-fhe/cli/demo.py"
   

2. Or run specific tests:

   "Run the quick_test_v2.py validation test"
   

Claude will handle activating the virtual environment and running the scripts for you.

Example Claude Code Commands

See what's in the project:

"Show me the structure of the min-fhe project"

Run the working demo:

"Run the FHE document comparison demo in /Users/creed/projects/min-fhe/cli/demo.py"

Run validation tests:

"Run the validation test at validation_tests/core/quick_test_v2.py"
"Show me the results of test_fhe_dimensions.py"

Explore the code:

"Show me how the inventor encrypts documents in inventor.py"
"Explain the dot product function in the demo"

Check test results:

"Show me the validation results in validation_tests/results/"
"What did the FHE validation tests prove?"

Claude Code will provide output directly in the chat, making it easy to see results without switching to Terminal.

Quick Start - Mac Terminal Instructions

Prerequisites

• Python 3.9 (comes with macOS)
• Terminal app (in Applications > Utilities)

Step 1: Open Terminal and Navigate to Project

# Open Terminal and go to the project directory
cd /Users/creed/projects/min-fhe

Step 2: Set Up Python Environment

# Create virtual environment if it doesn't exist
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install required packages
pip install -r requirements.txt

Step 3: Run the Demo (Recommended First Step)

# Go to CLI directory
cd cli

# Run the working demo
python demo.py

This demo shows the complete workflow with a small dimension (4) that works reliably.

Step 4: Try the Full CLI (Currently Has Issues)

# Attempt to set up the inventor's circuit
python cli.py inventor setup

# If successful, encrypt a document
python cli.py inventor encrypt doc1 "My secret invention details..."

# Export public keys for the system
python cli.py inventor export-keys

# System compares documents
python cli.py system compare doc1 "Similar invention description..."

Alternative: Run Validation Tests

# Go back to main directory
cd ..

# Run a test that we know works
python validation_tests/core/quick_test_v2.py

# Or run the dimension scaling test
python validation_tests/core/test_fhe_dimensions.py

Use Case

1. Inventor encrypts document A with private key
2. System receives encrypted A and plaintext document B
3. System encrypts B and compares with A homomorphically
4. Inventor decrypts the similarity score

The system never sees document A in plaintext, preserving privacy.

Key Technical Decisions

• Dimension: 16 (validated to work with good performance)
• Quantization Scale: 1000 (balances accuracy vs overflow)
• Model: all-MiniLM-L6-v2 (truncated to 16 dims)
• Performance: ~0.5-0.6s per comparison

See validation_tests/results/ for detailed technical findings.

Troubleshooting

Common Issues on Mac

1. "command not found: python"

   • Use python3 instead of python
   • Or create an alias: alias python=python3

2. "No module named 'concrete'"

   • Make sure virtual environment is activated: source venv/bin/activate
   • Reinstall requirements: pip install -r requirements.txt

3. SSL/TLS Warnings

   • The urllib3 warning about LibreSSL is harmless and can be ignored
   • It's related to macOS using LibreSSL instead of OpenSSL

4. "NoParametersFound" Error

   • This is a known issue with the full CLI
   • Use the demo.py instead, which works reliably
   • Or run the validation tests which are proven to work

5. Long Compilation Times

   • FHE circuit compilation can take 1-5 minutes
   • This is normal and only happens once
   • Be patient during "Compiling circuit..." phase

What's Working vs What's Not

✅ Working:

• cli/demo.py - Complete workflow demonstration
• validation_tests/core/quick_test_v2.py - Basic FHE test
• validation_tests/core/test_fhe_dimensions.py - Scaling test
• Basic FHE operations with dimensions up to 16

❌ Known Issues:

• Full CLI with dimension 16 (inputset generation problem)
• Type consistency with negative values
• Serialization with pickle (use concrete's methods instead)