# Tough Tongue AI

> AI-powered conversational training platform for high-stakes scenarios like job interviews, sales calls, and leadership coaching. Built with FastAPI backend and Next.js frontend in a monorepo architecture.

## Platform Overview

Tough Tongue AI is your 24/7 training partner for high-stakes conversations. Whether preparing for job interviews, sales calls, salary negotiations, or leadership scenarios, the platform provides three core training approaches:

**Three ways to train:**
- **Scenario**: One-off role-plays that target a single conversation. Perfect for tomorrow's interview, next week's negotiation, or a call with a difficult customer in an hour.
- **Coach**: A topic-focused AI coach that remembers every session, adapts to your style, and handles the menial coaching work—accountability, reflection, progress tracking.
- **Course**: A structured learning experience that weaves AI role-plays with expert-led sessions to give you 1:1 attention.

**What sets Tough Tongue AI apart:**
- **Rich interactive tools**: Our agent uses a powerful reasoning model that can write code, sketch on a whiteboard, create visual cards, and drop in diagrams—making complex ideas easy to understand and enabling hyper-realistic AI roleplays
- **Unique end-to-end workflow**: We've built a complete system that helps you prepare with smart agenda creation, guides you through the conversation, and wraps up with detailed debriefs that give you actionable insights
- **Truly multimodal understanding**: Beyond creating visual artifacts, our AI reads your facial expressions, tone of voice, and body language—giving you feedback on not just what you say, but how you say it

**How it works:**
- **Voice AI Coaching Agent**: A low-latency front model holds the mic while a heavyweight reasoning model works in the background, powering those rich interactive experiences
- **Creator Studio**: Create custom practice scenarios, coaches, or courses tailored to your specific needs with our simple UI
- **Professional Library**: Access an extensive collection of professionally-designed scenarios, coaches, and courses by domain experts

## API Integration Guide

Our API offers a complete lifecycle for building conversational experiences. You start by creating **scenarios** that define the conversation structure and AI behavior. Your end users can then interact with these scenarios, which creates a **session** — a running instance of a scenario. Each user interaction is recorded in the session, and you can retrieve transcripts and detailed results using the **Get Session Details** endpoint.

### API Experience Overview

The API workflow involves 4 key parts:
1. Creating API token
2. Using API to create scenario
3. Embedding scenario in your application
4. Managing scenarios and sessions

You can use our APIs to build rich, interactive conversational features that enhance your application. The platform provides three types of iframe experiences (full, basic, minimal) and comprehensive session management capabilities.

### API Authentication

All API requests require Bearer token authentication:
```
Authorization: Bearer YOUR_API_TOKEN
```

API tokens can be created and managed from the Developer Tools page at `/developer`.

### Base URL
All API endpoints use the base URL: `https://app.toughtongueai.com/api/public`

### Developer Tools

The platform provides comprehensive developer tools accessible at `/developer`:

#### API Key Management
- Create and manage API keys with customizable permissions
- Token-based authentication for secure API access
- Multiple API keys per account for different applications

#### API Playground
- Interactive testing environment for all API endpoints
- Built-in curl command generator with automatic API key insertion
- Real-time API response preview
- Organized by endpoint categories: Scenarios, Sessions, Featured, Purchases

#### Available Endpoint Categories:

**Scenarios**:
- Create/Update scenarios (unified endpoint)
- List all scenarios
- Get specific scenario by ID
- Generate scenario access tokens for private embedding

**Sessions**:
- List sessions with filtering by scenario ID and user email
- Get detailed session information including transcripts
- Analyze sessions for evaluation and improvement insights

**Featured**:
- Access curated featured scenarios

**Purchases**:
- Track monetization and purchase history for paid scenarios

## API Endpoints

### 1. Scenario Management

#### Create/Update Scenarios
**Endpoint**: `POST /api/public/scenarios`

**Description**: Unified endpoint that handles both creating new scenarios and updating existing ones.

**Create New Scenario** (omit `id` field):
```bash
curl -X POST https://app.toughtongueai.com/api/public/scenarios \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "name": "Customer Support Training",
    "description": "Practice handling difficult customer inquiries and complaints",
    "user_friendly_description": "Improve your customer service skills through realistic scenarios",
    "ai_instructions": "You are a frustrated customer with a billing issue. Be demanding but realistic, and escalate your concerns if not addressed properly.",
    "is_public": true,
    "is_recording": true
  }'
```

**JSON Request Body**:
```json
{
  "name": "Customer Support Training",
  "description": "Practice handling difficult customer inquiries and complaints",
  "user_friendly_description": "Improve your customer service skills through realistic scenarios",
  "ai_instructions": "You are a frustrated customer with a billing issue. Be demanding but realistic, and escalate your concerns if not addressed properly.",
  "is_public": true,
  "is_recording": true
}
```

**Update Existing Scenario** (include `id` field):
```bash
curl -X POST https://app.toughtongueai.com/api/public/scenarios \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "id": "SCENARIO_ID_TO_UPDATE",
    "name": "Advanced Customer Support Training",
    "description": "Enhanced customer service training with role-play scenarios",
    "restrict_analysis": false
  }'
```

**JSON Request Body**:
```json
{
  "id": "67bf57553f44cdf6055a8167",
  "name": "Advanced Customer Support Training",
  "description": "Enhanced customer service training with role-play scenarios",
  "restrict_analysis": false
}
```

**Response**:
```json
{
  "id": "67bf57553f44cdf6055a8167",
  "name": "Customer Support Training",
  "description": "Practice handling difficult customer inquiries and complaints",
  "user_friendly_description": "Improve your customer service skills through realistic scenarios",
  "rubrik": null,
  "is_public": true,
  "passcode": null,
  "is_recording": true,
  "restrict_analysis": false
}
```

#### List All Scenarios
**Endpoint**: `GET /api/public/scenarios`

**cURL Example**:
```bash
curl -X GET https://app.toughtongueai.com/api/public/scenarios \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response**:
```json
{
  "scenarios": [
    {
      "id": "67bf56c23f44cdf6055a8165",
      "name": "Customer Support Training",
      "description": "Internal description for your team",
      "user_friendly_description": null,
      "ai_instructions": "You are a frustrated customer with a billing issue...",
      "pdf_context": "",
      "rubrik": "",
      "is_public": true,
      "passcode": null,
      "is_recording": null,
      "restrict_analysis": null
    }
  ]
}
```

#### Get Specific Scenario
**Endpoint**: `GET /api/public/scenarios/{id}`

**cURL Example**:
```bash
curl -X GET https://app.toughtongueai.com/api/public/scenarios/SCENARIO_ID \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response**:
```json
{
  "id": "689e283d8ff2b6aca6239d8b",
  "name": "Customer Support Training",
  "description": "Practice handling difficult customer inquiries and complaints",
  "user_friendly_description": "Improve your customer service skills through realistic scenarios",
  "ai_instructions": "You are a frustrated customer with a billing issue. Be demanding but realistic, and escalate your concerns if not addressed properly.",
  "pdf_context": null,
  "rubrik": "Rate based on empathy, problem-solving, and communication clarity",
  "is_public": true,
  "passcode": null,
  "is_recording": true,
  "restrict_analysis": false,
  "appearance": {
    "avatar_url": "https://example.com/avatar.png",
    "background_color": "#1a1a2e"
  },
  "memory": {
    "is_memory": true,
    "memory_type": "conversation_history"
  },
  "session_analysis": {
    "auto_analysis": true,
    "analysis_prompt": "Analyze communication effectiveness"
  },
  "ai_model_config": {
    "provider": "openai",
    "model": "gpt-4"
  },
  "is_paid": false,
  "is_recurring_payment": false,
  "price": null,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:20:00Z"
}
```

#### List Featured Scenarios
**Endpoint**: `GET /api/public/featured-scenarios`

**cURL Example**:
```bash
curl -X GET https://app.toughtongueai.com/api/public/featured-scenarios \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response**:
```json
{
  "scenarios": [
    {
      "id": "67bf56c23f44cdf6055a8165",
      "name": "Customer Support Training",
      "description": "Practice handling difficult customer inquiries",
      "user_friendly_description": "Learn how to handle difficult customers effectively",
      "user_instructions": "You are a customer support representative. Handle the frustrated customer calmly and professionally."
    }
  ]
}
```

### 2. Session Management

#### List Sessions
**Endpoint**: `GET /api/public/sessions?scenario_id=SCENARIO_ID&user_email=optional@email.com`

**Parameters**:
- `scenario_id` (required): Filter sessions by scenario ID
- `user_email` (optional): Filter sessions by user email

**cURL Example**:
```bash
curl -X GET 'https://app.toughtongueai.com/api/public/sessions?scenario_id=SCENARIO_ID&user_email=optional@email.com' \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response**:
```json
{
  "sessions": [
    {
      "id": "67bf57183f44cdf6055a8166",
      "scenario_id": "67bf56c23f44cdf6055a8165",
      "scenario_name": "Customer Support Training",
      "created_at": "2025-02-26T18:02:00.945000",
      "completed_at": "2025-02-26T18:02:08.301000",
      "status": "completed",
      "user_name": "John Doe",
      "user_email": "john.doe@example.com"
    }
  ]
}
```

#### Get Session Details
**Endpoint**: `GET /api/public/sessions/{session_id}`

**cURL Example**:
```bash
curl -X GET https://app.toughtongueai.com/api/public/sessions/SESSION_ID \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response**:
```json
{
  "id": "67c551e8aa4a6a7575d33955",
  "scenario_id": "679c838ec41cfcb298fd9ace",
  "scenario_name": "Customer Support Training",
  "created_at": "2025-03-03T06:53:28.035000",
  "completed_at": "2025-03-03T06:54:14.346000",
  "status": "completed",
  "transcript_url": "https://scenario-pdf-bucket.s3.amazonaws.com/sessions/transcript.txt",
  "evaluation_results": {
    "overall_score": "8/10",
    "strengths": "Excellent active listening skills and empathetic responses",
    "weaknesses": "Could improve on solution presentation and follow-up questions",
    "detailed_feedback": "The participant demonstrated strong communication skills throughout the conversation...",
    "report_card": [
      {
        "topic": "Communication Skills",
        "score": 7.5,
        "score_str": "7.5/10",
        "note": "Demonstrated clear articulation and professional tone throughout the interaction.",
        "weight": 30
      }
    ],
    "final_score": 7.4
  },
  "improvement_results": {
    "improvement_areas": "Solution presentation, follow-up confirmation",
    "action_items": "1. Present solutions in a clear, step-by-step manner...",
    "resources": "- **Customer Support Training Guide**: [Link to resource]..."
  },
  "user_name": "test gcp",
  "user_email": "gcptestfdfd75@gmail.com"
}
```

#### Analyze Session Data
**Endpoint**: `POST /api/public/sessions/analyze`

**cURL Example**:
```bash
curl -X POST https://app.toughtongueai.com/api/public/sessions/analyze \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "session_id": "SESSION_ID"
  }'
```

**Request Body**:
```json
{
  "session_id": "SESSION_ID"
}
```

**Response**:
```json
{
  "evaluation": {
    "overall_score": "8/10",
    "strengths": "Excellent active listening skills and empathetic responses",
    "weaknesses": "Could improve on solution presentation and follow-up questions",
    "detailed_feedback": "The participant demonstrated strong communication skills...",
    "report_card": [...],
    "final_score": 7.4
  },
  "improvement": {
    "improvement_areas": "Solution presentation, follow-up confirmation",
    "action_items": "1. Present solutions in a clear, step-by-step manner...",
    "resources": "- **Customer Support Training Guide**: [Link to resource]..."
  }
}
```

### 3. Access Token Management

#### Create Scenario Access Token
**Endpoint**: `POST /api/public/scenario-access-token`

**Description**: Generate short-lived access tokens (valid for 1 hour) for private scenario embedding.

**cURL Example**:
```bash
curl -X POST https://app.toughtongueai.com/api/public/scenario-access-token \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "scenario_id": "SCENARIO_ID"
  }'
```

**Request Body**:
```json
{
  "scenario_id": "SCENARIO_ID"
}
```

**Response**:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-02-26T19:02:00.000Z"
}
```

### 4. Purchase Management

#### List Purchases
**Endpoint**: `GET /api/public/purchases`

**cURL Example**:
```bash
curl -X GET https://app.toughtongueai.com/api/public/purchases \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**Response**:
```json
{
  "purchases": [
    {
      "id": "67bf57183f44cdf6055a8166",
      "user_id": "67bf56c23f44cdf6055a8165",
      "product_id": "67bf56c23f44cdf6055a8165",
      "product_type": "scenario",
      "product_name": "Advanced Customer Support Training",
      "scenario_name": "Advanced Customer Support Training",
      "amount": 29.99,
      "currency": "USD",
      "status": "completed",
      "purchase_date": "2025-02-26T18:02:00.945000",
      "user_name": "John Doe",
      "user_email": "john.doe@example.com"
    }
  ]
}
```

## Scenario Field Specifications

### Required Fields
- `name`: The name of your scenario
- `description`: Internal description for your reference
- `ai_instructions`: Instructions for the AI on how to behave in this scenario

### Optional Fields
- `id`: Scenario ID for updates (omit for new scenarios)
- `user_friendly_description`: Description shown to users
- `pdf_context`: Additional context in PDF format (base64 encoded)
- `rubrik`: Evaluation criteria
- `is_public`: Whether the scenario is publicly accessible (default: true)
- `passcode`: Optional passcode protection
- `is_recording`: Whether to record conversations
- `restrict_analysis`: Whether to restrict analysis features

### Session Analysis Configuration
- `session_analysis.admin_email`: Email address to send analysis reports to
- `session_analysis.is_auto_analysis`: Whether to automatically trigger analysis when session ends
- `session_analysis.is_auto_submit`: Whether to automatically submit session data without user interaction

### Advanced Features

#### Monetization
- `is_paid`: Whether scenario requires payment (default: false)
- `price`: Price amount (required if is_paid is true)
- `currency`: Currency code (default: "USD")
- `is_recurring_payment`: Whether it's a subscription model (default: false)

#### Memory & AI Customization
- `memory.is_memory`: Enable AI memory to remember conversations
- `ai_model_config.provider`: AI provider ("Ocean" or "Galaxy")
- `ai_model_config.model`: Model tier ("mini", "medium", "mini-stable", etc.)

#### Appearance Customization
- `appearance.voice`: AI voice (Aoede, Charon, Fenrir, Kore, Puck)
- `appearance.avatar_url`: Custom avatar image URL
- `appearance.language_code`: Speech language (default: "en-US")

## Embedding Scenarios

### Three Types of Iframe Experiences

#### Basic Embed (Standard size)
```html
<iframe
  src="https://app.toughtongueai.com/embed/basic/SCENARIO_ID"
  width="100%"
  height="600px"
  frameborder="0"
  allow="microphone">
</iframe>
```

#### Full Embed (Complete experience)
```html
<iframe
  src="https://app.toughtongueai.com/embed/SCENARIO_ID"
  width="100%"
  height="800px"
  frameborder="0"
  allow="microphone">
</iframe>
```

#### Minimal Embed (Compact version)
```html
<iframe
  src="https://app.toughtongueai.com/embed/minimal/SCENARIO_ID"
  width="100%"
  height="300px"
  frameborder="0"
  allow="microphone">
</iframe>
```

### Embedding Private Scenarios

For private scenarios, generate an access token and use it in the iframe URL:

```html
<iframe
  src="https://app.toughtongueai.com/embed/SCENARIO_ID?scenarioAccessToken=YOUR_ACCESS_TOKEN"
  width="100%"
  height="800px"
  frameborder="0"
  allow="microphone">
</iframe>
```

### Pre-populating User Information

Add user information as URL parameters:

```html
<iframe
  src="https://app.toughtongueai.com/embed/SCENARIO_ID?userName=John%20Doe&userEmail=john@example.com"
  width="100%"
  height="800px"
  frameborder="0"
  allow="microphone">
</iframe>
```

**Available User Parameters:**
- `userName`: The user's full name
- `userEmail`: The user's email address

### Customization Options

Add these query parameters to customize your embed:
- `name`: Custom conversation name (e.g., `?name=Support%20Training`)
- `color`: Accent color (e.g., `?color=violet-500`)
- `showPulse`: Toggle pulse animation (e.g., `?showPulse=false`)
- `background`: Background color (e.g., `?background=black`)
- `hidePoweredBy`: Hide branding (e.g., `?hidePoweredBy=true`)

### Dynamic Variables

For scenarios using dynamic variables in their AI instructions, pass variables with `t_` prefix:

```html
<iframe
  src="https://app.toughtongueai.com/embed/SCENARIO_ID?t_company_name=Acme%20Corp&t_user_role=Manager&t_interview_type=Technical"
  width="100%"
  height="800px"
  frameborder="0"
  allow="microphone">
</iframe>
```

## Iframe Event Handling

Embedded scenarios emit events that your application can listen for to track session lifecycle. Events are sent via `window.postMessage` API.

### Available Events
- **onStart**: Emitted when a session begins (agent is connected)
- **onStop**: Emitted when a session ends (agent is disconnected)
- **onSubmit**: Emitted when post-session data submission is completed

### Event Payload Structure
```javascript
{
  event: 'onStart' | 'onStop' | 'onTerminated' | 'onSubmit',  // Event type
  sessionId: string,                           // Unique session identifier
  timestamp: number                            // Unix timestamp in milliseconds
}
```

### Event Listener Implementation
```javascript
window.addEventListener('message', (event) => {
  // Optional: verify the origin for security
  // if (event.origin !== 'https://app.toughtongueai.com') return;

  const data = event.data;

  if (data && data.event) {
    switch (data.event) {
      case 'onStart':
        console.log('Session started:', data);
        // Handle session start: initialize analytics, etc.
        break;

      case 'onStop':
        console.log('Session stopped:', data);
        // Handle session end
        break;

      case 'onSubmit':
        console.log('Submission completed:', data);
        // Handle submission completion: redirect to results, etc.
        break;
    }
  }
});
```

## Core Use Cases

### Sales and Negotiation
Practice sales pitches, vendor negotiations, and client conversations. Our multimodal agent creates visual cards and diagrams to explain complex strategies in real-time.

### Leadership Coaching
Build management skills through realistic scenarios—giving feedback, handling difficult conversations, and leading meetings. The agent remembers your progress across sessions for personalized coaching.

### Job Interview Preparation
Excel in high-value interviews with specialized coaching:
- **Coding**: Agent accesses code editor, publishes questions, and provides real-time feedback
- **System Design**: Interactive whiteboard for architectural diagrams
- **MBA & PM**: Tailored scenarios with visual aids for case studies and product questions

### Professional Coaching
Our library includes scenarios designed for professional coaching:
- Salary Negotiation
- Performance Review
- Giving and Receiving Feedback
- Selling your ideas
- Handling conflict at work

## Google Meet Agent

Tough Tongue AI agents can join Google Meet calls automatically. This feature is perfect for teams that are understaffed, need help with screening calls, want to collect customer data, conduct training sessions, or when you're overbooked on your calendar.

### Getting Started
1. **Create Your Scenario**: Navigate to your scenario library and create a new scenario describing what you want the AI agent to accomplish in the meeting.
2. **Access the Meeting Bot**: Go to Library → Scenario → Meeting Bot
3. **Choose Your Mode**: Select between Custom Meeting Mode or Calendar Integration Mode

### Two Modes Available

#### Custom Meeting Mode
1. Simply provide the meeting URL or Google Meet link
2. Specify when you want the bot to join
3. Perfect for one-off meetings, dual meetings, or ad-hoc meetings

#### Calendar Integration Mode
1. First, grant access to your calendar
2. Optionally specify a keyword filter (e.g., "interview 101") so the bot only joins specific meetings
3. This prevents the agent from joining meetings where you don't want it present

### Features
- Bot automatically generates transcripts and analysis
- Works best in quiet environments with one speaker at a time
- Currently supports Google Meet (Zoom and Microsoft Teams coming soon)
- Free through August 2025 for all users

### Limitations
1. **Background noise sensitivity**: Works best in quiet environments
2. **Multiple speakers**: While multiple people can be in the meeting, the agent performs best when one person speaks at a time
3. **Platform support**: Currently limited to Google Meet (more platforms coming soon)

## Conversation Strategies

### Talkative Mode
AI agent leads the conversation and will continue with its agenda even if the human participant remains silent. Ideal for interview practice or scenarios where you want continuous guidance.

### Quiz Mode
After completing the session, this mode immediately jumps to analysis, similar to how a quiz would function. No avatar display for a simple and uniform AI-conducted quizzing experience.

### Conductor Mode
Allows you to instruct the AI to perform specific actions at precise moments during the conversation. You can set timed messages that tell the AI what to say or do at specified seconds, including ending the call at a predetermined time.

## API Best Practices

Our goal with the Tough Tongue Public API is to help you create end-to-end conversational workflows that feel native to your application.

### Sample Repositories
We've created these demonstrations to help you get started:

- **Simple Course**: Uses iframe, iframe lifecycle events, and analysis: [repo](https://github.com/tough-tongue/ttai-simple-course/tree/main), [deployment](https://tough-tongue-starter-course-yn2p.vercel.app/)
- **AI Course Creation**: Uses OpenAI to create scenarios on Tough Tongue AI: [repo](https://github.com/ajitesh123/tough-tongue-starter), [deployment](https://tough-tongue-starter.vercel.app/)

### 1. Picking the Right Type of Iframe

We currently offer three types of iframe experiences:

**Full Iframe**:
Use this when you need the complete experience—recording the session, getting a detailed analysis, and so on.

**Basic Iframe**:
In most situations, the Basic option is your go-to. It gives an interactive experience with an avatar that simulates an AI agent.

**Minimal Iframe**:
The Minimal option is best for glimpses or previews. For example, you can place it on a landing page or in newsletters to provide a quick look at what your feature does. It's ideal for lightweight marketing content or basic introductions to the platform.

By default, we don't transcribe the session for basic and minimal iframe (and hence evaluation isn't available). In order to transcribe, you should enable the transcription option.

### 2. Customizing Your Scenario

While you can use the API to set up scenarios, we recommend customizing their appearance and behavior in our Advanced Scenario Creator UI. It offers rich controls and options, such as:

**Avatar Look & Voice**:
Pick from different avatars and voices to match your brand or style.

**Conversation Strategy**:
- **Talkative Mode**: The AI agent leads the conversation and continues talking even if the human remains silent.
- **Quiz Mode**: After the session, it jumps directly to an analysis (like a quiz), and no avatar is displayed.
- **Conductor Strategy**: Precisely control the AI's actions, including when it speaks or ends the call.

A good pattern is to create a few well-defined scenarios in the Scenario Editor and then embed those scenarios in multiple places using our APIs. This way, you build a great experience once and reuse it as often as you like.

### 3. Delivering an End-to-End Experience

A typical workflow on our platform involves these steps:

**Create a Scenario**:
After you design it in the Scenario Editor, you embed it in your application via an iframe.

**Fetch Session Details**:
Session is a running instance of a scenario which identifies the user's interaction with that scenario. Fetching session details API requires a Sessions ID. You can get session ID either from creating a unique iframe link for each user or catching from an iframe lifecycle event.

**Post Session Analysis**:
Use our "scenario analyze" API to process the transcript recorded during the session, giving you a complete analysis of the interaction.

Note: We do not by default trigger session analysis for sessions created using iFrame. So you do need to hit this API in order for us to give the analysis report.

Using Full Iframe: When you enable the Boolean option **Disable Participant Access to Analysis**, it tells us to store and analyze the transcript without showing the analysis directly to the end user. If this is disabled in your iframe settings, we won't record the transcript in case of full iframe. Why is it this way? To avoid sending your users to our analysis page, which can be disruptive to your application experience. We also expect most developers will build an evaluation page on their website. We plan to make this more intuitive in the future.

To map a session to a particular user, simply pass the user's name and email as query parameters in the iframe. Then, when calling the list sessions API, you can filter by the email to fetch the relevant session data.

### 4. User Management

If you use our full iframe and map sessions to specific users, you can:

- Display each user's experience and transcript in your own UI.
- Show them how they performed and what they can improve, using our analysis or your own custom logic built on our data.
- Offer a richer, personalized interaction for each user, leveraging both the transcript and our analysis results.

### 5. Purchase and Monetization

We also provide an option to attach a dollar value to a scenario. This means you can monetize your AI-driven content. You can use our LIST purchase API to get details of purchase. This way, you can manage payments and track user entitlements with ease.

## Creating Effective Scenarios

### Good Prompt Writing Tips
- Name scenarios as [Coach Name]:[Situation] (e.g., "PM Interviewer: Analytics Question", "Dating Coach: First Date")
- Use "You are [Role]" to set the AI agent role with tone specifications (positive, abrasive, humorous, skeptical)
- Provide clear agenda with list of questions and follow-up instructions
- Include context through PDF documents, blog post links, or YouTube video links for examples
- For interviews, provide specific scoring criteria; otherwise AI evaluates on general professionalism and communication skills

### Time Management
- AI naturally disconnects when agenda items are covered
- Use Conductor Mode for fixed time limits
- Add warning messages (e.g., at 9 minutes: "You have one minute left")
- Add final disconnect message (e.g., at 10 minutes: "Now immediately disconnect and say thank you")

## AI Counselling

For MBA candidates or career pivots, we offer 10-minute interactive AI counselling sessions focusing on specific aspects of career counselling. Each session is a guided conversation with AI to understand your career path, helping you brainstorm, reflect, and ideate while collecting rich information.

At the end of sessions, you can run analysis and get AI summaries on various helpful parameters. This serves as valuable prep work before meeting coaches, peers, or mentors.

## Technical Architecture

### Monorepo Structure
- **Backend**: FastAPI Python application in `py/` directory
- **Frontend**: Next.js TypeScript application in `www/` directory
- **Shared**: Docker configurations, documentation, and setup scripts

### Backend Architecture (FastAPI + MongoDB)
- FastAPI web framework with REST and WebSocket endpoints
- MongoDB with Beanie ODM for data persistence
- Redis for caching and session management
- Modular structure: routers, services, models, schemas

**Key backend directories:**
- `py/backend/models/` - Database models using Beanie ODM
- `py/backend/routers/` - API endpoints grouped by feature
- `py/backend/services/` - Business logic layer
- `py/backend/schemas/` - Pydantic request/response schemas
- `py/backend/db/operations/` - Database operations
- `py/backend/middleware/` - Authentication and OTEL middleware

### Frontend Architecture (Next.js + TypeScript)
- Next.js 15 with App Router
- TypeScript for type safety
- Tailwind CSS for styling
- Zustand for state management
- TanStack Query for API state management
- Radix UI components

**Key frontend directories:**
- `www/app/` - Next.js app router pages
- `www/components/` - Reusable UI components
- `www/http-hooks/` - API hooks for data fetching
- `www/store/` - Zustand state management
- `www/lib/` - Utility functions and configurations

### Core Data Models

#### Scenario
The core entity representing an AI conversation experience:
- **Source**: `py/backend/models/scenario.py` (MongoDB model)
- **Frontend**: `www/app/types/core-types.ts` (TypeScript interface)
- **Compiled**: Simplified runtime representation for AI conversations

#### Session
Represents an active conversation session:
- Tracks user interactions with scenarios
- Stores conversation history and state
- Supports multiple conversation engines (standard, quiz, code)

#### Collection
Groups related scenarios together:
- Can contain scenarios and static content
- Supports sequential playback
- Used for courses and learning paths

### Key Features

#### Scenario Execution Surfaces
1. **AppHero** - Homepage scenario cards
2. **Run Page** (`/run/[slug]`) - Full scenario execution
3. **Collection Play** - Sequential scenario playbook
4. **Embedded Views** - Multiple embed formats (full, basic, minimal)

#### Conversation Engines
- **Conversation Engine** - Standard AI interactions
- **Quiz Engine** - Assessment scenarios with scoring
- **Code Engine** - Programming exercises with execution

#### Authentication & Authorization
- Google OAuth integration
- Cookie-based session management
- Role-based access control for scenarios

## Session Management

### Session Duration & Limits
- **Guaranteed Time**: 12 minutes of uninterrupted session time
- **Token Limits**: High token consumption scenarios (video input, PDF sharing, continuous whiteboard usage) may reach limits sooner
- **Automatic Retries**: Connection issues trigger automatic retries with backup models
- **Smart Recovery**: Agent acknowledges interruptions and continues seamlessly

### Session Restoration
Sessions can be restored from disconnections:
- Restore disconnected sessions from session analysis page
- Continue sessions that exceeded the token limit
- Resume sessions that were disconnected due to internet issues
- Effectively have longer conversations by breaking them into segments

### Data Management
- Delete session data permanently using delete button on session analysis page
- All session data (recordings, metadata, analysis) can be permanently removed
- Users have complete control over their privacy

## Language Support

### User Language Settings
1. Enable "AI language assistance" in settings
2. Select preferred language
3. AI responds in chosen language across all conversations

### For Scenario Creators
1. **Voice Accent**: Set language code (e.g., "fr-FR") in Appearance section
2. **Response Language**: Include explicit language instructions in prompt

### Tips
- Set both language code AND language instructions for complete experience
- Create interesting combinations (e.g., French accent with English content)
- User preferences override scenario settings

## Troubleshooting

### Audio Issues
- **Chrome**: Click lock/camera icon in address bar or use chrome://settings/content/microphone
- **Safari**: Safari menu → Preferences → Websites → Microphone → Allow
- **Firefox**: Click permissions icon in address bar → Allow microphone

### Session Issues
- Sessions can be restored from the session analysis page
- Delete session data permanently using delete button on session analysis page
- All session data (recordings, metadata, analysis) can be permanently removed

## Development Guidelines

### Code Organization
- Use absolute imports from root directories
- Follow established patterns for new features
- Keep functions under 50 lines when possible
- Use descriptive naming conventions

### Python Backend
- All imports absolute from `py/` directory
- Use type hints for all function parameters
- Let exceptions bubble up to FastAPI handlers
- Use `DT.now()` for UTC datetime operations
- Database operations through `MongoStore` wrapper classes

### TypeScript Frontend
- Use absolute imports with `@/` prefix
- Explicit type annotations for function parameters
- Prefer interfaces for object types
- Use `cn()` utility for dynamic class names
- Follow component architecture: Components → Hooks → Stores

### Database Patterns
- Models inherit from `MongoModel` base class
- Use `MongoStore[ModelType]` for all database operations
- Define indexes in model `Settings` class
- All models registered in `backend/models/index.py`

### API Integration
- Backend serves API at `:8003/api/`
- Frontend consumes via axios clients in `lib/api-client.ts`
- Use TanStack Query for API state management
- Separate authenticated and unauthenticated clients

## Environment Setup

### Required Environment Variables

**Backend** (`.env` in `py/` directory):
- `MONGODB_CONNECTION_STRING`
- `REDIS_URL`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`

**Frontend** (`.env.local` in `www/` directory):
- `NEXT_PUBLIC_BACKEND_URL`
- `NEXT_PUBLIC_GOOGLE_CLIENT_ID`

### Development Workflow
1. Start backend server on port 8003: `uvicorn backend.main:app --reload --port 8003`
2. Start frontend server on port 3000: `pnpm dev`
3. Both services communicate via HTTP/WebSocket
4. Create PRs targeting `main` branch for staging deployment

## Testing Strategy
- **Backend**: pytest for unit and integration tests
- **Frontend**: Component testing with established patterns
- **API testing**: Via Bruno collections in `py/bruno/`
- **Admin tools**: Available at `py/admin/` for debugging

## Key Integrations
- **Google OAuth** - User authentication
- **Stripe** - Payment processing
- **E2B** - Code execution sandbox
- **OpenAI/Anthropic** - AI model providers
- **AWS S3** - File storage
- **MongoDB** - Primary database
- **Redis** - Caching and sessions

## Business Integration

### Subscription Reimbursement
Available for Google employees as part of job-related learning benefits. Working to expand to more companies. Download official reimbursement letter from Resources page for HR/finance submission.

### Transfer Minutes - Bulk Purchase & Team Distribution
Seamless solution for coaches, managers, and team leaders to enable AI practice sessions across organizations:

**Features**:
- Buy minutes in bulk (e.g., 2000 minutes)
- Transfer specific amounts to team members via email (e.g., 100 minutes each)
- Team members sign in and start practicing without payment setup
- Full control over minute allocation and usage

**Note**: Currently invite-only - email help@getarchieai.com for access.

### Custom Integration
For business deals, custom pricing, and enterprise features, contact help@getarchieai.com

## Limitations

- **Conversation Duration**: Limited to 10-12 minutes per session
- **Browser Compatibility**: Chrome recommended for best experience (Safari has recording issues)
- **Google Meet Agent**: Background noise sensitivity, works best with one speaker at a time
- **Platform Support**: Currently Google Meet only (more platforms coming)


## Release Notes & Latest Features

### Recent Major Features (2025)

#### September 2025 - Nano Banana Model: AI Image Editing & Faster Generation 🍌
Our image generation tool now uses Google's cutting-edge Gemini Nano Banana model with powerful image editing capabilities:
- **Image Editing**: Re-imagine scenario avatars in different scenarios while maintaining character consistency
- **Faster Generation**: Original image creation is now much quicker
- Ask the AI to edit existing images: *"Show me in a boardroom setting"* or *"Place me in a casual coffee shop environment"*

#### August 2025 - Google Meet Agent: AI Joins Your Meetings 🚀
AI agents can now join Google Meet calls autonomously! Perfect for teams needing help with screening calls, customer data collection, or training sessions.
- **Custom Meeting Mode**: Provide meeting URL and schedule when the bot joins
- **Calendar Integration**: Connect your calendar and filter by keywords (e.g., "interview 101")
- Bot automatically generates transcripts and analysis
- FREE through August 2025, then available on Premium ($20+) plans

#### August 2025 - AI Image Generation: Visualize Your Practice Scenarios
AI agents can now generate images during conversations, creating immersive visual context:
- **Use Cases**: See conference rooms before presentations, visualize interview settings, understand cultural contexts
- **For Users**: Simply ask the AI to show you what something looks like
- **For Creators**: Add image generation instructions directly in scenario AI Instructions

#### August 2025 - Playback Speed Control: Listen at Your Pace ⚡
Adjust AI speech speed from 0.5x to 2x for comfortable listening. This experimental feature addresses the common need to consume content at faster speeds, similar to YouTube and podcasts.

#### August 2025 - Tracks & Labels: Navigate Your Learning Journey 🎉
Finding the right practice scenario just got easier with career-focused learning paths:
- **Tracks**: Career-focused paths (PM, Engineering, Leadership, Sales) with progress tracking coming soon
- **Labels**: Instant filters for specific skills like Product Analytics or Array Problems

#### August 2025 - Daily Streaks: Track Your Practice Consistency 🔥
Track consecutive days of practice with streak counter in the Profile menu. Miss a day and your streak resets to zero, encouraging consistent skill development.

#### July 2025 - Google Slides Integration: Interactive Presentations 🎯
AI agents can now display and navigate Google Slides based on conversation flow:
- Setup: Get embed URL from Google Slides → Enable tool in scenario → Add slide instructions to AI prompt
- Perfect for: System design walkthroughs, product demos, onboarding sessions, technical interviews

#### July 2025 - Standard Plan & Annual Subscriptions: More Accessible Pricing 💳
- **Standard Plan**: 100 minutes/month for $12 (making AI practice more accessible)
- **Annual Subscriptions**: Standard Annual at $120/year (save $24), Premium Annual at $200/year (save $40)

#### July 2025 - Refer & Earn Program: Get 25 Free Minutes 🎁
Share Tough Tongue AI with friends and you'll both get 25 free minutes when they sign up.

#### July 2025 - Enhanced Features & Customizations
- **Skip Agent Greeting**: Add `?skipAutoStart=true` to make user speak first
- **Artifacts Model**: Specialized Galaxy Medium model for structured content generation
- **Noise Cancellation Models**: Filter background voices and ambient noise
- **Custom Avatar Upload**: Upload avatar images directly from your device

#### July 2025 - Courses Page: Structured Learning Experiences 📚
Moved Collections to dedicated Course page to better represent structured learning experiences:
- Clear distinction between Scenario Library (quick practice) and Courses (comprehensive journeys)
- Curated learning paths in Product Management, Software Development, Leadership, Sales Coaching

### Advanced Features Deep Dive

#### Interactive Tools & Capabilities
- **Multi-Language Coding**: Python, Java, and C++ support for coding interview scenarios
- **Whiteboard & Diagrams**: Interactive whiteboard for system design and architectural diagrams
- **Visual Cards**: AI creates visual cards and diagrams to explain complex concepts in real-time
- **Code Editor Integration**: Agent accesses code editor, publishes questions, provides real-time feedback

#### Dynamic Content & Personalization
- **Dynamic Variables**: Add {{name}}, {{resume}}, or any variable to AI Instructions for personalized experiences
- **Memory Management**: View, edit, and manage what AI agents remember about you
- **Tool Configuration**: Control AI agent capabilities (cards, diagrams, PDFs, code editor)
- **Email Analysis Reports**: Receive automated analysis reports for scenario sessions

#### Organization & Navigation
- **Creator Analytics**: Dashboard displaying all scenarios with session counts and performance metrics
- **Brand Pages**: Create fully customized landing pages with your own branding and subdomain URLs
- **Session Analysis Configuration**: Auto-analysis, admin email reports, auto-submit options

#### AI & Voice Enhancements
- **Multiple AI Models**: Choose between Galaxy mini, Galaxy mini-stable, Galaxy medium with different capabilities
- **Voice Customization**: Multiple voice options (Aoede, Charon, Fenrir, Kore, Puck)
- **Language Support**: Multiple languages with accent and response customization
- **Improved Conversation Quality**: Better at conducting longer sessions with appropriate pause handling

#### Embedding & Integration Features
- **Three Iframe Types**: Full (complete experience), Basic (standard), Minimal (compact preview)
- **Scenario Access Tokens**: Secure private scenario embedding with short-lived tokens (1 hour validity)
- **Enhanced Events**: onStart, onStop, onSubmit, onClick events for iframe lifecycle tracking
- **Customization Options**: Transparent background, countdown control, background color, title customization
- **Auto-Expanding Iframes**: Create dynamic experiences with audio visualization on first click

#### Business & Team Features
- **Transfer Minutes**: Bulk purchase and team distribution system for organizations (invite-only)
- **Monetization Support**: Attach dollar values to scenarios, track purchases via API
- **Private Scenario Access**: Secure token-based access for proprietary training content
- **Analytics & Reporting**: Comprehensive usage tracking and performance metrics

#### Session & Analysis Features
- **Session Restoration**: Continue disconnected sessions from where they left off
- **Transcript Access**: Download conversation transcripts and evaluation results
- **Detailed Analysis**: Overall scores, strengths/weaknesses, report cards, improvement suggestions
- **Enhanced User Instructions**: Sleek overlay design for better objective understanding

### Conversation Strategies & Modes
- **Talkative Mode**: AI leads conversation, continues even if human stays silent
- **Quiz Mode**: Immediately jumps to analysis after session completion
- **Conductor Mode**: Precisely control AI actions at specific timestamps during conversation

### Historical Development Timeline

**2025 Major Milestones:**
- **Q3**: Nano Banana model, Google Meet Agent, AI Image Generation, Playback Speed Control
- **Q2**: Dynamic Variables, Memory Management, Brand Pages, Transfer Minutes, Course Structure
- **Q1**: AI Model Selection, Iframe Events, Public API Enhancements, Tool Configuration

**2024 Foundation:**
- **December 2024**: Custom Scenario Creation, Library Feature with featured scenarios (Kellogg Business School, Google PM Interview, System Design)
- **December 2024**: Initial platform release - first version of Tough Tongue AI for high-stakes conversation training

### Upcoming Features & Roadmap
- **Platform Expansion**: Zoom and Microsoft Teams support for Google Meet Agent
- **Enhanced Analytics**: Progress tracking and personalized learning recommendations
- **Advanced Memory**: More sophisticated AI memory and context management
- **Multi-Modal Enhancements**: Expanded visual artifact capabilities and interaction modes

### AI Counselling & Career Development
Interactive AI counselling sessions for MBA candidates and career pivots:
- 10-minute guided conversations focusing on specific career counselling aspects
- Helps brainstorm, reflect, and ideate with AI interviewer
- Collects rich information for analysis and summary generation
- Valuable prep work before meeting coaches, peers, or mentors

## Support & Resources

### Contact Information
- **Technical Support**: help@getarchieai.com
- **Demos and Consultations**: https://cal.com/ajitesh/demo-tough-tongue-ai
- **GitHub Issues**: For reporting bugs and feature requests
- **Coach Community**: https://discord.gg/NfTPT3HsSj

### Sample Repositories
- **Simple Course**: Uses iframe, iframe lifecycle events, and analysis: [repo](https://github.com/tough-tongue/ttai-simple-course/tree/main), [deployment](https://tough-tongue-starter-course-yn2p.vercel.app/)
- **AI Course Creation**: Uses OpenAI to create scenarios on Tough Tongue AI: [repo](https://github.com/ajitesh123/tough-tongue-starter), [deployment](https://tough-tongue-starter.vercel.app/)

### Additional Resources
- **API Documentation Video**: [Loom walkthrough](https://www.loom.com/share/d9ae326da7b54f2f8d84120bd3399d0d?sid=43a47788-d99d-49fb-9cc5-f48993770863)
- **Coaching Platform Demo**: [Loom demo](https://www.loom.com/share/04a13f04a22b4547bf0dd9bd99a9db62?sid=b7e79b90-6ee8-462b-baaa-fef18bb8ab99)
- **15-minute Consultation**: [Book here](https://cal.com/ajitesh/15min)

---

This comprehensive documentation covers all aspects of the Tough Tongue AI platform, from basic usage to advanced API integration and technical implementation details.