bigquery-data-science 0.8.2__tar.gz → 0.9.0__tar.gz

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to `bigquery-data-science` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-10-21
+
+### Added
+- **CLI, Catalog, MCP Server & Google ADK Rollout (`P3.1`–`P3.5`):**
+  - **MCP `resources` & `prompts` Protocol Support (`P3.1`):** Extended `bigquery-data-science mcp` (`src/bigquery_data_science/mcp_server.py`) with `resources/list`, `resources/templates/list`, and `resources/read` (`bqds://skill/{skill}`, `bqds://reference/{skill}/{name}`, `bqds://syntax/{skill}/{slug}`, `bqds://narrative/{skill}/{topic}`), plus `prompts/list` and `prompts/get` (`design_bigquery_pipeline`, `audit_bigquery_sql`, `compare_ml_vs_ai`, `prevent_feature_leakage`).
+  - **Static SQL Query Reviewer (`P3.2`):** Added `review_sql` / `review` in `src/bigquery_data_science/catalog.py`, `bigquery-data-science review-sql <sql_or_file>` CLI command, and the 5th MCP tool `review_bigquery_sql` to statically audit BigQuery SQL queries against `namespace-matrix.md`, `pinned-models.json`, and empirical guardrails (retired functions, nonexistent `HYBRID_SEARCH`, unpinned foundation models, `TimesFM` covariate version requirements, unnecessary `OBJ.GET_ACCESS_URL`, `xgboost_version`, Enterprise reservation requirements, `ignore_feature_nulls`, and `ML.METRICS` `BOOL` semantics).
+  - **Opt-In `--json` Output Flag (`P3.3`):** Added `--json` across `list`, `lookup`, `search`, `triage`, and `review-sql` while preserving default human-readable text output.
+  - **Opt-In MCP Client Config Registration (`P3.4`):** Added `install_mcp_config` in `src/bigquery_data_science/installer.py` and `bigquery-data-science install --mcp` to non-destructively register the `bigquery-data-science mcp` stdio server in project `.mcp.json` or global `~/.claude.json` / `~/.gemini/settings.json`.
+  - **Google ADK Toolset Wrapper (`P3.5`):** Added `src/bigquery_data_science/adk.py` exporting `get_bigquery_tools()` and typed Python tool functions (`triage_bigquery_task`, `lookup_bigquery_syntax`, `search_bigquery_gotchas`, `get_bigquery_walkthrough`, `review_bigquery_sql`) ready for `google.adk.Agent(tools=get_bigquery_tools())`.
+
 ## [0.8.2] - 2026-10-21
 
 ### Added

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/CITATION.cff

@@ -9,7 +9,7 @@ authors:
 repository-code: "https://github.com/statmike/bigquery-data-science"
 url: "https://github.com/statmike/bigquery-data-science"
 license: Apache-2.0
-version: "0.8.2"
+version: "0.9.0"
 date-released: "2026-10-21"
 keywords:
   - google-cloud

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bigquery-data-science
-Version: 0.8.2
+Version: 0.9.0
 Summary: BigQuery ML, BigQuery AI, and 4-Lens Agent Skills: 104 live-verified SQL/Python workflows, zero-dependency CLI catalog & skill installer, and stdio MCP server.
 Project-URL: Homepage, https://github.com/statmike/bigquery-data-science
 Project-URL: Repository, https://github.com/statmike/bigquery-data-science
@@ -154,6 +154,7 @@ The core `bigquery-data-science` package has **zero third-party runtime dependen
 ```bash
 # Option A — Zero-install ephemeral CLI via uvx (recommended for instant setup):
 uvx bigquery-data-science install                     # installs into ./.agents/skills & ./.claude/skills
+uvx bigquery-data-science install --mcp               # also registers stdio MCP server in ./.mcp.json
 uvx bigquery-data-science install --global            # installs into ~/.agents/skills & ~/.claude/skills
 uvx bigquery-data-science install --target agents     # only .agents/skills (Antigravity, Cursor, Codex, Windsurf)
 uvx bigquery-data-science install --target claude     # only .claude/skills (Claude Code)
@@ -197,6 +198,12 @@ uvx bigquery-data-science lookup ML.ENTITY_FEATURES_AT_TIME
 
 # 4. Search across all 137 syntax cards, 14 reference guides, and 104 narratives:
 uvx bigquery-data-science search "point-in-time feature leakage"
+
+# 5. Statically audit a BigQuery SQL query or .sql file for prerequisites & gotchas:
+uvx bigquery-data-science review-sql "SELECT AI.GENERATE('Summarize', endpoint => 'gemini-3.5-flash')"
+
+# 6. Add --json to any catalog command (list, lookup, search, triage, review-sql) for automation:
+uvx bigquery-data-science lookup AI.AGG --json
 ```
 
 ### Journey 3 — Run the 104 ground-truth notebooks & SQL scripts (`uv` or `pip`)

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/README.md

@@ -66,6 +66,7 @@ The core `bigquery-data-science` package has **zero third-party runtime dependen
 ```bash
 # Option A — Zero-install ephemeral CLI via uvx (recommended for instant setup):
 uvx bigquery-data-science install                     # installs into ./.agents/skills & ./.claude/skills
+uvx bigquery-data-science install --mcp               # also registers stdio MCP server in ./.mcp.json
 uvx bigquery-data-science install --global            # installs into ~/.agents/skills & ~/.claude/skills
 uvx bigquery-data-science install --target agents     # only .agents/skills (Antigravity, Cursor, Codex, Windsurf)
 uvx bigquery-data-science install --target claude     # only .claude/skills (Claude Code)
@@ -109,6 +110,12 @@ uvx bigquery-data-science lookup ML.ENTITY_FEATURES_AT_TIME
 
 # 4. Search across all 137 syntax cards, 14 reference guides, and 104 narratives:
 uvx bigquery-data-science search "point-in-time feature leakage"
+
+# 5. Statically audit a BigQuery SQL query or .sql file for prerequisites & gotchas:
+uvx bigquery-data-science review-sql "SELECT AI.GENERATE('Summarize', endpoint => 'gemini-3.5-flash')"
+
+# 6. Add --json to any catalog command (list, lookup, search, triage, review-sql) for automation:
+uvx bigquery-data-science lookup AI.AGG --json
 ```
 
 ### Journey 3 — Run the 104 ground-truth notebooks & SQL scripts (`uv` or `pip`)

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "bigquery-data-science",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "BigQuery ML, BigQuery AI, and 4-Lens Agent Skills for SQL and Python data science on Google Cloud: task routing, prerequisite matrix, surgical syntax cards, and 104 live-verified walkthroughs.",
   "author": {
     "name": "Mike Henderson",

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bigquery-data-science"
-version = "0.8.2"
+version = "0.9.0"
 description = "BigQuery ML, BigQuery AI, and 4-Lens Agent Skills: 104 live-verified SQL/Python workflows, zero-dependency CLI catalog & skill installer, and stdio MCP server."
 dynamic = ["readme"]
 requires-python = ">=3.11"

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/scripts/check_install.sh

@@ -81,10 +81,14 @@ grep -q "bigquery-ai" <<<"$LIST_OUT" || fail "list missing bigquery-ai"
 "$BIN/bigquery-data-science" check-markdown --repo-root "$REPO_ROOT" >/dev/null || fail "check-markdown failed"
 
 TARGET_DIR="$WORK/installed-skills"
-"$BIN/bigquery-data-science" install --target "$TARGET_DIR" >/dev/null || fail "install failed"
+"$BIN/bigquery-data-science" install --target "$TARGET_DIR" --mcp >/dev/null || fail "install failed"
 [[ -f "$TARGET_DIR/bigquery-data-science/SKILL.md" ]] || fail "installed bigquery-data-science/SKILL.md missing"
 [[ -f "$TARGET_DIR/bigquery-ml/SKILL.md" ]] || fail "installed bigquery-ml/SKILL.md missing"
 [[ -f "$TARGET_DIR/bigquery-ai/SKILL.md" ]] || fail "installed bigquery-ai/SKILL.md missing"
+[[ -f "$TARGET_DIR/.mcp.json" ]] || fail "installed .mcp.json missing"
+
+"$BIN/bigquery-data-science" list --json >/dev/null || fail "list --json failed"
+"$BIN/bigquery-data-science" review-sql "SELECT AI.GENERATE('hi', endpoint => 'gemini-3.5-flash')" --json >/dev/null || fail "review-sql --json failed"
 
 ARIMA_OUT="$("$BIN/bigquery-data-science" lookup ARIMA_PLUS)" || fail "lookup ARIMA_PLUS failed"
 grep -qi "ARIMA_PLUS" <<<"$ARIMA_OUT" || fail "lookup ARIMA_PLUS output missing ARIMA_PLUS"
@@ -111,10 +115,13 @@ assert not rel_links, f"Un-rewritten relative links in PyPI Description: {rel_li
 assert "```mermaid" not in desc, "Un-substituted ```mermaid block in PyPI Description"
 
 requests = [
-    {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "smoke", "version": "0.7.0"}}},
+    {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "smoke", "version": "0.9.0"}}},
     {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
     {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "triage_bigquery_task", "arguments": {"query": "forecast daily sales"}}},
     {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "lookup_bigquery_syntax", "arguments": {"symbol": "ARIMA_PLUS"}}},
+    {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "review_bigquery_sql", "arguments": {"sql": "SELECT AI.GENERATE('hi', endpoint => 'gemini-3.5-flash')"}}},
+    {"jsonrpc": "2.0", "id": 6, "method": "resources/list", "params": {}},
+    {"jsonrpc": "2.0", "id": 7, "method": "prompts/list", "params": {}},
 ]
 payload = "\n".join(json.dumps(r) for r in requests) + "\n"
 proc = subprocess.run(
@@ -125,18 +132,24 @@ proc = subprocess.run(
     check=True,
 )
 responses = [json.loads(line) for line in proc.stdout.strip().splitlines() if line.strip()]
-assert len(responses) >= 4, f"Expected 4 JSON-RPC responses, got {len(responses)}"
+assert len(responses) >= 7, f"Expected 7 JSON-RPC responses, got {len(responses)}"
 tool_names = {t["name"] for t in responses[1]["result"]["tools"]}
 expected_tools = {
     "triage_bigquery_task",
     "lookup_bigquery_syntax",
     "search_bigquery_gotchas",
     "get_bigquery_walkthrough",
+    "review_bigquery_sql",
 }
 assert expected_tools <= tool_names, f"Missing MCP tools: {expected_tools - tool_names}"
 assert not responses[2]["result"].get("isError"), f"triage_bigquery_task returned error: {responses[2]}"
 assert not responses[3]["result"].get("isError"), f"lookup_bigquery_syntax returned error: {responses[3]}"
-print(f"   MCP tools verified: {sorted(tool_names)}")
+assert not responses[4]["result"].get("isError"), f"review_bigquery_sql returned error: {responses[4]}"
+assert len(responses[5]["result"]["resources"]) >= 10, "Expected >= 10 MCP resources"
+assert len(responses[6]["result"]["prompts"]) == 4, "Expected 4 MCP prompts"
+from bigquery_data_science.adk import get_bigquery_tools
+assert len(get_bigquery_tools()) == 5
+print(f"   MCP tools verified: {sorted(tool_names)} (+ resources, prompts & ADK toolset)")
 print("   0 relative links in built PyPI Description")
 PY
 

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/skills/bigquery-ai/SKILL.md

@@ -2,7 +2,7 @@
 name: bigquery-ai
 description: Use when calling Gemini, TimesFM, TabFM, or pre-trained Cloud AI services from BigQuery SQL or BigFrames — generation (AI.GENERATE*, AI.COUNT_TOKENS), managed scoring/classification (AI.IF, AI.SCORE, AI.CLASSIFY, AI.AGG), embeddings and vector/hybrid search (AI.EMBED, VECTOR_SEARCH, AI.SEARCH), forecasting/prediction (AI.FORECAST, AI.PREDICT, AI.KEY_DRIVERS), and Cloud AI service models (ML.PROCESS_DOCUMENT, ML.TRANSLATE, ML.TRANSCRIBE).
 metadata:
-  version: "0.8.2"
+  version: "0.9.0"
 ---
 
 # BigQuery AI (`bigquery-ai`)

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/skills/bigquery-ai/skill.manifest.json

@@ -1,10 +1,10 @@
 {
   "name": "bigquery-ai",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "source_project": "bigquery-ai",
   "narrative_sources": {},
   "generated_date": "2026-10-21",
-  "source_commit": "dcd557e",
+  "source_commit": "0dca5d7",
   "reference_files": [
     "augmented-analytics.md",
     "cloud-ai-service-models.md",

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/skills/bigquery-data-science/SKILL.md

@@ -2,7 +2,7 @@
 name: bigquery-data-science
 description: "Use FIRST when someone wants to predict, classify, forecast, embed, search, extract, or explain data in BigQuery and needs to choose between a trained model (bigquery-ml — CREATE MODEL + ML.*), a zero-training generative or foundation model function (bigquery-ai — AI.* + TimesFM + TabFM), or a pre-trained Google Cloud AI service model (ML.PROCESS_DOCUMENT, ML.TRANSLATE, ML.UNDERSTAND_TEXT, ML.ANNOTATE_IMAGE, ML.TRANSCRIBE)."
 metadata:
-  version: "0.8.2"
+  version: "0.9.0"
 ---
 
 # BigQuery Data Science — Umbrella Router & Triage (`bigquery-data-science`)

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/skills/bigquery-data-science/skill.manifest.json

@@ -1,10 +1,10 @@
 {
   "name": "bigquery-data-science",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "source_project": null,
   "narrative_sources": {},
   "generated_date": "2026-10-21",
-  "source_commit": "dcd557e",
+  "source_commit": "0dca5d7",
   "reference_files": [
     "namespace-matrix.md"
   ],

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/skills/bigquery-ml/SKILL.md

@@ -2,7 +2,7 @@
 name: bigquery-ml
 description: Use when training, evaluating, deploying, or monitoring a machine learning model in BigQuery with SQL (CREATE MODEL and ML.* functions) — picking a model type, choosing a preprocessing function, point-in-time feature retrieval, causal inference (including AI.CAUSAL_EFFECT), or production retraining pipelines across 23 model types, 49 functions, 18 workflows, and 8 pipelines.
 metadata:
-  version: "0.8.2"
+  version: "0.9.0"
 ---
 
 # BigQuery ML (`bigquery-ml`)

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/skills/bigquery-ml/skill.manifest.json

@@ -1,13 +1,13 @@
 {
   "name": "bigquery-ml",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "source_project": "bigquery-ml",
   "narrative_sources": {
     "feature_store.md": "functions/feature_store/feature_store.ipynb",
     "feature_store_workflow.md": "workflows/feature_store/feature_store.ipynb"
   },
   "generated_date": "2026-10-21",
-  "source_commit": "dcd557e",
+  "source_commit": "0dca5d7",
   "reference_files": [
     "classification.md",
     "model-management.md",

{bigquery_data_science-0.8.2 → bigquery_data_science-0.9.0}/src/bigquery_data_science/__init__.py

@@ -7,15 +7,20 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("bigquery-data-science")
 except PackageNotFoundError:
-    __version__ = "0.8.2"
+    __version__ = "0.9.0"
 
+from bigquery_data_science.adk import get_bigquery_tools
 from bigquery_data_science.catalog import (
     LookupResult,
+    ReviewFinding,
     SearchHit,
+    SqlReviewResult,
     TriageResult,
     get_walkthrough,
     lookup,
     lookup_symbol,
+    review,
+    review_sql,
     search,
     search_catalog,
     triage,
@@ -28,6 +33,7 @@ from bigquery_data_science.installer import (
     get_skill_path,
     get_skills_dir,
     install_kernel,
+    install_mcp_config,
     install_skills,
     list_bundled_skills,
 )
@@ -36,21 +42,27 @@ list_skills = list_bundled_skills
 
 __all__ = [
     "LookupResult",
+    "ReviewFinding",
     "SearchHit",
+    "SqlReviewResult",
     "TriageResult",
     "__version__",
     "available_skills",
     "bundled_skills_root",
     "discover_federated_skill_dirs",
+    "get_bigquery_tools",
     "get_skill_path",
     "get_skills_dir",
     "get_walkthrough",
     "install_kernel",
+    "install_mcp_config",
     "install_skills",
     "list_bundled_skills",
     "list_skills",
     "lookup",
     "lookup_symbol",
+    "review",
+    "review_sql",
     "search",
     "search_catalog",
     "triage",

bigquery_data_science-0.9.0/src/bigquery_data_science/adk.py

@@ -0,0 +1,116 @@
+"""Google Agent Development Kit (ADK) function-tool wrappers.
+
+Provides zero-dependency, strongly-typed Python functions with Google-style
+docstrings ready to pass directly into ``google.adk.Agent(tools=get_bigquery_tools())``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from bigquery_data_science.catalog import (
+    get_walkthrough,
+    lookup,
+    review,
+    search,
+    triage,
+)
+
+
+def triage_bigquery_task(query: str) -> dict[str, object]:
+    """Arbitrate between BigQuery ML and BigQuery AI for a data science task.
+
+    Args:
+        query: Natural-language description of the data science or SQL task
+            (for example, 'forecast daily store sales with holidays').
+
+    Returns:
+        Dictionary containing the task category, recommended primary skill,
+        ranked SQL/model options, empirical tradeoffs, prerequisites, and next steps.
+    """
+    return triage(query)
+
+
+def lookup_bigquery_syntax(symbol: str) -> dict[str, object]:
+    """Look up the syntax card, prerequisites, and gotchas for a BigQuery symbol.
+
+    Args:
+        symbol: BigQuery ML model_type or SQL function name (for example,
+            'ARIMA_PLUS', 'AI.FORECAST', 'AI.AGG', or 'VECTOR_SEARCH').
+
+    Returns:
+        Dictionary containing the syntax card content, prerequisite rows from
+        namespace-matrix.md, empirical gotchas, and related walkthrough paths.
+    """
+    return lookup(symbol)
+
+
+def search_bigquery_gotchas(
+    query: str,
+    skill: str = "",
+    limit: int = 10,
+) -> list[dict[str, object]]:
+    """Search empirical gotchas, reference guides, syntax cards, and walkthroughs.
+
+    Args:
+        query: Keywords or phrase to search for across the bundled skills.
+        skill: Optional skill name filter ('bigquery-data-science', 'bigquery-ml',
+            or 'bigquery-ai'). Leave empty to search all three skills.
+        limit: Maximum number of ranked hits to return (default: 10).
+
+    Returns:
+        List of ranked search hit dictionaries with skill, lens, file_path,
+        title, snippet, and relevance score.
+    """
+    skill_filter = skill.strip() if skill and skill.strip() else None
+    safe_limit = limit if isinstance(limit, int) and limit > 0 else 10
+    return search(query, limit=safe_limit, skill=skill_filter)
+
+
+def get_bigquery_walkthrough(topic: str) -> dict[str, object]:
+    """Retrieve a complete Lens 4 narrative walkthrough markdown document.
+
+    Args:
+        topic: Walkthrough topic stem (for example, 'arima_plus', 'ai_forecast',
+            'ai_agg', or 'feature_store').
+
+    Returns:
+        Dictionary containing topic, skill, path, found status, and full markdown
+        content with GitHub provenance links.
+    """
+    return get_walkthrough(topic)
+
+
+def review_bigquery_sql(sql: str) -> dict[str, object]:
+    """Statically audit a BigQuery SQL query for prerequisites and empirical gotchas.
+
+    Args:
+        sql: GoogleSQL query string using BigQuery ML (CREATE MODEL / ML.*) or
+            BigQuery AI (AI.* / VECTOR_SEARCH / OBJ.*).
+
+    Returns:
+        Dictionary containing ok status, detected symbols, prerequisite rows,
+        and structured findings (severity, rule, message, remediation).
+    """
+    return review(sql)
+
+
+def get_bigquery_tools() -> list[Callable[..., object]]:
+    """Return the 5 BigQuery Data Science tool callables for Google ADK agents."""
+    return [
+        triage_bigquery_task,
+        lookup_bigquery_syntax,
+        search_bigquery_gotchas,
+        get_bigquery_walkthrough,
+        review_bigquery_sql,
+    ]
+
+
+__all__ = [
+    "get_bigquery_tools",
+    "get_bigquery_walkthrough",
+    "lookup_bigquery_syntax",
+    "review_bigquery_sql",
+    "search_bigquery_gotchas",
+    "triage_bigquery_task",
+]