gofannon 0.25.19__py3-none-any.whl → 0.25.21__py3-none-any.whl

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)  

gofannon/simpler_grants_gov/query_by_dates.py

@@ -0,0 +1,108 @@
+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 QueryByDates(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities based on post dates and/or close dates.
+    Dates should be in YYYY-MM-DD format.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_dates"):
+        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 = {
+            "post_start_date": {"type": "string", "description": "Optional. Start of post date range (YYYY-MM-DD)."},
+            "post_end_date": {"type": "string", "description": "Optional. End of post date range (YYYY-MM-DD)."},
+            "close_start_date": {"type": "string", "description": "Optional. Start of close date range (YYYY-MM-DD)."},
+            "close_end_date": {"type": "string", "description": "Optional. End of close date range (YYYY-MM-DD)."},
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within the results filtered by dates."
+            },
+            "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 post and/or close date ranges. "
+                    "At least one date parameter must be specified. Dates must be YYYY-MM-DD. "
+                    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 date
+                }
+            }
+        }
+
+    def fn(self,
+           post_start_date: Optional[str] = None, post_end_date: Optional[str] = None,
+           close_start_date: Optional[str] = None, close_end_date: Optional[str] = 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 dates: post={post_start_date}-{post_end_date}, close={close_start_date}-{close_end_date}, query='{query_text}'")
+
+        specific_filters: Dict[str, Any] = {}
+        date_criteria_provided = False
+
+        post_date_filter = {}
+        if post_start_date:
+            post_date_filter["start_date"] = post_start_date
+            date_criteria_provided = True
+        if post_end_date:
+            post_date_filter["end_date"] = post_end_date
+            date_criteria_provided = True
+        if post_date_filter:
+            specific_filters["post_date"] = post_date_filter
+
+        close_date_filter = {}
+        if close_start_date:
+            close_date_filter["start_date"] = close_start_date
+            date_criteria_provided = True
+        if close_end_date:
+            close_date_filter["end_date"] = close_end_date
+            date_criteria_provided = True
+        if close_date_filter:
+            specific_filters["close_date"] = close_date_filter
+
+        if not date_criteria_provided and not query_text:
+            return json.dumps({"error": "At least one date parameter 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)  

gofannon/simpler_grants_gov/query_by_funding_details.py

@@ -0,0 +1,115 @@
+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 QueryByFundingDetails(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities based on funding instruments and/or categories.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_funding_details"):
+        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 = {
+            "funding_instruments": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional. List of funding instruments (e.g., ['grant', 'cooperative_agreement']). Valid values: "
+                               "grant, cooperative_agreement, direct_payment_for_specified_use, direct_payment_with_unrestricted_use, "
+                               "direct_loan, guaranteed_or_insured_loan, insurance, other, procurement_contract."
+            },
+            "funding_categories": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional. List of funding categories (e.g., ['health', 'education']). Valid values: "
+                               "agriculture, arts, business_and_commerce, community_development, consumer_protection, disaster_prevention_and_relief, "
+                               "education, employment_labor_and_training, energy, environment, food_and_nutrition, health, housing, "
+                               "humanities, information_and_statistics, infrastructure, income_security_and_social_services, "
+                               "international_affairs, law_justice_and_legal_services, natural_resources, opportunity_zone_benefits, "
+                               "recovery_act, regional_development, science_and_technology, transportation, other."
+            },
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within the results filtered by funding details."
+            },
+            "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 funding instruments and/or categories. "
+                    "At least one of 'funding_instruments' or 'funding_categories' must be provided. "
+                    f"{self._pagination_description}"
+                    f"{self._status_filter_description}"
+                    f"{self._common_search_description_suffix}"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": all_properties,
+                    "required": [] # No single field is required, but logic in fn enforces at least one funding filter
+                }
+            }
+        }
+
+    def fn(self,
+           funding_instruments: Optional[List[str]] = None,
+           funding_categories: Optional[List[str]] = 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 funding details: instruments={funding_instruments}, categories={funding_categories}, query='{query_text}'")
+
+        if not funding_instruments and not funding_categories:
+            return json.dumps({"error": "At least one of 'funding_instruments' or 'funding_categories' must be provided.", "success": False})
+
+        specific_filters: Dict[str, Any] = {}
+        if funding_instruments:
+            specific_filters["funding_instrument"] = {"one_of": funding_instruments}
+        if funding_categories:
+            specific_filters["funding_category"] = {"one_of": funding_categories}
+
+        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)