### Server Start Method Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Starts the Fastify server and includes error handling for startup failures.

```typescript
const server = new Server();
try {
  await server.start();
  // Server is now listening
} catch (error) {
  console.error('Failed to start server:', error);
  process.exit(1);
}
```

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

### Server Initialization Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Instantiates a new Server with custom logger and initial configuration, then starts the server.

```typescript
import Server from '@musistudio/llms';

const server = new Server({
  logger: true,
  initialConfig: {
    PORT: 3000,
    HOST: '127.0.0.1'
  }
});

await server.start();
```

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

### Server Configuration Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Example of how to configure the server's listening port and host.

```json5
{
  PORT: 8080,
  HOST: "0.0.0.0"
}
```

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

### Configuration File Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/provider-service.md

An example JSON5 configuration file demonstrating how to define providers and their transformer settings.

```json5
{
  providers: [
    {
      name: "anthropic",
      api_base_url: "https://api.anthropic.com",
      api_key: "sk-ant-...",
      models: [
        "claude-opus-4-1",
        "claude-sonnet-4",
        "claude-haiku-3"
      ],
      transformer: {
        use: [
          "anthropic",
          ["maxtoken", { minTokens: 1024 }]
        ],
        "claude-opus-4-1": {
          use: ["reasoning"]
        }
      }
    }
  ]
}
```

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

### Network Configuration Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Example of setting up an HTTPS proxy and request timeout.

```json5
{
  HTTPS_PROXY: "http://proxy.company.com:8080",
  TIMEOUT: 60000
}
```

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

### Logging Configuration Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Example of configuring the log level and log file path.

```json5
{
  LOG: "debug",
  LOG_FILE: "/var/log/llms.log"
}
```

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

### Development Commands

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Common commands for developing the project, including installing dependencies, running the development server, building for production, linting, and starting the production server.

```bash
# Install dependencies
npm install

# Development server with hot-reload
npm run dev

# Build for production
npm run build

# Run linter
npm run lint

# Start production
npm start
```

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

### Initialize and Start Server (CommonJS)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Shows how to import and instantiate the Server class using CommonJS modules and start the server.

```javascript
const Server = require('@musistudio/llms').default;

const server = new Server();
await server.start();
```

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

### Configuration Example (JSON5)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Example of a JSON configuration file. This file can be used to set server port and logging level.

```json5
// config.json
{
  PORT: 3000,
  LOG: "info"
}
```

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

### Production Build and Start

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Builds the project for production and starts the server. Outputs are generated in dist/cjs and dist/esm.

```bash
npm run build

npm start              # Run CJS version
npm run start:esm     # Run ESM version
```

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

### Initialize and Start Server (ESM)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Demonstrates how to import and instantiate the Server class using ECMAScript Modules (ESM) and start the server.

```typescript
import Server from '@musistudio/llms';

const server = new Server();
await server.start();
```

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

### Install Dependencies

Source: https://github.com/musistudio/llms/blob/main/README.md

Install project dependencies using npm or pnpm.

```sh
npm install
# or pnpm install
```

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

### Environment File (.env) Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Example of a configuration file in .env format. This format is commonly used for environment variables and supports key-value pairs.

```dotenv
PORT=3000
HOST=127.0.0.1
LOG=info
HTTPS_PROXY=http://proxy.example.com:8080
```

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

### Run in Development Mode

Source: https://github.com/musistudio/llms/blob/main/README.md

Start the development server with hot-reloading using nodemon and tsx.

```sh
npm run dev
# Uses nodemon + tsx for hot-reloading src/server.ts
```

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

### Provider Configuration Example: Custom API

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Example configuration for a custom API provider, detailing its name, base URL, API key, and supported models.

```json5
{
  name: "custom-api",
  api_base_url: "https://api.custom.example.com",
  api_key: "custom-key-…",
  models: ["custom-model-v1", "custom-model-v2"],
  transformer: {
    use: []
  }
}
```

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

### Curl Example for Updating Provider

Source: https://github.com/musistudio/llms/blob/main/_autodocs/endpoints.md

This example demonstrates how to use curl to send a PUT request to update a provider's models.

```bash
curl -X PUT http://localhost:3000/providers/anthropic \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["claude-opus-4-1", "claude-sonnet-4", "claude-haiku-3"]
  }'
```

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

### GET /

Source: https://github.com/musistudio/llms/blob/main/_autodocs/endpoints.md

Returns basic server information including the API name and version.

```APIDOC
## GET /

### Description
Returns basic server information.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200 OK)
- **message** (string) - API name
- **version** (string) - API version

#### Response Example
```json
{
  "message": "LLMs API",
  "version": "1.0.53"
}
```
```

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

### Initialize Server (CommonJS)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Initializes and starts the LLM API server using CommonJS module syntax.

```javascript
const Server = require('@musistudio/llms').default;

const server = new Server();
await server.start();
// Server listening on http://127.0.0.1:3000
```

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

### Troubleshoot Server Startup Issues

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Commands to diagnose why the server might not be starting, including checking port availability, configuration syntax, and logs.

```bash
# Check port is available
lsof -i :3000

# Check configuration syntax
node -e "const JSON5 = require('json5'); console.log(JSON5.parse(require('fs').readFileSync('./config.json', 'utf-8')))"

# Check logs
npm run dev 2>&1 | grep -i error
```

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

### Initialize LLMService and Register Provider

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/llm-service.md

Demonstrates the basic setup for LLMService, including initializing it with a ProviderService and registering a new provider with its configuration.

```typescript
const providerService = new ProviderService(configService, transformerService, logger);
const llmService = new LLMService(providerService);

// Register provider
llmService.registerProvider({
  name: 'anthropic',
  baseUrl: 'https://api.anthropic.com',
  apiKey: 'sk-ant-...',
  models: ['claude-opus-4-1']
});

// Get providers
const providers = llmService.getProviders();

// Get models
const models = await llmService.getAvailableModels();
```

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

### MaxTokenTransformer Configuration Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

Example of how to configure the MaxTokenTransformer within a provider's settings to enforce a maximum token limit of 4096.

```json5
{
  transformer: {
    use: [["maxtoken", { maxTokens: 4096 }]]
  }
}
```

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

### Server.start()

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Starts the Fastify server and begins listening for incoming requests. This method configures request preprocessing hooks, registers API routes, and sets up graceful shutdown handlers.

```APIDOC
## async start(): Promise<void>

### Description
Starts the Fastify server and begins listening for incoming requests.

### Method
`async`

### Endpoint
N/A (Method call)

### Parameters
None

### Returns
`Promise<void>` - Resolves when server starts successfully

### Throws
`Error` - If the server fails to start

### Description
Adds request preprocessing hooks to handle model/provider parsing and request body validation, registers API routes, starts listening on the configured PORT and HOST, and sets up graceful shutdown handlers for SIGINT and SIGTERM signals.

### Example
```typescript
const server = new Server();
try {
  await server.start();
  // Server is now listening
} catch (error) {
  console.error('Failed to start server:', error);
  process.exit(1);
}
```
```

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

### Initialize Server (TypeScript/ESM)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Initializes and starts the LLM API server using TypeScript and ESM syntax, with initial configuration options.

```typescript
import Server from '@musistudio/llms';

const server = new Server({
  initialConfig: {
    PORT: 3000
  }
});

await server.start();
```

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

### Tool Conversion Pipeline Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/utilities.md

Demonstrates a typical workflow for converting tool definitions between OpenAI, a unified format, and Anthropic formats using utility functions.

```typescript
import { convertToolsFromOpenAI } from '@/utils/converter';

// Receive OpenAI tools
const openaiTools = request.tools;

// Convert to unified format
const unifiedTools = convertToolsFromOpenAI(openaiTools);

// Use in unified request
const unifiedRequest = {
  messages: request.messages,
  model: request.model,
  tools: unifiedTools
};

// Later, convert to provider format
import { convertToolsToAnthropic } from '@/utils/converter';
const anthropicTools = convertToolsToAnthropic(unifiedTools);
```

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

### Optional .env File Configuration

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

This example shows how to configure the server using a .env file, which is optional and disabled by default. It mirrors many of the settings found in the JSON5 configuration.

```env
PORT=3000
HOST=127.0.0.1
LOG=info
LOG_FILE=/var/log/llms.log
HTTPS_PROXY=http://proxy.example.com:8080
TIMEOUT=3600000
```

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

### Provider Configuration Example: OpenAI

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Configuration for the OpenAI provider, specifying its API base URL, authentication key, and supported models.

```json5
{
  name: "openai",
  api_base_url: "https://api.openai.com/v1",
  api_key: "sk-…",
  models: ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"],
  transformer: {
    use: ["openai"]
  }
}
```

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

### Anthropic Transformer Example Request

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

Example of an incoming POST request to the Anthropic transformer's endpoint, demonstrating the expected message format.

```json
POST /v1/messages
{
  "model": "anthropic,claude-opus-4-1",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 1024
}
```

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

### Get Configuration Summary

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Returns a string describing which configuration sources are active. Useful for logging during startup to verify which configuration sources are being used.

```typescript
const summary = configService.getConfigSummary();
console.log(summary); // "Config sources: Initial Config, JSON: ./config.json, ENV: .env"
```

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

### Initialize ConfigService with Multiple Sources

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Configure the ConfigService to load settings from JSON files, environment files, and provide initial configuration values. This example shows how to enable loading from both JSON and .env files.

```typescript
const config = new ConfigService({
  jsonPath: './config.json',
  envPath: '.env.local',
  useEnvFile: true,
  useJsonFile: true,
  initialConfig: {
    PORT: 3000,
    CUSTOM: 'value'
  }
});
```

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

### Get Specific Provider Details

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Retrieves the configuration details for a specific registered provider, identified by its name.

```bash
curl http://localhost:3000/providers/anthropic
```

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

### Get Server Information

Source: https://github.com/musistudio/llms/blob/main/_autodocs/endpoints.md

Retrieves basic server information, including the API name and version.

```http
GET / HTTP/1.1
```

```json
{
  "message": "LLMs API",
  "version": "1.0.53"
}
```

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

### Complex Transformer Configuration

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

Example JSON configuration for defining multiple transformers and model-specific overrides for a provider like OpenRouter.

```json5
{
  name: "openrouter",
  api_base_url: "https://openrouter.ai/api/v1",
  api_key: "sk-or-...",
  models: ["openai/gpt-4", "anthropic/claude-3-opus"],
  transformer: {
    use: [
      "openrouter",
      ["maxtoken", { maxTokens: 4096 }],
      "streamoptions"
    ],
    "openai/gpt-4": {
      use: ["reasoning"]
    },
    "anthropic/claude-3-opus": {
      use: ["enhancetool", "cleancache"]
    }
  }
}
```

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

### Configuration Priority Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Illustrates the order of precedence for configuration values: initialConfig overrides .env, which overrides config.json. Unspecified values are retained.

```javascript
PORT: 4000          // From .env (overrides config.json)
LOG: "warn"         // From initialConfig (overrides all)
CUSTOM: "from-json" // From config.json (no override)
OTHER: "value"      // From initialConfig
```

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

### Initialize All Transformers

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Initializes the Transformer Service with configuration and logger. Use this at the start of your application to load all registered and custom transformers.

```typescript
const transformerService = new TransformerService(configService, logger);
await transformerService.initialize();
console.log(`Ready with ${transformerService.getAllTransformers().size} transformers`);
```

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

### Example: Creating and Throwing an API Error

Source: https://github.com/musistudio/llms/blob/main/_autodocs/errors.md

Demonstrates how to use the `createApiError` function to generate a specific error, such as 'Provider not found', and then throw it.

```typescript
import { createApiError } from '@/api/middleware';

throw createApiError(
  'Provider not found',
  404,
  'provider_not_found',
  'not_found_error'
);
```

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

### Curl Example for Toggling Provider Status

Source: https://github.com/musistudio/llms/blob/main/_autodocs/endpoints.md

Demonstrates using curl to send a PATCH request to toggle a provider's enabled status.

```bash
curl -X PATCH http://localhost:3000/providers/anthropic/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

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

### Provider Configuration Example: Google Gemini

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Configuration for the Google Gemini provider, including its API base URL, key, and supported models.

```json5
{
  name: "gemini",
  api_base_url: "https://generativelanguage.googleapis.com",
  api_key: "AIzaSyD…",
  models: ["gemini-pro", "gemini-pro-vision"],
  transformer: {
    use: ["gemini"]
  }
}
```

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

### Custom Transformer Configuration

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

JSON configuration snippet for loading custom transformers from a specified path during server setup.

```json5
{
  transformers: [
    {
      name: "my-transformer",
      type: "class",
      path: "./my-transformer.js"
    }
  ]
}
```

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

### Get All Configuration Values

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Retrieve a shallow copy of the entire configuration object. This is useful for inspecting all available settings or logging.

```typescript
const allConfig = configService.getAll();
console.log(Object.keys(allConfig)); // All available config keys
```

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

### Add Provider via Configuration

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Example of how to add an Anthropic provider by configuring its API base URL, API key, and supported models in a JSON configuration file.

```json5
{
  providers: [
    {
      name: "anthropic",
      api_base_url: "https://api.anthropic.com",
      api_key: "sk-ant-...",
      models: ["claude-opus-4-1"]
    }
  ]
}
```

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

### Basic Configuration Access

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Demonstrates how to access basic configuration values using the `get` method with default values. Ensures a fallback if the configuration key is not found.

```typescript
const config = new ConfigService();
const port = config.get('PORT', 3000);
const host = config.get('HOST', '127.0.0.1');
const logLevel = config.get('LOG', 'info');
```

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

### Provider Configuration Example: Anthropic

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Configuration for the Anthropic provider, including API base URL, key, supported models, and transformer settings.

```json5
{
  name: "anthropic",
  api_base_url: "https://api.anthropic.com",
  api_key: "sk-ant-v1-…",
  models: [
    "claude-opus-4-1",
    "claude-sonnet-4",
    "claude-haiku-3"
  ],
  transformer: {
    use: ["anthropic"]
  }
}
```

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

### Send a Chat Request

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Example of sending a basic chat request to the /v1/messages endpoint, specifying the model, messages, and maximum tokens.

```bash
curl -X POST http://localhost:3000/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic,claude-opus-4-1",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'
```

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

### Select Transformers in Provider Configuration

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Specify transformers for providers using string names or arrays with names and options. This example demonstrates provider-level and model-specific transformer selections.

```json5
{
  providers: [
    {
      name: "anthropic",
      api_base_url: "https://api.anthropic.com",
      api_key: "sk-ant-...",
      models: ["claude-opus-4-1", "claude-sonnet-4"],
      transformer: {
        // Provider-level transformers
        use: [
          "anthropic",
          ["maxtoken", { minTokens: 1024, maxTokens: 8192 }],
          "cleancache"
        ],
        
        // Model-specific transformers
        "claude-opus-4-1": {
          use: [
            "reasoning",
            ["forcereasoning", { enabled: true }]
          ]
        }
      }
    }
  ]
}
```

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

### Custom Transformer Class Structure

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

JavaScript example demonstrating the required structure for a custom transformer class, including export and method signatures.

```javascript
module.exports = class MyTransformer {
  constructor(options) {
    this.name = 'my-transformer';
  }
  
  async transformRequestIn(request, provider, context) {
    // Process unified request to provider format
    return modifiedRequest;
  }
  
  async transformResponseOut(response, context) {
    // Process provider response to unified format
    return modifiedResponse;
  }
};
```

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

### Retrieve Configuration Value with Default (Overload)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Demonstrates the overload of the get method that always returns a value by providing a default. This is useful for optional configurations.

```typescript
const timeout = configService.get('TIMEOUT', 30000); // Defaults to 30000
```

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

### Test Tool Conversion Utility

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/utilities.md

Example of how to test the `convertToolsToOpenAI` utility function using a testing framework like Jest. This snippet demonstrates asserting the expected output format for converted tools.

```typescript
describe('convertToolsToOpenAI', () => {
  it('converts unified to OpenAI format', () => {
    const unified = [/* ... */];
    const result = convertToolsToOpenAI(unified);
    expect(result[0].type).toBe('function');
  });
});
```

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

### Runtime Configuration with Server Constructor

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

This TypeScript snippet demonstrates how to pass initial configuration options directly when creating a new Server instance. This method allows for dynamic configuration at runtime.

```typescript
import Server from '@musistudio/llms';

const server = new Server({
  initialConfig: {
    PORT: 3000,
    HOST: '127.0.0.1',
    LOG: 'info'
  }
});

await server.start();
```

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

### Custom Transformer Module Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Implement a custom transformer class with methods for transforming requests and responses. This example shows the basic structure for a JavaScript module.

```javascript
module.exports = class MyCustomTransformer {
  constructor(options) {
    this.name = 'mycustom';
    this.options = options;
  }

  async transformRequestIn(request, provider, context) {
    // Transform unified request to provider format
    return modifiedRequest;
  }

  async transformResponseOut(response, context) {
    // Transform provider response to unified format
    return modifiedResponse;
  }
};
```

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

### GET /providers

Source: https://github.com/musistudio/llms/blob/main/_autodocs/endpoints.md

Retrieves a list of all currently registered LLM providers.

```APIDOC
## GET /providers

### Description
List all registered providers.

### Method
GET

### Endpoint
/providers

### Response
#### Success Response (200 OK)
- (array) - Array of registered provider objects, each containing name, baseUrl, apiKey, models, and transformer configuration.

#### Response Example
```json
[
  {
    "name": "anthropic",
    "baseUrl": "https://api.anthropic.com",
    "apiKey": "sk-ant-...",
    "models": ["claude-opus-4-1", "claude-sonnet-4"],
    "transformer": {}
  }
]
```
```

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

### Build Project

Source: https://github.com/musistudio/llms/blob/main/README.md

Compile the project for production, outputting to dist/cjs and dist/esm.

```sh
npm run build
# Outputs to dist/cjs and dist/esm
```

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

### Instantiate ConfigService with Options

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Create a new ConfigService instance, specifying paths for JSON5 and .env files, and providing an initial configuration object. Configuration is loaded in order: initial config, JSON5 file, then .env file, with later sources overriding earlier ones.

```typescript
const configService = new ConfigService({
  jsonPath: './config.json',
  envPath: '.env.local',
  useEnvFile: true,
  initialConfig: {
    PORT: 3000,
    LOG: 'info'
  }
});
```

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

### GET /providers/:id

Source: https://github.com/musistudio/llms/blob/main/_autodocs/endpoints.md

Retrieves details for a specific LLM provider identified by its name or ID.

```APIDOC
## GET /providers/:id

### Description
Retrieve a specific provider by name/ID.

### Method
GET

### Endpoint
/providers/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Provider name/ID

### Response
#### Success Response (200 OK)
- **name** (string) - Provider name
- **baseUrl** (string) - API base URL
- **apiKey** (string) - API authentication key
- **models** (array) - List of supported models
- **transformer** (object) - Transformer configuration

#### Response Example
```json
{
  "name": "anthropic",
  "baseUrl": "https://api.anthropic.com",
  "apiKey": "sk-ant-...",
  "models": ["claude-opus-4-1", "claude-sonnet-4"],
  "transformer": {}
}
```

### Error Responses
- **404** - provider_not_found: Provider not found
```

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

### Get Specific Provider

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Retrieves details for a specific registered AI model provider by name.

```APIDOC
## GET /providers/{name}

### Description
Retrieves details for a specific registered AI model provider by name.

### Method
GET

### Endpoint
/providers/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the provider to retrieve.
```

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

### get<T>(key, defaultValue?)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Retrieves a configuration value by key. This method is type-safe and supports optional default values.

```APIDOC
## get<T>(key, defaultValue?): T | undefined

### Description
Retrieves a configuration value by key. Type-safe configuration access with optional default values. Uses generic T parameter to infer return type.

### Method
(Not applicable - this is a class method)

### Endpoint
(Not applicable - this is a class method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (string) - Required - Configuration key name
- **defaultValue** (T) - Optional - Default value if key not found

### Request Example
```typescript
const port = configService.get('PORT', 3000); // Returns number, defaults to 3000
const apiKey = configService.get<string>('API_KEY'); // May be undefined
const timeout = configService.get('TIMEOUT', 30000); // Defaults to 30000
```

### Response
#### Success Response (200)
- **T | undefined** - Configuration value of type T, or defaultValue if not found, or undefined.

#### Response Example
(Value depends on the key and type T)
```

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

### Get All Registered Providers

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/llm-service.md

Retrieves an array of all currently registered LLM providers. Useful for listing available providers.

```typescript
const providers = llmService.getProviders();
providers.forEach(p => console.log(p.name));
```

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

### Server Constructor

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Creates and initializes a new Server instance with the specified configuration. The constructor sets up the Fastify application, registers essential middleware, and initializes core services.

```APIDOC
## constructor(options?: ServerOptions): Server

### Description
Creates and initializes a new Server instance with the specified configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| options | ServerOptions | No | {} | Server initialization options including Fastify configuration and initial config |
| options.initialConfig | AppConfig | No | undefined | Initial application configuration object to merge with loaded configs |
| options.logger | FastifyLoggerOptions | No | true | Fastify logger configuration (defaults to true for default logger) |
| options.bodyLimit | number | No | 50 * 1024 * 1024 | Maximum request body size in bytes |

### Returns
`Server` instance with initialized services

### Description
The constructor creates a Fastify application instance with a 50MB body limit, registers the CORS middleware, error handler, and initializes the ConfigService, TransformerService, ProviderService, and LLMService. Services are initialized sequentially to maintain dependencies.

### Example
```typescript
import Server from '@musistudio/llms';

const server = new Server({
  logger: true,
  initialConfig: {
    PORT: 3000,
    HOST: '127.0.0.1'
  }
});

await server.start();
```
```

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

### initialize

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Asynchronously initializes the TransformerService, loading all necessary built-in and custom transformers based on the application's configuration.

```APIDOC
## initialize(): Promise<void>

### Description
Asynchronously initializes the TransformerService. This method loads and registers all transformers defined in the configuration, including built-in and custom ones.

### Method
`initialize`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Returns
`Promise<void>`

### Example
```typescript
await transformerService.initialize();
console.log('TransformerService initialized.');
```
```

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

### getConfigSummary()

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Returns a string describing which configuration sources are active. This is useful for logging during startup to verify which configuration sources are being used.

```APIDOC
## getConfigSummary()

### Description
Returns a string describing which configuration sources are active.

### Method
`string`

### Returns
`string` - Summary of enabled config sources

### Example
```typescript
const summary = configService.getConfigSummary();
console.log(summary); // "Config sources: Initial Config, JSON: ./config.json, ENV: .env"
```
```

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

### getConfigSummary()

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Returns a string summary of the current configuration.

```APIDOC
## getConfigSummary(): string

### Description
Returns a string summary of the current configuration.

### Method
(Not applicable - this is a class method)

### Endpoint
(Not applicable - this is a class method)

### Parameters
None

### Request Example
```typescript
const summary = configService.getConfigSummary();
console.log(summary);
```

### Response
#### Success Response (200)
- **string** - A summary of the current configuration.

#### Response Example
"Configuration loaded from JSON5 and environment variables. PORT: 3000, LOG: info."
```

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

### Register a New Provider at Runtime

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Dynamically register a new LLM provider with the server. Ensure the server is initialized before registering.

```javascript
const server = new Server();

// Wait for initialization
await new Promise(r => setTimeout(r, 100));

const newProvider = server.providerService.registerProvider({
  name: 'custom',
  baseUrl: 'https://api.custom.com',
  apiKey: 'key-...',
  models: ['model-1', 'model-2']
});

console.log('Provider registered:', newProvider.name);
```

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

### Get Model Routes

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/llm-service.md

Retrieves all configured model routes, delegating to the ProviderService. Useful for understanding how models map to providers.

```typescript
const routes = llmService.getModelRoutes();
routes.forEach(route => {
  console.log(`${route.fullModel} -> ${route.provider}`);
});
```

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

### ConfigService Constructor

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Creates a new ConfigService instance and loads configuration from configured sources. Configuration is loaded in order: initial config → JSON5 file → .env file. Later sources override earlier ones.

```APIDOC
## constructor(options?: ConfigOptions): ConfigService

### Description
Creates a new ConfigService instance and loads configuration from configured sources.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (ConfigOptions) - Optional - Configuration loading options
  - **options.jsonPath** (string) - Optional - Path to JSON5 config file (relative or absolute). Defaults to './config.json'.
  - **options.envPath** (string) - Optional - Path to .env file (relative or absolute). Defaults to '.env'.
  - **options.useJsonFile** (boolean) - Optional - Whether to load JSON config file. Defaults to true.
  - **options.useEnvFile** (boolean) - Optional - Whether to load .env file. Defaults to false.
  - **options.useEnvironmentVariables** (boolean) - Optional - Whether to load environment variables. Defaults to true.
  - **options.initialConfig** (AppConfig) - Optional - Initial config object to merge.

### Request Example
```typescript
const configService = new ConfigService({
  jsonPath: './config.json',
  envPath: '.env.local',
  useEnvFile: true,
  initialConfig: {
    PORT: 3000,
    LOG: 'info'
  }
});
```

### Response
#### Success Response (200)
- **ConfigService** - The newly created ConfigService instance.

#### Response Example
(Instance of ConfigService)
```

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

### Transformer Unit Test Example

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

TypeScript unit test demonstrating how to instantiate and test a transformer's request transformation logic.

```typescript
const transformer = new AnthropicTransformer();

const request = {
  model: 'claude-opus-4-1',
  messages: [{ role: 'user', content: 'Hello' }]
};

const unified = await transformer.transformRequestOut(request);
expect(unified.messages[0].role).toBe('user');
```

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

### Unknown Provider Request and Response

Source: https://github.com/musistudio/llms/blob/main/_autodocs/errors.md

Example of a request to an unknown provider and the resulting 404 Not Found response with a 'provider_not_found' error code.

```json
POST /v1/messages
{
  "model": "unknown-provider,model-1"
}

{
  "error": {
    "message": "Provider 'unknown-provider' not found",
    "type": "api_error",
    "code": "provider_not_found"
  }
}
```

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

### getAll()

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Returns a shallow copy of the entire configuration object, providing access to all loaded configuration values.

```APIDOC
## getAll(): AppConfig

### Description
Returns a copy of the entire configuration object.

### Method
(Not applicable - this is a class method)

### Endpoint
(Not applicable - this is a class method)

### Parameters
None

### Request Example
```typescript
const allConfig = configService.getAll();
console.log(Object.keys(allConfig)); // All available config keys
```

### Response
#### Success Response (200)
- **AppConfig** - Shallow copy of all loaded configuration.

#### Response Example
```json
{
  "PORT": 3000,
  "LOG": "info",
  "API_KEY": "some-key"
}
```
```

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

### Runtime Configuration Override (TypeScript)

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Demonstrates how to override configuration at runtime using initialConfig. The initialConfig takes precedence over file-based configurations.

```typescript
// Runtime override
const server = new Server({
  initialConfig: { LOG: "debug" }
});
// Result: PORT=3000, LOG="debug" (initialConfig wins)
```

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

### Check Configuration File

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Execute this Node.js command to parse and display the content of the config.json file. Ensure the configuration is correctly formatted.

```bash
node -e "const JSON5 = require('json5'); console.log(JSON5.parse(require('fs').readFileSync('./config.json')))"
```

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

### Get Transformer for Request Processing

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Retrieves a specific transformer by its name. This is useful for applying transformations to incoming requests before they are sent to the LLM.

```typescript
const transformer = transformerService.getTransformer('anthropic');
if (transformer && typeof transformer !== 'function') {
  const result = await transformer.transformRequestOut(request);
}
```

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

### Get Transformers with Endpoints

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Filter and retrieve only those transformers that have an HTTP endpoint defined. These are typically used for direct API route mounting.

```typescript
const withEndpoint = transformerService.getTransformersWithEndpoint();
withEndpoint.forEach(({ name, transformer }) => {
  console.log(`${name} -> POST ${transformer.endPoint}`);
});
// Output:
// Anthropic -> POST /v1/messages
// OpenAI -> POST /v1/chat/completions
// Gemini -> POST /v1beta/models/:modelAndAction
```

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

### Initialize TransformerService

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Instantiate the TransformerService and then call initialize to load transformers. Ensure you have a configService and logger instance available.

```typescript
const transformerService = new TransformerService(configService, logger);
await transformerService.initialize();
```

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

### Get All Registered Transformers

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Retrieve a copy of the internal registry containing all registered transformers. Useful for debugging or iterating through available transformers.

```typescript
const allTransformers = transformerService.getAllTransformers();
console.log(`Registered ${allTransformers.size} transformers`);
allTransformers.forEach((transformer, name) => {
  const hasEndpoint = transformer.endPoint ? ' (has endpoint)' : '';
  console.log(`- ${name}${hasEndpoint}`);
});
```

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

### Retrieve Configuration Value Safely

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Get a configuration value by its key. This method may return undefined if the key does not exist in the configuration.

```typescript
const apiKey = configService.get<string>('API_KEY'); // May be undefined
```

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

### ServerOptions Interface

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Defines the configuration options for initializing the Server, extending standard Fastify server options.

```typescript
interface ServerOptions extends FastifyServerOptions {
  initialConfig?: AppConfig;
}
```

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

### Get Provider by ID

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/llm-service.md

Fetches a specific LLM provider using its unique ID or name. Returns undefined if the provider is not found.

```typescript
const provider = llmService.getProvider('anthropic');
if (provider) {
  console.log(`Base URL: ${provider.baseUrl}`);
}
```

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

### initialize

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Initializes the Transformer Service by loading built-in transformers and registering custom ones defined in the configuration.

```APIDOC
## initialize

### Description
Initializes the Transformer Service. This process includes loading all built-in transformers and registering any custom transformers specified in the application's configuration. Errors encountered during initialization are logged but do not halt the server startup process.

### Method
`async initialize(): Promise<void>`

### Returns
`Promise<void>` - A promise that resolves when the initialization process is complete.

### Example
```typescript
const transformerService = new TransformerService(configService, logger);
await transformerService.initialize();
console.log(`Transformers loaded: ${transformerService.getAllTransformers().size}`);
```
```

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

### Reload Configuration at Runtime

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Demonstrates how to reload the application's configuration at runtime using the `configService.reload()` method. Note that in-memory changes made via `set()` will be lost upon reloading.

```typescript
// Configuration file was updated
configService.reload();

// Now has updated values from files
const port = configService.get('PORT');
```

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

### Registering a Fastify Plugin

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/server.md

Demonstrates how to register an additional Fastify plugin with custom options and a prefix.

```typescript
const server = new Server();
await server.register(myPlugin, { prefix: '/custom' });
```

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

### Accessing Proxy Configuration

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Demonstrates how to retrieve the HTTPS proxy configuration. Logs the proxy URL if it is defined.

```typescript
const proxy = configService.getHttpsProxy();
if (proxy) {
  console.log('Using proxy:', proxy);
}
```

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

### Add Provider via API

Source: https://github.com/musistudio/llms/blob/main/_autodocs/README.md

Demonstrates adding an OpenAI provider using a POST request to the /providers endpoint, specifying its base URL, API key, and models.

```bash
curl -X POST http://localhost:3000/providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "models": ["gpt-4"]
  }'
```

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

### Get Transformers Without Endpoint

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Retrieves all registered transformers that do not have an associated HTTP endpoint. These are typically used as middleware for request or response processing.

```typescript
const noEndpoint = transformerService.getTransformersWithoutEndpoint();
noEndpoint.forEach(({ name }) => {
  console.log(`Middleware: ${name}`);
});
// Output:
// Middleware: maxtoken
// Middleware: reasoning
// Middleware: enhancetool
```

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

### Get a Transformer by Name

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformer-service.md

Retrieve a transformer by its registered name. Handles both instances and constructor functions, allowing for dynamic instantiation or direct use.

```typescript
const transformer = transformerService.getTransformer('anthropic');
if (transformer) {
  if (typeof transformer === 'function') {
    const instance = new transformer();
  } else {
    console.log(`Transformer has endpoint: ${transformer.endPoint}`);
  }
}
```

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

### Troubleshoot Authentication Failures

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Steps to resolve authentication issues, including verifying API keys in the configuration and enabling debug logging for more insights.

```bash
# Verify API key is correct
# Check in config.json: providers[].api_key

# For debug: enable debug logging
LOG=debug npm run dev
```

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

### Server and Logging Environment Variables

Source: https://github.com/musistudio/llms/blob/main/_autodocs/configuration.md

Define environment variables for server settings like PORT and HOST, and logging configurations such as LOG level and LOG_FILE.

```bash
# Server
PORT=3000
HOST=0.0.0.0

# Logging
LOG=info
LOG_FILE=/var/log/llms.log
```

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

### Get All Registered Model Routes

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/provider-service.md

Fetches a comprehensive list of all currently registered model routes. This data can be used for inspection or caching purposes.

```typescript
const routes = providerService.getModelRoutes();
routes.forEach(route => {
  console.log(`${route.fullModel} -> provider: ${route.provider}, model: ${route.model}`);
});
```

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

### Run Tests

Source: https://github.com/musistudio/llms/blob/main/README.md

Execute the project's test suite. Refer to CLAUDE.md for detailed testing information.

```sh
npm test
# See CLAUDE.md for details
```

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

### Python API Request for Messages

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Makes a POST request to the messages endpoint using the Python requests library to get a response from a model.

```python
import requests
import json

response = requests.post('http://localhost:3000/v1/messages', 
  headers={'Content-Type': 'application/json'},
  json={
    'model': 'anthropic,claude-opus-4-1',
    'messages': [{'role': 'user', 'content': 'Hello!'}],
    'max_tokens': 1024
  }
)

print(response.json()['content'])
```

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

### View and Search Server Logs

Source: https://github.com/musistudio/llms/blob/main/_autodocs/errors.md

Use command-line tools to monitor real-time server logs or search for specific error messages. This is crucial for identifying and diagnosing issues in production.

```bash
# View real-time logs
tail -f /var/log/llms.log

# Search for errors
grep ERROR /var/log/llms.log | head -20
```

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

### Node.js API Request for Messages

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/quick-start.md

Makes a POST request to the messages endpoint using Node.js fetch API to get a response from a model.

```javascript
const response = await fetch('http://localhost:3000/v1/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'anthropic,claude-opus-4-1',
    messages: [{ role: 'user', content: 'Hello!' }],
    max_tokens: 1024
  })
});

const data = await response.json();
console.log(data.content);
```

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

### ProviderService Constructor

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/provider-service.md

Initializes the ProviderService and loads providers from configuration. It automatically registers model routes for quick lookup.

```APIDOC
## constructor

### Description
Creates a new ProviderService instance and initializes providers from configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **configService** (ConfigService) - Yes - Configuration service instance
- **transformerService** (TransformerService) - Yes - Transformer service for resolver transformers
- **logger** (any) - Yes - Logger instance for logging provider operations

### Request Example
```typescript
const providerService = new ProviderService(
  configService,
  transformerService,
  logger
);
// Providers from config are automatically registered
```

### Response
#### Success Response (200)
- **ProviderService instance** - instance with providers loaded from config

#### Response Example
```json
{
  "example": "ProviderService instance"
}
```
```

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

### Get Available LLM Models

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/llm-service.md

Retrieves all available models in a standardized, OpenAI-compatible format. Note: The implementation may have a bug with `flatMap` on a Promise.

```typescript
const response = await llmService.getAvailableModels();
console.log(response.object); // 'list'
console.log(response.data);   // Array of models
```

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

### Get HTTPS Proxy URL

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/config-service.md

Retrieve the configured HTTPS proxy URL. The service checks common environment variable names for proxy settings.

```typescript
const proxyUrl = configService.getHttpsProxy();
if (proxyUrl) {
  // Use proxy for HTTP requests
  const dispatcher = new ProxyAgent(proxyUrl);
}
```

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

### Error Handling in Transformer

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

TypeScript example showing how to throw custom API errors within a transformer's `transformRequestIn` method for graceful error handling.

```typescript
async transformRequestIn(request, provider, context) {
  if (!request.messages) {
    throw createApiError(
      'Messages required',
      400,
      'invalid_request'
    );
  }
}
```

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

### Provider Configuration with Multiple Transformers

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/transformers.md

Shows how to configure a provider with a sequence of transformers, including 'anthropic', 'maxtoken', and 'cleancache', to manage various aspects of API interaction.

```json5
{
  name: "anthropic",
  api_base_url: "https://api.anthropic.com",
  api_key: "sk-ant-...",
  models: ["claude-opus-4-1"],
  transformer: {
    use: [
      "anthropic",
      ["maxtoken", { maxTokens: 8192 }],
      "cleancache"
    ]
  }
}
```

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

### Get Provider by Name

Source: https://github.com/musistudio/llms/blob/main/_autodocs/api-reference/provider-service.md

Retrieves a specific LLM provider by its unique name. Returns undefined if the provider is not found. Useful for validating and accessing provider details.

```typescript
const provider = providerService.getProvider('anthropic');
if (provider) {
  console.log(`Found provider: ${provider.name}`);
  console.log(`Base URL: ${provider.baseUrl}`);
  console.log(`Models: ${provider.models.join(', ')}`);
}
```