@dclbs/core

Framework-agnostic core utilities and types for integrating with Dclbs agents and LangGraph streaming.

Features

• 🔧 TypeScript Types - Complete type definitions for all SDK components
• 🌐 Framework Agnostic - Use with React, Vue, Angular, or vanilla JavaScript
• 🔌 Client Abstraction - StreamClient for advanced API interactions
• 🛠️ Utilities - Helper functions for state management and validation
• 📡 LangGraph Integration - Built on LangGraph SDK types

Installation

npm install @dclbs/core

Core Types

AgentConfig

Configuration for agent connections:

interface AgentConfig {
  assistantId: string; // Required: Assistant ID
  apiUrl?: string; // API endpoint URL
  apiKey?: string; // Authentication key
  headers?: Record<string, string>; // Custom headers
  metadata?: Record<string, any>; // Request metadata
}

StreamConfig

Configuration for streaming behavior:

interface StreamConfig {
  threadId?: string | null; // Thread ID (auto-create if null)
  streamMode?: ("values" | "messages-tuple" | "custom")[];
  streamResumable?: boolean; // Enable stream resumption
  onDisconnect?: "continue" | "error"; // Disconnect behavior
  messagesKey?: string; // State key for messages
  enableBranching?: boolean; // Enable conversation branching
  reconnectOnMount?: boolean; // Auto-reconnect on mount
}

StreamEvents

Event handlers for stream lifecycle:

interface StreamEvents {
  onThreadId?: (threadId: string) => void;
  onMessage?: (message: Message) => void;
  onError?: (error: Error) => void;
  onStateChange?: (state: StreamState) => void;
}

StreamState

Current state of the stream:

interface StreamState {
  messages: Message[];
  isLoading: boolean;
  error?: Error | null;
  threadId?: string | null;
  interrupt?: {
    value: any;
    when: string;
  } | null;
  [key: string]: any;
}

StreamClient

Advanced client for direct API interactions:

import { StreamClient, createStreamClient } from "@dclbs/core";

// Create client
const client = createStreamClient({
  assistantId: "your-assistant-id",
  apiKey: "your-api-key",
  apiUrl: "https://your-api-url.com",
  headers: {
    "Custom-Header": "value",
  },
});

// Access LangGraph client features
const threads = await client.threads.list();
const state = await client.threads.getState(threadId);

// Get assistant info
console.log(client.assistantId);
console.log(client.metadata);

StreamClient API

class StreamClient extends Client {
  constructor(config: AgentConfig);

  // Properties
  get assistantId(): string;
  get metadata(): Record<string, any> | undefined;

  // Inherited from LangGraph Client
  threads: ThreadsClient;
  runs: RunsClient;
  assistants: AssistantsClient;
  // ... all LangGraph SDK methods
}

Utilities

State Management

import {
  getMessagesFromState,
  createOptimisticUpdate,
  isValidThreadId,
  isValidAssistantId,
} from "@dclbs/core";

// Extract messages from state
const messages = getMessagesFromState(state, "messages");

// Create optimistic state updates
const optimisticState = createOptimisticUpdate(currentState, {
  messages: [...currentState.messages, newMessage],
});

// Validation helpers
if (isValidThreadId(threadId)) {
  // Thread ID is valid
}

if (isValidAssistantId(assistantId)) {
  // Assistant ID is valid
}

Re-exported Types

All LangGraph SDK types are re-exported for convenience:

import type {
  Assistant,
  Config,
  Message,
  Run,
  StreamMode,
  Thread,
  ToolMessage,
  ThreadState,
  Checkpoint,
  Interrupt,
  Metadata,
} from "@dclbs/core";

Usage Examples

Basic Client Usage

import { createStreamClient } from "@dclbs/core";

const client = createStreamClient({
  assistantId: "your-assistant-id",
  apiKey: "your-api-key",
});

// Create a thread
const thread = await client.threads.create();

// Send a message and stream response
const stream = client.runs.stream(thread.thread_id, client.assistantId, {
  input: { messages: [{ role: "human", content: "Hello!" }] },
  streamMode: ["values", "messages-tuple"],
});

for await (const { event, data } of stream) {
  if (event === "values") {
    console.log("New values:", data);
  }
  if (event === "messages") {
    console.log("New messages:", data);
  }
}

State Utilities

import { getMessagesFromState, createOptimisticUpdate } from "@dclbs/core";

// Working with state
const currentState = {
  messages: [
    { role: "human", content: "Hello", id: "1" },
    { role: "assistant", content: "Hi there!", id: "2" },
  ],
  context: { userId: "user-123" },
};

// Extract messages
const messages = getMessagesFromState(currentState, "messages");
console.log(messages); // Array of messages

// Create optimistic update
const optimisticState = createOptimisticUpdate(currentState, {
  messages: [
    ...currentState.messages,
    {
      role: "human",
      content: "How are you?",
      id: "temp-3",
    },
  ],
});

Type-safe Configuration

import type { AgentConfig, StreamConfig, StreamEvents } from "@dclbs/core";

const agentConfig: AgentConfig = {
  assistantId: "your-assistant-id",
  apiUrl: "https://api.example.com",
  apiKey: "your-api-key",
  headers: {
    Authorization: "Bearer token",
    "X-Custom-Header": "value",
  },
  metadata: {
    userId: "user-123",
    sessionId: "session-456",
  },
};

const streamConfig: StreamConfig = {
  threadId: null, // Auto-create
  streamMode: ["values", "messages-tuple"],
  messagesKey: "messages",
  enableBranching: false,
  reconnectOnMount: true,
};

const streamEvents: StreamEvents = {
  onThreadId: (id) => console.log("Thread ID:", id),
  onMessage: (msg) => console.log("New message:", msg),
  onError: (err) => console.error("Stream error:", err),
  onStateChange: (state) => console.log("State changed:", state),
};

Framework Integration

This package is framework-agnostic and can be used with any JavaScript framework:

Vanilla JavaScript

import { createStreamClient } from "@dclbs/core";

const client = createStreamClient({
  assistantId: "your-assistant-id",
  apiKey: "your-api-key",
});

async function sendMessage(content) {
  const thread = await client.threads.create();
  const stream = client.runs.stream(thread.thread_id, client.assistantId, {
    input: { messages: [{ role: "human", content }] },
  });

  for await (const { event, data } of stream) {
    if (event === "values") {
      updateUI(data);
    }
  }
}

Vue.js

<script setup>
import { ref, onMounted } from "vue";
import { createStreamClient } from "@dclbs/core";

const messages = ref([]);
const client = createStreamClient({
  assistantId: "your-assistant-id",
  apiKey: "your-api-key",
});

async function sendMessage(content) {
  const stream = client.runs.stream(threadId.value, client.assistantId, {
    input: { messages: [{ role: "human", content }] },
  });

  for await (const { event, data } of stream) {
    if (event === "values") {
      messages.value = data.messages || [];
    }
  }
}
</script>

Angular

import { Injectable } from "@angular/core";
import { createStreamClient, type StreamClient } from "@dclbs/core";

@Injectable({
  providedIn: "root",
})
export class ChatService {
  private client: StreamClient;

  constructor() {
    this.client = createStreamClient({
      assistantId: "your-assistant-id",
      apiKey: "your-api-key",
    });
  }

  async sendMessage(content: string, threadId: string) {
    const stream = this.client.runs.stream(threadId, this.client.assistantId, {
      input: { messages: [{ role: "human", content }] },
    });

    const messages = [];
    for await (const { event, data } of stream) {
      if (event === "values") {
        messages.push(...(data.messages || []));
      }
    }
    return messages;
  }
}

API Reference

Functions

• createStreamClient(config: AgentConfig): StreamClient - Create a new stream client
• getMessagesFromState(state: any, messagesKey: string): Message[] - Extract messages from state
• createOptimisticUpdate(currentState: any, optimisticValues: any): any - Create optimistic state update
• isValidThreadId(threadId: string | null | undefined): boolean - Validate thread ID
• isValidAssistantId(assistantId: string | null | undefined): boolean - Validate assistant ID

Classes

• StreamClient - Extended LangGraph client with additional functionality

Type Exports

All TypeScript types are exported for use in your applications. See the individual type definitions above for details.

Dependencies

• @langchain/langgraph-sdk - Core LangGraph SDK
• @langchain/core - LangChain core types (peer dependency)

License

MIT