fix: align prompt instructions with notebook index path prefixing

app.py

@@ -9,46 +9,62 @@ from langchain_core.prompts import ChatPromptTemplate
 from langchain_openai import ChatOpenAI
 
 # ==========================================================
-# 1. LOAD DATA & BUILD LOOKUP INDICES
+# 1. LOAD DATA & EXACT NOTEBOOK PARSING INDEX GENERATOR
 # ==========================================================
-# Hugging Face will look for this file in the root directory
 with open("gcmd_hierarchy.json", "r") as f:
     gcmd_data = json.load(f)
 
 def build_gcmd_indices(gcmd_json):
+    """
+    Parses the GCMD hierarchy exactly as done in the working notebook.
+    Omits high-level 'EARTH SCIENCE' and 'Topic' prefixes from the path string.
+    """
     topic_list = []
     sub_tree_indices = {}
+
+    # The root node level is "Category" (EARTH SCIENCE)
     topics = gcmd_json.get("children", [])
     
     for topic_node in topics:
         topic_name = topic_node.get("name", "").upper()
         topic_list.append(topic_name)
+        
+        # Collect paths inside this specific topic
         collected_paths = []
         
         def recurse_sub_tree(node, current_path=""):
             node_name = node.get("name", "")
+            # Append current node name to path
             node_path = f"{current_path} > {node_name}" if current_path else node_name
+            
+            # If it's a Variable or leaf term with text context, preserve it
             if "Variable" in node.get("level", "") or not node.get("children"):
                 definition = node.get("definition", "")
                 if definition:
                     collected_paths.append(f"{node_path} (Definition: {definition})")
                 else:
                     collected_paths.append(node_path)
+            
+            # Dig deeper into children
             for child in node.get("children", []):
                 recurse_sub_tree(child, node_path)
 
+        # Start the recursion from the children of this Topic (the 'Terms')
         for term_node in topic_node.get("children", []):
             recurse_sub_tree(term_node, current_path="")
             
+        # Format the collected paths into a clean lookup layout for the prompt
         sub_tree_indices[topic_name] = "\n".join([f"- {path}" for path in collected_paths])
+        
     return topic_list, sub_tree_indices
 
 VALID_TOPICS, SUB_TREE_LOOKUP = build_gcmd_indices(gcmd_data)
 
 # ==========================================================
-# 2. LANGGRAPH MULTI-TOPIC DEFINITION
+# 2. LANGGRAPH ASYNC MULTI-TOPIC ARCHITECTURE
 # ==========================================================
 def merge_lists(left: list, right: list) -> list:
+    """A reducer function that merges list contents across parallel branches."""
     return list(set((left or []) + (right or [])))
 
 class MultiTopicState(TypedDict):
@@ -59,32 +75,46 @@ class MultiTopicState(TypedDict):
     invalid_keywords: Annotated[List[str], merge_lists]
 
 class TopicsChoice(BaseModel):
-    topics: List[str] = Field(description="List of matching topic areas.")
+    topics: List[str] = Field(description="List of matching topic areas from the allowed dataset.")
 
-def route_multi_topic(state: MultiTopicState):
-    llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) # gpt-4o-mini keeps costs low for public demos
+async def route_multi_topic(state: MultiTopicState):
+    """Step 1: Identify ALL relevant high-level topics using async execution."""
+    llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) 
     structured_llm = llm.with_structured_output(TopicsChoice)
+    
     prompt = ChatPromptTemplate.from_messages([
-        ("system", f"You are an expert science cataloger. Identify ALL relevant major topic areas. Choose ONLY from: {', '.join(VALID_TOPICS)}"),
+        ("system", f"You are an expert science cataloger. Identify ALL relevant major topic areas that apply to this paper. Choose ONLY from the allowed list: {', '.join(VALID_TOPICS)}"),
         ("user", "Title: {title}\nAbstract: {abstract}\n\nSelect all relevant Topics.")
     ])
-    result = structured_llm.invoke(prompt.format(title=state["title"], abstract=state["abstract"]))
+    
+    result = await structured_llm.ainvoke(prompt.format(title=state["title"], abstract=state["abstract"]))
     valid_selected = [t.upper().strip() for t in result.topics if t.upper().strip() in VALID_TOPICS]
+    
     if not valid_selected:
         valid_selected = ["FALLBACK"]
     return {"chosen_topics": valid_selected}
 
 def classify_individual_topic(topic_name: str):
-    def node_runner(state: MultiTopicState):
+    """Factory generating ASYNC node runners to avoid cloud thread-thrashing."""
+    
+    async def node_runner(state: MultiTopicState):
         llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
         target_sub_tree = SUB_TREE_LOOKUP.get(topic_name, "")
+        
         prompt = ChatPromptTemplate.from_messages([
-            ("system", f"You are a specialist in {topic_name} data mapping. Extract exact keyword pathways present in the list."),
-            ("user", "Title: {title}\nAbstract: {abstract}\n\nValid Paths:\n{sub_tree}\n\nReturn exact matching entries as a comma-separated list.")
+            ("system", (
+                f"You are a specialist in {topic_name} data mapping. "
+                f"Extract exact keyword pathways present in the provided list. "
+                f"CRITICAL: Do NOT prepend '{topic_name} >' or 'EARTH SCIENCE >' to your answers. "
+                f"Your predictions must match the entries in the valid path list exactly, character-for-character."
+            )),
+            ("user", "Title: {title}\nAbstract: {abstract}\n\nValid Path List:\n{sub_tree}\n\nReturn exact matching entries as a clean, comma-separated list.")
         ])
-        response = llm.invoke(prompt.format(title=state["title"], abstract=state["abstract"], sub_tree=target_sub_tree))
+        
+        response = await llm.ainvoke(prompt.format(title=state["title"], abstract=state["abstract"], sub_tree=target_sub_tree))
         raw_keywords = [k.strip() for k in response.content.split(",") if k.strip()]
         
+        # Reconstruct the exact validator set matching your notebook layout
         valid_set = set()
         for line in target_sub_tree.split("\n"):
             if line.strip():
@@ -92,27 +122,34 @@ def classify_individual_topic(topic_name: str):
                 path = re.sub(r"\s*\(Definition:.*?\)$", "", path).strip()
                 valid_set.add(path)
                 
+        # Filter generated terms deterministically 
         valid_kws = [kw for kw in raw_keywords if kw in valid_set]
         invalid_kws = [kw for kw in raw_keywords if kw not in valid_set]
         return {"predicted_keywords": valid_kws, "invalid_keywords": invalid_kws}
+        
     return node_runner
 
 def parallel_router(state: MultiTopicState) -> List[str]:
+    """Tells LangGraph to trigger multiple sub-nodes simultaneously based on state."""
     return [f"classify_{topic.lower()}" for topic in state["chosen_topics"]]
 
-# Compile the Workflow
+# Assemble the workflow routing map
 workflow = StateGraph(MultiTopicState)
 workflow.add_node("top_router", route_multi_topic)
+
 for topic in VALID_TOPICS:
-    workflow.add_node(f"classify_{topic.lower()}", classify_individual_topic(topic))
-workflow.add_node("classify_fallback", lambda state: {"predicted_keywords": []})
+    node_id = f"classify_{topic.lower()}"
+    workflow.add_node(node_id, classify_individual_topic(topic))
 
+workflow.add_node("classify_fallback", lambda state: {"predicted_keywords": []})
 workflow.add_edge(START, "top_router")
+
 workflow.add_conditional_edges(
     "top_router",
     parallel_router,
     {f"classify_{t.lower()}": f"classify_{t.lower()}" for t in VALID_TOPICS} | {"classify_fallback": "classify_fallback"}
 )
+
 for topic in VALID_TOPICS:
     workflow.add_edge(f"classify_{topic.lower()}", END)
 workflow.add_edge("classify_fallback", END)
@@ -122,12 +159,12 @@ app = workflow.compile()
 # ==========================================================
 # 3. GRADIO USER INTERFACE FOR DEMONSTRATION
 # ==========================================================
-def run_agent_classifier(title, abstract):
+async def run_agent_classifier(title, abstract):
     if not title or not abstract:
         return "Please fill out both Title and Abstract fields.", "N/A"
         
     inputs = {"title": title, "abstract": abstract}
-    output = app.invoke(inputs)
+    output = await app.ainvoke(inputs)
     
     topics_str = ", ".join(output.get("chosen_topics", []))
     keywords_list = output.get("predicted_keywords", [])
@@ -139,7 +176,6 @@ def run_agent_classifier(title, abstract):
         
     return topics_str, keywords_str
 
-# Build out layout blocks
 demo = gr.Interface(
     fn=run_agent_classifier,
     inputs=[
@@ -153,11 +189,10 @@ demo = gr.Interface(
     title="GCMD Science Keyword Classifier Agent",
     description="Proof of Concept using LangGraph and LangChain. Routes articles concurrently across science domains and runs isolated self-validation routines.",
     examples=[
-        ["El Niño Southern Oscillation Shifting Evaporation Tracks", "Rising sea surface temperatures across equatorial waters directly trigger increased low-level cloud formation and accelerated surface winds."]
+        ["El Niño Southern Oscillation Driving Anomalous Atmospheric Evaporation", "We observe how rising sea surface temperatures across equatorial waters directly trigger increased low-level cloud formation and accelerated surface winds."]
     ]
 )
 
-# Launch configuration compatible with Hugging Face Space runtime rules
 if __name__ == "__main__":
     demo.launch()