transport

type ActiveModel struct {
	ModelName  string `json:"model_name,omitempty"`
	Type       string `json:"type,omitempty"`
	Digest     string `json:"digest,omitempty"`
	Path       string `json:"path,omitempty"`
	Config     Config `json:"config"`
	Generation uint64 `json:"generation"`
}

type Config struct {
	NumCtx       int       // context window in tokens
	NumBatch     int       // prefill batch size
	NumThreads   int       // CPU threads (0 = NumCPU)
	NumGpuLayers int       // layers offloaded to the GPU (0 = CPU only)
	TensorSplit  []float32 // multi-GPU split
	FlashAttn    bool
	KVCacheType  string // "", "q8_0", "q4_0"

	PromptFormat         string // profile-declared prompt format, e.g. "chatml" or "llama3"
	PromptTemplateDigest string // digest of the declared/rendered prompt template
	DisableBOS           bool
	ReasoningFormat      string // backend-native reasoning format for chat-template parsing/rendering
}

type ContextManifest = contextasm.ContextManifest

type ContextReport struct {
	ResidentTokens  int
	PrefixTokens    int
	NumCtx          int
	AvailableTokens int
	StableByteHash  string
	StableTokenHash string
	ManifestDigest  string
	Manifest        ContextManifest
	Closed          bool
}

type DaemonStatus struct {
	OwnerInstanceID string       `json:"owner_instance_id,omitempty"`
	Backend         string       `json:"backend,omitempty"`
	State           SlotState    `json:"state,omitempty"`
	Active          *ActiveModel `json:"active,omitempty"`
	BusyOperation   string       `json:"busy_operation,omitempty"`
	LastError       string       `json:"last_error,omitempty"`
}

type DecodeConfig struct {
	MaxTokens        int
	Temperature      *float64
	TopP             *float64
	TopK             int
	Seed             *int
	ParserProtocols  []string
	ReasoningFormat  string
	StructuredOutput StructuredOutputConfig
}

type DeviceInfo struct {
	Index       int    `json:"index"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Type        string `json:"type,omitempty"`
	MemoryFree  int64  `json:"memory_free,omitempty"`
	MemoryTotal int64  `json:"memory_total,omitempty"`
}

type EmbedRequest struct {
	Fence
	ModelName string // logical model name, e.g. "bge-small-en"
	Type      string // backend type the model targets: "llama" | "openvino"
	Digest    string // content digest; part of the model identity
	Path      string // runtime-resolved filesystem location (GGUF file or IR dir)
	Config    Config
	Text      string
}

type EmbedResult struct {
	Vector []float32 `json:"vector,omitempty"`
}

type Fence struct {
	OwnerInstanceID string
}

type LoadModelRequest struct {
	Fence
	ModelName string
	Type      string
	Digest    string
	Path      string
	Config    Config
	// ExpectedGeneration, when non-zero, makes load/switch conditional on the
	// caller's view of the active slot.
	ExpectedGeneration uint64
}

type MemoryService struct {
	// contains filtered or unexported fields
}

type ModelController interface {
	Status(ctx context.Context) (DaemonStatus, error)
	LoadModel(ctx context.Context, req LoadModelRequest) (ActiveModel, error)
	UnloadModel(ctx context.Context, req UnloadModelRequest) error
}

type ModelInfo struct {
	ModelMaxContext  int   `json:"model_max_context"`
	EffectiveContext int   `json:"effective_context"`
	KVBytesPerToken  int64 `json:"kv_bytes_per_token,omitempty"`
	FreeBytes        int64 `json:"free_bytes,omitempty"`
	WeightsBytes     int64 `json:"weights_bytes,omitempty"`
	OverheadBytes    int64 `json:"overhead_bytes,omitempty"`
	ReservedBytes    int64 `json:"reserved_bytes,omitempty"`
	UserLimitBytes   int64 `json:"user_limit_bytes,omitempty"`
	MinFreeBytes     int64 `json:"min_free_bytes,omitempty"`
	UsableBytes      int64 `json:"usable_bytes,omitempty"`
	RequiredBytes    int64 `json:"required_bytes,omitempty"`
	Clamped          bool  `json:"clamped,omitempty"`
	// Reason explains why EffectiveContext was lower than the requested or model
	// dense context. It is telemetry/debug text, not a stable API enum yet.
	Reason string `json:"reason,omitempty"`
	// DeviceKind/DeviceID identify the memory pool modeld used for the capacity
	// decision. Physical hot context is separate from future planner-level
	// effective context, which may exceed the model's dense trained window.
	DeviceKind        string `json:"device_kind,omitempty"`
	DeviceID          string `json:"device_id,omitempty"`
	DeviceTotalBytes  int64  `json:"device_total_bytes,omitempty"`
	SharedWithDisplay bool   `json:"shared_with_display,omitempty"`

	// RequestedGpuLayers is what the profile/env asked for. ResolvedGpuLayers is
	// what modeld will actually open after applying the device memory budget.
	RequestedGpuLayers int `json:"requested_gpu_layers,omitempty"`
	ResolvedGpuLayers  int `json:"resolved_gpu_layers,omitempty"`

	// Runtime identity and device inventory explain which native runtime modeld
	// actually linked and what memory pools it can allocate from.
	RuntimeName        string       `json:"runtime_name,omitempty"`
	RuntimeDigest      string       `json:"runtime_digest,omitempty"`
	RuntimeSystemInfo  string       `json:"runtime_system_info,omitempty"`
	SupportsGPUOffload bool         `json:"supports_gpu_offload,omitempty"`
	Devices            []DeviceInfo `json:"devices,omitempty"`
}

type OpenSessionRequest struct {
	Fence
	ModelName string // logical model name, e.g. "qwen2.5-1.5b"
	Type      string // backend type the model targets: "llama" | "openvino"
	Digest    string // content digest; part of the cache identity
	Path      string // runtime-resolved filesystem location (GGUF file or IR dir)
	Config    Config
}

type Option func(*MemoryService)

type PrefixInput struct {
	Text     string
	Manifest ContextManifest
	// Tools is a JSON array of tool definitions to render into the prompt via the
	// model's own GGUF chat template (model-native tool calls). "" means no tools.
	// The daemon renders it; the runtime never sees the model's tool format.
	Tools string `json:",omitempty"`
}

type PrefixStatus struct {
	ReusedTokens    int
	PrefilledTokens int
	DroppedTokens   int
	PrefixTokens    int
	ResidentTokens  int
	AvailableTokens int
	StableByteHash  string
	StableTokenHash string
	ManifestDigest  string
}

type Service interface {
	OpenSession(ctx context.Context, req OpenSessionRequest) (Session, error)
	// Describe reports a model's capabilities from its on-disk metadata. The
	// daemon is the authority because it owns the model format and hardware;
	// Config carries the requested context/runtime knobs for capacity planning.
	Describe(ctx context.Context, req OpenSessionRequest) (ModelInfo, error)
	// Embed computes a one-shot embedding for a model. It uses the same typed
	// handle and owner fence as Describe, but does not create a persistent decode
	// session because embedding pipelines do not participate in KV reuse.
	Embed(ctx context.Context, req EmbedRequest) (EmbedResult, error)
}

type Session interface {
	// EnsurePrefix makes the resident KV equal `prefix`, reusing the longest
	// already-resident matching prefix and prefilling only the divergent tail
	// (this also drops any previous suffix and generated tokens).
	EnsurePrefix(ctx context.Context, prefix PrefixInput) (PrefixStatus, error)

	// PrefillSuffix prefills the volatile suffix (diff / test output / user
	// turn) after the stable prefix, leaving the stable KV untouched.
	PrefillSuffix(ctx context.Context, suffix SuffixInput) (SuffixStatus, error)

	// Decode streams generated text from the current resident state.
	Decode(ctx context.Context, cfg DecodeConfig) (<-chan StreamChunk, error)

	// ExplainContext reports the resident context for observability.
	ExplainContext() ContextReport

	// Snapshot captures backend state for durability/branching. State is opaque
	// backend data; the manifest and bookkeeping fields are the compatibility
	// gate needed before Restore may trust it.
	Snapshot(ctx context.Context) (SessionSnapshot, error)

	// Restore replaces the resident session state from a compatible snapshot.
	Restore(ctx context.Context, snap SessionSnapshot) error

	// Close releases the session's resources.
	Close() error
}

type SessionSnapshot struct {
	State            []byte          `json:"state,omitempty"`
	ResidentTokens   int             `json:"resident_tokens,omitempty"`
	PrefixTokens     int             `json:"prefix_tokens,omitempty"`
	NumCtx           int             `json:"num_ctx,omitempty"`
	ResidentTokenIDs []int           `json:"resident_token_ids,omitempty"`
	StableText       string          `json:"stable_text,omitempty"`
	PrefixText       string          `json:"prefix_text,omitempty"`
	Tools            string          `json:"tools,omitempty"`
	Manifest         ContextManifest `json:"manifest"`
}

type SlotState string

type StreamChunk struct {
	Text      string
	Thinking  string
	ToolCalls []ToolCall
	Error     error
}

type StructuredOutputConfig struct {
	Protocol string
	Payload  string
	ToolName string
}

type SuffixInput struct {
	Text     string
	Manifest ContextManifest
	// EnableThinking controls model-owned chat-template rendering for the
	// assistant generation prompt when a backend supports it. nil means backend
	// default.
	EnableThinking *bool `json:",omitempty"`
}

type SuffixStatus struct {
	SuffixTokens    int
	PrefixTokens    int
	ResidentTokens  int
	AvailableTokens int
	ManifestDigest  string
}

type ToolCall struct {
	ID       string `json:"id,omitempty"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type UnloadModelRequest struct {
	Fence
	ExpectedGeneration uint64
}