> ## Documentation Index
> Fetch the complete documentation index at: https://developer.qaip.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ChartmetricをAgentで使う

> 自分のChartmetric refresh tokenを登録し、アーティストや楽曲を検索・分析する方法を説明します。

Chartmetric連携は、自分で用意したChartmetric Developer APIの契約と
refresh tokenを使うBYOK（Bring Your Own Key）方式です。
QAIPが共有APIキーを提供したり、対応外のプランを従量課金へ自動で
切り替えたりすることはありません。

## 利用できるか確認する

シークレット作成画面でChartmetricを選ぶと、その環境で認証済みの
契約プランだけが表示されます。自分のプランが表示されない場合は
登録できません。契約内容はChartmetricの管理画面で確認してください。

<Warning>
  Agentの利用は、自分のChartmetric契約のquota、rate limit、費用を
  消費することがあります。複数のAgentや実行を並行すると、その分だけ
  API requestが増える可能性があります。
</Warning>

## Refresh tokenを登録する

1. ChartmetricでDeveloper API用のrefresh tokenを取得します。
2. ダッシュボードの「シークレット」を開きます。
3. 「新規シークレット作成」を選び、データソースタイプを
   「Chartmetric」にします。
4. シークレット名とrefresh tokenを入力します。
5. 画面に表示された自分の契約プランを選び、
   `chartmetric-byoc-v1`のLLM provider/subprocessor/region、
   履歴・log・traceの保持日数、ユーザー・管理者の削除経路を確認します。
6. 全Agentで既定有効、quota・費用、LLM処理、会話履歴保存、
   保持・削除に関する5項目を個別に確認して保存します。

登録できるChartmetricシークレットは1ユーザーにつき1件です。
登録処理ではChartmetric APIを呼び出しません。refresh tokenは保存後に
再表示されず、Agentが実際にツールを使うときだけ認証に利用されます。

<Info>
  データの送信先、履歴の保持期間、削除経路は登録画面に表示される
  データ利用プロファイルと、契約ownerが管理する運用記録を確認してください。
  profile変更時の再確認と公開判断は運用で管理され、登録済み同意と
  現行profileのhashはapplicationでは照合しません。
</Info>

## 6つのツールを使う

登録後、既存と新規のAgentで次の6つのツールが既定で有効になります。

| ツール        | できること                                  |
| ---------- | -------------------------------------- |
| アーティスト検索   | 名前、ISRC、または対応DSP URLから候補を1ページ検索します     |
| 楽曲検索       | 楽曲名、ISRC、または対応DSP URLから候補を1ページ検索します    |
| アーティスト統計取得 | 検証済みChartmetric artist IDの現在値と差分を取得します |
| アーティスト推移取得 | 期間と配信元を指定して統計推移を取得します                  |
| アーティスト楽曲取得 | 指定アーティストの楽曲を並べ替えて1ページ取得します             |
| 楽曲統計取得     | 指定楽曲のplatform別統計を取得します                 |

検索候補が複数ある場合、Agentは先頭候補を自動採用しません。
名前、アーティスト、ISRCなどを見比べて対象を指定してください。

## 対応する指標を指定する

アーティスト推移では、次のsourceとmetricを利用できます。

| Source                 | Metric                                                       |
| ---------------------- | ------------------------------------------------------------ |
| Spotify                | followers、popularity、listeners                               |
| Instagram              | followers                                                    |
| YouTube Channel        | subscribers、views、comments、videos                            |
| YouTube Artist         | daily\_views、monthly\_views                                  |
| TikTok                 | followers、likes                                              |
| X                      | followers、retweets                                           |
| Facebook               | likes、talks                                                  |
| SoundCloud、Bandsintown | followers                                                    |
| Wikipedia              | views                                                        |
| Twitch                 | follower\_count、monthly\_viewer\_hours、weekly\_viewer\_hours |
| LINE                   | likes                                                        |
| Melon                  | fans                                                         |

アーティスト楽曲の並べ替えは`spotify_plays`、`tiktok_posts`、
`youtube_views`、`shazam_count`、`spotify_popularity`、`score`に対応します。

楽曲統計はSpotify、TikTok、Chartmetric、YouTube、Shazam、Genius、
SoundCloudに対応します。明示できるmetricはSpotifyの`popularity` /
`streams`、TikTokの`posts` / `views` / `comments` / `sound_*`、
Chartmetricの`score` / `rank`です。

契約プランまたはツールが対応しないendpoint・metricはエラーになります。
QAIPは別のmetric、Web検索、Xなどの値をChartmetricの値として補完しません。
rankは小さい値ほど上位です。TikTokのpostsとviewsも別の指標として扱います。

## 日付とページを明示する

アーティスト推移には`since`と`until`を`YYYY-MM-DD`で両方指定します。
楽曲統計の日付は両方指定するか、両方省略します。片側だけの指定や
開始日が終了日より後の指定は受け付けません。

検索はアーティスト5件、楽曲10件、アーティスト楽曲は50件が既定です。
いずれも1回に1ページだけ取得し、自動で次ページへ進んだり、期間を
分割したりしません。続きが必要なときは、回答に示されたpaginationを
確認して次のoffsetを指定してください。検索結果の`has_more`をproviderが
返さない場合は、上限件数に達したことをwarningとして示します。

## 引用とグラフを確認する

引用を有効にしたAgentでは、検証済みのChartmetric artist IDまたはtrack IDから
作ったChartmetric公式画面へのリンクが回答に付きます。引用を無効にした場合や、
安全なIDを確認できない場合はリンクを作りません。

推移データは回答の分析用データを変えず、表示だけを最大50点にサンプリングする
ことがあります。その場合は入力点数と表示点数が注記されます。

Redaction policyによって名前を安全に送れない場合、Agentは元の名前へ
フォールバックしません。Chartmetric ID、ISRC、またはSpotify、Apple Music、
YouTube Musicなどの対応DSP URLを指定してください。

## 無効化・更新・削除する

1つのAgentだけで止めるには、Agent編集画面の「ツール」で
「Chartmetricの検索・分析ツールを使う」をオフにして保存します。
他のAgentの設定は変わりません。

refresh tokenを変更するには、シークレット一覧から登録済みのChartmetricを
編集します。tokenの更新だけでは、現在の契約プランとデータ利用への同意は
変更されません。データ利用プロファイルが更新された場合や、削除後に
作り直す場合は再同意が必要です。

削除はシークレット一覧から行います。処理中はpending状態が表示されることが
あり、その間は新しいAgent実行でChartmetricツールを利用できません。
削除されたシークレットには7日間の復旧期間がありますが、QAIP上では
削除済みの同意を新しい登録へ流用しません。

<Note>
  環境がdormant状態の場合は、新規登録とAgentでの有効化を受け付けません。
  tokenを再登録せず、Chartmetricの利用再開を待ってください。既存登録の無効化・更新・削除は続けられます。
</Note>

## エラーから復旧する

| 表示                    | 対応                                              |
| --------------------- | ----------------------------------------------- |
| 認証に失敗した               | refresh tokenの有効期限とscopeを確認し、登録済みシークレットを更新します   |
| 契約planまたはscopeで利用できない | 画面で選んだプランとChartmetric契約のendpoint・metric権限を確認します |
| rate limitに達した        | Chartmetricのquotaと並行実行数を確認し、時間を置いて新しい実行で試します    |
| 結果が大きすぎる              | 期間、metric、limitを狭めます                            |
| この環境では登録・利用できない       | tokenを再登録せず、Chartmetricの利用再開を待ちます               |

同じAgent実行ではChartmetricのツール呼び出しを最大10回、データ取得を
retry込みで最大10回、token交換を最大2回に制限します。この上限は、
誤った繰り返しや障害時にquotaを使い続けないための安全策です。