### Start the Interposer Server

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Starts the FastAPI server for the AI Horde OpenAI API Interposer. It requires setting the AI_HORDE_API_KEY environment variable for proper authentication and priority. The server listens on host 0.0.0.0 and port 8080.

```bash
SET AI_HORDE_API_KEY=your_api_key(defaults to low priority queue if left empty)
uvicorn horde_openai.server:app --host 0.0.0.0 --port 8080
```

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

### Server Startup

Source: https://context7.com/tridefender/opencorde/llms.txt

Instructions on how to start the FastAPI server for the AI Horde OpenAI API Interposer.

```APIDOC
## Server Startup

Start the FastAPI server to expose OpenAI-compatible endpoints.

```bash
# Set API key (optional, defaults to anonymous queue)
export AI_HORDE_API_KEY=your_api_key

# Start the server
uvicorn horde_openai.server:app --host 0.0.0.0 --port 8080

# Or run directly
python -m horde_openai.server
```
```

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

### Install Project with Pip

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Installs the AI Horde OpenAI API Interposer package in editable mode using pip. This is useful for development as changes to the source code are immediately reflected without needing to reinstall.

```bash
pip install -e .
```

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

### Start AI Horde OpenAI API Interposer Server

Source: https://context7.com/tridefender/opencorde/llms.txt

Starts the FastAPI server to expose OpenAI-compatible endpoints. Requires setting the AI Horde API key as an environment variable. The server can be run using uvicorn or directly via Python.

```bash
# Set API key (optional, defaults to anonymous queue)
export AI_HORDE_API_KEY=your_api_key

# Start the server
uvicorn horde_openai.server:app --host 0.0.0.0 --port 8080

# Or run directly
python -m horde_openai.server
```

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

### Chat Completions API Request Body Example

Source: https://github.com/tridefender/opencorde/blob/main/README.md

An example JSON payload for the /v1/chat/completions endpoint. It includes the model name, a list of messages with roles and content, temperature, and max_tokens.

```json
{
  "model": "koboldcpp/Fimbulvetr-11B-v2",
  "messages": [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Tell me a joke."}
  ],
  "temperature": 0.7,
  "max_tokens": 100
}
```

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

### Make a Chat Completion Request via cURL

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Demonstrates how to make a POST request to the /v1/chat/completions endpoint using cURL. This example sends a simple user message and specifies the desired model and maximum tokens.

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "awsome_engine/splendid_model",
    "messages": [{"role": "user", "content": "Hello! How are you?"}],
    "max_tokens": 50
  }'
```

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

### GET /v1/models

Source: https://context7.com/tridefender/opencorde/llms.txt

List all available text generation models from AI Horde workers, including their capabilities such as context length, generation limits, and instruct format.

```APIDOC
## GET /v1/models

### Description
List all available text generation models from AI Horde workers with their capabilities including context length, generation limits, and instruct format.

### Method
GET

### Endpoint
/v1/models

### Parameters
None

### Request Example
```bash
curl http://localhost:8080/v1/models
```

### Response
#### Success Response (200)
- **object** (string) - The type of object, usually "list".
- **data** (array) - A list of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of object, usually "model".
  - **created** (integer) - Unix timestamp of creation.
  - **owned_by** (string) - The owner of the model (e.g., "ai-horde").
  - **permission** (array) - Permissions associated with the model.
  - **root** (string) - The root model identifier.
  - **parent** (null) - Parent model identifier (usually null).
  - **capabilities** (object) - Capabilities of the model.
    - **max_context_length** (integer) - Maximum context length supported.
    - **max_generation_length** (integer) - Maximum generation length supported.
    - **parameters** (integer) - Number of parameters in the model.
    - **instruct_format** (string) - The instruct format supported by the model (e.g., "ChatML").

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "koboldcpp/LLaMA2-13B-Psyfighter2",
      "object": "model",
      "created": 1700000000,
      "owned_by": "ai-horde",
      "permission": [],
      "root": "koboldcpp/LLaMA2-13B-Psyfighter2",
      "parent": null,
      "capabilities": {
        "max_context_length": 4096,
        "max_generation_length": 4096,
        "parameters": 13000000000,
        "instruct_format": "ChatML"
      }
    }
  ]
}
```
```

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

### Create Chat Completion via AI Horde API

Source: https://context7.com/tridefender/opencorde/llms.txt

Demonstrates how to create a chat completion using the AI Horde's distributed text generation network via the /v1/chat/completions endpoint. This endpoint accepts OpenAI-format requests and handles the translation and asynchronous polling internally. The example shows a POST request with a model, messages, and generation parameters.

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a short story about a dragon."}
    ],
    "temperature": 0.7,
    "max_tokens": 100,
    "top_p": 0.9,
    "stream": false
  }'

# Response:
# {
#   "id": "chatcmpl-abc123",
#   "object": "chat.completion",
#   "created": 1700000000,
#   "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
#   "choices": [
#     {
#       "index": 0,
#       "message": {
#         "role": "assistant",
#         "content": "Once upon a time, in a land of towering mountains..."
#       },
#       "finish_reason": "stop"
#     }
#   ],
#   "usage": {
#     "prompt_tokens": 25,
#     "completion_tokens": 75,
#     "total_tokens": 100
#   }
# }
```

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

### List Available Models via cURL

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Shows how to retrieve a list of all available text generation models from the interposer using a GET request to the /v1/models endpoint via cURL.

```bash
curl http://localhost:8080/v1/models
```

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

### GET /v1/models

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

Lists available models with their capabilities, aggregated from the `/v2/workers` endpoint. This provides information about which models can be used and their associated parameters.

```APIDOC
## GET /v1/models

### Description
Lists available models with their capabilities, aggregated from the `/v2/workers` endpoint. This provides information about which models can be used and their associated parameters.

### Method
GET

### Endpoint
/v1/models

### Parameters
None

### Response
#### Success Response (200)
- **object** (string) - Type of object, always "list".
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - Type of object, always "model".
  - **created** (integer) - Unix timestamp of when the model was registered.
  - **owned_by** (string) - The entity that owns the model (e.g., "ai-horde").
  - **permission** (array) - Permissions associated with the model.
  - **root** (string) - The root identifier for the model.
  - **parent** (null) - Indicates if this model is a fine-tune of another.
  - **capabilities** (object) - Technical capabilities of the model.
    - **max_context_length** (integer) - Maximum number of tokens the model can process in context.
    - **max_generation_length** (integer) - Maximum number of tokens the model can generate.
    - **parameters** (integer) - Number of parameters in the model.
    - **instruct_format** (string) - The instruction format the model understands (e.g., "ChatML").

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "koboldcpp/LLaMA2-13B-Psyfighter2",
      "object": "model",
      "created": 1700000000,
      "owned_by": "ai-horde",
      "permission": [],
      "root": "koboldcpp/LLaMA2-13B-Psyfighter2",
      "parent": null,
      "capabilities": {
        "max_context_length": 4096,
        "max_generation_length": 4096,
        "parameters": 13000000000,
        "instruct_format": "ChatML"
      }
    }
  ]
}
```
```

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

### Interact with AI Horde API Directly using Python Client

Source: https://context7.com/tridefender/opencorde/llms.txt

Demonstrates the usage of the `AIHordeClient` class for direct interaction with the AI Horde API. This Python code shows how to initialize the client, refresh the model registry, list available models, retrieve model information, and submit asynchronous generation requests.

```python
import asyncio
from horde_openai import AIHordeClient

async def main():
    async with AIHordeClient(
        api_key="your_api_key",  # Or use AI_HORDE_API_KEY env var
        timeout=120,             # Max wait time in seconds
        poll_interval=2.0        # Polling interval in seconds
    ) as client:
        # Refresh available models from workers
        await client.refresh_model_registry()

        # List available models
        models = client.list_models()
        print(f"Available models: {models[:5]}")

        # Get model capabilities
        info = client.get_model_info("koboldcpp/LLaMA2-13B-Psyfighter2")
        print(f"Context length: {info['capabilities']['max_context_length']}")

        # Submit async request and wait for completion
        payload = {
            "prompt": "### User:\nHello!\n\n### Response:",
            "params": {
                "max_length": 100,
                "temperature": 0.7,
                "max_context_length": 2048
            },
            "models": ["koboldcpp/LLaMA2-13B-Psyfighter2"]
        }
        generations = await client.submit_and_wait(payload)
        print(f"Response: {generations[0]['text']}")

asyncio.run(main())
```

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

### Python OpenAI SDK Integration with Interposer

Source: https://context7.com/tridefender/opencorde/llms.txt

Shows how to use the official OpenAI Python SDK with the AI Horde Interposer by simply redirecting the `base_url`. This allows existing OpenAI client code to work with AI Horde models without modification.

```python
from openai import OpenAI

# Point to the interposer instead of OpenAI
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # API key is handled by interposer
)

# Use exactly like the OpenAI API
response = client.chat.completions.create(
    model="koboldcpp/LLaMA2-13B-Psyfighter2",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the meaning of life?"}
    ],
    temperature=0.7,
    max_tokens=150
)

print(response.choices[0].message.content)

# List available models
models = client.models.list()
for model in models.data:
    print(f"- {model.id}: context={model.capabilities.get('max_context_length', 'N/A')}")
```

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

### Run Unit Tests

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Executes the unit tests for the project using the pytest framework. The -v flag provides verbose output, showing each test case being run.

```bash
pytest tests/ -v
```

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

### AIHordeClient Class

Source: https://context7.com/tridefender/opencorde/llms.txt

Documentation for the `AIHordeClient` class, which allows direct interaction with the AI Horde API.

```APIDOC
## AIHordeClient

### Description
The main client class for interacting with AI Horde API directly. Handles async request submission, polling for completion, and model registry management.

### Usage Example

```python
import asyncio
from horde_openai import AIHordeClient

async def main():
    async with AIHordeClient(
        api_key="your_api_key",  # Or use AI_HORDE_API_KEY env var
        timeout=120,             # Max wait time in seconds
        poll_interval=2.0        # Polling interval in seconds
    ) as client:
        # Refresh available models from workers
        await client.refresh_model_registry()

        # List available models
        models = client.list_models()
        print(f"Available models: {models[:5]}")

        # Get model capabilities
        info = client.get_model_info("koboldcpp/LLaMA2-13B-Psyfighter2")
        print(f"Context length: {info['capabilities']['max_context_length']}")

        # Submit async request and wait for completion
        payload = {
            "prompt": "### User:\nHello!\n\n### Response:",
            "params": {
                "max_length": 100,
                "temperature": 0.7,
                "max_context_length": 2048
            },
            "models": ["koboldcpp/LLaMA2-13B-Psyfighter2"]
        }
        generations = await client.submit_and_wait(payload)
        print(f"Response: {generations[0]['text']}")

asyncio.run(main())
```
```

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

### OpenCorde Chat Completion and Model Listing (Python)

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

This Python snippet demonstrates how to perform chat completions and list available models using the OpenCorde API. It requires the 'requests' library and assumes a local interposer is running. The chat_completion function takes a list of messages, a model name, and optional parameters like max_tokens and temperature. The list_models function retrieves all available models.

```python
import requests
import time

API_KEY = "0000000000"  # Anonymous or your API key
BASE_URL = "http://localhost:8080"  # Interposer URL

def chat_completion(messages, model, max_tokens=100, temperature=0.7):
    # Build prompt from messages
    prompt = messages_to_prompt(messages)
    
    # Submit to interposer
    response = requests.post(
        f"{BASE_URL}/v1/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": model,
            "messages": messages,
            "max_tokens": max_tokens,
            "temperature": temperature
        }
    )
    
    return response.json()

def list_models():
    response = requests.get(f"{BASE_URL}/v1/models")
    return response.json()
```

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

### List Available AI Horde Models

Source: https://context7.com/tridefender/opencorde/llms.txt

Retrieves a list of all available text generation models from AI Horde workers using the /v1/models endpoint. The response includes model capabilities such as context length, generation limits, and supported instruct formats. This is useful for discovering which models are available for use.

```bash
curl http://localhost:8080/v1/models

# Response:
# {
#   "object": "list",
#   "data": [
#     {
#       "id": "koboldcpp/LLaMA2-13B-Psyfighter2",
#       "object": "model",
#       "created": 1700000000,
#       "owned_by": "ai-horde",
#       "permission": [],
#       "root": "koboldcpp/LLaMA2-13B-Psyfighter2",
#       "parent": null,
#       "capabilities": {
#         "max_context_length": 4096,
#         "max_generation_length": 4096,
#         "parameters": 13000000000,
#         "instruct_format": "ChatML"
#       }
#     }
#   ]
# }
```

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

### List Models API

Source: https://github.com/tridefender/opencorde/blob/main/README.md

The `/v1/models` endpoint retrieves a list of all available text generation models accessible through the AI Horde interposer.

```APIDOC
## GET /v1/models

### Description
This endpoint returns a list of all available text generation models that the interposer can access via the AI Horde API. It includes model capabilities and other relevant information.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8080/v1/models
```

### Response
#### Success Response (200)
- **data** (array) - A list of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of object, usually `model`.
  - **owned_by** (string) - The entity that owns the model (e.g., "ai-horde").
  - **permission** (array) - Permissions associated with the model.

#### Response Example
```json
{
  "data": [
    {
      "id": "awsome_engine/splendid_model",
      "object": "model",
      "owned_by": "ai-horde",
      "permission": []
    },
    {
      "id": "koboldcpp/Fimbulvetr-11B-v2",
      "object": "model",
      "owned_by": "ai-horde",
      "permission": []
    }
  ]
}
```
```

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

### Update opencode.json with AI Horde Models (Bash)

Source: https://context7.com/tridefender/opencorde/llms.txt

A utility script to generate and continuously update an opencode.json configuration file with available AI Horde models. It can be run once or continuously with a specified refresh interval. Supports custom output file paths. Requires Python and the horde-openai library.

```bash
# Generate opencode.json once and exit
python update_opencode_models.py --once

# Run continuously with default 5-minute refresh
python update_opencode_models.py

# Custom output file and refresh interval (10 minutes)
python update_opencode_models.py --output my-opencode.json --interval 600
```

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

### POST /v1/chat/completions

Source: https://context7.com/tridefender/opencorde/llms.txt

Create a chat completion using AI Horde's distributed text generation network. This endpoint accepts OpenAI-format requests and handles all translation and async polling internally.

```APIDOC
## POST /v1/chat/completions

### Description
Create a chat completion using AI Horde's distributed text generation network. The endpoint accepts OpenAI-format requests and handles all translation and async polling internally.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The ID of the model to use for generation.
- **messages** (array) - Required - A list of message objects, each with a `role` (system, user, or assistant) and `content`.
- **temperature** (number) - Optional - Controls randomness. Lower values make output more focused and deterministic.
- **max_tokens** (integer) - Optional - The maximum number of tokens to generate in the completion.
- **top_p** (number) - Optional - An alternative to sampling with temperature, called nucleus sampling. The model considers only the tokens comprising the top `top_p` probability mass.
- **stream** (boolean) - Optional - Whether to stream back partial progress. Defaults to false.

### Request Example
```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a short story about a dragon."}
    ],
    "temperature": 0.7,
    "max_tokens": 100,
    "top_p": 0.9,
    "stream": false
  }'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the completion.
- **object** (string) - The type of object, usually "chat.completion".
- **created** (integer) - Unix timestamp of creation.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of completion choices.
  - **index** (integer) - Index of the choice.
  - **message** (object) - The message object.
    - **role** (string) - Role of the message sender (e.g., "assistant").
    - **content** (string) - The generated text content.
  - **finish_reason** (string) - The reason the model stopped generating tokens (e.g., "stop").
- **usage** (object) - Usage statistics for the completion.
  - **prompt_tokens** (integer) - Number of tokens in the prompt.
  - **completion_tokens** (integer) - Number of tokens in the completion.
  - **total_tokens** (integer) - Total number of tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Once upon a time, in a land of towering mountains..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 75,
    "total_tokens": 100
  }
}
```
```

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

### Convert OpenAI Messages to Prompt String

Source: https://context7.com/tridefender/opencorde/llms.txt

Provides a utility function `convert_messages_to_prompt` to transform an array of OpenAI-formatted messages into a single prompt string. It supports different instruct formats like ChatML (default), Mistral, and Alpaca, which is crucial for correctly formatting input for AI Horde models.

```python
from horde_openai.translate import convert_messages_to_prompt

messages = [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Write a Python function to calculate factorial."},
]

# ChatML format (default)
prompt_chatml = convert_messages_to_prompt(messages, format_name="ChatML")
print(prompt_chatml)
# Output:
# ### System:
# You are a helpful coding assistant.
#
# ### User:

```

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

### Chat Completions API

Source: https://github.com/tridefender/opencorde/blob/main/README.md

The `/v1/chat/completions` endpoint accepts chat messages in the OpenAI format and returns a completion generated by AI Horde workers.

```APIDOC
## POST /v1/chat/completions

### Description
This endpoint processes chat messages, translates them into the AI Horde format, submits them for generation, polls for the result, and returns the completion in OpenAI format.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The ID of the model to use for generation (e.g., "awsome_engine/splendid_model").
- **messages** (array) - Required - A list of message objects, each with a `role` (system, user, or assistant) and `content`.
- **temperature** (number) - Optional - Controls randomness. Lower values make output more focused and deterministic.
- **max_tokens** (integer) - Optional - The maximum number of tokens to generate in the completion.

### Request Example
```json
{
  "model": "koboldcpp/Fimbulvetr-11B-v2",
  "messages": [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Tell me a joke."}
  ],
  "temperature": 0.7,
  "max_tokens": 100
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the completion.
- **object** (string) - The type of object returned, usually `chat.completion`.
- **created** (integer) - Unix timestamp of when the completion was created.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of completion choices.
  - **index** (integer) - The index of the choice.
  - **message** (object) - The message content.
    - **role** (string) - The role of the message sender (e.g., `assistant`).
    - **content** (string) - The generated text content.
  - **finish_reason** (string) - The reason the model stopped generating tokens (e.g., `stop`, `length`).
- **usage** (object) - Information about token usage.
  - **prompt_tokens** (integer) - Number of tokens in the prompt.
  - **completion_tokens** (integer) - Number of tokens in the completion.
  - **total_tokens** (integer) - Total tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-12345",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "koboldcpp/Fimbulvetr-11B-v2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Why don't scientists trust atoms? Because they make up everything!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}
```
```

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

### POST /v1/chat/completions

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

Translates OpenAI chat completion requests to AI Horde async text generation. It takes an OpenAI-formatted request and converts it into AI Horde's native format for processing.

```APIDOC
## POST /v1/chat/completions

### Description
Translates OpenAI chat completion requests to AI Horde async text generation. It takes an OpenAI-formatted request and converts it into AI Horde's native format for processing.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The ID of the model to use for generation (e.g., "koboldcpp/LLaMA2-13B-Psyfighter2").
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the author of the message (e.g., "system", "user", "assistant").
  - **content** (string) - Required - The content of the message.
- **temperature** (number) - Optional - Controls randomness. Lower values make output more deterministic.
- **max_tokens** (integer) - Optional - The maximum number of tokens to generate in the completion. Capped at 4096.
- **stream** (boolean) - Optional - Whether to stream back partial progress. Currently not supported.

### Request Example
```json
{
  "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."}, 
    {"role": "user", "content": "Once upon a time in a magical forest,"}
  ],
  "temperature": 0.7,
  "max_tokens": 100,
  "stream": false
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the chat completion job.
- **object** (string) - Type of object, e.g., "chat.completion".
- **created** (integer) - Unix timestamp of when the completion was created.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of completion choices.
  - **index** (integer) - Index of the choice.
  - **message** (object) - The generated message.
    - **role** (string) - Role of the assistant.
    - **content** (string) - The generated text content.
  - **finish_reason** (string) - The reason the model stopped generating tokens (e.g., "stop").
- **usage** (object) - Usage statistics for the completion.
  - **prompt_tokens** (integer) - Number of tokens in the prompt.
  - **completion_tokens** (integer) - Number of tokens in the generated completion.
  - **total_tokens** (integer) - Total tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-job_id",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The trees whispered secrets to the wind..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 30,
    "completion_tokens": 50,
    "total_tokens": 80
  }
}
```
```

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

### Python Error Handling with AIHordeClient

Source: https://context7.com/tridefender/opencorde/llms.txt

Demonstrates robust error handling when interacting with the AI Horde API using the `AIHordeClient`. It specifically catches `InvalidRequestError`, `RequestTimeoutError`, and general `AIHordeError` exceptions, printing relevant details for debugging.

```python
import asyncio
from horde_openai.client import (
    AIHordeClient,
    AIHordeError,
    InvalidRequestError,
    RequestTimeoutError
)

async def safe_completion():
    async with AIHordeClient(timeout=30) as client:
        try:
            await client.refresh_model_registry()

            payload = {
                "prompt": "Hello!",
                "params": {"max_length": 100},
                "models": ["invalid/model"]
            }
            result = await client.submit_and_wait(payload)
            return result

        except InvalidRequestError as e:
            # HTTP 400 - bad request parameters
            print(f"Invalid request: {e}")
            print(f"Status code: {e.status_code}")

        except RequestTimeoutError as e:
            # Job didn't complete within timeout
            print(f"Request timed out: {e}")

        except AIHordeError as e:
            # Other AI Horde API errors
            print(f"AI Horde error: {e}")
            if e.status_code:
                print(f"Status code: {e.status_code}")

asyncio.run(safe_completion())
```

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

### Generate opencode.json Once

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Executes the model updater script to generate the opencode.json file once. This file contains AI Horde text models formatted for OpenCode, including limits and default model settings.

```bash
python update_opencode_models.py --once
```

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

### convert_messages_to_prompt Function

Source: https://context7.com/tridefender/opencorde/llms.txt

Utility function to convert an OpenAI-format messages array into a prompt string.

```APIDOC
## convert_messages_to_prompt

### Description
Convert OpenAI-format messages array to a prompt string using the specified instruct format (ChatML, Mistral, or Alpaca).

### Usage Example

```python
from horde_openai.translate import convert_messages_to_prompt

messages = [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Write a Python function to calculate factorial."},
]

# ChatML format (default)
prompt_chatml = convert_messages_to_prompt(messages, format_name="ChatML")
print(prompt_chatml)
# Output:
# ### System:
# You are a helpful coding assistant.
#
# ### User:

```

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

### Convert Chat Request to AI Horde Format (Python)

Source: https://context7.com/tridefender/opencorde/llms.txt

Translates an OpenAI chat completion request into the format required by the AI Horde asynchronous API. It considers model capabilities like token limits and formats the prompt according to the target model's expected structure. Requires the horde-openai library and a ModelRegistry instance.

```python
from horde_openai.translate import translate_chat_request_to_horde
from horde_openai.models import ModelRegistry

# Initialize registry (normally populated via refresh())
registry = ModelRegistry()

messages = [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Tell me a joke."}
]

params = {
    "temperature": 0.8,
    "max_tokens": 150,
    "top_p": 0.95,
    "frequency_penalty": 0.5,
    "presence_penalty": 0.3
}

horde_payload = translate_chat_request_to_horde(
    messages=messages,
    model="koboldcpp/LLaMA2-13B-Psyfighter2",
    params=params,
    model_registry=registry
)

print(horde_payload)
```

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

### Translate OpenAI Chat Completions to AI Horde Format

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

This snippet demonstrates the translation of an OpenAI-formatted chat completion request into the AI Horde's native asynchronous API format. It maps fields like 'messages' to 'prompt' and 'temperature' to 'params.temperature', handling different instruct formats.

```json
{
  "model": "koboldcpp/LLaMA2-13B-Psyfighter2",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."}, 
    {"role": "user", "content": "Once upon a time in a magical forest,"}
  ],
  "temperature": 0.7,
  "max_tokens": 100,
  "stream": false
}
```

```json
{
  "prompt": "### System:\nYou are a helpful assistant.\n\n### User:\nOnce upon a time in a magical forest,\n\n### Response:",
  "params": {
    "max_length": 100,
    "max_context_length": 2048,
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
    "rep_pen": 1.1,
    "n": 1
  },
  "models": ["koboldcpp/LLaMA2-13B-Psyfighter2"],
  "trusted_workers": false,
  "slow_workers": true
}
```

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

### Keep Models Updated Continuously

Source: https://github.com/tridefender/opencorde/blob/main/README.md

Runs the model updater script continuously to keep the opencode.json file updated. By default, it refreshes every 5 minutes. A custom refresh interval can be specified using the --interval flag.

```bash
# Run continuously with 5-minute refresh (default)
python update_opencode_models.py

# Custom refresh interval
python update_opencode_models.py --interval 600
```

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

### Translate AI Horde Response to OpenAI Format

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

This Python code snippet illustrates the process of translating the AI Horde's asynchronous job completion response back into an OpenAI-compatible chat completion format. It constructs the response object, including generated text, usage statistics, and metadata.

```python
import time

# Assume generation and original_model are defined
# Assume count_tokens function is defined

openai_response = {
    "id": f"chatcmpl-{job_id}",
    "object": "chat.completion",
    "created": int(time.time()),
    "model": original_model,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": generation["text"]
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": count_tokens(original_prompt),
        "completion_tokens": count_tokens(generation["text"]),
        "total_tokens": sum
    }
}
```

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

### Manage AI Horde Model Capabilities with ModelRegistry (Python)

Source: https://context7.com/tridefender/opencorde/llms.txt

Manages AI Horde model capabilities by fetching and caching information from the AI Horde workers endpoint. It allows refreshing the model list, retrieving specific model capabilities (like context length and generation limits), and accessing OpenAI-style model information. Requires the horde-openai library and asyncio.

```python
import asyncio
from horde_openai.models import ModelRegistry, ModelCapabilities

async def main():
    registry = ModelRegistry(
        api_key="your_api_key",
        cache_ttl=300  # Cache expires after 5 minutes
    )

    # Refresh model list from AI Horde workers
    await registry.refresh()

    # List all available models
    models = registry.list_models()
    print(f"Found {len(models)} models")

    # Get capabilities for a specific model
    caps = registry.get_capabilities("koboldcpp/LLaMA2-13B-Psyfighter2")
    print(f"Max context: {caps.max_context_length}")
    print(f"Max generation: {caps.max_generation_length}")
    print(f"Instruct format: {caps.instruct_format}")
    print(f"Online: {caps.online}")
    print(f"Trusted: {caps.trusted}")

    # Get OpenAI-style model info
    info = registry.get_model_info("koboldcpp/LLaMA2-13B-Psyfighter2")
    if info:
        print(f"Model ID: {info['id']}")
        print(f"Parameters: {info['capabilities']['parameters']}")

asyncio.run(main())
```

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

### Submit Request to AI Horde Async API

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

This Python code snippet shows how to submit a translated request payload to the AI Horde's asynchronous text generation API. It includes setting the necessary API key and client agent headers, and extracts the job ID from the response.

```python
import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://aihorde.net/api/v2/generate/text/async",
    headers={"apikey": API_KEY, "Client-Agent": "interposer:1.0"},
    json=translated_payload
)
job_id = response.json()["id"]
```

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

### Convert AI Horde Response to Chat Format (Python)

Source: https://context7.com/tridefender/opencorde/llms.txt

Translates a response from the AI Horde generation API back into the OpenAI chat completion format. This function reconstructs the standard OpenAI response structure, including message content, finish reasons, and usage statistics. It requires the AI Horde generation output and the original prompt used.

```python
from horde_openai.translate import translate_horde_response_to_chat

# AI Horde generation response
generations = [
    {
        "text": "Why did the programmer quit? Because he didn't get arrays!",
        "internal_error": False,
        "truncated": False
    }
]

response = translate_horde_response_to_chat(
    generations=generations,
    model="koboldcpp/LLaMA2-13B-Psyfighter2",
    original_prompt="### User:\nTell me a joke.\n\n### Response:"
)

print(response)
```

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

### Poll AI Horde for Job Completion

Source: https://github.com/tridefender/opencorde/blob/main/docs/INTERPOSER_SPEC.md

This Python code snippet demonstrates how to poll the AI Horde API to check the status of an asynchronous job. It repeatedly requests the job status until the 'done' field is true, then returns the generated content.

```python
import requests
import time

while True:
    status = requests.get(
        f"https://aihorde.net/api/v2/generate/text/status/{job_id}",
        headers={"Client-Agent": "interposer:1.0"}
    )
    data = status.json()
    if data["done"]:
        return data["generations"]
    time.sleep(2)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.