chemicalml 0.1.0

data/lib/chemicalml/model/reaction.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Model
+    # A chemical reaction. Reactants, products, arrow kind, optional
+    # conditions (above / below the arrow).
+    class Reaction < Node
+      ARROWS = %i[forward reverse equilibrium resonance].freeze
+
+      attr_accessor :id, :reactant_list, :product_list, :arrow,
+                    :conditions_above, :conditions_below, :title, :type
+
+      def initialize(id: nil, reactant_list:, product_list:,
+                     arrow: :forward, conditions_above: nil,
+                     conditions_below: nil, title: nil, type: nil)
+        @id = id
+        @reactant_list = reactant_list
+        @product_list = product_list
+        @arrow = arrow
+        @conditions_above = conditions_above
+        @conditions_below = conditions_below
+        @title = title
+        @type = type
+      end
+
+      def children
+        [reactant_list, product_list]
+      end
+
+      def value_attributes
+        {
+          id: id, reactant_list: reactant_list,
+          product_list: product_list, arrow: arrow,
+          conditions_above: conditions_above,
+          conditions_below: conditions_below,
+          title: title, type: type
+        }
+      end
+    end
+  end
+end

data/lib/chemicalml/model/reaction_list.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Model
+    # A reaction cascade: ordered list of `Reaction` instances where
+    # each step's products are the next step's reactants.
+    class ReactionList < Node
+      attr_accessor :reactions
+
+      def initialize(reactions: [])
+        @reactions = reactions
+      end
+
+      def children
+        reactions
+      end
+
+      def value_attributes
+        { reactions: reactions }
+      end
+    end
+  end
+end

data/lib/chemicalml/model/scalar.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Model
+    # A primitive scalar value with a data type and units.
+    class Scalar < Node
+      attr_accessor :id, :title, :dict_ref, :data_type, :units, :value
+
+      def initialize(value:, data_type: nil, units: nil, id: nil,
+                     title: nil, dict_ref: nil)
+        @value = value
+        @data_type = data_type
+        @units = units
+        @id = id
+        @title = title
+        @dict_ref = dict_ref
+      end
+
+      def value_attributes
+        { value: value, data_type: data_type, units: units,
+          id: id, title: title, dict_ref: dict_ref }
+      end
+    end
+  end
+end

data/lib/chemicalml/model/substance.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Model
+    # A reaction participant. Wraps a `Molecule` with a `role`
+    # (e.g. `:reactant`, `:product`, `:catalyst`, `:solvent`).
+    class Substance < Node
+      attr_accessor :molecule, :role, :title
+
+      def initialize(molecule:, role: nil, title: nil)
+        @molecule = molecule
+        @role = role
+        @title = title
+      end
+
+      def children
+        [molecule]
+      end
+
+      def value_attributes
+        { molecule: molecule, role: role, title: title }
+      end
+    end
+  end
+end

data/lib/chemicalml/model.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Canonical chemistry representation model. Format-agnostic plain
+  # Ruby classes; not tied to any wire format.
+  #
+  # Every adapter (CML XML, AsciiChem text, future SMILES/InChI/MOL)
+  # speaks the canonical model. Adapters never talk to each other
+  # directly — only through these classes.
+  module Model
+    autoload :Array, "chemicalml/model/cml_array"
+    autoload :Atom, "chemicalml/model/atom"
+    autoload :Bond, "chemicalml/model/bond"
+    autoload :Document, "chemicalml/model/document"
+    autoload :Formula, "chemicalml/model/formula"
+    autoload :Identifier, "chemicalml/model/identifier"
+    autoload :Label, "chemicalml/model/label"
+    autoload :Matrix, "chemicalml/model/matrix"
+    autoload :Metadata, "chemicalml/model/metadata"
+    autoload :MetadataList, "chemicalml/model/metadata_list"
+    autoload :Module, "chemicalml/model/cml_module"
+    autoload :Molecule, "chemicalml/model/molecule"
+    autoload :Name, "chemicalml/model/name"
+    autoload :Node, "chemicalml/model/node"
+    autoload :Parameter, "chemicalml/model/parameter"
+    autoload :ParameterList, "chemicalml/model/parameter_list"
+    autoload :Product, "chemicalml/model/product"
+    autoload :ProductList, "chemicalml/model/product_list"
+    autoload :Property, "chemicalml/model/property"
+    autoload :PropertyList, "chemicalml/model/property_list"
+    autoload :Reaction, "chemicalml/model/reaction"
+    autoload :ReactionList, "chemicalml/model/reaction_list"
+    autoload :Reactant, "chemicalml/model/reactant"
+    autoload :ReactantList, "chemicalml/model/reactant_list"
+    autoload :Scalar, "chemicalml/model/scalar"
+    autoload :Substance, "chemicalml/model/substance"
+  end
+end

data/lib/chemicalml/schema/definition.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Schema
+    # Value object describing one CML schema version. Immutable.
+    class Definition
+      attr_reader :version, :xsd_path, :xml_namespace, :ruby_namespace
+
+      def initialize(version:, xsd_path:, xml_namespace:, ruby_namespace:)
+        @version = version
+        @xsd_path = xsd_path
+        @xml_namespace = xml_namespace
+        @ruby_namespace = ruby_namespace
+        freeze
+      end
+
+      def xsd_full_path
+        File.expand_path(xsd_path, project_root)
+      end
+
+      def wire_namespace_constant
+        ruby_namespace.split("::").reduce(Object) { |ns, name| ns.const_get(name) }
+      end
+
+      def eql?(other)
+        other.is_a?(Definition) && version == other.version
+      end
+      alias == eql?
+
+      def hash
+        version.hash
+      end
+
+      private
+
+      def project_root
+        File.expand_path("../../..", __dir__)
+      end
+    end
+  end
+end

data/lib/chemicalml/schema/registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Schema
+    # Lookup table for schema versions. Adding a new schema = adding
+    # one entry to `Chemicalml::Schema::BUILTIN`. No mutation of
+    # existing entries, no switch statements.
+    module Registry
+      LOOKUP = Schema::BUILTIN.each_with_object({}) do |(key, defn), h|
+        h[key] = defn
+        h[key.to_s] = defn
+      end.freeze
+
+      def self.lookup(name)
+        entry = LOOKUP[name] || LOOKUP[name.to_sym] || LOOKUP[name.to_s]
+        raise ArgumentError, "unknown schema version: #{name.inspect}" unless entry
+
+        entry
+      end
+
+      def self.versions
+        Schema::BUILTIN.keys.freeze
+      end
+
+      def self.default
+        lookup(:schema3)
+      end
+    end
+  end
+end

data/lib/chemicalml/schema.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Schema version registry. Maps version symbols (e.g. `:schema3`,
+  # `:schema24`) to their canonical metadata: XSD path, default XML
+  # namespace, and the Ruby sub-namespace that holds the wire classes.
+  #
+  # The two XSDs are source-of-truth archival files under
+  # `reference-docs/schemas/`. They are never modified or regenerated
+  # from code.
+  module Schema
+    autoload :Definition, "chemicalml/schema/definition"
+    autoload :Registry,   "chemicalml/schema/registry"
+
+    CML_XML_NAMESPACE = "http://www.xml-cml.org/schema"
+
+    # Built-in versions registered at load time. Adding a new CML schema
+    # version = appending an entry here and creating the matching
+    # `Chemicalml::Cml::SchemaXxx` namespace. No existing code changes.
+    BUILTIN = {
+      schema24: Definition.new(
+        version: :schema24,
+        xsd_path: "reference-docs/schemas/schema24/schema.xsd",
+        xml_namespace: CML_XML_NAMESPACE,
+        ruby_namespace: "Chemicalml::Cml::Schema24"
+      ),
+      schema3: Definition.new(
+        version: :schema3,
+        xsd_path: "reference-docs/schemas/schema3/schema.xsd",
+        xml_namespace: CML_XML_NAMESPACE,
+        ruby_namespace: "Chemicalml::Cml::Schema3"
+      )
+    }.freeze
+  end
+end

data/lib/chemicalml/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  VERSION = "0.1.0"
+end

data/lib/chemicalml/versioned_parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Shared parse entrypoint for versioned schema modules. Each schema
+  # module (`Cml::Schema3`, `Cml::Schema24`) extends this; it provides
+  # `.parse(xml)` that ensures the schema's wire classes are
+  # registered with `Lutaml::Model::GlobalContext`, then delegates to
+  # `Document.from_xml(xml, register: context_id)`.
+  #
+  # Mirrors `Mml::VersionedParser`.
+  module VersionedParser
+    def parse(xml, namespace_exist: true)
+      configuration.ensure_registered!
+      document_class.from_xml(
+        xml_input(xml, namespace_exist),
+        register: configuration.context_id
+      )
+    end
+
+    def document_class
+      const_get(:Document)
+    end
+
+    def configuration
+      const_get(:Configuration)
+    end
+
+    private
+
+    def xml_input(xml, namespace_exist)
+      return xml if namespace_exist
+
+      namespace_uri = Chemicalml::Cml::Namespace.uri
+      inject_namespace(xml, namespace_uri)
+    end
+
+    def inject_namespace(xml_string, namespace_uri)
+      xml_string.sub(/<cml([\s>])/) do
+        "<cml xmlns=\"#{namespace_uri}\"#{Regexp.last_match(1)}"
+      end
+    end
+  end
+end

data/lib/chemicalml.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+# Chemicalml provides a Ruby object model for the Chemical Markup Language
+# (CML).
+#
+# Top-level entry points:
+#   Chemicalml::Cml::Document.from_xml(xml)  # parse CML
+#   document.to_xml                       # serialize back to XML
+#
+# Each CML element is a Lutaml::Model::Serializable subclass with
+# declared attributes and an XML mapping block. Serialization is
+# framework-backed — no hand-rolled XML in this library.
+module Chemicalml
+  autoload :Cml, "chemicalml/cml"
+  autoload :Configuration, "chemicalml/configuration"
+  autoload :ContextConfiguration, "chemicalml/context_configuration"
+  autoload :Convention, "chemicalml/convention"
+  autoload :Dictionary, "chemicalml/dictionary"
+  autoload :Error, "chemicalml/errors"
+  autoload :Model, "chemicalml/model"
+  autoload :ParseError, "chemicalml/errors"
+  autoload :Schema, "chemicalml/schema"
+  autoload :VERSION, "chemicalml/version"
+  autoload :VersionedParser, "chemicalml/versioned_parser"
+
+  module_function
+
+  def parse(xml, schema: :schema3, namespace_exist: true)
+    parser_for(schema).parse(xml, namespace_exist: namespace_exist)
+  end
+
+  def serialize(document, **opts)
+    document.to_xml(**opts)
+  end
+
+  def parser_for(schema)
+    case schema.to_sym
+    when :schema3  then Chemicalml::Cml::Schema3
+    when :schema24 then Chemicalml::Cml::Schema24
+    else
+      raise ArgumentError, "unsupported schema: #{schema.inspect} " \
+                           "(supported: :schema3, :schema24)"
+    end
+  end
+end

data/lib/tasks/reference_fetch.rake

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "fileutils"
+
+# Idempotent fetcher for xml-cml.org reference material.
+# Re-running this task only downloads files that are missing locally.
+module ReferenceFetch
+  BASE = "http://www.xml-cml.org".freeze
+  LICENSE = "Source: <url>. Distributed by xml-cml.org under CC-BY-3.0.".freeze
+
+  # Map of remote URL => local path under reference-docs/.
+  SOURCES = {
+    # Conventions
+    "#{BASE}/convention/"                                => "reference-docs/conventions/index.md",
+    "#{BASE}/convention/molecular"                       => "reference-docs/conventions/molecular.md",
+    "#{BASE}/convention/compchem"                        => "reference-docs/conventions/compchem.md",
+    "#{BASE}/convention/dictionary"                      => "reference-docs/conventions/dictionary.md",
+    "#{BASE}/convention/unit-dictionary"                 => "reference-docs/conventions/unit-dictionary.md",
+    "#{BASE}/convention/unitType-dictionary"             => "reference-docs/conventions/unitType-dictionary.md",
+    # Dictionaries
+    "#{BASE}/dictionary/"                                => "reference-docs/dictionaries/index.md",
+    "#{BASE}/dictionary/compchem/"                       => "reference-docs/dictionaries/compchem.md",
+    "#{BASE}/dictionary/cml/"                            => "reference-docs/dictionaries/cml.md",
+    "#{BASE}/dictionary/cml/name/"                       => "reference-docs/dictionaries/cml-name.md",
+    "#{BASE}/dictionary/cml/formula/"                    => "reference-docs/dictionaries/cml-formula.md",
+    "#{BASE}/dictionary/cif/"                            => "reference-docs/dictionaries/cif.md",
+    # Unit dictionaries
+    "#{BASE}/unit/si/"                                   => "reference-docs/dictionaries/unit-si.md",
+    "#{BASE}/unit/nonSi/"                                => "reference-docs/dictionaries/unit-nonSi.md",
+    "#{BASE}/unit/unitType/"                             => "reference-docs/dictionaries/unit-type.md",
+    # Schema / spec
+    "https://www.xml-cml.org/schema/cmllite.html"        => "reference-docs/cmllite.html",
+    # Examples
+    "#{BASE}/examples/schema3/molecular/"                => "reference-docs/examples/schema3-molecular-index.md",
+    "#{BASE}/examples/schema3/compchem/"                 => "reference-docs/examples/schema3-compchem-index.md",
+    "#{BASE}/examples/schema24/"                         => "reference-docs/examples/schema24-index.md"
+  }.freeze
+
+  def self.fetch_all
+    SOURCES.each do |url, path|
+      fetch_one(url, path)
+      sleep 0.5
+    end
+  end
+
+  def self.fetch_one(url, path)
+    full = File.expand_path(path, project_root)
+    if File.exist?(full)
+      puts "skip     #{path} (exists)"
+      return
+    end
+
+    FileUtils.mkdir_p(File.dirname(full))
+    body = http_get(url)
+    if body.nil?
+      File.write("#{full}.failed", "GET #{url} -> failed\n")
+      warn "FAILED  #{url}"
+      return
+    end
+
+    if path.end_with?(".html")
+      File.write(full, body)
+    else
+      File.write(full, header(url) + body)
+    end
+    puts "saved   #{path}"
+  end
+
+  def self.header(url)
+    "<!-- Source: #{url} -->\n<!-- License: CC-BY-3.0 (http://creativecommons.org/licenses/by/3.0/) -->\n\n"
+  end
+
+  def self.http_get(url, limit = 5)
+    raise "too many redirects" if limit.zero?
+
+    uri = URI(url)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true if uri.is_a?(URI::HTTPS)
+    http.read_timeout = 30
+    req = Net::HTTP::Get.new(uri, "User-Agent" => "chemicalml-gem-reference-fetch")
+    res = http.request(req)
+
+    case res
+    when Net::HTTPSuccess then res.body
+    when Net::HTTPRedirection then http_get(res["location"], limit - 1)
+    else nil
+    end
+  rescue StandardError => e
+    warn "  error fetching #{url}: #{e.message}"
+    nil
+  end
+
+  def self.project_root
+    File.expand_path("..", __dir__)
+  end
+end
+
+namespace :reference do
+  desc "Download all xml-cml.org reference material into reference-docs/. Idempotent."
+  task :fetch do
+    ReferenceFetch.fetch_all
+  end
+end

data/lib/tasks/scrape_fixtures.rake

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "fileutils"
+require "cgi"
+
+# Idempotent scraper for xml-cml.org example CML files. Walks the
+# HTML index pages, extracts the embedded CML, and writes one `.cml`
+# file per example under `spec/fixtures/`.
+module FixturesScrape
+  BASE = "http://www.xml-cml.org".freeze
+
+  # Map of remote index URL => local target directory.
+  INDEXES = {
+    "#{BASE}/examples/schema3/molecular/" => "spec/fixtures/schema3/molecular",
+    "#{BASE}/examples/schema3/compchem/"  => "spec/fixtures/schema3/compchem",
+    "#{BASE}/examples/schema24/"          => "spec/fixtures/schema24"
+  }.freeze
+
+  def self.scrape_all
+    INDEXES.each { |url, dir| scrape_index(url, dir) }
+  end
+
+  def self.scrape_index(index_url, target_dir)
+    full_target = File.expand_path(target_dir, project_root)
+    FileUtils.mkdir_p(full_target)
+
+    body = http_get(index_url)
+    unless body
+      warn "FAILED to fetch #{index_url}"
+      return
+    end
+
+    example_links = extract_example_links(body, index_url)
+    puts "#{index_url} -> #{example_links.length} examples"
+    example_links.each do |href, title|
+      save_example(href, title, full_target)
+      sleep 0.5
+    end
+  end
+
+  def self.extract_example_links(html, base_url)
+    hrefs = html.scan(/<a[^>]+href=["']([^"']+\.html?)["'][^>]*>([^<]+)<\/a>/i)
+    hrefs.map do |raw_href, raw_title|
+      href = URI.join(base_url, raw_href).to_s
+      title = CGI.unescapeHTML(raw_title.strip)
+      next nil if title.empty?
+      next nil unless title.match?(/\A[a-z]/i)
+
+      [href, title]
+    end.compact
+  end
+
+  def self.save_example(url, title, target_dir)
+    slug = slugify(title)
+    return if slug.empty?
+
+    path = File.join(target_dir, "#{slug}.cml")
+    if File.exist?(path)
+      puts "  skip     #{slug}.cml (exists)"
+      return
+    end
+
+    body = http_get(url)
+    unless body
+      log_failure(url, target_dir)
+      return
+    end
+
+    cml = extract_cml(body)
+    unless cml
+      log_failure(url, target_dir, reason: "no <cml> block found")
+      return
+    end
+
+    File.write(path, cml.strip + "\n")
+    puts "  saved   #{slug}.cml"
+  end
+
+  def self.extract_cml(html)
+    match = html.match(/<cml[^>]*>.*<\/cml>/m)
+    return match[0] if match
+
+    match = html.match(/<(?:cml|module|dictionary|molecule|reaction|unitList|unitTypeList)[^>]*>.*<\/(?:cml|module|dictionary|molecule|reaction|unitList|unitTypeList)>/m)
+    match && match[0]
+  end
+
+  def self.slugify(title)
+    title.downcase
+         .gsub(/[^a-z0-9]+/, "_")
+         .gsub(/^_+|_+$/, "")
+  end
+
+  def self.http_get(url, limit = 5)
+    raise "too many redirects" if limit.zero?
+
+    uri = URI(url)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true if uri.is_a?(URI::HTTPS)
+    http.read_timeout = 30
+    req = Net::HTTP::Get.new(uri, "User-Agent" => "chemicalml-gem-fixtures-scrape")
+    res = http.request(req)
+
+    case res
+    when Net::HTTPSuccess then res.body
+    when Net::HTTPRedirection then http_get(res["location"], limit - 1)
+    else nil
+    end
+  rescue StandardError => e
+    warn "  error fetching #{url}: #{e.message}"
+    nil
+  end
+
+  def self.log_failure(url, target_dir, reason: "fetch failed")
+    File.open(File.join(target_dir, ".scrape-log"), "a") do |f|
+      f.puts "#{Time.now.utc.iso8601}\t#{url}\t#{reason}"
+    end
+  end
+
+  def self.project_root
+    File.expand_path("../..", __dir__)
+  end
+end
+
+require "time"
+
+namespace :fixtures do
+  desc "Scrape every xml-cml.org example CML into spec/fixtures/. Idempotent."
+  task :scrape do
+    FixturesScrape.scrape_all
+  end
+end