genai-hub-tabular-orchestration

ルール

1. すべてのスクリプトは、スキルのルートから uv run scripts/<name>.py を実行してください。
2. 認証情報の値を表示またはログに記録しないでください。SDK は環境変数から読み込みます。
3. 予測リクエストを送信する前に、TCR の前提条件（データ宛先 → 表形式アーティファクト → シナリオ設定）が整っていることを必ず確認してください。
4. 予測リクエストでは、rows と columns は相互に排他的です。両方を含めないでください。
5. 認証情報または認証エラーが発生した場合は、まず aicore-admin-resources を呼び出してください。
6. 変更を加えるスクリプトには --confirm が必要です。削除操作では必ず明示的に指定してください。
7. ユーザーが --resource-group を指定しない場合は省略してください。SDK のデフォルトが使用されます。
8. btp update services/instance コマンドを実行する前に、必ず次の手順を行ってください。（a）btp get services/instance --id <id> を実行して、現在の parameters ブロック全体を取得します。（b）現在のパラメーター全体と正確な差分（追加、変更、削除される内容）、および送信する完全な結果のペイロードをユーザーに提示します。（c）提示したパラメーターと変更案について、ユーザーから明示的な確認を得ます。同じターンでユーザーが確認するまでは、いかなる場合も btp update services/instance を実行しないでください。

---

概念

Context Registry（TCR）は、次の3層のリソースを通じて、構造化データを AI Core シナリオに公開します。

Data Destination  →  Tabular Artifact  →  Scenario Configuration
(HDL connection)      (file + schema)       (named bundle of TAs)

• データ宛先：HDL（HANA Data Lake）エンドポイントの接続認証情報を保存します。
• 表形式アーティファクト（TA）：データ宛先にある特定のファイルを指し、スキーマのメタデータ （CSN）を含みます。CSV、Parquet、Delta 形式に対応しています。スキーマはインライン（DOCUMENT）で指定するか、 パスで参照（REFERENCE）するか、自動導出（AUTO）できます。
• シナリオ設定：名前付きの再利用可能な表形式アーティファクト名のリストで、推論時に AI Core シナリオによって使用されます。

すべてのリソースはリソースグループ（AI-Resource-Group ヘッダー）のスコープに属します。まず aicore-admin-resources スキルを使用して、認証情報を確認し、アクティブなリソースグループを取得してください。

---

クイックスタート

# 1. Check setup
uv run scripts/check_setup.py    # from aicore-admin-resources, or verify env vars

# 2. List all three resource types
uv run scripts/list_data_destinations.py
uv run scripts/list_tabular_artifacts.py
uv run scripts/list_scenario_configs.py

# 3. Register a new HDL data destination
uv run scripts/create_data_destination.py --name my-hdl --host <hdl-hostname>

# 4. Register a tabular artifact (AUTO schema, CSV)
uv run scripts/create_tabular_artifact.py \
  --name customer-ta \
  --data-destination my-hdl \
  --path /data/customer.csv \
  --type CSV

# 5. Create a scenario configuration
uv run scripts/create_scenario_config.py \
  --name my-scenario \
  --tabular-artifacts customer-ta,orders-ta

---

データの宛先

データの宛先には HDL のホスト名と認証情報が保存されます。作成時にシステムが接続を検証し、認証情報を安全に保存します。

データの宛先を作成する前に、ユーザーに次の情報を確認してください：

1. 名前 — ケバブケース、1～127 文字（例：my-hdl）
2. HDL のホスト名 — https:// のプレフィックスなし（例：abc123.files.hdl.eu10.hanacloud.ondemand.com）
3. (任意) ラベル — (ext|int).ai.sap.com/<suffix> のパターンに従う key=value のペア
4. (任意) 説明 — 自由記述の説明

uv run scripts/list_data_destinations.py               # list all
uv run scripts/list_data_destinations.py --json        # pipe-friendly JSON

uv run scripts/get_data_destination.py --name <name>   # get details of one destination
uv run scripts/get_data_destination.py --name <name> --json

uv run scripts/create_data_destination.py \
  --name <name> \
  --host <hdl-hostname>
  # hostname only — no https:// prefix, e.g. abc123.files.hdl.eu10.hanacloud.ondemand.com
  # optional: --labels ext.ai.sap.com/env=prod --description "Production HDL"

# Update labels (replaces the entire label set)
uv run scripts/patch_data_destination.py --name <name> --labels ext.ai.sap.com/env=prod
uv run scripts/patch_data_destination.py --name <name> --labels ext.ai.sap.com/env=prod ext.ai.sap.com/team=data

# Search by labels
uv run scripts/search_data_destinations.py --labels ext.ai.sap.com/env=prod
uv run scripts/search_data_destinations.py --labels ext.ai.sap.com/env=prod --json

uv run scripts/delete_data_destination.py --name <name> --confirm
# Note: deletes cascade to all tabular artifacts that reference this destination.

名前の制約：小文字、数字、ハイフンを使用します。1～127 文字で、英数字で始まり、英数字で終わる必要があります。

ラベルは (ext|int).ai.sap.com/<suffix> のパターンに従います。検索エンドポイントを使った絞り込みに便利です（references/API.md を参照）。

作成後に必要な手順 — HDL にサブジェクトパターンを登録する：create_data_destination.py が成功すると、応答に 1 つ以上の X.509 サブジェクト DN（subjectPatterns）が含まれます。これらを HDL Files サービスインスタンスの設定で authorizations として追加する必要があります。次の手順をユーザーに案内してください。

0. BTP CLI のログインを確認する

btp コマンドを実行する前に、BTP CLI がインストールされ、ログイン済みであることを確認してください。インストールとログインの手順については、references/SETUP.md を参照してください。

1. HDL Files インスタンス ID を確認する

btp target --subaccount <subaccount-id>
btp list services/instance

このデータの宛先で使用される HDL Files サービスに対応する名前またはタイプのインスタンスを探します。

2. 現在のインスタンスパラメーターを取得して表示する

btp get services/instance --id <hdl-instance-id>

出力から parameters ブロック全体を抽出します。そのままユーザーに表示してください。既存の authorizations エントリがあれば、更新ペイロードに保持する必要があることを伝えてください。

3. 更新ペイロードを作成して確認する

既存の authorizations エントリをすべて含め、新しいサブジェクトパターンを追加した parameters ペイロード全体を作成します。ユーザーに次の内容を表示してください：

• 現在の authorizations 配列（手順 2 の内容）
• 追加する新しいエントリ
• 送信する更新後のペイロード全体

AI Core が複数のパターンを返した場合は、パターンごとにエントリを追加し、ランクを順番に割り当てます。authorizations 配列は既存の配列を置き換えるため、既存のエントリをすべて必ず含めてください。

続行する前に、現在のパラメーターと提案するペイロードをユーザーにはっきり確認してください。同じターンで確認を得るまでは続行しないでください。

4. 更新を適用する

ユーザーの確認を得た後にのみ実行してください：

btp update services/instance \
  --id <hdl-instance-id> \
  --parameters '{
    "data": {
      "fileContainer": {
        "authorizations": [
          {
            "pattern": "<subject-pattern-from-ai-core>",
            "rank": 1,
            "roles": ["user"]
          }
        ]
      }
    }
  }'

このロールを持っていますか？ HDL インスタンスが属するサブアカウントで、Subaccount Administrator または Service Administrator が必要です。ロールを持っていない場合は、サブジェクトパターンを BTP 管理者に共有し、この手順の実行を依頼してください。

反映までの遅延：変更が反映されるまで 1～2 分かかる場合があります。更新直後に表形式アーティファクトの作成が引き続き 403 を返す場合は、待ってから再試行してください。

ユーザーがサブジェクトパターンの登録（または BTP 管理者による登録）を確認するまで、表形式アーティファクトの作成に進まないでください。

---

表形式アーティファクト

表形式アーティファクトは、データ宛先上のファイルをクエリ可能な仮想テーブルとして登録します。スキーマの定義モードは 3 つあります。

definitionType	使用する場面	必要なもの
AUTO	システムにファイルからスキーマを導出させる場合	definitionType: AUTO のみ
DOCUMENT	列名と型をインラインで指定する場合 — 推奨	--csn-columns col:cds.Type,...
REFERENCE	データ宛先上の CSN ファイルを参照する場合	documentReference.path のパス

表形式アーティファクトを作成する前に、ユーザーに以下を確認してください。

1. 名前 — ケバブケース、1～80 文字（例：customer-data）
2. データ宛先名 — すでに存在している必要があります。不明な場合は list_data_destinations.py で一覧表示してください。
3. ファイルパス — HDL 上のファイルの絶対パス（例：/data/customer.csv）
4. ファイル形式 — CSV、PARQUET、または DELTA
5. (DOCUMENT モードのみ) エンティティ名 — テーブルの PascalCase ラベル（例：Customer）
6. (DOCUMENT モードのみ) 列名 — ファイルのヘッダー行に記載されている名前と完全に一致するもの
7. (DOCUMENT モードのみ) 各列の型 — 完全な cds.* 型名を使用します（例：cds.String、cds.Integer）

次に、--csn-columns を使ってインラインで渡します。

uv run scripts/list_tabular_artifacts.py               # list all
uv run scripts/list_tabular_artifacts.py --json

uv run scripts/get_tabular_artifact.py --name <name>   # get details of one artifact
uv run scripts/get_tabular_artifact.py --name <name> --json

# AUTO schema (simplest — works well for CSV with a header row)
uv run scripts/create_tabular_artifact.py \
  --name <name> \
  --data-destination <dd-name> \
  --path /data/file.csv \
  --type CSV

# DOCUMENT schema — supply column names and types explicitly
uv run scripts/create_tabular_artifact.py \
  --name <name> \
  --data-destination <dd-name> \
  --path /data/file.csv \
  --type CSV \
  --csn-columns "id:cds.Integer,name:cds.String,score:cds.Decimal,active:cds.Boolean" \
  --entity-name MyEntity

# REFERENCE schema (CSN file lives on the HDL)
uv run scripts/create_tabular_artifact.py \
  --name <name> \
  --data-destination <dd-name> \
  --path /data/file.parquet \
  --type PARQUET \
  --csn-reference /data/metadata/schema.json \
  --entity-name MyEntity

uv run scripts/delete_tabular_artifact.py --name <name> --confirm
# Deletion is async (202 Accepted); the artifact transitions to DELETING status.

--csn-columns の形式：name:cds.Type のペアをカンマ区切りで指定します。 サポートされる型：cds.UUID、cds.Boolean、cds.Integer、cds.Int16、cds.Int32、cds.Int64、 cds.UInt8、cds.Decimal、cds.Double、cds.Date、cds.Time、cds.DateTime、cds.Timestamp、 cds.String、cds.Binary、cds.LargeBinary、cds.LargeString、cds.Map、cds.Vector。 列名は、ファイルのヘッダー行と完全に一致する必要があります。

名前の制約：小文字の英字、数字、ハイフンを使用します。1～80 文字で、英数字で始まり、英数字で終わる必要があります。

---

シナリオ設定

シナリオ設定は、名前で指定できる表形式アーティファクト名の、名前付きで安定したリストです。AI Core シナリオは推論時にこの名前を参照します。

uv run scripts/list_scenario_configs.py
uv run scripts/list_scenario_configs.py --json

uv run scripts/get_scenario_config.py --name <name>    # get details of one config
uv run scripts/get_scenario_config.py --name <name> --json

uv run scripts/create_scenario_config.py \
  --name <name> \
  --tabular-artifacts ta1,ta2,ta3

# Update the TA list (replaces the entire list)
uv run scripts/patch_scenario_config.py \
  --name <name> \
  --tabular-artifacts ta1,ta2,ta3,ta4

uv run scripts/delete_scenario_config.py --name <name> --confirm

名前の制約：データ宛先と同じです（小文字、ハイフン、1～127 文字）。

---

表形式の予測（predict.py）

predict.py を使用して、デプロイ済みの表形式 RPT モデル（sap-rpt-1-small または sap-rpt-1-large）に推論リクエストを送信します。モデルは TCR からコンテキスト行を読み取り、クエリ行の値を予測します。

uv run scripts/predict.py --deployment-id <id> --body '<json>'
# optional: --json  --main-tenant <uuid>  --resource-group <rg>

ルール

1. TCR の前提条件を満たしている必要があります — 予測リクエストを送信する前に、表形式アーティファクト、シナリオ設定、データ宛先をすべて登録してください（上記のセクションを参照）。

2. rows と columns は相互に排他的です — 同じリクエストに両方を含めないでください。

3. 予測対象には "[PREDICT]" を含める必要があります — クエリ行の対象列の各エントリには、プレースホルダー文字列 "[PREDICT]" を指定する必要があります。

---

インタラクティブなビルダーフロー

以下の手順を順番に進めてください。ユーザーがすでに回答した手順はスキップします。

ステップ 1 — TCR の前提条件を確認する

次のように尋ねます。

Before we proceed, please confirm you have already set up the following in TCR:
  ✓ Tabular artifact (context dataset uploaded)
  ✓ Scenario configuration (scenarioConfigName you want to use)
  ✓ Data destination

If any of these are missing, I can help you set them up first.

セットアップされていない場合は、上記の TCR スクリプトを使って登録できるようユーザーを支援し、その後、予測フローに戻ります。

---

ステップ 2 — scenarioConfigName と deploymentId を確認する

uv run scripts/list_scenario_configs.py

deployment ID を取得する（表形式の RPT デプロイメントは、既知のシナリオに表示されない場合があります）：

uv run ../aicore-lifecycle-management/scripts/get_deployments.py --status RUNNING

両方を確認したら、次の情報も一度に尋ねます。

パラメーター	尋ねる内容
deploymentId	「deployment ID は何ですか？」
modelName	「どのモデルを使いますか？ sap-rpt-1-small（高速）または sap-rpt-1-large（より高精度）から選んでください。」
予測対象の列	「どの列を予測しますか？」
タスクの種類	「分類（カテゴリを予測）ですか、それとも回帰（数値を予測）ですか？（任意 — モデルが自動検出できます）」
データ形式	「データはどのように提供しますか？ 列（配列のオブジェクト）または 行（オブジェクトの配列）ですか？」

---

ステップ 3 — データを収集して整形する

ユーザーにクエリデータの提供を依頼します。次の形式を受け付けます。

• 貼り付けた表／CSV テキスト
• JSON の行 [{...}, {...}]
• キーと値のペア
• スプレッドシート形式

ステップ 2 で選択した形式に従って変換します。

列形式の場合：

"columns": {
  "Col A": ["val1", "val2", "val3"],
  "Col B": [10, 20, 30],
  "Target": ["[PREDICT]", "[PREDICT]", "[PREDICT]"]
}

行形式の場合：

"rows" : [
  {"Col A": "val1", "Col B": 10, "Target": "[PREDICT]"},
  {"Col A": "val2", "Col B": 20, "Target": "[PREDICT]"}
]

整形時のルール：

• すべてのクエリ行で、予測対象列の値を "[PREDICT]" に置き換えます
• すべての配列の長さをそろえます
• ユーザーが指定した列名をそのまま保持します

また、ユーザーがコンテキストデータ（モデルが学習するための、正解がわかっている行）を持っているかどうかも尋ねます。持っている場合は収集し、実際の予測対象値を保持したまま contextColumns として整形します（コンテキストデータでは "[PREDICT]" を使用しないでください）。

---

ステップ 4 — predictionConfig を作成する

"predictionConfig": {
  "targetColumns": [
    {
      "name": "<target column name>",
      "predictionPlaceholder": "[PREDICT]",
      "taskType": "<classification | regression>"
    }
  ]
}

---

ステップ 5 — contextSelectionConfig を作成する

データ送信先からコンテキスト行をどのようにサンプリングするか、また何件含めるかをユーザーに選んでもらいます。：

How should context rows be sampled?
  A) random    — default, good general purpose
  B) heuristic — scoring-based, finds similar rows
  C) none      — take from HEAD or TAIL of the table
How many context rows? (default: 50)

選択内容に基づいて、references/PREDICT.md の contextSelectionConfig セクションを参照し、JSON オブジェクトを作成します。ユーザーがヒューリスティックサンプリングを選択した場合、indexColumn として必要な一意の行 ID 列を尋ねるか、確認してください。strategyConfig をカスタマイズするかどうかもユーザーに確認し、希望がなければ適切なデフォルト値を使用します。

---

ステップ 6 — 組み立てて送信する

組み立てた JSON 本文全体をユーザーに表示してから、次を実行します。

uv run scripts/predict.py \
  --deployment-id <deploymentId> \
  --body '<assembled-json>'

---

よくあるエラー

TCR／Context Registry

エラー	考えられる原因	解決方法
401 Unauthorized	トークン／認証情報が無効です	aicore configure を再実行します
404 Not Found	名前またはリソースグループが間違っています	--name と AI-Resource-Group を確認します
409 Conflict	その名前のリソースがすでに存在します	別の名前を選ぶか、先に削除します
400 Bad Request	名前のパターン違反、または必須フィールドがありません	上記の名前に関する制約を確認します
TA 作成時の 403 Access Denied	HDL インスタンスにサブジェクトパターンがまだ登録されていません	上記の「データ送信先」セクションの「サブジェクトパターンを登録する」手順に従います。更新後、1～2 分待ちます
HDL 接続拒否	ホスト名が間違っているか、ネットワークにアクセスできません	https:// を省略し、接続を確認します
TA が DELETING のままになる	バックグラウンドでクリーンアップが保留中です	cleanup エンドポイントを実行します。references/API.md を参照してください

エンドポイントの詳細、フィールドのスキーマ、ページネーションパラメーターについては、references/API.md を参照してください。

予測

HTTP	エラーコード	説明	対処方法
400	VALIDATION_ERROR	リクエストの検証に失敗しました	必須フィールド（modelName、scenarioConfigName、predictionConfig.targetColumns）を確認してください。rows と columns のどちらか一方のみが指定されていることを確認し、すべての配列の長さが同じであることを確認してください
401	—	認証に失敗しました	--main-tenant ヘッダーと --resource-group ヘッダーを確認してください
404	MODEL_NOT_FOUND	モデルを利用できません	modelName が sap-rpt-1-small または sap-rpt-1-large であり、デプロイメントが実行中であることを確認してください
404	SCENARIO_CONFIG_NOT_FOUND_ERROR	シナリオ設定が見つかりません	上記の「シナリオ設定」セクションで作成してください
500	CONTEXT_SELECTOR_ERROR	コンテキストセレクターでエラーが発生しました	TCR の設定を確認してください。表形式アーティファクトとデータの宛先が正常である必要があります
500	SAP_RPT1_SMALL_ERROR	SAP RPT-1 Small でエラーが発生しました	デプロイメントのステータスを確認し、再試行するか sap-rpt-1-large に切り替えてください
500	SAP_RPT1_LARGE_ERROR	SAP RPT-1 Large でエラーが発生しました	デプロイメントのステータスを確認し、再試行するか sap-rpt-1-small に切り替えてください
502	BAD_GATEWAY	外部サービスでエラーが発生しました	デプロイメントのステータスを確認してください。TFM またはコンテキストセレクターに到達できません
504	GATEWAY_TIMEOUT	リクエストがタイムアウトしました	numRows またはバッチサイズを小さくしてください

---

引き継ぎ

該当する場合	使用するスキル
認証情報または認証エラー、リソースグループの管理	aicore-admin-resources
デプロイメントのステータス確認、デプロイメントの作成／停止	aicore-lifecycle-management
実行可能 ID の検索、基盤モデルの閲覧	genai-hub-foundation-models

---

リファレンスファイルを読み込むタイミング

トリガー	読み込むファイル
認証情報または認証エラーが発生した場合	aicore-admin-resources スキル
BTP CLI がインストールされていない、またはログインしていない場合	references/SETUP.md
BTP の手順（サブジェクトパターンの登録など）をユーザーに案内する場合	references/API.md
予測の全フィールドリファレンスまたは完全なリクエスト例が必要な場合	references/PREDICT.md
ユーザーが一般的でないデータ形式を提示し、変換方法の案内が必要な場合	references/PREDICT.md