AI Chat and Research

Request pipeline for chat, search routing, deep search, document generation, and streaming.

Core chat processing is orchestrated in buildChatStream(...), called by POST /api/chat.

Execution model

This flow combines synchronous request orchestration, streaming output, and post-finish persistence/accounting in one pipeline.

Request Flow Overview

Request ingress

Client sends POST /api/chat; server resolves user/session and validates request context.

Chat builder pipeline

buildChatStream(...) performs limits checks, context assembly, optional deep-search routing, and model execution.

Stream and finalize

Response streams incrementally, then post-finish logic persists outputs and usage data.

Resume endpoint:

GET /api/chat/[id]/stream

Routing Model Inside `buildChatStream`

Deep-search branch

Triggered by user setting (deepResearch) or complexity detection.

Flow:

evaluate deep-search decision
optional clarification questions
run deep search + synthesis
optional document artifact generation

Standard branch

When deep-search branch is not taken:

classifier decides isNeedSearch, document intent, or direct reasoning
if search is needed: phased search agent executes
if document creation is needed: optional search context + artifact flow
else: direct final reasoning response

Streaming Behavior

output uses createUIMessageStreamResponse(...)
stream context supports resumable streams via Redis pub/sub
stream includes structured progress chunks for phases, classifier decisions, and document processing

Model/provider and Usage Integration

AI calls are wrapped with withUsageTracking(...)
usage tracking middleware records token usage for both generate and stream operations
supported providers in billing model: groq, openai

POST /api/enhance-prompt
POST /api/instruments/transcription
POST /api/instruments/compare
POST /api/artifact
PATCH /api/artifact/[id]/patch
POST /api/artifact/export

Configuration Touchpoints

Required minimum:

GROQ_API_KEY=
# or
OPENAI_API_KEY=

Related feature flags:

FEATURE_DEEP_SEARCH_ENABLED=true
FEATURE_ARTIFACTS_ENABLED=true
FEATURE_TRANSCRIPTION_ENABLED=true
FEATURE_DOCUMENT_COMPARISON_ENABLED=true
DEVELOPMENT_MODE=false

On this page