Metadata-Version: 2.4
Name: hana_ai
Version: 1.1.26110100
Summary: Generative AI Toolkit for SAP HANA Cloud
Author: SAP
License: Apache-2.0
Project-URL: Homepage, https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud
Project-URL: Documentation, https://sap.github.io/generative-ai-toolkit-for-sap-hana-cloud/
Project-URL: Report Issues, https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/issues
Project-URL: Notebook Examples, https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/tree/main/nutest/testscripts
Keywords: Generative AI Toolkit SAP HANA Cloud
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-community<0.4,>=0.3.18
Requires-Dist: langchain-text-splitters<0.4,>=0.3.11
Requires-Dist: numpy<2,>=1.26.4; python_version < "3.12"
Requires-Dist: numpy<3,>=2.2.3; python_version >= "3.12"
Requires-Dist: pandas<3,>=2.2.3
Requires-Dist: hana-ml<3,>=2.29.26072000
Requires-Dist: pydantic<3,>=2.11.7
Requires-Dist: langchain-hana<0.4,>=0.3.4
Requires-Dist: fastmcp<3,>=2.14.7
Provides-Extra: nlp
Requires-Dist: nltk<4,>=3.9; extra == "nlp"
Provides-Extra: graph
Requires-Dist: langgraph<1,>=0.2; extra == "graph"
Provides-Extra: all
Requires-Dist: sap-ai-sdk-gen[all]<6,>=5.11.0; extra == "all"
Requires-Dist: nltk<4,>=3.9; extra == "all"
Requires-Dist: langgraph<1,>=0.2; extra == "all"
Dynamic: license-file

[![REUSE status](https://api.reuse.software/badge/github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud)](https://api.reuse.software/info/github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud)

# Generative AI Toolkit for SAP HANA Cloud

## About this project

Generative AI Client for SAP HANA Cloud is an extension of the existing HANA ML Python client library, mainly focusing on GenAI and related use cases. It includes many leading-edge GenAI related open source libraries and provides seamless integration with HANA ML, HANA vector engine, and other SAP GenAI Hub SDK, see our [Introduction](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/blob/main/INTRODUCTION.md), [Notebook](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/blob/main/nutest/testscripts/demo/e2e_scenarios/context_agent.ipynb) and [Documentation](https://sap.github.io/generative-ai-toolkit-for-sap-hana-cloud/).

## Requirements and Setup

The prerequisites for using the Generative AI Toolkit for SAP HANA Cloud are listed at [Prerequisites](https://sap.github.io/generative-ai-toolkit-for-sap-hana-cloud/hana_ai.html#prerequisites).

The Generative AI Toolkit for SAP HANA Cloud is available as a Python package. You can install it via `pip`:

```bash
pip install hana-ai
```

## ContextAgent

The toolkit includes a file-based ContextAgent for conversational forecasting and data-preparation workflows with Markdown-backed memory, tool calling, and runtime-selectable skills.

Core ContextAgent skills include:

- `data_ingestion_and_dataset_preparation` for CSV import and time-ordered train, test, and validation table creation
- `timeseries_data_profiling` for dataset reports and statistical checks before model selection
- `timeseries_forecasting` for single-series train, predict, score, and plot workflows
- `prediction_result_analysis` for predicted-versus-actual comparison and quality analysis
- `outlier_detection_and_repair_prep` for anomaly inspection before model training
- `massive_forecasting` for grouped forecasting across many related series
- `model_lifecycle_and_artifacts` for listing, deleting, and packaging saved models
- `hana_dataframe_fallback` for SQL transformations (Python fallback requires explicit trusted-host opt-in)

## Tools

The toolkit exposes HANAML-oriented tools for data preparation, profiling, forecasting, evaluation, artifact generation, and grouped forecasting workflows.

Core forecasting and analysis tools include:

- `import_csv_to_table`, `split_table_for_forecasting`, `fetch_data`
- `ts_dataset_report`, `ts_check`, `stationarity_test`, `trend_test`, `seasonality_test`, `white_noise_test`
- `automatic_timeseries_fit_and_save`, `automatic_timeseries_load_model_and_predict`, `automatic_timeseries_load_model_and_score`
- `additive_model_forecast_fit_and_save`, `additive_model_forecast_load_model_and_predict`, `intermittent_forecast`
- `ts_outlier_detection`, `ts_make_future_table`, `forecast_line_plot`, `accuracy_measure`
- `list_models`, `delete_models`, `cap_artifacts`, `hdi_artifacts`
- `SelectStatement_to_table`

Grouped and massive forecasting tools include:

- `massive_ts_check`, `massive_ts_outlier_detection`
- `massive_automatic_timeseries_fit_and_save`, `massive_automatic_timeseries_load_model_and_predict`, `massive_automatic_timeseries_load_model_and_score`
- `massive_additive_model_forecast_fit_and_save`, `massive_additive_model_forecast_load_model_and_predict`
- `ts_make_future_table_for_massive_forecast`

See the ContextAgent notebook for an end-to-end example at [nutest/testscripts/demo/e2e_scenarios/context_agent.ipynb](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/blob/main/nutest/testscripts/demo/e2e_scenarios/context_agent.ipynb).

### Python execution trust boundary

`python_hanaml_exec` is **disabled by default** and is not included in the default
`HANAMLToolkit` tool list, including `used_tools='all'`, name-based selection, and
connection refreshes. Directly constructed instances also refuse to execute code
unless the host explicitly opts in. Tool-call arguments cannot enable execution.

This tool is **not a sandbox**. Code runs in the host process with its filesystem,
network, and HANA database permissions. The AST checks and reduced builtins are
best-effort guardrails only: full pandas/hana-ml objects support file I/O and raw
database access, and `sql()` does not enforce SQL authorization. There is no
execution timeout or resource isolation.

Applications that deliberately run **fully trusted code from trusted callers**
must construct `PythonHanaMLExecTool(connection_context=cc, allow_dangerous_code=True)`
from `hana_ai.tools.hana_ml_tools.python_exec_tools` and register that instance
using `toolkit.add_custom_tool(tool)`. Never expose an enabled instance to
untrusted agent or MCP callers. Untrusted-code execution requires a separately
designed OS-level isolation boundary, scoped credentials, and resource limits;
do not rely on this tool's syntax checks for containment.

### SQL agent deployment boundary

The SQL agent requires an explicit schema or table allowlist. For example, pass
`schema="APP_READ"` or `include_tables=["SALES_VIEW"]` to
`create_hana_sql_agent()` and `create_hana_sql_toolkit()`. The application rejects
queries outside that configured scope, but this parser-level check is defense in
depth and does not replace HANA authorization.

Run SQL agents with a dedicated HANA technical user or role that has only the
required `SELECT` privileges on approved schemas, tables, or restricted views. Do
not grant DDL/DML, unrestricted cross-schema access, or procedure execution unless
the application explicitly needs it. Validate effective privileges against the
target HANA deployment as part of release testing. Views and synonyms must be
reviewed together with the privileges of their underlying objects.

### MCP transport and vector-store security defaults

Environment-built HANA connections and runtime connection updates explicitly enable
TLS encryption and certificate validation by default, including omitted/null update
options. Configure the required trust material. Runtime admin tools remain host-opt-in
and require authentication over HTTP; remote MCP also requires HTTPS termination.
The HTTP client's insecure-network override requires the actual Boolean
`allow_insecure_http=True`, not a string such as `"false"`. Stdio profiles must point
to trusted executables and arguments; shell interpreters and Windows batch/PowerShell
scripts are rejected even when listed in a profile. Keep those executables, scripts,
their directories, and the inherited environment under trusted host control.

Vector-store configuration is validated before metadata lookup or table creation.
Table/schema names containing single quotes are rejected because the supported
hana-ml metadata API interpolates them into SQL literals. Existing double-quote,
NUL, and semicolon restrictions still apply. Ordinary case-sensitive names and
query text containing apostrophes remain supported through safe encoding.

## Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/blob/main/CONTRIBUTING.md).

## Security / Disclosure
If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.

## Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.

## Licensing

Copyright 2026 SAP SE or an SAP affiliate company and generative-ai-toolkit-for-sap-hana-cloud contributors. Please see our [LICENSE](https://github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud/blob/main/LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/generative-ai-toolkit-for-sap-hana-cloud).
