First commit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Candid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,14 +1,13 @@
 ---
-title: Rfp Recommendations
-emoji: 😻
-colorFrom: indigo
-colorTo: indigo
+title: RFP recommendations
+short_description: Get recommendations for funding opportunities
+emoji: 🤑
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 5.6.0
+sdk_version: 5.5.0
 app_file: app.py
-pinned: false
+pinned: true
 license: mit
-short_description: Get recommendations for funding opportunities
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,108 @@
+import os
+
+import gradio as gr
+
+from common import org_search_component as oss
+from formatting import process_reasons, parse_pcs_descriptions, parse_geo_descriptions
+from services import RfpRecommend
+
+api = RfpRecommend()
+
+
+def recommend_invoke(recipient: gr.State):
+    response = api(candid_entity_id=recipient[0])
+    output = []
+    for rfp in (response.get("recommendations", []) or []):
+        output.append([
+            rfp["funder_id"],
+            rfp["funder_name"],
+            rfp["funder_address"],
+            rfp["amount"],
+            (
+                f"<a href='{rfp['application_url']}' target='_blank' rel='noopener noreferrer'>"
+                f"{rfp['application_url']}</a>"
+            ),
+            rfp["deadline"],
+            rfp["description"],
+            parse_pcs_descriptions(rfp["taxonomy"]),
+            parse_geo_descriptions(rfp["area_served"])
+        ])
+    return (
+        output,
+        process_reasons(response.get("meta", {}) or {}),
+        response.get("recommendations", [])
+    )
+
+
+def build_demo():
+    with gr.Blocks(theme=gr.themes.Soft(), title="RFP recommendations") as demo:
+        gr.Markdown(
+            """
+            <h1>RFP recommendations</h1>
+
+            <p>Receive recommendations for funding opportunities relevant to your work.</p>
+            <p>To get started lookup your nonprofit and then click **Get recommendations**.</p>
+            """
+        )
+
+        with gr.Row():
+            with gr.Column():
+                _, selected_org_state = oss.render()
+        with gr.Row():
+            recommend = gr.Button("Get recommendations", scale=5, variant="primary")
+        with gr.Row():
+            with gr.Accordion(label="Parameters used for recommendations", open=False):
+                reasons_output = gr.DataFrame(
+                    col_count=3,
+                    headers=["Reason category", "Reason value", "Reason description"],
+                    interactive=False
+                )
+
+        rec_outputs = gr.DataFrame(
+            label="Recommended RFPs",
+            type="array",
+            headers=[
+                "Funder ID", "Name", "Address",
+                "Amount", "Application URL", "Deadline",
+                "Description", "About", "Where"
+            ],
+            col_count=(9, "fixed"),
+            datatype=[
+                "number", "str", "str",
+                "str", "markdown", "date",
+                "str", "markdown", "markdown"
+            ],
+            wrap=True,
+            max_height=1000,
+            column_widths=[
+                "5%", "10%", "20%",
+                "5", "15%", "5%",
+                "10%", "10%", "20%"
+            ],
+            interactive=False
+        )
+
+        with gr.Accordion("JSON output", open=False):
+            recommendations_json = gr.JSON(label="Recommended RFPs JSON")
+
+        # pylint: disable=no-member
+        recommend.click(
+            fn=recommend_invoke,
+            inputs=[selected_org_state],
+            outputs=[rec_outputs, reasons_output, recommendations_json]
+        )
+
+    return demo
+
+
+if __name__ == '__main__':
+    app = build_demo()
+    app.queue(max_size=5).launch(
+        show_api=False,
+        auth=[
+            (os.getenv("APP_USERNAME"), os.getenv("APP_PASSWORD")),
+            (os.getenv("APP_PUBLIC_USERNAME"), os.getenv("APP_PUBLIC_PASSWORD")),
+        ],
+        auth_message="Login to Candid's letter of intent demo",
+        ssr_mode=False
+    )

common/base/api_base.py

@@ -0,0 +1,42 @@
+from typing import Dict, Optional, Any
+
+from urllib3.util.retry import Retry
+from requests.adapters import HTTPAdapter
+import requests
+
+
+class BaseAPI:
+
+    def __init__(
+        self,
+        url: str,
+        headers: Optional[Dict[str, Any]] = None,
+        total_retries: int = 3,
+        backoff_factor: int = 2
+    ) -> None:
+        total_retries = max(total_retries, 10)
+
+        adapter = HTTPAdapter(
+            max_retries=Retry(
+                total=total_retries,
+                status_forcelist=[429, 500, 502, 503, 504],
+                allowed_methods=frozenset({"HEAD", "GET", "POST", "OPTIONS"}),
+                backoff_factor=backoff_factor,
+            )
+        )
+        self.session = requests.Session()
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+        self.__url = url
+        self.__headers = headers
+
+    def get(self, **request_kwargs):
+        r = self.session.get(url=self.__url, headers=self.__headers, params=request_kwargs, timeout=30)
+        r.raise_for_status()
+        return r.json()
+
+    def post(self, payload: Dict[str, Any]):
+        r = self.session.post(url=self.__url, headers=self.__headers, json=payload, timeout=30)
+        r.raise_for_status()
+        return r.json()

common/base/api_base_async.py

@@ -0,0 +1,48 @@
+from typing import Dict, Optional, Any
+import json
+
+import aiohttp
+
+
+class BaseAsyncAPI:
+
+    def __init__(self, url: str, headers: Optional[Dict[str, Any]] = None, retries: int = 3) -> None:
+        self.__url = url
+        self.__headers = headers
+        self.__retries = max(retries, 5)
+
+    async def get(self, **request_kwargs):
+        session_timeout = aiohttp.ClientTimeout(total=30)
+        async with aiohttp.ClientSession(headers=self.__headers, timeout=session_timeout) as session:
+            output = {}
+            count = 1
+            while True:
+                if count >= self.__retries:
+                    break
+                async with session.get(url=self.__url, params=request_kwargs) as r:
+                    if r.status in {429, 500, 502, 503, 504}:
+                        count += 1
+                    elif r.status == 200:
+                        output = await r.json()
+                        break
+                    else:
+                        break
+        return output
+
+    async def post(self, payload: Dict[str, Any]):
+        session_timeout = aiohttp.ClientTimeout(total=30)
+        async with aiohttp.ClientSession(headers=self.__headers, timeout=session_timeout) as session:
+            output = {}
+            count = 1
+            while True:
+                if count >= self.__retries:
+                    break
+                async with session.post(url=self.__url, data=json.dumps(payload).encode('utf8')) as r:
+                    if r.status in {429, 500, 502, 503, 504}:
+                        count += 1
+                    elif r.status == 200:
+                        output = await r.json()
+                        break
+                    else:
+                        break
+        return output

common/base/utils.py

@@ -0,0 +1,14 @@
+import asyncio
+
+
+def async_tasks(*tasks):
+
+    async def gather(*t):
+        t = [await _ for _ in t]
+        return await asyncio.gather(*t)
+
+    loop = asyncio.new_event_loop()
+    results = loop.run_until_complete(gather(*tasks))
+    loop.stop()
+    loop.close()
+    return results

common/org_search_component.py

@@ -0,0 +1,223 @@
+from typing import List, Tuple, Optional, Any
+import os
+
+import gradio as gr
+
+try:
+    from base.api_base import BaseAPI
+except ImportError:
+    from .base.api_base import BaseAPI
+
+
+class OrgSearch(BaseAPI):
+
+    def __init__(self):
+        super().__init__(
+            url=f"{os.getenv('CDS_API_URL')}/v1/organization/search",
+            headers={"x-api-key": os.getenv('CDS_API_KEY')}
+        )
+
+    def __call__(self, name: str, **kwargs):
+        is_valid = False
+
+        payload = {
+            "names": [{
+                "value": name,
+                "type": "main"
+            }],
+            "status": "authorized"
+        }
+
+        if kwargs.get("ein"):
+            ein = kwargs.get("ein")
+            if "-" not in ein:
+                ein = f"{ein[:2]}-{ein[2:]}"
+            payload["ids"] = [{
+                "value": ein,
+                "type": "ein"
+            }]
+            is_valid = True
+
+        if kwargs.get("street") or kwargs.get("city") or kwargs.get("state") or kwargs.get("postal_code"):
+            payload["addresses"] = [{
+                "street1": kwargs.get("street") or "",
+                "city": kwargs.get("city") or "",
+                "state": kwargs.get("state") or "",
+                "postal_code": kwargs.get("postal_code") or ""
+            }]
+            is_valid = True
+
+        if not is_valid:
+            return None
+
+        result = self.post(payload=payload)
+        return result.get("payload", [])
+
+
+search_org = OrgSearch()
+
+
+def callback_to_state(event: gr.SelectData, state: gr.State) -> Tuple[List[Any], int]:
+    """Handles DataFrame `select` events. Updates the internal state for either the recipient or funder based on
+    selection. Also sends along the selected Candid entity ID to the proposal generation tab.
+
+    Parameters
+    ----------
+    event : gr.SelectData
+    state : gr.State
+
+    Returns
+    -------
+    Tuple[List[Any], int]
+        (Updated state, Candid entity ID)
+    """
+
+    row, _ = event.index
+
+    if len(state) == 0:
+        return [], None
+
+    # the state should be a nested list of lists
+    # if the state is a single list with non-list elements then we just want a pass-through
+    if all(isinstance(s, list) for s in state):
+        return state[row], state[row][0]
+    return state, state[0]
+
+
+def lookup_organization(
+    name: str,
+    ein: Optional[str] = None,
+    # street: Optional[str] = None,
+    city: Optional[str] = None,
+    state: Optional[str] = None,
+    postal: Optional[str] = None,
+) -> Tuple[List[List[str]], List[List[str]]]:
+    """Performs a simple search using the CDS organization search API. Results are sent to the DataFrame table and also
+    populate the state for the recipient information.
+
+    Parameters
+    ----------
+    name : str
+        Org name
+    ein : Optional[str], optional
+        Org EIN, by default None
+    street : Optional[str], optional
+        Street address, by default None
+    city : Optional[str], optional
+        Address city, by default None
+    state : Optional[str], optional
+        Address state, by default None
+    postal : Optional[str], optional
+        Address postal code, by default None
+
+    Returns
+    -------
+    Tuple[List[List[str]], List[List[str]]]
+        (recip data, recip data)
+
+    Raises
+    ------
+    gr.Error
+        Raised if not enough information was entered to run a search
+    gr.Error
+        Raised if no search results were returned
+    """
+
+    results = search_org(name=name, ein=ein, city=city, state=state, postal=postal)
+    if results is None:
+        raise gr.Error("You must provide a name, and either an EIN or an address.")
+    if not results:
+        raise gr.Error("No organizations could be found. Please refine the search criteria.")
+
+    data = []
+    for applicant_data in results:
+        address = applicant_data.get("addresses", [{}])[0].get("normalized")
+        seal = (applicant_data.get("current_seal", {}) or {}).get("image")
+
+        record = [
+            applicant_data.get('candid_entity_id'),
+            applicant_data.get('main_sort_name'),
+            address
+        ]
+
+        if seal:
+            record.append(f"![](file={seal})")
+        else:
+            record.append("")
+
+        data.append(record)
+    return data, data
+
+
+def render(org_id_element: Optional[gr.Blocks] = None) -> Tuple[gr.Blocks, gr.State]:
+    """Main blocks build and render function.
+
+    Parameters
+    ----------
+    org_id_element : Optional[gr.Blocks], optional
+        Callback Gradio element, by default None
+
+    Returns
+    -------
+    Tuple[gr.Blocks, gr.State]
+        (component, selected org state)
+    """
+
+    with gr.Blocks() as component:
+        org_data = gr.State([])
+        selected_org_data = gr.State([])
+
+        with gr.Row():
+            with gr.Column(scale=2):
+                name = gr.Textbox(label="Name of organization", lines=1)
+                ein = gr.Textbox(label="EIN of organization", lines=1)
+            with gr.Column(scale=3):
+                with gr.Group():
+                    with gr.Row():
+                        with gr.Column():
+                            # street = gr.Textbox(label="Street address", lines=1)
+                            city = gr.Textbox(label="City", lines=1)
+                        with gr.Column():
+                            state = gr.Textbox(label="State/province", lines=1)
+                            postal = gr.Textbox(label="Postal code", lines=1)
+
+        search_button = gr.Button("Find organization", variant="primary")
+        org_info = gr.DataFrame(
+            label="Organizations",
+            type="array",
+            headers=["Candid ID", "Name", "Address", "Seal"],
+            col_count=(4, "fixed"),
+            datatype=["number", "str", "str", "markdown"],
+            wrap=True,
+            column_widths=["20%", "30%", "30%", "20%"]
+        )
+
+        if org_id_element is None:
+            org_id_element = gr.Textbox(label="Selected Candid entity ID", lines=1)
+
+        # pylint: disable=no-member
+        search_button.click(
+            fn=lambda name, ein, city, state, postal: lookup_organization(
+                name=name,
+                ein=ein,
+                # street=street,
+                city=city,
+                state=state,
+                postal=postal
+            ),
+            # inputs=[name, ein, street, city, state, postal],
+            inputs=[name, ein, city, state, postal],
+            outputs=[org_info, org_data],
+            api_name=False,
+            show_api=False
+        )
+
+        # pylint: disable=no-member
+        org_info.select(
+            fn=callback_to_state,
+            inputs=org_data,
+            outputs=[selected_org_data, org_id_element],
+            api_name=False,
+            show_api=False
+        )
+    return component, selected_org_data

formatting.py

@@ -0,0 +1,45 @@
+from typing import List, Tuple, Dict, Any
+
+
+def process_reasons(reasons: dict) -> List[Tuple[str, str, str]]:
+    """Proprocessing for recommendation reasons data to display in a dataframe.
+
+    Parameters
+    ----------
+    reasons : dict
+
+    Returns
+    -------
+    List[Tuple[str, str, str]]
+        (attribute type, attribute code, attribute description)
+    """
+
+    output = []
+    for code, desc in (reasons.get("subject_codes", {}) or {}).items():
+        output.append(["PCS subject", code, desc])
+
+    for code, desc in (reasons.get("pop_group_codes", {}) or {}).items():
+        output.append(["PCS population", code, desc])
+
+    for code, desc in (reasons.get("geo_ids", {}) or {}).items():
+        output.append(["Geography served", code, desc])
+    return output
+
+
+def parse_pcs_descriptions(taxonomy: List[Dict[str, Any]]) -> str:
+    reasons = []
+
+    for term in taxonomy:
+        if term.get("facet") == "subject":
+            reasons.append(f"- For <b>{term.get('description')}</b>")
+        elif term.get("facet") == "population":
+            reasons.append(f"- Serving <b>{term.get('description')}</b>")
+    return '\n'.join(reasons)
+
+
+def parse_geo_descriptions(geos: List[Dict[str, Any]]) -> str:
+    reasons = []
+
+    for geo in geos:
+        reasons.append(f"- Serving <b>{geo['name']}</b>")
+    return '\n'.join(reasons)

requirements.txt

@@ -0,0 +1,4 @@
+aiohttp
+gradio
+requests
+urllib3

services.py

@@ -0,0 +1,52 @@
+import os
+
+from common.base.api_base_async import BaseAsyncAPI
+from common.base.api_base import BaseAPI
+
+
+class RfpRecommend(BaseAPI):
+
+    def __init__(self):
+        super().__init__(
+            url=os.getenv("RFP_RECOMMENDATION_URL"),
+            headers={"x-api-key": os.getenv("RFP_RECOMMENDATION_API_KEY")},
+            total_retries=5,
+            backoff_factor=10
+        )
+
+    def __call__(self, candid_entity_id: int):
+        results = self.get(candid_entity_id=candid_entity_id)
+        return results
+
+
+class Inferencing(BaseAsyncAPI):
+
+    def __init__(self):
+        super().__init__(
+            url=os.getenv("AUTOCODING_API_URL"),
+            headers={"x-api-key": os.getenv("AUTOCODING_API_KEY")}
+        )
+
+    async def __call__(self, text: str, taxonomy: str = "pcs",
+        chunk: bool = False, high_precision: bool = False
+    ):
+        result = self.post(payload={
+            "text": text,
+            "taxonomy": taxonomy,
+            "chunk": chunk,
+            "high_precision": high_precision
+        })
+        return result
+
+
+class Entities(BaseAsyncAPI):
+
+    def __init__(self):
+        super().__init__(
+            url=os.getenv("DOCUMENT_API_URL").replace("/analyze", "/entities"),
+            headers={"x-api-key": os.getenv("DOCUMENT_API_KEY")}
+        )
+
+    async def __call__(self, text: str):
+        result = self.post(payload={"text": text})
+        return result