### Backend Setup and Server Start

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Sets up the Python virtual environment, installs backend dependencies, configures environment variables, runs database migrations, and starts the development server with auto-reloading.

```bash
cd backend

# Use Python 3.12 venv (system python may be 3.11)
python3.12 -m venv .venv
source .venv/bin/activate

# Install deps
pip install uv && uv sync --frozen --extra dev

# Required env vars (dev config references these)
export BOW_DATABASE_URL="sqlite:///db/app.db"
export BOW_SMTP_PASSWORD="dummy"

# Create directories and run migrations
mkdir -p db uploads/files uploads/branding
alembic upgrade head

# Start server (auto-reloads on .py changes)
python main.py &
```

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

### Frontend Setup and Development Server

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Installs frontend dependencies using yarn and starts the development server with Hot Module Replacement (HMR) for .vue and .ts files.

```bash
cd frontend
yarn install

# Start dev server (HMR on .vue/.ts changes)
yarn dev &
```

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

### Install Oracle Instant Client

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/data_sources.md

Installs Oracle Instant Client for Linux. Includes downloading, extracting, setting environment variables, and installing required libraries.

```bash
# Download Oracle Instant Client
wget https://download.oracle.com/otn_software/linux/instantclient/2360000/instantclient-basic-linux.x64-23.6.0.24.10.zip

# Extract the Oracle Instant Client
sudo mkdir -p /opt/oracle
sudo unzip instantclient-basic-linux.x64-23.6.0.24.10.zip -d /opt/oracle

# Set environment variables
echo "export LD_LIBRARY_PATH=/opt/oracle/instantclient_23_6:
$LD_LIBRARY_PATH" >> ~/.bashrc
echo "export PATH=/opt/oracle/instantclient_23_6:
$PATH" >> ~/.bashrc
source ~/.bashrc

# Install required libraries
sudo apt-get install libaio1

# Verify the installation
ls /opt/oracle/instantclient_23_6

```

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

### Playwright Verification Setup Commands

Source: https://github.com/bagofwords1/bagofwords/blob/main/sandbox-feedback-loop-save-button.md

These bash commands set up the necessary directory, copy verification files, and install Playwright dependencies for running the test loop.

```bash
mkdir -p /tmp/sticky-verify && cd /tmp/sticky-verify
cp <repo>/tools/sandbox/save-button-sticky/* .
npm i @playwright/test@1.56.1
export PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers

```

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

### Start Backend Server

Source: https://github.com/bagofwords1/bagofwords/blob/main/DEV.md

Starts the backend Python server using uv. The server will be available at http://localhost:8000.

```bash
uv run python main.py
```

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

### Install Dependencies and Set Up Environment

Source: https://github.com/bagofwords1/bagofwords/blob/main/sandbox-feedback-loop.md

Installs project dependencies using uv and sets the database URL for local SQLite usage. Ensure you are using Python 3.12.

```bash
cd backend
pip install uv
uv sync --frozen --extra dev

# Required by bow-config.dev.yaml (database.url: ${BOW_DATABASE_URL})
export BOW_DATABASE_URL="sqlite:///db/app.db"
mkdir -p db
```

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

### Install Backend Dependencies with uv

Source: https://github.com/bagofwords1/bagofwords/blob/main/DEV.md

Installs development dependencies for the backend using uv, creating a virtual environment.

```bash
cd backend
uv sync --extra dev
```

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

### Install Frontend Dependencies with Yarn

Source: https://github.com/bagofwords1/bagofwords/blob/main/DEV.md

Installs frontend dependencies using Yarn.

```bash
cd frontend
yarn install
```

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

### Install System Dependencies

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Installs necessary system packages for building psycopg2 and upgrades setuptools for dependency management.

```bash
# Needed for psycopg2 build
apt-get install -y libpq-dev

# Upgrade setuptools (needed for thrift transitive dep)
pip install --upgrade setuptools
```

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

### Set Up Python 3.12 Virtual Environment

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/druid-connector.md

Installs necessary packages for unit testing the Druid connector. It creates a virtual environment, installs a light set of requirements, and sets up the database URL.

```bash
cd backend
python3.12 -m venv /tmp/venv312
/tmp/venv312/bin/pip install -q --upgrade pip
grep -ivE '^psycopg2|^pyspark|^thrift|^pyodbc|^grpcio-tools|^confluent-kafka|^snowflake|^cx[-_]Oracle|^oracledb|^pymssql|^sqlalchemy-bigquery|^google-cloud|^pydruid' \
  requirements_versioned.txt > /tmp/reqs_lite.txt
/tmp/venv312/bin/pip install -q -r /tmp/reqs_lite.txt

# Required by bow-config.dev.yaml (database.url: ${BOW_DATABASE_URL})
export BOW_DATABASE_URL="sqlite:///db/app.db"
mkdir -p db
```

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

### Install with TLS and Google OAuth

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Helm command to install the application with TLS enabled and Google OAuth configured. Assumes cert-manager is installed for automatic certificate provisioning.

```bash
helm upgrade -i -n <namespace> <release> bow/bagofwords --set host=<HOST> --set postgresql.auth.username=<PG-USER> --set postgresql.auth.password=<PG-PASS> --set postgresql.auth.database=<PG-DB> --set config.googleOauthEnabled=true --set config.googleClientId=<CLIENT_ID> --set config.googleClientSecret=<CLIENT_SECRET>
```

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

### Install Dependencies

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/README.md

Installs project dependencies using npm, pnpm, yarn, or bun.

```bash
# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

# bun
bun install
```

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

### Install backend dependencies with uv

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/snyk-dependency-scanning.md

Synchronize the backend environment using uv to ensure all locked dependencies, including pip, are installed.

```bash
cd backend

# 1. Install the locked environment (and pip, which Snyk's pip plugin imports)
uv sync --frozen --no-dev
uv pip install pip
```

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

### Install Demo Data Source (Chinook)

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Installs the Chinook SQLite demo data source into the sandbox environment. This involves two steps: initiating the demo installation and then saving the resulting data source ID.

```bash
# 4. Install demo data source (chinook SQLite)
curl http://localhost:8000/api/data_sources/demos \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organization-Id: $ORG_ID"
```

```bash
curl -X POST http://localhost:8000/api/data_sources/demos/$DEMO_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organization-Id: $ORG_ID"
```

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

### Start Development Server

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/README.md

Starts the Nuxt 3 development server on http://localhost:3000 using npm, pnpm, yarn, or bun.

```bash
# npm
npm run dev

# pnpm
pnpm run dev

# yarn
yarn dev

# bun
bun run dev
```

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

### Start Frontend Development Server

Source: https://github.com/bagofwords1/bagofwords/blob/main/DEV.md

Starts the frontend development server using Yarn. This runs the application in regular mode.

```bash
yarn dev
```

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

### Install Runtime Dependencies with uv

Source: https://github.com/bagofwords1/bagofwords/blob/main/sandbox-feedback-loop-bigquery-db-dtypes.md

Install the application's runtime dependencies using 'uv sync --frozen --no-dev'. This command installs packages from the locked file, including db-dtypes.

```bash
cd backend
pip install uv
UV_HTTP_TIMEOUT=300 uv sync --frozen --no-dev
```

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

### Install pydruid

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/druid-connector.md

Installs the pydruid library, required for interacting with Druid.

```bash
/tmp/venv312/bin/pip install pydruid==0.6.9
```

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

### Example Prompt for Benchmarking

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sse-create-data-bloat.md

This is the prompt used during the benchmark to measure SSE payload size and server resource usage.

```text
show me list of albums
```

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

### Environment Setup and Test Execution

Source: https://github.com/bagofwords1/bagofwords/blob/main/sandbox-feedback-loop.md

Sets up necessary environment variables for database, Entra tenant, and OAuth testing, then executes integration tests for OAuth delegated flows.

```bash
cd backend
export BOW_DATABASE_URL="sqlite:///db/app.db"
export BOW_ENTRA_TENANT_ID=...        # app registration tenant
export BOW_ENTRA_CLIENT_ID=...
export BOW_ENTRA_CLIENT_SECRET=...
export BOW_OAUTH_TEST_DEMO1_EMAIL=...
export BOW_OAUTH_TEST_DEMO1_PASSWORD=...
export BOW_OAUTH_TEST_DEMO2_EMAIL=...
export BOW_OAUTH_TEST_DEMO2_PASSWORD=...
export BOW_FABRIC_SERVER=...          # <id>.datawarehouse.fabric.microsoft.com

/tmp/venv312/bin/python -m pytest tests/integrations/test_oauth_delegated.py \
  -k "TestClientCredentials or TestROPCLogin or TestOBOExchange or TestOBOServiceFunction" -v
```

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

### Install Chromium for Playwright

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Install the Chromium browser executable required by Playwright. This command should be run from the 'frontend' directory.

```bash
cd frontend && npx playwright install chromium
```

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

### Set up Snyk and uv CLI versions

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/snyk-dependency-scanning.md

Ensure you have the minimum required versions of the Snyk CLI and uv installed. Export your Snyk auth token as an environment variable.

```bash
export SNYK_TOKEN=<classic-uuid-token>
snyk --version   # must be >= 1.1304.0
uv --version     # must be >= 0.9.29
```

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

### Bow Configuration Example

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/installation.md

An example YAML configuration file for the Bow application, detailing deployment type, base URL, feature flags, OAuth settings, LLM providers, SMTP settings, and encryption key.

```yaml
## Bow Config:
# Deployment Configuration
deployment:
  type: "saas"  # Options: "saas" or "self_hosted"

base_url: http://0.0.0.0:3000
  
# Feature Flags
features:
  allow_uninvited_signups: true
  allow_multiple_organizations: true # If true, there could be more than 1 organization in the system
  verify_emails: false
  enable_google_oauth: true

google_oauth:
  # Enable Google OAuth and enable Google People API
  client_id: "YOUR_CLIENT_ID"
  client_secret: "YOUR_CLIENT_SECRET"

default_llm:
  - provider_type: "bow"
    provider_name: "Bow"
    api_key: "YOUR_API_KEY"
    models:
      - model_id: "gpt-4o-mini"
        model_name: "bow-small"
        is_default: true
        is_enabled: true
#  - provider_type: "anthropic"
#    provider_name: "Anthropic"
#    api_key: "YOUR_API_KEY"
#    models:
#      - model_id: "claude-3-5-sonnet"
#        model_name: "claude-3-5-sonnet"

smtp_settings:
  host: "smtp.gmail.com"
  port: 587
  username: "YOUR_EMAIL"
  password: "YOUR_PASSWORD"

encryption_key: "YOUR_ENCRYPTION_KEY"

# Example self-hosted configuration:
# deployment:
#   type: "self_hosted"
# features:
#   allow_signups: false
#   allow_multiple_organizations: false
#   show_billing_page: false
#   show_license_page: true
```

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

### Instructions API Calls

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

These commands show how to create a new global instruction and list existing instructions. Instructions guide the AI's behavior.

```bash
# Create instruction
curl -X POST http://localhost:8000/api/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organization-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"content": "Always use metric units", "scope": "global"}'
```

```bash
# List instructions
curl http://localhost:8000/api/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organization-Id: $ORG_ID"
```

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

### Start Bag of Words with Docker Compose

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/deployment-options.mdx

Starts the Bag of Words services using Docker Compose. Ensure a .env file is configured for domain and database credentials.

```bash
docker compose up -d
```

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

### Install Playwright Browsers

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Installs the Chromium browser and its dependencies for Playwright, used for taking frontend screenshots.

```bash
cd frontend
npx playwright install --with-deps chromium
```

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

### Install Sandbox Dependencies

Source: https://github.com/bagofwords1/bagofwords/blob/main/backend/email_sandbox/README.md

Install the necessary packages for running the email sandbox. This includes pytest for testing, pytest-asyncio for async tests, and aiosmtplib/aiosmtpd for SMTP client/server functionality.

```bash
pip install pytest pytest-asyncio aiosmtplib aiosmtpd
cd backend/email_sandbox
python -m pytest            # asyncio_mode=auto via pytest.ini
```

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

### Verify Python and ODBC Installation

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/installation.md

Optional commands to run inside the container to verify that the Python ODBC library is installed and that the SQL Server ODBC driver is available.

```bash
python -c "import pyodbc; print(pyodbc.version)"
odbcinst -q -d -n "ODBC Driver 18 for SQL Server"
```

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

### Example Aurora Deployment with IAM

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/README.md

A concrete example of deploying Bag of Words with an AWS Aurora cluster using IAM authentication, including specific hostnames and IAM role ARN.

```bash
helm upgrade -i --create-namespace \
 -nbowapp-1 bowapp bow/bagofwords \
 --set host=bow.example.com \
 --set database.auth.provider=aws_iam \
 --set database.auth.region=us-east-1 \
 --set database.auth.sslMode=require \
 --set database.host=bow-pg1-instance-1.cry2og862pqb.us-east-1.rds.amazonaws.com \
 --set database.port=5432 \
 --set database.username=bow_user \
 --set database.name=postgres \
 --set serviceAccount.annotations.'eks\.amazonaws\.com/role-arn'=arn:aws:iam::123456789012:role/bow-rds-role
```

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

### Install with Managed PostgreSQL

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Helm command to install the Bag of Words application with a managed PostgreSQL instance, specifying database credentials.

```bash
helm upgrade -i -n <namespace> <release> bow/bagofwords --set postgresql.auth.username=<PG-USER> --set postgresql.auth.password=<PG-PASS> --set postgresql.auth.database=<PG-DB>
```

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

### Use useI18n in Script Setup

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/i18n.md

In Vue's <script setup>, import and destructure `t` and `locale` from `useI18n` once at the top. Use `t(...)` for user-visible strings and `locale.value` for `Intl.*` APIs.

```typescript
const { t, locale } = useI18n()
```

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

### Install without TLS and Custom Hostname

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Helm command to install the application without TLS enabled on the Ingress and with a custom public hostname.

```bash
helm upgrade -i -n <namespace> <release> bow/bagofwords --set host=<HOST> --set postgresql.auth.username=<PG-USER> --set postgresql.auth.password=<PG-PASS> --set postgresql.auth.database=<PG-DB> --set ingress.tls=false
```

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

### Describe Kubernetes Pod

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Command to get detailed information about a specific Kubernetes pod in a given namespace.

```bash
kubectl describe pod <pod> -n <namespace>
```

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

### Install with TLS, Cert-Manager, and Google OAuth

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/README.md

Deploy Bag of Words with TLS enabled, integrated with cert-manager for certificate provisioning, and configured for Google OAuth authentication.

```bash
helm upgrade -i --create-namespace \
 -nbowapp-1 bowapp bow/bagofwords \
 --set host=<HOST> \
 --set postgresql.auth.username=<PG-USER> \
 --set postgresql.auth.password=<PG-PASS> \
 --set postgresql.auth.database=<PG-DB> \
 --set config.googleOauthEnabled=true \
 --set config.googleClientId=<CLIENT_ID> \
 --set config.googleClientSecret=<CLIENT_SECRET>
```

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

### Install Bag of Words Helm Chart with Bundled PostgreSQL

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/deployment-options.mdx

Deploy Bag of Words using the Helm chart, including a bundled PostgreSQL instance. Specify database credentials.

```bash
helm upgrade -i --create-namespace \
 -nbowapp-1 bowapp bow/bagofwords \
 --set postgresql.auth.username=<PG-USER> \
 --set postgresql.auth.password=<PG-PASS> \
 --set postgresql.auth.database=<PG-DB>

```

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

### Use useI18n in <script setup>

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/AGENTS.md

Use `useI18n` to access translation functions and locale. Wrap locale-reactive arrays in `computed` to ensure they update when the locale changes.

```javascript
const { t, locale } = useI18n()

const label = computed(() => {
  return t('some.label')
})
```

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

### Update Sandbox State with Session Data

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

This is a placeholder comment indicating the final step of updating the `sandbox_state.json` file with the retrieved token, organization ID, and data source ID after successful setup.

```bash
# 5. Update sandbox_state.json with token, org_id, ds_id
```

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

### ESLint Configuration for Vue I18n

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/i18n.md

Configuration for `eslint-plugin-vue-i18n` to enforce i18n best practices. It checks for missing keys, unused keys, raw text, and structural divergence across locales. Ensure the plugin is installed and configured in your ESLint setup.

```javascript
module.exports = {
  extends: ['plugin:@intlify/vue-i18n/recommended'],
  settings: {
    'vue-i18n': {
      localeDir: '../locales/*.{json}',
      messageSyntaxVersion: '^9.0.0',
    },
  },
  rules: {
    '@intlify/vue-i18n/no-missing-keys': 'error',
    '@intlify/vue-i18n/no-unused-keys': ['warn', { extensions: ['.vue', '.ts'] }],
    '@intlify/vue-i18n/no-raw-text': ['warn', { ignorePattern: '^[\s—–·•→·:]+$' }],
  },
}
```

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

### Install MSSQL ODBC Driver

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/data_sources.md

Installs the Microsoft ODBC Driver 18 for SQL Server on Ubuntu. Includes steps for adding the Microsoft repository and verifying installation.

```bash
# Update the package list
sudo apt update

# Install unixODBC and its development library
sudo apt install -y unixodbc unixodbc-dev curl gnupg2

# Add the Microsoft repository
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

# Update the package list again
sudo apt update

# Install the ODBC Driver 18 for SQL Server
sudo ACCEPT_EULA=Y apt install -y msodbcsql18

# Verify that the driver is installed
odbcinst -q -d

# Test a DSN-less connection using isql (replace placeholders with actual values)
isql -v "DRIVER={ODBC Driver 18 for SQL Server};SERVER=your_server;DATABASE=your_database;UID=your_username;PWD=your_password"
```

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

### Build and Run Docker Image

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/installation.md

Build the Docker image for the application and then run it as a container, exposing port 3000.

```bash
# Build the Docker image
docker build -t bow .

# Run the container
docker run -p 3000:3000 bow 
```

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

### Run Backend Migrations

Source: https://github.com/bagofwords1/bagofwords/blob/main/DEV.md

Applies database migrations using Alembic within the uv environment.

```bash
uv run alembic upgrade head
```

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

### Initialize Visualization App

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/public/mcp-visualization-app.html

Initiates the visualization app by sending an 'ui/initialize' request to the host and then broadcasting an 'ui/notifications/initialized' notification. It also sets up a listener for 'ui/notifications/tool-result'.

```javascript
async function boot() {
  try {
    // 1. Send ui/initialize
    var initResult = await sendRequest('ui/initialize', { appCapabilities: {}, appInfo: { name: 'bow-visualization', version: '1.0.0' }, protocolVersion: '2026-01-26' });
    // 2. Send ui/notifications/initialized
    sendNotification('ui/notifications/initialized', {});
    // 3. Listen for tool-result from host
    onNotification('ui/notifications/tool-result', function(params) {
      toolResult = params;
      loadVisualization();
    });
    // 4.
```

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

### Bootstrapping the MCP App

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/public/mcp-artifact-app.html

Initializes the MCP App by sending an 'ui/initialize' request, followed by 'ui/notifications/initialized'. It then sets up a listener for 'ui/notifications/tool-result' to trigger artifact loading.

```javascript
async function boot() {
    try {
        // 1. Send ui/initialize
        var initResult = await sendRequest('ui/initialize', { appCapabilities: {}, appInfo: { name: 'bow-artifact', version: '1.0.0' }, protocolVersion: '2026-01-26' });
        // 2. Send ui/notifications/initialized
        sendNotification('ui/notifications/initialized', {});
        // 3. Listen for tool-result from host
        onNotification('ui/notifications/tool-result', function(params) {
            toolResult = params;
            loadArtifact();
        });
        // 4. Listen for tool-input (spec-compliant, not strictly needed)
        onNotification('ui/notifications/tool-input', function(params) {
            // Tool arguments available here if needed
        });
    } catch (e) {
        showError('Initialization failed: ' + String(e));
    }
}
```

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

### First-Time Sandbox User Registration

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Registers a new sandbox user with provided email and password. This is the first step in setting up a new sandbox environment.

```bash
# 1. Register sandbox user
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "sandbox@bow.dev", "password": "Sandbox123!", "name": "Sandbox Admin"}'
```

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

### List Kubernetes Resources

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Command to list all Kubernetes resources within a specified namespace.

```bash
kubectl get all -n <namespace>
```

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

### Preview Production Build

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/README.md

Locally previews the production build of the Nuxt 3 application using npm, pnpm, yarn, or bun.

```bash
# npm
npm run preview

# pnpm
pnpm run preview

# yarn
yarn preview

# bun
bun run preview
```

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

### Initialize Visualization App

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/public/mcp-visualization-app.html

Initializes the visualization application by setting up event listeners for tool input and handling potential initialization errors. This function should be called on application startup.

```javascript
function initialize() {
  try {
    // Listen for tool-result notifications
    onNotification('ui/notifications/tool-result', function(params) {
      // Process tool result and load visualization
      loadVisualization();
    });

    // Also listen for tool-input (not strictly needed, but spec-compliant)
    onNotification('ui/notifications/tool-input', function(params) {
      // Tool arguments — we don't need these, we wait for tool-result
    });
  } catch (e) {
    showError('Initialization failed: ' + String(e));
  }
}
```

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

### GET /api/data_sources/{id}/tools

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/agent-yaml.md

Retrieve the effective tools for a specific agent, which is an overlay merged with default tools.

```APIDOC
## GET /api/data_sources/{id}/tools

### Description
Get the effective tools configured for a specific agent. This includes any per-agent overlay tools merged with the default tools.

### Method
GET

### Endpoint
/api/data_sources/{id}/tools

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the data source (agent) to retrieve tools for.

### Response
#### Success Response (200)
- **(object)** - A map of tool names to their configurations.

#### Response Example
```json
{
  "tool_name_1": {
    "description": "Tool description",
    "parameters": {},
    "return_direct": false
  }
}
```
```

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

### Webhook Adapter Structure

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/webhook-triggers.md

Illustrates the directory structure for webhook adapters, highlighting the base adapter, specific platform adapters, and the factory pattern.

```text
webhook_adapters/
  base.py            # WebhookAdapter ABC: verify(), normalize()
  github_adapter.py  # knows X-Hub-Signature-256, pull_request payload shape
  generic_adapter.py # X-BOW-Signature-256 HMAC, passes payload through
  factory.py
```

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

### Declare BigQuery and db-dtypes Dependencies

Source: https://github.com/bagofwords1/bagofwords/blob/main/sandbox-feedback-loop-bigquery-db-dtypes.md

Explicitly declare the google-cloud-bigquery and db-dtypes dependencies in pyproject.toml to ensure the correct versions are installed.

```toml
"google-cloud-bigquery>=3.42.0,<3.43",
"db-dtypes>=1.4.0,<1.5"
```

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

### Get View Type

Source: https://github.com/bagofwords1/bagofwords/blob/main/frontend/public/mcp-visualization-app.html

Retrieves the type of the view from the provided view object. Defaults to 'table' if no specific type is found.

```javascript
function getViewType(view) {
  if (!view) return 'table';
  return (view.view && view.view.type) || view.type || 'table';
}
```

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

### Install Bag of Words Helm Chart with TLS, Cert-Manager, and Google OAuth

Source: https://github.com/bagofwords1/bagofwords/blob/main/documents/deployment-options.mdx

Deploy Bag of Words using Helm with TLS enabled, cert-manager integration, and Google OAuth configured. Requires custom host and PostgreSQL credentials.

```bash
helm upgrade -i --create-namespace \
 -nbowapp-1 bowapp bow/bagofwords \
 --set host=<HOST> \
 --set postgresql.auth.username=<PG-USER> \
 --set postgresql.auth.password=<PG-PASS> \
 --set postgresql.auth.database=<PG-DB> \
 --set config.googleOauthEnabled=true \
 --set config.googleClientId=<CLIENT_ID> \
 --set config.googleClientSecret=<CLIENT_SECRET>

```

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

### GET /api/evals

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/agent-yaml.md

List the names, descriptions, and IDs of all visible evals. This endpoint provides a summary view of available evaluations.

```APIDOC
## GET /api/evals

### Description
List basic information for all visible evals, including their name, description, and ID.

### Method
GET

### Endpoint
/api/evals

### Response
#### Success Response (200)
- **name** (string) - The name of the eval.
- **description** (string) - A brief description of the eval.
- **id** (string) - The unique identifier of the eval.

#### Response Example
```json
[
  {
    "name": "eval-1",
    "description": "First example eval",
    "id": "eval-uuid-1"
  },
  {
    "name": "eval-2",
    "description": "Second example eval",
    "id": "eval-uuid-2"
  }
]
```
```

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

### GET /api/evals/{name}.yaml

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/agent-yaml.md

Export an eval's full manifest in YAML format. This operation is round-trip safe.

```APIDOC
## GET /api/evals/{name}.yaml

### Description
Export an eval's (test suite) full manifest in YAML format. This is useful for backing up configurations or for use in a "get → edit → apply" workflow.

### Method
GET

### Endpoint
/api/evals/{name}.yaml

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the eval to export.

### Response
#### Success Response (200)
- **(application/yaml)** - The full YAML manifest of the eval.

#### Response Example
```yaml
name: example-eval
description: An example evaluation suite
# ... other eval configuration ...
```
```

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

### GET /api/agents

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/agent-yaml.md

List the names, descriptions, and IDs of all visible agents. This endpoint provides a summary view of available agents.

```APIDOC
## GET /api/agents

### Description
List basic information for all visible agents, including their name, description, and ID.

### Method
GET

### Endpoint
/api/agents

### Response
#### Success Response (200)
- **name** (string) - The name of the agent.
- **description** (string) - A brief description of the agent.
- **id** (string) - The unique identifier of the agent.

#### Response Example
```json
[
  {
    "name": "agent-1",
    "description": "First example agent",
    "id": "agent-uuid-1"
  },
  {
    "name": "agent-2",
    "description": "Second example agent",
    "id": "agent-uuid-2"
  }
]
```
```

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

### Set Existing Secret Reference for Config

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Use this flag when installing from local chart sources to reference an existing secret for configuration.

```bash
--set config.secretRef=<secret-name>
```

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

### Run Single Playwright Test File

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Execute a single Playwright test file, for example, 'tests/reports/create-report.spec.ts'. Ensure you are in the 'frontend' directory.

```bash
cd frontend
npx playwright test tests/reports/create-report.spec.ts
```

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

### Set Existing Secret for PostgreSQL Auth

Source: https://github.com/bagofwords1/bagofwords/blob/main/k8s/AGENTS.md

Use this flag when installing from local chart sources to specify an existing secret for PostgreSQL authentication.

```bash
--set postgresql.auth.existingSecret=<secret-name>
```

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

### Instructions API

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/sandbox-feedback-loop.md

Endpoints for creating and listing instructions.

```APIDOC
## POST /api/instructions

### Description
Creates a new instruction.

### Method
POST

### Endpoint
/api/instructions

### Request Body
- **content** (string) - Required - The content of the instruction.
- **scope** (string) - Required - The scope of the instruction (e.g., "global").

### Request Example
```json
{
  "content": "Always use metric units",
  "scope": "global"
}
```

## GET /api/instructions

### Description
Lists all available instructions.

### Method
GET

### Endpoint
/api/instructions
```

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

### Code Generation Process for `load_step` and `load_entity`

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/load-step-entity.md

Illustrates the code generation pipeline where the AST is scanned for `load_step`/`load_entity` calls, references are resolved asynchronously to DataFrames, and a registry is passed to the execution environment.

```text
codegen ─▶ AST-scan final_code for load_step()/load_entity() literal args
        ─▶ async resolve only those refs → DataFrames (+ access checks)
        ─▶ pass {ref → df} registry into execute_code_async
        ─▶ execute_code builds load_step/load_entity closures over the registry
        ─▶ inject into generate_df namespace (name-based binding)
```

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

### BigQuery Client Pandas Extra Dependency

Source: https://github.com/bagofwords1/bagofwords/blob/main/sandbox-feedback-loop-bigquery-db-dtypes.md

The google-cloud-bigquery package requires 'db-dtypes' to be explicitly installed as an extra, such as 'google-cloud-bigquery[pandas]', if pandas output is desired.

```text
google-cloud-bigquery[pandas]
```

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

### Run Bag of Words with SQLite

Source: https://github.com/bagofwords1/bagofwords/blob/main/README.md

This command runs the Bag of Words application using the default SQLite database. Ensure Docker is installed and running.

```bash
docker run -p 3000:3000 bagofwords/bagofwords
```

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

### Using `load_entity` and `load_step` in `generate_df`

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/load-step-entity.md

Demonstrates how to load a published catalog entity by name and a step from the current report by name within the `generate_df` function. These functions resolve to DataFrames that can be merged.

```python
def generate_df(ds_clients, excel_files, load_step, load_entity):
    revenue  = load_entity("Monthly Revenue Model")  # published catalog entity
    previous = load_step("Raw Customer Data")         # a step from THIS report
    return revenue.merge(previous, on="customer_id")
```

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

### Fork Report API Response

Source: https://github.com/bagofwords1/bagofwords/blob/main/docs/design/fork-report-feature.md

Example response for the fork report endpoint, including the new report's ID, title, and fork lineage.

```json
{
  "id": "new-report-uuid",
  "title": "Fork of Revenue Analysis",
  "forked_from_id": "original-report-uuid",
  "slug": "fork-of-revenue-analysis-abc123"
}
```