Selecta

https://github.com/yogirk/selecta
Admin
Selecta provides natural-language analytics for BigQuery, powered by Google’s ADK and a streaming...
Tokens:12,058
Snippets:60
Trust Score:6
License:Apache-2.0
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install and Run Selecta Frontend (Bash)

Source: https://github.com/yogirk/selecta/blob/main/frontend/README.md

Instructions for installing dependencies, configuring environment variables, and starting the development server for the Selecta Next.js client. Assumes the ADK backend is running separately.

```bash
npm install
cp .env.local.example .env.local         # adjust NEXT_PUBLIC_API_URL if the backend runs elsewhere
npm run dev
# open http://localhost:3000
```

--------------------------------

### Start Frontend Development Server (Bash)

Source: https://github.com/yogirk/selecta/blob/main/README.md

Commands to install frontend dependencies and start the Next.js development server. This is a standard Node.js/npm workflow for running a frontend application.

```bash
cd frontend
npm install
npm run dev
```

--------------------------------

### Start ADK HTTP Server (Bash)

Source: https://context7.com/yogirk/selecta/llms.txt

Provides bash commands to set up and run the ADK HTTP backend server. It includes steps for navigating to the backend directory, installing dependencies using uv, setting essential environment variables like API keys and dataset configurations, and finally starting the server on port 8080.

```bash
# From backend directory
cd backend

# Install dependencies
uv venv
source .venv/bin/activate
uv pip install -e .

# Set environment variables
export GOOGLE_API_KEY="your-gemini-api-key"
export SELECTA_DATASET_CONFIG="$(pwd)/selecta/datasets/thelook.yaml"

# Start ADK server on port 8080
uv run adk api_server app --allow_origins "*" --port 8080

# Server exposes endpoints:
# POST /run_sse - Stream agent responses via Server-Sent Events
# POST /apps/{app}/users/{user}/sessions/{session} - Create/resume session
# GET  /apps/{app}/users/{user}/sessions - List user sessions
# GET  /apps/{app}/users/{user}/sessions/{session} - Get session details
# GET  /docs - Swagger UI documentation
```

--------------------------------

### Setup Selecta ADK Agent Environment

Source: https://github.com/yogirk/selecta/blob/main/backend/README.md

This snippet outlines the steps to set up the Selecta ADK agent's Python environment. It includes navigating to the backend directory, creating a virtual environment using 'uv', activating it, and installing project dependencies. It also shows how to configure essential environment variables for API keys and dataset configuration.

```bash
cd backend
uv venv
source .venv/bin/activate
uv pip install -e .

# Configure credentials
export GOOGLE_API_KEY="YOUR_GEMINI_KEY"      # or set Vertex AI env vars
export GOOGLE_GENAI_USE_VERTEXAI=0            # set to 1 for Vertex AI
export SELECTA_DATASET_CONFIG="$(pwd)/selecta/datasets/thelook.yaml"
```

--------------------------------

### Boot Backend Server (Bash)

Source: https://github.com/yogirk/selecta/blob/main/README.md

Commands to set up and run the backend ADK server. This involves navigating to the backend directory, creating and activating a virtual environment, installing dependencies, configuring API keys and dataset paths, and finally running the ADK API server.

```bash
cd backend
uv venv
source .venv/bin/activate
uv pip install -e .

# Configure credentials
export GOOGLE_API_KEY="YOUR_GEMINI_KEY"            # or set Vertex AI env vars
export SELECTA_DATASET_CONFIG="$(pwd)/selecta/datasets/thelook.yaml"

# Run the ADK server
uv run adk api_server app --allow_origins "*" --port 8080
```

--------------------------------

### Frontend Development with Next.js

Source: https://context7.com/yogirk/selecta/llms.txt

This section details how to set up and run the frontend development server using Next.js. It covers dependency installation, environment variable configuration, starting the development server, and building for production. Key frontend technologies are also listed.

```bash
# From frontend directory
cd frontend

# Install dependencies
npm install

# Set backend API URL (optional, defaults to /api proxy)
echo "NEXT_PUBLIC_API_URL=http://localhost:8080" > .env.local

# Start development server
npm run dev
# Opens on http://localhost:3000

# Build for production
npm run build
npm run start

# Key frontend dependencies:
# - Next.js 15 (App Router)
# - React 19
# - TypeScript
# - Zustand (state management)
# - Shadcn UI + Radix UI
# - Tailwind CSS 4
# - Vega-Lite + react-vega (visualizations)
# - React Markdown
```

--------------------------------

### Selecta Frontend Development Commands (Bash)

Source: https://github.com/yogirk/selecta/blob/main/frontend/README.md

Common development commands for the Selecta Next.js client, including starting the dev server, building for production, serving the production build, and running ESLint for code quality.

```bash
npm run dev      # Start the dev server
npm run build    # Production build
npm run start    # Serve the production build
npm run lint     # ESLint
```

--------------------------------

### Run Selecta ADK API Server

Source: https://github.com/yogirk/selecta/blob/main/backend/README.md

This command starts the ADK API server, making the agent accessible via REST and SSE endpoints. It specifies the application to load ('app' from the current directory), allows all origins, and sets the port to 8080. This server is the primary interface for frontends and tools to interact with the Selecta agent.

```bash
uv run adk api_server app --allow_origins "*" --port 8080
```

--------------------------------

### Verify Local Docker Run with curl

Source: https://github.com/yogirk/selecta/blob/main/docs/deployment/cloud-run.md

This command checks if the locally running Selecta application is accessible by sending an HTTP HEAD request to its documentation endpoint. This verifies that the container started correctly and is listening on the expected port.

```bash
curl -I http://localhost:8080/docs
```

--------------------------------

### Set Custom Dataset Configuration (Bash)

Source: https://context7.com/yogirk/selecta/llms.txt

Bash script to set the `SELECTA_DATASET_CONFIG` environment variable, pointing to a custom YAML configuration file. This allows the application to use specific dataset and model settings. It's typically used before starting the API server.

```bash
# Use the custom dataset configuration
export SELECTA_DATASET_CONFIG="$(pwd)/selecta/datasets/custom.yaml"
uv run adk api_server app --allow_origins "*" --port 8080

# The agent will now:
# 1. Load table schemas from my-data-warehouse.sales
# 2. Fetch data profiles for the 4 specified tables
# 3. Inject context into the Gemini prompt
# 4. Execute queries using my-gcp-project as billing project
```

--------------------------------

### Deploy Selecta to Cloud Run with Helper Script

Source: https://github.com/yogirk/selecta/blob/main/docs/deployment/cloud-run.md

This command utilizes a helper script to build and deploy the Selecta container to Cloud Run. It configures environment variables, service accounts, and authentication modes. Replace placeholders like YOUR_PROJECT and the service account email with your specific values.

```bash
./deploy-cloud-run.sh \
  --project YOUR_PROJECT \
  --region us-central1 \
  --service selecta \
  --service-account YOUR_PROJECT-compute@developer.gserviceaccount.com \
  --secret GOOGLE_API_KEY=selecta-gemini-key:latest \
  --allow-unauthenticated
```

--------------------------------

### Run Selecta ADK Web Playground

Source: https://github.com/yogirk/selecta/blob/main/backend/README.md

This command launches the ADK Web Playground, providing a user interface for interacting with the Selecta agent. It specifies the agent module ('selecta.agent:selecta_agent') and the port (8501) for the web interface.

```bash
uv run adk web --agent selecta.agent:selecta_agent --port 8501
```

--------------------------------

### Quick Verification: Interact with Selecta ADK API

Source: https://github.com/yogirk/selecta/blob/main/backend/README.md

This series of cURL commands provides a quick way to verify the Selecta ADK agent's functionality. It shows how to access API documentation, create a new session, and stream a natural-language question to the agent. The final command demonstrates how to send a query about cancelled orders per month and receive streaming results.

```bash
# docs
curl http://localhost:8080/docs

# create session
SESSION=$(uuidgen); USER=u_demo
curl -X POST "http://localhost:8080/apps/app/users/$USER/sessions/$SESSION" \
  -H "Content-Type: application/json" -d "{}"

# stream a question
curl -N -X POST http://localhost:8080/run_sse \
  -H "Content-Type: application/json" \
  -d "{\"appName\":\"app\",\"userId\":\"$USER\",\"sessionId\":\"$SESSION\", \
       \"newMessage\":{\"parts\":[{\"text\":\"What is the total number of cancelled orders per month?\"}],\"role\":\"user\"}, \
       \"streaming\":true}"
```

--------------------------------

### Deploy to Cloud Run with Shell Script

Source: https://context7.com/yogirk/selecta/llms.txt

This script automates the build and deployment of a Docker image to Google Cloud Run. It handles building the image, pushing it to a registry, and configuring the Cloud Run service with specific settings like service account, environment variables, and resource allocation. It also shows how to use a helper script for deployment.

```shell
# deploy-cloud-run.sh

PROJECT_ID="my-gcp-project"
REGION="us-central1"
SERVICE_NAME="selecta"
SERVICE_ACCOUNT="${PROJECT_ID}-compute@developer.gserviceaccount.com"

# Build and push Docker image
docker build -t gcr.io/${PROJECT_ID}/${SERVICE_NAME}:latest .
docker push gcr.io/${PROJECT_ID}/${SERVICE_NAME}:latest

# Deploy to Cloud Run
gcloud run deploy ${SERVICE_NAME} \
  --project ${PROJECT_ID} \
  --region ${REGION} \
  --image gcr.io/${PROJECT_ID}/${SERVICE_NAME}:latest \
  --platform managed \
  --allow-unauthenticated \
  --service-account ${SERVICE_ACCOUNT} \
  --set-secrets GOOGLE_API_KEY=selecta-gemini-key:latest \
  --set-env-vars SELECTA_DATASET_CONFIG=/opt/venv/lib/python3.12/site-packages/selecta/datasets/thelook.yaml \
  --memory 2Gi \
  --cpu 2 \
  --timeout 300 \
  --concurrency 80 \
  --min-instances 0 \
  --max-instances 10

# Or use the provided helper script:
./deploy-cloud-run.sh \
  --project my-gcp-project \
  --region us-central1 \
  --service selecta \
  --service-account my-gcp-project-compute@developer.gserviceaccount.com \
  --secret GOOGLE_API_KEY=selecta-gemini-key:latest \
  --allow-unauthenticated

# Service runs on port 8080 (Next.js frontend)
# Backend ADK server listens on port 8081 (proxied by Next.js)
```

--------------------------------

### Read Cloud Run Service Logs with gcloud

Source: https://github.com/yogirk/selecta/blob/main/docs/deployment/cloud-run.md

This command fetches the logs for the 'selecta' service running on Cloud Run, limited to the last 200 entries. This is useful for debugging startup issues or backend errors. Replace YOUR_PROJECT and the region if necessary.

```bash
gcloud run services logs read selecta \
  --project YOUR_PROJECT \
  --region us-central1 \
  --limit 200
```

--------------------------------

### Configure Dataset for Selecta

Source: https://github.com/yogirk/selecta/blob/main/backend/README.md

This snippet demonstrates how to set up a custom dataset configuration for the Selecta agent. It involves copying a default configuration file and exporting an environment variable to point to the new configuration. This allows customization of billing project IDs, dataset/table lists, and prompt instructions.

```bash
cp selecta/datasets/thelook.yaml my_dataset.yaml
export SELECTA_DATASET_CONFIG="$(pwd)/my_dataset.yaml"
```

--------------------------------

### Run Selecta Production Image Locally with Docker

Source: https://github.com/yogirk/selecta/blob/main/docs/deployment/cloud-run.md

This command runs the Selecta production Docker image locally, mapping port 8080 and setting the necessary Google API key environment variable. This allows for local testing before deploying to Cloud Run.

```bash
docker run --rm -p 8080:8080 \
  -e GOOGLE_API_KEY=YOUR_KEY \
  gcr.io/YOUR_PROJECT/selecta:TAG
```

--------------------------------

### Dataset Configuration

Source: https://context7.com/yogirk/selecta/llms.txt

Describes how to configure datasets and model settings using YAML files for the Selecta backend.

```APIDOC
## Dataset Configuration

### Description

Configure BigQuery datasets and model settings via YAML. This allows for customization of the data sources, display names, descriptions, and the underlying AI model used for analysis.

### Configuration File Example (`custom.yaml`)

```yaml
# backend/selecta/datasets/custom.yaml
id: sales_analytics
"display_name": "Sales Analytics Dataset"
description: "Company sales data warehouse"
model: "gemini-2.5-pro-preview-03-25"

prompt:
  instruction_file: "../instructions.yaml"

bigquery:
  billing_project_id: "my-gcp-project"
  data_project_id: "my-data-warehouse"
  dataset: "sales"
  location: "US"
  tables:
    - "transactions"
    - "customers"
    - "products"
    - "inventory"
  data_profiles_table: ""  # Optional: table containing column statistics
```

### Usage

To use a custom dataset configuration, set the `SELECTA_DATASET_CONFIG` environment variable to the path of your YAML file.

```bash
# Use the custom dataset configuration
export SELECTA_DATASET_CONFIG="$(pwd)/selecta/datasets/custom.yaml"
uv run adk api_server app --allow_origins "*" --port 8080

# The agent will now:
# 1. Load table schemas from my-data-warehouse.sales
# 2. Fetch data profiles for the 4 specified tables
# 3. Inject context into the Gemini prompt
# 4. Execute queries using my-gcp-project as billing project
```
```

--------------------------------

### Architecture Overview Diagram (Text)

Source: https://github.com/yogirk/selecta/blob/main/README.md

A text-based representation of the Selecta architecture, illustrating the flow of data from the user through the Next.js frontend, Google ADK HTTP Server, and finally to BigQuery + Gemini.

```text
      [Google ADK HTTP Server]
                │
                ▼
        [BigQuery + Gemini]
```

--------------------------------

### Deploy to Cloud Run (Bash)

Source: https://github.com/yogirk/selecta/blob/main/README.md

A helper script to build a container and deploy the Selecta stack (ADK backend and Next.js frontend) to Google Cloud Run. It allows configuration of project, region, service name, service account, and secrets.

```bash
./deploy-cloud-run.sh \
  --project PROJECT_ID \
  --region us-central1 \
  --service selecta \
  --service-account PROJECT_ID-compute@developer.gserviceaccount.com \
  --secret GOOGLE_API_KEY=selecta-gemini-key:latest \
  --allow-unauthenticated
```

--------------------------------

### Create SSE Connection (TypeScript)

Source: https://context7.com/yogirk/selecta/llms.txt

Demonstrates how to establish a Server-Sent Events (SSE) connection from a frontend application using TypeScript. It shows how to import an API client, initiate a connection with user and session details, and handle incoming events, results, errors, and connection completion.

```typescript
import { apiClient } from '@/lib/api';
import { Event } from '@/types';

const userId = 'user-123';
const sessionId = 'session-abc';
const message = 'What are the top 5 products by revenue?';

// Create streaming connection
const handle = apiClient.createSSEConnection(
  userId,
  sessionId,
  message,

  // onEvent callback - receives each streamed event
  (event: Event) => {
    // Event structure:
    // {
    //   content: { 
    //     parts: [{ text: "Analyzing your query..." }]
    //   },
    //   actions: {
    //     stateDelta: {
    //       latest_result: {
    //         id: "uuid",
    //         sql: "SELECT ...",
    //         rows: [...],
    //         chart: {...},
    //         executionMs: 2500,
    //         ...
    //       },
    //       results_history: [...],
    //       latest_error: null
    //     }
    //   },
    //   finishReason: "stop",
    //   timestamp: 1698765432.5,
    //   metrics: {
    //     tokens: { input: 5000, output: 1200 },
    //     latencyMs: 3400
    //   }
    // }

    console.log('Received event:', event);

    // Extract streaming text
    const text = event.content?.parts
      ?.map(p => p.text)
      .filter(Boolean)
      .join('');

    // Check for results in stateDelta
    if (event.actions?.stateDelta?.latest_result) {
      const result = event.actions.stateDelta.latest_result;
      console.log(`Query returned ${result.rowCount} rows`);
      console.log(`Execution time: ${result.executionMs}ms`);
    }

    // Check for completion
    if (event.finishReason === 'stop') {
      console.log('Stream completed');
    }
  },

  // onError callback
  (error: Error) => {
    console.error('SSE Error:', error);
  },

  // onComplete callback
  () => {
    console.log('Connection closed');
  }
);

// Close connection when needed
handle.close();
```

--------------------------------

### Deploy Selecta to Google Cloud Run (Bash)

Source: https://context7.com/yogirk/selecta/llms.txt

Bash script for deploying the full-stack Selecta application as a single container to Google Cloud Run. This script is intended to facilitate the deployment process.

```bash
#!/bin/bash
```

--------------------------------

### Configure BigQuery Datasets with YAML

Source: https://context7.com/yogirk/selecta/llms.txt

Configuration file in YAML format for defining BigQuery datasets and model settings. It specifies dataset details, model to use, and BigQuery connection parameters. This configuration can be loaded via an environment variable `SELECTA_DATASET_CONFIG`.

```yaml
# backend/selecta/datasets/custom.yaml
id: sales_analytics
display_name: "Sales Analytics Dataset"
description: "Company sales data warehouse"
model: "gemini-2.5-pro-preview-03-25"

prompt:
  instruction_file: "../instructions.yaml"

bigquery:
  billing_project_id: "my-gcp-project"
  data_project_id: "my-data-warehouse"
  dataset: "sales"
  location: "US"
  tables:
    - "transactions"
    - "customers"
    - "products"
    - "inventory"
  data_profiles_table: ""  # Optional: table containing column statistics

# Load this config via environment variable:
# export SELECTA_DATASET_CONFIG="/path/to/custom.yaml"
```

--------------------------------

### Verify Cloud Run Deployment with curl

Source: https://github.com/yogirk/selecta/blob/main/docs/deployment/cloud-run.md

This command performs an HTTP HEAD request to the deployed Cloud Run service to verify its availability and check for a successful HTTP 200 status code. The URL should be replaced with the actual URL provided after deployment.

```bash
curl -I https://selecta-<SERVICE_HASH>-<PROJECT>.us-central1.run.app/docs
```

--------------------------------

### Selecta API Endpoint Reference

Source: https://github.com/yogirk/selecta/blob/main/backend/api-contract.md

A reference table outlining the available HTTP methods, paths, and descriptions for the Selecta API. These endpoints cover actions such as creating/resuming sessions, listing and fetching session details, executing synchronous runs, and streaming agent events.

```markdown
| Method | Path |
| --- | --- |
| `GET` | `/docs` |
| `POST` | `/apps/{app}/users/{user}/sessions/{session}` |
| `GET` | `/apps/{app}/users/{user}/sessions` |
| `GET` | `/apps/{app}/users/{user}/sessions/{session}` |
| `POST` | `/run` |
| `POST` | `/run_sse` |
```

--------------------------------

### Build Chart Bundle from Query Results - Python

Source: https://context7.com/yogirk/selecta/llms.txt

This snippet shows how to generate Vega-Lite chart specifications from BigQuery result rows using the `build_chart_bundle` function. It takes a list of dictionaries representing the query results and heuristically determines appropriate chart types. The `build_chart_spec` function can also be used for individual chart generation.

```python
from selecta.visualization import build_chart_bundle, build_chart_spec

# Example result data from BigQuery
rows = [
    {"month": "2024-01", "revenue": 45230.50, "orders": 1234},
    {"month": "2024-02", "revenue": 52100.75, "orders": 1456},
    {"month": "2024-03", "revenue": 48900.25, "orders": 1389},
    {"month": "2024-04", "revenue": 61200.00, "orders": 1678}
]

# Build complete chart bundle with multiple options
chart_bundle = build_chart_bundle(rows)

```

--------------------------------

### Manage Sessions with Session Management API (TypeScript)

Source: https://context7.com/yogirk/selecta/llms.txt

API client for creating and managing user sessions for multi-turn conversations. It allows for session creation, listing, retrieval, and deletion. Dependencies include '@/lib/api'. Input is user ID and session ID, with outputs being session data or lists of sessions.

```typescript
import { apiClient } from '@/lib/api';

// Create a new session
const session = await apiClient.createSession('user-123', 'session-new');
// Returns: { id: "session-new", userId: "user-123", events: [], state: {} }

// List all sessions for a user
const sessions = await apiClient.getSessions('user-123');
// Returns: [
//   { id: "session-abc", userId: "user-123", ... },
//   { id: "session-xyz", userId: "user-123", ... }
// ]

// Get specific session with all events and state
const existingSession = await apiClient.getSession('user-123', 'session-abc');
// Returns: {
//   id: "session-abc",
//   userId: "user-123",
//   events: [
//     {
//       content: { parts: [{ text: "..." }] },
//       actions: { stateDelta: { latest_result: {...}, ... } },
//       timestamp: 1698765432.5
//     },
//     ...
//   ],
//   state: {
//     latest_result: {...},
//     results_history: [...],
//     errors_history: []
//   }
// }

// Delete a session
await apiClient.deleteSession('user-123', 'session-abc');

// Retrieve specific result from session history
const result = await apiClient.getResult('user-123', 'session-abc', 'result-id');
// Returns: {
//   id: "result-id",
//   sql: "SELECT ...",
//   rows: [...],
//   columns: [...],
//   rowCount: 100,
//   chart: {...},
//   executionMs: 2500,
//   jobId: "bquxjob_123"
// }
```

--------------------------------

### Session Management API

Source: https://context7.com/yogirk/selecta/llms.txt

Provides endpoints for creating, retrieving, listing, and deleting user sessions for multi-turn conversations.

```APIDOC
## Session Management API

### Description

Create and manage user sessions for multi-turn conversations. This API allows for the creation of new sessions, retrieval of existing sessions (including their events and state), listing all sessions for a user, and deleting sessions.

### Methods

- **Create Session**: Creates a new session for a given user.
- **List Sessions**: Retrieves all sessions associated with a user.
- **Get Session**: Fetches a specific session by user ID and session ID, including all historical events and the current state.
- **Delete Session**: Removes a specified session.
- **Get Result**: Retrieves a specific result from a session's history.

### Endpoints & Examples

#### Create a new session

```typescript
import { apiClient } from '@/lib/api';

// Create a new session
const session = await apiClient.createSession('user-123', 'session-new');
// Returns: { id: "session-new", userId: "user-123", events: [], state: {} }
```

#### List all sessions for a user

```typescript
// List all sessions for a user
const sessions = await apiClient.getSessions('user-123');
// Returns: [
//   { id: "session-abc", userId: "user-123", ... },
//   { id: "session-xyz", userId: "user-123", ... }
// ]
```

#### Get specific session with all events and state

```typescript
// Get specific session with all events and state
const existingSession = await apiClient.getSession('user-123', 'session-abc');
// Returns: {
//   id: "session-abc",
//   userId: "user-123",
//   events: [
//     {
//       content: { parts: [{ text: "..." }] },
//       actions: { stateDelta: { latest_result: {...}, ... } },
//       timestamp: 1698765432.5
//     },
//     ...
//   ],
//   state: {
//     latest_result: {...},
//     results_history: [...],
//     errors_history: []
//   }
// }
```

#### Delete a session

```typescript
// Delete a session
await apiClient.deleteSession('user-123', 'session-abc');
```

#### Retrieve specific result from session history

```typescript
// Retrieve specific result from session history
const result = await apiClient.getResult('user-123', 'session-abc', 'result-id');
// Returns: {
//   id: "result-id",
//   sql: "SELECT ...",
//   rows: [...],
//   columns: [...],
//   rowCount: 100,
//   chart: {...},
//   executionMs: 2500,
//   jobId: "bquxjob_123"
// }
```
```

--------------------------------

### Execute BigQuery Query Tool - Python

Source: https://context7.com/yogirk/selecta/llms.txt

This Python function, `execute_bigquery_query`, is the primary tool used by the Gemini agent to run SQL queries against BigQuery. It accepts an SQL query string and an optional `tool_context`. When executed by the ADK agent, the `tool_context.state` is enriched with detailed metadata, including execution time, job IDs, and generated chart specifications. Error handling is included to catch `RuntimeError` during query execution.

```python
from selecta.custom_tools import execute_bigquery_query

# SQL query to execute
sql_query = """
SELECT
  product_name,
  SUM(sale_price) AS total_revenue
FROM `bigquery-public-data.thelook_ecommerce.order_items` oi
JOIN `bigquery-public-data.thelook_ecommerce.products` p
  ON oi.product_id = p.id
WHERE oi.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 150 DAY)
GROUP BY product_name
ORDER BY total_revenue DESC
LIMIT 10
"""

# Execute the query (tool_context is provided by ADK during agent execution)
# Returns normalized rows with metadata attached to tool_context.state
try:
    rows = execute_bigquery_query(sql_query, tool_context=None)

    # Expected output structure:
    # [
    #   {"product_name": "Premium Headphones", "total_revenue": 45230.50},
    #   {"product_name": "Wireless Mouse", "total_revenue": 38450.25},
    #   ...
    # ]

    # When called by ADK agent, tool_context.state is enriched with:
    # {
    #   "latest_result": {
    #     "id": "uuid-v4",
    #     "sql": "SELECT ...",
    #     "rows": [...],
    #     "columns": ["product_name", "total_revenue"],
    #     "rowCount": 10,
    #     "chart": {...},  # Vega-Lite spec
    #     "chartOptions": [...],  # Multiple chart options
    #     "defaultChartId": "bar-horizontal",
    #     "executionMs": 2840,
    #     "jobId": "bquxjob_abc123",
    #     "dataset": {
    #       "id": "thelook_ecommerce",
    #       "projectId": "bigquery-public-data",
    #       "billingProjectId": "cloudside-academy",
    #       "location": "US",
    #       "tables": ["orders", "order_items", "products", "users"]
    #     }
    #   },
    #   "results_history": [...] 
    # }

except RuntimeError as e:
    # Error handling - errors are recorded in tool_context.state["latest_error"]
    # {
    #   "message": "Syntax error: Expected end of input but got identifier",
    #   "sql": "SELECT ...",
    #   "timestamp": 1698765432000,
    #   "type": "BadRequest",
    #   "jobId": "bquxjob_xyz789",
    #   "errorCode": 400,
    #   "details": [...] 
    # }
    print(f"Query failed: {e}")
```

--------------------------------

### Build ADK Agent and Refresh Configuration - Python

Source: https://context7.com/yogirk/selecta/llms.txt

This snippet demonstrates how to build and refresh an ADK agent for Selecta. The agent is configured with a Gemini model, specific tools like `execute_bigquery_query`, and dynamic instructions. Refreshing the agent is useful for updating configurations without restarting the server. The agent is accessible via `root_agent`.

```python
from google.adk.agents import Agent
from selecta.agent import build_agent, refresh_agent

# Build the agent with default configuration
agent = build_agent()

# Agent is configured with:
# - Model: gemini-2.5-pro-preview-03-25 (configurable via dataset YAML)
# - Name: "selecta"
# - Tools: [execute_bigquery_query]
# - Instruction: Dynamic prompt with table schemas, data profiles, and examples

# Refresh agent to reload instructions (useful when dataset config changes)
refreshed_agent = refresh_agent()

# The agent is automatically exposed as root_agent for ADK HTTP server
from selecta.agent import root_agent
print(root_agent.name)  # Output: "selecta"
```

--------------------------------

### Grant Secret Accessor Role with gcloud

Source: https://github.com/yogirk/selecta/blob/main/docs/deployment/cloud-run.md

This command grants a service account the necessary permissions to access secrets stored in Google Secret Manager. Ensure you replace YOUR_PROJECT with your actual project ID.

```bash
gcloud secrets add-iam-policy-binding selecta-gemini-key \
  --project YOUR_PROJECT \
  --member "serviceAccount:YOUR_PROJECT-compute@developer.gserviceaccount.com" \
  --role roles/secretmanager.secretAccessor
```

--------------------------------

### Manage SSE with useSSE Hook (TypeScript)

Source: https://context7.com/yogirk/selecta/llms.txt

This React hook manages streaming conversations, handling automatic state updates. It integrates with a store to manage messages, streaming text, and results. Dependencies include '@/hooks/useSSE' and '@/lib/store'. It takes user and session IDs as input and outputs message sending functionality.

```typescript
import { useSSE } from '@/hooks/useSSE';
import { useStore } from '@/lib/store';

function ChatComponent() {
  const userId = 'user-123';
  const sessionId = 'session-abc';

  // Initialize SSE hook
  const { sendMessage } = useSSE(userId, sessionId);

  // Access store state
  const {
    messages,
    isStreaming,
    streamingText,
    activeResult,
    activeError
  } = useStore();

  // Send a message
  const handleSubmit = (text: string) => {
    sendMessage(text);

    // Hook automatically:
    // 1. Adds user message to store
    // 2. Creates SSE connection to /run_sse
    // 3. Streams reasoning text progressively
    // 4. Extracts structured sections (Summary, Results, Business Insights)
    // 5. Caches results and errors
    // 6. Updates activeResult with chart specs and metadata
    // 7. Finalizes assistant message when complete
  };

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.text}

          {/* Show reasoning if available */}
          {msg.thinking && (
            <details>
              <summary>View reasoning</summary>
              <pre>{msg.thinking}</pre>
            </details>
          )}

          {/* Show result metadata */}
          {msg.result && (
            <div>
              <p>Rows: {msg.result.rowCount}</p>
              <p>Execution: {msg.result.executionMs}ms</p>
              <p>Job ID: {msg.result.jobId}</p>
            </div>
          )}
        </div>
      ))}

      {/* Show streaming text */}
      {isStreaming && streamingText && (
        <div className="animate-pulse">{streamingText}</div>
      )}

      {/* Show active error */}
      {activeError && (
        <div className="error">
          <p>{activeError.message}</p>
          <code>{activeError.sql}</code>
        </div>
      )}

      <input
        onSubmit={e => {
          e.preventDefault();
          handleSubmit(e.currentTarget.value);
        }}
        disabled={isStreaming}
      />
    </div>
  );
}

```

--------------------------------

### Backend Error Handling with Python

Source: https://context7.com/yogirk/selecta/llms.txt

This Python code snippet demonstrates error handling for a BigQuery query. It uses a try-except block to catch potential `RuntimeError` exceptions that might occur during query execution, such as invalid SQL or non-existent tables. The caught error is then recorded in a context object.

```python
# Backend: Error is caught and recorded
from selecta.custom_tools import execute_bigquery_query

try:
    rows = execute_bigquery_query(
        "SELECT invalid_column FROM nonexistent_table",
        tool_context=context
    )
except RuntimeError as e:
    # Error automatically recorded in context.state:
    # {
    #   "latest_error": {
    #     "message": "Not found: Table bigquery-public-data:nonexistent_table",
    #     "sql": "SELECT invalid_column FROM nonexistent_table",
    #     "timestamp": 1698765432000,
    #     "type": "NotFound",
    #     "jobId": "bquxjob_error123",
    #     "errorCode": 404,
    #     "details": [
    #       {
    #         "message": "Not found: Table...",
    #         "reason": "notFound",
    #         "location": "nonexistent_table"
    #       }
    #     ]
    #   },
    #   "errors_history": [...] 
    # }
    pass
```

--------------------------------

### Swagger UI

Source: https://github.com/yogirk/selecta/blob/main/backend/api-contract.md

Provides access to the Swagger UI for the ADK server, allowing interactive API exploration.

```APIDOC
## GET /docs

### Description
Swagger UI for the ADK server.

### Method
GET

### Endpoint
/docs
```

--------------------------------

### Session Management

Source: https://github.com/yogirk/selecta/blob/main/backend/api-contract.md

Endpoints for managing user sessions within applications, including creation, resumption, listing, and fetching details.

```APIDOC
## POST /apps/{app}/users/{user}/sessions/{session}

### Description
Create or resume a session.

### Method
POST

### Endpoint
/apps/{app}/users/{user}/sessions/{session}

### Parameters
#### Path Parameters
- **app** (string) - Required - The application identifier.
- **user** (string) - Required - The user identifier.
- **session** (string) - Required - The session identifier.

#### Request Body
- **{}** (object) - An empty object is expected.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
(Details depend on the specific session state and events)

#### Response Example
(Varies based on session state)
```

```APIDOC
## GET /apps/{app}/users/{user}/sessions

### Description
List sessions for a user.

### Method
GET

### Endpoint
/apps/{app}/users/{user}/sessions

### Parameters
#### Path Parameters
- **app** (string) - Required - The application identifier.
- **user** (string) - Required - The user identifier.

### Response
#### Success Response (200)
- **sessions** (array) - A list of session identifiers.

#### Response Example
```json
{
  "sessions": ["session1", "session2"]
}
```
```

```APIDOC
## GET /apps/{app}/users/{user}/sessions/{session}

### Description
Fetch session details, including state and events.

### Method
GET

### Endpoint
/apps/{app}/users/{user}/sessions/{session}

### Parameters
#### Path Parameters
- **app** (string) - Required - The application identifier.
- **user** (string) - Required - The user identifier.
- **session** (string) - Required - The session identifier.

### Response
#### Success Response (200)
- **state** (object) - The current state of the session.
- **events** (array) - A list of events that occurred in the session.

#### Response Example
```json
{
  "state": { ... },
  "events": [ { ... }, { ... } ]
}
```
```

--------------------------------

### Execution Endpoints

Source: https://github.com/yogirk/selecta/blob/main/backend/api-contract.md

Endpoints for executing tasks, either synchronously or via streaming Server-Sent Events.

```APIDOC
## POST /run

### Description
Execute a synchronous run (non-streaming).

### Method
POST

### Endpoint
/run

### Request Body
(Details of the request body for execution)

### Request Example
```json
{
  "query": "What is the total sales for last month?"
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the synchronous execution.

#### Response Example
```json
{
  "result": { ... }
}
```
```

```APIDOC
## POST /run_sse

### Description
Stream agent events via Server‑Sent Events. Selecta enriches the `actions.stateDelta` with structured result metadata.

### Method
POST

### Endpoint
/run_sse

### Request Body
(Details of the request body for streaming execution)

### Request Example
```json
{
  "query": "Show me a chart of daily active users."
}
```

### Response
#### Success Response (200)
- **SSE Events** - Server-Sent Events with JSON payloads identical to ADK `Event` objects.
  - **latest_result** (object) - The newest query result.
  - **results_history** (array) - Array of previous results.
  - **summary**, **resultsMarkdown**, **businessInsights** (optional legacy fields).

#### Response Example (SSE Event Payload)
```json
{
  "type": "action",
  "action": {
    "id": "action-123",
    "actions": {
      "stateDelta": {
        "latest_result": {
          "id": "uuid",
          "sql": "SELECT ...",
          "rows": [{ "column": "value" }],
          "columns": ["column"],
          "rowCount": 10,
          "chart": { "$schema": "https://vega.github.io/schema/vega-lite/v5.json", "..." : "..." },
          "chartOptions": [
            {
              "id": "bar-horizontal",
              "label": "Bar (Horizontal)",
              "spec": { "...": "..." }
            }
          ],
          "defaultChartId": "bar-horizontal",
          "summary": "### Summary ...",
          "resultsMarkdown": "| column | ...",
          "businessInsights": [
            "Insight bullet",
            "Another insight"
          ],
          "createdAt": 1760949425760,
          "executionMs": 2840,
          "jobId": "bquxjob_123",
          "dataset": {
            "id": "thelook_ecommerce",
            "projectId": "bigquery-public-data",
            "billingProjectId": "cloudside-academy",
            "location": "US",
            "tables": ["orders", "order_items", "products", "users"]
          }
        },
        "results_history": [],
        "summary": "### Summary ...",
        "resultsMarkdown": "| column | ...",
        "businessInsights": [
          "Insight bullet"
        ]
      }
    }
  }
}
```
```

--------------------------------

### Frontend Error Display with TypeScript

Source: https://context7.com/yogirk/selecta/llms.txt

This TypeScript code snippet shows how to display errors to the user in a frontend application using React and Zustand for state management. It conditionally renders an error panel based on the `activeError` state, displaying details like the error message, type, BigQuery job ID, and the SQL query that caused the issue.

```typescript
// Frontend: Error is displayed to user
import { useStore } from '@/lib/store';

function ErrorPanel() {
  const activeError = useStore(state => state.activeError);

  if (!activeError) return null;

  return (
    <div className="error-panel">
      <h3>Query Error</h3>

      {/* Error message */}
      <p className="text-red-600">{activeError.message}</p>

      {/* Error type and code */}
      <p>Type: {activeError.type}</p>
      {activeError.errorCode && <p>Code: {activeError.errorCode}</p>}

      {/* BigQuery job ID for debugging */}
      {activeError.jobId && (
        <p>Job ID: <code>{activeError.jobId}</code></p>
      )}

      {/* SQL that caused the error */}
      <details>
        <summary>View SQL</summary>
        <pre className="bg-gray-100 p-2">{activeError.sql}</pre>
      </details>

      {/* Detailed error information from BigQuery */}
      {activeError.details && activeError.details.length > 0 && (
        <details>
          <summary>Error Details</summary>
          {activeError.details.map((detail, i) => (
            <div key={i}>
              <p>{detail.message}</p>
              {detail.reason && <p>Reason: {detail.reason}</p>}
              {detail.location && <p>Location: {detail.location}</p>}
            </div>
          ))}
        </details>
      )}

      {/* Timestamp */}
      <p className="text-sm text-gray-500">
        {new Date(activeError.timestamp).toLocaleString()}
      </p>
    </div>
  );
}

```

--------------------------------

### JSON Chart Output Structure

Source: https://context7.com/yogirk/selecta/llms.txt

Defines the expected JSON structure for chart specifications, including default chart IDs and configurations for different chart types like line and area. This structure is used to represent visualized data.

```json
{
  "defaultChartId": "line",
  "charts": [
    {
      "id": "line",
      "label": "Line",
      "spec": {
        "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
        "data": {"values": [...]},
        "mark": {
          "type": "line",
          "tooltip": True,
          "point": {"filled": True, "size": 45, "opacity": 0.85},
          "strokeWidth": 2.5
        },
        "encoding": {
          "x": {"field": "month", "type": "temporal"},
          "y": {"field": "revenue", "type": "quantitative"},
          "tooltip": [...] 
        },
        "config": {...},  # Themed with purple palette
        "height": 320,
        "width": "container"
      }
    },
    {
      "id": "area",
      "label": "Area",
      "spec": {...}
    }
  ]
}
```

--------------------------------

### ADK Server Result Schema

Source: https://github.com/yogirk/selecta/blob/main/backend/api-contract.md

The JSON schema defining the structure of results returned by the ADK server. This schema includes fields for the executed SQL query, returned rows and columns, row count, chart specifications, execution time, and dataset information. It also contains optional legacy fields for compatibility.

```json
{
  "id": "uuid",                        // stable per execution
  "sql": "SELECT ...",
  "rows": [{ "column": "value" }],
  "columns": ["column"],
  "rowCount": 10,
  "chart": { "$schema": "https://vega.github.io/schema/vega-lite/v5.json", "..." : "..." },
  "chartOptions": [
    {
      "id": "bar-horizontal",
      "label": "Bar (Horizontal)",
      "spec": { "...": "..." }
    },
    {
      "id": "bar-vertical",
      "label": "Bar (Vertical)",
      "spec": { "...": "..." }
    }
  ],
  "defaultChartId": "bar-horizontal",
  "summary": "### Summary ...",
  "resultsMarkdown": "| column | ...",
  "businessInsights": [
    "Insight bullet",
    "Another insight"
  ],
  "createdAt": 1760949425760,          // epoch millis
  "executionMs": 2840,                 // BigQuery run time
  "jobId": "bquxjob_123",
  "dataset": {
    "id": "thelook_ecommerce",
    "projectId": "bigquery-public-data",
    "billingProjectId": "cloudside-academy",
    "location": "US",
    "tables": ["orders", "order_items", "products", "users"]
  }
}
```
Tokens:
Raw