agent-starter-pack 0.5.3__py3-none-any.whl → 0.6.1__py3-none-any.whl

agents/adk_gemini_fullstack/app/agent.py

@@ -0,0 +1,363 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import datetime
+import logging
+import os
+import re
+from collections.abc import AsyncGenerator
+from typing import Literal
+
+import google.auth
+from google.adk.agents import BaseAgent, LlmAgent, LoopAgent, SequentialAgent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.events import Event, EventActions
+from google.adk.planners import BuiltInPlanner
+from google.adk.tools import google_search
+from google.adk.tools.agent_tool import AgentTool
+from google.genai import types as genai_types
+from pydantic import BaseModel, Field
+
+from .config import config
+
+_, project_id = google.auth.default()
+os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
+os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
+os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")
+
+
+# --- 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."
+    )
+    comment: str = Field(
+        description="Detailed explanation of the evaluation, highlighting strengths and/or weaknesses of the research."
+    )
+    follow_up_queries: list[SearchQuery] | None = Field(
+        default=None,
+        description="A list of specific, targeted follow-up search queries needed to fix research gaps. This should be null or empty if the grade is 'pass'.",
+    )
+
+
+# --- 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", {})
+    id_counter = len(url_to_short_id) + 1
+    for event in session.events:
+        if not (event.grounding_metadata and event.grounding_metadata.grounding_chunks):
+            continue
+        chunks_info = {}
+        for idx, chunk in enumerate(event.grounding_metadata.grounding_chunks):
+            if not chunk.web:
+                continue
+            url = chunk.web.uri
+            title = (
+                chunk.web.title
+                if chunk.web.title != chunk.web.domain
+                else chunk.web.domain
+            )
+            if url not in url_to_short_id:
+                short_id = f"src-{id_counter}"
+                url_to_short_id[url] = short_id
+                sources[short_id] = {
+                    "short_id": short_id,
+                    "title": title,
+                    "url": url,
+                    "domain": chunk.web.domain,
+                    "supported_claims": [],
+                }
+                id_counter += 1
+            chunks_info[idx] = url_to_short_id[url]
+        if event.grounding_metadata.grounding_supports:
+            for support in event.grounding_metadata.grounding_supports:
+                confidence_scores = support.confidence_scores or []
+                chunk_indices = support.grounding_chunk_indices or []
+                for i, chunk_idx in enumerate(chunk_indices):
+                    if chunk_idx in chunks_info:
+                        short_id = chunks_info[chunk_idx]
+                        confidence = (
+                            confidence_scores[i] if i < len(confidence_scores) else 0.5
+                        )
+                        text_segment = support.segment.text if support.segment else ""
+                        sources[short_id]["supported_claims"].append(
+                            {
+                                "text_segment": text_segment,
+                                "confidence": confidence,
+                            }
+                        )
+    callback_context.state["url_to_short_id"] = url_to_short_id
+    callback_context.state["sources"] = sources
+
+
+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", {})
+
+    def tag_replacer(match: re.Match) -> str:
+        short_id = match.group(1)
+        if not (source_info := sources.get(short_id)):
+            logging.warning(f"Invalid citation tag found and removed: {match.group(0)}")
+            return ""
+        display_text = source_info.get("title", source_info.get("domain", short_id))
+        return f" [{display_text}]({source_info['url']})"
+
+    processed_report = re.sub(
+        r'<cite\s+source\s*=\s*["\']?\s*(src-\d+)\s*["\']?\s*/>',
+        tag_replacer,
+        final_report,
+    )
+    processed_report = re.sub(r"\s+([.,;:])", r"\1", processed_report)
+    callback_context.state["final_report_with_citations"] = processed_report
+    return genai_types.Content(parts=[genai_types.Part(text=processed_report)])
+
+
+# --- Custom Agent for Loop Control ---
+class EscalationChecker(BaseAgent):
+    """Checks research evaluation and escalates to stop the loop if grade is 'pass'."""
+
+    def __init__(self, name: str):
+        super().__init__(name=name)
+
+    async def _run_async_impl(
+        self, ctx: InvocationContext
+    ) -> AsyncGenerator[Event, None]:
+        evaluation_result = ctx.session.state.get("research_evaluation")
+        if evaluation_result and evaluation_result.get("grade") == "pass":
+            logging.info(
+                f"[{self.name}] Research evaluation passed. Escalating to stop loop."
+            )
+            yield Event(author=self.name, actions=EventActions(escalate=True))
+        else:
+            logging.info(
+                f"[{self.name}] Research evaluation failed or not found. Loop will continue."
+            )
+            # Yielding an event without content or actions just lets the flow continue.
+            yield Event(author=self.name)
+
+
+# --- AGENT DEFINITIONS ---
+plan_generator = LlmAgent(
+    model=config.worker_model,
+    name="plan_generator",
+    description="Generates a 4-5 line action-oriented research plan, using minimal search only for topic clarification.",
+    instruction=f"""
+    You are a research strategist. Your job is to create a high-level RESEARCH PLAN, not a summary.
+    **RULE: Your output MUST be a bulleted list of 4-5 action-oriented research goals or key questions.**
+    - A good goal starts with a verb like "Analyze," "Identify," "Investigate."
+    - A bad output is a statement of fact like "The event was in April 2024."
+    **TOOL USE IS STRICTLY LIMITED:**
+    Your goal is to create a generic, high-quality plan *without searching*.
+    Only use `google_search` if a topic is ambiguous or time-sensitive and you absolutely cannot create a plan without a key piece of identifying information.
+    You are explicitly forbidden from researching the *content* or *themes* of the topic. That is the next agent's job. Your search is only to identify the subject, not to investigate it.
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    """,
+    tools=[google_search],
+)
+
+
+section_planner = LlmAgent(
+    model=config.worker_model,
+    name="section_planner",
+    description="Breaks down the research plan into a structured markdown outline of report sections.",
+    instruction="""
+    You are an expert report architect. Using the research topic and the plan from the 'research_plan' state key, design a logical structure for the final report.
+    Your task is to create a markdown outline with 4-6 distinct sections that cover the topic comprehensively without overlap.
+    You can use any markdown format you prefer, but here's a suggested structure:
+    # Section Name
+    A brief overview of what this section covers
+    Feel free to add subsections or bullet points if needed to better organize the content.
+    Make sure your outline is clear and easy to follow.
+    Do not include a "References" or "Sources" section in your outline. Citations will be handled in-line.
+    """,
+    output_key="report_sections",
+)
+
+
+section_researcher = LlmAgent(
+    model=config.worker_model,
+    name="section_researcher",
+    description="Performs the crucial first pass of web research.",
+    planner=BuiltInPlanner(
+        thinking_config=genai_types.ThinkingConfig(include_thoughts=True)
+    ),
+    instruction="""
+    You are a diligent and exhaustive researcher. Your task is to perform the initial, broad information gathering for a report.
+    You will be provided with a list of sections in the 'report_sections' state key.
+    For each section where 'research' is marked as 'true', generate a comprehensive list of 4-5 targeted search queries to cover the topic from multiple angles.
+    Execute all of these queries using the 'google_search' tool and synthesize the results into a detailed summary for that section.
+    """,
+    tools=[google_search],
+    output_key="section_research_findings",
+    after_agent_callback=collect_research_sources_callback,
+)
+
+research_evaluator = LlmAgent(
+    model=config.critic_model,
+    name="research_evaluator",
+    description="Critically evaluates research and generates follow-up queries.",
+    instruction=f"""
+    You are a meticulous quality assurance analyst evaluating the research findings in 'section_research_findings'.
+
+    **CRITICAL RULES:**
+    1. Assume the given research topic is correct. Do not question or try to verify the subject itself.
+    2. Your ONLY job is to assess the quality, depth, and completeness of the research provided *for that topic*.
+    3. Focus on evaluating: Comprehensiveness of coverage, logical flow and organization, use of credible sources, depth of analysis, and clarity of explanations.
+    4. Do NOT fact-check or question the fundamental premise or timeline of the topic.
+    5. If suggesting follow-up queries, they should dive deeper into the existing topic, not question its validity.
+
+    Be very critical about the QUALITY of research. If you find significant gaps in depth or coverage, assign a grade of "fail",
+    write a detailed comment about what's missing, and generate 5-7 specific follow-up queries to fill those gaps.
+    If the research thoroughly covers the topic, grade "pass".
+
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    Your response must be a single, raw JSON object validating against the 'Feedback' schema.
+    """,
+    output_schema=Feedback,
+    output_key="research_evaluation",
+)
+
+enhanced_search_executor = LlmAgent(
+    model=config.worker_model,
+    name="enhanced_search_executor",
+    description="Executes follow-up searches and integrates new findings.",
+    planner=BuiltInPlanner(
+        thinking_config=genai_types.ThinkingConfig(include_thoughts=True)
+    ),
+    instruction="""
+    You are a specialist researcher executing a refinement pass.
+    You have been activated because the previous research was graded as 'fail'.
+
+    1.  Review the 'research_evaluation' state key to understand the feedback and required fixes.
+    2.  Execute EVERY query listed in 'follow_up_queries' using the 'google_search' tool.
+    3.  Synthesize the new findings and COMBINE them with the existing information in 'section_research_findings'.
+    4.  Your output MUST be the new, complete, and improved set of research findings.
+    """,
+    tools=[google_search],
+    output_key="section_research_findings",
+    after_agent_callback=collect_research_sources_callback,
+)
+
+report_composer = LlmAgent(
+    model=config.critic_model,
+    name="report_composer_with_citations",
+    include_contents="none",
+    description="Transforms research data and a markdown outline into a final, cited report.",
+    instruction="""
+    Transform the provided data into a polished, professional, and meticulously cited research report.
+
+    ---
+    ### INPUT DATA
+    *   Research Plan: `{research_plan}`
+    *   Research Findings: `{section_research_findings}`
+    *   Citation Sources: `{sources}`
+    *   Report Structure: `{report_sections}`
+
+    ---
+    ### CRITICAL: Citation System
+    To cite a source, you MUST insert a special citation tag directly after the claim it supports.
+
+    **The only correct format is:** `<cite source="src-ID_NUMBER" />`
+
+    ---
+    ### Final Instructions
+    Generate a comprehensive report using ONLY the `<cite source="src-ID_NUMBER" />` tag system for all citations.
+    The final report must strictly follow the structure provided in the **Report Structure** markdown outline.
+    Do not include a "References" or "Sources" section; all citations must be in-line.
+    """,
+    output_key="final_cited_report",
+    after_agent_callback=citation_replacement_callback,
+)
+
+research_pipeline = SequentialAgent(
+    name="research_pipeline",
+    description="Executes a pre-approved research plan. It performs iterative research, evaluation, and composes a final, cited report.",
+    sub_agents=[
+        section_planner,
+        section_researcher,
+        LoopAgent(
+            name="iterative_refinement_loop",
+            max_iterations=config.max_search_iterations,
+            sub_agents=[
+                research_evaluator,
+                EscalationChecker(name="escalation_checker"),
+                enhanced_search_executor,
+            ],
+        ),
+        report_composer,
+    ],
+)
+
+interactive_planner_agent = LlmAgent(
+    name="interactive_planner_agent",
+    model=config.worker_model,
+    description="The primary research assistant. It collaborates with the user to create a research plan, and then executes it upon approval.",
+    instruction=f"""
+    You are a research planning assistant. Your primary function is to convert ANY user request into a research plan.
+
+    **CRITICAL RULE: Never answer a question directly or refuse a request.** Your one and only first step is to use the `plan_generator` tool to propose a research plan for the user's topic.
+    If the user asks a question, you MUST immediately call `plan_generator` to create a plan to answer the question.
+
+    Your workflow is:
+    1.  **Plan:** Use `plan_generator` to create a draft plan and present it to the user.
+    2.  **Refine:** Incorporate user feedback until the plan is approved.
+    3.  **Execute:** Once the user gives EXPLICIT approval (e.g., "looks good, run it"), you MUST delegate the task to the `research_pipeline` agent, passing the approved plan.
+
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    Do not perform any research yourself. Your job is to Plan, Refine, and Delegate.
+    """,
+    sub_agents=[research_pipeline],
+    tools=[AgentTool(plan_generator)],
+    output_key="research_plan",
+)
+
+root_agent = interactive_planner_agent

src/frontends/streamlit_adk/frontend/style/app_markdown.py → agents/adk_gemini_fullstack/app/config.py

@@ -12,26 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-MARKDOWN_STR = """
-<style>
-button[kind="primary"] {
-    background: none!important;
-    border: 0;
-    padding: 20!important;
-    color: grey !important;
-    text-decoration: none;
-    cursor: pointer;
-    border: none !important;
-    # float: right;
-}
-button[kind="primary"]:hover {
-    text-decoration: none;
-    color: white !important;
-}
-button[kind="primary"]:focus {
-    outline: none !important;
-    box-shadow: none !important;
-    color:  !important;
-}
-</style>
-"""
+from dataclasses import dataclass
+
+
+@dataclass
+class ResearchConfiguration:
+    """Configuration for research-related models and parameters.
+
+    Attributes:
+        critic_model (str): Model for evaluation tasks.
+        worker_model (str): Model for working/generation tasks.
+        max_search_iterations (int): Maximum search iterations allowed.
+    """
+
+    critic_model: str = "gemini-2.5-pro"
+    worker_model: str = "gemini-2.5-flash"
+    max_search_iterations: int = 5
+
+
+config = ResearchConfiguration()