Skip to content

Open-source and local-first Slack and Notion alternative that puts you in control of your data

Refactor assistant response job and extract core assistant logic

Ylber Gashi00162ee06e1b
diff --git a/apps/server/src/jobs/assistant-response.ts b/apps/server/src/jobs/assistant-response.ts
index 52439757..13bceebb 100644
--- a/apps/server/src/jobs/assistant-response.ts
+++ b/apps/server/src/jobs/assistant-response.ts
@@ -1,32 +1,12 @@
-import {
- generateId,
- IdType,
- generateNodeIndex,
- getNodeModel,
- NodeAttributes,
- DatabaseNode,
- RecordNode,
- DatabaseAttributes,
-} from '@colanode/core';
-import { Document } from '@langchain/core/documents';
-import { StateGraph, Annotation } from '@langchain/langgraph';
+import { generateId, IdType, generateNodeIndex } from '@colanode/core';
import { database } from '@/data/database';
-import { eventBus } from '@/lib/event-bus';
import { configuration } from '@/lib/configuration';
-import { nodeRetrievalService } from '@/services/node-retrieval-service';
-import { documentRetrievalService } from '@/services/document-retrieval-service';
-import { JobHandler } from '@/types/jobs';
-import {
- rewriteQuery,
- rerankDocuments,
- generateFinalAnswer,
- generateNoContextAnswer,
- assessUserIntent,
- generateDatabaseFilters,
-} from '@/services/llm-service';
-import { CallbackHandler } from 'langfuse-langchain';
import { fetchNode } from '@/lib/nodes';
-import { recordsRetrievalService } from '@/services/records-retrieval-service';
+import { JobHandler } from '@/types/jobs';
+import { runAssistantResponseChain } from '@/lib/assistant';
+import { getNodeModel } from '@colanode/core';
+import { createNode } from '@/lib/nodes';
+import { MessageAttributes } from '@colanode/core';
export type AssistantResponseInput = {
type: 'assistant_response';
@@ -42,403 +22,6 @@ declare module '@/types/jobs' {
}
}
-// ---------------------------------------------------------------------
-// State Definition for the Response Chain
-// ---------------------------------------------------------------------
-const ResponseState = Annotation.Root({
- userInput: Annotation<string>(),
- workspaceId: Annotation<string>(),
- userId: Annotation<string>(),
- userDetails: Annotation<{ name: string; email: string }>(),
- parentMessageId: Annotation<string>(),
- currentMessageId: Annotation<string>(),
- rewrittenQuery: Annotation<string>(),
- contextDocuments: Annotation<Document[]>(),
- chatHistory: Annotation<Document[]>(),
- rerankedContext: Annotation<
- Array<{
- index: number;
- score: number;
- type: string;
- sourceId: string;
- }>
- >(),
- topContext: Annotation<Document[]>(),
- finalAnswer: Annotation<string>(),
- citations: Annotation<Array<{ sourceId: string; quote: string }>>(),
- originalMessage: Annotation<any>(),
- intent: Annotation<'retrieve' | 'no_context'>(),
- databaseContext: Annotation<
- Array<{
- id: string;
- name: string;
- fields: Record<string, { type: string; name: string }>;
- sampleRecords: any[];
- }>
- >(),
- databaseFilters: Annotation<{
- shouldFilter: boolean;
- filters: Array<{
- databaseId: string;
- filters: any[];
- }>;
- }>(),
-});
-
-// ---------------------------------------------------------------------
-// Chain Node Functions
-// ---------------------------------------------------------------------
-const generateRewrittenQuery = async (state: typeof ResponseState.State) => {
- const rewritten = await rewriteQuery(state.userInput);
- return { rewrittenQuery: rewritten };
-};
-
-const assessIntent = async (state: typeof ResponseState.State) => {
- const formattedChatHistory = state.chatHistory
- .map((doc) => {
- const timestamp = doc.metadata.createdAt
- ? new Date(doc.metadata.createdAt).toLocaleString()
- : 'Unknown time';
- const authorName = doc.metadata.authorName || 'User';
- return `- [${timestamp}] ${authorName}: ${doc.pageContent}`;
- })
- .join('\n');
-
- const intent = await assessUserIntent(state.userInput, formattedChatHistory);
- return { intent };
-};
-
-const generateNoContextResponse = async (state: typeof ResponseState.State) => {
- const formattedChatHistory = state.chatHistory
- .map((doc) => {
- const timestamp = doc.metadata.createdAt
- ? new Date(doc.metadata.createdAt).toLocaleString()
- : 'Unknown time';
- const authorName = doc.metadata.authorName || 'User';
- return `- [${timestamp}] ${authorName}: ${doc.pageContent}`;
- })
- .join('\n');
-
- const answer = await generateNoContextAnswer(
- state.userInput,
- formattedChatHistory
- );
- return { finalAnswer: answer };
-};
-
-const fetchContextDocuments = async (state: typeof ResponseState.State) => {
- const [nodeResults, documentResults] = await Promise.all([
- nodeRetrievalService.retrieve(
- state.rewrittenQuery,
- state.workspaceId,
- state.userId
- ),
- documentRetrievalService.retrieve(
- state.rewrittenQuery,
- state.workspaceId,
- state.userId
- ),
- ]);
-
- let databaseResults: Document[] = [];
-
- if (state.databaseFilters.shouldFilter) {
- const filteredRecords = await Promise.all(
- state.databaseFilters.filters.map(async (filter) => {
- const records = await recordsRetrievalService.retrieveByFilters(
- filter.databaseId,
- state.workspaceId,
- state.userId,
- {
- filters: filter.filters,
- sorts: [],
- page: 1,
- count: 10,
- }
- );
- const dbNode = await fetchNode(filter.databaseId);
- if (!dbNode || dbNode.type !== 'database') return [];
- const dbAttributes = dbNode.attributes as DatabaseAttributes;
- return records.map((record) => {
- const recordNode = record as unknown as RecordNode;
- return new Document({
- pageContent: `Database Record from ${dbAttributes.name}:\n${Object.entries(
- recordNode.attributes.fields || {}
- )
- .map(([key, value]) => `${key}: ${value}`)
- .join('\n')}`,
- metadata: {
- id: record.id,
- type: 'record',
- createdAt: record.created_at,
- author: record.created_by,
- databaseId: filter.databaseId,
- },
- });
- });
- })
- );
- databaseResults = filteredRecords.flat();
- }
-
- return {
- contextDocuments: [...nodeResults, ...documentResults, ...databaseResults],
- };
-};
-
-const fetchChatHistory = async (state: typeof ResponseState.State) => {
- const messages = await database
- .selectFrom('nodes')
- .where('parent_id', '=', state.parentMessageId)
- .where('type', '=', 'message')
- .where('id', '!=', state.currentMessageId)
- .where('workspace_id', '=', state.workspaceId)
- .orderBy('created_at', 'asc')
- .selectAll()
- .execute();
-
- return {
- chatHistory: messages.map((message) => {
- const isAI = message.created_by === 'colanode_ai';
- // Extract text using the node model's extractor for clean output
- const extracted = getNodeModel(message.attributes.type)?.extractNodeText(
- message.id,
- message.attributes
- );
- const text = extracted ? extracted.attributes : '';
- return new Document({
- pageContent: text || '',
- metadata: {
- id: message.id,
- type: 'message',
- createdAt: message.created_at,
- author: message.created_by,
- authorName: isAI ? 'Colanode AI' : 'User',
- },
- });
- }),
- };
-};
-
-const rerankContextDocuments = async (state: typeof ResponseState.State) => {
- const reranked = await rerankDocuments(
- state.contextDocuments.map((doc) => ({
- content: doc.pageContent,
- type: doc.metadata.type,
- sourceId: doc.metadata.id,
- })),
- state.rewrittenQuery
- );
- return { rerankedContext: reranked };
-};
-
-const selectRelevantDocuments = async (state: typeof ResponseState.State) => {
- const topDocs = selectTopContext(
- state.rerankedContext,
- 5,
- state.contextDocuments
- );
- return { topContext: topDocs };
-};
-
-const fetchWorkspaceDetails = async (workspaceId: string) => {
- return database
- .selectFrom('workspaces')
- .where('id', '=', workspaceId)
- .select(['name', 'id'])
- .executeTakeFirst();
-};
-
-const generateResponse = async (state: typeof ResponseState.State) => {
- const workspace = await fetchWorkspaceDetails(state.workspaceId);
-
- const formattedChatHistory = state.chatHistory
- .map((doc) => {
- const timestamp = doc.metadata.createdAt
- ? new Date(doc.metadata.createdAt).toLocaleString()
- : 'Unknown time';
- const authorName = doc.metadata.authorName || 'User';
- return `- [${timestamp}] ${authorName}: ${doc.pageContent}`;
- })
- .join('\n');
-
- const formattedContext = state.topContext
- .map((doc) => {
- const timestamp = doc.metadata?.createdAt
- ? new Date(doc.metadata.createdAt).toLocaleString()
- : 'Unknown time';
- const authorName = doc.metadata?.author || 'Unknown';
- let contextHeader = `Source ID: ${doc.metadata.id}\nAuthor: ${authorName}\nTime: ${timestamp}`;
- if (
- doc.metadata?.type === 'node' &&
- doc.metadata.nodeType === 'record' &&
- doc.metadata.parentContext?.name
- ) {
- contextHeader += `\nDatabase: ${doc.metadata.parentContext.name}`;
- }
- return `${contextHeader}\nContent: "${doc.pageContent}"\n`;
- })
- .join('\n');
-
- const result = await generateFinalAnswer({
- currentTimestamp: new Date().toISOString(),
- workspaceName: workspace?.name || state.workspaceId,
- userName: state.userDetails.name,
- userEmail: state.userDetails.email,
- formattedChatHistory,
- formattedMessages: '',
- formattedDocuments: formattedContext,
- question: state.userInput,
- });
-
- return {
- finalAnswer: result.answer,
- citations: result.citations,
- };
-};
-
-const fetchDatabaseContext = async (state: typeof ResponseState.State) => {
- const databases = await database
- .selectFrom('nodes as n')
- .innerJoin('collaborations as c', 'c.node_id', 'n.root_id')
- .where('n.type', '=', 'database')
- .where('n.workspace_id', '=', state.workspaceId)
- .where('c.collaborator_id', '=', state.userId)
- .where('c.deleted_at', 'is', null)
- .selectAll()
- .execute();
-
- const databaseContext = await Promise.all(
- databases.map(async (db) => {
- const dbNode = db as unknown as DatabaseNode;
- const sampleRecords = await recordsRetrievalService.retrieveByFilters(
- db.id,
- state.workspaceId,
- state.userId,
- {
- filters: [],
- sorts: [],
- page: 1,
- count: 5,
- }
- );
- const fields = dbNode.attributes.fields || {};
- const formattedFields = Object.entries(fields).reduce(
- (acc, [id, field]) => ({
- ...acc,
- [id]: {
- type: field.type,
- name: field.name,
- },
- }),
- {}
- );
- return {
- id: db.id,
- name: dbNode.attributes.name || 'Untitled Database',
- fields: formattedFields,
- sampleRecords,
- };
- })
- );
-
- return { databaseContext };
-};
-
-const generateDatabaseFilterAttributes = async (
- state: typeof ResponseState.State
-) => {
- if (state.intent === 'no_context' || !state.databaseContext.length) {
- return {
- databaseFilters: {
- shouldFilter: false,
- filters: [],
- },
- };
- }
-
- const filters = await generateDatabaseFilters({
- query: state.userInput,
- databases: state.databaseContext,
- });
-
- return { databaseFilters: filters };
-};
-
-const selectTopContext = (
- reranked: {
- index: number;
- score: number;
- type: string;
- sourceId: string;
- }[],
- max: number,
- contextDocuments: Document[]
-): Document[] => {
- if (reranked.length === 0) return [];
- const maxScore = Math.max(...reranked.map((item) => item.score));
- const threshold = maxScore * 0.5;
- return reranked
- .filter((item) => item.score >= threshold && item.score > 0)
- .sort((a, b) => b.score - a.score)
- .slice(0, max)
- .map((item) => {
- if (item.index >= 0 && item.index < contextDocuments.length) {
- const doc = contextDocuments[item.index];
- if (!doc) {
- return undefined;
- }
-
- if (
- doc.metadata.id === item.sourceId &&
- doc.metadata.type === item.type
- ) {
- return doc;
- }
- }
- return undefined;
- })
- .filter((doc): doc is Document => doc !== undefined);
-};
-
-// ---------------------------------------------------------------------
-// Response Chain Graph
-// ---------------------------------------------------------------------
-const assistantResponseChain = new StateGraph(ResponseState)
- .addNode('generateRewrittenQuery', generateRewrittenQuery)
- .addNode('fetchContextDocuments', fetchContextDocuments)
- .addNode('fetchChatHistory', fetchChatHistory)
- .addNode('rerankContextDocuments', rerankContextDocuments)
- .addNode('selectRelevantDocuments', selectRelevantDocuments)
- .addNode('generateResponse', generateResponse)
- .addNode('assessIntent', assessIntent)
- .addNode('generateNoContextResponse', generateNoContextResponse)
- .addNode('fetchDatabaseContext', fetchDatabaseContext)
- .addNode('generateDatabaseFilterAttributes', generateDatabaseFilterAttributes)
- .addEdge('__start__', 'fetchChatHistory')
- .addEdge('fetchChatHistory', 'assessIntent')
- .addConditionalEdges('assessIntent', (state) => {
- return state.intent === 'no_context'
- ? 'generateNoContextResponse'
- : 'generateRewrittenQuery';
- })
- .addEdge('generateRewrittenQuery', 'fetchContextDocuments')
- .addEdge('fetchContextDocuments', 'rerankContextDocuments')
- .addEdge('rerankContextDocuments', 'selectRelevantDocuments')
- .addEdge('selectRelevantDocuments', 'generateResponse')
- .addEdge('generateResponse', '__end__')
- .addEdge('generateNoContextResponse', '__end__')
- .compile();
-
-const langfuseCallback = new CallbackHandler({
- publicKey: configuration.ai.langfuse.publicKey,
- secretKey: configuration.ai.langfuse.secretKey,
- baseUrl: configuration.ai.langfuse.baseUrl,
-});
-
-// ---------------------------------------------------------------------
-// Main Job Handler
-// ---------------------------------------------------------------------
export const assistantResponseHandler: JobHandler<
AssistantResponseInput
> = async (input) => {
@@ -465,8 +48,8 @@ export const assistantResponseHandler: JobHandler<
const messageText = messageModel.extractNodeText(
message.id,
message.attributes
- );
- if (!messageText || !messageText.attributes) {
+ )?.attributes;
+ if (!messageText) {
return;
}
@@ -476,30 +59,32 @@ export const assistantResponseHandler: JobHandler<
.where('id', '=', message.created_by)
.selectAll()
.executeTakeFirst(),
- fetchWorkspaceDetails(workspaceId),
+ (async () => {
+ return database
+ .selectFrom('workspaces')
+ .where('id', '=', workspaceId)
+ .select(['name', 'id'])
+ .executeTakeFirst();
+ })(),
]);
+
if (!user || !workspace) {
return;
}
try {
- const chainResult = await assistantResponseChain.invoke(
- {
- userInput: messageText.attributes,
- workspaceId,
- userId: user.id,
- userDetails: {
- name: user.name || 'User',
- email: user.email || '[email protected]',
- },
- parentMessageId: message.parent_id || message.id,
- currentMessageId: message.id,
- originalMessage: message,
- intent: 'retrieve',
- databaseFilters: { shouldFilter: false, filters: [] },
+ const chainResult = await runAssistantResponseChain({
+ userInput: messageText,
+ workspaceId,
+ userId: user.id,
+ userDetails: {
+ name: user.name || 'User',
+ email: user.email || '[email protected]',
},
- { callbacks: [langfuseCallback] }
- );
+ parentMessageId: message.parent_id || message.id,
+ currentMessageId: message.id,
+ originalMessage: message,
+ });
await createAndPublishResponse(
chainResult.finalAnswer,
@@ -528,9 +113,9 @@ const createAndPublishResponse = async (
const id = generateId(IdType.Message);
const blockId = generateId(IdType.Block);
- const messageAttributes: NodeAttributes = {
- type: 'message',
- subtype: 'answer',
+ const messageAttributes: MessageAttributes = {
+ type: 'message' as const,
+ subtype: 'answer' as const,
parentId: originalMessage.parent_id,
content: {
[blockId]: {
@@ -559,28 +144,11 @@ const createAndPublishResponse = async (
},
};
- const createdMessage = await database
- .insertInto('nodes')
- .returningAll()
- .values({
- id,
- workspace_id: workspaceId,
- root_id: originalMessage.root_id,
- attributes: JSON.stringify(messageAttributes),
- created_by: 'colanode_ai',
- created_at: new Date(),
- revision: BigInt(0),
- })
- .executeTakeFirst();
-
- if (!createdMessage) {
- return;
- }
-
- eventBus.publish({
- type: 'node_created',
- nodeId: createdMessage.id,
- rootId: createdMessage.root_id,
- workspaceId: createdMessage.workspace_id,
+ await createNode({
+ nodeId: id,
+ workspaceId,
+ userId: 'colanode_ai',
+ rootId: originalMessage.root_id,
+ attributes: messageAttributes,
});
};
diff --git a/apps/server/src/jobs/embed-document.ts b/apps/server/src/jobs/embed-document.ts
index 1a5919cd..fe54a9f9 100644
--- a/apps/server/src/jobs/embed-document.ts
+++ b/apps/server/src/jobs/embed-document.ts
@@ -1,5 +1,5 @@
import { OpenAIEmbeddings } from '@langchain/openai';
-import { ChunkingService } from '@/services/chunking-service';
+import { chunkText } from '@/lib/chunking';
import { database } from '@/data/database';
import { configuration } from '@/lib/configuration';
import { CreateDocumentEmbedding } from '@/data/schema';
@@ -7,6 +7,7 @@ import { sql } from 'kysely';
import { fetchNode } from '@/lib/nodes';
import { extractDocumentText } from '@colanode/core';
import { getNodeModel } from '@colanode/core';
+import { enrichChunk } from '@/services/llm-service';
export type EmbedDocumentInput = {
type: 'embed_document';
@@ -58,11 +59,14 @@ export const embedDocumentHandler = async (input: {
return;
}
- const chunkingService = new ChunkingService();
- const textChunks = await chunkingService.chunkText(text, {
- type: 'document',
- node: node,
- });
+ const textChunks = await chunkText(
+ text,
+ {
+ type: 'document',
+ node: node,
+ },
+ enrichChunk
+ );
const embeddings = new OpenAIEmbeddings({
apiKey: configuration.ai.embedding.apiKey,
modelName: configuration.ai.embedding.modelName,
diff --git a/apps/server/src/jobs/embed-node.ts b/apps/server/src/jobs/embed-node.ts
index cfa4e406..d5e823c1 100644
--- a/apps/server/src/jobs/embed-node.ts
+++ b/apps/server/src/jobs/embed-node.ts
@@ -1,5 +1,5 @@
import { OpenAIEmbeddings } from '@langchain/openai';
-import { ChunkingService } from '@/services/chunking-service';
+import { chunkText } from '@/lib/chunking';
import { database } from '@/data/database';
import { configuration } from '@/lib/configuration';
import { CreateNodeEmbedding, SelectNode } from '@/data/schema';
@@ -7,6 +7,7 @@ import { sql } from 'kysely';
import { fetchNode } from '@/lib/nodes';
import { getNodeModel } from '@colanode/core';
import { FieldValue, DatabaseAttributes } from '@colanode/core';
+import { enrichChunk } from '@/services/llm-service';
export type EmbedNodeInput = {
type: 'embed_node';
@@ -121,11 +122,12 @@ export const embedNodeHandler = async (input: {
return;
}
- const chunkingService = new ChunkingService();
- const textChunks = await chunkingService.chunkText(text, {
- type: 'node',
- node,
- });
+ const textChunks = await chunkText(
+ text,
+ { type: 'node', node: node },
+ enrichChunk
+ );
+
const embeddings = new OpenAIEmbeddings({
apiKey: configuration.ai.embedding.apiKey,
modelName: configuration.ai.embedding.modelName,
diff --git a/apps/server/src/lib/assistant.ts b/apps/server/src/lib/assistant.ts
new file mode 100644
index 00000000..cdc6f3c8
--- /dev/null
+++ b/apps/server/src/lib/assistant.ts
@@ -0,0 +1,365 @@
+import { StateGraph } from '@langchain/langgraph';
+import { Document } from '@langchain/core/documents';
+import { database } from '@/data/database';
+import { configuration } from '@/lib/configuration';
+import { CallbackHandler } from 'langfuse-langchain';
+import { fetchNode } from '@/lib/nodes';
+import {
+ rewriteQuery,
+ assessUserIntent,
+ generateNoContextAnswer,
+ rerankDocuments,
+ generateFinalAnswer,
+ generateDatabaseFilters,
+} from '@/services/llm-service';
+import { nodeRetrievalService } from '@/services/node-retrieval-service';
+import { documentRetrievalService } from '@/services/document-retrieval-service';
+import { recordsRetrievalService } from '@/services/records-retrieval-service';
+import { getNodeModel } from '@colanode/core';
+import { AssistantChainState, ResponseState } from '@/types/assistant';
+
+/* ---------------------------------------------------------------------
+ Chain Node Functions
+--------------------------------------------------------------------- */
+
+async function generateRewrittenQuery(state: AssistantChainState) {
+ const rewritten = await rewriteQuery(state.userInput);
+ return { rewrittenQuery: rewritten };
+}
+
+async function assessIntent(state: AssistantChainState) {
+ const formattedChatHistory = state.chatHistory
+ .map((doc) => {
+ const timestamp = doc.metadata.createdAt
+ ? new Date(doc.metadata.createdAt).toLocaleString()
+ : 'Unknown time';
+ const authorName = doc.metadata.authorName || 'User';
+ return `- [${timestamp}] ${authorName}: ${doc.pageContent}`;
+ })
+ .join('\n');
+ const intent = await assessUserIntent(state.userInput, formattedChatHistory);
+ return { intent };
+}
+
+async function generateNoContextResponse(state: AssistantChainState) {
+ const formattedChatHistory = state.chatHistory
+ .map((doc) => {
+ const timestamp = doc.metadata.createdAt
+ ? new Date(doc.metadata.createdAt).toLocaleString()
+ : 'Unknown time';
+ const authorName = doc.metadata.authorName || 'User';
+ return `- [${timestamp}] ${authorName}: ${doc.pageContent}`;
+ })
+ .join('\n');
+ const answer = await generateNoContextAnswer(
+ state.userInput,
+ formattedChatHistory
+ );
+ return { finalAnswer: answer };
+}
+
+async function fetchContextDocuments(state: AssistantChainState) {
+ const [nodeResults, documentResults] = await Promise.all([
+ nodeRetrievalService.retrieve(
+ state.rewrittenQuery,
+ state.workspaceId,
+ state.userId
+ ),
+ documentRetrievalService.retrieve(
+ state.rewrittenQuery,
+ state.workspaceId,
+ state.userId
+ ),
+ ]);
+
+ let databaseResults: Document[] = [];
+ if (state.databaseFilters.shouldFilter) {
+ const filteredRecords = await Promise.all(
+ state.databaseFilters.filters.map(async (filter) => {
+ const records = await recordsRetrievalService.retrieveByFilters(
+ filter.databaseId,
+ state.workspaceId,
+ state.userId,
+ { filters: filter.filters, sorts: [], page: 1, count: 10 }
+ );
+ const dbNode = await fetchNode(filter.databaseId);
+ if (!dbNode || dbNode.type !== 'database') return [];
+ return records.map((record) => {
+ return new Document({
+ pageContent: `Database Record from ${
+ dbNode.attributes.type === 'database'
+ ? dbNode.attributes.name || 'Database'
+ : 'Database'
+ }:\n${Object.entries((record as any).attributes.fields || {})
+ .map(([key, value]) => `${key}: ${value}`)
+ .join('\n')}`,
+ metadata: {
+ id: record.id,
+ type: 'record',
+ createdAt: record.created_at,
+ author: record.created_by,
+ databaseId: filter.databaseId,
+ },
+ });
+ });
+ })
+ );
+ databaseResults = filteredRecords.flat();
+ }
+ return {
+ contextDocuments: [...nodeResults, ...documentResults, ...databaseResults],
+ };
+}
+
+async function fetchChatHistory(state: AssistantChainState) {
+ const messages = await database
+ .selectFrom('nodes')
+ .where('parent_id', '=', state.parentMessageId)
+ .where('type', '=', 'message')
+ .where('id', '!=', state.currentMessageId)
+ .where('workspace_id', '=', state.workspaceId)
+ .orderBy('created_at', 'asc')
+ .selectAll()
+ .execute();
+
+ return {
+ chatHistory: messages.map((message) => {
+ const isAI = message.created_by === 'colanode_ai';
+ const extracted = (message &&
+ message.attributes &&
+ getNodeModel(message.attributes.type)?.extractNodeText(
+ message.id,
+ message.attributes
+ )) || { attributes: '' };
+ const text = extracted.attributes;
+ return new Document({
+ pageContent: text || '',
+ metadata: {
+ id: message.id,
+ type: 'message',
+ createdAt: message.created_at,
+ author: message.created_by,
+ authorName: isAI ? 'Colanode AI' : 'User',
+ },
+ });
+ }),
+ };
+}
+
+async function rerankContextDocuments(state: AssistantChainState) {
+ const reranked = await rerankDocuments(
+ state.contextDocuments.map((doc) => ({
+ content: doc.pageContent,
+ type: doc.metadata.type,
+ sourceId: doc.metadata.id,
+ })),
+ state.rewrittenQuery
+ );
+ return { rerankedContext: reranked };
+}
+
+async function selectRelevantDocuments(state: AssistantChainState) {
+ const topDocs = selectTopContext(
+ state.rerankedContext,
+ 5,
+ state.contextDocuments
+ );
+ return { topContext: topDocs };
+}
+
+async function fetchWorkspaceDetails(workspaceId: string) {
+ return database
+ .selectFrom('workspaces')
+ .where('id', '=', workspaceId)
+ .select(['name', 'id'])
+ .executeTakeFirst();
+}
+
+async function generateResponse(state: AssistantChainState) {
+ const workspace = await fetchWorkspaceDetails(state.workspaceId);
+ const formattedChatHistory = state.chatHistory
+ .map((doc) => {
+ const timestamp = doc.metadata.createdAt
+ ? new Date(doc.metadata.createdAt).toLocaleString()
+ : 'Unknown time';
+ const authorName = doc.metadata.authorName || 'User';
+ return `- [${timestamp}] ${authorName}: ${doc.pageContent}`;
+ })
+ .join('\n');
+ const formattedContext = state.topContext
+ .map((doc) => {
+ const timestamp = doc.metadata?.createdAt
+ ? new Date(doc.metadata.createdAt).toLocaleString()
+ : 'Unknown time';
+ const authorName = doc.metadata?.author || 'Unknown';
+ let contextHeader = `Source ID: ${doc.metadata.id}\nAuthor: ${authorName}\nTime: ${timestamp}`;
+ if (
+ doc.metadata?.type === 'node' &&
+ doc.metadata.nodeType === 'record' &&
+ doc.metadata.parentContext?.name
+ ) {
+ contextHeader += `\nDatabase: ${doc.metadata.parentContext.name}`;
+ }
+ return `${contextHeader}\nContent: "${doc.pageContent}"\n`;
+ })
+ .join('\n');
+
+ const result = await generateFinalAnswer({
+ currentTimestamp: new Date().toISOString(),
+ workspaceName: workspace?.name || state.workspaceId,
+ userName: state.userDetails.name,
+ userEmail: state.userDetails.email,
+ formattedChatHistory,
+ formattedMessages: '',
+ formattedDocuments: formattedContext,
+ question: state.userInput,
+ });
+ return { finalAnswer: result.answer, citations: result.citations };
+}
+
+async function fetchDatabaseContext(state: AssistantChainState) {
+ const databases = await database
+ .selectFrom('nodes as n')
+ .innerJoin('collaborations as c', 'c.node_id', 'n.root_id')
+ .where('n.type', '=', 'database')
+ .where('n.workspace_id', '=', state.workspaceId)
+ .where('c.collaborator_id', '=', state.userId)
+ .where('c.deleted_at', 'is', null)
+ .selectAll()
+ .execute();
+
+ const databaseContext = await Promise.all(
+ databases.map(async (db) => {
+ const dbNode = db as any;
+ const sampleRecords = await recordsRetrievalService.retrieveByFilters(
+ db.id,
+ state.workspaceId,
+ state.userId,
+ { filters: [], sorts: [], page: 1, count: 5 }
+ );
+ const fields = dbNode.attributes.fields || {};
+ const formattedFields = Object.entries(fields).reduce(
+ (acc, [id, field]) => ({
+ ...acc,
+ [id]: {
+ type: (field as { type: string; name: string }).type,
+ name: (field as { type: string; name: string }).name,
+ },
+ }),
+ {}
+ );
+ return {
+ id: db.id,
+ name: dbNode.attributes.name || 'Untitled Database',
+ fields: formattedFields,
+ sampleRecords,
+ };
+ })
+ );
+ return { databaseContext };
+}
+
+async function generateDatabaseFilterAttributes(state: AssistantChainState) {
+ if (state.intent === 'no_context' || !state.databaseContext.length) {
+ return { databaseFilters: { shouldFilter: false, filters: [] } };
+ }
+ const filters = await generateDatabaseFilters({
+ query: state.userInput,
+ databases: state.databaseContext,
+ });
+ return { databaseFilters: filters };
+}
+
+function selectTopContext(
+ reranked: Array<{
+ index: number;
+ score: number;
+ type: string;
+ sourceId: string;
+ }>,
+ max: number,
+ contextDocuments: Document[]
+): Document[] {
+ if (reranked.length === 0) return [];
+ const maxScore = Math.max(...reranked.map((item) => item.score));
+ const threshold = maxScore * 0.5;
+ return reranked
+ .filter((item) => item.score >= threshold && item.score > 0)
+ .sort((a, b) => b.score - a.score)
+ .slice(0, max)
+ .map((item) => {
+ if (item.index >= 0 && item.index < contextDocuments.length) {
+ const doc = contextDocuments[item.index];
+ if (!doc) return undefined;
+ if (
+ doc.metadata.id === item.sourceId &&
+ doc.metadata.type === item.type
+ ) {
+ return doc;
+ }
+ }
+ return undefined;
+ })
+ .filter((doc): doc is Document => doc !== undefined);
+}
+
+/* ---------------------------------------------------------------------
+ Assistant response chain.
+--------------------------------------------------------------------- */
+const assistantResponseChain = new StateGraph(ResponseState)
+ .addNode('generateRewrittenQuery', generateRewrittenQuery)
+ .addNode('fetchContextDocuments', fetchContextDocuments)
+ .addNode('fetchChatHistory', fetchChatHistory)
+ .addNode('rerankContextDocuments', rerankContextDocuments)
+ .addNode('selectRelevantDocuments', selectRelevantDocuments)
+ .addNode('generateResponse', generateResponse)
+ .addNode('assessIntent', assessIntent)
+ .addNode('generateNoContextResponse', generateNoContextResponse)
+ .addNode('fetchDatabaseContext', fetchDatabaseContext)
+ .addNode('generateDatabaseFilterAttributes', generateDatabaseFilterAttributes)
+ .addEdge('__start__', 'fetchChatHistory')
+ .addEdge('fetchChatHistory', 'assessIntent')
+ .addConditionalEdges('assessIntent', (state) =>
+ state.intent === 'no_context'
+ ? 'generateNoContextResponse'
+ : 'generateRewrittenQuery'
+ )
+ .addEdge('generateRewrittenQuery', 'fetchContextDocuments')
+ .addEdge('fetchContextDocuments', 'rerankContextDocuments')
+ .addEdge('rerankContextDocuments', 'selectRelevantDocuments')
+ .addEdge('selectRelevantDocuments', 'generateResponse')
+ .addEdge('generateResponse', '__end__')
+ .addEdge('generateNoContextResponse', '__end__')
+ .compile();
+
+const langfuseCallback = new CallbackHandler({
+ publicKey: configuration.ai.langfuse.publicKey,
+ secretKey: configuration.ai.langfuse.secretKey,
+ baseUrl: configuration.ai.langfuse.baseUrl,
+});
+
+/* ---------------------------------------------------------------------
+ Core orchestration logic.
+--------------------------------------------------------------------- */
+export async function runAssistantResponseChain(input: {
+ userInput: string;
+ workspaceId: string;
+ userId: string;
+ userDetails: { name: string; email: string };
+ parentMessageId: string;
+ currentMessageId: string;
+ originalMessage: any;
+}): Promise<{
+ finalAnswer: string;
+ citations: Array<{ sourceId: string; quote: string }>;
+}> {
+ const result = await assistantResponseChain.invoke(
+ {
+ ...input,
+ intent: 'retrieve',
+ databaseFilters: { shouldFilter: false, filters: [] },
+ },
+ { callbacks: [langfuseCallback] }
+ );
+ return { finalAnswer: result.finalAnswer, citations: result.citations };
+}
diff --git a/apps/server/src/lib/chunking.ts b/apps/server/src/lib/chunking.ts
new file mode 100644
index 00000000..67ebed0e
--- /dev/null
+++ b/apps/server/src/lib/chunking.ts
@@ -0,0 +1,258 @@
+import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';
+import { configuration } from '@/lib/configuration';
+import { database } from '@/data/database';
+import { getNodeModel, FieldAttributes } from '@colanode/core';
+import type { SelectNode, SelectDocument } from '@/data/schema';
+import { getNodeContextPrompt, documentContextPrompt } from '@/lib/llm-prompts';
+import { BaseMetadata, NodeMetadata, DocumentMetadata } from '@/types/chunking';
+
+async function buildBaseMetadata(
+ node: SelectNode
+): Promise<BaseMetadata | undefined> {
+ const nodeModel = getNodeModel(node.attributes.type);
+ if (!nodeModel) return undefined;
+ const nodeText = nodeModel.extractNodeText(node.id, node.attributes);
+ if (!nodeText) return undefined;
+
+ const author = await database
+ .selectFrom('users')
+ .select(['id', 'name'])
+ .where('id', '=', node.created_by)
+ .executeTakeFirst();
+ const lastAuthor = node.updated_by
+ ? await database
+ .selectFrom('users')
+ .select(['id', 'name'])
+ .where('id', '=', node.updated_by)
+ .executeTakeFirst()
+ : undefined;
+ const workspace = await database
+ .selectFrom('workspaces')
+ .select(['id', 'name'])
+ .where('id', '=', node.workspace_id)
+ .executeTakeFirst();
+
+ return {
+ id: node.id,
+ name: nodeText.name ?? node.attributes.type,
+ createdAt: node.created_at,
+ createdBy: node.created_by,
+ updatedAt: node.updated_at,
+ updatedBy: node.updated_by,
+ author,
+ lastAuthor,
+ workspace,
+ };
+}
+
+async function buildParentContext(
+ node: SelectNode
+): Promise<BaseMetadata['parentContext'] | undefined> {
+ const parentNode = await database
+ .selectFrom('nodes')
+ .selectAll()
+ .where('id', '=', node.parent_id)
+ .executeTakeFirst();
+ if (!parentNode) return undefined;
+
+ const parentModel = getNodeModel(parentNode.attributes.type);
+ if (!parentModel) return undefined;
+ const parentText = parentModel.extractNodeText(
+ parentNode.id,
+ parentNode.attributes
+ );
+
+ const pathNodes = await database
+ .selectFrom('node_paths')
+ .innerJoin('nodes', 'nodes.id', 'node_paths.ancestor_id')
+ .select(['nodes.id', 'nodes.attributes'])
+ .where('node_paths.descendant_id', '=', node.id)
+ .orderBy('node_paths.level', 'desc')
+ .execute();
+ const path = pathNodes
+ .map((n) => {
+ const model = getNodeModel(n.attributes.type);
+ return model?.extractNodeText(n.id, n.attributes)?.name ?? '';
+ })
+ .join(' / ');
+ return {
+ id: parentNode.id,
+ type: parentNode.attributes.type,
+ name: parentText?.name ?? undefined,
+ path,
+ };
+}
+
+async function fetchCollaborators(
+ collaboratorIds: string[]
+): Promise<Array<{ id: string; name: string }>> {
+ if (!collaboratorIds.length) return [];
+ const collaborators = await database
+ .selectFrom('users')
+ .select(['id', 'name'])
+ .where('id', 'in', collaboratorIds)
+ .execute();
+ return collaborators.map((c) => ({ id: c.id, name: c.name }));
+}
+
+async function buildNodeMetadata(
+ node: SelectNode
+): Promise<NodeMetadata | undefined> {
+ const nodeModel = getNodeModel(node.attributes.type);
+ if (!nodeModel) return undefined;
+ const baseMetadata = await buildBaseMetadata(node);
+ if (!baseMetadata) return undefined;
+
+ if ('collaborators' in node.attributes) {
+ baseMetadata.collaborators = await fetchCollaborators(
+ Object.keys(node.attributes.collaborators)
+ );
+ }
+ if (node.parent_id) {
+ const parentContext = await buildParentContext(node);
+ if (parentContext) baseMetadata.parentContext = parentContext;
+ }
+ let fieldInfo: Record<string, { type: string; name: string }> | undefined;
+ if (node.attributes.type === 'record') {
+ const databaseNode = await database
+ .selectFrom('nodes')
+ .selectAll()
+ .where('id', '=', node.attributes.databaseId)
+ .executeTakeFirst();
+ if (databaseNode?.attributes.type === 'database') {
+ fieldInfo = Object.entries(databaseNode.attributes.fields).reduce(
+ (acc, [fieldId, field]) => ({
+ ...acc,
+ [fieldId]: {
+ type: (field as FieldAttributes).type,
+ name: (field as FieldAttributes).name,
+ },
+ }),
+ {} as Record<string, { type: string; name: string }>
+ );
+ }
+ }
+ return {
+ type: 'node',
+ nodeType: node.attributes.type,
+ fieldInfo,
+ ...baseMetadata,
+ };
+}
+
+async function buildDocumentMetadata(
+ document: SelectDocument,
+ node?: SelectNode
+): Promise<DocumentMetadata | undefined> {
+ if (!node) return undefined;
+ const baseMetadata: BaseMetadata = {
+ id: document.id,
+ createdAt: document.created_at,
+ createdBy: document.created_by,
+ };
+ const nodeModel = getNodeModel(node.attributes.type);
+ if (nodeModel) {
+ const nodeText = nodeModel.extractNodeText(node.id, node.attributes);
+ if (nodeText) baseMetadata.name = nodeText.name;
+ if (node.parent_id) {
+ const parentContext = await buildParentContext(node);
+ if (parentContext) baseMetadata.parentContext = parentContext;
+ }
+ }
+ return { type: 'document', ...baseMetadata };
+}
+
+async function fetchMetadata(metadata?: {
+ type: 'node' | 'document';
+ node: SelectNode;
+}): Promise<NodeMetadata | DocumentMetadata | undefined> {
+ if (!metadata) return undefined;
+ if (metadata.type === 'node') {
+ return buildNodeMetadata(metadata.node);
+ } else {
+ const document = await database
+ .selectFrom('documents')
+ .selectAll()
+ .where('id', '=', metadata.node.id)
+ .executeTakeFirst();
+ if (!document) return undefined;
+ return buildDocumentMetadata(document, metadata.node);
+ }
+}
+
+export async function prepareEnrichmentPrompt(
+ chunk: string,
+ fullText: string,
+ metadata: NodeMetadata | DocumentMetadata
+): Promise<{ prompt: string; baseVars: Record<string, string> }> {
+ const formatDate = (date?: Date) =>
+ date ? new Date(date).toUTCString() : 'unknown';
+
+ const baseVars: Record<string, string> = {
+ nodeType:
+ metadata.type === 'node'
+ ? (metadata as NodeMetadata).nodeType
+ : metadata.type,
+ name: metadata.name ?? 'Untitled',
+ createdAt: formatDate(metadata.createdAt),
+ updatedAt: metadata.updatedAt ? formatDate(metadata.updatedAt) : '',
+ authorName: metadata.author?.name ?? 'Unknown',
+ lastAuthorName: metadata.lastAuthor?.name ?? '',
+ path: metadata.parentContext?.path ?? '',
+ workspaceName: metadata.workspace?.name ?? 'Unknown Workspace',
+ fullText,
+ chunk,
+ };
+
+ let prompt: string;
+ if (metadata.type === 'node') {
+ prompt = getNodeContextPrompt(metadata as NodeMetadata);
+ } else {
+ prompt = documentContextPrompt.template.toString();
+ }
+ Object.entries(baseVars).forEach(([key, value]) => {
+ prompt = prompt.replace(new RegExp(`{${key}}`, 'g'), value);
+ });
+
+ return { prompt, baseVars };
+}
+
+export async function chunkText(
+ text: string,
+ metadata?: { type: 'node' | 'document'; node: SelectNode },
+ enrichFn?: (
+ prompt: string,
+ baseVars: Record<string, string>
+ ) => Promise<string>
+): Promise<string[]> {
+ const chunkSize = configuration.ai.chunking.defaultChunkSize;
+ const chunkOverlap = configuration.ai.chunking.defaultOverlap;
+ const splitter = new RecursiveCharacterTextSplitter({
+ chunkSize,
+ chunkOverlap,
+ });
+ const docs = await splitter.createDocuments([text]);
+ let chunks = docs
+ .map((doc) => doc.pageContent)
+ .filter((c) => c.trim().length > 5);
+
+ if (configuration.ai.chunking.enhanceWithContext && enrichFn && metadata) {
+ const enriched: string[] = [];
+ const enrichedMetadata = await fetchMetadata(metadata);
+ if (!enrichedMetadata) {
+ return chunks;
+ }
+ for (const chunk of chunks) {
+ const { prompt } = await prepareEnrichmentPrompt(
+ chunk,
+ text,
+ enrichedMetadata
+ );
+
+ const enrichment = await enrichFn(prompt, {});
+ enriched.push(enrichment + '\n\n' + chunk);
+ }
+ return enriched;
+ }
+ return chunks;
+}
diff --git a/apps/server/src/lib/llm-prompts.ts b/apps/server/src/lib/llm-prompts.ts
new file mode 100644
index 00000000..3a5ee9d0
--- /dev/null
+++ b/apps/server/src/lib/llm-prompts.ts
@@ -0,0 +1,199 @@
+import { PromptTemplate, ChatPromptTemplate } from '@langchain/core/prompts';
+
+// Existing prompt templates
+export const queryRewritePrompt = PromptTemplate.fromTemplate(
+ `You are an expert at rewriting queries for information retrieval within Colanode.
+
+Guidelines:
+1. Extract the core information need.
+2. Remove filler words.
+3. Preserve key technical terms and dates.
+
+Original query:
+{query}
+
+Rewrite the query and return only the rewritten version.`
+);
+
+export const summarizationPrompt = PromptTemplate.fromTemplate(
+ `Summarize the following text focusing on key points relevant to the user's query.
+If the text is short (<100 characters), return it as is.
+
+Text: {text}
+User Query: {query}`
+);
+
+export const rerankPrompt = PromptTemplate.fromTemplate(
+ `Re-rank the following list of documents by their relevance to the query.
+For each document, provide:
+- Original index (from input)
+- A relevance score between 0 and 1
+- Document type (node or document)
+- Source ID
+
+User query:
+{query}
+
+Documents:
+{context}
+
+Return an array of rankings in JSON format.`
+);
+
+export const answerPrompt = ChatPromptTemplate.fromTemplate(
+ `You are Colanode's AI assistant.
+
+CURRENT TIME: {currentTimestamp}
+WORKSPACE: {workspaceName}
+USER: {userName} ({userEmail})
+
+CONVERSATION HISTORY:
+{formattedChatHistory}
+
+RELEVANT CONTEXT:
+{formattedDocuments}
+
+USER QUERY:
+{question}
+
+Based solely on the conversation history and the relevant context above, provide a clear and professional answer to the user's query. In your answer, include exact quotes from the provided context that support your answer.
+
+Return your response as a JSON object with the following structure:
+{{
+ "answer": <your answer as a string>,
+ "citations": [
+ {{ "sourceId": <source id>, "quote": <exact quote from the context> }},
+ ...
+ ]
+}}`
+);
+
+export const intentRecognitionPrompt = PromptTemplate.fromTemplate(
+ `Determine if the following user query requires retrieving additional context.
+Return exactly one value: "retrieve" or "no_context".
+
+Conversation History:
+{formattedChatHistory}
+
+User Query:
+{question}`
+);
+
+export const noContextPrompt = PromptTemplate.fromTemplate(
+ `Answer the following query concisely using general knowledge, without retrieving additional context.
+
+Conversation History:
+{formattedChatHistory}
+
+User Query:
+{question}
+
+Return only the answer.`
+);
+
+export const databaseFilterPrompt = ChatPromptTemplate.fromTemplate(
+ `You are an expert at analyzing natural language queries and converting them into structured database filters.
+
+Available Databases:
+{databasesInfo}
+
+User Query:
+{query}
+
+Your task is to:
+1. Determine if this query is asking or makes sense to answer by filtering/searching databases
+2. If yes, generate appropriate filter attributes for each relevant database
+3. If no, return shouldFilter: false
+
+Return a JSON object with:
+- shouldFilter: boolean
+- filters: array of objects with:
+ - databaseId: string
+ - filters: array of DatabaseViewFilterAttributes
+
+Only include databases that are relevant to the query.
+For each filter, use the exact field IDs from the database schema.
+Use appropriate operators based on field types.
+
+Example Response:
+{{
+ "shouldFilter": true,
+ "filters": [
+ {{
+ "databaseId": "db1",
+ "filters": [
+ {{
+ "type": "field",
+ "fieldId": "field1",
+ "operator": "contains",
+ "value": "search term"
+ }}
+ ]
+ }}
+ ]
+}}
+
+Return a JSON object with:
+- shouldFilter: boolean
+- filters: array of objects with:
+ - databaseId: string
+ - filters: array of DatabaseViewFilterAttributes
+
+Only include databases that are relevant to the query.
+For each filter, use the exact field IDs from the database schema.
+Use appropriate operators based on field types.`
+);
+
+// --- New: Context Enrichment Prompt Templates ---
+
+/**
+ * Returns a plain string prompt to generate a contextual prefix for node content.
+ * This function embeds metadata into a prompt template.
+ */
+export function getNodeContextPrompt(metadata: any): string {
+ const metadataLines = [
+ metadata.name && `Name: ${metadata.name}`,
+ metadata.author?.name &&
+ `Created by: ${metadata.author.name} on ${new Date(metadata.createdAt).toUTCString()}`,
+ metadata.lastAuthor?.name &&
+ metadata.updatedAt &&
+ `Last updated: ${new Date(metadata.updatedAt).toUTCString()} by ${metadata.lastAuthor.name}`,
+ metadata.parentContext?.path && `Path: ${metadata.parentContext.path}`,
+ metadata.workspace?.name && `Workspace: ${metadata.workspace.name}`,
+ ]
+ .filter(Boolean)
+ .join('\n');
+
+ const contextHeader = `Given the following context about a ${metadata.nodeType === 'record' ? 'database record' : metadata.nodeType}:\n${metadataLines}\n`;
+ const contentSection =
+ metadata.nodeType === 'record'
+ ? `\n\nContent:\n{chunk}`
+ : `\n\nFull content:\n{fullText}\n\nCurrent chunk:\n{chunk}`;
+ const instructions = `\n\nGenerate a brief (50-100 tokens) contextual prefix that:
+1. Explains what this ${metadata.nodeType === 'record' ? 'record' : 'chunk'} represents.
+2. Highlights key details.
+3. Provides context to make the chunk understandable in isolation.`;
+ return `${contextHeader}${contentSection}${instructions}`;
+}
+
+export const documentContextPrompt = PromptTemplate.fromTemplate(
+ `Given the following context about a document:
+Type: {nodeType}
+Name: {name}
+Location: {path}
+Created by: {authorName} on {createdAt}
+Last updated: {updatedAt} by {lastAuthorName}
+Workspace: {workspaceName}
+
+Full content:
+{fullText}
+
+Current chunk:
+{chunk}
+
+Generate a brief (50-100 tokens) contextual prefix that:
+1. Explains what this document is.
+2. Provides relevant context about its location and purpose.
+3. Makes the chunk more understandable in isolation.
+Do not repeat the chunk content. Return only the contextual prefix.`
+);
diff --git a/apps/server/src/services/chunking-service.ts b/apps/server/src/services/chunking-service.ts
deleted file mode 100644
index a223618b..00000000
--- a/apps/server/src/services/chunking-service.ts
+++ /dev/null
@@ -1,303 +0,0 @@
-import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';
-import { configuration } from '@/lib/configuration';
-import { database } from '@/data/database';
-import { addContextToChunk } from '@/services/llm-service';
-import { getNodeModel, NodeType, FieldAttributes } from '@colanode/core';
-import type { SelectNode, SelectDocument } from '@/data/schema';
-
-type BaseMetadata = {
- id: string;
- name?: string | null;
- createdAt: Date;
- createdBy: string;
- updatedAt?: Date | null;
- updatedBy?: string | null;
- author?: { id: string; name: string };
- lastAuthor?: { id: string; name: string };
- parentContext?: {
- id: string;
- type: string;
- name?: string;
- path?: string;
- };
- collaborators?: Array<{ id: string; name: string }>;
- workspace?: { id: string; name: string };
-};
-
-export type NodeMetadata = BaseMetadata & {
- type: 'node';
- nodeType: NodeType;
- fieldInfo?: Record<string, { type: string; name: string }>;
-};
-
-export type DocumentMetadata = BaseMetadata & {
- type: 'document';
-};
-
-export type ChunkingMetadata = NodeMetadata | DocumentMetadata;
-
-export class ChunkingService {
- public async chunkText(
- text: string,
- metadata?: { type: 'node' | 'document'; node: SelectNode }
- ): Promise<string[]> {
- const chunkSize = configuration.ai.chunking.defaultChunkSize;
- const chunkOverlap = configuration.ai.chunking.defaultOverlap;
- const splitter = new RecursiveCharacterTextSplitter({
- chunkSize,
- chunkOverlap,
- });
-
- const docs = await splitter.createDocuments([text]);
- let chunks = docs.map((doc) => doc.pageContent);
- chunks = chunks.filter((c) => c.trim().length > 5); // We skip chunks that are 5 characters or less
-
- if (configuration.ai.chunking.enhanceWithContext) {
- const enrichedMetadata = await this.fetchMetadata(metadata);
- const enriched: string[] = [];
- for (const chunk of chunks) {
- const enrichedChunk = await addContextToChunk(
- chunk,
- text,
- enrichedMetadata
- );
- enriched.push(enrichedChunk);
- }
-
- return enriched;
- }
-
- return chunks;
- }
-
- private async fetchMetadata(metadata?: {
- type: 'node' | 'document';
- node: SelectNode;
- }): Promise<ChunkingMetadata | undefined> {
- if (!metadata) {
- return undefined;
- }
-
- if (metadata.type === 'node') {
- return this.buildNodeMetadata(metadata.node);
- } else {
- const document = await database
- .selectFrom('documents')
- .selectAll()
- .where('id', '=', metadata.node.id)
- .executeTakeFirst();
- if (!document) {
- return undefined;
- }
-
- return this.buildDocumentMetadata(document, metadata.node);
- }
- }
-
- private async buildNodeMetadata(
- node: SelectNode
- ): Promise<NodeMetadata | undefined> {
- const nodeModel = getNodeModel(node.attributes.type);
- if (!nodeModel) {
- return undefined;
- }
-
- const baseMetadata = await this.buildBaseMetadata(node);
- if (!baseMetadata) {
- return undefined;
- }
-
- // Add collaborators if the node type supports them
- if ('collaborators' in node.attributes) {
- baseMetadata.collaborators = await this.fetchCollaborators(
- Object.keys(node.attributes.collaborators)
- );
- }
-
- // Add parent context if the node has a parent
- if (node.parent_id) {
- const parentContext = await this.buildParentContext(node);
- if (parentContext) {
- baseMetadata.parentContext = parentContext;
- }
- }
-
- // For record nodes, fetch the database schema to provide field context
- let fieldInfo: Record<string, { type: string; name: string }> | undefined;
- if (node.attributes.type === 'record') {
- const databaseNode = await database
- .selectFrom('nodes')
- .selectAll()
- .where('id', '=', node.attributes.databaseId)
- .executeTakeFirst();
-
- if (databaseNode?.attributes.type === 'database') {
- fieldInfo = Object.entries(databaseNode.attributes.fields).reduce(
- (acc, [fieldId, field]) => ({
- ...acc,
- [fieldId]: {
- type: (field as FieldAttributes).type,
- name: (field as FieldAttributes).name,
- },
- }),
- {} as Record<string, { type: string; name: string }>
- );
- }
- }
-
- return {
- type: 'node',
- nodeType: node.attributes.type,
- fieldInfo,
- ...baseMetadata,
- };
- }
-
- private async buildDocumentMetadata(
- document: SelectDocument,
- node?: SelectNode
- ): Promise<DocumentMetadata | undefined> {
- let baseMetadata: BaseMetadata = {
- id: document.id,
- createdAt: document.created_at,
- createdBy: document.created_by,
- };
-
- if (!node) {
- return undefined;
- }
-
- const nodeModel = getNodeModel(node.attributes.type);
- if (nodeModel) {
- const nodeText = nodeModel.extractNodeText(node.id, node.attributes);
- if (nodeText) {
- baseMetadata.name = nodeText.name;
- }
-
- // Add parent context if available
- if (node.parent_id) {
- const parentContext = await this.buildParentContext(node);
- if (parentContext) {
- baseMetadata.parentContext = parentContext;
- }
- }
- }
-
- return {
- type: 'document',
- ...baseMetadata,
- };
- }
-
- private async buildBaseMetadata(
- node: SelectNode
- ): Promise<BaseMetadata | undefined> {
- const nodeModel = getNodeModel(node.attributes.type);
- if (!nodeModel) {
- return undefined;
- }
-
- const nodeText = nodeModel.extractNodeText(node.id, node.attributes);
- if (!nodeText) {
- return undefined;
- }
-
- const author = await database
- .selectFrom('users')
- .select(['id', 'name'])
- .where('id', '=', node.created_by)
- .executeTakeFirst();
-
- const lastAuthor = node.updated_by
- ? await database
- .selectFrom('users')
- .select(['id', 'name'])
- .where('id', '=', node.updated_by)
- .executeTakeFirst()
- : undefined;
-
- const workspace = await database
- .selectFrom('workspaces')
- .select(['id', 'name'])
- .where('id', '=', node.workspace_id)
- .executeTakeFirst();
-
- return {
- id: node.id,
- name: nodeText.name ?? node.attributes.type,
- createdAt: node.created_at,
- createdBy: node.created_by,
- updatedAt: node.updated_at,
- updatedBy: node.updated_by,
- author: author,
- lastAuthor: lastAuthor,
- workspace: workspace,
- };
- }
-
- private async buildParentContext(
- node: SelectNode
- ): Promise<BaseMetadata['parentContext'] | undefined> {
- const parentNode = await database
- .selectFrom('nodes')
- .selectAll()
- .where('id', '=', node.parent_id)
- .executeTakeFirst();
-
- if (!parentNode) {
- return undefined;
- }
-
- const parentModel = getNodeModel(parentNode.attributes.type);
- if (!parentModel) {
- return undefined;
- }
-
- const parentText = parentModel.extractNodeText(
- parentNode.id,
- parentNode.attributes
- );
-
- // Get the full path by traversing up the tree, ordered from root to leaf
- const pathNodes = await database
- .selectFrom('node_paths')
- .innerJoin('nodes', 'nodes.id', 'node_paths.ancestor_id')
- .select(['nodes.id', 'nodes.attributes'])
- .where('node_paths.descendant_id', '=', node.id)
- .orderBy('node_paths.level', 'desc')
- .execute();
-
- const path = pathNodes
- .map((n) => {
- const model = getNodeModel(n.attributes.type);
- return model?.extractNodeText(n.id, n.attributes)?.name ?? '';
- })
- .join(' / ');
-
- return {
- id: parentNode.id,
- type: parentNode.attributes.type,
- name: parentText?.name ?? undefined,
- path,
- };
- }
-
- private async fetchCollaborators(
- collaboratorIds: string[]
- ): Promise<Array<{ id: string; name: string }>> {
- if (!collaboratorIds.length) {
- return [];
- }
-
- const collaborators = await database
- .selectFrom('users')
- .select(['id', 'name'])
- .where('id', 'in', collaboratorIds)
- .execute();
-
- return collaborators.map((c) => ({
- id: c.id,
- name: c.name,
- }));
- }
-}
diff --git a/apps/server/src/services/document-retrieval-service.ts b/apps/server/src/services/document-retrieval-service.ts
index 63aded40..f6f50bcc 100644
--- a/apps/server/src/services/document-retrieval-service.ts
+++ b/apps/server/src/services/document-retrieval-service.ts
@@ -3,16 +3,7 @@ import { Document } from '@langchain/core/documents';
import { database } from '@/data/database';
import { configuration } from '@/lib/configuration';
import { sql } from 'kysely';
-
-type SearchResult = {
- id: string;
- text: string;
- score: number;
- type: 'semantic' | 'keyword';
- createdAt?: Date;
- chunkIndex: number;
-};
-
+import { SearchResult } from '@/types/retrieval';
export class DocumentRetrievalService {
private embeddings = new OpenAIEmbeddings({
apiKey: configuration.ai.embedding.apiKey,
diff --git a/apps/server/src/services/llm-service.ts b/apps/server/src/services/llm-service.ts
index 05954030..b5315e63 100644
--- a/apps/server/src/services/llm-service.ts
+++ b/apps/server/src/services/llm-service.ts
@@ -1,16 +1,28 @@
import { ChatOpenAI } from '@langchain/openai';
import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
-import { PromptTemplate, ChatPromptTemplate } from '@langchain/core/prompts';
import { StringOutputParser } from '@langchain/core/output_parsers';
-import { SystemMessage } from '@langchain/core/messages';
import { configuration } from '@/lib/configuration';
import { Document } from '@langchain/core/documents';
-import { z } from 'zod';
-import type {
- ChunkingMetadata,
- NodeMetadata,
-} from '@/services/chunking-service';
import { CallbackHandler } from 'langfuse-langchain';
+import {
+ rerankedDocumentsSchema,
+ RerankedDocuments,
+ citedAnswerSchema,
+ CitedAnswer,
+ databaseFilterSchema,
+ DatabaseFilterResult,
+} from '@/types/llm';
+
+import {
+ queryRewritePrompt,
+ summarizationPrompt,
+ rerankPrompt,
+ answerPrompt,
+ intentRecognitionPrompt,
+ noContextPrompt,
+ databaseFilterPrompt,
+} from '@/lib/llm-prompts';
+import { SystemMessage } from '@langchain/core/messages';
const langfuseCallback = new CallbackHandler({
publicKey: configuration.ai.langfuse.publicKey,
@@ -18,42 +30,7 @@ const langfuseCallback = new CallbackHandler({
baseUrl: configuration.ai.langfuse.baseUrl,
});
-const rerankedDocumentsSchema = z.object({
- rankings: z.array(
- z.object({
- index: z.number(),
- score: z.number().min(0).max(1),
- type: z.enum(['node', 'document']),
- sourceId: z.string(),
- })
- ),
-});
-type RerankedDocuments = z.infer<typeof rerankedDocumentsSchema>;
-
-const citedAnswerSchema = z.object({
- answer: z.string(),
- citations: z.array(
- z.object({
- sourceId: z.string(),
- quote: z.string(),
- })
- ),
-});
-type CitedAnswer = z.infer<typeof citedAnswerSchema>;
-
-const databaseFilterSchema = z.object({
- shouldFilter: z.boolean(),
- filters: z.array(
- z.object({
- databaseId: z.string(),
- filters: z.array(z.any()), // Using any for DatabaseViewFilterAttributes since it's complex
- })
- ),
-});
-
-type DatabaseFilterResult = z.infer<typeof databaseFilterSchema>;
-
-export const getChatModel = (
+const getChatModel = (
task: keyof typeof configuration.ai.models
): ChatOpenAI | ChatGoogleGenerativeAI => {
const modelConfig = configuration.ai.models[task];
@@ -82,151 +59,6 @@ export const getChatModel = (
}
};
-// Updated prompt templates using type-safe node types and context
-const queryRewritePrompt = PromptTemplate.fromTemplate(
- `You are an expert at rewriting queries for information retrieval within Colanode.
-
-Guidelines:
-1. Extract the core information need.
-2. Remove filler words.
-3. Preserve key technical terms and dates.
-
-Original query:
-{query}
-
-Rewrite the query and return only the rewritten version.`
-);
-
-const summarizationPrompt = PromptTemplate.fromTemplate(
- `Summarize the following text focusing on key points relevant to the user's query.
-If the text is short (<100 characters), return it as is.
-
-Text: {text}
-User Query: {query}`
-);
-
-const rerankPrompt = PromptTemplate.fromTemplate(
- `Re-rank the following list of documents by their relevance to the query.
-For each document, provide:
-- Original index (from input)
-- A relevance score between 0 and 1
-- Document type (node or document)
-- Source ID
-
-User query:
-{query}
-
-Documents:
-{context}
-
-Return an array of rankings in JSON format.`
-);
-
-const answerPrompt = ChatPromptTemplate.fromTemplate(
- `You are Colanode's AI assistant.
-
-CURRENT TIME: {currentTimestamp}
-WORKSPACE: {workspaceName}
-USER: {userName} ({userEmail})
-
-CONVERSATION HISTORY:
-{formattedChatHistory}
-
-RELEVANT CONTEXT:
-{formattedDocuments}
-
-USER QUERY:
-{question}
-
-Based solely on the conversation history and the relevant context above, provide a clear and professional answer to the user's query. In your answer, include exact quotes from the provided context that support your answer.
-
-Return your response as a JSON object with the following structure:
-{{
- "answer": <your answer as a string>,
- "citations": [
- {{ "sourceId": <source id>, "quote": <exact quote from the context> }},
- ...
- ]
-}}
-`
-);
-
-const intentRecognitionPrompt = PromptTemplate.fromTemplate(
- `Determine if the following user query requires retrieving additional context.
-Return exactly one value: "retrieve" or "no_context".
-
-Conversation History:
-{formattedChatHistory}
-
-User Query:
-{question}`
-);
-
-const noContextPrompt = PromptTemplate.fromTemplate(
- `Answer the following query concisely using general knowledge, without retrieving additional context.
-
-Conversation History:
-{formattedChatHistory}
-
-User Query:
-{question}
-
-Return only the answer.`
-);
-
-const databaseFilterPrompt = ChatPromptTemplate.fromTemplate(
- `You are an expert at analyzing natural language queries and converting them into structured database filters.
-
-Available Databases:
-{databasesInfo}
-
-User Query:
-{query}
-
-Your task is to:
-1. Determine if this query is asking or makes sense to answer by filtering/searching databases
-2. If yes, generate appropriate filter attributes for each relevant database
-3. If no, return shouldFilter: false
-
-Return a JSON object with:
-- shouldFilter: boolean
-- filters: array of objects with:
- - databaseId: string
- - filters: array of DatabaseViewFilterAttributes
-
-Only include databases that are relevant to the query.
-For each filter, use the exact field IDs from the database schema.
-Use appropriate operators based on field types.
-
-Example Response:
-{{
- "shouldFilter": true,
- "filters": [
- {{
- "databaseId": "db1",
- "filters": [
- {{
- "type": "field",
- "fieldId": "field1",
- "operator": "contains",
- "value": "search term"
- }}
- ]
- }}
- ]
-}}
-
-Return a JSON object with:
-- shouldFilter: boolean
-- filters: array of objects with:
- - databaseId: string
- - filters: array of DatabaseViewFilterAttributes
-
-Only include databases that are relevant to the query.
-For each filter, use the exact field IDs from the database schema.
-Use appropriate operators based on field types.`
-);
-
export const rewriteQuery = async (query: string): Promise<string> => {
const task = 'queryRewrite';
const model = getChatModel(task);
@@ -315,186 +147,6 @@ export const assessUserIntent = async (
: 'retrieve';
};
-const getNodeContextPrompt = (metadata: NodeMetadata): string => {
- const metadataLines = [
- metadata.name && `Name: ${metadata.name}`,
- metadata.author?.name &&
- `Created by: ${metadata.author.name} on ${metadata.createdAt}`,
- metadata.lastAuthor?.name &&
- metadata.updatedAt &&
- `Last updated: ${metadata.updatedAt} by ${metadata.lastAuthor.name}`,
- metadata.parentContext?.path && `Path: ${metadata.parentContext.path}`,
- metadata.workspace?.name && `Workspace: ${metadata.workspace.name}`,
- ].filter(Boolean);
-
- let additionalLines: string[] = [];
- const collaborators = metadata.collaborators
- ?.filter((c) => c.name)
- .map((c) => c.name)
- .join(', ');
-
- switch (metadata.nodeType) {
- case 'page':
- if (collaborators) {
- additionalLines.push(`Collaborators: ${collaborators}`);
- }
- break;
-
- case 'message':
- if (metadata.parentContext?.type || metadata.parentContext?.name) {
- additionalLines.push(
- `In: ${metadata.parentContext.type ?? 'channel'} "${metadata.parentContext.name ?? 'Untitled'}"`
- );
- }
- if (collaborators) {
- additionalLines.push(`Participants: ${collaborators}`);
- }
- break;
-
- case 'record':
- if (metadata.parentContext?.name) {
- additionalLines.push(`Database: ${metadata.parentContext.name}`);
- }
- if (metadata.fieldInfo) {
- const fieldDescriptions = Object.entries(metadata.fieldInfo)
- .map(([fieldId, info]) => `${info.name} (${info.type})`)
- .join(', ');
- additionalLines.push(`Fields: ${fieldDescriptions}`);
- }
- break;
- }
-
- const contextLines = [...metadataLines, ...additionalLines].filter(Boolean);
- const contextSection = `Given the following context about a ${metadata.nodeType === 'record' ? 'database record' : metadata.nodeType}:
-${contextLines.join('\n')}`;
-
- const contentSection =
- metadata.nodeType === 'record'
- ? `\n\nContent:\n{chunk}`
- : `\n\nFull content:\n{fullText}\n\nCurrent chunk:\n{chunk}`;
-
- const instructionsSection =
- metadata.nodeType === 'record'
- ? `\n\nGenerate a brief (50-100 tokens) contextual prefix that:
-1. Explains what this record represents
-2. Highlights key information from its fields
-3. Provides relevant context about which database it belongs to`
- : `\n\nGenerate a brief (50-100 tokens) contextual prefix that:
-1. Explains what this chunk is part of
-2. Provides relevant context from the metadata
-3. Makes the chunk more understandable in isolation`;
-
- return `${contextSection}${contentSection}${instructionsSection}\nDo not repeat the content. Return only the contextual prefix.`;
-};
-
-interface PromptVariables {
- nodeType: string;
- name: string;
- createdAt: string;
- updatedAt: string;
- authorName: string;
- lastAuthorName: string;
- path: string;
- workspaceName: string;
- fullText: string;
- chunk: string;
- [key: string]: string;
-}
-
-const documentContextPrompt = PromptTemplate.fromTemplate(
- `Given the following context about a document:
-Type: {nodeType}
-Name: {name}
-Location: {path}
-Created by: {authorName} on {createdAt}
-Last updated: {updatedAt} by {lastAuthorName}
-Workspace: {workspaceName}
-
-Full content:
-{fullText}
-
-Current chunk:
-{chunk}
-
-Generate a brief (50-100 tokens) contextual prefix that:
-1. Explains what this document is
-2. Provides relevant context about its location and purpose
-3. Makes the chunk more understandable in isolation
-Do not repeat the chunk content. Return only the contextual prefix.`
-);
-
-export const addContextToChunk = async (
- chunk: string,
- fullText: string,
- metadata?: ChunkingMetadata
-): Promise<string> => {
- try {
- if (!chunk || chunk.trim() === '') {
- return chunk;
- }
-
- if (!fullText || fullText.trim() === '') {
- return chunk;
- }
-
- if (!metadata) {
- return chunk;
- }
-
- const task = 'contextEnhancer';
- const model = getChatModel(task);
-
- let prompt: string;
- let promptVars: PromptVariables;
-
- const formatDate = (date?: Date) => {
- if (!date) return 'unknown';
- return new Date(date).toUTCString();
- };
-
- const baseVars = {
- nodeType: metadata.type === 'node' ? metadata.nodeType : metadata.type,
- name: metadata.name ?? 'Untitled',
- createdAt: formatDate(metadata.createdAt),
- updatedAt: metadata.updatedAt ? formatDate(metadata.updatedAt) : '',
- authorName: metadata.author?.name ?? 'Unknown',
- lastAuthorName: metadata.lastAuthor?.name ?? '',
- path: metadata.parentContext?.path ?? '',
- workspaceName: metadata.workspace?.name ?? 'Unknown Workspace',
- fullText,
- chunk,
- };
-
- //TODO: if metadata is empty, use a default context prompt for chunk
-
- if (metadata.type === 'node') {
- prompt = getNodeContextPrompt(metadata);
- promptVars = baseVars;
- } else {
- prompt = await documentContextPrompt.format(baseVars);
- promptVars = baseVars;
- }
-
- const formattedPrompt = Object.entries(promptVars).reduce(
- (acc, [key, value]) => acc.replace(`{${key}}`, value),
- prompt
- );
-
- const response = await model.invoke(
- [new SystemMessage({ content: formattedPrompt })],
- {
- callbacks: [langfuseCallback],
- }
- );
-
- const prefix = (response.content.toString() || '').trim();
- return prefix ? `${prefix}\n\n${chunk}` : chunk;
- } catch (err) {
- console.error('Error in addContextToChunk:', err);
- return chunk;
- }
-};
-
export const generateDatabaseFilters = async (args: {
query: string;
databases: Array<{
@@ -506,8 +158,6 @@ export const generateDatabaseFilters = async (args: {
}): Promise<DatabaseFilterResult> => {
const task = 'databaseFilter';
const model = getChatModel(task).withStructuredOutput(databaseFilterSchema);
-
- // Format database information for the prompt
const databasesInfo = args.databases
.map(
(db) => `
@@ -534,3 +184,17 @@ ${db.sampleRecords
.pipe(model)
.invoke({ query: args.query, databasesInfo });
};
+
+export async function enrichChunk(
+ prompt: string,
+ _baseVars: Record<string, string>
+): Promise<string> {
+ const task = 'contextEnhancer';
+ const model = getChatModel(task);
+ const messages = [new SystemMessage({ content: prompt })];
+ const response = await model.invoke(messages, {
+ callbacks: [langfuseCallback],
+ });
+
+ return (response.content.toString() || '').trim();
+}
diff --git a/apps/server/src/services/node-retrieval-service.ts b/apps/server/src/services/node-retrieval-service.ts
index e36c303e..84d1f740 100644
--- a/apps/server/src/services/node-retrieval-service.ts
+++ b/apps/server/src/services/node-retrieval-service.ts
@@ -3,15 +3,7 @@ import { Document } from '@langchain/core/documents';
import { database } from '@/data/database';
import { configuration } from '@/lib/configuration';
import { sql } from 'kysely';
-
-type SearchResult = {
- id: string;
- text: string;
- score: number;
- type: 'semantic' | 'keyword';
- createdAt?: Date;
- chunkIndex: number;
-};
+import { SearchResult } from '@/types/retrieval';
export class NodeRetrievalService {
private embeddings = new OpenAIEmbeddings({
diff --git a/apps/server/src/types/assistant.ts b/apps/server/src/types/assistant.ts
new file mode 100644
index 00000000..94977900
--- /dev/null
+++ b/apps/server/src/types/assistant.ts
@@ -0,0 +1,66 @@
+import { Document } from '@langchain/core/documents';
+import { Annotation } from '@langchain/langgraph';
+
+export type Citation = {
+ sourceId: string;
+ quote: string;
+};
+
+export type RerankedContextItem = {
+ index: number;
+ score: number;
+ type: string;
+ sourceId: string;
+};
+
+export type DatabaseFilter = {
+ databaseId: string;
+ filters: any[];
+};
+
+export type DatabaseFilters = {
+ shouldFilter: boolean;
+ filters: DatabaseFilter[];
+};
+
+export const ResponseState = Annotation.Root({
+ userInput: Annotation<string>(),
+ workspaceId: Annotation<string>(),
+ userId: Annotation<string>(),
+ userDetails: Annotation<{ name: string; email: string }>(),
+ parentMessageId: Annotation<string>(),
+ currentMessageId: Annotation<string>(),
+ rewrittenQuery: Annotation<string>(),
+ contextDocuments: Annotation<Document[]>(),
+ chatHistory: Annotation<Document[]>(),
+ rerankedContext: Annotation<
+ Array<{
+ index: number;
+ score: number;
+ type: string;
+ sourceId: string;
+ }>
+ >(),
+ topContext: Annotation<Document[]>(),
+ finalAnswer: Annotation<string>(),
+ citations: Annotation<Array<{ sourceId: string; quote: string }>>(),
+ originalMessage: Annotation<any>(),
+ intent: Annotation<'retrieve' | 'no_context'>(),
+ databaseContext: Annotation<
+ Array<{
+ id: string;
+ name: string;
+ fields: Record<string, { type: string; name: string }>;
+ sampleRecords: any[];
+ }>
+ >(),
+ databaseFilters: Annotation<{
+ shouldFilter: boolean;
+ filters: Array<{
+ databaseId: string;
+ filters: any[];
+ }>;
+ }>(),
+});
+
+export type AssistantChainState = typeof ResponseState.State;
diff --git a/apps/server/src/types/chunking.ts b/apps/server/src/types/chunking.ts
new file mode 100644
index 00000000..8dbfd2a6
--- /dev/null
+++ b/apps/server/src/types/chunking.ts
@@ -0,0 +1,28 @@
+export type BaseMetadata = {
+ id: string;
+ name?: string | null;
+ createdAt: Date;
+ createdBy: string;
+ updatedAt?: Date | null;
+ updatedBy?: string | null;
+ author?: { id: string; name: string };
+ lastAuthor?: { id: string; name: string };
+ parentContext?: {
+ id: string;
+ type: string;
+ name?: string;
+ path?: string;
+ };
+ collaborators?: Array<{ id: string; name: string }>;
+ workspace?: { id: string; name: string };
+};
+
+export type NodeMetadata = BaseMetadata & {
+ type: 'node';
+ nodeType: string;
+ fieldInfo?: Record<string, { type: string; name: string }>;
+};
+
+export type DocumentMetadata = BaseMetadata & {
+ type: 'document';
+};
diff --git a/apps/server/src/types/llm.ts b/apps/server/src/types/llm.ts
new file mode 100644
index 00000000..f7650c7f
--- /dev/null
+++ b/apps/server/src/types/llm.ts
@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+export const rerankedDocumentsSchema = z.object({
+ rankings: z.array(
+ z.object({
+ index: z.number(),
+ score: z.number().min(0).max(1),
+ type: z.enum(['node', 'document']),
+ sourceId: z.string(),
+ })
+ ),
+});
+export type RerankedDocuments = z.infer<typeof rerankedDocumentsSchema>;
+
+export const citedAnswerSchema = z.object({
+ answer: z.string(),
+ citations: z.array(
+ z.object({
+ sourceId: z.string(),
+ quote: z.string(),
+ })
+ ),
+});
+export type CitedAnswer = z.infer<typeof citedAnswerSchema>;
+
+export const databaseFilterSchema = z.object({
+ shouldFilter: z.boolean(),
+ filters: z.array(
+ z.object({
+ databaseId: z.string(),
+ filters: z.array(z.any()),
+ })
+ ),
+});
+export type DatabaseFilterResult = z.infer<typeof databaseFilterSchema>;
diff --git a/apps/server/src/types/retrieval.ts b/apps/server/src/types/retrieval.ts
new file mode 100644
index 00000000..b88452dc
--- /dev/null
+++ b/apps/server/src/types/retrieval.ts
@@ -0,0 +1,8 @@
+export type SearchResult = {
+ id: string;
+ text: string;
+ score: number;
+ type: 'semantic' | 'keyword';
+ createdAt?: Date;
+ chunkIndex: number;
+};