dhisana 0.0.1.dev314__tar.gz → 0.0.1.dev315__tar.gz

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dhisana
-Version: 0.0.1.dev314
+Version: 0.0.1.dev315
 Summary: A Python SDK for Dhisana AI Platform
 Home-page: https://github.com/dhisana-ai/dhisana-python-sdk
 Author: Admin

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='dhisana',  
-    version='0.0.1-dev314',
+    version='0.0.1-dev315',
     description='A Python SDK for Dhisana AI Platform',
     author='Admin',
     author_email='contact@dhisana.ai',

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/src/dhisana/utils/apollo_tools.py

@@ -21,6 +21,53 @@ logger = logging.getLogger(__name__)
 APOLLO_CACHE_TTL = 14 * 24 * 60 * 60  # 14 days in seconds
 
 
+def _count_apollo_records(result: Any, keys: Tuple[str, ...]) -> int:
+    """Count records in Apollo response fields that may be lists or objects."""
+    if not isinstance(result, dict):
+        return 0
+
+    total = 0
+    for key in keys:
+        value = result.get(key)
+        if isinstance(value, list):
+            total += len(value)
+        elif value:
+            total += 1
+    return total
+
+
+def _emit_apollo_usage(
+    *,
+    tool_config: Optional[List[Dict]] = None,
+    endpoint: Optional[str] = None,
+    records_attempted: int = 0,
+    records_returned: int = 0,
+    records_enriched: int = 0,
+) -> None:
+    """Emit an Apollo provider-usage record (best-effort, never raises)."""
+    try:
+        from dhisana.utils.fetch_openai_config import (
+            credential_owner_from_tool_config,
+        )
+        from dhisana.utils.usage_hook import ProviderUsageRecord, emit_usage
+
+        emit_usage(
+            ProviderUsageRecord(
+                provider="apollo",
+                model_or_endpoint=endpoint,
+                credential_owner=credential_owner_from_tool_config(
+                    tool_config, "apollo"
+                ),
+                api_calls=1,
+                records_attempted=records_attempted,
+                records_returned=records_returned,
+                records_enriched=records_enriched,
+            )
+        )
+    except Exception:  # noqa: BLE001 - metering must never break a provider call
+        logger.debug("failed to emit Apollo usage", exc_info=True)
+
+
 def get_apollo_access_token(tool_config: Optional[List[Dict]] = None) -> Tuple[str, bool]:
     """
     Retrieves an Apollo access token from tool configuration or environment variables.
@@ -180,6 +227,7 @@ async def enrich_person_info_from_apollo(
                 logger.debug(f"Received response status: {response.status}")
                 if response.status == 200:
                     result = await response.json()
+                    records_returned = _count_apollo_records(result, ("person",))
                     # Cache on success if organization_id is available
                     if organization_id and cache_key_identifier:
                         cache_key = f"{organization_id}:{cache_key_identifier}"
@@ -188,6 +236,13 @@ async def enrich_person_info_from_apollo(
                         except Exception:
                             logger.warning("Failed to cache Apollo person data.")
                     logger.info("Successfully retrieved person info from Apollo.")
+                    _emit_apollo_usage(
+                        tool_config=tool_config,
+                        endpoint="people/match",
+                        records_attempted=1,
+                        records_returned=records_returned,
+                        records_enriched=records_returned,
+                    )
                     return result
                 elif response.status == 429:
                     msg = "Rate limit exceeded"
@@ -274,6 +329,13 @@ async def lookup_person_in_apollo_by_name(
                 if response.status == 200:
                     result = await response.json()
                     logger.info("Successfully looked up person by name on Apollo.")
+                    records_returned = _count_apollo_records(result, ("people", "contacts"))
+                    _emit_apollo_usage(
+                        tool_config=tool_config,
+                        endpoint="mixed_people/search",
+                        records_attempted=1,
+                        records_returned=records_returned,
+                    )
                     return result
                 elif response.status == 429:
                     msg = "Rate limit exceeded"
@@ -363,6 +425,7 @@ async def enrich_organization_info_from_apollo(
                 logger.debug(f"Received response status: {response.status}")
                 if response.status == 200:
                     result = await response.json()
+                    records_returned = _count_apollo_records(result, ("organization",))
                     # Cache on success if organization_id is available
                     if organization_id and organization_domain:
                         cache_key = f"{organization_id}:{organization_domain}"
@@ -371,6 +434,13 @@ async def enrich_organization_info_from_apollo(
                         except Exception:
                             logger.warning("Failed to cache Apollo org data.")
                     logger.info("Successfully retrieved organization info from Apollo.")
+                    _emit_apollo_usage(
+                        tool_config=tool_config,
+                        endpoint="organizations/enrich",
+                        records_attempted=1,
+                        records_returned=records_returned,
+                        records_enriched=records_returned,
+                    )
                     return result
                 elif response.status == 429:
                     msg = "Rate limit exceeded"
@@ -405,7 +475,13 @@ async def enrich_organization_info_from_apollo(
     giveup=lambda e: e.status != 429,
     factor=2,
 )
-async def fetch_apollo_data(session, url: str, headers: Dict[str, str], payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+async def fetch_apollo_data(
+    session,
+    url: str,
+    headers: Dict[str, str],
+    payload: Dict[str, Any],
+    tool_config: Optional[List[Dict]] = None,
+) -> Optional[Dict[str, Any]]:
     logger.info("Entering fetch_apollo_data")
     logger.debug("Making POST request to Apollo.")
     async with session.post(url, headers=headers, json=payload) as response:
@@ -413,6 +489,15 @@ async def fetch_apollo_data(session, url: str, headers: Dict[str, str], payload:
         if response.status == 200:
             result = await response.json()
             logger.info("Successfully fetched data from Apollo.")
+            records_returned = _count_apollo_records(
+                result,
+                ("people", "contacts", "organizations", "accounts"),
+            )
+            _emit_apollo_usage(
+                tool_config=tool_config,
+                endpoint=url,
+                records_returned=records_returned,
+            )
             return result
         elif response.status == 429:
             msg = "Rate limit exceeded"
@@ -453,7 +538,9 @@ async def search_people_with_apollo(
     logger.info(f"Sending payload to Apollo (single page): {json.dumps(dynamic_payload, indent=2)}")
 
     async with aiohttp.ClientSession() as session:
-        data = await fetch_apollo_data(session, url, headers, dynamic_payload)
+        data = await fetch_apollo_data(
+            session, url, headers, dynamic_payload, tool_config=tool_config
+        )
         if not data:
             logger.error("No data returned from Apollo.")
             return []
@@ -1006,7 +1093,9 @@ async def search_leads_with_apollo_page(
     url = "https://api.apollo.io/api/v1/mixed_people/search"
     
     async with aiohttp.ClientSession() as session:
-        apollo_response = await fetch_apollo_data(session, url, headers, page_payload)
+        apollo_response = await fetch_apollo_data(
+            session, url, headers, page_payload, tool_config=tool_config
+        )
         if not apollo_response:
             return {"current_page": page, "per_page": per_page, "total_entries": 0, "total_pages": 0, "has_next_page": False, "results": []}
 
@@ -1393,7 +1482,9 @@ async def search_companies_with_apollo(
     logger.info(f"Sending payload to Apollo organizations endpoint (single page): {json.dumps(dynamic_payload, indent=2)}")
 
     async with aiohttp.ClientSession() as session:
-        data = await fetch_apollo_data(session, url, headers, dynamic_payload)
+        data = await fetch_apollo_data(
+            session, url, headers, dynamic_payload, tool_config=tool_config
+        )
         if not data:
             logger.error("No data returned from Apollo organizations search.")
             return []
@@ -1852,7 +1943,9 @@ async def search_companies_with_apollo_page(
     url = "https://api.apollo.io/api/v1/organizations/search"
     
     async with aiohttp.ClientSession() as session:
-        apollo_response = await fetch_apollo_data(session, url, headers, cleaned_payload)
+        apollo_response = await fetch_apollo_data(
+            session, url, headers, cleaned_payload, tool_config=tool_config
+        )
         if not apollo_response:
             return {
                 "current_page": page, 

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/src/dhisana/utils/fetch_openai_config.py

@@ -131,3 +131,77 @@ def get_openai_access_token(tool_config: Optional[List[Dict]] = None) -> str:
     """Return just the API key (legacy helper)."""
     _, key, _ = _discover_credentials(tool_config)
     return key
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 4. Credential-owner derivation (for usage metering)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def openai_provider_from_tool_config(tool_config: Optional[List[Dict]]) -> str:
+    """Return the provider label selected by the OpenAI credential config.
+
+    Values are ``"openai"`` or ``"azure_openai"``. This mirrors
+    :func:`_discover_credentials` without requiring valid secrets during
+    best-effort metering.
+    """
+    if _extract_config(tool_config, "openai"):
+        return "openai"
+    if _extract_config(tool_config, "azure_openai"):
+        return "azure_openai"
+
+    # Metadata-only configs appear in unit tests and in some host payloads.
+    if tool_config:
+        if any(block.get("name") == "openai" for block in tool_config):
+            return "openai"
+        if any(block.get("name") == "azure_openai" for block in tool_config):
+            return "azure_openai"
+
+    return "openai"
+
+
+def credential_owner_from_tool_config(
+    tool_config: Optional[List[Dict]],
+    provider: str,
+) -> str:
+    """Derive the credential owner for ``provider`` from ``tool_config``.
+
+    Returns one of ``"dhisana_default"``, ``"customer_owned"``,
+    ``"partner_owned"``, or ``"unknown"`` (lowercase; the host normalizes to its
+    own enum). The value is used only for usage metering and never affects which
+    credentials are used for a provider call.
+
+    Resolution:
+        1. An explicit ``credential_owner`` (or legacy ``owner``) field on the
+           provider's config block wins.
+        2. Otherwise a block flagged ``is_default`` is treated as a
+           Dhisana-managed default key (``dhisana_default``).
+        3. A present-but-not-default block is treated as customer-supplied
+           (``customer_owned``).
+        4. No matching block → ``unknown``.
+
+    For the OpenAI provider, both the ``openai`` and ``azure_openai`` blocks are
+    considered.
+    """
+    valid = {"dhisana_default", "customer_owned", "partner_owned", "unknown"}
+    candidate_names = [provider]
+    if provider == "openai":
+        candidate_names = ["openai", "azure_openai"]
+
+    if not tool_config:
+        return "unknown"
+
+    for name in candidate_names:
+        block = next((b for b in tool_config if b.get("name") == name), None)
+        if not block:
+            continue
+
+        explicit = block.get("credential_owner") or block.get("owner")
+        if explicit:
+            normalized = str(explicit).strip().lower()
+            return normalized if normalized in valid else "unknown"
+
+        if block.get("is_default"):
+            return "dhisana_default"
+        return "customer_owned"
+
+    return "unknown"

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/src/dhisana/utils/generate_structured_output_internal.py

@@ -17,7 +17,10 @@ from dhisana.utils import cache_output_tools
 from dhisana.utils.fetch_openai_config import (
     _extract_config,
     create_async_openai_client,
+    credential_owner_from_tool_config,
+    openai_provider_from_tool_config,
 )
+from dhisana.utils.usage_hook import ProviderUsageRecord, emit_usage
 
 # Import search and scrape utilities for web search tools
 try:
@@ -150,6 +153,84 @@ def is_context_length_error(error: Exception) -> bool:
     return "context_length_exceeded" in error_str or "context window" in error_str
 
 
+def _usage_attr(usage: Any, name: str, default: int = 0) -> int:
+    """Read an integer field from an OpenAI usage object (attr or dict)."""
+    if usage is None:
+        return default
+    value = getattr(usage, name, None)
+    if value is None and isinstance(usage, dict):
+        value = usage.get(name)
+    try:
+        return int(value) if value is not None else default
+    except (TypeError, ValueError):
+        return default
+
+
+def _cached_input_tokens(usage: Any) -> int:
+    """Read cached prompt tokens from a Responses API usage object."""
+    if usage is None:
+        return 0
+    details = getattr(usage, "input_tokens_details", None)
+    if details is None and isinstance(usage, dict):
+        details = usage.get("input_tokens_details")
+    if details is None:
+        return 0
+    return _usage_attr(details, "cached_tokens", 0)
+
+
+def _count_web_search_calls(completion: Any) -> int:
+    """Count web-search tool invocations in a Responses API completion."""
+    count = 0
+    output = getattr(completion, "output", None) or []
+    for item in output:
+        item_type = getattr(item, "type", None)
+        if item_type is None and isinstance(item, dict):
+            item_type = item.get("type")
+        if item_type and "web_search" in str(item_type):
+            count += 1
+            continue
+        if item_type == "function_call":
+            name = getattr(item, "name", None)
+            if name is None and isinstance(item, dict):
+                name = item.get("name")
+            if name in {"search_google", "fetch_url_content"}:
+                count += 1
+    return count
+
+
+def _emit_openai_usage(
+    completion: Any,
+    *,
+    model: Optional[str],
+    tool_config: Optional[List[Dict]],
+    web_search_calls: int = 0,
+) -> None:
+    """Build a :class:`ProviderUsageRecord` from ``completion`` and emit it.
+
+    Best-effort: this never raises into the calling provider path. The hook's
+    :func:`emit_usage` is a no-op when no sink is registered.
+    """
+    try:
+        usage = getattr(completion, "usage", None)
+        provider = openai_provider_from_tool_config(tool_config)
+        record = ProviderUsageRecord(
+            provider=provider,
+            model_or_endpoint=model,
+            credential_owner=credential_owner_from_tool_config(tool_config, provider),
+            input_tokens=_usage_attr(usage, "input_tokens", 0),
+            cached_input_tokens=_cached_input_tokens(usage),
+            output_tokens=_usage_attr(usage, "output_tokens", 0),
+            web_search_calls=web_search_calls,
+            grounded_search_queries=web_search_calls,
+            api_calls=1,
+            provider_request_id=getattr(completion, "id", None),
+            provider_status=getattr(completion, "status", None),
+        )
+        emit_usage(record)
+    except Exception:  # noqa: BLE001 - metering must never break a provider call
+        logging.debug("failed to emit OpenAI usage", exc_info=True)
+
+
 # ──────────────────────────────────────────────────────────────────────────────
 # 2.  Vector-store utilities (unchanged logic, new client factory)
 # ──────────────────────────────────────────────────────────────────────────────
@@ -292,6 +373,9 @@ async def get_structured_output_internal(
                 logging.error(f"OpenAI API error: {e}")
                 return f"OpenAI API error: {str(e)}", "API_ERROR"
 
+        # ─── usage metering (best-effort) ───────────────────────────────────
+        _emit_openai_usage(completion, model=model, tool_config=tool_config)
+
         # ─── handle model output ────────────────────────────────────────────
         return _parse_completion_response(completion, response_format, cache_key)
 
@@ -365,6 +449,12 @@ async def _get_structured_output_with_web_search(
                 logging.debug(f"[WebSearch] Sending request attempt {attempt + 1}")
                 completion = await client_async.responses.create(**request)
                 logging.info(f"[WebSearch] Response received, output items: {len(completion.output) if completion and completion.output else 0}")
+                _emit_openai_usage(
+                    completion,
+                    model=model,
+                    tool_config=tool_config,
+                    web_search_calls=_count_web_search_calls(completion),
+                )
                 break
             except (RateLimitError, OpenAIError) as e:
                 is_rl = (
@@ -437,7 +527,7 @@ async def _get_structured_output_with_web_search(
             logging.info(f"[WebSearch] Executed tool {func_name}, result length: {len(tool_result)}")
     
     logging.info(f"[WebSearch] Tool loop completed after {tool_iteration} iteration(s)")
-    
+
     # Parse and return the final response
     result, status = _parse_completion_response(completion, response_format, cache_key)
     logging.info(f"[WebSearch] Parse result status: {status}")
@@ -606,6 +696,14 @@ async def get_structured_output_with_mcp(
     if not completion:
         return "OpenAI request retry loop failed", "API_ERROR"
 
+    # ─── usage metering (best-effort) ─────────────────────────────────────────
+    _emit_openai_usage(
+        completion,
+        model=model,
+        tool_config=tool_config,
+        web_search_calls=_count_web_search_calls(completion),
+    )
+
     # ─── Parse the model’s structured output ──────────────────────────────────
     if not (completion and completion.output):
         return "No output returned", "FAIL"
@@ -724,6 +822,9 @@ async def get_structured_output_with_assistant_and_vector_store(
             store=False,
         )
 
+        # ─── usage metering (best-effort) ─────────────────────────────────────
+        _emit_openai_usage(completion, model=model, tool_config=tool_config)
+
         if completion and completion.output and len(completion.output) > 0:
             raw_text = None
             for out in completion.output:

dhisana-0.0.1.dev315/src/dhisana/utils/usage_hook.py

@@ -0,0 +1,103 @@
+"""
+Provider-usage hook for the Dhisana SDK.
+
+This module provides a lightweight, dependency-free mechanism for the SDK to
+emit provider-usage telemetry (token counts, API-call counts, record counts) to
+an optional sink registered by the host application (for example, the agentops
+backend's metering pipeline).
+
+Design constraints:
+    * This module MUST NOT import the backend, a database driver, or the
+      metering ledger. It depends only on the Python standard library.
+    * :func:`emit_usage` is best-effort: it swallows *all* exceptions so that
+      metering can never break a provider call.
+    * Backward compatible: with no sink registered, the hook is a no-op.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProviderUsageRecord:
+    """A single provider-usage observation emitted by the SDK.
+
+    Field names mirror the host metering ledger's ``ProviderUsageInput`` so the
+    host can duck-type this record without importing the SDK. The host normalizes
+    ``credential_owner`` and fills any missing field with a safe zero default, so
+    new fields can be added here without breaking older hosts.
+    """
+
+    provider: str
+    model_or_endpoint: Optional[str] = None
+    credential_owner: str = "unknown"
+    input_tokens: int = 0
+    cached_input_tokens: int = 0
+    output_tokens: int = 0
+    embedding_tokens: int = 0
+    grounded_search_queries: int = 0
+    web_search_calls: int = 0
+    api_calls: int = 1
+    provider_credit_units: Optional[float] = None
+    records_attempted: int = 0
+    records_returned: int = 0
+    records_enriched: int = 0
+    provider_request_id: Optional[str] = None
+    provider_status: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+UsageSink = Callable[[ProviderUsageRecord], None]
+
+_usage_sink: ContextVar[Optional[UsageSink]] = ContextVar(
+    "dhisana_usage_sink", default=None
+)
+
+
+def set_usage_sink(sink: Optional[UsageSink]) -> Token:
+    """Register ``sink`` for the current context and return a reset token.
+
+    The token must be passed to :func:`reset_usage_sink` to restore the previous
+    sink (typically in a ``finally`` block around an operation scope).
+    """
+    return _usage_sink.set(sink)
+
+
+def reset_usage_sink(token: Token) -> None:
+    """Restore the previous sink using the token from :func:`set_usage_sink`.
+
+    A token created in a different context is ignored rather than raised so that
+    cleanup is always safe.
+    """
+    try:
+        _usage_sink.reset(token)
+    except Exception:  # noqa: BLE001 - cleanup must always be safe
+        # Token belongs to a different context or was already consumed.
+        pass
+
+
+def current_usage_sink() -> Optional[UsageSink]:
+    """Return the sink registered for the current context, or ``None``."""
+    return _usage_sink.get()
+
+
+def emit_usage(record: ProviderUsageRecord) -> None:
+    """Emit ``record`` to the registered sink, if any.
+
+    Best-effort by contract: any exception (a missing sink, a failing sink, or a
+    malformed record) is swallowed so that metering can never break the provider
+    call that produced the usage.
+    """
+    try:
+        sink = _usage_sink.get()
+        if sink is None:
+            return
+        sink(record)
+    except Exception:  # noqa: BLE001 - metering must never break the caller
+        logger.debug("emit_usage sink raised; ignoring", exc_info=True)

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/src/dhisana.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dhisana
-Version: 0.0.1.dev314
+Version: 0.0.1.dev315
 Summary: A Python SDK for Dhisana AI Platform
 Home-page: https://github.com/dhisana-ai/dhisana-python-sdk
 Author: Admin

{dhisana-0.0.1.dev314 → dhisana-0.0.1.dev315}/src/dhisana.egg-info/SOURCES.txt

@@ -93,6 +93,7 @@ src/dhisana/utils/serperdev_search.py
 src/dhisana/utils/smtp_email_tools.py
 src/dhisana/utils/test_connect.py
 src/dhisana/utils/trasform_json.py
+src/dhisana/utils/usage_hook.py
 src/dhisana/utils/web_download_parse_tools.py
 src/dhisana/utils/workflow_code_model.py
 src/dhisana/utils/zoominfo_tools.py
@@ -109,6 +110,7 @@ tests/test_agent_tools.py
 tests/test_apollo_company_search.py
 tests/test_apollo_json_error_handling.py
 tests/test_apollo_lead_search.py
+tests/test_apollo_usage_emit.py
 tests/test_connectivity.py
 tests/test_email_body_utils.py
 tests/test_generate_email.py
@@ -119,9 +121,11 @@ tests/test_linkedin_serper.py
 tests/test_mailreach.py
 tests/test_mcp_connectivity.py
 tests/test_normalize_graph_datetime.py
+tests/test_openai_usage_emit.py
 tests/test_proxycurl_get_company_search_id.py
 tests/test_proxycurl_job_count.py
 tests/test_reply_html_format.py
 tests/test_reply_thread_fallback.py
 tests/test_send_email_recipients.py
-tests/test_structured_output_with_mcp.py
+tests/test_structured_output_with_mcp.py
+tests/test_usage_hook.py