Deployment and Testing Guide¶

Version: 1.0 Date: February 4, 2026 Branch: integration/deep-agent-final Status: Active

Overview¶

This guide covers deploying and testing the Deep Agent integration locally or on the dev environment. It includes Vertex AI credential setup, database migrations, UAT data seeding, and comprehensive testing.

Note: Extensive documentation has been created for this integration. See the Next Steps section for a complete reference to all available documentation, including architecture guides, feature documentation, ADRs, runbooks, and testing scripts.

Table of Contents¶

1. Prerequisites
2. Vertex AI Credentials Setup
3. Environment Configuration
4. Database Migrations
5. UAT Data Seeding
6. Running the Application
7. Testing
8. Troubleshooting

1. Prerequisites¶

Required Tools¶

• Docker & Docker Compose
• Git
• Node.js >= 20.17.0
• Python 3.12 (for local development)

Clone and Checkout¶

git clone https://github.com/Fintama/helvetiq.git
cd helvetiq
git checkout integration/deep-agent-final

2. Vertex AI Credentials Setup¶

The Deep Agent integration uses Google Vertex AI for LLM inference. You need to configure service account credentials.

Step 1: Create Credentials File¶

Place your GCP service account JSON at apps/backend/credentials/vertex-service-account.json.

Note: Obtain credentials from your GCP project. Do not commit credentials to the repository. The apps/backend/credentials/ directory is already gitignored.

3. Environment Configuration¶

Step 1: Copy Environment Template¶

cp .env.example .env

Step 2: Configure Vertex AI Settings¶

Add/update the following in your .env file:

# Vertex AI Configuration
GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/vertex-service-account.json
VERTEX_AI_PROJECT=swisper
VERTEX_AI_LOCATION=europe-west1

# Embedding Model (Vertex AI)
EMBEDDING_MODEL=vertex_ai
VERTEX_EMBEDDING_MODEL=gemini-embedding-001
VERTEX_EMBEDDING_DIMENSIONS=2000

The credentials directory is already volume-mounted in docker-compose.yml:

services:
  backend:
    volumes:
      - ./apps/backend/credentials:/app/credentials:ro

4. Database Migrations¶

Step 1: Start Database¶

docker compose up -d db redis

Step 2: Build and Start Backend¶

docker compose build backend
docker compose up -d backend

Step 3: Run Migrations¶

Migrations run automatically on startup via the prestart.sh script. To verify:

# Check migration status
docker compose exec backend alembic current

# If needed, run migrations manually
docker compose exec backend alembic upgrade head

Expected migrations include: - m02_global_supervisor_llm_nodes - m03_facts_attribute_qualifier - m04_contacts_electronic_addresses - m07_swisper_studio_config - m12_role_to_string - m13_migrate_embeddings_to_3072 - 20260203_add_vertex_ai_support - 20260204_vertex_all_nodes

5. UAT Data Seeding¶

Step 1: Run the Seed Script¶

# Full reset + seed (recommended for clean testing)
docker compose exec backend python app/scripts/seed_uat_data.py --reset

This creates: - Admin user with test entities - Disambiguation pairs (Thomas, Leo, Michael, Sarah, etc.) - Facts for each entity (birthdays, preferences, dietary info) - Role embeddings for entity resolution

Step 2: Verify Seeding¶

# Check user was created
docker compose exec backend python -c "
from swisper.core.db import engine
from swisper.persistence.models import User
from sqlmodel import Session, select
with Session(engine) as db:
    user = db.exec(select(User).where(User.email == 'admin@example.com')).first()
    print(f'User: {user.email if user else \"NOT FOUND\"}')"

Test Credentials¶

6. Running the Application¶

Start All Services¶

docker compose up -d

Verify Health¶

docker compose ps

Expected healthy services: - backend - FastAPI application - db - PostgreSQL database - redis - Session and cache storage - minio - S3-compatible object storage - mcp-research - Research agent MCP server - mcp-wealth - Wealth agent MCP server

Start Frontend (Development)¶

pnpm install
pnpm run dev

Access the application at: http://localhost:5173

7. Testing¶

7.1 Automated Tests¶

Backend CI Tests¶

# Copy latest code to container
docker compose cp apps/backend/swisper/. backend:/app/swisper/
docker compose cp apps/backend/tests/. backend:/app/tests/

# Run CI-critical tests
docker compose exec backend pytest tests/ -m ci_critical -vv

# Run all tests (takes longer)
docker compose exec backend pytest tests/ -vv

Frontend TypeScript Check¶

cd apps/frontend
npx tsc --noEmit

7.2 UAT Manual Testing¶

Use the comprehensive UAT script for manual testing:

📄 UAT_script_deep_agent_v2.md

Key Test Categories¶

Sample Test Flow¶

1. Login as admin@example.com / swisperswisper

2. Test Disambiguation:

   You: "Send an email to Thomas"
   Expected: Swisper asks which Thomas (Weber or Schmidt)
   

3. Test Entity Resolution:

   You: "What's Leo's birthday?"
   Expected: Swisper identifies Leo (8-year-old son) from context
   

4. Test Fact Extraction:

   You: "By the way, my mom's name is Elisabeth"
   Expected: Swisper acknowledges and stores the fact
   

5. Test Admin Panel:

6. Navigate to Settings → Admin Tools
7. Verify LLM node configuration displays
8. Check system health status

8. Troubleshooting¶

Vertex AI Authentication Errors¶

google.auth.exceptions.DefaultCredentialsError

Fix: Ensure the credentials file is mounted correctly:

# Verify file exists
ls -la apps/backend/credentials/vertex-service-account.json

# Check mount in container
docker compose exec backend ls -la /app/credentials/vertex-service-account.json

Migration Errors¶

alembic.util.exc.CommandError: Can't locate revision

Fix: Reset and re-run migrations:

docker compose exec backend alembic stamp head
docker compose exec backend alembic upgrade head

Embedding Dimension Mismatch¶

ValueError: Embedding dimension mismatch

Fix: Re-run the embedding migration:

docker compose exec backend python -m swisper.scripts.migrate_embeddings_to_vertex

Container Not Picking Up Changes¶

# Rebuild the backend image
docker compose build backend

# Restart with fresh container
docker compose down backend
docker compose up -d backend

Redis Connection Issues¶

# Clear Redis cache
docker compose exec redis redis-cli FLUSHALL

Quick Reference¶

Commands Cheat Sheet¶

Key URLs¶

Test Credentials¶

Next Steps¶

After successful deployment and testing, explore the comprehensive documentation that has been created for this integration.

Documentation Overview¶

We've produced extensive documentation to help you understand and work with the Deep Agent integration:

Architecture & System Design¶

Core Features¶

Configuration & Admin¶

Development & Patterns¶

Technical Decisions¶

Migration & Operations¶

Testing¶

Support¶

For issues or questions: - Start with: START_HERE.md for the documentation index - Review test logs: docker compose logs backend - Check the UAT script for testing guidance - Create an issue on GitHub