gseai 0.1.0__tar.gz

gseai-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: gseai
+Version: 0.1.0
+Summary: Python client for the GSE AI LMStudio server
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1

gseai-0.1.0/gseai/__init__.py

@@ -0,0 +1,3 @@
+from .server import GSEAIServer
+
+__all__ = ["GSEAIServer"]

gseai-0.1.0/gseai/server.py

@@ -0,0 +1,414 @@
+"""Client for the GSE AI LMStudio server's REST API v1."""
+
+from collections.abc import Generator, Iterator
+from typing import Any
+
+import httpx
+
+
+class GSEAIServer:
+    """Client for the GSE AI LMStudio server.
+
+    Args:
+        api_token: Bearer token for authentication.
+        host: Hostname of the server.
+        port: Port the server listens on.
+    """
+
+    def __init__(
+        self,
+        api_token: str,
+        host: str = "gseai.gse.buffalo.edu",
+        port: int = 11434,
+    ) -> None:
+        self.base_url = f"http://{host}:{port}"
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {api_token}"},
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # -------------------------------------------------------------------------
+    # Native REST API v1  (/api/v1/)
+    # -------------------------------------------------------------------------
+
+    def list_models(self) -> dict:
+        """GET /api/v1/models — list available models."""
+        return self._client.get("/api/v1/models").raise_for_status().json()
+
+    def load_model(self, model: str, ttl: int | None = None) -> dict:
+        """POST /api/v1/models/load — load a model into memory.
+
+        Args:
+            model: Model identifier.
+            ttl: Idle time-to-live in seconds before the model is evicted.
+        """
+        body: dict[str, Any] = {"model": model}
+        if ttl is not None:
+            body["ttl"] = ttl
+        return self._client.post("/api/v1/models/load", json=body).raise_for_status().json()
+
+    def unload_model(self, model: str) -> dict:
+        """POST /api/v1/models/unload — unload a model from memory.
+
+        Args:
+            model: Model identifier.
+        """
+        return (
+            self._client.post("/api/v1/models/unload", json={"model": model})
+            .raise_for_status()
+            .json()
+        )
+
+    def download_model(self, model: str) -> dict:
+        """POST /api/v1/models/download — start downloading a model.
+
+        Args:
+            model: Model identifier to download.
+
+        Returns:
+            Dict containing a ``job_id`` for tracking download progress.
+        """
+        return (
+            self._client.post("/api/v1/models/download", json={"model": model})
+            .raise_for_status()
+            .json()
+        )
+
+    def get_download_status(self, job_id: str) -> dict:
+        """GET /api/v1/models/download/status/{job_id} — check download progress.
+
+        Args:
+            job_id: Job ID returned by :meth:`download_model`.
+        """
+        return (
+            self._client.get(f"/api/v1/models/download/status/{job_id}")
+            .raise_for_status()
+            .json()
+        )
+
+    def chat(
+        self,
+        model: str,
+        input: str | list[dict],
+        *,
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        top_k: int | None = None,
+        min_p: float | None = None,
+        repeat_penalty: float | None = None,
+        max_output_tokens: int | None = None,
+        reasoning: str | None = None,
+        context_length: int | None = None,
+        store: bool = True,
+        previous_response_id: str | None = None,
+        ttl: int | None = None,
+        integrations: list[dict] | None = None,
+        stream: bool = False,
+    ) -> dict | Generator[dict, None, None]:
+        """POST /api/v1/chat — generate a chat response.
+
+        Args:
+            model: Model identifier.
+            input: A string prompt or a list of message dicts.
+            system_prompt: Optional system message.
+            temperature: Sampling temperature (0–2).
+            top_p: Nucleus sampling probability (0–1).
+            top_k: Top-k sampling limit.
+            min_p: Minimum probability threshold (0–1).
+            repeat_penalty: Repetition penalty.
+            max_output_tokens: Maximum number of tokens to generate.
+            reasoning: Reasoning effort — "off", "low", "medium", "high", or "on".
+            context_length: Context window size override.
+            store: Whether to persist the conversation server-side (default True).
+            previous_response_id: ID of a prior response to continue.
+            ttl: Model idle time-to-live in seconds.
+            integrations: MCP servers or plugin configs.
+            stream: If True, return a generator of Server-Sent Event dicts.
+
+        Returns:
+            Response dict, or a generator of SSE event dicts when ``stream=True``.
+        """
+        body: dict[str, Any] = {"model": model, "input": input, "store": store}
+        if system_prompt is not None:
+            body["system_prompt"] = system_prompt
+        if temperature is not None:
+            body["temperature"] = temperature
+        if top_p is not None:
+            body["top_p"] = top_p
+        if top_k is not None:
+            body["top_k"] = top_k
+        if min_p is not None:
+            body["min_p"] = min_p
+        if repeat_penalty is not None:
+            body["repeat_penalty"] = repeat_penalty
+        if max_output_tokens is not None:
+            body["max_output_tokens"] = max_output_tokens
+        if reasoning is not None:
+            body["reasoning"] = reasoning
+        if context_length is not None:
+            body["context_length"] = context_length
+        if previous_response_id is not None:
+            body["previous_response_id"] = previous_response_id
+        if ttl is not None:
+            body["ttl"] = ttl
+        if integrations is not None:
+            body["integrations"] = integrations
+
+        if stream:
+            body["stream"] = True
+            return self._stream_sse("/api/v1/chat", body)
+        else:
+            return self._client.post("/api/v1/chat", json=body).raise_for_status().json()
+
+    # -------------------------------------------------------------------------
+    # OpenAI-compatible endpoints  (/v1/)
+    # -------------------------------------------------------------------------
+
+    def list_models_openai(self) -> dict:
+        """GET /v1/models — list models (OpenAI-compatible format)."""
+        return self._client.get("/v1/models").raise_for_status().json()
+
+    def chat_completions(
+        self,
+        model: str,
+        messages: list[dict],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        stream: bool = False,
+        top_p: float | None = None,
+        top_k: int | None = None,
+        stop: str | list[str] | None = None,
+        presence_penalty: float | None = None,
+        frequency_penalty: float | None = None,
+        repeat_penalty: float | None = None,
+        logit_bias: dict | None = None,
+        seed: int | None = None,
+        response_format: dict | None = None,
+        tools: list[dict] | None = None,
+        tool_choice: str | None = None,
+        ttl: int | None = None,
+    ) -> dict | Generator[dict, None, None]:
+        """POST /v1/chat/completions — OpenAI-compatible chat completions.
+
+        Args:
+            model: Model identifier.
+            messages: List of message dicts with ``role`` and ``content``.
+            temperature: Sampling temperature (0–2).
+            max_tokens: Maximum tokens to generate.
+            stream: If True, return a generator of SSE event dicts.
+            top_p: Nucleus sampling (0–1).
+            top_k: Top-k sampling limit.
+            stop: Stop sequence(s).
+            presence_penalty: Presence penalty (-2 to 2).
+            frequency_penalty: Frequency penalty (-2 to 2).
+            repeat_penalty: Repetition penalty.
+            logit_bias: Token probability bias adjustments.
+            seed: Random seed for reproducibility.
+            response_format: JSON schema for structured output.
+            tools: Function definitions for tool/function calling.
+            tool_choice: Tool selection mode — "auto", "none", or "required".
+            ttl: Model idle time-to-live in seconds.
+        """
+        body: dict[str, Any] = {"model": model, "messages": messages}
+        if temperature is not None:
+            body["temperature"] = temperature
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if top_p is not None:
+            body["top_p"] = top_p
+        if top_k is not None:
+            body["top_k"] = top_k
+        if stop is not None:
+            body["stop"] = stop
+        if presence_penalty is not None:
+            body["presence_penalty"] = presence_penalty
+        if frequency_penalty is not None:
+            body["frequency_penalty"] = frequency_penalty
+        if repeat_penalty is not None:
+            body["repeat_penalty"] = repeat_penalty
+        if logit_bias is not None:
+            body["logit_bias"] = logit_bias
+        if seed is not None:
+            body["seed"] = seed
+        if response_format is not None:
+            body["response_format"] = response_format
+        if tools is not None:
+            body["tools"] = tools
+        if tool_choice is not None:
+            body["tool_choice"] = tool_choice
+        if ttl is not None:
+            body["ttl"] = ttl
+
+        if stream:
+            body["stream"] = True
+            return self._stream_sse("/v1/chat/completions", body)
+        else:
+            return (
+                self._client.post("/v1/chat/completions", json=body).raise_for_status().json()
+            )
+
+    def completions(
+        self,
+        model: str,
+        prompt: str | list,
+        *,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        top_k: int | None = None,
+        stop: str | list[str] | None = None,
+        frequency_penalty: float | None = None,
+        presence_penalty: float | None = None,
+        stream: bool = False,
+        seed: int | None = None,
+        ttl: int | None = None,
+    ) -> dict | Generator[dict, None, None]:
+        """POST /v1/completions — legacy text completions.
+
+        Args:
+            model: Model identifier.
+            prompt: Input text or list of texts.
+            max_tokens: Maximum tokens to generate.
+            temperature: Sampling temperature (0–2).
+            top_p: Nucleus sampling (0–1).
+            top_k: Top-k sampling limit.
+            stop: Stop sequence(s).
+            frequency_penalty: Frequency penalty (-2 to 2).
+            presence_penalty: Presence penalty (-2 to 2).
+            stream: If True, return a generator of SSE event dicts.
+            seed: Random seed.
+            ttl: Model idle time-to-live in seconds.
+        """
+        body: dict[str, Any] = {"model": model, "prompt": prompt}
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if temperature is not None:
+            body["temperature"] = temperature
+        if top_p is not None:
+            body["top_p"] = top_p
+        if top_k is not None:
+            body["top_k"] = top_k
+        if stop is not None:
+            body["stop"] = stop
+        if frequency_penalty is not None:
+            body["frequency_penalty"] = frequency_penalty
+        if presence_penalty is not None:
+            body["presence_penalty"] = presence_penalty
+        if seed is not None:
+            body["seed"] = seed
+        if ttl is not None:
+            body["ttl"] = ttl
+
+        if stream:
+            body["stream"] = True
+            return self._stream_sse("/v1/completions", body)
+        else:
+            return self._client.post("/v1/completions", json=body).raise_for_status().json()
+
+    def embeddings(
+        self,
+        model: str,
+        input: str | list[str],
+        *,
+        encoding_format: str | None = None,
+        dimensions: int | None = None,
+    ) -> dict:
+        """POST /v1/embeddings — generate text embeddings.
+
+        Args:
+            model: Model identifier.
+            input: Text or list of texts to embed.
+            encoding_format: Output format — "float" or "base64".
+            dimensions: Target embedding dimensionality.
+        """
+        body: dict[str, Any] = {"model": model, "input": input}
+        if encoding_format is not None:
+            body["encoding_format"] = encoding_format
+        if dimensions is not None:
+            body["dimensions"] = dimensions
+        return self._client.post("/v1/embeddings", json=body).raise_for_status().json()
+
+    def responses(
+        self,
+        model: str,
+        messages: list[dict],
+        **kwargs: Any,
+    ) -> dict:
+        """POST /v1/responses — stateful chat responses (OpenAI-compatible).
+
+        Args:
+            model: Model identifier.
+            messages: List of message dicts with ``role`` and ``content``.
+            **kwargs: Additional parameters forwarded to the endpoint.
+        """
+        body: dict[str, Any] = {"model": model, "messages": messages, **kwargs}
+        return self._client.post("/v1/responses", json=body).raise_for_status().json()
+
+    # -------------------------------------------------------------------------
+    # Anthropic-compatible endpoint  (/v1/messages)
+    # -------------------------------------------------------------------------
+
+    def messages(
+        self,
+        model: str,
+        messages: list[dict],
+        max_tokens: int,
+        *,
+        system: str | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        top_k: int | None = None,
+    ) -> dict:
+        """POST /v1/messages — Anthropic-compatible messages API.
+
+        Args:
+            model: Model identifier.
+            messages: List of message dicts with ``role`` and ``content``.
+            max_tokens: Maximum tokens to generate (required by the API).
+            system: System prompt.
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling (0–1).
+            top_k: Top-k sampling limit.
+        """
+        body: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+        }
+        if system is not None:
+            body["system"] = system
+        if temperature is not None:
+            body["temperature"] = temperature
+        if top_p is not None:
+            body["top_p"] = top_p
+        if top_k is not None:
+            body["top_k"] = top_k
+        return self._client.post("/v1/messages", json=body).raise_for_status().json()
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    def _stream_sse(self, path: str, body: dict) -> Generator[dict, None, None]:
+        """POST to *path* and yield parsed Server-Sent Event data dicts."""
+        import json
+
+        with self._client.stream("POST", path, json=body) as response:
+            response.raise_for_status()
+            for line in response.iter_lines():
+                if line.startswith("data: "):
+                    payload = line[len("data: "):]
+                    if payload == "[DONE]":
+                        break
+                    yield json.loads(payload)

gseai-0.1.0/gseai.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: gseai
+Version: 0.1.0
+Summary: Python client for the GSE AI LMStudio server
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1

gseai-0.1.0/gseai.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+gseai/__init__.py
+gseai/server.py
+gseai.egg-info/PKG-INFO
+gseai.egg-info/SOURCES.txt
+gseai.egg-info/dependency_links.txt
+gseai.egg-info/requires.txt
+gseai.egg-info/top_level.txt

gseai-0.1.0/gseai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gseai-0.1.0/gseai.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.28.1

gseai-0.1.0/gseai.egg-info/top_level.txt

@@ -0,0 +1 @@
+gseai

gseai-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "gseai"
+version = "0.1.0"
+description = "Python client for the GSE AI LMStudio server"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+]
+
+[dependency-groups]
+dev = [
+    "sphinx>=9.1.0",
+    "sphinx-autodoc-typehints>=3.10.0",
+    "sphinx-rtd-theme>=3.1.0",
+]

gseai-0.1.0/setup.cfg

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