My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** Structured output configuration using JSON Schema.
2
3 This module provides structured output support for Claude, allowing you to
4 specify the expected output format using JSON schemas. When a structured
5 output format is configured, Claude will return its response in the
6 specified JSON format, validated against your schema.
7
8 {2 Overview}
9
10 Structured outputs ensure that Claude's responses conform to a specific
11 JSON schema, making it easier to parse and use the results programmatically.
12 This is particularly useful for:
13
14 - Extracting structured data from unstructured text
15 - Building APIs that require consistent JSON responses
16 - Integrating Claude into data pipelines
17 - Ensuring type-safe parsing of Claude's outputs
18
19 {2 Creating Output Formats}
20
21 Use {!of_json_schema} to specify a JSON Schema as a {!Jsont.json} value:
22 {[
23 let meta = Jsont.Meta.none in
24 let schema = Jsont.Object ([
25 (("type", meta), Jsont.String ("object", meta));
26 (("properties", meta), Jsont.Object ([
27 (("name", meta), Jsont.Object ([
28 (("type", meta), Jsont.String ("string", meta))
29 ], meta));
30 (("age", meta), Jsont.Object ([
31 (("type", meta), Jsont.String ("integer", meta))
32 ], meta));
33 ], meta));
34 (("required", meta), Jsont.Array ([
35 Jsont.String ("name", meta);
36 Jsont.String ("age", meta)
37 ], meta));
38 ], meta) in
39
40 let format = Structured_output.of_json_schema schema
41 ]}
42
43 {3 Helper Functions for Building Schemas}
44
45 For complex schemas, you can use helper functions to make construction easier:
46 {[
47 let json_object fields =
48 Jsont.Object (fields, Jsont.Meta.none)
49
50 let json_string s =
51 Jsont.String (s, Jsont.Meta.none)
52
53 let json_array items =
54 Jsont.Array (items, Jsont.Meta.none)
55
56 let json_field name value =
57 ((name, Jsont.Meta.none), value)
58
59 let person_schema =
60 json_object [
61 json_field "type" (json_string "object");
62 json_field "properties" (json_object [
63 json_field "name" (json_object [
64 json_field "type" (json_string "string")
65 ]);
66 json_field "age" (json_object [
67 json_field "type" (json_string "integer")
68 ]);
69 ]);
70 json_field "required" (json_array [
71 json_string "name";
72 json_string "age"
73 ])
74 ]
75
76 let format = Structured_output.of_json_schema person_schema
77 ]}
78
79 {2 Usage with Claude Client}
80
81 {[
82 let options = Options.default
83 |> Options.with_output_format format
84
85 let client = Client.create ~sw ~process_mgr ~options () in
86 Client.query client "Extract person info from: John is 30 years old";
87
88 let messages = Client.receive_all client in
89 List.iter (function
90 | Message.Result result ->
91 (match Message.Result.structured_output result with
92 | Some json -> (* Process validated JSON *)
93 let json_str = match Jsont_bytesrw.encode_string' Jsont.json json with
94 | Ok s -> s
95 | Error err -> Jsont.Error.to_string err
96 in
97 Printf.printf "Structured output: %s\n" json_str
98 | None -> ())
99 | _ -> ()
100 ) messages
101 ]}
102
103 {2 JSON Schema Support}
104
105 The module supports standard JSON Schema Draft 7, including:
106 - Primitive types (string, integer, number, boolean, null)
107 - Objects with properties and required fields
108 - Arrays with item schemas
109 - Enumerations
110 - Nested objects and arrays
111 - Complex validation rules
112
113 @see <https://json-schema.org/> JSON Schema specification
114 @see <https://erratique.ch/software/jsont> jsont documentation *)
115
116(** The log source for structured output operations *)
117val src : Logs.Src.t
118
119(** {1 Output Format Configuration} *)
120
121type t
122(** The type of structured output format configurations. *)
123
124val of_json_schema : Jsont.json -> t
125(** [of_json_schema schema] creates an output format from a JSON Schema.
126
127 The schema should be a valid JSON Schema Draft 7 as a {!Jsont.json} value.
128
129 Example:
130 {[
131 let meta = Jsont.Meta.none in
132 let schema = Jsont.Object ([
133 (("type", meta), Jsont.String ("object", meta));
134 (("properties", meta), Jsont.Object ([
135 (("name", meta), Jsont.Object ([
136 (("type", meta), Jsont.String ("string", meta))
137 ], meta));
138 (("age", meta), Jsont.Object ([
139 (("type", meta), Jsont.String ("integer", meta))
140 ], meta));
141 ], meta));
142 (("required", meta), Jsont.Array ([
143 Jsont.String ("name", meta);
144 Jsont.String ("age", meta)
145 ], meta));
146 ], meta) in
147
148 let format = Structured_output.of_json_schema schema
149 ]} *)
150
151val json_schema : t -> Jsont.json
152(** [json_schema t] returns the JSON Schema. *)
153
154val jsont : t Jsont.t
155(** Codec for structured output format. *)
156
157(** {1 Serialization}
158
159 Internal use for encoding/decoding with the CLI. *)
160
161val to_json : t -> Jsont.json
162(** [to_json t] converts the output format to its JSON representation.
163 Internal use only. *)
164
165val of_json : Jsont.json -> t
166(** [of_json json] parses an output format from JSON.
167 Internal use only.
168 @raise Invalid_argument if the JSON is not a valid output format. *)
169
170val pp : Format.formatter -> t -> unit
171(** [pp fmt t] pretty-prints the output format. *)