lmstd 0.1.0__py3-none-any.whl

lmstd-0.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: lmstd
+Version: 0.1.0
+Summary: LM Studio v1 REST API Client Library
+Author: LM Studio User
+License: MIT
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# LMStd
+
+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.
+
+## Installation
+
+You can install this package via pip once published or from the source code:
+
+```bash
+pip install lmstd
+```
+
+## Usage
+
+```python
+import os
+from lmstd import LMStd
+
+# Initialize the client
+client = LMStd(
+    base_url="http://localhost:1234", 
+    api_token=os.environ.get("LMSTD_APIKEY")
+)
+
+# List available models
+models = client.list_models()
+print(models)
+```
+
+## Features
+
+- **Stateful chats**: Fully utilize the stateful `/api/v1/chat` endpoint.
+- **Model Context Protocol (MCP)**: Use integrations and MCP tools directly.
+- **Advanced Model Management**: Load, unload, and download models programmatically.
+- **Streaming Support**: Easy SSE-based chat streaming support.
+
+## License
+
+MIT License

lmstd-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+lmstd.py,sha256=Ouf69Brshw2UbdITAU1Y10eTpnTeCYI2QOjfuglcNAQ,14755
+lmstd-0.1.0.dist-info/licenses/LICENSE,sha256=Ct45NP0cQPcrziLZ_ssab49Jtmx3jJd68BgxfKkIW-s,1090
+lmstd-0.1.0.dist-info/METADATA,sha256=Au965gFgn7dx4z2JdqwUdUhoWAUaehsu4h8B-t4rfD8,1241
+lmstd-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+lmstd-0.1.0.dist-info/top_level.txt,sha256=iWRpN_xU3aEt7BtqtMEJlyHh3Pq13KQ4OrE6PPlIsXo,6
+lmstd-0.1.0.dist-info/RECORD,,

lmstd-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lmstd-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LM Studio User
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lmstd-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lmstd

lmstd.py

@@ -0,0 +1,316 @@
+"""
+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()