ai-service-layer

ルール：Domo App Platform AI（ツールキット優先）

このルールでは、ツールキットを優先します。@domoinc/toolkit の AIClient を使用してください。

標準クライアント

yarn add @domoinc/toolkit

import { AIClient } from '@domoinc/toolkit';

重要：AIClient のメソッドは静的メソッドです

これらのメソッドを使用する際、AIClient をインスタンス化しないでください。

誤り：

const ai = new AIClient();
await ai.text_to_sql('...');

正しい例：

await AIClient.text_to_sql('...');

テキスト生成

const response = await AIClient.generate_text(
  'Explain this sales trend in simple terms',
  { template: 'You are a business analyst. ${input}' },
  { tone: 'professional' },
  undefined,
  { temperature: 0.7 }
);

const body = response.data || response.body || response;
const text = body.output || body.choices?.[0]?.output;

その他の AI メソッド

text_to_sql の schema 引数は配列である必要があります

誤り：

await AIClient.text_to_sql('Show top vendors by spend', {
  dataSourceName: 'vendorPayments',
  columns: [{ name: 'amount', type: 'number' }]
});

正しい例：

await AIClient.text_to_sql('Show top vendors by spend', [
  {
    dataSourceName: 'vendorPayments',
    description: 'Vendor payment invoices',
    columns: [
      { name: 'vendor', type: 'string' },
      { name: 'amount', type: 'number' },
      { name: 'date', type: 'date' }
    ]
  }
]);

シグネチャの参照

（概略です。正確な現在のシグネチャについては、インストール済みのツールキットの型定義を確認してください。）

AIClient.text_to_sql(
  input: string,
  dataSourceSchemas?: DataSourceSchema[], // array
  promptTemplate?: any,
  parameters?: Record<string, string>,
  model?: string,
  modelConfiguration?: Record<string, Object>
): Promise<Response<TextAIResponse>>;

配列を使用する理由：複数の schema を指定した場合に、複数テーブルを対象とした SQL 生成（結合を考慮した SQL を含む）に対応できます。

text_to_sql の使用に関する注意

text_to_sql はアドホックな SQL に適していますが、/sql/v1 はダッシュボード／ページのフィルターを自動的に適用しません。 埋め込みカードでフィルターへの対応が必要な場合は、実行に Query API（@domoinc/query 経由の /data/v1）を使用してください。

const sqlResult = await AIClient.text_to_sql('Show total sales by region', [
  {
    dataSourceName: 'Sales',
    description: 'Sales transactions',
    columns: [{ name: 'region', type: 'string' }, { name: 'amount', type: 'number' }]
  }
]);

const beastModeResult = await AIClient.text_to_beastmode(
  'Calculate year over year growth percentage',
  { dataSourceName: 'Revenue', columns: [{ name: 'revenue', type: 'number' }, { name: 'date', type: 'date' }] }
);

レスポンス処理のルール

AIClient のレスポンスは、他のツールキットクライアントと同じ形式とは限りません。

• response.data を使用することがよくあります
• output と choices の両方が含まれる場合があります

防御的な解析と、厳密な文字列チェックを使用してください。

const body = response?.data ?? response?.body ?? response;
const outputCandidate = body?.output ?? body?.choices?.[0]?.output;
const output = typeof outputCandidate === 'string' ? outputCandidate.trim() : '';

if (!output) throw new Error('AI returned no usable output');

チェックリスト

• AIClient のメソッドには snake_case（generate_text、text_to_sql など）を使用する
• AIClient のメソッドは静的に呼び出す（例：AIClient.text_to_sql(...)。インスタンスメソッドではない）
• AIClient.text_to_sql の第 2 引数には、単一のオブジェクトではなく DataSourceSchema[]（配列）を指定する
• data／body のフォールバックを使ってレスポンスを解析する
• 出力の抽出に文字列チェックと空出力の処理を含める
• UI でエラー処理とローディング状態を実装する