chatroutes

v0.3.2

Published

3 months ago

Official TypeScript/JavaScript SDK for ChatRoutes - Conversation Branching Platform

0High
0Medium
0Low

afzalfarooqui

chatroutes ai conversation branching llm gpt claude chat sdk typescript

ChatRoutes SDK

🧩 Build branching, forkable AI conversations directly into your app — using the same APIs that power chatroutes.com.

ChatRoutes SDK is a developer-first gateway to the ChatRoutes ecosystem, giving you infrastructure access to:

✅ Authentication via API keys (from user dashboard) ✅ Conversation management (create, list, delete) ✅ Branching / forking / merging conversation paths ✅ Parallel responses across multiple AI models ✅ Streaming responses (real-time SSE) ✅ Conversation trees (visualize and navigate branches) ✅ Checkpoints (save and restore conversation state) ✅ AutoBranch (AI-powered branch detection and suggestions)

Perfect for:

🔬 Researchers comparing LLM responses
✍️ Writers exploring narrative branches
💻 Developers building chat UIs or AI copilots

Keywords: LLM, branching AI, OpenAI, Claude, conversation tree, chat SDK, AI developer tools, research assistant, multi-model AI

🔑 Get an API Key

To use ChatRoutes SDK, sign up at chatroutes.com and obtain your API key from the Dashboard → API Keys section.

const client = new ChatRoutesClient({ apiKey: 'cr_prod_sk_xxx' });

🎮 Try it live: ChatRoutes Demo

🚀 Quick Start

🎮 Try It Now! Interactive Demos

Want to explore all features? We have comprehensive demo scripts similar to Jupyter notebooks:

# Quick Start Demo (5-10 minutes) - Learn the basics
npx tsx examples/demo-quickstart.ts

# Complete Features Demo (20-30 minutes) - See everything!
npx tsx examples/demo-complete.ts

Features demonstrated:

✅ Basic conversation management
✅ Real-time streaming responses
✅ Branching with different creativity levels (temperature)
✅ Checkpoint system for token optimization
✅ Message immutability & cryptographic hashing
✅ Tree visualization (DAG structure)
✅ Multi-model comparison (GPT-5 vs Claude)

Perfect for sales demos, presentations, and comprehensive exploration!

Installation

npm install chatroutes

Basic Usage

import { ChatRoutesClient } from 'chatroutes';

const client = new ChatRoutesClient({
  apiKey: 'your-api-key'
});

// Create a conversation
const conversation = await client.conversations.create({
  title: 'My AI Chat',
  model: 'gpt-5'
});

// Send a message
const response = await client.messages.send(conversation.id, {
  content: 'Hello! Explain quantum computing.',
  model: 'gpt-5'
});

console.log(response.message.content);
console.log('Model:', response.model);
console.log('Usage:', response.usage);

📋 Prerequisites

You must have a ChatRoutes account to use this SDK:

Register for free at chatroutes.com
Generate an API key from your dashboard
Use the API key to initialize the SDK

⚠️ API key required - No guest mode available. All users must register for a free account to obtain an API key.

🎯 Features

✅ Full TypeScript Support (types included) ✅ Streaming Responses (SSE) ✅ Conversation Branching (create and manage branches) ✅ Parallel Responses (multi-model testing) ✅ Checkpoints (manual context management) ✅ AutoBranch (AI-powered branch suggestions) ✅ Auto Retry + Backoff ✅ Modern ESM/CJS builds ✅ Node.js + Browser Support

📚 Core Concepts

🔐 Authentication

const client = new ChatRoutesClient({
  apiKey: 'cr_prod_sk_your_key_here'
});

💬 Conversations

// Create a conversation
const conv = await client.conversations.create({
  title: 'Project Planning',
  model: 'gpt-5'
});

// List conversations
const { data: conversations } = await client.conversations.list({
  page: 1,
  limit: 10
});

// Get a conversation
const conversation = await client.conversations.get(conv.id);

// Update
await client.conversations.update(conv.id, {
  title: 'Updated Title'
});

// Delete
await client.conversations.delete(conv.id);

🧠 Messages

// Send a message (blocking)
const response = await client.messages.send(conversationId, {
  content: 'Explain machine learning',
  model: 'gpt-5',
  temperature: 0.7,
  maxTokens: 1000
});

console.log(response.message.content);
console.log('Usage:', response.usage);

// Stream responses (real-time)
await client.messages.stream(
  conversationId,
  { content: 'Write a long article about AI', model: 'gpt-5' },
  (chunk) => {
    if (chunk.type === 'content' && chunk.content) {
      process.stdout.write(chunk.content);
    }
  },
  (complete) => {
    console.log('\n\nStreaming complete!');
    console.log('Full response:', complete.message.content);
    console.log('Tokens:', complete.usage.totalTokens);
  }
);

🌿 Branches

// List all branches in a conversation
const branches = await client.branches.list(conversationId);

// Fork a conversation from a specific message
const newBranch = await client.branches.fork(conversationId, {
  forkPointMessageId: messageId,
  title: 'Alternative Approach',
  contextMode: 'FULL' // FULL, PARTIAL, MINIMAL
});

// Create a new branch manually
const branch = await client.branches.create(conversationId, {
  title: 'Technical Deep Dive',
  baseNodeId: messageId,
  contextMode: 'FULL'
});

// Get branch messages
const messages = await client.branches.getMessages(conversationId, branch.id);

// Send a message to a specific branch
const response = await client.branches.sendMessage(conversationId, branch.id, {
  content: 'Your message here',
  model: 'gpt-5'
});

// Merge a branch
const mergedBranch = await client.branches.merge(conversationId, branch.id);

🌳 Conversation Tree

const tree = await client.conversations.getTree(conversationId);

console.log('Conversation:', tree.conversation.title);
console.log('Total branches:', tree.branches.length);
console.log('Main branch:', tree.mainBranch.title);

📌 Checkpoints

const branches = await client.branches.list(conversationId);
const mainBranch = branches.find(b => b.isMain);

const checkpoint = await client.checkpoints.create(
  conversationId,
  mainBranch.id,
  messageId
);

console.log('Checkpoint created:', checkpoint.id);
console.log('Summary:', checkpoint.summary);
console.log('Token count:', checkpoint.tokenCount);

const checkpoints = await client.checkpoints.list(conversationId);

const recreated = await client.checkpoints.recreate(checkpoint.id);

await client.checkpoints.delete(checkpoint.id);

Message responses include checkpoint metadata:

const response = await client.messages.send(conversationId, {
  content: 'Your message here',
  model: 'gpt-5'
});

console.log('Context truncated:', response.message.metadata?.contextTruncated);
console.log('Checkpoint used:', response.message.metadata?.checkpointUsed);
console.log('Prompt tokens:', response.message.metadata?.promptTokens);
console.log('Context message count:', response.message.metadata?.contextMessageCount);

🤖 AutoBranch (AI-Powered Branch Detection)

AutoBranch uses AI to automatically detect branching opportunities in conversation text, making it easy to identify multiple topics or intents.

const health = await client.autobranch.health();
console.log('AutoBranch status:', health.status);

const text = 'I need help with billing and also have a technical question about the API';

const suggestions = await client.autobranch.suggestBranches({
  text: text,
  suggestionsCount: 3,
  hybridDetection: false,
  threshold: 0.7
});

console.log(`Found ${suggestions.suggestions.length} branch suggestions`);
console.log(`Detection method: ${suggestions.metadata.detectionMethod}`);

for (const suggestion of suggestions.suggestions) {
  console.log(`\nBranch: ${suggestion.title}`);
  console.log(`Description: ${suggestion.description}`);
  console.log(`Trigger: "${suggestion.triggerText}"`);
  console.log(`Confidence: ${(suggestion.confidence * 100).toFixed(1)}%`);
  console.log(`Divergence: ${suggestion.estimatedDivergence}`);
  console.log(`Position: chars ${suggestion.branchPoint.start}-${suggestion.branchPoint.end}`);
}

Convenience method:

const suggestions = await client.autobranch.analyzeText(
  'Can you explain machine learning and also help me debug this Python code?',
  {
    suggestionsCount: 5,
    threshold: 0.6
  }
);

Detection Modes:

hybridDetection: false - Fast pattern-based detection (default)
hybridDetection: true - Enhanced with LLM analysis

Use Cases:

Customer support routing (billing vs technical questions)
Multi-intent detection in user messages
Smart conversation topic separation
Quality assurance and conversation analysis
Automated topic classification

Parameters:

text (required) - The text to analyze
suggestionsCount (1-10, default: 3) - Number of suggestions to return
hybridDetection (boolean, default: false) - Enable LLM enhancement
threshold (0.0-1.0, default: 0.7) - Minimum confidence score
llmModel (optional) - Specify LLM model for hybrid mode
llmProvider (optional) - LLM provider ('openai', 'anthropic')
llmApiKey (optional) - Alternative LLM credentials

See examples/autobranch-example.ts for comprehensive examples.

🔧 Configuration

const client = new ChatRoutesClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.chatroutes.com',  // optional
  timeout: 30000,                         // default 30s
  retryAttempts: 3,                       // default 3
  retryDelay: 1000                        // ms between retries
});

❌ Error Handling

import {
  ChatRoutesError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  NetworkError
} from 'chatroutes';

try {
  const conv = await client.conversations.get('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.details);
  } else if (error instanceof NotFoundError) {
    console.error('Conversation not found');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, retry after:', error.retryAfter);
  } else {
    console.error('Unknown error:', error);
  }
}

📚 Examples

Full working examples are available in the examples/ directory:

🎯 Interactive Demos (Recommended!)

demo-quickstart.ts - 5-10 minute quick start guide (like Jupyter notebook)
demo-complete.ts - 20-30 minute complete feature demonstration

📝 Focused Examples

basic-chat.ts - Simple conversation creation and messaging
streaming-chat.ts - Real-time SSE streaming responses
branching.ts - Fork conversations and explore alternatives
model-comparison.ts - Compare GPT-5 vs Claude side-by-side
checkpoint-example.ts - Create and manage checkpoints

Run Examples Locally

# Clone the repository
git clone https://github.com/chatroutes/chatroutes-sdk.git
cd chatroutes-sdk

# Install dependencies
npm install

# Set up your API key
cp .env.example .env
# Edit .env and add your API key

# Run interactive demos (recommended for learning!)
npx tsx examples/demo-quickstart.ts       # Quick start guide
npx tsx examples/demo-complete.ts         # Complete feature demo

# Run focused examples
npx tsx examples/basic-chat.ts
npx tsx examples/streaming-chat.ts
npx tsx examples/branching.ts
npx tsx examples/model-comparison.ts
npx tsx examples/checkpoint-example.ts

Alternative: Set API key via environment variable:

export CHATROUTES_API_KEY="your-api-key-here"  # Unix/macOS
$env:CHATROUTES_API_KEY="your-api-key-here"    # Windows PowerShell

Complete Chat Demo

import { ChatRoutesClient } from 'chatroutes';

async function main() {
  const client = new ChatRoutesClient({
    apiKey: process.env.CHATROUTES_API_KEY
  });

  const conv = await client.conversations.create({
    title: 'Demo',
    model: 'gpt-5'
  });

  const msg = await client.messages.send(conv.id, {
    content: 'Explain branching AI'
  });

  console.log('Response:', msg.message.content);

  const branch = await client.branches.fork(conv.id, {
    forkPointMessageId: msg.message.id,
    title: 'Alternative version'
  });

  console.log('Created branch:', branch.title);
}

main().catch(console.error);

🌐 Environment Support

Node.js ≥ 18.x
Modern browsers with Fetch API
TypeScript ≥ 5.x

🔐 Security & Terms

Use of this SDK requires adherence to ChatRoutes Terms of Service.
ChatRoutes and its parent company Mednosis LLC reserve the right to revoke API access for misuse or abuse.

🤝 Contributing

See CONTRIBUTING.md for contribution guidelines.
Report bugs → GitHub Issues
Discuss ideas → Discussions
Community → r/ChatRoutes

🔗 Links

🌐 Website
🧰 API Documentation
💻 GitHub
🐛 Issues
✉️ Support

📊 Status

| Property | Value | |----------|-------| | Version | 0.3.1 (Beta) | | Status | Early Access | | License | MIT | | Maintainer | Afzal Farooqui | | Organization | ChatRoutes |