---
title: "API リファレンス"
description: "Arkor SDK: createArkor、createTrainer、ライフサイクルコールバック、infer、その周辺ヘルパー。"
---

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

## 最小例

```ts
// 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,
});
```

```ts
// src/arkor/index.ts
import { createArkor } from "arkor";
import { trainer } from "./trainer";

export const arkor = createArkor({ trainer });
```

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

## 主要 API

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

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

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

| シンボル | ソース | 目的 |
| --- | --- | --- |
| `runTrainer(file?)` | `core/runner.ts` | `arkor 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` | マニフェストの型ガード。 |
| [`CloudApiClient`](/ja/docs/framework/sdk/deployments) | `core/client.ts` | クラウド API の型付きクライアント。`*.arkor.app` 推論 URL を管理する `listDeployments` / `createDeployment` / `createDeploymentKey` などを公開。完全なメソッド一覧と使用例は [Deployments](/ja/docs/framework/sdk/deployments) を参照。 |
| `CloudApiError` | `core/client.ts` | `CloudApiClient` が非 2xx レスポンスで投げる Error クラス。`.status` と構造化された `{ error }` body をそのまま保持するので、`instanceof CloudApiError && err.status === 409` で slug 衝突などを分岐できます。 |
| `defaultArkorCloudApiUrl(credentials?)` | `core/credentials.ts` | SDK が使うクラウド 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](/ja/docs/framework/sdk/deployments) を参照）: `CloudApiClientOptions`、`DeploymentTarget`、`DeploymentAuthMode`、`DeploymentRunRetentionMode`、`DeploymentDto`、`DeploymentKeyDto`、`DeploymentScope`、`CreateDeploymentInput`、`UpdateDeploymentInput`、`CreateDeploymentKeyInput`、`CreateDeploymentKeyResult`。ランタイムの `CloudApiClient` / `CloudApiError` クラスは上の Utilities セクションに掲載されています。型ではなく値の export なので、値として import してください。

`TrainingLogContext`、`CheckpointContext`、`InferArgs` は今のところ名前付きでエクスポートされていません。型付きのコールバックパラメーターが必要なら、[コールバック](/ja/docs/framework/sdk/callbacks) と [infer](/ja/docs/framework/sdk/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()` を直接呼んでください。

## 関連項目

- [実行ライフサイクル](/ja/docs/framework/concepts/lifecycle): `start()` / `wait()` が実際に何をするか
- [プロジェクト構成](/ja/docs/framework/concepts/project-structure): プロジェクト内でマニフェストとトレーナーがどこに置かれるか
- [CLI 概要](/ja/docs/framework/cli/overview): SDK をシェルから実行するためのインターフェイス