llmlifecycle

package
v0.10.257 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package llmlifecycle owns durable structured LLM task execution.

Index

Constants

View Source 
const SchemaVersion = 1

SchemaVersion identifies the on-disk LLM task artifact schema.

Variables

This section is empty.

Functions

func Fingerprint 

func Fingerprint(adapter, taskID, phase, model, effort, prompt string, deps []string) string

Fingerprint returns the stable reuse fingerprint for task inputs.

func ResetIfInputFingerprintChanged added in v0.10.228 

func ResetIfInputFingerprintChanged(paths Paths, taskID, fingerprint string) error

ResetIfInputFingerprintChanged removes stale task artifacts when inputs change.

func ResumeSessionID 

func ResumeSessionID(meta Metadata) string

ResumeSessionID returns the best provider session ID for retrying a task.

func SanitizeError 

func SanitizeError(err error) string

SanitizeError prepares provider errors for durable metadata and markdown.

func TaskErrorText 

func TaskErrorText(meta Metadata) string

TaskErrorText returns the persisted error text for a failed task.

func ValidateMetadata 

func ValidateMetadata(meta Metadata, req Request, adapter string) error

ValidateMetadata checks whether task metadata is reusable for the request.

func ValidatePayloadPath 

func ValidatePayloadPath(paths Paths, taskID, field, recordedPath string) (string, error)

ValidatePayloadPath ensures a recorded payload path stays inside the task directory.

func WriteFailure 

func WriteFailure(paths Paths, meta *Metadata, attempts []llm.StructuredValidationAttempt) error

WriteFailure writes invalid attempts and metadata for a failed task.

func WriteMetadata 

func WriteMetadata(paths Paths, meta Metadata) error

WriteMetadata writes task metadata atomically.

func WriteSuccess 

func WriteSuccess(paths Paths, meta *Metadata, output []byte) error

WriteSuccess writes accepted output and metadata for a succeeded task.

Types

type AttemptMetadata 

type AttemptMetadata struct {
	Attempt           string `json:"attempt"`
	ProviderSessionID string `json:"provider_session_id,omitempty"`
	RawOutputPath     string `json:"raw_output_path,omitempty"`
	DecodeError       string `json:"decode_error,omitempty"`
}

AttemptMetadata records one invalid structured-output attempt.

type Metadata 

type Metadata struct {
	SchemaVersion       int               `json:"schema_version"`
	TaskID              string            `json:"task_id"`
	Phase               string            `json:"phase"`
	DependencyTaskIDs   []string          `json:"dependency_task_ids,omitempty"`
	InputFingerprint    string            `json:"input_fingerprint"`
	AgentID             string            `json:"agent_id,omitempty"`
	Status              Status            `json:"status"`
	SessionRowID        string            `json:"session_row_id,omitempty"`
	ProviderSessionID   string            `json:"provider_session_id,omitempty"`
	Adapter             string            `json:"adapter"`
	Model               string            `json:"model"`
	Effort              string            `json:"effort,omitempty"`
	LogPath             string            `json:"log_path,omitempty"`
	ValidatedOutputPath string            `json:"validated_output_path,omitempty"`
	Error               string            `json:"error,omitempty"`
	TokensIn            *int              `json:"tokens_in,omitempty"`
	TokensOut           *int              `json:"tokens_out,omitempty"`
	CacheRead           *int              `json:"cache_read,omitempty"`
	CacheCreate         *int              `json:"cache_create,omitempty"`
	CostUSD             *float64          `json:"cost_usd,omitempty"`
	Speed               string            `json:"speed,omitempty"`
	Attempts            []AttemptMetadata `json:"attempts,omitempty"`
}

Metadata is the durable descriptor for one structured LLM task.

func BaseMetadata 

func BaseMetadata(req Request, draft SessionDraft) Metadata

BaseMetadata builds metadata shared by success and failure paths.

func ReadMetadata 

func ReadMetadata(paths Paths, taskID string) (Metadata, bool, error)

ReadMetadata reads task metadata when it exists.

type Paths 

type Paths struct {
	LLMTasksDir string
}

Paths identifies the artifact root for durable LLM tasks.

func (Paths) Metadata 

func (p Paths) Metadata(taskID string) (string, error)

Metadata returns the metadata path for a task.

func (Paths) RawAttempt 

func (p Paths) RawAttempt(taskID, label string) (string, error)

RawAttempt returns the raw structured-output attempt payload path.

func (Paths) TaskDir 

func (p Paths) TaskDir(taskID string) (string, error)

TaskDir returns the encoded artifact directory for a task.

func (Paths) ValidatedOutput 

func (p Paths) ValidatedOutput(taskID string) (string, error)

ValidatedOutput returns the accepted structured-output payload path.

type Progress 

type Progress interface {
	StartLLMTask(ProgressEvent) ProgressSpan
	LoadLLMTask(ProgressEvent, ProgressResult)
}

Progress observes LLM task execution and cache-load events.

type ProgressEvent 

type ProgressEvent struct {
	TaskID          string
	Phase           string
	AgentID         string
	Model           string
	Effort          string
	LogPath         string
	ResumeSessionID string
	Source          string
}

ProgressEvent describes the task being executed or loaded.

func NewProgressEvent 

func NewProgressEvent(req Request, resumeSessionID string) ProgressEvent

NewProgressEvent builds a progress event from a task request.

type ProgressResult 

type ProgressResult struct {
	ProviderSessionID  string
	Status             string
	ValidationAttempts int
	Cached             bool
	Usage              llm.Usage
}

ProgressResult records the observable result for a task progress event.

type ProgressSpan 

type ProgressSpan interface {
	End(error, ProgressResult)
}

ProgressSpan is an in-flight LLM task progress event.

type Request 

type Request struct {
	Store             Store
	Adapter           llm.Adapter
	RunID             string
	TaskID            string
	Phase             string
	DependencyTaskIDs []string
	AllowNoRunCache   bool
	InputFingerprint  string
	Paths             Paths
	Role              ledger.SessionRole
	AgentID           *string
	Model             string
	Effort            string
	LogPath           string
	Prompt            string
	BaseRequest       llm.Request
	ResumeSessionID   string
	FailureStatus     Status
	Progress          Progress
	Now               func() time.Time
	NewSessionRowID   func() string
}

Request contains all dependencies and inputs for one structured LLM task.

type Result 

type Result[T any] struct {
	Value   T
	Draft   SessionDraft
	Session ledger.Session
	Cached  bool
}

Result contains either a decoded task value or durable failure/session state.

func LoadStructured 

func LoadStructured[T any](ctx context.Context, req Request, decode llm.Decoder[T]) (Result[T], bool, error)

LoadStructured loads a reusable task result without calling the provider.

func RunStructured 

func RunStructured[T any](ctx context.Context, req Request, decode llm.Decoder[T]) (Result[T], error)

RunStructured executes or loads one durable structured LLM task.

type SessionDraft 

type SessionDraft struct {
	RowID                     string
	ProviderReportedSessionID string
	ProviderSessionID         string
	Role                      ledger.SessionRole
	AgentID                   *string
	Adapter                   string
	Model                     string
	Effort                    string
	StartedAt                 time.Time
	CompletedAt               time.Time
	Response                  llm.Response
}

SessionDraft captures provider telemetry before it is persisted to the ledger.

func SessionDraftFromLedger 

func SessionDraftFromLedger(session ledger.Session) SessionDraft

SessionDraftFromLedger rebuilds a lifecycle draft from a ledger session.

func SessionDraftFromMetadata 

func SessionDraftFromMetadata(meta Metadata) SessionDraft

SessionDraftFromMetadata rebuilds a lifecycle draft from task metadata.

func (SessionDraft) ToLedger 

func (d SessionDraft) ToLedger(runID string) ledger.Session

ToLedger converts a completed draft into a ledger session for a run.

type Status 

type Status string

Status is the durable outcome recorded for one structured LLM task. 

const (
	// StatusSucceeded marks a task with validated reusable output.
	StatusSucceeded Status = "succeeded"
	// StatusFailedIsolated marks a recoverable task-local failure.
	StatusFailedIsolated Status = "failed_isolated"
	// StatusFailedBlocking marks a failure that must be retried before progress.
	StatusFailedBlocking Status = "failed_blocking"
)

type Store 

type Store interface {
	InsertSession(context.Context, ledger.Session) error
	GetSession(context.Context, string) (ledger.Session, error)
}

Store is the durable session store required by run-owned LLM tasks.

type TaskError 

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

TaskError wraps an LLM task error with its durable status.

func (*TaskError) Error 

func (e *TaskError) Error() string

Error returns the underlying task error message.

func (*TaskError) Status 

func (e *TaskError) Status() Status

Status returns the durable task status associated with the error.

func (*TaskError) Unwrap 

func (e *TaskError) Unwrap() error

Unwrap returns the underlying task error.

Source Files

View all Source files

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.