paid-python 0.0.5a40__py3-none-any.whl → 0.1.1__py3-none-any.whl

paid/tracing/wrappers/openai_agents/openaiAgentsHook.py

@@ -1,14 +1,10 @@
 from typing import Any, Optional
 
-from opentelemetry import trace
-from opentelemetry.trace import Status, StatusCode
+from opentelemetry.trace import Span, Status, StatusCode
 
+from paid.logger import logger
 from paid.tracing.tracing import (
     get_paid_tracer,
-    logger,
-    paid_external_agent_id_var,
-    paid_external_customer_id_var,
-    paid_token_var,
 )
 
 try:
@@ -22,7 +18,7 @@ except ImportError:
 
 # Global dictionary to store spans keyed by context object ID
 # This avoids polluting user's context.context and works across async boundaries
-_paid_span_store: dict[int, trace.Span] = {}
+_paid_span_store: dict[int, Span] = {}
 
 
 class PaidOpenAIAgentsHook(RunHooks[Any]):
@@ -32,14 +28,12 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
     Can optionally wrap user-provided hooks to combine Paid tracking with custom behavior.
     """
 
-    def __init__(self, user_hooks: Optional[RunHooks[Any]] = None, optional_tracing: bool = False):
+    def __init__(self, user_hooks: Optional[RunHooks[Any]] = None):
         """
         Initialize PaidAgentsHook.
 
         Args:
             user_hooks: Optional user-provided RunHooks to combine with Paid tracking
-            optional_tracing: If True, gracefully skip tracing when context is missing.
-                             If False, raise errors when tracing context is not available.
 
         Usage:
             @paid_tracing("<ext_customer_id>", "<ext_agent_id>")
@@ -55,67 +49,26 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
 
             my_hook = MyHook()
             hook = PaidAgentsHook(user_hooks=my_hook)
-
-            # Optional tracing (won't raise errors if context missing)
-            hook = PaidAgentsHook(optional_tracing=True)
         """
         super().__init__()
-        self.tracer = get_paid_tracer()
-        self.optional_tracing = optional_tracing
         self.user_hooks = user_hooks
 
-    def _get_context_vars(self):
-        """Get tracing context from context variables set by Paid.trace()."""
-        external_customer_id = paid_external_customer_id_var.get()
-        external_agent_id = paid_external_agent_id_var.get()
-        token = paid_token_var.get()
-        return external_customer_id, external_agent_id, token
-
-    def _should_skip_tracing(self, external_customer_id: Optional[str], token: Optional[str]) -> bool:
-        """Check if tracing should be skipped."""
-        # Check if there's an active span (from Paid.trace())
-        current_span = trace.get_current_span()
-        if current_span == trace.INVALID_SPAN:
-            if self.optional_tracing:
-                logger.info(f"{self.__class__.__name__} No tracing, skipping LLM tracking.")
-                return True
-            raise RuntimeError("No OTEL span found. Make sure to call this method from Paid.trace().")
-
-        if not (external_customer_id and token):
-            if self.optional_tracing:
-                logger.info(f"{self.__class__.__name__} No external_customer_id or token, skipping LLM tracking")
-                return True
-            raise RuntimeError(
-                "Missing required tracing information: external_customer_id or token."
-                " Make sure to call this method from Paid.trace()."
-            )
-        return False
-
     def _start_span(self, context, agent, hook_name) -> None:
         try:
-            external_customer_id, external_agent_id, token = self._get_context_vars()
-
-            # Skip tracing if required context is missing
-            if self._should_skip_tracing(external_customer_id, token):
-                return
+            tracer = get_paid_tracer()
 
             # Get model name from agent
             model_name = str(agent.model if agent.model else get_default_model())
 
             # Start span for this LLM call
-            span = self.tracer.start_span(f"openai.agents.{hook_name}")
-            logger.debug(f"{hook_name} : started span")
+            span = tracer.start_span(f"openai.agents.{hook_name}")
 
             # Set initial attributes
             attributes = {
                 "gen_ai.system": "openai",
                 "gen_ai.operation.name": f"{hook_name}",
-                "external_customer_id": external_customer_id,
-                "token": token,
                 "gen_ai.request.model": model_name,
             }
-            if external_agent_id:
-                attributes["external_agent_id"] = external_agent_id
 
             span.set_attributes(attributes)
 
@@ -123,7 +76,6 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
             # This works across async boundaries without polluting user's context
             context_id = id(context)
             _paid_span_store[context_id] = span
-            logger.debug(f"_start_span: Stored span for context ID {context_id}")
 
         except Exception as error:
             logger.error(f"Error while starting span in PaidAgentsHook.{hook_name}: {error}")
@@ -133,7 +85,6 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
             # Retrieve span from global dict using context object ID
             context_id = id(context)
             span = _paid_span_store.get(context_id)
-            logger.debug(f"_end_span: Retrieved span for context ID {context_id}: {span}")
 
             if span:
                 # Get usage data from the response
@@ -161,17 +112,13 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
                     span.set_status(Status(StatusCode.ERROR, "No usage available"))
 
                 span.end()
-                logger.debug(f"{hook_name} : ended span")
 
                 # Clean up from global dict
                 del _paid_span_store[context_id]
-                logger.debug(f"_end_span: Cleaned up span for context ID {context_id}")
-            else:
-                logger.warning(f"_end_span: No span found for context ID {context_id}")
 
         except Exception as error:
-            logger.error(f"Error while ending span in PaidAgentsHook.{hook_name}_end: {error}")
             # Try to end span on error
+            logger.error(f"Error while ending span in PaidAgentsHook.{hook_name}: {error}")
             try:
                 context_id = id(context)
                 span = _paid_span_store.get(context_id)
@@ -181,26 +128,18 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
                     span.end()
                     del _paid_span_store[context_id]
             except:
-                pass
+                logger.error(f"Failed to end span after error in PaidAgentsHook.{hook_name}")
 
     async def on_llm_start(self, context, agent, system_prompt, input_items) -> None:
-        logger.debug(f"on_llm_start : context_usage : {getattr(context, 'usage', None)}")
-
         if self.user_hooks and hasattr(self.user_hooks, "on_llm_start"):
             await self.user_hooks.on_llm_start(context, agent, system_prompt, input_items)
 
     async def on_llm_end(self, context, agent, response) -> None:
-        logger.debug(
-            f"on_llm_end : context_usage : {getattr(context, 'usage', None)} : response_usage : {getattr(response, 'usage', None)}"
-        )
-
         if self.user_hooks and hasattr(self.user_hooks, "on_llm_end"):
             await self.user_hooks.on_llm_end(context, agent, response)
 
     async def on_agent_start(self, context, agent) -> None:
         """Start a span for agent operations and call user hooks."""
-        logger.debug(f"on_agent_start : context_usage : {getattr(context, 'usage', None)}")
-
         if self.user_hooks and hasattr(self.user_hooks, "on_agent_start"):
             await self.user_hooks.on_agent_start(context, agent)
 
@@ -208,26 +147,19 @@ class PaidOpenAIAgentsHook(RunHooks[Any]):
 
     async def on_agent_end(self, context, agent, output) -> None:
         """End the span for agent operations and call user hooks."""
-        logger.debug(f"on_agent_end : context_usage : {getattr(context, 'usage', None)}")
-
         self._end_span(context, "on_agent")
 
         if self.user_hooks and hasattr(self.user_hooks, "on_agent_end"):
             await self.user_hooks.on_agent_end(context, agent, output)
 
     async def on_handoff(self, context, from_agent, to_agent) -> None:
-        logger.debug(f"on_handoff : context_usage : {getattr(context, 'usage', None)}")
         if self.user_hooks and hasattr(self.user_hooks, "on_handoff"):
             await self.user_hooks.on_handoff(context, from_agent, to_agent)
 
     async def on_tool_start(self, context, agent, tool) -> None:
-        logger.debug(f"on_tool_start : context_usage : {getattr(context, 'usage', None)}")
-
         if self.user_hooks and hasattr(self.user_hooks, "on_tool_start"):
             await self.user_hooks.on_tool_start(context, agent, tool)
 
     async def on_tool_end(self, context, agent, tool, result) -> None:
-        logger.debug(f"on_tool_end : context_usage : {getattr(context, 'usage', None)}")
-
         if self.user_hooks and hasattr(self.user_hooks, "on_tool_end"):
             await self.user_hooks.on_tool_end(context, agent, tool, result)

{paid_python-0.0.5a40.dist-info → paid_python-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: paid-python
-Version: 0.0.5a40
+Version: 0.1.1
 Summary: 
 Requires-Python: >=3.9,<3.14
 Classifier: Intended Audience :: Developers
@@ -135,7 +135,7 @@ from paid.tracing import paid_tracing
 
 @paid_tracing("<external_customer_id>", external_agent_id="<optional_external_agent_id>")
 def some_agent_workflow():  # your function
-    # Your logic - use any AI providers with Paid wrappers or send signals with Paid.signal().
+    # Your logic - use any AI providers with Paid wrappers or send signals with signal().
     # This function is typically an event processor that should lead to AI calls or events emitted as Paid signals
 ```
 
@@ -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.
@@ -263,31 +355,24 @@ paid_autoinstrument(libraries=["anthropic", "openai"])
 
 - Auto-instrumentation uses official OpenTelemetry instrumentors for each AI library
 - It automatically wraps library calls without requiring you to use Paid wrapper classes
-- Works seamlessly with `@paid_tracing()` decorator or `Paid.trace()` callback
+- Works seamlessly with `@paid_tracing()` decorator or context manager
 - Costs are tracked in the same way as when using manual wrappers
 - Should be called once during application startup, typically before creating AI client instances
 
 ## Signaling via OTEL tracing
 
-A more reliable and user-friendly way to send signals is to send them via OTEL tracing.
-This allows you to send signals with less arguments and boilerplate as the information is available in the tracing context `Paid.trace()` or `@paid_tracing()`.
-The interface is `Paid.signal()`, which takes in signal name, optional data, and a flag that attaches costs from the same trace.
-`Paid.signal()` has to be called within a trace - meaning inside of a callback to `Paid.trace()`.
-In contrast to `Paid.usage.record_bulk()`, `Paid.signal()` is using OpenTelemetry to provide reliable delivery.
+Signals allow you to emit events within your tracing context. They have access to all tracing information, so you need fewer arguments compared to manual API calls.
+Use the `signal()` function which must be called within an active `@paid_tracing()` context (decorator or context manager).
 
 Here's an example of how to use it:
 
 ```python
-from paid import Paid
-from paid.tracing import paid_tracing
+from paid.tracing import paid_tracing, signal
 
-# Initialize Paid SDK
-client = Paid(token="PAID_API_KEY")
-
-@paid_tracing("your_external_customer_id", "your_external_agent_id")  # external_agent_id is necessary for sending signals
+@paid_tracing("your_external_customer_id", "your_external_agent_id")
 def do_work():
     # ...do some work...
-    client.signal(
+    signal(
         event_name="<your_signal_name>",
         data={ } # optional data (ex. manual cost tracking data)
     )
@@ -295,28 +380,21 @@ def do_work():
 do_work()
 ```
 
-Same, but using callback to specify the function to trace:
+Same approach with context manager:
 
 ```python
-from paid import Paid
-
-# Initialize Paid SDK
-client = Paid(token="PAID_API_KEY")
-
-# Initialize tracing, must be after initializing Paid SDK
-client.initialize_tracing()
+from paid.tracing import paid_tracing, signal
 
 def do_work():
     # ...do some work...
-    client.signal(
+    signal(
         event_name="<your_signal_name>",
         data={ } # optional data (ex. manual cost tracking data)
     )
 
-# Finally, capture the traces!
-client.trace(external_customer_id = "<your_external_customer_id>",
-                external_agent_id = "<your_external_agent_id>",  # external_agent_id is required for signals
-                fn = lambda: do_work())
+# Use context manager instead
+with paid_tracing("your_external_customer_id", "your_external_agent_id"):
+    do_work()
 ```
 
 ### Signal-costs - Attaching cost traces to a signal
@@ -328,17 +406,13 @@ as the wrappers and hooks that recorded those costs.
 This will look something like this:
 
 ```python
-from paid import Paid
-from paid.tracing import paid_tracing
+from paid.tracing import paid_tracing, signal
 
-# Initialize Paid SDK
-client = Paid(token="PAID_API_KEY")
-
-@paid_tracing("your_external_customer_id", "your_external_agent_id")  # external_agent_id is necessary for sending signals
+@paid_tracing("your_external_customer_id", "your_external_agent_id")
 def do_work():
     # ... your workflow logic
     # ... your AI calls made through Paid wrappers or hooks
-    client.signal(
+    signal(
         event_name="<your_signal_name>",
         data={ }, # optional data (ex. manual cost tracking data)
         enable_cost_tracing=True, # set this flag to associate it with costs
@@ -356,20 +430,17 @@ Then, all of the costs traced in @paid_tracing() context are related to that sig
 Sometimes your agent workflow cannot fit into a single traceable function like above,
 because it has to be disjoint for whatever reason. It could even be running across different machines.
 
-For such cases, you can pass a tracing token directly to `@paid_tracing()` or `Paid.trace()` to link distributed traces together.
+For such cases, you can pass a tracing token directly to `@paid_tracing()` or context manager to link distributed traces together.
 
 #### Using `tracing_token` parameter (Recommended)
 
-The simplest way to implement distributed tracing is to pass the token directly to the decorator or trace function:
+The simplest way to implement distributed tracing is to pass the token directly to the decorator or context manager:
 
 ```python
-from paid import Paid
-from paid.tracing import paid_tracing, generate_tracing_token
+from paid.tracing import paid_tracing, signal, generate_tracing_token
 from paid.tracing.wrappers.openai import PaidOpenAI
 from openai import OpenAI
 
-# Initialize
-client = Paid(token="<PAID_API_KEY>")
 openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
 
 # Process 1: Generate token and do initial work
@@ -387,7 +458,7 @@ def process_part_1():
         messages=[{"role": "user", "content": "Analyze data"}]
     )
     # Signal without cost tracing
-    client.signal("part_1_complete", enable_cost_tracing=False)
+    signal("part_1_complete", enable_cost_tracing=False)
 
 process_part_1()
 
@@ -402,164 +473,42 @@ def process_part_2():
         messages=[{"role": "user", "content": "Generate response"}]
     )
     # Signal WITH cost tracing - links all costs from both processes
-    client.signal("workflow_complete", enable_cost_tracing=True)
+    signal("workflow_complete", enable_cost_tracing=True)
 
 process_part_2()
 # No cleanup needed - token is scoped to the decorated function
 ```
 
-Using `Paid.trace()` instead of decorator:
+Using context manager instead of decorator:
 
 ```python
-from paid import Paid
-from paid.tracing import generate_tracing_token
+from paid.tracing import paid_tracing, signal, generate_tracing_token
 from paid.tracing.wrappers.openai import PaidOpenAI
 from openai import OpenAI
 
 # Initialize
-client = Paid(token="<PAID_API_KEY>")
-client.initialize_tracing()
 openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
 
-# Process 1: Generate and use token
+# Process 1: Generate token and do initial work
 token = generate_tracing_token()
 save_to_storage("workflow_123", token)
 
-def process_part_1():
+with paid_tracing("customer_123", external_agent_id="agent_123", tracing_token=token):
     response = openai_client.chat.completions.create(
         model="gpt-4",
         messages=[{"role": "user", "content": "Analyze data"}]
     )
-    client.signal("part_1_complete", enable_cost_tracing=False)
-
-client.trace(
-    external_customer_id="customer_123",
-    external_agent_id="agent_123",
-    tracing_token=token,
-    fn=lambda: process_part_1()
-)
+    signal("part_1_complete", enable_cost_tracing=False)
 
 # Process 2: Retrieve and use the same token
 token = load_from_storage("workflow_123")
 
-def process_part_2():
+with paid_tracing("customer_123", external_agent_id="agent_123", tracing_token=token):
     response = openai_client.chat.completions.create(
         model="gpt-4",
         messages=[{"role": "user", "content": "Generate response"}]
     )
-    client.signal("workflow_complete", enable_cost_tracing=True)
-
-client.trace(
-    external_customer_id="customer_123",
-    external_agent_id="agent_123",
-    tracing_token=token,
-    fn=lambda: process_part_2()
-)
-```
-
-#### Alternative: Using global context (Advanced)
-
-For more complex scenarios where you need to set the tracing context globally, you can use these functions:
-
-```python
-from paid.tracing import (
-    generate_tracing_token,
-    generate_and_set_tracing_token,
-    set_tracing_token,
-    unset_tracing_token
-)
-
-def generate_tracing_token() -> int:
-    """
-    Generates and returns a tracing token without setting it in the tracing context.
-    Useful when you only want to store or send a tracing token somewhere else
-    without immediately activating it.
-
-    Returns:
-        int: The tracing token (OpenTelemetry trace ID)
-    """
-
-def generate_and_set_tracing_token() -> int:
-    """
-    This function returns tracing token and attaches it to all consequent
-    Paid.trace() or @paid_tracing tracing contexts. So all the costs and signals that share this
-    tracing context are associated with each other.
-
-    To stop associating the traces one can either call
-    generate_and_set_tracing_token() once again or call unset_tracing_token().
-    The former is suitable if you still want to trace but in a fresh
-    context, and the latter will go back to unique traces per Paid.trace().
-
-    Returns:
-        int: The tracing token (OpenTelemetry trace ID)
-    """
-
-def set_tracing_token(token: int):
-    """
-    Sets tracing token. Provided token should come from generate_and_set_tracing_token()
-    or generate_tracing_token(). Once set, the consequent traces Paid.trace() or
-    @paid_tracing() will be related to each other.
-
-    Args:
-        token (int): A tracing token from generate_and_set_tracing_token() or generate_tracing_token()
-    """
-
-def unset_tracing_token():
-    """
-    Unsets the token previously set by generate_and_set_tracing_token()
-    or by set_tracing_token(token). Does nothing if the token was never set.
-    """
-```
-
-Example using global context:
-
-```python
-from paid import Paid
-from paid.tracing import paid_tracing, generate_and_set_tracing_token, set_tracing_token, unset_tracing_token
-from paid.tracing.wrappers.openai import PaidOpenAI
-from openai import OpenAI
-
-# Initialize
-client = Paid(token="<PAID_API_KEY>")
-openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
-
-# Process 1: Generate token and do initial work
-token = generate_and_set_tracing_token()
-print(f"Tracing token: {token}")
-
-# Store token for other processes (e.g., in Redis, database, message queue)
-save_to_storage("workflow_123", token)
-
-@paid_tracing("customer_123", external_agent_id="agent_123")
-def process_part_1():
-    # AI calls here will be traced
-    response = openai_client.chat.completions.create(
-        model="gpt-4",
-        messages=[{"role": "user", "content": "Analyze data"}]
-    )
-    # Signal without cost tracing
-    client.signal("part_1_complete", enable_cost_tracing=False)
-
-process_part_1()
-
-# Process 2 (different machine/process): Retrieve and use token
-token = load_from_storage("workflow_123")
-set_tracing_token(token)
-
-@paid_tracing("customer_123", external_agent_id="agent_123")
-def process_part_2():
-    # AI calls here will be linked to the same trace
-    response = openai_client.chat.completions.create(
-        model="gpt-4",
-        messages=[{"role": "user", "content": "Generate response"}]
-    )
-    # Signal WITH cost tracing - links all costs from both processes
-    client.signal("workflow_complete", enable_cost_tracing=True)
-
-process_part_2()
-
-# Clean up
-unset_tracing_token()
+    signal("workflow_complete", enable_cost_tracing=True)
 ```
 
 ## Manual Cost Tracking
@@ -594,16 +543,12 @@ client.usage.record_bulk(signals=[signal])
 Alternatively the same `costData` payload can be passed to OTLP signaling mechanism:
 
 ```python
-from paid import Paid
-from paid.tracing import paid_tracing
-
-# Initialize Paid SDK
-client = Paid(token="PAID_API_KEY")
+from paid.tracing import paid_tracing, signal
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")  # external_agent_id is required for sending signals
+@paid_tracing("your_external_customer_id", "your_external_agent_id")
 def do_work():
     # ...do some work...
-    client.signal(
+    signal(
         event_name="<your_signal_name>",
         data={
             "costData": {
@@ -652,16 +597,12 @@ client.usage.record_bulk(signals=[signal])
 Same but via OTEL signaling:
 
 ```python
-from paid import Paid
-from paid.tracing import paid_tracing
+from paid.tracing import paid_tracing, signal
 
-# Initialize Paid SDK
-client = Paid(token="PAID_API_KEY")
-
-@paid_tracing("your_external_customer_id", "your_external_agent_id")  # external_agent_id is required for sending signals
+@paid_tracing("your_external_customer_id", "your_external_agent_id")
 def do_work():
     # ...do some work...
-    client.signal(
+    signal(
         event_name="<your_signal_name>",
         data={
             "costData": {
@@ -725,15 +666,13 @@ await generate_image()
 
 ### Async Signaling
 
-The `signal()` method works seamlessly in async contexts:
+The `signal()` function works seamlessly in async contexts:
 
 ```python
-from paid import AsyncPaid
-from paid.tracing import paid_tracing
+from paid.tracing import paid_tracing, signal
 from paid.tracing.wrappers.openai import PaidAsyncOpenAI
 from openai import AsyncOpenAI
 
-client = AsyncPaid(token="PAID_API_KEY")
 openai_client = PaidAsyncOpenAI(AsyncOpenAI(api_key="<OPENAI_API_KEY>"))
 
 @paid_tracing("your_external_customer_id", "your_external_agent_id")
@@ -744,8 +683,8 @@ async def do_work():
         messages=[{"role": "user", "content": "Hello!"}]
     )
 
-    # Send signal (synchronous call within async function)
-    client.signal(
+    # Send signal (works in async context)
+    signal(
         event_name="<your_signal_name>",
         enable_cost_tracing=True  # Associate with traced costs
     )