Documentation
¶
Overview ¶
Package narrative provides LLM-powered narrative generation for development episodes. It defines a provider-agnostic LLM interface with concrete implementations for OpenAI and deterministic mocks for testing. The generator consumes pre-assembled prompts and returns structured narrative objects.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrLLMFailed = errors.New("LLM request failed") ErrInvalidConfig = errors.New("invalid LLM configuration") )
var (
ErrGenerationFailed = errors.New("narrative generation failed")
)
var (
ErrMissingTargetEpisode = errors.New("target episode required for episode-level narrative")
)
Functions ¶
func AssemblePrompt ¶
Types ¶
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator produces narratives from episodes using an LLM. It invokes an LLM on an already-assembled prompt.
func NewGenerator ¶
NewGenerator creates a narrative generator with the given LLM implementation.
type LLM ¶
type LLM interface {
// Generate produces text from a prompt using the configured model.
// Returns the generated text or an error if generation fails.
Generate(ctx context.Context, prompt string) (string, error)
}
LLM defines the interface for interacting with language models. Implementations must be stateless and thread-safe.
type LLMConfig ¶
type LLMConfig struct {
// Model specifies the model identifier (e.g., "gpt-4", "gpt-3.5-turbo")
Model string
// Temperature controls randomness (0.0 = deterministic, 2.0 = very random)
Temperature float32
// MaxTokens limits the response length (0 = use provider default)
MaxTokens int
// APIKey is the authentication key for the provider
APIKey string
}
LLMConfig holds common configuration options for LLM providers.
func DefaultLLMConfig ¶
func DefaultLLMConfig() LLMConfig
DefaultLLMConfig returns sensible defaults for narrative generation.
type MockLLM ¶
type MockLLM struct {
// Response is the fixed text returned by Generate.
// If empty, a default response is generated from the prompt.
Response string
// Error, if set, is returned by Generate instead of a response.
Error error
// LastPrompt stores the most recent prompt passed to Generate.
LastPrompt string
}
MockLLM is a deterministic LLM implementation for testing. It returns predictable responses based on prompt content.
func NewMockLLM ¶
NewMockLLM creates a mock LLM with the given fixed response.
func NewMockLLMWithError ¶
NewMockLLMWithError creates a mock LLM that always returns an error.
type Narrative ¶
type Narrative struct {
// EpisodeID identifies the episode this narrative describes
EpisodeID string `json:"episode_id"`
// Text is the generated narrative content
Text string `json:"text"`
// GeneratedAt is when this narrative was created
GeneratedAt time.Time `json:"generated_at"`
// Model is the LLM model used to generate this narrative
Model string `json:"model"`
}
Narrative represents a generated human-readable explanation of an episode.
type OpenAILLM ¶
type OpenAILLM struct {
// contains filtered or unexported fields
}
OpenAILLM implements the LLM interface using OpenAI's API.
func NewOpenAILLM ¶
NewOpenAILLM creates an OpenAI-backed LLM implementation. Returns an error if the API key is missing or invalid.
Source Files