feat(people): add ultra mode to people search (#2149)

Stainless-Generated-From: 67275ca8930bf6537d4e079436adb185b057e7c7

Author: stlc-bot

pkg/cmd/person.go

@@ -152,20 +152,26 @@ var peopleSearch = requestflag.WithInnerFlags(cli.Command{
 	Flags: []cli.Flag{
 		&requestflag.Flag[string]{
 			Name:     "query",
-			Usage:    "Describe the people to find.",
+			Usage:    "Describe the people to find. Up to 500 characters in `fast` mode and 5000 in `ultra` mode.",
 			Required: true,
 			BodyPath: "query",
 		},
 		&requestflag.Flag[string]{
 			Name:     "cursor",
-			Usage:    "Use next_cursor with the same query and filters to fetch the next page.",
+			Usage:    "Use next_cursor with the same query, mode and filters to fetch the next page.",
 			BodyPath: "cursor",
 		},
 		&requestflag.Flag[map[string]any]{
 			Name:     "filters",
 			Usage:    "Additional constraints every result must match.",
 			BodyPath: "filters",
 		},
+		&requestflag.Flag[string]{
+			Name:     "mode",
+			Usage:    "`fast` matches people on basic criteria (e.g. their role, location or background); `ultra` plans a deeper search, judges each candidate against every criterion in the query and explains each match.",
+			Default:  "fast",
+			BodyPath: "mode",
+		},
 		&requestflag.Flag[[]string]{
 			Name:     "tag",
 			Usage:    "Labels for filtering usage in the dashboard.",

pkg/cmd/person_test.go

@@ -107,6 +107,7 @@ func TestPeopleSearch(t *testing.T) {
 			"--query", "VPs of sales at solar companies in California",
 			"--cursor", "cursor",
 			"--filters", "{countries: [SE], years_of_experience_max: 0, years_of_experience_min: 0}",
+			"--mode", "fast",
 			"--tag", "production",
 			"--tag", "team-alpha",
 		)
@@ -126,6 +127,7 @@ func TestPeopleSearch(t *testing.T) {
 			"--filters.countries", "[SE]",
 			"--filters.years-of-experience-max", "0",
 			"--filters.years-of-experience-min", "0",
+			"--mode", "fast",
 			"--tag", "production",
 			"--tag", "team-alpha",
 		)
@@ -141,6 +143,7 @@ func TestPeopleSearch(t *testing.T) {
 			"    - SE\n" +
 			"  years_of_experience_max: 0\n" +
 			"  years_of_experience_min: 0\n" +
+			"mode: fast\n" +
 			"tags:\n" +
 			"  - production\n" +
 			"  - team-alpha\n")