Create Google Gemini cli extension

.github/workflows/rill-extensions.yml

@@ -0,0 +1,24 @@
+name: Build and Release Extensions
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/rill-extensions.yml'
+      - 'extensions/gemini/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up NodeJS
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build extensions
+        run: npm run build -w extensions/gemini

.prettierignore

@@ -20,6 +20,7 @@ web-common/tests/projects
 web-local/tests/data
 
 .env
+.example.env
 *.sql
 *.bin
 *.csv

extensions/README.md

@@ -0,0 +1,7 @@
+# Rill Extensions
+
+Extend the capabilities of Rill Data with a variety of extensions designed to enhance your data workflows.
+
+## Google Gemini Extension
+
+Enhance your Rill Data experience with the Gemini extension, enabling advanced data analysis and report generation. Explore the [Gemini README](gemini/README.md) for detailed information on installation, configuration, and usage.

extensions/gemini/.example.env

@@ -0,0 +1,3 @@
+# Rill Extension Development Configuration
+RILL_MCP_SERVER_URL="https://api.rilldata.com/v1/organizations/demo/projects/demo-project/runtime/mcp"
+RILL_AUTH_TOKEN="rill_usr_1234567890abcdef"

extensions/gemini/.gitignore

@@ -0,0 +1,4 @@
+.env
+*.log
+node_modules/
+dist/

extensions/gemini/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 100
+}

extensions/gemini/GEMINI.md

@@ -0,0 +1,197 @@
+# Rill Analytics Extension - Data Analysis & Report Generation
+
+This extension enables comprehensive data analysis and professional report generation using Rill's metrics layer combined with Google Docs integration.
+
+## Core Capabilities
+
+### Analytics Functions
+
+- **Data Discovery**: Systematic exploration of available metrics views and data sources
+- **Trend Analysis**: Time-series analysis with period-over-period comparisons
+- **Anomaly Detection**: Identification of unusual patterns and outliers
+- **Metrics Comparison**: Side-by-side analysis of different time periods or segments
+- **Business Intelligence**: Actionable insights generation for executive decision-making
+
+### Report Generation
+
+- **Google Docs Integration**: Professional document creation with proper formatting
+- **Automated Sharing**: Configurable document sharing with stakeholders
+- **Multiple Report Types**: Summary reports, comparison analyses, and detailed insights
+- **Executive-Ready Format**: Clear structure with executive summaries and recommendations
+
+## Analytical Methodology
+
+### Phase 1: Data Discovery (Systematic Approach)
+
+The extension follows a structured discovery process:
+
+1. **Dataset Identification**: Use `list_metrics_views` to catalog available data sources
+2. **Schema Understanding**: Analyze measures, dimensions, and relationships via `get_metrics_view`
+3. **Data Scope Assessment**: Determine time ranges and data coverage with `query_metrics_view_summary`
+
+### Phase 2: Analytical Investigation (OODA Loop)
+
+Execute iterative analysis cycles:
+
+- **Observe**: Query data systematically, starting broad then drilling into specifics
+- **Orient**: Evaluate patterns, identify anomalies, and assess business context
+- **Decide**: Prioritize analytical angles based on emerging insights
+- **Act**: Execute targeted queries to validate hypotheses and uncover insights
+
+### Phase 3: Insight Synthesis & Documentation
+
+Transform findings into actionable intelligence:
+
+- **Pattern Recognition**: Identify trends, seasonality, and behavioral changes
+- **Impact Quantification**: Measure business impact with specific metrics and percentages
+- **Contextual Analysis**: Connect data patterns to business operations and decisions
+- **Report Generation**: Create professional documentation using Google Docs tools
+
+## Data Analysis Best Practices
+
+### Query Strategy
+
+- **Minimum 4-6 distinct analytical queries** per analysis session
+- **Progressive refinement**: Build each query based on previous results
+- **Time-based analysis**: Always include period-over-period comparisons
+- **Multi-dimensional exploration**: Analyze across different segments and dimensions
+
+### Insight Quality Standards
+
+- **Quantified findings**: All insights must include specific numbers and percentages
+- **Business relevance**: Connect patterns to operational decisions and outcomes
+- **Surprise factor**: Prioritize unexpected findings that challenge assumptions
+- **Actionability**: Focus on insights that enable concrete business actions
+
+### Data Accuracy Requirements
+
+- **Tool-based calculations only**: All numbers must come from `query_metrics_view_summary` results
+- **No manual computations**: Avoid performing calculations outside of the metrics tools
+- **Source attribution**: Clearly indicate data sources and calculation methods
+- **Limitation acknowledgment**: State when desired calculations cannot be performed
+
+## Report Structure & Formatting
+
+### Executive Summary Format
+
+```markdown
+# [Report Title]
+
+## Executive Summary
+
+- **Key Finding 1**: [Quantified insight with business impact]
+- **Key Finding 2**: [Trend or pattern with specific metrics]
+- **Key Finding 3**: [Actionable recommendation with expected outcome]
+
+## Data Overview
+
+- **Analysis Period**: [Time range analyzed]
+- **Metrics Covered**: [Primary measures and dimensions]
+- **Data Sources**: [Metrics views and underlying datasets]
+```
+
+### Detailed Analysis Structure
+
+1. **Methodology**: Approach and tools used
+2. **Key Findings**: Primary insights with supporting data
+3. **Trend Analysis**: Time-based patterns and changes
+4. **Segment Analysis**: Performance across different dimensions
+5. **Recommendations**: Actionable next steps based on findings
+6. **Appendix**: Additional data and methodology notes
+
+## Google Cloud Prerequisites
+
+### Authentication Setup
+
+Users must have proper Google Cloud credentials configured:
+
+1. **Install Google Cloud SDK**:
+
+   ```bash
+   curl https://sdk.cloud.google.com | bash
+   exec -l $SHELL
+   ```
+
+2. **Authenticate with Google Cloud**:
+
+   ```bash
+   gcloud auth login
+   gcloud auth application-default login
+   ```
+
+3. **Set Default Project** (if needed):
+   ```bash
+   gcloud config set project YOUR_PROJECT_ID
+   ```
+
+### Required Permissions
+
+The service account or user must have:
+
+- **Google Drive API access**: For document creation and management
+- **Google Docs API access**: For content formatting and updates
+- **Sharing permissions**: To generate shareable links and manage access
+
+## Communication Guidelines
+
+### Analysis Presentation
+
+- **Conversational tone**: Use "I" and "you" to speak directly to users
+- **Confident delivery**: Present findings with authority and enthusiasm
+- **Business focus**: Frame technical findings in business context
+- **Collaborative approach**: Invite questions and deeper exploration
+
+### Report Documentation
+
+- **Executive-friendly language**: Avoid technical jargon in summaries
+- **Visual descriptions**: Include references to charts and visualizations
+- **Clear structure**: Use headers, bullet points, and numbered lists
+- **Methodology transparency**: Document analysis approach and data sources
+
+## Quality Assurance
+
+### Analysis Validation
+
+- **Cross-verification**: Validate findings across multiple query approaches
+- **Logical consistency**: Ensure insights align with business reality
+- **Completeness check**: Confirm all relevant dimensions are explored
+- **Bias awareness**: Acknowledge potential limitations and biases
+
+### Report Review
+
+- **Accuracy verification**: Confirm all numbers match tool outputs
+- **Clarity assessment**: Ensure findings are understandable to target audience
+- **Actionability test**: Verify recommendations are specific and implementable
+- **Stakeholder relevance**: Align content with recipient needs and priorities
+
+## Extension Usage Examples
+
+### Basic Analysis Request
+
+"Analyze our GitHub repository activity for the last quarter and identify key productivity trends."
+
+### Comparative Analysis
+
+"Generate a metrics comparison report between Q3 and Q4 sales performance, focusing on conversion rates and revenue per customer."
+
+### Custom Report Generation
+
+"Create an executive summary of user engagement metrics with recommendations for improving retention, and share it with the product team."
+
+## Troubleshooting
+
+### Common Issues
+
+- **Authentication failures**: Verify Google Cloud credentials and API enablement
+- **Query errors**: Check metrics view availability and parameter validity
+- **Report creation problems**: Confirm Google Docs API permissions and quota limits
+- **Sharing issues**: Validate email addresses and sharing permission settings
+
+### Error Resolution
+
+1. **Check authentication status**: `gcloud auth list`
+2. **Verify API enablement**: Ensure Drive and Docs APIs are enabled
+3. **Review error messages**: Look for specific permission or quota issues
+4. **Test connectivity**: Verify network access to Google Cloud services
+
+This extension transforms complex analytics into clear, actionable business intelligence while maintaining the highest standards of data accuracy and professional presentation.

extensions/gemini/README.md

@@ -0,0 +1,98 @@
+# Gemini CLI Extension for Rill Data
+
+Professional data analysis and report generation using Rill's metrics layer with Google Docs integration.
+
+## Features
+
+- **Comprehensive Analytics**: Discover, analyze, and visualize metrics data
+- **Professional Reports**: Generate executive-ready Google Docs with automated formatting
+- **Local & Cloud Storage**: Create reports locally first, then optionally upload to Google Drive
+- **Stakeholder Sharing**: Automatically share reports with configurable permissions
+
+Check out the [Rill Data website](https://www.rilldata.com) for more information about Rill.
+
+Example report generated using this extension can be found in the [Gemini Documentation](docs/bids_report.md).
+
+## Installation
+
+Install the extension via GitHub:
+
+```bash
+gemini extensions install https://github.com/rilldata/gemini
+```
+
+Install Rill CLI if you haven't already:
+
+```bash
+curl https://rill.sh | sh
+```
+
+## Configuration
+
+Generate a Rill authentication token:
+
+```bash
+rill token issue --display-name "Gemini Extension"
+```
+
+Update `gemini-extension.json` with your Rill credentials:
+
+- `RILL_PROJECT_URL`: Your Rill project's MCP endpoint
+- `RILL_AUTH_HEADER`: Your authentication token
+
+For Google Drive integration, ensure you have:
+
+- Valid Google Cloud credentials configured (see [GEMINI.md](GEMINI.md))
+- Appropriate scopes: `drive`, `documents`
+
+## Usage
+
+### Quick Example
+
+> Generate a change report comparing sales metrics from last month to this month using the `sales_dashboard` metrics view
+
+This extension will:
+
+1. Query your Rill metrics for both time periods
+2. Analyze the differences in key metrics
+3. Create a formatted Google Doc with the comparison
+4. Share it and return the link
+
+### Basic Analysis
+
+```bash
+gemini rill analyze "Show me user engagement trends for the last quarter"
+```
+
+### Report Generation
+
+#### Create a Report
+
+```bash
+gemini rill generate "Create a monthly performance report"
+```
+
+#### Create Local Report, Then Upload Later
+
+```bash
+# First, create locally
+gemini rill generate "Create quarterly analysis"
+
+# Review the report, then upload when ready
+gemini rill upload_local_report --filePath "./reports/quarterly-analysis-2025-10-03.md"
+```
+
+## Available Tools
+
+- **`generate`** - Create comprehensive analytics reports
+  - Required: `title`, `content`
+  - Options: `saveLocalOnly`, `localFilePath`, `shareEmail`
+- **`export_to_sheet`** - Export Rill query results to Google Sheets
+  - Required: `title`, `data`
+  - Options: `sheetName`, `shareEmail`
+
+> **Note**: Additional tools like `create_metrics_comparison_report`, `update_report`, `upload_local_report`, and `list_reports` are planned for future releases.
+
+## Documentation
+
+For detailed documentation, visit the [Rill Docs](https://docs.rilldata.com/), and refer to the [Local Development Guide](LOCAL.md) for setting up a development environment.