Add User-Agent header and logging support

- Add InsForge-Python/{VERSION} User-Agent to all HTTP requests
- Read version from package metadata (importlib.metadata) to keep
  pyproject.toml as single source of truth
- Add logging module with setup_logging() helper for INFO/DEBUG levels
- INFO: SDK initialization config; DEBUG: HTTP request/response details
- Document logging usage in README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jwfing

README.md

@@ -196,6 +196,28 @@ Exception hierarchy:
   - `InsforgeValidationError` - Pydantic validation failures
   - `InsforgeSerializationError` - serialization failures
 
+## Logging
+
+The SDK uses Python's built-in `logging` module under the `insforge` logger. By default no logs are emitted. Call `setup_logging` to enable output:
+
+```python
+import insforge
+
+# INFO — SDK initialization details and important operation results
+insforge.setup_logging("INFO")
+
+# DEBUG — full HTTP request/response (method, URL, params, status code)
+insforge.setup_logging("DEBUG")
+```
+
+You can also configure the `insforge` logger directly with the standard `logging` module for more advanced setups:
+
+```python
+import logging
+
+logging.getLogger("insforge").setLevel(logging.DEBUG)
+```
+
 ## Authentication Model
 
 The SDK is **stateless** - it never stores or caches tokens. Every method that requires user auth takes an explicit `access_token` parameter. The API key is sent as `X-API-Key` on every request automatically.

insforge/__init__.py

@@ -1,4 +1,5 @@
 from .client import InsforgeClient
+from ._logging import setup_logging
 
-__all__ = ["InsforgeClient"]
+__all__ = ["InsforgeClient", "setup_logging"]
 

insforge/_base_client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 from typing import Any
 from typing import Mapping
 from urllib.parse import urlsplit
@@ -8,15 +9,18 @@
 
 from .exceptions import InsforgeHTTPError
 from ._utils import normalize_base_url
+from ._version import VERSION, USER_AGENT
+
+logger = logging.getLogger("insforge")
 
 
 def build_headers(
     api_key: str,
     access_token: str | None = None,
     extra_headers: Mapping[str, str] | None = None,
 ) -> dict[str, str]:
-    headers: dict[str, str] = {"X-API-Key": api_key}
-    reserved_headers = {"authorization", "x-api-key"}
+    headers: dict[str, str] = {"X-API-Key": api_key, "User-Agent": USER_AGENT}
+    reserved_headers = {"authorization", "x-api-key", "user-agent"}
 
     if access_token:
         headers["Authorization"] = f"Bearer {access_token}"
@@ -33,6 +37,7 @@ def __init__(self, base_url: str, api_key: str) -> None:
         self.base_url = normalize_base_url(base_url)
         self.api_key = api_key
         self.http_client = httpx.AsyncClient()
+        logger.info("InsforgeClient initialized (version=%s, base_url=%s)", VERSION, self.base_url)
 
     def _build_headers(
         self,
@@ -125,9 +130,12 @@ async def _request(
         extra_headers: Mapping[str, str] | None = None,
         exception_cls: type[InsforgeHTTPError] = InsforgeHTTPError,
     ) -> httpx.Response:
+        url = self._build_url(path)
+        logger.debug(">>> %s %s params=%s body=%s", method, url, params, json)
+
         response = await self.http_client.request(
             method,
-            self._build_url(path),
+            url,
             params=params,
             json=json,
             headers=self._build_headers(
@@ -136,6 +144,8 @@ async def _request(
             ),
         )
 
+        logger.debug("<<< %s %s status=%d", method, url, response.status_code)
+
         if response.is_error:
             raise exception_cls.from_response(method, path, response)
 

insforge/_logging.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import logging
+
+
+def setup_logging(level: int | str = logging.WARNING) -> None:
+    """Configure the ``insforge`` logger.
+
+    Parameters
+    ----------
+    level:
+        Logging level.  Accepts standard :mod:`logging` constants
+        (``logging.DEBUG``, ``logging.INFO``, …) or their string names
+        (``"DEBUG"``, ``"INFO"``, …).
+
+    Examples
+    --------
+    Show SDK configuration and important operation results::
+
+        import insforge
+        insforge.setup_logging("INFO")
+
+    Show full HTTP request / response details for debugging::
+
+        import insforge
+        insforge.setup_logging("DEBUG")
+    """
+    logger = logging.getLogger("insforge")
+    logger.setLevel(level)
+
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(
+            logging.Formatter("[%(name)s %(levelname)s] %(message)s"),
+        )
+        logger.addHandler(handler)

insforge/_version.py

@@ -0,0 +1,8 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    VERSION = version("insforge")
+except PackageNotFoundError:
+    VERSION = "0.0.0-dev"
+
+USER_AGENT = f"InsForge-Python/{VERSION}"

insforge/storage/client.py

@@ -6,8 +6,12 @@
 
 import httpx
 
+import logging
+
 from .._base_client import BaseClient
 from ..exceptions import InsforgeHTTPError
+
+logger = logging.getLogger("insforge")
 from .._utils import quote_path_segment
 from .models import DownloadStrategy
 from .models import StorageBucketListResponse
@@ -130,16 +134,21 @@ async def upload_object(
         extra_headers: Mapping[str, str] | None = None,
     ) -> StorageObjectResponse:
         path = self._object_url_path(bucket_name, object_key)
+        url = self._client._build_url(path)
+        logger.debug(">>> PUT %s file=%s size=%d", url, object_key, len(data))
+
         response = await self._client.http_client.request(
             "PUT",
-            self._client._build_url(path),
+            url,
             files={"file": (object_key, data, content_type or "application/octet-stream")},
             headers=self._client._build_headers(
                 access_token=access_token,
                 extra_headers=extra_headers,
             ),
         )
 
+        logger.debug("<<< PUT %s status=%d", url, response.status_code)
+
         if response.is_error:
             raise InsforgeHTTPError.from_response(
                 "PUT",
@@ -158,15 +167,20 @@ async def download_object(
         extra_headers: Mapping[str, str] | None = None,
     ) -> StorageDownloadResult:
         path = self._object_url_path(bucket_name, object_key)
+        url = self._client._build_url(path)
+        logger.debug(">>> GET %s", url)
+
         response = await self._client.http_client.request(
             "GET",
-            self._client._build_url(path),
+            url,
             headers=self._client._build_headers(
                 access_token=access_token,
                 extra_headers=extra_headers,
             ),
         )
 
+        logger.debug("<<< GET %s status=%d", url, response.status_code)
+
         if response.is_error:
             raise InsforgeHTTPError.from_response(
                 "GET",
@@ -214,13 +228,18 @@ async def upload_object_auto(
         access_token: str | None = None,
     ) -> StorageObjectResponse:
         path = f"/api/storage/buckets/{quote_path_segment(bucket_name)}/objects"
+        url = self._client._build_url(path)
+        logger.debug(">>> POST %s file=%s size=%d", url, filename, len(data))
+
         response = await self._client.http_client.request(
             "POST",
-            self._client._build_url(path),
+            url,
             files={"file": (filename, data, content_type or "application/octet-stream")},
             headers=self._client._build_headers(access_token=access_token),
         )
 
+        logger.debug("<<< POST %s status=%d", url, response.status_code)
+
         if response.is_error:
             raise InsforgeHTTPError.from_response("POST", path, response)