feat: ability to propagate tags to function runs

.gitignore

@@ -5,6 +5,7 @@ uv.lock
 # notebooks
 .ipynb_checkpoints
 docs/notebooks/dirty/
+docs/notebooks/html/
 
 
 # Byte-compiled / optimized / DLL files

Makefile

@@ -27,6 +27,10 @@ install: install-pre-commit
 	uv sync --all-extras
 
 
+docs-build:
+	@echo "Building docs..."
+	uv run mkdocs build
+
 docs-serve:
 	@echo "Serving docs locally..."
 	uv run mkdocs serve

docs/platform/ref/billing.md

@@ -0,0 +1,41 @@
+# Billing API.
+
+The DeepOriginClient can be used to access the billing API using:
+
+```{.python notest}
+from deeporigin.platform.client import DeepOriginClient
+
+client = DeepOriginClient()
+```
+
+Then, the following methods can be used, for example:
+
+```{.python notest}
+# Get usage information for a billing tag (with default dates)
+usage = client.billing.get_usage_by_tag(tag="foo14")
+
+# Get usage information with custom date range
+usage = client.billing.get_usage_by_tag(
+    tag="foo14",
+    start_date="2020-01-01",
+    end_date="2030-01-01",
+)
+```
+
+
+::: src.platform.billing.Billing
+    options:
+      heading_level: 2
+      docstring_style: google
+      show_root_heading: true
+      show_category_heading: true
+      show_object_full_path: false
+      show_root_toc_entry: false
+      inherited_members: true
+      members_order: alphabetical
+      filters:
+        - "!^_"  # Exclude private members (names starting with "_")
+      show_signature: true
+      show_signature_annotations: true
+      show_if_no_docstring: true
+      group_by_category: true

mkdocs.yaml

@@ -86,6 +86,7 @@ nav:
   - clusters: platform/ref/clusters.md
   - functions: platform/ref/functions.md
   - organizations: platform/ref/organizations.md
+  - billing: platform/ref/billing.md
 - Developing: 
   - Installing: dev/install.md
   - Clients: dev/clients.md

scripts/build_docs.sh

@@ -48,17 +48,28 @@ fi
 
 # Build docs and capture output
 echo "📚 Building documentation..."
-MKDOCS_OUT="$(uv run mkdocs build -s 2>&1)"
-BUILD_EXIT_CODE=$?
+# Use a temp file to capture output while still showing it in real-time
+MKDOCS_OUTPUT_FILE=$(mktemp)
+trap "rm -f $MKDOCS_OUTPUT_FILE" EXIT
+
+# Run mkdocs, showing output in real-time and capturing to file
+# Capture exit code from mkdocs (not tee) using PIPESTATUS
+set +e  # Temporarily disable exit on error to capture exit code
+uv run mkdocs build -s 2>&1 | tee "$MKDOCS_OUTPUT_FILE"
+BUILD_EXIT_CODE=${PIPESTATUS[0]}
+set -e  # Re-enable exit on error
 
 # Check if build failed
 if [ "$BUILD_EXIT_CODE" -gt 0 ]; then
   echo "❌ Build failed with exit code $BUILD_EXIT_CODE"
   echo "Build output:"
-  echo "$MKDOCS_OUT"
+  cat "$MKDOCS_OUTPUT_FILE"
   exit "$BUILD_EXIT_CODE"
 fi
 
+# Read captured output for warning checking
+MKDOCS_OUT=$(cat "$MKDOCS_OUTPUT_FILE")
+
 # Check for warnings
 WARNING_COUNT=$(echo "$MKDOCS_OUT" | grep -c "WARNING" || true)
 if [ "$WARNING_COUNT" -gt 0 ]; then

src/platform/__init__.py

@@ -9,8 +9,13 @@
 - `DEEPORIGIN_ENV` (defaults to "prod" if not provided)
 - `DEEPORIGIN_ORG_KEY`
 
-Use `DeepOriginClient.get()` to get a cached singleton instance that reuses
-connection pools across notebook cells.
+The client automatically caches instances based on (base_url, token, org_key, tag),
+so calling `DeepOriginClient()` multiple times with the same parameters returns
+the same cached instance, reusing connection pools.
+
+Example:
+    client = DeepOriginClient()  # Uses singleton cache automatically
+    client.tag = "my-tag"  # Set tag for all function runs
 """
 
 from deeporigin.platform.client import DeepOriginClient

src/platform/billing.py

@@ -0,0 +1,56 @@
+"""Billing API wrapper for DeepOriginClient."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from deeporigin.platform.client import DeepOriginClient
+
+
+class Billing:
+    """Billing API wrapper.
+
+    Provides access to billing-related endpoints through the DeepOriginClient.
+    """
+
+    def __init__(self, client: DeepOriginClient) -> None:
+        """Initialize Billing wrapper.
+
+        Args:
+            client: The DeepOriginClient instance to use for API calls.
+        """
+        self._c = client
+
+    def get_usage_by_tag(
+        self,
+        *,
+        tag: str,
+        start_date: str = "2020-01-01",
+        end_date: str | None = None,
+    ) -> dict:
+        """Get usage information for a billing tag within a date range.
+
+        Args:
+            tag: The billing tag to get usage for.
+            start_date: Start date in YYYY-MM-DD format.
+            end_date: End date in YYYY-MM-DD format. Defaults to today's date.
+
+        Returns:
+            Dictionary containing usage information.
+        """
+        if end_date is None:
+            end_date = date.today().strftime("%Y-%m-%d")
+
+        params = {
+            "startDate": start_date,
+            "endDate": end_date,
+        }
+
+        response = self._c.get_json(
+            f"/billing/{self._c.org_key}/usage/{tag}",
+            params=params,
+        )
+
+        return response