paid-python 0.1.0__tar.gz → 0.1.1__tar.gz

{paid_python-0.1.0 → paid_python-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: paid-python
-Version: 0.1.0
+Version: 0.1.1
 Summary: 
 Requires-Python: >=3.9,<3.14
 Classifier: Intended Audience :: Developers
@@ -205,6 +205,98 @@ def image_generate():
 image_generate()
 ```
 
+### Passing User Metadata
+
+You can attach custom metadata to your traces by passing a `metadata` dictionary to the `paid_tracing()` decorator or context manager. This metadata will be stored with the trace and can be used to filter and query traces later.
+
+<Tabs>
+  <Tab title="Python - Decorator">
+    ```python
+    from paid.tracing import paid_tracing, signal
+    from paid.tracing.wrappers import PaidOpenAI
+    from openai import OpenAI
+
+    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+    @paid_tracing(
+        "customer_123",
+        "agent_123",
+        metadata={
+            "campaign_id": "campaign_456",
+            "environment": "production",
+            "user_tier": "enterprise"
+        }
+    )
+    def process_event(event):
+        """Process event with custom metadata"""
+        response = openai_client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": event.content}]
+        )
+
+        signal("event_processed", enable_cost_tracing=True)
+        return response
+
+    process_event(incoming_event)
+    ```
+  </Tab>
+
+  <Tab title="Python - Context Manager">
+    ```python
+    from paid.tracing import paid_tracing, signal
+    from paid.tracing.wrappers import PaidOpenAI
+    from openai import OpenAI
+
+    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+    def process_event(event):
+        """Process event with custom metadata"""
+        response = openai_client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": event.content}]
+        )
+
+        signal("event_processed", enable_cost_tracing=True)
+        return response
+
+    # Pass metadata to context manager
+    with paid_tracing(
+        "customer_123",
+        external_agent_id="agent_123",
+        metadata={
+            "campaign_id": "campaign_456",
+            "environment": "production",
+            "user_tier": "enterprise"
+        }
+    ):
+        process_event(incoming_event)
+    ```
+  </Tab>
+
+  <Tab title="Node.js">
+    ```typescript
+    // Metadata support is not yet available in the Node.js SDK.
+    // Please use Python for passing custom metadata to traces.
+    ```
+  </Tab>
+</Tabs>
+
+#### Querying Traces by Metadata
+
+Once you've added metadata to your traces, you can filter traces using the metadata parameter in the traces API endpoint:
+
+```bash
+# Filter by single metadata field
+curl -G "https://api.paid.ai/api/organizations/{orgId}/traces" \
+  --data-urlencode 'metadata={"campaign_id":"campaign_456"}' \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+# Filter by multiple metadata fields (all must match)
+curl -G "https://api.paid.ai/api/organizations/{orgId}/traces" \
+  --data-urlencode 'metadata={"campaign_id":"campaign_456","environment":"production"}' \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
 ### Auto-Instrumentation (OpenTelemetry Instrumentors)
 
 For maximum convenience, you can use OpenTelemetry auto-instrumentation to automatically track costs without modifying your AI library calls. This approach uses official OpenTelemetry instrumentors for supported AI libraries.

{paid_python-0.1.0 → paid_python-0.1.1}/README.md

@@ -170,6 +170,98 @@ def image_generate():
 image_generate()
 ```
 
+### Passing User Metadata
+
+You can attach custom metadata to your traces by passing a `metadata` dictionary to the `paid_tracing()` decorator or context manager. This metadata will be stored with the trace and can be used to filter and query traces later.
+
+<Tabs>
+  <Tab title="Python - Decorator">
+    ```python
+    from paid.tracing import paid_tracing, signal
+    from paid.tracing.wrappers import PaidOpenAI
+    from openai import OpenAI
+
+    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+    @paid_tracing(
+        "customer_123",
+        "agent_123",
+        metadata={
+            "campaign_id": "campaign_456",
+            "environment": "production",
+            "user_tier": "enterprise"
+        }
+    )
+    def process_event(event):
+        """Process event with custom metadata"""
+        response = openai_client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": event.content}]
+        )
+
+        signal("event_processed", enable_cost_tracing=True)
+        return response
+
+    process_event(incoming_event)
+    ```
+  </Tab>
+
+  <Tab title="Python - Context Manager">
+    ```python
+    from paid.tracing import paid_tracing, signal
+    from paid.tracing.wrappers import PaidOpenAI
+    from openai import OpenAI
+
+    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+    def process_event(event):
+        """Process event with custom metadata"""
+        response = openai_client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": event.content}]
+        )
+
+        signal("event_processed", enable_cost_tracing=True)
+        return response
+
+    # Pass metadata to context manager
+    with paid_tracing(
+        "customer_123",
+        external_agent_id="agent_123",
+        metadata={
+            "campaign_id": "campaign_456",
+            "environment": "production",
+            "user_tier": "enterprise"
+        }
+    ):
+        process_event(incoming_event)
+    ```
+  </Tab>
+
+  <Tab title="Node.js">
+    ```typescript
+    // Metadata support is not yet available in the Node.js SDK.
+    // Please use Python for passing custom metadata to traces.
+    ```
+  </Tab>
+</Tabs>
+
+#### Querying Traces by Metadata
+
+Once you've added metadata to your traces, you can filter traces using the metadata parameter in the traces API endpoint:
+
+```bash
+# Filter by single metadata field
+curl -G "https://api.paid.ai/api/organizations/{orgId}/traces" \
+  --data-urlencode 'metadata={"campaign_id":"campaign_456"}' \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+# Filter by multiple metadata fields (all must match)
+curl -G "https://api.paid.ai/api/organizations/{orgId}/traces" \
+  --data-urlencode 'metadata={"campaign_id":"campaign_456","environment":"production"}' \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
 ### Auto-Instrumentation (OpenTelemetry Instrumentors)
 
 For maximum convenience, you can use OpenTelemetry auto-instrumentation to automatically track costs without modifying your AI library calls. This approach uses official OpenTelemetry instrumentors for supported AI libraries.

{paid_python-0.1.0 → paid_python-0.1.1}/pyproject.toml

@@ -3,7 +3,7 @@ name = "paid-python"
 
 [tool.poetry]
 name = "paid-python"
-version = "0.1.0"
+version = "0.1.1"
 description = ""
 readme = "README.md"
 authors = []

{paid_python-0.1.0 → paid_python-0.1.1}/src/paid/tracing/context_manager.py

@@ -62,7 +62,7 @@ class paid_tracing:
 
     def __init__(
         self,
-        external_customer_id: str,
+        external_customer_id: Optional[str] = None,
         *,
         external_agent_id: Optional[str] = None,
         tracing_token: Optional[int] = None,

{paid_python-0.1.0 → paid_python-0.1.1}/src/paid/tracing/tracing.py

@@ -258,7 +258,7 @@ def get_paid_tracer() -> trace.Tracer:
 
 
 def trace_sync_(
-    external_customer_id: str,
+    external_customer_id: Optional[str],
     fn: Callable[..., T],
     external_agent_id: Optional[str] = None,
     tracing_token: Optional[int] = None,
@@ -316,9 +316,6 @@ def trace_sync_(
         tracer = get_paid_tracer()
         logger.info(f"Creating span for external_customer_id: {external_customer_id}")
         with tracer.start_as_current_span("parent_span", context=ctx) as span:
-            span.set_attribute("external_customer_id", external_customer_id)
-            if external_agent_id:
-                span.set_attribute("external_agent_id", external_agent_id)
             try:
                 result = fn(*args, **kwargs)
                 span.set_status(Status(StatusCode.OK))
@@ -335,7 +332,7 @@ def trace_sync_(
 
 
 async def trace_async_(
-    external_customer_id: str,
+    external_customer_id: Optional[str],
     fn: Callable[..., Union[T, Awaitable[T]]],
     external_agent_id: Optional[str] = None,
     tracing_token: Optional[int] = None,
@@ -393,9 +390,6 @@ async def trace_async_(
         tracer = get_paid_tracer()
         logger.info(f"Creating span for external_customer_id: {external_customer_id}")
         with tracer.start_as_current_span("parent_span", context=ctx) as span:
-            span.set_attribute("external_customer_id", external_customer_id)
-            if external_agent_id:
-                span.set_attribute("external_agent_id", external_agent_id)
             try:
                 if asyncio.iscoroutinefunction(fn):
                     result = await fn(*args, **kwargs)