SwisperStudio Complete Setup & Deployment Guide¶

┌──────────────────────────────────────────────────────────────┐
│                     Same Data Center                         │
│                                                               │
│  ┌─────────────────┐                 ┌──────────────────┐   │
│  │  Swisper        │                 │  SwisperStudio   │   │
│  │  Backend        │                 │                  │   │
│  │                 │                 │  ┌────────────┐  │   │
│  │  • SDK          │                 │  │ Frontend   │  │   │
│  │  • Agents       │                 │  │ (React)    │  │   │
│  │                 │                 │  └────────────┘  │   │
│  │                 │                 │  ┌────────────┐  │   │
│  └────────┬────────┘                 │  │ Backend    │  │   │
│           │                          │  │ (FastAPI)  │  │   │
│           │ Publishes                │  └────────────┘  │   │
│           │ (<2ms)                   │  ┌────────────┐  │   │
│           │                          │  │ PostgreSQL │  │   │
│           ▼                          │  └────────────┘  │   │
│  ┌─────────────────┐                │         │        │   │
│  │ Redis (Studio)  │◄───────────────┼─────────┘        │   │
│  │ :6380           │    Consumes    │                  │   │
│  └─────────────────┘                └──────────────────┘   │
│                                                               │
└───────────────────────────────────────────────────────────────┘

1. User Request → Swisper
2. Agent Execution → SDK captures events
3. SDK publishes to Redis Streams (<2ms)
4. Swisper returns response (continues normally)

   [Async, separate process]
5. Studio consumer reads from Redis
6. Events written to PostgreSQL
7. Available in Studio UI

# Clone SwisperStudio
cd /root/projects  # Or your projects directory
git clone https://github.com/Fintama/swisper_studio.git
cd swisper_studio

services:
  redis:
    image: redis:7.2-alpine
    ports:
      - "6380:6379"  # External port 6380

  postgres:
    image: postgres:15-alpine
    ports:
      - "5433:5432"  # External port 5433

  backend:
    build: ./backend
    ports:
      - "8001:8000"  # External port 8001

# SwisperStudio Configuration

# Database
POSTGRES_DB=swisper_studio
POSTGRES_USER=studio_user
POSTGRES_PASSWORD=<CHANGE_IN_PRODUCTION>

# Security
SECRET_KEY=<GENERATE_RANDOM_KEY>
API_KEY=<GENERATE_API_KEY>

# CORS (adjust for your domains)
CORS_ORIGINS='["http://localhost:3000","http://localhost:5173","https://swisper-studio.fintama.com"]'

# Environment
ENVIRONMENT=development  # development | staging | production
LOG_LEVEL=INFO  # DEBUG | INFO | WARNING | ERROR

# Observability
OBSERVABILITY_ENABLED=true
OBSERVABILITY_REDIS_URL=redis://redis:6379
OBSERVABILITY_STREAM_NAME=observability:events
OBSERVABILITY_GROUP_NAME=swisper_studio_consumers
OBSERVABILITY_CONSUMER_NAME=consumer_1
OBSERVABILITY_BATCH_SIZE=100

# Generate SECRET_KEY
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Generate API_KEY
python3 -c "import secrets; print('studio_' + secrets.token_hex(32))"

# Start all services
docker compose up -d

# Check status
docker compose ps

# Expected output:
# NAME                       STATUS              PORTS
# swisper_studio_redis       Up (healthy)        0.0.0.0:6380->6379/tcp
# swisper_studio_postgres    Up (healthy)        0.0.0.0:5433->5432/tcp
# swisper_studio_backend     Up                  0.0.0.0:8001->8000/tcp

# Run database migrations
docker compose exec backend alembic upgrade head

# Verify migrations
docker compose exec postgres psql -U studio_user -d swisper_studio -c "\dt"

# Should show tables: traces, observations, projects, users, etc.

# Create initial admin user
docker compose exec backend python -m app.scripts.create_admin \
  --email admin@fintama.com \
  --password <secure-password>

# Or use the API
curl -X POST http://localhost:8001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@fintama.com",
    "password": "<secure-password>",
    "name": "Admin User"
  }'

# 1. Check backend health
curl http://localhost:8001/health

# Expected: {"status":"healthy","version":"0.1.0"}

# 2. Check Redis
docker exec swisper_studio_redis redis-cli ping

# Expected: PONG

# 3. Check Redis port exposure
docker port swisper_studio_redis

# Expected: 6379/tcp -> 0.0.0.0:6380

# 4. Check PostgreSQL
docker exec swisper_studio_postgres pg_isready -U studio_user

# Expected: /var/run/postgresql:5432 - accepting connections

# Start frontend development server
cd frontend
npm install
npm run dev

# Access at: http://localhost:3000

# Activate your Python environment
cd /path/to/swisper/backend
source .venv/bin/activate  # Or your venv path

# Install SDK from PyPI
pip install swisper-studio-sdk==0.5.0

# Verify installation
python -c "from swisper_studio_sdk import create_traced_graph; print('✅ SDK Ready')"

# SwisperStudio Observability
swisper-studio-sdk==0.5.0

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # ... existing settings ...

    # SwisperStudio Integration
    SWISPER_STUDIO_ENABLED: bool = True
    SWISPER_STUDIO_REDIS_URL: str = "redis://172.17.0.1:6380"  # Docker host IP
    SWISPER_STUDIO_STREAM_NAME: str = "observability:events"
    SWISPER_STUDIO_PROJECT_ID: str = ""  # Get from Studio UI
    SWISPER_STUDIO_CAPTURE_REASONING: bool = True
    SWISPER_STUDIO_REASONING_MAX_LENGTH: int = 50000

    class Config:
        env_file = ".env"
        case_sensitive = True

settings = Settings()

# SwisperStudio Observability
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380
SWISPER_STUDIO_PROJECT_ID=<GET_FROM_STUDIO_UI>

# 1. Access Studio UI
# Development: http://localhost:3000
# Production: https://swisper-studio.fintama.com

# 2. Navigate to "Projects" → "Create New Project"
#    - Name: "Swisper Production" (or "Swisper Development")
#    - Description: Main Swisper application
#    - Click "Create"

# 3. Click on the project, copy UUID from URL
#    URL: /projects/{THIS_IS_YOUR_PROJECT_ID}/traces
#    Example: /projects/0d7aa606-cb29-4a31-8a59-50fa61151a32/traces

# 4. Update .env file
echo "SWISPER_STUDIO_PROJECT_ID=0d7aa606-cb29-4a31-8a59-50fa61151a32" >> .env

import logging
from fastapi import FastAPI
from contextlib import asynccontextmanager

logger = logging.getLogger(__name__)

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Application lifespan"""

    # ===== STARTUP =====

    # ... existing startup code ...

    # Initialize SwisperStudio observability
    if settings.SWISPER_STUDIO_ENABLED:
        try:
            from swisper_studio_sdk import initialize_redis_publisher, wrap_llm_adapter

            # Initialize Redis publisher
            verification = await initialize_redis_publisher(
                redis_url=settings.SWISPER_STUDIO_REDIS_URL,
                stream_name=settings.SWISPER_STUDIO_STREAM_NAME,
                project_id=settings.SWISPER_STUDIO_PROJECT_ID,
                max_stream_length=100000,
                verify_consumer=True,
            )

            logger.info("✅ SwisperStudio observability initialized")
            logger.info(f"   Redis: {settings.SWISPER_STUDIO_REDIS_URL}")
            logger.info(f"   Project ID: {settings.SWISPER_STUDIO_PROJECT_ID}")
            logger.info(f"   Verification: {verification}")

            # Enable LLM prompt capture
            try:
                wrap_llm_adapter()
                logger.info("✅ LLM prompt capture enabled")
            except Exception as e:
                logger.warning(f"⚠️ LLM capture disabled: {e}")

        except ImportError:
            logger.warning("⚠️ SwisperStudio SDK not installed")
        except Exception as e:
            logger.error(f"❌ SwisperStudio initialization failed: {e}")
            logger.warning("   Continuing without observability")

    yield  # Application runs

    # ===== SHUTDOWN =====

    # Close SwisperStudio publisher
    if settings.SWISPER_STUDIO_ENABLED:
        try:
            from swisper_studio_sdk import close_redis_publisher
            await close_redis_publisher()
            logger.info("✅ SwisperStudio publisher closed")
        except Exception as e:
            logger.warning(f"⚠️ Failed to close publisher: {e}")

    # ... existing shutdown code ...

app = FastAPI(lifespan=lifespan)

from langgraph.graph import StateGraph

def build_graph(self):
    """Build LangGraph workflow"""

    # Wrap with SwisperStudio tracing
    try:
        from swisper_studio_sdk import create_traced_graph
        workflow = create_traced_graph(
            GlobalSupervisorState,
            trace_name="global_supervisor"
        )
        self.logger.info("✅ GlobalSupervisor wrapped with tracing")
    except ImportError:
        workflow = StateGraph(GlobalSupervisorState)
        self.logger.warning("⚠️ Tracing disabled (SDK not available)")

    # Add nodes (existing code)
    workflow.add_node("start", self.start_node)
    workflow.add_node("route", self.route_node)
    # ... etc

    return workflow.compile()

from typing import TypedDict, List, Dict, Any, Optional

class YourAgentState(TypedDict):
    # ... existing fields ...

    # SwisperStudio observability (add these)
    _tools_executed: List[Dict[str, Any]]
    _tools_executed_by: Optional[str]

from datetime import datetime, timezone

async def execute_tools(self, state):
    """Execute tools and populate observability data"""

    # Execute tool (your existing logic)
    result = await self.execute_tool(tool_name, params)

    # Create standardized tool entry
    tool_entry = {
        "tool_name": tool_name,
        "parameters": params,
        "result": result,
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "status": "success" if result else "failure"
    }

    # Append to _tools_executed
    existing = state.get("_tools_executed", [])
    updated = existing + [tool_entry]

    # Update state
    return {
        **state,
        "_tools_executed": updated,
        "_tools_executed_by": "tool_execution",  # MUST match node name!
    }

# If using Docker
docker compose restart backend

# If running locally
# Stop the server (Ctrl+C)
# Start again
uvicorn app.main:app --reload

# Check logs for confirmation
# Should see:
# ✅ SwisperStudio observability initialized
# ✅ LLM prompt capture enabled
# ✅ GlobalSupervisor wrapped with tracing
# ✅ ResearchAgent wrapped with tracing
# ... etc

cd /root/projects/swisper_studio
./scripts/verify_deployment.sh

# Expected output:
# ✅ SwisperStudio Redis is running
# ✅ SwisperStudio Backend is running
# ✅ Redis responds to PING
# ✅ Redis exposed on host port 6380
# ✅ Backend health endpoint OK
# ... etc

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Search for Python tutorials"
  }'

docker exec swisper_studio_redis redis-cli XLEN observability:events

# Should show: 10 (or some number > 0)

# Open in browser: http://localhost:3000
# Navigate to: Projects > Your Project > Traces
# Should see your test trace with:
# - Agent execution graph
# - State transitions
# - Tool executions
# - LLM prompts/responses

# 1. Stop Studio backend
docker compose stop backend

# 2. Send request through Swisper
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Test without Studio"}'

# 3. Swisper should respond normally ✅
# Events will queue in Redis (up to 100k)

# 4. Restart Studio
docker compose start backend

# 5. Studio will process queued events
docker logs swisper_studio_backend | grep "Processing batch"

# Should see: "Processing batch of N events"

# Without SDK (baseline)
time curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

# Record time: ~500ms (example)

# With SDK enabled (should be nearly identical)
# Overhead should be < 2ms per request

ENVIRONMENT=development
LOG_LEVEL=DEBUG
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380

ENVIRONMENT=staging
LOG_LEVEL=INFO
SWISPER_STUDIO_REDIS_URL=redis://swisper-studio-redis.staging.internal:6379

ENVIRONMENT=production
LOG_LEVEL=WARNING
SWISPER_STUDIO_REDIS_URL=redis://swisper-studio-redis.prod.internal:6379

# SECRET_KEY (64 characters)
openssl rand -base64 48

# API_KEY
openssl rand -hex 32

# PostgreSQL password (16+ characters)
openssl rand -base64 16

# Update in docker-compose.yml and .env

# Only allow your domains
CORS_ORIGINS='["https://swisper-studio.fintama.com"]'

# Add nginx reverse proxy
services:
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl

# Add to crontab
0 2 * * * docker exec swisper_studio_postgres pg_dump \
  -U studio_user swisper_studio | \
  gzip > /backups/swisper_studio_$(date +\%Y\%m\%d).sql.gz

# Retention: Keep 30 days
find /backups -name "swisper_studio_*.sql.gz" -mtime +30 -delete

services:
  redis:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

  postgres:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

# apps/backend/swisper/services/metrics.py
from prometheus_client import Counter, Histogram

events_published = Counter(
    'swisper_studio_events_published_total',
    'Total events published to Redis'
)

event_publish_duration = Histogram(
    'swisper_studio_event_publish_duration_seconds',
    'Time to publish event to Redis'
)

# apps/backend/swisper/api/routes/metrics.py
from fastapi import APIRouter
from prometheus_client import generate_latest

router = APIRouter()

@router.get("/metrics")
async def metrics():
    return Response(
        generate_latest(),
        media_type="text/plain"
    )

# apps/backend/swisper/core/logging_config.py
import logging
import json

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_data = {
            "timestamp": self.formatTime(record),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
        }
        return json.dumps(log_data)

# Configure
logging.basicConfig(
    level=logging.INFO,
    handlers=[logging.StreamHandler()],
    format='%(message)s'
)

@router.get("/health/detailed")
async def detailed_health():
    """Comprehensive health check"""

    health = {
        "status": "healthy",
        "timestamp": datetime.utcnow().isoformat(),
        "version": "0.1.0",
        "components": {}
    }

    # Check database
    try:
        await db.execute("SELECT 1")
        health["components"]["database"] = {"status": "up"}
    except Exception as e:
        health["components"]["database"] = {"status": "down", "error": str(e)}
        health["status"] = "degraded"

    # Check Redis
    try:
        await redis.ping()
        health["components"]["redis"] = {"status": "up"}
    except Exception as e:
        health["components"]["redis"] = {"status": "down", "error": str(e)}
        health["status"] = "degraded"

    # Check consumer
    try:
        heartbeat = await redis.get("swisper_studio:consumer:heartbeat")
        if heartbeat:
            health["components"]["consumer"] = {"status": "up"}
        else:
            health["components"]["consumer"] = {"status": "down"}
            health["status"] = "degraded"
    except Exception as e:
        health["components"]["consumer"] = {"status": "unknown"}

    return health

# Stream length
swisper_studio_stream_length{stream="observability:events"}

# Consumer lag
swisper_studio_consumer_lag_seconds

# Event publish rate
rate(swisper_studio_events_published_total[5m])

# P99 publish latency
histogram_quantile(0.99, 
  rate(swisper_studio_event_publish_duration_seconds_bucket[5m])
)

{
  "dashboard": {
    "title": "SwisperStudio Observability",
    "panels": [
      {
        "title": "Event Publish Rate",
        "targets": [{
          "expr": "rate(swisper_studio_events_published_total[5m])"
        }]
      },
      {
        "title": "Stream Length",
        "targets": [{
          "expr": "swisper_studio_stream_length"
        }]
      },
      {
        "title": "P99 Latency",
        "targets": [{
          "expr": "histogram_quantile(0.99, rate(swisper_studio_event_publish_duration_seconds_bucket[5m]))"
        }]
      }
    ]
  }
}

groups:
  - name: swisper_studio
    rules:
      - alert: StreamNearCapacity
        expr: swisper_studio_stream_length > 80000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Stream near capacity ({{ $value }} / 100k)"

      - alert: ConsumerDown
        expr: absent(swisper_studio_consumer_heartbeat) == 1
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Consumer heartbeat missing"

      - alert: HighPublishLatency
        expr: histogram_quantile(0.99, rate(swisper_studio_event_publish_duration_seconds_bucket[5m])) > 0.01
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "P99 latency > 10ms"

# 1. Check if consumer is running
docker logs swisper_studio_backend | grep consumer

# 2. Check for errors
docker logs swisper_studio_backend | grep ERROR

# 3. Restart backend
docker compose restart backend

# 4. Verify recovery
curl http://localhost:8001/health/detailed

# 1. Check stream length
docker exec swisper_studio_redis redis-cli XLEN observability:events

# 2. Check consumer lag
docker logs swisper_studio_backend | tail -100

# 3. If consumer stuck, restart
docker compose restart backend

# 4. If persistent, check DB performance
docker exec swisper_studio_postgres pg_stat_activity

# 1. Check Redis memory
docker exec swisper_studio_redis redis-cli INFO memory

# 2. Check stream length
docker exec swisper_studio_redis redis-cli XLEN observability:events

# 3. If needed, trim stream (CAUTION: data loss)
docker exec swisper_studio_redis redis-cli XTRIM observability:events MAXLEN 50000

# 4. Monitor recovery
watch docker stats swisper_studio_redis

⚠️ SwisperStudio initialization failed: Connection refused

# 1. Check Studio Redis is running
docker ps | grep swisper_studio_redis

# 2. Check port exposure
docker port swisper_studio_redis
# Should show: 6379/tcp -> 0.0.0.0:6380

# 3. Test from host
redis-cli -h 127.0.0.1 -p 6380 ping
# Should return: PONG

# 4. Find Docker host IP
docker network inspect bridge | grep Gateway
# Use this IP in SWISPER_STUDIO_REDIS_URL

# 5. Update Swisper config
SWISPER_STUDIO_REDIS_URL=redis://<GATEWAY_IP>:6380

# 1. Check events are in Redis
docker exec swisper_studio_redis redis-cli XLEN observability:events
# Should be > 0

# 2. Check Studio backend is running
docker ps | grep swisper_studio_backend

# 3. Check consumer logs
docker logs swisper_studio_backend | grep "Processing batch"
# Should see periodic processing

# 4. Check for errors
docker logs swisper_studio_backend | grep ERROR

# 5. If no processing, restart
docker compose restart backend

# 6. Verify project ID matches
# In Swisper config vs Studio UI

# 1. Check if Redis is overloaded
docker exec swisper_studio_redis redis-cli INFO stats
# Look for: instantaneous_ops_per_sec

# 2. Check network latency
docker exec swisper-backend ping -c 10 172.17.0.1

# 3. Check if Studio Redis is in same data center
# If cross-DC, implement bridge relay (see architecture docs)

# 4. Verify MAXLEN is set in SDK
# Should be 100k in SDK initialization

# 5. Scale Redis if needed
# Add read replicas or increase resources

# 1. Check slow queries
docker exec swisper_studio_postgres psql -U studio_user -d swisper_studio -c \
  "SELECT query, calls, total_time FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;"

# 2. Check DB size
docker exec swisper_studio_postgres psql -U studio_user -d swisper_studio -c \
  "SELECT pg_size_pretty(pg_database_size('swisper_studio'));"

# 3. Check indexes
docker exec swisper_studio_postgres psql -U studio_user -d swisper_studio -c \
  "SELECT schemaname, tablename, indexname FROM pg_indexes WHERE schemaname = 'public';"

# 4. Run VACUUM if needed
docker exec swisper_studio_postgres psql -U studio_user -d swisper_studio -c \
  "VACUUM ANALYZE;"

# 5. Consider partitioning (for large datasets)
# Partition traces table by date

swisper_studio/
├── docker-compose.yml          # Service orchestration
├── .env                        # Environment config
├── backend/
│   ├── app/
│   │   ├── main.py            # FastAPI app
│   │   ├── core/config.py     # Configuration
│   │   └── services/          # Business logic
│   ├── alembic/               # DB migrations
│   └── Dockerfile
├── frontend/
│   ├── src/                   # React app
│   ├── package.json
│   └── vite.config.ts
├── docs/
│   ├── architecture/          # Architecture docs
│   ├── deployment/            # Deployment guides
│   └── guides/                # Integration guides
└── scripts/
    └── verify_deployment.sh   # Verification script

# Deployment
docker compose up -d              # Start all services
docker compose down               # Stop all services
docker compose restart backend    # Restart backend
docker compose logs -f backend    # Follow backend logs

# Database
alembic upgrade head              # Run migrations
alembic downgrade -1              # Rollback one migration
pg_dump -U studio_user swisper_studio  # Backup database

# Redis
redis-cli -h 127.0.0.1 -p 6380 XLEN observability:events  # Stream length
redis-cli -h 127.0.0.1 -p 6380 INFO memory               # Memory usage
redis-cli -h 127.0.0.1 -p 6380 FLUSHALL                  # Clear all data (DANGER!)

# Health Checks
curl http://localhost:8001/health                    # Basic health
curl http://localhost:8001/health/detailed           # Detailed health
docker exec swisper_studio_redis redis-cli ping      # Redis health
docker exec swisper_studio_postgres pg_isready       # PostgreSQL health

# Verification
./scripts/verify_deployment.sh                       # Full verification