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