rag

Workspace API

---

Workspace API / types/rag

types/rag

Interfaces

RAGQueryRequest

Defined in: types/rag.ts:7

Properties

query

query: string

Defined in: types/rag.ts:8

scope

scope: RAGScope

Defined in: types/rag.ts:9

scopeIds

scopeIds: string[]

Defined in: types/rag.ts:10

topK?

optional topK: number

Defined in: types/rag.ts:11

enhanceQuery?

optional enhanceQuery: boolean

Defined in: types/rag.ts:12

skipRetrieval?

optional skipRetrieval: boolean

Defined in: types/rag.ts:13

metadataFilter?

optional metadataFilter: Record<string, any>

Defined in: types/rag.ts:14

maxTokens?

optional maxTokens: number

Defined in: types/rag.ts:15

temperature?

optional temperature: number

Defined in: types/rag.ts:16

stream?

optional stream: boolean

Defined in: types/rag.ts:17

domainKey?

optional domainKey: string

Defined in: types/rag.ts:18

history?

optional history: RAGHistoryPayload

Defined in: types/rag.ts:21

Optional conversation history for context

historyDelta?

optional historyDelta: RAGHistoryPayload

Defined in: types/rag.ts:24

Optional client-side history delta when conversationId is provided

conversationId?

optional conversationId: string

Defined in: types/rag.ts:27

Conversation ID for server-side history lookup (alternative to passing history)

intentMode?

optional intentMode: "auto" | "always_retrieve" | "history_only"

Defined in: types/rag.ts:35

Intent routing behavior

• 'auto': Use hybrid LLM/heuristic classification (default)
• 'always_retrieve': Skip intent classification, always retrieve
• 'history_only': Skip retrieval, use history only (for explicit follow-ups)

---

RAGHistoryPayload

Defined in: types/rag.ts:41

History payload for RAG queries

Properties

messages

messages: object[]

Defined in: types/rag.ts:43

Recent conversation messages

role

role: "user" | "assistant"

content

content: string

chunks?

optional chunks: object[]

createdAt?

optional createdAt: string

Client-side timestamp (ISO string) for delta reconciliation

maxTokens?

optional maxTokens: number

Defined in: types/rag.ts:51

Max tokens to allocate to history (default: 2000)

---

IntentClassificationResult

Defined in: types/rag.ts:62

Intent classification result returned in metadata

Properties

intent

intent: QueryIntent

Defined in: types/rag.ts:63

confidence

confidence: "high" | "medium" | "low"

Defined in: types/rag.ts:64

method

method: "heuristic" | "llm"

Defined in: types/rag.ts:65

latencyMs

latencyMs: number

Defined in: types/rag.ts:66

---

ContextUsageResult

Defined in: types/rag.ts:72

Context window usage breakdown for frontend display

Properties

totalUsed

totalUsed: number

Defined in: types/rag.ts:74

Total tokens used in this request

contextWindow

contextWindow: number

Defined in: types/rag.ts:76

Model's context window size

percentUsed

percentUsed: number

Defined in: types/rag.ts:78

Usage percentage (0-100)

breakdown

breakdown: object

Defined in: types/rag.ts:80

Breakdown by component

systemPrompt

systemPrompt: number

history

history: number

chunks

chunks: number

query

query: number

responseReserve

responseReserve: number

warning?

optional warning: "approaching_limit" | "at_capacity"

Defined in: types/rag.ts:88

Warning if approaching capacity

summarizationRecommended?

optional summarizationRecommended: boolean

Defined in: types/rag.ts:90

Whether summarization is recommended

currentQueryChunkCount?

optional currentQueryChunkCount: number

Defined in: types/rag.ts:92

Number of chunks retrieved in THIS query

historyChunkCount?

optional historyChunkCount: number

Defined in: types/rag.ts:94

Total chunks available in conversation history context

---

DocumentChunk

Defined in: types/rag.ts:97

Properties

chunk_id

chunk_id: string

Defined in: types/rag.ts:98

document_id

document_id: string

Defined in: types/rag.ts:99

chunk_index

chunk_index: number

Defined in: types/rag.ts:100

text

text: string

Defined in: types/rag.ts:101

similarity

similarity: number

Defined in: types/rag.ts:103

Vector search cosine similarity (0-1)

original_rank?

optional original_rank: number

Defined in: types/rag.ts:105

Position in vector search results (0-indexed, for debugging)

relevance_score?

optional relevance_score: number

Defined in: types/rag.ts:110

Reranker score (raw logit, unbounded, can be negative). Only present for reranked chunks.

See

docs/rag/technical/RAG_IMPLEMENTATION.md#reranking-pipeline

rerank_position?

optional rerank_position: number

Defined in: types/rag.ts:112

Position in reranked results (0-indexed)

padded?

optional padded: boolean

Defined in: types/rag.ts:114

True if this chunk was padded from vector search (not reranked). Has no relevance_score.

page_numbers?

optional page_numbers: number[]

Defined in: types/rag.ts:115

document_filename?

optional document_filename: string

Defined in: types/rag.ts:116

document_path?

optional document_path: string

Defined in: types/rag.ts:117

document_metadata?

optional document_metadata: Record<string, any>

Defined in: types/rag.ts:118

classification?

optional classification: string

Defined in: types/rag.ts:120

Optional classification (future feature)

stale?

optional stale: boolean

Defined in: types/rag.ts:122

True if source document was updated after query started

prompt_index?

optional prompt_index: number

Defined in: types/rag.ts:128

Index of this chunk in the prompt context (0-based). Used for citation mapping: citation [1] maps to prompt_index 0, [2] to 1, etc. This ensures citation mapping is stable even if chunks are re-ordered after retrieval.

---

RAGConfidenceMetrics

Defined in: types/rag.ts:140

Confidence metrics from the reranking process Always included in RAG responses (rerankerUsed true or false)

Properties

rerankerUsed

rerankerUsed: boolean

Defined in: types/rag.ts:142

True if reranking succeeded

rerankerSkipReason?

optional rerankerSkipReason: RerankerSkipReason

Defined in: types/rag.ts:144

Why reranker was skipped (only present when rerankerUsed=false)

candidatePoolSize

candidatePoolSize: number

Defined in: types/rag.ts:146

Candidates retrieved from vector search

returnedCount

returnedCount: number

Defined in: types/rag.ts:148

Chunks returned after reranking/slicing (includes reranked + padded)

rerankedCount?

optional rerankedCount: number

Defined in: types/rag.ts:150

How many chunks were actually reranked (only present when rerankerUsed=true)

paddedCount?

optional paddedCount: number

Defined in: types/rag.ts:152

How many chunks were padded from vector search fallback (only present when padding occurred)

truncated

truncated: boolean

Defined in: types/rag.ts:154

True if candidatePool was capped by config limits

latencyMs?

optional latencyMs: number

Defined in: types/rag.ts:156

Reranker call duration in ms (only present when rerankerUsed=true)

scores?

optional scores: object

Defined in: types/rag.ts:161

Score statistics for RERANKED items only (not padded items). Only present when rerankerUsed=true and reranked results exist.

avg

avg: number

max

max: number

min

min: number

raw

raw: true

Always true - scores are raw logits from cross-encoder, not normalized 0-1

---

RAGQueryResponse

Defined in: types/rag.ts:170

Properties

query

query: string

Defined in: types/rag.ts:171

enhancedQuery?

optional enhancedQuery: string

Defined in: types/rag.ts:172

chunks

chunks: DocumentChunk[]

Defined in: types/rag.ts:173

answer

answer: string

Defined in: types/rag.ts:174

metadata

metadata: object

Defined in: types/rag.ts:175

retrievalTimeMs

retrievalTimeMs: number

generationTimeMs

generationTimeMs: number

totalTimeMs

totalTimeMs: number

chunkCount

chunkCount: number

intentClassification?

optional intentClassification: IntentClassificationResult

Intent classification result (when history provided)

retrievalSkipped?

optional retrievalSkipped: boolean

Whether retrieval was skipped

contextUsage?

optional contextUsage: ContextUsageResult

Context window usage breakdown (for frontend display)

---

RAGStreamChunk

Defined in: types/rag.ts:189

Properties

type

type: "error" | "chunk" | "metadata" | "text" | "complete"

Defined in: types/rag.ts:190

data?

optional data: any

Defined in: types/rag.ts:191

Type Aliases

RAGScope

RAGScope = "organization" | "project" | "documents"

Defined in: types/rag.ts:5

RAG (Retrieval Augmented Generation) types

---

QueryIntent

QueryIntent = "RETRIEVE" | "HISTORY_ONLY" | "TARGETED" | "HYBRID"

Defined in: types/rag.ts:57

Query intent classification

---

RerankerSkipReason

RerankerSkipReason = "disabled" | "error" | "timeout" | "no_candidates"

Defined in: types/rag.ts:134

Reason why the reranker was skipped