30min Enterprise Workshop: Data Analysis

This workshop is a docs transcript of demos/enterprise/02_snippets_and_predicates.py and 03_agent_analysis_session.py. Live LLM analysis is optional (HVNB_RUN_LLM_DEMO=1).

You will register readonly SQL snippets and predicates, execute them through the database MCP profile, and simulate an agent analysis session. MCP tool-call logging is documented but not yet shipped on the current release base.

1. Prerequisites

Complete Data connection or ensure demos/data/warehouse.db exists:

rtk bash scripts/sync-env.bash -- --extra sql
rtk uv run python demos/enterprise/01_connect_and_ingest.py

2. Register Snippets and Predicates

Script: demos/enterprise/02_snippets_and_predicates.py Store readonly SQL as db-snippet rows and reusable filters as db-predicate rows:

import heavenbase as hb
import heavenbase.ext as hb_ext

ws = hb.HeavenBase("ent-02-snippets", backends={"main": {"type": "inmem"}})
ws.enable_extension("database")
database_id = hb_ext.ingest_database(ws, "demos/data/warehouse.db", name="warehouse")["database"][0]

ws.upsert(
    "db-snippet",
    {
        "object_id": "snippet-customer-count",
        "database_id": database_id,
        "title": "Count customers",
        "sql": "SELECT COUNT(*) AS n FROM customers",
        "readonly": True,
        "card_text": "count all customers in warehouse",
    },
)

ws.upsert(
    "db-predicate",
    {
        "object_id": "pred-high-spend",
        "column_id": amount_col_id,
        "expression": "amount > :threshold",
        "desc": "Orders above a spend threshold",
        "card_text": "high spend orders filter",
    },
)

3. Run Snippets Through the Database Profile

The database profile extends read/query tool groups and adds run_snippet and suggest_sql. It auto-enables the extension on first use:

toolkit = ws.to_mcp(profile="database")

result = toolkit.run("run_snippet", snippet_id="snippet-customer-count")
print(result["rows"])  # [{"n": ...}]

suggestions = toolkit.run("suggest_sql", question="count customers")
print([row["object_id"] for row in suggestions["snippets"]])

Write snippets are refused unless heavenbase.database.allow_write=true in CM_HVNB (default false).

rtk uv run python demos/enterprise/02_snippets_and_predicates.py

4. Agent Analysis Session

Script: demos/enterprise/03_agent_analysis_session.py Expose the database profile and simulate in-process agent calls:

ws.enable_extension("agent")
toolkit = ws.to_mcp(name="ent-03-database", profile="database")

suggested = toolkit.run("suggest_sql", question="count customers")
counted = toolkit.run("run_snippet", snippet_id="snippet-customer-count")
tables = toolkit.run("query", entity="db-table", spec={"select": ["table_name"], "limit": 5})

Serve for external agents:

hb mcp serve --workspace ent-03-analysis --profile database

Optional live LLM analysis (requires provider credentials):

HVNB_RUN_LLM_DEMO=1 rtk uv run python demos/enterprise/03_agent_analysis_session.py

The script uses deepseek-v4-flash and attaches the database MCP toolkit to an LLMSession.

5. Session Logging (Planned)

MCP tool-call logging via heavenbase.mcp.log_sessions is specified in the prototype plan but not implemented on the current release base. CLI logging through hb llm chat and hb llm session is shipped today. When MCP logging lands, enterprise demo 03 documents three meta-analysis queries over agent-message rows:

Tool frequency — group by tool_name
Error rate — filter rows where error_flag is true
Slow calls — sort by duration_ms descending

Summary

Readonly db-snippet rows execute safely through the database profile; write access stays off by default.
suggest_sql searches snippets and predicates by card text without calling an LLM inside the engine.
Agents connect through MCP with a small, schema-aware tool surface scoped to db-* entities.

Further Exploration

Related resources:

Data connection — Ingest and browse schema entities
MCP toolkit reference — Profile and tool tables
Agent extension — Sessions, skills, and CLI logging
Enterprise demo track — Full runnable scripts

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

30min Enterprise Workshop: Data Analysis

1. Prerequisites

2. Register Snippets and Predicates

3. Run Snippets Through the Database Profile

4. Agent Analysis Session

5. Session Logging (Planned)

Summary

Further Exploration

​1. Prerequisites

​2. Register Snippets and Predicates

​3. Run Snippets Through the Database Profile

​4. Agent Analysis Session

​5. Session Logging (Planned)

​Summary

​Further Exploration

1. Prerequisites

2. Register Snippets and Predicates

3. Run Snippets Through the Database Profile

4. Agent Analysis Session

5. Session Logging (Planned)

Summary

Further Exploration