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

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)  

gofannon/simpler_grants_gov/query_by_multiple_criteria.py

@@ -0,0 +1,134 @@
+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 QueryByMultipleCriteria(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities by combining multiple filter criteria.
+    Use this for more complex queries not covered by specialized tools.
+    All filter parameters are optional, but at least one filter or query_text should be provided.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_multiple_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()
+        # Parameters from other specific tools, all optional here
+        specific_params = {
+            "agency_codes": {
+                "type": "array", "items": {"type": "string"},
+                "description": "Optional. List of agency codes (e.g., ['USAID', 'DOC'])."
+            },
+            "funding_instruments": {
+                "type": "array", "items": {"type": "string"},
+                "description": "Optional. List of funding instruments."
+            },
+            "funding_categories": {
+                "type": "array", "items": {"type": "string"},
+                "description": "Optional. List of funding categories."
+            },
+            "applicant_types": {
+                "type": "array", "items": {"type": "string"},
+                "description": "Optional. List of applicant types."
+            },
+            "assistance_listing_numbers": {
+                "type": "array", "items": {"type": "string"},
+                "description": "Optional. List of Assistance Listing Numbers."
+            },
+            "requires_cost_sharing": {
+                "type": "boolean",
+                "description": "Optional. Filter by cost-sharing requirement."
+            },
+            # For simplicity, award criteria and dates are not individual params here.
+            # If needed, they could be added, or a user could use a more specific tool.
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within filtered results."
+            },
+            "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 grant opportunities by combining various filters like agency, funding types, applicant types, etc. "
+                    "Useful for complex queries. At least one filter criterion or query_text should be provided. "
+                    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
+                }
+            }
+        }
+
+    def fn(self,
+           agency_codes: Optional[List[str]] = None,
+           funding_instruments: Optional[List[str]] = None,
+           funding_categories: Optional[List[str]] = None,
+           applicant_types: Optional[List[str]] = None,
+           assistance_listing_numbers: 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 multiple criteria, query='{query_text}'")
+
+        specific_filters: Dict[str, Any] = {}
+        any_filter_provided = False
+
+        if agency_codes:
+            specific_filters["agency"] = {"one_of": agency_codes}
+            any_filter_provided = True
+        if funding_instruments:
+            specific_filters["funding_instrument"] = {"one_of": funding_instruments}
+            any_filter_provided = True
+        if funding_categories:
+            specific_filters["funding_category"] = {"one_of": funding_categories}
+            any_filter_provided = True
+        if applicant_types:
+            specific_filters["applicant_type"] = {"one_of": applicant_types}
+            any_filter_provided = True
+        if assistance_listing_numbers:
+            specific_filters["assistance_listing_number"] = {"one_of": assistance_listing_numbers}
+            any_filter_provided = True
+        if requires_cost_sharing is not None:
+            specific_filters["is_cost_sharing"] = {"one_of": [requires_cost_sharing]}
+            any_filter_provided = True
+
+        if not any_filter_provided and not query_text:
+            return json.dumps({"error": "At least one filter criterion or query_text must be specified for this tool.", "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_opportunities.py

@@ -0,0 +1,93 @@
+import logging
+from typing import Optional, Dict, Any
+
+from .search_base import SearchOpportunitiesBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class QueryOpportunities(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities using a general text query.
+    """
+    def __init__(self, api_key: Optional[str] = None,
+                 base_url: Optional[str] = None,
+                 name: str = "query_opportunities"):
+        super().__init__(api_key=api_key, base_url=base_url)
+        self.name = name
+
+    @property
+    def definition(self):
+        base_params = self._get_common_parameter_definitions()
+        specific_params = {
+            "query_text": {
+                "type": "string",
+                "description": "The text to search for in opportunity titles, descriptions, etc."
+            },
+            "query_operator": {
+                "type": "string",
+                "enum": ["AND", "OR"],
+                "description": "Operator for combining terms in 'query_text' (default: AND).",
+                "default": "AND"
+            }
+        }
+
+        # Combine and order parameters as desired for the definition
+        # Typically, specific parameters first, then common ones.
+        all_properties = {**specific_params, **base_params}
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Search for grant opportunities using a text query. "
+                    f"{self._pagination_description}"
+                    f"{self._status_filter_description}"
+                    f"{self._common_search_description_suffix}"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": all_properties,
+                    "required": ["query_text"] # Only query_text is strictly required for this tool
+                }
+            }
+        }
+
+    def fn(self,
+           query_text: str,
+           query_operator: str = "AND",
+           # Common params from base, with defaults
+           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:
+        """
+        Executes the general opportunity search.
+        """
+        self.logger.info(f"Executing general opportunity query: '{query_text}'")
+
+        specific_query_params = {
+            "query": query_text  # API expects "query" not "query_text"
+        }
+
+        payload = self._build_api_payload(
+            specific_query_params=specific_query_params,
+            specific_filters=None, # No other specific filters for this tool
+            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_opportunities_by_agency.py

@@ -0,0 +1,104 @@
+import logging
+from typing import Optional, Dict, Any, List
+
+from .search_base import SearchOpportunitiesBase
+from ..config import FunctionRegistry
+
+logger = logging.getLogger(__name__)
+
+@FunctionRegistry.register
+class QueryOpportunitiesByAgencyCode(SearchOpportunitiesBase):
+    """
+    Tool to search for grant opportunities filtered by agency code(s).
+    Optionally, a text query can also be provided.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "query_opportunities_by_agency"):
+        super().__init__(api_key=api_key, base_url=base_url)
+        self.name = name
+
+    @property
+    def definition(self):
+        base_params = self._get_common_parameter_definitions()
+        specific_params = {
+            "agency_codes": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "A list of agency codes to filter by (e.g., ['USAID', 'DOC'])."
+            },
+            "query_text": {
+                "type": "string",
+                "description": "Optional. Text to search for within the results filtered by agency."
+            },
+            "query_operator": {
+                "type": "string",
+                "enum": ["AND", "OR"],
+                "description": "Operator for combining terms in '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 filtered by one or more agency codes. "
+                    "An optional text query can further refine results. "
+                    f"{self._pagination_description}"
+                    f"{self._status_filter_description}"
+                    f"{self._common_search_description_suffix}"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": all_properties,
+                    "required": ["agency_codes"]
+                }
+            }
+        }
+
+    def fn(self,
+           agency_codes: List[str],
+           query_text: Optional[str] = None,
+           query_operator: str = "AND",
+           # Common params from base
+           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:
+        """
+        Executes the opportunity search filtered by agency codes.
+        """
+        self.logger.info(f"Executing opportunity query by agency codes: {agency_codes}, query_text: '{query_text}'")
+
+        if not agency_codes:
+            logger.error("agency_codes list cannot be empty.")
+            return json.dumps({"error": "agency_codes list cannot be empty.", "success": False})
+
+        specific_filters: Dict[str, Any] = {
+            "agency": {"one_of": agency_codes}
+        }
+
+        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/search_agencies.py

@@ -0,0 +1,102 @@
+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 SearchAgencies(SimplerGrantsGovBase):
+    """
+    Tool to search for agencies based on query text and filters.
+    Corresponds to the POST /v1/agencies/search endpoint.
+    """
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "search_agencies"):
+        super().__init__(api_key=api_key, base_url=base_url)
+        self.name = name
+
+    @property
+    def definition(self):
+        # Based on AgencySearchRequestSchema
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": "Search for agencies using a query string and structured filters like 'has_active_opportunity' or 'is_test_agency'.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Optional. Query string which searches against agency text fields."
+                        },
+                        "query_operator": {
+                            "type": "string",
+                            "enum": ["AND", "OR"],
+                            "description": "Optional. Operator for combining query conditions (default: OR).",
+                            "default": "OR"
+                        },
+                        "filters": {
+                            "type": "object",
+                            "description": "Optional. A JSON object for filtering. Keys can be 'has_active_opportunity' or 'is_test_agency'. Each key holds an object like {'one_of': [true/false]} specifying the filter.",
+                            "properties": {
+                                "has_active_opportunity": {
+                                    "type": "object",
+                                    "properties": {"one_of": {"type": "array", "items": {"type": "boolean"}}}
+                                },
+                                "is_test_agency": {
+                                    "type": "object",
+                                    "properties": {"one_of": {"type": "array", "items": {"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'] 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"]},
+                                            "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], query: Optional[str] = None, filters: Optional[Dict[str, Any]] = None, query_operator: str = "OR") -> str:
+        """
+        Executes the search agencies request.
+        """
+        self.logger.info("Executing Simpler Grants Gov search agencies tool")
+        payload: Dict[str, Any] = {
+            "pagination": pagination,
+            "query_operator": query_operator
+        }
+        if query:
+            payload["query"] = query
+        if filters:
+            payload["filters"] = filters
+
+        endpoint = "/v1/agencies/search"
+        try:
+            result = self._make_request("POST", endpoint, json_payload=payload)
+            self.logger.debug(f"Search agencies successful. Response length: {len(result)}")
+            return result
+        except Exception as e:
+            self.logger.error(f"Search agencies failed: {e}", exc_info=True)
+            return json.dumps({"error": f"Search agencies failed: {str(e)}", "success": False})