models

type Call struct {
	ID               string         `json:"id,omitempty"`
	Name             string         `json:"name,omitempty"`
	Type             string         `json:"type,omitempty"`
	Inputs           *Input         `json:"inputs,omitempty"`
	Function         Specification  `json:"function"`
	ExtraContent     map[string]any `json:"extra_content,omitempty"`
	ReasoningContent string         `json:"-"`
	// ReasoningItems are the opaque reasoning items (id + encrypted_content) that
	// preceded this call in the same Responses turn. They are replayed before the
	// function call so stateless (store:false) reasoning-model tool loops keep
	// reasoning continuity. OpenAI-only; empty for other vendors.
	ReasoningItems []ReasoningItem `json:"-"`
}

type CallUsageRecorder interface {
	Record(context.Context, CompletedModelCall) error
}

type Chat struct {
	Created time.Time `json:"created"`
	ID      string    `json:"id"`
	// Source is a stable, human-readable origin label.
	// Empty ("") for native clai chats.
	// Examples: "claude-code", "codex", "cursor", "clai" (forked from another clai chat).
	Source string `json:"source,omitempty"`
	// SourceID is the originating tool's conversation identifier, or the
	// parent chat ID when Source == "clai" (fork).
	SourceID string `json:"source_id,omitempty"`
	Profile  string `json:"profile,omitempty"`
	// OriginDir is the canonical working directory the chat was first persisted
	// from. It is stamped once on first persist and never rewritten, enabling
	// directory-anchored conversation search. Empty for conversations saved
	// before origin stamping existed (forward-only).
	OriginDir string `json:"origin_dir,omitempty"`
	// GroupKey is the hex-encoded SHA-256 of the first user message's canonical
	// text content. Empty when no user message exists, the first message is
	// image-only, or the chat predates this feature. Stamped once on first
	// persist; never rewritten.
	GroupKey string    `json:"group_key,omitempty"`
	Messages []Message `json:"messages"`
	// TokenUsage is the billable usage accumulated across all model calls in
	// the latest session. RecentTokenUsage is only the final model call, which
	// is the closest persisted gauge of the next request's context size.
	TokenUsage       *Usage      `json:"usage,omitempty"`
	RecentTokenUsage *Usage      `json:"recent_usage,omitempty"`
	Queries          []QueryCost `json:"queries,omitempty"`
}

type CompletedModelCall struct {
	StepIndex      int
	Model          string
	StartedAt      time.Time
	FinishedAt     time.Time
	Usage          *Usage
	EndedWithTool  bool
	EndedWithReply bool
	EndedWithStop  bool
}

type CompletionTokensDetails struct {
	ReasoningTokens          int `json:"reasoning_tokens"`
	AudioTokens              int `json:"audio_tokens"`
	AcceptedPredictionTokens int `json:"accepted_prediction_tokens"`
	RejectedPredictionTokens int `json:"rejected_prediction_tokens"`
}

type Configurations struct {
	Model         string
	SystemPrompt  string
	ConfigDir     string
	InternalTools []ToolName
	McpServers    []McpServer
	Out           io.Writer
}

type ImageOrTextInput struct {
	Text string `json:"text,omitempty"`
	Type string `json:"type,omitempty"`
	// This is openai's billion dollar API design
	// The "image_url" here may be b64 string
	ImageB64 *ImageURL `json:"image_url,omitempty"`
}

type ImageOrTextInputTypes string

type ImageURL struct {
	URL    string `json:"url"`
	Detail string `json:"detail"`
	// RawB64 is here for the vendors who does not encode
	// their mimetype and data into the "URL" field
	RawB64   string `json:"-"`
	MIMEType string `json:"-"`
}

type Input map[string]any

type InputSchema struct {
	Type       string                     `json:"type"`
	Required   []string                   `json:"required"`
	Properties map[string]ParameterObject `json:"properties"`
}

type JSONSchema struct {
	// Name of the schema. Required by the API.
	Name string
	// Description of what the schema represents. Optional.
	Description string
	// Strict enables strict mode. When true, the model will be forced to comply.
	Strict bool
	// Schema is the JSON Schema definition as a map.
	Schema map[string]any
}

type LLMTool interface {
	// Call the LLM tool with the given Input. Returns output from the tool or an error
	// if the call returned an error-like. An error-like is either exit code non-zero or
	// http response which isn't 2xx or 3xx.
	Call(Input) (string, error)

	// Return the Specification, later on used
	// by text queriers to send to their respective
	// models
	Specification() Specification
}

type McpServer struct {
	Name    string            `json:"name"`
	Command string            `json:"command"`
	Args    []string          `json:"args"`
	Env     map[string]string `json:"env"`
	EnvFile string            `json:"envfile,omitempty"`
	// TimeoutSeconds bounds a single tool call. 0 means unbounded: the call
	// waits for the server or for the caller's context, whichever comes first.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
}

type Message struct {
	Role             string `json:"role"`
	ToolCalls        []Call `json:"tool_calls,omitempty"`
	ToolCallID       string `json:"tool_call_id,omitempty"`
	ReasoningContent string `json:"reasoning_content,omitempty"`
	// ReasoningItems carry opaque reasoning continuity for a tool-bearing assistant
	// turn. They are stored out-of-band and keyed by the first persisted tool-call
	// ID, so the conversation JSON stays human-readable and portable.
	ReasoningItems []ReasoningItem `json:"-"`
	// Content and ContentParts is like this since
	// making Message generic would cause changes in 70+ places.
	//
	// This way we can use ContentParts (ImageInput) without
	// updating all places
	Content      string             `json:"-"`
	ContentParts []ImageOrTextInput `json:"-"`
}

type ParameterObject struct {
	Type        string            `json:"-"`
	Description string            `json:"description"`
	Enum        *[]string         `json:"enum,omitempty"`
	Items       *ParameterObject  `json:"items,omitempty"`
	AllOf       []ParameterObject `json:"allOf,omitempty"`
	AnyOf       []ParameterObject `json:"anyOf,omitempty"`
	OneOf       []ParameterObject `json:"oneOf,omitempty"`
}

type PromptTokensDetails struct {
	CachedTokens int `json:"cached_tokens"`
	AudioTokens  int `json:"audio_tokens"`
}

type QueryCost struct {
	CreatedAt time.Time `json:"created_at"`
	CostUSD   float64   `json:"cost_usd"`
	// MessageTrigger points at the most recent user message at the time
	// of the query cost
	MessageTrigger int    `json:"current_index"`
	Model          string `json:"model,omitempty"`
	Usage          Usage  `json:"usage"`
}

type ReasoningItem struct {
	ID               string   `json:"id"`
	EncryptedContent string   `json:"encrypted_content"`
	Summary          []string `json:"summary,omitempty"`
}

type ResponseFormat struct {
	// Type of response format: "text", "json_object", or "json_schema".
	Type string
	// Schema is used when Type is "json_schema".
	Schema *JSONSchema
}

type Specification struct {
	// Name of the tool. Prefer snake_case names
	Name string `json:"name"`
	// Description of the tool. This will be sent to the LLM. Simple instructions on how to use the tool is suitable here
	Description string `json:"description,omitempty"`
	// Inputs for the tool. Describe the inputs and how to use them. This will be sent to the LLM.
	Inputs *InputSchema `json:"input_schema,omitempty"`
	// Arguments which may be left unfilled. This field is requirement by ChatGPT
	Arguments string `json:"arguments,omitempty"`
}

type ToolCall struct {
	Name       string
	StartedAt  time.Time
	FinishedAt time.Time
	Err        error
}

type ToolCallRecorder interface {
	RecordToolCall(context.Context, ToolCall) error
}

type ToolName string

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`

	PromptTokensDetails     PromptTokensDetails     `json:"prompt_tokens_details"`
	CompletionTokensDetails CompletionTokensDetails `json:"completion_tokens_details"`
}