### Initialize and Start Servers

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Use these commands to initialize the project, set up environment variables, and start both the backend and frontend servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

--------------------------------

### Start Servers Separately

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Instructions for starting the backend and frontend servers in separate terminals. Ensure Python virtual environment is activated for the backend.

```bash
# Terminal 1 — Backend
./venv/bin/python app.py

# Terminal 2 — Frontend
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

--------------------------------

### Install Backend and Frontend Dependencies

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Commands to install backend Python dependencies using a virtual environment and frontend Node.js dependencies using pnpm.

```bash
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
frontend: cd frontend && corepack pnpm install
```

--------------------------------

### Initialize and Start FastAPI Flux

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/README.md

Use these commands to set up the environment, configure the API key, and launch the local development server.

```bash
make init
cp sample.env .env  # Add your DEEPGRAM_API_KEY
make start
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Examples of conventional commit messages used in this project.

```git
feat(fastapi-flux): add diarization support
```

```git
fix(fastapi-flux): resolve WebSocket close handling
```

```git
refactor(fastapi-flux): simplify session endpoint
```

```git
chore(deps): update frontend submodule
```

--------------------------------

### Makefile Commands for Project Management

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

The Makefile provides standardized commands for development workflow including initialization, starting servers, testing, and cleanup.

```bash
# Initialize project (install dependencies, setup submodules)
make init

# Start both backend and frontend servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080

# Start servers individually
make start-backend   # Backend only on port 8081
make start-frontend  # Frontend only on port 8080

# Run conformance tests (requires running app)
make test

# Update git submodules to latest versions
make update

# Clean build artifacts and dependencies
make clean

# Check project status
make status

# Eject frontend from submodule to regular directory
make eject-frontend

```

--------------------------------

### Add Keyterms for Recognition

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Example of how to add custom vocabulary hints (keyterms) as repeated query parameters in the WebSocket URL to improve recognition accuracy.

```bash
?keyterm=Deepgram&keyterm=Nova&keyterm=Aura
```

--------------------------------

### Get Application Metadata

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Retrieves application configuration and metadata defined in deepgram.toml.

```bash
# Request metadata
curl -s http://localhost:8081/api/metadata | python3 -m json.tool

# Response:
{
    "title": "FastAPI Flux",
    "description": "Get started using Deepgram's Flux real-time transcription with this FastAPI demo app",
    "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
    "repository": "https://github.com/deepgram-starters/fastapi-flux",
    "useCase": "flux",
    "language": "python",
    "framework": "fastapi",
    "tags": ["flux", "streaming", "speech-to-text", "real-time", "turn-detection", "fastapi", "python"]
}
```

--------------------------------

### Manual Endpoint Checks

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Examples of using curl to manually check API endpoints for metadata and session.

```bash
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
```

```bash
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

--------------------------------

### Establish Flux WebSocket Connection

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Example of establishing a WebSocket connection to the Deepgram Flux API using the constructed URL and an access token. The token should be passed as a subprotocol.

```javascript
// Example usage
const ws = new WebSocket(
    buildFluxUrl(dictationParams, dictationParams.keyterm),
    [`access_token.${token}`]
);
```

--------------------------------

### Get Application Metadata

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Returns application metadata including the use case, framework, and language information defined in `deepgram.toml`. Useful for identifying the starter app type and capabilities.

```APIDOC
## GET /api/metadata - Get Application Metadata

### Description
Returns application metadata including the use case, framework, and language information defined in `deepgram.toml`. Useful for identifying the starter app type and capabilities.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - The title of the application.
- **description** (string) - A brief description of the application.
- **author** (string) - The author of the application.
- **repository** (string) - The URL of the application's repository.
- **useCase** (string) - The use case of the application.
- **language** (string) - The programming language used.
- **framework** (string) - The framework used.
- **tags** (array of strings) - Tags associated with the application.

### Request Example
```bash
curl -s http://localhost:8081/api/metadata | python3 -m json.tool
```

### Response Example
```json
{
    "title": "FastAPI Flux",
    "description": "Get started using Deepgram's Flux real-time transcription with this FastAPI demo app",
    "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
    "repository": "https://github.com/deepgram-starters/fastapi-flux",
    "useCase": "flux",
    "language": "python",
    "framework": "fastapi",
    "tags": ["flux", "streaming", "speech-to-text", "real-time", "turn-detection", "fastapi", "python"]
}
```
```

--------------------------------

### Python WebSocket Client for Deepgram Flux

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Connect to the Flux WebSocket endpoint from Python using the websockets library. This example shows how to obtain a session token, construct the WebSocket URI with parameters, and handle incoming messages.

```python
import asyncio
import json
import httpx
import websockets

async def flux_client():
    # Get session token
    async with httpx.AsyncClient() as client:
        response = await client.get('http://localhost:8081/api/session')
        token = response.json()['token']

    # Build URL with parameters
    params = '&'.join([
        'encoding=linear16',
        'sample_rate=16000',
        'eot_threshold=0.7',
        'eot_timeout_ms=5000',
        'keyterm=Deepgram',
        'keyterm=Flux'
    ])

    uri = f'ws://localhost:8081/api/flux?{params}'
    subprotocol = f'access_token.{token}'

    async with websockets.connect(uri, subprotocols=[subprotocol]) as ws:
        print('Connected to Flux')

        # Handle incoming messages
        async def receive_messages():
            async for message in ws:
                data = json.loads(message)
                event_type = data.get('type')

                if event_type == 'StartOfTurn':
                    print('[START] User began speaking')
                elif event_type == 'Update':
                    transcript = data['channel']['alternatives'][0]['transcript']
                    print(f'[UPDATE] {transcript}')
                elif event_type == 'EagerEndOfTurn':
                    transcript = data['channel']['alternatives'][0]['transcript']
                    print(f'[EAGER] {transcript}')
                elif event_type == 'EndOfTurn':
                    transcript = data['channel']['alternatives'][0]['transcript']
                    print(f'[FINAL] {transcript}')
                elif event_type == 'Error':
                    print(f'[ERROR] {data["description"]}')

        # Stream audio file (16kHz, 16-bit PCM)
        async def send_audio(audio_file):
            with open(audio_file, 'rb') as f:
                while chunk := f.read(4096):
                    await ws.send(chunk)
                    await asyncio.sleep(0.1)  # Simulate real-time

            # Signal end of audio
            await ws.send(json.dumps({'type': 'CloseStream'}))

        # Run concurrently
        await asyncio.gather(
            receive_messages(),
            send_audio('audio.raw')
        )

asyncio.run(flux_client())

```

--------------------------------

### Docker Deployment Commands

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Build and run the application using Docker. This includes building the image, running the container with environment variables, and checking logs.

```docker
# Build and run with Docker
docker build -t fastapi-flux -f deploy/Dockerfile .

docker run -d \
    --name fastapi-flux \
    -p 8080:8080 \
    -e DEEPGRAM_API_KEY=your_api_key \
    -e SESSION_SECRET=$(openssl rand -hex 32) \
    fastapi-flux

# Check logs
docker logs -f fastapi-flux

# Access the application
curl http://localhost:8080/health

```

```yaml
# fly.toml for Fly.io deployment
app = "fastapi-flux"
primary_region = "iad"

[build]
  dockerfile = "deploy/Dockerfile"

[env]
  PORT = "8081"
  HOST = "0.0.0.0"

[http_service]
  internal_port = 8080
  force_https = true

[[http_service.checks]]
  path = "/health"
  interval = "30s"
  timeout = "5s"

```

--------------------------------

### Environment Configuration (.env file)

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Configure the application using environment variables in a .env file. The DEEPGRAM_API_KEY is required; other settings have sensible defaults.

```bash
# .env file configuration

# Required: Your Deepgram API key
DEEPGRAM_API_KEY=your_api_key_here

# Optional: Backend server port (default: 8081)
PORT=8081

# Optional: Server bind address (default: 0.0.0.0)
HOST=0.0.0.0

# Optional: JWT signing secret (auto-generated if not set)
# Set this in production for consistent sessions across restarts
SESSION_SECRET=your_secure_random_secret_here

```

```bash
# Quick setup commands
cp sample.env .env

# Generate a secure session secret
echo "SESSION_SECRET=$(openssl rand -hex 32)" >> .env

# Verify configuration
cat .env

```

--------------------------------

### Run Conformance Tests

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Command to run conformance tests. Requires the application to be running.

```bash
make test
```

--------------------------------

### Clean Rebuild Project

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Command to perform a clean rebuild by removing virtual environment, node modules, and Vite cache, then re-initializing.

```bash
rm -rf venv frontend/node_modules frontend/.vite
make init
```

--------------------------------

### Commit Frontend Changes

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Steps to commit changes in the frontend submodule and update the main project.

```bash
cd frontend && git add . && git commit -m "feat: description"
```

```bash
cd frontend && git push origin main
```

```bash
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

--------------------------------

### Configure Flux EOT Parameters

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Use these JavaScript objects to define parameters for end-of-turn (EOT) detection. Adjust 'eot_threshold' and 'eot_timeout_ms' to control responsiveness. 'eager_eot_threshold' enables tentative completions. Custom keywords can be provided via the 'keyterm' array.

```javascript
// Parameter tuning examples for different use cases

// Fast-paced conversation (quick turn endings)
const quickParams = {
    eot_threshold: '0.3',
    eot_timeout_ms: '2000',
    eager_eot_threshold: '0.2'
};

// Thoughtful discussion (longer pauses allowed)
const thoughtfulParams = {
    eot_threshold: '0.9',
    eot_timeout_ms: '8000',
};

// Dictation with custom vocabulary
const dictationParams = {
    eot_threshold: '0.7',
    eot_timeout_ms: '5000',
    keyterm: ['Deepgram', 'Nova', 'Aura', 'Flux']
};
```

--------------------------------

### Connect to Flux WebSocket and Stream Audio

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Establishes a WebSocket connection with JWT authentication and streams audio from the user's microphone.

```javascript
// JavaScript WebSocket client example
async function connectFlux() {
    // Get session token
    const response = await fetch('/api/session');
    const { token } = await response.json();

    // Build WebSocket URL with Flux parameters
    const params = new URLSearchParams({
        encoding: 'linear16',
        sample_rate: '16000',
        eot_threshold: '0.7',           // End-of-turn confidence (0.0-1.0)
        eager_eot_threshold: '0.5',     // Tentative EOT threshold
        eot_timeout_ms: '5000'          // Silence timeout in ms
    });
    // Add multiple keyterms for vocabulary hints
    params.append('keyterm', 'Deepgram');
    params.append('keyterm', 'Flux');

    // Connect with JWT subprotocol authentication
    const ws = new WebSocket(
        `ws://localhost:8081/api/flux?${params}`,
        [`access_token.${token}`]
    );

    ws.onopen = () => console.log('Connected to Flux');

    ws.onmessage = (event) => {
        const data = JSON.parse(event.data);

        switch (data.type) {
            case 'StartOfTurn':
                console.log('User started speaking');
                break;
            case 'Update':
                console.log('Interim:', data.channel.alternatives[0].transcript);
                break;
            case 'EagerEndOfTurn':
                console.log('Tentative end (may resume):', data.channel.alternatives[0].transcript);
                break;
            case 'TurnResumed':
                console.log('User continued speaking');
                break;
            case 'EndOfTurn':
                console.log('Final:', data.channel.alternatives[0].transcript);
                break;
            case 'Error':
                console.error('Error:', data.description);
                break;
        }
    };

    ws.onerror = (error) => console.error('WebSocket error:', error);
    ws.onclose = (event) => console.log(`Disconnected: ${event.code} ${event.reason}`);

    return ws;
}

// Stream audio from microphone
async function streamAudio(ws) {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
    const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });

    mediaRecorder.ondataavailable = (event) => {
        if (event.data.size > 0 && ws.readyState === WebSocket.OPEN) {
            ws.send(event.data);
        }
    };

    mediaRecorder.start(250); // Send chunks every 250ms
    return mediaRecorder;
}
```

--------------------------------

### Health Check Endpoint

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Checks the server health status, useful for liveness probes and readiness scripts.

```bash
# Check server health
curl -s http://localhost:8081/health | python3 -m json.tool

# Response:
{
    "status": "ok"
}

# Use in scripts for readiness checks
until curl -sf http://localhost:8081/health > /dev/null; do
    echo "Waiting for server..."
    sleep 1
done
echo "Server is ready!"
```

--------------------------------

### Build Flux WebSocket URL

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

This JavaScript function constructs a WebSocket URL for the Flux API, appending provided parameters and keyterms as query parameters. Ensure the base URL and port are correct for your deployment.

```javascript
// Build URL with parameters
function buildFluxUrl(params, keyterms = []) {
    const url = new URLSearchParams(params);
    keyterms.forEach(term => url.append('keyterm', term));
    return `ws://localhost:8081/api/flux?${url}`;
}
```

--------------------------------

### Issue JWT Session Token

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Requests a JWT session token for WebSocket authentication and demonstrates how to store it for subsequent connections.

```bash
# Request a session token
curl -s http://localhost:8081/api/session | python3 -m json.tool

# Response:
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4MjM0NTYsImV4cCI6MTcwOTgyNzA1Nn0.abc123..."
}

# Store token for subsequent WebSocket connections
TOKEN=$(curl -s http://localhost:8081/api/session | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
echo "Session token: $TOKEN"
```

--------------------------------

### Health Check Endpoint

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Returns the health status of the backend server. Used by deployment platforms like Fly.io for liveness probes and load balancer health checks.

```APIDOC
## GET /health - Health Check Endpoint

### Description
Returns the health status of the backend server. Used by deployment platforms like Fly.io for liveness probes and load balancer health checks.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server (e.g., "ok").

### Request Example
```bash
curl -s http://localhost:8081/health | python3 -m json.tool
```

### Response Example
```json
{
    "status": "ok"
}
```
```

--------------------------------

### Stop All Processes

Source: https://github.com/deepgram-starters/fastapi-flux/blob/main/AGENTS.md

Command to stop all running processes on ports 8080 and 8081.

```bash
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
```

--------------------------------

### Real-Time Transcription WebSocket

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Connects to the Deepgram Flux API WebSocket for real-time audio transcription. Requires JWT authentication and supports various configuration options for transcription behavior.

```APIDOC
## WS /api/flux - Real-Time Transcription WebSocket

WebSocket endpoint for real-time audio transcription using Deepgram's Flux API. Requires JWT authentication via the `access_token.<jwt>` subprotocol. Supports configurable EOT detection, eager EOT for tentative completions, and custom keyterms.

### Method
WS

### Endpoint
`/api/flux`

### Query Parameters
- **encoding** (string) - Required - The audio encoding format (e.g., `linear16`).
- **sample_rate** (integer) - Required - The audio sample rate in Hz (e.g., `16000`).
- **eot_threshold** (float) - Optional - End-of-turn confidence threshold (0.0-1.0).
- **eager_eot_threshold** (float) - Optional - Tentative end-of-turn threshold.
- **eot_timeout_ms** (integer) - Optional - Silence timeout in milliseconds.
- **keyterm** (string) - Optional - Custom keyterm for vocabulary hints. Can be specified multiple times.

### Authentication
Requires JWT authentication via the `access_token.<jwt>` subprotocol.

### Request Example (JavaScript WebSocket Client)
```javascript
async function connectFlux() {
    const response = await fetch('/api/session');
    const { token } = await response.json();

    const params = new URLSearchParams({
        encoding: 'linear16',
        sample_rate: '16000',
        eot_threshold: '0.7',
        eager_eot_threshold: '0.5',
        eot_timeout_ms: '5000'
    });
    params.append('keyterm', 'Deepgram');
    params.append('keyterm', 'Flux');

    const ws = new WebSocket(
        `ws://localhost:8081/api/flux?${params}`,
        [`access_token.${token}`]
    );

    ws.onopen = () => console.log('Connected to Flux');

    ws.onmessage = (event) => {
        const data = JSON.parse(event.data);
        switch (data.type) {
            case 'StartOfTurn':
                console.log('User started speaking');
                break;
            case 'Update':
                console.log('Interim:', data.channel.alternatives[0].transcript);
                break;
            case 'EagerEndOfTurn':
                console.log('Tentative end (may resume):', data.channel.alternatives[0].transcript);
                break;
            case 'TurnResumed':
                console.log('User continued speaking');
                break;
            case 'EndOfTurn':
                console.log('Final:', data.channel.alternatives[0].transcript);
                break;
            case 'Error':
                console.error('Error:', data.description);
                break;
        }
    };

    ws.onerror = (error) => console.error('WebSocket error:', error);
    ws.onclose = (event) => console.log(`Disconnected: ${event.code} ${event.reason}`);

    return ws;
}

async function streamAudio(ws) {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
    const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });

    mediaRecorder.ondataavailable = (event) => {
        if (event.data.size > 0 && ws.readyState === WebSocket.OPEN) {
            ws.send(event.data);
        }
    };

    mediaRecorder.start(250);
    return mediaRecorder;
}
```

### Response Message Types
- **StartOfTurn**: Indicates the user has started speaking.
- **Update**: Provides interim transcription results.
- **EagerEndOfTurn**: Indicates a tentative end of speech, which may be resumed.
- **TurnResumed**: Indicates the user has continued speaking after a tentative end.
- **EndOfTurn**: Provides the final transcription for a completed turn.
- **Error**: Indicates an error occurred during transcription.
```

--------------------------------

### Issue JWT Session Token

Source: https://context7.com/deepgram-starters/fastapi-flux/llms.txt

Issues a JWT session token for authenticating WebSocket connections. The token is valid for 1 hour and must be passed as a WebSocket subprotocol in the format `access_token.<jwt>`.

```APIDOC
## GET /api/session - Issue JWT Session Token

### Description
Issues a JWT session token for authenticating WebSocket connections. The token is valid for 1 hour and must be passed as a WebSocket subprotocol in the format `access_token.<jwt>`.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - The JWT session token.

### Request Example
```bash
curl -s http://localhost:8081/api/session | python3 -m json.tool
```

### Response Example
```json
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4MjM0NTYsImV4cCI6MTcwOTgyNzA1Nn0.abc123..."
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.