llm

type CallStat ¶ added in v0.7.1

type CallStat struct {
	Op       string
	Provider string
	Model    string
	// Items is the number of inputs in this call. The embedding path sets it
	// (one batch = N texts) so throughput (items or tokens per second) is
	// derivable from DurationMS; chat calls are single-prompt and leave it 0.
	Items             int
	InputTokens       int
	OutputTokens      int
	CacheReadTokens   int
	CacheCreateTokens int
	DurationMS        int64
}

CallStat is one LLM call's metrics, handed to a StatsSink for durable collection. The timestamp is added by the sink implementation. Cost is deliberately omitted: the provider APIs on the active (gollm) path report tokens and the prompt-cache breakdown but not a dollar cost, and we do not maintain a pricing table (see d-tac-zis).

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 {
	// Provider is the configured LLM provider that served the call
	// (e.g. "anthropic", "ollama", "openai", "claude-cli").
	Provider          string
	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 StatsSink ¶ added in v0.7.1

type StatsSink interface {
	RecordCall(CallStat)
}

StatsSink durably records per-call LLM metrics (e.g. to a local JSONL file). Implementations must be safe for concurrent use — batch operations like `sdd summarize --all` call them from multiple goroutines.

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)