1// Package provider defines the LLM client abstraction used by zot.
2//
3// It supports exactly two providers: Anthropic (Messages API) and
4// OpenAI (Chat Completions API). Everything above this package operates
5// on the types declared here and does not know about HTTP or SSE.
6package provider
7
8import (
9 "context"
10 "encoding/json"
11 "time"
12)
13
14// Role is the speaker of a Message.
15type Role string
16
17const (
18 RoleUser Role = "user"
19 RoleAssistant Role = "assistant"
20 RoleTool Role = "tool"
21)
22
23// Content is a block inside a Message. One of TextBlock, ImageBlock,
24// ToolCallBlock, or ToolResultBlock.
25type Content interface {
26 isContent()
27}
28
29// TextBlock is plain text content.
30type TextBlock struct {
31 Text string `json:"text"`
32 ThoughtSignature string `json:"thought_signature,omitempty"`
33}
34
35func (TextBlock) isContent() {}
36
37// ImageBlock is an inline image (PNG/JPEG/GIF/WebP).
38type ImageBlock struct {
39 MimeType string `json:"mime_type"`
40 Data []byte `json:"data"` // raw bytes; encoded to base64 on the wire
41 ThoughtSignature string `json:"thought_signature,omitempty"`
42}
43
44func (ImageBlock) isContent() {}
45
46// ToolCallBlock is an assistant-issued call to a tool.
47type ToolCallBlock struct {
48 ID string `json:"id"`
49 Name string `json:"name"`
50 Arguments json.RawMessage `json:"arguments"`
51 ThoughtSignature string `json:"thought_signature,omitempty"`
52}
53
54func (ToolCallBlock) isContent() {}
55
56// ToolResultBlock is the result of a tool execution, attached to a
57// Message with Role == RoleTool.
58type ToolResultBlock struct {
59 CallID string `json:"call_id"`
60 Content []Content `json:"content"`
61 IsError bool `json:"is_error"`
62}
63
64func (ToolResultBlock) isContent() {}
65
66// ReasoningBlock carries the assistant's chain-of-thought metadata so
67// providers that require it on follow-up requests (OpenAI Codex with
68// thinking enabled) can replay the same payload they emitted earlier.
69// Summary is the human-readable reasoning summary (may be empty); the
70// encrypted blob is opaque to zot. ID is the provider-issued reasoning
71// item id.
72type ReasoningBlock struct {
73 ID string `json:"reasoning_id,omitempty"`
74 Summary string `json:"summary,omitempty"`
75 Encrypted string `json:"encrypted_content,omitempty"`
76}
77
78func (ReasoningBlock) isContent() {}
79
80// RepairOrphanedToolResults removes tool_result content blocks (and
81// entire messages that become empty) when the matching tool_use ID
82// does not appear anywhere in the given messages. Resume tails,
83// compaction repair, and provider request builders all need this so
84// the upstream API never sees a tool_call_id with no corresponding
85// assistant tool_call earlier in the same request.
86func RepairOrphanedToolResults(msgs []Message) []Message {
87 useIDs := map[string]bool{}
88 for _, m := range msgs {
89 for _, c := range m.Content {
90 if tc, ok := c.(ToolCallBlock); ok {
91 useIDs[tc.ID] = true
92 }
93 }
94 }
95 out := make([]Message, 0, len(msgs))
96 for _, m := range msgs {
97 var filtered []Content
98 for _, c := range m.Content {
99 if tr, ok := c.(ToolResultBlock); ok {
100 if !useIDs[tr.CallID] {
101 continue
102 }
103 }
104 filtered = append(filtered, c)
105 }
106 if len(filtered) > 0 {
107 copy := m
108 copy.Content = filtered
109 out = append(out, copy)
110 }
111 }
112 return out
113}
114
115// Message is a single turn in the conversation.
116type Message struct {
117 Role Role `json:"role"`
118 Content []Content `json:"content"`
119 Time time.Time `json:"time"`
120 Meta map[string]string `json:"meta,omitempty"`
121 AddedToolNames []string `json:"added_tool_names,omitempty"`
122}
123
124// Tool is a tool definition advertised to the LLM.
125type Tool struct {
126 Name string `json:"name"`
127 Description string `json:"description"`
128 Schema json.RawMessage `json:"schema"` // JSON Schema for arguments
129 // Deferred hides the definition until a tool result activates it.
130 Deferred bool `json:"deferred,omitempty"`
131}
132
133// Usage aggregates token counts and cost for a turn.
134type Usage struct {
135 InputTokens int `json:"input_tokens"`
136 OutputTokens int `json:"output_tokens"`
137 CacheReadTokens int `json:"cache_read_tokens"`
138 CacheWriteTokens int `json:"cache_write_tokens"`
139 CostUSD float64 `json:"cost_usd"`
140}
141
142// Add returns u plus v.
143func (u Usage) Add(v Usage) Usage {
144 return Usage{
145 InputTokens: u.InputTokens + v.InputTokens,
146 OutputTokens: u.OutputTokens + v.OutputTokens,
147 CacheReadTokens: u.CacheReadTokens + v.CacheReadTokens,
148 CacheWriteTokens: u.CacheWriteTokens + v.CacheWriteTokens,
149 CostUSD: u.CostUSD + v.CostUSD,
150 }
151}
152
153// StopReason describes why a turn ended.
154type StopReason string
155
156const (
157 StopEnd StopReason = "end"
158 StopLength StopReason = "length"
159 StopToolUse StopReason = "tool_use"
160 StopError StopReason = "error"
161 StopAborted StopReason = "aborted"
162)
163
164// Event is one item from a provider stream.
165type Event interface {
166 isEvent()
167}
168
169type EventStart struct {
170 Model string
171 Provider string
172}
173
174func (EventStart) isEvent() {}
175
176type EventTextDelta struct {
177 Delta string
178}
179
180func (EventTextDelta) isEvent() {}
181
182type EventToolStart struct {
183 ID string
184 Name string
185}
186
187func (EventToolStart) isEvent() {}
188
189type EventToolArgs struct {
190 ID string
191 Delta string // partial JSON
192}
193
194func (EventToolArgs) isEvent() {}
195
196type EventToolEnd struct {
197 ID string
198}
199
200func (EventToolEnd) isEvent() {}
201
202type EventUsage struct {
203 Usage Usage
204}
205
206func (EventUsage) isEvent() {}
207
208// EventDone is always the final event on a stream.
209type EventDone struct {
210 Stop StopReason
211 Err error
212 Message Message // fully assembled assistant message
213}
214
215func (EventDone) isEvent() {}
216
217// Request is a single LLM call.
218type Request struct {
219 Model string
220 System string
221 Messages []Message
222 Tools []Tool
223 MaxTokens int
224 Temperature *float32
225 // Reasoning is "", "minimum", "low", "medium", "high", "xhigh", or
226 // "max". Empty disables reasoning. The max tier is sent natively only to
227 // models that support it and clamped elsewhere.
228 Reasoning string
229}
230
231// Client is an LLM streaming client.
232type Client interface {
233 // Name returns "anthropic" or "openai".
234 Name() string
235 // Stream starts a request. The returned channel delivers events
236 // and is closed after EventDone. Errors during request setup are
237 // returned directly; runtime errors arrive as EventDone{Err: ...}.
238 Stream(ctx context.Context, req Request) (<-chan Event, error)
239}