Back to Publiclear

Publiclear Simulation Studio Implementation Spec

Single handoff document for frontend, backend, and realtime infrastructure. Covers screen flow, data contracts, streaming events, and acceptance tests.

Updated: February 22, 2026 (Asia/Kolkata)

1) Product Architecture

2) Screen Map and Route Flow

3) Ingestion State Machine

{
  "states": [
    "idle",
    "uploading",
    "queued",
    "extracting_text",
    "chunking",
    "embedding",
    "indexing",
    "complete",
    "failed"
  ],
  "metrics": {
    "progress_pct": "number",
    "chunks_done": "number",
    "chunks_total": "number",
    "token_count": "number"
  }
}

4) Personality Calibration Schema

{
  "display_name": "string (2-80)",
  "primary_language": "en-IN | hi-IN | ...",
  "secondary_languages": ["string"],
  "speech_style": {
    "warmth": 0,
    "humor": 0,
    "formality": 0,
    "directness": 0,
    "spirituality": 0
  },
  "catchphrases": ["string"],
  "core_values_ranked": ["family", "discipline", "kindness"],
  "taboo_topics": ["string"],
  "favorite_topics": ["string"],
  "memory_cards": [
    {
      "year": 1983,
      "title": "World Cup memory",
      "people": ["brother", "neighbors"],
      "context": "street radio listening",
      "tone": "joyful"
    }
  ]
}

5) Voice Training Contract

{
  "status": "quality_failed",
  "report": {
    "snr_db": 13.2,
    "clipping_pct": 0.4,
    "silence_pct": 42.1,
    "single_speaker_confidence": 0.91
  },
  "issues": [
    {"code": "LOW_SNR", "message": "Move to quieter room"},
    {"code": "TOO_MUCH_SILENCE", "message": "Speak continuously"}
  ]
}

6) Avatar Upload Contract

{
  "status": "accepted",
  "quality_report": {
    "face_count": 1,
    "occlusion_score": 0.08,
    "yaw_deg": 6.1,
    "pitch_deg": 4.2,
    "lighting_score": 0.82
  }
}

7) REST API Endpoints

8) OpenAPI Snippets (YAML)

openapi: 3.1.0
info:
  title: Publiclear API
  version: 1.0.0
paths:
  /v1/simulations:
    post:
      summary: Create simulation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimulationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Simulation'
  /v1/realtime/sessions:
    post:
      summary: Create realtime session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeSessionRequest'
      responses:
        '200':
          description: Session token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeSession'
components:
  schemas:
    CreateSimulationRequest:
      type: object
      required: [name, primary_language, consent]
      properties:
        name: {type: string, minLength: 2, maxLength: 80}
        primary_language: {type: string}
        consent: {type: boolean}
    Simulation:
      type: object
      properties:
        simulation_id: {type: string}
        owner_id: {type: string}
        status: {type: string}
    RealtimeSessionRequest:
      type: object
      required: [simulation_id, relationship_id]
      properties:
        simulation_id: {type: string}
        relationship_id: {type: string}
        mode: {type: string, enum: [audio, text, multimodal]}
    RealtimeSession:
      type: object
      properties:
        session_id: {type: string}
        token: {type: string}
        expires_at: {type: string, format: date-time}

9) TypeScript Shared Interfaces

export interface Simulation {
  simulation_id: string;
  owner_id: string;
  name: string;
  primary_language: string;
  status: "draft" | "ready" | "published";
  created_at: string;
  updated_at: string;
}

export interface IngestionItem {
  ingestion_id: string;
  simulation_id: string;
  source_type: "file" | "whatsapp" | "manual" | "email_export";
  stage:
    | "idle"
    | "uploading"
    | "queued"
    | "extracting_text"
    | "chunking"
    | "embedding"
    | "indexing"
    | "complete"
    | "failed";
  progress_pct: number;
  chunks_done: number;
  chunks_total: number;
  token_count: number;
  error_code?: string;
  error_message?: string;
}

export interface RelationshipProfile {
  person_id: string;
  name: string;
  relation: string;
  closeness: 1 | 2 | 3 | 4 | 5;
  address_style: string;
  inside_jokes: string[];
  avoid_topics: string[];
  response_tone_override?: {
    warmth?: number;
    formality?: number;
    humor?: number;
    directness?: number;
  };
}

export interface TurnRequest {
  session_id: string;
  simulation_id: string;
  relationship_id: string;
  input: {
    modality: "audio" | "text";
    text?: string;
    language: string;
    audio_ref?: string;
  };
  options: {
    stream: boolean;
    temperature: number;
    max_output_tokens: number;
  };
}

export interface TurnResponse {
  turn_id: string;
  output_text: string;
  memory_citations: string[];
  latency_ms: {
    retrieval: number;
    first_token: number;
    total: number;
  };
}

10) Realtime Streaming Events

{
  "type": "response.output_text.delta",
  "turn_id": "turn_001",
  "seq": 12,
  "delta": "In school, we loved",
  "timestamp": "2026-02-22T10:15:17.311Z"
}

{
  "type": "avatar.viseme.delta",
  "turn_id": "turn_001",
  "seq": 12,
  "audio_offset_ms": 1640,
  "visemes": [
    {"t_ms": 0, "v": "AA", "w": 0.7},
    {"t_ms": 90, "v": "M", "w": 0.6},
    {"t_ms": 170, "v": "EH", "w": 0.8}
  ]
}

11) Frontend Realtime Handling Rules

12) Acceptance Test Matrix

13) Performance and SLO Targets

14) Security and Compliance Controls

This page is the implementation baseline. Engineering changes should update this spec and keep API, event, and UI contracts versioned together.