### Install Composio Core and xsAI Packages

Source: https://xsai.js.org/docs/integrations/tools/composio

Installs the necessary packages for integrating Composio with xsAI, including `composio-core`, `zod`, `@xsai/shared-chat`, and `@xsai/tool`. This is the initial setup step for using the Composio adapter.

```bash
npm i composio-core zod @xsai/shared-chat @xsai/tool

pnpm i composio-core zod @xsai/shared-chat @xsai/tool

yarn add composio-core zod @xsai/shared-chat @xsai/tool

bun add composio-core zod @xsai/shared-chat @xsai/tool
```

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

### Install @xsai/utils-reasoning

Source: https://xsai.js.org/docs/packages/utils/reasoning

Installs the xsAI utilities reasoning package using npm, pnpm, yarn, or bun.

```bash
npm i @xsai/utils-reasoning
```

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

### Install xsfetch using npm

Source: https://xsai.js.org/docs/packages/top-level/xsfetch

This snippet shows how to install the xsfetch package, which provides an enhanced Fetch API with auto-retry capabilities, using npm. It is a prerequisite for using the createFetch function.

```bash
npm i xsfetch
```

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

### Install xsAI Providers with npm

Source: https://xsai.js.org/docs/packages-ext/providers

This command installs the xsAI Providers package using npm. It's a prerequisite for using the predefined providers in your project.

```bash
npm i @xsai-ext/providers
```

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

### Example Usage of MCP Client and getTools

Source: https://xsai.js.org/docs/integrations/tools/model-context-protocol

Demonstrates how to initialize an MCP client and use the `getTools` utility function to fetch tools from a server. This example sets up a standard client connection and then retrieves tools, preparing them for integration.

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
import { getTools } from './utils/get-tools'

const transport = new StdioClientTransport({
  command: 'node',
  args: ['server.js']
})

const client = new Client({
  name: 'example-client',
  version: '1.0.0'
})

await client.connect(transport)

const tools = await getTools({ example: client })

```

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

### Install xsAI MCP SDK and Tool Package

Source: https://xsai.js.org/docs/integrations/tools/model-context-protocol

Installs the necessary packages for interacting with the Model Context Protocol using xsAI. This includes the MCP SDK client and the xsAI tool package.

```bash
npm i @modelcontextprotocol/sdk @xsai/tool
```

```bash
pnpm i @modelcontextprotocol/sdk @xsai/tool
```

```bash
yarn add @modelcontextprotocol/sdk @xsai/tool
```

```bash
bun add @modelcontextprotocol/sdk @xsai/tool
```

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

### Install xsAI Chat Utilities

Source: https://xsai.js.org/docs/packages/utils/chat

Installs the '@xsai/utils-chat' package using npm, pnpm, yarn, or bun. This package provides utility functions for creating chat messages.

```bash
npm i @xsai/utils-chat
```

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

### Install xsai Package

Source: https://xsai.js.org/docs/packages/top-level/xsai

This snippet shows how to install the xsai package using different package managers like npm, pnpm, yarn, and bun. It's a straightforward command-line operation.

```bash
npm i xsai
```

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

### Install @xsai/stream-transcription Package

Source: https://xsai.js.org/docs/packages/stream/transcription

Installs the '@xsai/stream-transcription' package using npm. This package is used for real-time audio transcription.

```bash
npm i @xsai/stream-transcription
```

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

### Install xsSchema using npm

Source: https://xsai.js.org/docs/packages/top-level/xsschema

This command installs the xsSchema package using npm. xsSchema is a dependency for some xsAI packages, so it may already be installed if you are using xsAI.

```bash
npm i xsschema
```

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

### Generate Text with xsAI and Composio Tools (TypeScript Example)

Source: https://xsai.js.org/docs/integrations/tools/composio

Demonstrates how to use the `XSAIToolSet` to fetch available tools and then use them with the `generateText` function from `@xsai/generate-text`. This example shows how to star a GitHub repository using an xsAI tool.

```typescript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'
import { XSAIToolSet } from './utils/xsai-tool-set'

const toolset = new XSAIToolSet()
const tools = await toolset.getTools({ apps: ['github'] })

const result = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  maxSteps: 5,
  model: 'gpt-4o-mini',
  messages: [
    {
      role: 'user',
      content: 'Star the repository "moeru-ai/xsai"',
    },
  ],
  tools,
  toolChoice: 'required',
  temperature: 0,
})

console.log(result.steps)
console.log(result.text)
```

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

### Install xsAI Transcription Package

Source: https://xsai.js.org/docs/packages/generate/transcription

Install the `@xsai/generate-transcription` package using your preferred package manager (npm, pnpm, yarn, or bun). This package provides the functionality to transcribe audio.

```bash
npm i @xsai/generate-transcription
```

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

### Install xsAI Telemetry Package

Source: https://xsai.js.org/docs/packages-ext/telemetry

Install the '@xsai-ext/telemetry' package using npm, pnpm, yarn, or bun. This package provides telemetry features for xsAI.

```bash
npm i @xsai-ext/telemetry
```

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

### Verbose Transcription with Segments using xsAI

Source: https://xsai.js.org/docs/packages/generate/transcription

This example shows how to get a verbose transcription including segments and their timings. It uses the `responseFormat: 'verbose_json'` option. The output includes duration, language, segments array, and the full text.

```javascript
import { generateTranscription } from '@xsai/generate-transcription'
import { openAsBlob } from 'node:fs'

const { duration, language, segments, text } = await generateTranscription({
  apiKey: '',
  baseURL: 'http://localhost:8000/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'deepdml/faster-whisper-large-v3-turbo-ct2',
  responseFormat: 'verbose_json',
})
```

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

### Create and Override a Weather Tool (JavaScript)

Source: https://xsai.js.org/docs/packages/tool

Demonstrates creating a 'weather' tool using '@xsai/tool' and Valibot for schema validation. It shows how to define the tool's description, execution logic, and parameters. The example also illustrates overriding the tool's execute function after its initial creation.

```javascript
import { tool } from '@xsai/tool'
import * as v from 'valibot'

const parameters = v.object({
  location: v.pipe(
    v.string(),
    v.description('The location to get the weather for')
  )
})

const weather = await tool({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({ location, temperature: 42 }),
  name: 'weather',
  parameters,
})

weather.execute = (input) => JSON.stringify({
  location: (input as v.InferInput).location,
  temperature: 5500,
})
```

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

### Install xsAI Model Package

Source: https://xsai.js.org/docs/packages/model

Install the xsAI model package using npm, pnpm, yarn, or bun. This package provides functionalities for managing language models within the xsAI ecosystem.

```bash
npm i @xsai/model
```

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

### Basic Audio Transcription with xsAI

Source: https://xsai.js.org/docs/packages/generate/transcription

This example demonstrates how to perform a basic audio transcription using the `generateTranscription` function from the `@xsai/generate-transcription` package. It requires an API key, base URL, the audio file as a Blob, file name, language, and the transcription model. It returns the transcribed text.

```javascript
import { generateTranscription } from '@xsai/generate-transcription'
import { openAsBlob } from 'node:fs'

const { text } = await generateTranscription({
  apiKey: '',
  baseURL: 'http://localhost:8000/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'deepdml/faster-whisper-large-v3-turbo-ct2',
})
```

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

### Define and Use Standard Tool with Valibot for LLM Function Calling

Source: https://xsai.js.org/docs/packages/tool

This example demonstrates how to define a standard tool using '@xsai/tool' and Valibot for parameter validation. The tool is then passed to 'generateText' to enable the LLM to call it. It requires the 'valibot' package for schema definition and 'node:process' for environment variables.

```typescript
import { generateText } from '@xsai/generate-text'
import { tool } from '@xsai/tool'
import { env } from 'node:process'
import * as v from 'valibot'

const weather = await tool({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({ location, temperature: 42 }),
  name: 'weather',
  parameters: v.object({
    location: v.pipe(
      v.string(),
      v.description('The location to get the weather for')
    ),
  }),
});

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  maxSteps: 2,
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  tools: [weather],
});
```

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

### Generate Text with OpenAI API using xsfetch and @xsai/generate-text

Source: https://xsai.js.org/docs/packages/top-level/xsfetch

This example illustrates how to generate text using the OpenAI API. It utilizes `generateText` from `@xsai/generate-text` and a configured `fetch` instance from `xsfetch` for making the API call. Environment variables are used for the API key.

```javascript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'
import { createFetch } from 'xsfetch'

const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  fetch,
  messages: [
    { content: 'You\'re a helpful assistant.', role: 'system' },
    { content: 'Why is the sky blue?', role: 'user' }
  ],
  model: 'gpt-4o',
})
```

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

### Generate Text with Predefined Google Provider (Node.js)

Source: https://xsai.js.org/docs/packages-ext/providers

Demonstrates generating text using a predefined Google Generative AI provider. It reads the API key from environment variables and requires the '@xsai/generate-text' package. This example is Node.js specific due to environment variable access.

```javascript
import { google } from '@xsai-ext/providers'
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  ...google.chat('gemini-2.5-flash'),
  apiKey: env.GEMINI_API_KEY!,
  baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
  messages: [{ content: 'Why is the sky blue?', role: 'user' }],
  model: 'gemini-2.5-flash',
})

```

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

### Smooth Stream Output with @xsai/utils-stream and @xsai/stream-text

Source: https://xsai.js.org/docs/packages/utils/stream

This example demonstrates how to pipe a text stream through `smoothStream` to control the output rate and chunking. It uses `streamText` from `@xsai/stream-text` to generate an initial text stream, then applies `smoothStream` for a more controlled, user-friendly experience. Requires an OpenAI API key.

```javascript
import { streamText } from '@xsai/stream-text'
import { smoothStream } from '@xsai/utils-stream'
import { env } from 'node:process'

const { textStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'This is a test, so please answer' + '\'The quick brown fox jumps over the lazy dog.\'' + 'and nothing else.',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
})

const smoothTextStream = textStream.pipeThrough(smoothStream({
  delay: 20,
  chunking: 'line',
}))
```

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

### Generate Text with Image Input (JavaScript)

Source: https://xsai.js.org/docs/packages/generate/text

This example shows how to generate text by including an image in the prompt. The user provides a URL for the image, and the model analyzes it to provide a text response. Ensure the model used supports multi-modal inputs.

```javascript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What\'s in this image?' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg',
          },
        },
      ],
    }
  ],
  model: 'gpt-4o',
})

```

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

### Define Tool Object Directly with Zod Schema for LLM Function Calling

Source: https://xsai.js.org/docs/packages/tool

This example demonstrates defining a tool as a plain object, similar to the previous example, but incorporates Zod for schema definition. The Zod schema is used to define the tool's parameters, providing a type-safe way to specify the expected input for the tool.

```typescript
import type { Tool } from '@xsai/shared-chat'
import * as z from 'zod'

const weatherSchema = z.object({
  location: z.string().describe('The location to get the weather for'),
})

const weather: Tool = {
  execute: (input) => JSON.stringify({ location: (input as z.input).location, temperature: 42 }),
  function: {
    description: 'Get the weather in a location',
    name: 'weather',
    parameters: z.toJSONSchema(weatherSchema) as unknown as Tool['function']['parameters'],
    strict: true,
  },
  type: 'function',
} satisfies Tool
```

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

### Create Runtime-Agnostic Google Generative AI Provider

Source: https://xsai.js.org/docs/packages-ext/providers

Shows how to create a runtime-agnostic Google Generative AI provider using the `createGoogleGenerativeAI` function. This method allows you to pass the API key directly, making it suitable for various environments, including potentially browsers (though the example uses Node.js context).

```javascript
import { createGoogleGenerativeAI } from '@xsai-ext/providers/create'
import { generateText } from '@xsai/generate-text'

const google = createGoogleGenerativeAI('YOUR_API_KEY_HERE')

const { text } = await generateText({
  ...google.chat('gemini-2.5-flash'),
  messages: [{ content: 'Why is the sky blue?', role: 'user' }],
})

```

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

### Define and Use Raw Tool with Manual JSON Schema for LLM Function Calling

Source: https://xsai.js.org/docs/packages/tool

This example shows how to define a raw tool using '@xsai/tool' with a manually defined JSON schema for parameters. The 'execute' function parameters need manual type definition. This approach offers more control over the schema structure.

```typescript
import { generateText } from '@xsai/generate-text'
import { rawTool } from '@xsai/tool'
import { env } from 'node:process'

const weather = rawTool<{ location: string }>({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({ location, temperature: 42 }),
  name: 'weather',
  parameters: {
    additionalProperties: false,
    properties: {
      location: {
        description: 'The location to get the weather for',
        type: 'string',
      },
    },
    required: ['location'],
    type: 'object',
  },
});

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  maxSteps: 2,
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  tools: [weather],
});
```

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

### Update Imports from @xsai to xsai

Source: https://xsai.js.org/docs/packages/top-level/xsai

This example demonstrates how to update import statements when migrating to the new xsai package structure. It shows changing imports from scoped packages like '@xsai/generate-text' to the unified 'xsai' package.

```javascript
import { generateText } from '@xsai/generate-text'
import { generateText } from 'xsai'
```

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

### Generate Structured Array Stream with xsAI and Valibot

Source: https://xsai.js.org/docs/packages/stream/object

This example shows how to stream an array of structured data using xsAI and Valibot. It's useful for generating lists of items, such as character descriptions in a game. The `output: 'array'` option combined with a schema for array elements enables this functionality.

```typescript
import { streamObject } from '@xsai/stream-object'
import { env } from 'node:process'
import * as v from 'valibot'

const { elementStream } = await streamObject({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    { content: 'Generate 3 hero descriptions for a fantasy role playing game.', role: 'user' }
  ],
  model: 'gpt-4o',
  output: 'array',
  schema: v.object({
    name: v.string(),
    class: v.pipe(
      v.string(),
      v.description('Character class, e.g. warrior, mage, or thief.'),
    ),
    description: v.string(),
  })
})

for await (const element of elementStream) {
  console.log(element)
}
```

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

### Generate Structured Object Stream with xsAI and Valibot

Source: https://xsai.js.org/docs/packages/stream/object

This example demonstrates how to stream structured object data from an LLM using xsAI and Valibot for schema validation. It requires an OpenAI API key and specifies messages, model, and the expected object schema. The output is a stream of partial objects.

```typescript
import { streamObject } from '@xsai/stream-object'
import { env } from 'node:process'
import * as v from 'valibot'

const { partialObjectStream } = await streamObject({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    { content: 'Extract the event information.', role: 'system' },
    { content: 'Alice and Bob are going to a science fair on Friday.', role: 'user' }
  ],
  model: 'gpt-4o',
  schema: v.object({
    name: v.string(),
    date: v.string(),
    participants: v.array(v.string()),
  })
})

for await (const partialObject of partialObjectStream) {
  console.log(partialObject)
}
```

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

### Generate Speech from Text with @xsai/generate-speech

Source: https://xsai.js.org/docs/packages/generate/speech

Generates audio from input text using the @xsai/generate-speech package. Requires installation via npm, pnpm, yarn, or bun. It takes parameters like baseURL, input text, model, and voice to produce audio output.

```typescript
import { generateSpeech } from '@xsai/generate-speech'
import { Buffer } from 'node:buffer'

const speech = await generateSpeech({
  baseURL: 'http://localhost:5050',
  input: 'Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.',
  model: 'tts-1',
  voice: 'en-US-AnaNeural',
})

const audio = Buffer.from(speech)
```

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

### Verbose Transcription with Word Timestamps using xsAI

Source: https://xsai.js.org/docs/packages/generate/transcription

This example demonstrates how to obtain word-level timestamps during transcription by setting `responseFormat: 'verbose_json'` and `timestampGranularities: 'word'`. The output includes duration, language, text, and a 'words' array with timestamp information for each word.

```javascript
import { generateTranscription } from '@xsai/generate-transcription'
import { openAsBlob } from 'node:fs'

const { duration, language, text, words } = await generateTranscription({
  apiKey: '',
  baseURL: 'http://localhost:8000/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'deepdml/faster-whisper-large-v3-turbo-ct2',
  responseFormat: 'verbose_json',
  timestampGranularities: 'word',
})
```

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

### Define and Use Tool Object Directly without '@xsai/tool' Package

Source: https://xsai.js.org/docs/packages/tool

This example shows how to define a tool as a plain JavaScript object, conforming to the 'Tool' type from '@xsai/shared-chat', without relying on the '@xsai/tool' package. This method is useful for direct integration and avoids package dependencies for the tool definition itself.

```typescript
import type { Tool } from '@xsai/shared-chat'
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const weather: Tool = {
  execute: (({ location }) => JSON.stringify({ location, temperature: 42 })) as Tool['execute'],
  function: {
    description: 'Get the weather in a location',
    name: 'weather',
    parameters: {
      additionalProperties: false,
      properties: {
        location: {
          description: 'The location to get the weather for',
          type: 'string',
        },
      },
      required: ['location'],
      type: 'object',
    },
    strict: true,
  },
  type: 'function',
} satisfies Tool

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  maxSteps: 2,
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  tools: [weather],
});
```

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

### Define Raw Tool with Zod Schema and Convert to JSON Schema

Source: https://xsai.js.org/docs/packages/tool

This example illustrates defining a raw tool using Zod for schema validation and then converting the Zod schema to a JSON schema compatible with the tool definition. It demonstrates how to avoid asynchronous contagion from 'tool' by using 'rawTool' and type casting.

```typescript
import type { RawToolOptions } from '@xsai/tool'
import { rawTool } from '@xsai/tool'
import * as z from 'zod'

const weatherSchema = z.object({
  location: z.string().describe('The location to get the weather for'),
})

const weather = rawTool<z.infer<typeof weatherSchema>>({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({ location, temperature: 42 }),
  name: 'weather',
  parameters: z.toJSONSchema(weatherSchema) as unknown as RawToolOptions['parameters'],
});
```

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

### Create Fetch Instance with xsfetch

Source: https://xsai.js.org/docs/packages-top/xsfetch

Demonstrates how to create a fetch instance using the `createFetch` function from the xsfetch package. This instance is configured with retry attempts and delay.

```javascript
import { createFetch } from 'xsfetch'
const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})
```

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

### Create Fetch Instance with xsfetch

Source: https://xsai.js.org/docs/packages/top-level/xsfetch

Demonstrates how to create a custom fetch instance using the `createFetch` function from the `xsfetch` package. This instance can be configured with retry attempts and delays, improving request robustness.

```javascript
import { createFetch } from 'xsfetch'

const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})
```

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

### xsAI Providers - Create Function Usage

Source: https://xsai.js.org/docs/packages-ext/providers

Shows how to use the `createGoogleGenerativeAI` function for runtime-agnostic provider creation.

```APIDOC
## xsAI Providers - Create Function Usage

### Description
This section demonstrates how to use the `createGoogleGenerativeAI` function. This approach allows for runtime-agnostic provider creation, meaning you can pass your API key directly during instantiation, making it more flexible than relying solely on environment variables.

### Method
Not Applicable (This is a usage example, not an API endpoint).

### Endpoint
Not Applicable

### Parameters
This example uses parameters for the `generateText` function and the `createGoogleGenerativeAI` function.

#### Request Body (for `generateText`)
- **messages** (array) - Required - An array of message objects, each with a `content` (string) and `role` ('user' or 'assistant').
- **model** (string) - Required - The name of the model to use (e.g., 'gemini-2.5-flash').

### Request Example
```javascript
// import { google } from '@xsai-ext/providers'
import { createGoogleGenerativeAI } from '@xsai-ext/providers/create'
import { generateText } from '@xsai/generate-text'

const google = createGoogleGenerativeAI('YOUR_API_KEY_HERE')

const { text } = await generateText({
  ...google.chat('gemini-2.5-flash'),
  messages: [{ content: 'Why is the sky blue?', role: 'user' }],
})
```

### Response
#### Success Response (200)
- **text** (string) - The generated text response from the AI model.

#### Response Example
```json
{
  "text": "The sky appears blue because of how sunlight interacts with Earth's atmosphere..."
}
```
```

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

### xsAI Providers - Predefined Usage

Source: https://xsai.js.org/docs/packages-ext/providers

Demonstrates how to use a predefined Google Generative AI provider, reading the API key from environment variables.

```APIDOC
## xsAI Providers - Predefined Usage

### Description
This section illustrates the usage of predefined providers, specifically the Google Generative AI provider. It highlights that the API key is read from environment variables (`process.env.GEMINI_API_KEY`), making it unsuitable for browser environments.

### Method
Not Applicable (This is a usage example, not an API endpoint).

### Endpoint
Not Applicable

### Parameters
This example uses parameters for the `generateText` function and the `google.chat` configuration.

#### Request Body (for `generateText` and `google.chat`)
- **apiKey** (string) - Required - The API key for the generative AI service.
- **baseURL** (string) - Optional - The base URL for the API service.
- **messages** (array) - Required - An array of message objects, each with a `content` (string) and `role` ('user' or 'assistant').
- **model** (string) - Required - The name of the model to use (e.g., 'gemini-2.5-flash').

### Request Example
```javascript
import { google } from '@xsai-ext/providers'
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  ...google.chat('gemini-2.5-flash'),
  apiKey: env.GEMINI_API_KEY!,
  baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
  messages: [{ content: 'Why is the sky blue?', role: 'user' }],
  model: 'gemini-2.5-flash',
})
```

### Response
#### Success Response (200)
- **text** (string) - The generated text response from the AI model.

#### Response Example
```json
{
  "text": "The sky appears blue due to a phenomenon called Rayleigh scattering..."
}
```
```

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

### Basic Audio Transcription with @xsai/stream-transcription

Source: https://xsai.js.org/docs/packages/stream/transcription

Demonstrates how to perform basic audio transcription using the '@xsai/stream-transcription' package. It requires an API key, base URL, file path, file name, language, and model. Ensure your provider supports streaming.

```javascript
import { streamTranscription } from '@xsai/stream-transcription'
import { openAsBlob } from 'node:fs'

const { textStream } = streamTranscription({
  apiKey: '',
  baseURL: 'https://api.openai.com/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'gpt-4o-transcribe',
})
```

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

### Simulate Readable Stream with @xsai/utils-stream

Source: https://xsai.js.org/docs/packages/utils/stream

This function simulates a readable stream, allowing you to define the chunks and delays for its emission. It's useful for testing stream-based logic without requiring actual external data sources. The function takes an options object with `chunks`, `chunkDelay`, and `initialDelay`.

```javascript
import { simulateReadableStream } from '@xsai/utils-stream'

const stream = simulateReadableStream({
  chunks: [1, 2, 3],
  chunkDelay: 100,
  initialDelay: 0,
})
```

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

### List Available Models with xsAI (JavaScript)

Source: https://xsai.js.org/docs/packages/model

Demonstrates how to list all available models using the `listModels` function from the `@xsai/model` package. It requires an API key and a base URL for the API endpoint. The function returns a list of model objects.

```javascript
import { listModels } from '@xsai/model'
import { env } from 'node:process'

// [
// {
// "id": "model-id-0",
// "object": "model",
// "created": 1686935002,
// "owned_by": "organization-owner"
// },
// {
// "id": "model-id-1",
// "object": "model",
// "created": 1686935002,
// "owned_by": "organization-owner",
// },
// {
// "id": "model-id-2",
// "object": "model",
// "created": 1686935002,
// "owned_by": "openai"
// },
// ]
const models = await listModels({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/'
})

```

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

### Generate Tools from MCP Servers

Source: https://xsai.js.org/docs/integrations/tools/model-context-protocol

A utility function written in TypeScript to retrieve and format tools available from multiple Model Context Protocol (MCP) servers. It maps server tools into a standardized 'function' type, suitable for use with xsAI.

```typescript
import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
import type { Tool } from "@xsai/shared-chat";

export const getTools = (mcpServers: Record<string, Client>): Promise<Tool[]> =>
  Promise.all(
    Object.entries(mcpServers)
      .map(([serverName, client]) =>
        client
          .listTools()
          .then(({ tools }) =>
            tools.map(({ description, inputSchema, name }) => ({
              execute: (args: unknown) =>
                client.callTool({ arguments: args as Record, name })
                  .then((res) => JSON.stringify(res)),
              function: {
                description,
                name: name === serverName ? name : `${serverName}_${name}`,
                parameters: inputSchema,
                strict: true,
              },
              type: "function",
            } satisfies Tool))
          )
      )
  ).then((tools) => tools.flat());

```

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

### Generate Text with Chat Messages in JavaScript

Source: https://xsai.js.org/docs/packages/utils/chat

Demonstrates how to use the '@xsai/generate-text' and '@xsai/utils-chat' packages to generate text with a system and user message. Requires an OpenAI API key and base URL. It utilizes the 'gpt-4o' model.

```javascript
import { generateText } from '@xsai/generate-text'
import { message } from '@xsai/utils-chat'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    { content: 'You\'re a helpful assistant.', role: 'system' },
    message.system('You\'re a helpful assistant.'),
    { content: 'Why is the sky blue?', role: 'user' },
    message.user('Why is the sky blue?'),
  ],
  model: 'gpt-4o',
})

```

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

### Basic Text Streaming with xsAI in JavaScript

Source: https://xsai.js.org/docs/packages/stream/text

Generates text from a prompt using the @xsai/stream-text package. It requires an API key and supports specifying system and user messages. The output is a stream of text parts that are collected into a single string.

```javascript
import { streamText } from '@xsai/stream-text'
import { env } from 'node:process'
const { textStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'This is a test, so please answer' + '\'The quick brown fox jumps over the lazy dog.\'' + 'and nothing else.',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
})
const text: string[] = []
for await (const textPart of textStream) {
  text.push(textPart)
}
// "The quick brown fox jumps over the lazy dog."
console.log(text)
```

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

### Generate Text with Basic Prompt (JavaScript)

Source: https://xsai.js.org/docs/packages/generate/text

This snippet demonstrates how to generate text using a simple text-based prompt. It requires an OpenAI API key and specifies the model and messages for the generation. The output is the generated text content.

```javascript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    { content: 'You\'re a helpful assistant.', role: 'system' },
    { content: 'Why is the sky blue?', role: 'user' }
  ],
  model: 'gpt-4o',
})

```

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

### Audio Input Text Streaming with xsAI in JavaScript

Source: https://xsai.js.org/docs/packages/stream/text

Facilitates text generation from an audio input using the @xsai/stream-text package. This involves fetching an audio file, encoding it to base64, and passing it to the model. It requires specifying the audio format and that the model supports audio modality.

```javascript
import { streamText } from '@xsai/stream-text'
import { Buffer } from 'node:buffer'
import { env } from 'node:process'
const data = await fetch('https://cdn.openai.com/API/docs/audio/alloy.wav')
  .then(res => res.arrayBuffer())
  .then(buffer => Buffer.from(buffer).toString('base64'))
const { textStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is in this recording?'
        },
        {
          type: 'input_audio',
          input_audio: {
            data,
            format: 'wav'
          }
        }
      ]
    }
  ],
  model: 'gpt-4o-audio-preview',
  modalities: ['text', 'audio'],
})
```

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

### Define a JSON Schema (jsonSchema)

Source: https://xsai.js.org/docs/packages-top/xsschema

Shows how to define a standard JSON Schema using the `jsonSchema` function from 'xsschema'. This is useful for creating JSON Schemas directly without relying on other schema definition libraries.

```javascript
import { jsonSchema } from 'xsschema'

const schema = jsonSchema({
  type: 'object',
  properties: {
    productId: {
      description: 'The unique identifier for a product',
      type: 'integer'
    }
  }
})
```

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

### Generate Image with xsAI

Source: https://xsai.js.org/docs/packages/generate/image

Generates an image based on a given text prompt using the '@xsai/generate-image' package. Requires an API key and optionally accepts parameters like 'n' for the number of images and 'baseURL'.

```javascript
import { generateImage } from '@xsai/generate-image'
import { env } from 'node:process'

const { image } = await generateImage({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'http://api.openai.com/v1/',
  model: 'dall-e-3',
  prompt: 'A cute baby sea otter'
})

const { images } = await generateImage({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'http://api.openai.com/v1/',
  n: 4,
  model: 'dall-e-3',
  prompt: 'A cute baby sea otter'
})
```

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

### Generate Text with Audio Input (JavaScript)

Source: https://xsai.js.org/docs/packages/generate/text

This snippet illustrates generating text from an audio input. The audio data is fetched, converted to base64, and then passed to the `generateText` function along with the audio format. This requires a model that supports audio modalities.

```javascript
import { generateText } from '@xsai/generate-text'
import { Buffer } from 'node:buffer'
import { env } from 'node:process'

const data = await fetch('https://cdn.openai.com/API/docs/audio/alloy.wav')
  .then(res => res.arrayBuffer())
  .then(buffer => Buffer.from(buffer).toString('base64'))

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is in this recording?' },
        { type: 'input_audio', input_audio: { data, format: 'wav' }}
      ],
    }
  ],
  model: 'gpt-4o-audio-preview',
  modalities: ['text', 'audio'],
})

```

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

### Generate JSON Schema from Various Libraries (toJsonSchema)

Source: https://xsai.js.org/docs/packages-top/xsschema

Demonstrates using the `toJsonSchema` function from 'xsschema' to convert schemas defined in popular libraries (ArkType, Effect Schema, Sury, Valibot, Zod) into JSON Schema format. It shows the import statements and the asynchronous call to `toJsonSchema` for each library.

```javascript
import { type } from 'arktype'
import { Schema } from 'effect'
import * as S from 'sury'
import * as v from 'valibot'
import { toJsonSchema } from 'xsschema'
import { z } from 'zod'

const arktypeSchema = type({
  myString: 'string',
  myUnion: 'number | boolean',
}).describe('My neat object schema')
const arktypeJsonSchema = await toJsonSchema(arktypeSchema)

const effectSchema = Schema.standardSchemaV1(
  Schema.Struct({
    myString: Schema.String,
    myUnion: Schema.Union(Schema.Number, Schema.Boolean),
  }).annotations({
    description: 'My neat object schema',
  })
)
const effectJsonSchema = await toJsonSchema(effectSchema)

const surySchema = S.schema({
  myString: S.string,
  myUnion: S.union([
    S.number,
    S.boolean
  ]),
}).with(S.meta, {
  description: 'My neat object schema',
})
const suryJsonSchema = await toJsonSchema(surySchema)

const valibotSchema = v.pipe(
  v.object({
    myString: v.string(),
    myUnion: v.union([
      v.number(),
      v.boolean()
    ]),
  }),
  v.description('My neat object schema'),
)
const valibotJsonSchema = await toJsonSchema(valibotSchema)

const zodSchema = z.object({
  myString: z.string(),
  myUnion: z.union([
    z.number(),
    z.boolean()
  ]),
}).describe('My neat object schema')
const zodJsonSchema = await toJsonSchema(zodSchema)
```

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

### Text Generation with Audio Input

Source: https://xsai.js.org/docs/packages/generate/text

This endpoint allows for text generation using audio input, enabling transcription and analysis of spoken content.

```APIDOC
## POST /generateText (with Audio Input)

### Description
Generates text for a given prompt that includes audio input. The model can transcribe and understand the audio content to provide a relevant text response.

### Method
POST

### Endpoint
/generateText

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your API key for authentication.
- **baseURL** (string) - Required - The base URL for the API endpoint.

#### Request Body
- **messages** (array) - Required - An array of message objects. For audio input, the 'user' message `content` should be an array including `type: 'text'` and `type: 'input_audio'`.
  - **content** (array)
    - **type** (string) - 'text' or 'input_audio'.
    - **text** (string) - The text part of the message (if type is 'text').
    - **input_audio** (object) - Contains the audio data and format (if type is 'input_audio').
      - **data** (string) - Base64 encoded audio data.
      - **format** (string) - The format of the audio (e.g., 'wav').
- **model** (string) - Required - The AI model to use (must support audio input, e.g., 'gpt-4o-audio-preview').
- **modalities** (array) - Required - Specifies the supported modalities for the model, including 'audio'.

### Request Example
```json
{
  "apiKey": "YOUR_API_KEY",
  "baseURL": "https://api.openai.com/v1/",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this recording?"
        },
        {
          "type": "input_audio",
          "input_audio": {
            "data": "BASE64_ENCODED_AUDIO_DATA_HERE",
            "format": "wav"
          }
        }
      ]
    }
  ],
  "model": "gpt-4o-audio-preview",
  "modalities": ["text", "audio"]
}
```

### Response
#### Success Response (200)
- **text** (string) - The generated text response based on the audio content and prompt.

#### Response Example
```json
{
  "text": "The recording contains a segment of speech discussing..."
}
```
```

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

### Speech Generation API

Source: https://xsai.js.org/docs/packages/generate/speech

Generates audio from input text using various models and voices.

```APIDOC
## POST /generate-speech

### Description
Generates audio from the input text using a specified model and voice.

### Method
POST

### Endpoint
/generate-speech

### Parameters
#### Query Parameters
- **baseURL** (string) - Required - The base URL for the xsAI API.

#### Request Body
- **input** (string) - Required - The text to be converted into speech.
- **model** (string) - Required - The speech synthesis model to use (e.g., 'tts-1').
- **voice** (string) - Required - The voice to use for synthesis (e.g., 'en-US-AnaNeural').

### Request Example
```json
{
  "input": "Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.",
  "model": "tts-1",
  "voice": "en-US-AnaNeural"
}
```

### Response
#### Success Response (200)
- **audio** (Buffer) - The generated audio data.

#### Response Example
```json
{
  "audio": "<audio data>"
}
```
```

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

### Define a standard JSON Schema with xsSchema

Source: https://xsai.js.org/docs/packages/top-level/xsschema

Shows how to define a JSON Schema using the `jsonSchema` function provided by xsSchema. This function helps in creating schemas that adhere to the JSON Schema specification.

```javascript
import { jsonSchema } from 'xsschema'

const schema = jsonSchema({
  type: 'object',
  properties: {
    productId: {
      description: 'The unique identifier for a product',
      type: 'integer',
    },
  },
})
```

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

### Extract Reasoning from Text Stream

Source: https://xsai.js.org/docs/packages/utils/reasoning

Illustrates the usage of `extractReasoningStream` to process a stream of text, extracting XML-tagged reasoning sections as they become available. This is useful for real-time analysis of streaming LLM responses. It utilizes the `@xsai/stream-text` package.

```javascript
import { streamText } from '@xsai/stream-text'
import { extractReasoningStream } from '@xsai/utils-reasoning'
import { env } from 'node:process'

const { textStream: rawTextStream } = streamText({
  baseURL: 'http://localhost:11434/v1/',
  messages: [
    { content: 'You\'re a helpful assistant.', role: 'system' },
    { content: 'Why is the sky blue?', role: 'user' },
  ],
  model: 'qwen3',
})

const { reasoningStream, textStream } = extractReasoningStream(rawTextStream)

```

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

### Convert Stream to Async Iterator with @xsai/utils-stream

Source: https://xsai.js.org/docs/packages/utils/stream

This utility converts a `ReadableStream` into an `AsyncIterableIterator`, providing a polyfill for environments like Safari that may have limited `ReadableStream` compatibility. It's useful for iterating over stream data using `for await...of` loops.

```javascript
import { simulateReadableStream, toAsyncIterator } from '@xsai/utils-stream'

const stream = simulateReadableStream({
  chunks: [1, 2, 3],
  chunkDelay: 100,
  initialDelay: 0,
})

const iterableStream = toAsyncIterator(stream)
```