SDK

Schiftは、PythonとTypeScriptのファーストパーティSDK、さらにターミナルワークフロー用のPython CLIを提供しています。これらの3つのインターフェースはすべて同じREST APIに接続し、同じAPIキーを使用します。

SDKパッケージ

パッケージ	言語	インストール	用途
`schift`	Python	`pip install schift`	Pythonアプリ、ノートブック、データパイプライン
`@schift-io/sdk`	TypeScript	`npm install @schift-io/sdk`	Node、ブラウザ、ダッシュボード統合
`schift-cli`	Python CLI	`pip install schift-cli`	繰り返し可能なターミナルワークフローとオペレーション

注意: 古いnpm @schift-io/cliは、レガシーなデプロイ/プロバイダー/エージェントワークフローとの互換性のためにまだ存在します。メンテナンスされているバケット、カタログ、使用状況、ベンチマーク、および移行ワークフローには、Pythonのschift-cliパッケージを使用してください。

認証

ワークスペースダッシュボードでAPIキーを作成し、環境変数または明示的なコンストラクタ引数で設定します。

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=<your-api-url>/v1

この環境では SCHIFT_API_URL を {apiUrl}/v1 に設定してください。SDKは、APIのオリジンとしてSCHIFT_BASE_URLも読み取ります。CLIは最初にSCHIFT_API_KEYを読み取り、次にschift auth loginによって書き込まれた~/.schift/config.jsonにフォールバックします。

環境変数

変数	利用者	用途
`SCHIFT_API_KEY`	Python SDK, TypeScript SDK, CLI	APIキー（`sch_...`）
`SCHIFT_API_URL`	Python SDK, TypeScript SDK, CLI	完全なAPIベースURL、通常は`/v1`で終わる
`SCHIFT_BASE_URL`	Python SDK, TypeScript SDK	`/v1`パスなしのAPIオリジン

注意: SCHIFT_API_URLが欠落している場合、SDKとCLIは本番オリジンを仮定しません。ローカル、ステージング、またはホストされたワークスペース用に明示的に設定してください。

Python SDK

Python SDKは、2つのクライアントスタイルを提供します。

WorkspaceClient: バケットの取り込み、検索、埋め込み、使用状況、ホストされたワークフローなどのライブAPI操作のためのモジュラークライアント。
Client: ローカルで実行されるProjectionオブジェクトのフィッティングとダウンロードのためのレガシープロジェクションクライアント。

WorkspaceClient

from schift import WorkspaceClient

with WorkspaceClient() as client:
    bucket = client.buckets.create(name="finance-docs")
    upload = client.buckets.upload(
        bucket["id"],
        [("files", ("q1-report.pdf", open("q1-report.pdf", "rb").read(), "application/pdf"))],
    )
    hits = client.buckets.search(
        bucket["id"],
        "revenue guidance",
        top_k=5,
    )

WorkspaceClientは共有のhttpx.Clientを保持するため、短命のスクリプトにはコンテキストマネージャを使用することを推奨します。長時間実行されるプロセスの場合は、1つのインスタンスを保持し、シャットダウン時にclose()を呼び出してください。

コアモジュール

モジュール	例	用途
`catalog`	`client.catalog.list()`	埋め込みモデルのリスト
`embed`	`client.embed(text, model=...)`	単一テキストの埋め込み
`embed.batch`	`client.embed.batch(texts=[...])`	バッチ埋め込み
`buckets`	`client.buckets.create(name=...)`	バケットの取り込みと検索
`db`	`client.db.upsert(collection=...)`	生のベクトルとドキュメントのアップサート
`query`	`client.query("...", bucket=...)`	ホストされたバケットまたはパススルー検索
`rerank`	`client.rerank(query, documents=[...])`	候補の再ランク付け
`providers`	`client.providers.set("openai", api_key=...)`	BYOKプロバイダーキー
`routing`	`client.routing.set(primary=..., fallback=...)`	サーバーサイドのモデルルーティング
`pii`	`client.redact_pii(text, types=[...])`	韓国のPIIをマスク
`usage`	`client.usage.get(period="30d")`	使用状況の要約
`workflow`	`client.workflow.create_rag(name=...)`	ワークフローのCRUDと実行
`bench`	`client.bench.run(source=..., target=...)`	移行品質のベンチマーク

レガシープロジェクションクライアント

from schift import Client

legacy = Client(api_key="sch_your_key_here")
projection = legacy.fit(
    source=source_pairs,
    target=target_pairs,
    source_model="openai/text-embedding-3-small",
    target_model="google/gemini-embedding-001",
    project_name="openai-to-gemini",
)
projection.save("./projection-openai-to-gemini")

保存されたProjectionはオフラインで再ロードでき、ローカル移行エンジンで適用できます。

from schift import Projection
from schift.migrate import migrate
from schift.adapters.file import NpyAdapter

projection = Projection.load("./projection-openai-to-gemini")
source = NpyAdapter("old_embeddings.npy")
sink = NpyAdapter("new_embeddings.npy")

migrate(source=source, sink=sink, projection=projection, batch_size=2048)

TypeScript SDK

TypeScript SDKはWorkspaceClientを中心に構成されています。

import { WorkspaceClient } from "@schift-io/sdk";

const client = new WorkspaceClient({
  apiKey: process.env.SCHIFT_API_KEY!,
  baseUrl: process.env.SCHIFT_API_URL!,
});

await client.createBucket({ name: "company-docs" });
const file = new File([await readFile("manual.pdf")], "manual.pdf", {
  type: "application/pdf",
});
await client.db.upload("company-docs", { files: [file] });

const results = await client.bucketSearch("company-docs", {
  query: "refund policy",
  topK: 5,
});

コアメソッド

メソッド	用途
`embed(request)`	単一テキストの埋め込み
`embedBatch(request)`	バッチ埋め込み
`search(request)`	ベクトル検索
`bucketSearch(nameOrId, request)`	バケットの検索
`chat(request)`	バケットバックのRAGチャット
`chatStream(request)`	ストリーミングRAGチャット
`webSearch(query, maxResults?)`	ウェブ検索
`redactPii(request)`	韓国のPIIをマスク
`mask(text, options)`	便利なPIIマスク
`restorePii(request)`	ローカルでPIIトークンを復元
`providers.set(provider, config)`	BYOKプロバイダーキーを登録
`workflows.create(request)`	ワークフローを作成
`workflows.run(id, inputs)`	ワークフローを実行
`tools.openai()` / `tools.anthropic()` / `tools.vercelAI()`	プロバイダーSDKのためのツール定義

注意: 完全なTypeScriptクラスと型のリファレンスについては、SDK API Referenceを参照してください。

CLI

Pythonのschift-cliパッケージは、schift実行可能ファイルをインストールします。

pip install schift-cli
schift auth login
schift auth status

コマンドグループ

コマンド	用途
`schift auth ...`	ローカル認証状態の管理
`schift catalog ...`	サポートされている埋め込みモデルのブラウズ
`schift embed ...`	テキストから埋め込みを生成
`schift bench ...`	2つのモデル間の移行品質を評価
`schift migrate ...`	プロジェクションをフィットさせ、データベース移行を実行
`schift db ...`	バケットの作成、リスト、検査
`schift upload ...`	バケットにファイルをアップロード
`schift jobs ...`	取り込みジョブの検査、再処理、キャンセル
`schift search ...`	バケット検索を実行
`schift query ...`	バケット検索の互換性エイリアス
`schift usage ...`	集計された使用状況と請求の要約を表示

一般的なワークフロー

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=<your-api-url>/v1

schift upload ./handbook.pdf --bucket company-docs
schift jobs list --bucket company-docs
schift search "revenue report" --bucket company-docs --top-k 5

SchiftIndex

SchiftIndexは、ワークスペースバケットへの繰り返し可能なソース取り込みのためのSDK管理の同期インターフェースです。チームがローカルマニフェスト、テキストの差分、チェックポイント同期、再試行、およびObsidianボールト同期などのソース固有のアダプターを必要とする場合に使用します。

cd "/path/to/Obsidian Vault"
schift-index init --manifest schift.index.json --template dot-vault
SCHIFT_API_KEY=... schift-index sync --manifest schift.index.json --cloud

エラーハンドリング

Python SDKエラー:

from schift import WorkspaceClient
from schift import AuthError, QuotaError, SDKError

try:
    with WorkspaceClient() as client:
        client.catalog.list()
except AuthError:
    ...
except QuotaError:
    ...
except SDKError:
    ...

TypeScript SDKエラークラス:

import { AuthError, QuotaError, PlatformError } from "@schift-io/sdk";

try {
  await client.embed({ text: "test" });
} catch (err) {
  if (err instanceof AuthError) {
    // 401
  } else if (err instanceof QuotaError) {
    // 402
  } else if (err instanceof PlatformError) {
    // 403, 422, 429, 500, 502
  }
}