artifact

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 18, 2026 License: AGPL-3.0 Imports: 3 Imported by: 0

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 

type Accumulable interface {
	Delta
	AccumulatorKey() string
	MergeInto(acc Artifact) Artifact
}

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 Compaction added in v0.12.0 

type Compaction struct {
	CompactedThrough     int       `json:"compacted_through"`
	DroppedTurnCount     int       `json:"dropped_turn_count"`
	DroppedTokenEstimate int64     `json:"dropped_token_estimate"`
	Strategy             string    `json:"strategy"`
	Model                string    `json:"model,omitempty"`
	CreatedAt            time.Time `json:"created_at"`
}

Compaction is a metadata artifact marking a state-buffer compaction event. It is appended to the buffer as part of a RoleSystem turn (in addition to the artifact.Text carrying the LLM-facing summary). The artifact carries the structured provenance of the compaction so that consumers (analytics, TUI, future routing layers) can reason about what was folded without having to parse the summary text.

Compaction is intentionally NOT a Delta and NOT Accumulable. It is emitted as a single, complete artifact at the moment a compaction is produced; there is no streaming form.

Fields:

  • CompactedThrough is the index of the compaction turn within the buffer; "everything before this index is folded behind the summary" — the cumulative projection the transform applies. Stored as the turn's own index for self-describing recovery.
  • DroppedTurnCount is the number of pre-compaction turns folded behind the summary. Computed at compaction time.
  • DroppedTokenEstimate is a best-effort LLM-visible byte/token estimate of the dropped turns, computed by summing llmbytes.Of over the dropped artifacts. It is an approximation, not a provider-reported value.
  • Strategy is a short identifier of the strategy that produced this compaction (e.g. "summarize"). Free-form so new strategies can be introduced without changing this struct.
  • Model is the identifier of the model that produced the summary text (e.g. "gpt-4o-mini"). May be empty when the strategy does not consult an LLM.
  • CreatedAt records when the compaction was produced.

func (Compaction) Kind added in v0.12.0 

func (c Compaction) Kind() string

Kind returns the artifact kind identifier.

func (Compaction) MarshalJSON added in v0.12.0 

func (c Compaction) MarshalJSON() ([]byte, error)

MarshalJSON serializes Compaction to JSON.

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) Kind 

func (i Image) Kind() string

Kind returns the artifact kind identifier.

func (Image) MarshalJSON added in v0.6.0 

func (i Image) MarshalJSON() ([]byte, error)

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) Kind 

func (r Reasoning) Kind() string

Kind returns the artifact kind identifier.

func (Reasoning) MarshalJSON added in v0.6.0 

func (r Reasoning) MarshalJSON() ([]byte, error)

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 

type StatusContributor interface {
	Status() map[string]string
}

StatusContributor is implemented by tool result values that carry ambient metadata to be broadcast to all subscribers via PropertiesEvent.

type StopReason added in v0.11.0 

type StopReason struct {
	Reason StopReasonKind
}

StopReason is the artifact emitted by adapters on the streaming channel to communicate why the model stopped generating. It is emitted immediately before the final Usage artifact at the end of a successful stream.

The Reason field is the canonical StopReasonKind. Adapters are responsible for translating their provider-specific vocabulary (Anthropic stop_reason, OpenAI finish_reason) into the canonical set at the read-side; consumers can switch on Reason without caring which provider produced the stream.

func (StopReason) Kind added in v0.11.0 

func (s StopReason) Kind() string

Kind returns the artifact kind identifier.

func (StopReason) MarshalJSON added in v0.11.0 

func (s StopReason) MarshalJSON() ([]byte, error)

MarshalJSON serializes StopReason to JSON.

type StopReasonKind added in v0.11.0 

type StopReasonKind string

StopReasonKind is a canonical, provider-agnostic description of why a model stopped generating. Adapters translate provider-specific values (Anthropic stop_reason, OpenAI finish_reason) into one of these constants at the read-side, so downstream code never has to know which provider produced the stream.

The empty string is not a valid reason. Adapters should not emit a StopReason when the upstream did not report a reason; consumers should treat a missing StopReason as equivalent to StopReasonOther for forward compatibility.

Adding a new value is non-breaking; renaming a value is breaking. 

const (
	// StopReasonStop indicates the model finished normally — it produced
	// a complete response without hitting a length cap, calling a tool,
	// or being interrupted by a safety filter.
	StopReasonStop StopReasonKind = "stop"

	// StopReasonLength indicates the model hit a token-output cap
	// (Anthropic max_tokens, OpenAI length). The response may be
	// truncated; consumers that cannot tolerate truncation should
	// surface an error.
	StopReasonLength StopReasonKind = "length"

	// StopReasonToolUse indicates the model emitted a tool invocation
	// block. Adapters emit a ToolCall artifact alongside.
	StopReasonToolUse StopReasonKind = "tool_use"

	// StopReasonRefusal indicates the model declined to produce a
	// response due to a safety filter (Anthropic refusal, OpenAI
	// content_filter).
	StopReasonRefusal StopReasonKind = "refusal"

	// StopReasonOther is the catch-all for upstream values not covered
	// by the canonical set (e.g. Anthropic stop_sequence, or any new
	// reason a future adapter introduces). Forward-compatible: new
	// adapters can map unknown values to this without breaking
	// existing consumers.
	StopReasonOther StopReasonKind = "other"
)

type Text 

type Text struct {
	Content string
}

Text represents a text content artifact.

func (Text) Kind 

func (t Text) Kind() string

Kind returns the artifact kind identifier.

func (Text) MarshalJSON added in v0.6.0 

func (t Text) MarshalJSON() ([]byte, error)

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 

func (d TextDelta) AccumulatorKey() string

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) Kind 

func (t TextDelta) Kind() string

Kind returns the artifact kind identifier.

func (TextDelta) MarshalJSON added in v0.6.0 

func (t TextDelta) MarshalJSON() ([]byte, error)

MarshalJSON serializes TextDelta to JSON.

func (TextDelta) MergeInto added in v0.1.0 

func (d TextDelta) MergeInto(acc Artifact) Artifact

MergeInto merges the delta into an existing Text artifact or seeds a new one.

type ToolCall 

type ToolCall struct {
	ID        string
	Name      string
	Arguments string
	Display   any
}

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) Kind 

func (t ToolCall) Kind() string

Kind returns the artifact kind identifier.

func (ToolCall) LLMString added in v0.4.0 

func (t ToolCall) LLMString() string

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 

func (t ToolCall) MarkdownString() string

MarkdownString returns a human-readable representation of the tool call for display layers (TUI, exporters, log viewers). The lookup order is:

  1. If Display implements MarkdownRenderer, use MarshalMarkdown.
  2. 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.
  3. Otherwise, fall back to json.Marshal of Display so structured values still render usefully.
  4. 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 

func (t ToolCall) MarshalJSON() ([]byte, error)

MarshalJSON serializes ToolCall to JSON. The display field is only included when it differs from the raw arguments.

type ToolCallDelta 

type ToolCallDelta struct {
	Index     int
	ID        string
	Name      string
	Arguments string
}

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.

When the result carries an error, the pre-serialized Content wins regardless of what Value holds. This guarantees the `**Error:** <err>` footer that the framework handler appended after truncation reaches the LLM, even when Value is a typed result that would otherwise be re-marshaled (and would drop the footer). Without this short-circuit, a tool that returns (result, err) on the error path would render only the partial result to the model — silently discarding the error.

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) Kind 

func (u Usage) Kind() string

Kind returns the artifact kind identifier.

func (Usage) MarshalJSON added in v0.6.0 

func (u Usage) MarshalJSON() ([]byte, error)

MarshalJSON serializes Usage to JSON.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.