v3 (#2)

- v3 (ff7d945817b6499040ae17cee1d8642a08c0c323)

ask_candid/base/config/constants.py

@@ -2,3 +2,16 @@ START_SYSTEM_PROMPT = (
     "You are a Candid subject matter expert on the social sector and philanthropy. "
     "You should address the user's queries and stay on topic."
 )
+
+TONE_PROMPT = (
+    "You must be cordial with the user. You should be helpful, but NEVER be sychophantic. "
+    "NEVER use extreme rhetoric such as 'perfect', 'excellent' or 'amazing'. "
+    "Be realistic, NEVER convey confidence when responding in a context with a high degree of uncertainty. "
+)
+
+FEEDBACK_PROMPT = (
+    "NEVER assume that your responses are sufficiently answering the user's inquiry. "
+    "Ask for clarification from the user if the intent is not clear. "
+    "Ask the user if responses are helpful/userful, "
+    "and if any further context is needed to hone in on a better response."
+)

ask_candid/base/config/models.py

@@ -1,9 +1,21 @@
 from types import MappingProxyType
+from enum import Enum
+
+
+class BedrockEndpoints(Enum):
+    claude_35_haiku = "us.anthropic.claude-3-5-haiku-20241022-v1:0"
+    claude_4_sonnet = "us.anthropic.claude-sonnet-4-20250514-v1:0"
+    claude_45_sonnet = "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+    llama_31_70b_instruct = "us.meta.llama3-1-70b-instruct-v1:0"
+    mistral_large = "mistral.mistral-large-2402-v1:0"
+    mixtral_8x7b = "mistral.mixtral-8x7b-instruct-v0:1"
+
 
 Name2Endpoint = MappingProxyType({
     "gpt-4o": "gpt-4o",
     "claude-3.5-haiku": "us.anthropic.claude-3-5-haiku-20241022-v1:0",
     "claude-4-sonnet": "us.anthropic.claude-sonnet-4-20250514-v1:0",
+    "claude-4.5-sonnet": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
     # "llama-3.1-70b-instruct": "us.meta.llama3-1-70b-instruct-v1:0",
     # "mistral-large": "mistral.mistral-large-2402-v1:0",
     # "mixtral-8x7B": "mistral.mixtral-8x7b-instruct-v0:1",

ask_candid/base/retrieval/sources.py

@@ -2,8 +2,11 @@ from ask_candid.base.retrieval.schemas import ElasticSourceConfig
 
 
 CandidBlogConfig = ElasticSourceConfig(
-    index_name="search-semantic-candid-blog",
-    semantic_fields=("content", "authors_text", "title_summary_tags")
+    index_name="search-semantic-blog",
+    semantic_fields=("semantic_title_summary_tags_text", "semantic_authors_text","semantic_content"),
+    text_fields=("title", "summary", "content", "authors_text"),
+    highlight_fields=("semantic_content",),
+    excluded_fields=("content",)
 )
 
 

ask_candid/chat.py

@@ -1,5 +1,5 @@
 from typing import TypedDict, Literal, Any
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
 from dataclasses import asdict
 import logging
 import json
@@ -34,11 +34,11 @@ class ToolResult(TypedDict):
     interrupts: list
 
 
-def convert_history_for_graph_agent(history: list[dict | ChatMessage]) -> list[dict]:
+def convert_history_for_graph_agent(history: Sequence[dict | ChatMessage]) -> list[dict]:
     _hist = []
     for h in history:
         if isinstance(h, ChatMessage):
-            h = asdict(h)
+            h = asdict(h)  # noqa: PLW2901
 
         if h.get("content"):
             # if h.get("metadata"):

ask_candid/services/knowledge_base.py

@@ -118,8 +118,13 @@ def generate_queries(
 
     for source_name in sources:
         if source_name == "Candid Blog":
-            q = build_sparse_vector_query(query=query, fields=S.CandidBlogConfig.semantic_fields)
-            q["_source"] = {"excludes": ["embeddings"]}
+            q = build_sparse_vector_and_text_query(
+                query=query,
+                semantic_fields=S.CandidBlogConfig.semantic_fields,
+                text_fields=S.CandidBlogConfig.text_fields,
+                highlight_fields=S.CandidBlogConfig.highlight_fields,
+                excluded_fields=S.CandidBlogConfig.excluded_fields
+            )
             q["size"] = 5
             vector_queries.extend([{"index": S.CandidBlogConfig.index_name}, q])
         elif source_name == "Candid Help":
@@ -289,7 +294,7 @@ def reranker(
                     text = '\n'.join(highlight_texts)
                 texts.append(text)
 
-    if search_text and len(texts) == len(results) and len(texts) > 1:
+    if search_text and len(texts) == len(results) and len(texts) > max_num_results:
         logger.info("Re-ranking %d retrieval results", len(results))
         scores = sparse_encoder.query_reranking(query=search_text, documents=texts)
         for r, s in zip(results, scores):
@@ -361,14 +366,13 @@ def process_hit(hit: ElasticHitsResult) -> Document:
                 "url": f"https://www.youtube.com/watch?v={hit.source['video_id']}"
             }
         )
-    elif "candid-blog" in hit.index:
+    elif "blog" in hit.index:
+        highlight = hit.highlight or {}
         doc = Document(
             page_content='\n\n'.join([
-                hit.source.get("title", ""),
-                hit.source.get("excerpt", ""),
-                get_context("content", hit, context_length=12, add_context=False),
-                get_context("authors_text", hit, context_length=12, add_context=False),
-                hit.source.get("title_summary_tags", "")
+                hit.source.get("title_summary_tags_text", ""),
+                ' '.join(highlight.get("semantic_content", [])),
+                hit.source.get("authors_text", "")
             ]),
             metadata={
                 "title": hit.source.get("title", ""),

ask_candid/tools/general.py

@@ -5,8 +5,16 @@ from langchain_core.tools import tool
 
 @tool
 def get_current_day() -> date:
-    """Get the current day to reference for any time-sensitive data requests. This might be useful for information
-    searches through news data, where more current articles may be more relevant.
+    """Get the current day to reference for any time-sensitive data requests.
+
+    ALWAYS call this tool:
+    * At the beginning of conversations involving dates or timelines
+    * Before searching news or time-sensitive data
+    * When interpreting or presenting any temporal information (recent, upcoming, last year, etc.)
+    * Before making statements about when events occurred or will occur
+
+    Never assume the correct date.
+    If data only includes partial date information, use this tool to infer missing details.
 
     Returns
     -------

ask_candid/tools/grants.py

@@ -1,3 +1,4 @@
+from typing import TypedDict, Annotated
 import logging
 
 from langchain_core.tools import tool
@@ -11,13 +12,28 @@ logger = logging.getLogger(__name__)
 logger.setLevel(logging.ERROR)
 
 
+class GrantRecord(TypedDict):
+    funder_id: Annotated[str, "Unique Candid ID value for the funder of the grant"]
+    funder_profile_link: Annotated[str, "Link to the Candid profile for the funder of the grant"]
+    funder_name: Annotated[str, "Name of the funder of the grant"]
+    recipient_id: Annotated[str, "Unique Candid ID value for the recipient of the grant"]
+    recipient_profile_link: Annotated[str, "Link to the Candid profile for the recipient of the grant"]
+    recipient_name: Annotated[str, "Name of the recipient of the grant"]
+    fiscal_year: Annotated[int | float, "Fiscal year that the grant was awarded"]
+    amount_usd: Annotated[int | float, "Dollar amount of the grant awarded in USD"]
+    description: Annotated[str, "Description of the purpose of the grant"]
+    working_on: Annotated[str, "Description of the subject purpose of the grant"]
+    serving: Annotated[str, "Description of the population groups served by the grant"]
+
+
 @tool
 def grants_search(
     query: str,
     subject_codes: str | None = None,
     populations_served_codes: str | None = None,
     geonameids_of_geographies_served: str | None = None
-) -> list[dict[str, str | int | float | None]] | str:
+# ) -> list[dict[str, str | int | float | None]] | str:
+) -> list[GrantRecord] | str:
     """Search for historical grants to find context about what is happening in the sector, and what organizations are
     involved with. This is intended for historial research purposes and contextualization. If trying to recommend
     funders then please use the dedicated funder recommendation tool instead of this. Funder recommendations uses grants
@@ -62,7 +78,7 @@ def grants_search(
 
     Returns
     -------
-    list[dict[str, str | int | float | None]] | str
+    list[GrantRecord] | str
         Array of relevant grants and information about the organizations involved
         If output is a string then that means there was some error, and retry should be considered
     """
@@ -97,17 +113,34 @@ def grants_search(
             elif facet == "population":
                 serving.extend([code["name"].lower() for code in data["value"]])
 
-        output.append({
-            "funder_id": grant["grantmakerId"],
-            "funder_profile_link": format_candid_profile_link(grant["grantmakerId"]),
-            "funder_name": grant["grantmakerName"],
-            "recipient_id": grant["recipientId"],
-            "recipient_profile_link": format_candid_profile_link(grant["recipientId"]),
-            "recipient_name": grant["recipientName"],
-            "fiscal_year": grant["fiscalYear"],
-            "amound_usd": grant["amountUsd"],
-            "description": grant["text"],
-            "working_on": f"Working on {', '.join(working_on)}",
-            "serving": f"Serving population groups {', '.join(serving)}",
-        })
+        # output.append({
+        #     "funder_id": grant["grantmakerId"],
+        #     "funder_profile_link": format_candid_profile_link(grant["grantmakerId"]),
+        #     "funder_name": grant["grantmakerName"],
+        #     "recipient_id": grant["recipientId"],
+        #     "recipient_profile_link": format_candid_profile_link(grant["recipientId"]),
+        #     "recipient_name": grant["recipientName"],
+        #     "fiscal_year": grant["fiscalYear"],
+        #     "amound_usd": grant["amountUsd"],
+        #     "description": grant["text"],
+        #     "working_on": f"Working on {', '.join(working_on)}",
+        #     "serving": f"Serving population groups {', '.join(serving)}",
+        # })
+
+        output.append(GrantRecord(
+            funder_id=grant["grantmakerId"],
+            funder_profile_link=format_candid_profile_link(grant["grantmakerId"]),
+            funder_name=grant["grantmakerName"],
+            recipient_id=grant["recipientId"],
+            recipient_profile_link=format_candid_profile_link(grant["recipientId"]),
+            recipient_name=grant["recipientName"],
+            fiscal_year=grant["fiscalYear"],
+            amount_usd=grant["amountUsd"],
+            description=grant["text"],
+            working_on=f"Working on {', '.join(working_on)}",
+            serving=f"Serving population groups {', '.join(serving)}"
+        ))
+
+    if not output:
+        return "No grants were found, try a different search strategy."
     return output

ask_candid/tools/org_search.py

@@ -20,12 +20,13 @@ class OrganizationNames(BaseModel):
 
 
 class OrganizationIdentifierArgs(BaseModel):
+    """Input arguments for the organization identifier tool"""
     text: str = Field(..., description="Chat model response text which contains named organizations.")
 
 
 class OrganizationIdentifier(BaseTool):
     llm: BaseChatModel
-    parser: type[PydanticOutputParser] = PydanticOutputParser(pydantic_object=OrganizationNames)
+    parser: PydanticOutputParser = PydanticOutputParser(pydantic_object=OrganizationNames)
     template: str = """Extract only the names of officially recognized organizations, foundations, and government
     entities from the text below. Do not include any entries that contain descriptions, regional identifiers, or
     explanations within parentheses or following the name. Strictly exclude databases, resources, crowdfunding
@@ -35,11 +36,19 @@ class OrganizationIdentifier(BaseTool):
     output format: ```{format_instructions}```
     """
 
-    name: str = "organization-identifier"
+    name: str = "organization_identifier"
     description: str = """
     Identify the names of nonprofits and foundations from chat model responses. If it is likely that a response contains
     proper names then it should be processed through this tool.
 
+    Some tools have outputs with organizations already identified by Candid's data. These include:
+        * grant search
+        * organization search
+        * funder recommendations
+        * RFP recommendations
+
+    If these tools are invoked then use the IDs and profile URLs provided in their outputs, and DO NOT use this tool.
+
     Examples
     --------
     >>> `organization_identifier('My Favorite Foundation awarded a grant to My Favorite Nonprofit.')`
@@ -55,12 +64,12 @@ class OrganizationIdentifier(BaseTool):
         )
         return RunnableSequence(prompt, self.llm, self.parser)
 
-    def _run(self, text: str) -> str:
+    def _run(self, text: str) -> list[str]:
         chain = self._build_pipeline()
         result: OrganizationNames = chain.invoke({"chatbot_output": text})
         return result.orgnames
 
-    async def _arun(self, text: str) -> str:
+    async def _arun(self, text: str) -> list[str]:
         chain = self._build_pipeline()
         result: OrganizationNames = await chain.ainvoke({"chatbot_output": text})
         return result.orgnames

ask_candid/tools/recommendations.py

@@ -1,4 +1,4 @@
-from typing import Literal, Any
+from typing import TypedDict, Literal, Annotated, Any
 import logging
 
 from langchain_core.tools import tool
@@ -13,6 +13,24 @@ logger = logging.getLogger(__name__)
 logger.setLevel(logging.ERROR)
 
 
+class OrganizationRecord(TypedDict):
+    nonprofit_id: Annotated[str, "Unique Candid ID value for the organization"]
+    name: Annotated[str, "Name of the organization"]
+    aka_name: Annotated[str, "'Also-known-as' name of the organization"]
+    acronym: Annotated[str, "Acronym of the name of the organization"]
+    city: Annotated[str, "City that the organization is located in"]
+    admin1: Annotated[str, "State, province, or canton that the organization is located in"]
+    country: Annotated[str, "Country that the organization is located in"]
+    ein: Annotated[str, "IRS employer identification number (EIN) of the organization, only relevant for US-based orgs"]
+    profile_link: Annotated[str, "Link to the Candid profile for the organization"]
+    working_on: Annotated[str, "Description of the subject purpose of the organization"]
+    serving: Annotated[str, "Description of the population groups served by the organization"]
+    transparency_level: Annotated[str, "Candid Seal level of the organization indicating transparency level"]
+    organization_roles: Annotated[str, "Roles of the organization (eg. grantmaker, recipient)"]
+    grants_awarded: Annotated[str, "Summary stats of the grants awarded by the organization"]
+    grants_received: Annotated[str, "Summary stats of the grants received by the organization"]
+
+
 @retry_on_status(num_retries=3)
 def get_with_retries(url: str, payload: dict[str, Any] | None, headers: dict[str, str] | None) -> httpx.Response:
     with httpx.Client(transport=httpx.HTTPTransport(retries=3), timeout=30) as client:
@@ -25,7 +43,7 @@ def organization_search(
     located_postal_code: str | None = None,
     located_admin1: str | None = None,
     search_mode: Literal["organization_only", "organization_and_grants"] | None = "organization_only"
-) -> list[dict[str, str | None]] | str:
+) -> list[OrganizationRecord] | str:
     """Search for organizations by name, description or work, program descriptions and locations. Here are some
     guidelines:
     * `query` controls hybrid searching involving both vector search and keyword search
@@ -54,7 +72,7 @@ def organization_search(
 
     Returns
     -------
-    list[dict[str, str]] | str
+    list[OrganizationRecord] | str
         List of the top organization search results
         If output is a string then that means there was some error, and retry should be considered
     """
@@ -90,23 +108,40 @@ def organization_search(
             elif code.startswith('S'):
                 working_on.append(description.lower())
 
-        output.append({
-            "nonprofit_id": org["candidEntityID"],
-            "name": org["orgName"],
-            "aka_name": org["akaName"],
-            "acronym": org["acronymName"],
-            "city": org["city"],
-            "admin1": org["admin1"],
-            "country": org["countryName"],
-            "EIN": org["ein"],
-            "profile_link": format_candid_profile_link(org['candidEntityID']),
-            "working_on": f"Working on {', '.join(working_on)}",
-            "serving": f"Serving population groups {', '.join(serving)}",
-            "transparency_level": org["seal"].get("description"),
-            "organization_roles": ', '.join(org["roles"]),
-            "grants_awarded": ', '.join([f"{k}: {v}" for k, v in org["transactionsGiven"].items()]),
-            "grants_received": ', '.join([f"{k}: {v}" for k, v in org["transactionsReceived"].items()])
-        })
+        # output.append({
+        #     "nonprofit_id": org["candidEntityID"],
+        #     "name": org["orgName"],
+        #     "aka_name": org["akaName"],
+        #     "acronym": org["acronymName"],
+        #     "city": org["city"],
+        #     "admin1": org["admin1"],
+        #     "country": org["countryName"],
+        #     "EIN": org["ein"],
+        #     "profile_link": format_candid_profile_link(org['candidEntityID']),
+        #     "working_on": f"Working on {', '.join(working_on)}",
+        #     "serving": f"Serving population groups {', '.join(serving)}",
+        #     "transparency_level": org["seal"].get("description"),
+        #     "organization_roles": ', '.join(org["roles"]),
+        #     "grants_awarded": ', '.join([f"{k}: {v}" for k, v in org["transactionsGiven"].items()]),
+        #     "grants_received": ', '.join([f"{k}: {v}" for k, v in org["transactionsReceived"].items()])
+        # })
+        output.append(OrganizationRecord(
+            nonprofit_id=org["candidEntityID"],
+            name=org["orgName"],
+            aka_name=org["akaName"],
+            acronym=org["acronymName"],
+            city=org["city"],
+            admin1=org["admin1"],
+            country=org["countryName"],
+            ein=org["ein"],
+            profile_link=format_candid_profile_link(org['candidEntityID']),
+            working_on=f"Working on {', '.join(working_on)}",
+            serving=f"Serving population groups {', '.join(serving)}",
+            transparency_level=org["seal"].get("description"),
+            organization_roles=', '.join(org["roles"]),
+            grants_awarded=', '.join([f"{k}: {v}" for k, v in org["transactionsGiven"].items()]),
+            grants_received=', '.join([f"{k}: {v}" for k, v in org["transactionsReceived"].items()])
+        ))
     return output
 
 
@@ -201,7 +236,7 @@ def recommend_funders(
         data.get("meta") or {},
         [{
             **r,
-            "candid_profile_url": format_candid_profile_link(r['funder_id'])
+            "profile_link": format_candid_profile_link(r['funder_id'])
         } for r in (data.get("recommendations") or [])]
     )
 
@@ -282,6 +317,6 @@ def recommend_funding_opportunities(
         data.get("meta") or {},
         [{
             **r,
-            "candid_profile_url": format_candid_profile_link(r['funder_id'])
+            "profile_link": format_candid_profile_link(r['funder_id'])
         } for r in (data.get("recommendations") or [])]
     )

ask_candid/utils.py

@@ -1,5 +1,4 @@
 from typing import Any
-from uuid import uuid4
 
 from langchain_core.documents import Document
 
@@ -51,13 +50,3 @@ def format_chat_ag_response(chatbot: list[Any]) -> list[Any]:
             chatbot.pop(-1)
             chatbot[-1]["content"] = chatbot[-1]["content"] + sources
     return chatbot
-
-
-def valid_inputs(*args) -> bool:
-    return any(a is not None or (isinstance(a, str) and a.strip() != '') for a in args)
-
-
-def get_session_id(thread_id: str | None) -> str:
-    if not thread_id:
-        thread_id = uuid4().hex
-    return thread_id

chat_v2.py

@@ -14,7 +14,7 @@ from ask_candid.tools.search import search_candid_knowledge_base
 from ask_candid.tools.general import get_current_day
 from ask_candid.utils import html_format_docs_chat
 from ask_candid.base.config.constants import START_SYSTEM_PROMPT
-from ask_candid.base.config.models import Name2Endpoint
+from ask_candid.base.config.models import BedrockEndpoints
 from ask_candid.chat import convert_history_for_graph_agent, format_tool_call, format_tool_response
 
 try:
@@ -40,7 +40,7 @@ class LoggedComponents(TypedDict):
 def build_execution_graph() -> CompiledStateGraph:
     llm = ChatBedrock(
         client=boto3.client("bedrock-runtime", region_name="us-east-1"),
-        model=Name2Endpoint["claude-3.5-haiku"]
+        model=BedrockEndpoints.claude_35_haiku.value
     )
     org_name_recognition = OrganizationIdentifier(llm=llm) # bind the main chat model to the tool
     return create_react_agent(
@@ -82,14 +82,14 @@ async def execute(
         if fname.endswith('.txt'):
             with open(fname, 'r', encoding='utf8') as f:
                 history.append(gr.ChatMessage(role="user", content=f.read()))
-    yield gr.MultimodalTextbox(value=None, interactive=True), history
 
     horizon = len(history)
-    inputs = {"messages": convert_history_for_graph_agent(history)}
+    history.append(gr.ChatMessage(role="assistant", content=""))
+    yield gr.MultimodalTextbox(value=None, interactive=True), history
 
+    inputs = {"messages": convert_history_for_graph_agent(history)}
     graph = build_execution_graph()
 
-    history.append(gr.ChatMessage(role="assistant", content=""))
     async for stream_mode, chunk in graph.astream(inputs, stream_mode=["messages", "tasks"]):
         if stream_mode == "messages" and chunk[0].content:
             for msg in chunk[0].content:
@@ -165,7 +165,7 @@ def build_chat_app():
                     None,  # user
                     BOT_LOGO,  # bot
                 ),
-                height="50vh",
+                height="60vh",
                 type="messages",
                 show_label=False,
                 show_copy_button=True,