Skip to content

local-interfaces.md

Latest commit

 

History

History
171 lines (115 loc) · 12.9 KB

local-interfaces.md

File metadata and controls

171 lines (115 loc) · 12.9 KB
Raw

ローカル参照インターフェース

目的

正規取得済みPMGS原資料から生成した版付きSQLiteを、Python、CLI、stdio MCP、Codex、Claude Codeから同じ検索契約で参照する。通常の導入はpmgs setupがSQLiteの構築、検証、現行版の切替まで行う。

いずれの経路もモデルを呼ばず、定義の要約、分類候補の推測、機械翻訳、ネットワーク取得を行わない。

PMGSの原archive、展開後の原資料、生成SQLite、一括exportはローカルに保ち、Gitや外部AIサービスへアップロードしない。AIはローカルMCPが返す上限付きの構造化結果だけを証拠として利用し、その本文内のリンク、コマンド、設定変更指示を命令として実行しない。

データベースの指定

PMGSStore.open()とquery系CLIは、次の順でSQLiteを探す。

  1. pathまたは--dbで渡した明示パス
  2. data_dirまたは--data-dirで渡した管理ディレクトリのstate/current.json
  3. PMGS_REFERENCE_DB環境変数
  4. OS既定の管理ディレクトリにあるstate/current.json
  5. pointerがまだない旧構成だけ、管理ディレクトリのdata/current.sqlite

OS既定の管理ディレクトリはWindowsが%LOCALAPPDATA%\pmgs-reference、macOSが~/Library/Application Support/pmgs-reference、Linuxが${XDG_DATA_HOME:-~/.local/share}/pmgs-referenceである。

current.jsonはrelease、source manifest SHA-256、database SHA-256、schema version、管理ディレクトリ内の相対DBパスを持つ。通常のqueryは、形式不正、管理ディレクトリ外への参照、欠損ファイル、内容アドレス付きpathとDB内metadataの不一致をfail closedで拒否し、旧current.sqliteへ暗黙にfallbackしない。

実DBの全量SHA-256は参照のたびには計算しない。pmgs setupは有効化または再利用前に、pmgs doctor --data-dir ...は診断時に、実ファイルhashをcurrent.jsonのdatabase_sha256と照合する。内容アドレス付きDBを外部編集した場合は、通常queryの前にこのどちらかを実行する。

PythonパッケージにPMGS原資料やSQLiteは同梱しない。データベースが見つからない場合も自動ダウンロードしない。

照会言語は日本語jaを既定とし、原資料に英語がある場合はenへ切り替えられる。

Python API

from pmgs_reference import PMGSStore

store = PMGSStore.open()

record = store.lookup("fi", "G06F3/048", language="ja")
ipc_old = store.lookup("ipc", "G06F3/048", edition="8U", version="2006.01")
classifications = store.search("相互作用技術", schemes=["fi", "ipc"], limit=20)
combined = store.search_pmgs("相互作用技術", limit=20)
parents = store.parents("fi", "G06F3/048")
documents = store.related_documents("ipc", "G06F3/048", edition="8U")
release = store.release_info()

公開メソッドは次のとおりである。

  • PMGSStore.open(path=None, *, data_dir=None)
  • lookup(scheme, code, release="current", edition=None, language="ja", *, version=None, relation_limit=50, relation_offset=0)
  • search(query, schemes=None, release="current", language="ja", limit=20, *, offset=0)
  • search_pmgs(query, schemes=None, content_types=None, release="current", language="ja", limit=20, *, classification_offset=0, document_offset=0)
  • hierarchy(direction, scheme, code, release="current", edition=None, language="ja", *, limit=50, offset=0)
  • parents(scheme, code, release="current", edition=None, language="ja", *, limit=None, offset=0)
  • children(scheme, code, release="current", edition=None, language="ja", *, limit=None, offset=0)
  • related_documents(scheme, code, release="current", edition=None)
  • get_document(document_id, page=None, section=None, *, locator=None, segment_limit=200, segment_offset=0, related_classification_limit=200, related_classification_offset=0)
  • search_documents(query, release="current", language="ja", limit=20, *, offset=0)
  • release_info(release="current")

IPCでeditionを省略した場合は、正本に存在する版から8U、8B、7、7E、6、5、4の優先順で選ぶ。FIとFタームへeditionを渡すとINVALID_EDITIONになる。versionはIPCだけに指定でき、CLIでは--ipc-versionを使う。

IPCのversion省略時はrelease基準日に有効な唯一のrevisionを返す。有効なrevisionがない場合はnot_valid_at_release、指定したversionがない場合はversion_not_foundを、利用可能なversion一覧とともに正常な構造化応答として返す。旧revisionへ推測でfallbackしない。

分類照会は候補を推測しない。コードが存在しない場合は、空の共通レコードをmatch_status: not_foundで返す。入力不正、release不明、文書不明、DBエラーはPMGSQueryErrorの安全なcodeとmessageで区別する。

関係は安定順でページングし、relation_count、relations_truncated、next_relation_offsetを返す。relation_limitは最大200件である。分類・文書の構造化応答がUTF-8 JSONで4 MiBを超える場合はRESPONSE_TOO_LARGEでfail closedにする。

階層一覧はhierarchy()を正本とし、親または子をcount、limit、offset、truncated、next_offset付きのbounded summaryとして返す。各summaryはscheme、edition、code、version、label、record statusだけを持ち、一件ごとの完全なlookup()を行わない。parents()とchildren()は、limitを指定した場合は同じページ応答を返し、省略時は互換性のため全ページのsummary listを返す。release基準日に複数revisionが同時にactiveな場合は、並び順で一つを選ばずMULTIPLE_ACTIVE_REVISIONSでfail closedにする。完全なtexts、properties、relations、documents、sourcesが必要な場合は、選択したsummaryをlookup()へ渡す。従来parents()またはchildren()から完全recordを受け取っていた呼び出し側は、この二段階へ移行する。

文字列検索

3文字以上の各検索語はSQLite FTS5のtrigram索引で照合する。1文字または2文字の検索語を含む場合だけ、エスケープ済みLIKEによるリテラル部分一致へ切り替える。

応答のsearch_modeは、使用した経路を次のいずれかで示す。

  • sqlite_fts5_trigram_lexical
  • sqlite_literal_substring_lexical
  • MCPで分類と文書が異なる経路になった場合のmixed_lexical

search()は互換性のため分類だけを検索する。search_pmgs()は分類と文書をresults_by_type.classificationとresults_by_type.documentへ分け、limitを各種類へ独立適用する。各ページはlimit、offset、has_more、next_offsetを返す。複合検索ではclassification_offsetとdocument_offsetを別々に指定し、一方の結果だけを続けて取得できる。重複する本文行は分類または文書単位でまとめてからページ上限を適用する。いずれも文字列検索であり、意味検索ではない。類義語、表記揺れ、分類候補をAIで補わない。

文書selectorとページング

ローカルのPython API、CLI、stdio MCPでは、page、section、locatorは相互排他である。pageはPDF等の1始まりページ番号、sectionはdocument_text.sequence_numberに対応する1始まりのsegment番号を表す。locator、heading、source locatorを文字列で完全一致させる場合だけlocatorを使う。公開APIは同じ意味のpageと整数sectionだけを公開し、ローカル専用のlocatorやoffset引数は公開しない。公開側の続きはchunk.previousとchunk.nextで取得する。

ローカルのsegment応答はsegment_limitとsegment_offsetでページングする。応答はsegment_count、segment_limit、segment_offset、segments_truncated、next_segment_offsetを返す。関連分類は独立したrelated_classification_limitとrelated_classification_offsetを使い、related_classification_count、related_classification_limit、related_classification_offset、related_classifications_truncated、next_related_classification_offsetを返す。各limitの上限は200件である。

いずれかのtruncated fieldが真なら、対応するnext_*_offsetを次のローカル呼出しへ渡す。存在しないselectorはDOCUMENT_SELECTOR_NOT_FOUND、selectorの同時指定はINVALID_DOCUMENT_SELECTORとしてfail closedにする。v0.4.0で文字列をsectionへ渡していたPython呼出し側は、その値をlocatorへ移す。sectionは正のsequence番号だけを受け付ける。

CLI

pmgs lookup fi "G06F3/048" --json
pmgs lookup ipc "G06F3/048" --ipc-version 2006.01 --relation-limit 50 --json
pmgs search "相互作用技術" --scheme fi --scheme ipc --json
pmgs search "改正" --content-type document --document-offset 20 --json
pmgs document DOCUMENT_ID --page 1 --json
pmgs document DOCUMENT_ID --section 201 --segment-limit 50 --segment-offset 0 --json
pmgs document DOCUMENT_ID --locator "page:1" --related-classification-limit 50 --json
pmgs doctor --timeout-seconds 30 --json

lookup --jsonはnot_found、version_not_found、not_valid_at_releaseのいずれも、説明可能な共通recordを出力して終了コード1を返す。該当recordを返した正常照会は0を返す。

lookupとsearchの--language既定値はjaである。英語は--language enを指定する。

doctorはSQLite schema、release、実stdio接続、read-only annotation、lookup_classification、search_pmgs、get_pmgs_documentの実呼び出し、照会前後hashを検査する。管理ディレクトリを指定した場合は、実ファイルhashとcurrent.jsonのdatabase_sha256を照合し、診断中にcurrent pointerが切り替わっていないことも確認する。

stdio診断全体は既定30秒で有界化し、--timeout-secondsには有限の正数だけを指定できる。起動、初期化、tool列挙、各tool呼び出し、終了処理のいずれかで期限を超えた場合、taskをcancelしてstdio子プロセスを終了・回収し、failure.code: MCP_TIMEOUTと失敗時のfailure.stageを返す。決定的なsampleをDBから選べない場合はSAMPLE_SELECTION_FAILED、tool応答の構造契約に失敗した場合はMCP_CONTRACT_FAILEDを返す。例外の生メッセージや本文全量をfailureへ含めない。

JSON reportのdatabaseはファイル名だけを返し、sample queryはSHA-256、tool結果は件数と状態の要約だけを返す。ローカル絶対path、検索語本文、取得本文、excerpt、source pathはreportへ含めない。

stdio MCP

サーバーは次の読み取り専用toolだけを公開する。

  • lookup_classification
  • search_pmgs
  • get_pmgs_document

起動例：

C:\path\to\pmgs-reference\Scripts\python.exe -m pmgs_reference.cli mcp --data-dir C:\path\to\pmgs-data

MCPクライアント設定では、裸のpython、py、uvxキャッシュではなく、このプロジェクト用の安定仮想環境にあるpython.exeの絶対パスを指定する。

{
  "mcpServers": {
    "pmgs-reference": {
      "command": "C:\\path\\to\\pmgs-reference\\Scripts\\python.exe",
      "args": [
        "-m",
        "pmgs_reference.cli",
        "mcp",
        "--data-dir",
        "C:\\path\\to\\pmgs-data"
      ]
    }
  }
}

stdioの標準出力はMCPプロトコル専用とする。診断ログは標準出力へ書かない。

CodexとClaude Code

uv run --frozen pmgs agent-kit `
  --data-dir C:\path\to\pmgs-data `
  --output build\local-agent-kit `
  --python-executable C:\absolute\path\.venv\Scripts\python.exe `
  --client both

uv run --frozen pmgs install-agent-skill --client both

通常はpmgs setupが登録とskill導入まで行う。agent-kitは設定を先にレビューしたい場合に、Codex用TOML、Claude Code用JSON、共通skill、登録commandを新しい出力directoryへ生成する。既存directoryは上書きしない。

install-agent-skillは同一内容なら冪等で、内容の異なる同名skillを上書きしない。CodexとClaude Codeの設定形式は別々に保ち、照会手順だけを共通skillとして配布する。

Windowsの一括導入、設定scope、更新、削除はローカルAIエージェント導入ガイドを参照する。

検証

合成fixtureでは、Python API、JSON Schema、CLIの終了コード、MCP tool列挙、構造化応答、入力エラー、実際のstdioクライアント接続、timeout時の子プロセス終了、setup lock解放、agent kit、skill導入をpytestで検査する。

実データでは、FI、Fターム、IPC 8U、IPC旧版、関連PDFページ、日本語部分語検索、正本ファイルの照会前後ハッシュを検査する。