sap-cloud-sdk-ai-python

# SAP Cloud SDK for AI (Python)

> **Package rename**: The PyPI package `generative-ai-hub-sdk` is **deprecated** (v4.12.4 is the last release).
> Its successor is **`sap-ai-sdk-gen`** (currently v6.10.0). Code and tutorials referencing
> `generative-ai-hub-sdk` should migrate to `sap-ai-sdk-gen`; the import name remains `gen_ai_hub`.

The official Python SDK for SAP Generative AI Hub and Orchestration Service. It wraps
the native SDKs of model providers (OpenAI, Amazon Bedrock, Google GenAI) and offers
a harmonised LangChain integration and a full Orchestration client — all routed through
SAP AI Core with unified authentication.

## Related Skills

- **sap-ai-core**: Platform setup, deployments, resource groups, and model management in SAP AI Core
- **sap-cloud-sdk-ai**: JavaScript/TypeScript and Java equivalents of this SDK
- **sap-hana-ml**: HANA-side machine learning in Python
- **dependency-upgrade**: Pip dependency hygiene and upgrade patterns

### Related external skills

If your task involves working inside Databricks (notebooks, Unity Catalog, Spark,
SAP Databricks in SAP Business Data Cloud), consider installing the
[Databricks agent skills plugin](https://github.com/databricks/databricks-agent-skills).
Ask whether you would like help installing it — never install unprompted.

## When to Use This Skill

Use this skill when:

- Building Python applications that call LLMs through SAP AI Core / Generative AI Hub
- Using the `gen_ai_hub` Python package (installed as `sap-ai-sdk-gen`)
- Integrating OpenAI, Amazon Bedrock, or Google GenAI models via SAP's proxy
- Implementing LangChain chains with SAP AI Core as the backend
- Using the Orchestration Service from Python (templating, filtering, masking, grounding)
- Migrating code from the deprecated `generative-ai-hub-sdk` to `sap-ai-sdk-gen`
- Generating embeddings through SAP AI Core
- Working with SAP RPT-1 (Relational Pretrained Transformer) for tabular predictions

## Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [Authentication](#authentication)
- [Available Modules](#available-modules)
- [Supported Models](#supported-models)
- [Core Features](#core-features)
- [Bundled Resources](#bundled-resources)

## Quick Start

### Native OpenAI Chat Completion

```python
from gen_ai_hub.proxy.native.openai import chat

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is SAP BTP?"}
]

response = chat.completions.create(
    model_name="gpt-4o-mini",
    messages=messages
)
print(response.choices[0].message.content)
```

### Orchestration Service

```python
from gen_ai_hub.orchestration_v2 import (
    OrchestrationConfig, OrchestrationService,
    ModuleConfig, PromptTemplatingModuleConfig,
    Template, UserMessage, LLMModelDetails
)

config = OrchestrationConfig(
    modules=ModuleConfig(
        prompt_templating=PromptTemplatingModuleConfig(
            prompt=Template(
                template=[UserMessage(role="user", content="{{?question}}")]
            ),
            model=LLMModelDetails(name="gpt-4o-mini")
        )
    )
)

service = OrchestrationService(config=config)
response = service.run(placeholder_values={"question": "What is SAP?"})
print(response.final_result.choices[0].message.content)
```

## Installation

```bash
# All providers + LangChain support
pip install "sap-ai-sdk-gen[all]"

# Default (OpenAI only, no LangChain)
pip install sap-ai-sdk-gen

# Specific providers (without LangChain)
pip install "sap-ai-sdk-gen[google, amazon]"
```

## Authentication

The SDK reads credentials via `AICoreV2Client.from_env()`, which resolves
credentials in this order:

1. **Keyword arguments** passed to `GenAIHubProxyClient(...)`
2. **Environment variables** — `AICORE_CLIENT_ID`, `AICORE_CLIENT_SECRET`,
   `AICORE_AUTH_URL`, `AICORE_BASE_URL`, `AICORE_RESOURCE_GROUP`
3. **Config file** — `$AICORE_HOME/config.json` (or path set by `AICORE_CONFIG`);
   use `AICORE_PROFILE` to select a named profile
4. **VCAP_SERVICES** — automatic on Cloud Foundry/Kyma when the AI Core service is bound

### Local Development (Environment Variables)

```bash
export AICORE_CLIENT_ID="sb-..."
export AICORE_CLIENT_SECRET="..."
export AICORE_AUTH_URL="https://<tenant>.authentication.sap.hana.ondemand.com/oauth/token"
export AICORE_BASE_URL="https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com/v2"
export AICORE_RESOURCE_GROUP="default"
```

### Config File Profile

```bash
# ~/.aicore/config.json
{
  "AICORE_CLIENT_ID": "sb-...",
  "AICORE_CLIENT_SECRET": "...",
  "AICORE_AUTH_URL": "https://<tenant>.authentication.sap.hana.ondemand.com/oauth/token",
  "AICORE_BASE_URL": "https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com/v2",
  "AICORE_RESOURCE_GROUP": "default"
}
```

For detailed auth setup and troubleshooting, see `references/getting-started-auth.md`.

## Available Modules

| Module | Import Path | Purpose |
|--------|-------------|---------|
| Proxy (native clients) | `gen_ai_hub.proxy.native.*` | Direct model access per provider |
| LangChain integration | `gen_ai_hub.proxy.langchain` | `init_llm`, `init_embedding_model`, `ChatOpenAI`, etc. |
| Orchestration | `gen_ai_hub.orchestration_v2` | Templating, filtering, masking, grounding |
| Document Grounding | `gen_ai_hub.document_grounding` | Pipeline, Vector, Retrieval APIs |
| Prompt Registry | `gen_ai_hub.prompt_registry` | Template management and config storage |
| Evaluations | `gen_ai_hub.evaluations` | Model evaluation runs and metrics |
| SAP RPT-1 | `gen_ai_hub.proxy.native.sap` | Tabular prediction (classification, regression) |

### Native Clients by Provider

| Provider | Import | Key Classes |
|----------|--------|-------------|
| OpenAI | `gen_ai_hub.proxy.native.openai` | `OpenAI`, `completions`, `chat`, `embeddings`, `responses` |
| Amazon Bedrock | `gen_ai_hub.proxy.native.amazon` | `Session`, `ClientWrapper` |
| Google GenAI | `gen_ai_hub.proxy.native.google_genai` |