v0.0.6
zoobzio February 20, 2026 Edit this page

API Reference

Complete API reference for cogito. For the most up-to-date documentation, see pkg.go.dev/github.com/zoobz-io/cogito.

Core Types

Thought

type Thought struct {
    ID        string    // Auto-generated UUID
    Intent    string    // Purpose of this thought
    TraceID   string    // Unique trace identifier
    ParentID  *string   // Parent thought (for branching)
    Session   *Session  // LLM conversation state
    CreatedAt time.Time
    UpdatedAt time.Time
}

Constructors

func New(ctx context.Context, intent string) *Thought
func NewWithTrace(ctx context.Context, intent, traceID string) *Thought

Methods

func (t *Thought) AddNote(ctx context.Context, note Note) error
func (t *Thought) SetContent(ctx context.Context, key, content, source string) error
func (t *Thought) SetNote(ctx context.Context, key, content, source string, metadata map[string]string) error
func (t *Thought) GetNote(key string) (Note, bool)
func (t *Thought) GetContent(key string) (string, error)
func (t *Thought) GetMetadata(key, field string) (string, error)
func (t *Thought) GetLatestNote() (Note, bool)
func (t *Thought) AllNotes() []Note
func (t *Thought) GetBool(key string) (bool, error)
func (t *Thought) GetFloat(key string) (float64, error)
func (t *Thought) GetInt(key string) (int, error)
func (t *Thought) Clone() *Thought
func (t *Thought) PublishedCount() int
func (t *Thought) GetUnpublishedNotes() []Note
func (t *Thought) MarkNotesPublished(ctx context.Context)

Note

type Note struct {
    ID        string
    ThoughtID string
    Key       string
    Content   string
    Metadata  map[string]string
    Source    string
    Created   time.Time
}

Primitives

Decision & Analysis

Decide

Binary yes/no decisions with confidence scores.

func NewDecide(key, question string) *Decide
func (d *Decide) WithProvider(p Provider) *Decide
func (d *Decide) WithIntrospection() *Decide
func (d *Decide) WithSummaryKey(key string) *Decide
func (d *Decide) WithReasoningTemperature(t float32) *Decide
func (d *Decide) WithIntrospectionTemperature(t float32) *Decide
func (d *Decide) Scan(t *Thought) (*DecideResponse, error)

Analyze

Extract structured data into typed results.

func NewAnalyze[T any](key, prompt string) *Analyze[T]
func (a *Analyze[T]) WithProvider(p Provider) *Analyze[T]
func (a *Analyze[T]) WithIntrospection() *Analyze[T]
func (a *Analyze[T]) Scan(t *Thought) (*T, error)

Categorize

Classify into one of N categories.

func NewCategorize(key, question string, categories []string) *Categorize
func (c *Categorize) WithProvider(p Provider) *Categorize
func (c *Categorize) WithIntrospection() *Categorize
func (c *Categorize) Scan(t *Thought) (*CategorizeResponse, error)

Assess

Sentiment analysis with emotional scoring.

func NewAssess(key, question string) *Assess
func (a *Assess) WithProvider(p Provider) *Assess
func (a *Assess) WithIntrospection() *Assess
func (a *Assess) Scan(t *Thought) (*AssessResponse, error)

Prioritize

Rank items by specified criteria.

func NewPrioritize(key, criteria string, items []string) *Prioritize
func (p *Prioritize) WithProvider(provider Provider) *Prioritize
func (p *Prioritize) WithIntrospection() *Prioritize
func (p *Prioritize) Scan(t *Thought) (*PrioritizeResponse, error)

Control Flow

Sift

Semantic gate - LLM decides whether to execute wrapped processor.

func NewSift(name, criteria string, processor pipz.Chainable[*Thought]) *Sift
func (s *Sift) WithProvider(p Provider) *Sift

Discern

Semantic router - LLM classifies and routes to different processors.

func NewDiscern(name, question string) *Discern
func (d *Discern) AddRoute(category string, processor pipz.Chainable[*Thought]) *Discern
func (d *Discern) WithProvider(p Provider) *Discern

Reflection

Reflect

Consolidate current Thought's Notes into a summary.

func NewReflect(key string) *Reflect
func (r *Reflect) WithPrompt(prompt string) *Reflect
func (r *Reflect) WithProvider(p Provider) *Reflect
func (r *Reflect) WithUnpublishedOnly() *Reflect

Session Management

Reset

Clear session state.

func NewReset(key string) *Reset
func (r *Reset) WithSystemMessage(msg string) *Reset
func (r *Reset) WithPreserveNote(noteKey string) *Reset

Compress

LLM-summarise session history to reduce tokens.

func NewCompress(targetMessages int) *Compress
func (c *Compress) WithProvider(p Provider) *Compress

Truncate

Sliding window session trimming (no LLM).

func NewTruncate(keepMessages int) *Truncate

Synthesis

Amplify

Iterative refinement until criteria met.

func NewAmplify(key, criteria string, processor pipz.Chainable[*Thought]) *Amplify
func (a *Amplify) WithMaxIterations(n int) *Amplify
func (a *Amplify) WithProvider(p Provider) *Amplify

Converge

Parallel execution with semantic synthesis.

func NewConverge(key, synthesisPrompt string, processors ...pipz.Chainable[*Thought]) *Converge
func (c *Converge) WithProvider(p Provider) *Converge

Pipeline Helpers

func Sequence(identity pipz.Identity, processors ...pipz.Chainable[*Thought]) *pipz.Sequence[*Thought]
func Filter(identity pipz.Identity, predicate func(context.Context, *Thought) bool, processor pipz.Chainable[*Thought]) *pipz.Filter[*Thought]
func Switch(identity pipz.Identity, condition func(context.Context, *Thought) string) *pipz.Switch[*Thought]
func Gate(identity pipz.Identity, predicate func(context.Context, *Thought) bool) pipz.Processor[*Thought]
func Fallback(identity pipz.Identity, processors ...pipz.Chainable[*Thought]) *pipz.Fallback[*Thought]
func Retry(identity pipz.Identity, processor pipz.Chainable[*Thought], maxAttempts int) *pipz.Retry[*Thought]
func Backoff(identity pipz.Identity, processor pipz.Chainable[*Thought], maxAttempts int, baseDelay time.Duration) *pipz.Backoff[*Thought]
func Timeout(identity pipz.Identity, processor pipz.Chainable[*Thought], duration time.Duration) *pipz.Timeout[*Thought]
func Concurrent(identity pipz.Identity, reducer func(*Thought, map[pipz.Identity]*Thought, map[pipz.Identity]error) *Thought, processors ...pipz.Chainable[*Thought]) *pipz.Concurrent[*Thought]
func Race(identity pipz.Identity, processors ...pipz.Chainable[*Thought]) *pipz.Race[*Thought]

Provider Management

func SetProvider(p Provider)
func GetProvider() Provider
func WithProvider(ctx context.Context, p Provider) context.Context
func ProviderFromContext(ctx context.Context) (Provider, bool)
func ResolveProvider(ctx context.Context, stepProvider Provider) (Provider, error)

Utilities

func RenderNotesToContext(notes []Note) string

Configuration

var DefaultIntrospection = false
var DefaultReasoningTemperature = 0.0
var DefaultIntrospectionTemperature = 0.7
© 2026 Alexander Thorwaldson