Generative AI Toolkit for SAP HANA Cloud

_images/SAP_R_grad2.jpg

Welcome to Generative AI Toolkit for SAP HANA Cloud (hana.ai)!

This package enables the users to access SAP HANA data and build various machine learning models using the data directly in SAP HANA via natural language. This page provides an overview of hana.ai.

Generative AI Toolkit for SAP HANA Cloud consists of five main parts:

  • AI tools, which provides a set of tools to analyze data and build machine learning models.

  • HANA Vector Store and Knowledge Base API, which provides a way to store and retrieve vectors and knowledge bases.

  • Smart DataFrame, which is a HANA dataframe Agent to interact with HANA data.

  • ContextAgent, which provides the recommended way to interact with the AI tools via natural language using Markdown-backed memory and runtime skill routing.

  • MCP server, which exposes the toolkit's tools (including the HANA object discovery and data retrieval tools) over either stdio or HTTP transport with structured audit context.

Prerequisites

ContextAgent with HANAML Toolkit

HANAML Toolkit is a set of tools to analyze data and build machine learning models using the data directly in SAP HANA. It can be consumed by ContextAgent. cc is a connection to a SAP HANA instance.

from hana_ai.agents.context_agent import ContextAgent
from hana_ai.tools.toolkit import HANAMLToolkit

tools = HANAMLToolkit(connection_context=cc, used_tools='all').get_tools()
chatbot = ContextAgent(llm=llm, tools=tools, storage_dir=".context_agent")
A ContextAgent with HANAML Toolkit.

ContextAgent currently supports workflow skills for dataset preparation, time-series profiling, forecasting, prediction-result analysis, outlier inspection, grouped forecasting, model lifecycle operations, and dataframe-oriented fallback steps.

used_tools='all' does not enable Python execution or include the separate SQL agent. Select tools and HANA privileges for the intended workflow: model training, storage and deletion can require write/execute privileges. The SQL agent's read-only checks do not apply to those tools. See Changelog for the security defaults and migration notes.

ContextAgent also supports command-style controls during chat calls:

  • Memory commands: !clear_notes, !clear_session, !reset_memory, !clear_notes_file, !clear_todo, !clear_decisions, !clear_context, !clear_chat, !clear_summary

  • Skill commands: !list_skills, !active_skills, !skills_on, !skills_off, !enable_skill <skill_name>, !disable_skill <skill_name>

HANA Vector Store and Knowledge Base API

Create Knowledge Base for hana-ml codes in HANA Vector Engine.

from hana_ai.vectorstore.hana_vector_engine import HANAMLinVectorEngine

hana_vec = HANAMLinVectorEngine(connection_context=cc, table_name="hana_vec_hana_ml_knowledge")
hana_vec.create_knowledge()

Create Code Template Tool and Add Knowledge Bases to It

Create a code template tool and add knowledge bases to it.

from hana_ai.tools.code_template_tools import GetCodeTemplateFromVectorDB

code_tool = GetCodeTemplateFromVectorDB()
code_tool.set_vectordb(vectordb=hana_vec)

Create HANA Dataframe Agent and Retrieve Templates

The legacy dataframe agent is deprecated; prefer ContextAgent for new workflows. It requires explicit tools by default. This example retrieves code templates; it does not execute Python or generate report files.

from hana_ai.agents.hana_dataframe_agent import create_hana_dataframe_agent

hana_df = cc.table("MY_DATA")
agent = create_hana_dataframe_agent(
    llm=llm, df=hana_df, tools=[code_tool], verbose=True
)
agent.invoke("Retrieve example code for a dataset report. Do not execute it.")

For report generation or model operations, register the corresponding dedicated tools with ContextAgent. Python/REPL execution is disabled by default; the explicit trusted-code opt-in is not a sandbox and must not be exposed to untrusted callers.

Smart DataFrame

Smart DataFrame is a HANA dataframe Agent to interact with HANA data.

from hana_ai.smart_dataframe import SmartDataFrame

sdf = SmartDataFrame(dataframe=hana_df)
sdf.configure(llm=llm)
new_df = sdf.transform(question="Get first two rows")
new_df.collect()
A Smart DataFrame's transformed result.

transform() accepts a single read-only SELECT/WITH query generated by the model. Unsafe statements and embedded semicolons are rejected; one trailing statement terminator is removed. This validation does not restrict the database privileges of other tools available through ask().