インターフェースと API

indx は、一つの厳密な Pydantic コントラクトを、インプロセス Python facade、CLI、同期 HTTP API の三つのインターフェースで公開します。

操作

操作	目的
capabilities / GET /v1/capabilities	現在の機能と埋め込み空間のスナップショットを返します。
plan / POST /v1/plan	処理を実行せず、決定論的な判断を確認します。
encode / POST /v1/encode	渡された計画または新しい計画を、ブロックと埋め込みへ実行します。
embed / POST /v1/embed	テキストまたは画像クエリを、指定した埋め込み空間へエンコードします。

Python

from indx import EncodeRequest, Indx, RequestId, UriSource

result = Indx().encode(
    EncodeRequest(
        request_id=RequestId("encode-1"),
        source=UriSource(uri="file:///absolute/path/report.pdf"),
        embedding_space_ids=("default-text",),
    )
)

for block in result.blocks:
    print(block.kind, block.status, block.text)

トップレベルの indx パッケージは、遅延生成される既定サービスを使うモジュール関数 capabilities()、plan()、encode()、embed() も公開しています。

CLI

uv run indx capabilities
uv run indx plan file:///absolute/path/report.pdf
uv run indx encode file:///absolute/path/report.pdf
uv run indx embed --space default-text "annual recurring revenue"
uv run indx serve --host 127.0.0.1 --port 8000

CLI は同じコントラクトを整形済み JSON として出力します。意図的に小さいインターフェースなので、制約や文書の埋め込み空間を含む完全なリクエストが必要な場合は Python または HTTP を使用してください。

HTTP

JSON リクエストは URI または base64 インラインソースを受け付けます。計画、エンコード、画像埋め込みでは、JSON の request パートとバイナリの file パートを持つ multipart アップロードも利用できます。

curl -s http://127.0.0.1:8000/v1/capabilities

すべてのレスポンスには相関用の X-Request-ID ヘッダーが付きます。失敗は一つの型付きエンベロープを使います。

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Input should be a valid string",
    "param": "source.uri.uri",
    "request_id": "request-from-your-body"
  }
}

just demo::server を実行し、ローカル Swagger を開くと、コントラクトを対話的に確認できます。

リファレンス

• API コントラクト
• コミット済み OpenAPI 文書
• Python facade