scale-gp-beta 0.1.0a21__tar.gz → 0.1.0a22__tar.gz

scale_gp_beta-0.1.0a22/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0-alpha.22"
+}

{scale_gp_beta-0.1.0a21 → scale_gp_beta-0.1.0a22}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.0-alpha.22 (2025-06-16)
+
+Full Changelog: [v0.1.0-alpha.21...v0.1.0-alpha.22](https://github.com/scaleapi/sgp-python-beta/compare/v0.1.0-alpha.21...v0.1.0-alpha.22)
+
+### Features
+
+* Updated README.md to include tracing information ([#111](https://github.com/scaleapi/sgp-python-beta/issues/111)) ([e2d0d8d](https://github.com/scaleapi/sgp-python-beta/commit/e2d0d8de22d347b830771fdf7a7fd4be954f30f0))
+
 ## 0.1.0-alpha.21 (2025-06-13)
 
 Full Changelog: [v0.1.0-alpha.20...v0.1.0-alpha.21](https://github.com/scaleapi/sgp-python-beta/compare/v0.1.0-alpha.20...v0.1.0-alpha.21)

{scale_gp_beta-0.1.0a21 → scale_gp_beta-0.1.0a22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: scale-gp-beta
-Version: 0.1.0a21
+Version: 0.1.0a22
 Summary: The official Python library for the Scale GP API
 Project-URL: Homepage, https://github.com/scaleapi/sgp-python-beta
 Project-URL: Repository, https://github.com/scaleapi/sgp-python-beta
@@ -77,6 +77,244 @@ we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
 to add `SGP_API_KEY="My API Key"` to your `.env` file
 so that your API Key is not stored in source control.
 
+---
+
+## Tracing & Spans
+
+The SGP Tracing library provides a convenient way to instrument your Python applications with tracing capabilities, allowing you to generate, manage, and send spans to the Scale GP platform. This enables detailed monitoring and debugging of your workflows.
+
+### Quick Start Examples
+
+For runnable examples, see the [examples/tracing](https://github.com/scaleapi/sgp-python-beta/tree/main/examples/tracing) directory in the repository.
+
+### Using the SDK
+
+#### Initialization
+
+Before you can create any traces or spans, you should initialize the tracing SDK with your `SGPClient`. It's best practice to do this once at your application's entry point. You can omit this step if you have set the `SGP_API_KEY` and `SGP_ACCOUNT_ID` environment variables, as the SDK will attempt to create a default client.
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+from scale_gp_beta import SGPClient
+
+client = SGPClient(api_key="YOUR_API_KEY", account_id="YOUR_ACCOUNT_ID")
+tracing.init(client=client)
+```
+
+Tracing uses the `SGPClient` for all requests. You can edit the `base_url` or any other parameters via the client you pass to `init()`.
+
+#### Disabling Tracing
+
+You can disable tracing by setting the environment variable `DISABLE_SCALE_TRACING` or programmatically via the `disabled` parameter in `init()`.
+
+#### Core Concepts
+
+The SDK revolves around two primary concepts: **Traces** and **Spans**.
+
+  * **Trace:** A trace represents a complete workflow or transaction, such as a web request or an AI agent's operation. It's a collection of related spans. Every trace has a single **root span**.
+  * **Span:** A span represents a single unit of work within a trace, like a function call, a database query, or an external API request. Spans can be nested to show hierarchical relationships.
+
+When starting a trace, we will also create a root span. Server-side, we do not record the trace resource, only spans, but rely on the root span for trace data.
+
+#### Creating Traces and Spans
+
+The SDK offers flexible ways to create traces and spans: using **context managers** for automatic start/end handling, or **explicit control** for manual lifecycle management.
+
+##### 1\. Using Context Managers (Recommended)
+
+The most straightforward way to create traces and spans is by using them as context managers (`with` statements). This ensures that spans are automatically started and ended, and errors are captured.
+
+**Creating a Trace with a Root Span:**
+
+Use `tracing.create_trace()` as a context manager to define a new trace. This automatically creates a root span for your trace.
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+
+def my_workflow():
+    with tracing.create_trace(name="my_application_workflow", metadata={"env": "production"}):
+        # All spans created within this block will belong to "my_application_workflow" trace
+        print("Starting my application workflow...")
+        # ... your workflow logic
+        print("Application workflow completed.")
+```
+
+**Creating Spans within a Trace:**
+
+Inside a `create_trace` block, use `tracing.create_span()` as a context manager. These spans will automatically be associated with the current trace and parent span (if one exists).
+
+```python
+import time
+import scale_gp_beta.lib.tracing as tracing
+
+def fibonacci(curr: int) -> int:
+    with tracing.create_span("fibonacci_calculation", input={"curr": curr}) as span:
+        time.sleep(0.1) # Simulate some work
+        if curr < 2:
+            span.output = {"res": curr}
+            return curr
+        res = fibonacci(curr - 1) + fibonacci(curr - 2)
+        span.output = {"res": res}
+        return res
+
+def main_traced_example():
+    with tracing.create_trace("my_fibonacci_trace"): # Creates a root span
+        # This span will be a child of the "my_fibonacci_trace" root span
+        with tracing.create_span("main_execution", metadata={"version": "1.0"}) as main_span:
+            fib_result = fibonacci(5)
+            main_span.output = {"final_fib_result": fib_result}
+            print(f"Fibonacci(5) = {fib_result}")
+```
+
+##### 2\. Explicit Control
+
+For scenarios where context managers aren't suitable, you can manually start and end spans. This approach requires more diligence to ensure all spans are properly ended and maintaining consistency.
+
+**Manually Managing Spans (without an explicit Trace context):**
+
+You can create spans and explicitly provide their `trace_id` and `parent_id` for fine-grained control. This is useful when integrating with existing systems that manage trace IDs.
+
+```python
+import uuid
+import time
+import random
+from typing import Any, Dict
+import scale_gp_beta.lib.tracing as tracing
+
+class MockDatabase:
+    def __init__(self) -> None:
+        self._data = {
+            "SELECT * FROM users WHERE id = 1;": {"id": 1, "name": "Alice"},
+            "SELECT * FROM users WHERE id = 2;": {"id": 2, "name": "Bob"},
+        }
+    def execute_query(self, query: str, trace_id: str) -> Dict[str, Any]:
+        db_span = tracing.create_span("db_query", input={"query": query}, trace_id=trace_id)
+        db_span.start()
+        try:
+            time.sleep(random.uniform(0.1, 0.3)) # Simulate delay
+            result = self._data.get(query, {})
+            db_span.output = {"result": result}
+            return result
+        finally:
+            db_span.end()
+
+def get_user_from_db_explicit(db: MockDatabase, user_id: int, trace_id: str) -> Dict[str, Any]:
+    with tracing.create_span("get_user_from_db", input={"user_id": user_id}, trace_id=trace_id):
+        query = f"SELECT * FROM users WHERE id = {user_id};"
+        return db.execute_query(query, trace_id)
+
+def main_explicit_control_example():
+    db = MockDatabase()
+    my_trace_id = str(uuid.uuid4())
+    # Manually create a root span
+    main_span = tracing.create_span("main_explicit_call", metadata={"env": "local"}, trace_id=my_trace_id)
+    main_span.start()
+    try:
+        user = get_user_from_db_explicit(db, 1, my_trace_id)
+        print(f"Retrieved user: {user.get('name')}")
+    finally:
+        main_span.end()
+```
+
+**Exporting Existing Tracing Data (Manual Timestamps)**
+
+You can even pre-define `start_time`, `end_time`, `span_id`, `parent_id`, and `trace_id` if you need to report historical data or reconstruct traces.
+
+```python
+import uuid
+from datetime import datetime, timezone, timedelta
+import scale_gp_beta.lib.tracing as tracing
+
+parent_span_id = str(uuid.uuid4())
+trace_id = str(uuid.uuid4())
+child_span_id = str(uuid.uuid4())
+
+now = datetime.now(timezone.utc)
+
+# Parent Span
+parent_span = tracing.create_span(
+    "my_parent_span_name",
+    input={"test": "input"},
+    output={"test": "output"},
+    metadata={"test": "metadata"},
+    span_id=parent_span_id,
+    trace_id=trace_id,
+)
+parent_span.start_time = (now - timedelta(minutes=10)).isoformat()
+parent_span.end_time = now.isoformat()
+parent_span.flush(blocking=True)
+
+# Child Span
+child_span = tracing.create_span(
+    "my_child_span_name",
+    input={"test": "another input"},
+    output={"test": "another output"},
+    metadata={"test": "another metadata"},
+    span_id=child_span_id,
+    trace_id=trace_id,
+    parent_id=parent_span_id,
+)
+child_span.start_time = (now - timedelta(minutes=6)).isoformat()
+child_span.end_time = (now - timedelta(minutes=2)).isoformat()
+child_span.flush()
+```
+
+Note that `span.flush()` will by default block the main thread until the request has finished. Use `blocking=False` to enqueue the request which will be picked up by the background worker.
+
+#### Helper Methods
+
+You can retrieve the currently active span or trace in the execution context using `current_span()` and `current_trace()`:
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+
+def nested_function():
+    with tracing.create_span("nested_operation"):
+        current = tracing.current_span()
+        if current:
+            print(f"Currently active span: {current.name} (ID: {current.span_id})")
+        current_t = tracing.current_trace()
+        if current_t:
+            print(f"Currently active trace: (ID: {current_t.trace_id})")
+```
+
+#### Flushing Tracing Data
+
+Spans are generally batched and sent asynchronously by a background worker for efficiency. However, you might need to ensure all buffered spans are sent before an application exits or at critical points in your workflow (e.g., in a distributed worker setting).
+
+You can force a synchronous flush of all queued spans using `flush_queue()` or on individual spans and traces (via their root span) with `span.flush()` & `trace.root_span.flush()`.
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+
+# ... (create some spans) ...
+
+# Ensure all spans are sent before continuing
+tracing.flush_queue()
+print("All pending spans have been flushed.")
+```
+
+You do not need to manually flush all spans on program exit; when shutting down the background worker, we will attempt to flush all tracing data before exiting.
+
+#### Configuration Options
+
+| ENV Variable            | Description                                                                                                                                    |
+|:------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `DISABLE_SCALE_TRACING` | If set, no tracing data will be exported. You can still observe tracing data programmatically via the No-Op variant of Trace and Span objects. |
+| `SGP_API_KEY`           | SGP API Key. Used by `SGPClient`.                                                                                                              |
+| `SGP_ACCOUNT_ID`        | SGP Account ID. Used by `SGPClient`.                                                                                                           |
+
+#### Multi-Process / Multi-Worker Tracing
+
+> **_WARNING:_** Developers should be careful when attempting tracing over multiple workers / Python processes. The SGP backend will expect well-formed trace data, and there is a strong chance of race conditions if a child span is reported before a parent span.
+
+The easiest approach to working over multiple workers and Python processes is to only create one trace per worker. You can group traces with a `group_id`.
+
+If you want to track an entire workflow over multiple workers, ensure you call `tracing.flush_queue()` before you enqueue a job which creates child spans of the current trace.
+
+You will need to use the explicit controls to forward trace and parent span IDs to your workers. The automatic context detection works within the context of the original Python process only.
+
+
 ## Async usage
 
 Simply import `AsyncSGPClient` instead of `SGPClient` and use `await` with each API call:

{scale_gp_beta-0.1.0a21 → scale_gp_beta-0.1.0a22}/README.md

@@ -46,6 +46,244 @@ we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
 to add `SGP_API_KEY="My API Key"` to your `.env` file
 so that your API Key is not stored in source control.
 
+---
+
+## Tracing & Spans
+
+The SGP Tracing library provides a convenient way to instrument your Python applications with tracing capabilities, allowing you to generate, manage, and send spans to the Scale GP platform. This enables detailed monitoring and debugging of your workflows.
+
+### Quick Start Examples
+
+For runnable examples, see the [examples/tracing](https://github.com/scaleapi/sgp-python-beta/tree/main/examples/tracing) directory in the repository.
+
+### Using the SDK
+
+#### Initialization
+
+Before you can create any traces or spans, you should initialize the tracing SDK with your `SGPClient`. It's best practice to do this once at your application's entry point. You can omit this step if you have set the `SGP_API_KEY` and `SGP_ACCOUNT_ID` environment variables, as the SDK will attempt to create a default client.
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+from scale_gp_beta import SGPClient
+
+client = SGPClient(api_key="YOUR_API_KEY", account_id="YOUR_ACCOUNT_ID")
+tracing.init(client=client)
+```
+
+Tracing uses the `SGPClient` for all requests. You can edit the `base_url` or any other parameters via the client you pass to `init()`.
+
+#### Disabling Tracing
+
+You can disable tracing by setting the environment variable `DISABLE_SCALE_TRACING` or programmatically via the `disabled` parameter in `init()`.
+
+#### Core Concepts
+
+The SDK revolves around two primary concepts: **Traces** and **Spans**.
+
+  * **Trace:** A trace represents a complete workflow or transaction, such as a web request or an AI agent's operation. It's a collection of related spans. Every trace has a single **root span**.
+  * **Span:** A span represents a single unit of work within a trace, like a function call, a database query, or an external API request. Spans can be nested to show hierarchical relationships.
+
+When starting a trace, we will also create a root span. Server-side, we do not record the trace resource, only spans, but rely on the root span for trace data.
+
+#### Creating Traces and Spans
+
+The SDK offers flexible ways to create traces and spans: using **context managers** for automatic start/end handling, or **explicit control** for manual lifecycle management.
+
+##### 1\. Using Context Managers (Recommended)
+
+The most straightforward way to create traces and spans is by using them as context managers (`with` statements). This ensures that spans are automatically started and ended, and errors are captured.
+
+**Creating a Trace with a Root Span:**
+
+Use `tracing.create_trace()` as a context manager to define a new trace. This automatically creates a root span for your trace.
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+
+def my_workflow():
+    with tracing.create_trace(name="my_application_workflow", metadata={"env": "production"}):
+        # All spans created within this block will belong to "my_application_workflow" trace
+        print("Starting my application workflow...")
+        # ... your workflow logic
+        print("Application workflow completed.")
+```
+
+**Creating Spans within a Trace:**
+
+Inside a `create_trace` block, use `tracing.create_span()` as a context manager. These spans will automatically be associated with the current trace and parent span (if one exists).
+
+```python
+import time
+import scale_gp_beta.lib.tracing as tracing
+
+def fibonacci(curr: int) -> int:
+    with tracing.create_span("fibonacci_calculation", input={"curr": curr}) as span:
+        time.sleep(0.1) # Simulate some work
+        if curr < 2:
+            span.output = {"res": curr}
+            return curr
+        res = fibonacci(curr - 1) + fibonacci(curr - 2)
+        span.output = {"res": res}
+        return res
+
+def main_traced_example():
+    with tracing.create_trace("my_fibonacci_trace"): # Creates a root span
+        # This span will be a child of the "my_fibonacci_trace" root span
+        with tracing.create_span("main_execution", metadata={"version": "1.0"}) as main_span:
+            fib_result = fibonacci(5)
+            main_span.output = {"final_fib_result": fib_result}
+            print(f"Fibonacci(5) = {fib_result}")
+```
+
+##### 2\. Explicit Control
+
+For scenarios where context managers aren't suitable, you can manually start and end spans. This approach requires more diligence to ensure all spans are properly ended and maintaining consistency.
+
+**Manually Managing Spans (without an explicit Trace context):**
+
+You can create spans and explicitly provide their `trace_id` and `parent_id` for fine-grained control. This is useful when integrating with existing systems that manage trace IDs.
+
+```python
+import uuid
+import time
+import random
+from typing import Any, Dict
+import scale_gp_beta.lib.tracing as tracing
+
+class MockDatabase:
+    def __init__(self) -> None:
+        self._data = {
+            "SELECT * FROM users WHERE id = 1;": {"id": 1, "name": "Alice"},
+            "SELECT * FROM users WHERE id = 2;": {"id": 2, "name": "Bob"},
+        }
+    def execute_query(self, query: str, trace_id: str) -> Dict[str, Any]:
+        db_span = tracing.create_span("db_query", input={"query": query}, trace_id=trace_id)
+        db_span.start()
+        try:
+            time.sleep(random.uniform(0.1, 0.3)) # Simulate delay
+            result = self._data.get(query, {})
+            db_span.output = {"result": result}
+            return result
+        finally:
+            db_span.end()
+
+def get_user_from_db_explicit(db: MockDatabase, user_id: int, trace_id: str) -> Dict[str, Any]:
+    with tracing.create_span("get_user_from_db", input={"user_id": user_id}, trace_id=trace_id):
+        query = f"SELECT * FROM users WHERE id = {user_id};"
+        return db.execute_query(query, trace_id)
+
+def main_explicit_control_example():
+    db = MockDatabase()
+    my_trace_id = str(uuid.uuid4())
+    # Manually create a root span
+    main_span = tracing.create_span("main_explicit_call", metadata={"env": "local"}, trace_id=my_trace_id)
+    main_span.start()
+    try:
+        user = get_user_from_db_explicit(db, 1, my_trace_id)
+        print(f"Retrieved user: {user.get('name')}")
+    finally:
+        main_span.end()
+```
+
+**Exporting Existing Tracing Data (Manual Timestamps)**
+
+You can even pre-define `start_time`, `end_time`, `span_id`, `parent_id`, and `trace_id` if you need to report historical data or reconstruct traces.
+
+```python
+import uuid
+from datetime import datetime, timezone, timedelta
+import scale_gp_beta.lib.tracing as tracing
+
+parent_span_id = str(uuid.uuid4())
+trace_id = str(uuid.uuid4())
+child_span_id = str(uuid.uuid4())
+
+now = datetime.now(timezone.utc)
+
+# Parent Span
+parent_span = tracing.create_span(
+    "my_parent_span_name",
+    input={"test": "input"},
+    output={"test": "output"},
+    metadata={"test": "metadata"},
+    span_id=parent_span_id,
+    trace_id=trace_id,
+)
+parent_span.start_time = (now - timedelta(minutes=10)).isoformat()
+parent_span.end_time = now.isoformat()
+parent_span.flush(blocking=True)
+
+# Child Span
+child_span = tracing.create_span(
+    "my_child_span_name",
+    input={"test": "another input"},
+    output={"test": "another output"},
+    metadata={"test": "another metadata"},
+    span_id=child_span_id,
+    trace_id=trace_id,
+    parent_id=parent_span_id,
+)
+child_span.start_time = (now - timedelta(minutes=6)).isoformat()
+child_span.end_time = (now - timedelta(minutes=2)).isoformat()
+child_span.flush()
+```
+
+Note that `span.flush()` will by default block the main thread until the request has finished. Use `blocking=False` to enqueue the request which will be picked up by the background worker.
+
+#### Helper Methods
+
+You can retrieve the currently active span or trace in the execution context using `current_span()` and `current_trace()`:
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+
+def nested_function():
+    with tracing.create_span("nested_operation"):
+        current = tracing.current_span()
+        if current:
+            print(f"Currently active span: {current.name} (ID: {current.span_id})")
+        current_t = tracing.current_trace()
+        if current_t:
+            print(f"Currently active trace: (ID: {current_t.trace_id})")
+```
+
+#### Flushing Tracing Data
+
+Spans are generally batched and sent asynchronously by a background worker for efficiency. However, you might need to ensure all buffered spans are sent before an application exits or at critical points in your workflow (e.g., in a distributed worker setting).
+
+You can force a synchronous flush of all queued spans using `flush_queue()` or on individual spans and traces (via their root span) with `span.flush()` & `trace.root_span.flush()`.
+
+```python
+import scale_gp_beta.lib.tracing as tracing
+
+# ... (create some spans) ...
+
+# Ensure all spans are sent before continuing
+tracing.flush_queue()
+print("All pending spans have been flushed.")
+```
+
+You do not need to manually flush all spans on program exit; when shutting down the background worker, we will attempt to flush all tracing data before exiting.
+
+#### Configuration Options
+
+| ENV Variable            | Description                                                                                                                                    |
+|:------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `DISABLE_SCALE_TRACING` | If set, no tracing data will be exported. You can still observe tracing data programmatically via the No-Op variant of Trace and Span objects. |
+| `SGP_API_KEY`           | SGP API Key. Used by `SGPClient`.                                                                                                              |
+| `SGP_ACCOUNT_ID`        | SGP Account ID. Used by `SGPClient`.                                                                                                           |
+
+#### Multi-Process / Multi-Worker Tracing
+
+> **_WARNING:_** Developers should be careful when attempting tracing over multiple workers / Python processes. The SGP backend will expect well-formed trace data, and there is a strong chance of race conditions if a child span is reported before a parent span.
+
+The easiest approach to working over multiple workers and Python processes is to only create one trace per worker. You can group traces with a `group_id`.
+
+If you want to track an entire workflow over multiple workers, ensure you call `tracing.flush_queue()` before you enqueue a job which creates child spans of the current trace.
+
+You will need to use the explicit controls to forward trace and parent span IDs to your workers. The automatic context detection works within the context of the original Python process only.
+
+
 ## Async usage
 
 Simply import `AsyncSGPClient` instead of `SGPClient` and use `await` with each API call:

{scale_gp_beta-0.1.0a21 → scale_gp_beta-0.1.0a22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scale-gp-beta"
-version = "0.1.0-alpha.21"
+version = "0.1.0-alpha.22"
 description = "The official Python library for the Scale GP API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{scale_gp_beta-0.1.0a21 → scale_gp_beta-0.1.0a22}/src/scale_gp_beta/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "scale_gp_beta"
-__version__ = "0.1.0-alpha.21"  # x-release-please-version
+__version__ = "0.1.0-alpha.22"  # x-release-please-version

scale_gp_beta-0.1.0a21/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.1.0-alpha.21"
-}