Documentation
¶
Overview ¶
Package artifact defines the extensible Artifact interface and common concrete types used throughout ore. The Artifact interface exposes a public Kind() method to allow custom artifact types to be defined in other packages.
Package artifact defines the extensible Artifact interface and common concrete types used throughout ore.
The Artifact interface exposes a public Kind() method to allow custom artifact types to be defined in other packages. Private marker methods would prevent cross-package extensibility because Go does not allow implementing unexported methods across package boundaries.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Accumulable ¶ added in v0.1.0
Accumulable marks delta artifacts that can be merged into complete artifacts by a generic accumulator. Implementations must return a stable AccumulatorKey and define MergeInto to combine the delta with an existing accumulated artifact or seed a new one when acc is nil.
type Artifact ¶
type Artifact interface {
Kind() string
}
Artifact is the base interface for all LLM response artifacts.
type Delta ¶
type Delta interface {
Artifact
IsDelta()
}
Delta marks artifacts that are ephemeral streaming fragments. These must never be persisted to state; only complete artifacts should be.
type Image ¶
type Image struct {
URL string
}
Image represents an image artifact referenced by URL.
func (Image) MarshalJSON ¶ added in v0.6.0
MarshalJSON serializes Image to JSON.
type LLMRenderer ¶ added in v0.2.0
type LLMRenderer interface {
MarshalLLM() string
}
LLMRenderer is implemented by tool result values that know how to serialize themselves for consumption by an LLM provider.
type MarkdownRenderer ¶ added in v0.2.0
type MarkdownRenderer interface {
MarshalMarkdown() string
}
MarkdownRenderer is implemented by tool result values that know how to render themselves as Markdown for human display.
type Reasoning ¶
type Reasoning struct {
Content string
}
Reasoning represents a reasoning or thinking content artifact.
func (Reasoning) MarshalJSON ¶ added in v0.6.0
MarshalJSON serializes Reasoning to JSON.
type ReasoningDelta ¶
type ReasoningDelta struct {
Content string
}
ReasoningDelta represents a partial chunk of reasoning content for streaming.
func (ReasoningDelta) AccumulatorKey ¶ added in v0.1.0
func (d ReasoningDelta) AccumulatorKey() string
AccumulatorKey returns a stable routing key for the generic accumulator. ReasoningDelta accumulates into a single "reasoning" block.
func (ReasoningDelta) IsDelta ¶
func (r ReasoningDelta) IsDelta()
IsDelta marks ReasoningDelta as an ephemeral streaming fragment.
func (ReasoningDelta) Kind ¶
func (r ReasoningDelta) Kind() string
Kind returns the artifact kind identifier.
func (ReasoningDelta) MarshalJSON ¶ added in v0.6.0
func (r ReasoningDelta) MarshalJSON() ([]byte, error)
MarshalJSON serializes ReasoningDelta to JSON.
func (ReasoningDelta) MergeInto ¶ added in v0.1.0
func (d ReasoningDelta) MergeInto(acc Artifact) Artifact
MergeInto merges the delta into an existing Reasoning artifact or seeds a new one.
type ReasoningSignature ¶ added in v0.9.0
type ReasoningSignature struct {
Provider string `json:"provider"`
SubKind string `json:"sub_kind"`
Data string `json:"data"`
}
ReasoningSignature represents an opaque, provider-issued signature that anchors a prior reasoning block to the next request. It is emitted by providers that support extended-thinking / reasoning replay, and is consumed by request serializers to attach the right wire shape to the assistant content array of the next turn.
The three fields are the minimal representation that lets a single artifact type carry every wire shape the supported upstreams produce:
- Provider discriminates the upstream. Today the supported values are "anthropic" and "openai"; new providers extend the set.
- SubKind discriminates the wire shape that the upstream expects for replay. Defined values:
- "signature": Anthropic thinking-block signature (the opaque signature that anchors extended-thinking across turns; arrives on the response side of ThinkingBlock).
- "redacted": Anthropic redacted_thinking block data (encrypted reasoning; arrives on the response side of RedactedThinkingBlock).
- "encrypted": OpenAI / OpenRouter reasoning.encrypted entry in reasoning_details[] on the chat-completions wire.
- Data is opaque. Consumers MUST NOT parse it; the request serializer routes it to the correct upstream shape based on (Provider, SubKind).
The struct field is named SubKind (not Kind) to avoid a name collision with the artifact interface's Kind() method. The explicit JSON tags are required so the wire-level `sub_kind` key is matched to the `SubKind` field on the way in; without them, encoding/json's case-insensitive field matching would route `sub_kind` to a `Kind` field (which does not exist) instead, silently dropping the value.
ReasoningSignature is intentionally not Delta / Accumulable: signatures are complete artifacts emitted at the close of a reasoning block, never incrementally.
func (ReasoningSignature) Kind ¶ added in v0.9.0
func (r ReasoningSignature) Kind() string
Kind returns the artifact kind identifier.
func (ReasoningSignature) MarshalJSON ¶ added in v0.9.0
func (r ReasoningSignature) MarshalJSON() ([]byte, error)
MarshalJSON serializes ReasoningSignature to JSON.
type StatusContributor ¶ added in v0.4.0
StatusContributor is implemented by tool result values that carry ambient metadata to be broadcast to all subscribers via PropertiesEvent.
type Text ¶
type Text struct {
Content string
}
Text represents a text content artifact.
func (Text) MarshalJSON ¶ added in v0.6.0
MarshalJSON serializes Text to JSON.
type TextDelta ¶
type TextDelta struct {
Content string
}
TextDelta represents a partial chunk of text content for streaming.
func (TextDelta) AccumulatorKey ¶ added in v0.1.0
AccumulatorKey returns a stable routing key for the generic accumulator. TextDelta accumulates into a single "text" block.
func (TextDelta) IsDelta ¶
func (t TextDelta) IsDelta()
IsDelta marks TextDelta as an ephemeral streaming fragment.
func (TextDelta) MarshalJSON ¶ added in v0.6.0
MarshalJSON serializes TextDelta to JSON.
type ToolCall ¶
ToolCall represents a tool invocation artifact.
Arguments is the JSON object the model streamed; it is the source of truth for the wire format that providers serialize back to the upstream API. Display is an optional, opaque value attached by applyDisplayHints in the loop pipeline; it is for human rendering only (TUI, exporters, log viewers) and is never consulted by the wire-format code path. The two fields are deliberately decoupled so a tool's display choice cannot corrupt the wire format.
func (ToolCall) LLMString ¶ added in v0.4.0
LLMString returns the LLM-visible string representation of the tool call. For a tool call, the LLM sees the wire format — the JSON object the model originally streamed — so this returns Arguments directly. The display value is intentionally ignored: display is a human-rendering concern, not a wire-format concern.
This method exists primarily to support x/llmbytes' byte counting, which estimates the LLM-visible size of each artifact. Returning Arguments gives a more accurate estimate than the previous json.Marshal-of-Display fallback, which frequently diverged from the actual wire size for tools that return non-JSON display values.
func (ToolCall) MarkdownString ¶ added in v0.4.0
MarkdownString returns a human-readable representation of the tool call for display layers (TUI, exporters, log viewers). The lookup order is:
- If Display implements MarkdownRenderer, use MarshalMarkdown.
- If Display is a string, return it as-is. This is the common case for tools whose DisplayHint returns a pre-formatted label (e.g. "📁 list_directory(/path)"). The previous implementation json.Marshaled strings and embedded literal quotes; this is corrected here.
- Otherwise, fall back to json.Marshal of Display so structured values still render usefully.
- When Display is nil, fall through to Arguments.
Display is the single source of truth for human rendering; Arguments is intentionally not consulted unless Display is nil. Providers never call this method — it is for display consumers only.
func (ToolCall) MarshalJSON ¶ added in v0.6.0
MarshalJSON serializes ToolCall to JSON. The display field is only included when it differs from the raw arguments.
type ToolCallDelta ¶
ToolCallDelta represents a partial chunk of a tool invocation for streaming. Index identifies which parallel tool call in the current turn this fragment belongs to, enabling the generic accumulator to merge chunks independently.
func (ToolCallDelta) AccumulatorKey ¶ added in v0.1.0
func (d ToolCallDelta) AccumulatorKey() string
AccumulatorKey returns a stable routing key for the generic accumulator. ToolCallDelta accumulates per-index: "tool_call:0", "tool_call:1", etc.
func (ToolCallDelta) IsDelta ¶
func (t ToolCallDelta) IsDelta()
IsDelta marks ToolCallDelta as an ephemeral streaming fragment.
func (ToolCallDelta) Kind ¶
func (t ToolCallDelta) Kind() string
Kind returns the artifact kind identifier.
func (ToolCallDelta) MarshalJSON ¶ added in v0.6.0
func (t ToolCallDelta) MarshalJSON() ([]byte, error)
MarshalJSON serializes ToolCallDelta to JSON.
func (ToolCallDelta) MergeInto ¶ added in v0.1.0
func (d ToolCallDelta) MergeInto(acc Artifact) Artifact
MergeInto merges the delta into an existing ToolCall artifact or seeds a new one. ID uses latest-wins semantics; Name and Arguments are concatenated. Display is not present in deltas and is left nil on seeding; it is populated later by applyDisplayHints in the loop pipeline.
type ToolResult ¶
type ToolResult struct {
ToolCallID string `json:"tool_call_id"`
Content string `json:"content"`
Value any `json:"-"`
IsError bool `json:"is_error"`
Truncation *Truncation `json:"truncation,omitempty"`
}
ToolResult represents the result of executing a tool call. Content holds a JSON-marshaled fallback string for consumers that do not support custom rendering. Value holds the raw typed result, enabling downstream packages (providers, conduits) to apply custom serialization via LLMRenderer or MarkdownRenderer. When Value is nil or its type is not recognized, consumers fall back to Content.
Truncation is set by the framework handler when a tool's result was bounded by Format or by the framework defaults. A nil Truncation means the result was not truncated.
func (ToolResult) Kind ¶
func (t ToolResult) Kind() string
Kind returns the artifact kind identifier.
func (ToolResult) LLMString ¶ added in v0.2.0
func (t ToolResult) LLMString() string
LLMString returns a string representation of the tool result suitable for consumption by an LLM provider. It prefers the custom LLMRenderer on Value, falls back to json.Marshal of Value, and finally falls back to the pre-serialized Content string.
func (ToolResult) MarkdownString ¶ added in v0.2.0
func (t ToolResult) MarkdownString() string
MarkdownString returns a string representation of the tool result suitable for human display. It prefers the custom MarkdownRenderer on Value, falls back to json.Marshal of Value, and finally falls back to the pre-serialized Content string.
func (ToolResult) MarshalJSON ¶ added in v0.6.0
func (t ToolResult) MarshalJSON() ([]byte, error)
MarshalJSON serializes ToolResult to JSON.
type Truncation ¶ added in v0.8.0
type Truncation struct {
// OriginalBytes is the byte length of the full, untruncated
// result. Equal to ShownBytes when no truncation occurred.
OriginalBytes int `json:"original_bytes,omitempty"`
// OriginalLines is the line count of the full, untruncated
// result. A trailing line without a newline is counted. Equal
// to ShownLines when no truncation occurred.
OriginalLines int `json:"original_lines,omitempty"`
// ShownBytes is the byte length of the result that was
// actually sent to the LLM. Always ≤ OriginalBytes.
ShownBytes int `json:"shown_bytes"`
// ShownLines is the line count of the result that was
// actually sent to the LLM. Always ≤ OriginalLines.
ShownLines int `json:"shown_lines"`
// Style is "head" or "tail" — the truncation strategy that
// was applied. Empty when no truncation occurred.
Style string `json:"style,omitempty"`
// RecoveryHint is the rendered (template-substituted) hint
// that the framework appended to the truncated result. Empty
// when no hint was configured or no truncation occurred.
RecoveryHint string `json:"recovery_hint,omitempty"`
}
Truncation reports the relationship between the original tool result and the value that was actually surfaced to the LLM. It is emitted on artifact.ToolResult when a tool's output was bounded by the framework or by an explicit Format declaration.
A nil *Truncation on a ToolResult means the result was not truncated. The zero-value Truncation is treated as "no truncation" by consumers that check Truncated.
func (*Truncation) Truncated ¶ added in v0.8.0
func (t *Truncation) Truncated() bool
Truncated reports whether t indicates that a result was shortened. A nil receiver returns false. A non-nil receiver with OriginalBytes > ShownBytes returns true.
type Usage ¶
type Usage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
TotalTokens int `json:"total_tokens"`
CacheReadTokens int `json:"cache_read_tokens,omitempty"`
CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
ThinkingTokens int `json:"thinking_tokens,omitempty"`
}
Usage represents token consumption metadata from a provider response.
CacheReadTokens and CacheWriteTokens are populated by providers that support prompt caching. On OpenAI native, CacheReadTokens is set from usage.prompt_tokens_details.cached_tokens. On Anthropic-style hosts (and Anthropic-via-OpenRouter), CacheReadTokens and CacheWriteTokens are set from usage.cache_read_input_tokens and usage.cache_creation_input_tokens respectively. Providers that do not report cache metadata leave both fields at their zero value; the `omitempty` tags keep them out of the JSON payload in that case so consumers can distinguish "no cache reported" from "explicitly zero".
ThinkingTokens is the count of output tokens consumed by the model's extended-thinking / reasoning phase. Anthropic and Anthropic-via-OpenRouter surface this on the streaming message_delta usage block; other providers leave it at zero and the `omitempty` tag hides it from the JSON payload.
func (Usage) MarshalJSON ¶ added in v0.6.0
MarshalJSON serializes Usage to JSON.
Source Files