perplexity

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2024 License: MIT Imports: 11 Imported by: 0

README

Perplexity Go Client

Go Reference

A Go client library for interacting with the Perplexity AI API.

Installation

To install the package, run:

go get github.com/emmaly/perplexity

Features

  • Chat Completions: Generate responses using various models provided by Perplexity AI.
  • Streaming Responses: Support for handling streaming responses with callback functions.
  • Customization: Configure request parameters like temperature, max tokens, top_p, and more.
  • Error Handling: Comprehensive error handling for API responses and network issues.
  • Fully Typed: Typed API requests and responses for a better development experience.
  • No Dependencies: Pure Go implementation with no dependencies outside of the standard library.

Usage

Here's a basic example of how to use the client:

package main

import (
    "context"
    "fmt"

    "github.com/emmaly/perplexity"
)

func main() {
    // Replace with your actual API token
    token := "your_api_token_here"

    // Create a new client
    client := perplexity.NewClient(token, nil)

    // Prepare the chat completion request
    req := perplexity.ChatCompletionRequest{
        Model: perplexity.ModelLlama31SonarLarge128kChat,
        Messages: []perplexity.Message{
            {
                Role:    perplexity.MessageRoleUser,
                Content: "Hello, how are you?",
            },
        },
        MaxTokens:   150,
        Temperature: 0.7,
    }

    // Send the chat completion request
    resp, err := client.ChatCompletion(context.Background(), req)
    if err != nil {
        panic(err)
    }

    // Print the assistant's reply
    fmt.Println(resp.Choices[0].Message.Content)
}
Streaming Responses

To handle streaming responses, provide a callback function to the Stream field:

req := perplexity.ChatCompletionRequest{
    Model: perplexity.ModelLlama31SonarLarge128kChat,
    Messages: []perplexity.Message{
        {
            Role:    perplexity.MessageRoleUser,
            Content: "Tell me a joke.",
        },
    },
    Stream: func(delta perplexity.ChatCompletionResponse) {
        // Handle incremental updates
        fmt.Print(delta.Choices[0].Delta.Content)
    },
}

// The response will be nil when streaming
_, err := client.ChatCompletion(context.Background(), req)
if err != nil {
    panic(err)
}

Available Models

The client supports several models:

  • ModelLlama31SonarSmall128kOnline
  • ModelLlama31SonarLarge128kOnline
  • ModelLlama31SonarHuge128kOnline
  • ModelLlama31SonarSmall128kChat
  • ModelLlama31SonarLarge128kChat
  • ModelLlama31Instruct8b
  • ModelLlama31Instruct70b

Request Parameters

  • Model: Required. The name of the model to use.
  • Messages: Required. Conversation history as a list of messages.
  • MaxTokens: Maximum number of tokens to generate.
  • Temperature: Controls randomness in the output (0 to 2).
  • TopP: Nucleus sampling threshold (0 to 1).
  • ReturnCitations: Include citations in the response (requires beta access).
  • ReturnImages: Include images in the response (requires beta access).
  • ReturnRelatedQuestions: Include related questions (requires beta access).
  • SearchRecencyFilter: Limit search results to recent content (hour, day, week, month).
  • TopK: Number of highest probability tokens to keep for top-k filtering.
  • PresencePenalty: Penalize new tokens based on their presence in the text so far (-2.0 to 2.0).
  • FrequencyPenalty: Penalize new tokens based on their frequency in the text so far (>= 0).

Error Handling

Errors returned by the API are wrapped in Go error types. Check for errors when making API calls:

resp, err := client.ChatCompletion(context.Background(), req)
if err != nil {
    // Handle error
    fmt.Println("Error:", err)
    return
}

Documentation

For more detailed information, refer to the GoDoc documentation.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Note: Replace "your_api_token_here" with your actual Perplexity AI API token. Ensure you handle sensitive information like API tokens securely and avoid hardcoding them in your source code.

Documentation

Overview

Package perplexity provides a client for interacting with the Perplexity AI API.

Example usage: 

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/emmaly/perplexity"
)

func main() {
    // Replace with your actual API token
    token := "<your_api_token>"

    client := perplexity.NewClient(token, nil) // Pass nil to use default settings

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    req := perplexity.ChatCompletionRequest{
        Model: "llama-3.1-sonar-small-128k-online",
        Messages: []perplexity.Message{
            {
                Role:    perplexity.MessageRoleSystem,
                Content: "Be precise and concise.",
            },
            {
                Role:    perplexity.MessageRoleUser,
                Content: "How many stars are there in our galaxy?",
            },
        },
        MaxTokens:              100,
        Temperature:            0.2,
        TopP:                   0.9,
        ReturnCitations:        true,
        SearchDomainFilter:     []string{"perplexity.ai"},
        ReturnImages:           false,
        ReturnRelatedQuestions: false,
        SearchRecencyFilter:    perplexity.RecencyFilterMonth,
        TopK:                   0,
        Stream:                 false,
        PresencePenalty:        0.0,
        FrequencyPenalty:       1.0,
    }

    response, err := client.ChatCompletion(ctx, req)
    if err != nil {
        log.Fatalf("Error calling ChatCompletion: %v", err)
    }

    if len(response.Choices) > 0 {
        fmt.Printf("Assistant's reply: %s\n", response.Choices[0].Message.Content)
    } else {
        fmt.Println("No choices found in the response.")
    }
}

Index

Constants

View Source 
const DefaultBaseURL = "https://api.perplexity.ai"

DefaultBaseURL is the default base URL for the Perplexity API.

Variables

This section is empty.

Functions

This section is empty.

Types

type ChatCompletionRequest 

type ChatCompletionRequest struct {
	// Model is the name of the model that will complete your prompt.
	// Refer to Supported Models to find all the models offered.
	// *This field is required.*
	Model Model `json:"model"`

	// Messages is a list of messages comprising the conversation so far.
	// *This field is required.*
	//
	// ***Warning:** "We do not raise any exceptions if your chat inputs contain messages with special
	// tokens. If avoiding prompt injections is a concern for your use case, it is recommended that
	// you check for special tokens prior to calling the API. For more details, read
	// (Meta’s recommendations for Llama)[https://github.com/meta-llama/llama/blob/008385a/UPDATES.md#token-sanitization-update]."*
	Messages []Message `json:"messages"`

	// MaxTokens is the maximum number of completion tokens returned by the API.
	// If left unspecified, the model will generate tokens until it reaches a stop token
	// or the end of its context window.
	MaxTokens int `json:"max_tokens,omitempty"`

	// Temperature controls the amount of randomness in the response,
	// valued between 0 (inclusive) and 2 (exclusive).
	// Higher values result in more random outputs, while lower values are more deterministic.
	// Default: `0.2`
	Temperature float64 `json:"temperature,omitempty"`

	// TopP is the nucleus sampling threshold, valued between 0 and 1 (inclusive).
	// For each token, the model considers the results of the tokens with TopP probability mass.
	// It's recommended to adjust either TopK or TopP, but not both.
	// Default: `0.9`
	TopP float64 `json:"top_p,omitempty"`

	// ReturnCitations determines whether the response should include citations.
	// Default: `false`
	// *This feature is only available via closed beta access.*
	ReturnCitations bool `json:"return_citations"`

	// SearchDomainFilter limits the citations used by the online model to URLs from the specified domains.
	// Currently limited to only 3 domains for allowlisting and blocklisting.
	// For blocklisting, add a "-" to the beginning of the domain string.
	SearchDomainFilter []string `json:"search_domain_filter"`

	// ReturnImages determines whether the response should include images.
	// Default: `false`
	// *This feature is only available via closed beta access.*
	ReturnImages bool `json:"return_images"`

	// ReturnRelatedQuestions determines whether the response should include related questions.
	// Default: `false`
	// *This feature is only available via closed beta access.*
	ReturnRelatedQuestions bool `json:"return_related_questions"`

	// SearchRecencyFilter restricts search results to within the specified time interval.
	// Does not apply to images.
	// Valid values are `RecencyFilterMonth`, `RecencyFilterWeek`, `RecencyFilterDay`, `RecencyFilterHour`.
	SearchRecencyFilter RecencyFilter `json:"search_recency_filter,omitempty"`

	// TopK is the number of tokens to keep for highest top-k filtering,
	// specified as an integer between 0 and 2048 (inclusive).
	// If set to 0, top-k filtering is disabled.
	// It's recommended to adjust either TopK or TopP, but not both.
	// Default: `0`
	TopK int `json:"top_k,omitempty"`

	// Stream is a callback function that is called when new tokens are generated.
	// If provided, the response will be streamed incrementally as the model generates new tokens.
	// Default: `nil`
	Stream OnUpdateHandler `json:"-"` // this will be set as a bool in MarshalJSON for the API

	// PresencePenalty is a value between -2.0 and 2.0.
	// Positive values penalize new tokens based on whether they appear in the text so far,
	// increasing the model's likelihood to discuss new topics.
	// Incompatible with FrequencyPenalty.
	// Default: `0.0`
	PresencePenalty float64 `json:"presence_penalty,omitempty"`

	// FrequencyPenalty is a multiplicative penalty greater than 0.
	// Values greater than 1.0 penalize new tokens based on their existing frequency in the text so far,
	// decreasing the model's likelihood to repeat the same line verbatim.
	// A value of 1.0 means no penalty.
	// Incompatible with PresencePenalty.
	// Default: `1.0`
	FrequencyPenalty float64 `json:"frequency_penalty,omitempty"`
}

ChatCompletionRequest represents a request for a chat completion.

func (*ChatCompletionRequest) MarshalJSON 

func (req *ChatCompletionRequest) MarshalJSON() ([]byte, error)

MarshalJSON marshals a ChatCompletionRequest into JSON.

type ChatCompletionResponse 

type ChatCompletionResponse struct {
	// ID is an ID generated uniquely for each response.
	ID string `json:"id"`

	// Model is the model used to generate the response.
	Model string `json:"model"`

	// Object is the object type, which always equals `chat.completion`.
	Object string `json:"object"`

	// Created is the Unix timestamp (in seconds) of when the completion was created.
	Created int64 `json:"created"`

	// Choices is the list of completion choices the model generated for the input prompt.
	Choices []Choice `json:"choices"`

	// Usage contains usage statistics for the completion request.
	Usage Usage `json:"usage"`
}

ChatCompletionResponse represents a response from the chat completion API.

type Choice 

type Choice struct {
	// Index is the index of this completion in the list.
	Index int `json:"index"`

	// FinishReason is the reason the model stopped generating tokens.
	// Possible values include `FinishReasonStop` if the model hit a natural stopping point,
	// or `FinishReasonLength` if the maximum number of tokens specified in the request was reached.
	FinishReason FinishReason `json:"finish_reason"`

	// Message is the message generated by the model.
	Message Message `json:"message"`

	// Delta is the incrementally streamed next tokens.
	// Only meaningful when Stream is `true`.
	Delta Message `json:"delta"`
}

Choice represents a single completion choice generated by the model.

type Client 

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

Client is a client for the Perplexity AI API.

func NewClient 

func NewClient(token string, options *ClientOptions) *Client

NewClient creates a new Perplexity API client with the given token. Optionally, you can pass a custom *http.Client to override default settings. If httpClient is nil, a default client with reasonable timeouts is used.

func (*Client) ChatCompletion 

func (c *Client) ChatCompletion(ctx context.Context, req ChatCompletionRequest) (*ChatCompletionResponse, error)

ChatCompletion sends a chat completion request to the Perplexity AI API.

type ClientOptions 

type ClientOptions struct {
	// HTTPClient is an optional *http.Client to use for requests.
	HTTPClient *http.Client

	// BaseURL is the base URL for the Perplexity API.
	// If empty, `DefaultBaseURL` is used.
	BaseURL string
}

ClientOptions represents options for configuring a new Perplexity API client.

type FinishReason 

type FinishReason string

FinishReason represents the reason the model stopped generating tokens. 

const (
	FinishReasonStop   FinishReason = "stop"
	FinishReasonLength FinishReason = "length"
)

type Message 

type Message struct {
	// Role of the speaker in this turn of conversation.
	// Allowed values are `MessageRoleSystem`, `MessageRoleUser`, or `MessageRoleAssistant`.
	Role MessageRole `json:"role"`

	// Content is the contents of the message in this turn of conversation.
	Content string `json:"content"`
}

Message represents a message in the conversation.

type MessageRole 

type MessageRole string

MessageRole represents the role of the speaker in a message. 

const (
	// MessageRoleSystem represents a system message.
	MessageRoleSystem MessageRole = "system"
	// MessageRoleUser represents a user message.
	MessageRoleUser MessageRole = "user"
	// MessageRoleAssistant represents an assistant message.
	MessageRoleAssistant MessageRole = "assistant"
)

type Model 

type Model string

Model represents a model that can complete prompts. 

const (
	// ModelLlama31SonarSmall128kOnline represents the Llama 3.1 Sonar Small 128k Online model.
	ModelLlama31SonarSmall128kOnline Model = "llama-3.1-sonar-small-128k-online"
	// ModelLlama31SonarLarge128kOnline represents the Llama 3.1 Sonar Large 128k Online model.
	ModelLlama31SonarLarge128kOnline Model = "llama-3.1-sonar-large-128k-online"
	// ModelLlama31SonarHuge128kOnline represents the Llama 3.1 Sonar Huge 128k Online model.
	ModelLlama31SonarHuge128kOnline Model = "llama-3.1-sonar-huge-128k-online"

	// ModelLlama31SonarSmall128kChat represents the Llama 3.1 Sonar Small 128k Chat model.
	ModelLlama31SonarSmall128kChat Model = "llama-3.1-sonar-small-128k-chat"
	// ModelLlama31SonarLarge128kChat represents the Llama 3.1 Sonar Large 128k Chat model.
	ModelLlama31SonarLarge128kChat Model = "llama-3.1-sonar-large-128k-chat"

	// ModelLlama31Instruct8b represents the Llama 3.1 Instruct 8b model.
	ModelLlama31Instruct8b Model = "llama-3.1-8b-instruct"
	// ModelLlama31Instruct70b represents the Llama 3.1 Instruct 70b model.
	ModelLlama31Instruct70b Model = "llama-3.1-70b-instruct"
)

type OnUpdateHandler 

type OnUpdateHandler func(delta ChatCompletionResponse)

OnUpdateHandler is a callback function that is called when new tokens are generated.

type RecencyFilter 

type RecencyFilter string

RecencyFilter represents a recency filter for search results. 

const (
	// RecencyFilterHour represents a recency filter for the last hour.
	RecencyFilterHour RecencyFilter = "hour"
	// RecencyFilterDay represents a recency filter for the last day.
	RecencyFilterDay RecencyFilter = "day"
	// RecencyFilterWeek represents a recency filter for the last week.
	RecencyFilterWeek RecencyFilter = "week"
	// RecencyFilterMonth represents a recency filter for the last month.
	RecencyFilterMonth RecencyFilter = "month"
)

type Usage 

type Usage struct {
	// PromptTokens is the number of tokens provided in the request prompt.
	PromptTokens int `json:"prompt_tokens"`

	// CompletionTokens is the number of tokens generated in the response output.
	CompletionTokens int `json:"completion_tokens"`

	// TotalTokens is the total number of tokens used in the chat completion (prompt + completion).
	TotalTokens int `json:"total_tokens"`
}

Usage contains usage statistics for the completion request.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.