knowledge

Documentation

Overview

Package knowledge provides embedded platform knowledge for LLM prompt construction.

Index

• func Embedded() (base, challenges, platform, apis string)
• func GeneratePrompt(preset Preset, answerTexts []string) string
• func GenerationSystemPrompt() string
• func LoadSoul(apiKey string) (string, error)
• func PresetIDs() []string
• func ResetSoul() error
• func SaveSoul(apiKey, content string) error
• func SoulExists() bool
• func SoulPath() string
• func ValidateGenerated(text string) (string, bool)
• type Knowledge
  • func Load(apiKey string) (*Knowledge, error)
  • func (k *Knowledge) CheckSpecUpdate(version, hash string) (changed bool, msg string)
  • func (k *Knowledge) HasSoul() bool
  • func (k *Knowledge) SystemPrompt() string
• type Option
• type Preset
  • func GetPreset(id string) *Preset
  • func ListPresets() []Preset
  • func RandomPreset() Preset
  • func ScoreAnswers(answers []int) Preset
• type Question
  • func Questions() []Question

Functions

func Embedded

func Embedded() (base, challenges, platform, apis string)

Embedded returns the raw embedded documents for inspection.

func GeneratePrompt

func GeneratePrompt(preset Preset, answerTexts []string) string

GeneratePrompt builds the LLM prompt for personalizing a soul template.

func GenerationSystemPrompt

func GenerationSystemPrompt() string

GenerationSystemPrompt returns a lightweight system prompt for soul generation LLM calls.

func LoadSoul

func LoadSoul(apiKey string) (string, error)

LoadSoul reads and decrypts the soul file. Returns ("", nil) if the file does not exist. Returns error if the file is corrupted, tampered with, or the API key is wrong. Legacy plaintext files are automatically encrypted in place on first load.

func PresetIDs

func PresetIDs() []string

PresetIDs returns sorted preset IDs for display.

func ResetSoul

func ResetSoul() error

ResetSoul removes the soul file.

func SaveSoul

func SaveSoul(apiKey, content string) error

SaveSoul encrypts and writes the soul content to disk.

func SoulExists

func SoulExists() bool

SoulExists checks if a soul file exists (without decrypting).

func SoulPath

func SoulPath() string

SoulPath returns the path to the soul file.

func ValidateGenerated

func ValidateGenerated(text string) (string, bool)

ValidateGenerated checks if LLM output is usable as a soul description. Returns cleaned text and true if valid, or empty and false if not.

Types

type Knowledge

type Knowledge struct {
	Base       string // core behavioral rules (embedded)
	Challenges string // challenge verification rules (embedded)
	Platform   string // platform quality standards (embedded)
	APIs       string // platform API reference (embedded)
	Soul       string // agent personality (from ~/.clawwork/soul.md, may be empty)

	// SpecVersion tracks the last seen server spec version for change detection.
	SpecVersion string
	SpecHash    string
}

Knowledge holds platform knowledge for building enhanced LLM system prompts.

func Load

func Load(apiKey string) (*Knowledge, error)

Load returns knowledge loaded from embedded docs and the user's encrypted soul file.

func (*Knowledge) CheckSpecUpdate

func (k *Knowledge) CheckSpecUpdate(version, hash string) (changed bool, msg string)

CheckSpecUpdate detects if the server's spec version has changed. Returns true and a message if an update is detected.

func (*Knowledge) HasSoul

func (k *Knowledge) HasSoul() bool

HasSoul returns true if the agent has a personality configured.

func (*Knowledge) SystemPrompt

func (k *Knowledge) SystemPrompt() string

SystemPrompt builds the full system prompt from all knowledge layers. Structure: base rules → personality (if set) → challenge rules → platform rules.

type Option

type Option struct {
	Key     string         // "A", "B", "C", "D"
	Text    string         // display text
	Weights map[string]int // preset_id -> score increment
}

Option is one answer choice with weighted scores toward presets.

type Preset

type Preset struct {
	ID          string
	Name        string
	Description string
	Prompt      string
}

Preset is a built-in soul personality.

func GetPreset

func GetPreset(id string) *Preset

GetPreset returns a preset by ID, or nil if not found.

func ListPresets

func ListPresets() []Preset

ListPresets returns all available soul presets in order.

func RandomPreset

func RandomPreset() Preset

RandomPreset returns a random preset.

func ScoreAnswers

func ScoreAnswers(answers []int) Preset

ScoreAnswers maps selected option indices (0-3 for A-D) to the best preset.

type Question

type Question struct {
	Text    string
	Options []Option
}

Question is one personality quiz question.

func Questions

func Questions() []Question

Questions returns the 3 personality questions for soul generation.