embed-client 1.0.0.1__py3-none-any.whl → 2.0.0.0__py3-none-any.whl

embed_client/async_client.py

@@ -4,11 +4,15 @@ Async client for Embedding Service API (OpenAPI 3.0.2)
 - 100% type-annotated
 - English docstrings and examples
 - Ready for PyPi
+- Supports new API format with body, embedding, and chunks
 """
 
 from typing import Any, Dict, List, Optional, Union
 import aiohttp
+import asyncio
 import os
+import json
+import logging
 
 class EmbeddingServiceError(Exception):
     """Base exception for EmbeddingServiceAsyncClient."""
@@ -29,28 +33,73 @@ class EmbeddingServiceAPIError(EmbeddingServiceError):
         super().__init__(f"API error: {error}")
         self.error = error
 
+class EmbeddingServiceConfigError(EmbeddingServiceError):
+    """Raised for configuration errors (invalid base_url, port, etc.)."""
+
+class EmbeddingServiceTimeoutError(EmbeddingServiceError):
+    """Raised when request times out."""
+
+class EmbeddingServiceJSONError(EmbeddingServiceError):
+    """Raised when JSON parsing fails."""
+
 class EmbeddingServiceAsyncClient:
     """
     Asynchronous client for the Embedding Service API.
+    
+    Supports both old and new API formats:
+    - Old format: {"result": {"success": true, "data": {"embeddings": [...]}}}
+    - New format: {"result": {"success": true, "data": {"embeddings": [...], "results": [{"body": "text", "embedding": [...], "tokens": [...], "bm25_tokens": [...]}]}}}
+    
     Args:
         base_url (str): Base URL of the embedding service (e.g., "http://localhost").
         port (int): Port of the embedding service (e.g., 8001).
+        timeout (float): Request timeout in seconds (default: 30).
     Raises:
-        ValueError: If base_url or port is not provided.
+        EmbeddingServiceConfigError: If base_url or port is invalid.
     """
-    def __init__(self, base_url: Optional[str] = None, port: Optional[int] = None):
-        self.base_url = base_url or os.getenv("EMBEDDING_SERVICE_BASE_URL", "http://localhost")
-        if not self.base_url:
-            raise ValueError("base_url must be provided.")
-        self.port = port or int(os.getenv("EMBEDDING_SERVICE_PORT", "8001"))
-        if self.port is None:
-            raise ValueError("port must be provided.")
+    def __init__(self, base_url: Optional[str] = None, port: Optional[int] = None, timeout: float = 30.0):
+        # Validate and set base_url
+        try:
+            self.base_url = base_url or os.getenv("EMBEDDING_SERVICE_BASE_URL", "http://localhost")
+            if not self.base_url:
+                raise EmbeddingServiceConfigError("base_url must be provided.")
+            if not isinstance(self.base_url, str):
+                raise EmbeddingServiceConfigError("base_url must be a string.")
+            
+            # Validate URL format
+            if not (self.base_url.startswith("http://") or self.base_url.startswith("https://")):
+                raise EmbeddingServiceConfigError("base_url must start with http:// or https://")
+        except (TypeError, AttributeError) as e:
+            raise EmbeddingServiceConfigError(f"Invalid base_url configuration: {e}") from e
+        
+        # Validate and set port
+        try:
+            port_env = os.getenv("EMBEDDING_SERVICE_PORT", "8001")
+            self.port = port if port is not None else int(port_env)
+            if self.port is None:
+                raise EmbeddingServiceConfigError("port must be provided.")
+            if not isinstance(self.port, int) or self.port <= 0 or self.port > 65535:
+                raise EmbeddingServiceConfigError("port must be a valid integer between 1 and 65535.")
+        except (ValueError, TypeError) as e:
+            raise EmbeddingServiceConfigError(f"Invalid port configuration: {e}") from e
+        
+        # Validate timeout
+        try:
+            self.timeout = float(timeout)
+            if self.timeout <= 0:
+                raise EmbeddingServiceConfigError("timeout must be positive.")
+        except (ValueError, TypeError) as e:
+            raise EmbeddingServiceConfigError(f"Invalid timeout configuration: {e}") from e
+        
         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}"
+        try:
+            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}"
+        except Exception as e:
+            raise EmbeddingServiceConfigError(f"Failed to construct URL: {e}") from e
 
     def _format_error_response(self, error: str, lang: Optional[str] = None, text: Optional[str] = None) -> Dict[str, Any]:
         """
@@ -69,14 +118,221 @@ class EmbeddingServiceAsyncClient:
             response["text"] = text
         return response
 
+    def extract_embeddings(self, result: Dict[str, Any]) -> List[List[float]]:
+        """
+        Extract embeddings from API response, supporting both old and new formats.
+        
+        Args:
+            result: API response dictionary
+            
+        Returns:
+            List of embedding vectors (list of lists of floats)
+            
+        Raises:
+            ValueError: If embeddings cannot be extracted from the response
+        """
+        # Handle direct embeddings field (old format compatibility)
+        if "embeddings" in result:
+            return result["embeddings"]
+        
+        # Handle result wrapper
+        if "result" in result:
+            res = result["result"]
+            
+            # Handle direct list in result (old format)
+            if isinstance(res, list):
+                return res
+            
+            if isinstance(res, dict):
+                # Handle old format: result.embeddings
+                if "embeddings" in res:
+                    return res["embeddings"]
+                
+                # Handle old format: result.data.embeddings
+                if "data" in res and isinstance(res["data"], dict) and "embeddings" in res["data"]:
+                    return res["data"]["embeddings"]
+                
+                # Handle new format: result.data[].embedding
+                if "data" in res and isinstance(res["data"], list):
+                    embeddings = []
+                    for item in res["data"]:
+                        if isinstance(item, dict) and "embedding" in item:
+                            embeddings.append(item["embedding"])
+                        else:
+                            raise ValueError(f"Invalid item format in new API response: {item}")
+                    return embeddings
+        
+        raise ValueError(f"Cannot extract embeddings from response: {result}")
+
+    def extract_embedding_data(self, result: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """
+        Extract full embedding data from API response (new format only).
+        
+        Args:
+            result: API response dictionary
+            
+        Returns:
+            List of dictionaries with 'body', 'embedding', 'tokens', and 'bm25_tokens' fields
+            
+        Raises:
+            ValueError: If data cannot be extracted or is in old format
+        """
+        if "result" in result and isinstance(result["result"], dict):
+            res = result["result"]
+            if "data" in res and isinstance(res["data"], dict) and "results" in res["data"]:
+                # New format: result.data.results[]
+                results = res["data"]["results"]
+                if isinstance(results, list):
+                    # Validate that all items have required fields
+                    for i, item in enumerate(results):
+                        if not isinstance(item, dict):
+                            raise ValueError(f"Item {i} is not a dictionary: {item}")
+                        if "body" not in item:
+                            raise ValueError(f"Item {i} missing 'body' field: {item}")
+                        if "embedding" not in item:
+                            raise ValueError(f"Item {i} missing 'embedding' field: {item}")
+                        if "tokens" not in item:
+                            raise ValueError(f"Item {i} missing 'tokens' field: {item}")
+                        if "bm25_tokens" not in item:
+                            raise ValueError(f"Item {i} missing 'bm25_tokens' field: {item}")
+                    
+                    return results
+            
+            # Legacy support for old format: result.data[]
+            if "data" in res and isinstance(res["data"], list):
+                # Validate that all items have required fields
+                for i, item in enumerate(res["data"]):
+                    if not isinstance(item, dict):
+                        raise ValueError(f"Item {i} is not a dictionary: {item}")
+                    if "body" not in item:
+                        raise ValueError(f"Item {i} missing 'body' field: {item}")
+                    if "embedding" not in item:
+                        raise ValueError(f"Item {i} missing 'embedding' field: {item}")
+                    # Old format had 'chunks' instead of 'tokens'
+                    if "chunks" not in item and "tokens" not in item:
+                        raise ValueError(f"Item {i} missing 'chunks' or 'tokens' field: {item}")
+                
+                return res["data"]
+        
+        raise ValueError(f"Cannot extract embedding data from response (new format required): {result}")
+
+    def extract_texts(self, result: Dict[str, Any]) -> List[str]:
+        """
+        Extract original texts from API response (new format only).
+        
+        Args:
+            result: API response dictionary
+            
+        Returns:
+            List of original text strings
+            
+        Raises:
+            ValueError: If texts cannot be extracted or is in old format
+        """
+        data = self.extract_embedding_data(result)
+        return [item["body"] for item in data]
+
+    def extract_chunks(self, result: Dict[str, Any]) -> List[List[str]]:
+        """
+        Extract text chunks from API response (new format only).
+        Note: This method now extracts 'tokens' instead of 'chunks' for compatibility.
+        
+        Args:
+            result: API response dictionary
+            
+        Returns:
+            List of token lists for each text
+            
+        Raises:
+            ValueError: If chunks cannot be extracted or is in old format
+        """
+        data = self.extract_embedding_data(result)
+        chunks = []
+        for item in data:
+            # New format uses 'tokens', old format used 'chunks'
+            if "tokens" in item:
+                chunks.append(item["tokens"])
+            elif "chunks" in item:
+                chunks.append(item["chunks"])
+            else:
+                raise ValueError(f"Item missing both 'tokens' and 'chunks' fields: {item}")
+        return chunks
+
+    def extract_tokens(self, result: Dict[str, Any]) -> List[List[str]]:
+        """
+        Extract tokens from API response (new format only).
+        
+        Args:
+            result: API response dictionary
+            
+        Returns:
+            List of token lists for each text
+            
+        Raises:
+            ValueError: If tokens cannot be extracted or is in old format
+        """
+        data = self.extract_embedding_data(result)
+        return [item["tokens"] for item in data]
+
+    def extract_bm25_tokens(self, result: Dict[str, Any]) -> List[List[str]]:
+        """
+        Extract BM25 tokens from API response (new format only).
+        
+        Args:
+            result: API response dictionary
+            
+        Returns:
+            List of BM25 token lists for each text
+            
+        Raises:
+            ValueError: If BM25 tokens cannot be extracted or is in old format
+        """
+        data = self.extract_embedding_data(result)
+        return [item["bm25_tokens"] for item in data]
+
     async def __aenter__(self):
-        self._session = aiohttp.ClientSession()
-        return self
+        try:
+            # Create session with timeout configuration
+            timeout = aiohttp.ClientTimeout(total=self.timeout)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+            return self
+        except Exception as e:
+            raise EmbeddingServiceError(f"Failed to create HTTP session: {e}") from e
 
     async def __aexit__(self, exc_type, exc, tb):
         if self._session:
-            await self._session.close()
-            self._session = None
+            try:
+                await self._session.close()
+            except Exception as e:
+                raise EmbeddingServiceError(f"Failed to close HTTP session: {e}") from e
+            finally:
+                self._session = None
+
+    async def _parse_json_response(self, resp: aiohttp.ClientResponse) -> Dict[str, Any]:
+        """
+        Parse JSON response with proper error handling.
+        
+        Args:
+            resp: aiohttp response object
+            
+        Returns:
+            dict: Parsed JSON data
+            
+        Raises:
+            EmbeddingServiceJSONError: If JSON parsing fails
+        """
+        try:
+            return await resp.json()
+        except json.JSONDecodeError as e:
+            try:
+                text = await resp.text()
+                raise EmbeddingServiceJSONError(f"Invalid JSON response: {e}. Response text: {text[:500]}...") from e
+            except Exception as text_error:
+                raise EmbeddingServiceJSONError(f"Invalid JSON response: {e}. Failed to get response text: {text_error}") from e
+        except UnicodeDecodeError as e:
+            raise EmbeddingServiceJSONError(f"Unicode decode error in response: {e}") from e
+        except Exception as e:
+            raise EmbeddingServiceJSONError(f"Unexpected error parsing JSON: {e}") from e
 
     async def health(self, base_url: Optional[str] = None, port: Optional[int] = None) -> Dict[str, Any]:
         """
@@ -89,17 +345,35 @@ class EmbeddingServiceAsyncClient:
         """
         url = self._make_url("/health", base_url, port)
         try:
-            async with self._session.get(url) as resp:
+            async with self._session.get(url, timeout=self.timeout) as resp:
                 await self._raise_for_status(resp)
-                return await resp.json()
+                try:
+                    data = await resp.json()
+                except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as e:
+                    raise EmbeddingServiceJSONError(f"Invalid JSON response: {e}") from e
+                if "error" in data:
+                    raise EmbeddingServiceAPIError(data["error"])
+                return data
         except EmbeddingServiceHTTPError:
             raise
         except EmbeddingServiceConnectionError:
             raise
+        except EmbeddingServiceJSONError:
+            raise
+        except EmbeddingServiceTimeoutError:
+            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 asyncio.TimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Request timeout: {e}") from e
+        except aiohttp.ServerTimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Server timeout: {e}") from e
+        except aiohttp.ClientSSLError as e:
+            raise EmbeddingServiceConnectionError(f"SSL error: {e}") from e
+        except aiohttp.ClientOSError as e:
+            raise EmbeddingServiceConnectionError(f"OS error: {e}") from e
         except Exception as e:
             raise EmbeddingServiceError(f"Unexpected error: {e}") from e
 
@@ -114,17 +388,35 @@ class EmbeddingServiceAsyncClient:
         """
         url = self._make_url("/openapi.json", base_url, port)
         try:
-            async with self._session.get(url) as resp:
+            async with self._session.get(url, timeout=self.timeout) as resp:
                 await self._raise_for_status(resp)
-                return await resp.json()
+                try:
+                    data = await resp.json()
+                except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as e:
+                    raise EmbeddingServiceJSONError(f"Invalid JSON response: {e}") from e
+                if "error" in data:
+                    raise EmbeddingServiceAPIError(data["error"])
+                return data
         except EmbeddingServiceHTTPError:
             raise
         except EmbeddingServiceConnectionError:
             raise
+        except EmbeddingServiceJSONError:
+            raise
+        except EmbeddingServiceTimeoutError:
+            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 asyncio.TimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Request timeout: {e}") from e
+        except aiohttp.ServerTimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Server timeout: {e}") from e
+        except aiohttp.ClientSSLError as e:
+            raise EmbeddingServiceConnectionError(f"SSL error: {e}") from e
+        except aiohttp.ClientOSError as e:
+            raise EmbeddingServiceConnectionError(f"OS error: {e}") from e
         except Exception as e:
             raise EmbeddingServiceError(f"Unexpected error: {e}") from e
 
@@ -139,17 +431,35 @@ class EmbeddingServiceAsyncClient:
         """
         url = self._make_url("/api/commands", base_url, port)
         try:
-            async with self._session.get(url) as resp:
+            async with self._session.get(url, timeout=self.timeout) as resp:
                 await self._raise_for_status(resp)
-                return await resp.json()
+                try:
+                    data = await resp.json()
+                except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as e:
+                    raise EmbeddingServiceJSONError(f"Invalid JSON response: {e}") from e
+                if "error" in data:
+                    raise EmbeddingServiceAPIError(data["error"])
+                return data
         except EmbeddingServiceHTTPError:
             raise
         except EmbeddingServiceConnectionError:
             raise
+        except EmbeddingServiceJSONError:
+            raise
+        except EmbeddingServiceTimeoutError:
+            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 asyncio.TimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Request timeout: {e}") from e
+        except aiohttp.ServerTimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Server timeout: {e}") from e
+        except aiohttp.ClientSSLError as e:
+            raise EmbeddingServiceConnectionError(f"SSL error: {e}") from e
+        except aiohttp.ClientOSError as e:
+            raise EmbeddingServiceConnectionError(f"OS error: {e}") from e
         except Exception as e:
             raise EmbeddingServiceError(f"Unexpected error: {e}") from e
 
@@ -221,41 +531,54 @@ class EmbeddingServiceAsyncClient:
         if command == "embed" and params and "texts" in params:
             self._validate_texts(params["texts"])
 
+        logger = logging.getLogger('EmbeddingServiceAsyncClient.cmd')
         url = self._make_url("/cmd", base_url, port)
         payload = {"command": command}
         if params is not None:
             payload["params"] = params
-
+        logger.info(f"Sending embedding command: url={url}, payload={payload}")
         try:
-            async with self._session.post(url, json=payload) as resp:
+            async with self._session.post(url, json=payload, timeout=self.timeout) as resp:
+                logger.info(f"Embedding service HTTP status: {resp.status}")
                 await self._raise_for_status(resp)
-                data = await resp.json()
-                
-                if "error" in data:
-                    raise EmbeddingServiceAPIError(data["error"])
-                
-                if "result" in data:
-                    res = data["result"]
-                    if isinstance(res, dict) and "success" in res and res["success"] is False:
-                        if "error" in res:
-                            raise EmbeddingServiceAPIError(res["error"])
-                
-                return data
-                
+                try:
+                    resp_json = await resp.json()
+                except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as e:
+                    raise EmbeddingServiceJSONError(f"Invalid JSON response: {e}") from e
+                logger.info(f"Embedding service response: {str(resp_json)[:300]}")
+                # Обработка ошибок API
+                if "error" in resp_json:
+                    raise EmbeddingServiceAPIError(resp_json["error"])
+                if "result" in resp_json:
+                    result = resp_json["result"]
+                    if isinstance(result, dict) and (result.get("success") is False or "error" in result):
+                        raise EmbeddingServiceAPIError(result.get("error", result))
+                return resp_json
+        except EmbeddingServiceAPIError:
+            raise
+        except EmbeddingServiceHTTPError:
+            raise
+        except EmbeddingServiceConnectionError:
+            raise
+        except EmbeddingServiceJSONError:
+            raise
+        except EmbeddingServiceTimeoutError:
+            raise
+        except aiohttp.ServerTimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Server timeout: {e}") from e
         except aiohttp.ClientConnectionError as e:
-            raise EmbeddingServiceAPIError({
-                "code": -32000,
-                "message": f"Connection error: {e}"
-            }) from e
+            raise EmbeddingServiceConnectionError(f"Connection error: {e}") from e
         except aiohttp.ClientResponseError as e:
             raise EmbeddingServiceHTTPError(e.status, e.message) from e
-        except EmbeddingServiceHTTPError:
-            raise
+        except asyncio.TimeoutError as e:
+            raise EmbeddingServiceTimeoutError(f"Request timeout: {e}") from e
+        except aiohttp.ClientSSLError as e:
+            raise EmbeddingServiceConnectionError(f"SSL error: {e}") from e
+        except aiohttp.ClientOSError as e:
+            raise EmbeddingServiceConnectionError(f"OS error: {e}") from e
         except Exception as e:
-            raise EmbeddingServiceAPIError({
-                "code": -32000,
-                "message": f"Unexpected error: {e}"
-            }) from e
+            logger.error(f"Error in embedding cmd: {e}", exc_info=True)
+            raise EmbeddingServiceError(f"Unexpected error: {e}") from e
 
     async def _raise_for_status(self, resp: aiohttp.ClientResponse):
         try:
@@ -263,4 +586,22 @@ class EmbeddingServiceAsyncClient:
         except aiohttp.ClientResponseError as e:
             raise EmbeddingServiceHTTPError(e.status, e.message) from e
 
+    async def close(self) -> None:
+        """
+        Close the underlying HTTP session explicitly.
+
+        This method allows the user to manually close the aiohttp.ClientSession used by the client.
+        It is safe to call multiple times; if the session is already closed or was never opened, nothing happens.
+
+        Raises:
+            EmbeddingServiceError: If closing the session fails.
+        """
+        if self._session:
+            try:
+                await self._session.close()
+            except Exception as e:
+                raise EmbeddingServiceError(f"Failed to close HTTP session: {e}") from e
+            finally:
+                self._session = None
+
     # TODO: Add methods for /cmd, /api/commands, etc. 

embed_client/example_async_usage.py

@@ -1,19 +1,51 @@
 """
 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 errors.
+USAGE:
+    python embed_client/example_async_usage.py --base-url http://localhost --port 8001
+    # или
+    python -m asyncio embed_client/example_async_usage.py --base-url http://localhost --port 8001
+
+    # Можно также использовать переменные окружения:
+    export EMBED_CLIENT_BASE_URL=http://localhost
+    export EMBED_CLIENT_PORT=8001
+    python embed_client/example_async_usage.py
+
+    # ВАЖНО:
+    # --base-url и --port должны быть отдельными аргументами (через пробел),
+    # а не через = (НЕ --base_url=...)
+    # base_url должен содержать http:// или https://
 
-Run this script with:
+EXAMPLES:
+    python embed_client/example_async_usage.py --base-url http://localhost --port 8001
     python -m asyncio embed_client/example_async_usage.py --base-url http://localhost --port 8001
+    export EMBED_CLIENT_BASE_URL=http://localhost
+    export EMBED_CLIENT_PORT=8001
+    python embed_client/example_async_usage.py
 
-You can also set EMBED_CLIENT_BASE_URL and EMBED_CLIENT_PORT environment variables.
+Explicit session close example:
+    import asyncio
+    from embed_client.async_client import EmbeddingServiceAsyncClient
+    async def main():
+        client = EmbeddingServiceAsyncClient(base_url="http://localhost", port=8001)
+        # ... use client ...
+        await client.close()  # Explicitly close session
+    asyncio.run(main())
 """
 
 import asyncio
 import sys
 import os
-from embed_client.async_client import EmbeddingServiceAsyncClient
+from embed_client.async_client import (
+    EmbeddingServiceAsyncClient,
+    EmbeddingServiceError,
+    EmbeddingServiceAPIError,
+    EmbeddingServiceHTTPError,
+    EmbeddingServiceConnectionError,
+    EmbeddingServiceTimeoutError,
+    EmbeddingServiceJSONError,
+    EmbeddingServiceConfigError
+)
 
 def get_params():
     base_url = None
@@ -33,37 +65,101 @@ def get_params():
         return None, None
     return base_url, int(port)
 
+def extract_vectors(result):
+    """Extract embeddings from the API response, supporting both old and new formats."""
+    # Handle direct embeddings field (old format compatibility)
+    if "embeddings" in result:
+        return result["embeddings"]
+    
+    # Handle result wrapper
+    if "result" in result:
+        res = result["result"]
+        
+        # Handle direct list in result (old format)
+        if isinstance(res, list):
+            return res
+        
+        if isinstance(res, dict):
+            # Handle old format: result.embeddings
+            if "embeddings" in res:
+                return res["embeddings"]
+            
+            # Handle old format: result.data.embeddings
+            if "data" in res and isinstance(res["data"], dict) and "embeddings" in res["data"]:
+                return res["data"]["embeddings"]
+            
+            # Handle new format: result.data[].embedding
+            if "data" in res and isinstance(res["data"], list):
+                embeddings = []
+                for item in res["data"]:
+                    if isinstance(item, dict) and "embedding" in item:
+                        embeddings.append(item["embedding"])
+                    else:
+                        raise ValueError(f"Invalid item format in new API response: {item}")
+                return embeddings
+    
+    raise ValueError(f"Cannot extract embeddings from response: {result}")
+
 async def main():
-    base_url, port = get_params()
-    async with EmbeddingServiceAsyncClient(base_url=base_url, port=port) as client:
-        # Check health
-        health = await client.health()
-        print("Service health:", health)
+    try:
+        base_url, port = get_params()
+        # Explicit open/close example
+        client = EmbeddingServiceAsyncClient(base_url=base_url, port=port)
+        print("Explicit session open/close example:")
+        await client.close()
+        print("Session closed explicitly (manual close example).\n")
+        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(f"Connection error during health check: {e}")
+                return
+            except EmbeddingServiceTimeoutError as e:
+                print(f"Timeout error during health check: {e}")
+            except EmbeddingServiceError as e:
+                print(f"Error during health check: {e}")
 
-        # Request embeddings for a list of texts
-        texts = ["hello world", "test embedding"]
-        result = await client.cmd("embed", params={"texts": texts})
-        
-        if "error" in result:
-            print(f"Error occurred: {result['error']}")
-            if "lang" in result:
-                print(f"Language: {result['lang']}")
-            if "text" in result:
-                print(f"Text: {result['text']}")
-        else:
-            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)")
+            # Request embeddings for a list of texts
+            texts = ["hello world", "test embedding"]
+            try:
+                result = await client.cmd("embed", params={"texts": texts})
+                vectors = extract_vectors(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(f"API error during embedding: {e}")
+            except EmbeddingServiceConnectionError as e:
+                print(f"Connection error during embedding: {e}")
+            except EmbeddingServiceTimeoutError as e:
+                print(f"Timeout error during embedding: {e}")
+            except EmbeddingServiceError as e:
+                print(f"Error during embedding: {e}")
+
+            # Example: health check via cmd
+            try:
+                result = await client.cmd("health")
+                print("Health check result:", result)
+            except EmbeddingServiceError as e:
+                print(f"Error during health command: {e}")
 
-        # Example: error handling for invalid command
-        result = await client.cmd("health")
-        print("Health check result:", result)
+            # Example: error handling for empty command
+            try:
+                result = await client.cmd("")
+                print("Empty command result:", result)
+            except EmbeddingServiceAPIError as e:
+                print(f"Expected error for empty command: {e}")
+            except EmbeddingServiceError as e:
+                print(f"Error for empty command: {e}")
 
-        # Example: error handling for empty command
-        # result = await client.cmd("")
-        # if "error" in result:
-        #     print(f"Error for empty command: {result['error']}")
+    except EmbeddingServiceConfigError as e:
+        print(f"Configuration error: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        sys.exit(1)
 
 if __name__ == "__main__":
     asyncio.run(main()) 

embed_client/example_async_usage_ru.py

@@ -1,13 +1,27 @@
 """
-Example usage of EmbeddingServiceAsyncClient.
+Пример использования 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:
+USAGE:
+    python embed_client/example_async_usage_ru.py --base-url http://localhost --port 8001
+    # или
     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.
+    # Можно также использовать переменные окружения:
+    export EMBED_CLIENT_BASE_URL=http://localhost
+    export EMBED_CLIENT_PORT=8001
+    python embed_client/example_async_usage_ru.py
+
+    # ВАЖНО:
+    # --base-url и --port должны быть отдельными аргументами (через пробел),
+    # а не через = (НЕ --base_url=...)
+    # base_url должен содержать http:// или https://
+
+EXAMPLES:
+    python embed_client/example_async_usage_ru.py --base-url http://localhost --port 8001
+    python -m asyncio embed_client/example_async_usage_ru.py --base-url http://localhost --port 8001
+    export EMBED_CLIENT_BASE_URL=http://localhost
+    export EMBED_CLIENT_PORT=8001
+    python embed_client/example_async_usage_ru.py
 """
 
 import asyncio
@@ -34,7 +48,7 @@ def get_params():
     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.")
+        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)
@@ -62,10 +76,30 @@ async def main():
             texts = ["hello world", "test embedding"]
             try:
                 result = await client.cmd("embed", params={"texts": texts})
-                vectors = result["result"]
+                # Use client's extract method for compatibility with both old and new formats
+                vectors = client.extract_embeddings(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)")
+                
+                # Try to extract additional data if new format is available
+                try:
+                    embedding_data = client.extract_embedding_data(result)
+                    print("\nAdditional data from new format:")
+                    for i, data in enumerate(embedding_data):
+                        print(f"  Text: {data['body']!r}")
+                        print(f"  Tokens: {data['tokens']}")
+                        print(f"  BM25 tokens: {data['bm25_tokens']}")
+                        
+                    # Extract tokens and BM25 tokens separately
+                    tokens = client.extract_tokens(result)
+                    bm25_tokens = client.extract_bm25_tokens(result)
+                    print(f"\nExtracted tokens: {tokens}")
+                    print(f"Extracted BM25 tokens: {bm25_tokens}")
+                    
+                except ValueError as e:
+                    print(f"(Old format detected - no additional data available): {e}")
+                    
             except EmbeddingServiceAPIError as e:
                 print("[API error]", e.error)
             except EmbeddingServiceHTTPError as e:

{embed_client-1.0.0.1.dist-info → embed_client-2.0.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embed-client
-Version: 1.0.0.1
+Version: 2.0.0.0
 Summary: Async client for Embedding Service API
 Author: Your Name
 Requires-Dist: aiohttp

embed_client-2.0.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+embed_client/__init__.py,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
+embed_client/async_client.py,sha256=8jsDvHQhtoYNrQ4B2rGHqmniGPVMQeSsrzZZUyMx_J8,26357
+embed_client/example_async_usage.py,sha256=6oCDALFebTv1o5k7lB7UuiacP9Scvf2r3gVIVtIrsPk,6623
+embed_client/example_async_usage_ru.py,sha256=J9K3UpDJwwwy7gNQzy6G3clX4VoMleBmRk_9vymlIiw,5425
+embed_client-2.0.0.0.dist-info/METADATA,sha256=3_4NeyifJYxq9iQQHgmxgegFxeoNPvriW_UpWNsAOmI,254
+embed_client-2.0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+embed_client-2.0.0.0.dist-info/top_level.txt,sha256=uG00A4d9o9DFrhiN7goObpeig72Pniby0E7UpDRgyXY,13
+embed_client-2.0.0.0.dist-info/RECORD,,

embed_client-1.0.0.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-embed_client/__init__.py,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
-embed_client/async_client.py,sha256=sppZ8fPr4XNNLE3M6kLFTL6u5HE3nqo87bxAgt0S0zE,10589
-embed_client/example_async_usage.py,sha256=df0RRwq2FtqVSL2MHVclfVIJj1wyQUuKZXB-lyVb3Kg,2538
-embed_client/example_async_usage_ru.py,sha256=kZXQcbEFkx9tWXoCq-AoyvvUY4aCuW1XqPVb1ADWeAM,3558
-embed_client-1.0.0.1.dist-info/METADATA,sha256=nFDbLecEwcLOuqhJe84hSdboS9vCEhmmX-Ajw9LYark,254
-embed_client-1.0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-embed_client-1.0.0.1.dist-info/top_level.txt,sha256=uG00A4d9o9DFrhiN7goObpeig72Pniby0E7UpDRgyXY,13
-embed_client-1.0.0.1.dist-info/RECORD,,