llm

type Embedder ¶ added in v0.4.0

type Embedder interface {
	// EmbedDocuments embeds texts as index-side passages, applying the
	// configured DocumentTemplate. Used by the indexer at build /
	// lazy-fill time.
	EmbedDocuments(ctx context.Context, texts []string) ([][]float32, error)
	// EmbedQueries embeds texts as retrieval-side queries, applying the
	// configured QueryTemplate. Used by the search finder at query time.
	EmbedQueries(ctx context.Context, texts []string) ([][]float32, error)
	Dimensions() int
	Fingerprint() string
	// BatchSize is the per-call input cap the embedder targets. Drivers
	// the indexer's outer bucketing so each Embed call corresponds to
	// exactly one HTTP round-trip — progress callbacks fire per batch
	// instead of "all-at-once at the end" of a giant cross-entry call.
	// Larger inputs still embed correctly; the embedder splits
	// internally and the indexer just sees a slower individual call.
	BatchSize() int
}

Embedder turns a batch of texts into dense vectors. Implementations are thin transport adapters around an embedding service (OpenAI-compatible `/v1/embeddings`, Ollama `/api/embed`); construction is via embed.New.

The interface splits embedding into a document-side and a query-side because instruction-tuned encoders (Qwen3, E5, Nomic, BGE) want asymmetric prefixes — `passage:` on documents, `query:` on queries, or `Instruct: …\nQuery:…` only on queries. The split makes the call-site intent explicit so the wrong template can't silently slip onto the wrong side. Untemplated models (OpenAI text-embedding-3) treat both methods as equivalent.

Dimensions returns the vector length the implementation produces — must be stable across calls so the index can validate row shape.

Fingerprint is an opaque identifier for the (provider + model + truncation + document template) tuple. Used by the search index to detect rows whose embedding is stale after a configuration change. The format is implementation-defined, but implementations must guarantee that two embedders that produce distribution-comparable document vectors share a fingerprint, and two that don't, don't. The query template deliberately does NOT factor into the fingerprint — query template changes affect retrieval quality but never invalidate indexed embeddings, so they're a free-tweak knob (see EmbeddingConfig).

type Finding ¶

type Finding struct {
	Severity    Severity
	Category    string
	Observation string
}

Finding is a single observation from pre-flight validation.

type LLMMetadata ¶

type LLMMetadata struct {
	TotalCostUSD      float64
	InputTokens       int
	OutputTokens      int
	CacheReadTokens   int
	CacheCreateTokens int
	NumTurns          int
	Duration          time.Duration
	DurationAPI       time.Duration
	Models            map[string]ModelUsage
}

LLMMetadata holds agent-neutral per-call metrics from the LLM provider.

type ModelUsage ¶

type ModelUsage struct {
	InputTokens       int
	OutputTokens      int
	CacheReadTokens   int
	CacheCreateTokens int
	CostUSD           float64
}

ModelUsage holds per-model token and cost metrics.

type PreflightResult ¶

type PreflightResult struct {
	Findings []Finding
}

PreflightResult holds the parsed findings from a pre-flight validator run. An empty Findings slice means the validator reported no findings.

func Preflight(ctx context.Context, runner Runner, entry *model.Entry, graph *model.Graph, configuredLanguage string) (*PreflightResult, error)

func (r *PreflightResult) HasBlocking() bool

type Request ¶ added in v0.2.0

type Request struct {
	SystemPrompt string
	UserPrompt   string
}

Request carries the two-part prompt submitted to a Runner. SystemPrompt holds the stable portion (instructions, structural rules) — providers that support prompt caching treat this as the cacheable prefix. UserPrompt holds the per-call variable portion (entry content, refs). Runners that can't distinguish system from user concatenate them with SystemPrompt first.

func RenderSummaryPrompt(entry *model.Entry, graph *model.Graph) (Request, error)

func (r Request) Combined() string

type RunResult ¶

type RunResult struct {
	Text string
	Meta *LLMMetadata
}

RunResult holds the LLM response text and optional metadata.

func Run(ctx context.Context, runner Runner, req Request, op string) (*RunResult, error)

type Runner ¶

type Runner interface {
	Run(ctx context.Context, req Request) (*RunResult, error)
}

Runner executes a structured LLM request and returns the response with metadata. The implementation decides which model and transport to use. Injected so tests can substitute fakes.

type Severity ¶

type Severity string

Severity classifies a pre-flight finding. Mirrored in the query package; templates describe severity in purely semantic terms.

const (
	SeverityHigh   Severity = "high"
	SeverityMedium Severity = "medium"
	SeverityLow    Severity = "low"
)

type SummarizeResult ¶

type SummarizeResult struct {
	Summary     string
	SummaryHash string
}

SummarizeResult holds the generated summary and its prompt hash.

func Summarize(ctx context.Context, runner Runner, entry *model.Entry, graph *model.Graph, force bool) (*SummarizeResult, error)