Skip to main content

ragService

Workspace API

Workspace API / services/ragService

services/ragService

Interfaces​

RerankResult​

Defined in: services/ragService.ts:46

Result from rerankChunks operation

Properties​

chunks​

chunks: DocumentChunk[]

Defined in: services/ragService.ts:47

confidence​

confidence: RAGConfidenceMetrics

Defined in: services/ragService.ts:48

DocumentAccessValidation​

Defined in: services/ragService.ts:376

Result of document access validation

Properties​

hasAccess​

hasAccess: boolean

Defined in: services/ragService.ts:378

Whether the user has access to all documents

unauthorizedDocuments​

unauthorizedDocuments: string[]

Defined in: services/ragService.ts:380

Document IDs that belong to orgs the user doesn't have access to

unauthorizedOrganizations​

unauthorizedOrganizations: string[]

Defined in: services/ragService.ts:382

Organization IDs that the user doesn't have access to

documentOrganizations​

documentOrganizations: Map<string, string>

Defined in: services/ragService.ts:384

Map of document ID to organization ID for valid documents

DocumentResolutionResult​

Defined in: services/ragService.ts:542

Properties​

documentIds​

documentIds: string[]

Defined in: services/ragService.ts:543

organizationId​

organizationId: string | null

Defined in: services/ragService.ts:544

error?​

optional error: string

Defined in: services/ragService.ts:545

errorType?​

optional errorType: DocumentResolutionErrorType

Defined in: services/ragService.ts:546

StructuredRAGPrompt​

Defined in: services/ragService.ts:1338

Structured RAG prompt containing separate system and user prompts

Properties​

systemPrompt​

systemPrompt: string

Defined in: services/ragService.ts:1339

userPrompt​

userPrompt: string

Defined in: services/ragService.ts:1340

combinedPrompt​

combinedPrompt: string

Defined in: services/ragService.ts:1341

Type Aliases​

DocumentResolutionErrorType​

DocumentResolutionErrorType = "not_found" | "access_denied" | "multi_org" | "invalid_input"

Defined in: services/ragService.ts:536

Error types for document resolution - used to map to correct HTTP status codes

  • 'not_found': Documents don't exist (400 invalid_scope)
  • 'access_denied': User lacks permission (403 permission_denied)
  • 'multi_org': Documents span multiple orgs (400 invalid_scope)
  • 'invalid_input': Mixed UUID/path input (400 invalid_scope)

Variables​

BASE_CHAT_SYSTEM_PROMPT​

const BASE_CHAT_SYSTEM_PROMPT: "You are an AI assistant specializing in document analysis.\n\nCRITICAL CITATION RULES:\n1. Answer based ONLY on the DOCUMENT CONTEXT section (numbered [1], [2], etc.)\n2. EVERY factual claim MUST include a citation like [1], [2], [3 p.5], etc.\n3. Include page numbers when available (e.g., [2 p.5])\n4. If information is not in the documents, explicitly state it is unavailable\n5. NEVER answer from memory or general knowledge - only cite the provided documents\n6. Use conversation history to understand intent, but ALWAYS cite from DOCUMENT CONTEXT\n\nIMPORTANT: Responses without proper [n] citations are considered incomplete."

Defined in: services/ragService.ts:1223

Base system prompt for all chat interactions Mirrors Skills framework pattern but optimized for conversational output

BASE_SKILL_SYSTEM_PROMPT​

const BASE_SKILL_SYSTEM_PROMPT: "You are a document analysis assistant that outputs structured data in JSON format.\n\nCRITICAL RULES:\n1. Always output valid JSON matching the requested schema\n2. Extract information ONLY from the provided document context\n3. If a required field has no data in the documents, use null or an empty array\n4. Never fabricate or infer information not present in the source\n5. Include source citations for all extracted data (page numbers, section references)\n\nOUTPUT FORMAT:\n- Return a single JSON object\n- Use camelCase for field names\n- Include metadata: { "source_citations": [...], "confidence": "high|medium|low" }\n\nWhen data is missing or ambiguous, reduce confidence and note the issue in the JSON output."

Defined in: services/ragService.ts:1239

Base system prompt for all skill executions Optimized for structured JSON output

Functions​

computeCandidateK()​

computeCandidateK(effectiveTopK, rerankerMaxK): object

Defined in: services/ragService.ts:67

Compute candidate pool size with proper capping

Ensures we fetch enough candidates for effective reranking while respecting:

  • Reranker's maxK limit (service capability)
  • MAX_RERANK_CANDIDATES (absolute ceiling for payload size)
  • At least effectiveTopK (never return fewer than requested)

Parameters​

effectiveTopK​

number

Number of results the user wants

rerankerMaxK​

Maximum K the reranker service supports (or undefined if not set)

number | undefined

Returns​

object

candidateK and whether truncation occurred

candidateK​

candidateK: number

truncated​

truncated: boolean

rerankChunks()​

rerankChunks(query, chunks, topK): Promise<RerankResult>

Defined in: services/ragService.ts:121

Rerank chunks and compute confidence metrics

Takes vector search results and reranks them using the cross-encoder reranker. Sorts results by relevance_score descending to ensure deterministic ordering. If reranker returns fewer than topK (due to maxK cap), pads with next-best vector search results to meet caller expectations.

Parameters​

query​

string

The original user query

chunks​

DocumentChunk[]

Candidate chunks from vector search (with original order)

topK​

number

Number of results to return after reranking

Returns​

Promise<RerankResult>

Reranked chunks with confidence metrics

buildFallbackConfidence()​

buildFallbackConfidence(candidatePoolSize, returnedCount, truncated, skipReason): RAGConfidenceMetrics

Defined in: services/ragService.ts:253

Build fallback confidence when reranker is skipped or fails

Always returns a valid RAGConfidenceMetrics object so that confidence is ALWAYS present in responses (even when reranking doesn't run).

Parameters​

candidatePoolSize​

number

Number of candidates from vector search

returnedCount​

number

Number of chunks returned to user

truncated​

boolean

Whether candidate pool was capped

skipReason​

RerankerSkipReason

Why the reranker was skipped

Returns​

RAGConfidenceMetrics

Fallback confidence metrics

detectStaleCitations()​

detectStaleCitations(chunks, queryStartAt): Promise<Map<string, boolean>>

Defined in: services/ragService.ts:296

Check if citations are stale (document updated after query started)

Staleness rule: citation is stale if doc.updated_at > query_start_at This ensures citations are marked stale even if document updates mid-request.

IMPORTANT: updated_at changes on ANY document update, including:

  • File re-upload (content change)
  • File replacement (content change)
  • Metadata updates (non-content change)

This means citations may be marked stale even if only metadata changed. This is intentional: "stale indicates potential mismatch" - if document metadata changes, citations may be stale even if content is unchanged. Support expectation: "stale reflects any document update, including metadata"

Future enhancement: If content_updated_at or file_hash tracking is added, consider scoping staleness to content changes only for more granular detection.

Parameters​

chunks​

DocumentChunk[]

Document chunks to check

queryStartAt​

Timestamp when query request started (Date or number ms)

number | Date

Returns​

Promise<Map<string, boolean>>

Map of chunk_id to stale status

recomputeStaleCitations()​

recomputeStaleCitations(chunks, messageCreatedAt, docUpdatedAtMap?): Promise<Map<string, boolean>>

Defined in: services/ragService.ts:347

Recompute stale citations for a saved message (used when fetching historical messages)

Parameters​

chunks​

DocumentChunk[]

Chunks from saved message

messageCreatedAt​

Date

Timestamp when message was created (from message.created_at)

docUpdatedAtMap?​

Map<string, Date>

Optional pre-computed map of document_id -> updated_at Date (for batch optimization)

Returns​

Promise<Map<string, boolean>>

Map of chunk_id to stale status

validateDocumentAccess()​

validateDocumentAccess(documentIds, userOrganizationIds): Promise<DocumentAccessValidation>

Defined in: services/ragService.ts:395

Validate user has access to documents by checking their organization membership Documents belong to organizations; users must be members of those orgs to access.

Parameters​

documentIds​

string[]

Array of document UUIDs to validate

userOrganizationIds​

string[]

Array of org IDs the user has membership in

Returns​

Promise<DocumentAccessValidation>

Validation result with access status and unauthorized details

getOrganizationIdsFromDocuments()​

getOrganizationIdsFromDocuments(documentIds): Promise<string[]>

Defined in: services/ragService.ts:469

Get organization IDs from document IDs Used to infer organization for documents scope when not explicitly provided.

Parameters​

documentIds​

string[]

Array of document UUIDs

Returns​

Promise<string[]>

Array of unique organization IDs

resolveScopeIdsToDocumentIds()​

resolveScopeIdsToDocumentIds(userOrgIds, scopeIds): Promise<DocumentResolutionResult>

Defined in: services/ragService.ts:558

Resolve scope IDs to document IDs, supporting both UUIDs and file paths The frontend may send either document UUIDs directly or file paths/names. This function handles both cases for backwards compatibility.

Parameters​

userOrgIds​

string[]

Array of organization IDs the user has access to

scopeIds​

string[]

Array of document UUIDs OR file paths/filenames (must be all one type)

Returns​

Promise<DocumentResolutionResult>

Object with resolved document IDs, organization ID, and optional error with type

resolveFilePathsToDocumentIds()​

resolveFilePathsToDocumentIds(organizationId, filePaths): Promise<string[]>

Defined in: services/ragService.ts:727

Resolve file paths/names to document IDs (legacy function for backwards compatibility) The frontend sends display_filename (e.g., "document.pdf") but the database expects document UUIDs. This function resolves paths to document IDs via the app_data_document_locations table.

Parameters​

organizationId​

string

Organization ID (required for scoped lookup)

filePaths​

string[]

Array of file paths or filenames

Returns​

Promise<string[]>

Array of document UUIDs

Deprecated​

Use resolveScopeIdsToDocumentIds instead

searchSimilarChunks()​

searchSimilarChunks(queryEmbedding, scope, scopeIds, topK, metadataFilter?): Promise<DocumentChunk[]>

Defined in: services/ragService.ts:781

Search for similar document chunks based on query embedding

Uses direct database connections:

  • coda_rag: Vector similarity search on rag_document_chunks
  • coda_app: Document metadata and access control

Parameters​

queryEmbedding​

number[]

Vector embedding of the query

scope​

RAGScope

Search scope (organization, project, or documents)

scopeIds​

string[]

Array of scope identifiers (single ID for org/project, multiple for documents)

topK​

number = 8

Number of results to return

metadataFilter?​

Record<string, any>

Optional metadata filter

Returns​

Promise<DocumentChunk[]>

searchCDUChunksByKeyword()​

searchCDUChunksByKeyword(scope, scopeIds, limit): Promise<DocumentChunk[]>

Defined in: services/ragService.ts:972

Search for CDU-specific chunks using keyword matching This is a fallback for when semantic search doesn't retrieve CDU content because the query embedding doesn't match the legal terminology well enough.

Uses direct database connections:

  • coda_rag: Keyword search on rag_document_chunks
  • coda_app: Document metadata and access control

Supports all RAG scopes:

  • Organization scope: Searches all documents in the organization
  • Project scope: Searches all documents in the project
  • Documents scope: Searches only the specified document IDs (must be UUIDs)

Parameters​

scope​

RAGScope

RAG scope ('organization', 'project', or 'documents')

scopeIds​

string[]

Scope-specific IDs:

  • organization: [organizationId]
  • project: [projectId, ...]
  • documents: [documentId, ...] (must be resolved UUIDs, not filenames)
limit​

number = 10

Maximum number of chunks to return

Returns​

Promise<DocumentChunk[]>

Array of DocumentChunks containing CDU-related content

generateQueryEmbedding()​

generateQueryEmbedding(query): Promise<number[]>

Defined in: services/ragService.ts:1099

Generate embeddings for query text using self-hosted Granite Embedding model

Parameters​

query​

string

Returns​

Promise<number[]>

enhanceQuery()​

enhanceQuery(query): Promise<string>

Defined in: services/ragService.ts:1120

Enhance query for better retrieval This function expands the query to improve retrieval quality

Domain-aware enhancement for municipal bond and legal document analysis. Aligned with the legal-analyst system prompt v1.2+ for consistent terminology.

Parameters​

query​

string

Returns​

Promise<string>

composeChatSystemPrompt()​

composeChatSystemPrompt(agentPrompt, domainKey?, userOrgIds?): Promise<string>

Defined in: services/ragService.ts:1271

Compose system prompt for chat using layered architecture Mirrors Skills framework pattern: Base + Domain (chat-specific)

Strategy:

  • If no domainKey: Use agentPrompt.systemPrompt (preserves existing behavior)
  • If valid domainKey: BASE_CHAT_SYSTEM_PROMPT + Domain Chat Prompt
  • If invalid domainKey: Fall back to agentPrompt.systemPrompt (ignore invalid key)

This ensures backwards compatibility while enabling domain-specific prompting. Invalid domain keys are treated as "no domain" to avoid unexpected behavior changes.

Parameters​

agentPrompt​

AgentPrompt

Agent prompt configuration (for fallback)

domainKey?​

string

Optional domain pack key for specialized behavior

userOrgIds?​

string[]

Returns​

Promise<string>

Composed system prompt string

buildRAGPrompt()​

buildRAGPrompt(query, chunks, systemPrompt?): StructuredRAGPrompt

Defined in: services/ragService.ts:1354

Build RAG prompt with context chunks Returns structured prompt with separate system and user components for proper audit logging and LLM systemInstruction support.

Parameters​

query​

string

User's query

chunks​

DocumentChunk[]

Retrieved document chunks

systemPrompt?​

string

Optional custom system prompt (from agent config)

Returns​

StructuredRAGPrompt

Structured prompt object

buildRAGPromptWithHistory()​

buildRAGPromptWithHistory(query, chunks, historyContext, systemPrompt?): StructuredRAGPrompt

Defined in: services/ragService.ts:1408

Build RAG prompt with conversation history context Uses tiered memory: key facts + summary + recent exchanges

Parameters​

query​

string

User's query

chunks​

DocumentChunk[]

Retrieved document chunks

historyContext​

string

Formatted history context string

systemPrompt?​

string

Optional custom system prompt (from agent config)

Returns​

StructuredRAGPrompt

Structured prompt object

generateAnswer()​

generateAnswer(prompt, stream, options?): Promise<string | AsyncGenerator<string, void, unknown>>

Defined in: services/ragService.ts:1484

Generate answer using LLM with streaming support Supports both string prompts (backwards compatible) and structured prompts Uses the configured default LLM provider (model-agnostic)

Parameters​

prompt​

string | StructuredRAGPrompt

stream​

boolean = true

options?​
maxTokens?​

number

temperature?​

number

timeoutMs?​

number

Returns​

Promise<string | AsyncGenerator<string, void, unknown>>