ArkorAlpha
English

API リファレンス

Arkor SDK: createArkor、createTrainer、ライフサイクルコールバック、infer、その周辺ヘルパー。

arkor パッケージは、CLI と Studio が利用する TypeScript の公開 API を提供します。典型的なプロジェクトに必要なものは、3 つのプリミティブとそれぞれの型付き入力にすべて収まります。

最小例

// src/arkor/trainer.ts
import { createTrainer } from "arkor";

export const trainer = createTrainer({
  name: "support-bot-v1",
  model: "unsloth/gemma-4-E4B-it",
  dataset: { type: "huggingface", name: "arkorlab/triage-demo" },
  lora: { r: 16, alpha: 16 },
  maxSteps: 100,
});
// src/arkor/index.ts
import { createArkor } from "arkor";
import { trainer } from "./trainer";

export const arkor = createArkor({ trainer });

これが arkor dev と arkor start が発見する全体の形です。

主要 API

シンボルページ
createArkor(input)プロジェクトマニフェスト。CLI / Studio が見つけられるよう Trainer をラップ。
createTrainer(input)ファインチューニング学習の定義: モデル、データセット、LoRA、ハイパーパラメーター、コールバック。
Trainer.start / wait / cancel学習制御メソッド。wait() がライフサイクルコールバックを発火する場所。
TrainerCallbacks5 つのライフサイクルコールバック（onStarted、onLog、onCheckpoint、onCompleted、onFailed）。
InferArgs / inferonCheckpoint 内での推論。生の Response を返す。
DatasetSourceHuggingFace データセット名 or blob URL。

補助ヘルパー（上級者向け）

CLI フローの外で Arkor を実行するコード（自前のサーバーやスクリプトから学習を走らせるなど）のためにエクスポートされています。ほとんどのプロジェクトでは不要です。

シンボルソース目的
runTrainer(file?)core/runner.tsarkor start が裏で呼んでいるもの。エントリーを解決し、トレーナーを選び（arkor を最優先、次に trainer、最後に default export）、start() + wait() を実行。
readCredentials() / writeCredentials() / ensureCredentials()core/credentials.ts~/.arkor/credentials.json の読み書き。readCredentials はファイルが無いか内容が破損（不正な JSON）のとき null を返す（切り詰められたファイルは欠損として扱う）。ファイルが存在するが読めない場合（EACCES / EIO / EISDIR）のみ再 throw し、有効だが一時的にロックされたログインを黙って捨てないようにします。ensureCredentials は既存レコードがあれば返し、認証情報が無いか破損しているときは警告して 新規の匿名 ID を初期化（requestAnonymousToken を呼んで永続化）します。ファイルが存在するが読めない場合や、匿名トークン取得自体が失敗（ネットワーク／トークンエンドポイントエラー）した場合は throw します。writeCredentials はアトミックに書き込みます（temp ファイル + rename）。ファイルは SDK が書いている前提。
requestAnonymousToken(baseUrl, kind?)core/credentials.ts新しい匿名トークンを直接発行。CLI は arkor login --anonymous と初回 arkor dev でこれを使う。
credentialsPath()core/credentials.ts~/.arkor/credentials.json の絶対パス。
readState(cwd?) / writeState(state, cwd?) / statePath(cwd?)core/state.ts.arkor/state.json（プロジェクトルーティング）の読み書き。
isArkor(value)core/arkor.tsマニフェストの型ガード。
CloudApiClientcore/client.tsクラウド API の型付きクライアント。*.arkor.app 推論 URL を管理する listDeployments / createDeployment / createDeploymentKey などを公開。完全なメソッド一覧と使用例は Deployments を参照。
CloudApiErrorcore/client.tsCloudApiClient が非 2xx レスポンスで投げる Error クラス。.status と構造化された { error } body をそのまま保持するので、instanceof CloudApiError && err.status === 409 で slug 衝突などを分岐できます。
defaultArkorCloudApiUrl(credentials?)core/credentials.tsSDK が使うクラウド API のベース URL を解決します。優先順位: ARKOR_CLOUD_API_URL 環境変数 → 渡された credentials に保存された URL（匿名は signup 時、OAuth は arkor login が認証時の URL を保存するように更新済み）→ 本番エンドポイント。readCredentials() / ensureCredentials() で得た credentials から CloudApiClient を作るときに使い、ユーザーが認証した staging / self-hosted control plane に追従させます。

型

公開型エクスポート（arkor から）:

Arkor、ArkorInput、ArkorProjectState、BlobDatasetSource、DatasetSource、HuggingfaceDatasetSource、JobStatus、LoraConfig、Trainer、TrainerCallbacks、TrainerInput、TrainingJob、TrainingResult。加えて認証ヘルパー用の OAuthCredentials、AnonymousCredentials、Credentials。

Deployment 関連の型のみエクスポート（Deployments を参照）: CloudApiClientOptions、DeploymentTarget、DeploymentAuthMode、DeploymentRunRetentionMode、DeploymentDto、DeploymentKeyDto、DeploymentScope、CreateDeploymentInput、UpdateDeploymentInput、CreateDeploymentKeyInput、CreateDeploymentKeyResult。ランタイムの CloudApiClient / CloudApiError クラスは上の Utilities セクションに掲載されています。型ではなく値の export なので、値として import してください。

TrainingLogContext、CheckpointContext、InferArgs は今のところ名前付きでエクスポートされていません。型付きのコールバックパラメーターが必要なら、コールバック と infer ページを見てインラインで同じ形を定義してください。

公開 API に含まれないもの

ソースツリーには存在しますが意図的に arkor からエクスポートされていないもの。内部扱いです:

  • SDK_VERSION: CLI と Studio サーバーがヘッダー / ログ用途で使います。深いパスから import しないでください。エクスポート契約は変わり得ます。
  • CLI コマンドランナー（runBuild、runStart、runDev、runInit、runLogin、runLogout、runWhoami）: src/cli/commands/ 以下にあり、CLI 専用です。学習を実行したいなら（上記の）runTrainer を使うか、trainer.start() / trainer.wait() を直接呼んでください。

関連項目