# uncloseai. Ruby Client

A Ruby client library for interacting with vLLM, Ollama, and OpenAI-compatible APIs.

## Features

- 🔍 **Automatic Model Discovery** - Discovers available models from configured endpoints
- 💬 **Chat Completions** - Both streaming and non-streaming modes
- 🎙️ **Text-to-Speech** - Generate audio from text with multiple voice options
- 🔄 **Multiple Endpoints** - Support for multiple model and TTS endpoints
- 🛡️ **Error Handling** - Comprehensive error handling with custom exceptions
- 💎 **Pure Ruby** - No external dependencies, uses only standard library

## Installation

```bash
# Copy the library file to your project
cp uncloseai_lib.rb your-project/

# Or require it directly
require_relative 'uncloseai_lib'
```

## Quick Start

```ruby
require_relative 'uncloseai_lib'

# Initialize client (auto-discovers from environment variables)
client = uncloseai::Client.new

# Non-streaming chat
response = client.chat(
  [{ role: 'user', content: 'Hello!' }]
)
puts response['choices'][0]['message']['content']

# Streaming chat
client.chat_stream(
  [{ role: 'user', content: 'Write a story' }]
) do |chunk|
  content = chunk.dig('choices', 0, 'delta', 'content')
  print content if content
end
```

## Configuration

### Environment Variables

```bash
export MODEL_ENDPOINT_1="https://hermes.ai.unturf.com/v1"
export MODEL_ENDPOINT_2="https://qwen.ai.unturf.com/v1"
export TTS_ENDPOINT_1="https://speech.ai.unturf.com/v1"
```

### Programmatic Configuration

```ruby
client = uncloseai::Client.new(
  endpoints: ['https://api.example.com/v1'],
  tts_endpoints: ['https://tts.example.com/v1'],
  api_key: 'your-api-key',
  timeout: 30,
  debug: true
)
```

## API Reference

### uncloseai::Client

#### `new(endpoints: nil, tts_endpoints: nil, api_key: nil, timeout: 30, debug: false)`

Initialize the client.

#### `list_models() → Array<ModelInfo>`

List all discovered models.

#### `chat(messages, model: 'auto', max_tokens: nil, temperature: 0.7, top_p: 1.0) → Hash`

Send a non-streaming chat completion request.

#### `chat_stream(messages, model: 'auto', max_tokens: nil, temperature: 0.7, top_p: 1.0) { |chunk| ... }`

Send a streaming chat completion request. Yields each chunk.

#### `tts(text, voice: 'alloy', model: 'tts-1') → String`

Generate speech from text. Returns binary MP3 data.

## Examples

### Basic Chat

```ruby
client = uncloseai::Client.new

response = client.chat(
  [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is Ruby?' }
  ],
  max_tokens: 100
)

puts response['choices'][0]['message']['content']
```

### Streaming Chat

```ruby
client.chat_stream(
  [{ role: 'user', content: 'Write a haiku about code' }]
) do |chunk|
  content = chunk.dig('choices', 0, 'delta', 'content')
  print content if content
end
```

### Text-to-Speech

```ruby
audio = client.tts('Hello from uncloseai.!', voice: 'alloy')
File.binwrite('speech.mp3', audio)
```

## Running Examples

```bash
export MODEL_ENDPOINT_1="https://hermes.ai.unturf.com/v1"
export TTS_ENDPOINT_1="https://speech.ai.unturf.com/v1"

ruby examples.rb
```

## License

MIT License