kainguru-sdk 0.1.8.dev0__tar.gz → 0.2.9.dev0__tar.gz

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: kainguru-sdk
-Version: 0.1.8.dev0
+Version: 0.2.9.dev0
 Summary: Python SDK for the Kainguru ML platform — run models and fine-tune them.
 Project-URL: Homepage, https://kainguru.com
 Project-URL: Repository, https://github.com/kainguru/kainguru
@@ -191,6 +191,7 @@ client = KainguruClient(
     base_url="https://your-host/api",    # required, full host incl. /api context path
     timeout=30.0,                        # per-request timeout in s
     max_retries=3,                       # retries on 429 / 5xx / network
+    debug=True,                          # verbose request/response logging (default False)
 )
 ```
 
@@ -200,6 +201,13 @@ the dashboard's `/api` context path.
 
 Every method also accepts a per-request `api_key=` to override the client key for one call.
 
+### Debug logging
+
+Pass `debug=True` to trace every request and response on the `kainguru` logger (the
+`X-API-Key` header is redacted). If your app hasn't configured that logger, the SDK
+attaches a stderr handler at `DEBUG` level so the traces are visible out of the box.
+Keep it off in production — request and response bodies are logged in full.
+
 ---
 
 ## Error handling

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/README.md

@@ -162,6 +162,7 @@ client = KainguruClient(
     base_url="https://your-host/api",    # required, full host incl. /api context path
     timeout=30.0,                        # per-request timeout in s
     max_retries=3,                       # retries on 429 / 5xx / network
+    debug=True,                          # verbose request/response logging (default False)
 )
 ```
 
@@ -171,6 +172,13 @@ the dashboard's `/api` context path.
 
 Every method also accepts a per-request `api_key=` to override the client key for one call.
 
+### Debug logging
+
+Pass `debug=True` to trace every request and response on the `kainguru` logger (the
+`X-API-Key` header is redacted). If your app hasn't configured that logger, the SDK
+attaches a stderr handler at `DEBUG` level so the traces are visible out of the box.
+Keep it off in production — request and response bodies are logged in full.
+
 ---
 
 ## Error handling

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kainguru-sdk"
-version = "0.1.8.dev0"
+version = "0.2.9.dev0"
 description = "Python SDK for the Kainguru ML platform — run models and fine-tune them."
 readme = "README.md"
 requires-python = ">=3.10"

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/src/kainguru/_config.py

@@ -18,6 +18,7 @@ class KainguruConfig:
     timeout: float
     max_retries: int
     retry_base_delay: float
+    debug: bool = False
 
     @classmethod
     def resolve(
@@ -28,6 +29,7 @@ class KainguruConfig:
         timeout: float = DEFAULT_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
         retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        debug: bool = False,
     ) -> KainguruConfig:
         """Resolve configuration, failing fast when the caller omits a required field.
 
@@ -56,6 +58,7 @@ class KainguruConfig:
             timeout=timeout,
             max_retries=max_retries,
             retry_base_delay=retry_base_delay,
+            debug=debug,
         )
 
 

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/src/kainguru/_transport.py

@@ -8,6 +8,7 @@ identically.
 from __future__ import annotations
 
 import asyncio
+import logging
 import random
 import time
 from typing import Any, TypeVar
@@ -28,6 +29,67 @@ API_KEY_HEADER = "X-API-Key"
 
 ModelT = TypeVar("ModelT", bound=BaseModel)
 
+#: Logger used for verbose request/response tracing when the client is in debug mode.
+logger = logging.getLogger("kainguru")
+
+
+def enable_debug_logging() -> None:
+    """Make the ``kainguru`` logger emit DEBUG traces to stderr.
+
+    Called by the clients when ``debug=True``. If the application has already
+    configured handlers for the ``kainguru`` logger, those are left untouched and
+    only the level is lowered.
+    """
+    logger.setLevel(logging.DEBUG)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(
+            logging.Formatter("%(asctime)s [kainguru] %(levelname)s %(message)s")
+        )
+        logger.addHandler(handler)
+        logger.propagate = False
+
+
+def _redact_headers(headers: dict[str, str]) -> dict[str, str]:
+    safe = dict(headers)
+    if API_KEY_HEADER in safe:
+        safe[API_KEY_HEADER] = "***redacted***"
+    return safe
+
+
+def _log_request(
+    config: KainguruConfig,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    params: dict[str, Any] | None,
+    json: dict[str, Any] | None,
+    attempt: int,
+) -> None:
+    if not config.debug:
+        return
+    logger.debug(
+        "--> %s %s (attempt %d) params=%s headers=%s json=%s",
+        method,
+        url,
+        attempt + 1,
+        params,
+        _redact_headers(headers),
+        json,
+    )
+
+
+def _log_response(config: KainguruConfig, response: httpx.Response) -> None:
+    if not config.debug:
+        return
+    logger.debug(
+        "<-- %s %s (%s) %s",
+        response.status_code,
+        response.request.url,
+        response.elapsed,
+        response.text,
+    )
+
 
 def _headers(config: KainguruConfig, api_key: str | None) -> dict[str, str]:
     headers = {"Accept": "application/json"}
@@ -142,6 +204,7 @@ class Transport:
         headers = _headers(self._config, api_key)
         last_exc: Exception | None = None
         for attempt in range(self._config.max_retries + 1):
+            _log_request(self._config, method, url, headers, params, json, attempt)
             try:
                 response = self._client.request(
                     method, url, params=params, json=json, headers=headers
@@ -154,6 +217,7 @@ class Transport:
                     ) from exc
                 time.sleep(_retry_delay(attempt, None, self._config.retry_base_delay))
                 continue
+            _log_response(self._config, response)
             if _is_retriable_status(response.status_code) and attempt < self._config.max_retries:
                 time.sleep(_retry_delay(attempt, response, self._config.retry_base_delay))
                 continue
@@ -184,6 +248,7 @@ class AsyncTransport:
         headers = _headers(self._config, api_key)
         last_exc: Exception | None = None
         for attempt in range(self._config.max_retries + 1):
+            _log_request(self._config, method, url, headers, params, json, attempt)
             try:
                 response = await self._client.request(
                     method, url, params=params, json=json, headers=headers
@@ -196,6 +261,7 @@ class AsyncTransport:
                     ) from exc
                 await asyncio.sleep(_retry_delay(attempt, None, self._config.retry_base_delay))
                 continue
+            _log_response(self._config, response)
             if _is_retriable_status(response.status_code) and attempt < self._config.max_retries:
                 await asyncio.sleep(_retry_delay(attempt, response, self._config.retry_base_delay))
                 continue

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/src/kainguru/async_client.py

@@ -12,7 +12,7 @@ from ._config import (
     DEFAULT_TIMEOUT,
     KainguruConfig,
 )
-from ._transport import AsyncTransport
+from ._transport import AsyncTransport, enable_debug_logging
 from .resources import AsyncExecutionsResource, AsyncFineTuningResource
 
 
@@ -39,6 +39,7 @@ class AsyncKainguruClient:
         timeout: float = DEFAULT_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
         retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        debug: bool = False,
         http_client: httpx.AsyncClient | None = None,
     ) -> None:
         self._config = KainguruConfig.resolve(
@@ -47,7 +48,10 @@ class AsyncKainguruClient:
             timeout=timeout,
             max_retries=max_retries,
             retry_base_delay=retry_base_delay,
+            debug=debug,
         )
+        if self._config.debug:
+            enable_debug_logging()
         client = http_client or httpx.AsyncClient(
             base_url=self._config.base_url, timeout=self._config.timeout
         )

{kainguru_sdk-0.1.8.dev0 → kainguru_sdk-0.2.9.dev0}/src/kainguru/client.py

@@ -12,7 +12,7 @@ from ._config import (
     DEFAULT_TIMEOUT,
     KainguruConfig,
 )
-from ._transport import Transport
+from ._transport import Transport, enable_debug_logging
 from .resources import ExecutionsResource, FineTuningResource
 
 
@@ -39,6 +39,7 @@ class KainguruClient:
         timeout: float = DEFAULT_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
         retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        debug: bool = False,
         http_client: httpx.Client | None = None,
     ) -> None:
         self._config = KainguruConfig.resolve(
@@ -47,7 +48,10 @@ class KainguruClient:
             timeout=timeout,
             max_retries=max_retries,
             retry_base_delay=retry_base_delay,
+            debug=debug,
         )
+        if self._config.debug:
+            enable_debug_logging()
         client = http_client or httpx.Client(
             base_url=self._config.base_url, timeout=self._config.timeout
         )