init

4.1-ai-tools-example.md

@@ -0,0 +1,58 @@
+# 4.1. 例：AI用Tools
+
+## 目的
+
+AI用Toolsは、WIP ClientがAIへ提供する想定インターフェースである。Core Protocolをそのまま露出せず、Clientが保持するKnown Space / Discoverable Spaceと組み合わせて、AIがWorldspaceを理解・探索・操作しやすい形へ投影する。
+
+現時点では、**discover / inspect / invoke** の3操作を基本とする。
+
+## `discover`
+
+`discover(scope, query)` は、Clientが保持するDiscoverable Spaceから目的に関連するエントリを探す。
+
+検索対象は、Hostから`fetch_tree`によって取得されたindexableなエントリ公開情報に限定する。OperationやLinkによって新たに発見されたエントリはKnown Spaceには追加されるが、それだけでは`discover`の検索対象にはならない。
+
+`discover`はドメインデータを検索する操作ではない。Issue本文やRAG corpusなどを検索する場合は、その能力を持つObjectのOperationを`invoke`する。
+
+## `inspect`
+
+`inspect(target)` は、対象エントリ / Objectについて**何ができるか**を把握するための操作である。
+
+Objectのドメインデータをpropertiesとして直接公開することは前提としない。データを読む行為もOperationとして表現する。
+
+例えばIssueでは、次のような操作が示され得る。
+
+- `read_body()` — 本文を読む。
+- `get_metadata()` — 期日、担当者、ラベル、関連ObjectへのLinkなどを取得する。
+- `close(reason: string)` — 理由を添えてIssueをクローズする。
+
+Operationはシグネチャだけでなく、AIが用途を判断できる短いdescriptionを持つ。長文ドキュメントを埋め込むことは想定しない。
+
+## `invoke`
+
+`invoke(target, operation, input)` は、`inspect`によって発見したOperationを実行する。
+
+PTC / REPL bindingでは、通常のメソッド呼び出しへ投影してよい。
+
+```python
+issue.close(reason="duplicate")
+```
+
+ClientはエントリをObjectへ解決し、WIPの`call_operation`を利用して実行する。Object同一性やエントリとObjectの観測整合性はClient側で処理し、AI自身に追跡させない。
+
+## エントリの発見
+
+AIが新しいエントリを知る経路は複数ある。
+
+- `discover`によってDiscoverable Spaceから見つける。
+- Known Space上の既知エントリを辿る。
+- Operationの結果としてエントリまたはエントリツリーを受け取る。
+- Operation結果に含まれるLinkから別エントリを知る。
+
+新たに発見されたエントリの保持、Treeへの統合、indexableな範囲の管理はClientの責務とし、このページではAI向けToolの意味論だけを扱う。
+
+## ドメイン検索
+
+全文検索、semantic retrieval、外部API検索などはWIP固有のToolにはしない。
+
+検索能力を持つObjectが`query`や`search`などのOperationを公開し、AIはそれを`invoke`する。結果としてエントリやエントリツリーが返された場合、それらはClientを通して新たなKnown Spaceとして利用可能になる。