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(** High-level response events from Claude.
7
8 This module provides a unified interface for handling different types of
9 responses from Claude. It converts low-level message and content block types
10 into high-level response events that are easier to work with in application
11 code. *)
12
13(** {1 Response Event Types} *)
14
15module Text : sig
16 (** Text content from the assistant. *)
17
18 type t
19 (** The type of text response events (opaque). *)
20
21 val content : t -> string
22 (** [content t] returns the text content. *)
23
24 val of_block : Content_block.Text.t -> t
25 (** [of_block block] creates a text response from a content block. *)
26end
27
28module Tool_use : sig
29 (** Tool invocation request from the assistant. *)
30
31 type t
32 (** The type of tool use response events (opaque). *)
33
34 val id : t -> string
35 (** [id t] returns the unique identifier of the tool use. *)
36
37 val name : t -> string
38 (** [name t] returns the name of the tool being invoked. *)
39
40 val input : t -> Tool_input.t
41 (** [input t] returns the input parameters for the tool. *)
42
43 val of_block : Content_block.Tool_use.t -> t
44 (** [of_block block] creates a tool use response from a content block. *)
45end
46
47module Thinking : sig
48 (** Internal reasoning from the assistant. *)
49
50 type t
51 (** The type of thinking response events (opaque). *)
52
53 val content : t -> string
54 (** [content t] returns the thinking content. *)
55
56 val signature : t -> string
57 (** [signature t] returns the cryptographic signature. *)
58
59 val of_block : Content_block.Thinking.t -> t
60 (** [of_block block] creates a thinking response from a content block. *)
61end
62
63module Init : sig
64 (** Session initialization event. *)
65
66 type t
67 (** The type of init response events (opaque). *)
68
69 val session_id : t -> string option
70 (** [session_id t] returns the optional session identifier. *)
71
72 val model : t -> string option
73 (** [model t] returns the optional model name. *)
74
75 val cwd : t -> string option
76 (** [cwd t] returns the optional current working directory. *)
77
78 val of_system : Message.System.t -> t option
79 (** [of_system sys] returns Some if system message is init, None if error. *)
80end
81
82module Error : sig
83 (** Error events from system or assistant. *)
84
85 type t
86 (** The type of error response events (opaque). *)
87
88 val message : t -> string
89 (** [message t] returns the error message. *)
90
91 val is_system_error : t -> bool
92 (** [is_system_error t] returns true if this is a system error. *)
93
94 val is_assistant_error : t -> bool
95 (** [is_assistant_error t] returns true if this is an assistant error. *)
96
97 val of_system : Message.System.t -> t option
98 (** [of_system sys] returns Some if system message is error, None if init. *)
99
100 val of_assistant : Message.Assistant.t -> t option
101 (** [of_assistant msg] returns Some if assistant has error, None otherwise. *)
102end
103
104module Complete : sig
105 (** Session completion event with final results. *)
106
107 type t
108 (** The type of completion response events (opaque). *)
109
110 val duration_ms : t -> int
111 (** [duration_ms t] returns the total duration in milliseconds. *)
112
113 val num_turns : t -> int
114 (** [num_turns t] returns the number of conversation turns. *)
115
116 val session_id : t -> string
117 (** [session_id t] returns the session identifier. *)
118
119 val total_cost_usd : t -> float option
120 (** [total_cost_usd t] returns the optional total cost in USD. *)
121
122 val usage : t -> Message.Result.Usage.t option
123 (** [usage t] returns the optional usage statistics. *)
124
125 val result_text : t -> string option
126 (** [result_text t] returns the optional result string. *)
127
128 val structured_output : t -> Jsont.json option
129 (** [structured_output t] returns the optional structured JSON output. *)
130
131 val of_result : Message.Result.t -> t
132 (** [of_result result] creates a completion response from a result message. *)
133end
134
135(** {1 Response Event Union Type} *)
136
137(** The type of response events that can be received from Claude. *)
138type t =
139 | Text of Text.t (** Text content from assistant *)
140 | Tool_use of Tool_use.t (** Tool invocation request *)
141 | Tool_result of Content_block.Tool_result.t
142 (** Tool result (pass-through) *)
143 | Thinking of Thinking.t (** Internal reasoning *)
144 | Init of Init.t (** Session initialization *)
145 | Error of Error.t (** Error event *)
146 | Complete of Complete.t (** Session completion *)
147
148(** {1 Conversion} *)
149
150val of_message : Message.t -> t list
151(** [of_message msg] converts a message to response events. An assistant message
152 may produce multiple events (one per content block). User messages produce
153 empty lists since they are not responses. *)