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

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})  

gofannon/simpler_grants_gov/search_base.py

@@ -0,0 +1,167 @@
+import logging
+import json
+from typing import Optional, Dict, Any, List
+
+from .base import SimplerGrantsGovBase
+from ..config import FunctionRegistry # Will be used by subclasses
+
+logger = logging.getLogger(__name__)
+
+class SearchOpportunitiesBase(SimplerGrantsGovBase):
+    """
+    Base class for Simpler Grants Gov tools that search for opportunities.
+    Handles common pagination and opportunity status filtering logic.
+    """
+
+    # Common descriptions
+    _pagination_description = (
+        " Control the pagination of results. If not provided, defaults will be used by the API "
+        "(typically page 1, a small number of items, and sorted by relevance or ID)."
+    )
+    _status_filter_description = (
+        " Filter results by opportunity status. By default, only 'posted' opportunities are shown. "
+        "Set other flags to True to include them."
+    )
+    _common_search_description_suffix = (
+        " Returns a JSON string of matching opportunities."
+    )
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, name: str = "search_opportunities_base"):
+        super().__init__(api_key=api_key, base_url=base_url, name=name)
+        # 'name' will be overridden by subclasses for their specific tool name
+
+    def _get_common_parameter_definitions(self) -> Dict[str, Any]:
+        """
+        Returns a dictionary of common parameter definitions for pagination and status.
+        """
+        return {
+            "items_per_page": {
+                "type": "integer",
+                "description": "Number of results per page (e.g., 10, 25, 50). Default: 5.",
+                "default": 5
+            },
+            "page_number": {
+                "type": "integer",
+                "description": "The page number to retrieve (starts at 1). Default: 1.",
+                "default": 1
+            },
+            "order_by": {
+                "type": "string",
+                "description": "Field to sort results by (e.g., 'relevancy', 'post_date', 'opportunity_id', 'agency_code'). Default: 'relevancy'.",
+                "default": "relevancy" # API default might be opportunity_id or post_date
+            },
+            "sort_direction": {
+                "type": "string",
+                "enum": ["ascending", "descending"],
+                "description": "Direction to sort (ascending or descending). Default: 'descending'.",
+                "default": "descending"
+            },
+            "show_posted": {
+                "type": "boolean",
+                "description": "Include 'posted' opportunities. Default: True.",
+                "default": True
+            },
+            "show_forecasted": {
+                "type": "boolean",
+                "description": "Include 'forecasted' opportunities. Default: False.",
+                "default": False
+            },
+            "show_closed": {
+                "type": "boolean",
+                "description": "Include 'closed' opportunities. Default: False.",
+                "default": False
+            },
+            "show_archived": {
+                "type": "boolean",
+                "description": "Include 'archived' opportunities. Default: False.",
+                "default": False
+            }
+        }
+
+    def _build_api_payload(
+            self,
+            specific_query_params: Optional[Dict[str, Any]] = None,
+            specific_filters: Optional[Dict[str, Any]] = None,
+            # Pagination and status args from function call
+            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,
+            query_operator: str = "AND"
+    ) -> Dict[str, Any]:
+        """
+        Constructs the full payload for the /v1/opportunities/search API endpoint.
+        """
+        payload: Dict[str, Any] = {}
+
+        # 1. Pagination
+        payload["pagination"] = {
+            "page_offset": page_number,
+            "page_size": items_per_page,
+            "sort_order": [{"order_by": order_by, "sort_direction": sort_direction}]
+        }
+
+        # 2. Query and Specific Query Params
+        if specific_query_params and specific_query_params.get("query"): # Check if 'query' key actually has a value
+            payload.update(specific_query_params)
+            payload["query_operator"] = query_operator
+        elif specific_query_params: # If other specific_query_params exist without 'query'
+            payload.update(specific_query_params)
+
+
+            # 3. Filters
+        filters_dict: Dict[str, Any] = {}
+
+        # 3a. Opportunity Status Filter
+        active_statuses: List[str] = []
+        if show_posted:
+            active_statuses.append("posted")
+        if show_forecasted:
+            active_statuses.append("forecasted")
+        if show_closed:
+            active_statuses.append("closed")
+        if show_archived:
+            active_statuses.append("archived")
+
+        if active_statuses:
+            filters_dict["opportunity_status"] = {"one_of": active_statuses}
+        else:
+            self.logger.warning("No opportunity statuses selected for filtering.")
+            # Consider if an empty list should be sent or if the key should be omitted.
+            # For now, omitting if empty, as API might require at least one status if key is present.
+            # filters_dict["opportunity_status"] = {"one_of": []} # Alternative
+
+        # 3b. Specific Filters
+        if specific_filters:
+            filters_dict.update(specific_filters)
+
+        if filters_dict:
+            payload["filters"] = filters_dict
+
+        self.logger.debug(f"Constructed API payload: {json.dumps(payload, indent=2)}")
+        return payload
+
+    def _execute_search(self, payload: Dict[str, Any]) -> str:
+        """
+        Shared method to make the API call.
+        """
+        endpoint = "/v1/opportunities/search"
+        try:
+            result = self._make_request("POST", endpoint, json_payload=payload)
+            self.logger.debug(f"Search successful. Response length: {len(result)}")
+            return result
+        except Exception as e:
+            self.logger.error(f"Opportunity search failed: {e}", exc_info=True)
+            return json.dumps({"error": f"Opportunity search API request failed: {str(e)}", "success": False})
+
+            # Subclasses will implement their specific '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.")