Knowledge & Context

ContractSpec provides first-class support for knowledge management, enabling semantic search, RAG (Retrieval-Augmented Generation), and context-aware decision-making. Knowledge is organized into typed spaces with different trust levels and access controls.

Why knowledge matters

Modern applications need to:

• Understand context - Access relevant information to make informed decisions
• Learn from history - Use past interactions to improve future responses
• Trust sources - Distinguish between authoritative and reference information
• Scale knowledge - Handle growing amounts of documentation and data
• Maintain privacy - Keep tenant knowledge isolated and secure

Knowledge architecture

ContractSpec's knowledge system has three main components:

type KnowledgeSpaceSpec = {
  id: string;
  label: string;
  category: KnowledgeCategory;
  storageStrategy: "vector" | "search" | "hybrid";
  indexProvider: string;  // e.g., "qdrant"
  retentionPolicy: { days?: number };
  intendedAudience: "agents" | "humans" | "admin-only";
};

type KnowledgeSourceConfig = {
  id: string;
  tenantId: string;
  spaceId: string;
  kind: "uploaded-document" | "url" | "email" 
        | "notion" | "database-query" | "raw-text";
  location: string;
  syncPolicy: { interval?: string; webhook?: boolean };
  lastSyncedAt?: string;
};

How it works

Knowledge flows through ContractSpec in four stages:

1. Define spaces - Create KnowledgeSpaceSpec for each logical domain (e.g., "Product Canon", "Support FAQ")
2. Configure sources - Tenants connect their data sources (Notion, Gmail, uploads, etc.)
3. Sync & index - Sources are synced, chunked, and indexed in vector databases
4. Query & retrieve - Workflows and agents perform semantic search to find relevant context

Use cases

Integration with workflows

Knowledge spaces are consumed by workflows through standard capabilities:

import { defineWorkflow } from '@lssm/lib.contracts';
import { OpenAIEmbeddings, VectorSearch, OpenAIChat } from './specs';

export const AnswerSupportQuestion = defineWorkflow({
  meta: {
    name: 'support.answerQuestion',
    version: 1,
    description: 'Answer support questions using RAG',
    owners: ['team-support'],
    tags: ['ai', 'support'],
    stability: 'stable',
  },
  steps: [
    {
      id: 'embed-question',
      operation: OpenAIEmbeddings,
      inputs: (ctx, input) => ({
        text: input.question,
      }),
    },
    {
      id: 'search-knowledge',
      operation: VectorSearch,
      inputs: (ctx, input, steps) => ({
        collection: 'product-canon', // KnowledgeSpace
        vector: steps['embed-question'].output.embedding,
        limit: 5,
      }),
    },
    {
      id: 'generate-answer',
      operation: OpenAIChat,
      inputs: (ctx, input, steps) => ({
        messages: [
          { role: 'system', content: 'Answer using the provided context' },
          { 
            role: 'user', 
            content: `Context: ${steps['search-knowledge'].output.results}\nQuestion: ${input.question}`
          },
        ],
      }),
    },
  ],
});

Real-world examples

See how different applications use knowledge spaces: