originaiagent-core-master-sdk-python 0.1.0a2

Origin Core Master SDK (Python port of @originaiagent/core-master-sdk)

originaiagent-core-master-sdk-python

全 Python ツール共通の origin-core マスタ参照 SDK。TS 版 @originaiagent/core-master-sdk の Python ポート (v0.1.0-alpha.1 と機能同等 / read-only 14 メソッド)。

• 設計書: core-master-sdk-python-design.md
• TS-Python 対応表: core-master-sdk-python-parity.md
• Python 要件: 3.11 以降

インストール

Private repo のため GITHUB_TOKEN を環境変数に設定した上で pip から git URL で取得する。

# 最新 alpha をインストール
pip install "git+https://${GITHUB_TOKEN}@github.com/originaiagent/origin-core.git@core-master-sdk-python-v0.1.0-alpha.1#subdirectory=packages/core-master-sdk-python"

# pandas ヘルパもまとめて
pip install "originaiagent-core-master-sdk-python[pandas] @ git+https://${GITHUB_TOKEN}@github.com/originaiagent/origin-core.git@core-master-sdk-python-v0.1.0-alpha.1#subdirectory=packages/core-master-sdk-python"

Streamlit Cloud では .streamlit/secrets.toml に GITHUB_TOKEN を置き、requirements.txt に上記 URL を 1 行追加するだけで導入できる。

環境変数

変数	必須	用途
CORE_MASTER_BASE_URL	必須	Core API のベース URL (例: https://your-core-api.example.com)
CORE_MASTER_INTERNAL_API_KEY	必須	INTERNAL API キー。INTERNAL_API_KEY も後方互換フォールバックとして読むが、両方設定時は CORE_MASTER_* を優先し warnings.warn を出す

使用例

1. sync で products を取得して DataFrame 表示

from core_master_sdk import create_core_master
from core_master_sdk.pandas_helpers import products_to_df

# 引数を省略すると環境変数から自動読み込み
with create_core_master() as client:
    products = client.products.search("配線カバー", limit=50)
    df = products_to_df(products)
    print(df[["id", "product_name", "jan_code"]].head())

2. async で ASIN を一括逆引き

import asyncio
from core_master_sdk import create_async_core_master

async def map_asins() -> None:
    async with create_async_core_master() as client:
        result = await client.mall_identifiers.amazon_asin_map(
            ["B000000001", "B000000002", "B000000003"]
        )
        print(result)  # {"B000000001": 422, "B000000002": 423, "B000000003": None}

asyncio.run(map_asins())

3. エラーハンドリング

from core_master_sdk import (
    create_core_master,
    CoreMasterNotFound,
    CoreMasterAuthError,
)

with create_core_master() as client:
    try:
        product = client.products.get_by_id(999999)
    except CoreMasterNotFound:
        product = None  # 静かに握りつぶして OK
    except CoreMasterAuthError:
        raise  # env 設定ミスなので上位で止める

Streamlit アプリに組み込む

examples/streamlit_demo.py 参照。streamlit run examples/streamlit_demo.py で動作する。

提供リソース (14 メソッド × sync+async)

リソース	メソッド
products	list / get_by_id / by_ids / search / get_by_logi_id
product_groups	list / get_by_id
product_costs	list_by_product_id / get_latest_by_product_id
mall_identifiers	list_by_product_id / lookup / lookup_bulk / amazon_asin_map
mall_code_definitions	list / get_by_mall_id
malls	list / get_by_id

詳細は TS-Python 対応表 (parity.md) を参照。

例外階層

CoreMasterError (Exception)
├── CoreMasterAuthError       (401/403, retryable=False)
├── CoreMasterNotFound         (404,    retryable=False)
├── CoreMasterValidationError  (400/422, retryable=False)
├── CoreMasterRateLimitError   (429,    retryable=True)
└── CoreMasterUpstreamError    (5xx/network/timeout, retryable=True)

GET は retries=2 で retry (指数バックオフ + jitter)。429 / 5xx / タイムアウト / ネットワーク断が retry 対象。

開発

cd packages/core-master-sdk-python
python3.11 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest --cov

バージョニング

0.1.0a1 (= TS 版 0.1.0-alpha.1 と同マイルストーン)。TS 版と機能マイルストーンで一致させるが、patch レベルでは独立インクリメントされることがある (設計書 §10.1)。

関連

• 設計書: docs/core-master-sdk-design.md (TS 版共通設計)
• Core API: server/routes/masterV1.ts (13 GET エンドポイント)

License

Apache License 2.0. See LICENSE for details.