Update agent.py

agent.py

@@ -1,4 +1,4 @@
-"""LangGraph Agent – Solo GPT-4.1 (OpenAI)"""
+"""LangGraph Agent – Solo GPT-4.1 (OpenAI) con docstring obbligatorie."""
 
 import os
 from dotenv import load_dotenv
@@ -8,46 +8,58 @@ from langchain_openai import ChatOpenAI
 from langchain_core.messages import SystemMessage, HumanMessage
 from langchain_core.tools import tool
 
-# Tools – loaders
+# Loader & search tools
 from langchain_community.tools.tavily_search import TavilySearchResults
 from langchain_community.document_loaders import WikipediaLoader, ArxivLoader
 
 # ------------------------------------------------------------------ #
-#  Inizializzazione ambiente                                         #
+#  Ambiente                                                          #
 # ------------------------------------------------------------------ #
-load_dotenv()  # carica OPENAI_KEY dai secrets dello Space
-
+load_dotenv()  # carica OPENAI_KEY dallo Space
 OPENAI_KEY = os.getenv("OPENAI_KEY")
 if not OPENAI_KEY:
     raise ValueError("❌  OPENAI_KEY non impostata: aggiungila nei Secrets dello Space.")
 
 # ------------------------------------------------------------------ #
-#  TOOL di esempio (aritmetica)                                      #
+#  TOOL: aritmetica                                                  #
 # ------------------------------------------------------------------ #
 @tool
-def multiply(a: int, b: int) -> int: return a * b
+def multiply(a: int, b: int) -> int:
+    """Multiply two integers and return the product."""
+    return a * b
 
 @tool
-def add(a: int, b: int) -> int: return a + b
+def add(a: int, b: int) -> int:
+    """Add two integers and return the sum."""
+    return a + b
 
 @tool
-def subtract(a: int, b: int) -> int: return a - b
+def subtract(a: int, b: int) -> int:
+    """Subtract the second integer from the first and return the difference."""
+    return a - b
 
 @tool
 def divide(a: int, b: int) -> float:
+    """Divide the first integer by the second and return the quotient.
+
+    Raises:
+        ValueError: If b is zero.
+    """
     if b == 0:
         raise ValueError("Cannot divide by zero.")
     return a / b
 
 @tool
-def modulus(a: int, b: int) -> int: return a % b
+def modulus(a: int, b: int) -> int:
+    """Return the remainder of the division of a by b."""
+    return a % b
 
 # ------------------------------------------------------------------ #
 #  TOOL: Wikipedia                                                   #
 # ------------------------------------------------------------------ #
 @tool
 def wiki_search(query: str) -> str:
-    """Search Wikipedia (max 2 docs) and return formatted result."""
+    """Search Wikipedia (max 2 docs) and return formatted content."""
     docs = WikipediaLoader(query=query, load_max_docs=2).load()
     return "\n\n---\n\n".join(
         f'<Document source="{d.metadata["source"]}" page="{d.metadata.get("page","")}"/>\n'
@@ -56,11 +68,11 @@ def wiki_search(query: str) -> str:
     )
 
 # ------------------------------------------------------------------ #
-#  TOOL: Tavily                                                      #
+#  TOOL: Tavily web search                                           #
 # ------------------------------------------------------------------ #
 @tool
 def web_search(query: str) -> str:
-    """Search Tavily (max 3 docs) and return formatted result."""
+    """Perform a web search using Tavily (max 3 docs) and return formatted content."""
     docs = TavilySearchResults(max_results=3).invoke(query=query)
     return "\n\n---\n\n".join(
         f'<Document source="{d.metadata["source"]}" page="{d.metadata.get("page","")}"/>\n'
@@ -73,7 +85,7 @@ def web_search(query: str) -> str:
 # ------------------------------------------------------------------ #
 @tool
 def arxiv_search(query: str) -> str:
-    """Search ArXiv (max 3 docs) and return formatted snippet."""
+    """Search ArXiv (max 3 docs) and return the first 1000 chars of each paper."""
     docs = ArxivLoader(query=query, load_max_docs=3).load()
     return "\n\n---\n\n".join(
         f'<Document source="{d.metadata["source"]}" page="{d.metadata.get("page","")}"/>\n'
@@ -89,7 +101,7 @@ with open("system_prompt.txt", "r", encoding="utf-8") as f:
 sys_msg = SystemMessage(content=system_prompt)
 
 # ------------------------------------------------------------------ #
-#  Lista tool                                                        #
+#  Tool list                                                         #
 # ------------------------------------------------------------------ #
 tools = [
     multiply, add, subtract, divide, modulus,
@@ -97,10 +109,10 @@ tools = [
 ]
 
 # ------------------------------------------------------------------ #
-#  Costruzione graph                                                 #
+#  Build LangGraph                                                   #
 # ------------------------------------------------------------------ #
 def build_graph():
-    """Restituisce un graph LangGraph che usa solo GPT-4.1."""
+    """Return a LangGraph graph that uses only GPT-4.1 via OpenAI."""
     llm = ChatOpenAI(
         model_name="gpt-4.1",
         temperature=0,
@@ -110,10 +122,11 @@ def build_graph():
 
     # Nodes --------------------------------------------------------- #
     def prepend_system(state: MessagesState):
-        """Prepend system prompt to conversation."""
+        """Prepend system prompt to the incoming messages."""
         return {"messages": [sys_msg] + state["messages"]}
 
     def assistant(state: MessagesState):
+        """Invoke the LLM (tool calling enabled)."""
         return {"messages": [llm_with_tools.invoke(state["messages"])]}
 
     # Graph --------------------------------------------------------- #
@@ -130,12 +143,12 @@ def build_graph():
     return builder.compile()
 
 # ------------------------------------------------------------------ #
-#  Test rapido (facoltativo)                                         #
+#  Test rapido                                                       #
 # ------------------------------------------------------------------ #
 if __name__ == "__main__":
     g = build_graph()
-    q = "When was a picture of St. Thomas Aquinas first added to the Wikipedia page on the Principle of double effect?"
-    msgs = [HumanMessage(content=q)]
-    res = g.invoke({"messages": msgs})
-    for m in res["messages"]:
+    query = "When was a picture of St. Thomas Aquinas first added to the Wikipedia page on the Principle of double effect?"
+    msgs = [HumanMessage(content=query)]
+    result = g.invoke({"messages": msgs})
+    for m in result["messages"]:
         m.pretty_print()