rmi-dataagent-helper

name	rmi-dataagent-helper
description	Use this skill to configure, optimize, and ground BigQuery Conversational Data Agents for RMI. When invoked, helps users select a persona profile (TOM, Urban Planner, BQ Admin, Data Engineer, Data Scientist, or RMI Planner) to receive tailored grounding mantras, glossary definitions, and verified golden queries.
dependencies	["api-geminidataanalytics","rmi-sql"]

RMI BigQuery Data Agent Helper

[!NOTE] Conceptual Layer vs. NLP Implementation Layer:

• rmi-personas serves as the Conceptual Layer, defining high-level business challenges, quantitative SLAs, and cross-persona lifecycles.
• rmi-dataagent-helper serves as the NLP Implementation Layer. It translates those conceptual personas into machine-readable prompts, grounding indices, glossary terms, and verified golden queries (rmi-sql) to optimize BigQuery Conversational Data Agents.

This skill provides expert guidance and tooling to configure, ground, and programmatically manage BigQuery Conversational Data Agents for Roads Management Insights.

---

1. Persona-Driven Activation Workflow

When assisting a user with configuring a BigQuery Data Agent:

1. Identify Target Persona: Determine which of the 6 GA personas (or preview roles) the agent is being configured for:
   • Traffic Operations Manager (TOM): Real-time incidents, bottlenecks, detour detection.
   • Urban Planner (UP): Infrastructure ROI, before-and-after studies, TTI/PTI indices.
   • BigQuery Admin (BQA): Spend governance, slot contention, zero-cost audits.
   • Data Engineer (DE): Ingestion lag, geometry validation, 2-stage SRI pre-aggregations.
   • Data Scientist (DS): Z-score anomalies, predictive forecasting (TimesFM/ARIMA_PLUS), reliability ranking.
   • RMI Planner (RMIP): Total Addressable Monitoring (TAM) coverage, commercial tier SLAs, compute growth budgeting.
2. Retrieve Grounding Mantra & Glossary: Load the corresponding section from references/persona_setup_guides.md.
3. Inject Verified Golden Queries: Map the corresponding SQL assets from rmi-sql into the Data Agent's sampleQueries field.

---

2. Global Grounding & Schema Annotation Principles

Regardless of persona, all RMI Conversational Data Agents require strong metadata grounding:

2.1 Metadata-Enriched Views

Annotate views and underlying physical tables using ALTER VIEW ... SET OPTIONS so the LLM semantic parser accurately interprets column semantics:

ALTER VIEW `my_project.rmi.cleaned_routes`
SET OPTIONS (
  description="Main analytical view for RMI route performance, travel times, and SRI sub-segment speeds."
);

ALTER COLUMN duration_in_seconds 
SET OPTIONS(description="Traffic-aware actual trip duration in seconds.")
ON `my_project.rmi.cleaned_routes`;

2.2 Standard Job ID Headers

Instruct the Data Agent to prepend standardized rmica_ Job IDs to all generated SQL:

-- Job ID: rmica_<persona>_YYYYMMDD_HHMMSS

---

3. Grounding Index & Golden Query Assets

To prevent hallucinated column names and unpartitioned scans, ground the conversational agent with verified golden queries from rmi-sql:

Persona	Primary Grounding Focus	Key Golden Queries (rmi-sql)	Reference Guide
Traffic Ops Manager	Incidents, SRIs, Detour Fingerprints	tom1_peak_hour_delay.sql, tom2_persistent_bottlenecks.sql, tom6_dynamic_detour_detection.sql	TOM Guide
Urban Planner	Before/After ROI, TTI/PTI, Emissions	up1_corridor_trend.sql, up2_impact_analysis.sql, up4_weekend_vs_weekday.sql	UP Guide
BigQuery Admin	Spend, Slots, INFORMATION_SCHEMA	bqa0_metadata_inventory.sql, bqa1_scan_volume.sql, bqa2_cost_attribution.sql, bqa5_partition_pruning.sql	BQA Guide
Data Engineer	Geometry Integrity, SRI Flattening	de1_materialized_view.sql, de2_data_cleaning.sql, de3_sri_flattening.sql, de6_hourly_preaggregation.sql	DE Guide
Data Scientist

---

4. Multi-Persona Provisioning & Execution (scripts/provision_data_agent.sh)

Automate the lifecycle, provisioning, and conversational querying of all 6 RMI persona Data Agents using scripts/provision_data_agent.sh (which leverages api-geminidataanalytics):

Option A: Direct CLI Provisioning

Provision any of the 6 RMI personas in a single shell command:

# Provision a Traffic Operations Manager (TOM) agent:
bash scripts/provision_data_agent.sh --persona tom --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga

# Provision an Urban Planner (UP) agent:
bash scripts/provision_data_agent.sh --persona up --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga

# Provision a BigQuery Admin (BQA) FinOps agent:
bash scripts/provision_data_agent.sh --persona bqa --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga

# Provision a Data Engineer (DE) spatial ETL agent:
bash scripts/provision_data_agent.sh --persona de --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga

# Provision a Data Scientist (DS) predictive modeling agent:
bash scripts/provision_data_agent.sh --persona ds --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga

# Provision an RMI Planner (RMIP) network capacity agent:
bash scripts/provision_data_agent.sh --persona rmip --location projects/my-project/locations/us-central1 --project my-project --dataset src_boston_ga

Option B: Sourced Bash Operations

source scripts/provision_data_agent.sh

# Provision via generic function or persona wrapper:
setup_persona_agent "tom" "projects/my-project/locations/us-central1" "my-project" "src_boston_ga"

# Converse with the provisioned Data Agent:
chat_with_rmi_agent \
  "projects/my-project/locations/us-central1" \
  "projects/my-project/locations/us-central1/dataAgents/rmi-tom-agent" \
  "Which corridors are experiencing severe congestion (TTR > 1.5) right now?" \
  "my-project"

---

5. Tooling & Reasoning Safety Patterns

1. SQL Transparency: Instruct the conversational agent to always display the generated SQL so users can verify partition pruning before execution.
2. Iterative Context Hinting: When schema drift occurs, inject "Contextual Hints" via the BigQuery console or API patch operations.
3. Partition Bounds Enforcement: Alert users whenever a query omits record_time bounds on high-volume partitioned tables.

---

References

• references/persona_setup_guides.md: Concrete setup steps and grounding mantras for all 6 RMI personas.
• references/data_agent_best_practices.md: General BigQuery Conversational Data Agent grounding guidelines.
• references/instructions.md: System instructions and schema mapping reference.
• BigQuery Data Agent Official Documentation
• BigQuery Conversational Analytics API

Related Skills

• rmi-personas: Conceptual definitions, business challenges, and SLAs for RMI personas.
• rmi-sql: Production SQL asset library and golden queries.
• bigquery-practices: Foundational BigQuery performance, security, and governance best practices.