graphlit-client 1.0.20250610010 → 1.0.20250611002

package/README.md

@@ -1,197 +1,238 @@
-# Node.js Client for Graphlit Platform
+# Graphlit TypeScript Client SDK
 
-## Overview
+[![npm version](https://badge.fury.io/js/graphlit-client.svg)](https://badge.fury.io/js/graphlit-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-The Graphlit Client for Node.js enables straightforward interactions with the Graphlit API, allowing developers to execute GraphQL queries and mutations against the Graphlit service. This document outlines the setup process and provides examples of using the client, including advanced streaming capabilities with real-time token delivery and tool calling support.
+The official TypeScript/JavaScript SDK for the [Graphlit Platform](https://www.graphlit.com) - build AI-powered applications with knowledge retrieval in minutes.
+
+## 🚀 What is Graphlit?
+
+Graphlit is a cloud platform that handles the complex parts of building AI applications:
+- **Ingest any content** - PDFs, websites, audio, video, and more
+- **Chat with your data** - Using RAG (Retrieval-Augmented Generation)
+- **Extract insights** - Summaries, entities, and metadata
+- **Build knowledge graphs** - Automatically connect related information
+
+## ✨ What's New in v1.1.0
+- **Real-time streaming** - Watch AI responses appear word-by-word
+- **Tool calling** - Let AI execute functions and retrieve data
+- **Better performance** - Native integration with OpenAI, Anthropic, and Google
+
+## 📋 Table of Contents
+- [Quick Start](#quick-start)
+- [Basic Examples](#basic-examples)
+- [Common Use Cases](#common-use-cases)
+- [API Reference](#api-reference)
+- [Support](#support)
 
 ## Quick Start
 
-Get up and running in 2 minutes:
+Get started in 2 minutes:
 
 ```bash
-# Install the client
+# Install the SDK
 npm install graphlit-client
 
-# Set your credentials (get from https://portal.graphlit.dev)
+# Set your credentials (get free account at https://portal.graphlit.dev)
 export GRAPHLIT_ORGANIZATION_ID=your_org_id
 export GRAPHLIT_ENVIRONMENT_ID=your_env_id  
 export GRAPHLIT_JWT_SECRET=your_secret
 ```
 
 ```typescript
-import { Graphlit } from "graphlit-client";
+import { Graphlit, Types } from "graphlit-client";
 
-const client = new Graphlit();
+const client = new Graphlit(); // Uses env vars: GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID, GRAPHLIT_JWT_SECRET
+
+// First, create a specification (or use your project default)
+const spec = await client.createSpecification({
+  name: "Assistant",
+  type: Types.SpecificationTypes.Completion,
+  serviceType: Types.ModelServiceTypes.OpenAi,
+  openAI: {
+    model: Types.OpenAiModels.Gpt4O_128K
+  }
+});
 
-// Stream a conversation
+// Start chatting with AI
 await client.streamAgent(
-  "Hello! Tell me a joke",
+  "Tell me a joke",
   (event) => {
     if (event.type === "message_update") {
       console.log(event.message.message);
     }
-  }
+  },
+  undefined, // conversationId (optional)
+  { id: spec.createSpecification.id } // specification
 );
 ```
 
-## Prerequisites
-
-Before you begin, ensure you have the following:
-
-- Node.js installed on your system (recommended version 18.x or higher).
-- An active account on the [Graphlit Platform](https://portal.graphlit.dev) with access to the API settings dashboard.
-
 ## Installation
 
-### Basic Installation
-
-To install the Graphlit Client with core functionality:
-
 ```bash
 npm install graphlit-client
 ```
 
-or
-
-```bash
-yarn add graphlit-client
-```
+### Want Real-time Streaming?
 
-### Streaming Support (Optional)
+Install the LLM SDK for streaming responses:
 
-For real-time token streaming with LLM conversations, install the desired LLM clients as additional dependencies:
+```bash
+# For OpenAI streaming
+npm install openai
 
-**All streaming providers:**
+# For Anthropic streaming  
+npm install @anthropic-ai/sdk
 
-```bash
-npm install graphlit-client openai @anthropic-ai/sdk @google/generative-ai
+# For Google streaming
+npm install @google/generative-ai
 ```
 
-**Selective streaming providers:**
-
-```bash
-# OpenAI streaming only
-npm install graphlit-client openai
+## Setting Up
 
-# Anthropic streaming only
-npm install graphlit-client @anthropic-ai/sdk
+Create a `.env` file in your project:
 
-# Google streaming only
-npm install graphlit-client @google/generative-ai
+```env
+GRAPHLIT_ORGANIZATION_ID=your_org_id
+GRAPHLIT_ENVIRONMENT_ID=your_env_id
+GRAPHLIT_JWT_SECRET=your_secret
+
+# Optional: For streaming
+OPENAI_API_KEY=your_key
+ANTHROPIC_API_KEY=your_key
+GOOGLE_API_KEY=your_key
 ```
 
-> **Note:** The LLM client libraries are optional peer dependencies. The base Graphlit client works perfectly without them, but streaming functionality will gracefully fall back to regular API calls.
-
-## Configuration
+## Basic Examples
 
-The Graphlit Client supports environment variables to be set for authentication and configuration:
+### 1. Chat with AI
 
-- `GRAPHLIT_ENVIRONMENT_ID`: Your environment ID.
-- `GRAPHLIT_ORGANIZATION_ID`: Your organization ID.
-- `GRAPHLIT_JWT_SECRET`: Your JWT secret for signing the JWT token.
+Simple conversation with streaming responses:
 
-Alternately, you can pass these values with the constructor of the Graphlit client.
-
-You can find these values in the API settings dashboard on the [Graphlit Platform](https://portal.graphlit.dev).
+```typescript
+import { Graphlit, Types } from "graphlit-client";
 
-### Setting Environment Variables
+const client = new Graphlit(); // Uses env vars: GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID, GRAPHLIT_JWT_SECRET
 
-To set these environment variables on your system, you can place them in a `.env` file at the root of your project:
+// Create a specification for the AI model
+const spec = await client.createSpecification({
+  name: "Assistant",
+  type: Types.SpecificationTypes.Completion,
+  serviceType: Types.ModelServiceTypes.OpenAi,
+  openAI: {
+    model: Types.OpenAiModels.Gpt4O_128K,
+    temperature: 0.7
+  }
+});
 
-```env
-GRAPHLIT_ENVIRONMENT_ID=your_environment_id_value
-GRAPHLIT_ORGANIZATION_ID=your_organization_id_value
-GRAPHLIT_JWT_SECRET=your_jwt_secret_value
-
-# Optional: For native streaming support
-OPENAI_API_KEY=your_openai_api_key
-ANTHROPIC_API_KEY=your_anthropic_api_key
-GOOGLE_API_KEY=your_google_api_key
+// Chat with streaming
+await client.streamAgent(
+  "What can you help me with?",
+  (event) => {
+    if (event.type === "message_update") {
+      // Print the AI's response as it streams
+      process.stdout.write(event.message.message);
+    }
+  },
+  undefined, // conversationId
+  { id: spec.createSpecification.id } // specification
+);
 ```
 
-## Usage
+### 2. Ingest and Query Documents
 
-### Basic Client Usage
+Upload a PDF and ask questions about it:
 
 ```typescript
-import { Graphlit } from "graphlit-client";
+import { Graphlit, Types } from "graphlit-client";
 
-const client = new Graphlit();
+const client = new Graphlit(); // Uses env vars: GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID, GRAPHLIT_JWT_SECRET
 
-// Create a content
-const contentResponse = await client.ingestUri({
-  uri: "https://example.com/document.pdf",
-  name: "My Document"
-});
-
-// Query contents
-const contents = await client.queryContents({
-  filter: { name: { contains: "Document" } }
+// Create a specification
+const spec = await client.createSpecification({
+  name: "Document Q&A",
+  type: Types.SpecificationTypes.Completion,
+  serviceType: Types.ModelServiceTypes.OpenAi,
+  openAI: {
+    model: Types.OpenAiModels.Gpt4O_128K
+  }
 });
-```
 
-### Streaming Conversations with streamAgent
+// Upload a PDF synchronously to ensure it's ready
+const content = await client.ingestUri(
+  "https://arxiv.org/pdf/1706.03762.pdf", // Attention Is All You Need paper
+  "AI Research Paper", // name
+  undefined, // id
+  true // isSynchronous - waits for processing
+);
 
-The `streamAgent` method provides real-time streaming responses with automatic UI event handling. It supports both native SDK streaming (when LLM clients are configured) and fallback streaming through the Graphlit API:
+console.log(`✅ Uploaded: ${content.ingestUri.id}`);
 
-```typescript
-import { Graphlit, AgentStreamEvent } from "graphlit-client";
+// Wait a moment for content to be fully indexed
+await new Promise(resolve => setTimeout(resolve, 5000));
 
-const client = new Graphlit();
+// Create a conversation that filters to this specific content
+const conversation = await client.createConversation({
+  filter: { contents: [{ id: content.ingestUri.id }] }
+});
 
-// Basic streaming conversation
+// Ask questions about the PDF
 await client.streamAgent(
-  "Tell me about artificial intelligence",
-  (event: AgentStreamEvent) => {
-    switch (event.type) {
-      case "conversation_started":
-        console.log(`Started conversation: ${event.conversationId}`);
-        break;
-        
-      case "message_update":
-        // Complete message text - automatically accumulated
-        console.log(`Assistant: ${event.message.message}`);
-        break;
-        
-      case "conversation_completed":
-        console.log(`Completed: ${event.message.message}`);
-        break;
-        
-      case "error":
-        console.error(`Error: ${event.error.message}`);
-        break;
+  "What are the key innovations in this paper?",
+  (event) => {
+    if (event.type === "message_update") {
+      console.log(event.message.message);
     }
-  }
+  },
+  conversation.createConversation.id, // conversationId with content filter
+  { id: spec.createSpecification.id } // specification
 );
 ```
 
-### Non-Streaming Conversations with promptAgent
+### 3. Web Scraping
 
-For simpler use cases without streaming, use `promptAgent`:
+Extract content from websites:
 
 ```typescript
-const result = await client.promptAgent(
-  "What's the weather like?",
-  undefined, // conversationId (creates new)
-  { id: "your-specification-id" }, // specification
-  tools, // optional tools array
-  toolHandlers, // optional tool handlers
-  { timeout: 30000 } // optional timeout
+// Scrape a website (waits for processing to complete)
+const webpage = await client.ingestUri(
+  "https://en.wikipedia.org/wiki/Artificial_intelligence", // uri
+  "AI Wikipedia Page", // name
+  undefined, // id
+  true // isSynchronous
+);
+
+// Wait for content to be indexed
+await new Promise(resolve => setTimeout(resolve, 5000));
+
+// Create a conversation filtered to this content
+const conversation = await client.createConversation({
+  filter: { contents: [{ id: webpage.ingestUri.id }] }
+});
+
+// Ask about the specific content
+const response = await client.promptAgent(
+  "Summarize the key points about AI from this Wikipedia page",
+  conversation.createConversation.id, // conversationId with filter
+  { id: spec.createSpecification.id } // specification (create one as shown above)
 );
 
-console.log(result.message); // Complete response
-console.log(result.conversationId); // For continuing the conversation
+console.log(response.message);
 ```
 
-### Tool Calling with Streaming
+### 4. Tool Calling
 
-`streamAgent` supports sophisticated tool calling with automatic execution and parallel processing:
+Let AI call functions to get real-time data:
 
 ```typescript
-// Define tools
-const tools = [{
+import { Graphlit, Types } from "graphlit-client";
+
+const client = new Graphlit(); // Uses env vars: GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID, GRAPHLIT_JWT_SECRET
+
+// Define a weather tool
+const weatherTool: Types.ToolDefinitionInput = {
   name: "get_weather",
-  description: "Get weather for a city",
+  description: "Get current weather for a city",
   schema: JSON.stringify({
     type: "object",
     properties: {
@@ -199,544 +240,377 @@ const tools = [{
     },
     required: ["city"]
   })
-}];
+};
 
-// Tool handlers
+// Tool implementation
 const toolHandlers = {
   get_weather: async (args: { city: string }) => {
-    // Your weather API call here
-    return { temperature: 72, condition: "sunny" };
+    // Call your weather API here
+    return { 
+      city: args.city,
+      temperature: 72, 
+      condition: "sunny" 
+    };
   }
 };
 
-// Stream with tools
+// Create a specification for tool calling
+const spec = await client.createSpecification({
+  name: "Weather Assistant",
+  type: Types.SpecificationTypes.Completion,
+  serviceType: Types.ModelServiceTypes.OpenAi,
+  openAI: {
+    model: Types.OpenAiModels.Gpt4O_128K
+  }
+});
+
+// Chat with tools
 await client.streamAgent(
   "What's the weather in San Francisco?",
-  (event: AgentStreamEvent) => {
-    if (event.type === "tool_update") {
-      console.log(`Tool ${event.toolCall.name}: ${event.status}`);
-      if (event.result) {
-        console.log(`Result: ${JSON.stringify(event.result)}`);
-      }
-      if (event.error) {
-        console.error(`Tool error: ${event.error}`);
-      }
-    } else if (event.type === "conversation_completed") {
-      console.log(`Final: ${event.message.message}`);
+  (event) => {
+    if (event.type === "tool_update" && event.status === "completed") {
+      console.log(`🔧 Called ${event.toolCall.name}`);
+    } else if (event.type === "message_update") {
+      console.log(event.message.message);
     }
   },
   undefined, // conversationId
-  { id: "your-specification-id" }, // specification
-  tools,
-  toolHandlers
+  { id: spec.createSpecification.id }, // specification
+  [weatherTool], // tools
+  toolHandlers // handlers
 );
 ```
 
-### Using Custom LLM Clients
+## Common Use Cases
 
-You can provide your own configured LLM clients for streaming:
+### Build a Knowledge Base Assistant
 
-```typescript
-import OpenAI from "openai";
-import Anthropic from "@anthropic-ai/sdk";
-
-// Configure custom clients
-const openai = new OpenAI({
-  apiKey: "your-api-key",
-  baseURL: "https://your-proxy.com/v1" // Optional proxy
-});
-
-const anthropic = new Anthropic({
-  apiKey: "your-api-key",
-  baseURL: "https://your-proxy.com" // Optional proxy
-});
-
-// Set custom clients
-client.setOpenAIClient(openai);
-client.setAnthropicClient(anthropic);
-
-// Now streaming will use your custom clients
-await client.streamAgent("Hello!", (event) => {
-  // Your event handler
-});
-```
-
-### Streaming Options
-
-Configure streaming behavior with options:
+Create an AI that answers questions from your documents:
 
 ```typescript
-await client.streamAgent(
-  "Your prompt",
-  (event) => { /* handler */ },
-  undefined, // conversationId
-  { id: "spec-id" }, // specification
-  undefined, // tools
-  undefined, // toolHandlers
-  {
-    maxToolRounds: 10,        // Maximum tool calling rounds (default: 1000)
-    smoothingEnabled: true,   // Enable smooth streaming (default: true)
-    chunkingStrategy: 'word', // 'character' | 'word' | 'sentence' (default: 'word')
-    smoothingDelay: 30,       // Milliseconds between chunks (default: 30)
-    abortSignal: controller.signal // AbortController signal for cancellation
-  }
-);
-```
+import { Graphlit, Types } from "graphlit-client";
 
-### Conversation Continuity
+class KnowledgeAssistant {
+  private client: Graphlit;
+  private conversationId?: string;
+  private specificationId?: string;
+  private contentIds: string[] = [];
 
-Continue existing conversations by passing the conversation ID:
+  constructor() {
+    this.client = new Graphlit(); // Uses env vars: GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID, GRAPHLIT_JWT_SECRET
+  }
 
-```typescript
-let conversationId: string;
+  async initialize() {
+    // Create a specification for the assistant
+    const spec = await this.client.createSpecification({
+      name: "Knowledge Assistant",
+      type: Types.SpecificationTypes.Completion,
+      serviceType: Types.ModelServiceTypes.OpenAi,
+      openAI: {
+        model: Types.OpenAiModels.Gpt4O_128K,
+        temperature: 0.7
+      }
+    });
+    this.specificationId = spec.createSpecification?.id;
+  }
 
-// First message
-await client.streamAgent(
-  "Remember that my favorite color is blue",
-  (event) => {
-    if (event.type === "conversation_started") {
-      conversationId = event.conversationId;
+  async uploadDocuments(urls: string[]) {
+    console.log("📚 Uploading documents...");
+    
+    for (const url of urls) {
+      const content = await this.client.ingestUri(
+        url, // uri
+        url.split('/').pop() || "Document", // name
+        undefined, // id
+        true // isSynchronous - wait for processing
+      );
+      this.contentIds.push(content.ingestUri.id);
     }
+    
+    console.log("✅ Documents uploaded!");
+    
+    // Wait for content to be indexed
+    await new Promise(resolve => setTimeout(resolve, 5000));
   }
-);
 
-// Continue conversation
-await client.streamAgent(
-  "What's my favorite color?",
-  (event) => {
-    if (event.type === "conversation_completed") {
-      console.log(event.message.message); // Should mention "blue"
+  async ask(question: string) {
+    // Create conversation with content filter if not exists
+    if (!this.conversationId && this.contentIds.length > 0) {
+      const conversation = await this.client.createConversation({
+        filter: { contents: this.contentIds.map(id => ({ id })) }
+      });
+      this.conversationId = conversation.createConversation?.id;
     }
-  },
-  conversationId // Pass the conversation ID
-);
-```
+    
+    await this.client.streamAgent(
+      question,
+      (event) => {
+        if (event.type === "conversation_started" && !this.conversationId) {
+          this.conversationId = event.conversationId;
+        } else if (event.type === "message_update") {
+          process.stdout.write(event.message.message);
+        }
+      },
+      this.conversationId, // Maintains conversation context
+      { id: this.specificationId! } // specification
+    );
+  }
+}
 
-### Error Handling
+// Usage
+const assistant = new KnowledgeAssistant();
+await assistant.initialize();
 
-The streaming client provides comprehensive error handling:
+// Upload your documents
+await assistant.uploadDocuments([
+  "https://arxiv.org/pdf/2103.15348.pdf",
+  "https://arxiv.org/pdf/1706.03762.pdf"
+]);
 
-```typescript
-await client.streamAgent(
-  "Your prompt",
-  (event) => {
-    if (event.type === "error") {
-      console.error(`Error: ${event.error.message}`);
-      console.log(`Recoverable: ${event.error.recoverable}`);
-      
-      // Handle specific error types
-      if (event.error.code === "RATE_LIMIT") {
-        // Implement retry logic
-      }
-    }
-  }
-);
+// Ask questions
+await assistant.ask("What are these papers about?");
+await assistant.ask("How do they relate to each other?");
 ```
 
-### Cancelling Streams
+### Extract Data from Documents
 
-Use an AbortController to cancel ongoing streams:
+Extract specific information from uploaded content:
 
 ```typescript
-const controller = new AbortController();
+// Upload a document synchronously
+const document = await client.ingestUri(
+  "https://example.com/document.pdf", // uri
+  "Document #12345", // name
+  undefined, // id
+  true // isSynchronous
+);
 
-// Start streaming
-client.streamAgent(
-  "Write a long story...",
-  (event) => {
-    // Your handler
-  },
-  undefined,
-  undefined,
-  undefined,
-  undefined,
-  { abortSignal: controller.signal }
+// Wait for content to be indexed
+await new Promise(resolve => setTimeout(resolve, 5000));
+
+// Extract specific data
+const extraction = await client.extractContents(
+  "Extract the key information from this document",
+  undefined, // tools
+  undefined, // specification
+  { contents: [{ id: document.ingestUri.id }] } // filter
 );
 
-// Cancel after 5 seconds
-setTimeout(() => controller.abort(), 5000);
+console.log("Extracted data:", extraction.extractContents);
 ```
 
-## Advanced Tool Calling
+### Summarize Multiple Documents
 
-### Multiple Tool Calls
-
-The agent can make multiple tool calls in a single response:
+Create summaries across multiple files:
 
 ```typescript
-const tools = [
-  {
-    name: "search_web",
-    description: "Search the web for information",
-    schema: JSON.stringify({
-      type: "object",
-      properties: {
-        query: { type: "string" }
-      },
-      required: ["query"]
-    })
-  },
-  {
-    name: "calculate",
-    description: "Perform calculations",
-    schema: JSON.stringify({
-      type: "object",
-      properties: {
-        expression: { type: "string" }
-      },
-      required: ["expression"]
-    })
-  }
-];
-
-const toolHandlers = {
-  search_web: async ({ query }) => {
-    // Implement web search
-    return { results: ["Result 1", "Result 2"] };
-  },
-  calculate: async ({ expression }) => {
-    // Implement calculation
-    return { result: eval(expression) }; // Use a proper math parser in production
-  }
-};
+// Upload multiple documents synchronously
+const ids: string[] = [];
+
+for (const url of documentUrls) {
+  const content = await client.ingestUri(
+    url, // uri
+    url.split('/').pop() || "Document", // name
+    undefined, // id
+    true // isSynchronous
+  );
+  ids.push(content.ingestUri.id);
+}
 
-// The agent can use multiple tools to answer complex queries
-await client.streamAgent(
-  "Search for the current GDP of Japan and calculate 2.5% of it",
-  handleStreamEvent,
-  undefined,
-  { id: specId },
-  tools,
-  toolHandlers,
-  { maxToolRounds: 5 } // Allow multiple rounds of tool calls
+// Generate a summary across all documents
+const summary = await client.summarizeContents(
+  [{
+    type: Types.SummarizationTypes.Custom,
+    prompt: "Create an executive summary of these documents"
+  }], // summarizations
+  { contents: ids.map(id => ({ id })) } // filter
 );
-```
 
-### Tool Calling with Timeouts
+console.log("Summary:", summary.summarizeContents);
+```
 
-Protect against hanging tools with timeouts:
+### Processing Options
 
 ```typescript
-const toolHandlers = {
-  slow_operation: async (args) => {
-    // This will timeout after 30 seconds (default)
-    await someSlowOperation(args);
-  }
-};
-
-// Or set custom timeout in AgentOptions
-await client.promptAgent(
-  "Run the slow operation",
-  undefined,
-  { id: specId },
-  tools,
-  toolHandlers,
-  { 
-    timeout: 60000, // 60 second timeout for entire operation
-    maxToolRounds: 3 
-  }
+// Option 1: Synchronous processing (simpler)
+const content = await client.ingestUri(
+  "https://example.com/large-document.pdf", // uri
+  undefined, // name
+  undefined, // id
+  true // isSynchronous
 );
-```
-
-## Stream Event Reference
-
-### Agent Stream Events
+console.log("✅ Content ready!");
 
-| Event Type | Description | Properties |
-|------------|-------------|------------|
-| `conversation_started` | Conversation initialized | `conversationId`, `timestamp`, `model?` |
-| `message_update` | Message text updated | `message` (complete text), `isStreaming` |
-| `tool_update` | Tool execution status | `toolCall`, `status`, `result?`, `error?` |
-| `conversation_completed` | Streaming finished | `message` (final) |
-| `error` | Error occurred | `error` object with `message`, `code?`, `recoverable` |
+// Option 2: Asynchronous processing (for large files)
+const content = await client.ingestUri(
+  "https://example.com/very-large-video.mp4" // uri
+  // isSynchronous defaults to false
+);
 
-### Tool Execution Statuses
+// Check status later
+let isReady = false;
+while (!isReady) {
+  const status = await client.isContentDone(content.ingestUri.id);
+  isReady = status.isContentDone?.result || false;
+  
+  if (!isReady) {
+    console.log("⏳ Still processing...");
+    await new Promise(resolve => setTimeout(resolve, 2000));
+  }
+}
+console.log("✅ Content ready!");
+```
 
-- `preparing` - Tool call detected, preparing to execute
-- `executing` - Tool handler is running
-- `completed` - Tool executed successfully
-- `failed` - Tool execution failed
+## Advanced Workflows
 
-## Examples
+### Creating Workflows for Content Processing
 
-### Basic Chat UI Integration
+Workflows automatically process content when ingested:
 
 ```typescript
-// React example
-function ChatComponent() {
-  const [message, setMessage] = useState("");
-  const [isLoading, setIsLoading] = useState(false);
-
-  const handleSend = async (prompt: string) => {
-    setIsLoading(true);
-    setMessage("");
-
-    await client.streamAgent(
-      prompt,
-      (event) => {
-        if (event.type === "message_update") {
-          setMessage(event.message.message);
-        } else if (event.type === "conversation_completed") {
-          setIsLoading(false);
-        } else if (event.type === "error") {
-          setMessage(`Error: ${event.error.message}`);
-          setIsLoading(false);
-        }
-      }
-    );
-  };
-
-  return (
-    <div>
-      <div>{message}</div>
-      <button onClick={() => handleSend("Hello!")} disabled={isLoading}>
-        Send
-      </button>
-    </div>
-  );
-}
-```
+import { Graphlit, Types } from "graphlit-client";
 
-### Multi-Model Support
+const client = new Graphlit(); // Uses env vars: GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID, GRAPHLIT_JWT_SECRET
 
-```typescript
-// Create specifications for different models
-const gpt4Spec = await client.createSpecification({
-  name: "GPT-4",
-  type: Types.SpecificationTypes.Completion,
+// Create specifications for AI models
+const summarizationSpec = await client.createSpecification({
+  name: "Summarizer",
+  type: Types.SpecificationTypes.Summarization,
   serviceType: Types.ModelServiceTypes.OpenAi,
   openAI: {
-    model: Types.OpenAiModels.Gpt4O_128K,
-    temperature: 0.7
+    model: Types.OpenAiModels.Gpt4O_128K
   }
 });
 
-const claudeSpec = await client.createSpecification({
-  name: "Claude",
-  type: Types.SpecificationTypes.Completion,
-  serviceType: Types.ModelServiceTypes.Anthropic,
-  anthropic: {
-    model: Types.AnthropicModels.Claude_3_5Haiku,
-    temperature: 0.7
+// Create a workflow that summarizes all content
+const workflow = await client.createWorkflow({
+  name: "Document Intelligence",
+  preparation: {
+    summarizations: [{
+      type: Types.SummarizationTypes.Summary,
+      specification: { id: summarizationSpec.createSpecification.id }
+    }]
   }
 });
 
-// Use different models
-await client.streamAgent(
-  "Hello!",
-  handler,
-  undefined,
-  { id: gpt4Spec.createSpecification.id } // Use GPT-4
-);
+// Set workflow as default for project
+await client.updateProject({
+  workflow: { id: workflow.createWorkflow.id }
+});
 
-await client.streamAgent(
-  "Hello!",
-  handler,
-  undefined,
-  { id: claudeSpec.createSpecification.id } // Use Claude
+// Now all content will be automatically summarized
+const content = await client.ingestUri(
+  "https://example.com/report.pdf" // uri
 );
 ```
 
-## Best Practices
+### Creating Specifications
 
-### 1. Always Handle Errors
+Specifications configure how AI models behave:
 
 ```typescript
-await client.streamAgent(
-  prompt,
-  (event) => {
-    if (event.type === "error") {
-      // Check if error is recoverable
-      if (event.error.recoverable) {
-        // Could retry or fallback
-        console.warn("Recoverable error:", event.error.message);
-      } else {
-        // Fatal error
-        console.error("Fatal error:", event.error.message);
-      }
-    }
-  }
-);
-```
-
-### 2. Clean Up Resources
-
-```typescript
-// Always clean up conversations when done
-let conversationId: string;
-
-try {
-  await client.streamAgent(
-    prompt,
-    (event) => {
-      if (event.type === "conversation_started") {
-        conversationId = event.conversationId;
-      }
-    }
-  );
-} finally {
-  if (conversationId) {
-    await client.deleteConversation(conversationId);
-  }
-}
-```
-
-### 3. Tool Handler Best Practices
+import { Graphlit, Types } from "graphlit-client";
 
-```typescript
-const toolHandlers = {
-  // Always validate inputs
-  calculate: async (args) => {
-    if (!args.expression || typeof args.expression !== 'string') {
-      throw new Error("Invalid expression");
-    }
-    
-    // Return structured data
-    return {
-      expression: args.expression,
-      result: evaluateExpression(args.expression),
-      timestamp: new Date().toISOString()
-    };
-  },
-  
-  // Handle errors gracefully
-  fetch_data: async (args) => {
-    try {
-      const data = await fetchFromAPI(args.url);
-      return { success: true, data };
-    } catch (error) {
-      return { 
-        success: false, 
-        error: error.message,
-        // Help the LLM understand what went wrong
-        suggestion: "The URL might be invalid or the service is down"
-      };
-    }
+// Create a conversational AI specification
+const conversationSpec = await client.createSpecification({
+  name: "Customer Support AI",
+  type: Types.SpecificationTypes.Completion,
+  serviceType: Types.ModelServiceTypes.OpenAi,
+  systemPrompt: "You are a helpful customer support assistant.",
+  openAI: {
+    model: Types.OpenAiModels.Gpt4O_128K,
+    temperature: 0.7,
+    completionTokenLimit: 2000
   }
-};
-```
-
-### 4. Optimize for Performance
-
-```typescript
-// Use appropriate chunking strategy for your use case
-const options = {
-  // For code generation or technical content
-  chunkingStrategy: 'character' as const,
-  
-  // For natural conversation (default)
-  chunkingStrategy: 'word' as const,
-  
-  // For long-form content
-  chunkingStrategy: 'sentence' as const,
-  
-  // Adjust smoothing delay for your UI
-  smoothingDelay: 20, // Faster updates
-  smoothingDelay: 50, // Smoother updates (default: 30)
-};
-```
-
-## Migration Guide
-
-If you're upgrading from `promptConversation` to `streamAgent` or `promptAgent`:
-
-```typescript
-// Before (v1.0)
-const response = await client.promptConversation(
-  "Your prompt",
-  undefined,
-  { id: specId }
-);
-console.log(response.promptConversation.message.message);
-
-// After (v1.1) - Non-streaming
-const result = await client.promptAgent(
-  "Your prompt",
-  undefined,
-  { id: specId }
-);
-console.log(result.message);
+});
 
-// After (v1.1) - Streaming
+// Use the specification in conversations
 await client.streamAgent(
-  "Your prompt",
+  "How do I reset my password?",
   (event) => {
-    if (event.type === "conversation_completed") {
+    if (event.type === "message_update") {
       console.log(event.message.message);
     }
   },
   undefined,
-  { id: specId }
+  { id: conversationSpec.createSpecification.id }
 );
 ```
 
-## Troubleshooting
-
-### Common Issues
+## API Reference
 
-#### 1. Streaming Not Working
+### Client Methods
 
 ```typescript
-// Check if streaming is supported
-if (!client.supportsStreaming()) {
-  console.log("Streaming not supported - using fallback mode");
-}
-
-// Ensure LLM clients are properly configured
-const hasNativeStreaming = 
-  client.hasOpenAIClient() || 
-  client.hasAnthropicClient() || 
-  client.hasGoogleClient();
+const client = new Graphlit(organizationId?, environmentId?, jwtSecret?);
 ```
 
-#### 2. Tool Calls Not Executing
+#### Content Operations
+- `ingestUri(uri, name?, id?, isSynchronous?, ...)` - Ingest content from URL
+- `ingestText(text, name?, textType?, ...)` - Ingest text content directly
+- `queryContents(filter?)` - Search and query content
+- `getContent(id)` - Get content by ID
+- `deleteContent(id)` - Delete content
+- `extractContents(prompt, tools, specification?, filter?)` - Extract data from content
+- `summarizeContents(summarizations, filter?)` - Summarize content
+- `isContentDone(id)` - Check if content processing is complete
+
+#### Conversation Operations  
+- `createConversation(input?)` - Create a new conversation
+- `streamAgent(prompt, handler, ...)` - Stream AI responses
+- `promptAgent(prompt, ...)` - Get AI response without streaming
+- `deleteConversation(id)` - Delete conversation
+
+#### Specification Operations
+- `createSpecification(input)` - Create AI model configuration
+- `querySpecifications(filter?)` - List specifications
+- `deleteSpecification(id)` - Delete specification
+
+#### Workflow Operations
+- `createWorkflow(input)` - Create content processing workflow
+- `queryWorkflows(filter?)` - List workflows
+- `updateProject(input)` - Update project settings
+
+### Event Types
 
 ```typescript
-// Ensure tool schemas are valid JSON Schema
-const validSchema = {
-  type: "object",
-  properties: {
-    param: { type: "string", description: "Parameter description" }
-  },
-  required: ["param"] // Don't forget required fields
-};
-
-// Tool names must match exactly
-const tools = [{ name: "my_tool", /* ... */ }];
-const toolHandlers = { 
-  "my_tool": async (args) => { /* ... */ } // Name must match
-};
+type AgentStreamEvent = 
+  | { type: "conversation_started"; conversationId: string }
+  | { type: "message_update"; message: { message: string } }
+  | { type: "tool_update"; toolCall: any; status: string }
+  | { type: "conversation_completed"; message: { message: string } }
+  | { type: "error"; error: { message: string; recoverable: boolean } }
 ```
 
-#### 3. Incomplete Streaming Responses
+## Testing & Examples
 
-Some LLM providers may truncate responses. The client handles this automatically, but you can enable debug logging:
+All examples in this README are tested and verified. See [`test/readme-simple.test.ts`](test/readme-simple.test.ts) for runnable versions of these examples.
+
+To run the examples yourself:
 
 ```bash
-DEBUG_STREAMING=true npm start
-```
+# Clone the repository
+git clone https://github.com/graphlit/graphlit-client-typescript.git
+cd graphlit-client-typescript
 
-#### 4. Type Errors
+# Install dependencies
+npm install
 
-Ensure you're importing the correct types:
+# Set up your environment variables
+cp .env.example .env
+# Edit .env with your Graphlit credentials
 
-```typescript
-import { 
-  Graphlit,
-  AgentStreamEvent,  // For streaming events
-  AgentResult,       // For promptAgent results
-  ToolHandler,       // For tool handler functions
-  StreamAgentOptions // For streaming options
-} from "graphlit-client";
-
-// Also available if needed
-import * as Types from "graphlit-client/generated/graphql-types";
+# Run the examples
+npm test test/readme-simple.test.ts
 ```
 
 ## Support
 
-Please refer to the [Graphlit API Documentation](https://docs.graphlit.dev/).
+- 📖 **Documentation**: [https://docs.graphlit.dev/](https://docs.graphlit.dev/)
+- 💬 **Discord Community**: [Join our Discord](https://discord.gg/ygFmfjy3Qx)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/graphlit/graphlit-client-typescript/issues)
+- 📧 **Email**: support@graphlit.com
 
-For support with the Graphlit Client, please submit a [GitHub Issue](https://github.com/graphlit/graphlit-client-typescript/issues).
+## License
 
-For further support with the Graphlit Platform, please join our [Discord](https://discord.gg/ygFmfjy3Qx) community.
+MIT License - see LICENSE file for details.

package/dist/client.d.ts

@@ -1,11 +1,12 @@
-import { ApolloClient, NormalizedCacheObject } from "@apollo/client/core";
+export declare const ApolloClient: any, InMemoryCache: any, createHttpLink: any, ApolloLink: any;
+import type { ApolloClient as ApolloClientType, NormalizedCacheObject } from "@apollo/client";
 import * as Types from "./generated/graphql-types.js";
 import { AgentOptions, AgentResult, StreamAgentOptions, ToolHandler } from "./types/agent.js";
 import { AgentStreamEvent } from "./types/ui-events.js";
 export type { AgentOptions, AgentResult, StreamAgentOptions, ToolCallResult, UsageInfo, AgentError, } from "./types/agent.js";
 export type { AgentStreamEvent } from "./types/ui-events.js";
 declare class Graphlit {
-    client: ApolloClient<NormalizedCacheObject> | undefined;
+    client: ApolloClientType<NormalizedCacheObject> | undefined;
     token: string | undefined;
     private apiUri;
     private organizationId;

package/dist/client.js

@@ -1,9 +1,15 @@
+// Runtime import via createRequire
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const apollo = require("@apollo/client");
+// Runtime value import
+const { ApolloError } = require("@apollo/client");
+export const { ApolloClient, InMemoryCache, createHttpLink, ApolloLink } = apollo;
 import * as jwt from "jsonwebtoken";
-import { ApolloClient, InMemoryCache, createHttpLink, ApolloLink, ApolloError, } from "@apollo/client/core";
 import * as Types from "./generated/graphql-types.js";
 import * as Documents from "./generated/graphql-documents.js";
 import * as dotenv from "dotenv";
-import { getServiceType, } from "./model-mapping.js";
+import { getServiceType } from "./model-mapping.js";
 import { UIEventAdapter } from "./streaming/ui-event-adapter.js";
 import { formatMessagesForOpenAI, formatMessagesForAnthropic, formatMessagesForGoogle, } from "./streaming/llm-formatters.js";
 import { streamWithOpenAI, streamWithAnthropic, streamWithGoogle, } from "./streaming/providers.js";
@@ -1724,7 +1730,8 @@ class Graphlit {
                             // Check for common truncation patterns
                             const lastChars = toolCall.arguments.slice(-20);
                             let isTruncated = false;
-                            if (!toolCall.arguments.includes('}') || !lastChars.includes('}')) {
+                            if (!toolCall.arguments.includes("}") ||
+                                !lastChars.includes("}")) {
                                 console.error(`Possible truncation detected - arguments don't end with '}': ...${lastChars}`);
                                 isTruncated = true;
                             }
@@ -1737,7 +1744,8 @@ class Graphlit {
                                 const missingBraces = openBraces - closeBraces;
                                 if (missingBraces > 0) {
                                     // Check if we're mid-value (ends with number or boolean)
-                                    if (fixedJson.match(/:\s*\d+$/) || fixedJson.match(/:\s*(true|false)$/)) {
+                                    if (fixedJson.match(/:\s*\d+$/) ||
+                                        fixedJson.match(/:\s*(true|false)$/)) {
                                         // Complete the current property and close
                                         fixedJson += ', "content": ""'; // Add empty content field
                                     }
@@ -1747,7 +1755,8 @@ class Graphlit {
                                         fixedJson += ', "content": ""';
                                     }
                                     // Add missing closing quote if the string ends with an unfinished string
-                                    else if (fixedJson.endsWith('"') === false && fixedJson.includes('"')) {
+                                    else if (fixedJson.endsWith('"') === false &&
+                                        fixedJson.includes('"')) {
                                         const lastQuoteIndex = fixedJson.lastIndexOf('"');
                                         const afterLastQuote = fixedJson.slice(lastQuoteIndex + 1);
                                         if (!afterLastQuote.includes('"')) {
@@ -1755,7 +1764,7 @@ class Graphlit {
                                         }
                                     }
                                     // Add missing closing braces
-                                    fixedJson += '}'.repeat(missingBraces);
+                                    fixedJson += "}".repeat(missingBraces);
                                     console.log(`Attempting to fix truncated JSON by adding ${missingBraces} closing brace(s):`);
                                     console.log(fixedJson);
                                     try {
@@ -1771,7 +1780,7 @@ class Graphlit {
                             // If we couldn't parse or fix the JSON, log details and continue
                             if (!args) {
                                 // Log position mentioned in error if available
-                                const errorMsg = parseError instanceof Error ? parseError.message : '';
+                                const errorMsg = parseError instanceof Error ? parseError.message : "";
                                 const posMatch = errorMsg.match(/position (\d+)/);
                                 if (posMatch) {
                                     const pos = parseInt(posMatch[1]);
@@ -1781,7 +1790,7 @@ class Graphlit {
                                 // Update UI with error - use StreamEvent error type
                                 uiAdapter.handleEvent({
                                     type: "error",
-                                    error: `Tool ${toolCall.name} failed: Invalid JSON arguments: ${parseError instanceof Error ? parseError.message : 'Unknown error'}`,
+                                    error: `Tool ${toolCall.name} failed: Invalid JSON arguments: ${parseError instanceof Error ? parseError.message : "Unknown error"}`,
                                 });
                                 continue;
                             }
@@ -2058,7 +2067,8 @@ class Graphlit {
             return result.data;
         }
         catch (error) {
-            if (error instanceof ApolloError && error.graphQLErrors.length > 0) {
+            if (error instanceof ApolloError &&
+                error.graphQLErrors.length > 0) {
                 const errorMessage = error.graphQLErrors
                     .map((err) => this.prettyPrintGraphQLError(err))
                     .join("\n");
@@ -2094,7 +2104,8 @@ class Graphlit {
             return result.data;
         }
         catch (error) {
-            if (error instanceof ApolloError && error.graphQLErrors.length > 0) {
+            if (error instanceof ApolloError &&
+                error.graphQLErrors.length > 0) {
                 const errorMessage = error.graphQLErrors
                     .map((err) => this.prettyPrintGraphQLError(err))
                     .join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20250610010",
+  "version": "1.0.20250611002",
   "description": "Graphlit API Client for TypeScript",
   "main": "dist/client.js",
   "types": "dist/client.d.ts",
@@ -63,6 +63,7 @@
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^1.0.0",
     "dotenv": "^16.5.0",
+    "react": "^19.1.0",
     "typescript": "^5.8.2",
     "vitest": "^1.0.0"
   },