client

README

client

The typed REST client for a running recall-server. It is the transport behind the recall CLI's server mode and the natural way for applications to talk to the service.

c, err := client.New(client.Config{
    BaseURL: "http://localhost:8080",
    APIKey:  os.Getenv("RECALL_API_KEY"), // optional; sent as Bearer + X-API-Key
    Timeout: 30 * time.Second,
})

Methods

Method	Endpoint
Upload(ctx, UploadRequest)	POST /upload — document upload (ID auto-generated when empty)
Search(ctx, query, SearchOptions)	vector search
HybridSearch(ctx, query, SearchOptions)	hybrid (BM25+vector) search
RAG(ctx, query, hybrid)	POST /rag — rendered RAG prompt + sources + citations
GraphEntity(ctx, id)	entity lookup
Reason(ctx, ReasonRequest)	path exploration / NL reasoning
Health(ctx) / Diagnostics(ctx)	GET /healthz / GET /diagnostics

All responses are typed structs mirroring the OpenAPI contract; the client is safe for concurrent use.

Documentation

Overview

Package client is an HTTP client for the Recall REST API (see package api). It wraps every endpoint with typed request/response structs and a structured error type for non-2xx responses. It is the transport behind the recall CLI's server mode.

Index

• type Citation
• type Client
  • func New(cfg Config) (*Client, error)
  • func (c *Client) BaseURL() string
  • func (c *Client) Diagnostics(ctx context.Context) (*StoreDiagnostics, error)
  • func (c *Client) GraphEntity(ctx context.Context, id string) (*EntityDetail, error)
  • func (c *Client) Health(ctx context.Context) (*StoreHealth, error)
  • func (c *Client) HybridSearch(ctx context.Context, query string, opts SearchOptions) (*SearchResults, error)
  • func (c *Client) RAG(ctx context.Context, query string, hybrid bool) (*RAGResponse, error)
  • func (c *Client) Reason(ctx context.Context, req ReasonRequest) (*ReasonResponse, error)
  • func (c *Client) Search(ctx context.Context, query string, opts SearchOptions) (*SearchResults, error)
  • func (c *Client) Upload(ctx context.Context, req UploadRequest) (*UploadResult, error)
• type ClusterDiagnostics
  • func ProbeClusterNode(ctx context.Context, baseURL string, timeout time.Duration) (*ClusterDiagnostics, error)
• type ClusterNodeHealth
• type ClusterShardStats
• type Config
• type Entity
• type EntityDetail
• type Error
  • func (e *Error) Error() string
• type InferredRelation
• type Integrity
• type Path
• type RAGResponse
• type ReasonRequest
• type ReasonResponse
• type Relation
• type Result
• type SearchOptions
• type SearchResults
• type StoreDiagnostics
• type StoreHealth
• type UploadRequest
• type UploadResult

Types

type Citation

type Citation struct {
	Number   int     `json:"number"`
	ChunkID  string  `json:"chunk_id"`
	Document string  `json:"document,omitempty"`
	Score    float64 `json:"score"`
	Snippet  string  `json:"snippet,omitempty"`
}

Citation is a ranked reference to a source chunk in RAG responses.

type Client

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

Client talks to a recall-server. It is safe for concurrent use.

func New

func New(cfg Config) (*Client, error)

New creates a Client, validating and normalizing the configuration.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the normalized base URL the client sends requests to.

func (*Client) Diagnostics

func (c *Client) Diagnostics(ctx context.Context) (*StoreDiagnostics, error)

Diagnostics fetches the full diagnostics snapshot via GET /diagnostics.

func (*Client) GraphEntity

func (c *Client) GraphEntity(ctx context.Context, id string) (*EntityDetail, error)

GraphEntity fetches an entity (by ID, or unique label) with its neighbors and relations via GET /graph/{entity}.

func (*Client) Health

func (c *Client) Health(ctx context.Context) (*StoreHealth, error)

Health fetches the store health report via GET /healthz.

func (*Client) HybridSearch

func (c *Client) HybridSearch(ctx context.Context, query string, opts SearchOptions) (*SearchResults, error)

HybridSearch performs a vector + BM25 search via POST /hybrid-search.

func (*Client) RAG

func (c *Client) RAG(ctx context.Context, query string, hybrid bool) (*RAGResponse, error)

RAG runs a RAG query via POST /rag. When hybrid is true the server uses hybrid retrieval.

func (*Client) Reason

func (c *Client) Reason(ctx context.Context, req ReasonRequest) (*ReasonResponse, error)

Reason runs multi-hop reasoning via POST /graph/reason.

func (*Client) Search

func (c *Client) Search(ctx context.Context, query string, opts SearchOptions) (*SearchResults, error)

Search performs a vector-similarity search via GET /search.

func (*Client) Upload

func (c *Client) Upload(ctx context.Context, req UploadRequest) (*UploadResult, error)

Upload sends a document to POST /upload.

type ClusterDiagnostics

type ClusterDiagnostics struct {
	Health      ClusterNodeHealth `json:"health"`
	Shards      ClusterShardStats `json:"shards"`
	GeneratedAt time.Time         `json:"generated_at"`
}

ClusterDiagnostics mirrors the GET /diagnostics response of a distributed cluster node (distributed.HealthHandler).

func ProbeClusterNode

func ProbeClusterNode(ctx context.Context, baseURL string, timeout time.Duration) (*ClusterDiagnostics, error)

ProbeClusterNode fetches the /diagnostics snapshot served by a distributed cluster node at baseURL. A non-2xx or unparseable response returns an error; callers report such nodes as unreachable.

type ClusterNodeHealth

type ClusterNodeHealth struct {
	Total    int    `json:"Total"`
	Online   int    `json:"Online"`
	Degraded int    `json:"Degraded"`
	Offline  int    `json:"Offline"`
	Overall  string `json:"Overall"`
}

ClusterNodeHealth mirrors the distributed package's ClusterHealth (served by distributed.HealthHandler; the fields are exported without JSON tags, so the keys are the Go field names).

type ClusterShardStats

type ClusterShardStats struct {
	Total    int            `json:"total"`
	Active   int            `json:"active"`
	Inactive int            `json:"inactive"`
	Degraded int            `json:"degraded"`
	Chunks   int            `json:"chunks"`
	PerNode  map[string]int `json:"per_node,omitempty"`
}

ClusterShardStats mirrors the distributed package's ShardStats.

type Config

type Config struct {
	// BaseURL is the server base URL (e.g. "http://localhost:8080").
	// Required.
	BaseURL string

	// APIKey, when set, authenticates every request. It is sent as both
	// "Authorization: Bearer <key>" and "X-API-Key: <key>" so servers with
	// either convention accept it.
	APIKey string

	// Timeout bounds each HTTP request. Defaults to 30s.
	Timeout time.Duration
}

Config configures a Client.

type Entity

type Entity struct {
	ID           string            `json:"id"`
	Label        string            `json:"label"`
	Type         string            `json:"type"`
	Properties   map[string]string `json:"properties,omitempty"`
	SourceChunks []string          `json:"source_chunks,omitempty"`
}

Entity is a graph entity in API responses.

type EntityDetail

type EntityDetail struct {
	Entity    Entity     `json:"entity"`
	Neighbors []Entity   `json:"neighbors"`
	Relations []Relation `json:"relations"`
}

EntityDetail is the response of GET /graph/{entity}.

type Error

type Error struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// Code is the API error code (e.g. "not_found"). Empty when the
	// response body was not a valid error envelope.
	Code string
	// Message is the human-readable error message.
	Message string
}

Error is a non-2xx response from the server carrying the standard JSON error envelope ({"code","message"}).

func (*Error) Error

func (e *Error) Error() string

type InferredRelation

type InferredRelation struct {
	From       string  `json:"from"`
	To         string  `json:"to"`
	Type       string  `json:"type"`
	Confidence float64 `json:"confidence"`
	Rule       string  `json:"rule"`
	Hops       int     `json:"hops"`
}

InferredRelation is an inferred relation in POST /graph/reason responses.

type Integrity

type Integrity struct {
	OK          bool     `json:"OK"`
	Issues      []string `json:"Issues"`
	ForeignKeys []string `json:"ForeignKeys"`
}

Integrity mirrors store.IntegrityReport (the store package serves these fields without JSON tags, so the keys are the Go field names).

type Path

type Path struct {
	Entities  []string `json:"entities"`
	Relations []string `json:"relations"`
}

Path is a discovered entity path in POST /graph/reason responses.

type RAGResponse

type RAGResponse struct {
	Query     string     `json:"query"`
	Answer    string     `json:"answer"`
	Context   string     `json:"context"`
	Tokens    int        `json:"tokens"`
	Sources   []Result   `json:"sources"`
	Citations []Citation `json:"citations,omitempty"`
}

RAGResponse is the response of POST /rag.

type ReasonRequest

type ReasonRequest struct {
	Query   string `json:"query,omitempty"`
	From    string `json:"from,omitempty"`
	To      string `json:"to,omitempty"`
	MaxHops int    `json:"max_hops,omitempty"`
}

ReasonRequest is the body of POST /graph/reason. Either Query (natural language reasoning) or both From and To (path exploration) is required.

type ReasonResponse

type ReasonResponse struct {
	Inferences []InferredRelation `json:"inferences"`
	Paths      []Path             `json:"paths"`
}

ReasonResponse is the response of POST /graph/reason.

type Relation

type Relation struct {
	From   string  `json:"from"`
	To     string  `json:"to"`
	Type   string  `json:"type"`
	Weight float64 `json:"weight"`
}

Relation is a graph relation in API responses.

type Result

type Result struct {
	ID         string         `json:"id"`
	Document   string         `json:"document"`
	ChunkIndex int            `json:"chunk_index"`
	Content    string         `json:"content"`
	Score      float64        `json:"score"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

Result is a single search result.

type SearchOptions

type SearchOptions struct {
	// TopK is the maximum number of results. Defaults to 10 when <= 0.
	TopK int
	// MinScore is the minimum relevance score.
	MinScore float64
	// BM25Weight is the keyword weight for hybrid search (0-1). Zero means
	// the server default (0.5).
	BM25Weight float64
	// EfSearch controls HNSW search width (0 = server default).
	EfSearch int
}

SearchOptions configures a search request.

type SearchResults

type SearchResults struct {
	Query   string   `json:"query"`
	Count   int      `json:"count"`
	Results []Result `json:"results"`
}

SearchResults is the response of GET /search and POST /hybrid-search.

type StoreDiagnostics

type StoreDiagnostics struct {
	Health      StoreHealth `json:"health"`
	GeneratedAt time.Time   `json:"generated_at"`
}

StoreDiagnostics mirrors the GET /diagnostics response of a recall-server.

type StoreHealth

type StoreHealth struct {
	OK         bool       `json:"ok"`
	Status     string     `json:"status"`
	Backend    string     `json:"backend"`
	Connected  bool       `json:"connected"`
	Count      int        `json:"count"`
	Namespaces []string   `json:"namespaces,omitempty"`
	Integrity  *Integrity `json:"integrity,omitempty"`
	Issues     []string   `json:"issues,omitempty"`
	CheckedAt  time.Time  `json:"checked_at"`
}

StoreHealth mirrors the store HealthReport served at /healthz and embedded in /diagnostics.

type UploadRequest

type UploadRequest struct {
	// ID is the document ID. The server generates one when empty.
	ID string `json:"id,omitempty"`
	// Title is the document title.
	Title string `json:"title,omitempty"`
	// Author is the document author.
	Author string `json:"author,omitempty"`
	// Source is the origin (file path, URL, ...).
	Source string `json:"source,omitempty"`
	// Namespace optionally overrides the store default.
	Namespace string `json:"namespace,omitempty"`
	// Tags are arbitrary labels.
	Tags []string `json:"tags,omitempty"`
	// Metadata carries arbitrary structured attributes.
	Metadata map[string]any `json:"metadata,omitempty"`
	// Content is the document text (required).
	Content string `json:"content"`
}

UploadRequest is the body of POST /upload.

type UploadResult

type UploadResult struct {
	ID        string `json:"id"`
	Title     string `json:"title,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Chunks    int    `json:"chunks"`
	CreatedAt string `json:"created_at,omitempty"`
	UpdatedAt string `json:"updated_at,omitempty"`
}

UploadResult is the response of POST /upload.