update retail-ai-location-strategy agent (#755)

Co-authored-by: Deepak Moonat <dmoonat@google.com>
Co-authored-by: Lavi Nigam <lavinigam@google.com>

Author: 3 people

.gitignore

@@ -18,6 +18,7 @@ downloads/
 eggs/
 .eggs/
 lib/
+!**/frontend/lib/
 lib64/
 parts/
 sdist/
@@ -142,6 +143,7 @@ env.bak/
 venv.bak/
 .env*
 !.env.example
+!.env.local.example
 
 # Spyder project settings
 .spyderproject

python/agents/retail-ai-location-strategy/Makefile

@@ -28,7 +28,7 @@ ag-ui-install:
 	@echo "Installing AG-UI backend dependencies..."
 	pip install -r app/frontend/backend/requirements.txt
 	@echo "Installing AG-UI frontend dependencies..."
-	cd app/frontend && npm install --legacy-peer-deps
+	cd app/frontend && npm install
 	@if [ ! -f app/frontend/.env.local ]; then \
 		cp app/frontend/.env.local.example app/frontend/.env.local; \
 		echo "Created app/frontend/.env.local from example"; \

python/agents/retail-ai-location-strategy/README.md

@@ -9,23 +9,35 @@ A multi-agent AI pipeline for retail site selection, built with [Google Agent De
     </tr>
   </thead>
   <tbody>
-    <tr>
-      <td>🏗️</td>
-      <td><strong>Production-Ready:</strong> Built with ADK for seamless deployment to <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>Multi-Agent Pipeline:</strong> 7 specialized agents for market research, competitor mapping, gap analysis, strategy recommendations, and report generation.</td>
+      <td><strong>Multi-Agent Pipeline:</strong> 7 specialized agents for market research, competitor mapping, gap analysis, strategy synthesis, and report generation.</td>
     </tr>
     <tr>
       <td>🗺️</td>
-      <td><strong>Real-World Data:</strong> Integrates Google Maps Places API for competitor mapping and live web search for market research.</td>
+      <td><strong>Real-World Data:</strong> Integrates Google Maps Places API for competitor mapping and Google Search for live market research.</td>
+    </tr>
+    <tr>
+      <td>🐍</td>
+      <td><strong>Code Execution:</strong> Python/pandas analysis for quantitative gap analysis with viability scoring.</td>
+    </tr>
+    <tr>
+      <td>🎨</td>
+      <td><strong>AI-Generated Outputs:</strong> Executive HTML reports and infographics via Gemini's native image generation.</td>
+    </tr>
+    <tr>
+      <td>🖥️</td>
+      <td><strong>AG-UI Frontend:</strong> Optional interactive dashboard with <a href="https://docs.ag-ui.com/">AG-UI Protocol</a> and <a href="https://docs.copilotkit.ai/">CopilotKit</a> for real-time pipeline visualization.</td>
+    </tr>
+    <tr>
+      <td>🏗️</td>
+      <td><strong>Production-Ready:</strong> Deploy to <a href="https://cloud.google.com/run">Cloud Run</a> or <a href="https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview">Vertex AI Agent Engine</a> via <a href="https://goo.gle/agent-starter-pack">Agent Starter Pack</a>.</td>
     </tr>
   </tbody>
 </table>
 
 <p align="center">
-  <img src="assets/images/hero-image.png" alt="Retail AI Location Strategy - Multi-Agent Pipeline" width="700">
+  <img src="assets/images/main-intro-image.png" alt="Retail AI Location Strategy - System Architecture" width="800">
 </p>
 
 ## What It Does
@@ -38,10 +50,6 @@ Given a location and business type, this pipeline automatically:
 - Generates strategic recommendations with extended reasoning
 - Produces an HTML executive report and visual infographic
 
-<p align="center">
-  <img src="assets/images/simplified-pipeline.png" alt="7-Stage Pipeline Flow" width="700">
-</p>
-
 ---
 
 ## Getting Started: From Zero to Running Agent in 5 Minutes
@@ -263,6 +271,10 @@ This starts:
 
 Open `http://localhost:3000` to see the interactive dashboard.
 
+<p align="center">
+  <img src="assets/gifs/ag-ui-demo.gif" alt="AG-UI Frontend Demo" width="700">
+</p>
+
 <details>
 <summary>Manual Setup (Alternative)</summary>
 
@@ -275,7 +287,7 @@ python main.py
 
 # Terminal 2: Start the frontend
 cd app/frontend
-npm install --legacy-peer-deps
+npm install
 cp .env.local.example .env.local
 npm run dev
 # Runs at http://localhost:3000
@@ -325,38 +337,52 @@ Each agent reads from and writes to a shared session state, enabling seamless da
 
 ```
 retail-ai-location-strategy/
-├── Makefile                 # Build and run commands
-├── pyproject.toml           # Dependencies and package config
-├── .env.example             # Environment template
-├── README.md                # This file
-├── DEVELOPER_GUIDE.md       # Detailed developer documentation
+├── Makefile                          # Build and run commands
+├── pyproject.toml                    # Dependencies and package config
+├── .env.example                      # Environment template
+├── README.md                         # This file
+├── DEVELOPER_GUIDE.md                # Detailed developer documentation
 │
-├── notebook/                # Original Gemini API notebook
+├── notebook/                         # Original Gemini API notebook
 │   └── retail_ai_location_strategy_gemini_3.ipynb
 │
-└── app/                     # Agent package (exported as root_agent)
-    ├── __init__.py          # Exports root_agent for ADK discovery
-    ├── agent.py             # SequentialAgent pipeline definition
-    ├── config.py            # Model selection and retry config
-    ├── .env                 # Environment variables (from .env.example)
+└── app/                              # Agent package (exported as root_agent)
+    ├── __init__.py                   # Exports root_agent for ADK discovery
+    ├── agent.py                      # SequentialAgent pipeline definition
+    ├── config.py                     # Model selection and retry config
+    ├── .env                          # Environment variables (from .env.example)
     │
-    ├── sub_agents/          # 7 specialized agents
-    │   ├── intake_agent.py
-    │   ├── market_research.py
-    │   ├── competitor_mapping.py
-    │   ├── gap_analysis.py
-    │   ├── strategy_advisor.py
-    │   ├── report_generator.py
-    │   └── infographic_generator.py
+    ├── sub_agents/                   # 7 specialized agents
+    │   ├── competitor_mapping/
+    │   │   ├── __init__.py
+    │   │   └── agent.py
+    │   ├── gap_analysis/
+    │   │   ├── __init__.py
+    │   │   └── agent.py
+    │   ├── infographic_generator/
+    │   │   ├── __init__.py
+    │   │   └── agent.py
+    │   ├── intake_agent/
+    │   │   ├── __init__.py
+    │   │   └── agent.py
+    │   ├── market_research/
+    │   │   ├── __init__.py
+    │   │   └── agent.py
+    │   ├── report_generator/
+    │   │   ├── __init__.py
+    │   │   └── agent.py
+    │   └── strategy_advisor/
+    │       ├── __init__.py
+    │       └── agent.py
     │
-    ├── tools/               # Custom function tools
-    │   ├── places_search.py         # Google Maps Places API
-    │   ├── html_report_generator.py # Executive report generation
-    │   └── image_generator.py       # Infographic generation
+    ├── tools/                        # Custom function tools
+    │   ├── places_search.py          # Google Maps Places API
+    │   ├── html_report_generator.py  # Executive report generation
+    │   └── image_generator.py        # Infographic generation
     │
-    ├── schemas/             # Pydantic output schemas
-    ├── callbacks/           # Pipeline lifecycle callbacks
-    └── frontend/            # AG-UI interactive dashboard (optional)
+    ├── schemas/                      # Pydantic output schemas
+    ├── callbacks/                    # Pipeline lifecycle callbacks
+    └── frontend/                     # AG-UI interactive dashboard
 ```
 
 ---

python/agents/retail-ai-location-strategy/app/agent.py

@@ -47,20 +47,22 @@
 """
 
 from google.adk.agents import SequentialAgent
+from google.adk.agents.llm_agent import Agent
+from google.adk.tools.agent_tool import AgentTool
 
-from .sub_agents import (
-    intake_agent,
-    market_research_agent,
-    competitor_mapping_agent,
-    gap_analysis_agent,
-    strategy_advisor_agent,
-    report_generator_agent,
-    infographic_generator_agent,
-)
 
+from .sub_agents.intake_agent.agent import intake_agent
+from .sub_agents.market_research.agent import market_research_agent
+from .sub_agents.competitor_mapping.agent import competitor_mapping_agent
+from .sub_agents.gap_analysis.agent import gap_analysis_agent
+from .sub_agents.strategy_advisor.agent import strategy_advisor_agent
+from .sub_agents.infographic_generator.agent import infographic_generator_agent
+from .sub_agents.report_generator.agent import report_generator_agent
 
-# Root agent orchestrating the complete location strategy pipeline
-root_agent = SequentialAgent(
+from .config import FAST_MODEL, APP_NAME
+
+# location_strategy_pipeline
+location_strategy_pipeline = SequentialAgent(
     name="LocationStrategyPipeline",
     description="""Comprehensive retail location strategy analysis pipeline.
 
@@ -72,15 +74,14 @@
 5. Professional HTML executive report
 6. Visual infographic summary
 
-To use, provide:
-- target_location: Geographic area to analyze (e.g., "Indiranagar, Bangalore")
-- business_type: Type of business (e.g., "coffee shop", "bakery", "gym")
+To use, get the following details:
+- target_location: {target_location}
+- business_type: {business_type}
 
 The analysis runs automatically through all stages and produces artifacts
 including JSON report, HTML report, and infographic image.
 """,
     sub_agents=[
-        intake_agent,               # Part 0: Parse user request
         market_research_agent,      # Part 1: Market research with search
         competitor_mapping_agent,   # Part 2A: Competitor mapping with Maps
         gap_analysis_agent,         # Part 2B: Gap analysis with code exec
@@ -90,4 +91,18 @@
     ],
 )
 
-
+# Root agent orchestrating the complete location strategy pipeline
+root_agent = Agent(
+    model=FAST_MODEL,
+    name=APP_NAME,
+    description='A strategic partner for retail businesses, guiding them to optimal physical locations that foster growth and profitability.',
+    instruction="""Your primary role is to orchestrate the retail location analysis.
+1. Start by greeting the user.
+2. Check if the `TARGET_LOCATION` (Geographic area to analyze (e.g., "Indiranagar, Bangalore")) and `BUSINESS_TYPE` (Type of business (e.g., "coffee shop", "bakery", "gym")) have been provided.
+3. If they are missing, **ask the user clarifying questions to get the required information.**
+4. Once you have the necessary details, call the `IntakeAgent` tool to process them.
+5. After the `IntakeAgent` is successful, delegate the full analysis to the `LocationStrategyPipeline`.
+Your main function is to manage this workflow conversationally.""",
+    sub_agents=[location_strategy_pipeline],
+    tools = [AgentTool(intake_agent)], # Part 0: Parse user request
+)

python/agents/retail-ai-location-strategy/app/frontend/.env.local.example

@@ -0,0 +1,2 @@
+# Backend URL - the FastAPI server running the ADK agent
+NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

python/agents/retail-ai-location-strategy/app/frontend/lib/parseCodeBlocks.ts

@@ -0,0 +1,72 @@
+/**
+ * Utility to extract code blocks from markdown content.
+ * Used primarily for parsing gap_analysis output which contains both code and results.
+ */
+
+export interface CodeBlock {
+  language: string;
+  code: string;
+}
+
+export interface ParsedContent {
+  codeBlocks: CodeBlock[];
+  textContent: string; // content with code blocks removed
+}
+
+/**
+ * Parses markdown content to extract code blocks and remaining text.
+ * Handles fenced code blocks with language specifiers (```python, ```js, etc.)
+ */
+export function parseCodeBlocks(content: string): ParsedContent {
+  if (!content) {
+    return { codeBlocks: [], textContent: "" };
+  }
+
+  const codeBlocks: CodeBlock[] = [];
+
+  // Regex to match fenced code blocks: ```language\ncode\n```
+  const codeBlockRegex = /```(\w*)\n([\s\S]*?)```/g;
+
+  let match;
+  while ((match = codeBlockRegex.exec(content)) !== null) {
+    codeBlocks.push({
+      language: match[1] || "text",
+      code: match[2].trim(),
+    });
+  }
+
+  // Remove code blocks from content to get text-only content
+  const textContent = content
+    .replace(codeBlockRegex, "")
+    .replace(/\n{3,}/g, "\n\n") // Clean up extra newlines
+    .trim();
+
+  return { codeBlocks, textContent };
+}
+
+/**
+ * Extracts just the Python code from content (for gap analysis).
+ */
+export function extractPythonCode(content: string): string {
+  const { codeBlocks } = parseCodeBlocks(content);
+
+  // Find Python code blocks
+  const pythonBlocks = codeBlocks.filter(
+    (block) => block.language.toLowerCase() === "python"
+  );
+
+  if (pythonBlocks.length > 0) {
+    return pythonBlocks.map((b) => b.code).join("\n\n");
+  }
+
+  // Fallback: return all code blocks
+  return codeBlocks.map((b) => b.code).join("\n\n");
+}
+
+/**
+ * Gets the text content without code blocks.
+ */
+export function getTextContent(content: string): string {
+  const { textContent } = parseCodeBlocks(content);
+  return textContent;
+}