SwisperStudio Architecture Overview¶

┌─────────────────────────────────────┐         ┌──────────────────────────────────┐
│      SwisperStudio Platform         │         │          Swisper                 │
│                                     │         │                                  │
│  ┌──────────────┐  ┌──────────────┐│         │  ┌───────────────────────────┐  │
│  │   Frontend   │  │   Backend    ││         │  │    Swisper Backend        │  │
│  │              │  │              ││         │  │    + SDK v0.5.0           │  │
│  │  React + MUI │◄─┤   FastAPI    ││         │  │                           │  │
│  │  + Vite      │  │  + SQLModel  ││         │  │  Port 8000                │  │
│  │              │  │              ││         │  └─────────┬─────────────────┘  │
│  │  Port 3000   │  │  Port 8001   ││         │            │                    │
│  └──────────────┘  └──────┬───────┘│         │  ┌─────────▼─────────────────┐  │
│                           │        │         │  │  SwisperStudio SDK        │  │
│  ┌──────────────┐  ┌──────▼───────┐│         │  │                           │  │
│  │  PostgreSQL  │  │    Redis     ││         │  │  • @traced decorator      │  │
│  │              │  │              ││◄────────┼──┤  • State capture          │  │
│  │  Traces      │  │  Streams     ││ Events  │  │  • Tool extraction        │  │
│  │  Observations│  │  Cache       ││         │  │  • Redis publisher        │  │
│  │  Pricing     │  │              ││         │  └───────────────────────────┘  │
│  │              │  │              ││         │            │                    │
│  │  Port 5433   │  │  Port 6379   ││         │  ┌─────────▼─────────────────┐  │
│  └──────────────┘  └──────────────┘│         │  │  4 LangGraph Agents       │  │
│                                     │         │  │                           │  │
└─────────────────────────────────────┘         │  │  • Research Agent         │  │
                                                │  │  • Productivity Agent     │  │
                                                │  │  • Wealth Agent           │  │
                                                │  │  • Document Agent         │  │
                                                │  └───────────────────────────┘  │
                                                │                                  │
                                                └──────────────────────────────────┘

1. User Request
   └─► Swisper Frontend (Port 5173)
       └─► Swisper Backend API (Port 8000)

2. LangGraph Execution
   └─► SDK wraps graph.ainvoke()
       └─► Creates Trace (user_id, session_id, name)

3. Node Execution
   └─► @traced decorator captures:
       • State (before/after)
       • LLM calls (prompts, responses, tokens)
       • Tool executions (arguments, results)
       • Errors (if any)

4. Event Publishing
   └─► SDK publishes to Redis Streams
       └─► Event: { type, trace_id, observation, metadata }

5. SwisperStudio Consumption
   └─► Backend consumer reads Redis stream
       └─► Stores in PostgreSQL (traces + observations)
       └─► Calculates costs (model_pricing table)

6. Frontend Display
   └─► User opens SwisperStudio
       └─► Fetches traces via REST API
       └─► Displays tree/graph/timeline with state + costs

1. Admin toggles tracing OFF for project
   └─► Frontend: PATCH /projects/{id}/tracing { enabled: false }

2. Backend updates cache
   └─► Redis: SET tracing:project:{id} "false" (immediate)
   └─► PostgreSQL: UPDATE projects SET tracing_enabled = false

3. Next Swisper request
   └─► SDK checks: is_tracing_enabled_for_project(project_id)
       └─► Redis lookup (< 2ms)
       └─► If disabled: Skip all tracing (zero overhead)
       └─► If enabled: Normal tracing flow

id (UUID)
project_id (FK)
user_id (String)
session_id (String)
name (String)
input (JSON)
output (JSON)
metadata (JSON)
created_at (Timestamp)

id (UUID)
trace_id (FK)
parent_observation_id (FK, nullable)
type (SPAN, GENERATION, TOOL, AGENT, EVENT)
name (String)
input (JSON)        -- State before / LLM prompt
output (JSON)       -- State after / LLM response
metadata (JSON)
level (INFO, WARNING, ERROR)
status_message (String)

-- Telemetry
start_time (Timestamp)
end_time (Timestamp)
model (String)
model_parameters (JSON)
prompt_tokens (Integer)
completion_tokens (Integer)
total_tokens (Integer)
total_cost (Decimal)        -- Calculated from model_pricing

id (UUID)
project_id (FK, nullable)   -- NULL = global pricing
hosting_provider (String)   -- e.g., "inference-apertus-8b"
model_name (String)         -- e.g., "swiss-ai/Apertus-8B-Instruct-2509"
type (String)               -- Chat, Embedding, Multimodal, etc.
description (Text)          -- Model capabilities
input_price_per_million (Decimal)   -- CHF
output_price_per_million (Decimal)  -- CHF
created_at (Timestamp)
updated_at (Timestamp)

UNIQUE (project_id, hosting_provider, model_name)