lemonade-python-sdk 1.0.1__tar.gz

lemonade_python_sdk-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name or Organization
+
+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.

lemonade_python_sdk-1.0.1/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: lemonade-python-sdk
+Version: 1.0.1
+Summary: A clean interface for interacting with the Lemonade LLM server
+Home-page: https://github.com/Tetramatrix/lemonade-python-sdk
+Author: Your Name
+Author-email: your.email@example.com
+Project-URL: Bug Reports, https://github.com/Tetramatrix/lemonade-python-sdk/issues
+Project-URL: Source, https://github.com/Tetramatrix/lemonade-python-sdk
+Keywords: llm,ai,lemonade,sdk,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 🍋 Lemonade Python SDK
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A robust, production-grade Python wrapper for the **Lemonade C++ Backend**. 
+
+This SDK provides a clean, pythonic interface for interacting with local LLMs running on Lemonade. It was built to power **Sorana** (a visual workspace for AI), extracting the core integration logic into a standalone, open-source library for the developer community.
+
+## 🚀 Key Features
+
+* **Auto-Discovery:** Automatically scans multiple ports and hosts to find active Lemonade instances.
+* **Low-Overhead Architecture:** Designed as a thin, efficient wrapper to leverage Lemonade's C++ performance with minimal Python latency.
+* **Health Checks & Recovery:** Built-in utilities to verify server status and handle connection drops.
+* **Type-Safe Client:** Full Python type hinting for better developer experience (IDE autocompletion).
+* **Model Management:** Simple API to load, unload, and list models dynamically.
+* **Embeddings API:** Generate text embeddings for semantic search, RAG, and clustering (FLM & llamacpp backends).
+
+## 📦 Installation
+
+```bash
+pip install .
+```
+
+Alternatively, you can install it directly from GitHub:
+
+```bash
+pip install git+[https://github.com/Tetramatrix/lemonade-python-sdk.git](https://github.com/Tetramatrix/lemonade-python-sdk.git)
+```
+
+## ⚡ Quick Start
+
+### 1. Connecting to Lemonade
+
+The SDK automatically handles port discovery, so you don't need to hardcode localhost:8000.
+
+```python
+from lemonade_integration.client import LemonadeClient
+from lemonade_integration.port_scanner import find_available_lemonade_port
+
+# Auto-discover running instance
+port = find_available_lemonade_port()
+if port:
+    client = LemonadeClient(base_url=f"http://localhost:{port}")
+    if client.health_check():
+        print(f"Connected to Lemonade on port {port}")
+else:
+    print("No Lemonade instance found.")
+```
+
+### 2. Chat Completion
+
+```python
+response = client.chat_completion(
+    model="Llama-3-8B-Instruct",
+    messages=[
+        {"role": "system", "content": "You are a helpful coding assistant."},
+        {"role": "user", "content": "Write a Hello World in C++"}
+    ],
+    temperature=0.7
+)
+
+print(response['choices'][0]['message']['content'])
+```
+
+### 3. Model Management
+
+```python
+# List all available models
+models = client.list_models()
+for m in models:
+    print(f"Found model: {m['id']}")
+
+# Load a specific model into memory
+client.load_model("Mistral-7B-v0.1")
+```
+
+### 4. Embeddings (NEW)
+
+Generate text embeddings for semantic search, RAG pipelines, and clustering.
+
+```python
+# List available embedding models (filtered by 'embeddings' label)
+embedding_models = client.list_embedding_models()
+for model in embedding_models:
+    print(f"Embedding model: {model['id']}")
+
+# Generate embeddings for single text
+response = client.embeddings(
+    input="Hello, world!",
+    model="nomic-embed-text-v1-GGUF"
+)
+
+embedding_vector = response["data"][0]["embedding"]
+print(f"Vector length: {len(embedding_vector)}")
+
+# Generate embeddings for multiple texts
+texts = ["Text 1", "Text 2", "Text 3"]
+response = client.embeddings(
+    input=texts,
+    model="nomic-embed-text-v1-GGUF"
+)
+
+for item in response["data"]:
+    print(f"Text {item['index']}: {len(item['embedding'])} dimensions")
+```
+
+**Supported Backends:**
+- ✅ **FLM (FastFlowLM)** - NPU-accelerated on Windows
+- ✅ **llamacpp** (.GGUF models) - CPU/GPU
+- ❌ ONNX/OGA - Not supported
+
+### 🖼️ Production Showcase: [Sorana](https://tetramatrix.github.io/Sorana/)
+This SDK was extracted from the core engine of [Sorana](https://tetramatrix.github.io/Sorana/), a professional visual workspace for AI. It demonstrates the SDK's capability to handle complex, real-world requirements on AMD Ryzen AI hardware:
+
+* **Low Latency:** Powers sub-second response times for multi-model chat interfaces.
+* **Dynamic Workflows:** Manages the loading and unloading of 20+ different LLMs based on user activity to optimize local NPU/GPU memory.
+* **Zero-Config UX:** Uses the built-in port scanner to automatically connect the Sorana frontend to the Lemonade backend without user intervention.
+
+## 🛠️ Project Structure
+
+* **client.py:** Main entry point for API interactions (chat, embeddings, model management).
+* **port_scanner.py:** Utilities for detecting Lemonade instances across ports (8000-9000).
+* **model_discovery.py:** Logic for fetching and parsing model metadata.
+* **request_builder.py:** Helper functions to construct compliant payloads (chat, embeddings).
+* **utils.py:** Additional utility functions.
+
+## 📚 Documentation
+
+* **[Embeddings API](docs/embeddings_api.md)** - Complete guide for using embeddings
+* [Lemonade Server Docs](https://lemonade-server.ai/docs/server/server_spec/) - Official Lemonade documentation
+
+## 🤝 Contributing
+
+Contributions are welcome! This project is intended to help the AMD Ryzen AI and Lemonade community build downstream applications faster.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

lemonade_python_sdk-1.0.1/README.md

@@ -0,0 +1,139 @@
+# 🍋 Lemonade Python SDK
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A robust, production-grade Python wrapper for the **Lemonade C++ Backend**. 
+
+This SDK provides a clean, pythonic interface for interacting with local LLMs running on Lemonade. It was built to power **Sorana** (a visual workspace for AI), extracting the core integration logic into a standalone, open-source library for the developer community.
+
+## 🚀 Key Features
+
+* **Auto-Discovery:** Automatically scans multiple ports and hosts to find active Lemonade instances.
+* **Low-Overhead Architecture:** Designed as a thin, efficient wrapper to leverage Lemonade's C++ performance with minimal Python latency.
+* **Health Checks & Recovery:** Built-in utilities to verify server status and handle connection drops.
+* **Type-Safe Client:** Full Python type hinting for better developer experience (IDE autocompletion).
+* **Model Management:** Simple API to load, unload, and list models dynamically.
+* **Embeddings API:** Generate text embeddings for semantic search, RAG, and clustering (FLM & llamacpp backends).
+
+## 📦 Installation
+
+```bash
+pip install .
+```
+
+Alternatively, you can install it directly from GitHub:
+
+```bash
+pip install git+[https://github.com/Tetramatrix/lemonade-python-sdk.git](https://github.com/Tetramatrix/lemonade-python-sdk.git)
+```
+
+## ⚡ Quick Start
+
+### 1. Connecting to Lemonade
+
+The SDK automatically handles port discovery, so you don't need to hardcode localhost:8000.
+
+```python
+from lemonade_integration.client import LemonadeClient
+from lemonade_integration.port_scanner import find_available_lemonade_port
+
+# Auto-discover running instance
+port = find_available_lemonade_port()
+if port:
+    client = LemonadeClient(base_url=f"http://localhost:{port}")
+    if client.health_check():
+        print(f"Connected to Lemonade on port {port}")
+else:
+    print("No Lemonade instance found.")
+```
+
+### 2. Chat Completion
+
+```python
+response = client.chat_completion(
+    model="Llama-3-8B-Instruct",
+    messages=[
+        {"role": "system", "content": "You are a helpful coding assistant."},
+        {"role": "user", "content": "Write a Hello World in C++"}
+    ],
+    temperature=0.7
+)
+
+print(response['choices'][0]['message']['content'])
+```
+
+### 3. Model Management
+
+```python
+# List all available models
+models = client.list_models()
+for m in models:
+    print(f"Found model: {m['id']}")
+
+# Load a specific model into memory
+client.load_model("Mistral-7B-v0.1")
+```
+
+### 4. Embeddings (NEW)
+
+Generate text embeddings for semantic search, RAG pipelines, and clustering.
+
+```python
+# List available embedding models (filtered by 'embeddings' label)
+embedding_models = client.list_embedding_models()
+for model in embedding_models:
+    print(f"Embedding model: {model['id']}")
+
+# Generate embeddings for single text
+response = client.embeddings(
+    input="Hello, world!",
+    model="nomic-embed-text-v1-GGUF"
+)
+
+embedding_vector = response["data"][0]["embedding"]
+print(f"Vector length: {len(embedding_vector)}")
+
+# Generate embeddings for multiple texts
+texts = ["Text 1", "Text 2", "Text 3"]
+response = client.embeddings(
+    input=texts,
+    model="nomic-embed-text-v1-GGUF"
+)
+
+for item in response["data"]:
+    print(f"Text {item['index']}: {len(item['embedding'])} dimensions")
+```
+
+**Supported Backends:**
+- ✅ **FLM (FastFlowLM)** - NPU-accelerated on Windows
+- ✅ **llamacpp** (.GGUF models) - CPU/GPU
+- ❌ ONNX/OGA - Not supported
+
+### 🖼️ Production Showcase: [Sorana](https://tetramatrix.github.io/Sorana/)
+This SDK was extracted from the core engine of [Sorana](https://tetramatrix.github.io/Sorana/), a professional visual workspace for AI. It demonstrates the SDK's capability to handle complex, real-world requirements on AMD Ryzen AI hardware:
+
+* **Low Latency:** Powers sub-second response times for multi-model chat interfaces.
+* **Dynamic Workflows:** Manages the loading and unloading of 20+ different LLMs based on user activity to optimize local NPU/GPU memory.
+* **Zero-Config UX:** Uses the built-in port scanner to automatically connect the Sorana frontend to the Lemonade backend without user intervention.
+
+## 🛠️ Project Structure
+
+* **client.py:** Main entry point for API interactions (chat, embeddings, model management).
+* **port_scanner.py:** Utilities for detecting Lemonade instances across ports (8000-9000).
+* **model_discovery.py:** Logic for fetching and parsing model metadata.
+* **request_builder.py:** Helper functions to construct compliant payloads (chat, embeddings).
+* **utils.py:** Additional utility functions.
+
+## 📚 Documentation
+
+* **[Embeddings API](docs/embeddings_api.md)** - Complete guide for using embeddings
+* [Lemonade Server Docs](https://lemonade-server.ai/docs/server/server_spec/) - Official Lemonade documentation
+
+## 🤝 Contributing
+
+Contributions are welcome! This project is intended to help the AMD Ryzen AI and Lemonade community build downstream applications faster.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

lemonade_python_sdk-1.0.1/lemonade_integration/__init__.py

@@ -0,0 +1,6 @@
+from .client import LemonadeClient
+from .model_discovery import discover_lemonade_models
+from .port_scanner import find_available_lemonade_port
+from .request_builder import build_embedding_payload
+
+__all__ = ['LemonadeClient', 'discover_lemonade_models', 'find_available_lemonade_port', 'build_embedding_payload']

lemonade_python_sdk-1.0.1/lemonade_integration/client.py

@@ -0,0 +1,177 @@
+"""
+LemonadeClient - Main class for interacting with the Lemonade server
+"""
+
+import requests
+import json
+from typing import Dict, List, Optional, Any
+from .request_builder import build_chat_completion_payload, send_request, build_embedding_payload
+from .model_discovery import get_active_model
+
+
+class LemonadeClient:
+    """
+    A class for interacting with the Lemonade LLM Server.
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8000"):
+        """
+        Initializes the Lemonade Client with the base URL.
+
+        Args:
+            base_url (str): The base URL of the Lemonade server (default: http://localhost:8000)
+        """
+        self.base_url = base_url.rstrip('/')
+        self.session = requests.Session()
+        
+    def list_models(self) -> List[Dict[str, Any]]:
+        """
+        Retrieves the list of available models from the Lemonade server.
+
+        Returns:
+            List[Dict[str, Any]]: List of available models
+        """
+        url = f"{self.base_url}/api/v1/models"
+        try:
+            response = self.session.get(url, timeout=10)
+            response.raise_for_status()
+            data = response.json()
+
+            # Lemonade returns models under 'data' key
+            models = data.get('data', [])
+            return models
+        except requests.exceptions.RequestException as e:
+            print(f"Error retrieving models: {e}")
+            return []
+        except json.JSONDecodeError as e:
+            print(f"Error parsing response: {e}")
+            return []
+    
+    def chat_completion(self, model: str, messages: List[Dict[str, str]], **kwargs) -> Dict[str, Any]:
+        """
+        Sends a chat completion request to the Lemonade server.
+
+        Args:
+            model (str): The name of the model to use
+            messages (List[Dict[str, str]]): The messages for the conversation
+            **kwargs: Additional parameters for the request
+
+        Returns:
+            Dict[str, Any]: The response from the server
+        """
+        url = f"{self.base_url}/api/v1/chat/completions"
+
+        payload = build_chat_completion_payload(model, messages, **kwargs)
+
+        try:
+            response = send_request(url, payload, session=self.session)
+            return response
+        except Exception as e:
+            print(f"Error in chat completion request: {e}")
+            return {"error": str(e)}
+    
+    def health_check(self) -> bool:
+        """
+        Checks if the Lemonade server is running and reachable.
+
+        Returns:
+            bool: True if the server is reachable, otherwise False
+        """
+        try:
+            models = self.list_models()
+            return len(models) >= 0  # If we don't get an error, the server is reachable
+        except:
+            return False
+    
+    def get_current_model(self) -> Optional[str]:
+        """
+        Retrieves the currently active model from the Lemonade server.
+
+        Returns:
+            Optional[str]: The name of the current model or None
+        """
+        return get_active_model(self.base_url)
+    
+    def load_model(self, model_name: str, **kwargs) -> Dict[str, Any]:
+        """
+        Loads a specific model on the Lemonade server.
+
+        Args:
+            model_name (str): The name of the model to load
+            **kwargs: Additional parameters for loading the model
+
+        Returns:
+            Dict[str, Any]: Response from the server
+        """
+        url = f"{self.base_url}/api/v1/load_model"
+
+        payload = {
+            "model": model_name,
+            **kwargs
+        }
+
+        try:
+            response = send_request(url, payload, session=self.session)
+            return response
+        except Exception as e:
+            print(f"Error loading model: {e}")
+            return {"error": str(e)}
+    
+    def unload_model(self) -> Dict[str, Any]:
+        """
+        Unloads the current model from the Lemonade server.
+
+        Returns:
+            Dict[str, Any]: Response from the server
+        """
+        url = f"{self.base_url}/api/v1/unload_model"
+
+        try:
+            response = send_request(url, {}, session=self.session)
+            return response
+        except Exception as e:
+            print(f"Error unloading model: {e}")
+            return {"error": str(e)}
+
+    def embeddings(self, input: str, model: str, **kwargs) -> Dict[str, Any]:
+        """
+        Sends an embedding request to the Lemonade server.
+
+        Args:
+            input (str): The text or list of texts to embed
+            model (str): The name of the embedding model to use (e.g., "nomic-embed-text-v1-GGUF")
+            **kwargs: Additional parameters for the request
+                - encoding_format (str): "float" (default) or "base64"
+
+        Returns:
+            Dict[str, Any]: The response containing the embedding vectors
+        """
+        url = f"{self.base_url}/api/v1/embeddings"
+
+        payload = build_embedding_payload(input, model, **kwargs)
+
+        try:
+            response = send_request(url, payload, session=self.session)
+            return response
+        except Exception as e:
+            print(f"Error in embedding request: {e}")
+            return {"error": str(e)}
+
+    def list_embedding_models(self) -> List[Dict[str, Any]]:
+        """
+        Retrieves only the embedding models from the Lemonade server.
+        Filters models by the 'embeddings' label.
+
+        Returns:
+            List[Dict[str, Any]]: List of available embedding models
+        """
+        all_models = self.list_models()
+        
+        # Filter models that have the 'embeddings' label
+        embedding_models = []
+        for model in all_models:
+            labels = model.get("labels", [])
+            if labels and "embeddings" in labels:
+                embedding_models.append(model)
+        
+        return embedding_models

lemonade_python_sdk-1.0.1/lemonade_integration/model_discovery.py

@@ -0,0 +1,131 @@
+"""
+Module for discovering and managing Lemonade models
+"""
+
+import requests
+import json
+from typing import List, Dict, Any, Optional
+from .port_scanner import find_available_lemonade_port
+
+
+def discover_lemonade_models(base_url: str = "http://localhost:8000") -> List[Dict[str, Any]]:
+    """
+    Scans for available models on the Lemonade server.
+
+    Args:
+        base_url (str): The base URL of the Lemonade server
+
+    Returns:
+        List[Dict[str, Any]]: List of found models with their properties
+    """
+    # Try to find the correct port if the default port is not available
+    if "localhost" in base_url or "127.0.0.1" in base_url:
+        # Extract port from URL
+        import re
+        port_match = re.search(r':(\d+)', base_url)
+        if port_match:
+            current_port = int(port_match.group(1))
+            available_port = find_available_lemonade_port(ports=[current_port])
+            if available_port and available_port != current_port:
+                # Replace the port in the URL
+                base_url = base_url.replace(f':{current_port}', f':{available_port}')
+    
+    url = f"{base_url}/api/v1/models"
+    
+    try:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+        
+        # Lemonade returns models under 'data' key
+        models = data.get('data', [])
+        
+        # Format the models to match the expected structure
+        formatted_models = []
+        for model in models:
+            formatted_model = {
+                'id': model.get('id', model.get('name', 'unknown')),
+                'name': model.get('name', model.get('id', 'unknown')),
+                'object': model.get('object', 'model'),
+                'created': model.get('created', 0),
+                'owned_by': model.get('owned_by', 'unknown'),
+                'source': 'external',
+                'provider': 'Lemonade',
+                'status': 'Available',
+                'size_gb': 0,  # Lemonade doesn't provide size info in the API
+                'local_path': f"lemonade://{model.get('name', model.get('id', 'unknown'))}",
+                'backend': 'lemonade'
+            }
+            formatted_models.append(formatted_model)
+        
+        return formatted_models
+    except requests.exceptions.RequestException as e:
+        print(f"Error retrieving models from {base_url}: {e}")
+        return []
+    except json.JSONDecodeError as e:
+        print(f"Error parsing response from {base_url}: {e}")
+        return []
+
+
+def get_active_model(base_url: str = "http://localhost:8000") -> Optional[str]:
+    """
+    Retrieves the currently active model from the Lemonade server.
+
+    Args:
+        base_url (str): The base URL of the Lemonade server
+
+    Returns:
+        Optional[str]: The name of the active model or None
+    """
+    # Lemonade has no direct endpoint for the active model,
+    # so we try various known endpoints
+    endpoints_to_try = [
+        f"{base_url}/api/v1/current_model",
+        f"{base_url}/api/v1/model",
+        f"{base_url}/api/v1/status"
+    ]
+
+    for endpoint in endpoints_to_try:
+        try:
+            response = requests.get(endpoint, timeout=5)
+            if response.status_code == 200:
+                data = response.json()
+
+                # Try various possible field names for the active model
+                for field in ['model', 'current_model', 'active_model', 'name']:
+                    if field in data:
+                        return data[field]
+
+                # If the result is directly a string
+                if isinstance(data, str):
+                    return data
+
+        except (requests.exceptions.RequestException, json.JSONDecodeError):
+            continue
+
+    # As a fallback, try to get the first available model
+    available_models = discover_lemonade_models(base_url)
+    if available_models:
+        return available_models[0]['name']
+
+    return None
+
+
+def verify_model_availability(model_name: str, base_url: str = "http://localhost:8000") -> bool:
+    """
+    Checks if a specific model is available on the Lemonade server.
+
+    Args:
+        model_name (str): The name of the model to check
+        base_url (str): The base URL of the Lemonade server
+
+    Returns:
+        bool: True if the model is available, otherwise False
+    """
+    available_models = discover_lemonade_models(base_url)
+    
+    for model in available_models:
+        if model['name'] == model_name or model['id'] == model_name:
+            return True
+    
+    return False

lemonade_python_sdk-1.0.1/lemonade_integration/port_scanner.py

@@ -0,0 +1,114 @@
+"""
+Module for scanning available Lemonade servers
+"""
+
+import socket
+import requests
+from typing import List, Optional
+
+
+def is_port_open(host: str, port: int, timeout: float = 0.5) -> bool:
+    """
+    Checks if a TCP port is reachable on the host.
+
+    Args:
+        host (str): The host on which to check the port
+        port (int): The port to check
+        timeout (float): Timeout for the connection (default: 0.5 seconds)
+
+    Returns:
+        bool: True if the port is reachable, otherwise False
+    """
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except Exception:
+        return False
+
+
+def verify_lemonade_server(port: int, host: str = "127.0.0.1") -> bool:
+    """
+    Checks if a Lemonade server is running on the specified port.
+
+    Args:
+        port (int): The port to check
+        host (str): The host (default: 127.0.0.1)
+
+    Returns:
+        bool: True if a Lemonade server is running on the port, otherwise False
+    """
+    url = f"http://{host}:{port}/api/v1/models"
+
+    try:
+        response = requests.get(url, timeout=2)
+        # A Lemonade server should respond to this endpoint with a list of models
+        if response.status_code == 200:
+            try:
+                data = response.json()
+                # Check if the response has the expected format
+                if "data" in data or isinstance(data, list):
+                    return True
+            except ValueError:
+                # If the response is not valid JSON, it's probably not a Lemonade server
+                pass
+    except requests.RequestException:
+        pass
+
+    return False
+
+
+def find_available_lemonade_port(
+    host: str = "127.0.0.1",
+    ports: List[int] = None
+) -> Optional[int]:
+    """
+    Finds the first available port on which a Lemonade server is running.
+
+    Args:
+        host (str): The host to search on (default: 127.0.0.1)
+        ports (List[int]): List of ports to check (default: [8000, 8020, 8040, 8060, 8080, 9000])
+
+    Returns:
+        Optional[int]: The first found port with a Lemonade server, or None
+    """
+    if ports is None:
+        # Standard Lemonade ports
+        ports = [8000, 8020, 8040, 8060, 8080, 9000]
+    
+    for port in ports:
+        if is_port_open(host, port):
+            if verify_lemonade_server(port, host):
+                return port
+    
+    return None
+
+
+def scan_multiple_hosts_for_lemonade(
+    hosts: List[str] = None,
+    ports: List[int] = None
+) -> List[tuple]:
+    """
+    Scans multiple hosts and ports for available Lemonade servers.
+
+    Args:
+        hosts (List[str]): List of hosts to scan
+        ports (List[int]): List of ports to scan
+
+    Returns:
+        List[tuple]: List of (host, port) tuples where Lemonade servers were found
+    """
+    if hosts is None:
+        hosts = ["127.0.0.1", "localhost"]
+
+    if ports is None:
+        ports = [8000, 8020, 8040, 8060, 8080, 9000]
+    
+    available_servers = []
+    
+    for host in hosts:
+        for port in ports:
+            if is_port_open(host, port):
+                if verify_lemonade_server(port, host):
+                    available_servers.append((host, port))
+    
+    return available_servers

lemonade_python_sdk-1.0.1/lemonade_integration/request_builder.py

@@ -0,0 +1,137 @@
+"""
+Module for building API requests to the Lemonade server
+"""
+
+import requests
+import json
+from typing import Dict, Any, List, Optional
+
+
+def build_chat_completion_payload(model: str, messages: List[Dict[str, str]], **kwargs) -> Dict[str, Any]:
+    """
+    Creates the payload for chat completion requests.
+
+    Args:
+        model (str): The name of the model to use
+        messages (List[Dict[str, str]]): The messages for the conversation
+        **kwargs: Additional parameters for the request
+
+    Returns:
+        Dict[str, Any]: The finished payload for the request
+    """
+    payload = {
+        "model": model,
+        "messages": messages,
+        "stream": kwargs.get("stream", False),
+    }
+
+    # Add optional parameters if they exist
+    optional_params = [
+        "temperature", "top_p", "top_k", "max_tokens", "stop",
+        "presence_penalty", "frequency_penalty", "repetition_penalty"
+    ]
+
+    for param in optional_params:
+        if param in kwargs and kwargs[param] is not None:
+            payload[param] = kwargs[param]
+
+    # Handle special parameters for Lemonade
+    if "options" in kwargs:
+        payload["options"] = kwargs["options"]
+
+    return payload
+
+
+def build_model_load_payload(model_name: str, **kwargs) -> Dict[str, Any]:
+    """
+    Creates the payload for loading a model.
+
+    Args:
+        model_name (str): The name of the model to load
+        **kwargs: Additional parameters for loading the model
+
+    Returns:
+        Dict[str, Any]: The finished payload for loading the model
+    """
+    payload = {
+        "model": model_name
+    }
+
+    # Add optional parameters
+    for key, value in kwargs.items():
+        payload[key] = value
+
+    return payload
+
+
+def send_request(url: str, payload: Dict[str, Any], headers: Optional[Dict[str, str]] = None, session: Optional[requests.Session] = None, method: str = "POST") -> Dict[str, Any]:
+    """
+    Sends a request to the Lemonade server.
+
+    Args:
+        url (str): The target URL for the request
+        payload (Dict[str, Any]): The payload to send
+        headers (Optional[Dict[str, str]]): Optional headers for the request
+        session (Optional[requests.Session]): Optional session for the request
+        method (str): HTTP method to use ("POST" or "GET")
+
+    Returns:
+        Dict[str, Any]: The response from the server
+    """
+    if headers is None:
+        headers = {
+            "Content-Type": "application/json"
+        }
+
+    # Use either the passed session or create a temporary one
+    req_session = session or requests.Session()
+
+    try:
+        if method.upper() == "POST":
+            response = req_session.post(url, json=payload, headers=headers, timeout=30)
+        elif method.upper() == "GET":
+            response = req_session.get(url, headers=headers, timeout=30, params=payload if payload else None)
+        else:
+            return {"error": f"Unsupported HTTP method: {method}"}
+        
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.HTTPError as e:
+        print(f"HTTP error in request to {url}: {e}")
+        if response is not None:
+            print(f"Response body: {response.text}")
+        return {"error": f"HTTP Error: {e}"}
+    except requests.exceptions.RequestException as e:
+        print(f"Error in request to {url}: {e}")
+        return {"error": f"Request Error: {e}"}
+    except json.JSONDecodeError as e:
+        print(f"Error parsing response from {url}: {e}")
+        return {"error": f"JSON Decode Error: {e}"}
+    finally:
+        # If no session was passed, close the temporary one here
+        if session is None:
+            req_session.close()
+
+
+def build_embedding_payload(input_text: str, model: str, **kwargs) -> Dict[str, Any]:
+    """
+    Creates the payload for embedding requests.
+
+    Args:
+        input_text (str): The text for the embedding
+        model (str): The name of the model to use
+        **kwargs: Additional parameters for the request
+
+    Returns:
+        Dict[str, Any]: The finished payload for the embedding request
+    """
+    payload = {
+        "input": input_text,
+        "model": model
+    }
+
+    # Add optional parameters
+    for key, value in kwargs.items():
+        payload[key] = value
+
+    return payload

lemonade_python_sdk-1.0.1/lemonade_integration/utils.py

@@ -0,0 +1,118 @@
+"""
+Helper functions for Lemonade integration
+"""
+
+import json
+from typing import List, Dict, Any
+
+
+def format_messages_for_lemonade(messages: List[Dict[str, str]]) -> List[Dict[str, str]]:
+    """
+    Formats messages in Lemonade-compatible format.
+
+    Args:
+        messages (List[Dict[str, str]]): The messages to format
+
+    Returns:
+        List[Dict[str, str]]: The formatted messages
+    """
+    # Lemonade expects messages in OpenAI-like format
+    # Ensure each message has a 'role' and 'content' field
+    formatted_messages = []
+    for msg in messages:
+        formatted_msg = {
+            "role": msg.get("role", "user"),
+            "content": msg.get("content", "")
+        }
+        formatted_messages.append(formatted_msg)
+
+    return formatted_messages
+
+
+def extract_model_info_from_response(response: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Extracts relevant model information from the response.
+
+    Args:
+        response (Dict[str, Any]): The response from the server
+
+    Returns:
+        Dict[str, Any]: Extracted model information
+    """
+    model_info = {}
+
+    # Try to extract various possible fields
+    if "model" in response:
+        model_info["model"] = response["model"]
+
+    if "usage" in response:
+        model_info["usage"] = response["usage"]
+
+    if "choices" in response:
+        model_info["choices"] = response["choices"]
+
+    if "created" in response:
+        model_info["created"] = response["created"]
+
+    # For model list responses
+    if "data" in response:
+        model_info["data"] = response["data"]
+
+    return model_info
+
+
+def validate_lemonade_response(response: Dict[str, Any]) -> bool:
+    """
+    Validates whether the response from the Lemonade server has the expected format.
+
+    Args:
+        response (Dict[str, Any]): The response from the server
+
+    Returns:
+        bool: True if the response is valid, otherwise False
+    """
+    # Check for basic fields that a valid response should have
+    if not isinstance(response, dict):
+        return False
+
+    # For chat completion responses, there should be choices
+    if "choices" in response:
+        if not isinstance(response["choices"], list) or len(response["choices"]) == 0:
+            return False
+
+    # For model list responses, there should be data
+    if "data" in response:
+        if not isinstance(response["data"], list):
+            return False
+
+    return True
+
+
+def sanitize_model_name(model_name: str) -> str:
+    """
+    Cleans the model name of invalid characters.
+
+    Args:
+        model_name (str): The model name to clean
+
+    Returns:
+        str: The cleaned model name
+    """
+    # Remove or replace invalid characters
+    sanitized = model_name.strip()
+    # Replace spaces with underscores if necessary
+    sanitized = sanitized.replace(" ", "_")
+    return sanitized
+
+
+def format_error_message(error: Exception) -> str:
+    """
+    Formats an error message for output.
+
+    Args:
+        error (Exception): The exception that occurred
+
+    Returns:
+        str: Formatted error message
+    """
+    return f"Error: {type(error).__name__} - {str(error)}"

lemonade_python_sdk-1.0.1/lemonade_python_sdk.egg-info/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: lemonade-python-sdk
+Version: 1.0.1
+Summary: A clean interface for interacting with the Lemonade LLM server
+Home-page: https://github.com/Tetramatrix/lemonade-python-sdk
+Author: Your Name
+Author-email: your.email@example.com
+Project-URL: Bug Reports, https://github.com/Tetramatrix/lemonade-python-sdk/issues
+Project-URL: Source, https://github.com/Tetramatrix/lemonade-python-sdk
+Keywords: llm,ai,lemonade,sdk,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 🍋 Lemonade Python SDK
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A robust, production-grade Python wrapper for the **Lemonade C++ Backend**. 
+
+This SDK provides a clean, pythonic interface for interacting with local LLMs running on Lemonade. It was built to power **Sorana** (a visual workspace for AI), extracting the core integration logic into a standalone, open-source library for the developer community.
+
+## 🚀 Key Features
+
+* **Auto-Discovery:** Automatically scans multiple ports and hosts to find active Lemonade instances.
+* **Low-Overhead Architecture:** Designed as a thin, efficient wrapper to leverage Lemonade's C++ performance with minimal Python latency.
+* **Health Checks & Recovery:** Built-in utilities to verify server status and handle connection drops.
+* **Type-Safe Client:** Full Python type hinting for better developer experience (IDE autocompletion).
+* **Model Management:** Simple API to load, unload, and list models dynamically.
+* **Embeddings API:** Generate text embeddings for semantic search, RAG, and clustering (FLM & llamacpp backends).
+
+## 📦 Installation
+
+```bash
+pip install .
+```
+
+Alternatively, you can install it directly from GitHub:
+
+```bash
+pip install git+[https://github.com/Tetramatrix/lemonade-python-sdk.git](https://github.com/Tetramatrix/lemonade-python-sdk.git)
+```
+
+## ⚡ Quick Start
+
+### 1. Connecting to Lemonade
+
+The SDK automatically handles port discovery, so you don't need to hardcode localhost:8000.
+
+```python
+from lemonade_integration.client import LemonadeClient
+from lemonade_integration.port_scanner import find_available_lemonade_port
+
+# Auto-discover running instance
+port = find_available_lemonade_port()
+if port:
+    client = LemonadeClient(base_url=f"http://localhost:{port}")
+    if client.health_check():
+        print(f"Connected to Lemonade on port {port}")
+else:
+    print("No Lemonade instance found.")
+```
+
+### 2. Chat Completion
+
+```python
+response = client.chat_completion(
+    model="Llama-3-8B-Instruct",
+    messages=[
+        {"role": "system", "content": "You are a helpful coding assistant."},
+        {"role": "user", "content": "Write a Hello World in C++"}
+    ],
+    temperature=0.7
+)
+
+print(response['choices'][0]['message']['content'])
+```
+
+### 3. Model Management
+
+```python
+# List all available models
+models = client.list_models()
+for m in models:
+    print(f"Found model: {m['id']}")
+
+# Load a specific model into memory
+client.load_model("Mistral-7B-v0.1")
+```
+
+### 4. Embeddings (NEW)
+
+Generate text embeddings for semantic search, RAG pipelines, and clustering.
+
+```python
+# List available embedding models (filtered by 'embeddings' label)
+embedding_models = client.list_embedding_models()
+for model in embedding_models:
+    print(f"Embedding model: {model['id']}")
+
+# Generate embeddings for single text
+response = client.embeddings(
+    input="Hello, world!",
+    model="nomic-embed-text-v1-GGUF"
+)
+
+embedding_vector = response["data"][0]["embedding"]
+print(f"Vector length: {len(embedding_vector)}")
+
+# Generate embeddings for multiple texts
+texts = ["Text 1", "Text 2", "Text 3"]
+response = client.embeddings(
+    input=texts,
+    model="nomic-embed-text-v1-GGUF"
+)
+
+for item in response["data"]:
+    print(f"Text {item['index']}: {len(item['embedding'])} dimensions")
+```
+
+**Supported Backends:**
+- ✅ **FLM (FastFlowLM)** - NPU-accelerated on Windows
+- ✅ **llamacpp** (.GGUF models) - CPU/GPU
+- ❌ ONNX/OGA - Not supported
+
+### 🖼️ Production Showcase: [Sorana](https://tetramatrix.github.io/Sorana/)
+This SDK was extracted from the core engine of [Sorana](https://tetramatrix.github.io/Sorana/), a professional visual workspace for AI. It demonstrates the SDK's capability to handle complex, real-world requirements on AMD Ryzen AI hardware:
+
+* **Low Latency:** Powers sub-second response times for multi-model chat interfaces.
+* **Dynamic Workflows:** Manages the loading and unloading of 20+ different LLMs based on user activity to optimize local NPU/GPU memory.
+* **Zero-Config UX:** Uses the built-in port scanner to automatically connect the Sorana frontend to the Lemonade backend without user intervention.
+
+## 🛠️ Project Structure
+
+* **client.py:** Main entry point for API interactions (chat, embeddings, model management).
+* **port_scanner.py:** Utilities for detecting Lemonade instances across ports (8000-9000).
+* **model_discovery.py:** Logic for fetching and parsing model metadata.
+* **request_builder.py:** Helper functions to construct compliant payloads (chat, embeddings).
+* **utils.py:** Additional utility functions.
+
+## 📚 Documentation
+
+* **[Embeddings API](docs/embeddings_api.md)** - Complete guide for using embeddings
+* [Lemonade Server Docs](https://lemonade-server.ai/docs/server/server_spec/) - Official Lemonade documentation
+
+## 🤝 Contributing
+
+Contributions are welcome! This project is intended to help the AMD Ryzen AI and Lemonade community build downstream applications faster.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

lemonade_python_sdk-1.0.1/lemonade_python_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+setup.py
+lemonade_integration/__init__.py
+lemonade_integration/client.py
+lemonade_integration/model_discovery.py
+lemonade_integration/port_scanner.py
+lemonade_integration/request_builder.py
+lemonade_integration/utils.py
+lemonade_python_sdk.egg-info/PKG-INFO
+lemonade_python_sdk.egg-info/SOURCES.txt
+lemonade_python_sdk.egg-info/dependency_links.txt
+lemonade_python_sdk.egg-info/requires.txt
+lemonade_python_sdk.egg-info/top_level.txt

lemonade_python_sdk-1.0.1/lemonade_python_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lemonade_python_sdk-1.0.1/lemonade_python_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.25.0
+
+[dev]
+pytest>=6.0
+pytest-cov
+flake8

lemonade_python_sdk-1.0.1/lemonade_python_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+lemonade_integration

lemonade_python_sdk-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lemonade_python_sdk-1.0.1/setup.py

@@ -0,0 +1,51 @@
+"""
+Setup file for the Lemonade integration module
+This file allows installation as a standalone package
+"""
+
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+with open("LICENSE", "r", encoding="utf-8") as fh:
+    license_content = fh.read()
+
+setup(
+    name="lemonade-python-sdk",
+    version="1.0.1",
+    author="Your Name",
+    author_email="your.email@example.com",
+    description="A clean interface for interacting with the Lemonade LLM server",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/Tetramatrix/lemonade-python-sdk",
+    packages=find_packages(),
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.8",
+    install_requires=[
+        "requests>=2.25.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=6.0",
+            "pytest-cov",
+            "flake8",
+        ],
+    },
+    keywords="llm, ai, lemonade, sdk, api",
+    project_urls={
+        "Bug Reports": "https://github.com/Tetramatrix/lemonade-python-sdk/issues",
+        "Source": "https://github.com/Tetramatrix/lemonade-python-sdk",
+    },
+)