paid-python 0.4.1a0__py3-none-any.whl → 0.5.0__py3-none-any.whl

paid/usage/raw_client.py

@@ -6,9 +6,16 @@ from json.decoder import JSONDecodeError
 from ..core.api_error import ApiError
 from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
 from ..core.http_response import AsyncHttpResponse, HttpResponse
+from ..core.pydantic_utilities import parse_obj_as
 from ..core.request_options import RequestOptions
 from ..core.serialization import convert_and_respect_annotation_metadata
+from ..errors.bad_request_error import BadRequestError
+from ..errors.internal_server_error import InternalServerError
+from ..errors.not_found_error import NotFoundError
+from ..types.error import Error
 from ..types.signal import Signal
+from ..types.signal_v_2 import SignalV2
+from .types.usage_check_usage_response import UsageCheckUsageResponse
 
 # this is used as the default value for optional parameters
 OMIT = typing.cast(typing.Any, ...)
@@ -25,6 +32,8 @@ class RawUsageClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[None]:
         """
+        DEPRECATED: Use POST /usage/v2/signals/bulk instead for cleaner field names.
+
         Parameters
         ----------
         signals : typing.Optional[typing.Sequence[Signal]]
@@ -58,6 +67,142 @@ class RawUsageClient:
             raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
         raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
 
+    def usage_record_bulk_v_2(
+        self,
+        *,
+        signals: typing.Optional[typing.Sequence[SignalV2]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> HttpResponse[None]:
+        """
+        Parameters
+        ----------
+        signals : typing.Optional[typing.Sequence[SignalV2]]
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[None]
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "usage/v2/signals/bulk",
+            method="POST",
+            json={
+                "signals": convert_and_respect_annotation_metadata(
+                    object_=signals, annotation=typing.Sequence[SignalV2], direction="write"
+                ),
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return HttpResponse(response=_response, data=None)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def check_usage(
+        self,
+        *,
+        external_customer_id: str,
+        external_product_id: str,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> HttpResponse[UsageCheckUsageResponse]:
+        """
+        Parameters
+        ----------
+        external_customer_id : str
+            External customer ID
+
+        external_product_id : str
+            External product ID (the external ID of the product/agent)
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[UsageCheckUsageResponse]
+            Usage check response
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "usage/check-usage",
+            method="POST",
+            json={
+                "externalCustomerId": external_customer_id,
+                "externalProductId": external_product_id,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    UsageCheckUsageResponse,
+                    parse_obj_as(
+                        type_=UsageCheckUsageResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
 
 class AsyncRawUsageClient:
     def __init__(self, *, client_wrapper: AsyncClientWrapper):
@@ -70,6 +215,8 @@ class AsyncRawUsageClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[None]:
         """
+        DEPRECATED: Use POST /usage/v2/signals/bulk instead for cleaner field names.
+
         Parameters
         ----------
         signals : typing.Optional[typing.Sequence[Signal]]
@@ -102,3 +249,139 @@ class AsyncRawUsageClient:
         except JSONDecodeError:
             raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
         raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def usage_record_bulk_v_2(
+        self,
+        *,
+        signals: typing.Optional[typing.Sequence[SignalV2]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncHttpResponse[None]:
+        """
+        Parameters
+        ----------
+        signals : typing.Optional[typing.Sequence[SignalV2]]
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[None]
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "usage/v2/signals/bulk",
+            method="POST",
+            json={
+                "signals": convert_and_respect_annotation_metadata(
+                    object_=signals, annotation=typing.Sequence[SignalV2], direction="write"
+                ),
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return AsyncHttpResponse(response=_response, data=None)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def check_usage(
+        self,
+        *,
+        external_customer_id: str,
+        external_product_id: str,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncHttpResponse[UsageCheckUsageResponse]:
+        """
+        Parameters
+        ----------
+        external_customer_id : str
+            External customer ID
+
+        external_product_id : str
+            External product ID (the external ID of the product/agent)
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[UsageCheckUsageResponse]
+            Usage check response
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "usage/check-usage",
+            method="POST",
+            json={
+                "externalCustomerId": external_customer_id,
+                "externalProductId": external_product_id,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    UsageCheckUsageResponse,
+                    parse_obj_as(
+                        type_=UsageCheckUsageResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        Error,
+                        parse_obj_as(
+                            type_=Error,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

paid/usage/types/__init__.py

@@ -0,0 +1,7 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+from .usage_check_usage_response import UsageCheckUsageResponse
+
+__all__ = ["UsageCheckUsageResponse"]

paid/usage/types/usage_check_usage_response.py

@@ -0,0 +1,53 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+import typing_extensions
+from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from ...core.serialization import FieldMetadata
+
+
+class UsageCheckUsageResponse(UniversalBaseModel):
+    allowed: typing.Optional[bool] = pydantic.Field(default=None)
+    """
+    Whether usage is allowed
+    """
+
+    message: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Human-readable message about the usage check result
+    """
+
+    event_name: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="eventName")] = pydantic.Field(
+        default=None
+    )
+    """
+    Event name (only present when usage is not allowed)
+    """
+
+    available: typing.Optional[float] = pydantic.Field(default=None)
+    """
+    Available credits (only present for PrepaidCredits when insufficient)
+    """
+
+    events_quantity: typing_extensions.Annotated[typing.Optional[float], FieldMetadata(alias="eventsQuantity")] = (
+        pydantic.Field(default=None)
+    )
+    """
+    Current events quantity (only present when usage exceeds limit)
+    """
+
+    limit: typing.Optional[float] = pydantic.Field(default=None)
+    """
+    Usage limit (only present when usage exceeds limit)
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

{paid_python-0.4.1a0.dist-info → paid_python-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: paid-python
-Version: 0.4.1a0
+Version: 0.5.0
 Summary: 
 Requires-Python: >=3.9,<3.14
 Classifier: Intended Audience :: Developers
@@ -183,7 +183,7 @@ The easiest way to add cost tracking is using the `@paid_tracing` decorator or c
 ```python
 from paid.tracing import paid_tracing
 
-@paid_tracing("<external_customer_id>", external_agent_id="<optional_external_agent_id>")
+@paid_tracing("<external_customer_id>", external_product_id="<optional_external_product_id>")
 def some_agent_workflow():  # your function
     # 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
@@ -197,11 +197,11 @@ You can also use `paid_tracing` as a context manager with `with` statements:
 from paid.tracing import paid_tracing
 
 # Synchronous
-with paid_tracing("customer_123", external_agent_id="agent_456"):
+with paid_tracing("customer_123", external_product_id="product_456"):
     result = workflow()
 
 # Asynchronous
-async with paid_tracing("customer_123", external_agent_id="agent_456"):
+async with paid_tracing("customer_123", external_product_id="product_456"):
     result = await workflow()
 ```
 
@@ -210,7 +210,7 @@ Both approaches:
 - Initialize tracing using your API key you provided to the Paid client, falls back to `PAID_API_KEY` environment variable.
 - Handle both sync and async functions/code blocks
 - Gracefully fall back to normal execution if tracing fails
-- Support the same parameters: `external_customer_id`, `external_agent_id`, `tracing_token`, `store_prompt`, `metadata`
+- Support the same parameters: `external_customer_id`, `external_product_id`, `tracing_token`, `store_prompt`, `metadata`
 
 * Note - if it happens that you're calling `paid_tracing` from non-main thread, then it's advised to initialize from main thread:
 ```python
@@ -249,7 +249,7 @@ openAIClient = PaidOpenAI(OpenAI(
     api_key="<OPENAI_API_KEY>",
 ))
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 def image_generate():
     response = openAIClient.images.generate(
         model="dall-e-3",
@@ -281,7 +281,7 @@ You can attach custom metadata to your traces by passing a `metadata` dictionary
 
     @paid_tracing(
         "customer_123",
-        "agent_123",
+        external_product_id="product_123",
         metadata={
             "campaign_id": "campaign_456",
             "environment": "production",
@@ -325,7 +325,7 @@ You can attach custom metadata to your traces by passing a `metadata` dictionary
     # Pass metadata to context manager
     with paid_tracing(
         "customer_123",
-        external_agent_id="agent_123",
+        external_product_id="product_123",
         metadata={
             "campaign_id": "campaign_456",
             "environment": "production",
@@ -380,7 +380,7 @@ paid_autoinstrument()  # instruments all available: anthropic, gemini, openai, o
 # Now all OpenAI calls will be automatically traced
 openai_client = OpenAI(api_key="<OPENAI_API_KEY>")
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 def chat_with_gpt():
     response = openai_client.chat.completions.create(
         model="gpt-4",
@@ -433,7 +433,7 @@ Here's an example of how to use it:
 ```python
 from paid.tracing import paid_tracing, signal
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 def do_work():
     # ...do some work...
     signal(
@@ -457,7 +457,7 @@ def do_work():
     )
 
 # Use context manager instead
-with paid_tracing("your_external_customer_id", "your_external_agent_id"):
+with paid_tracing("your_external_customer_id", external_product_id="your_external_product_id"):
     do_work()
 ```
 
@@ -472,7 +472,7 @@ This will look something like this:
 ```python
 from paid.tracing import paid_tracing, signal
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 def do_work():
     # ... your workflow logic
     # ... your AI calls made through Paid wrappers or hooks
@@ -516,7 +516,7 @@ 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", tracing_token=token, external_agent_id="agent_123")
+@paid_tracing("customer_123", tracing_token=token, external_product_id="product_123")
 def process_part_1():
     # AI calls here will be traced
     response = openai_client.chat.completions.create(
@@ -531,7 +531,7 @@ process_part_1()
 # Process 2 (different machine/process): Retrieve and use token
 token = load_from_storage("workflow_123")
 
-@paid_tracing("customer_123", tracing_token=token, external_agent_id="agent_123")
+@paid_tracing("customer_123", tracing_token=token, external_product_id="product_123")
 def process_part_2():
     # AI calls here will be linked to the same trace
     response = openai_client.chat.completions.create(
@@ -561,7 +561,7 @@ openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
 token = generate_tracing_token()
 save_to_storage("workflow_123", token)
 
-with paid_tracing("customer_123", external_agent_id="agent_123", tracing_token=token):
+with paid_tracing("customer_123", external_product_id="product_123", tracing_token=token):
     response = openai_client.chat.completions.create(
         model="gpt-4",
         messages=[{"role": "user", "content": "Analyze data"}]
@@ -571,7 +571,7 @@ with paid_tracing("customer_123", external_agent_id="agent_123", tracing_token=t
 # Process 2: Retrieve and use the same token
 token = load_from_storage("workflow_123")
 
-with paid_tracing("customer_123", external_agent_id="agent_123", tracing_token=token):
+with paid_tracing("customer_123", external_product_id="product_123", tracing_token=token):
     response = openai_client.chat.completions.create(
         model="gpt-4",
         messages=[{"role": "user", "content": "Generate response"}]
@@ -613,7 +613,7 @@ Alternatively the same `costData` payload can be passed to OTLP signaling mechan
 ```python
 from paid.tracing import paid_tracing, signal
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 def do_work():
     # ...do some work...
     signal(
@@ -667,7 +667,7 @@ Same but via OTEL signaling:
 ```python
 from paid.tracing import paid_tracing, signal
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 def do_work():
     # ...do some work...
     signal(
@@ -719,7 +719,7 @@ initialize_tracing()
 # Wrap the async OpenAI client
 openai_client = PaidAsyncOpenAI(AsyncOpenAI(api_key="<OPENAI_API_KEY>"))
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 async def generate_image():
     response = await openai_client.images.generate(
         model="dall-e-3",
@@ -747,7 +747,7 @@ initialize_tracing()
 
 openai_client = PaidAsyncOpenAI(AsyncOpenAI(api_key="<OPENAI_API_KEY>"))
 
-@paid_tracing("your_external_customer_id", "your_external_agent_id")
+@paid_tracing("your_external_customer_id", external_product_id="your_external_product_id")
 async def do_work():
     # Perform async AI operations
     response = await openai_client.chat.completions.create(