### Install OpenAI SDK

Source: https://docs.thesys.dev/welcome/guides/setup-from-scratch

Installs the OpenAI SDK for interacting with OpenAI APIs.

```bash
npm install openai
```

--------------------------------

### Install C1 and Crayon SDKs

Source: https://docs.thesys.dev/welcome/guides/setup-from-scratch

Installs the necessary packages for C1 (@thesysai/genui-sdk) and Crayon AI (@crayonai/react-core, @crayonai/stream) using npm.

```bash
npm install @thesysai/genui-sdk @crayonai/react-core @crayonai/stream
```

--------------------------------

### Install Project Dependencies

Source: https://docs.thesys.dev/welcome/guides/conversational/quickstart

Navigates into the cloned project directory and installs all required Node.js dependencies using npm, preparing the application for development.

```bash
cd template-c1-next
npm install
```

--------------------------------

### Create a Next.js project

Source: https://docs.thesys.dev/welcome/guides/setup-from-scratch

Initializes a new Next.js application using `create-next-app`.

```bash
npx create-next-app c1-app
```

--------------------------------

### Install Project Dependencies for Thesys Template

Source: https://docs.thesys.dev/welcome/guides/setup

Navigates into the cloned Thesys template directory and installs all required Node.js dependencies using npm, preparing the project for development.

```bash
cd template-c1-component-next
npm install
```

--------------------------------

### Run Thesys Generative UI Development Server

Source: https://docs.thesys.dev/welcome/guides/setup

Starts the local development server for the Thesys Generative UI application, allowing you to test and view the generative UI in action in your browser.

```bash
npm run dev
```

--------------------------------

### Run Thesys Development Server

Source: https://docs.thesys.dev/welcome/guides/conversational/quickstart

Starts the local development server for the Thesys Generative UI application, allowing you to test and view the conversational UI in action.

```bash
npm run dev
```

--------------------------------

### Clone Thesys Generative UI Template Repository

Source: https://docs.thesys.dev/welcome/guides/setup

Clones the official Thesys Generative UI Next.js template repository from GitHub to your local machine, providing a starting point for your application.

```bash
git clone https://github.com/thesysdev/template-c1-component-next.git
```

--------------------------------

### Integrate C1Chat component into Next.js frontend

Source: https://docs.thesys.dev/welcome/guides/setup-from-scratch

Demonstrates how to use the `C1Chat` component from `@thesysai/genui-sdk` in a Next.js application. This component provides a ready-to-use chat interface, requiring only the `apiUrl` prop to connect to the backend endpoint.

```typescript
"use client";

import { C1Chat } from "@thesysai/genui-sdk";
import "@crayonai/react-ui/styles/index.css";

export default function Home() {
  return <C1Chat apiUrl="/api/chat" />;
}
```

--------------------------------

### Stream Responses from Thesys C1 Chat Completions

Source: https://docs.thesys.dev/welcome/guides/calling-api

Illustrates how to enable streaming for chat completion responses from the Thesys C1 API, providing real-time output similar to the OpenAI API.

```Python
stream = client.chat.completions.create(
  model="thesys-c1",
  messages=[{"role": "user", "content": "Hello"}],
  stream=True,
)
```

```JavaScript
const stream = await openai.chat.completions.create({
  model: 'thesys-c1',
  messages: [{ role: 'user', content: userMessage }],
  stream: true,
});
```

--------------------------------

### Implement Next.js API endpoint for chat agent

Source: https://docs.thesys.dev/welcome/guides/setup-from-scratch

Sets up a Next.js API route (`/api/chat`) to handle chat interactions. It uses the message store to maintain conversation history, interacts with the C1 API via the OpenAI SDK, and streams responses back to the client. It also transforms the OpenAI stream to a C1 stream and handles message accumulation.

```typescript
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import type { ChatCompletionMessageParam } from "openai/resources.mjs";
import { transformStream } from "@crayonai/stream";
import { getMessageStore } from "./messageStore";

export async function POST(req: NextRequest) {
  const { prompt, threadId, responseId } = (await req.json()) as {
    prompt: ChatCompletionMessageParam;
    threadId: string;
    responseId: string;
  };

  const client = new OpenAI({
    baseURL: "https://api.thesys.dev/v1/embed",
    apiKey: process.env.THESYS_API_KEY, // Use the API key you created in the previous step
  });

  const messageStore = getMessageStore(threadId);
  messageStore.addMessage(prompt);

  const llmStream = await client.chat.completions.create({
    model: "c1-nightly",
    messages: messageStore.getOpenAICompatibleMessageList(),
    stream: true,
  });

  // Unwrap the OpenAI stream to a C1 stream
  const responseStream = transformStream(
    llmStream,
    (chunk) => {
      return chunk.choices[0].delta.content;
    },
    {
      onEnd: ({ accumulated }) => {
        const message = accumulated.filter((chunk) => chunk).join("");
        messageStore.addMessage({
          id: responseId,
          role: "assistant",
          content: message,
        });
      },
    }
  ) as ReadableStream<string>;

  return new NextResponse(responseStream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
    },
  });
}
```

--------------------------------

### Thesys C1 Chat Completions API Parameters Reference

Source: https://docs.thesys.dev/welcome/guides/calling-api

A reference list of standard OpenAI chat completion parameters supported by the Thesys C1 API, detailing their purpose and usage.

```APIDOC
model: The model to use. See Models for more information.
messages: Array of message objects with role and content
temperature: Controls randomness (0.0 to 1.0)
max_tokens: Maximum tokens in the response
stream: Whether to stream the response
top_p: Nucleus sampling parameter
parallel_tool_calls: Whether to call tools in parallel
stop: Stop sequences
```

--------------------------------

### Thesys C1 API Base URL

Source: https://docs.thesys.dev/welcome/guides/calling-api

The base URL for making API requests to the Thesys C1 service, compatible with OpenAI SDKs.

```HTTP
https://api.thesys.dev/v1/embed/chat/completions
```

--------------------------------

### Define in-memory message store for chat history

Source: https://docs.thesys.dev/welcome/guides/setup-from-scratch

Creates a simple in-memory store for chat messages, providing functions to add messages and retrieve OpenAI-compatible message lists. This store is used to manage conversation state in the backend.

```typescript
import OpenAI from "openai";

export type DBMessage = OpenAI.Chat.ChatCompletionMessageParam & {
  id?: string;
};

const messagesStore: {
  [threadId: string]: DBMessage[];
} = {};

export const getMessageStore = (id: string) => {
  if (!messagesStore[id]) {
    messagesStore[id] = [];
  }
  const messageList = messagesStore[id];
  return {
    addMessage: (message: DBMessage) => {
      messageList.push(message);
    },
    messageList,
    getOpenAICompatibleMessageList: () => {
      return messageList.map((m) => {
        const message = {
          ...m,
        };
        delete message.id;
        return message;
      });
    },
  };
};
```

--------------------------------

### Install @crayonai/stream Dependency

Source: https://docs.thesys.dev/welcome/guides/conversational/frameworks/mcp

This command installs the `@crayonai/stream` npm package. This dependency is essential for enabling streaming response capabilities in the application, as demonstrated in the provided code examples.

```bash
npm install @crayonai/stream
```

--------------------------------

### Import and Render Thesys C1Chat React Component

Source: https://docs.thesys.dev/welcome/guides/conversational/ui-installation

After installation, import the `C1Chat` component and its associated styles. This example shows how to render the `C1Chat` component within a React functional component, connecting it to a specified API endpoint for chat functionality.

```React
import { C1Chat } from "@thesysai/genui-sdk";
import "@crayonai/react-ui/styles/index.css";

export default function Home() {
  return <C1Chat apiUrl="/api/chat"/>;
}
```

--------------------------------

### Install Thesys GenUI SDK Package

Source: https://docs.thesys.dev/welcome/guides/conversational/ui-installation

This command installs the `@thesysai/genui-sdk` package, which provides the `C1Chat` React component, into your project's `node_modules` directory.

```JavaScript
npm install @thesysai/genui-sdk
```

--------------------------------

### Clone Thesys Next.js Template Repository

Source: https://docs.thesys.dev/welcome/guides/conversational/quickstart

Clones the official Thesys template repository for a Next.js conversational Generative UI application from GitHub, providing the foundational project structure.

```bash
git clone https://github.com/thesysdev/template-c1-next.git
```

--------------------------------

### Set Thesys API Key as Environment Variable

Source: https://docs.thesys.dev/welcome/guides/setup

Instructs on creating a new API key from the C1 Console and setting it as an environment variable (THESYS_API_KEY) for the application to authenticate with Thesys services.

```bash
export THESYS_API_KEY=<your-api-key>
```

--------------------------------

### Install Dependencies for Tool Calling

Source: https://docs.thesys.dev/welcome/guides/tool-calling

Installs `zod`, `zod-to-json-schema`, and `exa-js` via npm. These packages are essential for defining and using the web search tool in your application.

```Shell
npm install zod zod-to-json-schema exa-js
```

--------------------------------

### Install MCP Client Dependencies

Source: https://docs.thesys.dev/welcome/guides/conversational/frameworks/mcp

Install the necessary dependencies for the Model Context Protocol (MCP) client and a filesystem MCP server in your C1 application using npm.

```npm
npm install @modelcontextprotocol/sdk @modelcontextprotocol/client-stdio
```

--------------------------------

### Install Python dependencies

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Installs all the specified Python packages from the `requirements.txt` file into the current environment, making them available for the backend application.

```bash
cd backend
pip install -r requirements.txt
```

--------------------------------

### Set Thesys API Key Environment Variable

Source: https://docs.thesys.dev/welcome/guides/conversational/quickstart

Sets the THESYS_API_KEY environment variable with your newly created API key from the C1 Console, enabling authentication for Thesys API calls.

```bash
export THESYS_API_KEY=<your-api-key>
```

--------------------------------

### Invoke Thesys C1 Chat Completions API

Source: https://docs.thesys.dev/welcome/guides/calling-api

Demonstrates how to make a chat completions request to the Thesys C1 API, which is fully compatible with the OpenAI API, using cURL, Python, and JavaScript.

```cURL
curl -X POST https://api.thesys.dev/v1/embed/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "thesys-c1",
    "messages": [
      {
        "role": "user",
        "content": "Create a simple contact form"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 1500
  }'
```

```Python
from openai import OpenAI

# Initialize the client with Thesys C1 endpoint
client = OpenAI(
    api_key="YOUR_THESYS_API_KEY",
    base_url="https://api.thesys.dev/v1/embed"
)

response = client.chat.completions.create(
    model="thesys-c1",
    messages=[
        {"role": "user", "content": "hello"}
    ],
    temperature=0.7,
    max_tokens=1500
)
```

```JavaScript
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.thesys.dev/v1',
});

const completion = await openai.chat.completions.create({
  model: 'thesys-c1',
  messages: [
      { role: 'user', content: userMessage }
  ],
  temperature: 0.7,
  max_tokens: 1500,
});
```

--------------------------------

### Start React Frontend Development Server

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

This command starts the React development server, typically configured in the `package.json` scripts. It compiles the frontend code and serves it, usually at `http://localhost:3000`, allowing you to view and interact with the chat interface.

```JavaScript
npm run dev
```

--------------------------------

### Send Chat Completion Request with cURL

Source: https://docs.thesys.dev/welcome/api-reference/getting-started

This cURL command demonstrates how to make a POST request to the Thesys API's chat completions endpoint. It includes setting the Authorization header with a Bearer token for API key authentication and sending a JSON payload with the model and user message.

```curl
curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "c1-embed-latest", "messages": [{"role": "user", "content": "Hello, world!"}]}' \
  https://api.thesys.dev/v1/embed/chat/completions
```

--------------------------------

### Install Next.js Chat API Dependencies

Source: https://docs.thesys.dev/welcome/guides/conversational/backend-installation

Install the necessary npm packages, `openai` and `@crayonai/stream`, required for building the streaming chat API endpoint in a Next.js application.

```Shell
npm install openai @crayonai/stream
```

--------------------------------

### Thesys C1 API Authentication Header

Source: https://docs.thesys.dev/welcome/guides/calling-api

All requests to the Thesys C1 API require an API key to be included in the Authorization header as a Bearer token.

```HTTP
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Run Python Backend Server

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

These commands navigate into the `backend` directory and execute the main Python script. This action starts the FastAPI server, making the API endpoints available for testing and use, and initiating the LangChain agent's functionality.

```bash
cd backend
python main.py
```

--------------------------------

### Install React Frontend Dependencies

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

This command installs all Node.js packages defined in the `package.json` file for the React frontend. It must be executed in the frontend project directory to prepare the application for development or production.

```JavaScript
npm install
```

--------------------------------

### Run React Frontend Development Server

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Executes the npm run dev command to start the Vite development server for the React frontend. This command assumes the LangChain backend is already running and makes the application accessible locally.

```bash
npm run dev
```

--------------------------------

### Create Chinook SQLite database

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Downloads the Chinook SQL script from GitHub and uses `sqlite3` to create a sample database file named `Chinook.db` in the `db` directory, providing data for SQL query examples.

```bash
cd db
curl -s https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDatabase/DataSources/Chinook_Sqlite.sql | sqlite3 Chinook.db
```

--------------------------------

### Install Frontend Dependencies for C1 Generative UI Integration

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Installs essential npm packages required for integrating C1 generative UI components into the React frontend. This includes @crayonai/react-ui for UI components and @thesysai/genui-sdk for the SDK.

```bash
npm install @crayonai/react-ui @thesysai/genui-sdk
```

--------------------------------

### Start Python FastAPI Development Server

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

This command starts the FastAPI development server using Uvicorn. The `--reload` flag enables automatic server restarts on code changes, facilitating development. The backend API will be accessible at `http://localhost:8000`.

```Python
uvicorn main:fastapi_app --reload
```

--------------------------------

### Install Python Backend Dependencies

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

This command installs all necessary Python packages listed in the `requirements.txt` file. It should be run in the backend project directory to ensure all dependencies for the FastAPI application are met.

```Python
pip install -r requirements.txt
```

--------------------------------

### Run FastAPI Application with Uvicorn

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

This Python snippet demonstrates how to start the FastAPI application using Uvicorn, making it accessible on all network interfaces at port 8000.

```Python
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(fastapi_app, host="0.0.0.0", port=8000)
```

--------------------------------

### Integrate System Prompt into AI Agent Message History (TypeScript/JavaScript)

Source: https://docs.thesys.dev/welcome/guides/system-prompt

This snippet demonstrates how to import and integrate the `systemPrompt` into the messages array passed to an OpenAI-compatible chat completion client. By setting the role to 'system' and placing it as the first message, it ensures the AI agent always receives these instructions at the start of any conversation.

```TypeScript
// ... all your imports
import { systemPrompt } from "./systemPrompt";

export async function POST(req: NextRequest) {
  // ... existing code

  const llmStream = await client.chat.completions.create({
    model: "c1-nightly",
    messages: [
      { role: "system", content: systemPrompt },
      ...messageStore.getOpenAICompatibleMessageList(),
    ],
    stream: true,
  });

  // ... existing code
}
```

--------------------------------

### Example Next.js API Route for Tool-Enabled Chat Endpoint

Source: https://docs.thesys.dev/welcome/guides/tool-calling

This TypeScript code provides the initial structure of a Next.js API route (`route.ts`) for handling chat requests. It imports essential modules, including `systemPrompt` and `tools`, setting up the endpoint to receive prompts and thread IDs.

```TypeScript
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";
import { DBMessage, getMessageStore } from "./messageStore";
import { systemPrompt } from "./systemPrompt";
import { tools } from "./tools";

export async function POST(req: NextRequest) {
  const { prompt, threadId, responseId } = (await req.json()) as {
    prompt: DBMessage;
    threadId: string;
  };
}
```

--------------------------------

### Set up LangChain project directory

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Creates a new directory for the LangChain project and navigates into the backend subdirectory, establishing the basic project structure.

```bash
mkdir backend db
cd backend
```

--------------------------------

### Initialize React Frontend Project with Vite and TypeScript

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Commands to navigate up, create a new React project named 'frontend' using Vite with the TypeScript template, and then enter the new project directory. This sets up the basic project structure.

```bash
cd ..
npm create vite@latest frontend -- --template react-ts
cd frontend
```

--------------------------------

### C1 API Error Response Format

Source: https://docs.thesys.dev/welcome/guides/calling-api

The C1 API returns standard HTTP status codes and error responses. This JSON snippet illustrates the format of an error response, compatible with OpenAI's error structure, including a message, type, and code.

```JSON
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

--------------------------------

### Complete AI Agent API Route with System Prompt (TypeScript)

Source: https://docs.thesys.dev/welcome/guides/system-prompt

This comprehensive snippet provides the full Next.js API route for an AI agent. It initializes an OpenAI client, manages message history, integrates the system prompt, and streams responses back to the client, demonstrating a complete backend implementation for an AI application.

```TypeScript
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";
import { DBMessage, getMessageStore } from "./messageStore";
import { systemPrompt } from "./systemPrompt";

export async function POST(req: NextRequest) {
  const { prompt, threadId, responseId } = (await req.json()) as {
    prompt: DBMessage;
    threadId: string;
    responseId: string;
  };
  const client = new OpenAI({
    baseURL: "https://api.thesys.dev/v1/embed/",
    apiKey: process.env.THESYS_API_KEY,
  });
  const messageStore = getMessageStore(threadId);

  messageStore.addMessage(prompt);

  const llmStream = await client.chat.completions.create({
    model: "c1-nightly",
    messages: [
      { role: "system", content: systemPrompt },
      ...messageStore.getOpenAICompatibleMessageList(),
    ],
    stream: true,
  });

  const responseStream = transformStream(
    llmStream,
    (chunk) => {
      return chunk.choices[0].delta.content;
    },
    {
      onEnd: ({ accumulated }) => {
        const message = accumulated.filter((message) => message).join("");
        messageStore.addMessage({
          role: "assistant",
          content: message,
          id: responseId,
        });
      },
    }
  ) as ReadableStream<string>;

  return new NextResponse(responseStream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
    },
  });
}
```

--------------------------------

### Create LangChain Agent, Executor, and Runnable Chain

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

This section sets up the core LangChain components: an OpenAI tools agent, an agent executor, and a runnable chain. It defines the tools available to the agent (the `execute_sql_query` function), creates the agent using the model, tools, and prompt, and then wraps the agent execution in a `RunnableLambda` for integration into a larger chain. The `format_inputs` function transforms input for the agent and extracts the output, ensuring proper data flow.

```python
tools = [execute_sql_query]
agent = create_openai_tools_agent(model, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

def format_inputs(inputs: ChainInput):
    """Transform ChainInput to prompt variables and execute agent"""
    context = inputs.get("c1Response", "No previous context")

    # Execute the agent
    result = agent_executor.invoke({
        "context": context,
        "query": inputs["query"]
    })
    return result["output"]

# Create a proper runnable chain
chain = RunnableLambda(format_inputs)
```

--------------------------------

### ThemeProvider Component API Reference

Source: https://docs.thesys.dev/welcome/guides/styling-c1

API documentation for the ThemeProvider component, detailing its available props for customizing the C1 UI's appearance.

```APIDOC
ThemeProvider Component:
  Props:
    mode:
      Type: ThemeMode
      Optional: true
      Description: The theme mode for the chat component. This can be either ‘light’ or ‘dark’.
    theme:
      Type: Theme
      Optional: true
      Description: The main theme configuration object. If not provided, the default theme will be used. Partial theme can be provided, in which case, only the provided properties will be overridden, while the rest of the options will be taken from the default theme.
    darkTheme:
      Type: Theme
      Optional: true
      Description: The dark theme configuration object used when in dark mode. If not provided, the `theme` object will be used.
```

--------------------------------

### API: Get All Threads (Metadata)

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

Retrieves a list of all conversational threads, returning only their metadata. This endpoint is useful for displaying an overview of available threads.

```APIDOC
GET /threads
Description: Returns a list of all threads (metadata only).
Response Model: List[ThreadInfo]
Python Function: get_threads()
```

--------------------------------

### Configure OpenAI runTools with Thinking State Callback (TypeScript)

Source: https://docs.thesys.dev/welcome/guides/thinking-states

This TypeScript snippet demonstrates how to instantiate and pass the `getWebSearchTool` to OpenAI's `client.beta.chat.completions.runTools` method. It shows how to provide a specific `writeThinkItem` callback to the tool, which updates the UI with a 'Searching the web...' message, providing real-time feedback during the tool's execution.

```typescript
const llmStream = await client.beta.chat.completions.runTools({
  model: "c1-nightly",
  messages: [
    { role: "system", content: systemPrompt },
    ...messageStore.getOpenAICompatibleMessageList(),
  ],
  stream: true,
  tools: [
    getWebSearchTool(() => {
      c1Response.writeThinkItem({
        title: "Searching the web...",
        description:
          "Scouring the digital universe for the most relevant and up-to-date insights.",
      });
    }),
  ],
  toolChoice: "auto",
});
```

--------------------------------

### API: Get Messages for a Specific Thread

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

Retrieves formatted messages for a specified thread ID. If the thread does not exist, a 404 HTTP error is returned.

```APIDOC
GET /threads/{thread_id}/messages
Description: Returns formatted messages for a specific thread.
Path Parameter: thread_id (string)
Response Model: List[UIMessage]
Errors: 404 Not Found (if thread_id does not exist)
Python Function: get_messages_endpoint(thread_id: str)
```

--------------------------------

### Create Backend API Endpoint for AI Chat with Tool Calling

Source: https://docs.thesys.dev/welcome/guides/solutions/company-research

This Next.js API route defines a POST endpoint (`/api/chat`) for an AI search application. It processes user prompts and optional previous agent responses, leveraging an OpenAI client with custom base URL and API key. The endpoint uses a predefined system prompt and web search tools to generate responses, streaming the LLM output back to the client.

```TypeScript
import { NextRequest } from "next/server";
import OpenAI from "openai";
import { ChatCompletionMessageParam } from "openai/resources/chat/completions";
import { transformStream } from "@crayonai/stream";
import { tools } from "./tools";
import { systemPrompt } from "./systemPrompt";

const client = new OpenAI({
  baseURL: "https://api.thesys.dev/v1/embed",
  apiKey: process.env.THESYS_API_KEY,
});

export async function POST(req: NextRequest) {
  const { prompt, previousC1Response } = (await req.json()) as {
    prompt: string;
    previousC1Response?: string;
  };

  const runToolsResponse = client.beta.chat.completions.runTools({
    model: "c1-nightly",
    messages: [
      {
        // Add the system prompt to provide appropriate instructions to the agent on how to generate the response and what UI constraints to consider.
        role: "system",
        content: systemPrompt,
      },

      // If there was a previous agent response, the user prompt may be a follow up question. Add the previous response
      // to the messages sent to the LLM so that the agent can generate an appropriate response.
      ...((previousC1Response
        ? [{ role: "assistant", content: previousC1Response }]
        : []) as ChatCompletionMessageParam[]),

      { role: "user", content: prompt },
    ],
    stream: true,
    tools: tools,
  });

  const llmStream = await runToolsResponse;

  const responseStream = transformStream(llmStream, (chunk) => {
    return chunk.choices[0]?.delta?.content || "";
  });

  return new Response(responseStream as ReadableStream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
    },
  });
}
```

--------------------------------

### Add System Prompt for AI Search Application

Source: https://docs.thesys.dev/welcome/guides/solutions/company-research

This snippet defines a system prompt for an AI business research assistant. The prompt instructs the AI to act like Crunchbase, search the web for company or domain information, and include a follow-up question form at the end of its response to tailor the UI output for a search application.

```TypeScript
export const systemPrompt = `
  You are a business research assistant just like crunchbase. You answer questions about a company or domain.
  given a company name or domain, you will search the web for the latest information.

  At the end of your response, add a form with single input field to ask for follow up questions.
`;
```

--------------------------------

### Configure Vite Proxy for Frontend-Backend API Communication

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Sets up vite.config.ts to proxy API requests starting with /api to the LangChain backend running on http://localhost:4001. This configuration is crucial for development, allowing the frontend to seamlessly communicate with the backend.

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:4001',
        changeOrigin: true,
      }
    }
  }
})
```

--------------------------------

### Implementing Search UI with C1Component in React/Next.js

Source: https://docs.thesys.dev/welcome/guides/solutions/company-research

This React component, designed for Next.js, constructs the main user interface for a search application. It features an input field for queries, a submit button, and integrates the C1Component from @thesysai/genui-sdk for rendering generative AI responses. The ThemeProvider ensures correct styling, and useUIState manages the application's UI state, including loading status and user input.

```JSX
"use client";

import "@crayonai/react-ui/styles/index.css";
import { ThemeProvider, C1Component } from "@thesysai/genui-sdk";
import { useUIState } from "./uiState";
import { Loader } from "./Loader";

export const HomePage = () => {
  const { state, actions } = useUIState();

  return (
    <div className="min-h-screen bg-gray-50 dark:bg-gray-900 py-8 px-4">
      <div className="max-w-[750px] mx-auto space-y-6">
        <div className="flex gap-4 items-center">
          <input
            className="flex-1 px-4 py-2 rounded-lg border border-gray-300 dark:border-gray-600
              bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100
              focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent
              placeholder-gray-500 dark:placeholder-400"
            value={state.query}
            placeholder="Enter company name/domain..."
            onChange={({ target: { value } }) => actions.setQuery(value)}
            onKeyDown={(e) => {
              // make api call only when response loading is not in progress
              if (e.key === "Enter" && !state.isLoading) {
                actions.makeApiCall(state.query);
              }
            }}
          />
          <button
            onClick={() => actions.makeApiCall(state.query)}
            disabled={state.query.length === 0 || state.isLoading}
            className="enabled:cursor-pointer px-6 py-2 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg
              transition-colors duration-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2
              disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center min-w-[100px]"
          >
            {state.isLoading ? <Loader /> : "Submit"}
          </button>
        </div>

        <div className="max-w-[750px] mx-auto">
          <ThemeProvider mode="dark">
            <C1Component
              c1Response={state.c1Response}
              isStreaming={state.isLoading}
              updateMessage={(message) => actions.setC1Response(message)}
              onAction={({ llmFriendlyMessage }) => {
                if (!state.isLoading) {
                  actions.makeApiCall(llmFriendlyMessage, state.c1Response);
                }
              }}
            />
          </ThemeProvider>
        </div>
      </div>
    </div>
  );
};
```

--------------------------------

### Example Streaming Chat Completion Response

Source: https://docs.thesys.dev/welcome/api-reference/objects/streaming

Illustrates the format of a streaming response from the chat completions API. Each `data` field contains a `chat.completion.chunk` object, showing how the response is broken into multiple chunks with unique `id`s for streaming.

```text
  id: 1
  data: {"id":"chatcmpl-1743157601318-pzx9ougakm","object":"chat.completion.chunk","created":1743157601,"model":"c1-embed-latest","choices":[{"index":0,"delta":{"role":"assistant","content":{...}}}]}

  id: 2
  data: {"id":"chatcmpl-1743157601318-pzx9ougakm","object":"chat.completion.chunk","created":1743157601,"model":"c1-embed-latest","choices":[{"index":0,"delta":{"content":{...}}}]}
```

--------------------------------

### Send Chat Completion Request with Curl

Source: https://docs.thesys.dev/welcome/api-reference/objects/streaming

Demonstrates how to send a POST request to the `/v1/embed/chat/completions` endpoint using `curl`. This example includes setting authorization and content type headers, and sending a JSON payload for a streaming chat completion request.

```shell
curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "c1-embed-latest", "stream": true, "messages": [{"role": "user", "content": "Hello, world!"}]}' \
  https://api.thesys.dev/v1/embed/chat/completions
```

--------------------------------

### Send Chat Completion Request with cURL

Source: https://docs.thesys.dev/welcome/api-reference/objects/message

Demonstrates how to send a POST request to the Thesys chat completions API using cURL. This example includes setting authorization, content type, and providing a basic JSON payload with a user message to the `/v1/embed/chat/completions` endpoint.

```curl
curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "c1-embed-latest", "messages": [{"role": "user", "content": "Hello, world!"}]}' \
  https://api.thesys.dev/v1/embed/chat/completions
```

--------------------------------

### Begin Tool Definition for Image Fetching

Source: https://docs.thesys.dev/welcome/guides/solutions/chat

This snippet initiates the definition of a tool that the AI agent can call to fetch image URLs. It imports necessary types from `openai/lib/RunnableFunction.mjs` and `zod` for schema validation, laying the groundwork for integrating external services like Google Custom Search for image retrieval.

```typescript
import type { RunnableToolFunctionWithParse } from "openai/lib/RunnableFunction.mjs";
import type { RunnableToolFunctionWithoutParse } from "openai/lib/RunnableFunction.mjs";
import { z } from "zod";
```

--------------------------------

### Create Next.js API Route File and Imports

Source: https://docs.thesys.dev/welcome/guides/conversational/backend-installation

Set up the main API route file (`route.ts`) for the chat endpoint in Next.js, including essential imports like `NextRequest`, `NextResponse`, `OpenAI`, `transformStream`, and the custom `DBMessage` and `getMessageStore`.

```TypeScript
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";
import { DBMessage, getMessageStore } from "./messageStore";
```

--------------------------------

### Example Streaming Chat Completion Response Format

Source: https://docs.thesys.dev/welcome/api-reference/objects/streaming

Illustrates the Server-Sent Events (SSE) format for streaming responses from the Thesys API. Each chunk contains an `id` and `data` field, with the `data` field holding a JSON object representing a part of the chat completion.

```text
  id: 1
  data: {"id":"chatcmpl-1743157601318-pzx9ougakm","object":"chat.completion.chunk","created":1743157601,"model":"c1-embed-latest","choices":[{"index":0,"delta":{"role":"assistant","content":{...}}}]}

  id: 2
  data: {"id":"chatcmpl-1743157601318-pzx9ougakm","object":"chat.completion.chunk","created":1743157601,"model":"c1-embed-latest","choices":[{"index":0,"delta":{"content":{...}}}]}
```

--------------------------------

### Integrate Tools and System Prompt into Agent's Chat Completion

Source: https://docs.thesys.dev/welcome/guides/tool-calling

This TypeScript snippet shows how to import `systemPrompt` and `tools` into a Next.js API route. It then passes these to the `client.beta.chat.completions.runTools` method, enabling the agent to use the defined tools.

```TypeScript
// ... all your other imports
import { systemPrompt } from "./systemPrompt";
import { tools } from "./tools";

export async function POST(req: NextRequest) {
  // ... rest of your code

  const llmStream = await client.beta.chat.completions.runTools({
    model: "c1-nightly",
    messages: [
      { role: "system", content: systemPrompt },
      ...messageStore.getOpenAICompatibleMessageList(),
    ],
    tools,
    stream: true,
  });

  // ... rest of your code
}
```

--------------------------------

### Example Chat Completion API Response JSON

Source: https://docs.thesys.dev/welcome/api-reference/objects/message

Illustrates a typical JSON response structure from the chat completions API, showing fields like ID, object type, creation timestamp, model, choices (with message content and finish reason), and usage statistics.

```json
{
      "id": "chatcmpl-1743157633416-cffw7tgswx",
      "object": "chat.completion",
      "created": 1743157633,
      "model": "c1-embed-latest",
      "choices": [
          {
          "index": 0,
          "message": {
              "role": "assistant",
              "content": {
                  ...
              }
          },
          "finish_reason": "stop"
          }
      ],
      "usage": {
          "prompt_tokens": 8,
          "completion_tokens": 439,
          "total_tokens": 447
      }
}
```

--------------------------------

### Wrap C1Component with ThemeProvider for UI Customization

Source: https://docs.thesys.dev/welcome/guides/styling-c1

This snippet demonstrates how to integrate the C1Component into a React application and apply UI customizations using the ThemeProvider. It shows how to import the necessary components from @thesys/genui-sdk and wrap C1Component to apply a theme and set the mode.

```JavaScript
import { C1Component, ThemeProvider } from "@thesys/genui-sdk";

const App = () => {
  return (
    <ThemeProvider theme={theme} mode="light">
      <C1Component />
    </ThemeProvider>
  );
}
```

--------------------------------

### Define LangChain Chat Prompt Template for SQL Agent

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Defines a `ChatPromptTemplate` for the LangChain agent, setting up the system message, human input, and a placeholder for agent scratchpad. The system message instructs the agent on its role as a helpful assistant for the Chinook database, detailing the available SQL tool and database contents. It includes context from previous conversations and the current query for dynamic interaction.

```python
prompt = ChatPromptTemplate.from_messages([
    ("system", """You are a helpful assistant that can answer questions about the Chinook digital media store database.\n\nYou have access to a SQL tool that can execute queries on the database. The database contains information about:\n- Artists, Albums, and Tracks\n- Customers and their purchase history\n- Employees and sales data\n- Playlists and media types\n\nWhen users ask questions about the music store data, use the SQL tool to query the database and provide accurate information.\n\nContext from previous conversation: {context}"""),
    ("human", "{query}"),
    ("placeholder", "{agent_scratchpad}")
])
```

--------------------------------

### Example Chat Completion API Response

Source: https://docs.thesys.dev/welcome/api-reference/objects/message

Illustrates the typical JSON structure returned by the Thesys chat completions API. It includes fields such as `id`, `object` type, `created` timestamp, `model` used, `choices` array with message content, `finish_reason`, and `usage` statistics for tokens.

```json
{
      "id": "chatcmpl-1743157633416-cffw7tgswx",
      "object": "chat.completion",
      "created": 1743157633,
      "model": "c1-embed-latest",
      "choices": [
          {
          "index": 0,
          "message": {
              "role": "assistant",
              "content": {
                  ...
              }
          },
          "finish_reason": "stop"
          }
      ],
      "usage": {
          "prompt_tokens": 8,
          "completion_tokens": 439,
          "total_tokens": 447
      }
}
```

--------------------------------

### Run FastAPI Server with Uvicorn

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

This block provides the standard Python entry point to run the FastAPI application using Uvicorn. It configures the server to listen on `localhost` at port `4001`, making the API accessible locally for development and testing purposes.

```python
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="localhost", port=4001)
```

--------------------------------

### Integrate MCP Client with Next.js Chat Route in TypeScript

Source: https://docs.thesys.dev/welcome/guides/conversational/frameworks/mcp

Update your Next.js chat route to utilize the MCP client integration. This example demonstrates how to connect to MCP, retrieve tools, and use OpenAI's `runTools` method for automatic tool execution within a POST request handler.

```typescript
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";
import { DBMessage, getMessageStore } from "./messageStore";
import { MCPClient } from "./mcp";
import { JSONSchema } from "openai/lib/jsonschema.mjs";

// Initialize MCP client
const mcpClient = new MCPClient();

interface RequestBody {
  prompt: DBMessage;
  threadId: string;
  responseId: string;
}

async function ensureMCPConnection(): Promise<void> {
  if (mcpClient.tools.length === 0) {
    await mcpClient.connect();
  }
}

export async function POST(req: NextRequest): Promise<NextResponse> {
  const { prompt, threadId, responseId } = (await req.json()) as RequestBody;

  const client = new OpenAI({
    baseURL: "https://api.thesys.dev/v1/embed/",
    apiKey: process.env.THESYS_API_KEY,
  });

  const messageStore = getMessageStore(threadId);
  messageStore.addMessage(prompt);

  // Ensure MCP connection is established
  await ensureMCPConnection();

  const llmStream = await client.beta.chat.completions.runTools({
    model: "c1-nightly",
    messages: messageStore.getOpenAICompatibleMessageList(),
    tools: mcpClient.tools.map((tool) => ({
      type: "function",
      function: {
        name: tool.function.name,
        description: tool.function.description || "",
        parameters: tool.function.parameters as unknown as JSONSchema,

```

--------------------------------

### Add LangChain Runnable Chain Route to FastAPI App

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Integrates the previously defined LangChain `chain` into the FastAPI application using `add_routes`. It specifies the input type for the chain and defines the `/chain` endpoint, making the LangChain agent accessible via HTTP. This setup allows the agent to receive requests and return responses through the web API.

```python
add_routes(
    app,
    chain.with_types(input_type=ChainInput),
    path="/chain",
)
```

--------------------------------

### Embed Thesys C1 Component in React Application

Source: https://docs.thesys.dev/welcome/guides/embedding-c1-component/index

This snippet demonstrates how to integrate the <C1Component /> from the @thesys/genui-sdk into a React application. It uses ThemeProvider for styling and passes the streamed API response to the c1Response prop to render dynamic, AI-generated UI.

```JavaScript
import { C1Component, ThemeProvider } from "@thesys/genui-sdk";

const App = () => {
  const response = await fetch("<your-backend-url>");
  return (
    <ThemeProvider>
      <C1Component c1Response={response.text()} />
    </ThemeProvider>
  );
};
```

--------------------------------

### Integrate System Prompt into Message Store

Source: https://docs.thesys.dev/welcome/guides/solutions/chat

This TypeScript code defines a message store that persists conversation state for a chat agent. It ensures that a predefined system prompt is added to the beginning of each new conversation thread, guiding the AI's behavior and enabling features like image integration. The store also provides a method to format messages for OpenAI compatibility.

```typescript
import OpenAI from "openai";
import { systemPrompt } from "./systemPrompt";

export type DBMessage = OpenAI.Chat.ChatCompletionMessageParam & {
  id?: string;
};

const messagesStore: {
  [threadId: string]: DBMessage[];
} = {};

export const getMessageStore = (id: string) => {
  if (!messagesStore[id]) {
    messagesStore[id] = [{ role: "system", content: systemPrompt }];
  }
  const messageList = messagesStore[id];
  return {
    addMessage: (message: DBMessage) => {
      messageList.push(message);
    },
    messageList,
    getOpenAICompatibleMessageList: () => {
      return messageList.map((m) => {
        const message = {
          ...m,
        };
        delete message.id;
        return message;
      });
    },
  };
};
```

--------------------------------

### Partial LangGraph Agent Implementation (graph.py)

Source: https://docs.thesys.dev/welcome/guides/frameworks/langgraph

Provides the initial structure of the `graph.py` file, including necessary imports, environment variable loading, and the re-definition of the `AgentState` class, setting the foundation for the full LangGraph implementation.

```python
import os
from typing import TypedDict, Annotated, List
from langchain_core.messages import AnyMessage, AIMessage
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from dotenv import load_dotenv
# Assume tools.py defines runnable_tools
from tools import runnable_tools

load_dotenv()

# 1. Define the State
class AgentState(TypedDict):
    messages: Annotated[List[AnyMessage], add_messages]
    response_id: str
```

--------------------------------

### Define FastAPI Application for LangChain Agent

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Initializes a FastAPI application instance, setting its title, version, and description. This application will serve as the entry point for exposing the LangChain agent via HTTP endpoints, providing a robust and scalable API interface.

```python
app = FastAPI(
    title="LangChain + C1 Server",
    version="1.0",
    description="A simple API server using LangChain's Runnable interfaces powered by Thesys C1",
)
```

--------------------------------

### Initialize FastAPI server with LangChain and C1 integration

Source: https://docs.thesys.dev/welcome/guides/frameworks/langchain

Sets up a FastAPI application, defines an input model for API requests, and initializes the ChatOpenAI model, configuring it to use the Thesys C1 API endpoint as the underlying LLM for LangChain agents.

```python
#!/usr/bin/env python
import os
import sqlite3
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.tools import tool
from langchain_core.runnables import RunnableLambda
from langchain.agents import create_openai_tools_agent, AgentExecutor
from fastapi import FastAPI
from langserve import add_routes
from pydantic import BaseModel

# Input model
class ChainInput(BaseModel):
    c1Response: str = ""  # Can be empty
    query: str

# 1. Create model
model = ChatOpenAI(
    base_url="https://api.thesys.dev/v1/embed",
    model="c1-nightly",
    api_key=os.environ.get("THESYS_API_KEY")
)
```