chemicalml 0.2.1 → 0.4.0

data/docs/constraints.md

@@ -0,0 +1,161 @@
+# Registered Convention Constraints
+
+Auto-generated from `Chemicalml::Convention::Registry.each_constraint`.
+Last regenerated: 2026-07-20T09:43:53Z.
+
+Total constraints: **91**
+
+## convention:cascade
+
+- **Namespace**: `http://www.xml-cml.org/convention/cascade`
+- **Constraint count**: 4
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `ReactionSchemeMustHaveContent` | ReactionScheme | A `<reactionScheme>` MUST contain at least one `<reactionStepList>` or `<reaction>` child. An empty scheme carries no cascade information. |
+| `ReactionStepListMustContainSteps` | ReactionStepList | A `<reactionStepList>` MUST contain at least one `<reactionStep>` child. An empty step list breaks the cascade chain. |
+| `ReactionStepMustHaveReactionOrLists` | ReactionStep | A `<reactionStep>` MUST contain either a `<reaction>` child or explicit `<reactantList>` + `<productList>` children. An empty step is a dead-end in the cascade. |
+| `ReactiveCentreAtomRefsShouldBePresent` | ReactiveCentre | A `<reactiveCentre>` SHOULD declare its `atomRefs` attribute. Without atom references the reactive centre is indistinguishable from a placeholder. Warning severity — |
+
+## convention:compchem
+
+- **Namespace**: `http://www.xml-cml.org/convention/compchem`
+- **Constraint count**: 20
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `CompchemModuleMustContainJobList` | _(document-wide)_ | A CompChem module MUST contain at least one jobList module child per the compchem convention. |
+| `JobMustContainInitialization` | Module | A job module MUST contain exactly one initialization module child per the compchem convention. |
+| `JobListModuleMustHaveId` | Module | A jobList module MUST have an `id` unique within the compchem module. |
+| `JobModuleMustHaveId` | Module | A job module MUST have an `id` unique within the compchem module. |
+| `JobModuleAtMostOneFinalization` | Module | A job module MUST contain at most one finalization module. |
+| `JobModuleAtMostOneEnvironment` | Module | A job module MUST contain at most one environment module. |
+| `CalculationRequiresFinalization` | Module | Co-constraint: if a calculation module is present inside a job, a finalization MUST also be present. |
+| `InitializationAtMostOneMolecule` | Module | The initialization module MUST NOT contain more than one molecule child. |
+| `InitializationAtMostOneParameterList` | Module | The initialization module MUST NOT contain more than one parameterList child. |
+| `InitializationMustNotContainProperty` | Module | The initialization module MUST NOT contain property or propertyList children directly. (Properties belong in finalization.) |
+| `FinalizationAtMostOneMolecule` | Module | The finalization module MUST NOT contain more than one molecule child. |
+| `FinalizationAtMostOnePropertyList` | Module | The finalization module MUST NOT contain more than one propertyList child. |
+| `FinalizationMustNotContainParameter` | Module | The finalization module MUST NOT contain parameter or parameterList children directly. (Parameters belong in initialization.) |
+| `EnvironmentAtMostOnePropertyList` | Module | The environment module MUST NOT contain more than one propertyList child. |
+| `EnvironmentMustNotContainParameter` | Module | The environment module MUST NOT contain parameter or parameterList children directly. It MAY contain a propertyList (which itself can hold parameters). |
+| `ScalarUnits` | Scalar | CompChem value-container rules: `scalar` with dataType `xsd:integer` or `xsd:double` MUST have `units`; `scalar` with dataType `xsd:string` MUST NOT have `units`. |
+| `ArrayRules` | Array | CompChem `array` value-container rules: MUST have `size` attribute (≥ 1); `dataType` MUST be integer or double; MUST have `units`. |
+| `MatrixRules` | Matrix | CompChem `matrix` value-container rules: MUST have `rows` and `columns` attributes (each ≥ 1); `dataType` MUST be integer or double; MUST have `units`. |
+| `InitializationMustHaveContent` | Module | An `initialization` module MUST contain at least one of: `molecule`, `parameterList`, or a user-defined module child. Per the compchem convention spec. |
+| `FinalizationMustHaveContent` | Module | A `finalization` module MUST contain at least one of: `molecule`, `propertyList`, or a user-defined module child. Per the compchem convention spec. |
+
+## convention:dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/dictionary`
+- **Constraint count**: 8
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `EntryMustHaveIdAndTerm` | DictionaryEntry | Every entry MUST have an `id` and a `term` attribute per the dictionary convention. |
+| `EntryIdsUniqueWithinDictionary` | Dictionary | Entry ids MUST be unique within the parent dictionary per the dictionary convention. |
+| `DictionaryMustHaveNamespace` | Dictionary | A `<dictionary>` element MUST have a `namespace` attribute whose value is a valid URI defining the scope within which the entry terms are unique. |
+| `DictionaryNamespaceShouldEndWithSlashOrHash` | Dictionary | The `namespace` URI SHOULD end with `/` or `#` so terms can be referenced by appending them to the URI. Warning level. |
+| `EntryMustContainDefinition` | DictionaryEntry | An `<entry>` MUST contain a single `definition` child element. The schema allows it as a string; this constraint enforces presence. |
+| `EntryIdMustMatchPattern` | DictionaryEntry | An `<entry>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*` — start with a letter, followed by letters/digits/dot/hyphen/ underscore. Mirrors the upstream IdStartChar / IdChar BNF. |
+| `EntryMustHaveUnitType` | DictionaryEntry | An `<entry>` MUST have a `unitType` attribute. Entries describing concepts that should not have units (e.g. name of a program) should reference `none` in the standard CML |
+| `EntryUnitsCoConstraints` | DictionaryEntry | Co-constraint between `unitType` and `units`: - If `unitType` is `unknown`, `units` MUST NOT be present. - If `unitType` is `none`, `units` MUST be present and point |
+
+## convention:molecular
+
+- **Namespace**: `http://www.xml-cml.org/convention/molecular`
+- **Constraint count**: 36
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `AtomArrayMustContainAtoms` | Molecule | `atomArray` MUST contain at least one atom. The atoms can be in the child form (`<atom>` elements) or the parallel-array form (`atomID` attribute with whitespace-separated ids). |
+| `AtomIdsUniqueWithinMolecule` | _(document-wide)_ | Atom ids MUST be unique within the eldest containing molecule per the molecular convention. |
+| `BondMustReferenceAtomsInSameMolecule` | _(document-wide)_ | Bonds MUST reference atoms within the same parent molecule per the molecular convention. |
+| `AtomMustHaveId` | Atom | An <atom> inside an atomArray in a molecule MUST have an id attribute. |
+| `AtomMustHaveElementType` | Atom | An <atom> inside an atomArray in a molecule MUST have an elementType attribute. |
+| `BondMustHaveAtomRefs2` | Bond | A <bond> MUST have an atomRefs2 attribute referencing two distinct atoms in the same molecule. |
+| `BondMustHaveOrder` | Bond | A <bond> MUST have an order attribute (S/D/T/A recommended). |
+| `MoleculeMustHaveId` | Molecule | A <molecule> in a molecular document MUST have an id attribute unique within document scope. |
+| `AtomCoordinatesMustBePaired` | Atom | <atom> 2D coordinates (x2, y2) must appear together; 3D coordinates (x3, y3, z3) must appear together. |
+| `PropertyMustHaveDictRef` | Property | A <property> MUST have a dictRef attribute that identifies the property type via a dictionary entry. |
+| `ScalarMustHaveDataType` | Scalar | A <scalar> child of a <property> MUST have a dataType attribute (e.g. xsd:float, xsd:integer). |
+| `BondOrderShouldNotBeNumeric` | Bond | A <bond>'s order attribute SHOULD be one of S/D/T/Q/A or 'other' (numeric values are not recommended). |
+| `AtomIdMustMatchPattern` | Atom | An <atom>'s id attribute SHOULD start with a letter and contain only letters, digits, dot, hyphen, or underscore. |
+| `MoleculeCountMustNotAppearOnTopLevel` | _(document-wide)_ | Molecular convention: `count` MUST NOT appear on top-level molecules (direct children of `<cml>`). It is REQUIRED on molecules nested inside another `<molecule>`. |
+| `MoleculeAtomArrayMutuallyExclusiveWithChildren` | Molecule | Molecular convention: a `<molecule>` MAY hold an `atomArray` OR child `<molecule>` elements, but not both. The two are mutually exclusive ways of describing composition. |
+| `MoleculeBondArrayMutuallyExclusiveWithChildren` | Molecule | Molecular convention: a `<molecule>` MAY hold a `bondArray` OR child `<molecule>` elements, but not both. |
+| `BondStereoWedgeHashMustHaveAtomRefs2` | BondStereo | Molecular convention: `<bondStereo>` value W (wedge) or H (hatch) MUST have `atomRefs2` and MUST NOT have `atomRefs4`. |
+| `BondStereoCisTransMustHaveAtomRefs4` | BondStereo | Molecular convention: `<bondStereo>` value C (cis) or T (trans) MUST have `atomRefs4` and MUST NOT have `atomRefs2`. |
+| `BondStereoOtherMustHaveDictRef` | BondStereo | Molecular convention: `<bondStereo>` with value `other` MUST have a `dictRef` pointing to the convention that defines the stereo semantics. |
+| `BondIdsUniqueWithinMolecule` | _(document-wide)_ | Molecular convention: a `<bond>` `id` MUST be unique within the eldest containing molecule. Mirrors the existing `AtomIdsUniqueWithinMolecule` constraint for bonds. |
+| `BondOrderOtherMustHaveDictRef` | Bond | Molecular convention: `<bond>` with `order="other"` MUST have a `dictRef` pointing to the dictionary that defines the order semantics. The warning-level "should not be |
+| `AtomArrayMustBeChildOfMoleculeOrFormula` | _(document-wide)_ | Molecular convention: `<atomArray>` MUST be a child of `<molecule>` or `<formula>`. Any other parent is invalid. Checked from the parent's perspective during the walk — |
+| `BondArrayMustBeChildOfMolecule` | _(document-wide)_ | Molecular convention: `<bondArray>` MUST be a child of `<molecule>`. Any other parent is invalid. |
+| `BondOrderShouldBeInEnum` | Bond | A `<bond>`'s `order` attribute SHOULD be one of the XSD orderType enum values: S/1/D/2/T/3/A/unknown/other. Warning severity — CML permits extension values via |
+| `BondStereoShouldBeInEnum` | BondStereo | A `<bondStereo>`'s `value` attribute SHOULD be one of the XSD stereoType enum values: C/T/W/H/undefined/other. Warning severity. |
+| `MoleculeChiralityShouldBeInEnum` | Molecule | A `<molecule>`'s `chirality` attribute SHOULD be one of the XSD chiralityType enum values: enantiomer/racemate/unknown/other. Warning severity. |
+| `BondAtomRefs2ShouldBeDistinct` | Bond | A `<bond>`'s `atomRefs2` SHOULD reference two distinct atom ids. A self-bond (`a1 a1`) is chemically meaningless. Warning severity — there are edge cases in non-classical |
+| `ReferencesShouldResolve` | _(document-wide)_ | Walks the document via `Cml::ReferenceResolver` and reports every bond whose `atomRefs2` references atoms that don't exist in the parent molecule. Warning severity — there are |
+| `BondStereoAtomRefs4ShouldBeDistinct` | BondStereo | A `<bondStereo>` with `atomRefs4` (used by C/T stereo) SHOULD reference four distinct atom ids. Duplicate ids make the stereo descriptor meaningless. Warning severity. |
+| `AtomParityAtomRefs4ShouldBeDistinct` | AtomParity | An `<atomParity>` element's `atomRefs4` attribute SHOULD reference four distinct atom ids around a chiral center. Duplicate ids make the parity descriptor meaningless. |
+| `AtomElementTypeShouldBeInPeriodicTable` | Atom | An `<atom>`'s `elementType` attribute SHOULD be one of the XSD elementTypeType enum values (the periodic table plus the special "Du" dummy and "R" group placeholder). Warns |
+| `DictRefShouldResolve` | Atom, Bond, Molecule, Property, Scalar, Array, Matrix, Name, Label | Walks the document and warns on any element whose `dictRef` attribute cannot be resolved against the built-in dictionaries. Catches typos like `dictRef="cml:bpingpoint"`. |
+| `MoleculeIdShouldMatchPattern` | Molecule | A `<molecule>`'s `id` attribute SHOULD match the XSD moleculeIDType pattern (letter/underscore start, alphanumeric body, optional namespace prefix). Warning severity. |
+| `BondIdShouldMatchPattern` | Bond | A `<bond>`'s `id` attribute SHOULD match the XSD idType pattern (letter start, alphanumeric body with dots/dashes). Warning severity. |
+| `AtomParityShouldIncludeParentAtom` | _(document-wide)_ | Walks the document and warns on `<atomParity>` elements whose parent `<atom>`'s id does not appear in atomRefs4. The CML convention requires the parent atom to be one of |
+| `PropertyScalarDataTypeMatchesDictionary` | Property | A `<property>` with a `dictRef` whose dictionary entry declares a `dataType` SHOULD have a child `<scalar>` whose `dataType` attribute matches. Catches inconsistencies like a property |
+
+## convention:simpleUnit
+
+- **Namespace**: `http://www.xml-cml.org/convention/simpleUnit`
+- **Constraint count**: 3
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitMustHavePower` | Unit | A `<unit>` under simpleUnit MUST declare a `power` attribute (integer). Without a power the unit's exponent is undefined. |
+| `UnitMustHaveSymbol` | Unit | A `<unit>` under simpleUnit MUST declare a non-empty `symbol` attribute. Without a symbol the unit cannot be rendered in formulae. |
+| `RootMustBeUnitList` | _(document-wide)_ | The root of a simpleUnit document MUST be a `<unitList>` declaring `convention="convention:simpleUnit"`. Any other root shape is rejected. |
+
+## convention:spectroscopy
+
+- **Namespace**: `http://www.xml-cml.org/convention/spectroscopy`
+- **Constraint count**: 5
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `SpectrumMustHaveConvention` | Spectrum | A `<spectrum>` MUST declare its own convention attribute so consumers know how to interpret its format and peaks. Per the molecular convention: "spectrum — any number, each MUST |
+| `SpectrumMustHaveFormat` | Spectrum | A `<spectrum>` MUST have a `format` attribute (e.g. "mass", "ir", "nmr", "uv") so consumers know the measurement type. |
+| `SpectrumMustHaveContent` | Spectrum | A `<spectrum>` MUST contain at least one of: `<xaxis>`, `<yaxis>`, `<peakList>`. An empty spectrum carries no data. |
+| `PeakListMustContainPeaks` | PeakList | A `<peakList>` MUST contain at least one `<peak>` or `<peakGroup>` child. An empty peakList carries no data. |
+| `PeakShouldHaveValues` | Peak | A `<peak>` SHOULD declare at least one of `xValue` or `yValue`. A peak with neither carries no position information. Warning severity — there are edge cases |
+
+## convention:unit-dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/unit-dictionary`
+- **Constraint count**: 10
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitMustHaveSymbolAndUnitType` | Unit | Every unit MUST have `id`, `title`, `symbol`, `parentSI`, at least one of `multiplierToSI`/`constantToSI`, and `unitType` per the unit-dictionary convention. |
+| `UnitMustHaveId` | Unit | A `<unit>` element MUST have an `id` attribute, unique within the unitList. |
+| `UnitMustContainDefinition` | Unit | A `<unit>` element MUST contain a single `<definition>` child element with XHTML content. |
+| `UnitListMustHaveNamespace` | UnitList | A `<unitList>` element MUST have a `namespace` attribute whose value is a valid URI defining the scope within which the unit ids are unique. SHOULD end with `/` or `#`. |
+| `UnitListMustContainAtLeastOneUnit` | UnitList | A `<unitList>` element MUST contain one or more `<unit>` children, and MUST NOT contain any other CML-namespace child elements. |
+| `UnitMustHaveTitle` | Unit | A `<unit>` element MUST have a `title` attribute (the full human-readable name of the unit). Per the unit-dictionary convention spec. |
+| `UnitMustHaveParentSi` | Unit | A `<unit>` element MUST have a `parentSI` attribute — a QName referencing the SI unit it derives from. Per the unit-dictionary convention spec. |
+| `UnitMustHaveMultiplierOrConstantToSi` | Unit | A `<unit>` element MUST have at least one of `multiplierToSI` or `constantToSI` — to define the conversion to the parent SI unit. Per the unit-dictionary convention spec. |
+| `UnitUnitTypeShouldResolve` | Unit | A `<unit>`'s `unitType` attribute SHOULD reference a unitType that exists in a built-in unitType-dictionary. Catches typos like `unitType="unitType:lenght"` (misspelled). |
+| `UnitParentSiShouldResolve` | Unit | A `<unit>`'s `parentSI` attribute SHOULD reference a unit that exists in a built-in dictionary (typically the SI dictionary). Catches typos like `parentSI="si:metr"`. |
+
+## convention:unitType-dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/unitType-dictionary`
+- **Constraint count**: 5
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitTypeMustHaveIdAndName` | UnitType | Every unitType MUST have an `id` and a `name` attribute per the unitType-dictionary convention. |
+| `UnitTypeIdMustMatchPattern` | UnitType | A `<unitType>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*`. |
+| `UnitTypeMustContainDefinition` | UnitType | A `<unitType>` MUST contain a single `<definition>` child with XHTML content. |
+| `UnitTypeListMustHaveNamespace` | UnitTypeList | A `<unitTypeList>` MUST have a `namespace` attribute (valid URI, SHOULD end with `/` or `#`). |
+| `UnitTypeListMustContainAtLeastOneUnitType` | UnitTypeList | A `<unitTypeList>` MUST contain one or more `<unitType>` children. |

data/docs/generate_constraint_docs.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "chemicalml"
+
+# Auto-generated documentation of every registered convention
+# constraint. Run via `bundle exec rake docs:constraints` or
+# `bundle exec ruby docs/generate_constraint_docs.rb`.
+#
+# Single source of truth: derived from `Convention::Registry.each_constraint`.
+# Do not edit `docs/constraints.md` by hand — regenerate.
+
+output = []
+output << "# Registered Convention Constraints"
+output << ""
+output << "Auto-generated from `Chemicalml::Convention::Registry.each_constraint`."
+output << "Last regenerated: #{Time.now.utc.iso8601}."
+output << ""
+output << "Total constraints: **#{Chemicalml::Convention::Registry.total_constraint_count}**"
+output << ""
+
+Chemicalml::Convention::Registry.each do |conv|
+  output << "## #{conv.qname}"
+  output << ""
+  output << "- **Namespace**: `#{conv.namespace_uri}`"
+  output << "- **Constraint count**: #{conv.constraint_count}"
+  output << ""
+
+  output << "| Constraint | Applies to | Description |"
+  output << "|---|---|---|"
+  conv.constraints.each do |klass|
+    name = klass.name.split("::").last
+    roles = klass.applies_to_roles
+    applies = roles.nil? ? "_(document-wide)_" : roles.map { |r| r.name.split("::").last }.join(", ")
+    desc = klass.description
+    desc = "" if desc == name
+    desc_escaped = desc.gsub("|", "\\|")
+    output << "| `#{name}` | #{applies} | #{desc_escaped} |"
+  end
+  output << ""
+end
+
+path = File.expand_path("constraints.md", __dir__)
+File.write(path, output.join("\n"))
+puts "Wrote #{path} (#{Chemicalml::Convention::Registry.total_constraint_count} constraints)"

data/exe/chemicalml

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "chemicalml"
+exit Chemicalml::Cli.run(ARGV)

data/lib/chemicalml/cli/base.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Chemicalml
+  module Cli
+    # Thor-based dispatcher. Each command delegates to a dedicated
+    # `Chemicalml::Cli::*Command` class invoked as
+    # `MyCommand.new.run(options)`, where `options` is a single hash
+    # carrying both positional args (keyed by name) and flags.
+    #
+    # A `Chemicalml::Logger` bridged to Thor's shell is injected into
+    # every command — so info/warn/error get coloured output on the
+    # terminal while remaining loggable for library callers.
+    class Base < Thor
+      private
+
+      # Build a logger bridged to this Thor instance for coloured output.
+      def bridged_logger
+        Chemicalml::Logger.default.tap { |l| l.thor_shell = self }
+      end
+
+      public
+
+      desc 'validate FILE', 'Validate a CML file against its declared convention'
+      method_option :json, type: :boolean, aliases: '-j',
+                           desc: 'Emit machine-readable JSON output'
+      def validate(file)
+        ValidateCommand.new(logger: bridged_logger).run(file: file, json: options[:json])
+      end
+
+      desc 'inspect FILE', 'Print a tree-style summary of the document'
+      def inspect(file)
+        InspectCommand.new(logger: bridged_logger).run(file: file)
+      end
+
+      desc 'conventions', 'List registered conventions'
+      def conventions
+        ConventionsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'dictionaries', 'List built-in dictionaries'
+      def dictionaries
+        DictionariesCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'elements', 'List all CML wire classes'
+      def elements
+        ElementsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'constraints', 'List all registered constraints'
+      def constraints
+        ConstraintsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'enums', 'List all XSD enum constants'
+      def enums
+        EnumsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'info ELEMENT', 'Show details about a CML element'
+      def info(element)
+        InfoCommand.new(logger: bridged_logger).run(element: element)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/command.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # Base class for every command. Subclasses implement `#run(options)`.
+    #
+    # Each command receives a `Chemicalml::Logger` in its constructor.
+    # When dispatched via Thor (the normal CLI path), the logger is
+    # bridged to Thor's shell for coloured output. When invoked
+    # directly (MyCommand.new.run(options)), the logger writes plain
+    # text to $stderr.
+    class Command
+      attr_reader :logger
+
+      # @param logger [Chemicalml::Logger] the logger to use. Defaults
+      #   to a plain stderr logger. The Thor dispatcher passes one
+      #   bridged to Thor's shell for colour.
+      def initialize(logger: Chemicalml::Logger.default)
+        @logger = logger
+      end
+
+      class << self
+        def run(options = {}, logger: Chemicalml::Logger.default)
+          new(logger: logger).run(options)
+        end
+      end
+
+      def run(_options = {})
+        raise NotImplementedError, "#{self.class} must implement #run"
+      end
+
+      private
+
+      def puts(*args)
+        $stdout.puts(*args)
+      end
+
+      def stderr(*args)
+        $stderr.puts(*args)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/constraints_command.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml constraints` — list every registered constraint
+    # across every convention with its applies_to roles.
+    class ConstraintsCommand < Command
+      def run(_options = {})
+        current = nil
+        Chemicalml::Convention::Registry.each_constraint do |conv, klass|
+          unless conv.qname == current
+            current = conv.qname
+            puts ''
+            puts "=== #{current} (#{conv.constraint_count}) ==="
+          end
+          name = klass.name.split('::').last
+          applies = klass.applies_to_roles
+          roles_str = applies.nil? ? '' : "  → #{applies.map { |r| r.name.split('::').last }.join(', ')}"
+          puts "  #{name}#{roles_str}"
+          desc = klass.description
+          puts "    #{desc}" unless desc == name
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/conventions_command.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml conventions` — list every registered convention
+    # by QName, sorted.
+    class ConventionsCommand < Command
+      def run(_options = {})
+        Chemicalml::Convention::Registry.builtin_qnames.sort.each { |q| puts q }
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/dictionaries_command.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml dictionaries` — list built-in YAML dictionaries
+    # by short name.
+    class DictionariesCommand < Command
+      def run(_options = {})
+        Chemicalml::Dictionary::Registry.builtin_names.each { |n| puts n }
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/elements_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml elements` — list every CML wire class registered
+    # in Schema3 with its XML element name.
+    class ElementsCommand < Command
+      def run(_options = {})
+        Chemicalml::Cml::Schema3::Configuration.ensure_registered!
+        Chemicalml::Cml::Elements::ALL.sort.each do |cls, xml_id|
+          puts "#{cls.to_s.ljust(25)} → <#{xml_id}>"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/enums_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml enums` — list every `Cml::Enums` constant with
+    # its allowed values.
+    class EnumsCommand < Command
+      def run(_options = {})
+        Chemicalml::Cml::Enums.constants(false).sort.each do |name|
+          values = Chemicalml::Cml::Enums.const_get(name)
+          puts "#{name} (#{values.size}): #{values.to_a.sort.first(20).join(', ')}"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/info_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml info <element>` — show details about a CML element
+    # by XML name: Ruby class, role, attributes, applicable constraints.
+    class InfoCommand < Command
+      def run(options)
+        name = options[:element]
+        unless name
+          logger.error 'info requires an <element-name> argument (e.g. "atom")'
+          return 2
+        end
+
+        klass = Chemicalml::Cml.for_xml_name(name)
+        unless klass
+          stderr "unknown element: #{name}"
+          return 2
+        end
+
+        Chemicalml::Cml::Schema3::Configuration.ensure_registered!
+        puts "Element: <#{name}>"
+        puts "Class:   #{klass}"
+        role = role_of(klass)
+        puts "Role:    #{role || '(none)'}"
+        puts ''
+        puts "Attributes (#{klass.attributes.size}):"
+        klass.attributes.each_value do |attr|
+          col = attr.collection? ? '[]' : ' '
+          puts "  #{attr.name}#{col}"
+        end
+        applicable = constraints_for_role(role)
+        return 0 if applicable.empty?
+
+        puts ''
+        puts "Applicable constraints (#{applicable.size}):"
+        applicable.each do |(conv, c)|
+          puts "  [#{conv.qname}] #{c.name.split('::').last}"
+        end
+        0
+      end
+
+      private
+
+      def role_of(klass)
+        # Find the most specific Role module included in klass
+        # (the one with the longest name that matches Cml::Role::*).
+        klass.ancestors.find do |a|
+          next false unless a.is_a?(Module)
+          next false unless a.name
+
+          a.name.start_with?('Chemicalml::Cml::Role::')
+        end
+      end
+
+      def constraints_for_role(role)
+        return [] unless role
+
+        Chemicalml::Convention::Registry.each_constraint.with_object([]) do |(conv, c), acc|
+          roles = c.applies_to_roles
+          next if roles.nil?
+
+          matched = roles.any? do |r|
+            role <= r
+          rescue StandardError
+            false
+          end
+          next unless matched
+
+          acc << [conv, c]
+        end
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/inspect_command.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml inspect <file>` — print a tree-style summary of
+    # the document: element names, ids, nested children.
+    class InspectCommand < Command
+      def run(options)
+        path = options[:file]
+        unless path
+          logger.error 'inspect requires a <file> argument'
+          return 2
+        end
+
+        doc = Chemicalml.parse(File.read(path), schema: :schema3)
+        print_tree(doc, 0)
+        0
+      rescue ArgumentError, Lutaml::Model::InvalidFormatError => e
+        logger.error "FAIL: #{e.message}"
+        2
+      end
+
+      private
+
+      def print_tree(node, depth, max_depth: 6)
+        return if depth > max_depth
+        return unless node.is_a?(Lutaml::Model::Serializable)
+
+        indent = '  ' * depth
+        line = "#{indent}#{node.class.name.split('::').last}"
+        line += " [#{node.node_id}]" if node.is_a?(Chemicalml::Cml::Visitable) && node.node_id
+        puts line
+        return unless node.is_a?(Chemicalml::Cml::Visitable)
+
+        node.wire_children.each { |c| print_tree(c, depth + 1, max_depth: max_depth) }
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/validate_command.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml validate <file>` — auto-detect convention and
+    # print violations. With `--json` / `-j`, emits machine-readable
+    # JSON.
+    class ValidateCommand < Command
+      def run(options)
+        path = options[:file]
+        unless path
+          logger.error 'validate requires a <file> argument'
+          return 2
+        end
+
+        logger.info "Validating #{path}" unless options[:json]
+        doc = Chemicalml.parse(File.read(path), schema: :schema3)
+        report = Chemicalml.validate(doc)
+
+        if options[:json]
+          puts json_report(report, path)
+        elsif report.ok? && !report.has_warnings?
+          logger.info "OK: #{path}"
+        else
+          logger.error report.summary
+        end
+        report.ok? ? 0 : 1
+      rescue ArgumentError, Lutaml::Model::InvalidFormatError => e
+        logger.error "FAIL: #{e.message}"
+        2
+      end
+
+      private
+
+      def json_report(report, path)
+        require 'json'
+        payload = {
+          file: path,
+          ok: report.ok?,
+          has_warnings: report.has_warnings?,
+          violations: report.violations.map do |v|
+            {
+              severity: v.severity,
+              path: v.path,
+              message: v.message,
+              value: v.value
+            }.compact
+          end
+        }
+        JSON.pretty_generate(payload)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Command-line interface. Built on Thor for dispatch; each command is
+  # a dedicated class under `Chemicalml::Cli::*Command` exposing
+  # `.run(args, options)` (and `#run` on an instance).
+  #
+  # Dispatch flow:
+  #
+  #   exe/chemicalml ARGV
+  #     -> Chemicalml::Cli::Base.start(ARGV)  (Thor)
+  #     -> Chemicalml::Cli::<Name>Command.new.run(args, options)
+  #
+  # Adding a new command:
+  #   1. Create `lib/chemicalml/cli/<name>_command.rb` with a class
+  #      extending `Chemicalml::Cli::Command` and implementing `#run`.
+  #   2. Add one `desc + def` block in `Chemicalml::Cli::Base` that
+  #      invokes `<Name>Command.new.run(args, options)`.
+  #   3. Add the autoload entry below.
+  module Cli
+    autoload :Base,           'chemicalml/cli/base'
+    autoload :Command,        'chemicalml/cli/command'
+    autoload :ValidateCommand,    'chemicalml/cli/validate_command'
+    autoload :InspectCommand,     'chemicalml/cli/inspect_command'
+    autoload :ConventionsCommand, 'chemicalml/cli/conventions_command'
+    autoload :DictionariesCommand, 'chemicalml/cli/dictionaries_command'
+    autoload :ElementsCommand,    'chemicalml/cli/elements_command'
+    autoload :ConstraintsCommand, 'chemicalml/cli/constraints_command'
+    autoload :EnumsCommand,       'chemicalml/cli/enums_command'
+    autoload :InfoCommand,        'chemicalml/cli/info_command'
+
+    # Backward-compatible entry point used by `exe/chemicalml` and tests.
+    # @param argv [Array<String>] the command line.
+    # @return [Integer] process exit code.
+    def self.run(argv)
+      Base.start(argv)
+      0
+    rescue StandardError => e
+      warn "FAIL: #{e.message}"
+      2
+    end
+  end
+end