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 invalid tool_result content blocks
81// and entire messages that become empty. A result is invalid when its
82// matching tool_use ID does not appear anywhere in the messages or when
83// an earlier result already covers the same ID. Resume tails, compaction
84// repair, and provider request builders all need this so the upstream API
85// sees exactly one result for each referenced tool call.
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 resultIDs := map[string]bool{}
96 out := make([]Message, 0, len(msgs))
97 for _, m := range msgs {
98 var filtered []Content
99 for _, c := range m.Content {
100 if tr, ok := c.(ToolResultBlock); ok {
101 if !useIDs[tr.CallID] || resultIDs[tr.CallID] {
102 continue
103 }
104 resultIDs[tr.CallID] = true
105 }
106 filtered = append(filtered, c)
107 }
108 if len(filtered) > 0 {
109 copy := m
110 copy.Content = filtered
111 out = append(out, copy)
112 }
113 }
114 return out
115}
116
117// Message is a single turn in the conversation.
118type Message struct {
119 Role Role `json:"role"`
120 Content []Content `json:"content"`
121 Time time.Time `json:"time"`
122 Meta map[string]string `json:"meta,omitempty"`
123 AddedToolNames []string `json:"added_tool_names,omitempty"`
124}
125
126// Tool is a tool definition advertised to the LLM.
127type Tool struct {
128 Name string `json:"name"`
129 Description string `json:"description"`
130 Schema json.RawMessage `json:"schema"` // JSON Schema for arguments
131 // Deferred hides the definition until a tool result activates it.
132 Deferred bool `json:"deferred,omitempty"`
133}
134
135// activeToolDefinitions returns eager tools plus deferred tools activated by
136// prior tool results. Providers with a native position-sensitive deferred-tool
137// format can use the activation markers directly instead.
138func activeToolDefinitions(tools []Tool, messages []Message) []Tool {
139 activated := activatedToolNames(messages)
140 active := make([]Tool, 0, len(tools))
141 for _, tool := range tools {
142 if !tool.Deferred || activated[tool.Name] {
143 active = append(active, tool)
144 }
145 }
146 return active
147}
148
149func activatedToolNames(messages []Message) map[string]bool {
150 activated := make(map[string]bool)
151 for _, message := range messages {
152 for _, name := range message.AddedToolNames {
153 activated[name] = true
154 }
155 }
156 return activated
157}
158
159// Usage aggregates token counts and cost for a turn.
160type Usage struct {
161 InputTokens int `json:"input_tokens"`
162 OutputTokens int `json:"output_tokens"`
163 ReasoningTokens int `json:"reasoning_tokens"`
164 ReasoningTokensKnown bool `json:"reasoning_tokens_known,omitempty"`
165 CacheReadTokens int `json:"cache_read_tokens"`
166 CacheWriteTokens int `json:"cache_write_tokens"`
167 CostUSD float64 `json:"cost_usd"`
168}
169
170// Add returns u plus v. A reasoning total is known only when both
171// component usage reports include a separate reasoning-token count.
172func (u Usage) Add(v Usage) Usage {
173 return Usage{
174 InputTokens: u.InputTokens + v.InputTokens,
175 OutputTokens: u.OutputTokens + v.OutputTokens,
176 ReasoningTokens: u.ReasoningTokens + v.ReasoningTokens,
177 ReasoningTokensKnown: u.ReasoningTokensKnown && v.ReasoningTokensKnown,
178 CacheReadTokens: u.CacheReadTokens + v.CacheReadTokens,
179 CacheWriteTokens: u.CacheWriteTokens + v.CacheWriteTokens,
180 CostUSD: u.CostUSD + v.CostUSD,
181 }
182}
183
184// StopReason describes why a turn ended.
185type StopReason string
186
187const (
188 StopEnd StopReason = "end"
189 StopLength StopReason = "length"
190 StopToolUse StopReason = "tool_use"
191 StopError StopReason = "error"
192 StopAborted StopReason = "aborted"
193)
194
195// Event is one item from a provider stream.
196type Event interface {
197 isEvent()
198}
199
200type EventStart struct {
201 Model string
202 Provider string
203}
204
205func (EventStart) isEvent() {}
206
207type EventTextDelta struct {
208 Delta string
209}
210
211func (EventTextDelta) isEvent() {}
212
213type EventToolStart struct {
214 ID string
215 Name string
216}
217
218func (EventToolStart) isEvent() {}
219
220type EventToolArgs struct {
221 ID string
222 Delta string // partial JSON
223}
224
225func (EventToolArgs) isEvent() {}
226
227type EventToolEnd struct {
228 ID string
229}
230
231func (EventToolEnd) isEvent() {}
232
233type EventUsage struct {
234 Usage Usage
235}
236
237func (EventUsage) isEvent() {}
238
239// EventDone is always the final event on a stream.
240type EventDone struct {
241 Stop StopReason
242 Err error
243 Message Message // fully assembled assistant message
244}
245
246func (EventDone) isEvent() {}
247
248// Request is a single LLM call.
249type Request struct {
250 Model string
251 System string
252 Messages []Message
253 Tools []Tool
254 MaxTokens int
255 Temperature *float32
256 // Reasoning is "", "minimum", "low", "medium", "high", "xhigh", or
257 // "max". Empty disables reasoning. The max tier is sent natively only to
258 // models that support it and clamped elsewhere.
259 Reasoning string
260}
261
262// Client is an LLM streaming client.
263type Client interface {
264 // Name returns "anthropic" or "openai".
265 Name() string
266 // Stream starts a request. The returned channel delivers events
267 // and is closed after EventDone. Errors during request setup are
268 // returned directly; runtime errors arrive as EventDone{Err: ...}.
269 Stream(ctx context.Context, req Request) (<-chan Event, error)
270}