TypeSafe で構築する
TypeSafe は、AI インテリジェンスのユニットをプログラミングのプリミティブのように利用可能にします。つまり、より大きな機能に組み合わせられる小さな判断です。その System One モデル は、ソフトウェアが直接消費できる高速で焦点の絞られた判断を返します。Jev は TypeSafe のフラッグシップかつ最初の System One モデルです。自然言語を理解し、テキストや推論の説明を生成する代わりに、型付きの回答と確率を返します。コードがワークフローを所有し、モデルは通常のコードにセマンティックな理解が必要な場所で、プログラマブルな常識を提供します。
OpenRouter 経由で Jev を呼び出す
このスキルのバリアントは、TypeSafe 自身の API ではなく OpenRouter 経由で Jev を呼び出します。TypeSafe のドキュメントは、コンセプトと質問設計のリファレンスとして引き続き有効です。アクセス、モデル ID、課金のみが異なります。
- 認証情報: OpenRouter API キー。OpenRouter アカウントに請求されます。TypeSafe アカウントは不要です。環境変数 (
OPENROUTER_API_KEYまたはTYPESAFE_API_KEYに OpenRouter キーを設定) から読み取り、ハードコードせず、Web アプリではサーバー側に保持してください。 - System One API (デフォルト):
POST https://openrouter.ai/api/v1/systemone、Authorization: Bearer <OpenRouter キー>を使用します。TypeSafe のリクエストおよびレスポンスの形状を実装し、レスポンスにid、provider、usage.costを追加します。 - TypeSafe SDK (
@typesafe-ai/sdk、typesafe_sdk):baseURL/base_urlまたはTYPESAFE_BASE_URLを介してベース URL をhttps://openrouter.ai/api（SDK が/v1/systemoneを追加）に設定し、apiKey/api_keyまたはTYPESAFE_API_KEYを介して OpenRouter キーを渡します。その他はすべて TypeSafe の SDK ドキュメントに従います。 - SDK のモデルリストは呼び出さないでください (
client.models.list()): OpenRouter では OpenRouter の Models API にヒットし、そのレスポンス形状を SDK が拒否します。 - モデル ID:
jev-1.14(現在)、jev-1.13、またはjev-latest。ベア ID はtypesafe/jev-…および~typesafe/jev-latestにマップされます。再現可能なしきい値のためにバージョンを固定してください。現在のバージョン、価格、コンテキスト長については OpenRouter 上の TypeSafe モデル を確認してください。レスポンスのmodelフィールドは、リクエストを処理した正確なバージョンを示します。 - Box (
state内の画像内で記述されたターゲットを特定する) にはjev-1.14以降が必要です。1.13 は 400 で拒否します。Box は常にエッジを返すため、ターゲットが存在しない可能性がある場合は Noul と組み合わせて使用してください。 - 代替手段: OpenRouter 自身の Decisions API (
POST https://openrouter.ai/api/alpha/decisions) と、その TypeScript、Python、Go SDK。プロジェクトが既に OpenRouter SDK を使用している場合にのみ優先してください。 - Jev の型付き API ではありません:
typesafe/jev-routerは、Jev を使用して別の LLM を選択するチャット補完ルーターです。テキスト生成を返し、型付き回答を返さないため、このスキルのパターンには適合しません。 - クラウドおよびサンドボックスセッション: ネットワーク許可リストに
openrouter.aiを含める必要があります。キーはプレーンな環境変数ではなく、シークレットとして保存してください。
OpenRouter ドキュメント: OpenRouter 上の Jev、OpenRouter 上の TypeSafe SDK、Jev チュートリアル、およびドキュメントインデックス (「Jev」を検索してクックブックを見つけてください)。アクセス、エンドポイント、モデル ID、価格について OpenRouter と TypeSafe のドキュメントが異なる場合は、この設定では OpenRouter のドキュメントが優先されます。
ライブドキュメントを読む
ライブの TypeSafe ドキュメントが信頼できる情報源です。タスクの一部として読んでください。 このスキルは方向性を示します。ドキュメントには、現在のコンセプト、プロンプトガイダンス、API 契約、SDK の使用法、モデル、制限、および実際の例が含まれています。
- ドキュメントインデックス から始めて、関連するページとクックブックを見つけてください。サイト全体をロードするのではなく、対象を絞った読み取りを使用してください。
- Mintlify はページパスに
.mdを追加して Markdown を提供します。例: TypeSafe で構築する方法。インデックスからリンクをたどってください。必要に応じて、拡張子のないドキュメントページリンクを.mdに変換してください。相対リンクはhttps://docs.typesafe.aiに対して解決してください。 - 統合を記述する前に、現在の API または選択した SDK ページと、設計に関連する質問ガイダンスを読んでください。新しいワークフローの場合は、最も近いクックブックも確認してください。汎用的な分類器よりも優れた分解が示されていることがよくあります。
- インデックスが利用できない場合は、以下の直接リンクまたはサイトのナビゲーションを使用してください。Markdown の取得に失敗した場合は、通常のページを試してください。ライブアクセスが利用できない場合は、利用可能なローカルドキュメントまたはインストール済み SDK の型を使用し、その制限を明記し、バージョン依存の詳細をでっち上げないでください。
| タスク | ここから始めて、関連する詳細をたどる |
|---|---|
| プログラミングモデルを理解する | System One、構築ガイド |
| 何を構築するか探る | ユースケースマップ、次に関連するクックブックをインデックスから |
| 入力と質問を準備する | State、プリミティブ、次に選択したプリミティブのページ |
| 不確実性への対処方法を決める | Confidence |
| API コードを書く | 最初に OpenRouter 上の TypeSafe SDK、次にリクエスト形状については HTTP API、Python SDK、または JavaScript SDK (OpenRouter のベース URL とキーを使用) |
| OpenRouter クックブックを見つける | ツールコールゲーティング、検証カスケード、大規模分類、権限プロンプト自動承認 |
| 古い統合を更新する | 移行ガイド とインストールされている SDK の現在のリファレンス |
有用な形状を見つける
ユーザーが望む動作から始めてください。アプリケーションは何を表示、選択、変更、または引き継ぐのでしょうか？ 必要となる判断に向かって逆算してください。既知のルール、計算、正確なルックアップ、および実行はコードに残してください。ユーザーの選択したスタックとスコープを維持し、セマンティックな理解が役立つ場所に TypeSafe を追加してください。
ブレインストーミングやアーキテクチャの選択時には、分類以上のものを検討してください。以下のパターンは出発点です。ユーザーの目標に合わせてプリミティブを組み合わせてください。確立されたレシピに当てはまらないアイデアも含めてください。
- ルーティングと既知の引数の入力。 リクエストは、ハンドラーとその型付きパラメータを選択できます。有用なブランチ固有の質問を事前に行い、関連する回答のみを消費します。関数呼び出し と 投機的ファンアウト を参照してください。
- 生成ではなく選択。 コード内の候補値またはソーススパンを見つけ、判断を使用して意図されたものを選択し、コピーまたは正規化します。コードはソーステキストをフォーマットされたドキュメントや読み上げガイドに組み立てることもできます。値抽出 と 構造回復 を参照してください。
- 証拠を見つけて判断する。 候補を取得し、クエリとの関連性を比較し、有用なコンテキストを選択します。再ランキング と 階層的分類 を参照してください。
- 判断を再利用可能なデータに変える。 次元を一度スコアリングし、コードまたはユーザーコントロールが重み、しきい値、ランキング、ビューを変更できるようにします。ラベル付けされた結果があれば、それらのシグナルは古典的な ML 特徴量になります。複合スコアリング と 特徴発見 を参照してください。
- 検証とエスカレーション。 特定の主張やフィールドをその証拠に対してチェックし、不確実または失敗したケースを人間または推論モデルに送信します。引用チェック と 抽出カスケード を参照してください。
- 変化する状態への応答。 コードは目標と観察結果を保持し、新鮮な判断が次の境界のあるステップを導くことができます。推論された状態は観察された事実と区別し、変更された状況に結果を適用する前に鮮度を確認してください。
オープンなリクエストに対しては、ユーザーの目標に最も適したいくつかの方向性を提案し、開始点を推奨してください。具体的なリクエストに対しては、関連するパターンを選択して構築してください。ブレインストーミングは必須の寄り道ではありません。
判断を設計する
答えの意味によって選択し、次に関連するプリミティブのページを読んでください。
| ニーズ | プリミティブ | 重要な区別 |
|---|---|---|
| 定義されたセットの 1 つ | Choice | 1 つのオプションを選択。その分布は競合するオプションを比較する |
| 条件が成立するかどうか | Noul | はいの確率。別個の信頼度はなし。複数が該当する可能性がある場合は、ラベルごとに 1 つ使用する |
| 記述された次元に沿った程度 | Score | 順序付けられたレベルの確率重み付け位置。段階的ランキングには、アイテムごとに比較可能な Score を使用する |
| 記述されたターゲットが画像内のどこにあるか | Box | Jev 1.14+ のみ。基準なし。常にエッジを返すため、存在確認には Noul を尋ねる |
各質問に、回答するために十分な関連 state を提供してください。ソーステキスト、ID、関係、ポリシー、現在の事実などです。コンテキストに複数の部分がある場合は、名前付き JSON フィールドを優先してください。判断を instructions に配置し、その可能な答えを criteria で定義してください。質問 ID はコード用であり、モデルには送信されません。完全な意味を質問に含めてください。ネストされた state は、ticket.messages[0].text のようなバックティック付きパスで参照してください。
質問ごとに、1 つの狭く一貫した判断を尋ねてください。独立して有用な次元を分割しますが、判断対象の関係を破壊しないでください。境界のあるアクション選択や文脈に応じた解釈は有効です。アトミックとは、文字通りの事実抽出や 1 文の制限を意味しません。単純な質問には文字列で十分です。定義、対比、除外、例が指示や基準を明確にする場合は、構造化オブジェクトまたは配列を使用してください。Score レベルは具体的な状況を説明し、それ自体で意味が通じる必要があります。
必要な答えが利用可能であることを確認してください。何も当てはまらない場合のために、一致なしの結果を含めてください。独立して有用な場合は、別個の存在判断を使用してください。ソース値の選択では、候補のカバレッジを確認してください。モデルは省略された値を選択できません。
合成と検証
同じ state に対して独立した質問を一緒に尋ねてください。 有用な投機的質問を含めてください。これらは並行して実行され、お互いの答えを見ることはできません。各投機的前提は明示的に記述してください。コードは該当する答えを消費します。以前の回答が証拠を取得したり、新しい state を構築したり、次のオプションを決定したりするために必要な場合にのみ、2 番目のリクエストが必要です。余分な質問でもトークンは使用されます。実際のリクエスト予算、コスト、エンドツーエンドのレイテンシを測定してください。
確率と信頼度を使用して動作をガイドし、しきい値はユーザーのデータと結果に基づいて評価してください。Choice/Score の信頼度は分布の集中度を要約しますが、ワークフロー全体の正当性や実行許可ではありません。0.5 付近の Noul は、中程度の強さではなく、はいといいえの確率が同程度であることを意味します。いくつかの許容可能な代替案でも確率が分散する可能性があります。低い信頼度が無害な選好選択を無効にする必要はありません。未使用のブランチの不確実性は無視してください。
ポリシーは明示的に保ち、生の判断は再利用可能にしてください。重み付けスコアは補完的な選好に適しています。「重大な違反」ルールには個別の条件が必要です。証拠と質問の意味が変わらない場合、重みや表示フィルターを変更しても推論を再実行する必要はありません。型付き出力はインターフェースを保証しますが、真実は保証しません。System One モデルは調整された決定のためにトレーニングされています。ターゲットドメインでのパフォーマンスを検証してください。
代表的なケースと結果のアプリケーション動作をテストしてください。障害が発生した場合は、正確な state、質問、候補、回答、構成、観察された結果を検査してください。欠落した証拠、モデルエラー、コードエラー、サービス障害を分離してください。クックブックのしきい値とデモ結果は、評価する例として扱い、普遍的なルールや永続的なモデルの制限としては扱わないでください。Web アプリでは API 認証情報をサーバー側に保持してください。