client

type App struct {
	OrgID        string
	Name         string
	DisplayName  string
	SystemPrompt string
	DefaultModel string
	// Tools advertises functions the model may call inside this app.
	Tools []Tool
	// MemoryEnabled — true to bind a memory store at MemoryKey scope.
	MemoryEnabled bool
	UpdatedAt     time.Time
}

type Chat struct {
	ID        string
	OrgID     string
	UserID    string
	AppName   string
	Title     string
	Messages  []Message
	CreatedAt time.Time
	UpdatedAt time.Time
	Pinned    bool
	Archived  bool
}

type ChatSummary struct {
	ID           string
	Title        string
	AppName      string
	UpdatedAt    time.Time
	Pinned       bool
	MessageCount int
}

type Cloud interface {
	// Kind reports the backend identifier (hanzo-cloud).
	Kind() string

	// Complete runs a non-streaming chat completion against the named
	// model. Mirrors the gateway shape but is routed through cloud's
	// app-aware enrichment (per-app prompt prelude, tool registration,
	// memory store).
	Complete(ctx context.Context, req CompletionRequest) (*CompletionResult, error)

	// Stream runs a streaming completion. SSE JSON chunks.
	Stream(ctx context.Context, req CompletionRequest) (io.ReadCloser, error)

	// Embed produces embedding vectors.
	Embed(ctx context.Context, req EmbedRequest) (*EmbedResult, error)

	// ListModels returns the model registry visible to the caller's
	// org. Org-level enablement gates the visible set.
	ListModels(ctx context.Context, orgID string) ([]Model, error)

	// SaveChat persists a conversation. Returns the canonical chat id.
	SaveChat(ctx context.Context, chat Chat) (string, error)

	// GetChat returns a saved chat by id.
	GetChat(ctx context.Context, orgID, chatID string) (*Chat, error)

	// ListChats returns the user's chat history. Newest first.
	ListChats(ctx context.Context, orgID, userID string, opts ListOpts) ([]ChatSummary, error)

	// DeleteChat removes a saved chat. Idempotent.
	DeleteChat(ctx context.Context, orgID, chatID string) error

	// UpsertApp registers a chat app (system prompt, tool registry,
	// memory binding, model defaults) keyed by name+org.
	UpsertApp(ctx context.Context, app App) error

	// ListApps returns the apps visible to the caller's org.
	ListApps(ctx context.Context, orgID string) ([]App, error)

	// GetUsage returns the org's usage summary for a time window.
	GetUsage(ctx context.Context, orgID string, since, until time.Time) (*Usage, error)
}

type CompletionRequest struct {
	OrgID, UserID string
	// AppName selects the chat-app (system prompt + tool registry +
	// model default); empty selects the org's default app.
	AppName     string
	Model       string // optional override of the app's default model
	Messages    []Message
	MaxTokens   int
	Temperature float64
	JSONMode    bool
	// MemoryKey ties this turn to a persistent memory store. Empty
	// disables memory for this call.
	MemoryKey string
	// Extra carries backend-specific knobs (system_prompt_cache, seed,
	// top_k).
	Extra map[string]any
}

type CompletionResult struct {
	ChatID       string // populated when the call persisted to a chat
	Message      Message
	FinishReason string
	UsageDelta   Usage
	ModelUsed    string
}

type EmbedRequest struct {
	OrgID, UserID string
	Model         string
	Inputs        []string
}

type EmbedResult struct {
	Vectors    [][]float32
	Model      string
	UsageDelta Usage
}

type ListOpts struct {
	Page               int
	PerPage            int
	IncludeArchived    bool
	IncludePinnedFirst bool
}

type Message struct {
	Role       string
	Content    string
	Name       string
	ToolCallID string
	ToolCalls  []ToolCall
}

type Model struct {
	ID                    string
	Provider              string
	ContextSize           int
	Capabilities          []string // chat | embed | vision | tool_use | json | streaming
	PriceInUSDPerMillion  float64
	PriceOutUSDPerMillion float64
	// Enabled — true when the model is enabled for the caller's org.
	Enabled bool
}

type Tool struct {
	Name        string
	Description string
	Parameters  map[string]any // JSON Schema
}

type ToolCall struct {
	ID        string
	Name      string
	Arguments string // JSON string
}

type Usage struct {
	OrgID            string
	From, To         time.Time
	PromptTokens     int64
	CompletionTokens int64
	EmbeddingTokens  int64
	PriceUSD         float64
	// PerModel — breakdown by model id.
	PerModel map[string]Usage
}