chemicalml 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07b63ae96c1ef6187081c9f14ab76722b91f4438516a46c993abadac25f37a8f
+  data.tar.gz: 5130f3b5538741239be68d6632eaeecc0175ecb44f7a85cdf88e9414657c1689
+SHA512:
+  metadata.gz: 29433a22bbfd290ce7146fefda2d4e68944bda3098902e3d8c6f282d05c7b99ee95de9097685ed55e9ff365799e17eee785bb3b5414dff39076616c65db87189
+  data.tar.gz: 300c20a1df5cf4cbad657ce97fc0b26b6aec9f2ecb84ac524ab4f30a209636aeebbf6756637ee0e3fc6dec96685f4334aa8ee90e34a1058078ea2ccba4d2f4a8

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/
+.rspec_status

data/.rubocop.yml

@@ -0,0 +1,20 @@
+require:
+  - rubocop
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+  Exclude:
+    - "pkg/**/*"
+    - "vendor/**/*"
+    - "coverage/**/*"
+    - "reference-docs/**/*"
+    - "spec/fixtures/**/*"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to ChemML are documented here.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Initial gem scaffold: autoload tree, version, errors.
+- CML namespace declaration (`Chemicalml::Cml::Namespace`) for the CML
+  default XML namespace.
+- CML model classes for the core CML element set:
+  `Document`, `Molecule`, `AtomArray`, `Atom`, `BondArray`, `Bond`,
+  `Reaction`, `ReactantList`, `Reactant`, `ProductList`, `Product`,
+  `ReactionList`, `Name`, `Identifier`.
+- AsciiChem extension namespace (`Chemicalml::Ext::Namespace`) for
+  attributes CML doesn't natively cover (lone pairs, radical
+  electrons, stereochemistry).
+- Round-trip specs covering canonical CML fragments.
+
+[Unreleased]: https://github.com/lutaml/chemicalml/commits/main

data/CLAUDE.md

@@ -0,0 +1,198 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this gem is
+
+Chemicalml is a Ruby object model for the Chemical Markup Language (CML),
+the XML standard published at http://www.xml-cml.org/. It is a sibling
+model layer to other chemistry tooling (AsciiChem consumes it via the
+translator adapter) and is built on
+[lutaml-model](https://github.com/lutaml/lutaml-model) — there is no
+hand-rolled XML serialization anywhere in this library.
+
+The repo targets **two schema versions** simultaneously:
+`reference-docs/schemas/schema24/schema.xsd` and
+`reference-docs/schemas/schema3/schema.xsd`. Both XSDs ship in-tree;
+they are the source of truth for element/attribute names.
+
+## Commands
+
+```sh
+bundle install                 # one-time
+bundle exec rspec              # full suite
+bundle exec rspec spec/chemicalml/cml/molecule_spec.rb   # one file
+bundle exec rspec -e "round-trips"                       # by name match
+bundle exec rake              # alias for rspec
+bundle exec rubocop           # lint
+bundle exec rubocop -A        # autocorrect
+```
+
+`spec/examples.txt` and `Gemfile.lock` are gitignored — `spec/examples.txt`
+is regenerated by RSpec on every run, and `Gemfile.lock` is development-only.
+
+## Architecture (big picture)
+
+There are **five namespaces** under `Chemicalml`, deliberately kept
+independent:
+
+```
+Chemicalml
+├── parse(xml, schema: :schema3)   # top-level entry point
+├── Model                          # canonical, format-agnostic chemistry objects
+├── Cml                            # CML XML wire-format classes
+│  ├── Base::*                     # shared attribute+mapping mixins
+│  ├── Schema3::*                  # Schema 3 wire classes
+│  ├── Schema24::*                 # Schema 2.4 wire classes
+│  └── Translator                  # the only adapter between Model and Cml
+├── Schema                         # version registry
+├── Convention                     # 5 conventions + constraint framework
+└── Dictionary                     # dictionary model + YAML store
+```
+
+### Schema-versioned wire classes (mirrors `mml` V3/V4 pattern)
+
+Both Schema 3 and Schema 2.4 have **real, distinct** class hierarchies
+at `Chemicalml::Cml::Schema3::*` and `Chemicalml::Cml::Schema24::*`.
+They share attribute and XML-mapping declarations via
+`Chemicalml::Cml::Base::*` mixins (each Base module declares
+attributes and an `xml do ... end` block inside a `self.included`
+hook). Schema-specific deviations would live in additional
+`Base::Schema3Only::*` / `Base::Schema24Only::*` modules included
+only by the relevant version's classes — Open/Closed Principle.
+
+Each schema owns a `Configuration` sub-module that registers its
+wire classes with `Lutaml::Model::GlobalContext` under a context id
+(`:chemicalml_schema3`, `:chemicalml_schema24`). Each wire class
+declares `def self.lutaml_default_register` returning its context id,
+which lets `from_xml(xml, register: ctx)` correctly resolve child
+element types.
+
+The top-level `Chemicalml::Cml::*` constants (e.g. `Cml::Atom`,
+`Cml::Molecule`) are **backward-compatible aliases** pointing at the
+Schema3 versions. New code should prefer the versioned namespaces
+directly.
+
+### Top-level entry points
+
+```ruby
+Chemicalml.parse(xml)                    # → Schema3::Document (default)
+Chemicalml.parse(xml, schema: :schema24) # → Schema24::Document
+Chemicalml.serialize(document)           # → XML string
+Chemicalml::Cml::Schema3.parse(xml)      # version-specific
+Chemicalml::Cml::Schema24.parse(xml)     # version-specific
+```
+
+### The canonical model (`Chemicalml::Model::*`)
+
+Plain Ruby `Node` subclasses. **No XML, no JSON, no YAML**. Format-agnostic.
+Every adapter speaks this model; adapters never talk to each other directly.
+`Node` provides `accept(visitor)`, `value_attributes`, `children`, and
+class-level `short_name` so visitors written against the canonical model
+work across every adapter.
+
+### The CML wire layer (`Chemicalml::Cml::*`)
+
+Every CML element is a `Lutaml::Model::Serializable` subclass that
+includes three mixins: a `Base::*` module (shared declarations +
+xml mapping + `namespace Chemicalml::Cml::Namespace`), a
+`Role::*` marker module (type identity used by constraints and the
+translator — independent of which schema version's class it is), and
+`Cml::Visitable` (uniform interface for the constraint walker —
+`wire_children`, `node_id`, `element_name`).
+
+Wire classes are generated in-place by each schema module from the
+shared `Chemicalml::Cml::Elements::ALL` table — no 70+ boilerplate
+files. Adding a new CML element = adding one entry to `Elements::ALL`,
+one `Base::*` mixin, and one `Role::*` module. Both `Schema3::*` and
+`Schema24::*` pick up the new element automatically (unless it's
+listed in `Elements::SCHEMA3_ONLY`).
+
+The framework handles (de)serialization; **never** add `def to_xml` /
+`def from_xml` /
+`def to_h` to these classes.
+
+### The translator (`Chemicalml::Cml::Translator`)
+
+Pure transformation. `to_canonical(wire_doc)` accepts either Schema3
+or Schema24 wire documents (dispatches via `is_a?`).
+`from_canonical(model_doc, schema: :schema3)` produces the requested
+schema's wire format. It is the **only** place that imports both
+`Chemicalml::Model` and `Chemicalml::Cml`. Adding a new CML element
+means updating translator rules — the two namespaces stay decoupled.
+
+### Schema versions
+
+`Chemicalml::Schema::Registry` is the registry for schema versions
+(`schema24`, `schema3`). The schema XSDs are **archival source** —
+they must never be deleted, edited, or regenerated from code.
+
+### Conventions
+
+`Chemicalml::Convention` is a registry of named constraint sets
+(`molecular`, `compchem`, `dictionary`, `unit-dictionary`,
+`unitType-dictionary`). Each convention owns:
+
+- a namespace URI (e.g. `http://www.xml-cml.org/convention/molecular`)
+- a set of constraint classes registered against it
+
+Constraints are **registered**, not switch-statement'd — adding a new
+rule = registering a new constraint class, not editing existing
+renderer code (Open/Closed Principle).
+
+The constraint walker uses `Cml::Visitable#wire_children` to traverse
+the tree — no `respond_to?` duck typing.
+
+### Dictionaries
+
+`Chemicalml::Dictionary` is the model; entries have `id`, `term`,
+`definition`, `description`, `dataType`, `unitType`, `units`, optional
+`enum` (open or closed set), `links`, and `source_code`. Built-in
+dictionaries ship as YAML under `data/dictionaries/` and are loaded
+into a registry at startup.
+
+## Coding standards (project-specific)
+
+These are non-negotiable and apply in addition to the user's global rules:
+
+1. **No `require_relative` and no intra-library `require`** anywhere in
+   `lib/`. Use Ruby `autoload`, declared in the immediate parent
+   namespace's file (create the file if it doesn't exist). Example:
+   `lib/chemicalml/foo.rb` declares `autoload :Bar, "chemicalml/foo/bar"`.
+
+2. **Never hand-roll serialization.** No `def to_h`, `def from_h`,
+   `def to_xml`, `def from_xml`, `def to_json`, `def from_json` on
+   model classes. Wire names live in `mapping` blocks; round-trips go
+   through lutaml-model.
+
+3. **Never use `double` in specs.** Use real model instances or
+   `Struct.new` for plain data.
+
+4. **Never use `send` to call private methods, `instance_variable_set`/`get`,
+   or `respond_to?` for type checks.** Use `is_a?` or design the type
+   hierarchy so the check isn't needed.
+
+5. **One concern, one place (MECE).** Adding a CML element = adding one
+   model class + one Cml class + one translator rule + specs. Don't
+   entangle them.
+
+## Reference docs (in-tree)
+
+`reference-docs/` holds archival source material downloaded from
+xml-cml.org:
+
+- `schemas/schema24/schema.xsd`, `schemas/schema3/schema.xsd` — the XSDs
+- `conventions/` — convention specs (molecular, compchem, dictionary, etc.)
+- `cmllite.html` — the CMLLite paper
+
+These files are **source material, not derived output**. Never delete
+or edit them. Treat them as canonical references when designing model
+classes.
+
+## Fixtures
+
+`spec/fixtures/` holds CML example documents scraped from
+xml-cml.org/examples/, organized by schema version and category
+(`schema3/molecular/`, `schema3/compchem/`, `schema24/`). The scrape
+is one-shot via `bundle exec rake fixtures:scrape` — re-run only when
+the upstream examples change.

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "canon"
+  gem "nokogiri"
+  gem "rake", "~> 13.2"
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.66", require: false
+  gem "simplecov", "~> 0.22", require: false
+end

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/NOTICES.adoc

@@ -0,0 +1,115 @@
+= Chemicalml — Third-Party Notices
+
+Chemicalml is distributed under the BSD-2-Clause license. See
+link:LICENSE[LICENSE] for the full text.
+
+== Acknowledgements
+
+Chemicalml builds directly on the Chemical Markup Language (CML), a
+long-running community project hosted at http://www.xml-cml.org/. The
+CML schema, conventions, dictionaries, and example documents are the
+work of many people over more than two decades. We acknowledge with
+gratitude the people who built CML and continue to maintain it.
+
+=== Editors and authors of the convention specifications
+
+* **Sam Adams** (University of Cambridge) — editor of the molecular,
+  compchem, dictionary, unit-dictionary, and unitType-dictionary
+  convention specifications
+* **Joe Townsend** (University of Cambridge) — editor of the molecular,
+  compchem, dictionary, unit-dictionary, and unitType-dictionary
+  convention specifications
+* **Weerapong Phadungsukanan** (University of Cambridge) — editor of
+  the CompChem convention; author of the CompChem dictionary
+* **Jens Thomas** (STFC Daresbury Laboratory) — editor of the CompChem
+  convention
+* **Peter Murray-Rust** (University of Cambridge) — originator of CML,
+  author of the CompChem dictionary, driving force behind CML's
+  evolution
+* **Alex Wade**, **Nick England**, **Daniel Lowe**, **Hannah Barjat**,
+  **Egon Willighagen** — contributors to the convention specifications
+  and dictionaries
+
+=== The xml-cml.org project
+
+The http://www.xml-cml.org/[xml-cml.org] website is the canonical home
+of CML — schema files, convention specifications, dictionaries, example
+documents, and validation tooling. We are grateful to the entire CML
+community for keeping the project alive and openly licensed.
+
+== Third-party content redistributed in this repository
+
+The following files derive from upstream sources at xml-cml.org and are
+licensed under the
+http://creativecommons.org/licenses/by/3.0/[Creative Commons Attribution
+3.0 Unported License (CC-BY-3.0)]:
+
+=== CML schema XSDs
+
+* `reference-docs/schemas/schema3/schema.xsd` — the official CML
+  Schema 3 XSD
+* `reference-docs/schemas/schema24/schema.xsd` — the official CML
+  Schema 2.4 XSD
+
+=== Convention specifications (HTML originals archived as Markdown)
+
+* `reference-docs/conventions/index.md`
+* `reference-docs/conventions/molecular.md`
+* `reference-docs/conventions/compchem.md`
+* `reference-docs/conventions/dictionary.md`
+* `reference-docs/conventions/unit-dictionary.md`
+* `reference-docs/conventions/unitType-dictionary.md`
+
+=== Dictionary source content
+
+* `reference-docs/dictionaries/index.md` — landing page
+* `reference-docs/dictionaries/compchem.md` — CompChem dictionary
+  source content
+
+The YAML representation of the CompChem dictionary at
+`data/dictionaries/compchem.yaml` is derived from the upstream XML at
+http://www.xml-cml.org/dictionary/compchem/[xml-cml.org/dictionary/compchem/].
+
+=== Example CML documents
+
+Example CML files under `spec/fixtures/` are derived from
+http://www.xml-cml.org/examples/[xml-cml.org/examples/]. Each
+subdirectory corresponds to an upstream category:
+
+* `spec/fixtures/schema3/molecular/` — Schema 3 molecular examples
+* `spec/fixtures/schema3/compchem/` — Schema 3 compchem examples
+* `spec/fixtures/schema24/` — Schema 2.4 examples
+
+Some seed fixtures in this directory are synthetic (created for this
+gem) and are not subject to the upstream license; the BSD-2-Clause
+license of this gem applies to those.
+
+== Creative Commons Attribution 3.0 Unported License
+
+For the upstream content listed above:
+
+----
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS
+CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS
+PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE
+WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS
+PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND
+AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS
+LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU
+THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH
+TERMS AND CONDITIONS.
+
+Full license text: http://creativecommons.org/licenses/by/3.0/legalcode
+----
+
+== Attribution for derived works
+
+The Ruby wire-format classes in `lib/chemicalml/cml/`, the canonical
+model in `lib/chemicalml/model/`, the convention framework in
+`lib/chemicalml/convention/`, and the dictionary layer in
+`lib/chemicalml/dictionary/` are original work of the Chemicalml gem
+authors, distributed under the BSD-2-Clause license of this gem. They
+implement the semantics described by the upstream CML specifications
+but contain no upstream source code or text.

data/README.adoc

@@ -0,0 +1,87 @@
+= ChemML
+
+ChemML provides a https://www.xml-cml.org/[Chemical Markup Language (CML)]
+object model for Ruby, built on
+{lutaml-model}[https://github.com/lutaml/lutaml-model].
+
+== Purpose
+
+CML is the established XML standard for chemistry. Existing Ruby
+libraries either don't exist or use hand-rolled XML manipulation that
+drifts from the CML schema. ChemML gives CML a proper model layer
+with declarative attribute/mapping definitions and framework-backed
+serialization.
+
+== Install
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem "chemicalml"
+----
+
+Or install directly:
+
+[source,sh]
+----
+$ gem install chemicalml
+----
+
+== Usage
+
+Parse a CML document:
+
+[source,ruby]
+----
+require "chemicalml"
+
+doc = Chemicalml::Cml::Document.from_xml(File.read("ethanol.cml"))
+doc.molecules.first.atoms.first.element_type # => "C"
+----
+
+Build a document programmatically:
+
+[source,ruby]
+----
+atom = Chemicalml::Cml::Atom.new(id: "a1", element_type: "C")
+mol  = Chemicalml::Cml::Molecule.new(id: "m1", atoms: [atom])
+doc  = Chemicalml::Cml::Document.new(molecules: [mol])
+
+doc.to_xml # => well-formed CML XML
+----
+
+== Design
+
+Each CML element is a `Lutaml::Model::Serializable` subclass with
+declared attributes and an XML mapping block. Serialization goes
+through lutaml-model — no hand-rolled XML.
+
+The library is designed as a sibling model layer to other chemistry
+tooling. AsciiChem (https://www.asciichem.org) uses ChemML for CML
+round-trip support via a translator adapter.
+
+Both Schema 2.4 and Schema 3 are supported via
+`Chemicalml::Cml::Schema3` and `Chemicalml::Cml::Schema24` namespaces
+(see `lib/chemicalml/schema.rb`).
+
+The CML conventions (molecular, compchem, dictionary, unit-dictionary,
+unitType-dictionary) are implemented as registered constraint sets in
+`Chemicalml::Convention`. Built-in dictionaries ship as YAML under
+`data/dictionaries/`.
+
+== Acknowledgements
+
+CML is the work of the http://www.xml-cml.org/[xml-cml.org] community,
+edited by Sam Adams, Joe Townsend, Weerapong Phadungsukanan, and Jens
+Thomas, with originator Peter Murray-Rust and contributors Alex Wade,
+Nick England, Daniel Lowe, Hannah Barjat, and Egon Willighagen. The
+schema, conventions, dictionaries, and examples are licensed by
+xml-cml.org under
+http://creativecommons.org/licenses/by/3.0/[CC-BY-3.0]. See
+link:NOTICES.adoc[NOTICES.adoc] for full attribution of upstream
+content redistributed in this gem.
+
+== License
+
+BSD-2-Clause. See link:LICENSE[LICENSE].

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/TODO.align/01-cml-base-mixins.md

@@ -0,0 +1,122 @@
+# 01 — Cml::Base shared mixins
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+Extract every CML element's `attribute` + `xml do ... end` declarations
+into a reusable mixin under `Chemicalml::Cml::Base::*`. Each schema
+version's wire class then includes the relevant Base module and adds
+only its version-specific deviations.
+
+This mirrors `mml`'s `lib/mml/base/` directory: shared declarations
+live in modules, version namespaces consume them via `include`.
+
+## Why
+
+Without this factoring:
+
+- Adding a new schema version means duplicating every class body.
+- Schema-specific deviations touch the shared class — violates OCP.
+- Constraint code can't reason about a uniform interface.
+
+With Base mixins:
+
+- Adding Schema5 later = new namespace that includes the same Base
+  modules plus its own additions.
+- Schema24-specific behavior is added in `Base::Schema24Only::*`
+  modules, included only by Schema24 classes.
+
+## Deliverables
+
+- [ ] `lib/chemicalml/cml/base.rb` — namespace file with autoloads
+- [ ] `lib/chemicalml/cml/base/atom.rb` — `Base::Atom` mixin
+- [ ] `lib/chemicalml/cml/base/atom_array.rb`
+- [ ] `lib/chemicalml/cml/base/bond.rb`
+- [ ] `lib/chemicalml/cml/base/bond_array.rb`
+- [ ] `lib/chemicalml/cml/base/document.rb`
+- [ ] `lib/chemicalml/cml/base/formula.rb`
+- [ ] `lib/chemicalml/cml/base/identifier.rb`
+- [ ] `lib/chemicalml/cml/base/label.rb`
+- [ ] `lib/chemicalml/cml/base/list.rb`
+- [ ] `lib/chemicalml/cml/base/matrix.rb`
+- [ ] `lib/chemicalml/cml/base/metadata.rb`
+- [ ] `lib/chemicalml/cml/base/metadata_list.rb`
+- [ ] `lib/chemicalml/cml/base/module.rb`
+- [ ] `lib/chemicalml/cml/base/molecule.rb`
+- [ ] `lib/chemicalml/cml/base/name.rb`
+- [ ] `lib/chemicalml/cml/base/parameter.rb`
+- [ ] `lib/chemicalml/cml/base/parameter_list.rb`
+- [ ] `lib/chemicalml/cml/base/product.rb`
+- [ ] `lib/chemicalml/cml/base/product_list.rb`
+- [ ] `lib/chemicalml/cml/base/property.rb`
+- [ ] `lib/chemicalml/cml/base/property_list.rb`
+- [ ] `lib/chemicalml/cml/base/reaction.rb`
+- [ ] `lib/chemicalml/cml/base/reaction_list.rb`
+- [ ] `lib/chemicalml/cml/base/reactant.rb`
+- [ ] `lib/chemicalml/cml/base/reactant_list.rb`
+- [ ] `lib/chemicalml/cml/base/scalar.rb`
+- [ ] `lib/chemicalml/cml/base/array.rb`
+- [ ] `lib/chemicalml/cml/base/substance.rb`
+- [ ] `lib/chemicalml/cml/base/atom_parity.rb`
+- [ ] `lib/chemicalml/cml/base/bond_stereo.rb`
+- [ ] `lib/chemicalml/cml/base/dictionary.rb`
+- [ ] `lib/chemicalml/cml/base/dictionary_entry.rb`
+- [ ] `lib/chemicalml/cml/base/unit.rb`
+- [ ] `lib/chemicalml/cml/base/unit_list.rb`
+- [ ] `lib/chemicalml/cml/base/unit_type.rb`
+- [ ] `lib/chemicalml/cml/base/unit_type_list.rb`
+
+## Pattern
+
+Each Base module follows the same shape:
+
+```ruby
+# lib/chemicalml/cml/base/atom.rb
+module Chemicalml
+  module Cml
+    module Base
+      module Atom
+        def self.included(klass)
+          klass.class_eval do
+            attribute :id, :string
+            attribute :element_type, :string
+            # ...
+
+            xml do
+              root "atom"
+              map_attribute "id", to: :id
+              map_attribute "elementType", to: :element_type
+              # ...
+            end
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+The schema-versioned wire class is then a thin shell:
+
+```ruby
+# lib/chemicalml/cml/schema3/atom.rb
+module Chemicalml
+  module Cml
+    module Schema3
+      class Atom < Lutaml::Model::Serializable
+        include Base::Atom
+      end
+    end
+  end
+end
+```
+
+## Acceptance
+
+- All 36 Base mixin files exist, one per CML element.
+- Existing `Chemicalml::Cml::*` classes still load (they will be
+  refactored in task 02 to include the Base modules).
+- No `require_relative` — Base autoloads declared in
+  `lib/chemicalml/cml/base.rb`.