feat(structured-output): add typed helpers for structured JSON (RunJSON, RunStreamedJSON)

README.md

@@ -93,6 +93,24 @@ turn, err := thread.Run(ctx, "Write a one sentence update.", &godex.TurnOptions{
 })
 ```
 
+### Typed helpers
+
+Generate and decode structured JSON into Go types with `RunJSON` / `RunStreamedJSON`. Provide
+your own schema or allow the helpers to infer one from `T`:
+
+```go
+type Update struct {
+ Headline string `json:"headline"`
+ NextStep string `json:"next_step"`
+}
+
+result, err := godex.RunJSON[Update](ctx, thread, "Provide a concise update.", nil)
+if err != nil {
+ log.Fatal(err)
+}
+log.Printf("update: %+v", result)
+```
+
 ## Multi-part input and local images
 
 Mix text segments and local image paths by using `RunInputs` / `RunStreamedInputs` with
@@ -119,6 +137,7 @@ fmt.Println("Assistant:", turn.FinalResponse)
 - `examples/basic`: single-turn conversation (`go run ./examples/basic`)
 - `examples/streaming`: step-by-step event streaming demo (`go run ./examples/streaming`)
 - `examples/schema`: structured JSON output with schema validation (`go run ./examples/schema`)
+- `examples/structured_output`: typed structured output helpers (`go run ./examples/structured_output`)
 - `examples/images`: multi-part prompt mixing text and a local image (`go run ./examples/images`)
 
 ## Thread persistence

examples/structured_output/main.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/activadee/godex"
+)
+
+type projectUpdate struct {
+	Headline string `json:"headline" jsonschema:"description=Short summary of the update"`
+	NextStep string `json:"next_step" jsonschema:"description=Concrete follow-up action"`
+}
+
+func main() {
+	client, err := godex.New(godex.CodexOptions{})
+	if err != nil {
+		log.Fatalf("create codex client: %v", err)
+	}
+
+	thread := client.StartThread(godex.ThreadOptions{
+		Model: "gpt-5",
+	})
+
+	update, err := godex.RunJSON[projectUpdate](context.Background(), thread, "Provide a concise project update and a suggested next step.", nil)
+	if err != nil {
+		log.Fatalf("run structured turn: %v", err)
+	}
+
+	fmt.Printf("Headline: %s\nNext step: %s\n", update.Headline, update.NextStep)
+
+	streamed, err := godex.RunStreamedJSON[projectUpdate](context.Background(), thread, "Give another update and next step, streaming partial results.", nil)
+	if err != nil {
+		log.Fatalf("start streamed structured turn: %v", err)
+	}
+	defer streamed.Close()
+
+	for update := range streamed.Updates() {
+		fmt.Printf("[structured update] final=%t headline=%q next_step=%q\n", update.Final, update.Value.Headline, update.Value.NextStep)
+	}
+
+	if err := streamed.Wait(); err != nil {
+		log.Fatalf("streamed structured turn failed: %v", err)
+	}
+}

go.mod

@@ -1,3 +1,13 @@
 module github.com/activadee/godex
 
 go 1.22
+
+require github.com/invopop/jsonschema v0.13.0
+
+require (
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
+	github.com/buger/jsonparser v1.1.1 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,21 @@
+github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
+github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
+github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
+github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
+github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
+github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=