embed-client 0.0.1__py3-none-any.whl

embed_client/__init__.py

@@ -0,0 +1 @@
+ 

embed_client/async_client.py

@@ -0,0 +1,180 @@
+"""
+Async client for Embedding Service API (OpenAPI 3.0.2)
+
+- 100% type-annotated
+- English docstrings and examples
+- Ready for PyPi
+"""
+
+from typing import Any, Dict, List, Optional, Union
+import aiohttp
+
+class EmbeddingServiceError(Exception):
+    """Base exception for EmbeddingServiceAsyncClient."""
+
+class EmbeddingServiceConnectionError(EmbeddingServiceError):
+    """Raised when the service is unavailable or connection fails."""
+
+class EmbeddingServiceHTTPError(EmbeddingServiceError):
+    """Raised for HTTP errors (4xx, 5xx)."""
+    def __init__(self, status: int, message: str):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+
+class EmbeddingServiceAPIError(EmbeddingServiceError):
+    """Raised for errors returned by the API in the response body."""
+    def __init__(self, error: Any):
+        super().__init__(f"API error: {error}")
+        self.error = error
+
+class EmbeddingServiceAsyncClient:
+    """
+    Asynchronous client for the Embedding Service API.
+    Args:
+        base_url (str): Base URL of the embedding service (e.g., "http://localhost").
+        port (int): Port of the embedding service (e.g., 8001).
+    Raises:
+        ValueError: If base_url or port is not provided.
+    """
+    def __init__(self, base_url: str, port: int):
+        if not base_url:
+            raise ValueError("base_url must be provided.")
+        if port is None:
+            raise ValueError("port must be provided.")
+        self.base_url = base_url.rstrip("/")
+        self.port = port
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    def _make_url(self, path: str, base_url: Optional[str] = None, port: Optional[int] = None) -> str:
+        url = (base_url or self.base_url).rstrip("/")
+        port_val = port if port is not None else self.port
+        return f"{url}:{port_val}{path}"
+
+    async def __aenter__(self):
+        self._session = aiohttp.ClientSession()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def health(self, base_url: Optional[str] = None, port: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Check the health of the service.
+        Args:
+            base_url (str, optional): Override base URL.
+            port (int, optional): Override port.
+        Returns:
+            dict: Health status and model info.
+        """
+        url = self._make_url("/health", base_url, port)
+        try:
+            async with self._session.get(url) as resp:
+                await self._raise_for_status(resp)
+                return await resp.json()
+        except EmbeddingServiceHTTPError:
+            raise
+        except EmbeddingServiceConnectionError:
+            raise
+        except aiohttp.ClientConnectionError as e:
+            raise EmbeddingServiceConnectionError(f"Connection error: {e}") from e
+        except aiohttp.ClientResponseError as e:
+            raise EmbeddingServiceHTTPError(e.status, e.message) from e
+        except Exception as e:
+            raise EmbeddingServiceError(f"Unexpected error: {e}") from e
+
+    async def get_openapi_schema(self, base_url: Optional[str] = None, port: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Get the OpenAPI schema of the service.
+        Args:
+            base_url (str, optional): Override base URL.
+            port (int, optional): Override port.
+        Returns:
+            dict: OpenAPI schema.
+        """
+        url = self._make_url("/openapi.json", base_url, port)
+        try:
+            async with self._session.get(url) as resp:
+                await self._raise_for_status(resp)
+                return await resp.json()
+        except EmbeddingServiceHTTPError:
+            raise
+        except EmbeddingServiceConnectionError:
+            raise
+        except aiohttp.ClientConnectionError as e:
+            raise EmbeddingServiceConnectionError(f"Connection error: {e}") from e
+        except aiohttp.ClientResponseError as e:
+            raise EmbeddingServiceHTTPError(e.status, e.message) from e
+        except Exception as e:
+            raise EmbeddingServiceError(f"Unexpected error: {e}") from e
+
+    async def get_commands(self, base_url: Optional[str] = None, port: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Get the list of available commands.
+        Args:
+            base_url (str, optional): Override base URL.
+            port (int, optional): Override port.
+        Returns:
+            dict: List of commands and their descriptions.
+        """
+        url = self._make_url("/api/commands", base_url, port)
+        try:
+            async with self._session.get(url) as resp:
+                await self._raise_for_status(resp)
+                return await resp.json()
+        except EmbeddingServiceHTTPError:
+            raise
+        except EmbeddingServiceConnectionError:
+            raise
+        except aiohttp.ClientConnectionError as e:
+            raise EmbeddingServiceConnectionError(f"Connection error: {e}") from e
+        except aiohttp.ClientResponseError as e:
+            raise EmbeddingServiceHTTPError(e.status, e.message) from e
+        except Exception as e:
+            raise EmbeddingServiceError(f"Unexpected error: {e}") from e
+
+    async def cmd(self, command: str, params: Optional[Dict[str, Any]] = None, base_url: Optional[str] = None, port: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Execute a command via JSON-RPC protocol.
+        Args:
+            command (str): Command to execute (embed, models, health, help, config).
+            params (dict, optional): Parameters for the command.
+            base_url (str, optional): Override base URL.
+            port (int, optional): Override port.
+        Returns:
+            dict: Command execution result.
+        """
+        url = self._make_url("/cmd", base_url, port)
+        payload = {"command": command}
+        if params is not None:
+            payload["params"] = params
+        try:
+            async with self._session.post(url, json=payload) as resp:
+                await self._raise_for_status(resp)
+                data = await resp.json()
+                # Обработка ошибок, возвращаемых сервером в теле ответа
+                if "error" in data:
+                    raise EmbeddingServiceAPIError(data["error"])
+                return data
+        except EmbeddingServiceAPIError:
+            raise
+        except EmbeddingServiceHTTPError:
+            raise
+        except EmbeddingServiceConnectionError:
+            raise
+        except aiohttp.ClientConnectionError as e:
+            raise EmbeddingServiceConnectionError(f"Connection error: {e}") from e
+        except aiohttp.ClientResponseError as e:
+            raise EmbeddingServiceHTTPError(e.status, e.message) from e
+        except Exception as e:
+            raise EmbeddingServiceError(f"Unexpected error: {e}") from e
+
+    async def _raise_for_status(self, resp: aiohttp.ClientResponse):
+        try:
+            resp.raise_for_status()
+        except aiohttp.ClientResponseError as e:
+            raise EmbeddingServiceHTTPError(e.status, e.message) from e
+
+    # TODO: Add methods for /cmd, /api/commands, etc. 

embed_client/example_async_usage.py

@@ -0,0 +1,94 @@
+"""
+Example usage of EmbeddingServiceAsyncClient.
+
+This example demonstrates how to use the async client to check the health of the embedding service,
+request embeddings, and handle all possible exceptions.
+
+Run this script with:
+    python -m asyncio embed_client/example_async_usage.py --base-url http://localhost --port 8001
+
+You can also set EMBED_CLIENT_BASE_URL and EMBED_CLIENT_PORT environment variables.
+"""
+
+import asyncio
+import sys
+import os
+from embed_client.async_client import (
+    EmbeddingServiceAsyncClient,
+    EmbeddingServiceConnectionError,
+    EmbeddingServiceHTTPError,
+    EmbeddingServiceAPIError,
+    EmbeddingServiceError,
+)
+
+def get_params():
+    base_url = None
+    port = None
+    for i, arg in enumerate(sys.argv):
+        if arg in ("--base-url", "-b") and i + 1 < len(sys.argv):
+            base_url = sys.argv[i + 1]
+        if arg in ("--port", "-p") and i + 1 < len(sys.argv):
+            port = sys.argv[i + 1]
+    if not base_url:
+        base_url = os.environ.get("EMBED_CLIENT_BASE_URL")
+    if not port:
+        port = os.environ.get("EMBED_CLIENT_PORT")
+    if not base_url or not port:
+        print("Error: base_url and port must be provided via --base-url/--port arguments or EMBED_CLIENT_BASE_URL/EMBED_CLIENT_PORT environment variables.")
+        sys.exit(1)
+        return None, None
+    return base_url, int(port)
+
+async def main():
+    base_url, port = get_params()
+    # Always use try/except to handle all possible errors
+    try:
+        async with EmbeddingServiceAsyncClient(base_url=base_url, port=port) as client:
+            # Check health
+            try:
+                health = await client.health()
+                print("Service health:", health)
+            except EmbeddingServiceConnectionError as e:
+                print("[Connection error]", e)
+                return
+            except EmbeddingServiceHTTPError as e:
+                print(f"[HTTP error] {e.status}: {e.message}")
+                return
+            except EmbeddingServiceError as e:
+                print("[Other error]", e)
+                return
+
+            # Request embeddings for a list of texts
+            texts = ["hello world", "test embedding"]
+            try:
+                result = await client.cmd("embed", params={"texts": texts})
+                vectors = result["result"]
+                print(f"Embeddings for {len(texts)} texts:")
+                for i, vec in enumerate(vectors):
+                    print(f"  Text: {texts[i]!r}\n  Vector: {vec[:5]}... (total {len(vec)} dims)")
+            except EmbeddingServiceAPIError as e:
+                print("[API error]", e.error)
+            except EmbeddingServiceHTTPError as e:
+                print(f"[HTTP error] {e.status}: {e.message}")
+            except EmbeddingServiceConnectionError as e:
+                print("[Connection error]", e)
+            except EmbeddingServiceError as e:
+                print("[Other error]", e)
+
+            # Example: error handling for invalid command
+            try:
+                await client.cmd("not_a_command")
+            except EmbeddingServiceAPIError as e:
+                print("[API error for invalid command]", e.error)
+
+            # Example: error handling for empty texts
+            try:
+                await client.cmd("embed", params={"texts": []})
+            except EmbeddingServiceAPIError as e:
+                print("[API error for empty texts]", e.error)
+
+    except Exception as e:
+        print("[Unexpected error]", e)
+
+if __name__ == "__main__":
+    asyncio.run(main()) 

embed_client/example_async_usage_ru.py

@@ -0,0 +1,94 @@
+"""
+Example usage of EmbeddingServiceAsyncClient.
+
+This example demonstrates how to use the async client to check the health of the embedding service,
+request embeddings, and handle all possible exceptions.
+
+Run this script with:
+    python -m asyncio embed_client/example_async_usage_ru.py --base-url http://localhost --port 8001
+
+You can also set EMBED_CLIENT_BASE_URL and EMBED_CLIENT_PORT environment variables.
+"""
+
+import asyncio
+import sys
+import os
+from embed_client.async_client import (
+    EmbeddingServiceAsyncClient,
+    EmbeddingServiceConnectionError,
+    EmbeddingServiceHTTPError,
+    EmbeddingServiceAPIError,
+    EmbeddingServiceError,
+)
+
+def get_params():
+    base_url = None
+    port = None
+    for i, arg in enumerate(sys.argv):
+        if arg in ("--base-url", "-b") and i + 1 < len(sys.argv):
+            base_url = sys.argv[i + 1]
+        if arg in ("--port", "-p") and i + 1 < len(sys.argv):
+            port = sys.argv[i + 1]
+    if not base_url:
+        base_url = os.environ.get("EMBED_CLIENT_BASE_URL")
+    if not port:
+        port = os.environ.get("EMBED_CLIENT_PORT")
+    if not base_url or not port:
+        print("Error: base_url and port must be provided via --base-url/--port arguments or EMBED_CLIENT_BASE_URL/EMBED_CLIENT_PORT environment variables.")
+        sys.exit(1)
+        return None, None
+    return base_url, int(port)
+
+async def main():
+    base_url, port = get_params()
+    # Always use try/except to handle all possible errors
+    try:
+        async with EmbeddingServiceAsyncClient(base_url=base_url, port=port) as client:
+            # Check health
+            try:
+                health = await client.health()
+                print("Service health:", health)
+            except EmbeddingServiceConnectionError as e:
+                print("[Connection error]", e)
+                return
+            except EmbeddingServiceHTTPError as e:
+                print(f"[HTTP error] {e.status}: {e.message}")
+                return
+            except EmbeddingServiceError as e:
+                print("[Other error]", e)
+                return
+
+            # Request embeddings for a list of texts
+            texts = ["hello world", "test embedding"]
+            try:
+                result = await client.cmd("embed", params={"texts": texts})
+                vectors = result["result"]
+                print(f"Embeddings for {len(texts)} texts:")
+                for i, vec in enumerate(vectors):
+                    print(f"  Text: {texts[i]!r}\n  Vector: {vec[:5]}... (total {len(vec)} dims)")
+            except EmbeddingServiceAPIError as e:
+                print("[API error]", e.error)
+            except EmbeddingServiceHTTPError as e:
+                print(f"[HTTP error] {e.status}: {e.message}")
+            except EmbeddingServiceConnectionError as e:
+                print("[Connection error]", e)
+            except EmbeddingServiceError as e:
+                print("[Other error]", e)
+
+            # Example: error handling for invalid command
+            try:
+                await client.cmd("not_a_command")
+            except EmbeddingServiceAPIError as e:
+                print("[API error for invalid command]", e.error)
+
+            # Example: error handling for empty texts
+            try:
+                await client.cmd("embed", params={"texts": []})
+            except EmbeddingServiceAPIError as e:
+                print("[API error for empty texts]", e.error)
+
+    except Exception as e:
+        print("[Unexpected error]", e)
+
+if __name__ == "__main__":
+    asyncio.run(main()) 

embed_client-0.0.1.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: embed-client
+Version: 0.0.1
+Summary: Async client for Embedding Service API
+Author: Your Name
+Requires-Dist: aiohttp
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"

embed_client-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+embed_client/__init__.py,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
+embed_client/async_client.py,sha256=HzvJ85Qh8fT-YHuam4YFW5Kbxx2hrbsOV8EzjbQ34Eg,7329
+embed_client/example_async_usage.py,sha256=7j9Hro7-TjsKVC2vHUX2J1_-Rh3V9FxsOmsCdCV8KYM,3555
+embed_client/example_async_usage_ru.py,sha256=kZXQcbEFkx9tWXoCq-AoyvvUY4aCuW1XqPVb1ADWeAM,3558
+embed_client-0.0.1.dist-info/METADATA,sha256=GUuiN2owdcnNa7XqqZeEJo_G9oV8Z7ZoqcNUtn-Cuyo,252
+embed_client-0.0.1.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
+embed_client-0.0.1.dist-info/top_level.txt,sha256=uG00A4d9o9DFrhiN7goObpeig72Pniby0E7UpDRgyXY,13
+embed_client-0.0.1.dist-info/RECORD,,

embed_client-0.0.1.dist-info/WHEEL

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

embed_client-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+embed_client