> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 30min Enterprise Workshop: Data Analysis

> Register readonly SQL snippets, run them through the database MCP profile, and simulate agent analysis.

<Note>
  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`).
</Note>

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.

<br />

## 1. Prerequisites

Complete [Data connection](/quickstart/data-connection) or ensure `demos/data/warehouse.db` exists:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk bash scripts/sync-env.bash -- --extra sql
rtk uv run python demos/enterprise/01_connect_and_ingest.py
```

<br />

## 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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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",
    },
)
```

<br />

## 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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk uv run python demos/enterprise/02_snippets_and_predicates.py
```

<br />

## 4. Agent Analysis Session

**Script:** `demos/enterprise/03_agent_analysis_session.py`

Expose the database profile and simulate in-process agent calls:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb mcp serve --workspace ent-03-analysis --profile database
```

Optional live LLM analysis (requires provider credentials):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

<br />

## 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

<br />

## 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.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Data connection](/quickstart/data-connection) — Ingest and browse schema entities
  * [MCP toolkit reference](/reference/mcp-toolkit/overview) — Profile and tool tables
  * [Agent extension](/features/agent-extension) — Sessions, skills, and CLI logging
  * [Enterprise demo track](https://github.com/Magolor/HeavenBase/tree/master/demos/enterprise) — Full runnable scripts
</Tip>

<br />