### Initialize and Start Project

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

Commands to initialize the project by cloning submodules and installing dependencies, setting up environment variables, and starting 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
```

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

### Initialize and Start the PHP Application

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

Use these commands to initialize the project, configure environment variables, and start the local development server.

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

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

### Start Development Servers with Make

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

Use this make command to simultaneously start both the frontend and backend development servers for the application.

```bash
make start
```

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

### Install Frontend Dependencies

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

Commands to navigate to the frontend directory and install its dependencies using pnpm.

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

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

### Install Backend Dependencies

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

Command to install backend PHP dependencies using Composer.

```bash
composer install
```

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

### Start Servers Separately

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

Instructions for starting the backend and frontend servers in separate terminals. The backend runs using PHP's built-in server, and the frontend uses Vite.

```bash
# Terminal 1 — Backend
php server.php

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

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

### Initialize Project Dependencies with Make

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

Execute this make command to initialize the project by setting up submodules and installing all required dependencies.

```bash
make init
```

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

### Manage Project Lifecycle with Makefile

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

Use these commands to start servers, build the frontend, update dependencies, and run tests.

```bash
make start-backend   # PHP server on port 8081
make start-frontend  # Vite dev server on port 8080

# Build frontend for production
make build

# Update submodules to latest
make update

# Clean build artifacts
make clean

# View project status
make status

# Run contract conformance tests
make test
```

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

### Conventional Commits Examples

Source: https://github.com/deepgram-starters/php-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(php-text-intelligence): add diarization support
```

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

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

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

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

### Check Prerequisites with Make

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

Run this make command to verify that all necessary prerequisites like git, php, composer, and pnpm are installed and available in your environment.

```bash
make check-prereqs
```

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

### GET /health

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

Simple health check endpoint for monitoring and load balancer configurations.

```APIDOC
## GET /health

### Description
A simple health check endpoint used for monitoring and load balancer configurations.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The status of the service (e.g., "ok").
- **service** (string) - The name of the service being checked.

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

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

### Handle API Error Responses

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

Examples of API request failures and their corresponding JSON error structures.

```bash
# Missing authorization token
curl -X POST "http://localhost:8081/api/text-intelligence" \
  -H "Content-Type: application/json" \
  -d '{"text": "test"}'

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

# Invalid/expired token
# Response (401):
{
  "error": {
    "type": "AuthenticationError",
    "code": "INVALID_TOKEN",
    "message": "Session expired, please refresh the page"
  }
}

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

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

# Empty text content
# Response (400):
{
  "error": {
    "type": "validation_error",
    "code": "EMPTY_TEXT",
    "message": "Text content cannot be empty",
    "details": {}
  }
}
```

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

### Retrieve Application Metadata

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

Fetch application metadata, including title, description, author, and repository, by making a GET request to the /api/metadata endpoint.

```bash
curl -X GET "http://localhost:8081/api/metadata"
```

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

### GET /api/metadata

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

Returns application metadata from the deepgram.toml configuration file's [meta] section.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata, including title, description, author, repository, use case, language, framework, and tags, as defined in the `deepgram.toml` configuration file's `[meta]` section.

### 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(s) of the application.
- **repository** (string) - The URL of the application's repository.
- **useCase** (string) - The primary 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.

#### Response Example
```json
{
  "title": "PHP Text Intelligence",
  "description": "Get started using Deepgram's Text Intelligence with this PHP demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/php-text-intelligence",
  "useCase": "text-intelligence",
  "language": "php",
  "framework": "php",
  "tags": ["text-intelligence", "text-analysis", "summarization", "topics", "sentiment", "php"]
}
```
```

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

### GET /api/session

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

Issues a signed JWT token for session authentication. Required before making requests to protected endpoints.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT token for session authentication. This token is required before making requests to protected endpoints.

### Method
GET

### Endpoint
/api/session

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

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

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

### Health Check Endpoint

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

Perform a simple health check by sending a GET request to the /health endpoint. This is useful for monitoring and load balancer configurations.

```bash
curl -X GET "http://localhost:8081/health"
```

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

### Get Session Token for Authentication

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

This cURL command retrieves a signed JWT token required for authenticating requests to protected API endpoints. Store this token for subsequent API calls.

```bash
curl -X GET "http://localhost:8081/api/session"
```

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

### Deploy with Docker and Fly.io

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

Commands for building the Docker image locally and deploying the application to Fly.io with required environment variables.

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

# Run container locally
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_session_secret \
  php-text-intelligence

# Deploy to Fly.io
fly launch  # First time setup
fly secrets set DEEPGRAM_API_KEY=your_api_key
fly secrets set SESSION_SECRET=your_session_secret
fly deploy

# View deployment logs
fly logs
```

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

### Run Conformance Tests

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

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

```bash
make test
```

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

### Clean and Rebuild Project

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

Commands to perform a clean rebuild of the project by removing vendor and node_modules directories, clearing the Vite cache, and re-initializing dependencies.

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

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

### Environment Variable Configuration

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

Configure the application by setting environment variables in a .env file. Key variables include DEEPGRAM_API_KEY, PORT, HOST, and SESSION_SECRET.

```bash
# .env file configuration
# Required: Your Deepgram API key from https://console.deepgram.com
DEEPGRAM_API_KEY=your_api_key_here

# Optional: Backend server configuration
PORT=8081
HOST=0.0.0.0

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

# Quick setup from sample
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY
```

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

### Use Session Token in API Request

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

Demonstrates how to capture the session token obtained from the /api/session endpoint and use it in the Authorization header for subsequent API requests.

```bash
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r '.token')
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your text content here"}'
```

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

### Commit Frontend Changes

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

Steps to commit changes made to the frontend code within the git submodule. This includes staging, committing, and pushing the changes.

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

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

### Update Frontend Submodule Reference

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

Command to update the main project's reference to the frontend git submodule after making changes and pushing them.

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

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

### Manual Endpoint Check - Metadata

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

Perform a manual check of 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
```

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

### Analyze Raw Text with Text Intelligence API

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

Use this cURL command to send raw text to the API and enable various text intelligence features. Ensure you include your session token and set the appropriate query parameters.

```bash
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=true&topics=true&sentiment=true&intents=true&language=en" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session_token>" \
  -d '{"text": "Deepgram is a speech recognition company that provides AI-powered transcription services. Their technology uses deep learning to deliver fast and accurate speech-to-text conversion. The company focuses on enterprise customers who need reliable audio processing at scale."}'
```

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

### Manual Endpoint Check - Session

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

Perform a manual check of 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
```

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

### Stop All Running Processes

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

Command to stop any processes listening on ports 8080 and 8081, typically used to halt the backend and frontend servers.

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

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

### Analyze URL Content with Text Intelligence API

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

This cURL command analyzes content fetched from a given URL. It supports different summarization versions and other intelligence features. Replace the URL with your target content.

```bash
curl -X POST "http://localhost:8081/api/text-intelligence?summarize=v2&topics=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session_token>" \
  -d '{"url": "https://example.com/article.html"}'
```

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

### POST /api/text-intelligence

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

Analyzes text content using Deepgram's Text Intelligence API. Accepts either raw text or a URL to fetch content from. Supports multiple intelligence features via query parameters.

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

### Description
Analyzes text content using Deepgram's Text Intelligence API. Accepts either raw text or a URL to fetch content from. Supports multiple intelligence features via query parameters.

### Method
POST

### Endpoint
/api/text-intelligence

### Query Parameters
- **summarize** (boolean or string) - Optional - Whether to perform summarization. Can be `true` or `v2` for advanced summarization.
- **topics** (boolean) - Optional - Whether to detect topics.
- **sentiment** (boolean) - Optional - Whether to perform sentiment analysis.
- **intents** (boolean) - Optional - Whether to perform intent recognition.
- **language** (string) - Optional - The language code for the text (e.g., 'en').

### Request Body
- **text** (string) - Required if 'url' is not provided - The raw text content to analyze.
- **url** (string) - Required if 'text' is not provided - The URL of the content to fetch and analyze.

### Request Example
```json
{
  "text": "Deepgram is a speech recognition company that provides AI-powered transcription services. Their technology uses deep learning to deliver fast and accurate speech-to-text conversion. The company focuses on enterprise customers who need reliable audio processing at scale."
}
```

### Response
#### Success Response (200)
- **results** (object) - Contains the analysis results.
  - **summary** (object) - The summary of the text.
    - **text** (string) - The summarized text.
  - **topics** (object) - Detected topics.
    - **segments** (array) - An array of topic segments.
      - **text** (string) - The text segment.
      - **topics** (array) - An array of detected topics for the segment.
        - **topic** (string) - The detected topic.
        - **confidence** (number) - The confidence score for the topic.
  - **sentiments** (object) - Detected sentiments.
    - **segments** (array) - An array of sentiment segments.
      - **text** (string) - The text segment.
      - **sentiment** (string) - The detected sentiment (e.g., 'positive').
      - **confidence** (number) - The confidence score for the sentiment.
  - **intents** (object) - Detected intents.
    - **segments** (array) - An array of intent segments.
      - **text** (string) - The text segment.
      - **intent** (string) - The detected intent.
      - **confidence** (number) - The confidence score for the intent.

#### Response Example
```json
{
  "results": {
    "summary": {
      "text": "Deepgram provides AI-powered speech recognition and transcription services for enterprise customers."
    },
    "topics": {
      "segments": [
        {"text": "speech recognition", "topics": [{"topic": "Technology", "confidence": 0.95}]}
      ]
    },
    "sentiments": {
      "segments": [
        {"text": "...", "sentiment": "positive", "confidence": 0.87}
      ]
    },
    "intents": {
      "segments": [
        {"text": "...", "intent": "inform", "confidence": 0.92}
      ]
    }
  }
}
```
```

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