feat(answers): add live web research with fast and ultra modes (#954)

Stainless-Generated-From: 462dacbcb30fa1a30926f16d800581d9e4cb508b

Author: stlc-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 47
+configured_endpoints: 48

pkg/cmd/cmd.go

@@ -97,6 +97,7 @@ func init() {
 				Category: "API RESOURCE",
 				Suggest:  true,
 				Commands: []*cli.Command{
+					&webAnswers,
 					&webExtract,
 					&webExtractCompetitors,
 					&webExtractFonts,

pkg/cmd/web.go

@@ -14,6 +14,42 @@ import (
 	"github.com/urfave/cli/v3"
 )
 
+var webAnswers = cli.Command{
+	Name:    "answers",
+	Usage:   "Researches the live web and returns a sourced answer in your requested JSON\nshape. Select fast for a smaller research budget at 10 credits or ultra for\ndeeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to\n30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline.",
+	Suggest: true,
+	Flags: []cli.Flag{
+		&requestflag.Flag[string]{
+			Name:     "task",
+			Usage:    `What to research and answer, in plain language. Naming a domain in the task (for example "pricing on context.dev") makes the agent read that site before it searches.`,
+			Required: true,
+			BodyPath: "task",
+		},
+		&requestflag.Flag[map[string]any]{
+			Name:     "json-format",
+			Usage:    `An example object with placeholder values (for example {"pricing_page_url": "", "plans": [{"name": "", "price": 0}]}). Object keys and value types are preserved; unknown values may be null. Empty arrays accept any JSON items. Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters.`,
+			BodyPath: "json_format",
+		},
+		&requestflag.Flag[string]{
+			Name:     "mode",
+			Usage:    "Research level: fast uses a smaller model and research budget for 10 credits; ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. Only successful requests consume credits.",
+			BodyPath: "mode",
+		},
+		&requestflag.Flag[[]string]{
+			Name:     "tag",
+			Usage:    "Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.",
+			BodyPath: "tags",
+		},
+		&requestflag.Flag[int64]{
+			Name:     "timeout-ms",
+			Usage:    "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).",
+			BodyPath: "timeoutMS",
+		},
+	},
+	Action:          handleWebAnswers,
+	HideHelpCommand: true,
+}
+
 var webExtract = requestflag.WithInnerFlags(cli.Command{
 	Name:    "extract",
 	Usage:   "Crawl a website, use the provided JSON Schema and instructions to prioritize\nrelevant internal links, and extract structured data from the selected pages.",
@@ -1010,6 +1046,47 @@ var webWebScrapeSitemap = cli.Command{
 	HideHelpCommand: true,
 }
 
+func handleWebAnswers(ctx context.Context, cmd *cli.Command) error {
+	client := contextdev.NewClient(getDefaultRequestOptions(cmd)...)
+	unusedArgs := cmd.Args().Slice()
+
+	if len(unusedArgs) > 0 {
+		return fmt.Errorf("Unexpected extra arguments: %v", unusedArgs)
+	}
+
+	options, err := flagOptions(
+		cmd,
+		apiquery.NestedQueryFormatBrackets,
+		apiquery.ArrayQueryFormatComma,
+		ApplicationJSON,
+		false,
+	)
+	if err != nil {
+		return err
+	}
+
+	params := contextdev.WebAnswersParams{}
+
+	var res []byte
+	options = append(options, option.WithResponseBodyInto(&res))
+	_, err = client.Web.Answers(ctx, params, options...)
+	if err != nil {
+		return err
+	}
+
+	obj := gjson.ParseBytes(res)
+	format := cmd.Root().String("format")
+	explicitFormat := cmd.Root().IsSet("format")
+	transform := cmd.Root().String("transform")
+	return ShowJSON(obj, ShowJSONOpts{
+		ExplicitFormat: explicitFormat,
+		Format:         format,
+		RawOutput:      cmd.Root().Bool("raw-output"),
+		Title:          "web answers",
+		Transform:      transform,
+	})
+}
+
 func handleWebExtract(ctx context.Context, cmd *cli.Command) error {
 	client := contextdev.NewClient(getDefaultRequestOptions(cmd)...)
 	unusedArgs := cmd.Args().Slice()

pkg/cmd/web_test.go

@@ -9,6 +9,42 @@ import (
 	"github.com/context-dot-dev/context-dev-cli/internal/requestflag"
 )
 
+func TestWebAnswers(t *testing.T) {
+	t.Skip("Mock server tests are disabled")
+	t.Run("regular flags", func(t *testing.T) {
+		mocktest.TestRunMockTestWithFlags(
+			t,
+			"--api-key", "string",
+			"web", "answers",
+			"--task", "Find the pricing page URL and plan names for context.dev.",
+			"--json-format", "{pricing_page_url: bar, plans: bar}",
+			"--mode", "fast",
+			"--tag", "production",
+			"--tag", "team-alpha",
+			"--timeout-ms", "1000",
+		)
+	})
+
+	t.Run("piping data", func(t *testing.T) {
+		// Test piping YAML data over stdin
+		pipeData := []byte("" +
+			"task: Find the pricing page URL and plan names for context.dev.\n" +
+			"json_format:\n" +
+			"  pricing_page_url: bar\n" +
+			"  plans: bar\n" +
+			"mode: fast\n" +
+			"tags:\n" +
+			"  - production\n" +
+			"  - team-alpha\n" +
+			"timeoutMS: 1000\n")
+		mocktest.TestRunMockTestWithPipeAndFlags(
+			t, pipeData,
+			"--api-key", "string",
+			"web", "answers",
+		)
+	})
+}
+
 func TestWebExtract(t *testing.T) {
 	t.Skip("Mock server tests are disabled")
 	t.Run("regular flags", func(t *testing.T) {