package app import ( "bytes" "encoding/json" "fmt" "io" "strings" ) // A content feature is absent, disabled, enabled, or an options object. type Feature struct { Set, Enabled bool Query string MaxCharacters int } func (f *Feature) UnmarshalJSON(b []byte) error { f.Set = true switch string(bytes.TrimSpace(b)) { case "true": f.Enabled = true return nil case "false", "null": return nil } var opts struct { Query string `json:"query"` MaxCharacters int `json:"maxCharacters"` } if err := strictJSON(b, &opts); err != nil { return err } if opts.MaxCharacters < 0 || opts.MaxCharacters > 10000 || len(opts.Query) > 4000 { return fmt.Errorf("invalid content query or maxCharacters (1–10000)") } *f = Feature{Set: true, Enabled: true, Query: opts.Query, MaxCharacters: opts.MaxCharacters} return nil } type ContentsOptions struct { Text Feature `json:"text"` Highlights Feature `json:"highlights"` Summary Feature `json:"summary"` MaxAgeHours *int `json:"maxAgeHours"` LivecrawlTimeout int `json:"livecrawlTimeout"` } func (o *ContentsOptions) defaults(contents bool) error { if contents && !o.Text.Set && !o.Highlights.Set && !o.Summary.Set { o.Text = Feature{Set: true, Enabled: true} } if o.MaxAgeHours != nil && (*o.MaxAgeHours < -1 || *o.MaxAgeHours > 720) { return fmt.Errorf("maxAgeHours must be -1 through 720") } if o.LivecrawlTimeout < 0 || o.LivecrawlTimeout > 90000 { return fmt.Errorf("livecrawlTimeout must be 1–90000 milliseconds") } if o.Summary.MaxCharacters != 0 { return fmt.Errorf("summary accepts query, not maxCharacters") } if o.Text.Query != "" { return fmt.Errorf("text accepts maxCharacters, not query") } return nil } type SearchRequest struct { Query string `json:"query"` Type string `json:"type"` NumResults int `json:"numResults"` IncludeDomains []string `json:"includeDomains"` ExcludeDomains []string `json:"excludeDomains"` Contents *ContentsOptions `json:"contents"` // minScore drops candidates the reranker scored lower, keeping at least the // best one; answer() uses it so that off-topic results never become sources. minScore float64 } func (q *SearchRequest) validate() error { q.Query = strings.TrimSpace(q.Query) if q.Query == "" || len(q.Query) > 4000 { return fmt.Errorf("query must contain 1–4000 bytes") } if q.Type != "" && q.Type != "auto" { return fmt.Errorf("only type=auto is supported; this is kagi + jev, not exa's index") } if q.NumResults == 0 { q.NumResults = 10 } if q.NumResults < 1 || q.NumResults > 20 { return fmt.Errorf("numResults must be 1–20") } for _, domains := range [][]string{q.IncludeDomains, q.ExcludeDomains} { if len(domains) > 20 { return fmt.Errorf("at most 20 domain filters") } for _, d := range domains { if _, err := domainFilter(d); err != nil { return err } } } if q.Contents != nil { return q.Contents.defaults(false) } return nil } type ContentsRequest struct { IDs []string `json:"ids"` URLs []string `json:"urls"` ContentsOptions } func (q *ContentsRequest) validate() ([]string, error) { if (len(q.IDs) == 0) == (len(q.URLs) == 0) { return nil, fmt.Errorf("provide exactly one of ids or urls") } urls := q.URLs if len(q.IDs) > 0 { urls = q.IDs } if len(urls) > 20 { return nil, fmt.Errorf("at most 20 urls per request") } for _, raw := range urls { if _, err := parseWebURL(raw); err != nil { return nil, err } } return urls, q.ContentsOptions.defaults(true) } type AnswerRequest struct { Query string `json:"query"` Text bool `json:"text"` Stream bool `json:"stream"` } type Result struct { ID string `json:"id"` URL string `json:"url"` Title string `json:"title"` PublishedDate string `json:"publishedDate,omitempty"` Author string `json:"author,omitempty"` Text *string `json:"text,omitempty"` Highlights *[]string `json:"highlights,omitempty"` HighlightScores *[]float64 `json:"highlightScores,omitempty"` Summary *string `json:"summary,omitempty"` // Internal evidence is never confused with generated text or put on Exa's wire. pack EvidencePack score float64 snippet string } type ItemError struct { Tag string `json:"tag"` HTTPStatusCode int `json:"httpStatusCode,omitempty"` } type ItemStatus struct { ID string `json:"id"` Status string `json:"status"` Source string `json:"source,omitempty"` Error *ItemError `json:"error,omitempty"` } type ResultsResponse struct { RequestID string `json:"requestId"` Results []Result `json:"results"` Statuses []ItemStatus `json:"statuses,omitempty"` } type AnswerResponse struct { RequestID string `json:"requestId"` Answer string `json:"answer"` Citations []Result `json:"citations"` } type APIError struct { Status int `json:"-"` RequestID string `json:"requestId"` Message string `json:"error"` Tag string `json:"tag"` } func (e *APIError) Error() string { return e.Message } func failure(status int, tag, message string) error { return &APIError{Status: status, Tag: tag, Message: message} } func strictJSON(b []byte, dst any) error { d := json.NewDecoder(bytes.NewReader(b)) d.DisallowUnknownFields() if err := d.Decode(dst); err != nil { return err } var extra any if err := d.Decode(&extra); err != io.EOF { return fmt.Errorf("expected one json value") } return nil }