perplexity

README

perplexity

Package perplexity wraps Perplexity's OpenAI-compatible Sonar API. Every Sonar model runs an online retrieval step before answering; the response includes citations + search results. Perplexity-specific knobs are exposed as RequestOptions through RequestExtensionKey: - "search_mode" ("web" / "academic"), "search_domain_filter", "search_recency_filter" steer the underlying web search. - "return_images" / "return_related_questions" toggle extra response fields. - "web_search_options" controls per-call search behavior (search context size, user location, etc.). Response extras (citations, search_results, images, related_questions, detailed usage, and costs) are preserved from the exact provider JSON in the namespaced Core response extension. See https://docs.perplexity.ai/ for the full API reference.

Install

go get github.com/Tangerg/scope/models/perplexity

Constructors

Every constructor validates its config and returns a value implementing the Model contracts in core:

• NewOpenAIChat

Testing

This module integrates a third-party service, so its tests cover what runs without live credentials: config validation, request and response mapping, and error classification. The shared conformance contract is core/modeltest for behavior and dev/providerconformance for construction and API consistency — this module runs it rather than copying it.

An integration probe skips unless its credential environment variable is set, so go test ./... is always runnable offline.

Boundaries

This is an independent leaf module: it carries only its own SDK dependency and never imports a sibling provider. The shared contract every module in this family obeys is in ../ARCHITECTURE.md.

See ARCHITECTURE.md for what this module owns.

Documentation

Overview

Package perplexity wraps Perplexity's OpenAI-compatible Sonar API. Every Sonar model runs an online retrieval step before answering; the response includes citations + search results.

Perplexity-specific knobs are exposed as RequestOptions through RequestExtensionKey:

• "search_mode" ("web" / "academic"), "search_domain_filter", "search_recency_filter" steer the underlying web search.
• "return_images" / "return_related_questions" toggle extra response fields.
• "web_search_options" controls per-call search behavior (search context size, user location, etc.).

Response extras (citations, search_results, images, related_questions, detailed usage, and costs) are preserved from the exact provider JSON in the namespaced Core response extension.

See https://docs.perplexity.ai/ for the full API reference.

Index

• Constants
• type ImageFormat
  • func (i ImageFormat) Valid() bool
• type OpenAIChat
  • func NewOpenAIChat(config OpenAIChatConfig) (*OpenAIChat, error)
• type OpenAIChatConfig
  • func (o OpenAIChatConfig) Validate() error
• type ReasoningEffort
  • func (r ReasoningEffort) Valid() bool
• type RequestOptions
  • func (r RequestOptions) ValidateFor(model string, stream bool) error
• type SearchContextSize
  • func (s SearchContextSize) Valid() bool
• type SearchDate
  • func (s SearchDate) Valid() bool
• type SearchMode
  • func (s SearchMode) Valid() bool
• type SearchRecency
  • func (s SearchRecency) Valid() bool
• type SearchType
  • func (s SearchType) Valid() bool
• type UserLocation
  • func (u UserLocation) Validate() error
• type WebSearchOptions
  • func (w WebSearchOptions) ValidateFor(model string, stream bool) error

Constants

const (
	OpenAIResponseExtensionKey    = "perplexity/openai_response"
	OpenAIStreamChunkExtensionKey = "perplexity/openai_stream_chunk"
)

const (
	Provider = "Perplexity"

	BaseURL = "https://api.perplexity.ai"
)

const (
	ModelSonar             = "sonar"
	ModelSonarPro          = "sonar-pro"
	ModelSonarReasoningPro = "sonar-reasoning-pro"
	ModelSonarDeepResearch = "sonar-deep-research"
)

Sonar online-search models. See https://docs.perplexity.ai/guides/model-cards for the current catalog. ModelSonarDeepResearch runs an extended multi-hop research loop — slow, expensive, produces deeply-cited reports.

const (
	RequestExtensionKey = "perplexity/request"
)

Types

type ImageFormat

type ImageFormat string

ImageFormat names one image format accepted by Sonar image filtering.

const (
	ImageFormatGIF  ImageFormat = "gif"
	ImageFormatJPG  ImageFormat = "jpg"
	ImageFormatJPEG ImageFormat = "jpeg"
	ImageFormatPNG  ImageFormat = "png"
	ImageFormatWebP ImageFormat = "webp"
)

func (ImageFormat) Valid

func (i ImageFormat) Valid() bool

type OpenAIChat

type OpenAIChat = openai.Chat

OpenAIChat implements Perplexity's OpenAI-compatible endpoint.

func NewOpenAIChat

func NewOpenAIChat(config OpenAIChatConfig) (*OpenAIChat, error)

type OpenAIChatConfig

type OpenAIChatConfig struct {
	APIKey         string
	DefaultOptions corechat.Options
	BaseURL        string
	HTTPClient     *http.Client
}

func (OpenAIChatConfig) Validate

func (o OpenAIChatConfig) Validate() error

type ReasoningEffort

type ReasoningEffort string

const (
	ReasoningEffortMinimal ReasoningEffort = "minimal"
	ReasoningEffortLow     ReasoningEffort = "low"
	ReasoningEffortMedium  ReasoningEffort = "medium"
	ReasoningEffortHigh    ReasoningEffort = "high"
)

func (ReasoningEffort) Valid

func (r ReasoningEffort) Valid() bool

type RequestOptions

type RequestOptions struct {
	WebSearchOptions        *WebSearchOptions `json:"web_search_options,omitempty"`
	SearchMode              SearchMode        `json:"search_mode,omitempty"`
	ReturnImages            *bool             `json:"return_images,omitempty"`
	ReturnRelatedQuestions  *bool             `json:"return_related_questions,omitempty"`
	EnableSearchClassifier  *bool             `json:"enable_search_classifier,omitempty"`
	DisableSearch           *bool             `json:"disable_search,omitempty"`
	SearchDomainFilter      []string          `json:"search_domain_filter,omitempty"`
	SearchLanguageFilter    []string          `json:"search_language_filter,omitempty"`
	SearchRecencyFilter     SearchRecency     `json:"search_recency_filter,omitempty"`
	SearchAfterDateFilter   SearchDate        `json:"search_after_date_filter,omitempty"`
	SearchBeforeDateFilter  SearchDate        `json:"search_before_date_filter,omitempty"`
	LastUpdatedBeforeFilter SearchDate        `json:"last_updated_before_filter,omitempty"`
	LastUpdatedAfterFilter  SearchDate        `json:"last_updated_after_filter,omitempty"`
	ImageFormatFilter       []ImageFormat     `json:"image_format_filter,omitempty"`
	ImageDomainFilter       []string          `json:"image_domain_filter,omitempty"`
	ReasoningEffort         ReasoningEffort   `json:"reasoning_effort,omitempty"`
	LanguagePreference      string            `json:"language_preference,omitempty"`
}

RequestOptions contains the documented Sonar fields without a neutral Core equivalent. Store it in [chat.Options.Extensions] under RequestExtensionKey.

func (RequestOptions) ValidateFor

func (r RequestOptions) ValidateFor(model string, stream bool) error

type SearchContextSize

type SearchContextSize string

const (
	SearchContextLow    SearchContextSize = "low"
	SearchContextMedium SearchContextSize = "medium"
	SearchContextHigh   SearchContextSize = "high"
)

func (SearchContextSize) Valid

func (s SearchContextSize) Valid() bool

type SearchDate

type SearchDate string

SearchDate is a Sonar search boundary encoded as MM/DD/YYYY.

func (SearchDate) Valid

func (s SearchDate) Valid() bool

type SearchMode

type SearchMode string

const (
	SearchModeWeb      SearchMode = "web"
	SearchModeAcademic SearchMode = "academic"
	SearchModeSEC      SearchMode = "sec"
)

func (SearchMode) Valid

func (s SearchMode) Valid() bool

type SearchRecency

type SearchRecency string

const (
	SearchRecencyHour  SearchRecency = "hour"
	SearchRecencyDay   SearchRecency = "day"
	SearchRecencyWeek  SearchRecency = "week"
	SearchRecencyMonth SearchRecency = "month"
	SearchRecencyYear  SearchRecency = "year"
)

func (SearchRecency) Valid

func (s SearchRecency) Valid() bool

type SearchType

type SearchType string

const (
	SearchTypeFast SearchType = "fast"
	SearchTypeAuto SearchType = "auto"
	SearchTypePro  SearchType = "pro"
)

func (SearchType) Valid

func (s SearchType) Valid() bool

type UserLocation

type UserLocation struct {
	Country   string   `json:"country,omitempty"`
	Region    string   `json:"region,omitempty"`
	City      string   `json:"city,omitempty"`
	Latitude  *float64 `json:"latitude,omitempty"`
	Longitude *float64 `json:"longitude,omitempty"`
}

UserLocation biases Sonar search toward one geographic location.

func (UserLocation) Validate

func (u UserLocation) Validate() error

type WebSearchOptions

type WebSearchOptions struct {
	SearchContextSize SearchContextSize `json:"search_context_size,omitempty"`
	SearchType        SearchType        `json:"search_type,omitempty"`
	UserLocation      *UserLocation     `json:"user_location,omitempty"`
}

WebSearchOptions controls Sonar's retrieval depth and Pro Search routing.

func (WebSearchOptions) ValidateFor

func (w WebSearchOptions) ValidateFor(model string, stream bool) error