# gllm

[![Package Version](https://img.shields.io/hexpm/v/gllm)](https://hex.pm/packages/gllm)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gllm/)

Gleam library for interacting with OpenAI-compatible APIs.

**⚠️ Important Note**: This is **not** a complete library. Currently, only simple chat completion queries to LLM have been implemented. The library is in early development and may not support all features of OpenAI-compatible APIs.

## Current Limitations

- Only supports basic chat completion requests
- No streaming support
- Limited error handling
- No support for other OpenAI features (embeddings, images, etc.)
- Only works with synchronous requests


## Installation

```sh
gleam add gllm@1
```

## Usage

### Basic Chat Completion

```gleam
import gllm
import gllm/types/message
import glenvy/dotenv
import glenvy/env

pub fn main() {
  // Load environment variables (optional)
  let _ = dotenv.load()
  
  // Get API key from environment
  let assert Ok(api_key) = env.string("OPENROUTER_API_KEY")
  let base_url = "https://openrouter.ai/api/v1"
  
  // Create client
  let client = gllm.Client(api_key, base_url)
  
  // Create messages
  let messages = [
    gllm.new_message("system", "You are a helpful assistant."),
    gllm.new_message("user", "Hello, how are you?")
  ]
  
  // Send completion request
  case gllm.completion(client, "openai/gpt-oss-20b", messages, 0.7) {
    Ok(completion) -> {
      io.println("Success!")
      io.println("Response: " <> completion.choices.0.message.content)
    }
    Error(error) -> {
      io.println("Error: " <> string.inspect(error))
    }
  }
}
```

### Supported Providers

The library works with any OpenAI-compatible API:

- **OpenAI**: `https://api.openai.com`
- **OpenRouter**: `https://openrouter.ai/api/v1`
- **All other LLM providers**: Any server that provides OpenAI-compatible endpoints

## API Reference

### Types

#### `Client`

Represents an API client with authentication and endpoint configuration.

```gleam
pub type Client {
  Client(api_key: String, base_url: String)
}
```

#### `Message`

Represents a chat message with role and content.

```gleam
pub type Message {
  Message(
    role: String,
    content: String,
    refusal: Option(String),
    reasoning: Option(String),
    reasoning_details: Option(List(ReasoningDetail)),
  )
}
```

### Functions

#### `new_message`

Creates a new message with the given role and content.

```gleam
pub fn new_message(role: String, content: String) -> Message
```

#### `completion`

Sends a chat completion request to the API.

```gleam
pub fn completion(
  client: Client,
  model: String,
  messages: List(Message),
  temperature: Float,
) -> Result(ChatCompletion, ApiError)
```

**Parameters:**
- `client`: API client containing authentication and endpoint info
- `model`: Model identifier (e.g., "gpt-3.5-turbo", "openai/gpt-oss-20b")
- `messages`: List of messages representing conversation history
- `temperature`: Controls randomness (0.0 to 2.0, lower = more focused)

**Returns:**
- `Ok(ChatCompletion)` on success
- `Error(ApiError)` on failure

## Development

```sh
gleam run   # Run the project
gleam test  # Run the tests
```

### Running Tests

The tests require valid API credentials. Set up your environment variables:

```sh
export OPENROUTER_API_KEY=your_api_key_here
gleam test
```

## License

This project is licensed under the same terms as Gleam. See the LICENSE file for details.

Further documentation can be found at <https://hexdocs.pm/gllm>.