Feat add docstrings gemini fullstack (#200)

* feat: add docstring gemini fullstack, replace diagram

* feat: add docstring gemini fullstack, replace diagram

* feat: add docstring gemini fullstack, replace diagram

Author: eliasecchig

Makefile

@@ -13,7 +13,7 @@ generate-lock:
 lint:
 	uv run ruff check . --config pyproject.toml --diff
 	uv run ruff format . --check  --config pyproject.toml --diff
-	uv run mypy --config-file pyproject.toml ./agents ./src/cli ./tests ./src/frontends/streamlit ./src/frontends/streamlit_adk
+	uv run mypy --config-file pyproject.toml ./agents ./src/cli ./tests ./src/frontends/streamlit
 
 lint-templated-agents:
 	uv run tests/integration/test_template_linting.py

agents/adk_gemini_fullstack/README.md

@@ -2,32 +2,29 @@
 
 The **Gemini Fullstack Agent Development Kit (ADK) Quickstart** is a production-ready blueprint for building a sophisticated, fullstack research agent with Gemini. It's built to demonstrate how the ADK helps structure complex agentic workflows, build modular agents, and incorporate critical Human-in-the-Loop (HITL) steps.
 
-<div style="display: flex; align-items: center; justify-content: space-between;">
-  <table style="width: 50%;">
-    <thead>
-      <tr>
-        <th colspan="2">Key Features</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>🏗️</td>
-        <td><strong>Fullstack & Production-Ready:</strong> A complete React frontend and ADK-powered FastAPI backend, with deployment options for <a href="https://cloud.google.com/run">Google Cloud Run</a> and <a href="https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview">Vertex AI Agent Engine</a>.</td>
-      </tr>
-      <tr>
-        <td>🧠</td>
-        <td><strong>Advanced Agentic Workflow:</strong> The agent uses Gemini to <strong>strategize</strong> a multi-step plan, <strong>reflect</strong> on findings to identify gaps, and <strong>synthesize</strong> a final, comprehensive report.</td>
-      </tr>
-      <tr>
-        <td>🔄</td>
-        <td><strong>Iterative & Human-in-the-Loop Research:</strong> Involves the user for plan approval, then autonomously loops through searching (via Gemini function calling) and refining its results until it has gathered sufficient information.</td>
-      </tr>
-    </tbody>
-  </table>
-  <div style="width: 45%;">
-    <img src="../../docs/images/adk_gemini_fullstack_preview.png" width="100%" alt="Gemini Fullstack ADK Preview">
-  </div>
-</div>
+<table>
+  <thead>
+    <tr>
+      <th colspan="2">Key Features</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>🏗️</td>
+      <td><strong>Fullstack & Production-Ready:</strong> A complete React frontend and ADK-powered FastAPI backend, with deployment options for <a href="https://cloud.google.com/run">Google Cloud Run</a> and <a href="https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview">Vertex AI Agent Engine</a>.</td>
+    </tr>
+    <tr>
+      <td>🧠</td>
+      <td><strong>Advanced Agentic Workflow:</strong> The agent uses Gemini to <strong>strategize</strong> a multi-step plan, <strong>reflect</strong> on findings to identify gaps, and <strong>synthesize</strong> a final, comprehensive report.</td>
+    </tr>
+    <tr>
+      <td>🔄</td>
+      <td><strong>Iterative & Human-in-the-Loop Research:</strong> Involves the user for plan approval, then autonomously loops through searching (via Gemini function calling) and refining its results until it has gathered sufficient information.</td>
+    </tr>
+  </tbody>
+</table>
+
+<img src="../../docs/images/adk_gemini_fullstack_preview.png" alt="Gemini Fullstack ADK Preview">
 
 This project adapts concepts from the [Gemini FullStack LangGraph Quickstart](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart) for the frontend app. 
 

agents/adk_gemini_fullstack/app/agent.py

@@ -26,12 +26,16 @@
 
 # --- Structured Output Models ---
 class SearchQuery(BaseModel):
+    """Model representing a specific search query for web search."""
+
     search_query: str = Field(
         description="A highly specific and targeted query for web search."
     )
 
 
 class Feedback(BaseModel):
+    """Model for providing evaluation feedback on research quality."""
+
     grade: Literal["pass", "fail"] = Field(
         description="Evaluation result. 'pass' if the research is sufficient, 'fail' if it needs revision."
     )
@@ -46,6 +50,17 @@ class Feedback(BaseModel):
 
 # --- Callbacks ---
 def collect_research_sources_callback(callback_context: CallbackContext) -> None:
+    """Collects and organizes web-based research sources and their supported claims from agent events.
+
+    This function processes the agent's `session.events` to extract web source details (URLs,
+    titles, domains from `grounding_chunks`) and associated text segments with confidence scores
+    (from `grounding_supports`). The aggregated source information and a mapping of URLs to short
+    IDs are cumulatively stored in `callback_context.state`.
+
+    Args:
+        callback_context (CallbackContext): The context object providing access to the agent's
+            session events and persistent state.
+    """
     session = callback_context._invocation_context.session
     url_to_short_id = callback_context.state.get("url_to_short_id", {})
     sources = callback_context.state.get("sources", {})
@@ -99,6 +114,18 @@ def collect_research_sources_callback(callback_context: CallbackContext) -> None
 def citation_replacement_callback(
     callback_context: CallbackContext,
 ) -> genai_types.Content:
+    """Replaces citation tags in a report with Markdown-formatted links.
+
+    Processes 'final_cited_report' from context state, converting tags like
+    `<cite source="src-N"/>` into hyperlinks using source information from
+    `callback_context.state["sources"]`. Also fixes spacing around punctuation.
+
+    Args:
+        callback_context (CallbackContext): Contains the report and source information.
+
+    Returns:
+        genai_types.Content: The processed report with Markdown citation links.
+    """
     final_report = callback_context.state.get("final_cited_report", "")
     sources = callback_context.state.get("sources", {})
 

docs/images/adk_gemini_fullstack_architecture.png

@@ -72,7 +72,7 @@ log_cli_date_format = "%Y-%m-%d %H:%M:%S"
 [tool.ruff]
 line-length = 88
 target-version = "py310"
-include = ["./agents/**/*.py", "src/cli/**/*.py", "tests/**/*.py", "src/frontends/streamlit/**/*.py", "src/frontends/streamlit_adk/**/*.py"]
+include = ["./agents/**/*.py", "src/cli/**/*.py", "tests/**/*.py", "src/frontends/streamlit/**/*.py"]
 exclude = ["./agents/agentic_rag/**/*.py"]
 
 [tool.ruff.lint]