package gateway import ( "context" "fmt" "strings" "github.com/samcharles93/archie-core/internal/domain/messaging" "github.com/samcharles93/archie-core/internal/tools" ) // askUserToolName is the model-facing tool that asks the human a question. const askUserToolName = "ask_user" // askQuestionsToolName is the model-facing tool that asks several questions // in one interaction. const askQuestionsToolName = "ask_questions" // maxQuestions bounds one questionnaire: a longer one is a form the human will // abandon, and the model can ask again. const maxQuestions = 8 // InteractiveTools returns the tools that ask the human, for the interactions // the turn's channel can carry, and nothing otherwise. func InteractiveTools(ctx context.Context) []tools.ToolEntry { interactive := InteractiveFromContext(ctx) var out []tools.ToolEntry if interactive.Clarifier != nil || interactive.Picker != nil { out = append(out, askUserTool()) } if interactive.Questioner != nil { out = append(out, askQuestionsTool()) } return out } func askQuestionsTool() tools.ToolEntry { return tools.ToolEntry{ Name: askQuestionsToolName, Toolset: "chat", Description: "Ask the human several related questions at once, each with choices to pick from or a free-text answer. " + "Prefer it to repeated ask_user calls when you need more than one answer. " + "Blocks until they answer or skip, so ask at most once and only when you cannot proceed without it.", Classification: tools.ClassIdempotent, Schema: tools.JSONSchema{ "type": "object", "properties": map[string]any{ "questions": map[string]any{ "type": "array", "description": fmt.Sprintf("One to %d questions, asked in order.", maxQuestions), "items": map[string]any{ "type": "object", "properties": map[string]any{ "name": map[string]any{"type": "string", "description": "A short unique key the answer comes back under."}, "title": map[string]any{"type": "string", "description": "The question."}, "description": map[string]any{"type": "string", "description": "Optional detail under the question."}, "multiple": map[string]any{"type": "boolean", "description": "Let the human pick several choices."}, "required": map[string]any{"type": "boolean", "description": "The human must answer before continuing."}, "allow_other": map[string]any{"type": "boolean", "description": "Let the human type an answer that is not a choice."}, "choices": map[string]any{ "type": "array", "description": "The options. Omit for a free-text question.", "items": map[string]any{ "type": "object", "properties": map[string]any{ "value": map[string]any{"type": "string"}, "label": map[string]any{"type": "string"}, "description": map[string]any{"type": "string"}, }, "required": []string{"value"}, }, }, }, "required": []string{"name", "title"}, }, }, }, "required": []string{"questions"}, }, Handler: askQuestionsHandler, } } func askQuestionsHandler(ctx context.Context, args map[string]any) (any, error) { interactive := InteractiveFromContext(ctx) if interactive.Questioner == nil { return nil, fmt.Errorf("ask_questions: this channel cannot ask questions") } req, err := questionnaireRequest(args["questions"]) if err != nil { return nil, fmt.Errorf("ask_questions: %w", err) } answers, err := interactive.Questioner.RequestAnswers(ctx, req) if err != nil { return nil, err } var skipped []string for _, q := range req.Questions { if _, ok := answers[q.Name]; !ok { skipped = append(skipped, q.Name) } } return map[string]any{"answers": answers, "skipped": skipped}, nil } // questionnaireRequest reads the model's questions, refusing a set the human // could not answer: no question, too many, an unnamed or repeated name, a // choice with no value, or a choice repeated within a question. func questionnaireRequest(raw any) (messaging.QuestionnaireRequest, error) { items, _ := raw.([]any) if len(items) == 0 || len(items) > maxQuestions { return messaging.QuestionnaireRequest{}, fmt.Errorf("ask between 1 and %d questions", maxQuestions) } names := map[string]bool{} req := messaging.QuestionnaireRequest{} for _, item := range items { fields, _ := item.(map[string]any) q := messaging.Question{ Name: strings.TrimSpace(asString(fields["name"])), Title: strings.TrimSpace(asString(fields["title"])), Description: strings.TrimSpace(asString(fields["description"])), } q.Multiple, _ = fields["multiple"].(bool) q.Required, _ = fields["required"].(bool) q.AllowOther, _ = fields["allow_other"].(bool) if q.Name == "" || q.Title == "" { return messaging.QuestionnaireRequest{}, fmt.Errorf("every question needs a name and a title") } if names[q.Name] { return messaging.QuestionnaireRequest{}, fmt.Errorf("question name %q is used twice", q.Name) } names[q.Name] = true values := map[string]bool{} choices, _ := fields["choices"].([]any) for _, c := range choices { cf, _ := c.(map[string]any) choice := messaging.QuestionChoice{ Value: strings.TrimSpace(asString(cf["value"])), Label: strings.TrimSpace(asString(cf["label"])), Description: strings.TrimSpace(asString(cf["description"])), } if choice.Value == "" || values[choice.Value] { return messaging.QuestionnaireRequest{}, fmt.Errorf("question %q has an empty or repeated choice", q.Name) } values[choice.Value] = true if choice.Label == "" { choice.Label = choice.Value } q.Choices = append(q.Choices, choice) } req.Questions = append(req.Questions, q) } return req, nil } func askUserTool() tools.ToolEntry { return tools.ToolEntry{ Name: askUserToolName, Toolset: "chat", Description: "Ask the human a question when their answer changes what you do. " + "Pass options to ask them to choose exactly one; without options it is a free-text question. " + "Blocks until they answer, so ask at most once and only when you cannot proceed without it.", Classification: tools.ClassIdempotent, Schema: tools.JSONSchema{ "type": "object", "properties": map[string]any{ "question": map[string]any{ "type": "string", "description": "The question to ask.", }, "options": map[string]any{ "type": "array", "description": "Optional choices; when present the human picks exactly one.", "items": map[string]any{"type": "string"}, }, }, "required": []string{"question"}, }, Handler: askUserHandler, } } // askUserHandler carries one question through the turn's channel adapter. func askUserHandler(ctx context.Context, args map[string]any) (any, error) { question := strings.TrimSpace(asString(args["question"])) if question == "" { return nil, fmt.Errorf("ask_user: question is required") } interactive := InteractiveFromContext(ctx) options := asStringSlice(args["options"]) if len(options) > 0 { return askUserChoice(ctx, interactive, question, options) } if interactive.Clarifier == nil { return nil, fmt.Errorf("ask_user: this channel cannot ask a question") } answer, err := interactive.Clarifier.RequestClarification(ctx, ClarifyRequest{Question: question}) if err != nil { return nil, err } return map[string]any{"answer": answer}, nil } // askUserChoice asks a single-choice question with the channel's Picker, or // as numbered text through Clarify. func askUserChoice(ctx context.Context, interactive Interactive, question string, options []string) (any, error) { req := PickerRequest{Prompt: question, Options: interactiveChoices(options)} if interactive.Picker != nil { choice, err := interactive.Picker.RequestChoice(ctx, req) if err != nil { return nil, err } return choiceResult(choice), nil } if interactive.Clarifier == nil { return nil, fmt.Errorf("ask_user: this channel cannot ask a question") } answer, err := interactive.Clarifier.RequestClarification(ctx, ClarifyRequest{Question: FormatPickerText(req)}) if err != nil { return nil, err } choice, ok := ParsePickerReply(req, answer) if !ok { return nil, fmt.Errorf("ask_user: reply %q does not match any offered option", strings.TrimSpace(answer)) } return choiceResult(choice), nil } func choiceResult(choice messaging.InteractiveChoice) map[string]any { return map[string]any{"value": choice.ID, "choice": choice.Label} } func interactiveChoices(options []string) []messaging.InteractiveChoice { choices := make([]messaging.InteractiveChoice, 0, len(options)) for _, option := range options { choices = append(choices, messaging.InteractiveChoice{ID: option, Label: option}) } return choices }