llm

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 21, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package llm handles LLM-based generation tasks: prompt rendering, template embedding, runner invocation, and output parsing. Finders (read side) and handlers (write side) both consume this package — it owns the "call an LLM with a structured prompt" concern.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputePromptHash 

func ComputePromptHash(prompt string) string

ComputePromptHash returns the hex-encoded SHA-256 hash of the rendered prompt. Uses the first 16 bytes (32 hex chars) — enough for collision avoidance.

func FormatEntryForPrompt 

func FormatEntryForPrompt(e *model.Entry) string

FormatEntryForPrompt formats an entry as readable text for inclusion in a prompt.

Types

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 

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

Preflight runs the pre-flight validator against the given entry and graph. Returns the parsed result regardless of finding severity. Returns an error only for infrastructure failures (runner error, template error, parse error).

func (*PreflightResult) HasBlocking 

func (r *PreflightResult) HasBlocking() bool

HasBlocking reports whether any finding blocks entry creation. Currently only SeverityHigh blocks.

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 

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

RenderSummaryPrompt renders the summary prompt for an entry. Returns a Request with the full rendered prompt in UserPrompt; the system/user split is introduced when templates are refactored (see the plan decision).

func (Request) Combined added in v0.2.0 

func (r Request) Combined() string

Combined returns SystemPrompt followed by UserPrompt separated by a blank line when both are non-empty. Runners without native system-prompt support use this to flatten the Request into a single payload. The hash used for summary-skip detection is computed over this combined form so changes to either half invalidate the cached summary.

type RunResult 

type RunResult struct {
	Text string
	Meta *LLMMetadata
}

RunResult holds the LLM response text and optional metadata.

func Run added in v0.2.0 

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

Run executes a pre-rendered Request against the Runner and emits the standard debug log entry. Callers that orchestrate prompt rendering themselves (e.g. the parallel summarize handler) use this instead of Runner.Run directly so logging stays uniform across call sites.

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 

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

Summarize generates a summary for a single entry using the LLM runner. Returns nil if the entry's stored SummaryHash matches the computed hash (skip). Set force to regenerate regardless.

Source Files

View all Source files

Directories

Path Synopsis
Package claude implements llm.Runner by invoking the Claude CLI.
 Package claude implements llm.Runner by invoking the Claude CLI.
Package factory resolves an llm.Runner from model.LLMConfig.
 Package factory resolves an llm.Runner from model.LLMConfig.
Package gollm implements llm.Runner on top of github.com/teilomillet/gollm, providing a unified adapter for Anthropic API, OpenAI, Ollama, and other providers supported by gollm.
 Package gollm implements llm.Runner on top of github.com/teilomillet/gollm, providing a unified adapter for Anthropic API, OpenAI, Ollama, and other providers supported by gollm.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.