Skip to content

Commit 82710b4

Browse files
steipetesteipete
committed
docs: document lmstudio runtime contracts
1 parent d23558e commit 82710b4

1 file changed

Lines changed: 27 additions & 0 deletions

File tree

‎src/plugin-sdk/lmstudio-runtime.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ type LmstudioReasoningCapabilityWire = {
1414
default?: unknown;
1515
};
1616

17+
/** Raw model entry returned by LM Studio's local model catalog endpoints. */
1718
export type LmstudioModelWire = {
1819
type?: "llm" | "embedding";
1920
key?: string;
@@ -33,6 +34,7 @@ export type LmstudioModelWire = {
3334
} | null>;
3435
};
3536

37+
/** Normalized model metadata used by OpenClaw provider catalogs. */
3638
export type LmstudioModelBase = {
3739
id: string;
3840
displayName: string;
@@ -48,6 +50,7 @@ export type LmstudioModelBase = {
4850
maxTokens: number;
4951
};
5052

53+
/** Result from probing LM Studio model discovery without throwing on unreachable servers. */
5154
export type FetchLmstudioModelsResult = {
5255
reachable: boolean;
5356
status?: number;
@@ -130,48 +133,72 @@ function loadFacadeModule(): FacadeModule {
130133

131134
// Keep defaults inline so importing the runtime facade stays cold until a helper
132135
// is actually used. These values are part of the public LM Studio contract.
136+
/** Default local LM Studio server base URL. */
133137
export const LMSTUDIO_DEFAULT_BASE_URL: FacadeModule["LMSTUDIO_DEFAULT_BASE_URL"] =
134138
"http://localhost:1234";
139+
/** Default OpenAI-compatible inference base derived from the local LM Studio server URL. */
135140
export const LMSTUDIO_DEFAULT_INFERENCE_BASE_URL: FacadeModule["LMSTUDIO_DEFAULT_INFERENCE_BASE_URL"] = `${LMSTUDIO_DEFAULT_BASE_URL}/v1`;
141+
/** Default embedding model id advertised by LM Studio setup helpers. */
136142
export const LMSTUDIO_DEFAULT_EMBEDDING_MODEL: FacadeModule["LMSTUDIO_DEFAULT_EMBEDDING_MODEL"] =
137143
"text-embedding-nomic-embed-text-v1.5";
144+
/** Human-readable provider label for LM Studio catalogs and setup output. */
138145
export const LMSTUDIO_PROVIDER_LABEL: FacadeModule["LMSTUDIO_PROVIDER_LABEL"] = "LM Studio";
146+
/** Environment variable checked for LM Studio API tokens. */
139147
export const LMSTUDIO_DEFAULT_API_KEY_ENV_VAR: FacadeModule["LMSTUDIO_DEFAULT_API_KEY_ENV_VAR"] =
140148
"LM_API_TOKEN";
149+
/** Placeholder token used for local LM Studio servers that accept any API key. */
141150
export const LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER: FacadeModule["LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER"] =
142151
"lmstudio-local";
152+
/** Placeholder model id shown when setup needs a model from `/api/v1/models`. */
143153
export const LMSTUDIO_MODEL_PLACEHOLDER: FacadeModule["LMSTUDIO_MODEL_PLACEHOLDER"] =
144154
"model-key-from-api-v1-models";
155+
/** Default context length requested when loading LM Studio models. */
145156
export const LMSTUDIO_DEFAULT_LOAD_CONTEXT_LENGTH: FacadeModule["LMSTUDIO_DEFAULT_LOAD_CONTEXT_LENGTH"] = 64000;
157+
/** Default chat model id used when no local LM Studio model has been selected. */
146158
export const LMSTUDIO_DEFAULT_MODEL_ID: FacadeModule["LMSTUDIO_DEFAULT_MODEL_ID"] =
147159
"qwen/qwen3.5-9b";
160+
/** Stable provider id used in OpenClaw config and provider catalogs. */
148161
export const LMSTUDIO_PROVIDER_ID: FacadeModule["LMSTUDIO_PROVIDER_ID"] = "lmstudio";
149162

163+
/** Resolve whether an LM Studio wire entry advertises reasoning support. */
150164
export const resolveLmstudioReasoningCapability: FacadeModule["resolveLmstudioReasoningCapability"] =
151165
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioReasoningCapability");
166+
/** Resolve context-window metadata from currently loaded LM Studio instances. */
152167
export const resolveLoadedContextWindow: FacadeModule["resolveLoadedContextWindow"] =
153168
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLoadedContextWindow");
169+
/** Normalize a configured LM Studio server base URL. */
154170
export const resolveLmstudioServerBase: FacadeModule["resolveLmstudioServerBase"] =
155171
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioServerBase");
172+
/** Normalize the OpenAI-compatible LM Studio inference base URL. */
156173
export const resolveLmstudioInferenceBase: FacadeModule["resolveLmstudioInferenceBase"] =
157174
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioInferenceBase");
175+
/** Normalize an LM Studio provider config before runtime use. */
158176
export const normalizeLmstudioProviderConfig: FacadeModule["normalizeLmstudioProviderConfig"] =
159177
createLazyFacadeRuntimeValue(loadFacadeModule, "normalizeLmstudioProviderConfig");
178+
/** Fetch raw LM Studio model entries with SSRF and timeout handling owned by the facade. */
160179
export const fetchLmstudioModels: FacadeModule["fetchLmstudioModels"] =
161180
createLazyFacadeRuntimeValue(loadFacadeModule, "fetchLmstudioModels");
181+
/** Map one raw LM Studio model entry into OpenClaw model metadata. */
162182
export const mapLmstudioWireEntry: FacadeModule["mapLmstudioWireEntry"] =
163183
createLazyFacadeRuntimeValue(loadFacadeModule, "mapLmstudioWireEntry");
184+
/** Discover OpenClaw model definitions from an LM Studio server. */
164185
export const discoverLmstudioModels: FacadeModule["discoverLmstudioModels"] =
165186
createLazyFacadeRuntimeValue(loadFacadeModule, "discoverLmstudioModels");
187+
/** Ensure a specific LM Studio model is loaded before use. */
166188
export const ensureLmstudioModelLoaded: FacadeModule["ensureLmstudioModelLoaded"] =
167189
createLazyFacadeRuntimeValue(loadFacadeModule, "ensureLmstudioModelLoaded");
190+
/** Build request headers for LM Studio calls from optional API key and caller headers. */
168191
export const buildLmstudioAuthHeaders: FacadeModule["buildLmstudioAuthHeaders"] =
169192
createLazyFacadeRuntimeValue(loadFacadeModule, "buildLmstudioAuthHeaders");
193+
/** Resolve the configured LM Studio API key from config, env, or profile path. */
170194
export const resolveLmstudioConfiguredApiKey: FacadeModule["resolveLmstudioConfiguredApiKey"] =
171195
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioConfiguredApiKey");
196+
/** Resolve provider headers for LM Studio catalog and runtime requests. */
172197
export const resolveLmstudioProviderHeaders: FacadeModule["resolveLmstudioProviderHeaders"] =
173198
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioProviderHeaders");
199+
/** Resolve the combined API key and headers used for LM Studio requests. */
174200
export const resolveLmstudioRequestContext: FacadeModule["resolveLmstudioRequestContext"] =
175201
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioRequestContext");
202+
/** Resolve the runtime API key for an agent-scoped LM Studio request. */
176203
export const resolveLmstudioRuntimeApiKey: FacadeModule["resolveLmstudioRuntimeApiKey"] =
177204
createLazyFacadeRuntimeValue(loadFacadeModule, "resolveLmstudioRuntimeApiKey");

0 commit comments

Comments
 (0)