### Project Setup and Installation

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

Initializes the project environment and starts the development servers.

```bash
# Clone the repository with submodules
git clone --recurse-submodules https://github.com/deepgram-starters/fastapi-text-intelligence.git
cd fastapi-text-intelligence

# Initialize project (creates venv, installs dependencies)
make init

# Configure environment
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

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

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

### Initialize and Start Project with Makefile

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

Use the Makefile for a streamlined local development setup. Ensure your DEEPGRAM_API_KEY is added to the .env file.

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

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

### Start FastAPI Backend Separately

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

To start only the backend server, navigate to the project's virtual environment and run the app.py script. Ensure the frontend is started separately if needed.

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

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

### Initialize and Start FastAPI App

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

Use these make commands to initialize dependencies, set up the environment by copying a sample .env file, 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
```

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

### Install Frontend Dependencies

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

Install frontend dependencies using corepack pnpm. Navigate to the frontend directory before running this command.

```bash
cd frontend && corepack pnpm install
```

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

### Clone Repository and Install Dependencies

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

Clone the project with submodules, set up a Python virtual environment, install backend requirements, and install frontend dependencies using pnpm. Remember to add your DEEPGRAM_API_KEY to the .env file.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/fastapi-text-intelligence.git
cd fastapi-text-intelligence
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cd frontend && corepack pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Install Backend Dependencies

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

Install backend dependencies using Python's virtual environment and pip. This command creates a venv and installs packages listed in requirements.txt.

```bash
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
```

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

### Start Frontend Server

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

Start the frontend development server using pnpm. This server will run on port 8080 and is configured not to open automatically.

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

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

### Start Frontend Separately

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

To start only the frontend development server, navigate to the frontend directory and use corepack pnpm to run the dev command, specifying the port and disabling auto-opening.

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

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

### Manage Project Lifecycle with Makefile

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

Use these commands to start the backend and frontend servers, run conformance tests, and clean up build artifacts.

```bash
make start-backend  # Port 8081
make start-frontend # Port 8080

# Run conformance tests (requires running app)
make test

# Clean build artifacts
make clean
```

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format. Ensure all commits adhere to this standard for consistency.

```bash
feat(fastapi-text-intelligence): add diarization support
```

```bash
fix(fastapi-text-intelligence): resolve WebSocket close handling
```

```bash
refactor(fastapi-text-intelligence): simplify session endpoint
```

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

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

### GET /api/metadata

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

Returns metadata about the starter application including use case, framework, language, and SDK version.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the starter application.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application title
- **description** (string) - Application description
- **author** (string) - Author information
- **repository** (string) - GitHub repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Web framework
- **sdk** (string) - SDK version
```

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

### Start Backend Server

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

Run the FastAPI backend server using the Python virtual environment. This server will typically run on port 8081.

```bash
# Terminal 1 - Backend (port 8081)
./venv/bin/python app.py
```

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

### Get Application Metadata

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

Fetches application configuration and metadata from the deepgram.toml file.

```bash
# Get application metadata
curl -X GET http://localhost:8081/api/metadata

# Response:
# {
#   "title": "FastAPI Text Intelligence",
#   "description": "Get started using Deepgram's Text Intelligence with this FastAPI demo app",
#   "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
#   "repository": "https://github.com/deepgram-starters/fastapi-text-intelligence",
#   "useCase": "text-intelligence",
#   "language": "python",
#   "framework": "fastapi",
#   "sdk": "6.0.0-rc.1",
#   "tags": ["text-intelligence", "text-analysis", "nlp", "natural-language-processing", "python", "fastapi"]
# }
```

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

### Handle API Errors

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

Examples of API requests and their corresponding structured error responses for authentication and validation issues.

```bash
# Missing authentication token
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=true" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}'

# Response (401):
# {
#   "detail": {
#     "error": {
#       "type": "AuthenticationError",
#       "code": "MISSING_TOKEN",
#       "message": "Authorization header with Bearer token is required"
#     }
#   }
# }

# Invalid input (neither text nor url provided)
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# Response (400):
# {
#   "error": {
#     "type": "validation_error",
#     "code": "INVALID_TEXT",
#     "message": "Request must contain either 'text' or 'url' field",
#     "details": {}
#   }
# }

# Both text and url provided (invalid)
curl -X POST "http://localhost:8081/api/text-intelligence" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "url": "https://example.com"}'

# Response (400):
# {
#   "error": {
#     "type": "validation_error",
#     "code": "INVALID_TEXT",
#     "message": "Request must contain either 'text' or 'url', not both",
#     "details": {}
#   }
# }
```

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

### GET /health

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

Returns the health status of the service for monitoring purposes.

```APIDOC
## GET /health

### Description
Returns the health status of the service.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Service status
- **service** (string) - Service name
```

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

### GET /api/session

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

Issues a JWT session token required for authenticating subsequent API requests. The token is valid for 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token required for authenticating subsequent API requests.

### Method
GET

### Endpoint
/api/session

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

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

### Get Session Token

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

Retrieves a JWT session token valid for 1 hour. The token must be included in the Authorization header for subsequent requests.

```bash
# Request a new session token
curl -X GET http://localhost:8081/api/session

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

# Store token for subsequent requests
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
echo "Session token: $TOKEN"
```

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

### Deploy with Docker

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

Build and run the application container, or deploy to production environments like Fly.io.

```bash
# Build the Docker image
docker build -f deploy/Dockerfile -t fastapi-text-intelligence .

# Run the container
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_production_secret \
  fastapi-text-intelligence

# Production deployment on Fly.io
fly deploy
```

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

### Commit Frontend Changes in Submodule

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

After making changes to the frontend code within the starter project, navigate to the frontend directory to add, commit, and push those changes to the frontend's git repository.

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

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

### Run Conformance Tests

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

Execute conformance tests for the application. This command requires the application to be running.

```bash
make test
```

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

### Clean Rebuild Project Dependencies

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

Perform a clean rebuild by removing virtual environment, node modules, and Vite cache, then re-initializing dependencies using the make init command.

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

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

### Update Frontend Submodule Reference

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

After pushing frontend changes, return to the main project directory, stage the updated submodule reference, and commit it to the main project's repository.

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

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

### Configure Environment Variables

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

Define required and optional settings in a .env file. The DEEPGRAM_API_KEY is mandatory for API access.

```bash
# Required: Deepgram API key from https://console.deepgram.com
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 for production (auto-generated if not set)
SESSION_SECRET=your_secret_key_for_production
```

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

### Metadata API

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

Retrieves application metadata including use case, framework, and language.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata, including its use case, framework, and programming language.

### Method
GET

### Endpoint
/api/metadata

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **useCase** (string) - The primary use case of the application.
- **framework** (string) - The backend framework used (e.g., FastAPI).
- **language** (string) - The programming language used (e.g., Python).

#### Response Example
{
  "useCase": "Text Intelligence",
  "framework": "FastAPI",
  "language": "Python"
}
```

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

### Integrate Deepgram Python SDK

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

Initialize the Deepgram client and perform text or URL analysis using the Text Intelligence Read API.

```python
from deepgram import DeepgramClient
import os

# Initialize Deepgram client
api_key = os.environ.get("DEEPGRAM_API_KEY")
deepgram = DeepgramClient(api_key=api_key)

# Build request options
options = {
    "language": "en",
    "summarize": True,      # or "v2" for version 2
    "topics": True,
    "sentiment": True,
    "intents": True
}

# Analyze text content
response = deepgram.read.v1.text.analyze(
    request={"text": "Your text content here..."},
    **options
)

# Analyze URL content
response = deepgram.read.v1.text.analyze(
    request={"url": "https://example.com/article"},
    **options
)

# Access results
if hasattr(response, 'results'):
    summary = response.results.summary.text if response.results.summary else None
    topics = response.results.topics.segments if response.results.topics else []
    sentiment = response.results.sentiments.average if response.results.sentiments else None
    intents = response.results.intents.segments if response.results.intents else []
```

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

### Stop FastAPI and Frontend Servers

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

This command uses lsof to find processes listening on ports 8080 and 8081, then kills them to stop both the backend and frontend servers.

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

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

### Manual Endpoint Check - Metadata

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

Manually check the /api/metadata endpoint using curl. The output is formatted using Python's json.tool for readability.

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

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

### Health Check Endpoint

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

Verifies the service status for monitoring and orchestration.

```bash
# Check service health
curl -X GET http://localhost:8081/health

# Response:
# {"status": "ok", "service": "text-intelligence"}
```

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

### User Authentication API

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

Issues JWT session tokens for user authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for user authentication.

### Method
GET

### Endpoint
/api/session

### Parameters
None

### Request Example
None

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

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Manual Endpoint Check - Session

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

Manually check the /api/session endpoint using curl. The output is formatted using Python's json.tool for readability.

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

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

### Analyze Text with Text Intelligence

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

Analyzes raw text or URL content for summaries, topics, sentiment, and intents. Requires a valid Bearer token in the Authorization header.

```bash
# Analyze raw text with all features enabled
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=true&topics=true&sentiment=true&intents=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "I absolutely love this product! It has exceeded all my expectations. The quality is outstanding and the customer service team was incredibly helpful when I had questions. I would highly recommend this to anyone looking for a reliable solution."}'

# Response:
# {
#   "results": {
#     "summary": {
#       "text": "The customer expresses high satisfaction with the product quality and customer service."
#     },
#     "topics": {
#       "segments": [
#         {"topics": [{"topic": "product review", "confidence": 0.95}]}
#       ]
#     },
#     "sentiments": {
#       "average": {"sentiment": "positive", "score": 0.92},
#       "segments": [...]
#     },
#     "intents": {
#       "segments": [
#         {"intents": [{"intent": "recommendation", "confidence": 0.88}]}
#       ]
#     }
#   }
# }

# Analyze content from a URL
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=v2&language=en" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article.html"}'

# Analyze with specific features only (sentiment analysis)
curl -X POST "http://localhost:8081/api/text-intelligence?sentiment=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "The meeting was productive but ran longer than expected."}'
```

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

### POST /api/text-intelligence

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

Analyzes text content provided as raw text or a URL, returning results based on enabled features.

```APIDOC
## POST /api/text-intelligence

### Description
Analyzes text content for summaries, topics, sentiment, and user intents.

### Method
POST

### Endpoint
/api/text-intelligence

### Parameters
#### Query Parameters
- **summarize** (boolean/string) - Optional - Enable summarization feature
- **topics** (boolean) - Optional - Enable topic extraction
- **sentiment** (boolean) - Optional - Enable sentiment analysis
- **intents** (boolean) - Optional - Enable intent detection
- **language** (string) - Optional - Language code

#### Request Body
- **text** (string) - Optional - Raw text to analyze
- **url** (string) - Optional - URL to fetch content from

### Response
#### Success Response (200)
- **results** (object) - Analysis results containing summary, topics, sentiments, and intents
```

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

### Text Intelligence API

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

Analyzes provided text for summaries, topics, sentiment, and intents. Supports text or URL input and customizable analysis features.

```APIDOC
## POST /api/text-intelligence

### Description
Analyzes text for summaries, topics, sentiment, and intents. Can accept text directly or a URL to fetch content from. Analysis features can be toggled via query parameters.

### Method
POST

### Endpoint
/api/text-intelligence

### Query Parameters
- **summarize** (string) - Optional - Set to `true` or `v2` to enable summarization.
- **topics** (string) - Optional - Set to `true` to enable topic detection.
- **sentiment** (string) - Optional - Set to `true` to enable sentiment analysis.
- **intents** (string) - Optional - Set to `true` to enable intent detection.
- **language** (string) - Optional - The language code for analysis (default: `en`).

### Request Body
- **text** (string) - Required if `url` is not provided - The text content to analyze.
- **url** (string) - Required if `text` is not provided - The URL to fetch text content from.

### Request Example
```json
{
  "text": "This is a sample text to analyze."
}
```

### Response
#### Success Response (200)
- **results** (object) - Contains the analysis results.
  - **summary** (object) - Summary results.
    - **text** (string) - The generated summary text.
  - **topics** (object) - Topic detection results.
    - **segments** (array) - Array of segments with detected topics.
      - **topics** (array) - Array of topics within a segment.
        - **topic** (string) - The detected topic.
        - **confidence** (number) - Confidence score for the topic.
  - **sentiments** (object) - Sentiment analysis results.
    - **average** (object) - Overall sentiment.
      - **score** (number) - Average sentiment score.
      - **label** (string) - Sentiment label (e.g., positive, neutral, negative).
    - **segments** (array) - Per-segment sentiment analysis.
  - **intents** (object) - Intent detection results.
    - **segments** (array) - Array of segments with detected intents.
      - **intents** (array) - Array of intents within a segment.
        - **intent** (string) - The detected intent.
        - **confidence** (number) - Confidence score for the intent.

#### Response Example
```json
{
  "results": {
    "summary": {
      "text": "This is a summary of the provided text."
    },
    "topics": {
      "segments": [
        {
          "topics": [
            {
              "topic": "API",
              "confidence": 0.95
            }
          ]
        }
      ]
    },
    "sentiments": {
      "average": {
        "score": 0.8,
        "label": "positive"
      },
      "segments": []
    },
    "intents": {
      "segments": [
        {
          "intents": [
            {
              "intent": "analyze_text",
              "confidence": 0.9
            }
          ]
        }
      ]
    }
  }
}
```
```

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