Type Safety

Learn how to leverage TypeScript for type-safe AI applications with the CG SDK.

Full TypeScript Support

The CG SDK is written in TypeScript and provides comprehensive type definitions for all API methods, parameters, and responses.

Type-Safe Client

import { CGateClient, CGateClientOptions } from '@cognipeer/cgate-sdk';

// Options are fully typed
const options: CGateClientOptions = {
  apiKey: 'your-api-key',
  baseURL: 'https://api.cognipeer.com',
  timeout: 30000,
  maxRetries: 3,
};

const client = new CGateClient(options);

Chat Completions

Request Types

import type {
  ChatCompletionRequest,
  ChatMessage,
  ChatCompletionResponse,
} from '@cognipeer/cgate-sdk';

// Messages are strongly typed
const messages: ChatMessage[] = [
  {
    role: 'system',
    content: 'You are a helpful assistant.',
  },
  {
    role: 'user',
    content: 'Hello!',
  },
];

// Request parameters are validated
const request: ChatCompletionRequest = {
  model: 'gpt-4',
  messages,
  temperature: 0.7,
  max_tokens: 150,
};

// Response type is inferred
const response = await client.chat.completions.create(request);
// response: ChatCompletionResponse

// Access properties with autocomplete
const content = response.choices[0].message.content;

Message Types

import type {
  SystemMessage,
  UserMessage,
  AssistantMessage,
  ToolMessage,
} from '@cognipeer/cgate-sdk';

const systemMsg: SystemMessage = {
  role: 'system',
  content: 'You are a helpful assistant.',
  name: 'system', // optional
};

const userMsg: UserMessage = {
  role: 'user',
  content: 'What is TypeScript?',
};

const assistantMsg: AssistantMessage = {
  role: 'assistant',
  content: 'TypeScript is a typed superset of JavaScript.',
  tool_calls: [], // optional
};

const toolMsg: ToolMessage = {
  role: 'tool',
  content: 'Tool result',
  tool_call_id: 'call_123',
};

Streaming Types

import type {
  ChatCompletionChunk,
  ChatChoiceDelta,
} from '@cognipeer/cgate-sdk';

const stream = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: true,
});

// Type-safe iteration
for await (const chunk of stream) {
  // chunk: ChatCompletionChunk
  const delta: ChatChoiceDelta = chunk.choices[0];
  const content: string | undefined = delta.delta.content;
  
  if (content) {
    process.stdout.write(content);
  }
}

Embeddings

import type {
  EmbeddingRequest,
  EmbeddingResponse,
  EmbeddingObject,
} from '@cognipeer/cgate-sdk';

const request: EmbeddingRequest = {
  model: 'text-embedding-3-small',
  input: 'Hello world',
  encoding_format: 'float', // Type-safe enum
};

const response = await client.embeddings.create(request);
// response: EmbeddingResponse

const embeddings: number[] = response.data[0].embedding;

Vector Operations

import type {
  VectorProvider,
  VectorIndex,
  VectorUpsertRequest,
  VectorQueryRequest,
  VectorMatch,
} from '@cognipeer/cgate-sdk';

// Provider type is constrained
const provider: VectorProvider = 'pinecone'; // or 'chroma', 'qdrant', 'weaviate'

// Index creation is type-safe
const index: VectorIndex = await client.vectors.createIndex({
  name: 'my-index',
  provider: 'pinecone',
  dimension: 1536,
  metric: 'cosine', // Type-safe enum
});

// Upsert with typed vectors
const upsertRequest: VectorUpsertRequest = {
  index: index.id,
  vectors: [
    {
      id: 'vec1',
      values: new Array(1536).fill(0),
      metadata: {
        text: 'Hello',
        timestamp: Date.now(),
      },
    },
  ],
};

await client.vectors.upsert(upsertRequest);

// Query with type-safe results
const queryRequest: VectorQueryRequest = {
  index: index.id,
  vector: new Array(1536).fill(0),
  topK: 5,
  includeMetadata: true,
};

const results = await client.vectors.query(queryRequest);

results.matches.forEach((match: VectorMatch) => {
  console.log(`Score: ${match.score}`);
  console.log(`Metadata:`, match.metadata);
});

Tool Definitions

import type {
  Tool,
  FunctionDefinition,
  ToolCall,
} from '@cognipeer/cgate-sdk';

// Type-safe tool definition
const tool: Tool = {
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get weather information',
    parameters: {
      type: 'object',
      properties: {
        location: {
          type: 'string',
          description: 'City name',
        },
        unit: {
          type: 'string',
          enum: ['celsius', 'fahrenheit'],
        },
      },
      required: ['location'],
    },
  },
};

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Weather in Paris?' }],
  tools: [tool],
});

// Type-safe tool call handling
const message = response.choices[0].message;

if (message.tool_calls && message.tool_calls.length > 0) {
  message.tool_calls.forEach((toolCall: ToolCall) => {
    console.log('Function:', toolCall.function.name);
    console.log('Arguments:', toolCall.function.arguments);
  });
}

File Operations

import type {
  FileUploadRequest,
  FileObject,
  FileListResponse,
} from '@cognipeer/cgate-sdk';

// Type-safe file upload
const uploadRequest: FileUploadRequest = {
  file: fileBuffer,
  filename: 'document.pdf',
  purpose: 'assistants', // Type-safe enum
};

const file: FileObject = await client.files.upload(uploadRequest);

// Status is type-checked
if (file.status === 'processed') {
  console.log('Markdown:', file.markdown);
}

Tracing

import type {
  Trace,
  TraceEvent,
  TraceWithEvents,
} from '@cognipeer/cgate-sdk';

// Type-safe trace creation
const trace: Trace = await client.tracing.createTrace({
  name: 'My Agent',
  metadata: {
    userId: 'user_123',
  },
  tags: ['production'],
});

// Type-safe event types
await client.tracing.addEvent(trace.id, {
  type: 'llm', // or 'tool', 'agent', 'custom'
  name: 'chat-completion',
  input: { prompt: 'Hello' },
  output: { response: 'Hi!' },
  metadata: {
    tokens: 15,
  },
});

Error Handling

import { CGateError } from '@cognipeer/cgate-sdk';

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  // Type guard for CGateError
  if (error instanceof CGateError) {
    // Properties are typed
    const status: number | undefined = error.status;
    const code: string | undefined = error.code;
    const message: string = error.message;
    
    console.error(`Error ${status}: ${message}`);
  } else {
    // Handle other error types
    console.error('Unexpected error:', error);
  }
}

Custom Type Guards

Create reusable type guards:

import type { AssistantMessage } from '@cognipeer/cgate-sdk';

// Check if message has tool calls
function hasToolCalls(message: AssistantMessage): boolean {
  return Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
}

// Check if response is streaming
function isStreaming(
  response: ChatCompletionResponse | AsyncIterable<ChatCompletionChunk>
): response is AsyncIterable<ChatCompletionChunk> {
  return Symbol.asyncIterator in response;
}

// Usage
const response = await client.chat.completions.create({...});

if (isStreaming(response)) {
  for await (const chunk of response) {
    // Handle stream
  }
} else {
  // Handle regular response
}

Generic Helper Functions

Build type-safe helper functions:

import type {
  ChatMessage,
  ChatCompletionResponse,
} from '@cognipeer/cgate-sdk';

async function chat(
  messages: ChatMessage[],
  options?: {
    model?: string;
    temperature?: number;
    maxTokens?: number;
  }
): Promise<string> {
  const response = await client.chat.completions.create({
    model: options?.model || 'gpt-4',
    messages,
    temperature: options?.temperature ?? 0.7,
    max_tokens: options?.maxTokens,
  });

  return response.choices[0].message.content || '';
}

// Type-safe usage
const result = await chat(
  [{ role: 'user', content: 'Hello' }],
  { temperature: 0.5 }
);

Exporting Types

All types are exported for use in your application:

import type {
  // Client
  CGateClient,
  CGateClientOptions,
  
  // Chat
  ChatCompletionRequest,
  ChatCompletionResponse,
  ChatMessage,
  ChatCompletionChunk,
  
  // Embeddings
  EmbeddingRequest,
  EmbeddingResponse,
  EmbeddingObject,
  
  // Vectors
  VectorProvider,
  VectorIndex,
  VectorMatch,
  
  // Files
  FileObject,
  FileUploadRequest,
  
  // Tracing
  Trace,
  TraceEvent,
  
  // Errors
  CGateError,
  
  // Tools
  Tool,
  ToolCall,
  FunctionDefinition,
} from '@cognipeer/cgate-sdk';

IDE Support

The SDK provides excellent IDE support:

• Autocomplete: All methods and parameters
• Type Hints: Inline documentation
• Error Detection: Catch type errors before runtime
• Refactoring: Safe renaming and restructuring

Best Practices

1. Use Type Imports: Import types with import type for better tree-shaking
2. Define Interfaces: Create interfaces for your application-specific types
3. Type Guards: Use type guards for runtime type checking
4. Strict Mode: Enable strict: true in tsconfig.json
5. Avoid any: Leverage the provided types instead of using any

Example: Type-Safe RAG System

import type {
  ChatMessage,
  EmbeddingResponse,
  VectorMatch,
} from '@cognipeer/cgate-sdk';

interface Document {
  id: string;
  text: string;
  embedding: number[];
}

async function retrievalAugmentedGeneration(
  query: string,
  documents: Document[]
): Promise<string> {
  // 1. Embed query (type-safe)
  const queryEmbedding: EmbeddingResponse = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: query,
  });

  // 2. Search vectors (type-safe)
  const results = await client.vectors.query({
    index: 'documents',
    vector: queryEmbedding.data[0].embedding,
    topK: 3,
  });

  // 3. Build context (type-safe)
  const context = results.matches
    .map((match: VectorMatch) => match.metadata?.text)
    .filter(Boolean)
    .join('\n\n');

  // 4. Generate response (type-safe)
  const messages: ChatMessage[] = [
    {
      role: 'system',
      content: `Answer based on this context:\n\n${context}`,
    },
    {
      role: 'user',
      content: query,
    },
  ];

  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages,
  });

  return response.choices[0].message.content || '';
}

Related

• API Types - Complete type reference
• Client API - Type-safe client usage
• Error Handling - Type-safe error handling