ontology-explorer

オントロジーエクスプローラー

目標

エージェントが、詳細な OWL/XML ファイルを直接読み込まずに、材料科学オントロジーの構造を理解し、探索して、クエリを実行できるようにします。前処理済みの JSON サマリーを通じて、クラス階層、プロパティ定義、ドメインとレンジの関係にすばやくアクセスできます。

要件

• Python 3.10+
• 外部依存関係なし（Python 標準ライブラリのみ）
• owl_parser.py と ontology_summarizer.py でリモート OWL ファイルを取得する場合に限り、インターネットアクセスが必要です

収集する入力

入力	説明	例
オントロジー名	クエリ対象の登録済みオントロジー	cmso
クラス名	調査する特定のクラス	Material、UnitCell
プロパティ名	検索する特定のプロパティ	hasMaterial、hasSpaceGroupNumber
検索語	ラベルを対象に検索するキーワード	crystal、lattice
OWL ソース	OWL/XML ファイルのパスまたは URL（解析／要約用）	https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl

判断の指針

What do you need?
├── Understand overall ontology structure
│   └── class_browser.py --ontology cmso --list-roots
├── Inspect a specific class
│   └── class_browser.py --ontology cmso --class <name>
├── Find properties for a class
│   └── property_lookup.py --ontology cmso --class <name>
├── Look up a specific property
│   └── property_lookup.py --ontology cmso --property <name>
├── Search for a concept
│   ├── class_browser.py --ontology cmso --search <term>
│   └── property_lookup.py --ontology cmso --search <term>
├── Parse a new/updated OWL file
│   └── owl_parser.py --source <path-or-url>
└── Generate/refresh a summary JSON
    └── ontology_summarizer.py --source <url> --output <path>

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

スクリプト	主な出力
scripts/owl_parser.py	results.metadata、results.classes、results.object_properties、results.data_properties、results.class_hierarchy
scripts/ontology_summarizer.py	results.output_file、results.statistics
scripts/class_browser.py	results.class_info、results.subtree、results.properties、results.path_to_root、results.roots、results.search_results
scripts/property_lookup.py	results.property_info、results.class_properties、results.search_results

ワークフロー

1. ユーザーが使用しているオントロジーを特定します（デフォルト：CMSO）。
2. class_browser.py --list-roots を使って、最上位の概念を確認します。
3. class_browser.py --class <name> で特定のクラスを掘り下げ、階層、子クラス、適用可能なプロパティを確認します。
4. property_lookup.py --property <name> で個々のプロパティを検索します。
5. ユーザーが概念に言及していてもオントロジー名を指定していない場合は、--search を使って一致するクラスまたはプロパティを探します。
6. 新しいオントロジーまたは更新されたオントロジーの場合は、owl_parser.py を実行して生の OWL を解析し、その後 ontology_summarizer.py を実行して要約 JSON を生成します。

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

User: I have an FCC copper simulation. What CMSO classes should I use to describe it?

Agent: Let me explore the CMSO ontology to find the relevant classes. I'll run
a few targeted searches and property lookups (the answer below is synthesized
from several commands, per the Workflow section).

[Runs: class_browser.py --ontology cmso --search "crystal" --json]
  → Crystalline Material, Crystal Structure (among others)
[Runs: class_browser.py --ontology cmso --search "sample" --json]
  → Computational Sample, Atomic Scale Sample
[Runs: class_browser.py --ontology cmso --search "unit cell" --json]
  → Unit Cell
[Runs: class_browser.py --ontology cmso --search "space group" --json]
  → Space Group
[Runs: class_browser.py --ontology cmso --search "element" --json]
  → Chemical Element
[Runs: property_lookup.py --ontology cmso --property "has material" --json]
  → domain Computational Sample → range Material
[Runs: property_lookup.py --ontology cmso --property "has structure" --json]
  → domain Material → range Structure
[Runs: property_lookup.py --ontology cmso --property "has unit cell" --json]
  → domain Crystal Structure → range Unit Cell

For an FCC copper simulation, the relevant CMSO classes are:

- **Computational Sample** → **Atomic Scale Sample**: your simulation is an atomic-scale sample
- **Material** → **Crystalline Material**: copper is crystalline
- **Crystal Structure**: describes the FCC arrangement
- **Unit Cell**: the repeating FCC unit cell (a=b=c=3.615 Å, α=β=γ=90°)
- **Space Group**: FCC copper is space group 225 (Fm-3m)
- **Chemical Element**: Cu

The key relationship chain (from the property domains/ranges above):
  Computational Sample → has material → Material → has structure → Structure
  → (Crystal Structure) → has unit cell → Unit Cell

Shall I look up the specific properties for any of these classes?

CLI の例

# List root classes in CMSO
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --list-roots --json

# Inspect the Material class hierarchy
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --class Material --json

# Search for crystal-related classes
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --search crystal --json

# Find all properties for UnitCell
python3 skills/ontology/ontology-explorer/scripts/property_lookup.py \
  --ontology cmso --class UnitCell --json

# Look up a specific property
python3 skills/ontology/ontology-explorer/scripts/property_lookup.py \
  --ontology cmso --property "has space group" --json

# Parse a remote OWL file
python3 skills/ontology/ontology-explorer/scripts/owl_parser.py \
  --source https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl --json

# Generate a summary JSON from an OWL file
python3 skills/ontology/ontology-explorer/scripts/ontology_summarizer.py \
  --source https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl \
  --output summary.json --json

エラー処理

エラー	原因	解決方法
Ontology 'X' not in registry	オントロジー名が登録されていません	使用可能な名前を references/ontology_registry.json で確認します
Class 'X' not found	クラスラベルがどのエントリーにも一致しません	類似する名前を --search で探すか、--list-roots で使用可能なクラスを確認します
Property 'X' not found	プロパティラベルが一致しません	類似するプロパティを --search で探します
Cannot parse OWL source	XML が無効であるか、URL に到達できません	ファイルパスまたは URL を確認し、ファイルが有効な OWL/XML であることを確かめます
Summary file not found	要約 JSON が生成されていません	先に ontology_summarizer.py を実行します

解釈の指針

• クラス階層：ルートクラスは最も広範な概念であり、リーフクラスは最も具体的な概念です。クラスはすべての祖先からプロパティを継承します。
• オブジェクトプロパティ：クラス同士の関係を示します（ドメイン → レンジ）。ドメインが UnitCell、レンジが Basis のプロパティは、単位胞が基底を持つことを意味します。
• データプロパティ：クラスが持つリテラル値を示します。ドメインが ChemicalElement、レンジが xsd:string のプロパティは、元素が文字列型の属性を持つことを意味します。
• 複数クラスのドメイン：プロパティが複数のクラスに適用される場合があります。その場合、ドメインはクラスをパイプでつないで表示されます（例：A | B）。（同梱の CMSO／ASMO サマリーには、現在、複数クラスのドメインを持つプロパティはありません。）
• 検索の関連度：1.0 = ラベルが一致、0.5 = 説明のみ一致。

検証チェックリスト

クラス、プロパティ、または関係を事実として提示する前に、次の事項を確認して記録してください。

• class_browser.py --class <name>（または property_lookup.py）を使って対象を解決し、results.class_info.label / results.property_info.name で返された正確な正式な label を記録しました。エージェントが入力した名前を引用せず、ツールが解決したラベルを引用してください（例：UnitCell → Unit Cell）。
• 記載した関係の連鎖ごとに、クラス名からリンクを推測せず、property_lookup.py --property <name> の呼び出しで実際に返された domain と range（results.property_info.domain と .range に記録）を引用しました。
• プロパティの domain にパイプ（A | B）が含まれる場合、和集合として報告し（列挙された各クラスに適用）、対象のクラスが正規化されたメンバーのいずれかに一致することを確認しました。単一クラスの domain だと暗黙に決めつけていません。
• --search の結果について、各一致の relevance を記録し、それがラベル一致（1.0）か説明文のみの一致（0.5）かを明記しました。関連度0.5の説明文の一致を、確認済みの用語一致として提示していません。
• オントロジーをレジストリキー（cmso または asmo）で特定し、references/ontology_registry.json に登録されていることを確認しました。未登録のオントロジーを検索したり、CMSO と ASMO の用語を混同したりしていません。
• 生成または更新された要約を根拠にする場合、その要約の metadata.source_url と metadata.generated_at、および statistics（num_classes、num_object_properties、num_data_properties）を記録し、特定の OWL ソースまで追跡できるようにしました。
• 親クラス、説明、または domain/range がない場合は、データの欠落として扱いました（「そのような関係は存在しない」とは扱っていません）。パーサーが抽出するのは単純な rdfs:subClassOf と宣言された domain/range のみで、推論は行いません。

よくある落とし穴とその正当化

つい選びたくなる近道	それが間違っている理由／対処方法
「クラス名 UnitCell では何も返ってこなかったので、この用語は存在しません。」	ラベルには空白が含まれます（Unit Cell）。ツールは完全一致 → 大文字小文字を区別しない一致 → 空白を正規化した一致の順に解決します。直接入力した名前で見つからない場合は --search を実行し、入力した文字列ではなく、ツールが返した正式な label を使用してください。
「この2つのクラスには明らかに関連があるので、リンクを記載します。」	関係が存在するのは、オブジェクトプロパティで宣言されている場合に限られます。property_lookup.py --property <name> で確認し、記録された domain → range を引用してください。クラス名だけからトリプルを推測してはいけません。
「スクリプトが実行されて結果も表示されたので、回答は完全です。」	実行成功は完全性を意味しません。parent、description、または domain/range が欠けている場合、OWL にその注釈がありません。パーサーは推論を行わず、複雑な OWL 制約も無視します。欠けている情報を明記してください。
「--search crystal で一致したので、これが正しい用語です。」	一致の関連度が0.5（説明文のみ）で、ラベル一致ではない場合があります。relevance フィールドを確認し、関連度1.0のラベル一致を優先してください。関連度0.5の結果は、正式な用語としてではなく「説明文に記載」として報告してください。
「プロパティの domain クラスは1つです。」	domain は和集合（`A
「どの OCDO オントロジーでも使える／CMSO と ASMO は互換性がある。」	登録されているのは cmso と asmo のみです。CDCO/PODO/PLDO/LDO は計画中であり、利用できません。正しいレジストリキーを選び、オントロジー間で用語を混同しないでください。
「この http:// の OWL URL をパーサーに指定します。」	owl_parser.py/ontology_summarizer.py は仕様上、https:// 以外の URL を拒否します。https:// のソースまたはローカルファイルパスを使用してください。

セキュリティ

入力の検証

• --ontology は、ontology_registry.json に登録されているオントロジー名（固定の許可リスト）に照らして検証されます
• --class と --property の名前は、インジェクションを防止するため、安全な文字パターンに照らして検証されます
• --search の検索語には長さの上限があり、前処理済みのラベルとの部分文字列照合にのみ使用されます（クエリやコードに埋め込まれることはありません）
• owl_parser.py の --source には、ファイルパスまたは URL を指定できます。URL は https:// スキームのみを許可するよう検証されます

ファイルアクセス

• class_browser.py と property_lookup.py は、references/ ディレクトリの前処理済み JSON サマリーファイルを読み取ります（読み取り専用）
• owl_parser.py は、ローカルパスまたは HTTPS URL から単一の OWL/XML ファイルを読み取ります。リモートからの取得には 30 秒のタイムアウトが設定されています
• ontology_summarizer.py は、--output で指定されたパスに単一の JSON サマリーファイルを書き込みます
• 既存のファイルを変更または削除するスクリプトはありません

ツールの制限

• Read：スクリプトのソース、参照ファイル、オントロジーのサマリーの確認に使用します
• Bash：4 つの Python スクリプト（owl_parser.py、ontology_summarizer.py、class_browser.py、property_lookup.py）を、明示的な引数リストで実行するために使用します。URL の取得は、タイムアウト制限を設けた Python スクリプト内で行われます

安全対策

• eval()、exec()、動的なコード生成は使用しません
• すべてのサブプロセス呼び出しで明示的な引数リストを使用します（shell=True は使用しません）
• OWL/XML の解析には Python の xml.etree.ElementTree を使用します。これはデフォルトで外部エンティティを解決しないため、XXE 攻撃のリスクを軽減します
• 不正利用を防ぐため、リモート URL の取得は HTTPS に限定し、30 秒のタイムアウトを設定しています
• 出力の氾濫を防ぐため、検索結果の件数に上限を設けています

制限事項

• OWL/XML 形式のみをサポートします（Turtle、JSON-LD、N-Triples はサポートしません）
• OWL の推論や導出はサポートしません（推移閉包の計算などは行いません）
• クラス階層の抽出では、単純な rdfs:subClassOf のみを扱います（複雑な OWL 制約は扱いません）
• rdfs:comment、skos:definition、IAO アノテーションのいずれも持たないクラスには、説明がない場合があります
• URL の取得にはインターネットアクセスが必要で、タイムアウトする場合があります（上限 30 秒）

参考資料

• OWL/RDF 入門 — OWL の概念に関する簡単な入門
• CMSO ガイド — CMSO オントロジーに関する解説ガイド
• オントロジーレジストリ — 登録済みオントロジーとそのメタデータ
• CMSO サマリー — 前処理済みの CMSO 構造
• CMSO ドキュメント — CMSO の公式ドキュメント
• CMSO リポジトリ — OWL ソースファイルと開発情報

バージョン履歴

日付	バージョン	変更内容
2026-06-24	1.2.2	検証チェックリスト（根拠に基づき、正規ラベルの解決、記録されたドメイン／レンジ、和集合ドメイン、検索の関連性、レジストリキー、サマリーの出所に関連付けたもの）と、よくある落とし穴とその正当化の表を追加しました。
2026-06-23	1.2.0	property_lookup の --class が正規ラベルを解決するよう修正しました（UnitCell のようなスペースを含まない名前が一致するようになりました）。クラス／プロパティのドメイン照合をツール間で統一し、文書化されたセキュリティ制御（安全な文字パターン、長さ上限、検索結果の件数上限、HTTPS のみの URL）を適用し、和集合ドメインのドキュメント例と eval アサーションを修正し、説明の対象を CMSO／ASMO に限定しました。
2026-02-25	1.0	CMSO サポートを含む初回リリース