DEV Community: Hastimal Jangid

From Search to Care: Applying Gemini Search Journeys to Healthcare Discovery

Hastimal Jangid — Sat, 10 Oct 2026 07:26:01 +0000

Across this series, I started with a simple question:

How does a user query become a grounded decision?

That took the project through query fan-out, retrieval, ranking, AI visibility, agents, OpenTelemetry, and AgentOps.

For the final part, I wanted to apply the same design ideas to a domain where evidence boundaries matter much more: healthcare discovery.

The goal is not to build an AI doctor.

The goal is narrower:

Can an AI-assisted search journey help someone discover appropriate healthcare providers while making the supporting evidence, limitations, and source provenance visible?

For this experiment, I used pediatric dental discovery as the example.

A parent might ask:

Find three pediatric dentists in Houston for a child who is scared of going to the dentist. Compare them using trustworthy sources, provider credentials, services, and location, and explain why you selected each one.

That sounds like a local-search problem.

But healthcare changes the architecture.

Step 1: The query needs more than location

For a coffee-shop search, the system might extract:

location
group size
opening hours
quiet/work preference

For healthcare discovery, the same query can contain several different information needs:

specialty
location
patient need
provider discovery
credential context
clinical evidence
care-related constraints

So the first step is still intent understanding and query fan-out — but the search plan becomes more deliberate.

For the pediatric-dentist example, the search planner can generate queries for:

Provider discovery
Dental-anxiety experience
Professional directory discovery
State licensing sources
Biomedical evidence on behavior guidance
Biomedical evidence in sedation / nitrous oxide
FHIR interoperability context

The healthcare platform represents these as a structured SearchPlan rather than treating the entire request as one search string.

This is the same idea I used earlier in the AI Search Journey Lab:

one user question does not necessarily equal one retrieval query.

Step 2: Different questions need different sources

This is where healthcare becomes more interesting.

A single retrieval source is not enough.

For this workflow, I separate the evidence paths.

Provider discovery
      ↓
NPPES

Biomedical evidence
      ↓
PubMed

Interoperability exploration
      ↓
FHIR R4

The healthcare platform uses Google ADK with an MCP-based retrieval layer to route provider and research queries to the appropriate sources.

The important point is that these sources do different jobs.
NPPES can provide structured provider information.

PubMed can provide biomedical literature.

FHIR can represent standardized relationships between practitioners, specialties, organizations, and locations.

I do not want to mix those evidence types and pretend they prove the same thing.

Step 3: Discovery is not verification

This became one of the most important healthcare rules in the project.

Generating a query such as:

Texas State Board of Dental Examiners dentist license verification

does not mean a provider's license has been verified.

Similarly:

AAPD find a pediatric dentist Houston TX

does not mean professional membership or board status has been confirmed.

The search-planning instructions explicitly preserve that distinction: identifying an authoritative source is not the same as retrieving and validating evidence from it.

That leads to a simple rule I use throughout the healthcare work:

No evidence → no claim.

Step 4: Let agents plan, but keep evidence deterministic

The healthcare architecture uses three core agents.

User Healthcare Question
          ↓
Search Planner Agent
          ↓
SearchPlan
          ↓
Healthcare Research Agent
          ↓
MCP Retrieval
          ↓
Evidence
          ↓
Grounded Answer

The broader platform uses Gemini or Gemma for reasoning while keeping the Google ADK workflow and deterministic evidence boundaries intact.

This separation matters.

I am comfortable letting a model:

interpret the question
create retrieval plans
select tools
summarize evidence

I do not want the model to manufacture:

provider credentials
services
citation IDs
verification claims
unsupported healthcare facts

For example, citation references are validated against the actual selected evidence, and invalid citation IDs are rejected.

That makes the system less magical, but much more inspectable.

Step 5: The answer should expose its boundaries

Healthcare search should not sound more certain than the evidence allows.

A useful result should distinguish:

What was found
What was supported
What still needs verification

For example, the system may find a provider through NPPES and biomedical evidence about pediatric dental anxiety through PubMed.

That does not automatically prove that the specific provider:

offers sedation
accepts a particular insurance plan
has a particular appointment available
has specialized expertise in a specific anxiety-management technique

Those require their own evidence.

This is the healthcare version of a principle that appeared throughout the AI Search Journey Lab:

Make the evidence boundary visible.

Step 6: Provider discovery and medical advice are different

I also wanted a very clear product boundary.

This workflow supports healthcare discovery.

It is not intended to diagnose a patient or prescribe treatment.

There is a significant difference between:

Find pediatric dentists near Houston and show me the evidence you used.

and:

Tell me which medical treatment my child should receive.

The first is primarily a discovery and evidence-retrieval problem.
The second can become clinical decision-making.

I keep those two problems separate.

The system can retrieve research about dental anxiety and behavior guidance to provide context, but that evidence should not be transformed into individualized medical advice.

Step 7: Run the same journey as an inspectable workflow

What I like about applying the search-journey architecture to healthcare is that the journey remains inspectable.

Instead of:

Question
   ↓
LLM
   ↓
Answer

I can inspect:

Question
   ↓
Intent
   ↓
Search Plan
   ↓
Generated Queries
   ↓
Sources Used
   ↓
Retrieved Records
   ↓
Evidence Selection
   ↓
Ranking
   ↓
Citations
   ↓
Answer

That is far more useful for healthcare than a confident paragraph with invisible provenance.

What changed when I moved from search to care

The basic search architecture still worked:

Intent
↓
Fan-Out
↓
Retrieval
↓
Evidence
↓
Ranking
↓
Grounded Answer

But healthcare forced me to be stricter about several things.

1. Source roles
Not every source proves the same thing.

2. Claim boundaries
Finding a provider is not the same as verifying every provider attribute.

3. Citations
The model should not be able to invent evidence references.

4. Safety
Provider discovery is not medical diagnosis.

5. Explainability
Unknown information should remain unknown rather than being filled in by the model.

Those lessons are useful well beyond healthcare.

What I learned from the full series

This project started as a search demo.

It gradually became a study of how AI systems can make decisions more inspectable.

The progression looked like this:

Search
   ↓
Grounding
   ↓
Journey Analysis
   ↓
Visibility
   ↓
Agents
   ↓
Tracing
   ↓
AgentOps
   ↓
Healthcare Discovery

The biggest lesson for me is still the simplest:

A good AI search system should not only tell me the answer. It should help me understand where that answer came from.

In healthcare, that becomes even more important.

Cleanup Resource

To clean up all cloud resources, avoid cost, just run below -

./scripts/delete_cloud_run.sh

Source code

1. AI Search Journey Lab:
https://github.com/hastimal/ai-search-journey-lab

2. Healthcare agentic platform:
https://github.com/hastimal/gemini-healthcare-agentic-platform

The two projects explore the same underlying idea from different directions:

retrieve evidence, preserve provenance, expose uncertainty, and let the model reason inside explicit boundaries.

Building AgentOps for Gemini Agents with Grafana, Tempo, and Prometheus

Hastimal Jangid — Sat, 10 Oct 2026 07:14:08 +0000

In Part 5, I added OpenTelemetry tracing to the AI Search Journey Lab.

That changed the way I could debug a single execution.

Instead of seeing only:

User Query
    ↓
...
    ↓
Final Answer

I could inspect:

journey.execution
├── intent parsing
├── query fan-out
├── retrieval
├── search grounding
├── evidence aggregation
├── ranking
└── synthesis

Each stage had timing, status, attributes, and parent-child relationships.

That solved one problem:

What happened during this request?

But once I had traces, another question appeared:

How is the system behaving across many requests?

I wanted to see more than one execution.

I wanted:

request volume
average latency
failure rates
latency by workflow
V4 agent behavior
MCP tool activity
trace drill-down
historical operational trends

That pushed the project from observability toward AgentOps.

For this milestone, I built a local Docker-based observability stack using:

OpenTelemetry
Grafana
Tempo
Prometheus
Docker

The entire stack can run alongside the application locally.

From tracing to AgentOps

OpenTelemetry gave me the instrumentation.

But instrumentation alone is not an operational system.

I needed somewhere for traces to go.

I needed somewhere for metrics to go.

And I needed a UI where I could investigate both.

The architecture became:

Gemini / AI Search Application
              ↓
        OpenTelemetry
              ↓
      OTel Collector
         ↙         ↘
      Tempo     Prometheus
      Traces      Metrics
         ↘         ↙
            Grafana

That is the basic AgentOps stack I wanted.

The application remains responsible for generating telemetry.

The OpenTelemetry Collector handles telemetry transport.

Tempo stores traces.

Prometheus stores metrics.

Grafana becomes the operational view.

Step 1: Keep the observability stack local

One goal was important from the beginning:

I did not need another cloud service just to inspect my AI application during development.

So I created a Docker Compose stack for the observability infrastructure.

The project includes:

docker-compose.observability.yml

GitHub Code: Source Code

along with configuration for:

observability/
├── otel-collector/
├── prometheus/
├── tempo/
└── grafana/

The Docker Compose stack runs the OpenTelemetry Collector, Prometheus, Grafana Tempo, and Grafana locally.

That gives me a repeatable development environment without manually installing each observability component.

Step 2: Use the OpenTelemetry Collector as the routing layer

I did not want the application to know how every backend worked.
The application should emit telemetry.

The collector should decide where that telemetry goes.

Conceptually:

Application
    ↓
OTLP
    ↓
OpenTelemetry Collector
    ├── traces → Tempo
    └── metrics → Prometheus

The project has a dedicated collector configuration:

observability/otel-collector/otel-collector-config.yaml

which routes traces and metrics into the local backends.

This is a useful separation because the application instrumentation does not have to be rewritten every time I change the backend.

Step 3: Export traces from the application

In V5, traces could already be inspected locally.

For AgentOps, I extended the telemetry initialization so traces can also be exported over OTLP when a local collector endpoint is configured.

The local endpoint is:

http://localhost:4318

The telemetry client can conditionally attach the OTLP exporter while preserving the original in-memory tracing behavior.

Conceptually:

settings.otel_exporter_otlp_endpoint = "http://localhost:4318"
init_telemetry()

Then normal instrumentation continues to use the same span helper:

with trace_span(
    "journey.search_to_decision",
    attributes={
        "workflow.stage": "v1",
    },
):
    ...

The difference is that the completed trace can now leave the Python process and become visible in Tempo and Grafana.

Step 4: Send traces to Tempo

Tempo becomes the trace backend.

That gives me persistent trace inspection outside the Streamlit application.

For example, I can query Tempo directly:

curl -s "http://localhost:3200/api/search"

And if I know a trace ID:

curl -s \
  "http://localhost:3200/api/traces/<TRACE_ID>"

During implementation, I used those API calls to verify that traces were actually reaching Tempo before relying on Grafana to visualize them.

I like this verification pattern:

Application generated span
        ↓
Collector received span
        ↓
Tempo stored trace
        ↓
Grafana displayed trace

Note: If the Grafana panel is empty, I can work backwards through the pipeline.

Step 5: Add operational metrics

Traces answer:

What happened in this request?

Metrics answer:

What is happening across the system?

I added a small set of intentionally low-cardinality metrics.
The current implementation emits:

ai_search_journey_requests_total
ai_search_journey_failures_total
ai_search_journey_duration_seconds_count
ai_search_journey_duration_seconds_sum

The key labels are intentionally constrained to values such as:

stage = v1 | v3 | v4

status = ok | error

I deliberately did not put things like these into metric labels:

prompt
raw query
session ID
trace ID
user text

The project explicitly excludes those from metric labels for privacy and cardinality reasons.

That matters because a metric such as:

requests_total{prompt="..."}

would quickly become both a privacy problem and a cardinality problem.

Step 6: Verify metrics before building dashboards

One thing I learned during this milestone was not to assume that because traces are working, metrics are working too.

They are separate telemetry paths.

I verified the collector's Prometheus endpoint directly:

curl -s http://localhost:8889/metrics \
  | grep ai_search_journey

Also verify that the collector endpoint itself accepts OTLP traffic:

curl -i -X POST \
  http://localhost:4318/v1/metrics \
  -H "Content-Type: application/json" \
  -d '{"resourceMetrics":[]}'

If that returns an HTTP response, 4318 is fine.

If after restarting the app and running one workflow you still get no metrics, run:

docker logs otel-collector --tail 100

and:

grep -RniE 'OTEL_EXPORTER_OTLP_ENDPOINT|otel_exporter_otlp_endpoint|metrics' \
  .env .env.example src/ai_search_journey/config.py

Then send me those outputs. The Docker stack itself is not the problem; we now need to confirm the application → collector metrics export path.

That debugging process was actually a good example of why observability needs independent verification.

Step 7: Query Prometheus directly

Before trusting Grafana, I tested Prometheus directly.

For example, total V4 requests:

curl -sG \
  http://localhost:9090/api/v1/query \
  --data-urlencode \
  'query=sum(ai_search_journey_requests_total{stage="v4"})'

Again, Prometheus returned the expected value.

This gave me three independent checkpoints:

Collector
   ↓
Prometheus
   ↓
Grafana

Note: If the Grafana panel looks wrong, you can check the underlying PromQL directly.

Let's open http://localhost:9090 and run:

sum(ai_search_journey_requests_total{stage="v4"})

Step 8: Build the Grafana dashboard

Once traces and metrics were verified independently, I built the Grafana layer.

The project provisions the dashboard automatically through:

observability/grafana/provisioning/dashboards/

and provisions the Prometheus and Tempo datasources through:

observability/grafana/provisioning/datasources/

The main dashboard is:

AI Search Journey — Observability Overview

with UID:

ai-search-journey-overview

That means the dashboard is infrastructure-as-code rather than something I have to recreate manually every time I start Grafana.

Step 9: Track request rate by workflow

One useful panel is request rate grouped by workflow stage.

The dashboard uses PromQL such as:

sum by (stage) (
  rate(ai_search_journey_requests_total[1m])
)

That lets me distinguish activity from:

v1  → Search to Decision
v3  → AI Visibility Scans
v4  → AI Visibility Agent

This is more useful than a single global request counter.

I can immediately see which part of the application is actually generating activity.

Step 10: Track average execution duration

The next useful view is latency.

The dashboard computes average duration using the accumulated duration sum and count:

sum by (stage) (
  rate(ai_search_journey_duration_seconds_sum[1m])
)
/
sum by (stage) (
  rate(ai_search_journey_duration_seconds_count[1m])
)

This gives me a stage-level operational view:

V1 average duration
V3 average duration
V4 average duration

That is different from the span-level view in Tempo.

Prometheus answers:

Is this workflow getting slower over time?

Tempo answers:

Why was this particular request slow?

I want both.

Step 11: Combine metrics and traces

This is where Grafana becomes much more useful than either backend alone.

Prometheus gives me the macro view:

Request rate
Average latency
Failures
Workflow health

Tempo gives me the micro view:

One request
One trace
Individual spans
Tool calls
Timing
Errors

So the operational workflow becomes:

Grafana metric shows latency increase
             ↓
Choose suspicious time window
             ↓
Open related traces
             ↓
Inspect span hierarchy in Tempo
             ↓
Find slow tool / model / database operation

That is much closer to how I want to debug agentic systems.

Step 12: Observe real V4 agent behavior

The AgentOps story becomes more interesting with V4.

A V4 request is not just: prompt → response

It can involve:

User Question
      ↓
Gemini
      ↓
Google ADK
      ↓
MCP tool
      ↓
BigQuery
      ↓
Tool Result
      ↓
Gemini Synthesis

So I added child-span instrumentation around the V4 workflow.

The implementation preserves the root agent span and traces child operations for the agent workflow. A live V4 interaction was used to verify that those traces reached the local Docker observability stack.

That lets me inspect questions such as:
Which tool did the agent choose?
How long did the MCP call take?
Was BigQuery the bottleneck?
Did the agent call multiple tools?
Which stage failed?

That is much more meaningful AgentOps than simply charting LLM request counts.

Step 13: Use TraceQL for agent investigation

Once the V4 spans included consistent workflow metadata, I could filter traces by attributes rather than manually searching through everything.

For example, V4 spans can carry:

workflow.stage = "v4"

The project verified the Grafana-to-Tempo query path against actual V4 agent traces using TraceQL filtering.

That gives me a useful investigation pattern:

Show me V4 traces
      ↓
Find slow request
      ↓
Open trace
      ↓
Inspect MCP child span
      ↓
Inspect BigQuery span

This becomes increasingly valuable as the number of agents and tools grows.

Step 14: Start everything locally

One thing I wanted from this milestone was a simple local workflow.

From the repository root:

source .venv/bin/activate

Then:

python scripts/run_app_locally.py

That is the normal local startup path for this project.

The stack gives me:

Streamlit
http://localhost:8502

Grafana
http://localhost:3000

Prometheus
http://localhost:9090

Tempo
http://localhost:3200

So one command can give me the application and the local AgentOps environment.

Step 15: Verify that Docker is healthy

If Grafana does not open, I first inspect Docker instead of debugging the Python application.

docker ps

I expect the local observability services to be running.

The project Compose definition can also be validated independently:

docker compose \
  -f docker-compose.observability.yml \
  config

Step 17: Validate the complete stack

The AgentOps milestone is not complete just because Grafana loads.

I validate both code and infrastructure.

The verification suite includes:

./.venv/bin/ruff check .
./.venv/bin/mypy src
./.venv/bin/pytest -q
git diff --check
docker compose -f docker-compose.observability.yml config

During the completed Dockerized observability implementation, the recorded results were:

Ruff
All checks passed!

Mypy
Success: no issues found in 38 source files

Pytest
381 passed, 3 warnings

Git diff check
Clean

Docker Compose config
Valid

What I learned building the stack

The first lesson was:

Traces and metrics answer different questions.

Trying to force one to do everything makes the system harder to use.

The second lesson was:

Verify every telemetry layer independently.

I now think in terms of:

Application instrumentation

→ Collector ingestion

→ Backend storage

→ Query result

→ Dashboard

The third lesson was:

Agent observability needs tool-level visibility.

Only tracing the outer Gemini request would hide most of the interesting behavior.

For an agent, I want to see:

reasoning boundary

tool selection

tool execution

database call

response synthesis

The fourth lesson was:

Local observability is extremely useful.

I can experiment with AgentOps architecture without keeping another cloud observability environment running continuously.

What I intentionally did not do

This project is not trying to rebuild a commercial observability platform.

I kept the architecture relatively small:

OpenTelemetry
Collector
Tempo
Prometheus
Grafana

I also do not record full prompts as Prometheus labels.

I do not make trace IDs into high-cardinality metrics.

And I do not treat raw chain-of-thought as something that should be logged.

The goal is operational visibility into the system:

Which stage ran?
Which tool ran?
How long did it take?
Did it succeed?
How often does it fail?
Which trace should I inspect?

That is enough to make debugging substantially better without turning telemetry into a privacy problem.

From AgentOps to healthcare discovery

At this point the AI Search Journey Lab has evolved through several layers:

Grounded Search
      ↓
Journey Analysis
      ↓
AI Visibility
      ↓
AI Visibility Agent
      ↓
OpenTelemetry Tracing
      ↓
AgentOps

For the final article in this series, I want to take the architecture into a domain where grounding and evidence matter even more:

healthcare discovery.

The question changes from:

Which coffee shop should I choose?

to something much more sensitive:

How can an AI-assisted search journey help someone discover appropriate care while preserving evidence, source attribution, and explainability?

That becomes Part 7.

Next: From Search to Care — Applying Gemini Search Journeys to Healthcare Discovery

In Part 7, I will apply the search journey pattern to healthcare discovery.

The focus will be on:

Gemini
healthcare provider discovery
grounded evidence
search journey fan-out
source attribution
deterministic evaluation
explainable recommendations
care-oriented constraints
the boundary between discovery and medical advice

The goal is not to build an AI doctor.

The goal is to explore how the same grounded search architecture can support a more evidence-oriented path from a healthcare question to provider discovery.

Source code

The project is open source: https://github.com/hastimal/ai-search-journey-lab

From Query Fan-Out to Trace: Observing AI Search Journeys with OpenTelemetry

Hastimal Jangid — Sat, 10 Oct 2026 07:12:36 +0000

In the earlier parts of this series, I focused on what the system produced.

I started with grounded search journeys, then added historical visibility analysis, and eventually put an agent in front of that history with Gemini, Google ADK, MCP, and BigQuery.

But once the workflow became more complex, a different question started bothering me:

When something is slow, fails, or behaves unexpectedly, how do I know which stage caused it?

A single request could involve:

Intent parsing
      ↓
Query fan-out
      ↓
Places retrieval
      ↓
Search grounding
      ↓
Evidence aggregation
      ↓
Constraint evaluation
      ↓
Ranking
      ↓
Answer synthesis

And in later versions:

Agent chat
      ↓
MCP tool call
      ↓
BigQuery read
      ↓
Gemini synthesis

Looking only at the final answer was no longer enough.

I needed to see the execution journey itself.

That became V5: OpenTelemetry observability for the AI Search Journey Lab.

Why tracing became necessary

Consider a query like:

Find a coffee shop near Geekdom San Antonio for 6 people to work together, preferably quiet, and open after 8 PM.

From the UI, I can see whether the final recommendations look reasonable.

But suppose the request takes six seconds.

Where did those six seconds go?
Was Gemini intent extraction slow?
Did query fan-out generate too many retrieval tasks?
Did Google Places take most of the time?
Was Search grounding the bottleneck?
Did ranking become expensive?
Did final synthesis take longer than expected?

Without tracing, all I really know is:

Request started

...

Request completed

That is not enough once an AI workflow has multiple stages, external APIs, tools, agents, and data stores.

I wanted this instead:

Request
├── intent parsing              410 ms
├── query fan-out               530 ms
├── places retrieval          1,240 ms
├── search grounding            870 ms
├── evidence aggregation        120 ms
├── constraint evaluation        70 ms
├── ranking                      95 ms
└── answer synthesis            690 ms

Now I can reason about the system.

OpenTelemetry turns the AI search journey into a trace composed of spans for intent parsing, fan-out, retrieval, grounding, ranking, and synthesis.

Step 1: Think in traces and spans

The first concept I needed was simple:

A trace represents one complete operation.

A span represents one step inside that operation.

For V1, the root operation is the search journey itself.

The implementation creates a root span around the full journey and then nests child spans for the major execution stages. The project also propagates a journey.run_id so the spans belonging to the same execution can be correlated.

Conceptually:

Trace: journey.execution
│
├── journey.intent_parsing
├── journey.query_fanout
├── journey.places_retrieval
├── journey.normalize
├── journey.search_grounding
├── journey.evidence_aggregation
├── journey.constraint_eval
├── journey.ranking
├── journey.static_map
└── journey.answer_synthesis

Those names are not arbitrary UI labels.

They correspond to actual stages I wanted to inspect independently.

That immediately gave me something the original application did not have:

structure around execution time.

Step 2: Instrument the stages I actually care about

I did not want to create spans for every Python function.

That would create a lot of noise without adding much value.

Instead, I instrumented meaningful workflow boundaries.

For example:

1. Intent parsing

journey.intent_parsing

This covers Gemini-based intent extraction.

Useful attributes include:

intent.category
intent.has_location
intent.constraint_count

2. Query fan-out

journey.query_fanout

This records the fan-out planning stage.

Useful attributes include:

fanout.total_queries
fanout.places_queries
fanout.search_queries

3. Places retrieval

journey.places_retrieval

Useful attributes include:

places.task_id
places.raw_count

4. Search grounding

journey.search_grounding

Useful attributes include:

search.task_id
search.sources_count
search.queries_count

5. Ranking

journey.ranking

Useful attributes include:

ranking.candidate_count
ranking.top_score

6. Final synthesis

journey.answer_synthesis

Useful attributes include:

answer.recommendations_count
answer.caveats_count

The project also traces normalization, evidence aggregation, constraint evaluation, and static map generation.

This gave me a trace model that follows the way I already think about the search journey.

Step 3: Add correlation IDs

Timing alone is useful.

Correlation is what makes the traces much more powerful.

The project uses identifiers such as:

journey.run_id
visibility.scan_id
session.id

to connect related operations across the different application stages.

That matters because a V1 journey can later lead to a V3 visibility scan.

And a V4 agent interaction has its own session and turn IDs.

So instead of looking at disconnected events, I can follow relationships such as:

journey.run_id
      ↓
V1 Search Journey
      ↓
visibility.scan_id
      ↓
V3 Visibility Scan

For V4:

session.id
      ↓
v4.session_id
      ↓
v4.turn_id
      ↓
MCP tool call
      ↓
BigQuery read

The V4 tracing model includes spans such as:

v4.chat_turn

v4.mcp_tool.<tool_name>

v4.bigquery.read

with metadata for tool names, brands, date ranges, read-only BigQuery operations, and rows returned.

This is where observability starts becoming useful across versions instead of only inside one function.

Step 4: Propagate trace context

Creating spans is easy.

Creating the correct parent-child relationships is more important.
OpenTelemetry context propagation keeps child operations attached to the correct parent span.

The implementation uses standard OpenTelemetry context handling, including span context attachment and propagation, so nested work such as ranking, BigQuery reads, and tool calls stays under the correct workflow.

That gives me a trace hierarchy like:

journey.execution
│
├── journey.intent_parsing
│
├── journey.query_fanout
│
│   ├── places query 1
│   ├── places query 2
│   └── search query 1
│
├── journey.search_grounding
│
├── journey.ranking
│
└── journey.answer_synthesis

Without parent-child relationships, tracing becomes little more than a list of timestamps.

With them, I get an execution tree.

Step 5: Create a reusable tracing helper

I did not want tracing logic scattered through the application.
So the telemetry layer includes a reusable helper around span creation.

Conceptually, the code looks like this:

with trace_span(
    "journey.ranking",
    attributes={
        "ranking.candidate_count": len(candidates),
    },
):
    ranked = rank_candidates(candidates)

The tracing helper is responsible for things such as:

span creation
attributes
duration
status
error capture
sanitization

The telemetry design includes a dedicated tracer module plus a trace_span(...) context manager so instrumentation can stay small at each call site.

That matters because I did not want observability code to dominate the actual application logic.

The business code should still read like business code.

Step 6: Record status, not just duration

A slow span and a failed span are different problems.

So each span records status.

Conceptually:

StatusCode.OK

or

StatusCode.ERROR

When an exception occurs, the span captures the failure before the exception continues through the normal error-handling path.

That means I can distinguish:

journey.places_retrieval
Duration: 1.8 s
Status: OK

from:

journey.places_retrieval
Duration: 1.8 s
Status: ERROR

That is much more useful during debugging.

The observability tests were designed to verify normal span lifecycle as well as error capture and parent-child relationships.

Step 7: Treat telemetry as sensitive data

One observability mistake I wanted to avoid was dumping everything into traces.

An AI application can easily expose:

API keys
authorization headers
tokens
raw prompts
private user input
URLs containing credentials
exception payloads

So I added an explicit redaction layer.

Sensitive dictionary keys such as:

api_key
key
secret
authorization
password
token

are masked.

The implementation also scans for credential-like patterns such as Google API keys, OAuth tokens, and bearer tokens.

I also avoid storing raw prompts as span attributes.

Instead, telemetry can record safer metadata such as:

query length
sanitized summary
hash
category
constraint count

The design explicitly avoids verbatim system prompts and user prompts in the trace attributes.

That became an important principle for me:

Observability should make the system easier to inspect without turning telemetry into a second sensitive-data store.

Step 8: Keep V5 local first

For the initial observability milestone, I deliberately kept the tracing stack lightweight.

The design uses the OpenTelemetry API and SDK with an in-memory span exporter rather than requiring an external tracing platform.

The core dependencies are:

opentelemetry-api
opentelemetry-sdk

That was enough to support:

TracerProvider
SimpleSpanProcessor
InMemorySpanExporter

without requiring an external collector just to understand the tracing model.

This made V5 useful locally and kept the milestone focused:

Instrument
      ↓
Capture
      ↓
Inspect
      ↓
Debug

The Grafana/Tempo/Prometheus stack comes later.

That becomes Part 6.

Step 9: Retain traces without leaking memory

Streamlit has its own execution model.

The script can rerun from top to bottom as users interact with the app.

So trace retention needs to survive UI interactions without growing forever.

The V5 design uses an in-memory telemetry store plus Streamlit session state.

Completed traces are kept in a bounded buffer instead of being retained indefinitely. The design considered limits such as the last 50 execution runs or roughly 2,000 spans, with older entries discarded automatically.

That gives me enough history for local debugging without creating an unbounded memory problem.

Step 10: Build an observability UI

Raw spans are useful to developers.

A visual timeline is faster.

So V5 adds an Observability [V5] tab to the Streamlit application.
The UI is designed around three things:

Run selection
Execution timeline
Span inspection

The run selector can distinguish workflows such as:

V1 Search
V3 Visibility Scan
V4 Agent Chat

The timeline shows:

span name
start offset
duration
status

And the span inspector exposes safe attributes, correlation IDs, events, and sanitized exception details.

That means I can click a run and inspect the journey without leaving the application.

Step 11: Trace V3 visibility scans too

Once the tracing foundation existed, I did not want it to stop at V1.

The visibility workflow also gets its own trace hierarchy.

The V3 root span is:

visibility.scan_execution

with attributes such as:

visibility.scan_id
visibility.brand_id
journey.run_id

Child spans include:

visibility.extract_bundle
visibility.save_bundle

The persistence span can record metadata such as:

bigquery.dataset
bigquery.table_count
bigquery.saved

That makes it possible to distinguish:

The search journey was slow

from:

The visibility extraction was slow

or:

The BigQuery persistence stage was slow

Those are operationally very different problems.

Step 12: Trace V4 agent/tool behavior

V4 introduced another layer: agent orchestration.

Now a single user question can result in:

Gemini reasoning
      ↓
ADK tool selection
      ↓
MCP request
      ↓
BigQuery read
      ↓
tool result
      ↓
Gemini synthesis

So V5 also traces agent activity.

The root agent interaction uses:

v4.chat_turn

Tool calls use:

v4.mcp_tool.<tool_name>

And BigQuery reads use:

v4.bigquery.read

The BigQuery span includes a bigquery.read_only attribute so the observability layer can preserve and expose the read-only nature of the V4 agent.

This is useful because now I can answer questions such as:

Which MCP tool did the agent call?
How long did it take?
Which brand did it analyze?
What date range was requested?
How many rows came back?
Did the BigQuery read succeed?

without needing to infer that from the final answer.

Step 13: Use traces to find bottlenecks

This is where tracing becomes practical.

Suppose a journey takes 5.4 seconds.

The trace might reveal:

intent parsing             310 ms
query fan-out              460 ms
places retrieval         2,310 ms
search grounding           890 ms
ranking                     80 ms
answer synthesis           740 ms

Now the bottleneck is obvious.

I do not need to optimize ranking.

I do not need to optimize Gemini intent parsing.

I need to investigate Places retrieval.

On another run:

intent parsing             280 ms
query fan-out              440 ms
places retrieval           780 ms
search grounding         2,420 ms
ranking                     75 ms
answer synthesis           810 ms

Now the problem is different.

Tracing turns:

The app feels slow.

into:

Search grounding contributed almost half the request duration.

That is a much more actionable statement.

Step 14: Use traces to debug failures

Latency is only one use case.

Failures become much easier to understand too.

Instead of:

Search failed.

I can inspect:

journey.execution             ERROR
├── journey.intent_parsing     OK
├── journey.query_fanout       OK
├── journey.places_retrieval   OK
├── journey.search_grounding   ERROR
└── remaining stages           not executed

Now I know exactly where to start.

The telemetry test plan also explicitly covers failure injection, sanitized error capture, and span status verification.

This becomes especially valuable once external services are involved.

Step 15: Run the application locally

For local development, I still use the normal project workflow.

Activate the virtual environment:

source .venv/bin/activate

Then start the project:

python scripts/run_app_locally.py

What I learned building the tracing layer

The first lesson was that observability works best when the spans follow the architecture.

If I create traces around random functions, the timeline becomes noise.

If I create spans around real workflow stages, the trace becomes documentation.

The second lesson was:

Correlation matters as much as timing.

A fast span is useful.

A fast span tied to the correct search journey, visibility scan, or chat turn is much more useful.

The third lesson was:

Telemetry needs its own privacy model.

Logging every prompt and exception is easy.

Designing traces that are useful without leaking secrets is harder—and more important.

The fourth lesson was that observability should be added before the system becomes impossible to reason about.

V5 was the point where the application had enough moving parts that tracing stopped being optional for me.

One thing I intentionally kept separate

OpenTelemetry gives me the instrumentation model.

It gives me:

traces
spans
attributes
statuses
context propagation
events

But V5 does not need to solve the entire production monitoring problem.

I deliberately separated:

Instrumentation

from:

Operational dashboards
metrics backend
trace backend
AgentOps

That second layer is the next article.

The project later extends the same telemetry into a Dockerized stack with an OpenTelemetry Collector, Tempo, Prometheus, and Grafana.

But I wanted to understand the traces first.

From traces to AgentOps

Once the traces were available, the next set of questions became operational:

How many requests are running?
What is the average latency?
Which stage fails most often?
How many tool calls does the agent make?
Which traces should I investigate?
Can I see request metrics and traces together?
Can the entire observability stack run locally?

That led to the next milestone:

AgentOps.

Next: Building AgentOps for Gemini Agents with Grafana, Tempo, and Prometheus

In Part 6, I will take the OpenTelemetry instrumentation from V5 and connect it to a complete local observability stack.

The architecture becomes:

Gemini / Agent Application
          ↓
OpenTelemetry
          ↓
OTel Collector
       ↙       ↘
   Tempo      Prometheus
   Traces       Metrics
       ↘       ↙
        Grafana

The focus will move from instrumenting individual runs to operating the system over time.

Source code

The project is open source: https://github.com/hastimal/ai-search-journey-lab

Building an AI Visibility Agent with Gemini, Google ADK, MCP, and BigQuery

Hastimal Jangid — Sat, 10 Oct 2026 07:10:22 +0000

In Part 3, I built the historical layer.

The system could persist AI visibility scans, brand observations, citations, and fan-out behavior in BigQuery. That gave me something I did not have in the earlier versions of this project: history.

I could ask questions such as:

Which brands were mentioned?
Which brands were recommended?
Which citation domains appeared?
Which queries found or missed a brand?
How did visibility change across repeated scans?

But there was still friction.

Every time I wanted to investigate something new, I had to open the dashboard or write another SQL query.

GitHub Code: ai-search-journey-lab

That led to the next step:

What if I could ask an agent questions about the visibility history instead?

Not a generic chatbot.

Not an agent with unrestricted access.

I wanted a constrained analytical agent that could inspect the visibility data I had already collected, use explicit tools, stay read-only, and return an answer grounded in actual BigQuery history.

That became V4: the AI Visibility Agent.

What changed from V3 to V4

V3 gave me this:

Visibility Scans
      ↓
BigQuery
      ↓
Dashboard + SQL

V4 adds an agent between the user and that historical data:

User Question
      ↓
Gemini
      ↓
Google ADK Agent
      ↓
MCP Toolset
      ↓
Local MCP Server
      ↓
Read-Only BigQuery Analytics
      ↓
Grounded Answer

The important part is not simply that an LLM sits in front of BigQuery.

The important part is the boundary.

V4 does not execute new Places searches, does not run new web searches, and does not write new visibility data. It acts as an analytical layer over the history produced by V3.

That separation made the design much easier to reason about.

V3 creates evidence.

V4 investigates evidence.

Step 1: Define the agent boundary first

Before I built the agent, I decided what it should not be allowed to do.

That turned out to be one of the most important design choices in this version.

The V4 agent is intentionally read-only.

It should not:

insert new BigQuery rows
update visibility records
delete historical data
trigger new visibility scans
call Google Places
perform live web searches
execute arbitrary user-supplied SQL

Instead, the agent should answer questions using a fixed set of analytical tools.

That gives me a much cleaner boundary:

V1 / V2
Live search journey

V3
Persisted visibility evidence

V4
Read-only analytics over V3

I find this pattern much more useful than giving the model broad database access and trying to control it only through prompting.

The capability boundary is architectural, not only instructional.

Step 2: Use Google ADK as the orchestration layer

The agent itself is built with Google ADK.

Its job is not to contain all of the analytical logic.

Instead, it handles the conversational layer:

User asks a question
        ↓
Gemini interprets the intent
        ↓
ADK selects an appropriate tool
        ↓
Tool returns structured data
        ↓
Gemini explains the result

In the implementation, the ADK agent connects to the MCP toolset over stdio, while the MCP server runs separately and performs the read-only BigQuery analytics.

That gives me two useful separations:

Reasoning
    ≠
Data access

and:

Agent orchestration
    ≠
Analytics implementation

The model decides what information it needs.

The tools decide how that information is retrieved.

Use a clean architecture diagram showing:

User Question
      ↓
Gemini
      ↓
Google ADK Agent
      ↓
MCP Toolset
      ↓
Local MCP Server
      ↓
Read-Only BigQuery
      ↓
V3 Visibility History

Step 3: Why I used MCP here

I could have connected the agent directly to Python functions.

But I wanted the data-access boundary to be more explicit.
That is where MCP became useful.

The analytical tools live behind a local MCP server that communicates with the ADK agent over JSON-RPC stdio.

Conceptually:

ADK Agent
    │
    │ MCP over stdio
    ▼
MCP Server
    │
    ▼
Approved Analytics Tools
    │
    ▼
BigQuery

That means the agent does not need direct knowledge of the underlying SQL implementation.

It sees a set of capabilities.

For example:

get_available_history
get_visibility_summary
get_brand_trend
compare_brands
analyze_citations
find_fanout_gaps

Those six tools form the analytical surface of V4.

That is a much more controlled interface than:

run_any_sql(query)

Step 4: Build tools around analytical questions

I did not want the tool names to mirror database tables.

I wanted them to mirror the questions I actually ask when analyzing visibility.

That resulted in six read-only tools.

get_available_history

Before asking for a trend or comparison, I first need to know what history actually exists.

This tool discovers things such as:

persisted scan counts
available date ranges
known brand IDs
recent scan windows

That makes it especially useful for broad prompts where the user does not specify a brand or date range.

This also supports a pattern I like:

Discover first, analyze second.

Instead of letting the model assume what history exists, the agent can inspect the available data.

get_visibility_summary

This tool provides an aggregated visibility view over a selected brand and time window.

It can work with metrics such as:

mention rate
recommendation rate
citation rate

Rather than making the model calculate those metrics itself, I keep them in the analytical layer.

That makes the agent responsible for explanation rather than arithmetic.

get_brand_trend

This tool turns historical scan records into a time-oriented visibility view.

Conceptually:

Scan 1
Scan 2
Scan 3
Scan 4
   ↓
Historical visibility trajectory

That gives the agent a way to answer questions such as:

Is this brand becoming more or less visible?

The trend logic remains deterministic.

Gemini interprets the result.

compare_brands

This tool gives the agent a controlled way to compare a target brand with competitors.

Instead of letting the model assemble arbitrary joins, the comparison is exposed as an explicit business operation.

The tool can compare signals such as:

mentions
recommendations
citations

between the target and competing brands.

analyze_citations

In V3, citations became independently queryable.

V4 turns that into an agent capability.

The agent can inspect citation-domain behavior across the stored search journeys instead of only answering questions about brand presence.

That lets me ask questions closer to:

Which domains repeatedly support this brand?

rather than only:

Was this brand mentioned?

find_fanout_gaps

This is one of the more interesting tools.

The purpose is to identify fan-out queries where a target brand was absent from observed results.

Conceptually:

User Prompt
   ↓
Fan-Out Query A → Brand found
Fan-Out Query B → Brand found
Fan-Out Query C → Brand missing
Fan-Out Query D → Brand missing

That means the agent can investigate where visibility breaks down, not only whether overall visibility is high or low.

Step 5: Keep the tools deterministic

A design principle I carried over from V3 was this:

Let the model reason about results, but do not make the model invent the measurements.

The MCP tools perform the analytical work.

Gemini receives structured results and explains them.

So instead of:

Gemini:
"I think the brand visibility is probably around 70%."

the flow becomes:

Tool:
mention_rate = 68.2
recommendation_rate = 41.7
citation_rate = 53.6

Gemini:
"Your brand appeared in roughly two-thirds of the observed journeys,
but it was recommended less frequently..."

The exact values come from data.

The language comes from the model.

That separation is important to me.

Step 6: Use discovery-first grounding

One problem with analytical agents is that users often ask incomplete questions.

For example:

Give me a visibility summary.

A model could easily make assumptions:

which brand?
what date range?
which scans?
what data actually exists?

Instead, V4 can discover the available history first using get_available_history. For broad questions or questions without an explicit brand/date window, that discovery step gives the agent actual scan coverage before it performs deeper analysis

That means:

Question
   ↓
Discover available history
   ↓
Choose valid scope
   ↓
Run analysis
   ↓
Explain answer

I prefer this to embedding assumed date ranges in the prompt.

Step 7: Run the agent locally

The V4 agent can be used through the Streamlit application or through a standalone CLI demo.

First activate the environment:

source .venv/bin/activate

Then launch the application:

streamlit run src/ai_search_journey/app.py

Step 8: Start with a broad-history question

One of the first prompts I use is:

Give me a visibility summary for the available history.
Use the most recent available scan window.

The important phrase is:

available history

I do not want the model to assume that a particular brand or date range exists.

The agent can inspect the historical coverage first and then use the appropriate read-only tools to produce the summary.

This gives me a much more grounded conversation.

The user does not need to know the dataset structure.

The agent does not need to guess the dataset structure.

The tools bridge that gap.

Step 9: Ask for a competitor comparison

The next test is more specific.

For example:

Compare "pullman_coffee" against its competitors for the most recent available scan window.

The important detail is that the brand ID needs to exist in the historical data. The project documentation explicitly treats pullman_coffee as an example only when it is present in the available scan history.

In practice, I can first discover the available brand IDs and then choose one.

The comparison tool can then return a structured view of:

mentions
recommendations
citations

between the target brand and competing brands.

The model then explains the comparison in natural language.

Step 10: Independently verify the agent with BigQuery

One thing I do not want is an agent that becomes the only interface to the data.

The underlying history should still be independently verifiable.

V4 never writes to BigQuery; the queries below are only for verifying the V3 data that the agent reads.

For example, I can inspect per-brand visibility metrics directly:

bq --project_id=ai-search-journey-lab query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    brand_id,
    COUNT(DISTINCT scan_id) AS total_scans,
    ROUND(100 * AVG(CAST(mentioned AS INT64)), 1) AS mention_rate_pct,
    ROUND(100 * AVG(CAST(recommended AS INT64)), 1) AS recommendation_rate_pct,
    ROUND(100 * AVG(CAST(cited AS INT64)), 1) AS citation_rate_pct,
    MAX(started_at) AS latest_scan_at
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.brand_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 365 DAY)
  GROUP BY
    brand_id
  ORDER BY
    citation_rate_pct DESC,
    mention_rate_pct DESC,
    total_scans DESC
  '

That query gives me an independent path to the same underlying evidence used by the agent.

I can also inspect recent persisted scans:

bq --project_id=ai-search-journey-lab query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    scan_id,
    started_at,
    brand_id,
    brand_name_snapshot,
    prompt_text_snapshot
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.visibility_scans`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 365 DAY)
  ORDER BY
    started_at DESC
  LIMIT 10
  '

The partition filter matters here because the historical tables require filtering on started_at.

Step 11: Why I did not give the agent raw SQL

A natural question is:

Why not just let Gemini generate SQL?

That would certainly be simpler.

But it would also create a much broader capability surface.

With arbitrary SQL generation:

User
  ↓
LLM
  ↓
Generated SQL
  ↓
Database

the model has to understand:

table names
schemas
joins
partition requirements
date handling
security boundaries
allowed operations
analytical semantics

And then I have to validate all of that.

With MCP tools:

User
  ↓
Gemini + ADK
  ↓
compare_brands(...)
  ↓
Controlled analytics logic
  ↓
BigQuery

the capability is much narrower.

The model asks for an operation.

The tool owns the implementation.

That is a pattern I increasingly prefer for production-oriented agent systems.

Step 12: Separate reasoning from authority

This is probably the most important lesson from V4.

LLMs are very good at:

interpreting a question
selecting an analytical path
comparing results
summarizing findings
explaining trade-offs

But that does not mean the model needs unrestricted authority over the underlying system.

I can keep the reasoning flexible while keeping the capabilities constrained.

Gemini
    ↓
Flexible reasoning

Google ADK
    ↓
Agent orchestration

MCP
    ↓
Explicit capability boundary

BigQuery
    ↓
Deterministic historical evidence

That architecture is much easier for me to understand and debug.

Step 13: Preserve unsupported-answer behavior

Another boundary matters just as much:

The agent should be able to say:

I do not have enough historical data to answer that.

If the user asks about:

a brand that does not exist in the scan history
a time period with no scans
a metric the tools do not expose
current live-search behavior

the right response is not to manufacture an answer.

The system should stay within the evidence available to V4.

That makes the agent less magical.

It also makes it much more useful.

Step 14: Validate the agent layer

As with the previous versions, I do not consider the feature complete just because the UI responds.

I run the repository checks:

./.venv/bin/ruff check . && \
./.venv/bin/mypy src && \
./.venv/bin/pytest -q

What V4 changed for me

V3 taught me to preserve the evidence before calculating the conclusion.

V4 added another lesson:

Give the model access to capabilities, not unrestricted infrastructure.

The final architecture is not:

Gemini
   ↓
Database

It is:

User Question
      ↓
Gemini
      ↓
Google ADK
      ↓
Approved MCP Tools
      ↓
Read-Only Analytics
      ↓
BigQuery History
      ↓
Structured Evidence
      ↓
Grounded Explanation

That distinction matters.

Gemini provides the reasoning.

Google ADK orchestrates the workflow.

MCP defines the tool boundary.

BigQuery remains the source of historical evidence.

The analytical tools remain deterministic and read-only.

What I learned building the AI Visibility Agent

The first lesson was that an analytical agent becomes more trustworthy when it knows less about the database.

That may sound backward.

But the model does not need to know every table, join, and partition rule.

It needs to know which analytical capability to use.

The second lesson was that discovery is a tool too.

get_available_history is not just convenience.

It helps prevent the model from reasoning over data that does not exist.

The third lesson was that agents become easier to evaluate when the tools reflect real business questions:

What history exists?

How visible is this brand?

How is visibility changing?

How does it compare with competitors?

Which sources are citing it?

Where does query fan-out miss it?

From agentic analytics to observability

Once the agent started working, another problem became much more obvious.

Now I had:

User Question
      ↓
Gemini
      ↓
ADK Agent
      ↓
MCP Tool Selection
      ↓
MCP Server
      ↓
BigQuery
      ↓
Tool Result
      ↓
Gemini Synthesis

But if something became slow or failed, I needed to know:

Which stage caused it?

Was Gemini slow?

Did the MCP process take too long?

Did the BigQuery tool fail?

Which tool did the agent call?

How much time did each stage take?

That moved the project into the next phase: observability.

Next: From Query Fan-Out to Trace — Observing AI Search Journeys with OpenTelemetry

In Part 5, I will instrument the AI Search Journey so I can trace what happens across the workflow.

The focus moves from:

What answer did the system produce?

to:

How did the system produce it?

Source code

The project is open source: GitHub Project

Building an AI Search Visibility & Brand Analyzer with Gemini, BigQuery, and Google Search Grounding

Hastimal Jangid — Tue, 29 Sep 2026 05:22:17 +0000

AI Search Journey Lab — Part 3 of 7

Measuring how brands appear across AI search journeys using Gemini, Google Search grounding, deterministic visibility scans, and BigQuery history.

Open source: ai-search-journey-lab

Previous: Building Grounded Local Search with Gemini and Google Maps on Google Cloud

The first two articles answered a user question. This one measures the system itself.

In Part 1, I focused on the search journey:

How does one natural-language request become a grounded decision?

In Part 2, I went deeper into the actual local-search implementation:

How do Gemini, Google Places, Search grounding, deterministic ranking, and Maps work together?

Once that worked, I started asking a different question.

Suppose I run the same kind of search repeatedly.

What happens if instead of only asking:

Which business should the user choose?

I ask:

Which brands keep appearing?
Which brands are cited?
Which competitors show up more often?
Does a brand appear in the initial answer, the fan-out journey, or only in supporting evidence?
How does that change over time?

That was the starting point for V3 — AI Visibility.

This article is about turning an AI search workflow into something measurable.

Why AI visibility needs a different data model

A single search result is transient.

If I want to measure visibility, I need history.

One run is interesting.

Fifty runs are analyzable.

Five hundred runs can start showing patterns.

So V3 introduced a new concern into the project: persistence

That is where BigQuery enters the architecture.

What I wanted to measure

For each visibility run, I wanted to capture things such as:

target brand
competitors
original query
fan-out tasks
mentions
citations
candidate coverage
source coverage
ranking position
execution timestamp
historical trend

The important shift was this:

V1/V2:
user query → recommendation

V3:
many queries → repeatable measurements

That turns the project from a search demo (which we have planned) into an analytics system. :)

Architecture

Step 1: I made visibility scans deterministic

One important design choice was that V3 should not rely on a user manually clicking around and interpreting the results.

I wanted repeatable runs.

That means the runner should accept an explicit input scope and execute the same workflow consistently.

Conceptually:

run = VisibilityRun(
    target_brand="Example Brand",
    competitors=[
        "Competitor A",
        "Competitor B",
    ],
    queries=[
        "best local coffee shops in San Antonio",
        "quiet coffee shop for remote work",
    ],
)

Then the runner executes the scan and records the results.

The goal is reproducibility.

If I run the same scenario tomorrow, I want to compare the resulting data rather than rely on screenshots or memory.

Step 2: Separate mention detection from visibility scoring

A brand appearing in a response is not the same as a brand being strongly visible.

For example:

Target brand:
RankRabbit

Response:
"Other platforms include RankRabbit, Competitor A, and Competitor B."

That is a mention.

But now compare:

1. RankRabbit — recommended first
2. Competitor A
3. Competitor B

Those two appearances should not necessarily have the same visibility weight.

So I separate several concepts:

mention presence
position
citation presence
fan-out coverage
narrative prominence

That lets the application calculate visibility metrics explicitly instead of collapsing everything into one LLM judgment.

Step 3: Capture evidence before calculating visibility

The workflow should preserve what caused a brand to be counted.

Conceptually:

{
  "brand": "Example Brand",
  "mentioned": true,
  "rank": 2,
  "citation_present": true,
  "fanout_coverage": 0.67,
  "evidence_sources": [
    "source-a",
    "source-b"
  ]
}

That data is much more valuable later than a single score such as:

visibility_score = 74

because it lets me explain where the score came from.

Step 4: Persist visibility history in BigQuery

V3 can run in-memory for a quick demo, but historical analysis needs persistence.

I used a BigQuery dataset for that purpose:

Project:
ai-search-journey-lab

Dataset:
ai_search_journey_v3

Let's explore how bigQuery tables look like.....

bq query \
  --use_legacy_sql=false \
  '
  SELECT
    table_name,
    table_type,
    creation_time
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.INFORMATION_SCHEMA.TABLES`
  ORDER BY
    table_name
  '

Step 5: Query historical visibility with SQL

Once I started persisting V3 runs in BigQuery, I no longer had to rely only on what the Streamlit dashboard displayed.

I could query the visibility history directly from the terminal.
That became one of my favorite parts of V3 because it gave me a second way to validate everything the UI was showing.

For all of the examples below, I use the BigQuery CLI:

Once scan results are persisted, SQL becomes one of the most useful tools in the project.

BigQuery dataset showing the persisted visibility-analysis tables.

The four tables I use most for visibility analysis are:

visibility_scans
brand_observations
fanout_observations
citations

Each answers a different question.

visibility_scans
    └── What happened during the scan?

brand_observations
    └── How did each brand appear?

fanout_observations
    └── Where was the brand found during query fan-out?

citations
    └── Which sources supported the grounded result?

That separation became important as V3 grew.

I did not want one oversized table containing execution metadata, brand observations, fan-out evidence, citations, and historical measurements all mixed together.

Inspect the actual schema

Before writing analytical queries, I wanted to verify the exact schema from the terminal.

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    table_name,
    ordinal_position,
    column_name,
    data_type
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.INFORMATION_SCHEMA.COLUMNS`
  WHERE
    table_name IN (
      "visibility_scans",
      "brand_observations",
      "fanout_observations",
      "citations"
    )
  ORDER BY
    table_name,
    ordinal_position
  '

This is useful because the schema itself reflects the measurements I wanted to preserve.

For example, brand_observations contains separate fields for:

mentioned
mention_count
first_mention_position

retrieved
best_retrieval_position

recommended
recommendation_position

cited
citation_urls
citation_domains

That was deliberate.

I wanted to store what actually happened before reducing everything to a single visibility number.

Query recent visibility scans

The first operational query I usually run is simple:

Show me the latest scans

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    scan_id,
    batch_id,
    project_id,
    brand_id,
    brand_name_snapshot,
    prompt_id,
    model_name,
    location_snapshot,
    started_at,
    completed_at,
    status,
    duration_seconds
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.visibility_scans`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  ORDER BY
    started_at DESC
  LIMIT 20
  '

Recent AI visibility scans queried directly from BigQuery using the bq CLI.

The time filter is important.

My visibility tables are partitioned by started_at, and I intentionally require partition filtering rather than allowing unrestricted scans over the complete history.

That becomes increasingly useful as the amount of historical data grows.

From this one query I can inspect:

which scan ran
which batch it belonged to
which brand was evaluated
which prompt triggered it
which Gemini model was used
which location context was applied
when the scan started and completed
whether it succeeded
how long it took

The dashboard gives me the visualization.

BigQuery gives me the underlying record.

Step 6: Mentioned is not the same as recommended

This became one of the most important distinctions in V3.

A brand can appear in an AI-generated result in several different ways.

It might be:

retrieved
mentioned
recommended
cited
ranked before or after another brand

Those are not the same thing.

Let's consider these two observations:

retrieved = true
mentioned = true
recommended = false
cited = true

and

retrieved = true
mentioned = true
recommended = true
cited = true

Both brands were visible.

But they were not visible in the same way.

The first brand was discovered and mentioned.

The second made it into the recommendation.

Instead of asking Gemini to generate a vague visibility score, I first persist these observable states.

I can inspect them directly:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    scan_id,
    brand_id,
    role,
    mentioned,
    mention_count,
    first_mention_position,
    retrieved,
    best_retrieval_position,
    recommended,
    recommendation_position,
    cited,
    citation_domains
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.brand_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  ORDER BY
    started_at DESC,
    scan_id,
    first_mention_position
  LIMIT 50
  '

I can ask:

Was the brand retrieved?

Was it mentioned?

Where did the first mention occur?

Was it actually recommended?

At what recommendation position?

Was there citation evidence associated with it?

Those questions are much easier to reason about than:

visibility_score = 74

without knowing why the score is 74.

Step 7: Aggregate visibility across repeated scans

Once multiple scans exist, SQL becomes even more useful.

For example, I can ask:

How often does each brand appear, get recommended, or receive citation support?

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    brand_id,
    COUNT(*) AS observations,
    COUNTIF(mentioned) AS mentioned_count,
    COUNTIF(retrieved) AS retrieved_count,
    COUNTIF(recommended) AS recommended_count,
    COUNTIF(cited) AS cited_count,
    ROUND(
      SAFE_DIVIDE(COUNTIF(mentioned), COUNT(*)) * 100,
      2
    ) AS mention_rate_pct,
    ROUND(
      SAFE_DIVIDE(COUNTIF(recommended), COUNT(*)) * 100,
      2
    ) AS recommendation_rate_pct
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.brand_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  GROUP BY
    brand_id
  ORDER BY
    recommendation_rate_pct DESC,
    mention_rate_pct DESC
  '

Now I am no longer asking only:

What did Gemini answer?

I can ask:

Across repeated grounded search journeys, which brands keep appearing?

That is a very different problem.

And it is where V3 started becoming an analytics system rather than only a search demo.

Aggregating brand mentions, retrievals, recommendations, and citations across repeated scans

Let's be on the same page.

Position matters too
Presence alone is not enough.

A brand appearing first in an answer is different from appearing sixth.

That is why V3 also preserves:

first_mention_position
best_retrieval_position
recommendation_position

I can analyze those separately:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    brand_id,
    COUNTIF(mentioned) AS mentions,
    ROUND(AVG(first_mention_position), 2) AS avg_first_mention_position,
    COUNTIF(recommended) AS recommendations,
    ROUND(AVG(recommendation_position), 2) AS avg_recommendation_position,
    ROUND(AVG(best_retrieval_position), 2) AS avg_best_retrieval_position
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.brand_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  GROUP BY
    brand_id
  ORDER BY
    recommendations DESC,
    avg_recommendation_position ASC
  '

This lets me separate several ideas that often get grouped together as AI visibility:

Presence
Position
Retrieval
Recommendation
Citation

I find that separation much more useful.

Step 8: Look inside query fan-out

One thing I learned while building the earlier versions of this project is that the final answer hides a lot of interesting behavior.

A single user query can create several retrieval tasks.

For example:

User prompt
    │
    ├── search intent A
    ├── search intent B
    ├── search intent C
    └── search intent D

A brand may appear in all four branches.

Or only one.

Those situations should not necessarily be treated as identical.

That is why V3 persists fanout_observations.

The table includes fields such as:

task_id
query_text
tool
brand_id
brand_found
position_in_task

I can inspect those observations directly:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    scan_id,
    prompt_id,
    task_id,
    query_text,
    tool,
    brand_id,
    brand_found,
    position_in_task
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.fanout_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  ORDER BY
    started_at DESC,
    scan_id,
    task_id,
    position_in_task
  LIMIT 100
  '

Now the intermediate journey becomes queryable:

Original prompt
      ↓
Fan-out task
      ↓
Generated query
      ↓
Retrieval tool
      ↓
Brand found?
      ↓
Position in task

This gives me a way to investigate why one brand appears repeatedly while another does not.

Measure fan-out coverage

I can also aggregate the fan-out behavior.

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    brand_id,
    COUNT(DISTINCT task_id) AS fanout_tasks,
    COUNTIF(brand_found) AS observations_where_brand_was_found,
    ROUND(
      SAFE_DIVIDE(
        COUNTIF(brand_found),
        COUNT(*)
      ) * 100,
      2
    ) AS found_rate_pct
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.fanout_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  GROUP BY
    brand_id
  ORDER BY
    found_rate_pct DESC
  '

I think of this as a project-specific fan-out coverage signal.

It is not intended to be a universal AI visibility metric.

It simply tells me how consistently a brand was found across the retrieval observations generated by this implementation.

Being explicit about that distinction matters.

Step 9: Make citation visibility queryable

Mentions are useful.

Recommendations are useful.

But I also wanted to understand the evidence behind the grounded answer.

So citations are persisted separately.

The citations table contains:

scan_id
project_id
prompt_id
started_at
url
domain
source_type
matched_brand_ids

I can inspect the underlying evidence directly:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    scan_id,
    prompt_id,
    domain,
    source_type,
    url,
    matched_brand_ids
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.citations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  ORDER BY
    started_at DESC
  LIMIT 100
  '

This leads to another interesting question:

Which domains repeatedly appear as supporting sources?

That gives me another dimension of AI visibility.

Instead of only asking:

Was my brand mentioned?

I can also ask:

Which sources repeatedly support grounded answers?

Which domains are connected to particular brands?

Which sources appear across multiple scans?

For me, that makes citation analysis one of the more interesting parts of V3.

Working with repeated fields in BigQuery

matched_brand_ids is stored as an ARRAY<STRING>.

BigQuery makes it straightforward to expand that repeated field using UNNEST.

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    matched_brand_id AS brand_id,
    domain,
    COUNT(*) AS citation_count
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.citations`,
    UNNEST(matched_brand_ids) AS matched_brand_id
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  GROUP BY
    matched_brand_id,
    domain
  ORDER BY
    citation_count DESC
  LIMIT 50
  '

That connects two useful concepts:

Brand visibility
        +
Citation visibility

A brand may appear frequently but have relatively little citation support.

Another may appear less often but repeatedly connect to a particular set of sources.

Persisting both lets me investigate that difference instead of hiding it inside one aggregate score.

Step 10: Turn visibility into a historical signal

The reason I chose BigQuery was not just to persist individual runs.

The real value appears when the same measurements accumulate over time.

For example, I can calculate daily visibility observations:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    DATE(started_at) AS scan_date,
    brand_id,
    COUNT(*) AS observations,
    COUNTIF(mentioned) AS mentions,
    COUNTIF(recommended) AS recommendations,
    COUNTIF(cited) AS citations,
    ROUND(
      SAFE_DIVIDE(COUNTIF(mentioned), COUNT(*)) * 100,
      2
    ) AS mention_rate_pct,
    ROUND(
      SAFE_DIVIDE(COUNTIF(recommended), COUNT(*)) * 100,
      2
    ) AS recommendation_rate_pct
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.brand_observations`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  GROUP BY
    scan_date,
    brand_id
  ORDER BY
    scan_date DESC,
    brand_id
  '

Now the system evolves from:

Search Journey
      ↓
One Answer

into:

Search Journey
      ↓
Repeated Scans
      ↓
Persisted Observations
      ↓
Historical Visibility

That historical layer is what I was missing in the first versions of the project.

A single answer can tell me what happened now.

A history can start telling me what keeps happening.

Step 11: The scan itself is also observable

Another useful part of the schema is that visibility_scans does not only record the result.

It also records operational information such as:

started_at
completed_at
status
duration_seconds
error_code
error_message

That means I can inspect the behavior of the visibility pipeline itself.

For example:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    status,
    COUNT(*) AS scans,
    ROUND(AVG(duration_seconds), 2) AS avg_duration_seconds,
    ROUND(MAX(duration_seconds), 2) AS max_duration_seconds
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.visibility_scans`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  GROUP BY
    status
  ORDER BY
    scans DESC
  '

And I can inspect unsuccessful runs separately:

bq query \
  --use_legacy_sql=false \
  --format=pretty \
  '
  SELECT
    scan_id,
    brand_name_snapshot,
    prompt_text_snapshot,
    model_name,
    started_at,
    status,
    error_code,
    error_message
  FROM
    `ai-search-journey-lab.ai_search_journey_v3.visibility_scans`
  WHERE
    started_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
    AND status != "completed"
  ORDER BY
    started_at DESC
  LIMIT 25
  '

This distinction became useful later when I added deeper observability to the project.

There are really two different things I want to observe:

What did the AI search journey produce?

and

How did the system behave while producing it?

V3 primarily focuses on the first.

Later versions go much deeper into the second.

Step 12: Keep BigQuery as the analytical source of truth

At this point, the V3 architecture became much clearer to me.

                    AI Visibility Scan
                           │
                           ▼
                 Gemini + Search Grounding
                           │
                           ▼
                    Evidence Extraction
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        Brand          Fan-out       Citation
      Observation    Observation     Evidence
              │            │            │
              └────────────┼────────────┘
                           │
                           ▼
                        BigQuery
                           │
                 ┌─────────┴─────────┐
                 ▼                   ▼
          Streamlit Dashboard    SQL Analysis
                 │                   │
                 └─────────┬─────────┘
                           ▼
                Historical Visibility

BigQuery gives me an independent analytical layer.

That means I can:

validate what the dashboard shows
write new analytical queries without changing the UI
compare historical runs
inspect fan-out behavior
study citation sources
later expose the same evidence to an agent

That last part becomes important in V4.

Step 13: Validate the implementation, not just the demo

I try not to treat a working Streamlit page as proof that the underlying application is healthy.

Before considering a milestone complete, I run the repository checks together.

./.venv/bin/ruff check . && \
./.venv/bin/mypy src && \
./.venv/bin/pytest -q

At the time of this build, the repository validation looked like:

ruff
All checks passed!

mypy
Success: no issues found in 38 source files

pytest
382 passed

The exact number of tests will naturally change as the project continues to grow.

What matters more to me is keeping the same habit:

Build
  ↓
Run
  ↓
Inspect
  ↓
Test
  ↓
Then extend

That has become especially important as this project has expanded from one search workflow into multiple versions with analytics, agents, and observability.

From analytics to an agent

Once V3 was working, I found myself doing something repeatedly.

I would open the dashboard.

Then I would run a BigQuery query.

Then another.

Then I would compare brands.

Then citation domains.

Then fan-out behavior.

Eventually the next question became obvious:

What if I could ask an agent questions about this visibility history instead of manually writing every query?

But I did not want an unconstrained agent with arbitrary access to the analytics store.

I wanted something much more controlled:

User question
      ↓
Gemini
      ↓
Google ADK Agent
      ↓
Approved tools
      ↓
MCP
      ↓
BigQuery visibility history
      ↓
Grounded analytical answer

That became V4.

And it introduced a different engineering problem:

How do I give an AI agent useful access to analytics while keeping its capabilities explicit, inspectable, and constrained?

That is where I go next.

Next: Building an AI Visibility Agent with Gemini, Google ADK, MCP, and BigQuery

In Part 4, I take the visibility history created in V3 and put an agent in front of it.

The focus will be on:

Gemini for reasoning
Google ADK for agent orchestration
MCP for tool access
BigQuery as the visibility data source
explicit read-only analytical boundaries
tool-call visibility
handling unsupported questions
keeping deterministic data access separate from model reasoning

The goal is not to add a chatbot on top of a dashboard.

The goal is to build an agent that can investigate the evidence already produced by the system.

Building Grounded Local Search with Gemini and Google Maps on Google Cloud

Hastimal Jangid — Tue, 29 Sep 2026 04:09:07 +0000

AI Search Journey Lab — Part 2 of 7

Building a grounded local-search workflow with Gemini, Google Places API (New), Google Search grounding, deterministic ranking, Maps links, and Cloud Run.

Open source: ai-search-journey-lab

Previous article: Search Journey Optimization with Gemini: From Query Fan-Out to Grounded Decisions

In Part 1, I explained the journey. In Part 2, I want to show the implementation.

In the first article, I focused on the architecture behind a search journey:

intent → query fan-out → retrieval → evidence → deduplication → ranking → grounded answer

That was the conceptual layer.

This article is more practical.

I want to show how I built the actual local-search workflow behind that architecture using:

Gemini
Google Places API (New)
Google Search grounding
Google Maps links
deterministic ranking
Python
Streamlit
Cloud Run

The original demo query is still the same:

Find a coffee shop near Geekdom in San Antonio for six people, quiet enough to work, open after 8 PM, and recommend the top three.

The difference now is that I want to focus on what happens after the intent has been understood.

The local-search problem is really two retrieval problems
When I first started implementing this workflow, I realized that one retrieval system was not enough.

Some constraints are structured.

For example:

business name
address
rating
review count
opening hours
Place ID
Maps URL

Google Places is a very good fit for those.

But some user requirements are much softer:

quiet enough to work
suitable for a group
good vegetarian options
comfortable for studying
appropriate for a child who is anxious about dental visits

Those do not always map cleanly to one structured field.

That led me to split retrieval into two paths:

Google Places for structured local data

and

Google Search grounding for additional evidence

That separation is at the heart of this article.

The architecture

The V1 flow for grounded local search looks like this:

User Query → Gemini Intent → Query Fan-Out → Places API + Google Search Grounding → Normalize → Evidence → Score → Gemini Synthesis → Maps-linked Recommendations

Step 1: Start from structured intent

I do not call Places directly with the full user prompt.

First, I want a structured representation of what the user is asking for.

Conceptually:

{
  "category": "coffee_shop",
  "location_reference": "Geekdom, San Antonio",
  "party_size": 6,
  "open_after": "20:00",
  "preferences": [
    "quiet",
    "work-friendly"
  ],
  "result_count": 3
}

The important thing here is that the retrieval layer no longer has to interpret every phrase from scratch.

Gemini handles the language ambiguity.

The application gets a predictable structure.

Step 2: Turn intent into retrieval tasks

Once I have the intent, I generate a bounded retrieval plan.

A simplified example might look like:

{
  "places_tasks": [
    {
      "query": "coffee shops near Geekdom San Antonio"
    },
    {
      "query": "work-friendly coffee shops downtown San Antonio"
    }
  ],
  "search_tasks": [
    {
      "query": "coffee near Geekdom quiet work open late"
    }
  ]
}

I deliberately keep this small.

The goal is not to generate ten variants of the same search.

The goal is to cover enough of the user's intent without creating unnecessary duplication and latency.

Step 3: Google Places becomes the structured candidate source

For local search, Google Places API (New) gives me the first candidate set.

A simplified Text Search call looks like this:

import requests


def search_places(query: str, api_key: str) -> list[dict]:
    endpoint = "https://places.googleapis.com/v1/places:searchText"

    payload = {
        "textQuery": query,
        "pageSize": 10,
    }

    headers = {
        "Content-Type": "application/json",
        "X-Goog-Api-Key": api_key,
        "X-Goog-FieldMask": ",".join(
            [
                "places.id",
                "places.displayName",
                "places.formattedAddress",
                "places.rating",
                "places.userRatingCount",
                "places.currentOpeningHours",
                "places.googleMapsUri",
            ]
        ),
    }

    response = requests.post(
        endpoint,
        json=payload,
        headers=headers,
        timeout=20,
    )

    response.raise_for_status()

    return response.json().get("places", [])

What matters most to me here is not the HTTP request itself.

It is the set of fields that become available to downstream logic.

I use field masks intentionally

For this workflow, I do not need every possible field.

I only want the fields that are useful for the decision.

For example:

places.id
places.displayName
places.formattedAddress
places.rating
places.userRatingCount
places.currentOpeningHours
places.googleMapsUri

This keeps the retrieval boundary explicit.

It also makes it easier to understand which parts of the final recommendation came directly from Places data.

Step 4: Place ID becomes the anchor for identity

One thing I did not appreciate enough at the beginning was how important entity identity would become.

Suppose two fan-out tasks return the same business.

Without normalization, I might end up with:

Candidate A
Candidate A
Candidate B
Candidate C

That creates a ranking problem.

So I use a canonical identifier such as Place ID to determine whether I am looking at the same entity.

A simplified deduplication step looks like:

def deduplicate_places(candidates: list[dict]) -> list[dict]:
    unique: dict[str, dict] = {}

    for candidate in candidates:
        place_id = candidate["place_id"]

        if place_id not in unique:
            unique[place_id] = candidate
            continue

        unique[place_id] = merge_candidate(
            unique[place_id],
            candidate,
        )

    return list(unique.values())

The order matters:

retrieve → normalize identity → deduplicate → rank

NOT

retrieve → rank duplicates → fix identity later

Step 5: Generate Google Maps links as part of the decision output

One thing I wanted from the beginning was that the recommendation should not end as plain text.

If the user asks for a local business, the result should be actionable.

That is why I keep the Google Maps URI returned by Places.

Conceptually:

candidate = {
    "name": place["displayName"]["text"],
    "address": place["formattedAddress"],
    "rating": place.get("rating"),
    "maps_url": place.get("googleMapsUri"),
}

Then the final recommendation can give the user a direct route from:

AI recommendation

Google Maps

That sounds small, but it changes the experience from “read an AI answer” to “act on an AI answer.”

Step 6: Places alone did not solve the problem

Now we reach the interesting part.

Google Places can tell me:

the business exists
where it is
its rating
its opening hours
its Maps URL

But the original user also asked for:

quiet enough to work

That is a different class of requirement.

There may not be a clean structured field for it.

So I added a second evidence path using Google Search grounding.

Step 7: Ground the softer constraints

I do not ask Gemini a broad question like:

Is this coffee shop suitable?

I make the verification task more specific.

For example:

Candidate:
Example Coffee

Verify:
1. evidence that it is open late
2. evidence relevant to working/studying
3. evidence relevant to seating/group suitability

For each constraint:
- supported
- unsupported
- supporting evidence
- citation

Conceptually, the call sits behind a workflow stage like:

with trace_span(
    "search_grounding.verify_evidence",
    attributes={"workflow.stage": "v1"},
):
    evidence = verify_candidates(
        candidates=candidates,
        intent=intent,
    )

This gives me a richer candidate representation.

A candidate now has two kinds of evidence

Conceptually:

{
  "place_id": "abc123",
  "name": "Example Coffee",
  "places": {
    "rating": 4.6,
    "review_count": 825,
    "open_after_8": true
  },
  "search_evidence": {
    "work_friendly": true,
    "group_suitability": null
  }
}

That null is useful.

If I cannot verify group suitability, I do not want the system to quietly convert uncertainty into confidence.

That is one of the most important lessons I took from this build:

Unsupported should remain unsupported.

Step 8: I keep evidence matching separate from synthesis

Another decision I made was to avoid letting the final LLM call discover and interpret everything again from scratch.

By the time Gemini reaches the final synthesis stage, the system already has:

structured intent
candidate identities
Places data
grounded Search evidence
unsupported constraints
scores
rank order

This makes the final prompt much narrower.

Step 9: Deterministic ranking before final synthesis

I deliberately keep ranking outside Gemini.

A simplified workflow looks like:

with trace_span(
    "evidence.aggregate_and_score",
    attributes={"workflow.stage": "v1"},
):
    ranked_candidates = aggregate_and_score(
        candidates=candidates,
        evidence=evidence,
        intent=intent,
    )

The scoring logic can consider signals such as:

location relevance
category match
opening-hour compatibility
rating
rating count
constraint coverage
grounded evidence
unsupported constraints

The point is not that one universal formula can rank every local-search problem.

The point is that the system can explain why one candidate scored higher than another.

def build_static_map_url(
    ranked_candidates: list[RankedCandidate],
    *,
    api_key: Optional[str] = None,
    max_candidates: int = 3,
    width: int = 640,
    height: int = 360,
    maptype: str = "roadmap",
) -> str:
    """Build a Google Maps Static API URL for the top ranked candidates.

    Args:
        ranked_candidates: List of ranked candidates.
        api_key: Optional Google Maps API Key override.
        max_candidates: Maximum candidate markers to place (default: 3).
        width: Image width in pixels (default: 640).
        height: Image height in pixels (default: 360).
        maptype: Map type (default: 'roadmap').

    Returns:
        Fully-formed Static Maps URL including API key.

    Raises:
        ValueError: If GOOGLE_MAPS_API_KEY is not configured or no valid coordinates exist.
    """
    result = generate_static_map(
        ranked_candidates,
        api_key=api_key,
        max_candidates=max_candidates,
        width=width,
        height=height,
        maptype=maptype,
    )
    return result.url

View the complete scoring implementation on GitHub

Step 10: Gemini handles the final explanation

Gemini comes back near the end.

Conceptually:

with trace_span(
    "gemini.synthesize_recommendations",
    attributes={"workflow.stage": "v1"},
):
    answer = synthesize_recommendations(
        intent=intent,
        ranked_candidates=ranked_candidates,
    )

By this point, Gemini is not being asked to search the world.

It is being asked to explain a decision whose evidence is already available.

That is a much smaller and more controllable problem.

What the final answer should contain

For each recommendation, I want the output to include useful decision context.

For example:

1. Example Coffee
   Rating: 4.6
   Open after 8 PM: Yes
   Work-friendly evidence: Supported
   Group suitability: Not fully verified
   Maps: [Open in Google Maps]

That is much more useful than:

“I recommend Example Coffee because it looks great.”

Step 11: Validate the architecture with another query

I did not want the workflow to work only for the one query it was designed around.

So I also tested:

Find an Indian restaurant near Trinity University for eight students, open after 9 PM, with vegetarian options. Recommend the top three.

This changes several constraints:

category
geographic anchor
party size
hours
dietary preference

But the architecture stays the same.

That is important.

I want a reusable search workflow, not a prompt-specific demo.

Step 12: Test the workflow like normal software

I keep normal engineering checks around the AI workflow.

My standard validation is:

./.venv/bin/ruff check .
./.venv/bin/mypy src
./.venv/bin/pytest -q

The point is simple:

Gemini does not eliminate the need for testable software.

If anything, combining model behavior with APIs, ranking logic, state, and deployment makes testing more important.

Step 13: Run the same workflow on Cloud Run

Once the local implementation was stable, I deployed the same application to Cloud Run.

That gave me a clean path from local development to a hosted demo.

You can inspect the service with:

gcloud run services describe ai-search-journey-lab \
  --region us-central1 \
  --format="yaml(
      metadata.name,
      status.url,
      status.latestReadyRevisionName,
      status.conditions
  )"

And verify health:

curl -fsS \
"https://ai-search-journey-lab-642110324230.us-central1.run.app/_stcore/health"

Let's run locally!

Let's run the same Geekdom query from the deployed Google cloud service.

What I learned from building the local-search layer

The biggest lesson was that local AI search is not just:

prompt → model → answer

It is closer to:

natural-language intent → retrieval plan → entity search → evidence search → identity normalization → constraint verification → deterministic ranking → grounded explanation → actionable Maps result

That distinction is important.

Because once the application has multiple evidence sources and multiple ranking signals, the LLM becomes one component in the system rather than the entire system.

That is the architecture I wanted.

Why this matters for agentic systems

This local-search workflow also became a useful foundation for the later agent work in the repository.

Once the system already has:

structured intent
tools
explicit retrieval
evidence
state
ranking
bounded outputs

it becomes much easier to add agent orchestration later.

That is where Google ADK eventually enters the story in Part 4.

But I deliberately did not start there.

I first wanted a workflow I could understand without an agent.
Then I could add the agent layer intentionally.

Next: Building an AI Search Visibility & Brand Analyzer with Gemini, BigQuery, and Google Search Grounding

In the next article, I will move from:

Which business should this user consider?

to:

How visible is a brand across AI-generated search journeys?

I will cover:

target brands
competitors
visibility runs
mentions
citations
fan-out coverage
deterministic visibility analysis
BigQuery history
visibility trends

Try the project

Repository: GitHub Repository

Local startup:

python scripts/run_app_locally.py

Search Journey Optimization with Gemini: From Query Fan-Out to Grounded Decisions

Hastimal Jangid — Mon, 28 Sep 2026 21:29:53 +0000

AI Search Journey Lab — Part 1 of 7

Building an explainable search-to-decision workflow with Gemini, Google Places, Google Search grounding, deterministic ranking, and Google Cloud.

Open source: ai-search-journey-lab

It started with one search query
I started ai-search-journey-lab with a question that looked simple enough:

Find a coffee shop near Geekdom in San Antonio for six people, quiet enough to work, open after 8 PM, and recommend the top three.

At first, I thought of it as a local-search problem.

Then I started implementing it.

Almost immediately, that single sentence turned into several separate engineering problems.

I needed to understand what the user actually meant by “near Geekdom.” I needed to capture the group size. I needed opening hours. I needed to find places that might actually work for six people sitting together.

Then there was the phrase:

quiet enough to work

That is where things became more interesting.

A structured Places response can give me things like an address, rating, hours, and a Place ID.

But “quiet enough to work” is not simply another field I can request.

So now I needed both structured place data and additional evidence.

Then, once I started generating more than one retrieval query, another problem appeared: the same place could be returned by multiple searches.

That meant I also needed:

candidate normalization,
deduplication,
evidence matching,
scoring,
ranking,
and finally, a way to explain why one candidate beat another.

Oh gosh..It's getting a lot!!

At that point, I wasn't building a “send a prompt to Gemini and print the answer” application anymore.

I was building a search journey. (and later think about search journey optimization!)

And that became the idea behind AI Search Journey Lab.

AI Search Journey Lab: one project, seven engineering stages

This is the first article in a seven-part series built from the same open-source repository.

I wanted the series to follow the way the project itself evolved instead of creating seven unrelated AI demos.

The topics are also centered around the problems I am most interested in as a Google Cloud and AI developer: grounding, search behavior, data, agents, observability, and production deployment.

Search Journey Optimization with Gemini: From Query Fan-Out to Grounded Decisions (this article)
Building Grounded Local Search with Gemini and Google Maps on Google Cloud
Building an AI Search Visibility & Brand Analyzer with Gemini, BigQuery, and Google Search Grounding
Building an AI Visibility Agent with Gemini, Google ADK, MCP, and BigQuery
From Query Fan-Out to Trace: Observing AI Search Journeys with OpenTelemetry
Building AgentOps for Gemini Agents with Grafana, Tempo, and Prometheus
From Search to Care: Applying Gemini Search Journeys to Healthcare Discovery

The progression looks roughly like this:

search journey → grounded retrieval → visibility measurement → agentic analytics → tracing → AgentOps → healthcare application

My goal with the series is not just to show what Gemini can generate.

I want to show how the pieces around the model matter just as much: APIs, deterministic logic, persistence, tools, traces, tests, and deployment.

Starting from the actual problem

Let's go back to the original request:

Find a coffee shop near Geekdom in San Antonio for six people, quiet enough to work, open after 8 PM, and recommend the top three.

From an application perspective, that contains several different constraints:

category: coffee shop
geographic anchor: Geekdom
location: San Antonio
party size: six
operating-hours requirement: open after 8 PM
qualitative preference: quiet/work-friendly
result count: three

And not all of those constraints should be handled the same way.

For example:

Opening hours can often come from structured place data.
Quiet enough to work may require additional evidence.

That distinction ended up shaping most of the architecture.

The architecture decision that mattered most

One decision influenced almost everything that came afterward:

I did not want Gemini to own the entire workflow.

It would have been very easy to send the whole prompt to a model and ask:

Find the best three places and explain why.

That would certainly produce an answer.

But it would make several things harder for me:

understanding which constraints were actually verified,
seeing where candidates came from,
knowing why something ranked highly,
reproducing a decision,
debugging wrong answers,
and eventually tracing the system.

So I divided the workflow into three responsibilities.

Gemini reasoning
I use Gemini where natural-language interpretation is valuable:

intent extraction,
planning,
query fan-out,
final response synthesis.

Retrieval
I use external data sources for evidence:

Google Places API (New),
Google Search grounding.

Deterministic application logic
I keep things such as these in normal application code:

normalization,
entity matching,
deduplication,
evidence aggregation,
scoring,
ranking.

That gave me a much more inspectable pipeline.

Running the project

I normally start the local environment with:

python scripts/run_app_locally.py

As the project evolved, I added observability components as well, so the local startup script eventually became responsible for more than just Streamlit.

For this article, though, I am concentrating on two parts:

V1 — Search to Decision
V2 — Journey Analysis

The later articles will move into visibility, agents, and observability.

Step 1: I first turn the prompt into structured intent

Before I search for anything, I need to understand what the request actually contains.

Conceptually, the Geekdom query becomes something like:

{
  "category": "coffee_shop",
  "location_reference": "Geekdom, San Antonio",
  "party_size": 6,
  "open_after": "20:00",
  "preferences": [
    "quiet",
    "work-friendly"
  ],
  "result_count": 3
}

The important part here is not the JSON.

It is the boundary between language and application state.

People do not normally talk in schemas.

A user might say:

Somewhere close to Geekdom. We have six people, don't want somewhere too loud, and we'll probably stay late.

The application still needs to understand:

{
  "party_size": 6,
  "noise_preference": "quiet",
  "minimum_close_time": "20:00"
}

That is a good job for Gemini.

The model interprets the language.

My application controls the structure.

A typed intent model

Since I am more into development and technical architecture role, I prefer moving the result into a typed object rather than passing free-form model text deeper into the workflow.

A simplified version looks like this:

from pydantic import BaseModel, Field


class SearchIntent(BaseModel):
    category: str
    location_reference: str
    party_size: int | None = None
    open_after: str | None = None
    preferences: list[str] = Field(default_factory=list)
    result_count: int = 3

That gives me a cleaner boundary:

Natural-language request → Gemini interpretation → Structured application state

From this point forward, the rest of the pipeline has something predictable to work with.

I also made this a real workflow boundary

I didn't want intent extraction buried somewhere inside one large function.

I gave the stage its own observable boundary.

Conceptually:

with trace_span(
    "gemini.extract_intent",
    attributes={"workflow.stage": "v1"},
):
    intent = extract_intent(user_query)

That may look like a small detail here.

It became much more useful later when I added OpenTelemetry.

A lesson I learned while building this project was:

Good architecture boundaries often become good observability boundaries later.

As you run locally, it should open in http://localhost:8502/

Let's see the journey now and wait to trace the results!

Step 2: One prompt becomes several retrieval tasks

Once I knew what the user wanted, I ran into the next question:

What exactly should I search for?

Using the complete user sentence as one search query would throw many different requirements into the same retrieval call.

Instead, I started decomposing the request into a small retrieval plan.

A simplified fan-out might look like:

Places task:

coffee shops near Geekdom San Antonio

Places task:

work-friendly coffee shops near downtown San Antonio

Search evidence task:

coffee near Geekdom quiet work open late

In the project, I treat that planning step separately:

with trace_span(
    "gemini.plan_fan_out",
    attributes={"workflow.stage": "v1"},
):
    fanout_plan = plan_fan_out(intent)

This is the part I refer to as query fan-out.

One user's decision question becomes multiple narrower retrieval tasks.

I learned quickly that more queries are not automatically better

Initially, fan-out sounds like a simple idea:

If one query is useful, several queries should be better.

But that creates its own problems.

Imagine generating all of these:

coffee near Geekdom
quiet coffee near Geekdom
coffee for six near Geekdom
coffee with large tables near Geekdom
coffee open after 8 near Geekdom
coffee good for working near Geekdom
late-night coffee downtown San Antonio

Now I have:

more requests,
more latency,
more overlapping results,
more duplicates,
more evidence to reconcile,
and more opportunities for noisy candidates.

The opposite extreme is also bad:

coffee near Geekdom

because most of the intent has disappeared.

So query fan-out became an optimization problem of its own:

Generate enough retrieval tasks to cover the user's important constraints without turning the workflow into uncontrolled query expansion.

That is a much more interesting problem than simply asking a model to generate ten related searches.

Step 3: Google Places gave me the structured candidate layer

Once I had the fan-out plan, I needed actual entities.

For the local-search portion of the workflow, that meant Google Places API (New).

This gave me structured information such as:

Place ID,
business name,
address,
rating,
number of ratings,
opening information,
and Maps URLs.

A simplified retrieval call looks like this:

import requests


def search_places(query: str, api_key: str) -> list[dict]:
    endpoint = "https://places.googleapis.com/v1/places:searchText"

    payload = {
        "textQuery": query,
        "pageSize": 10,
    }

    headers = {
        "Content-Type": "application/json",
        "X-Goog-Api-Key": api_key,
        "X-Goog-FieldMask": ",".join(
            [
                "places.id",
                "places.displayName",
                "places.formattedAddress",
                "places.rating",
                "places.userRatingCount",
                "places.currentOpeningHours",
                "places.googleMapsUri",
            ]
        ),
    }

    response = requests.post(
        endpoint,
        json=payload,
        headers=headers,
        timeout=20,
    )

    response.raise_for_status()

    return response.json().get("places", [])

This is intentionally simplified for the article.

In the repository, there is additional application logic around the retrieval and candidate handling.

Place ID turned out to be more important than I expected

At first I was mostly interested in ratings, addresses, and opening hours.

Once fan-out was involved, identity became equally important.

Suppose two searches produce:

Merit Coffee

and

Merit Coffee — Southtown

String matching alone is not a great basis for deciding whether I have one business or two.

Using a canonical identifier such as Place ID gives me a stronger entity boundary.

That became important almost immediately when I started combining results from multiple retrieval tasks.

Step 4: Places could not answer everything

This is where the system became more than a Places demo.

The API can tell me a lot about a place.

But look again at part of the original requirement:

quiet enough to work

That is not the same kind of data as:

rating = 4.6

or:

open until 10 PM

The same problem appears in other searches:

good for a large student group

strong vegan options

suitable for someone with a specific preference

These are softer constraints.

I needed another evidence path.

Step 5: I added Google Search grounding for the missing evidence

Rather than asking Gemini:

Is this place good for working?

I wanted the system to investigate specific claims.

For example:

Candidate: Example Coffee

Verify:
- late-hour availability
- evidence relevant to working/studying
- evidence relevant to group seating

For each constraint:
- supported
- unsupported
- evidence
- citation

Conceptually, that stage looks like:

with trace_span(
    "search_grounding.verify_evidence",
    attributes={"workflow.stage": "v1"},
):
    evidence = verify_candidates(
        candidates=candidates,
        intent=intent,
    )

This gave me two different types of evidence:

Google Places + Search-grounded evidence

I wanted to preserve that distinction instead of blending everything together.

If operating hours come from Places, I should know that.

If “work-friendly” comes from grounded Search evidence, I should know that too.

And if I cannot verify something, I want the system to keep that state visible.

Step 6: Fan-out created a duplicate problem

Once I started running multiple Places tasks, something predictable happened:

the same business started appearing more than once.

For example:

Places task A ───────┐
                     ├── Candidate X
Places task B ───────┘

If I ranked those raw results directly, Candidate X could appear stronger simply because more than one retrieval task discovered it.

That is not relevance.

That is duplication.

So I introduced normalization and deduplication before scoring.

A simplified form is:

def deduplicate_places(candidates: list[dict]) -> list[dict]:
    unique: dict[str, dict] = {}

    for candidate in candidates:
        place_id = candidate["place_id"]

        if place_id not in unique:
            unique[place_id] = candidate
            continue

        unique[place_id] = merge_candidate(
            unique[place_id],
            candidate,
        )

    return list(unique.values())

The sequence matters:

retrieve → normalize → deduplicate → score

I specifically did NOT want:

retrieve → score duplicates → fix identity afterward

V2 made this problem visible

For Journey Analysis, I used another demo query:

Find an Indian restaurant near Trinity University for eight students, open after 9 PM, with vegetarian options. Recommend the top three.

One of my representative executions produced:

Places tasks                     2
Raw Places results              20
Unique Places candidates        13

Search tasks                     2

Candidates with Search evidence  3
Places-only candidates          10
Unmatched evidence               8

That was a useful moment in the project.

Instead of asking only:

What are the top three restaurants?

I could now ask:

What actually happened during retrieval?

That became the purpose of V2 — Journey Analysis.

Step 7: Retrieval and ranking are not the same thing

This sounds obvious, but it became an important rule in my implementation.

Retrieval asks:

Which candidates might be relevant?

Ranking asks:

Which of those candidates best satisfies the original constraints?

A candidate should not rank higher simply because two fan-out queries happened to retrieve it.

And the highest-rated business should not automatically win if it fails an important constraint such as opening hours.

So after deduplication, I aggregate the evidence and score candidates explicitly.

Step 8: I keep ranking outside the LLM

This was another decision I made deliberately.

I did not want this architecture:

Retrieve 10 places
       ↓
Send all 10 to Gemini
       ↓
"Pick the best three"

That would give me an answer.

But it would make one of the most important decisions in the system opaque.

Instead, I keep the ranking logic inspectable in application code.

Depending on the workflow, signals can include things like:

location relevance,
category match,
operating-hour compatibility,
rating,
review volume,
constraint coverage,
grounded evidence,
unsupported constraints.

Conceptually:

with trace_span(
    "evidence.aggregate_and_score",
    attributes={"workflow.stage": "v1"},
):
    ranked_candidates = aggregate_and_score(
        candidates=candidates,
        evidence=evidence,
        intent=intent,
    )

The important property here is not one universal scoring formula.

It is that I can inspect why a candidate received its score.

def calculate_haversine_distance_miles(
    lat1: float,
    lon1: float,
    lat2: float,
    lon2: float,
) -> float:
    """Calculate the great circle distance in miles between two latitude/longitude points."""
    r_earth = 3958.8  # Earth radius in miles
    d_lat = math.radians(lat2 - lat1)
    d_lon = math.radians(lon2 - lon1)
    a = (
        math.sin(d_lat / 2.0) ** 2
        + math.cos(math.radians(lat1))
        * math.cos(math.radians(lat2))
        * math.sin(d_lon / 2.0) ** 2
    )
    c = 2.0 * math.atan2(math.sqrt(a), math.sqrt(1.0 - a))
    return round(r_earth * c, 2)


def calculate_proximity_score(distance_miles: float) -> float:
    """Calculate smooth bounded proximity bonus from distance in miles (max 12.0 pts).

    Formula: bonus = MAX_PROXIMITY_BONUS / (1.0 + distance_miles)
    - 0.0 mi  -> 12.00 pts
    - 0.5 mi  -> 8.00 pts
    - 1.0 mi  -> 6.00 pts
    - 2.0 mi  -> 4.00 pts
    - 5.0 mi  -> 2.00 pts
    - 190 mi  -> 0.06 pts (Houston vs San Antonio)
    """
    if distance_miles < 0.0:
        return 0.0
    bonus = MAX_PROXIMITY_BONUS / (1.0 + distance_miles)
    return round(bonus, 2)

View the complete scoring implementation on GitHub

Candidates are ranked after normalization and evidence aggregation rather than being silently reordered by the model.

Step 9: Gemini comes back at the end

Gemini still has an important job after the deterministic ranking stage.

I use it to turn the structured result into an answer that is useful to a person.

Conceptually:

with trace_span(
    "gemini.synthesize_recommendations",
    attributes={"workflow.stage": "v1"},
):
    response = synthesize_recommendations(
        intent=intent,
        ranked_candidates=ranked_candidates,
    )

But notice what has changed.

At the start of the workflow, Gemini had:

one natural-language request

At the end, it can work with:

structured intent
       +
normalized candidates
       +
Places evidence
       +
Search evidence
       +
constraint states
       +
candidate scores
       +
final ranking

So instead of asking Gemini to discover, verify, rank, and explain everything at once, I give it a much narrower final job:

Explain a decision whose evidence has already been assembled.

That is the architecture I wanted.

The complete journey

At a high level, the workflow became:

And internally, I started giving the major stages explicit names such as:

gemini.extract_intent
gemini.plan_fan_out
places.text_search
search_grounding.verify_evidence
candidate.normalize_and_dedup
evidence.aggregate_and_score
gemini.synthesize_recommendations

Those names become important again later in this series when I start tracing the workflows.

Step 10: I test it like normal software

Another goal for this project was to avoid treating AI code as somehow exempt from normal software-engineering practices.

After making changes, I run:

./.venv/bin/ruff check .
./.venv/bin/mypy src
./.venv/bin/pytest -q

Step 11: Then I moved the same application to Cloud Run

I also wanted the project to go beyond my laptop.

The application runs on Google Cloud Run.

I can inspect the deployed service from the CLI:

gcloud run services describe ai-search-journey-lab \
  --region us-central1 \
  --format="yaml(
      metadata.name,
      status.url,
      status.latestReadyRevisionName,
      status.conditions
  )"

And verify the Streamlit health endpoint:

curl -fsS \
"https://ai-search-journey-lab-642110324230.us-central1.run.app/_stcore/health"

For me, this matters because it closes the development loop:

local code
   ↓
local execution
   ↓
tests
   ↓
container
   ↓
Cloud Run
   ↓
live application

The same Search-to-Decision workflow running from the Cloud Run deployment.

What I am not trying to reproduce

There is an important distinction I want to make.

This project is not:

a reproduction of Google's internal ranking systems,
a reverse-engineered implementation of AI Mode,
an implementation of Google AI Overviews,
or a claim that my query fan-out represents Google's proprietary query fan-out.

I am using query fan-out as an application architecture pattern.

The project asks a developer-focused question:

If one natural-language request turns into multiple retrieval tasks, what engineering problems do I have to solve before I can return a grounded decision?

That is what I am trying to explore.

What happens when I run many search journeys?

V1 and V2 focus on one user's decision.

But imagine running many related prompts.

Now I can start asking:
How often does a brand appear?
Which competitors are being mentioned?
Which sources are being cited?
Does the brand appear in the initial query, the fan-out queries, or only the final answer?
How does visibility change across different prompts?

That is where this project moved from Search Journey Optimization into AI Search Visibility.

And that is the next article.

Next: Building Grounded Local Search with Gemini and Google Maps on Google Cloud

Before I move fully into visibility analytics, Part 2 will go deeper into the actual local-search implementation:

Gemini,
Google Places API (New),
Google Maps,
Google Search grounding,
grounded recommendation generation,
and Cloud Run deployment.

Then Part 3 will move into the AI Search Visibility & Brand Analyzer with Gemini and BigQuery.

Try the project

Repository: GitHub Repository

Local startup:

python scripts/run_app_locally.py