dhisana 0.0.1.dev44__tar.gz → 0.0.1.dev45__tar.gz

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/PKG-INFO

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

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/setup.py

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

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/src/dhisana/schemas/sales.py

@@ -280,14 +280,14 @@ class ExternalDataSources(BaseModel):
 class ContentGenerationContext(BaseModel):
     """
     Consolidates all relevant data needed for generating content:
-      1) campaing_context: Details about the current campaign or marketing approach.
+      1) campaign_context: Details about the current campaign or marketing approach.
       2) lead_info: The lead's basic information.
       3) sender_info: Who is sending the message.
       4) external_known_data: Any references to external data sources (e.g., vector store IDs).
       5) current_conversation_context: Current or ongoing conversation threads (email or LinkedIn).
       6) target_channel_type: Which channel we are generating content for (email, LinkedIn, etc.).
     """
-    campaing_context: Optional[CampaingContext] = None
+    campaign_context: Optional[CampaingContext] = None
     lead_info: Optional[Lead] = None
     sender_info: Optional[SenderInfo] = None
     external_known_data: Optional[ExternalDataSources] = None

dhisana-0.0.1.dev45/src/dhisana/utils/check_email_validity_tools.py

@@ -0,0 +1,587 @@
+import os
+import json
+import logging
+from typing import Dict, List, Optional, Any
+import aiohttp
+
+logger = logging.getLogger(__name__)
+from dhisana.utils.assistant_tool_tag import assistant_tool
+from dhisana.utils.cache_output_tools import cache_output, retrieve_output
+
+
+# --------------------------------------------------------------------------------
+# 1. Access Token Helpers
+# --------------------------------------------------------------------------------
+
+def get_zero_bounce_access_token(tool_config: Optional[List[Dict]] = None) -> str:
+    """
+    Retrieves the ZeroBounce access token from the provided tool configuration or environment.
+    """
+    if tool_config:
+        zerobounce_config = next(
+            (item for item in tool_config if item.get("name") == "zerobounce"), None
+        )
+        if zerobounce_config:
+            config_map = {
+                c["name"]: c["value"]
+                for c in zerobounce_config.get("configuration", [])
+                if c
+            }
+            ZERO_BOUNCE_API_KEY = config_map.get("apiKey")
+        else:
+            logger.warning("ZeroBounce config not provided or missing 'apiKey'.")
+            ZERO_BOUNCE_API_KEY = None
+    else:
+        logger.warning("ZeroBounce config not provided or missing 'apiKey'.")
+        ZERO_BOUNCE_API_KEY = None
+
+    ZERO_BOUNCE_API_KEY = ZERO_BOUNCE_API_KEY or os.getenv("ZERO_BOUNCE_API_KEY")
+    if not ZERO_BOUNCE_API_KEY:
+        logger.warning("ZERO_BOUNCE_API_KEY not found in config or env.")
+        return ""  # Return empty so we don't break
+
+    return ZERO_BOUNCE_API_KEY
+
+
+def get_hunter_access_token(tool_config: Optional[List[Dict]] = None) -> str:
+    """
+    Retrieves the Hunter.io access token from the provided tool configuration or environment.
+    """
+    if tool_config:
+        hunter_config = next(
+            (item for item in tool_config if item.get("name") == "hunter"), None
+        )
+        if hunter_config:
+            config_map = {
+                c["name"]: c["value"]
+                for c in hunter_config.get("configuration", [])
+                if c
+            }
+            HUNTER_API_KEY = config_map.get("apiKey")
+        else:
+            logger.warning("Hunter config not provided or missing 'apiKey'.")
+            HUNTER_API_KEY = None
+    else:
+        logger.warning("Hunter config not provided or missing 'apiKey'.")
+        HUNTER_API_KEY = None
+
+    HUNTER_API_KEY = HUNTER_API_KEY or os.getenv("HUNTER_API_KEY")
+    if not HUNTER_API_KEY:
+        logger.warning("HUNTER_API_KEY not found in config or env.")
+        return ""  # Return empty so we don't break
+
+    return HUNTER_API_KEY
+
+
+# --------------------------------------------------------------------------------
+# 2. Provider-Specific Validation Functions
+# --------------------------------------------------------------------------------
+
+def _map_zerobounce_status_to_confidence(status: str) -> str:
+    """
+    Map ZeroBounce's status string to "high", "medium", or "low" confidence.
+    """
+    status = status.lower()
+    if status == "valid":
+        return "high"
+    elif status in ["catch-all", "unknown"]:
+        return "medium"
+    elif status in ["spamtrap", "invalid"]:
+        return "low"
+    return "low"
+
+
+@assistant_tool
+async def check_email_validity_with_zero_bounce(
+    email_id: str,
+    tool_config: Optional[List[Dict]] = None
+) -> Dict[str, Any]:
+    """
+    Validate a single email address using the ZeroBounce API, with caching.
+    Returns: {
+      "email": str,
+      "confidence": "high"|"medium"|"low",
+      "is_valid": bool
+    }
+    """
+    logger.info("Entering check_email_validity_with_zero_bounce for email_id: %s", email_id)
+    import re
+    if not email_id or not re.fullmatch(r"[^@]+@[^@]+\.[^@]+", email_id):
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    cache_key = f"{email_id}"
+    cached_response = retrieve_output("zerobounce_validate", cache_key)
+    if cached_response is not None:
+        logger.info("Cache hit for ZeroBounce validate.")
+        if not cached_response:
+            return {
+                "email": email_id,
+                "confidence": "low",
+                "is_valid": False
+            }
+        return json.loads(cached_response[0])
+
+    # Get API key
+    ZERO_BOUNCE_API_KEY = get_zero_bounce_access_token(tool_config)
+    if not ZERO_BOUNCE_API_KEY:
+        logger.warning("No ZeroBounce API key available. Returning low confidence.")
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    url = (
+        "https://api.zerobounce.net/v2/validate"
+        f"?api_key={ZERO_BOUNCE_API_KEY}&email={email_id}"
+    )
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                if response.status != 200:
+                    content = await safe_read_json_or_text(response)
+                    logger.warning(
+                        f"[ZeroBounce] Non-200 status: {response.status} => {content}"
+                    )
+                    # Return fallback instead of raising
+                    final_response = {
+                        "email": email_id,
+                        "confidence": "low",
+                        "is_valid": False
+                    }
+                    cache_output("zerobounce_validate", cache_key, [json.dumps(final_response)])
+                    return final_response
+
+                result = await response.json()
+    except Exception as ex:
+        logger.warning(f"[ZeroBounce] Exception occurred => {ex}")
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    zb_status = result.get("status", "").lower()  # e.g. "valid", "invalid"
+    confidence = _map_zerobounce_status_to_confidence(zb_status)
+    is_valid = (confidence == "high")
+
+    final_response = {
+        "email": email_id,
+        "confidence": confidence,
+        "is_valid": is_valid
+    }
+    cache_output("zerobounce_validate", cache_key, [json.dumps(final_response)])
+    logger.info("Exiting check_email_validity_with_zero_bounce.")
+    return final_response
+
+
+def _map_hunter_status_to_confidence(hunter_result: str) -> str:
+    """
+    Map Hunter's email verifier result to "high", "medium", or "low" confidence.
+    Possible results: deliverable, undeliverable, risky, unknown, accept_all.
+    """
+    val = hunter_result.lower()
+    if val == "deliverable":
+        return "high"
+    elif val in ["risky", "unknown", "accept_all"]:
+        return "medium"
+    elif val == "undeliverable":
+        return "low"
+    return "low"
+
+
+@assistant_tool
+async def check_email_validity_with_hunter(
+    email_id: str,
+    tool_config: Optional[List[Dict]] = None
+) -> Dict[str, Any]:
+    """
+    Validate a single email address using Hunter.io's email verification API.
+    Returns: {
+      "email": str,
+      "confidence": "high"|"medium"|"low",
+      "is_valid": bool
+    }
+    """
+    logger.info("Entering check_email_validity_with_hunter for email_id: %s", email_id)
+    import re
+    if not email_id or not re.fullmatch(r"[^@]+@[^@]+\.[^@]+", email_id):
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    HUNTER_API_KEY = get_hunter_access_token(tool_config)
+    if not HUNTER_API_KEY:
+        logger.warning("No Hunter API key available. Returning low confidence.")
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    url = (
+        "https://api.hunter.io/v2/email-verifier"
+        f"?email={email_id}&api_key={HUNTER_API_KEY}"
+    )
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                if response.status != 200:
+                    content = await safe_read_json_or_text(response)
+                    logger.warning(f"[Hunter] Non-200 status: {response.status} => {content}")
+                    return {
+                        "email": email_id,
+                        "confidence": "low",
+                        "is_valid": False
+                    }
+
+                result = await response.json()
+    except Exception as ex:
+        logger.warning(f"[Hunter] Exception occurred => {ex}")
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    data = result.get("data", {})
+    verifier_result = data.get("result", "")  # "deliverable", "undeliverable", etc.
+    confidence = _map_hunter_status_to_confidence(verifier_result)
+    is_valid = (confidence == "high")
+
+    final_response = {
+        "email": email_id,
+        "confidence": confidence,
+        "is_valid": is_valid
+    }
+    logger.info("Exiting check_email_validity_with_hunter.")
+    return final_response
+
+
+# --------------------------------------------------------------------------------
+# 3. Provider-Specific Guessing Functions
+# --------------------------------------------------------------------------------
+
+@assistant_tool
+async def guess_email_with_zero_bounce(
+    first_name: str,
+    last_name: str,
+    domain: str,
+    middle_name: Optional[str] = None,
+    tool_config: Optional[List[Dict]] = None
+) -> Dict[str, Any]:
+    """
+    Attempt to guess the email using ZeroBounce's guessFormat endpoint, with caching.
+    We assume the API returns an "email" and an "email_confidence" field.
+    """
+    logger.info("Entering guess_email_with_zero_bounce.")
+    if not first_name or not last_name or not domain:
+        logger.error("Required parameters first_name, last_name, and domain must be provided.")
+        return {"email": "", "email_confidence": "low"}
+
+    cache_key = f"{first_name}_{last_name}_{domain}_{middle_name or ''}"
+    cached_response = retrieve_output("zerobounce_guess", cache_key)
+    if cached_response is not None:
+        logger.info("Cache hit for ZeroBounce guess.")
+        return json.loads(cached_response[0]) if cached_response else {"email": "", "email_confidence": "low"}
+
+    ZERO_BOUNCE_API_KEY = get_zero_bounce_access_token(tool_config)
+    if not ZERO_BOUNCE_API_KEY:
+        logger.warning("No ZeroBounce API key available. Returning low confidence guess.")
+        return {"email": "", "email_confidence": "low"}
+
+    base_url = "https://api.zerobounce.net/v2/guessformat"
+    query_params = (
+        f"?api_key={ZERO_BOUNCE_API_KEY}"
+        f"&domain={domain}"
+        f"&first_name={first_name}"
+        f"&middle_name={middle_name or ''}"
+        f"&last_name={last_name}"
+    )
+    url = base_url + query_params
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                if response.status != 200:
+                    content = await safe_read_json_or_text(response)
+                    logger.warning(f"[ZeroBounce] guessFormat error: {response.status} => {content}")
+                    return {"email": "", "email_confidence": "low"}
+                result = await response.json()
+    except Exception as ex:
+        logger.warning(f"[ZeroBounce] Exception => {ex}")
+        return {"email": "", "email_confidence": "low"}
+
+    # If the API doesn't provide "email_confidence", you can supply a fallback:
+    if "email_confidence" not in result:
+        result["email_confidence"] = "medium" if result.get("email") else "low"
+
+    cache_output("zerobounce_guess", cache_key, [json.dumps(result)])
+    logger.info("Exiting guess_email_with_zero_bounce.")
+    return result
+
+
+@assistant_tool
+async def guess_email_with_hunter(
+    first_name: str,
+    last_name: str,
+    domain: str,
+    middle_name: Optional[str] = None,
+    tool_config: Optional[List[Dict]] = None
+) -> Dict[str, Any]:
+    """
+    Attempt to guess the email using Hunter.io's email-finder endpoint.
+    We'll interpret the "score" (0-100) from the response and map it to "email_confidence".
+    
+    Fix applied: We handle the case where score might be None or not numeric, defaulting to 0.
+    """
+    logger.info("Entering guess_email_with_hunter.")
+    if not first_name or not last_name or not domain:
+        logger.error("Required parameters first_name, last_name, and domain must be provided.")
+        return {"email": "", "email_confidence": "low"}
+
+    HUNTER_API_KEY = get_hunter_access_token(tool_config)
+    if not HUNTER_API_KEY:
+        logger.warning("No Hunter API key available. Returning low-confidence guess.")
+        return {"email": "", "email_confidence": "low"}
+
+    url = (
+        "https://api.hunter.io/v2/email-finder"
+        f"?domain={domain}"
+        f"&first_name={first_name}"
+        f"&last_name={last_name}"
+        f"&api_key={HUNTER_API_KEY}"
+    )
+    # If you want to handle middle_name and the API supports it, you could append it:
+    #   f"&middle_name={middle_name}"
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                if response.status != 200:
+                    content = await safe_read_json_or_text(response)
+                    logger.warning(f"[Hunter] email-finder error: {response.status} => {content}")
+                    return {"email": "", "email_confidence": "low"}
+
+                result = await response.json()
+    except Exception as ex:
+        logger.warning(f"[Hunter] Exception => {ex}")
+        return {"email": "", "email_confidence": "low"}
+
+    data = result.get("data", {})
+    found_email = data.get("email", "")
+
+    # Safely parse numeric score
+    raw_score = data.get("score")  # might be int, float, None, or not present
+    try:
+        score = float(raw_score) if raw_score is not None else 0.0
+    except (ValueError, TypeError):
+        score = 0.0
+
+    if score >= 80:
+        confidence = "high"
+    elif score >= 50:
+        confidence = "medium"
+    else:
+        confidence = "low"
+
+    output = {
+        "email": found_email,
+        "email_confidence": confidence
+    }
+    logger.info("Exiting guess_email_with_hunter.")
+    return output
+
+
+GUESS_EMAIL_TOOL_MAP = {
+    "zerobounce": guess_email_with_zero_bounce,
+    "hunter": guess_email_with_hunter
+}
+
+
+# --------------------------------------------------------------------------------
+# 4. Aggregators (High-Level Validation + Guess)
+# --------------------------------------------------------------------------------
+
+@assistant_tool
+async def check_email_validity(
+    email_id: str,
+    tool_config: Optional[List[Dict]] = None
+) -> Dict[str, Any]:
+    """
+    Validate an email address by checking each provider in priority order:
+      1) ZeroBounce
+      2) Hunter
+    If a provider returns high confidence, we stop. Otherwise we continue.
+    """
+    logger.info("Entering check_email_validity method.")
+    if not tool_config:
+        logger.warning("No tool configuration found; returning low confidence.")
+        return {
+            "email": email_id,
+            "confidence": "low",
+            "is_valid": False
+        }
+
+    # Identify which providers are available
+    provider_names = [item.get("name") for item in tool_config if item.get("name")]
+    priority = ["zerobounce", "hunter"]
+
+    final_result = {
+        "email": email_id,
+        "confidence": "low",
+        "is_valid": False
+    }
+
+    for provider in priority:
+        if provider in provider_names:
+            if provider == "zerobounce":
+                result = await check_email_validity_with_zero_bounce(email_id, tool_config)
+            elif provider == "hunter":
+                result = await check_email_validity_with_hunter(email_id, tool_config)
+            else:
+                continue
+
+            # Overwrite final_result with the latest
+            final_result = result
+            # If we get "high" confidence, stop.
+            if result["confidence"] == "high":
+                logger.info(f"{provider} gave high confidence. Stopping further checks.")
+                break
+
+    logger.info("Exiting check_email_validity method with result: %s", final_result)
+    return final_result
+
+
+@assistant_tool
+async def guess_email(
+    first_name: str,
+    last_name: str,
+    domain: str,
+    middle_name: Optional[str],
+    tool_config: Optional[List[Dict]] = None
+) -> Dict[str, Any]:
+    """
+    Attempt to guess the email using the provider(s) indicated in the tool_config, in priority order.
+    If the first guess is "high" confidence, we stop. Otherwise we move on.
+    """
+    logger.info("Entering guess_email method.")
+    if not tool_config:
+        logger.warning("No tool configuration found; returning low-confidence guess.")
+        return {"email": "", "email_confidence": "low"}
+
+    provider_names = [item.get("name") for item in tool_config if item.get("name")]
+    priority = ["hunter", "zerobounce"]
+    final_result = {"email": "", "email_confidence": "low"}
+
+    for provider in priority:
+        if provider in provider_names:
+            guess_func = GUESS_EMAIL_TOOL_MAP[provider]
+            result = await guess_func(first_name, last_name, domain, middle_name, tool_config)
+            final_result = result
+            if result.get("email_confidence") == "high":
+                logger.info(f"{provider} gave high confidence on guess. Stopping further guesses.")
+                break
+
+    logger.info("Exiting guess_email method with result: %s", final_result)
+    return final_result
+
+
+# --------------------------------------------------------------------------------
+# 5. Orchestrating everything in a single function
+# --------------------------------------------------------------------------------
+
+@assistant_tool
+async def process_email_properties(
+    input_properties: Dict[str, Any],
+    tool_config: Optional[List[Dict]] = None
+) -> None:
+    """
+    1. If input_properties["email"] is present, validate it.
+       - If invalid or medium/low confidence, guess a new one.
+    2. If email is empty, guess a new one using domain + name fields.
+    3. If guessed email has "HIGH" confidence, replace input_properties["email"].
+       Otherwise, store guess in `additional_properties["guessed_email"]`.
+    """
+    logger.info("Entering process_email_properties.")
+    first_name = input_properties.get("first_name", "")
+    last_name = input_properties.get("last_name", "")
+    email = input_properties.get("email", "")
+    additional_properties = input_properties.get("additional_properties", {})
+
+    if email:
+        val_result = await check_email_validity(email, tool_config)
+        # If not valid or confidence < "high", we attempt to guess
+        if not val_result["is_valid"]:
+            logger.info("Email invalid or low/medium confidence; attempting to guess new one.")
+            guessed_result = await guess_email(
+                first_name,
+                last_name,
+                extract_domain(email),
+                "",
+                tool_config
+            )
+            if is_guess_usable(guessed_result):
+                input_properties["email"] = guessed_result["email"]
+            else:
+                additional_properties["guessed_email"] = guessed_result.get("email", "")
+                input_properties["email"] = ""
+    else:
+        # No existing email => must guess a new one
+        domain = input_properties.get("primary_domain_of_organization", "")
+        if not domain:
+            logger.info("No primary domain found; cannot guess.")
+            additional_properties["guessed_email"] = ""
+            input_properties["email"] = ""
+        else:
+            guessed_result = await guess_email(first_name, last_name, domain, "", tool_config)
+            if is_guess_usable(guessed_result):
+                input_properties["email"] = guessed_result["email"]
+            else:
+                additional_properties["guessed_email"] = guessed_result.get("email", "")
+                input_properties["email"] = ""
+
+    input_properties["additional_properties"] = additional_properties
+    logger.info("Exiting process_email_properties.")
+    return input_properties
+
+
+# --------------------------------------------------------------------------------
+# 6. Helper Functions
+# --------------------------------------------------------------------------------
+
+async def safe_read_json_or_text(response: aiohttp.ClientResponse) -> Any:
+    """
+    Safely attempts to parse an aiohttp response as JSON, else returns text.
+    """
+    try:
+        return await response.json()
+    except Exception:
+        return await response.text()
+
+
+def extract_domain(email: str) -> str:
+    """Extract domain from email ( user@domain.com -> domain.com )."""
+    if "@" not in email:
+        return ""
+    return email.split("@")[-1].strip()
+
+
+def is_guess_usable(guess_result: Dict[str, Any]) -> bool:
+    """
+    Decide if a guess is "usable". 
+    Here we treat "high" or "medium" as usable. 
+    Adjust as needed.
+    """
+    if not guess_result:
+        return False
+    email_confidence = guess_result.get("email_confidence", "").lower()
+    return email_confidence in ["high", "medium"]

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/src/dhisana/utils/dataframe_tools.py

@@ -52,7 +52,7 @@ async def get_structured_output(message: str, response_type, model: str = "o3-mi
         
         # Generate the cache key
         cache_key = f"{message_hash}:{response_type_hash}"
-        cached_response = retrieve_output(get_structured_output, cache_key)
+        cached_response = retrieve_output("get_structured_output", cache_key)
         if cached_response is not None:
             parsed_cached_response = response_type.parse_raw(cached_response)
             return parsed_cached_response, 'SUCCESS'

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/src/dhisana/utils/enrich_lead_information.py

@@ -129,11 +129,13 @@ async def enrich_with_provider(
         raise ValueError("No tool configuration found.")
 
     chosen_tool_func = None
-    for item in tool_config:
-        logger.debug("Selected tool: %s", item.get("name"))
-        name = item.get("name")
-        if name in USER_LOOKUP_TOOL_NAME_TO_FUNCTION_MAP and name in ALLOWED_ENRICHMENT_TOOLS:
-            chosen_tool_func = USER_LOOKUP_TOOL_NAME_TO_FUNCTION_MAP[name]
+    for allowed_tool_name in ALLOWED_ENRICHMENT_TOOLS:
+        for item in tool_config:
+            logger.debug("Selected tool: %s", item.get("name"))
+            if item.get("name") == allowed_tool_name and allowed_tool_name in USER_LOOKUP_TOOL_NAME_TO_FUNCTION_MAP:
+                chosen_tool_func = USER_LOOKUP_TOOL_NAME_TO_FUNCTION_MAP[allowed_tool_name]
+                break
+        if chosen_tool_func:
             break
 
     if not chosen_tool_func:

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/src/dhisana/utils/generate_email.py

@@ -87,7 +87,7 @@ async def generate_personalized_email_copy(
     # Pull out fields or fallback to empty if None
     lead_data = cleaned_context.lead_info or Lead()
     sender_data = cleaned_context.sender_info or SenderInfo()
-    campaign_data = cleaned_context.campaing_context or CampaingContext()
+    campaign_data = cleaned_context.campaign_context or CampaingContext()
     conversation_data = cleaned_context.current_conversation_context or ConversationContext()
 
     # Construct the consolidated prompt

{dhisana-0.0.1.dev44 → dhisana-0.0.1.dev45}/src/dhisana/utils/generate_email_response.py

@@ -83,7 +83,7 @@ async def generate_inbound_email_response_copy(
        {cleaned_context.model_dump()}
 
     3. Triage Guidelines:
-       {cleaned_context.campaing_context.email_triage_guidelines}
+       {cleaned_context.campaign_context.email_triage_guidelines}
 
        - If the request is standard, simple, or obviously handled by standard processes,
          set triage_status to "AUTOMATIC".