v1

README

Swagger Docs

Swagger docs are generated through swaggo/swag from Go annotations in the Godoc comments.

Install swag

go install github.com/swaggo/swag/cmd/swag@latest

Generate docs

swag init -g api.go -o http/docs/

Documentation

Index

• Constants
• func ErrorCode(err error) string
• func ErrorMessage(err error) string
• type Chunking
• type ChunkingInput
• type ChunkingResponse
• type Dim
• type Embedding
• type EmbeddingsResponse
• type EmbeddingsUpdate
• type Error
  • func Errorf(code string, format string, args ...interface{}) *Error
  • func (e *Error) Error() string
• type ErrorResponse
• type Page
• type Projection
• type ProjectionsResponse
• type ProjectionsUpdate
• type Provider
• type ProviderFilter
• type ProvidersResponse
• type ProvidersService

Constants

const (
	ECONFLICT       = "conflict"
	EINTERNAL       = "internal"
	EINVALID        = "invalid"
	ENOTFOUND       = "not_found"
	ENOTIMPLEMENTED = "not_implemented"
	EUNAUTHORIZED   = "unauthorized"
)

API error codes.

const (
	ProjMetaKey  = "projection"
	LabelMetaKey = "label"
)

const (
	// DefaultLimit defines default results limit
	DefaultLimit = 20
)

Functions

func ErrorCode

func ErrorCode(err error) string

ErrorCode unwraps an application error and returns its code. Non-application errors always return EINTERNAL.

func ErrorMessage

func ErrorMessage(err error) string

ErrorMessage unwraps an application error and returns its message. Non-application errors always return "Internal error".

Types

type Chunking

type Chunking struct {
	// Size of each chunk.
	Size int `json:"size"`
	// Overlap between chunks.
	Overlap int `json:"overlap"`
	// Trim empty space chars.
	Trim bool `json:"trim"`
	// Sep keeps separator in chunks.
	Sep bool `json:"sep"`
}

Chunking splits input text into chunks if enabled.

type ChunkingInput

type ChunkingInput struct {
	// Options to configure chunking.
	Options Chunking `json:"options"`
	// Input to split into chunks.
	Input string `json:"input"`
}

ChunkingInput is used for chunking.

type ChunkingResponse

type ChunkingResponse struct {
	// Chunks contain indices into the chunked input.
	Chunks [][]int `json:"chunks"`
}

ChunkingResponse is returned when input chunking has been requested.

type Dim

type Dim string

Dim is projection dimenstion

const (
	// Dim2D is 2D projection.
	Dim2D Dim = "2D"
	// Dim3D is 3D projection.
	Dim3D Dim = "3D"
)

type Embedding

type Embedding struct {
	// UID is the unique ID for this embedding.
	UID string `json:"uid,omitempty"`
	// Values stores embedding vector values.
	// NOTE: the key is set to value - singular
	// because the API is consumed by ECharts and
	// it's just sad ECharts expects value slice.
	// We could handle that in JS but who can be bothered?
	Values []float64 `json:"value,omitempty"`
	// Metadata for the given embedding vector.
	Metadata map[string]any `json:"metadata,omitempty"`
}

Embedding is vector embedding.

type EmbeddingsResponse

type EmbeddingsResponse struct {
	Embeddings []Embedding `json:"embeddings"`
	Page       Page        `json:"page"`
}

EmbeddingsResponse is returned when querying provider embeddings.

type EmbeddingsUpdate

type EmbeddingsUpdate struct {
	Text       string         `json:"text"`
	Label      string         `json:"label"`
	Projection Projection     `json:"projection"`
	Chunking   *Chunking      `json:"chunking,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

EmbeddingsUpdate is used to fetch embeddings. NOTE: we call this an Update because it updates the vector store.

type Error

type Error struct {
	// Machine-readable error code.
	Code string
	// Human-readable error message.
	Message string
}

Error represents an application-specific error. Application errors can be unwrapped by the caller to extract out the code & message.

Any non-application error (such as a disk error) should be reported as an EINTERNAL error and the human user should only see "Internal error" as the message. These low-level internal error details should only be logged and reported to the operator of the application (not the end user).

func Errorf

func Errorf(code string, format string, args ...interface{}) *Error

Errorf is a helper function to return an Error with a given code and formatted message.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface. Not used by the application otherwise.

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse represents a JSON structure for error output.

type Page

type Page struct {
	// Next is either a number
	// or a string ID which allows
	// resuming paging if provided.
	Next *string `json:"next,omitempty"`
	// Count is the number of all
	// results if provided.
	Count *int `json:"count,omitempty"`
}

Page is used for API paging. Some upstream providers do not provide full count, but instead the ID of the next Page.

type Projection

type Projection string

Projection algorithm.

const (
	// TSNE projection
	// https://en.wikipedia.org/wiki/T-distributed_stochastic_neighbor_embedding
	TSNE Projection = "tsne"
	// PCA projection
	// https://en.wikipedia.org/wiki/Principal_component_analysis
	PCA Projection = "pca"
)

type ProjectionsResponse

type ProjectionsResponse struct {
	Projections map[Dim][]Embedding `json:"embeddings"`
	Page        Page                `json:"page"`
}

ProjectionsResponse is returned when querying provider embeddings projections

type ProjectionsUpdate

type ProjectionsUpdate struct {
	Projection Projection     `json:"projection"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

ProjectionsUpdate is used to recompute embedding projections.

type Provider

type Provider struct {
	// UID of the provider's UUID.
	UID string `json:"id"`
	// Name is the name of the provider
	Name string `json:"name"`
	// Metadata about the provider.
	Metadata map[string]any `json:"metadata,omitempty"`
}

Provider for embeddings.

type ProviderFilter

type ProviderFilter struct {
	// Filtering fields.
	Dim *Dim `json:"dim"`
	// Restrict to subset of range.
	Offset any `json:"offset"`
	Limit  int `json:"limit"`
}

ProviderFilter is used for filtering providers.

type ProvidersResponse

type ProvidersResponse struct {
	Providers []*Provider `json:"providers"`
	Page      Page        `json:"page"`
}

ProvidersResponse is returned when querying providers.

type ProvidersService

type ProvidersService interface {
	// AddProvider creates a new provider and returns it.
	AddProvider(ctx context.Context, name string, metadata map[string]any) (*Provider, error)
	// GetProviders returns a list of providers filtered by filter.
	GetProviders(ctx context.Context, filter ProviderFilter) ([]*Provider, Page, error)
	// GetProviderByUID returns the provider with the given uuid.
	GetProviderByUID(ctx context.Context, uid string) (*Provider, error)
	// GetProviderEmbeddings returns embeddings for the provider with the given uid.
	GetProviderEmbeddings(ctx context.Context, uid string, filter ProviderFilter) ([]Embedding, Page, error)
	// GetProviderProjections returns embeddings projections for the provider with the given uid.
	GetProviderProjections(ctx context.Context, uid string, filter ProviderFilter) (map[Dim][]Embedding, Page, error)
	// UpdateProviderEmbeddings generates embeddings for the provider with the given uid.
	UpdateProviderEmbeddings(ctx context.Context, uid string, update []Embedding, projection Projection) ([]Embedding, error)
	// DropProviderEmbeddings drops all provider embeddings from the store.
	DropProviderEmbeddings(ctx context.Context, uid string) error
	// ComputeProviderProjections drops existing projections and recomputes anew.
	ComputeProviderProjections(ctx context.Context, uid string, projection Projection) error
}

ProvidersService manages embedding providers.