### Prompt Example with Roles and Content

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Provides an example of constructing a prompt with specific roles and content, demonstrating the structure expected by the language model.

```typescript
import { LanguageModelPrompt } from "@electron/llm";

const prompt: LanguageModelPrompt = {
  role: "user",
  content: {
    type: "text",
    text: "Hello, how are you?",
  },
};

const response = await model.prompt(prompt);
```

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

### Prompt Example with System Role

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Demonstrates using the 'system' role in a prompt to provide instructions or context to the language model before user interactions begin. This helps guide the model's behavior.

```typescript
import { LanguageModelPrompt } from "@electron/llm";

const systemPrompt: LanguageModelPrompt = {
  role: "system",
  content: { type: "text", text: "You are a helpful assistant." },
};

const userPrompt: LanguageModelPrompt = {
  role: "user",
  content: { type: "text", text: "Tell me a joke." },
};

const response = await model.prompt([systemPrompt, userPrompt]);
```

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

### Create Language Model with System Prompt

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Configure a system prompt to guide the model's behavior and personality.

```typescript
await window.electronAi.create({
  modelAlias: 'my-model',
  systemPrompt: `You are a helpful coding assistant.
Answer programming questions concisely.
Use code examples when appropriate.`
})
```

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

### Prompt Example with Multiple Content Parts

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Illustrates creating a prompt that includes multiple parts of content, such as text and potentially other types in the future. This allows for richer input.

```typescript
import { LanguageModelPrompt } from "@electron/llm";

const prompt: LanguageModelPrompt = {
  role: "user",
  content: [
    { type: "text", text: "What is the capital of France?" },
    { type: "text", text: "Please provide the answer in a single word." },
  ],
};

const response = await model.prompt(prompt);
```

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

### startAiModel

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/main-process.md

Starts the AI model in a utility process. This function returns a UtilityProcess object that can be used to interact with the running AI model.

```APIDOC
## startAiModel

### Description
Initiates and starts the AI model within a dedicated utility process. This function returns a handle to the utility process for further interaction.

### Method
`async function`

### Returns
- `Promise<UtilityProcess>` - A promise that resolves with the `UtilityProcess` object representing the running AI model.
```

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

### Install @electron/llm Module

Source: https://github.com/electron/llm/blob/main/README.md

Install the @electron/llm package using npm. This is the first step to integrating LLM capabilities into your Electron app.

```bash
npm i --save @electron/llm
```

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

### Load Electron LLM with Default Options

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Demonstrates the basic usage of loading the Electron LLM with default configuration. Ensure the necessary setup for the main process is completed before calling this function.

```typescript
import { loadElectronLlm } from "@electron/llm";

await loadElectronLlm();
```

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

### Handle Streaming Port Errors

Source: https://github.com/electron/llm/blob/main/_autodocs/errors.md

Ensure the model is created before calling `promptStreaming()`. This example shows the correct usage after initialization to avoid 'AI model process not started' errors.

```typescript
// Correct usage
await window.electronAi.create({ modelAlias: 'my-model' })
const iterator = await window.electronAi.promptStreaming('Hello')  // OK
```

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

### Create Language Model Instance

Source: https://github.com/electron/llm/blob/main/_autodocs/types.md

Example of how to create a language model instance with specific configuration options. Use this to set the model alias, system prompt, initial conversation context, and control output randomness and diversity.

```typescript
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  systemPrompt: 'You are a helpful assistant.',
  initialPrompts: [
    {
      role: LanguageModelPromptRole.USER,
      type: LanguageModelPromptType.TEXT,
      content: 'Previous question?'
    },
    {
      role: LanguageModelPromptRole.ASSISTANT,
      type: LanguageModelPromptType.TEXT,
      content: 'Previous answer.'
    }
  ],
  temperature: 0.5,
  topK: 40
})
```

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

### Constructing LanguageModelPrompt Objects

Source: https://github.com/electron/llm/blob/main/_autodocs/types.md

Provides examples of how to construct LanguageModelPrompt objects using different roles and types. Note that only TEXT type is currently supported.

```typescript
const systemPrompt: LanguageModelPrompt = {
  role: LanguageModelPromptRole.SYSTEM,
  type: LanguageModelPromptType.TEXT,
  content: 'You are a helpful coding assistant.'
}
```

```typescript
const userMessage: LanguageModelPrompt = {
  role: LanguageModelPromptRole.USER,
  type: LanguageModelPromptType.TEXT,
  content: 'How do I write a for loop in Python?'
}
```

```typescript
const assistantResponse: LanguageModelPrompt = {
  role: LanguageModelPromptRole.ASSISTANT,
  type: LanguageModelPromptType.TEXT,
  content: 'A for loop in Python iterates over a sequence...'
}
```

```typescript
const textPrompt: LanguageModelPrompt = {
  role: LanguageModelPromptRole.USER,
  type: LanguageModelPromptType.TEXT,
  content: 'What is machine learning?'
}
```

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

### Create Language Model Instance

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/renderer-api.md

Loads a new language model. This must be called before sending prompts. Example shows loading an alternative model.

```typescript
await window.electronAi.create({
  modelAlias: 'another-model'
})
```

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

### Custom Model Resolution Example

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Demonstrates how to use a custom `getModelPath` function within `loadElectronLlm` to resolve model paths, such as fetching from a remote source or implementing custom logic.

```typescript
await loadElectronLlm({
  getModelPath: async (alias) => {
    // Custom logic: fetch from remote, check permissions, etc.
    return '/path/to/model.gguf'
  }
})
```

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

### Main Module Exports

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Exports available specifically from the '/main' module of '@electron/llm'. This includes the LLM loading function and a function to start the AI model.

```APIDOC
## Module Exports from `@electron/llm/main`

### Functions
- `loadElectronLlm`
- `startAiModel`

### Types
- All types from interfaces
```

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

### Importing TypeScript Types and Functions

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Import necessary types and functions from the main '@electron/llm' entry point for TypeScript development. Ensure you have the package installed.

```typescript
import {
  loadElectronLlm,
  LanguageModelCreateOptions,
  LanguageModelPromptOptions,
  LanguageModelPrompt,
  LanguageModelPromptRole,
  LanguageModelPromptType,
  ElectronLlmRenderer
} from '@electron/llm'
```

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

### Starting AI Model Utility Process

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/main-process.md

Spawns a new utility process for running the language model. It configures stdio for logging and handles process exit events. This function is part of the public API.

```typescript
const aiProcess = utilityProcess.fork(utilityScriptPath, [], {
  stdio: ['ignore', 'pipe', 'pipe', 'pipe'],
})

// Output handling
if (aiProcess.stdout) {
  aiProcess.stdout.on('data', (data) => {
    console.info(`AI model child process stdout: ${data}`)
  })
}

if (aiProcess.stderr) {
  aiProcess.stderr.on('data', (data) => {
    console.error(`AI model child process stderr: ${data}`)
  })
}

aiProcess.on('exit', () => {
  console.info('AI model child process exited.')
})

return aiProcess
```

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

### Handle Runtime Errors During AI Creation

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

This example shows how to catch and handle runtime errors, such as a missing model path or timeouts, that occur during the AI creation process via IPC.

```typescript
try {
  await window.electronAi.create({ modelAlias: 'model' })
} catch (error) {
  if (error.message.includes('Model path not found')) {
    // Handle missing model
  } else if (error.message.includes('timed out')) {
    // Handle timeout
  } else {
    // Generic error handling
  }
}
```

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

### Start AI Model Utility Process

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Spawns a utility process for AI model inference. This is typically called internally by `registerAiHandlers()` and not directly by users.

```typescript
export async function startAiModel(): Promise<UtilityProcess>
```

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

### Configure Environment-Based Model Path Resolution

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

This example demonstrates how to dynamically set the `getModelPath` function based on environment variables and whether the application is in development or production mode.

```typescript
import { app } from 'electron'
import { loadElectronLlm } from '@electron/llm'
import path from 'path'
import fs from 'fs'

const MODELS_ENV = process.env.LLM_MODELS_PATH
const isDevelopment = !app.isPackaged

app.on('ready', async () => {
  let getModelPath

  if (isDevelopment && MODELS_ENV) {
    // Use environment variable in development
    getModelPath = (modelAlias) => {
      const modelPath = path.join(MODELS_ENV, modelAlias)
      return fs.existsSync(modelPath) ? modelPath : null
    }
  } else {
    // Use default resolver in production
    getModelPath = undefined
  }

  await loadElectronLlm({ getModelPath })
})
```

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

### Configure Model Alias Mapping with getModelPath

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

This example demonstrates using `getModelPath` to map model aliases to specific file paths, allowing for a flexible way to reference different models.

```typescript
import { loadElectronLlm } from '@electron/llm'
import path from 'path'

const modelMap: Record<string, string> = {
  'small': '/models/phi-2.gguf',
  'medium': '/models/llama-3-8b.gguf',
  'large': '/models/llama-3-70b.gguf',
}

await loadElectronLlm({
  getModelPath: (modelAlias) => {
    return modelMap[modelAlias] || null
  }
})
```

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

### Configure Remote Model Resolution with getModelPath

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

This example shows how to implement `getModelPath` to check for locally cached models before potentially downloading them from a remote source, optimizing model loading.

```typescript
import { loadElectronLlm } from '@electron/llm'
import fs from 'fs'
import path from 'path'

await loadElectronLlm({
  getModelPath: async (modelAlias) => {
    const localPath = path.join(process.env.HOME, '.cache/llm-models', modelAlias)
    
    // Check if model is cached locally
    if (fs.existsSync(localPath)) {
      return localPath
    }
    
    // Could download from remote source here
    // For now, return null if not available
    console.warn(`Model ${modelAlias} not found locally`)
    return null
  }
})
```

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

### Use LLM Module in Renderer Process

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Interact with the LLM module from your renderer process. Models are available via `window.electronAi`. This example shows creating a model, sending a prompt, streaming responses, and cleaning up.

```typescript
// Model is automatically available as window.electronAi

// Create a model
await window.electronAi.create({
  modelAlias: 'llama-3-8b'
})

// Send a prompt
const response = await window.electronAi.prompt('What is AI?')
console.log(response)

// Or stream chunks
const iterator = await window.electronAi.promptStreaming(
  'Tell me a story'
)
for await (const chunk of iterator) {
  process.stdout.write(chunk)
}

// Clean up
await window.electronAi.destroy()
```

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

### Configure Custom Model Directory for getModelPath

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

This example shows how to provide a custom function to `getModelPath` to load models from a specific directory, ensuring the model file exists before returning its path.

```typescript
import { app } from 'electron'
import { loadElectronLlm } from '@electron/llm'
import path from 'path'
import fs from 'fs'

app.on('ready', async () => {
  await loadElectronLlm({
    getModelPath: async (modelAlias) => {
      // Load models from custom directory
      const modelsDir = '/opt/llm-models'
      const modelPath = path.join(modelsDir, modelAlias)
      
      // Validate file exists
      try {
        await fs.promises.access(modelPath, fs.constants.F_OK)
        return modelPath
      } catch {
        return null
      }
    }
  })
})
```

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

### Constrain AI Response with JSON Schema

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

This example demonstrates how to use the `responseJSONSchema` option to guide the AI into returning a response that conforms to a specified JSON structure. The response is then parsed.

```typescript
const response = await window.electronAi.prompt(
  'Extract name and age from: John is 30',
  {
    responseJSONSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' }
      },
      required: ['name', 'age']
    }
  }
)

const data = JSON.parse(response)
console.log(data.name, data.age)
```

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

### Basic Usage in Main Process

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/loadElectronLlm.md

Demonstrates how to load the Electron LLM module with default options in the main process upon application readiness.

```typescript
import { app } from 'electron'
import { loadElectronLlm } from '@electron/llm'

app.on('ready', async () => {
  // Load the module with default options
  await loadElectronLlm()
  
  // Create your browser window
  const window = new BrowserWindow()
  window.loadURL('app://index.html')
})
```

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

### loadElectronLlm

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Initializes the module in the main process. Sets up IPC handlers and preload script registration.

```APIDOC
## loadElectronLlm()

### Description
Initializes the module in the main process. Sets up IPC handlers and preload script registration.

### Method
`async function`

### Endpoint
Main entry point (`@electron/llm`), Main Process Entry (`@electron/llm/main`)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options.isAutomaticPreloadDisabled** (boolean, optional) - 
- **options.getModelPath** (function, optional) - 

### Request Example
```typescript
import {
  app
} from 'electron'
import {
  loadElectronLlm
} from '@electron/llm'

app.on('ready', async () => {
  await loadElectronLlm()
  createBrowserWindow()
})
```

### Response
#### Success Response (void)
Returns a Promise that resolves when the module is initialized.

#### Response Example
None (void return type)
```

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

### window.electronAi.create()

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Creates and initializes a language model instance with specified options.

```APIDOC
## window.electronAi.create()

### Description
Creates and initializes a language model instance.

### Method
`create`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (object, required)
  - **modelAlias** (string, required) - Alias of the language model to create.
  - **systemPrompt** (string, optional) - The system prompt to use for the model.
  - **initialPrompts** (array, optional) - An array of initial prompts.
  - **topK** (number, optional) - The top-k sampling parameter. Defaults to 10.
  - **temperature** (number, optional) - The temperature sampling parameter. Defaults to 0.7.
  - **requestUUID** (string, optional) - A unique identifier for the request.

### Request Example
```javascript
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  temperature: 0.7,
  topK: 40
})
```

### Response
#### Success Response (void)
This method returns a void promise upon successful creation.

#### Response Example
```json
// No response body for void promise
```
```

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

### startAiModel()

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/main-process.md

Spawns a new utility process to run the language model. This function returns an Electron UtilityProcess instance representing the spawned process, which communicates via IPC messages.

```APIDOC
## startAiModel()

### Description
Spawns a new utility process that runs the language model. The utility process is isolated from the main process and communicates via IPC messages.

### Method
`async`

### Return Value
- `UtilityProcess`: An instance from Electron that represents the spawned process.

### Behavior
- Spawns a child process using `utilityProcess.fork` with the script `src/utility/call-ai-model-entry-point.js`.
- Configures stdio to `['ignore', 'pipe', 'pipe', 'pipe']` to capture stdout and stderr.
- Logs stdout as info-level messages and stderr as error-level messages.
- Logs when the AI model child process exits.

### Error Handling
This function does not throw errors directly. Errors may occur if the child script fails, leading to the returned `UtilityProcess` emitting error events or exiting unexpectedly.
```

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

### Handle Model Not Created Error

Source: https://github.com/electron/llm/blob/main/_autodocs/errors.md

Catch the 'AI model process not started' error and ensure the model is created before prompting.

```typescript
// Error: Model not created
const response = await window.electronAi.prompt('Hello')
// Throws Error

// Correct usage
await window.electronAi.create({ modelAlias: 'my-model' })
const response = await window.electronAi.prompt('Hello')  // OK
```

```typescript
try {
  const response = await window.electronAi.prompt('Hello')
} catch (error) {
  if (error instanceof Error && error.message.includes('not started')) {
    console.error('Create model first')
    await window.electronAi.create({ modelAlias: 'my-model' })
  }
}
```

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

### Main Process Module Exports

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/main-process.md

These are the primary functions exported from the main process module for loading and starting the AI model.

```typescript
export async function loadElectronLlm(options?: LoadOptions): Promise<void>
export async function startAiModel(): Promise<UtilityProcess>
export * from '../interfaces.js'
```

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

### Initialize and Chat with Model in Renderer

Source: https://github.com/electron/llm/blob/main/README.md

Initialize the language model in the renderer process using window.electronAi.create, specifying the model path. Then, interact with the model using window.electronAi.prompt.

```javascript
// First, load the model
await window.electronAi.create({
  modelPath: "/full/path/to/model.gguf"
})

// Then, talk to it
const response = await window.electronAi.prompt("Hi! How are you doing today?")
```

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

### Main Process API: loadElectronLlm

Source: https://github.com/electron/llm/blob/main/README.md

Loads the LLM module in the main process. This should be called before loading any windows to ensure the window.electronAi API is available in renderers.

```APIDOC
## loadElectronLlm

### Description
Loads the LLM module in the main process. This function should be called early in your application's lifecycle, before windows are created, to ensure the renderer process API (`window.electronAi`) is properly injected.

### Method
`loadElectronLlm(options?: LoadOptions): Promise<void>`

### Parameters
#### Options
- **isAutomaticPreloadDisabled** (boolean) - Optional - If true, the automatic preload script injection is disabled.
- **getModelPath** (function) - Optional - A function that takes a model alias and returns the full path to the GGUF model file. Defaults to `path.join(app.getPath('userData'), 'models', modelAlias)`.

### Request Example
```javascript
import { app } from "electron"
import { loadElectronLlm } from "@electron/llm"

app.on("ready", async () => {
  await loadElectronLlm({
    getModelPath: (alias) => `/path/to/models/${alias}.gguf`
  })
  // ... create browser window
})
```

### Response
This function returns a Promise that resolves when the module is loaded.
```

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

### Set a Short Timeout for Prompt

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Use a short timeout to ensure quick responses. This example sets a 5-second timeout for a simple prompt.

```typescript
const response = await window.electronAi.prompt(
  'What is 2 + 2?',
  { timeout: 5000 }  // 5 seconds
)
```

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

### Load Electron LLM in Main Process

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Initialize the module in the main process. This sets up IPC handlers and preload script registration. Use this when the application is ready.

```typescript
import { app } from 'electron'
import { loadElectronLlm } from '@electron/llm'

app.on('ready', async () => {
  await loadElectronLlm()
  createBrowserWindow()
})
```

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

### Import Main Entry Point

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Import the primary entry point for most applications from the main @electron/llm package.

```typescript
import { loadElectronLlm } from '@electron/llm'
```

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

### window.electronAi.prompt()

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Sends a prompt to the language model and returns the complete response as a string.

```APIDOC
## window.electronAi.prompt()

### Description
Sends a prompt and returns the complete response as a string.

### Method
`prompt`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **input** (string, required) - The prompt to send to the model.
- **options** (object, optional)
  - **timeout** (number, optional) - The timeout for the request in milliseconds. Defaults to 20000.
  - **requestUUID** (string, optional) - A unique identifier for the request.
  - **responseJSONSchema** (object, optional) - A JSON schema to validate the response against.

### Request Example
```javascript
const response = await window.electronAi.prompt('What is AI?', {
  timeout: 30000
})
```

### Response
#### Success Response (string)
- **response** (string) - The complete response from the language model.

#### Response Example
```json
"The response from the AI model."
```
```

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

### Set a Long Timeout for Prompt

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Use a long timeout for complex generation tasks. This example sets a 2-minute timeout for a detailed essay prompt.

```typescript
const response = await window.electronAi.prompt(
  'Write a detailed essay...', 
  { timeout: 120000 }  // 2 minutes
)
```

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

### Import Main Process Entry Point

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Import specific exports for main process code from the @electron/llm/main package.

```typescript
import { loadElectronLlm, startAiModel } from '@electron/llm/main'
```

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

### Send Prompt and Get Response

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Sends a user prompt to the language model and retrieves the full response as a string. Supports custom timeouts for the request.

```typescript
const response = await window.electronAi.prompt('What is AI?', {
  timeout: 30000
})
```

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

### loadElectronLlm

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Initializes the Electron LLM functionality. This is typically the first step before using other API features.

```APIDOC
## loadElectronLlm

### Description
Initializes the Electron LLM functionality. This function must be called before any other Electron LLM API functions can be used.

### Method
(Not specified, likely a direct function call in the main process)

### Endpoint
(Not applicable, SDK function)

### Parameters
(No specific parameters documented in the source for this function, but configuration options are mentioned elsewhere)

### Request Example
```javascript
// Example usage in the main process
loadElectronLlm();
```

### Response
(No specific response documented, assumed to be a success/failure indicator or void)

```

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

### Constrain Response to Array Schema

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Use responseJSONSchema to constrain the model's response to an array format. This example requests a list of 3 programming languages.

```typescript
const response = await window.electronAi.prompt(
  'List 3 programming languages',
  {
    responseJSONSchema: {
      type: 'array',
      items: { type: 'string' }
    }
  }
)
```

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

### Create a Language Model Instance

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Demonstrates how to create an instance of a LanguageModel using the `create` method. This instance can then be used to interact with the language model.

```typescript
import { ElectronLlm } from "@electron/llm";

const model = await ElectronLlm.create("my-model-name");
```

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

### Track and Cancel Prompt with requestUUID

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Utilize requestUUID to track and cancel a prompt request. This example generates a UUID, initiates a prompt, and cancels it after 10 seconds.

```typescript
const promptId = crypto.randomUUID()

const promptPromise = window.electronAi.prompt(
  'Generate very long text...', 
  { requestUUID: promptId }
)

// Cancel after 10 seconds
setTimeout(() => {
  window.electronAi.abortRequest(promptId)
}, 10000)

try {
  const response = await promptPromise
} catch (error) {
  console.log('Prompt was cancelled')
}
```

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

### Renderer to Main: Initialization Request

Source: https://github.com/electron/llm/blob/main/_autodocs/architecture.md

The Renderer process initiates the LLM by sending an IPC message to the Main process. The Main process then forks a Utility process to load the model.

```mermaid
Renderer                Main                    Utility
  │                      │                       │
  ├─ window.electronAi ──►                      │
  │   (preload inject)    │                      │
  │                       │ loadElectronLlm()    │
  │                       ├─ register handlers   │
  │                       │ (no process yet)     │
  │                       │                      │
  │ create()             │                      │
  ├──────────IPC────────►│                      │
  │ (ELECTRON_LLM_CREATE) │ fork() ─────────────►│
  │                       │                 load model
  │                       │◄────ack (port)───────┤
  │◄──────────ack────────┤                      │
  │ (model ready)         │                      │
```

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

### Constrain Response to Simple Object Schema

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Use responseJSONSchema to constrain the model's response to a simple object format. This example extracts name and age from text.

```typescript
const response = await window.electronAi.prompt(
  'Extract name and age from: John is 30 years old',
  {
    responseJSONSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' }
      },
      required: ['name', 'age']
    }
  }
)
```

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

### create()

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/renderer-api.md

Creates and initializes a language model instance. It manages a single utility process and loaded model, handling updates if new options are provided.

```APIDOC
## create()

### Description

Creates and initializes a language model instance. The module maintains at most one utility process with one loaded model. Calling `create()` multiple times with identical options returns the existing instance. Calling it with different options stops the previous model and loads the new one.

### Method

```typescript
create(options: LanguageModelCreateOptions): Promise<void>
```

### Parameters

#### Path Parameters

* None

#### Query Parameters

* None

#### Request Body

* **options** (LanguageModelCreateOptions) - Required - Configuration for the language model. Must include `modelAlias`.

### LanguageModelCreateOptions Type

```typescript
interface LanguageModelCreateOptions {
  modelAlias: string;
  systemPrompt?: string;
  initialPrompts?: LanguageModelPrompt[];
  topK?: number;
  temperature?: number;
  requestUUID?: string;
}
```

| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| modelAlias | string | Yes | — | Name of the model to load. Passed to the `getModelPath` function configured in main process. |
| systemPrompt | string | No | — | System prompt to initialize the model with, providing context or instructions for the model's behavior. |
| initialPrompts | LanguageModelPrompt[] | No | — | Array of initial prompts to provide conversation context. Each prompt has a `role` (SYSTEM, USER, ASSISTANT), `type` (TEXT, IMAGE, AUDIO), and `content`. |
| topK | number | No | 10 | Controls diversity of generated text. Higher values increase diversity; valid range typically 1-100. |
| temperature | number | No | 0.7 | Controls randomness of generated text. Range 0 (deterministic) to 2+ (very random). Lower values = more focused. |
| requestUUID | string | No | — | Optional UUID to identify and cancel this request using `abortRequest()`. |

### Response

#### Success Response (200)

* **None** - Resolves when the model is successfully loaded and ready for prompting.

#### Response Example

* None (Promise<void>)

### Throws

* **TypeError**: If `modelAlias` is missing or not a string.
* **TypeError**: If `systemPrompt` is provided but not a string.
* **TypeError**: If `initialPrompts` is provided but not an array.
* **TypeError**: If `topK` is provided but not a positive number.
* **TypeError**: If `temperature` is provided but not a non-negative number.
* **Error**: If the model path cannot be resolved for the given `modelAlias`.
* **Error**: If the model fails to load in the utility process.
* **Error**: If model loading times out (60 second limit).

### Usage Example

```typescript
// Basic model creation
await window.electronAi.create({
  modelAlias: 'llama-3-8b'
})

// With system prompt and initial context
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  systemPrompt: 'You are a helpful coding assistant.',
  temperature: 0.3,
  topK: 50
})

// With initial conversation history
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  initialPrompts: [
    {
      role: 'system',
      type: 'text',
      content: 'You are an expert Python programmer.'
    },
    {
      role: 'user',
      type: 'text',
      content: 'What is a generator in Python?'
    },
    {
      role: 'assistant',
      type: 'text',
      content: 'A generator is a function that yields values lazily...'
    }
  ]
})

// With cancellation support
const requestId = crypto.randomUUID()
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  requestUUID: requestId
})
```
```

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

### Create Language Model Instance

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Initializes a language model. Use this to set up the model with specific aliases and parameters before making prompts. Ensure `modelAlias` is provided.

```typescript
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  temperature: 0.7,
  topK: 40
})
```

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

### LLM Memory Lifecycle

Source: https://github.com/electron/llm/blob/main/_autodocs/architecture.md

Illustrates the lifecycle of an LLM model in memory, from creation to destruction, including process forking and garbage collection.

```text
create() called
    │
    ├─► Main: fork() utility process
    │
    ├─► Utility: LanguageModel.create()
    │   ├─ Load model into memory (~GB)
    │   ├─ Create context
    │   └─ Initialize chat session
    │
    ├─► Ready for prompts
    │   (memory stays allocated)
    │
    └─► destroy() called
        ├─ Utility: model.destroy()
        │   ├─ Clear session reference
        │   ├─ Clear context reference
        │   └─ GC reclaims model memory
        │
        ├─ Main: kill utility process
        │   └─ OS reclaims all process memory
        │
        └─ Renderer: ready for new model
```

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

### loadElectronLlm()

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/loadElectronLlm.md

Initializes the Electron LLM module. It automatically detects the process type and loads the appropriate implementation. Configuration options can be provided to customize its behavior, such as disabling automatic preload injection or providing a custom model path resolver.

```APIDOC
## loadElectronLlm()

### Description
Main entry point function to initialize the Electron LLM module. This function automatically detects the current process type (main, renderer, or preload) and loads the appropriate implementation.

### Signature
```typescript
export async function loadElectronLlm(options?: LoadOptions): Promise<void>
```

### Parameters
#### options (LoadOptions) - Optional
Configuration options for loading the module. When not provided, uses default behavior with automatic preload injection enabled.

##### LoadOptions Type
- **isAutomaticPreloadDisabled** (boolean) - Optional - Default: `false` - If true, disables automatic injection of the preload script. Useful if you want to handle preload script injection manually.
- **getModelPath** ((modelAlias: string) => Promise<string | null> | string | null) - Optional - Custom function to resolve model aliases to file paths. By default, resolves to `{userData}/models/{modelAlias}`. Should return the full path to a GGUF model file, or null if the model cannot be found.

### Return Value
Returns a `Promise<void>` that resolves when the module has been successfully loaded.

### Throws
- **Error**: When called in an unsupported process type (anything other than 'main', 'renderer', or 'preload').

### Behavior by Process Type
- **Main Process**: Registers the preload script, sets up IPC handlers, and initializes the model path resolver.
- **Renderer Process**: Throws an error, instructing to load via preload.
- **Preload Process**: Exposes the `window.electronAi` global API via context bridge.

### Usage Examples
#### Basic Usage in Main Process
```typescript
import { app } from 'electron'
import { loadElectronLlm } from '@electron/llm'

app.on('ready', async () => {
  await loadElectronLlm()
  const window = new BrowserWindow()
  window.loadURL('app://index.html')
})
```

#### Custom Model Path Resolver
```typescript
import { loadElectronLlm } from '@electron/llm'
import { app } from 'electron'
import path from 'path'

await loadElectronLlm({
  getModelPath: async (modelAlias) => {
    const customPath = path.join('/opt/models', modelAlias)
    const fs = require('fs')
    
    if (fs.existsSync(customPath)) {
      return customPath
    }
    
    return null
  }
})
```

#### Disable Automatic Preload Injection
```typescript
import { loadElectronLlm } from '@electron/llm'

await loadElectronLlm({
  isAutomaticPreloadDisabled: true
})
```
```

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

### Constrain Response to Complex Nested Schema

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Use responseJSONSchema for complex nested structures. This example defines a schema for planning a trip to Paris, including destination, days, and activities.

```typescript
const response = await window.electronAi.prompt(
  'Plan a trip to Paris',
  {
    responseJSONSchema: {
      type: 'object',
      properties: {
        destination: { type: 'string' },
        days: { type: 'number' },
        activities: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              day: { type: 'number' },
              name: { type: 'string' },
              duration_hours: { type: 'number' }
            }
          }
        }
      },
      required: ['destination', 'days', 'activities']
    }
  }
)
```

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

### Create Language Model with Initial Prompts

Source: https://github.com/electron/llm/blob/main/_autodocs/configuration.md

Establish conversation context using an array of initial prompts, including roles, types, and content.

```typescript
await window.electronAi.create({
  modelAlias: 'my-model',
  initialPrompts: [
    {
      role: 'system',
      type: 'text',
      content: 'You are an expert Python programmer.'
    },
    {
      role: 'user',
      type: 'text',
      content: 'What is a generator?'
    },
    {
      role: 'assistant',
      type: 'text',
      content: 'A generator is a special function that yields values lazily...'
    },
    {
      role: 'user',
      type: 'text',
      content: 'Give me an example.'
    },
    {
      role: 'assistant',
      type: 'text',
      content: 'def count_up(n):\n    for i in range(n):\n        yield i'
    }
  ]
})
```

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

### Main Process Module Exports

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Exports specifically for the main process, including the function to load the LLM and start the AI model. It also re-exports all types defined for interfaces.

```typescript
export { loadElectronLlm, startAiModel }
export { /* All types from interfaces */ }
```

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

### Temperature and TopK Application

Source: https://github.com/electron/llm/blob/main/_autodocs/architecture.md

Shows how temperature and topK parameters are stored within the LanguageModel instance and applied during each prompt call. These parameters influence the generation process.

```plaintext
create({ temperature: 0.5, topK: 40 })
    │
    ├─► Stored in LanguageModel instance
    │
    └─► Applied to each prompt() call:
        model.session.prompt(input, {
          temperature: 0.5,
          topK: 40,
          signal: abortSignal
        })
```

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

### LanguageModelCreateOptions

Source: https://github.com/electron/llm/blob/main/_autodocs/types.md

Configuration options for creating and initializing a language model instance. These options are passed to the `window.electronAi.create()` function to customize the model's behavior and context.

```APIDOC
## LanguageModelCreateOptions (Interface)

### Description
Configuration options for creating and initializing a language model instance. Passed to `window.electronAi.create()`.

### Properties

| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| modelAlias | string | Yes | — | Name of the model to load, passed to the `getModelPath` function |
| systemPrompt | string | No | — | System prompt providing instructions or context for the model |
| initialPrompts | LanguageModelPrompt[] | No | — | Array of initial prompts to establish conversation context |
| topK | number | No | 10 | Controls diversity by limiting selection to top K most likely tokens |
| temperature | number | No | 0.7 | Controls randomness of output (0 = deterministic, higher = more random) |
| requestUUID | string | No | — | UUID for tracking/cancelling this request via `abortRequest()` |

### Validation

- `modelAlias` is required and must be a non-empty string
- `systemPrompt` if provided must be a string
- `initialPrompts` if provided must be an array
- `topK` if provided must be a positive number (> 0)
- `temperature` if provided must be non-negative (>= 0)

### Usage Example

```typescript
await window.electronAi.create({
  modelAlias: 'llama-3-8b',
  systemPrompt: 'You are a helpful assistant.',
  initialPrompts: [
    {
      role: LanguageModelPromptRole.USER,
      type: LanguageModelPromptType.TEXT,
      content: 'Previous question?'
    },
    {
      role: LanguageModelPromptRole.ASSISTANT,
      type: LanguageModelPromptType.TEXT,
      content: 'Previous answer.'
    }
  ],
  temperature: 0.5,
  topK: 40
})
```
```

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

### Implement Request Timeout with Abort

Source: https://github.com/electron/llm/blob/main/_autodocs/errors.md

Set a custom timeout for AI requests to prevent indefinite waiting. This example uses `setTimeout` and `crypto.randomUUID` to manage request cancellation via `window.electronAi.abortRequest`.

```typescript
async function promptWithCustomTimeout(input: string, timeoutMs: number) {
  const abortId = crypto.randomUUID()
  
  const timeoutHandle = setTimeout(() => {
    window.electronAi.abortRequest(abortId)
  }, timeoutMs)
  
  try {
    const response = await window.electronAi.prompt(input, {
      requestUUID: abortId,
      timeout: timeoutMs + 1000  // Give IPC timeout a small buffer
    })
    clearTimeout(timeoutHandle)
    return response
  } catch (error) {
    clearTimeout(timeoutHandle)
    throw error
  }
}
```

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

### LanguageModelCreateOptions

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Options for creating a new language model instance using `window.electronAi.create()`.

```APIDOC
## LanguageModelCreateOptions

Options for `window.electronAi.create()`:

```typescript
interface LanguageModelCreateOptions {
  modelAlias: string;           // Required: name of model to load
  systemPrompt?: string;        // Optional: system prompt
  initialPrompts?: LanguageModelPrompt[];  // Optional: context
  topK?: number;               // Optional: sampling diversity (default: 10)
  temperature?: number;        // Optional: randomness (default: 0.7)
  requestUUID?: string;        // Optional: for cancellation
}
```
```

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

### Main Entry Point Exports

Source: https://github.com/electron/llm/blob/main/_autodocs/README.md

Exports available from the main entry point of the '@electron/llm' package. This includes the primary function to load the LLM and various types for configuration and interaction.

```APIDOC
## Module Exports from `@electron/llm` (main entry)

### Function
- `loadElectronLlm`

### Types
- `LanguageModelPromptRole`
- `LanguageModelPromptType`
- `LanguageModelPromptContent`
- `LanguageModelPrompt`
- `LanguageModelCreateOptions`
- `LanguageModelPromptOptions`
- `ElectronLlmRenderer`
- `ElectronLlmMain`
- `ElectronLlmShared`
- `MainLoadOptions`
- `LoadOptions`
- `GetModelPathFunction`
- ... and more

### Constant
- `IPC_PREFIX`
```

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

### Handle Model Load Timeout Error

Source: https://github.com/electron/llm/blob/main/_autodocs/errors.md

Catch the 'AI model process start timed out' error when model loading exceeds 60 seconds. Consider using a smaller model.

```typescript
// Error: Model load timeout (> 60 seconds)
await window.electronAi.create({
  modelAlias: 'very-large-model'
}) // Throws Error if load takes > 60 seconds

// Workaround: Use smaller model
await window.electronAi.create({
  modelAlias: 'small-model'
}) // OK
```

```typescript
try {
  await window.electronAi.create({ modelAlias: 'my-model' })
} catch (error) {
  if (error instanceof Error && error.message.includes('timed out')) {
    console.error('Model took too long to load')
    // Use smaller model or check system resources
  }
}
```

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

### Utility Process stdio Configuration

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/utility-process.md

Illustrates the stdio configuration used when spawning the utility process. It specifies how stdin, stdout, and stderr are handled, with fd 3 available for additional communication.

```typescript
stdio: ['ignore', 'pipe', 'pipe', 'pipe']
```

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

### LanguageModel.create()

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/language-model.md

Creates and initializes a new LanguageModel instance. This method loads the GGUF model file, sets up the necessary context, and prepares a chat session, optionally including a system prompt and initial conversation history.

```APIDOC
## LanguageModel.create()

### Description
Creates and initializes a new LanguageModel instance. Loads the GGUF model file, creates a context, and initializes a chat session with optional system prompt and initial context.

### Method
`static async create`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (InternalLanguageModelCreateOptions) - Required - Configuration including model path, prompts, temperature, and topK

### Request Example
```typescript
const model = await LanguageModel.create({
  modelPath: '/path/to/model.gguf',
  systemPrompt: 'You are a helpful assistant.',
  temperature: 0.7,
  topK: 40
})
```

### Response
#### Success Response
- **LanguageModel** - A fully initialized LanguageModel instance ready to process prompts.

#### Response Example
(A LanguageModel instance)

### Throws
- **Error**: Model file not found at modelPath
- **Error**: Invalid GGUF format
- **Error**: Insufficient memory to load model
- **Error**: node-llama-cpp unavailable
```

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

### Handle JSON Schema Parsing Errors

Source: https://github.com/electron/llm/blob/main/_autodocs/errors.md

This example shows how a JSON schema mismatch can lead to an error. The model attempts to format output according to the schema, but the promise rejects if the response does not conform.

```typescript
// Potentially error if schema mismatch
const response = await window.electronAi.prompt(
  'Extract name: John Doe',
  {
    responseJSONSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' }  // Required but not in prompt
      },
      required: ['name', 'age']
    }
  }
)
// May throw Error if model doesn't include age
```

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

### window.electronAi.create

Source: https://github.com/electron/llm/blob/main/_autodocs/INDEX.txt

Creates a new language model instance. This is used to manage individual LLM contexts or sessions.

```APIDOC
## window.electronAi.create

### Description
Creates a new language model instance. This function allows for the instantiation of separate LLM contexts, which can be managed independently.

### Method
(Not specified, likely a method call on a global or imported object)

### Endpoint
(Not applicable, SDK function)

### Parameters
#### Request Body
- **modelCreationOptions** (object) - Required - Options for creating the language model instance. (Details not provided in source)

### Request Example
```javascript
// Example usage in the renderer process
window.electronAi.create({
  // model creation options here
});
```

### Response
#### Success Response (200)
(Response details not specified in source)

```

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

### AbortSignalUtilityManager Class Definition

Source: https://github.com/electron/llm/blob/main/_autodocs/api-reference/index.md

Manages request cancellation using AbortSignals. Provides methods to get, abort, and associate signals with requests. Use `getWithSignalFromCreateOptions` and `getWithSignalFromPromptOptions` to integrate signals into model operations.

```typescript
export class AbortSignalUtilityManager {
  getSignalForUUID(uuid: string): AbortSignal
  abortSignalForUUID(uuid?: string): void
  getWithSignalFromCreateOptions(input: InternalLanguageModelCreateOptions): InternalLanguageModelCreateOptions
  getWithSignalFromPromptOptions(input: LanguageModelPromptOptions): InternalLanguageModelPromptOptions
  removeUUID(uuid?: string): void
}
```