Add docstring caveats on config API stability

Author: ncoghlan

src/lmstudio/async_api.py

@@ -502,7 +502,10 @@ async def load_new_instance(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TAsyncModelHandle:
-        """Load this model with the given identifier and configuration."""
+        """Load this model with the given identifier and configuration.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         handle: TAsyncModelHandle = await self._session._load_new_instance(
             self.model_key, instance_identifier, ttl, config, on_load_progress
         )
@@ -516,6 +519,11 @@ async def model(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TAsyncModelHandle:
+        """Retrieve model with given identifier, or load it with given configuration.
+
+        Note: configuration of retrieved model is NOT checked against the given config.
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         # Call _get_or_load directly, since we have a model identifier
         handle: TAsyncModelHandle = await self._session._get_or_load(
             self.model_key, ttl, config, on_load_progress
@@ -786,7 +794,11 @@ async def model(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TAsyncModelHandle:
-        """Get a handle to the specified model (loading it if necessary)."""
+        """Get a handle to the specified model (loading it if necessary).
+
+        Note: configuration of retrieved model is NOT checked against the given config.
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         if model_key is None:
             # Should this raise an error if a config is supplied?
             return await self._get_any()
@@ -816,7 +828,10 @@ async def load_new_instance(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TAsyncModelHandle:
-        """Load the specified model with the given identifier and configuration."""
+        """Load the specified model with the given identifier and configuration.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         return await self._load_new_instance(
             model_key, instance_identifier, ttl, config, on_load_progress
         )
@@ -1033,7 +1048,10 @@ async def _complete_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> AsyncPredictionStream[str] | AsyncPredictionStream[DictObject]:
-        """Request a one-off prediction without any context and stream the generated tokens."""
+        """Request a one-off prediction without any context and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         endpoint = CompletionEndpoint(
             model_specifier,
             prompt,
@@ -1086,7 +1104,10 @@ async def _respond_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> AsyncPredictionStream[str] | AsyncPredictionStream[DictObject]:
-        """Request a response in an ongoing assistant chat session and stream the generated tokens."""
+        """Request a response in an ongoing assistant chat session and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         if not isinstance(history, Chat):
             history = Chat.from_history(history)
         endpoint = ChatResponseEndpoint(
@@ -1256,7 +1277,10 @@ async def complete_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> AsyncPredictionStream[str] | AsyncPredictionStream[DictObject]:
-        """Request a one-off prediction without any context and stream the generated tokens."""
+        """Request a one-off prediction without any context and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         return await self._session._complete_stream(
             self.identifier,
             prompt,
@@ -1304,7 +1328,10 @@ async def complete(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionResult[str] | PredictionResult[DictObject]:
-        """Request a one-off prediction without any context."""
+        """Request a one-off prediction without any context.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         prediction_stream = await self._session._complete_stream(
             self.identifier,
             prompt,
@@ -1357,7 +1384,10 @@ async def respond_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> AsyncPredictionStream[str] | AsyncPredictionStream[DictObject]:
-        """Request a response in an ongoing assistant chat session and stream the generated tokens."""
+        """Request a response in an ongoing assistant chat session and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         return await self._session._respond_stream(
             self.identifier,
             history,
@@ -1405,7 +1435,10 @@ async def respond(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionResult[str] | PredictionResult[DictObject]:
-        """Request a response in an ongoing assistant chat session."""
+        """Request a response in an ongoing assistant chat session.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         prediction_stream = await self._session._respond_stream(
             self.identifier,
             history,

src/lmstudio/sync_api.py

@@ -690,7 +690,10 @@ def load_new_instance(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TModelHandle:
-        """Load this model with the given identifier and configuration."""
+        """Load this model with the given identifier and configuration.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         handle: TModelHandle = self._session._load_new_instance(
             self.model_key, instance_identifier, ttl, config, on_load_progress
         )
@@ -704,6 +707,11 @@ def model(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TModelHandle:
+        """Retrieve model with default identifier, or load it with given configuration.
+
+        Note: configuration of retrieved model is NOT checked against the given config.
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         # Call _get_or_load directly, since we have a model identifier
         handle: TModelHandle = self._session._get_or_load(
             self.model_key, ttl, config, on_load_progress
@@ -951,7 +959,11 @@ def model(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TModelHandle:
-        """Get a handle to the specified model (loading it if necessary)."""
+        """Get a handle to the specified model (loading it if necessary).
+
+        Note: configuration of retrieved model is NOT checked against the given config.
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         if model_key is None:
             # Should this raise an error if a config is supplied?
             return self._get_any()
@@ -981,7 +993,10 @@ def load_new_instance(
         config: TLoadConfig | TLoadConfigDict | None = None,
         on_load_progress: ModelLoadingCallback | None = None,
     ) -> TModelHandle:
-        """Load the specified model with the given identifier and configuration."""
+        """Load the specified model with the given identifier and configuration.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         return self._load_new_instance(
             model_key, instance_identifier, ttl, config, on_load_progress
         )
@@ -1198,7 +1213,10 @@ def _complete_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionStream[str] | PredictionStream[DictObject]:
-        """Request a one-off prediction without any context and stream the generated tokens."""
+        """Request a one-off prediction without any context and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         endpoint = CompletionEndpoint(
             model_specifier,
             prompt,
@@ -1251,7 +1269,10 @@ def _respond_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionStream[str] | PredictionStream[DictObject]:
-        """Request a response in an ongoing assistant chat session and stream the generated tokens."""
+        """Request a response in an ongoing assistant chat session and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         if not isinstance(history, Chat):
             history = Chat.from_history(history)
         endpoint = ChatResponseEndpoint(
@@ -1417,7 +1438,10 @@ def complete_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionStream[str] | PredictionStream[DictObject]:
-        """Request a one-off prediction without any context and stream the generated tokens."""
+        """Request a one-off prediction without any context and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         return self._session._complete_stream(
             self.identifier,
             prompt,
@@ -1465,7 +1489,10 @@ def complete(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionResult[str] | PredictionResult[DictObject]:
-        """Request a one-off prediction without any context."""
+        """Request a one-off prediction without any context.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         prediction_stream = self._session._complete_stream(
             self.identifier,
             prompt,
@@ -1518,7 +1545,10 @@ def respond_stream(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionStream[str] | PredictionStream[DictObject]:
-        """Request a response in an ongoing assistant chat session and stream the generated tokens."""
+        """Request a response in an ongoing assistant chat session and stream the generated tokens.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         return self._session._respond_stream(
             self.identifier,
             history,
@@ -1566,7 +1596,10 @@ def respond(
         on_prediction_fragment: PredictionFragmentCallback | None = None,
         on_prompt_processing_progress: PromptProcessingCallback | None = None,
     ) -> PredictionResult[str] | PredictionResult[DictObject]:
-        """Request a response in an ongoing assistant chat session."""
+        """Request a response in an ongoing assistant chat session.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         prediction_stream = self._session._respond_stream(
             self.identifier,
             history,
@@ -1608,7 +1641,10 @@ def act(
         ]
         | None = None,
     ) -> ActResult:
-        """Request a response (with implicit tool use) in an ongoing agent chat session."""
+        """Request a response (with implicit tool use) in an ongoing agent chat session.
+
+        Note: details of configuration fields may change in SDK feature releases.
+        """
         start_time = time.perf_counter()
         # It is not yet possible to combine tool calling with requests for structured responses
         response_format = None
@@ -1920,7 +1956,11 @@ def llm(
     ttl: int | None = DEFAULT_TTL,
     config: LlmLoadModelConfig | LlmLoadModelConfigDict | None = None,
 ) -> LLM:
-    """Access an LLM using the default global client."""
+    """Access an LLM using the default global client.
+
+    Note: configuration of retrieved model is NOT checked against the given config.
+    Note: details of configuration fields may change in SDK feature releases.
+    """
     return get_default_client().llm.model(model_key, ttl=ttl, config=config)
 
 
@@ -1932,7 +1972,11 @@ def embedding_model(
     ttl: int | None = DEFAULT_TTL,
     config: EmbeddingLoadModelConfig | EmbeddingLoadModelConfigDict | None = None,
 ) -> EmbeddingModel:
-    """Access an embedding model using the default global client."""
+    """Access an embedding model using the default global client.
+
+    Note: configuration of retrieved model is NOT checked against the given config.
+    Note: details of configuration fields may change in SDK feature releases.
+    """
     return get_default_client().embedding.model(model_key, ttl=ttl, config=config)