gofannon 0.25.18__py3-none-any.whl → 0.25.20__py3-none-any.whl

gofannon/config.py

@@ -15,6 +15,8 @@ class ToolConfig:
             'google_search_api_key': os.getenv('GOOGLE_SEARCH_API_KEY'),
             'google_search_engine_id': os.getenv('GOOGLE_SEARCH_ENGINE_ID'),
             'nasa_apod_api_key': os.getenv('NASA_APOD_API_KEY'),
+            'simpler_grants_api_key': os.getenv('SIMPLER_GRANTS_API_KEY'),
+            'simpler_grants_base_url': os.getenv('SIMPLER_GRANTS_BASE_URL', 'https://api.simpler.grants.gov'), #configurable as key in dev, maybe someone wants to test?
         }
 
     @classmethod

gofannon/simpler_grants_gov/base.py

@@ -0,0 +1,125 @@
+import requests
+import logging
+import json
+from typing import Optional, Dict, Any
+
+from ..base import BaseTool
+from ..config import ToolConfig
+
+logger = logging.getLogger(__name__)
+
+class SimplerGrantsGovBase(BaseTool):
+    """
+    Base class for tools interacting with the Simpler Grants Gov API.
+
+    Handles common setup like API key and base URL management, and provides
+    a helper method for making authenticated requests.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, **kwargs):
+        super().__init__(**kwargs)
+        self.api_key = api_key or ToolConfig.get("simpler_grants_api_key")
+        self.base_url = base_url or ToolConfig.get("simpler_grants_base_url")
+
+        if not self.api_key:
+            msg = "Simpler Grants Gov API key is missing. Please set SIMPLER_GRANTS_API_KEY environment variable or pass api_key argument."
+            logger.error(msg)
+            # Decide on behavior: raise error or allow initialization but fail on execution?
+            # Raising an error early is often clearer.
+            # raise ValueError(msg)
+            # Or, log and proceed, letting _make_request handle the missing key later.
+            self.logger.warning(msg + " Tool execution will likely fail.")
+
+
+        if not self.base_url:
+            msg = "Simpler Grants Gov base URL is missing. Please set SIMPLER_GRANTS_BASE_URL environment variable or pass base_url argument."
+            logger.error(msg)
+            # raise ValueError(msg)
+            self.logger.warning(msg + " Tool execution will likely fail.")
+
+        self.logger.debug(f"Initialized {self.__class__.__name__} with base_url: {self.base_url} and API key {'present' if self.api_key else 'missing'}")
+
+
+    def _make_request(self, method: str, endpoint: str, params: Optional[Dict[str, Any]] = None, json_payload: Optional[Dict[str, Any]] = None) -> str:
+        """
+        Makes an authenticated request to the Simpler Grants Gov API.
+
+        Args:
+            method: HTTP method (e.g., 'GET', 'POST').
+            endpoint: API endpoint path (e.g., '/v1/opportunities/search').
+            params: URL query parameters.
+            json_payload: JSON body for POST/PUT requests.
+
+        Returns:
+            The JSON response content as a string.
+
+        Raises:
+            requests.exceptions.RequestException: If the request fails.
+            ValueError: If API key or base URL is missing.
+        """
+        if not self.api_key:
+            raise ValueError("Simpler Grants Gov API key is missing.")
+        if not self.base_url:
+            raise ValueError("Simpler Grants Gov base URL is missing.")
+
+        full_url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
+        headers = {
+            # Based on api_key_auth.py, the API expects the key in this header
+            'X-Auth': self.api_key,
+            'Content-Type': 'application/json',
+            'accept': 'application/json'
+        }
+
+        self.logger.debug(f"Making {method} request to {full_url}")
+        self.logger.debug(f"Headers: {{'X-Auth': '***', 'Content-Type': 'application/json', 'accept': 'application/json'}}") # Don't log key
+        if params:
+            self.logger.debug(f"Params: {params}")
+        if json_payload:
+            # Be careful logging potentially large/sensitive payloads
+            log_payload = json.dumps(json_payload)[:500] # Log truncated payload
+            self.logger.debug(f"JSON Payload (truncated): {log_payload}")
+
+
+        try:
+            response = requests.request(
+                method,
+                full_url,
+                headers=headers,
+                params=params,
+                json=json_payload,
+                timeout=30 # Add a reasonable timeout
+            )
+            response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
+
+            # Check if response is empty or not JSON before trying to parse
+            content_type = response.headers.get('Content-Type', '')
+            if response.content and 'application/json' in content_type:
+                try:
+                    # Return raw text which usually includes JSON string
+                    return response.text
+                except json.JSONDecodeError as e:
+                    self.logger.error(f"Failed to decode JSON response from {full_url}. Status: {response.status_code}. Content: {response.text[:500]}... Error: {e}")
+                    # Return raw text even if not JSON, could be an error message
+                    return response.text
+            elif response.content:
+                self.logger.warning(f"Response from {full_url} is not JSON (Content-Type: {content_type}). Returning raw text.")
+                return response.text
+            else:
+                self.logger.warning(f"Received empty response from {full_url}. Status: {response.status_code}")
+                return "" # Return empty string for empty response
+
+
+        except requests.exceptions.RequestException as e:
+            self.logger.error(f"Request to {full_url} failed: {e}")
+            # Re-raise the exception to be handled by the BaseTool's execute method
+            # Or return a formatted error string
+            # return json.dumps({"error": f"API request failed: {e}"})
+            raise # Re-raise for BaseTool's error handling
+
+
+    # Subclasses must implement definition and fn
+    @property
+    def definition(self):
+        raise NotImplementedError("Subclasses must implement the 'definition' property.")
+
+    def fn(self, *args, **kwargs):
+        raise NotImplementedError("Subclasses must implement the 'fn' method.")

gofannon/simpler_grants_gov/get_opportunity.py

@@ -0,0 +1,66 @@
+import logging
+from typing import Optional
+import json
+
+from .base import SimplerGrantsGovBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class GetOpportunity(SimplerGrantsGovBase):
+    """
+    Tool to retrieve details for a specific grant opportunity by its ID.
+    Corresponds to the GET /v1/opportunities/{opportunity_id} endpoint.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "get_opportunity"):
+        super().__init__(api_key=api_key, base_url=base_url)
+        self.name = name
+
+    @property
+    def definition(self):
+        # Based on route GET /v1/opportunities/{opportunity_id} and OpportunityGetResponseV1Schema
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": "Retrieve the full details of a specific grant opportunity, including attachments, using its unique identifier.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "opportunity_id": {
+                            "type": "integer",
+                            "description": "The unique numeric identifier for the grant opportunity."
+                        }
+                    },
+                    "required": ["opportunity_id"]
+                }
+            }
+        }
+
+    def fn(self, opportunity_id: int) -> str:
+        """
+        Executes the get opportunity request.
+
+        Args:
+            opportunity_id: The ID of the opportunity to retrieve.
+
+        Returns:
+            A JSON string representing the opportunity details.
+        """
+        self.logger.info(f"Executing Simpler Grants Gov get opportunity tool for ID: {opportunity_id}")
+
+        if not isinstance(opportunity_id, int) or opportunity_id <= 0:
+            # Add validation for the ID
+            self.logger.error(f"Invalid opportunity_id provided: {opportunity_id}. Must be a positive integer.")
+            return json.dumps({"error": "Invalid opportunity_id provided. Must be a positive integer.", "success": False})
+
+        endpoint = f"/v1/opportunities/{opportunity_id}"
+        try:
+            result = self._make_request("GET", endpoint)
+            self.logger.debug(f"Get opportunity successful for ID {opportunity_id}. Response length: {len(result)}")
+            return result
+        except Exception as e:
+            self.logger.error(f"Get opportunity failed for ID {opportunity_id}: {e}", exc_info=True)
+            # Return a JSON error string
+            return json.dumps({"error": f"Get opportunity failed: {str(e)}", "success": False})

gofannon/simpler_grants_gov/list_agencies.py

@@ -0,0 +1,83 @@
+import logging
+from typing import Optional, Dict, Any
+import json
+
+from .base import SimplerGrantsGovBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class ListAgencies(SimplerGrantsGovBase):
+    """
+    Tool to retrieve a list of agencies, potentially filtered.
+    Corresponds to the POST /v1/agencies endpoint.
+    NOTE: The API uses POST for listing/filtering, not GET.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "list_agencies"):
+        super().__init__(api_key=api_key, base_url=base_url)
+        self.name = name
+
+    @property
+    def definition(self):
+        # Based on AgencyListRequestSchema
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": "Retrieve a paginated list of agencies, optionally filtered by agency ID or active status.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "filters": {
+                            "type": "object",
+                            "description": "Optional. A JSON object for filtering. Can contain 'agency_id' (UUID string) or 'active' (boolean).",
+                            "properties": {
+                                "agency_id": {"type": "string", "format": "uuid"},
+                                "active": {"type": "boolean"}
+                            }
+                        },
+                        "pagination": {
+                            "type": "object",
+                            "description": "Required. A JSON object for pagination. Must include 'page_offset', 'page_size', and 'sort_order' (array of objects with 'order_by': ['agency_code', 'agency_name', 'created_at'] and 'sort_direction': ['ascending', 'descending']).",
+                            "properties": {
+                                "page_offset": {"type": "integer", "description": "Page number (starts at 1)."},
+                                "page_size": {"type": "integer", "description": "Results per page."},
+                                "sort_order": {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "object",
+                                        "properties": {
+                                            "order_by": {"type": "string", "enum": ["agency_code", "agency_name", "created_at"]},
+                                            "sort_direction": {"type": "string", "enum": ["ascending", "descending"]}
+                                        },
+                                        "required": ["order_by", "sort_direction"]
+                                    }
+                                }
+                            },
+                            "required": ["page_offset", "page_size", "sort_order"]
+                        }
+                    },
+                    "required": ["pagination"]
+                }
+            }
+        }
+
+    def fn(self, pagination: Dict[str, Any], filters: Optional[Dict[str, Any]] = None) -> str:
+        """
+        Executes the list agencies request.
+        """
+        self.logger.info("Executing Simpler Grants Gov list agencies tool")
+        payload = {"pagination": pagination}
+        if filters:
+            payload["filters"] = filters
+
+        endpoint = "/v1/agencies"
+        try:
+            result = self._make_request("POST", endpoint, json_payload=payload)
+            self.logger.debug(f"List agencies successful. Response length: {len(result)}")
+            return result
+        except Exception as e:
+            self.logger.error(f"List agencies failed: {e}", exc_info=True)
+            return json.dumps({"error": f"List agencies failed: {str(e)}", "success": False})
+  

gofannon/simpler_grants_gov/query_by_applicant_eligibility.py

@@ -0,0 +1,114 @@
+import logging
+import json
+from typing import Optional, Dict, Any, List
+
+from .search_base import SearchOpportunitiesBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class QueryByApplicantEligibility(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities based on applicant types and/or cost-sharing requirements.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_applicant_eligibility"):
+        super().__init__(api_key=api_key, base_url=base_url, name=name)
+        self.name = name
+
+    @property
+    def definition(self):
+        base_params = self._get_common_parameter_definitions()
+        specific_params = {
+            "applicant_types": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional. List of applicant types (e.g., ['state_governments', 'nonprofits_with_501c3']). Valid values: "
+                               "city_or_township_governments, county_governments, federal_government_agencies_fed_recognized_tribes_excluded, "
+                               "independent_school_districts, individuals, native_american_tribal_governments_federally_recognized, "
+                               "native_american_tribal_organizations_other_than_federally_recognized_tribal_governments, "
+                               "nonprofits_having_a_501c3_status_with_the_irs_other_than_institutions_of_higher_education, "
+                               "nonprofits_that_do_not_have_a_501c3_status_with_the_irs_other_than_institutions_of_higher_education, "
+                               "private_institutions_of_higher_education, public_and_state_controlled_institutions_of_higher_education, "
+                               "public_housing_authorities_or_indian_housing_authorities, small_businesses, special_district_governments, state_governments, other."
+            },
+            "requires_cost_sharing": { # Parameter name is more direct for LLM
+                "type": "boolean",
+                "description": "Optional. Filter by cost-sharing requirement. True for opportunities requiring cost sharing, False for those not requiring it. Omit to not filter by this."
+            },
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within the results filtered by eligibility."
+            },
+            "query_operator": {
+                "type": "string",
+                "enum": ["AND", "OR"],
+                "description": "Operator for 'query_text' if provided (default: AND).",
+                "default": "AND"
+            }
+        }
+        all_properties = {**specific_params, **base_params}
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Search for grant opportunities by applicant types and/or cost-sharing requirements. "
+                    "At least one of 'applicant_types' or 'requires_cost_sharing' must be specified if used for filtering. "
+                    f"{self._pagination_description}"
+                    f"{self._status_filter_description}"
+                    f"{self._common_search_description_suffix}"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": all_properties,
+                    "required": [] # Logic in fn enforces condition
+                }
+            }
+        }
+
+    def fn(self,
+           applicant_types: Optional[List[str]] = None,
+           requires_cost_sharing: Optional[bool] = None,
+           query_text: Optional[str] = None,
+           query_operator: str = "AND",
+           # Common params
+           items_per_page: int = 5,
+           page_number: int = 1,
+           order_by: str = "relevancy",
+           sort_direction: str = "descending",
+           show_posted: bool = True,
+           show_forecasted: bool = False,
+           show_closed: bool = False,
+           show_archived: bool = False) -> str:
+
+        self.logger.info(f"Querying by applicant eligibility: types={applicant_types}, cost_sharing={requires_cost_sharing}, query='{query_text}'")
+
+        if applicant_types is None and requires_cost_sharing is None and not query_text: # if no specific filters or query, it's too broad
+            return json.dumps({"error": "Please provide 'applicant_types', 'requires_cost_sharing', or 'query_text' to refine the search.", "success": False})
+
+        specific_filters: Dict[str, Any] = {}
+        if applicant_types:
+            specific_filters["applicant_type"] = {"one_of": applicant_types}
+        if requires_cost_sharing is not None: # API expects list for boolean filters
+            specific_filters["is_cost_sharing"] = {"one_of": [requires_cost_sharing]}
+
+        specific_query_params: Optional[Dict[str, Any]] = None
+        if query_text:
+            specific_query_params = {"query": query_text}
+
+        payload = self._build_api_payload(
+            specific_query_params=specific_query_params,
+            specific_filters=specific_filters,
+            items_per_page=items_per_page,
+            page_number=page_number,
+            order_by=order_by,
+            sort_direction=sort_direction,
+            show_posted=show_posted,
+            show_forecasted=show_forecasted,
+            show_closed=show_closed,
+            show_archived=show_archived,
+            query_operator=query_operator
+        )
+        return self._execute_search(payload)  

gofannon/simpler_grants_gov/query_by_assistance_listing.py

@@ -0,0 +1,102 @@
+import logging
+import json
+from typing import Optional, Dict, Any, List
+
+from .search_base import SearchOpportunitiesBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class QueryByAssistanceListing(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities by Assistance Listing Numbers (formerly CFDA numbers).
+    Numbers should be in the format '##.###' or '##.##'.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_assistance_listing"):
+        super().__init__(api_key=api_key, base_url=base_url, name=name)
+        self.name = name
+
+    @property
+    def definition(self):
+        base_params = self._get_common_parameter_definitions()
+        specific_params = {
+            "assistance_listing_numbers": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of Assistance Listing Numbers (e.g., ['10.001', '93.123']). Must match pattern ##.### or ##.##."
+            },
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within the results filtered by assistance listing."
+            },
+            "query_operator": {
+                "type": "string",
+                "enum": ["AND", "OR"],
+                "description": "Operator for 'query_text' if provided (default: AND).",
+                "default": "AND"
+            }
+        }
+        all_properties = {**specific_params, **base_params}
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Search for grant opportunities by one or more Assistance Listing Numbers. "
+                    f"{self._pagination_description}"
+                    f"{self._status_filter_description}"
+                    f"{self._common_search_description_suffix}"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": all_properties,
+                    "required": ["assistance_listing_numbers"]
+                }
+            }
+        }
+
+    def fn(self,
+           assistance_listing_numbers: List[str],
+           query_text: Optional[str] = None,
+           query_operator: str = "AND",
+           # Common params
+           items_per_page: int = 5,
+           page_number: int = 1,
+           order_by: str = "relevancy",
+           sort_direction: str = "descending",
+           show_posted: bool = True,
+           show_forecasted: bool = False,
+           show_closed: bool = False,
+           show_archived: bool = False) -> str:
+
+        self.logger.info(f"Querying by Assistance Listing Numbers: {assistance_listing_numbers}, query='{query_text}'")
+
+        if not assistance_listing_numbers:
+            return json.dumps({"error": "assistance_listing_numbers list cannot be empty.", "success": False})
+            # Basic pattern validation could be added here for each number if desired,
+        # but the API will ultimately validate.
+
+        specific_filters: Dict[str, Any] = {
+            "assistance_listing_number": {"one_of": assistance_listing_numbers}
+        }
+
+        specific_query_params: Optional[Dict[str, Any]] = None
+        if query_text:
+            specific_query_params = {"query": query_text}
+
+        payload = self._build_api_payload(
+            specific_query_params=specific_query_params,
+            specific_filters=specific_filters,
+            items_per_page=items_per_page,
+            page_number=page_number,
+            order_by=order_by,
+            sort_direction=sort_direction,
+            show_posted=show_posted,
+            show_forecasted=show_forecasted,
+            show_closed=show_closed,
+            show_archived=show_archived,
+            query_operator=query_operator
+        )
+        return self._execute_search(payload)  

gofannon/simpler_grants_gov/query_by_award_criteria.py

@@ -0,0 +1,117 @@
+import logging
+import json
+from typing import Optional, Dict, Any
+
+from .search_base import SearchOpportunitiesBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class QueryByAwardCriteria(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities based on award amount criteria.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_award_criteria"):
+        super().__init__(api_key=api_key, base_url=base_url, name=name)
+        self.name = name
+
+    @property
+    def definition(self):
+        base_params = self._get_common_parameter_definitions()
+        specific_params = {
+            "min_award_floor": {"type": "integer", "description": "Optional. Minimum award floor amount."},
+            "max_award_ceiling": {"type": "integer", "description": "Optional. Maximum award ceiling amount."},
+            "min_expected_awards": {"type": "integer", "description": "Optional. Minimum number of expected awards."},
+            "max_expected_awards": {"type": "integer", "description": "Optional. Maximum number of expected awards."},
+            "min_total_funding": {"type": "integer", "description": "Optional. Minimum estimated total program funding."},
+            "max_total_funding": {"type": "integer", "description": "Optional. Maximum estimated total program funding."},
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within the results filtered by award criteria."
+            },
+            "query_operator": {
+                "type": "string",
+                "enum": ["AND", "OR"],
+                "description": "Operator for 'query_text' if provided (default: AND).",
+                "default": "AND"
+            }
+        }
+        all_properties = {**specific_params, **base_params}
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Search for grant opportunities by award criteria (floor, ceiling, number of awards, total funding). "
+                    "At least one award criterion must be specified. "
+                    f"{self._pagination_description}"
+                    f"{self._status_filter_description}"
+                    f"{self._common_search_description_suffix}"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": all_properties,
+                    "required": [] # Logic in fn enforces one award criteria
+                }
+            }
+        }
+
+    def fn(self,
+           min_award_floor: Optional[int] = None, max_award_ceiling: Optional[int] = None,
+           min_expected_awards: Optional[int] = None, max_expected_awards: Optional[int] = None,
+           min_total_funding: Optional[int] = None, max_total_funding: Optional[int] = None,
+           query_text: Optional[str] = None, query_operator: str = "AND",
+           # Common params
+           items_per_page: int = 5, page_number: int = 1, order_by: str = "relevancy",
+           sort_direction: str = "descending", show_posted: bool = True, show_forecasted: bool = False,
+           show_closed: bool = False, show_archived: bool = False) -> str:
+
+        self.logger.info(f"Querying by award criteria: floor={min_award_floor}, ceiling={max_award_ceiling}, ... query='{query_text}'")
+
+        specific_filters: Dict[str, Any] = {}
+        award_criteria_provided = False
+
+        if min_award_floor is not None:
+            specific_filters.setdefault("award_floor", {})["min"] = min_award_floor
+            award_criteria_provided = True
+        if max_award_ceiling is not None:
+            specific_filters.setdefault("award_ceiling", {})["max"] = max_award_ceiling
+            award_criteria_provided = True
+
+        expected_awards_filter = {}
+        if min_expected_awards is not None:
+            expected_awards_filter["min"] = min_expected_awards
+            award_criteria_provided = True
+        if max_expected_awards is not None:
+            expected_awards_filter["max"] = max_expected_awards
+            award_criteria_provided = True
+        if expected_awards_filter:
+            specific_filters["expected_number_of_awards"] = expected_awards_filter
+
+        total_funding_filter = {}
+        if min_total_funding is not None:
+            total_funding_filter["min"] = min_total_funding
+            award_criteria_provided = True
+        if max_total_funding is not None:
+            total_funding_filter["max"] = max_total_funding
+            award_criteria_provided = True
+        if total_funding_filter:
+            specific_filters["estimated_total_program_funding"] = total_funding_filter
+
+        if not award_criteria_provided and not query_text:
+            return json.dumps({"error": "At least one award criterion or query_text must be specified.", "success": False})
+
+        specific_query_params: Optional[Dict[str, Any]] = None
+        if query_text:
+            specific_query_params = {"query": query_text}
+
+        payload = self._build_api_payload(
+            specific_query_params=specific_query_params,
+            specific_filters=specific_filters if specific_filters else None,
+            items_per_page=items_per_page, page_number=page_number, order_by=order_by,
+            sort_direction=sort_direction, show_posted=show_posted, show_forecasted=show_forecasted,
+            show_closed=show_closed, show_archived=show_archived, query_operator=query_operator
+        )
+        return self._execute_search(payload)