openrouterapigo

README

OpenRouter API Go Client

This library provides a Go client for interacting with the OpenRouter API. It allows you to easily send chat completion requests and receive responses, both synchronously and via streaming.

Installation

go get github.com/askie/openrouter-api-go

Usage

Synchronous Request

package main

import (
	"fmt"
	"github.com/askie/openrouter-api-go"
)

func main() {
	client := openrouterapigo.NewOpenRouterClient("YOUR_OPENROUTER_API_KEY")

	request := openrouterapigo.Request{
		Messages: []openrouterapigo.MessageRequest{
			{Role: openrouterapigo.RoleUser, Content: "Hello"},
		},
	}

	response, err := client.FetchChatCompletions(request)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Response: %s\n", response.Choices[0].Message.Content)
}

Streaming Request

package main

import (
	"context"
	"fmt"
	"github.com/askie/openrouter-api-go"
)

func main() {
	client := openrouterapigo.NewOpenRouterClient("YOUR_OPENROUTER_API_KEY")

	request := openrouterapigo.Request{
		Model: "meta-llama/llama-3.2-1b-instruct",
		Messages: []openrouterapigo.MessageRequest{
			{Role: openrouterapigo.RoleUser, Content: "Hello"},
		},
		Stream: true, // Enable streaming
	}

	outputChan := make(chan openrouterapigo.Response)
	processingChan := make(chan interface{})
	errChan := make(chan error)
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	go client.FetchChatCompletionsStream(request, outputChan, processingChan, errChan, ctx)

	for {
		select {
		case output := <-outputChan:
			fmt.Printf("%s", output.Choices[0].Delta.Content) // Access delta content for streaming responses
		case <-processingChan:
			// Handle processing events (optional)
		case err := <-errChan:
			if err != nil {
				fmt.Printf("Error: %v\n", err)
			}
			return
		case <-ctx.Done():
			fmt.Println("Context cancelled")
			return
		}
	}
}

Router Agent

The router_agent.go file introduces a RouterAgent. The RouterAgent simplifies the API for processing requests, abstracting away the need to manage channels and context directly for streaming requests.

RouterAgent Example

client := openrouterapigo.NewOpenRouterClient("YOUR_OPENROUTER_API_KEY")
agent := openrouterapigo.NewRouterAgent(client, "your-model", openrouterapigo.RouterAgentConfig{})
response, err := agent.Completion("your prompt")
// or for streaming
agent.CompletionStream("your prompt", outputChan, processingChan, errChan, ctx)

RouterAgentChat Example

client := openrouterapigo.NewOpenRouterClient("YOUR_OPENROUTER_API_KEY")
agent := openrouterapigo.NewRouterAgentChat(client, "your-model", openrouterapigo.RouterAgentConfig{}, "Initial system prompt")
agent.Chat("First message")
agent.Chat("Second message")
// Access the conversation history via agent.Messages

Specifying Model

You can specify a specific model to use with the Model field in the Request struct. If no model is specified, OpenRouter will select a default model.

request := openrouterapigo.Request{
    Model: "google/flan-t5-xxl",
    Messages: []openrouterapigo.MessageRequest{
        {Role: openrouterapigo.RoleUser, Content: "Translate 'Hello' to French."},
    },
}

Setting Provider Preferences

You can set provider preferences using the Provider field in the Request struct. This allows you to specify the RefererURL and SiteName for your request.

request := openrouterapigo.Request{
    // ... other request fields
    Provider: &openrouterapigo.ProviderPreferences{
        RefererURL: "https://yourwebsite.com",
        SiteName:   "Your Website Name",
    },
}

Contributing

Contributions are welcome! Feel free to open issues and submit pull requests.

License

This project is licensed under the MIT License

Documentation

Index

• type Choice
• type ContentPart
• type ContnetType
• type Delta
• type ErrorResponse
• type FunctionDescription
• type ImageURL
• type MessageRequest
• type MessageResponse
• type MessageRole
• type OpenRouterClient
  • func NewOpenRouterClient(apiKey string) *OpenRouterClient
  • func NewOpenRouterClientFull(apiKey string, apiUrl string, client *http.Client) *OpenRouterClient
  • func (c *OpenRouterClient) FetchChatCompletions(request Request) (*Response, error)
  • func (c *OpenRouterClient) FetchChatCompletionsStream(request Request, outputChan chan Response, processingChan chan interface{}, ...)
• type Prediction
• type ProviderPreferences
• type Request
• type Response
• type ResponseFormat
• type ResponseUsage
• type RouterAgent
  • func NewRouterAgent(client *OpenRouterClient, model string, config RouterAgentConfig) *RouterAgent
  • func (agent RouterAgent) Chat(messages []MessageRequest) (*Response, error)
  • func (agent RouterAgent) ChatStream(messages []MessageRequest, outputChan chan Response, ...)
  • func (agent RouterAgent) Completion(prompt string) (*Response, error)
  • func (agent RouterAgent) CompletionStream(prompt string, outputChan chan Response, processingChan chan interface{}, ...)
• type RouterAgentChat
  • func NewRouterAgentChat(client *OpenRouterClient, model string, config RouterAgentConfig, ...) RouterAgentChat
  • func (agent *RouterAgentChat) Chat(message string) error
• type RouterAgentConfig
• type Tool
• type ToolCall
• type ToolChoice

Types

type Choice

type Choice struct {
	FinishReason string           `json:"finish_reason"`
	Text         string           `json:"text,omitempty"`
	Message      *MessageResponse `json:"message,omitempty"`
	Delta        *Delta           `json:"delta,omitempty"`
	Error        *ErrorResponse   `json:"error,omitempty"`
}

type ContentPart

type ContentPart struct {
	Type     ContnetType `json:"type"`
	Text     string      `json:"text,omitempty"`
	ImageURL *ImageURL   `json:"image_url,omitempty"`
}

ContentPart represents the content part structure.

type ContnetType

type ContnetType string

const (
	ContentTypeText  ContnetType = "text"
	ContentTypeImage ContnetType = "image_url"
)

type Delta

type Delta struct {
	Content   string     `json:"content"`
	Role      string     `json:"role,omitempty"`
	Reasoning string     `json:"reasoning,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
}

type ErrorResponse

type ErrorResponse struct {
	Code     int                    `json:"code"`
	Message  string                 `json:"message"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type FunctionDescription

type FunctionDescription struct {
	Description string      `json:"description,omitempty"`
	Name        string      `json:"name"`
	Parameters  interface{} `json:"parameters"` // JSON Schema object
}

FunctionDescription represents the function description structure.

type ImageURL

type ImageURL struct {
	URL    string `json:"url"`
	Detail string `json:"detail,omitempty"`
}

ImageURL represents the image URL structure.

type MessageRequest

type MessageRequest struct {
	Role       MessageRole `json:"role"`
	Content    interface{} `json:"content"` // Can be string or []ContentPart
	Name       string      `json:"name,omitempty"`
	ToolCallID string      `json:"tool_call_id,omitempty"`
}

Message represents the message structure.

type MessageResponse

type MessageResponse struct {
	Content   string     `json:"content"`
	Role      string     `json:"role"`
	Reasoning string     `json:"reasoning,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
}

type MessageRole

type MessageRole string

const (
	RoleSystem    MessageRole = "system"
	RoleUser      MessageRole = "user"
	RoleAssistant MessageRole = "assistant"
	RoleTool      MessageRole = "tool"
)

type OpenRouterClient

type OpenRouterClient struct {
	// contains filtered or unexported fields
}

func NewOpenRouterClient

func NewOpenRouterClient(apiKey string) *OpenRouterClient

func NewOpenRouterClientFull

func NewOpenRouterClientFull(apiKey string, apiUrl string, client *http.Client) *OpenRouterClient

func (*OpenRouterClient) FetchChatCompletions

func (c *OpenRouterClient) FetchChatCompletions(request Request) (*Response, error)

func (*OpenRouterClient) FetchChatCompletionsStream

func (c *OpenRouterClient) FetchChatCompletionsStream(request Request, outputChan chan Response, processingChan chan interface{}, errChan chan error, ctx context.Context)

type Prediction

type Prediction struct {
	Type    string `json:"type"`
	Content string `json:"content"`
}

Prediction represents the prediction structure.

type ProviderPreferences

type ProviderPreferences struct {
	RefererURL string `json:"referer_url,omitempty"`
	SiteName   string `json:"site_name,omitempty"`
}

ProviderPreferences represents the provider preferences structure.

type Request

type Request struct {
	Messages          []MessageRequest     `json:"messages,omitempty"`
	Prompt            string               `json:"prompt,omitempty"`
	Model             string               `json:"model,omitempty"`
	ResponseFormat    *ResponseFormat      `json:"response_format,omitempty"`
	Stop              []string             `json:"stop,omitempty"`
	Stream            bool                 `json:"stream,omitempty"`
	MaxTokens         int                  `json:"max_tokens,omitempty"`
	Temperature       float64              `json:"temperature,omitempty"`
	Tools             []Tool               `json:"tools,omitempty"`
	ToolChoice        ToolChoice           `json:"tool_choice,omitempty"`
	Seed              int                  `json:"seed,omitempty"`
	TopP              float64              `json:"top_p,omitempty"`
	TopK              int                  `json:"top_k,omitempty"`
	FrequencyPenalty  float64              `json:"frequency_penalty,omitempty"`
	PresencePenalty   float64              `json:"presence_penalty,omitempty"`
	RepetitionPenalty float64              `json:"repetition_penalty,omitempty"`
	LogitBias         map[int]float64      `json:"logit_bias,omitempty"`
	TopLogprobs       int                  `json:"top_logprobs,omitempty"`
	MinP              float64              `json:"min_p,omitempty"`
	TopA              float64              `json:"top_a,omitempty"`
	Prediction        *Prediction          `json:"prediction,omitempty"`
	Transforms        []string             `json:"transforms,omitempty"`
	Models            []string             `json:"models,omitempty"`
	Route             string               `json:"route,omitempty"`
	Provider          *ProviderPreferences `json:"provider,omitempty"`
	IncludeReasoning  bool                 `json:"include_reasoning,omitempty"`
}

Request represents the main request structure.

type Response

type Response struct {
	ID                string         `json:"id"`
	Choices           []Choice       `json:"choices"`
	Created           int64          `json:"created"`
	Model             string         `json:"model"`
	Object            string         `json:"object"`
	SystemFingerprint *string        `json:"system_fingerprint,omitempty"`
	Usage             *ResponseUsage `json:"usage,omitempty"`
}

type ResponseFormat

type ResponseFormat struct {
	Type string `json:"type"`
}

ResponseFormat represents the response format structure.

type ResponseUsage

type ResponseUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type RouterAgent

type RouterAgent struct {
	// contains filtered or unexported fields
}

func NewRouterAgent

func NewRouterAgent(client *OpenRouterClient, model string, config RouterAgentConfig) *RouterAgent

func (RouterAgent) Chat

func (agent RouterAgent) Chat(messages []MessageRequest) (*Response, error)

func (RouterAgent) ChatStream

func (agent RouterAgent) ChatStream(messages []MessageRequest, outputChan chan Response, processingChan chan interface{}, errChan chan error, ctx context.Context)

func (RouterAgent) Completion

func (agent RouterAgent) Completion(prompt string) (*Response, error)

func (RouterAgent) CompletionStream

func (agent RouterAgent) CompletionStream(prompt string, outputChan chan Response, processingChan chan interface{}, errChan chan error, ctx context.Context)

type RouterAgentChat

type RouterAgentChat struct {
	RouterAgent
	Messages []MessageRequest
}

func NewRouterAgentChat

func NewRouterAgentChat(client *OpenRouterClient, model string, config RouterAgentConfig, system_prompt string) RouterAgentChat

func (*RouterAgentChat) Chat

func (agent *RouterAgentChat) Chat(message string) error

type RouterAgentConfig

type RouterAgentConfig struct {
	ResponseFormat    *ResponseFormat `json:"response_format,omitempty"`
	Stop              []string        `json:"stop,omitempty"`
	MaxTokens         int             `json:"max_tokens,omitempty"`
	Temperature       float64         `json:"temperature,omitempty"`
	Tools             []Tool          `json:"tools,omitempty"`
	ToolChoice        ToolChoice      `json:"tool_choice,omitempty"`
	Seed              int             `json:"seed,omitempty"`
	TopP              float64         `json:"top_p,omitempty"`
	TopK              int             `json:"top_k,omitempty"`
	FrequencyPenalty  float64         `json:"frequency_penalty,omitempty"`
	PresencePenalty   float64         `json:"presence_penalty,omitempty"`
	RepetitionPenalty float64         `json:"repetition_penalty,omitempty"`
	LogitBias         map[int]float64 `json:"logit_bias,omitempty"`
	TopLogprobs       int             `json:"top_logprobs,omitempty"`
	MinP              float64         `json:"min_p,omitempty"`
	TopA              float64         `json:"top_a,omitempty"`
}

type Tool

type Tool struct {
	Type     string              `json:"type"`
	Function FunctionDescription `json:"function"`
}

Tool represents the tool structure.

type ToolCall

type ToolCall struct {
	ID       string      `json:"id"`
	Type     string      `json:"type"`
	Function interface{} `json:"function"`
}

type ToolChoice

type ToolChoice struct {
	Type     string `json:"type"`
	Function struct {
		Name string `json:"name"`
	} `json:"function"`
}

ToolChoice represents the tool choice structure.