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

gleam add gllm@1

Usage

Basic Chat Completion

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.

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

Message

Represents a chat message with role and content.

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.

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

completion

Sends a chat completion request to the API.

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

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

Running Tests

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

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.