Skip to content

AGENTS.md

Latest commit

 

History

History
166 lines (124 loc) · 6.02 KB

AGENTS.md

File metadata and controls

166 lines (124 loc) · 6.02 KB

cpp-text-intelligence

C++ (Crow) demo app for Deepgram Text Intelligence.

Architecture

  • Backend: C++ (Crow) (C++) on port 8081
  • Frontend: Vite + vanilla JS on port 8080 (git submodule: text-intelligence-html)
  • API type: REST — POST /api/text-intelligence
  • Deepgram API: Text Intelligence / Read API (/v1/read)
  • Auth: JWT session tokens via /api/session (WebSocket auth uses access_token.<jwt> subprotocol)

Key Files

File Purpose
src/main.cpp Main backend — API endpoints and request handlers
deepgram.toml Metadata, lifecycle commands, tags
Makefile Standardized build/run targets
sample.env Environment variable template
frontend/main.js Frontend logic — UI controls, API calls, result rendering
frontend/index.html HTML structure and UI layout
deploy/Dockerfile Production container (Caddy + backend)
deploy/Caddyfile Reverse proxy, rate limiting, static serving

Quick Start

# 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 / Stop

Start (recommended):

make start

Start separately:

# Terminal 1 — Backend
./build/app

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

Stop all:

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

Clean rebuild:

rm -rf build frontend/node_modules frontend/.vite
make init

Dependencies

  • Backend: CMakeLists.txt + vcpkg.json — Uses vcpkg for C++ deps and CMake for builds. Set VCPKG_ROOT env var. Crow framework for HTTP/WebSocket.
  • Frontend: frontend/package.json — Vite dev server
  • Submodules: frontend/ (text-intelligence-html), contracts/ (starter-contracts)

Install: cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" && cmake --build build Frontend: cd frontend && corepack pnpm install

API Endpoints

Endpoint Method Auth Purpose
/api/session GET None Issue JWT session token
/api/metadata GET None Return app metadata (useCase, framework, language)
/api/text-intelligence POST JWT Analyzes text for summaries, topics, sentiment, and intents.

Customization Guide

Toggling Analysis Features

The API supports four analysis features, each enabled independently via query parameters:

Feature Parameter Values Effect
Summarize summarize true, v2 Generate text summary
Topics topics true Detect discussed topics
Sentiment sentiment true Analyze sentiment (positive/neutral/negative)
Intents intents true Detect user intents

Backend: These are passed as query parameters to the Deepgram Read API. Enable/disable them in the backend handler or let the frontend control them.

Frontend: The frontend has checkboxes for each feature. Users select which analyses to run. To change defaults (e.g., always enable sentiment), edit frontend/main.js.

Changing the Language

Add language=<code> as a query parameter. Default is en. Supported languages depend on the feature — check Deepgram docs.

Input Modes

The app supports two input modes:

  1. Text — User pastes text directly
  2. URL — User provides a URL; the backend fetches and analyzes the text content

Customizing the Response

The full Deepgram response includes:

  • results.summary.text — Summary text
  • results.topics.segments[].topics[].topic — Detected topics with confidence
  • results.sentiments.average — Overall sentiment with score
  • results.sentiments.segments[] — Per-segment sentiment
  • results.intents.segments[].intents[].intent — Detected intents with confidence

You can modify the backend response formatter to include/exclude specific fields or add post-processing.

Frontend Changes

The frontend is a git submodule from deepgram-starters/text-intelligence-html. To modify:

  1. Edit files in frontend/ — this is the working copy
  2. Test locally — changes reflect immediately via Vite HMR
  3. Commit in the submodule: cd frontend && git add . && git commit -m "feat: description"
  4. Push the frontend repo: cd frontend && git push origin main
  5. Update the submodule ref: cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"

IMPORTANT: Always edit frontend/ inside THIS starter directory. The standalone text-intelligence-html/ directory at the monorepo root is a separate checkout.

Adding a UI Control for a New Feature

  1. Add the HTML element in frontend/index.html (input, checkbox, dropdown, etc.)
  2. Read the value in frontend/main.js when making the API call or opening the WebSocket
  3. Pass it as a query parameter or request body field
  4. Handle it in the backend src/main.cpp — read the param and pass it to the Deepgram API

Environment Variables

Variable Required Default Purpose
DEEPGRAM_API_KEY Yes — Deepgram API key
PORT No 8081 Backend server port
HOST No 0.0.0.0 Backend bind address
SESSION_SECRET No — JWT signing secret (production)

Conventional Commits

All commits must follow conventional commits format. Never include Co-Authored-By lines for Claude.

feat(cpp-text-intelligence): add diarization support
fix(cpp-text-intelligence): resolve WebSocket close handling
refactor(cpp-text-intelligence): simplify session endpoint
chore(deps): update frontend submodule

Testing

# Run conformance tests (requires app to be running)
make test

# Manual endpoint check
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool