constants.go

package blmstudio

import "time"

// ── Base configuration ────────────────────────────────────────────────────────

const (
	// DefaultBaseURL is the default LM Studio server address.
	DefaultBaseURL = "http://localhost:1234"

	// DefaultPort is the default LM Studio server port.
	DefaultPort = 1234

	// DefaultTimeout is the default HTTP client timeout.
	// Generous to accommodate large model loading times.
	DefaultTimeout = 5 * time.Minute
)

// ── API path prefixes ─────────────────────────────────────────────────────────

const (
	// NativeAPIPrefix is the path prefix for the LM Studio native REST API.
	NativeAPIPrefix = "/api/v1"

	// OpenAIAPIPrefix is the path prefix for the OpenAI-compatible REST API.
	OpenAIAPIPrefix = "/v1"
)

// ── Native API endpoint paths (/api/v1/*) ─────────────────────────────────────

const (
	// PathChat is POST /api/v1/chat — native chat endpoint (text + images).
	PathChat = NativeAPIPrefix + "/chat"

	// PathModels is GET /api/v1/models — list all known models with metadata.
	PathModels = NativeAPIPrefix + "/models"

	// PathModelsLoad is POST /api/v1/models/load — load a model into memory.
	PathModelsLoad = NativeAPIPrefix + "/models/load"

	// PathModelsUnload is POST /api/v1/models/unload — unload a model instance.
	PathModelsUnload = NativeAPIPrefix + "/models/unload"

	// PathModelsDownload is POST /api/v1/models/download — start a model download.
	PathModelsDownload = NativeAPIPrefix + "/models/download"

	// PathModelsDownloadStatus is GET /api/v1/models/download/status/{job_id}.
	// Append the job ID when constructing the full URL.
	PathModelsDownloadStatus = NativeAPIPrefix + "/models/download/status/"
)

// ── OpenAI-compatible endpoint paths (/v1/*) ──────────────────────────────────

const (
	// PathOpenAIModels is GET /v1/models — list models in OpenAI format.
	PathOpenAIModels = OpenAIAPIPrefix + "/models"

	// PathOpenAIChatCompletions is POST /v1/chat/completions.
	PathOpenAIChatCompletions = OpenAIAPIPrefix + "/chat/completions"

	// PathOpenAICompletions is POST /v1/completions — legacy text completions.
	PathOpenAICompletions = OpenAIAPIPrefix + "/completions"

	// PathOpenAIEmbeddings is POST /v1/embeddings.
	PathOpenAIEmbeddings = OpenAIAPIPrefix + "/embeddings"

	// PathOpenAIResponses is POST /v1/responses — OpenAI Responses API.
	PathOpenAIResponses = OpenAIAPIPrefix + "/responses"
)

// ── HTTP header names and values ──────────────────────────────────────────────

const (
	headerAuthorization = "Authorization"
	headerContentType   = "Content-Type"
	headerAccept        = "Accept"

	contentTypeJSON        = "application/json"
	contentTypeEventStream = "text/event-stream"
)

// ── Model types ───────────────────────────────────────────────────────────────

const (
	// ModelTypeLLM identifies a large language model.
	ModelTypeLLM = "llm"

	// ModelTypeEmbedding identifies an embedding model.
	ModelTypeEmbedding = "embedding"
)

// ── Message roles ─────────────────────────────────────────────────────────────

const (
	// RoleSystem is the system prompt role.
	RoleSystem = "system"

	// RoleUser is the end-user message role.
	RoleUser = "user"

	// RoleAssistant is the model response role.
	RoleAssistant = "assistant"

	// RoleTool is the tool (function) response role.
	RoleTool = "tool"
)

// ── Finish reasons ────────────────────────────────────────────────────────────

const (
	// FinishReasonStop means the model reached a natural stopping point.
	FinishReasonStop = "stop"

	// FinishReasonLength means the maximum token count was reached.
	FinishReasonLength = "length"

	// FinishReasonToolCalls means the model generated tool call(s).
	FinishReasonToolCalls = "tool_calls"

	// FinishReasonContentFilter means the output was filtered.
	FinishReasonContentFilter = "content_filter"
)

// ── Native chat input item types ──────────────────────────────────────────────

const (
	// InputItemTypeMessage is used for text message input items.
	InputItemTypeMessage = "message"

	// InputItemTypeImage is used for base64-encoded image input items.
	InputItemTypeImage = "image"
)

// ── Native streaming event types (/api/v1/chat with stream: true) ─────────────

const (
	// StreamEventChatStart is the first SSE event of a native streaming chat.
	StreamEventChatStart = "chat.start"

	// StreamEventChatDelta carries an incremental text fragment.
	StreamEventChatDelta = "chat.delta"

	// StreamEventChatEnd is the final SSE event containing the full output.
	StreamEventChatEnd = "chat.end"
)

// ── SSE parsing tokens ────────────────────────────────────────────────────────

const (
	sseDataPrefix  = "data: "
	sseEventPrefix = "event: "
	sseDone        = "[DONE]"
)

// ── Response format types ─────────────────────────────────────────────────────

const (
	// ResponseFormatText requests plain text output (default).
	ResponseFormatText = "text"

	// ResponseFormatJSONObject requests unstructured JSON output.
	ResponseFormatJSONObject = "json_object"

	// ResponseFormatJSONSchema requests JSON output validated against a schema.
	ResponseFormatJSONSchema = "json_schema"
)

// ── Tool choice string constants ──────────────────────────────────────────────

const (
	// ToolChoiceNone instructs the model not to call any tools.
	ToolChoiceNone = "none"

	// ToolChoiceAuto lets the model decide whether to call a tool.
	ToolChoiceAuto = "auto"

	// ToolChoiceRequired forces the model to call at least one tool.
	ToolChoiceRequired = "required"
)

// ── Tool types ────────────────────────────────────────────────────────────────

const (
	// ToolTypeFunction is the only supported tool type.
	ToolTypeFunction = "function"
)

// ── Embedding encoding formats ────────────────────────────────────────────────

const (
	// EncodingFormatFloat returns embeddings as arrays of float64 (default).
	EncodingFormatFloat = "float"

	// EncodingFormatBase64 returns embeddings as base64-encoded strings.
	EncodingFormatBase64 = "base64"
)