lmstd 0.1.0__tar.gz → 0.2.0__tar.gz

{lmstd-0.1.0 → lmstd-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 LM Studio User
+Copyright (c) 2026 EMuVi (emuvi@outlook.com.br)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{lmstd-0.1.0 → lmstd-0.2.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: lmstd
-Version: 0.1.0
+Version: 0.2.0
 Summary: LM Studio v1 REST API Client Library
 Author: LM Studio User
-License: MIT
+License-Expression: MIT
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -51,4 +51,6 @@ print(models)
 
 ## License
 
-MIT License
+Copyright (c) 2026 EMuVi (emuvi@outlook.com.br)
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{lmstd-0.1.0 → lmstd-0.2.0}/README.md

@@ -39,4 +39,6 @@ print(models)
 
 ## License
 
-MIT License
+Copyright (c) 2026 EMuVi (emuvi@outlook.com.br)
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{lmstd-0.1.0 → lmstd-0.2.0}/lmstd.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: lmstd
-Version: 0.1.0
+Version: 0.2.0
 Summary: LM Studio v1 REST API Client Library
 Author: LM Studio User
-License: MIT
+License-Expression: MIT
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -51,4 +51,6 @@ print(models)
 
 ## License
 
-MIT License
+Copyright (c) 2026 EMuVi (emuvi@outlook.com.br)
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

lmstd-0.2.0/lmstd.py

@@ -0,0 +1,612 @@
+# Copyright (c) 2026 EMuVi (emuvi@outlook.com.br)
+# Licensed under the MIT License.
+
+"""
+LM Studio v1 REST API Client Library
+
+This single-file library provides a clean, fully documented Python interface 
+to interact with an LM Studio local server based on the v1 REST API endpoints.
+
+Features supported natively via the v1 API:
+- Stateful chats 
+- Model Context Protocol (MCP) integrations via API 
+- Authentication configuration with API tokens 
+- Advanced model lifecycle management (download, load, unload) 
+
+Dependencies:
+    requests
+"""
+
+import json
+import os
+from typing import Any, Dict, Iterator, List, Optional, Union, Literal, TypedDict
+
+class TextInput(TypedDict):
+    type: Literal["message"]
+    content: str
+
+class ImageInput(TypedDict):
+    type: Literal["image"]
+    data_url: str
+
+InputItem = Union[TextInput, ImageInput]
+
+class PluginIntegrationBase(TypedDict):
+    type: Literal["plugin"]
+    id: str
+
+class PluginIntegration(PluginIntegrationBase, total=False):
+    allowed_tools: List[str]
+
+class EphemeralMCPIntegrationBase(TypedDict):
+    type: Literal["ephemeral_mcp"]
+    server_label: str
+    server_url: str
+
+class EphemeralMCPIntegration(EphemeralMCPIntegrationBase, total=False):
+    allowed_tools: List[str]
+
+Integration = Union[str, PluginIntegration, EphemeralMCPIntegration]
+
+class ProviderInfoPlugin(TypedDict):
+    type: Literal["plugin"]
+    plugin_id: str
+
+class ProviderInfoEphemeralMCP(TypedDict):
+    type: Literal["ephemeral_mcp"]
+    server_label: str
+
+ProviderInfo = Union[ProviderInfoPlugin, ProviderInfoEphemeralMCP]
+
+class MessageOutput(TypedDict):
+    type: Literal["message"]
+    content: str
+
+class ToolCallOutput(TypedDict, total=False):
+    type: Literal["tool_call"]
+    tool: str
+    arguments: Dict[str, Any]
+    output: str
+    provider_info: ProviderInfo
+
+class ReasoningOutput(TypedDict):
+    type: Literal["reasoning"]
+    content: str
+
+class InvalidToolCallMetadata(TypedDict, total=False):
+    type: Literal["invalid_name", "invalid_arguments"]
+    tool_name: str
+    arguments: Dict[str, Any]
+    provider_info: ProviderInfo
+
+class InvalidToolCallOutput(TypedDict, total=False):
+    type: Literal["invalid_tool_call"]
+    reason: str
+    metadata: InvalidToolCallMetadata
+
+OutputItem = Union[MessageOutput, ToolCallOutput, ReasoningOutput, InvalidToolCallOutput]
+
+class ChatStats(TypedDict, total=False):
+    input_tokens: int
+    total_output_tokens: int
+    reasoning_output_tokens: int
+    tokens_per_second: float
+    time_to_first_token_seconds: float
+    model_load_time_seconds: float
+
+class ChatResponse(TypedDict, total=False):
+    model_instance_id: str
+    output: List[OutputItem]
+    stats: ChatStats
+    response_id: str
+
+class ChatStartEvent(TypedDict):
+    type: Literal["chat.start"]
+    model_instance_id: str
+
+class ModelLoadStartEvent(TypedDict):
+    type: Literal["model_load.start"]
+    model_instance_id: str
+
+class ModelLoadProgressEvent(TypedDict):
+    type: Literal["model_load.progress"]
+    model_instance_id: str
+    progress: float
+
+class ModelLoadEndEvent(TypedDict):
+    type: Literal["model_load.end"]
+    model_instance_id: str
+    load_time_seconds: float
+
+class PromptProcessingStartEvent(TypedDict):
+    type: Literal["prompt_processing.start"]
+
+class PromptProcessingProgressEvent(TypedDict):
+    type: Literal["prompt_processing.progress"]
+    progress: float
+
+class PromptProcessingEndEvent(TypedDict):
+    type: Literal["prompt_processing.end"]
+
+class ReasoningStartEvent(TypedDict):
+    type: Literal["reasoning.start"]
+
+class ReasoningDeltaEvent(TypedDict):
+    type: Literal["reasoning.delta"]
+    content: str
+
+class ReasoningEndEvent(TypedDict):
+    type: Literal["reasoning.end"]
+
+class ToolCallStartEvent(TypedDict):
+    type: Literal["tool_call.start"]
+    tool: str
+    provider_info: ProviderInfo
+
+class ToolCallArgumentsEvent(TypedDict):
+    type: Literal["tool_call.arguments"]
+    tool: str
+    arguments: Dict[str, Any]
+    provider_info: ProviderInfo
+
+class ToolCallSuccessEvent(TypedDict):
+    type: Literal["tool_call.success"]
+    tool: str
+    arguments: Dict[str, Any]
+    output: str
+    provider_info: ProviderInfo
+
+class ToolCallFailureEvent(TypedDict, total=False):
+    type: Literal["tool_call.failure"]
+    reason: str
+    metadata: InvalidToolCallMetadata
+
+class MessageStartEvent(TypedDict):
+    type: Literal["message.start"]
+
+class MessageDeltaEvent(TypedDict):
+    type: Literal["message.delta"]
+    content: str
+
+class MessageEndEvent(TypedDict):
+    type: Literal["message.end"]
+
+class ErrorInfo(TypedDict, total=False):
+    type: Literal["invalid_request", "unknown", "mcp_connection_error", "plugin_connection_error", "not_implemented", "model_not_found", "job_not_found", "internal_error"]
+    message: str
+    code: str
+    param: str
+
+class ErrorEvent(TypedDict):
+    type: Literal["error"]
+    error: ErrorInfo
+
+class ChatEndEvent(TypedDict):
+    type: Literal["chat.end"]
+    result: ChatResponse
+
+ChatStreamEvent = Union[
+    ChatStartEvent,
+    ModelLoadStartEvent,
+    ModelLoadProgressEvent,
+    ModelLoadEndEvent,
+    PromptProcessingStartEvent,
+    PromptProcessingProgressEvent,
+    PromptProcessingEndEvent,
+    ReasoningStartEvent,
+    ReasoningDeltaEvent,
+    ReasoningEndEvent,
+    ToolCallStartEvent,
+    ToolCallArgumentsEvent,
+    ToolCallSuccessEvent,
+    ToolCallFailureEvent,
+    MessageStartEvent,
+    MessageDeltaEvent,
+    MessageEndEvent,
+    ErrorEvent,
+    ChatEndEvent
+]
+
+class ModelQuantization(TypedDict, total=False):
+    name: Optional[str]
+    bits_per_weight: Optional[int]
+
+class ModelConfig(TypedDict, total=False):
+    context_length: int
+    eval_batch_size: int
+    parallel: int
+    flash_attention: bool
+    num_experts: int
+    offload_kv_cache_to_gpu: bool
+
+class LoadedInstance(TypedDict):
+    id: str
+    config: ModelConfig
+
+class ModelCapabilities(TypedDict, total=False):
+    vision: bool
+    trained_for_tool_use: bool
+
+class ModelReasoning(TypedDict):
+    allowed_options: List[Literal["off", "on", "low", "medium", "high"]]
+    default: Literal["off", "on", "low", "medium", "high"]
+
+class ModelInfo(TypedDict, total=False):
+    type: Literal["llm", "embedding"]
+    publisher: str
+    key: str
+    display_name: str
+    architecture: Optional[str]
+    quantization: Optional[ModelQuantization]
+    size_bytes: int
+    params_string: Optional[str]
+    loaded_instances: List[LoadedInstance]
+    max_context_length: int
+    format: Optional[Literal["gguf", "mlx"]]
+    capabilities: ModelCapabilities
+    reasoning: ModelReasoning
+    description: Optional[str]
+    variants: List[str]
+    selected_variant: str
+
+class ListModelsResponse(TypedDict):
+    models: List[ModelInfo]
+
+class LoadConfig(TypedDict, total=False):
+    context_length: int
+    eval_batch_size: int
+    flash_attention: bool
+    num_experts: int
+    offload_kv_cache_to_gpu: bool
+
+class LoadModelResponse(TypedDict, total=False):
+    type: Literal["llm", "embedding"]
+    instance_id: str
+    load_time_seconds: float
+    status: Literal["loaded"]
+    load_config: LoadConfig
+
+class UnloadModelResponse(TypedDict):
+    instance_id: str
+
+class DownloadStatusResponse(TypedDict, total=False):
+    job_id: str
+    status: Literal["downloading", "paused", "completed", "failed", "already_downloaded"]
+    bytes_per_second: int
+    estimated_completion: str
+    completed_at: str
+    total_size_bytes: int
+    downloaded_bytes: int
+    started_at: str
+
+
+
+class LMStdError(Exception):
+    """Exception raised for errors returned by the LM Studio API."""
+    def __init__(self, status_code: int, response_text: str):
+        self.status_code = status_code
+        self.response_text = response_text
+        super().__init__(f"API Error {status_code}: {response_text}")
+
+
+class LMStd:
+    """
+    A client library for interacting with LM Studio's native v1 REST API.
+    """
+
+    def __init__(self, base_url: str = "http://localhost:1234", api_token: Optional[str] = None):
+        """
+        Initializes the LM Studio API Client.
+
+        Args:
+            base_url (str): The base URL where your LM Studio local server is running.
+                            By default, the server is available at http://localhost:1234.
+            api_token (str, optional): The LM_API_TOKEN authorization bearer token if required. 
+                                       Passed as an Authorization header[cite: 57, 58].
+        """
+        import requests  
+        self.base_url = base_url.rstrip('/')
+        self.session = requests.Session()
+        
+        self.session.headers.update({
+            "Content-Type": "application/json"
+        })
+        if api_token:
+            self.session.headers.update({
+                "Authorization": f"Bearer {api_token}"
+            })
+
+    def _request(self, method: str, endpoint: str, json_data: Optional[Dict[str, Any]] = None) -> Any:
+        """Internal helper to process HTTP requests cleanly."""
+        url = f"{self.base_url}{endpoint}"
+        try:
+            response = self.session.request(method=method, url=url, json=json_data)
+            if response.status_code not in (200, 201):
+                raise LMStdError(response.status_code, response.text)
+            return response.json()
+        except Exception as e:
+            if isinstance(e, LMStdError):
+                raise e
+            raise RuntimeError(f"Failed to connect or process request to {url}: {e}")
+
+    def chat(
+        self, 
+        model: Optional[str] = None, 
+        input_data: Optional[Union[str, List[InputItem]]] = None, 
+        system_prompt: Optional[str] = None,
+        integrations: Optional[List[Integration]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        top_k: Optional[int] = None,
+        min_p: Optional[float] = None,
+        repeat_penalty: Optional[float] = None,
+        max_output_tokens: Optional[int] = None,
+        reasoning: Optional[Literal["off", "low", "medium", "high", "on"]] = None,
+        context_length: Optional[int] = None,
+        store: Optional[bool] = True,
+        previous_response_id: Optional[str] = None
+    ) -> ChatResponse:
+        """
+        POST /api/v1/chat
+        Send a message to a model and receive a full response. 
+        The /api/v1/chat endpoint is stateful by default, storing and managing context automatically.
+
+        Args:
+            model (str): Unique identifier for the model to use.
+            input_data (str or list): Text message string or an array of input items (messages/images). 
+                                      Images can be passed using 'type': 'image' and 'data_url'[cite: 642, 656, 660].
+            system_prompt (str, optional): System message that sets model behavior or instructions.
+            integrations (list, optional): List of integrations (plugins, ephemeral MCP servers) to enable for this request.
+            headers (dict, optional): Custom HTTP headers to send with requests to the server.
+            temperature (float, optional): Randomness in token selection (0 is deterministic, [0,1]).
+            top_p (float, optional): Minimum cumulative probability for the possible next tokens [0,1].
+            top_k (int, optional): Limits next token selection to top-k most probable tokens.
+            min_p (float, optional): Minimum base probability for a token to be selected for output [0,1].
+            repeat_penalty (float, optional): Penalty for repeating token sequences. 1 is no penalty.
+            max_output_tokens (int, optional): Maximum number of tokens to generate.
+            reasoning (str, optional): Reasoning setting ('off', 'low', 'medium', 'high', 'on').
+            context_length (int, optional): Number of tokens to consider as context. Higher values recommended for MCP usage.
+            store (bool, optional): Whether to store the chat. If set to true, response will return a 'response_id' field.
+            previous_response_id (str, optional): Identifier of existing response to append to. Must start with "resp_".
+
+        Returns:
+            ChatResponse: Response fields containing 'model_instance_id', an 'output' array (messages, tool_calls, reasoning), 
+                            'stats' (token usage/metrics), and an optional 'response_id'[cite: 753, 756, 804, 837].
+        """
+        model = model or os.environ.get("LMSTD_MODEL")
+        if not model:
+            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
+        if input_data is None:
+            raise ValueError("input_data must be provided.")
+
+        payload = {
+            "model": model,
+            "input": input_data,
+            "stream": False,
+            "store": store
+        }
+        
+        if system_prompt is not None: payload["system_prompt"] = system_prompt
+        if integrations is not None: payload["integrations"] = integrations
+        if headers is not None: payload["headers"] = headers
+        if temperature is not None: payload["temperature"] = temperature
+        if top_p is not None: payload["top_p"] = top_p
+        if top_k is not None: payload["top_k"] = top_k
+        if min_p is not None: payload["min_p"] = min_p
+        if repeat_penalty is not None: payload["repeat_penalty"] = repeat_penalty
+        if max_output_tokens is not None: payload["max_output_tokens"] = max_output_tokens
+        if reasoning is not None: payload["reasoning"] = reasoning
+        if context_length is not None: payload["context_length"] = context_length
+        if previous_response_id is not None: payload["previous_response_id"] = previous_response_id
+
+        return self._request("POST", "/api/v1/chat", json_data=payload)
+
+    def chat_stream(
+        self, 
+        model: Optional[str] = None, 
+        input_data: Optional[Union[str, List[InputItem]]] = None, 
+        system_prompt: Optional[str] = None,
+        integrations: Optional[List[Integration]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        top_k: Optional[int] = None,
+        min_p: Optional[float] = None,
+        repeat_penalty: Optional[float] = None,
+        max_output_tokens: Optional[int] = None,
+        reasoning: Optional[Literal["off", "low", "medium", "high", "on"]] = None,
+        context_length: Optional[int] = None,
+        store: Optional[bool] = True,
+        previous_response_id: Optional[str] = None
+    ) -> Iterator[ChatStreamEvent]:
+        """
+        POST /api/v1/chat (Streaming)
+        Send a message to a model with `stream` set to true. The response is sent as a stream of events using Server-Sent Events (SSE).
+
+        Args:
+            model (str, optional): Unique identifier for the model to use. Can be an LLM or embedding model.
+            input_data (str | List[InputItem], optional): Message to send to the model. Text message string or an array of InputItem objects.
+            system_prompt (str, optional): System message that sets model behavior or instructions.
+            integrations (List[Integration], optional): List of integrations (plugins, ephemeral MCP servers, etc...) to enable for this request.
+            headers (dict, optional): Custom HTTP headers to send with requests to the server.
+            temperature (float, optional): Randomness in token selection. 0 is deterministic, higher values increase creativity [0,1].
+            top_p (float, optional): Minimum cumulative probability for the possible next tokens [0,1].
+            top_k (int, optional): Limits next token selection to top-k most probable tokens.
+            min_p (float, optional): Minimum base probability for a token to be selected for output [0,1].
+            repeat_penalty (float, optional): Penalty for repeating token sequences. 1 is no penalty, higher values discourage repetition.
+            max_output_tokens (int, optional): Maximum number of tokens to generate.
+            reasoning (Literal["off", "low", "medium", "high", "on"], optional): Reasoning setting. Will error if the model being used does not support the reasoning setting using. Defaults to the automatically chosen setting for the model.
+            context_length (int, optional): Number of tokens to consider as context. Higher values recommended for MCP usage.
+            store (bool, optional): Whether to store the chat. If set, response will return a 'response_id' field. Default true.
+            previous_response_id (str, optional): Identifier of existing response to append to. Must start with "resp_".
+
+        Yields:
+            ChatStreamEvent: Parsed JSON objects corresponding to streaming events. Events arrive in order and may include multiple deltas.
+                             Events: 'chat.start', 'model_load.start', 'model_load.progress', 'model_load.end', 
+                             'prompt_processing.start', 'prompt_processing.progress', 'prompt_processing.end',
+                             'reasoning.start', 'reasoning.delta', 'reasoning.end',
+                             'tool_call.start', 'tool_call.arguments', 'tool_call.success', 'tool_call.failure',
+                             'message.start', 'message.delta', 'message.end', 'error', 'chat.end'.
+        """
+        model = model or os.environ.get("LMSTD_MODEL")
+        if not model:
+            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
+        if input_data is None:
+            raise ValueError("input_data must be provided.")
+
+        url = f"{self.base_url}/api/v1/chat"
+        payload = {
+            "model": model,
+            "input": input_data,
+            "stream": True,
+            "store": store
+        }
+        
+        if system_prompt is not None: payload["system_prompt"] = system_prompt
+        if integrations is not None: payload["integrations"] = integrations
+        if headers is not None: payload["headers"] = headers
+        if temperature is not None: payload["temperature"] = temperature
+        if top_p is not None: payload["top_p"] = top_p
+        if top_k is not None: payload["top_k"] = top_k
+        if min_p is not None: payload["min_p"] = min_p
+        if repeat_penalty is not None: payload["repeat_penalty"] = repeat_penalty
+        if max_output_tokens is not None: payload["max_output_tokens"] = max_output_tokens
+        if reasoning is not None: payload["reasoning"] = reasoning
+        if context_length is not None: payload["context_length"] = context_length
+        if previous_response_id is not None: payload["previous_response_id"] = previous_response_id
+
+        try:
+            response = self.session.post(url, json=payload, stream=True)
+            if response.status_code not in (200, 201):
+                raise LMStdError(response.status_code, response.text)
+                
+            for line in response.iter_lines():
+                if line:
+                    decoded_line = line.decode('utf-8')
+                    if decoded_line.startswith('data: '):
+                        data_str = decoded_line[6:].strip()
+                        if data_str:
+                            yield json.loads(data_str)
+                            
+        except Exception as e:
+            if isinstance(e, LMStdError):
+                raise e
+            raise RuntimeError(f"Failed to connect or stream request to {url}: {e}")
+
+    def list_models(self) -> ListModelsResponse:
+        """
+        GET /api/v1/models
+        Get a list of available models on your system, including both LLMs and embedding models.
+
+        Returns:
+            ListModelsResponse: JSON object containing a list of available models, their configs (context_length, 
+                            architecture, format), and currently loaded instances[cite: 1102, 1118, 1130, 1134].
+        """
+        return self._request("GET", "/api/v1/models")
+
+    def load_model(
+        self, 
+        model: Optional[str] = None, 
+        context_length: Optional[int] = None,
+        eval_batch_size: Optional[int] = None,
+        flash_attention: Optional[bool] = None,
+        num_experts: Optional[int] = None,
+        offload_kv_cache_to_gpu: Optional[bool] = None,
+        echo_load_config: Optional[bool] = False
+    ) -> LoadModelResponse:
+        """
+        POST /api/v1/models/load
+        Load an LLM or Embedding model into memory with custom configuration for inference.
+
+        Args:
+            model (str): Unique identifier for the model to load.
+            context_length (int, optional): Maximum number of tokens that the model will consider.
+            eval_batch_size (int, optional): Number of input tokens to process together in a single batch during evaluation.
+            flash_attention (bool, optional): Whether to optimize attention computation. Can decrease memory usage and improve speed.
+            num_experts (int, optional): Number of experts to use during inference for MoE (Mixture of Experts) models.
+            offload_kv_cache_to_gpu (bool, optional): Whether KV cache is offloaded to GPU memory.
+            echo_load_config (bool, optional): If true, echoes the final load configuration in the response.
+
+        Returns:
+            LoadModelResponse: Response featuring 'type', 'instance_id', 'load_time_seconds', 'status', and optionally 'load_config'[cite: 1251, 1261].
+        """
+        model = model or os.environ.get("LMSTD_MODEL")
+        if not model:
+            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
+
+        payload = {
+            "model": model,
+            "echo_load_config": echo_load_config
+        }
+        if context_length is not None: payload["context_length"] = context_length
+        if eval_batch_size is not None: payload["eval_batch_size"] = eval_batch_size
+        if flash_attention is not None: payload["flash_attention"] = flash_attention
+        if num_experts is not None: payload["num_experts"] = num_experts
+        if offload_kv_cache_to_gpu is not None: payload["offload_kv_cache_to_gpu"] = offload_kv_cache_to_gpu
+
+        return self._request("POST", "/api/v1/models/load", json_data=payload)
+
+    def unload_model(self, instance_id: str) -> UnloadModelResponse:
+        """
+        POST /api/v1/models/unload
+        Unload a loaded model from memory.
+
+        Args:
+            instance_id (str): Unique identifier of the model instance to unload.
+
+        Returns:
+            UnloadModelResponse: Response containing the 'instance_id' of the unloaded model instance.
+        """
+        payload = {"instance_id": instance_id}
+        return self._request("POST", "/api/v1/models/unload", json_data=payload)
+
+    def download_model(self, model: Optional[str] = None, quantization: Optional[str] = None) -> DownloadStatusResponse:
+        """
+        POST /api/v1/models/download
+        Download LLMs and embedding models.
+
+        Args:
+            model (str, optional): The model to download. Accepts model catalog identifiers (e.g., openai/gpt-oss-20b) and exact Hugging Face links (e.g., https://huggingface.co/lmstudio-community/gpt-oss-20b-GGUF).
+            quantization (str, optional): Quantization level of the model to download (e.g., Q4_K_M). Only supported for Hugging Face links.
+
+        Returns:
+            DownloadStatusResponse: Returns a download job status object. The response varies based on the download status ('downloading', 'paused', 'completed', 'failed', 'already_downloaded').
+        """
+        model = model or os.environ.get("LMSTD_MODEL")
+        if not model:
+            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
+
+        payload = {"model": model}
+        if quantization is not None:
+            payload["quantization"] = quantization
+        return self._request("POST", "/api/v1/models/download", json_data=payload)
+
+    def get_download_status(self, job_id: str) -> DownloadStatusResponse:
+        """
+        GET /api/v1/models/download/status/:job_id
+        Get the status of model downloads.
+
+        Args:
+            job_id (str): The unique identifier of the download job.
+
+        Returns:
+            DownloadStatusResponse: Download job status object including 'status', 'bytes_per_second', 'total_size_bytes', 
+                            'downloaded_bytes', 'estimated_completion', etc[cite: 1391, 1394, 1396, 1400, 1402].
+        """
+        return self._request("GET", f"/api/v1/models/download/status/{job_id}")
+
+
+# --- Basic Usage Verification Example ---
+if __name__ == "__main__":
+    client = LMStd(api_token=os.environ.get("LMSTD_APIKEY"))
+    
+    print("1. Listing system models...")
+    try:
+        models = client.list_models()
+        print(json.dumps(models, indent=2))
+        
+    except Exception as error:
+        print(f"Server communication failed: {error}")
+
+    input()

{lmstd-0.1.0 → lmstd-0.2.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lmstd"
-version = "0.1.0"
+version = "0.2.0"
 description = "LM Studio v1 REST API Client Library"
 readme = "README.md"
 requires-python = ">=3.7"
-license = {text = "MIT"}
+license = "MIT"
 authors = [
     { name = "LM Studio User" }
 ]

lmstd-0.1.0/lmstd.py

@@ -1,316 +0,0 @@
-"""
-LM Studio v1 REST API Client Library
-
-This single-file library provides a clean, fully documented Python interface 
-to interact with an LM Studio local server based on the v1 REST API endpoints.
-
-Features supported natively via the v1 API:
-- Stateful chats 
-- Model Context Protocol (MCP) integrations via API 
-- Authentication configuration with API tokens 
-- Advanced model lifecycle management (download, load, unload) 
-
-Dependencies:
-    requests
-"""
-
-import json
-import os
-from typing import Any, Dict, Iterator, List, Optional, Union
-
-
-class LMStdError(Exception):
-    """Exception raised for errors returned by the LM Studio API."""
-    def __init__(self, status_code: int, response_text: str):
-        self.status_code = status_code
-        self.response_text = response_text
-        super().__init__(f"API Error {status_code}: {response_text}")
-
-
-class LMStd:
-    """
-    A client library for interacting with LM Studio's native v1 REST API.
-    """
-
-    def __init__(self, base_url: str = "http://localhost:1234", api_token: Optional[str] = None):
-        """
-        Initializes the LM Studio API Client.
-
-        Args:
-            base_url (str): The base URL where your LM Studio local server is running.
-                            By default, the server is available at http://localhost:1234.
-            api_token (str, optional): The LM_API_TOKEN authorization bearer token if required. 
-                                       Passed as an Authorization header[cite: 57, 58].
-        """
-        import requests  
-        self.base_url = base_url.rstrip('/')
-        self.session = requests.Session()
-        
-        self.session.headers.update({
-            "Content-Type": "application/json"
-        })
-        if api_token:
-            self.session.headers.update({
-                "Authorization": f"Bearer {api_token}"
-            })
-
-    def _request(self, method: str, endpoint: str, json_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Internal helper to process HTTP requests cleanly."""
-        url = f"{self.base_url}{endpoint}"
-        try:
-            response = self.session.request(method=method, url=url, json=json_data)
-            if response.status_code not in (200, 201):
-                raise LMStdError(response.status_code, response.text)
-            return response.json()
-        except Exception as e:
-            if isinstance(e, LMStdError):
-                raise e
-            raise RuntimeError(f"Failed to connect or process request to {url}: {e}")
-
-    def chat(
-        self, 
-        model: Optional[str] = None, 
-        input_data: Optional[Union[str, List[Dict[str, Any]]]] = None, 
-        system_prompt: Optional[str] = None,
-        integrations: Optional[List[Union[str, Dict[str, Any]]]] = None,
-        headers: Optional[Dict[str, str]] = None,
-        temperature: Optional[float] = None,
-        top_p: Optional[float] = None,
-        top_k: Optional[int] = None,
-        min_p: Optional[float] = None,
-        repeat_penalty: Optional[float] = None,
-        max_output_tokens: Optional[int] = None,
-        reasoning: Optional[str] = None,
-        context_length: Optional[int] = None,
-        store: bool = True,
-        previous_response_id: Optional[str] = None
-    ) -> Dict[str, Any]:
-        """
-        POST /api/v1/chat
-        Send a message to a model and receive a full response. 
-        The /api/v1/chat endpoint is stateful by default, storing and managing context automatically.
-
-        Args:
-            model (str): Unique identifier for the model to use.
-            input_data (str or list): Text message string or an array of input items (messages/images). 
-                                      Images can be passed using 'type': 'image' and 'data_url'[cite: 642, 656, 660].
-            system_prompt (str, optional): System message that sets model behavior or instructions.
-            integrations (list, optional): List of integrations (plugins, ephemeral MCP servers) to enable for this request.
-            headers (dict, optional): Custom HTTP headers to send with requests to the server.
-            temperature (float, optional): Randomness in token selection (0 is deterministic, [0,1]).
-            top_p (float, optional): Minimum cumulative probability for the possible next tokens [0,1].
-            top_k (int, optional): Limits next token selection to top-k most probable tokens.
-            min_p (float, optional): Minimum base probability for a token to be selected for output [0,1].
-            repeat_penalty (float, optional): Penalty for repeating token sequences. 1 is no penalty.
-            max_output_tokens (int, optional): Maximum number of tokens to generate.
-            reasoning (str, optional): Reasoning setting ('off', 'low', 'medium', 'high', 'on').
-            context_length (int, optional): Number of tokens to consider as context. Higher values recommended for MCP usage.
-            store (bool, optional): Whether to store the chat. If set to true, response will return a 'response_id' field.
-            previous_response_id (str, optional): Identifier of existing response to append to. Must start with "resp_".
-
-        Returns:
-            Dict[str, Any]: Response fields containing 'model_instance_id', an 'output' array (messages, tool_calls, reasoning), 
-                            'stats' (token usage/metrics), and an optional 'response_id'[cite: 753, 756, 804, 837].
-        """
-        model = model or os.environ.get("LMSTD_MODEL")
-        if not model:
-            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
-        if input_data is None:
-            raise ValueError("input_data must be provided.")
-
-        payload = {
-            "model": model,
-            "input": input_data,
-            "stream": False,
-            "store": store
-        }
-        
-        if system_prompt is not None: payload["system_prompt"] = system_prompt
-        if integrations is not None: payload["integrations"] = integrations
-        if headers is not None: payload["headers"] = headers
-        if temperature is not None: payload["temperature"] = temperature
-        if top_p is not None: payload["top_p"] = top_p
-        if top_k is not None: payload["top_k"] = top_k
-        if min_p is not None: payload["min_p"] = min_p
-        if repeat_penalty is not None: payload["repeat_penalty"] = repeat_penalty
-        if max_output_tokens is not None: payload["max_output_tokens"] = max_output_tokens
-        if reasoning is not None: payload["reasoning"] = reasoning
-        if context_length is not None: payload["context_length"] = context_length
-        if previous_response_id is not None: payload["previous_response_id"] = previous_response_id
-
-        return self._request("POST", "/api/v1/chat", json_data=payload)
-
-    def chat_stream(
-        self, 
-        model: Optional[str] = None, 
-        input_data: Optional[Union[str, List[Dict[str, Any]]]] = None, 
-        **kwargs
-    ) -> Iterator[Dict[str, Any]]:
-        """
-        POST /api/v1/chat (Streaming)
-        Send a message to a model with `stream` set to true. The response is sent as a stream of events using Server-Sent Events (SSE).
-
-        Args:
-            model (str): Unique identifier for the model to use.
-            input_data (str or list): Text message string or an array of input items.
-            **kwargs: Additional parameters matching the `chat` function (e.g., system_prompt, integrations, store, temperature, etc.).
-
-        Yields:
-            Dict[str, Any]: Parsed JSON objects corresponding to streaming events. Events arrive in order and include:
-                            'chat.start', 'model_load.*', 'prompt_processing.*', 'reasoning.*', 'tool_call.*', 'message.*', 
-                            'error', and finally 'chat.end'[cite: 211, 216, 217, 220, 227, 238].
-        """
-        model = model or os.environ.get("LMSTD_MODEL")
-        if not model:
-            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
-        if input_data is None:
-            raise ValueError("input_data must be provided.")
-
-        url = f"{self.base_url}/api/v1/chat"
-        payload = {
-            "model": model,
-            "input": input_data,
-            "stream": True,
-            "store": kwargs.get("store", True)
-        }
-        
-        for key in ["system_prompt", "integrations", "headers", "temperature", "top_p", "top_k", 
-                    "min_p", "repeat_penalty", "max_output_tokens", "reasoning", 
-                    "context_length", "previous_response_id"]:
-            if key in kwargs and kwargs[key] is not None:
-                payload[key] = kwargs[key]
-
-        try:
-            response = self.session.post(url, json=payload, stream=True)
-            if response.status_code not in (200, 201):
-                raise LMStdError(response.status_code, response.text)
-                
-            for line in response.iter_lines():
-                if line:
-                    decoded_line = line.decode('utf-8')
-                    if decoded_line.startswith('data: '):
-                        data_str = decoded_line[6:].strip()
-                        if data_str:
-                            yield json.loads(data_str)
-                            
-        except Exception as e:
-            if isinstance(e, LMStdError):
-                raise e
-            raise RuntimeError(f"Failed to connect or stream request to {url}: {e}")
-
-    def list_models(self) -> Dict[str, Any]:
-        """
-        GET /api/v1/models
-        Get a list of available models on your system, including both LLMs and embedding models.
-
-        Returns:
-            Dict[str, Any]: JSON object containing a list of available models, their configs (context_length, 
-                            architecture, format), and currently loaded instances[cite: 1102, 1118, 1130, 1134].
-        """
-        return self._request("GET", "/api/v1/models")
-
-    def load_model(
-        self, 
-        model: Optional[str] = None, 
-        context_length: Optional[int] = None,
-        eval_batch_size: Optional[int] = None,
-        flash_attention: Optional[bool] = None,
-        num_experts: Optional[int] = None,
-        offload_kv_cache_to_gpu: Optional[bool] = None,
-        echo_load_config: bool = False
-    ) -> Dict[str, Any]:
-        """
-        POST /api/v1/models/load
-        Load an LLM or Embedding model into memory with custom configuration for inference.
-
-        Args:
-            model (str): Unique identifier for the model to load.
-            context_length (int, optional): Maximum number of tokens that the model will consider.
-            eval_batch_size (int, optional): Number of input tokens to process together in a single batch during evaluation.
-            flash_attention (bool, optional): Whether to optimize attention computation. Can decrease memory usage and improve speed.
-            num_experts (int, optional): Number of experts to use during inference for MoE (Mixture of Experts) models.
-            offload_kv_cache_to_gpu (bool, optional): Whether KV cache is offloaded to GPU memory.
-            echo_load_config (bool, optional): If true, echoes the final load configuration in the response.
-
-        Returns:
-            Dict[str, Any]: Response featuring 'type', 'instance_id', 'load_time_seconds', 'status', and optionally 'load_config'[cite: 1251, 1261].
-        """
-        model = model or os.environ.get("LMSTD_MODEL")
-        if not model:
-            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
-
-        payload = {
-            "model": model,
-            "echo_load_config": echo_load_config
-        }
-        if context_length is not None: payload["context_length"] = context_length
-        if eval_batch_size is not None: payload["eval_batch_size"] = eval_batch_size
-        if flash_attention is not None: payload["flash_attention"] = flash_attention
-        if num_experts is not None: payload["num_experts"] = num_experts
-        if offload_kv_cache_to_gpu is not None: payload["offload_kv_cache_to_gpu"] = offload_kv_cache_to_gpu
-
-        return self._request("POST", "/api/v1/models/load", json_data=payload)
-
-    def unload_model(self, instance_id: str) -> Dict[str, Any]:
-        """
-        POST /api/v1/models/unload
-        Unload a loaded model from memory.
-
-        Args:
-            instance_id (str): Unique identifier of the model instance to unload.
-
-        Returns:
-            Dict[str, Any]: Confirmation of the unloaded model 'instance_id'.
-        """
-        payload = {"instance_id": instance_id}
-        return self._request("POST", "/api/v1/models/unload", json_data=payload)
-
-    def download_model(self, model: Optional[str] = None, quantization: Optional[str] = None) -> Dict[str, Any]:
-        """
-        POST /api/v1/models/download
-        Download LLMs and embedding models.
-
-        Args:
-            model (str): The model to download. Accepts model catalog identifiers and exact Hugging Face links.
-            quantization (str, optional): Quantization level of the model to download (e.g. 'Q4_K_M'). Only supported for Hugging Face links.
-
-        Returns:
-            Dict[str, Any]: Returns a download job status object (e.g., 'job_id', 'status', 'total_size_bytes', 'started_at')[cite: 1321, 1333, 1335].
-        """
-        model = model or os.environ.get("LMSTD_MODEL")
-        if not model:
-            raise ValueError("Model must be provided or set via the LMSTD_MODEL environment variable.")
-
-        payload = {"model": model}
-        if quantization is not None:
-            payload["quantization"] = quantization
-        return self._request("POST", "/api/v1/models/download", json_data=payload)
-
-    def get_download_status(self, job_id: str) -> Dict[str, Any]:
-        """
-        GET /api/v1/models/download/status/:job_id
-        Get the status of model downloads.
-
-        Args:
-            job_id (str): The unique identifier of the download job.
-
-        Returns:
-            Dict[str, Any]: Download job status object including 'status', 'bytes_per_second', 'total_size_bytes', 
-                            'downloaded_bytes', 'estimated_completion', etc[cite: 1391, 1394, 1396, 1400, 1402].
-        """
-        return self._request("GET", f"/api/v1/models/download/status/{job_id}")
-
-
-# --- Basic Usage Verification Example ---
-if __name__ == "__main__":
-    client = LMStd(api_token=os.environ.get("LMSTD_APIKEY"))
-    
-    print("1. Listing system models...")
-    try:
-        models = client.list_models()
-        print(json.dumps(models, indent=2))
-        
-    except Exception as error:
-        print(f"Server communication failed: {error}")
-
-    input()