Migration Guide

Migrating from legacy AI governance tools is straightforward. TruthVouch provides data import tools, API compatibility layers, and parallel-run options to ensure zero downtime and smooth transition.

Migration Paths

Quick Migration (1-2 weeks)

For organizations with simple workflows:

Import knowledge bases
Map alert rules to policies
Update API endpoints
Run parallel verification

Standard Migration (4-6 weeks)

For mid-size organizations:

Audit current configuration
Plan knowledge base structure
Design policy framework
Train team on TruthVouch
Gradual cutover

Enterprise Migration (8-12 weeks)

For complex deployments:

Detailed audit and gap analysis
Custom integration work
Performance optimization
Security hardening
Post-migration support

Pre-Migration Checklist

Assessment

Inventory current AI governance systems
Document all rules and policies
Identify knowledge base content
List integration touchpoints
Measure baseline metrics

Planning

Preparation

Data Import

Knowledge Base Migration

TruthVouch imports from common formats:

# CSV format
claim,source_url,category,confidence
"OpenAI raised $10B in Series C",https://...,funding,high
"Claude has 200k context window",https://...,product,high

# Import via CLI
truthvouch import --type=knowledge-base \
  --format=csv \
  --file=knowledge-base.csv \
  --organization-id=org_abc123

JSON Format

{
  "nuggets": [
    {
      "claim": "OpenAI raised $10B in Series C",
      "source_url": "https://openai.com/blog/...",
      "category": "funding",
      "confidence": 0.95,
      "created_at": "2024-01-15"
    }
  ]
}

Bulk Import Script (Python)

from truthvouch.client import TruthVouchClient
import csv

def import_knowledge_base(csv_file: str, org_id: str):
    client = TruthVouchClient(
        api_key="your-api-key",
        organization_id=org_id
    )

    with open(csv_file) as f:
        reader = csv.DictReader(f)
        nuggets = list(reader)

    # Batch import (1000 at a time)
    for i in range(0, len(nuggets), 1000):
        batch = nuggets[i:i+1000]
        result = client.knowledge_base.import_nuggets(batch)
        print(f"Imported {result.count} nuggets")

    print(f"Total imported: {len(nuggets)}")

# Usage
import_knowledge_base("legacy_kb.csv", "org_abc123")

Database Migration

For SQL databases, export and transform:

import sqlite3
from truthvouch.client import TruthVouchClient

def migrate_from_sqlite(db_path: str):
    # Read from legacy database
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()

    cursor.execute("SELECT claim, source, confidence FROM facts")
    rows = cursor.fetchall()

    # Transform to TruthVouch format
    nuggets = [
        {
            "claim": row[0],
            "source_url": row[1],
            "confidence": row[2]
        }
        for row in rows
    ]

    # Import to TruthVouch
    client = TruthVouchClient(api_key="your-api-key")
    result = client.knowledge_base.import_nuggets(nuggets)

    print(f"Migrated {result.count} facts")
    conn.close()

Configuration Migration

Policy Migration

Map existing rules to TruthVouch policies:

# Legacy system
rules:
  - name: "hallucination_threshold"
    threshold: 0.8
  - name: "citation_required"
    applies_to: ["healthcare", "legal"]

# TruthVouch equivalent
policies:
  - name: "hallucination_detection"
    rules:
      - condition: "confidence < 0.8"
        action: "flag_for_review"
  - name: "citation_enforcement"
    rules:
      - condition: "category in [healthcare, legal]"
        action: "require_citations"

Alert Rule Mapping

def migrate_alert_rules(legacy_rules: list[dict]) -> list[dict]:
    """Convert legacy alert rules to TruthVouch format."""

    truthvouch_rules = []

    for rule in legacy_rules:
        truthvouch_rule = {
            "name": rule["name"],
            "condition": convert_condition(rule["condition"]),
            "actions": [
                {
                    "type": "notification",
                    "channels": rule.get("channels", ["email"])
                }
            ]
        }
        truthvouch_rules.append(truthvouch_rule)

    return truthvouch_rules

def convert_condition(legacy_condition: str) -> dict:
    """Convert condition syntax."""
    # Example: "confidence < 0.7 && category = 'healthcare'"
    # Convert to TruthVouch condition format
    return {
        "type": "expression",
        "expression": legacy_condition
    }

Parallel Running

Run both systems simultaneously during transition:

Legacy System             TruthVouch
    |                        |
    v                        v
LLM Response
    |
    +---> Compare Results
    |
    v
Single Response
(with metadata from both)

Implementation (Python)

from truthvouch.client import TruthVouchClient
import asyncio

async def parallel_verification(
    text: str,
    legacy_client,
    truthvouch_client: TruthVouchClient
):
    """Run verification on both systems."""

    # Parallel execution
    legacy_result, truthvouch_result = await asyncio.gather(
        asyncio.to_thread(lambda: legacy_client.verify(text)),
        truthvouch_client.verify_fact(text)
    )

    # Compare results
    comparison = {
        "text": text,
        "legacy": {
            "score": legacy_result.score,
            "verdict": legacy_result.verdict
        },
        "truthvouch": {
            "score": truthvouch_result.confidence,
            "verdict": "pass" if truthvouch_result.confidence > 0.7 else "fail"
        },
        "agreement": legacy_result.verdict == (
            "pass" if truthvouch_result.confidence > 0.7 else "fail"
        )
    }

    return comparison

API Migration

Endpoint Mapping

Map legacy API endpoints to TruthVouch:

Legacy Endpoint	TruthVouch Equivalent
`POST /verify`	`POST /api/v1/shield/verify`
`GET /rules`	`GET /api/v1/governance/policies`
`POST /rules`	`POST /api/v1/governance/policies`
`POST /alerts`	`POST /api/v1/webhooks/create`

Adapter Layer

from fastapi import FastAPI, Body
from truthvouch.client import TruthVouchClient

app = FastAPI()
tv_client = TruthVouchClient(api_key="your-api-key")

@app.post("/verify")  # Legacy endpoint
async def verify_legacy(
    text: str = Body(...),
    knowledge_base: str = Body(default=None)
):
    """Adapter: legacy endpoint -> TruthVouch API."""

    result = await tv_client.verify_fact(
        text=text,
        knowledge_base_id=knowledge_base
    )

    # Return in legacy format
    return {
        "score": result.confidence,
        "verdict": "pass" if result.confidence > 0.7 else "fail",
        "citations": result.citations
    }

@app.get("/rules")  # Legacy endpoint
async def get_rules():
    """Adapter: list policies in legacy format."""

    policies = await tv_client.governance.list_policies()

    # Transform to legacy format
    return {
        "rules": [
            {
                "name": p.name,
                "threshold": p.threshold,
                "enabled": p.enabled
            }
            for p in policies
        ]
    }

Testing and Validation

Test Plan

def test_migration():
    """Validate migration completeness."""

    # Test 1: Knowledge base completeness
    legacy_count = count_facts_in_legacy_system()
    truthvouch_count = tv_client.knowledge_base.count()

    assert truthvouch_count == legacy_count, \
        f"Missing {legacy_count - truthvouch_count} facts"

    # Test 2: Policy migration
    legacy_rules = export_rules_from_legacy()
    truthvouch_policies = tv_client.governance.list_policies()

    assert len(truthvouch_policies) >= len(legacy_rules), \
        "Not all rules were migrated"

    # Test 3: API compatibility
    test_queries = [
        "OpenAI raised $10B",
        "Claude can analyze code",
        "Anthropic founded in 2021"
    ]

    for query in test_queries:
        legacy_result = legacy_client.verify(query)
        truthvouch_result = tv_client.verify_fact(query)

        # Check agreement rate
        legacy_pass = legacy_result.score > 0.7
        truthvouch_pass = truthvouch_result.confidence > 0.7

        assert legacy_pass == truthvouch_pass, \
            f"Results diverged for: {query}"

    print("✓ Migration validation passed")

Validation Report

After migration, generate a comparison report:

def generate_migration_report(duration_days: int) -> dict:
    """Compare system performance during migration period."""

    legacy_metrics = get_metrics_from_legacy(days=duration_days)
    truthvouch_metrics = get_metrics_from_truthvouch(days=duration_days)

    return {
        "period": f"Last {duration_days} days",
        "knowledge_base": {
            "legacy_facts": legacy_metrics["fact_count"],
            "truthvouch_nuggets": truthvouch_metrics["nugget_count"],
            "difference": abs(legacy_metrics["fact_count"] -
                            truthvouch_metrics["nugget_count"])
        },
        "accuracy": {
            "legacy_avg_confidence": legacy_metrics["avg_score"],
            "truthvouch_avg_confidence": truthvouch_metrics["avg_confidence"],
            "agreement_rate": calculate_agreement_rate()
        },
        "performance": {
            "legacy_latency_ms": legacy_metrics["avg_latency"],
            "truthvouch_latency_ms": truthvouch_metrics["avg_latency"],
            "improvement": f"{((legacy_metrics['avg_latency'] - truthvouch_metrics['avg_latency']) / legacy_metrics['avg_latency'] * 100):.1f}%"
        },
        "readiness": {
            "all_policies_migrated": len(truthvouch_metrics["policies"]) >= len(legacy_metrics["rules"]),
            "kb_completeness": f"{(truthvouch_metrics['nugget_count'] / legacy_metrics['fact_count'] * 100):.1f}%",
            "integration_status": "ready" if calculate_agreement_rate() > 0.95 else "review_needed"
        }
    }

Cutover Plan

Day-1: Final Validation

Run final full comparison
Verify all integrations
Check backup systems
Notify stakeholders

Day-2: Switch Traffic

Update API endpoints
Redirect webhooks
Activate TruthVouch dashboards
Disable legacy system logging

Day-3: Monitor

Watch error rates
Check integration health
Monitor performance
Gather feedback

Days-4-30: Stabilize

Address any issues
Optimize configurations
Run optimization on knowledge base
Decommission legacy system (after 30 days)

Support During Migration

TruthVouch provides:

Migration engineer: Dedicated support during transition
Parallel run environment: Test before production
Rollback capability: Revert to legacy if needed
Daily standups: During first 2 weeks

Contact: migration-support@truthvouch.com

Post-Migration Optimization

After cutover, optimize TruthVouch:

# 1. Fine-tune confidence thresholds
def optimize_thresholds():
    # Analyze false positive/negative rates
    # Adjust per-category thresholds
    pass

# 2. Expand knowledge base
def expand_knowledge_base():
    # Add new domain-specific nuggets
    # Increase coverage
    pass

# 3. Custom policies
def create_custom_policies():
    # Implement organization-specific rules
    # Set up automated remediation
    pass

Troubleshooting

Q: Data didn’t import completely

Check file format (CSV headers must match)
Verify API key has write permissions
Try importing smaller batches (500 items)

Q: Confidence scores differ significantly

Thresholds might be different
Knowledge bases might diverge
Review and align categorization

Q: Parallel running shows high divergence

May indicate existing bugs in legacy system
Run for longer period to gather statistics
Consider manual validation of discrepancies

Next Steps

Review Knowledge Base documentation
Explore Policy Writing guide
Check API Reference for all endpoints