dhisana 0.0.1.dev116__py3-none-any.whl → 0.0.1.dev236__py3-none-any.whl

dhisana/utils/apollo_tools.py

@@ -1,19 +1,15 @@
 import asyncio
-import hashlib
 import json
 import logging
 import os
 import re
 import aiohttp
 import backoff
-from datetime import datetime, timedelta
 
-from pydantic import BaseModel
-from dhisana.schemas.sales import LeadsQueryFilters, SmartList, SmartListLead
-from dhisana.utils.cache_output_tools import cache_output, retrieve_output
+from dhisana.schemas.sales import LeadsQueryFilters, CompanyQueryFilters
 from dhisana.utils.assistant_tool_tag import assistant_tool
 from urllib.parse import urlparse, parse_qs
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 from dhisana.utils.clean_properties import cleanup_properties
 
@@ -21,48 +17,81 @@ logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-def get_apollo_access_token(tool_config: Optional[List[Dict]] = None) -> str:
+def get_apollo_access_token(tool_config: Optional[List[Dict]] = None) -> Tuple[str, bool]:
     """
-    Retrieves the APOLLO_API_KEY access token from the provided tool configuration.
+    Retrieves an Apollo access token from tool configuration or environment variables.
 
     Args:
-        tool_config (list): A list of dictionaries containing the tool configuration. 
-                            Each dictionary should have a "name" key and a "configuration" key,
-                            where "configuration" is a list of dictionaries containing "name" and "value" keys.
+        tool_config (list): Optional tool configuration payload provided to the tool.
 
     Returns:
-        str: The APOLLO_API_KEY access token.
+        Tuple[str, bool]: A tuple containing the token string and a boolean flag indicating
+            whether the token represents an OAuth bearer token (``True``) or an API key (``False``).
 
     Raises:
-        ValueError: If the access token is not found in the tool configuration or environment variable.
+        ValueError: If the Apollo integration has not been configured.
     """
-    APOLLO_API_KEY = None
+    token: Optional[str] = None
+    is_oauth = False
 
     if tool_config:
-        logger.debug(f"Tool config provided: {tool_config}")
         apollo_config = next(
             (item for item in tool_config if item.get("name") == "apollo"), None
         )
         if apollo_config:
             config_map = {
-                item["name"]: item["value"]
+                item["name"]: item.get("value")
                 for item in apollo_config.get("configuration", [])
                 if item
             }
-            APOLLO_API_KEY = config_map.get("apiKey")
+
+            raw_oauth = config_map.get("oauth_tokens")
+            if isinstance(raw_oauth, str):
+                try:
+                    raw_oauth = json.loads(raw_oauth)
+                except Exception:
+                    raw_oauth = None
+            if isinstance(raw_oauth, dict):
+                token = (
+                    raw_oauth.get("access_token")
+                    or raw_oauth.get("token")
+                )
+                if token:
+                    is_oauth = True
+
+            if not token:
+                direct_access_token = config_map.get("access_token")
+                if direct_access_token:
+                    token = direct_access_token
+                    is_oauth = True
+
+            if not token:
+                api_key = config_map.get("apiKey") or config_map.get("api_key")
+                if api_key:
+                    token = api_key
+                    is_oauth = False
         else:
             logger.warning("No 'apollo' config item found in tool_config.")
-    else:
-        logger.debug("No tool_config provided or it's None.")
 
-    # Check environment variable if no key found yet
-    APOLLO_API_KEY = APOLLO_API_KEY or os.getenv("APOLLO_API_KEY")
-
-    if not APOLLO_API_KEY:
-        logger.error("APOLLO_API_KEY not found in configuration or environment.")
-        raise ValueError("APOLLO_API_KEY access token not found in tool_config or environment variable")
+    if not token:
+        env_oauth_token = os.getenv("APOLLO_ACCESS_TOKEN")
+        if env_oauth_token:
+            token = env_oauth_token
+            is_oauth = True
+
+    if not token:
+        env_api_key = os.getenv("APOLLO_API_KEY")
+        if env_api_key:
+            token = env_api_key
+            is_oauth = False
+
+    if not token:
+        logger.error("Apollo integration is not configured.")
+        raise ValueError(
+            "Apollo integration is not configured. Please configure the connection to Apollo in Integrations."
+        )
 
-    return APOLLO_API_KEY
+    return token, is_oauth
 
 
 @assistant_tool
@@ -77,6 +106,7 @@ async def enrich_person_info_from_apollo(
     linkedin_url: Optional[str] = None,
     email: Optional[str] = None,
     phone: Optional[str] = None,
+    fetch_valid_phone_number: Optional[bool] = False,
     tool_config: Optional[List[Dict]] = None,
 ) -> Dict[str, Any]:
     """
@@ -86,37 +116,40 @@ async def enrich_person_info_from_apollo(
     - **linkedin_url** (*str*, optional): LinkedIn profile URL of the person.
     - **email** (*str*, optional): Email address of the person.
     - **phone** (*str*, optional): Phone number of the person.
+    - **fetch_valid_phone_number** (*bool*, optional): If True, include phone numbers in the API response. Defaults to False.
 
     Returns:
     - **dict**: JSON response containing person information.
     """
     logger.info("Entering enrich_person_info_from_apollo")
 
-    APOLLO_API_KEY = get_apollo_access_token(tool_config)
+    token, is_oauth = get_apollo_access_token(tool_config)
 
     if not linkedin_url and not email and not phone:
         logger.warning("No linkedin_url, email, or phone provided. At least one is required.")
         return {'error': "At least one of linkedin_url, email, or phone must be provided"}
 
-    headers = {
-        "X-Api-Key": f"{APOLLO_API_KEY}",
-        "Content-Type": "application/json"
-    }
+    headers = {"Content-Type": "application/json"}
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
 
     data = {}
     if linkedin_url:
         logger.debug(f"LinkedIn URL provided: {linkedin_url}")
         data['linkedin_url'] = linkedin_url
-        cached_response = retrieve_output("enrich_person_info_from_apollo", linkedin_url)
-        if cached_response is not None:
-            logger.info(f"Cache hit for LinkedIn URL: {linkedin_url}")
-            return cached_response
     if email:
         logger.debug(f"Email provided: {email}")
         data['email'] = email
     if phone:
         logger.debug(f"Phone provided: {phone}")
         data['phone_numbers'] = [phone]  # Apollo expects a list for phone numbers
+    
+    # Add reveal_phone_number parameter if fetch_valid_phone_number is True
+    if fetch_valid_phone_number:
+        logger.debug("fetch_valid_phone_number flag is True, including phone numbers in API response")
+        data['reveal_phone_number'] = True
 
     url = 'https://api.apollo.io/api/v1/people/match'
 
@@ -126,8 +159,6 @@ async def enrich_person_info_from_apollo(
                 logger.debug(f"Received response status: {response.status}")
                 if response.status == 200:
                     result = await response.json()
-                    if linkedin_url:
-                        cache_output("enrich_person_info_from_apollo", linkedin_url, result)
                     logger.info("Successfully retrieved person info from Apollo.")
                     return result
                 elif response.status == 429:
@@ -179,11 +210,12 @@ async def lookup_person_in_apollo_by_name(
         logger.warning("No full_name provided.")
         return {'error': "Full name is required"}
 
-    APOLLO_API_KEY = get_apollo_access_token(tool_config)
-    headers = {
-        "X-Api-Key": f"{APOLLO_API_KEY}",
-        "Content-Type": "application/json"
-    }
+    token, is_oauth = get_apollo_access_token(tool_config)
+    headers = {"Content-Type": "application/json"}
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
 
     # Construct the query payload
     data = {
@@ -192,16 +224,6 @@ async def lookup_person_in_apollo_by_name(
         "per_page": 10
     }
 
-    # Build a cache key that includes full_name and company_name (if provided)
-    # so that results are correctly cached and retrieved.
-    key_item = f"lookup_person_in_apollo_by_name_{full_name}_{company_name or ''}".lower()
-
-    # Attempt to retrieve a cached response first
-    cached_response = retrieve_output("lookup_person_in_apollo_by_name", key_item)
-    if cached_response is not None:
-        logger.info(f"Cache hit for user: {full_name}, company: {company_name or ''}")
-        return cached_response
-
     url = 'https://api.apollo.io/api/v1/mixed_people/search'
     logger.debug(f"Making request to Apollo with payload: {data}")
 
@@ -212,7 +234,6 @@ 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.")
-                    cache_output("lookup_person_in_apollo_by_name", key_item, result)
                     return result
                 elif response.status == 429:
                     msg = "Rate limit exceeded"
@@ -256,23 +277,21 @@ async def enrich_organization_info_from_apollo(
     """
     logger.info("Entering enrich_organization_info_from_apollo")
 
-    APOLLO_API_KEY = get_apollo_access_token(tool_config)
+    token, is_oauth = get_apollo_access_token(tool_config)
 
     if not organization_domain:
         logger.warning("No organization domain provided.")
         return {'error': "organization domain must be provided"}
 
     headers = {
-        "X-Api-Key": f"{APOLLO_API_KEY}",
         "Content-Type": "application/json",
         "Cache-Control": "no-cache",
         "accept": "application/json"
     }
-
-    cached_response = retrieve_output("enrich_organization_info_from_apollo", organization_domain)
-    if cached_response is not None:
-        logger.info(f"Cache hit for organization domain: {organization_domain}")
-        return cached_response
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
 
     url = f'https://api.apollo.io/api/v1/organizations/enrich?domain={organization_domain}'
     logger.debug(f"Making GET request to Apollo for organization domain: {organization_domain}")
@@ -283,7 +302,6 @@ async def enrich_organization_info_from_apollo(
                 logger.debug(f"Received response status: {response.status}")
                 if response.status == 200:
                     result = await response.json()
-                    cache_output("enrich_organization_info_from_apollo", organization_domain, result)
                     logger.info("Successfully retrieved organization info from Apollo.")
                     return result
                 elif response.status == 429:
@@ -315,22 +333,12 @@ async def enrich_organization_info_from_apollo(
 )
 async def fetch_apollo_data(session, url: str, headers: Dict[str, str], payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     logger.info("Entering fetch_apollo_data")
-    key_data = f"{url}_{json.dumps(payload, sort_keys=True)}"
-    key_hash = hashlib.sha256(key_data.encode()).hexdigest()
-    logger.debug(f"Cache key hash: {key_hash}")
-
-    cached_response = retrieve_output("fetch_apollo_data", key_hash)
-    if cached_response is not None:
-        logger.info("Cache hit for fetch_apollo_data.")
-        return cached_response
-
-    logger.debug("No cache hit. Making POST request to Apollo.")
+    logger.debug("Making POST request to Apollo.")
     async with session.post(url, headers=headers, json=payload) as response:
         logger.debug(f"Received response status: {response.status}")
         if response.status == 200:
             result = await response.json()
-            cache_output("fetch_apollo_data", key_hash, result)
-            logger.info("Successfully fetched data from Apollo and cached it.")
+            logger.info("Successfully fetched data from Apollo.")
             return result
         elif response.status == 429:
             msg = "Rate limit exceeded"
@@ -357,12 +365,15 @@ async def search_people_with_apollo(
         logger.warning("No payload given; returning empty result.")
         return []
 
-    api_key = get_apollo_access_token(tool_config)
+    token, is_oauth = get_apollo_access_token(tool_config)
     headers = {
         "Cache-Control": "no-cache",
         "Content-Type": "application/json",
-        "X-Api-Key": api_key,
     }
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
 
     url = "https://api.apollo.io/api/v1/mixed_people/search"
     logger.info(f"Sending payload to Apollo (single page): {json.dumps(dynamic_payload, indent=2)}")
@@ -388,16 +399,6 @@ def fill_in_properties_with_preference(input_user_properties: dict, person_data:
         """Returns True if the value is None, empty string, or only whitespace."""
         return value is None or (isinstance(value, str) and not value.strip())
 
-    # Email
-    if is_empty(input_user_properties.get("email")):
-        input_user_properties["email"] = person_data.get("email", "")
-
-    # Phone
-    if is_empty(input_user_properties.get("phone")):
-        # person_data["contact"] might not be defined, so we chain get calls
-        input_user_properties["phone"] = ((person_data.get("contact", {}) or {})
-                                          .get("sanitized_phone", ""))
-
     # Full name
     # Because `person_data.get("name")` has precedence over input_user_properties,
     # we only update it if input_user_properties is empty/None for "full_name".
@@ -412,6 +413,16 @@ def fill_in_properties_with_preference(input_user_properties: dict, person_data:
     if is_empty(input_user_properties.get("last_name")) and person_data.get("last_name"):
         input_user_properties["last_name"] = person_data["last_name"]
 
+    # Email
+    if is_empty(input_user_properties.get("email")):
+        input_user_properties["email"] = person_data.get("email", "")
+
+    # Phone
+    if is_empty(input_user_properties.get("phone")):
+        # person_data["contact"] might not be defined, so we chain get calls
+        input_user_properties["phone"] = ((person_data.get("contact", {}) or {})
+                                          .get("sanitized_phone", ""))
+
     # LinkedIn URL
     if is_empty(input_user_properties.get("user_linkedin_url")) and person_data.get("linkedin_url"):
         input_user_properties["user_linkedin_url"] = person_data["linkedin_url"]
@@ -451,11 +462,19 @@ def fill_in_properties_with_preference(input_user_properties: dict, person_data:
     if is_empty(input_user_properties.get("summary_about_lead")) and person_data.get("headline"):
         input_user_properties["summary_about_lead"] = person_data["headline"]
 
-    # City/State -> lead_location
-    city = person_data.get("city", "")
-    state = person_data.get("state", "")
-    if is_empty(input_user_properties.get("lead_location")) and (city or state):
-        lead_location = f"{city}, {state}".strip(", ")
+    # City/State -> lead_location (avoid literal "None")
+    city = person_data.get("city")
+    state = person_data.get("state")
+    parts = []
+    for value in (city, state):
+        if value is None:
+            continue
+        s = str(value).strip()
+        if not s or s.lower() == "none":
+            continue
+        parts.append(s)
+    lead_location = ", ".join(parts) if parts else None
+    if is_empty(input_user_properties.get("lead_location")) and lead_location:
         input_user_properties["lead_location"] = lead_location
 
     # Filter out placeholder emails
@@ -467,13 +486,13 @@ def fill_in_properties_with_preference(input_user_properties: dict, person_data:
 
 async def search_leads_with_apollo(
     query: LeadsQueryFilters,
-    request: SmartList,
+    max_items_to_search: Optional[int] = 10,
     example_url: Optional[str] = None,
     tool_config: Optional[List[Dict[str, Any]]] = None,
-) -> List[SmartListLead]:
+) -> List[Dict]:
     logger.info("Entering search_leads_with_apollo")
 
-    max_items = request.max_items_to_search or 10
+    max_items = max_items_to_search or 10
     if max_items > 2500:
         logger.warning("Requested max_items_to_search > 2000, overriding to 2000.")
         max_items = 2500
@@ -519,7 +538,7 @@ async def search_leads_with_apollo(
             # Important: handle personNotTitles as well
             "personNotTitles": "person_not_titles",
 
-            "qOrganizationJobTitles": "q_keywords",
+            "qOrganizationJobTitles": "q_organization_job_titles",
             "sortAscending": "sort_ascending",
             "sortByField": "sort_by_field",
             "contactEmailStatusV2": "contact_email_status",
@@ -592,6 +611,8 @@ async def search_leads_with_apollo(
                     "organization_ids",
                     "organization_num_employees_ranges",
                     "person_not_titles",  # <--- added so single item is forced into list
+                    "q_organization_job_titles",
+                    "organization_latest_funding_stage_cd",
                 ):
                     if isinstance(final_value, str):
                         final_value = [final_value]
@@ -612,7 +633,8 @@ async def search_leads_with_apollo(
         dynamic_payload = {
             "person_titles": query.person_current_titles or [],
             "person_locations": query.person_locations or [],
-            "search_signal_ids": query.search_signal_ids or query.filter_by_signals or [],
+            "search_signal_ids": query.filter_by_signals or [],
+            "q_keywords": query.search_keywords or "",
             "organization_num_employees_ranges": (
                 query.organization_num_employees_ranges
                 or [f"{query.min_employees_in_organization or 1},{query.max_employees_in_organization or 1000}"]
@@ -620,6 +642,10 @@ async def search_leads_with_apollo(
             "page": 1,
             "per_page": min(max_items, 100),
         }
+        if query.job_openings_with_titles:
+            dynamic_payload["q_organization_job_titles"] = query.job_openings_with_titles
+        if query.latest_funding_stages:
+            dynamic_payload["organization_latest_funding_stage_cd"] = query.latest_funding_stages
         if query.sort_by_field is not None:
             dynamic_payload["sort_by_field"] = query.sort_by_field
         if query.sort_ascending is not None:
@@ -657,9 +683,9 @@ async def search_leads_with_apollo(
     logger.info(f"Fetched a total of {len(all_people)} items from Apollo (across pages).")
 
     # -----------------------------------------------
-    # Convert raw results -> SmartListLead objects
+    # Convert raw results -> dictionary objects
     # -----------------------------------------------
-    leads: List[SmartListLead] = []
+    leads: List[Dict[str, Any]] = []
     for user_data_from_apollo in all_people:
         person_data = user_data_from_apollo
 
@@ -673,15 +699,217 @@ async def search_leads_with_apollo(
         additional_props["apollo_person_data"] = json.dumps(person_data)
         input_user_properties["additional_properties"] = additional_props
 
-        lead = SmartListLead(**input_user_properties)
-        lead.agent_instance_id = request.agent_instance_id
-        lead.smart_list_id = request.id
-        lead.organization_id = request.organization_id
-        leads.append(lead)
+        leads.append(input_user_properties)
 
-    logger.info(f"Converted {len(leads)} Apollo records into SmartListLead objects.")
+    logger.info(f"Converted {len(leads)} Apollo records into dictionaries.")
     return leads
 
+
+async def search_leads_with_apollo_page(
+    query: LeadsQueryFilters,
+    page: Optional[int] = 1,
+    per_page: Optional[int] = 25,
+    example_url: Optional[str] = None,
+    tool_config: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Fetch a single page of Apollo leads using ``page`` and ``per_page``.
+
+    This helper performs one request to the Apollo API and returns the fetched
+    leads along with comprehensive pagination metadata.
+
+    Args:
+        query: LeadsQueryFilters object containing search criteria
+        page: Page number to fetch (1-indexed, defaults to 1)
+        per_page: Number of results per page (defaults to 25)
+        example_url: Optional URL to parse search parameters from
+        tool_config: Optional tool configuration for API keys
+
+    Returns:
+        Dict containing:
+        - current_page: The current page number
+        - per_page: Number of results per page
+        - total_entries: Total number of results available
+        - total_pages: Total number of pages available
+        - has_next_page: Boolean indicating if more pages exist
+        - next_page: Next page number (None if no more pages)
+        - results: List of lead dictionaries for this page
+    """
+    logger.info("Entering search_leads_with_apollo_page")
+
+    if example_url:
+        parsed_url = urlparse(example_url)
+        query_string = parsed_url.query
+
+        if not query_string and "?" in parsed_url.fragment:
+            fragment_query = parsed_url.fragment.split("?", 1)[1]
+            query_string = fragment_query
+
+        query_params = parse_qs(query_string)
+
+        dynamic_payload: Dict[str, Any] = {
+            "page": page,
+            "per_page": per_page,
+        }
+
+        mapping = {
+            "personLocations": "person_locations",
+            "organizationNumEmployeesRanges": "organization_num_employees_ranges",
+            "personTitles": "person_titles",
+            "personNotTitles": "person_not_titles",
+            "qOrganizationJobTitles": "q_organization_job_titles",
+            "sortAscending": "sort_ascending",
+            "sortByField": "sort_by_field",
+            "contactEmailStatusV2": "contact_email_status",
+            "searchSignalIds": "search_signal_ids",
+            "organizationLatestFundingStageCd": "organization_latest_funding_stage_cd",
+            "revenueRange[max]": "revenue_range_max",
+            "revenueRange[min]": "revenue_range_min",
+            "currentlyUsingAnyOfTechnologyUids": "currently_using_any_of_technology_uids",
+            "organizationIndustryTagIds": "organization_industry_tag_ids",
+            "notOrganizationIds": "not_organization_ids",
+        }
+
+        for raw_key, raw_value_list in query_params.items():
+            if raw_key.endswith("[]"):
+                key = raw_key[:-2]
+            else:
+                key = raw_key
+
+            if raw_key in mapping:
+                key = mapping[raw_key]
+            elif key in mapping:
+                key = mapping[key]
+            else:
+                key = re.sub(r"(?<!^)(?=[A-Z])", "_", key).lower()
+
+            if len(raw_value_list) == 1:
+                final_value: Union[str, List[str]] = raw_value_list[0]
+            else:
+                final_value = raw_value_list
+
+            if key in ("sort_ascending",):
+                val_lower = str(final_value).lower()
+                final_value = val_lower in ("true", "1", "yes")
+
+            if key in ("page", "per_page"):
+                try:
+                    final_value = int(final_value)
+                except ValueError:
+                    pass
+
+            if key == "q_keywords" and isinstance(final_value, list):
+                final_value = " ".join(final_value)
+
+            if raw_key.endswith("[]"):
+                if isinstance(final_value, str):
+                    final_value = [final_value]
+            else:
+                if key in (
+                    "person_locations",
+                    "person_titles",
+                    "person_seniorities",
+                    "organization_locations",
+                    "q_organization_domains",
+                    "contact_email_status",
+                    "organization_ids",
+                    "organization_num_employees_ranges",
+                    "person_not_titles",
+                    "q_organization_job_titles",
+                    "organization_latest_funding_stage_cd",
+                ):
+                    if isinstance(final_value, str):
+                        final_value = [final_value]
+
+            dynamic_payload[key] = final_value
+
+        if dynamic_payload.get("sort_by_field") == "[none]":
+            dynamic_payload.pop("sort_by_field")
+
+    # -----------------------------------
+    # B) No example_url -> build from `query`
+    # -----------------------------------
+    else:
+        dynamic_payload = {
+            "person_titles": query.person_current_titles or [],
+            "person_locations": query.person_locations or [],
+            "search_signal_ids": query.filter_by_signals or [],
+            "q_keywords": query.search_keywords or "",
+            "organization_num_employees_ranges": (
+                query.organization_num_employees_ranges
+                or [f"{query.min_employees_in_organization or 1},{query.max_employees_in_organization or 1000}"]
+            ),
+        }
+        if query.job_openings_with_titles:
+            dynamic_payload["q_organization_job_titles"] = query.job_openings_with_titles
+        if query.latest_funding_stages:
+            dynamic_payload["organization_latest_funding_stage_cd"] = query.latest_funding_stages
+        if query.sort_by_field is not None:
+            dynamic_payload["sort_by_field"] = query.sort_by_field
+        if query.sort_ascending is not None:
+            dynamic_payload["sort_ascending"] = query.sort_ascending
+
+    page_payload = dict(dynamic_payload)
+    page_payload["page"] = page
+    page_payload["per_page"] = per_page
+
+    print(f"Fetching Apollo page {page} with per_page {per_page}..."
+          f" Payload: {json.dumps(page_payload, indent=2)}")
+
+    # Get the full Apollo API response with pagination metadata
+    token, is_oauth = get_apollo_access_token(tool_config)
+    headers = {
+        "Cache-Control": "no-cache",
+        "Content-Type": "application/json",
+    }
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
+
+    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)
+        if not apollo_response:
+            return {"current_page": page, "per_page": per_page, "total_entries": 0, "total_pages": 0, "has_next_page": False, "results": []}
+
+        # Extract pagination metadata
+        pagination = apollo_response.get("pagination", {})
+        current_page = pagination.get("page", page)
+        total_entries = pagination.get("total_entries", 0)
+        total_pages = pagination.get("total_pages", 0)
+        per_page_actual = pagination.get("per_page", per_page)
+        
+        # Determine if there are more pages
+        has_next_page = current_page < total_pages
+        
+        # Extract people and contacts
+        people = apollo_response.get("people", [])
+        contacts = apollo_response.get("contacts", [])
+        page_results = people + contacts
+
+    leads: List[Dict[str, Any]] = []
+    for person_data in page_results:
+        input_user_properties: Dict[str, Any] = {}
+        additional_props = input_user_properties.get("additional_properties") or {}
+        input_user_properties = fill_in_properties_with_preference(input_user_properties, person_data)
+        person_data = cleanup_properties(person_data)
+        additional_props["apollo_person_data"] = json.dumps(person_data)
+        input_user_properties["additional_properties"] = additional_props
+        leads.append(input_user_properties)
+
+    logger.info(f"Converted {len(leads)} Apollo records into dictionaries (single page mode). Page {current_page} of {total_pages}")
+    
+    return {
+        "current_page": current_page,
+        "per_page": per_page_actual,
+        "total_entries": total_entries,
+        "total_pages": total_pages,
+        "has_next_page": has_next_page,
+        "next_page": current_page + 1 if has_next_page else None,
+        "results": leads
+    }
+
 @assistant_tool
 async def get_organization_domain_from_apollo(
     organization_id: str,
@@ -741,22 +969,20 @@ async def get_organization_details_from_apollo(
     """
     logger.info("Entering get_organization_details_from_apollo")
 
-    APOLLO_API_KEY = get_apollo_access_token(tool_config)
+    token, is_oauth = get_apollo_access_token(tool_config)
     if not organization_id:
         logger.warning("No organization_id provided.")
         return {'error': "Organization ID must be provided"}
 
     headers = {
-        "X-Api-Key": APOLLO_API_KEY,
         "Content-Type": "application/json",
         "Cache-Control": "no-cache",
         "Accept": "application/json"
     }
-
-    cached_response = retrieve_output("get_organization_details_from_apollo", organization_id)
-    if cached_response is not None:
-        logger.info(f"Cache hit for organization ID: {organization_id}")
-        return cached_response
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
 
     url = f'https://api.apollo.io/api/v1/organizations/{organization_id}'
     logger.debug(f"Making GET request to Apollo for organization ID: {organization_id}")
@@ -769,7 +995,6 @@ async def get_organization_details_from_apollo(
                     result = await response.json()
                     org_details = result.get('organization', {})
                     if org_details:
-                        cache_output("get_organization_details_from_apollo", organization_id, org_details)
                         logger.info("Successfully retrieved organization details from Apollo.")
                         return org_details
                     else:
@@ -836,7 +1061,7 @@ async def enrich_user_info_with_apollo(
                 email=email,
                 tool_config=tool_config
             )
-        except Exception as e:
+        except Exception:
             logger.exception("Exception occurred while enriching person info from Apollo by LinkedIn or email.")
     else:
         # Fallback to name-based lookup
@@ -884,11 +1109,11 @@ async def enrich_user_info_with_apollo(
                                 linkedin_url=linkedin_url,
                                 tool_config=tool_config
                             )
-                        except Exception as e:
+                        except Exception:
                             logger.exception("Exception occurred during second stage Apollo enrichment.")
                     if user_data_from_apollo:
                         break
-        except Exception as e:
+        except Exception:
             logger.exception("Exception occurred while performing name-based lookup in Apollo.")
 
     if not user_data_from_apollo:
@@ -938,11 +1163,20 @@ async def enrich_user_info_with_apollo(
         if not input_user_properties.get("summary_about_lead"):
             input_user_properties["summary_about_lead"] = person_data["headline"]
 
-    # Derive location
-    city = person_data.get("city", "")
-    state = person_data.get("state", "")
-    if city or state:
-        input_user_properties["lead_location"] = f"{city}, {state}".strip(", ")
+    # Derive location (avoid literal "None")
+    city = person_data.get("city")
+    state = person_data.get("state")
+    parts = []
+    for value in (city, state):
+        if value is None:
+            continue
+        s = str(value).strip()
+        if not s or s.lower() == "none":
+            continue
+        parts.append(s)
+    lead_location = ", ".join(parts)
+    if lead_location:
+        input_user_properties["lead_location"] = lead_location
 
     # Verify name match
     first_matched = bool(
@@ -962,3 +1196,389 @@ async def enrich_user_info_with_apollo(
     input_user_properties["additional_properties"] = additional_props
 
     return input_user_properties
+
+
+async def search_companies_with_apollo(
+    tool_config: Optional[List[Dict[str, Any]]] = None,
+    dynamic_payload: Optional[Dict[str, Any]] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Search for companies using Apollo's organizations/search endpoint.
+    
+    Args:
+        tool_config: Apollo API configuration
+        dynamic_payload: Search parameters for the API call
+        
+    Returns:
+        List of company/organization dictionaries
+    """
+    logger.info("Entering search_companies_with_apollo")
+
+    if not dynamic_payload:
+        logger.warning("No payload given; returning empty result.")
+        return []
+
+    token, is_oauth = get_apollo_access_token(tool_config)
+    headers = {
+        "Cache-Control": "no-cache",
+        "Content-Type": "application/json",
+    }
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
+
+    url = "https://api.apollo.io/api/v1/organizations/search"
+    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)
+        if not data:
+            logger.error("No data returned from Apollo organizations search.")
+            return []
+
+        organizations = data.get("organizations", [])
+        accounts = data.get("accounts", [])  # Apollo sometimes returns accounts as well
+        return organizations + accounts
+
+
+def fill_in_company_properties(company_data: dict) -> dict:
+    """
+    Convert Apollo company/organization data into a standardized format.
+    
+    Args:
+        company_data: Raw company data from Apollo API
+        
+    Returns:
+        Dictionary with standardized company properties
+    """
+    company_properties = {}
+
+    # Basic company information
+    company_properties["organization_name"] = company_data.get("name", "")
+    company_properties["primary_domain"] = company_data.get("primary_domain", "")
+    company_properties["website_url"] = company_data.get("website_url", "")
+    company_properties["organization_linkedin_url"] = company_data.get("linkedin_url", "")
+    
+    # Location information
+    company_properties["organization_city"] = company_data.get("city", "")
+    company_properties["organization_state"] = company_data.get("state", "")
+    company_properties["organization_country"] = company_data.get("country", "")
+    
+    # Create a combined location string
+    location_parts = [
+        company_data.get("city", ""),
+        company_data.get("state", ""),
+        company_data.get("country", "")
+    ]
+    company_properties["organization_location"] = ", ".join([part for part in location_parts if part])
+
+    # Company size and financial info
+    company_properties["employee_count"] = company_data.get("estimated_num_employees", 0)
+    company_properties["annual_revenue"] = company_data.get("annual_revenue", 0)
+    
+    # Industry and business info
+    company_properties["industry"] = company_data.get("industry", "")
+    company_properties["keywords"] = ", ".join(company_data.get("keywords", []))
+    company_properties["description"] = company_data.get("description", "")
+    
+    # Funding and growth
+    company_properties["founded_year"] = company_data.get("founded_year", "")
+    company_properties["funding_stage"] = company_data.get("latest_funding_stage", "")
+    company_properties["total_funding"] = company_data.get("total_funding", 0)
+    
+    # Technology stack
+    tech_stack = company_data.get("technology_names", [])
+    if tech_stack:
+        company_properties["technology_stack"] = ", ".join(tech_stack)
+    
+    # Apollo-specific IDs
+    company_properties["apollo_organization_id"] = company_data.get("id", "")
+    
+    # Additional metadata
+    company_properties["phone"] = company_data.get("phone", "")
+    company_properties["facebook_url"] = company_data.get("facebook_url", "")
+    company_properties["twitter_url"] = company_data.get("twitter_url", "")
+    
+    # Store raw data for reference
+    company_properties["additional_properties"] = {
+        "apollo_organization_data": json.dumps(cleanup_properties(company_data))
+    }
+
+    return company_properties
+
+
+@assistant_tool
+async def search_companies_with_apollo_page(
+    query: CompanyQueryFilters,
+    page: Optional[int] = 1,
+    per_page: Optional[int] = 25,
+    example_url: Optional[str] = None,
+    tool_config: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """
+    Fetch a single page of Apollo companies using ``page`` and ``per_page``.
+
+    This helper performs one request to the Apollo API and returns the fetched
+    companies along with comprehensive pagination metadata.
+
+    Args:
+        query: CompanyQueryFilters object containing search criteria
+        page: Page number to fetch (1-indexed, defaults to 1)
+        per_page: Number of results per page (defaults to 25)
+        example_url: Optional URL to parse search parameters from
+        tool_config: Optional tool configuration for API keys
+
+    Returns:
+        Dict containing:
+        - current_page: The current page number
+        - per_page: Number of results per page
+        - total_entries: Total number of results available
+        - total_pages: Total number of pages available
+        - has_next_page: Boolean indicating if more pages exist
+        - next_page: Next page number (None if no more pages)
+        - results: List of company dictionaries for this page
+    """
+    logger.info("Entering search_companies_with_apollo_page")
+
+    if example_url:
+        parsed_url = urlparse(example_url)
+        query_string = parsed_url.query
+
+        if not query_string and "?" in parsed_url.fragment:
+            fragment_query = parsed_url.fragment.split("?", 1)[1]
+            query_string = fragment_query
+
+        query_params = parse_qs(query_string)
+
+        dynamic_payload: Dict[str, Any] = {
+            "page": page,
+            "per_page": per_page,
+        }
+
+        # Organization-specific URL parameter mapping
+        mapping = {
+            "organizationLocations": "organization_locations",
+            "organizationNumEmployeesRanges": "organization_num_employees_ranges",
+            "organizationIndustries": "organization_industries",
+            "organizationIndustryTagIds": "organization_industry_tag_ids",
+            "qKeywords": "q_keywords",
+            "qOrganizationDomains": "q_organization_domains",
+            "sortAscending": "sort_ascending",
+            "sortByField": "sort_by_field",
+            "organizationLatestFundingStageCd": "organization_latest_funding_stage_cd",
+            "revenueRange[max]": "revenue_range_max",
+            "revenueRange[min]": "revenue_range_min",
+            "currentlyUsingAnyOfTechnologyUids": "currently_using_any_of_technology_uids",
+            "organizationIds": "organization_ids",
+            "notOrganizationIds": "not_organization_ids",
+            "qOrganizationSearchListId": "q_organization_search_list_id",
+            "qNotOrganizationSearchListId": "q_not_organization_search_list_id",
+        }
+
+        for raw_key, raw_value_list in query_params.items():
+            if raw_key.endswith("[]"):
+                key = raw_key[:-2]
+            else:
+                key = raw_key
+
+            if raw_key in mapping:
+                key = mapping[raw_key]
+            elif key in mapping:
+                key = mapping[key]
+            else:
+                key = re.sub(r"(?<!^)(?=[A-Z])", "_", key).lower()
+
+            if len(raw_value_list) == 1:
+                final_value: Union[str, List[str]] = raw_value_list[0]
+            else:
+                final_value = raw_value_list
+
+            if key in ("sort_ascending",):
+                val_lower = str(final_value).lower()
+                final_value = val_lower in ("true", "1", "yes")
+
+            if key in ("page", "per_page", "revenue_range_min", "revenue_range_max"):
+                try:
+                    final_value = int(final_value)
+                except ValueError:
+                    pass
+
+            if key == "q_organization_keyword_tags":
+                # Handle both string and list inputs, split by comma if string
+                if isinstance(final_value, str):
+                    # Split by comma and strip whitespace
+                    final_value = [tag.strip() for tag in final_value.split(",") if tag.strip()]
+                elif isinstance(final_value, list):
+                    # If it's already a list, flatten any comma-separated items
+                    flattened = []
+                    for item in final_value:
+                        if isinstance(item, str) and "," in item:
+                            flattened.extend([tag.strip() for tag in item.split(",") if tag.strip()])
+                        else:
+                            flattened.append(item)
+                    final_value = flattened
+
+            if raw_key.endswith("[]"):
+                if isinstance(final_value, str):
+                    final_value = [final_value]
+            else:
+                if key in (
+                    "organization_locations",
+                    "organization_industries",
+                    "organization_industry_tag_ids",
+                    "q_organization_domains",
+                    "q_organization_keyword_tags",
+                    "organization_ids",
+                    "not_organization_ids",
+                    "organization_num_employees_ranges",
+                    "currently_using_any_of_technology_uids",
+                    "organization_latest_funding_stage_cd",
+                ):
+                    if isinstance(final_value, str):
+                        final_value = [final_value]
+
+            dynamic_payload[key] = final_value
+
+        if dynamic_payload.get("sort_by_field") == "[none]":
+            dynamic_payload.pop("sort_by_field")
+
+    # -----------------------------------
+    # B) No example_url -> build from `query`
+    # -----------------------------------
+    else:
+        dynamic_payload = {}
+        
+        # Only add fields if they have values (Apollo doesn't like empty arrays)
+        if query.organization_locations:
+            dynamic_payload["organization_locations"] = query.organization_locations
+        if query.organization_industries:
+            dynamic_payload["organization_industries"] = query.organization_industries
+        if query.organization_industry_tag_ids:
+            dynamic_payload["organization_industry_tag_ids"] = query.organization_industry_tag_ids
+            
+        # Handle employee ranges
+        employee_ranges = []
+        if query.organization_num_employees_ranges:
+            employee_ranges = query.organization_num_employees_ranges
+        elif query.min_employees or query.max_employees:
+            employee_ranges = [f"{query.min_employees or 1},{query.max_employees or 1000}"]
+        
+        if employee_ranges:
+            dynamic_payload["organization_num_employees_ranges"] = employee_ranges
+
+        # Add optional parameters only if they have values
+        if query.q_keywords:
+            # Split comma-separated keywords into an array for company search
+            if isinstance(query.q_keywords, str):
+                keyword_tags = [tag.strip() for tag in query.q_keywords.split(",") if tag.strip()]
+            else:
+                keyword_tags = query.q_keywords
+            dynamic_payload["q_organization_keyword_tags"] = keyword_tags
+        if query.q_organization_domains:
+            dynamic_payload["q_organization_domains"] = query.q_organization_domains
+        if query.revenue_range_min is not None:
+            dynamic_payload["revenue_range_min"] = query.revenue_range_min
+        if query.revenue_range_max is not None:
+            dynamic_payload["revenue_range_max"] = query.revenue_range_max
+        if query.organization_latest_funding_stage_cd:
+            dynamic_payload["organization_latest_funding_stage_cd"] = query.organization_latest_funding_stage_cd
+        if query.currently_using_any_of_technology_uids:
+            dynamic_payload["currently_using_any_of_technology_uids"] = query.currently_using_any_of_technology_uids
+        if query.organization_ids:
+            dynamic_payload["organization_ids"] = query.organization_ids
+        if query.not_organization_ids:
+            dynamic_payload["not_organization_ids"] = query.not_organization_ids
+        if query.q_organization_search_list_id:
+            dynamic_payload["q_organization_search_list_id"] = query.q_organization_search_list_id
+        if query.q_not_organization_search_list_id:
+            dynamic_payload["q_not_organization_search_list_id"] = query.q_not_organization_search_list_id
+        if query.sort_by_field is not None:
+            dynamic_payload["sort_by_field"] = query.sort_by_field
+        if query.sort_ascending is not None:
+            dynamic_payload["sort_ascending"] = query.sort_ascending
+
+    # Remove sorting parameters that may not be supported by organizations endpoint
+    if "sort_by_field" in dynamic_payload:
+        dynamic_payload.pop("sort_by_field")
+    if "sort_ascending" in dynamic_payload:
+        dynamic_payload.pop("sort_ascending")
+
+    page_payload = dict(dynamic_payload)
+    page_payload["page"] = page
+    page_payload["per_page"] = per_page
+    
+    # Clean up the payload - remove empty arrays and None values that Apollo doesn't like
+    cleaned_payload = {}
+    for key, value in page_payload.items():
+        if value is not None:
+            if isinstance(value, list):
+                # Only include non-empty lists
+                if value:
+                    cleaned_payload[key] = value
+            else:
+                cleaned_payload[key] = value
+    
+    # Ensure page and per_page are always included
+    cleaned_payload["page"] = page
+    cleaned_payload["per_page"] = per_page
+
+    print(f"Fetching Apollo companies page {page} with per_page {per_page}..."
+          f" Payload: {json.dumps(cleaned_payload, indent=2)}")
+
+    # Get the full Apollo API response with pagination metadata
+    token, is_oauth = get_apollo_access_token(tool_config)
+    headers = {
+        "Cache-Control": "no-cache",
+        "Content-Type": "application/json",
+    }
+    if is_oauth:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        headers["X-Api-Key"] = token
+
+    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)
+        if not apollo_response:
+            return {
+                "current_page": page, 
+                "per_page": per_page, 
+                "total_entries": 0, 
+                "total_pages": 0, 
+                "has_next_page": False, 
+                "results": []
+            }
+
+        # Extract pagination metadata
+        pagination = apollo_response.get("pagination", {})
+        current_page = pagination.get("page", page)
+        total_entries = pagination.get("total_entries", 0)
+        total_pages = pagination.get("total_pages", 0)
+        per_page_actual = pagination.get("per_page", per_page)
+        
+        # Determine if there are more pages
+        has_next_page = current_page < total_pages
+        
+        # Extract organizations and accounts
+        organizations = apollo_response.get("organizations", [])
+        accounts = apollo_response.get("accounts", [])
+        page_results = organizations + accounts
+
+    companies: List[Dict[str, Any]] = []
+    for company_data in page_results:
+        company_properties = fill_in_company_properties(company_data)
+        companies.append(company_properties)
+
+    logger.info(f"Converted {len(companies)} Apollo company records into standardized dictionaries (single page mode). Page {current_page} of {total_pages}")
+    
+    return {
+        "current_page": current_page,
+        "per_page": per_page_actual,
+        "total_entries": total_entries,
+        "total_pages": total_pages,
+        "has_next_page": has_next_page,
+        "next_page": current_page + 1 if has_next_page else None,
+        "results": companies
+    }