bigdata-skill

Bigdata.com SDK + REST ツールキット

Bigdata.com MCP サーバーからは取得できない、構造化された基盤データを取得します。MCP は読みやすい文章と事前に合成されたティアシートを返しますが、検索ツールが返すのはチャンクで、チャンクごとのセンチメントやエンティティのスパンは含まれません。また、ティアシートが返すのは集計値であり、パイプライン構築に使える会計期間ごとの時系列、ユニバーススクリーナー、フィールドごとの JSON ではありません。公式の bigdata-client SDK と、同じバックエンド、同じ JWT を使う薄い REST パススルーを組み合わせれば、データが格納されている公式の /v1/* エンドポイントにアクセスできます。このスキルには、それを実現するツールキットが含まれています。すでにデバッグ済みで、コストガードも実装済みなので、探索にかかるコストを再び払う必要はありません。

このスキルが解決する中心的な問題（まずお読みください）

Bigdata MCP サーバーに「NVIDIA のセンチメントはどうですか？」と尋ねると、読みやすい段落や事前に合成されたティアシートが返されます。チャットのやり取りには本当に役立ちます。しかし、パイプライン構築に必要な機械可読な基盤データが必要になった途端、MCP からは取得できません。

• 検索ツールが返すのは、テキストと関連性のみを含むチャンクです。チャンクごとのセンチメント値も、エンティティの文字位置スパンもありません。
• ティアシートが返すのは集計値（単一のセンチメントスコアや予測の要約）です。計算に使える会計期間ごとの時系列、ユニバーススクリーナー、フィールドごとの JSONはありません。

解決策は Bigdata 固有の裏技ではなく、汎用的なパターンです。

MCP のデータソースが合成済みの出力しか返さず、その下にある構造化フィールドが必要な場合は、ベンダー SDK または REST を使ってください。 MCP はチャットのやり取りに最適化されており、パイプライン向けではありません。

重要なのは、Bigdata の構造化フィールドが、隠されたバックエンドではなく、公式に公開・文書化された REST エンドポイント（docs.bigdata.com/api-reference/...）だということです。また、Bigdata はSDK の提供を終了し（EOL 2026-12-31）、REST API に移行する予定です。そのため、ここで使う REST レイヤーはハックではなく、将来との互換性を保つための方法です。SDK（bigdata_client.Bigdata）が対応するのは検索とナレッジグラフまでです。bd._api.http を使えば、SDK がラップしていないすべての /v1/* エンドポイントにアクセスできます。同梱の bigdata_toolkit は、この両方を単一の BigdataClient の背後にまとめています。

このスキルを使う場面

言語を問わず、次のいずれかに該当する場合に使います。

• ユーザーがBigdata.com / RavenPack を使っていて、MCP の結果が物足りない場合。「センチメントスコアはどこ？」「エンティティレベルのデータが必要」「カレンダーが欲しい」など。
• ティッカーの将来予測または構造化された財務データを求めている場合：アナリスト予測、決算またはイベントカレンダー、決算サプライズ、アナリスト評価、目標株価、企業スクリーナー／ユニバース。
• 数値センチメントとエンティティスパンが付いた注釈付きニュースチャンク、センチメント時系列、または共起グラフを求めている場合。
• bd_v2_ API キー、rp_entity_id、query_unit／チャンクのコスト、bigdata-client、または「Bigdata MCP では足りない」と言及している場合。
• 単発の MCP 呼び出しではなく、再利用可能でコストを考慮したデータ取得レイヤーが必要な投資リサーチ用データセットを構築している場合。

セットアップ（初回のみ）

1 — API キー（ハードコードしないでください）。 クライアントは API キーがない場合、即座にエラーを返します。

export BIGDATA_API_KEY=bd_v2_xxxxxxxx

2 — 公式 SDK を使う独立した Python 環境。 同梱のツールキットは bigdata_client をインポートするため、一度インストールしてください。

uv venv .venv --python 3.12
uv pip install --python .venv/bin/python bigdata-client
# Behind a slow/blocked PyPI (e.g. mainland China) add a mirror, and unset any
# outbound proxy for the install step so uv reaches the index directly:
#   --index-url https://pypi.tuna.tsinghua.edu.cn/simple

3 — 外部向けプロキシ（ネットワークから api.bigdata.com に接続するために必要な場合のみ）。 同等の方法が 2 つあります。公式 SDK はどちらにも対応しています。環境変数を使う方法と、コード内で BigdataClient(proxy=...) を指定する方法です。環境変数を使うのが最も簡単です。

export HTTPS_PROXY=http://<host>:<port>     # plus WSS_PROXY for chat/WebSocket

プロキシが TLS を傍受する（自己署名 CA を使う）ために SSL ハンドシェイクエラーが発生する場合、公式の解決策は BigdataClient(verify_ssl="<proxy-CA>.pem") を指定することです。むやみに再試行することではありません。

4 — このスキルの scripts/ を PYTHONPATH に追加する（または sys.path.insert(0, "<this-skill>/scripts") を使う）ことで、同梱パッケージをインポート可能にします。

経路全体をスモークテストします（エンティティ解決とクォータ確認は無料です。--with-search を指定すると、約 1 query_unit のチャンク検索が 1 回追加されます）。

BIGDATA_API_KEY=bd_v2_xxx PYTHONPATH=scripts .venv/bin/python scripts/probe_example.py

クイックスタート

import sys
sys.path.insert(0, "<this-skill>/scripts")          # so `import bigdata_toolkit` resolves
from bigdata_toolkit import (
    BigdataClient, EntityResolver, AnnotatedSearcher,
    StructuredDataREST, CostTracker, CostModel, rc,   # rc = SSL-retry wrapper
)

c  = BigdataClient()                                  # SDK + REST escape hatch, one object
er = EntityResolver(c)
nvda = rc(lambda: er.resolve_id("NVIDIA", country="US"))   # -> 'E09E2B'  (rp_entity_id is the gateway key)

# --- Structured financials the MCP does NOT expose (REST escape hatch) ---
rest = StructuredDataREST(c)
est  = rc(lambda: rest.analyst_estimates(nvda, period="quarter", limit=5))  # forward consensus
surp = rc(lambda: rest.latest_surprise(nvda))                               # last EPS/revenue surprise
cal  = rc(lambda: rest.events_calendar(nvda, categories=["earnings-call"],
                                       start_date="2026-06-01", end_date="2026-12-31"))

# --- Annotated chunks the MCP STRIPS: sentiment + entity spans (cost-guarded) ---
s    = AnnotatedSearcher(c)
docs = rc(lambda: s.search_entity(nvda, keyword="data center", chunk_limit=10))
# each chunk dict: {"sentiment": float, "entities": [{"key": rp_id, "start", "end"}], "text", ...}

# --- Always know your spend (chunk-billed; see Cost discipline) ---
ct = CostTracker(c); ct.snapshot()
# ... run a batch ...
print(ct.delta())     # {'delta_chunks':..., 'delta_query_units':..., 'usd_fast':...}

すべてのネットワーク呼び出しを rc(lambda: ...) でラップしてください。最初のハンドシェイクで SSL: UNEXPECTED_EOF が発生するのはよくあることで、SDK 内部の再試行では対処できません。

ルーティング — 質問に答える機能

ユーザーが知りたいこと…	使用するもの	モジュール
会社名／ISIN／CUSIP／SEDOL → rp_entity_id	EntityResolver.resolve_id / .resolve_by_isin	kg.py（SDK）
将来のアナリストコンセンサス（会計期間別の売上高／EPS）	StructuredDataREST.analyst_estimates	rest_ext.py
最新の決算サプライズ（実績と予想の比較）	.latest_surprise	rest_ext.py
今後の決算／イベントカレンダー（1社または市場全体）	.events_calendar	rest_ext.py
アナリスト評価／目標株価コンセンサス	.analyst_ratings / .price_target	rest_ext.py
財務諸表全般（損益計算書／貸借対照表／キャッシュフロー、複数年）	.income_statement / .balance_sheet / .cash_flow_statement	rest_ext.py
TTM バリュエーション指標と比率（EV/EBITDA、ROE、P/E、利益率）	.key_metrics_ttm / .company_ratios_ttm	rest_ext.py
会社概要（CEO、セクター、従業員数、IPO 日）	.company_profile	rest_ext.py
日次 OHLC 価格／配当履歴	.daily_prices / .dividends	rest_ext.py
地域別／製品セグメント別売上高	.revenue_geographic_segments / .revenue_product_segments	rest_ext.py
日次の企業センチメント時系列（チャンクから独自に集計しないでください！）	.entity_sentiment	rest_ext.py
共起グラフ（サプライチェーン／競合他社／顧客 — ⚠️ チャンク課金）	.connected_entities	rest_ext.py
時価総額／セクター／国別にユニバースを構築する	.company_screener	rest_ext.py
センチメントとエンティティの範囲を含むニュース／提出書類／トランスクリプトのチャンク	AnnotatedSearcher.search_entity	search.py（SDK）
複数の検索を一括取得し、費用を 50% 削減する（ポートフォリオのバックフィル）	BatchSearch（作成→アップロード→ポーリング→ダウンロード）	rest_ext.py
バックフィル前にクォータの消費量を追跡／予測する	CostTracker / CostModel	cost.py
ツールキットでまだラップされていないエンドポイントを呼び出す	client.http.post("v1/<resource>/query", body)	client.py

income/balance/cash-flow/daily-prices/dividends/revenue-segments は {fields, values} を返します。fields_values_to_records() でラップすると [{field: value}] になります。*_ttm / company_profile エンドポイントはすでにフラットな形式です。 上記の構造化エンドポイントは、connected_entities と AnnotatedSearcher（チャンク課金）を除き、すべて無料（0 チャンク）です。

2つのデータ領域（「Bigdata は中国／A 株に対応できない」と言わないでください）

この区分は、最も重要で見落とされやすい結論です。正確に伝えてください。

領域	パス	A 株／中国語に関する結論
構造化財務データ（予想、カレンダー、サプライズ、評価、目標株価、スクリーナー、財務諸表、価格、配当、売上セグメント、日次の企業センチメント）	REST（rest_ext.py）	利用できます — 中国語名ではなく、英語名または ISIN から解決した rp_entity_id を使用します。データは最新です。一部に小さな欠落があります（一部の A 株の目標株価では、数値の目標株価がなく、エンティティのみが返されます）。日次の entity_sentiment 系列はこちらにあり、解決可能なエンティティならどれでも利用できます。下記の行き止まりとは異なります。
非構造化の中国語 NLP（中国語ニュースのエンティティ検出、チャンクごとの中国語センチメント）	SDK 検索（search.py）	利用できません — SDK のバグではなく、データソースレベルの制約です。中国語のエンティティ検出はほぼ 0 で、チャンクごとの CJK センチメントはドキュメントレベルの値を継承したものです。また、language は中国語の提出書類を英語と誤って分類します。中国語のチャンクコンテンツには Bigdata と中国国内のソースを併用してください。構造化データ領域（集約された entity_sentiment を含む）、ISIN/KG のクロスウォーク、英語のチャンクセンチメントには Bigdata を使用してください。

コスト管理

1 query_unit = 10 chunks（公式）。課金対象はチャンク検索のみです。構造化された /v1/* エンドポイント（推定値、財務情報、価格、カレンダー、サプライズ、評価、センチメントの時系列、スクリーナーなど）は無料です（チャンク数 0、契約テスト済み）。connected_entities（共起）と AnnotatedSearcher はチャンク課金の対象です。

チャンクに料金がかかる場合に使える手段は 3 つあります。

1. int をそのまま使わず、必ず ChunkLimit を使ってください。 Search.run(int) はドキュメント数の上限で、チャンクのページ全体に課金されます。ChunkLimit(n) はチャンク単位で課金されます。 AnnotatedSearcher.search は ChunkLimit を自動的に適用します。（一度、約 52 倍の差を観測しましたが、公式ドキュメントに記載された値ではなく、単一の測定データポイントです。倍率の正確な値は目安として扱ってください。max_chunks が公式の課金単位であるため、「ChunkLimit を使う」というルールは変わりません。）
2. リランクでは、返されたチャンクのみが課金対象です（公式）。rerank_threshold を渡して広く検索しつつ、関連性の高いヒットだけに課金できます。
3. バッチ検索は 50% 割安です（1 qu あたり $0.0075 対 $0.015）。大量の複数クエリをバックフィルする場合は、BatchSearch を使ってください。

CostModel を使って、予算超過のジョブを実行前に拒否し、CostTracker.snapshot() / delta() で実際の支出を測定します。詳しい費用計算については、references/cost_accounting.md を参照してください。

既知の落とし穴（すでに解決済みです。再調査しないでください）

これらの問題は、実際のデバッグに時間を要し、ツールキットで修正またはガード済みです。詳しい再現手順と修正内容については、references/known_pitfalls.md を参照してください。

1. 最初のハンドシェイクで SSL: UNEXPECTED_EOF が発生する → 呼び出しを rc() でラップしてください。SDK の urllib3 リトライは HTTP ステータスのみを対象とし、SSL EOF は対象外です。
2. All(entity, Keyword(kw)) で TypeError が発生する → & 演算子で結合してください（entity & Keyword(kw)）。All が受け取るのは単一のイテラブルです。（AnnotatedSearcher.entity_query で修正済みです。）
3. ドキュメント数上限による 52 倍の課金の落とし穴 → int をそのまま使わず、必ず ChunkLimit を使ってください。
4. ループ内でのクロージャによる変数捕捉 → ループ変数をバインドしてください：rc(lambda q=q, dr=dr: ...)。
5. analyst_estimates(period="quarter") は limit≈20 を超えると 400 エラーになります。
6. company_screener のフィルターは "filters" の下にネストする必要があります — トップレベルにフラットなキーを指定しても 400 エラーにはならず、黙って無視されるため、フィルターなしの銘柄群になります。
7. Document.reporting_period は常に None です（SDK モデルが REST のワイヤー上に存在するフィールドを破棄します） → fetch_reporting_period_raw を使ってください。

このスキルで行わないこと

• API キーをハードコードすることはありません。 BigdataClient は BIGDATA_API_KEY を読み込み、存在しない場合は即座に失敗します。平文へのフォールバックはありません（これはまさにシークレットスキャナーが検出するパターンです）。
• 読み取りのみで、書き込みやアップロードは行いません。 すべてのメソッドは読み取り専用のクエリです（API キーモードでは uploads も NotImplementedError になります）。そのため、このツールキットがアカウントを変更したり、データを外部に送信したりすることはありません。
• エンドポイントやスキーマを推測で作りません。 ここに記載されているシグネチャはすべて、実行時に L4 検証済みか、L3（ドキュメントで確認済み、未実行）と明記されています。references/verified_api_signatures.md を参照してください。新しいエンドポイントを使う場合は、推測せずに docs.bigdata.com/llms.txt でパスを確認してください。

ファイル構成

bigdata-skill/
├── SKILL.md                       # this file — routing + setup + quickstart
├── scripts/
│   ├── bigdata_toolkit/           # the verified, cost-guarded package
│   │   ├── client.py              # BigdataClient: SDK (.bd) + REST escape hatch (.http/.conn)
│   │   ├── kg.py                  # EntityResolver: name/ISIN/CUSIP/SEDOL → rp_entity_id
│   │   ├── search.py              # AnnotatedSearcher: chunks + sentiment + entity spans (SDK)
│   │   ├── rest_ext.py            # StructuredDataREST (estimates/financials/prices/dividends/sentiment/co-mentions/screener) + BatchSearch + fields_values_to_records — official REST
│   │   ├── cost.py                # CostTracker + CostModel: chunk billing + budget veto
│   │   └── retry.py               # rc(): SSL/transient-error retry passthrough
│   └── probe_example.py           # runnable end-to-end smoke test
└── references/
    ├── escape_hatch_architecture.md  # WHY the MCP is lossy; bd._api.http mechanism; adding endpoints
    ├── verified_api_signatures.md    # L4/L3-verified signatures + the two data faces, with evidence
    ├── cost_accounting.md            # chunk billing, the 52x trap, CostModel/CostTracker, budgeting
    └── known_pitfalls.md             # every pitfall above, with reproduction + fix

参考資料

次のことを調べる場合…	ファイル
MCP ではなぜ不十分なのか、REST のエスケープハッチがどのように機能するのか（および新しい /v1/* エンドポイントをラップする方法）を理解する	references/escape_hatch_architecture.md
検証済みメソッドの正確なシグネチャと検証レベルを確認する	references/verified_api_signatures.md
バックフィルの予算を立てる、または予期しないクォータ消費をデバッグする	references/cost_accounting.md
データ取得中に発生したエラーを診断する	references/known_pitfalls.md