140 lines
3.1 KiB
Markdown
140 lines
3.1 KiB
Markdown
# 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
|