onboarding

Documentation

Index

• Constants
• Variables
• func NewLoop(session *Session, maxIter uint) agent.Agent
• type AnswerExtractor
• type Answers
• type Draft
  • func ExtractDraft(answers Answers) (Draft, error)
• type Input
• type Intent
• type InterviewStepAgent
  • func NewInterviewStepAgent(session *Session) *InterviewStepAgent
  • func (*InterviewStepAgent) Description() string
  • func (a *InterviewStepAgent) FindAgent(name string) agent.Agent
  • func (a *InterviewStepAgent) Name() string
  • func (a *InterviewStepAgent) Run(ic agent.InvocationContext) iter.Seq2[*agent.Event, error]
  • func (*InterviewStepAgent) SubAgents() []agent.Agent
• type LLMAnswerExtractor
  • func NewLLMAnswerExtractor(client llm.Client, model string) *LLMAnswerExtractor
  • func (e *LLMAnswerExtractor) Extract(ctx context.Context, step Step, raw string) (Answers, error)
• type Session
  • func NewSession(identityID, identityName string) *Session
  • func (s *Session) Apply(in Input) (Transition, error)
  • func (s *Session) Queue(inputs ...Input)
• type Status
• type Step
• type Transition

Constants

const (
	// InterviewStepAgentName is the agent name emitted on onboarding events.
	InterviewStepAgentName = "InterviewStepAgent"
	// LoopName is the workflow loop name for profile onboarding.
	LoopName = "ProfileOnboardingLoop"
)

Variables

var (
	// ErrDraftRequired is returned when confirm or edit is requested before a draft exists.
	ErrDraftRequired = errors.New("onboarding draft required")
	// ErrTerminal is returned when input is applied to a terminal session.
	ErrTerminal = errors.New("onboarding session is terminal")
	// ErrInvalidIntent is returned for an unknown onboarding intent.
	ErrInvalidIntent = errors.New("invalid onboarding intent")
)

Functions

func NewLoop

func NewLoop(session *Session, maxIter uint) agent.Agent

NewLoop creates the profile onboarding workflow loop.

Types

type AnswerExtractor

type AnswerExtractor interface {
	Extract(ctx context.Context, step Step, raw string) (Answers, error)
}

AnswerExtractor turns a free-text interview answer into structured Answers.

type Answers

type Answers struct {
	Name      string
	Role      string
	Company   string
	Location  string
	Expertise []string
	Stack     []string
	Projects  []string
	Goals     []string
	Interests []string
	People    []string // e.g. "Andrea — business partner"
	Vetoes    []string // hard "never do" rules; not interview-collected yet (set via direct profile edit / future passive extraction)

	// style/preferences
	Lang                string
	Timezone            string
	TonePreference      string
	ResponseLength      string
	VoiceMode           *bool
	CanProactiveMessage *bool
	CustomInstructions  string
}

Answers contains structured profile facts collected during onboarding.

type Draft

type Draft struct {
	AgentMD         string
	Preferences     profile.Preferences
	PreferencesJSON string
}

Draft is the rendered Agent.md plus structured preferences from onboarding answers.

func ExtractDraft

func ExtractDraft(answers Answers) (Draft, error)

ExtractDraft renders a bounded Agent.md draft and preferences from answers.

type Input

type Input struct {
	Intent  Intent
	Text    string
	Answers Answers
}

Input is one queued user action for the session state machine.

type Intent

type Intent string

Intent describes the next user action applied to an onboarding session.

const (
	// IntentAnswer records an answer for the current onboarding step.
	IntentAnswer Intent = "answer"
	// IntentConfirm accepts and completes the current Agent.md draft.
	IntentConfirm Intent = "confirm"
	// IntentEdit updates the current Agent.md draft with revised answers.
	IntentEdit Intent = "edit"
	// IntentSkip ends onboarding without saving a profile.
	IntentSkip Intent = "skip"
	// IntentCancel cancels onboarding and resumes normal chat.
	IntentCancel Intent = "cancel"
	// IntentRestart resets onboarding to the first step.
	IntentRestart Intent = "restart"
)

type InterviewStepAgent

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

InterviewStepAgent adapts onboarding session transitions to agent events.

func NewInterviewStepAgent

func NewInterviewStepAgent(session *Session) *InterviewStepAgent

NewInterviewStepAgent creates an interview step agent backed by a session.

func (*InterviewStepAgent) Description

func (*InterviewStepAgent) Description() string

Description returns a short description of the onboarding step agent.

func (*InterviewStepAgent) FindAgent

func (a *InterviewStepAgent) FindAgent(name string) agent.Agent

FindAgent returns this agent when the requested name matches.

func (*InterviewStepAgent) Name

func (a *InterviewStepAgent) Name() string

Name returns the onboarding step agent name.

func (*InterviewStepAgent) Run

func (a *InterviewStepAgent) Run(ic agent.InvocationContext) iter.Seq2[*agent.Event, error]

Run emits the next onboarding transition event, when one is available.

func (*InterviewStepAgent) SubAgents

func (*InterviewStepAgent) SubAgents() []agent.Agent

SubAgents returns no child agents because onboarding is a leaf step.

type LLMAnswerExtractor

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

LLMAnswerExtractor extracts fields via a one-shot tool-free LLM completion, mirroring the reasoningOracle pattern. It never returns a hard error: on transport or parse failure it falls back to storing the raw answer in the step's primary field, so onboarding never blocks.

func NewLLMAnswerExtractor

func NewLLMAnswerExtractor(client llm.Client, model string) *LLMAnswerExtractor

NewLLMAnswerExtractor creates an LLMAnswerExtractor backed by the given client and model.

func (*LLMAnswerExtractor) Extract

func (e *LLMAnswerExtractor) Extract(ctx context.Context, step Step, raw string) (Answers, error)

Extract runs a one-shot LLM call and returns structured Answers for the given step.

type Session

type Session struct {
	IdentityID   string
	IdentityName string
	Step         Step
	Status       Status

	Answers      Answers
	DraftAgentMD string
	Preferences  profile.Preferences
	// contains filtered or unexported fields
}

Session tracks one identity's profile onboarding state.

func NewSession

func NewSession(identityID, identityName string) *Session

NewSession starts profile onboarding for an identity.

func (*Session) Apply

func (s *Session) Apply(in Input) (Transition, error)

Apply applies one input to the session and returns the next transition.

func (*Session) Queue

func (s *Session) Queue(inputs ...Input)

Queue appends inputs that the loop agent will consume in order.

type Status

type Status string

Status is the lifecycle state for a profile onboarding session.

const (
	// StatusActive means the interview is still collecting answers.
	StatusActive Status = "active"
	// StatusDraft means an Agent.md draft is ready for review.
	StatusDraft Status = "draft"
	// StatusCompleted means onboarding produced a confirmed profile.
	StatusCompleted Status = "completed"
	// StatusSkipped means onboarding ended without saving a profile.
	StatusSkipped Status = "skipped"
	// StatusCanceled means onboarding was canceled before completion.
	StatusCanceled Status = "canceled"
)

type Step

type Step string

Step is the current profile onboarding interview step.

const (
	// StepIdentity asks name, role, company, and location.
	StepIdentity Step = "identity"
	// StepWork collects expertise and tech stack.
	StepWork Step = "work"
	// StepProjects collects active projects and goals.
	StepProjects Step = "projects"
	// StepSocial collects interests and key collaborators.
	StepSocial Step = "social"
	// StepStyle collects tone, language, response-length, and voice preferences.
	StepStyle Step = "style"
	// StepDraft presents the Agent.md draft for confirm, edit, or skip.
	StepDraft Step = "draft"
)

type Transition

type Transition struct {
	Content    string
	StateDelta map[string]any
	Terminal   bool
}

Transition is the prompt and state delta emitted after applying input.