@bgicli/bgicli 2.1.1 → 2.2.1

package/data/skills/ontology-explorer/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: ontology-explorer
+description: >
+  Parse, navigate, and query materials science ontology structure (classes, properties, hierarchy).
+  Use when exploring an ontology like CMSO, understanding class relationships, finding properties
+  for a given class, or searching for ontology terms related to a materials science concept.
+  Supports OWL/XML format from the OCDO ecosystem (CMSO, ASMO, CDCO, PODO, PLDO, LDO).
+allowed-tools: Read, Bash
+---
+
+# Ontology Explorer
+
+## Goal
+
+Enable an agent to understand, navigate, and query the structure of materials science ontologies without loading verbose OWL/XML files directly. Provides fast access to class hierarchies, property definitions, and domain-range relationships through pre-processed JSON summaries.
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies (Python standard library only)
+- Internet access required only for `owl_parser.py` and `ontology_summarizer.py` when fetching remote OWL files
+
+## Inputs to Gather
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Ontology name | Registered ontology to query | `cmso` |
+| Class name | A specific class to inspect | `Material`, `UnitCell` |
+| Property name | A specific property to look up | `hasMaterial`, `hasSpaceGroupNumber` |
+| Search term | Keyword to search across labels | `crystal`, `lattice` |
+| OWL source | Path or URL to an OWL/XML file (for parsing/summarizing) | `https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl` |
+
+## Decision Guidance
+
+```
+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>
+```
+
+## Script Outputs (JSON Fields)
+
+| Script | Key Outputs |
+|--------|-------------|
+| `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` |
+
+## Workflow
+
+1. Identify which ontology the user is working with (default: CMSO).
+2. Use `class_browser.py --list-roots` to see the top-level concepts.
+3. Drill into specific classes with `class_browser.py --class <name>` to see hierarchy, children, and applicable properties.
+4. Look up individual properties with `property_lookup.py --property <name>`.
+5. If the user mentions a concept but not its ontology name, use `--search` to find matching classes or properties.
+6. For a new or updated ontology, run `owl_parser.py` to parse the raw OWL, then `ontology_summarizer.py` to generate a summary JSON.
+
+## Conversational Workflow Example
+
+```
+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.
+
+[Runs: class_browser.py --ontology cmso --search "crystal" --json]
+
+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 relationships:
+  AtomicScaleSample → hasMaterial → CrystallineMaterial → hasStructure → CrystalStructure → hasUnitCell → UnitCell
+
+Shall I look up the specific properties for any of these classes?
+```
+
+## CLI Examples
+
+```bash
+# 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
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `Ontology 'X' not in registry` | Ontology name not registered | Check `references/ontology_registry.json` for available names |
+| `Class 'X' not found` | Class label doesn't match any entry | Use `--search` to find similar names, or `--list-roots` to see available classes |
+| `Property 'X' not found` | Property label doesn't match | Use `--search` to find similar properties |
+| `Cannot parse OWL source` | Invalid XML or unreachable URL | Check file path or URL; ensure the file is valid OWL/XML |
+| `Summary file not found` | Summary JSON hasn't been generated | Run `ontology_summarizer.py` first |
+
+## Interpretation Guidance
+
+- **Class hierarchy**: root classes are the broadest concepts; leaf classes are the most specific. A class inherits all properties from its ancestors.
+- **Object properties**: show how classes relate to each other (domain → range). A property with domain `UnitCell` and range `Basis` means a unit cell *has a* basis.
+- **Data properties**: show what literal values a class carries. A property with domain `ChemicalElement` and range `xsd:string` means an element has a string-valued attribute.
+- **Union domains**: some properties apply to multiple classes (e.g., `hasVector` applies to both `SimulationCell` and `UnitCell`), shown as `SimulationCell | UnitCell`.
+- **Search relevance**: 1.0 = label match, 0.5 = description match only.
+
+## Limitations
+
+- Only supports OWL/XML format (not Turtle, JSON-LD, or N-Triples)
+- Does not support OWL reasoning or inference (e.g., does not compute transitive closures)
+- Class hierarchy extraction handles simple `rdfs:subClassOf` only (not complex OWL restrictions)
+- Descriptions may be missing for classes that lack `rdfs:comment`, `skos:definition`, or IAO annotations
+- URL fetching requires internet access and may time out (30-second limit)
+
+## References
+
+- [OWL/RDF Primer](references/owl_primer.md) — brief introduction to OWL concepts
+- [CMSO Guide](references/cmso_guide.md) — narrative guide to the CMSO ontology
+- [Ontology Registry](references/ontology_registry.json) — registered ontologies and their metadata
+- [CMSO Summary](references/cmso_summary.json) — pre-processed CMSO structure
+- [CMSO Documentation](https://ocdo.github.io/cmso/) — official CMSO docs
+- [CMSO Repository](https://github.com/OCDO/cmso) — source OWL file and development
+
+## Version History
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-02-25 | 1.0 | Initial release with CMSO support |

package/data/skills/ontology-mapper/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ontology-mapper
+description: >
+  Map materials science terms, crystal structures, and sample descriptions to ontology classes
+  and properties. Supports any ontology registered in ontology_registry.json. Use when translating
+  natural-language material descriptions to ontology terms, annotating simulation inputs with
+  ontology metadata, or mapping crystal parameters (space group, Bravais lattice, lattice constants)
+  to standardized ontology representations.
+allowed-tools: Read, Bash
+---
+
+# Ontology Mapper
+
+## Goal
+
+Translate real-world materials science descriptions into standardized ontology annotations. Given terms like "FCC copper" or structured data like `{"material": "iron", "structure": "BCC", "lattice_a": 2.87}`, produce the corresponding ontology classes and properties for any registered ontology.
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies (Python standard library only)
+- Requires ontology-explorer's summary JSON and `ontology_registry.json`
+- Per-ontology mapping config (`<name>_mappings.json`) for ontology-specific synonyms and labels
+
+## Inputs to Gather
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Ontology | Ontology name from registry | `cmso`, `asmo` |
+| Term(s) | Natural-language materials concept(s) | `"unit cell"`, `"FCC,copper,lattice"` |
+| Crystal system | One of the 7 crystal systems | `cubic`, `hexagonal` |
+| Bravais lattice | Lattice type (symbol or common name) | `FCC`, `cF`, `BCC` |
+| Space group | Space group number (1-230) | `225` |
+| Lattice parameters | a, b, c in angstroms; alpha, beta, gamma in degrees | `a=3.615` |
+| Sample description | JSON dict with material properties | `{"material":"copper","structure":"FCC"}` |
+
+## Decision Guidance
+
+```
+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"
+```
+
+## Script Outputs (JSON Fields)
+
+| Script | Key Outputs |
+|--------|-------------|
+| `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` |
+
+## Workflow
+
+1. If the user provides natural-language terms, use `concept_mapper.py` to find matching ontology classes.
+2. If the user describes crystal structure parameters, use `crystal_mapper.py` to map them and validate constraints.
+3. For a complete sample description, use `sample_annotator.py` to produce full ontology annotations.
+4. Review any validation warnings (e.g., lattice parameter mismatches for the crystal system).
+5. Check `unmapped_fields` and `suggested_properties` for completeness.
+
+## Conversational Workflow Example
+
+```
+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 Examples
+
+```bash
+# 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
+```
+
+## Adding a New Ontology
+
+To support a new ontology (e.g., ASMO), create a `<name>_mappings.json` in `references/`:
+
+```json
+{
+  "ontology": "asmo",
+  "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": [...], ... }
+}
+```
+
+Then add `"mappings_file": "asmo_mappings.json"` to the ontology's entry in `ontology_registry.json`. No code changes needed.
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `space_group must be between 1 and 230` | Invalid space group number | Use a valid space group number |
+| `a must be positive` | Non-positive lattice parameter | Provide positive values in angstroms |
+| `Sample must be a non-empty dict` | Empty or missing sample data | Provide a valid JSON sample dict |
+| Validation warnings | Lattice parameters inconsistent with crystal system | Check that a=b=c for cubic, etc. |
+
+## Interpretation Guidance
+
+- **Confidence scores**: 1.0 = exact match, 0.9 = synonym match, 0.7 = substring match, 0.5 = description match
+- **Validation warnings**: indicate potential mistakes (e.g., specifying a!=b for cubic). These are warnings, not errors — the mapping still proceeds.
+- **Unmapped fields**: input keys that the annotator doesn't recognize. These may need manual mapping.
+- **Suggested properties**: additional ontology properties that would make the annotation more complete.
+
+## Limitations
+
+- Concept mapping uses string matching and a per-ontology synonym table; it does not understand arbitrary natural language
+- Crystal system validation checks basic constraints only (not all crystallographic rules)
+- The element resolver recognizes common element names and symbols but may miss unusual spellings
+- Bravais lattice aliases cover common usage (FCC, BCC, HCP) but not all crystallographic notation variants
+
+## References
+
+- [Mapping Patterns](references/mapping_patterns.md) — common mapping examples
+- [Crystal Systems](references/crystal_systems.json) — crystal system definitions and Bravais lattices
+- [Element Data](references/element_data.json) — periodic table data
+- [CMSO Mappings](references/cmso_mappings.json) — CMSO-specific synonym tables and annotation config
+- [CMSO Guide](../ontology-explorer/references/cmso_guide.md) — CMSO ontology overview
+
+## Version History
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-02-25 | 1.1 | Refactored for multi-ontology support: externalized CMSO-specific knowledge to config |
+| 2026-02-25 | 1.0 | Initial release with CMSO mapping support |

package/data/skills/ontology-validator/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ontology-validator
+description: >
+  Validate material sample annotations and data structures against ontology constraints.
+  Use when checking if CMSO annotations are correct, verifying that required properties are
+  present, or validating that object property relationships have consistent domain and range.
+  Catches unknown classes, unknown properties, domain mismatches, and missing required fields.
+allowed-tools: Read, Bash
+---
+
+# Ontology Validator
+
+## Goal
+
+Validate that material sample annotations comply with ontology constraints: correct class names, valid properties, consistent domain/range relationships, and required fields present.
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies (Python standard library only)
+- Requires ontology-explorer's `cmso_summary.json` and `ontology_registry.json`
+
+## Inputs to Gather
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Annotation | JSON dict or list of annotation dicts | `{"class":"UnitCell","properties":{"has Bravais lattice":"cF"}}` |
+| Class name | Class to check completeness for | `Crystal Structure` |
+| Provided properties | Comma-separated property names | `"has unit cell,has space group"` |
+| Relationships | JSON array of subject-property-object triples | `[{"subject_class":"Material","property":"has structure","object_class":"Crystal Structure"}]` |
+
+## Decision Guidance
+
+```
+What do you need to validate?
+├── An annotation (classes and properties are correct)
+│   └── schema_checker.py --ontology cmso --annotation '<json>'
+├── Completeness of a class annotation
+│   └── completeness_checker.py --ontology cmso --class <name> --provided <props>
+└── Object property relationships
+    └── relationship_checker.py --ontology cmso --relationships '<json>'
+```
+
+## Script Outputs (JSON Fields)
+
+| Script | Key Outputs |
+|--------|-------------|
+| `scripts/schema_checker.py` | `results.valid`, `results.errors`, `results.warnings`, `results.class_valid`, `results.properties_valid` |
+| `scripts/completeness_checker.py` | `results.completeness_score`, `results.required_missing`, `results.recommended_missing`, `results.optional_missing`, `results.unrecognized` |
+| `scripts/relationship_checker.py` | `results.valid`, `results.results`, `results.errors` |
+
+## Workflow
+
+1. After mapping a sample with ontology-mapper, pass the annotations to `schema_checker.py` to verify correctness.
+2. For a specific class, use `completeness_checker.py` to see what required/recommended properties are missing.
+3. When building relationships between instances, use `relationship_checker.py` to ensure domain/range consistency.
+
+## Conversational Workflow Example
+
+```
+User: I annotated my sample as CrystalStructure with properties hasUnitCell and hasBasis.
+      Is this correct and complete?
+
+Agent: Let me validate your annotation and check completeness.
+
+[Runs: completeness_checker.py --ontology cmso --class "Crystal Structure" --provided "has unit cell,has basis" --json]
+
+Your annotation is partially complete:
+- has unit cell: provided (required)
+- has basis: not a direct property of Crystal Structure (it belongs to Unit Cell)
+- **Missing required**: has space group
+
+The "has basis" property belongs to the Unit Cell class, not Crystal Structure.
+You should add "has space group" to Crystal Structure and move "has basis"
+to the Unit Cell annotation.
+```
+
+## CLI Examples
+
+```bash
+# Validate an annotation
+python3 skills/ontology/ontology-validator/scripts/schema_checker.py \
+  --ontology cmso \
+  --annotation '{"class":"Unit Cell","properties":{"has Bravais lattice":"cF"}}' \
+  --json
+
+# Check completeness
+python3 skills/ontology/ontology-validator/scripts/completeness_checker.py \
+  --ontology cmso \
+  --class "Crystal Structure" \
+  --provided "has unit cell,has space group" \
+  --json
+
+# Validate relationships
+python3 skills/ontology/ontology-validator/scripts/relationship_checker.py \
+  --ontology cmso \
+  --relationships '[{"subject_class":"Computational Sample","property":"has material","object_class":"Material"}]' \
+  --json
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `Class 'X' not found` | Invalid class name | Use ontology-explorer to find correct name |
+| `Property 'X' not found` | Invalid property name | Use property_lookup.py to search |
+| `Annotation must be a dict` | Wrong input format | Provide valid JSON dict |
+| `Relationships must be a non-empty list` | Wrong input format | Provide JSON array of relationship dicts |
+
+## Interpretation Guidance
+
+- **Errors** indicate definite problems (unknown class/property, range mismatch)
+- **Warnings** indicate potential issues (domain mismatch — may be intentional for subclasses)
+- **Completeness score**: 0.0-1.0 ratio of provided vs. total tracked properties
+- **required_missing**: must fix for valid annotation
+- **recommended_missing**: should fix for quality
+- **unrecognized**: may indicate typos or properties from a different ontology
+
+## Limitations
+
+- Constraints file is manually curated, not derived from OWL axioms
+- Does not validate data types (e.g., whether a value is actually a float vs string)
+- Does not validate cardinality (e.g., exactly one space group per structure)
+- Subclass checking uses simple parent traversal, not full OWL reasoning
+
+## References
+
+- [Validation Rules](references/validation_rules.md) — what is validated and why
+- [CMSO Constraints](references/cmso_constraints.json) — required/recommended properties per class
+- [CMSO Guide](../ontology-explorer/references/cmso_guide.md) — CMSO ontology overview
+
+## Version History
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-02-25 | 1.0 | Initial release with CMSO validation support |