ontology-mapper

オントロジーマッパー

目標

実世界の材料科学に関する記述を、標準化されたオントロジー注釈に変換します。「FCC 銅」のような用語や、{"material": "iron", "structure": "BCC", "lattice_a": 2.87}のような構造化データを入力すると、登録済みの任意のオントロジーに対応するクラスとプロパティを出力します。

要件

• Python 3.10 以降
• 外部依存関係なし（Python 標準ライブラリのみ）
• ontology-explorer のサマリー JSON と ontology_registry.json が必要です
• オントロジーごとのマッピング設定ファイル（<name>_mappings.json）。オントロジー固有の同義語とラベルを指定します

収集する入力情報

入力	説明	例
オントロジー	レジストリに登録されたオントロジー名	cmso、asmo
用語	自然言語による材料概念	"unit cell"、"FCC,copper,lattice"
結晶系	7 つの結晶系のいずれか	cubic、hexagonal
ブラベー格子	格子の種類（記号または一般的な名称）	FCC、cF、BCC
空間群	空間群番号（1～230）	225
格子定数	オングストローム単位の a、b、c、および度単位の alpha、beta、gamma	a=3.615
サンプルの説明	材料のプロパティを含む JSON 辞書	{"material":"copper","structure":"FCC"}

判断ガイド

What do you need to map?
├── A concept or term to find its ontology class
│   └── concept_mapper.py --ontology <name> --term "<term>"
├── Crystal structure parameters to ontology terms
│   └── crystal_mapper.py --ontology <name> --bravais <type> --space-group <N> --a <val>
├── A full sample description to ontology annotations
│   └── sample_annotator.py --ontology <name> --sample '<json>'
└── Multiple terms at once
    └── concept_mapper.py --ontology <name> --terms "term1,term2,term3"

オントロジーの対象範囲 — 結晶／サンプルの注釈付けは CMSO のみです。 crystal_mapper.py と sample_annotator.py は、結晶構造の語彙（Crystalline Material、 Crystal Structure、Unit Cell、Space Group、格子プロパティ）を出力します。この語彙は CMSO によって定義されています。ASMO はシミュレーション手法のオントロジーであり、結晶／サンプルのクラスは定義していません。 そのため、ASMO では概念マッピングの経路（DFT、NPT、timestep、PBE などの用語を実際の ASMO クラスに対応付ける concept_mapper.py）のみを使用してください。必要なクラスがサマリーにないオントロジーを指定して sample_annotator.py／crystal_mapper.py（例：--ontology asmo）を実行した場合、解決できない各用語は results.validation_warnings に警告として示され、無効な用語が黙って出力されるのではなく、 confidence: 0.0 が付与されます。

スクリプトの出力（JSON フィールド）

スクリプト	主な出力
scripts/concept_mapper.py	results.matches、results.unmatched、results.suggestions
scripts/crystal_mapper.py	results.ontology_classes、results.ontology_properties、results.effective_system、results.bravais_lattice、results.validation_warnings
scripts/sample_annotator.py	results.annotations、results.sample_type、results.material_type、results.unmapped_fields、results.suggested_properties、results.validation_warnings

ワークフロー

1. ユーザーが自然言語の用語を提示した場合は、concept_mapper.py を使用して一致するオントロジークラスを検索します。
2. ユーザーが結晶構造のパラメーターを説明した場合は、crystal_mapper.py を使用してマッピングし、制約を検証します。
3. サンプルの説明全体がある場合は、sample_annotator.py を使用してオントロジー注釈をすべて生成します。
4. 検証警告（例：結晶系に対する格子定数の不一致）を確認します。
5. unmapped_fields と suggested_properties を確認し、情報が不足していないか確認します。

会話形式のワークフロー例

User: I'm setting up an MD simulation of BCC iron with lattice parameter 2.87 angstroms.
      What CMSO terms should I use?

Agent: Let me map your iron sample to CMSO ontology terms.

[Runs: sample_annotator.py --ontology cmso --sample '{"material":"iron","structure":"BCC","lattice_a":2.87,"space_group":229}' --json]

Your BCC iron simulation maps to these CMSO annotations:

- **Sample**: Atomic Scale Sample (subclass of Computational Sample)
- **Material**: Crystalline Material
- **Unit Cell**: Bravais lattice = "cI" (body-centered cubic)
- **Space Group**: number = 229 (Im-3m)
- **Lattice**: a = 2.87 Å
- **Element**: Fe

Suggested additions:
- Number of atoms in the simulation cell
- Simulation cell vectors and angles

CLI の例

# Map a single concept
python3 skills/ontology/ontology-mapper/scripts/concept_mapper.py \
  --ontology cmso --term "space group" --json

# Map multiple terms
python3 skills/ontology/ontology-mapper/scripts/concept_mapper.py \
  --ontology cmso --terms "FCC,copper,lattice constant" --json

# Map crystal parameters (with ontology-specific labels)
python3 skills/ontology/ontology-mapper/scripts/crystal_mapper.py \
  --ontology cmso --bravais FCC --space-group 225 --a 3.615 --json

# Map crystal parameters (generic labels, no ontology specified)
python3 skills/ontology/ontology-mapper/scripts/crystal_mapper.py \
  --bravais FCC --space-group 225 --a 3.615 --json

# Annotate a full sample
python3 skills/ontology/ontology-mapper/scripts/sample_annotator.py \
  --ontology cmso \
  --sample '{"material":"copper","structure":"FCC","space_group":225,"lattice_a":3.615}' \
  --json

新しいオントロジーの追加

新しいオントロジーをサポートするには、references/ に <name>_mappings.json を作成します。

{
  "ontology": "myonto",
  "synonyms": { "simulation method": "Simulation Method", ... },
  "property_synonyms": { "timestep": "has timestep", ... },
  "material_type_rules": { "keyword_rules": [...], "default": "Material" },
  "sample_schema": { "sample_class": "Simulation", ... },
  "crystal_output": { "base_classes": [...], "property_map": {...} },
  "annotation_routing": { "unit_cell_indicators": [...], ... }
}

次に、ontology_registry.json 内のオントロジーのエントリに "mappings_file": "myonto_mappings.json" を追加します。コードの変更は不要です。

sample_schema、crystal_output、material_type_rules、annotation_routing の各ブロックは、そこに記載するすべてのクラス／プロパティが、そのオントロジーのサマリーに実際に存在する場合に限り含めてください。 sample_annotator.py は、出力された用語を読み込んだサマリーと照合し、定義されていないものにフラグを付けます（results.validation_warnings、confidence: 0.0）。 たとえば、asmo_mappings.json に含まれているのは、意図的に synonyms と property_synonyms のみです。ASMO はシミュレーション手法のオントロジーであり、結晶／サンプルの語彙がないためです。その概念用語（DFT、NPT、timestep、PBE）はすべて解決されますが、結晶／サンプルの設定を出力すると、解決できない用語が生成されます。

エラー処理

エラー	原因	解決方法
space_group must be between 1 and 230	空間群番号が無効です	有効な空間群番号を使用してください
a must be positive	格子定数が正の値ではありません	オングストローム単位で正の値を指定してください
Unrecognized Bravais lattice '<x>'	ブラベー格子の記号／名称が認識対象に含まれていません	一般的な名称（FCC、BCC、HCP）またはピアソン記号（cF、cI、hP、...）を使用してください
Term exceeds maximum length of 200 characters	--term／--terms のエントリが長すぎます	用語を短くしてください
Too many terms (max 100)	指定された用語が100件を超えています	より小さなバッチに分けてください
Sample must be a non-empty dict	サンプルデータが空、または指定されていません	有効なJSONサンプル辞書を指定してください
Sample has too many keys (max 100)	サンプル辞書が大きすぎます	サンプルキーの数を減らしてください
検証警告（格子）	格子定数が結晶系と一致していません	立方晶ではa=b=cであることなどを確認してください
results.validation_warnings（用語）	出力されたクラス／プロパティが、選択したオントロジーで定義されていません（例：ASMOでの結晶用語）	結晶／サンプルの注釈にはCMSOを使用し、ASMOは概念のマッピングにのみ使用してください

解釈の指針

• 信頼度スコア：1.0 = ラベルの完全一致、0.9 = 同義語テーブルとの一致、0.7 = 部分文字列の一致、0.5 = 説明との一致。注：オントロジーごとの同義語テーブルはラベルの完全一致より先に参照されます。そのため、同義語キーとクラスラベルの両方に該当する用語（例：space group、unit cell、atom）は、クラスラベルと完全に一致していても、同義語との一致として0.9で報告されます。ただし、一致したクラスとIRIは正しいままです。
• sample_annotator.py の検証警告：出力されたすべてのクラス／プロパティが、読み込まれたオントロジーサマリーと照合されます。そのオントロジーで定義されていない用語には results.validation_warnings でフラグが付けられます（対応する注釈には confidence: 0.0 を含む validation_warning フィールドが付与されます）。これは、選択したオントロジーでは結晶／サンプル用語をIRIに解決できないことを注釈ツールが示す方法です（例：結晶サンプルに対して --ontology asmo を実行する場合。以下を参照）。
• 検証警告：潜在的な間違い（例：立方晶に対してa!=bを指定）を示します。エラーではなく警告です。マッピングは引き続き実行されます。
• 未マッピングのフィールド：注釈ツールが認識しない入力キーです。手動でのマッピングが必要な場合があります。
• 推奨プロパティ：注釈をより完全にするために追加できるオントロジープロパティです。

検証チェックリスト

• results.validation_warnings が空であること（または各項目について説明があること）を確認しました。空でないリストは、出力されたクラス／プロパティが選択したオントロジーで定義されておらず、confidence: 0.0 が設定されたことを意味します。そのような用語を有効なアノテーションとして報告しないでください。
• 各概念マッチについて match_type と confidence を記録し、選択した用語がその信頼度の段階で許容できることを確認しました（1.0 は完全一致、0.9 は同義語、0.7 は部分文字列、0.5 は説明文）。substring_* または description_class によるマッチでは、マッチしたクラスが実際に意図した概念であり、偶然文字列がヒットしたものではないことを確認しました。
• 結晶マッピングでは、results.effective_system と results.bravais_lattice（解決された Pearson 記号。例：cF／cI）を記録し、入力した Bravais 格子／空間群／系が互いに整合していることを確認しました（validation_warnings に「空間群 N は X を意味しますが、Y が指定されています」という警告がないこと）。
• effective_system に照らして格子パラメーターの制約を確認しました。「Cubic requires a=b」や角度 90° の違反などの警告がないことを確認するか、各警告について明示的に妥当性を説明しました（警告は参考情報であり、マッピングは引き続き実行されます）。
• results.unmatched（概念）と results.unmapped_fields（サンプル）を一覧にし、重要な項目が気付かないうちに欠落していないことを確認しました。解決されるべき未マッチ用語については、出力された class_browser.py の候補を実行しました。
• results.suggested_properties を確認し、不足しているフィールド（elements、space_group、lattice_a など）のうち、意図的に省略するものと、アノテーションを完成とみなす前に追加すべきものを記録しました。

よくある落とし穴と誤った正当化

ありがちな近道	それが誤りである理由／すべきこと
「スクリプトがアノテーションを出力したので、サンプルは正しくアノテーションされています。」	出力は検証ではありません。sample_annotator.py は用語を出力した後、その用語がオントロジーに存在しない場合は validation_warning／confidence: 0.0 を付けてフラグを立てます。出力を信頼する前に、必ず results.validation_warnings を確認してください。
「この結晶サンプルには --ontology asmo を指定してアノテーションします。」	ASMO はシミュレーション手法のオントロジーであり、結晶／サンプルに関する語彙はありません。結晶に関する用語はすべて confidence: 0.0 になります。結晶／サンプルのアノテーションには CMSO を使用し、ASMO は概念マッピングの経路でのみ使用してください。
「用語がマッチしたので、マッピングの信頼度は高いです。」	マッチは、信頼度 0.7 の部分文字列や 0.5 の説明文に対するもの（例：無関係なラベル内の偶然の部分文字列）である場合があります。confidence／match_type を確認し、完全一致または同義語マッチ未満のものは事実ではなく、検証すべき候補として扱ってください。
「space group がクラスラベルにマッチしたので、完全一致の 1.0 です。」	オントロジーごとの同義語テーブルは、完全なラベルとのマッチングより先に参照されます。そのため、同義語キーの用語（space group、unit cell、atom）はクラスラベルと一致する場合でも、同義語マッチの 0.9 として報告されます。マッチしたクラス／IRI は正しいため、信頼度を「修正」しないでください。
「空間群は有効（1～230）なので、結晶系も問題ありません。」	有効な空間群でも、明示的に指定された --system または Bravais 格子と矛盾することがあります。effective_system を確認し、validation_warnings に「空間群 N は X を意味しますが、Y が指定されています」という項目がないか確認してください。
「サンプルに structure フィールドがあるので、Bravais 格子は解決済みです。」	サンプルの経路では strict_bravais=False です。フリーテキストの構造（例：rocksalt、perovskite）はマッピングされずにそのまま渡され、警告が出て、bravais_lattice は null のままになります。results.bravais_lattice が期待する Pearson 記号であることを確認するか、FCC／BCC／HCP／Pearson 記号を指定してください。

セキュリティ

入力検証

• --ontology は、ontology_registry.json に登録されたオントロジー名（固定の許可リスト）に照らして検証されます
• --term と --terms は長さが制限されており、前処理済みの同義語テーブルに対する部分文字列マッチングにのみ使用されます（コードに埋め込まれることはありません）
• --bravais は、認識されている格子型シンボルの固定セットに照らして検証されます
• --space-group は、1〜230の整数として検証されます
• 格子定数（--a、--b、--c、--alpha、--beta、--gamma）は、有限の正の数値として検証されます
• --sample の JSON は json.loads() で解析され、空でない辞書として検証されます。キーと値の型もチェックされます

ファイルアクセス

• スクリプトは references/ ディレクトリにある前処理済みの JSON ファイル（ontology_registry.json、*_mappings.json、*_summary.json、crystal_systems.json、element_data.json）を読み取ります（すべて読み取り専用です）
• スクリプトがファイルシステムに書き込むことはありません。出力はすべて標準出力に送られます
• ネットワークアクセスは必要ありません

ツールの制限

• Read：スクリプトのソース、参照ファイル、オントロジーデータの確認に使用します
• Grep：参照ファイル内のマッピングパターンやオントロジー用語の検索に使用します
• Glob：参照ファイルやオントロジーデータの場所の特定に使用します
• 特筆すべき点として、このスキルには Bash や Write へのアクセス権がありません。そのため、すべてのスキルの中で攻撃対象領域が最も小さくなっています

安全対策

• eval()、exec()、動的なコード生成は使用しません
• いかなる種類のサブプロセス呼び出しもありません。すべてのロジックはエージェントが呼び出す Python スクリプト内で実行されます
• ファイルへの書き込みはありません。このスキルは完全に読み取り専用で、分析のみを行います
• ツールの対象範囲が最小限（Read、Grep、Glob のみ）であるため、エージェントは任意のコマンドを実行したり、ファイルシステムを変更したりできません

制限事項

• 概念マッピングでは文字列マッチングとオントロジーごとの同義語テーブルを使用します。任意の自然言語を理解するわけではありません
• 結晶系の検証では基本的な制約のみを確認します（すべての結晶学的規則を確認するわけではありません）
• 元素リゾルバーは一般的な元素名と元素記号を認識しますが、珍しい綴りは認識できない場合があります
• ブラベー格子の別名は一般的な用法（FCC、BCC、HCP）をカバーしますが、結晶学的表記のすべてのバリエーションを網羅するわけではありません

参考資料

• マッピングパターン — 一般的なマッピング例
• 結晶系 — 結晶系の定義とブラベー格子
• 元素データ — 周期表データ
• CMSO マッピング — CMSO 固有の同義語テーブルとアノテーション設定
• CMSO ガイド — CMSO オントロジーの概要
• オントロジーエクスプローラー — 関連するスキル。概念が見つからない場合は、scripts/class_browser.py --ontology <name> --search <term> でクラスを閲覧できます

バージョン履歴

日付	バージョン	変更内容
2026-06-23	1.2	出力される用語を読み込んだオントロジーに照らして検証するように変更（ASMO の結晶／サンプル用語が、黙って出力されずに警告されるようになりました）。ASMO は概念マッピングのみであることを記載。同義語と完全一致の信頼度の優先順位を明確化。class_browser の提案を自己完結型に変更。入力検証を強化（term／sample のサイズ上限、Bravais の許可リスト）
2026-02-25	1.1	複数のオントロジーへの対応に向けてリファクタリングし、CMSO 固有の知識を設定ファイルに分離
2026-02-25	1.0	CMSO マッピングに対応して初回リリース