asciichem 0.31.1 → 0.31.3

data/lib/asciichem/mechanism_graph.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # The mechanism step graph (TODO.v2/13 item 4): `mechanism{}` entries
+  # stay verbatim (label + reaction text) in the model; this service
+  # derives the graph the text implies — each step's reaction parsed
+  # with the same grammar, species that appear on both sides of a step
+  # recognised as catalysts, and steps linked where a product species
+  # of an earlier step is a reactant of a later one.
+  #
+  # Everything is computed; nothing mutates. A step whose value is not
+  # a reaction (prose, "proton transfer") keeps a nil reaction and
+  # takes part in no links — never an error.
+  module MechanismGraph
+    Step = Struct.new(:label, :reaction, :catalysts, keyword_init: true)
+    Link = Struct.new(:from, :to, :species, keyword_init: true)
+    Graph = Struct.new(:steps, :links, keyword_init: true)
+
+    module_function
+
+    def for(mechanism)
+      steps = mechanism.steps.map { |step| graph_step(step) }
+      Graph.new(steps: steps, links: links(steps))
+    end
+
+    def graph_step(step)
+      reaction = parse_reaction(step.reaction)
+      sides = sides_of(reaction)
+      catalysts = sides ? sides[:reactants].keys & sides[:products].keys : []
+      Step.new(label: step.label, reaction: reaction, catalysts: catalysts)
+    end
+
+    def links(steps)
+      steps.each_with_index.flat_map do |from, i|
+        next [] unless from.reaction
+
+        from_products = sides_of(from.reaction)[:products].keys
+        steps[(i + 1)..].filter_map { |to| link_between(from, to, from_products) }
+      end
+    end
+
+    def link_between(from, to, from_products)
+      return nil unless to.reaction
+
+      shared = from_products & sides_of(to.reaction)[:reactants].keys
+      Link.new(from: from.label, to: to.label, species: shared) unless shared.empty?
+    end
+
+    def parse_reaction(text)
+      node = AsciiChem.parse(text).nodes.first
+      node if node.is_a?(AsciiChem::Model::Reaction) ||
+              node.is_a?(AsciiChem::Model::ReactionCascade)
+    rescue AsciiChem::ParseError
+      nil
+    end
+
+    # Coefficient-free species names per side; a cascade's entry side
+    # is its head and its exit side is its last step.
+    def sides_of(reaction)
+      case reaction
+      when AsciiChem::Model::Reaction
+        reaction.stoichiometry
+      when AsciiChem::Model::ReactionCascade
+        steps = reaction.steps
+        return nil if steps.empty?
+
+        { reactants: steps.first.stoichiometry[:reactants],
+          products: steps.last.stoichiometry[:products] }
+      end
+    end
+  end
+end

data/lib/asciichem/model/atom.rb

@@ -35,7 +35,7 @@ module AsciiChem
                     :charge, :oxidation_state,
                     :lone_pairs, :radical_electrons,
                     :ring_closures, :aromatic, :hydrogens,
-                    :x2, :y2, :z2, :atom_parity,
+                    :x2, :y2, :z2, :atom_parity, :chirality,
                     :spin_multiplicity, :atom_title,
                     :x_fract, :y_fract, :z_fract
 
@@ -60,6 +60,7 @@ module AsciiChem
                      lone_pairs: nil, radical_electrons: nil,
                      ring_closures: nil, aromatic: nil, hydrogens: nil,
                      x2: nil, y2: nil, z2: nil, atom_parity: nil,
+                     chirality: nil,
                      spin_multiplicity: nil, atom_title: nil,
                      x_fract: nil, y_fract: nil, z_fract: nil)
         @element = element
@@ -77,6 +78,7 @@ module AsciiChem
         @y2 = y2
         @z2 = z2
         @atom_parity = atom_parity
+        @chirality = chirality
         @spin_multiplicity = spin_multiplicity
         @atom_title = atom_title
         @x_fract = x_fract
@@ -92,6 +94,7 @@ module AsciiChem
           ring_closures: ring_closures, aromatic: aromatic,
           hydrogens: hydrogens,
           x2: x2, y2: y2, z2: z2, atom_parity: atom_parity,
+          chirality: chirality,
           spin_multiplicity: spin_multiplicity, atom_title: atom_title,
           x_fract: x_fract, y_fract: y_fract, z_fract: z_fract }
       end

data/lib/asciichem/model/bond.rb

@@ -4,40 +4,48 @@ module AsciiChem
   module Model
     # A bond between two adjacent nodes in a structural chain.
     class Bond < Node
-      attr_accessor :kind
+      attr_accessor :kind, :direction
 
       KINDS = {
-        single:    { ascii: "-",  mathml_entity: "-" },
-        double:    { ascii: "=",  mathml_entity: "=" },
-        triple:    { ascii: "#",  mathml_entity: "≡" },
-        quadruple: { ascii: "##", mathml_entity: "≣" },
-        wedge:     { ascii: ">-", mathml_entity: "↑" },
-        hash:      { ascii: "-<", mathml_entity: "↓" },
-        dative:    { ascii: "~>", mathml_entity: "→" },
-        wavy:      { ascii: "~~", mathml_entity: "∼" },
-        aromatic:  { ascii: ":",  mathml_entity: ":" }
+        single: { ascii: '-',  mathml_entity: '-' },
+        double: { ascii: '=',  mathml_entity: '=' },
+        triple: { ascii: '#',  mathml_entity: '≡' },
+        quadruple: { ascii: '##', mathml_entity: '≣' },
+        wedge: { ascii: '>-', mathml_entity: '↑' },
+        hash: { ascii: '-<', mathml_entity: '↓' },
+        dative: { ascii: '~>', mathml_entity: '→' },
+        wavy: { ascii: '~~', mathml_entity: '∼' },
+        aromatic: { ascii: ':', mathml_entity: ':' }
       }.freeze
 
       # CML wire order codes per bond kind. Single source of truth
       # for both adapter directions — to_canonical emits, from_canonical
       # parses. Adding a new bond kind = one entry here + one in KINDS.
       CML_ORDER_CODES = {
-        single: "S", double: "D", triple: "T",
-        quadruple: "Q", wedge: "W", hash: "H",
-        dative: "A", wavy: "V"
+        single: 'S', double: 'D', triple: 'T',
+        quadruple: 'Q', wedge: 'W', hash: 'H',
+        dative: 'A', wavy: 'V'
       }.freeze
       KIND_BY_CML_ORDER = CML_ORDER_CODES.invert.freeze
 
       # Subset that carries stereo meaning (wedge = out of page,
       # hash = into page). Used for <bondStereo> elements.
-      CML_STEREO_CODES = { wedge: "W", hash: "H" }.freeze
+      CML_STEREO_CODES = { wedge: 'W', hash: 'H' }.freeze
 
-      def initialize(kind: :single)
+      def initialize(kind: :single, direction: nil)
         @kind = kind
+        @direction = direction
+      end
+
+      # SMILES directional-bond orientation (`/` up, `\` down) on the
+      # single bonds flanking a stereogenic double bond. Orthogonal to
+      # the bond kind; only :single carries it.
+      def direction
+        @direction if kind == :single
       end
 
       def value_attributes
-        { kind: kind }
+        { kind: kind, direction: direction }
       end
 
       def ascii
@@ -49,7 +57,7 @@ module AsciiChem
       end
 
       def cml_order_code
-        CML_ORDER_CODES.fetch(kind, "S")
+        CML_ORDER_CODES.fetch(kind, 'S')
       end
 
       def cml_stereo_code

data/lib/asciichem/model/molecule.rb

@@ -124,15 +124,21 @@ module AsciiChem
       # describe the substance, not the stoichiometric multiplier.
       def element_counts(with_coefficient: true)
         tally = Hash.new(0)
-        multiplier = 1
-        if with_coefficient
-          own = coefficient&.to_i
-          multiplier = own if own && own.positive?
-        end
+        multiplier = with_coefficient ? stoichiometric_coefficient : 1
         nodes.each { |node| tally_element(node, tally, multiplier) }
         tally
       end
 
+      # The integer stoichiometric coefficient: the authored leading
+      # number, or 1 when absent or not positive. Single source for
+      # every consumer (reaction stoichiometry, the balance check,
+      # composition) — coefficients are model data, not per-caller
+      # parsing.
+      def stoichiometric_coefficient
+        own = coefficient&.to_i
+        own && own.positive? ? own : 1
+      end
+
       private
 
       def tally_element(node, tally, multiplier)

data/lib/asciichem/model/reaction.rb

@@ -5,8 +5,49 @@ module AsciiChem
     # A chemical reaction: reactants, an arrow, and products. Conditions
     # render above and below the arrow per IUPAC.
     class Reaction < Node
+      # Conditions carry the bracket text verbatim (the round-trip
+      # source) and derive typed entries from it: `[cat: Pd]` is a
+      # catalyst entry, `[water]` stays free text. `;` separates
+      # entries inside one bracket; unknown role prefixes are free text
+      # (lossless — never an error).
       Conditions = Struct.new(:above, :below, keyword_init: true)
 
+      class Conditions
+        ROLE_PREFIXES = {
+          'cat' => :catalyst, 'catalyst' => :catalyst,
+          'solv' => :solvent, 'solvent' => :solvent,
+          'reag' => :reagent, 'reagent' => :reagent
+        }.freeze
+        ENTRY_SEPARATOR = ';'
+        Entry = Struct.new(:role, :value, :side, keyword_init: true)
+
+        def entries
+          [[:above, above], [:below, below]].flat_map do |side, text|
+            entries_for(side, text)
+          end
+        end
+
+        private
+
+        def entries_for(side, text)
+          return [] if text.nil? || text.strip.empty?
+
+          text.split(ENTRY_SEPARATOR).filter_map do |chunk|
+            chunk = chunk.strip
+            next if chunk.empty?
+
+            role, value = split_role(chunk)
+            Entry.new(role: role, value: value, side: side)
+          end
+        end
+
+        def split_role(chunk)
+          prefix, rest = chunk.split(':', 2)
+          role = ROLE_PREFIXES[prefix.strip.downcase] unless rest.nil?
+          role ? [role, rest.strip] : [nil, chunk]
+        end
+      end
+
       ARROWS = {
         forward:     { ascii: '->',   mathml_entity: '→', wire: 'forward' },
         reverse:     { ascii: '<-',   mathml_entity: '←', wire: 'reverse' },
@@ -29,6 +70,14 @@ module AsciiChem
           conditions: conditions }
       end
 
+      # Normalized stoichiometry (item 4): each side maps the species'
+      # coefficient-free canonical text to its integer coefficient
+      # (absent coefficient = 1). A species can appear on both sides.
+      def stoichiometry
+        { reactants: side_stoichiometry(reactants),
+          products: side_stoichiometry(products) }
+      end
+
       def children
         reactants + products
       end
@@ -59,6 +108,14 @@ module AsciiChem
         "Reaction(#{reactants.map(&:to_s).join(' + ')} " \
           "#{arrow_ascii} #{products.map(&:to_s).join(' + ')})"
       end
+
+      private
+
+      def side_stoichiometry(side)
+        side.each_with_object(Hash.new(0)) do |molecule, out|
+          out[molecule.to_text.sub(/\A\d+/, '')] += molecule.stoichiometric_coefficient
+        end
+      end
     end
   end
 end

data/lib/asciichem/molfile/parser.rb

@@ -73,7 +73,9 @@ module AsciiChem
           Model::Atom.new(
             element: element,
             x2: x, y2: y, z2: z,
-            isotope: isotope_from_mass_diff(element, mass_diff)
+            isotope: isotope_from_mass_diff(element, mass_diff),
+            chirality: chirality_from_parity(line[39, 3].to_i),
+            hydrogens: hydrogens_from_hcount(line[42, 3].to_i)
           )
         end
       end
@@ -153,6 +155,20 @@ module AsciiChem
       def isotope_from_mass_diff(_element, mass_diff)
         nil
       end
+
+      # MDL atom parity: 1 odd, 2 even, 0/3 not stereo (or either).
+      # The parity is relative to the neighbour order in the bond
+      # block, which the linearizer preserves — the same ordering the
+      # SMILES TH1/TH2 convention uses.
+      def chirality_from_parity(parity)
+        { 1 => 'TH1', 2 => 'TH2' }[parity]
+      end
+
+      # MDL H-count code: 0 default, 1 H0, 2 H1, 3 H2, ...
+      def hydrogens_from_hcount(code)
+        code >= 1 ? code - 1 : nil
+      end
+
       def atoms_count
         field(3, 0, 3).to_i
       end

data/lib/asciichem/molfile/writer.rb

@@ -7,12 +7,21 @@ module AsciiChem
     # computed (Layout walks atoms in the same order as
     # Structure::Graph, so positions map by index). Charges and
     # isotopes are emitted as `M  CHG` / `M  ISO` property lines.
+    #
+    # Tetrahedral chirality crosses as the atom parity field
+    # (TH1 → 1 odd, TH2 → 2 even) relative to the neighbour order in
+    # the bond block, which is the model's linear order — the InChI
+    # binary consumes it when wedges or coordinates are absent.
+    # Directional bonds (`/`, `\`, E/Z) have no V2000 field: the
+    # model's Bond#direction is documented as a molfile loss rather
+    # than silently invented from geometry.
     class Writer
       BOND_TYPES = {
         single: 1, double: 2, triple: 3, aromatic: 4,
         wedge: 1, hash: 1
       }.freeze
       BOND_STEREO = { wedge: 1, hash: 6 }.freeze
+      CHIRALITY_PARITY = { 'TH1' => 1, 'TH2' => 2 }.freeze
 
       def initialize(molecule, name: nil)
         @molecule = molecule
@@ -21,7 +30,7 @@ module AsciiChem
 
       def write
         atoms, edges = Structure::Graph.build(@molecule)
-        raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty?
+        raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty? && atoms.length > 1
 
         lines = []
         lines << @name.to_s
@@ -32,8 +41,10 @@ module AsciiChem
         layout = nil
         atoms.each_with_index do |atom, index|
           x, y = coordinates(atom, index, atoms)
-          lines << format("%10.4f%10.4f%10.4f %-3s 0  0  0  0  0  0  0  0  0  0  0  0",
-                          x, y, atom.z2 || 0.0, atom.element)
+          lines << format("%10.4f%10.4f%10.4f %-3s 0  0%3d%3d  0  0  0  0  0  0  0  0  0",
+                          x, y, atom.z2 || 0.0, atom.element,
+                          CHIRALITY_PARITY.fetch(atom.chirality, 0),
+                          hcount_code(atom))
         end
 
         edges.each do |edge|
@@ -53,6 +64,12 @@ module AsciiChem
 
       private
 
+      # MDL H-count code: 0 default, 1 H0, 2 H1, 3 H2, ... — so a
+      # stated count n crosses as n + 1.
+      def hcount_code(atom)
+        atom.hydrogens.nil? ? 0 : atom.hydrogens + 1
+      end
+
       # Authored coordinates win; otherwise positions from the
       # deterministic 2D layout (same walk order as the graph).
       def coordinates(atom, index, atoms)

data/lib/asciichem/perception.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # The perception pass (TODO.v2/13 item 2): chemistry that the SYNTAX
+  # leaves implicit, derived once here and consumed everywhere — the
+  # linter, the canonicalizer, renderers, and the SMILES writer.
+  #
+  # Everything is a pure function of the model; nothing mutates.
+  module Perception
+    # Default valences per element (the common ground-state values;
+    # multi-valent elements list their allowed valences in order).
+    DEFAULT_VALENCES = {
+      'H' => [1], 'B' => [3], 'C' => [4], 'N' => [3], 'O' => [2],
+      'F' => [1], 'Al' => [3], 'Si' => [4], 'P' => [3, 5],
+      'S' => [2, 4, 6], 'Cl' => [1], 'Br' => [1], 'I' => [1]
+    }.freeze
+
+    BOND_ORDER = {
+      single: 1, double: 2, triple: 3, quadruple: 4,
+      aromatic: 1, wedge: 1, hash: 1, dative: 1, wavy: 1
+    }.freeze
+
+    module_function
+
+    # Perception runs over the neutral graph pair from
+    # Structure::Graph.build: [atoms, edges].
+
+    # Neighbour indexes of an atom, in edge order.
+    def neighbours(atom_index, edges)
+      edges.each_with_object([]) do |edge, acc|
+        acc << edge.to if edge.from == atom_index
+        acc << edge.from if edge.to == atom_index
+      end
+    end
+
+    # Sum of explicit bond orders at an atom (wedge/hash/dative/wavy
+    # bonds order as single; aromatic orders as 1 — Hückel alternation
+    # is a ring-perception concern, not a bond-order sum concern).
+    # This is the valence-feasibility sum: the linter's max-valence
+    # check consumes it.
+    def bond_order_sum(atom_index, edges)
+      edges.sum do |edge|
+        next 0 unless edge.from == atom_index || edge.to == atom_index
+
+        BOND_ORDER.fetch(edge.kind, 1)
+      end
+    end
+
+    # Hydrogen-counting sum: aromatic bonds order as 1.5 (Hückel), so
+    # both spellings of benzene sum to 3.0 at every carbon and perceive
+    # one implicit hydrogen — the two syntaxes share semantics. Whole
+    # numbers only: a fractional remainder means the Hückel arithmetic
+    # cannot decide (fused aromatic-schematic atoms), and perception
+    # declines rather than invents.
+    def hydrogen_valence_sum(atom_index, edges)
+      edges.sum do |edge|
+        next 0 unless edge.from == atom_index || edge.to == atom_index
+
+        edge.kind == :aromatic ? 1.5 : BOND_ORDER.fetch(edge.kind, 1)
+      end
+    end
+
+    # Implicit hydrogens for an atom: the smallest default valence
+    # that the hydrogen-valence sum fits, minus that sum. The sum must
+    # come from #hydrogen_valence_sum (aromatic-aware).
+    # - Atoms that STATE hydrogens ([NH4+], [CH4]) return 0 — never
+    #   add to what the source said.
+    # - Charged atoms return nil: charge algebra on valence is
+    #   element-specific and deferred until the perception pass grows
+    #   one (wrong implicit hydrogens are worse than none).
+    # - Elements without a table entry, non-integral or over-valent
+    #   sums return nil — never invent.
+    def implicit_hydrogens(atom, valence_sum)
+      return 0 if atom.hydrogens
+      return nil if atom.charge
+
+      deficits = valence_deficits(atom.element, valence_sum)
+      return nil if deficits.empty?
+
+      deficits.min.to_i
+    end
+
+    # Whole-number, non-negative gaps between each default valence and
+    # the hydrogen-valence sum; empty when the element is unknown or
+    # no valence fits integrally.
+    def valence_deficits(element, valence_sum)
+      valences = DEFAULT_VALENCES[element]
+      return [].freeze if valences.nil?
+
+      valences.map { |v| v - valence_sum }
+              .select { |deficit| deficit >= 0 && deficit.modulo(1).zero? }
+    end
+
+    # Six-membered cycles where every atom is sp2 (participates in a
+    # double bond) or aromatic-flagged — the practical fused-system
+    # rule: per-ring strict alternation can never see both rings of
+    # naphthalene (the shared bond is single), but per-atom sp2 does.
+    # Returns arrays of atom indexes, one per perceived ring, or an
+    # empty list. Full Hückel pi-electron counting is a later slice.
+    def aromatic_rings(atoms, edges)
+      cycles = ring_cycles(edges, max_size: 6, atom_count: atoms.length)
+        .select { |cycle| cycle.length == 6 }
+      cycles.select { |cycle| cycle.all? { |i| sp2?(i, atoms, edges) } }
+    end
+
+    def sp2?(atom_index, atoms, edges)
+      return true if atoms[atom_index].aromatic == true
+
+      edges.any? do |edge|
+        (edge.from == atom_index || edge.to == atom_index) && edge.kind == :double
+      end
+    end
+
+    def bond_kind(a, b, edges)
+      edge = edges.find do |e|
+        (e.from == a && e.to == b) || (e.from == b && e.to == a)
+      end
+      edge&.kind
+    end
+
+    # Simple cycles up to max_size via DFS (molecules are small).
+    def ring_cycles(edges, max_size:, atom_count:)
+      found = []
+      atom_count.times do |start|
+        dfs_cycles(edges, start, start, [start], max_size, found)
+      end
+      found.uniq { |cycle| cycle.minmax }
+    end
+
+    def dfs_cycles(edges, start, current, path, max_size, found)
+      neighbours(current, edges).each do |nb|
+        next if nb == path[-2]
+
+        if nb == start
+          found << path.dup if path.length >= 3
+        elsif !path.include?(nb) && path.length < max_size
+          dfs_cycles(edges, start, nb, path + [nb], max_size, found)
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/reaction_roles.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Reaction-role derivation (TODO.v2/13 item 4): explicit typed
+  # entries (`[cat: Pd]`, `[solv: THF]`, `[reag: NaH]`) win; free-text
+  # entries fall back to the writing convention — catalysts and light
+  # reagents ABOVE the arrow, solvents BELOW — classified by hint
+  # matching. Pure functions, nothing mutates.
+  module ReactionRoles
+    CATALYST_HINTS = %w[pd pt ni fe catalyst cat].freeze
+    SOLVENT_HINTS = %w[h2o thf dmso dmf etoh meoh toluene solvent sol water].freeze
+
+    module_function
+
+    # Returns { catalysts: [strings], solvents: [strings],
+    # reagents: [strings], other_below: [strings] }. Explicit roles
+    # route to their bucket regardless of side; free-text entries are
+    # split and classified by the above/below convention.
+    def roles_for(reaction)
+      roles = { catalysts: [], reagents: [], solvents: [], other_below: [] }
+      entries = reaction.conditions ? reaction.conditions.entries : []
+      entries.each { |entry| assign(entry, roles) }
+      roles
+    end
+
+    def assign(entry, roles)
+      case entry.role
+      when :catalyst then roles[:catalysts] << entry.value
+      when :solvent then roles[:solvents] << entry.value
+      when :reagent then roles[:reagents] << entry.value
+      else classify_free(entry, roles)
+      end
+    end
+
+    def classify_free(entry, roles)
+      split_entries(entry.value).each do |value|
+        roles[bucket(value, entry.side)] << value
+      end
+    end
+
+    def bucket(value, side)
+      if matches?(value, CATALYST_HINTS) then :catalysts
+      elsif matches?(value, SOLVENT_HINTS) then :solvents
+      elsif side == :above then :reagents
+      else :other_below
+      end
+    end
+
+    def split_entries(text)
+      return [] if text.nil? || text.strip.empty?
+
+      text.strip.split(/[;,\s]+/).reject(&:empty?)
+    end
+
+    def matches?(entry, hints)
+      hints.any? { |hint| entry.to_s.downcase.include?(hint) }
+    end
+  end
+end

data/lib/asciichem/resolver/opsin.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'net/https'
+require 'uri'
+
+module AsciiChem
+  module Resolver
+    # OPSIN source adapter (TODO.v2/13 item 3): IUPAC name → structure
+    # — name-to-structure perception for systematic names, the piece
+    # PubChem's name lookup cannot do (PubChem indexes a curated name
+    # list; OPSIN *derives* the structure from any systematic IUPAC
+    # name). Uses the public OPSIN web service
+    # (https://opsin.ch.cam.ac.uk), which answers with CML or SMILES.
+    #
+    # Citation profile: publisher University of Cambridge Centre for
+    # Molecular Informatics; per-access retrievedAt provenance.
+    class Opsin < Adapter
+      source_name :opsin
+      # Derivation only: 'name' is the curated-lookup convention
+      # (PubChem/Common Chemistry). OPSIN DERIVES structures from
+      # systematic names - reachable via 'iupac-name' so it can
+      # never preempt a lookup source.
+      supports 'iupac-name'
+
+      BASE = 'https://opsin.ch.cam.ac.uk/opsin'
+      private_constant :BASE
+
+      def fetch_record(value:, convention: nil, fetch:)
+        body = fetch.get("#{BASE}/#{CGI.escape(value.to_s)}.smiles")
+        return nil unless body
+
+        substance_from(body.strip)
+      rescue StandardError => e
+        raise Error, "opsin request failed: #{e.message}"
+      end
+
+      def attribution
+        'OPSIN, University of Cambridge Centre for Molecular Informatics'
+      end
+
+      private
+
+      def substance_from(smiles)
+        return nil if smiles.empty?
+
+        provenance = default_provenance
+        Substance.new(
+          preferred_name: nil,
+          identifiers: [Identifier.new(value: smiles, convention: 'canonical-smiles',
+                                       provenance: provenance)],
+          properties: [],
+          structure: parse_structure(smiles)
+        )
+      end
+
+      # OPSIN answers SMILES that may use features outside the
+      # supported subset (wildcards, exotic stereo); then the SMILES
+      # stays as an identifier and structure is nil — no silent loss.
+      def parse_structure(smiles)
+        AsciiChem.parse_smiles(smiles).nodes.first
+      rescue AsciiChem::ParseError
+        nil
+      end
+    end
+  end
+end

data/lib/asciichem/resolver.rb

@@ -17,6 +17,7 @@ module AsciiChem
     autoload :Adapter, "asciichem/resolver/adapter"
     autoload :Cache, "asciichem/resolver/cache"
     autoload :PubChem, "asciichem/resolver/pubchem"
+    autoload :Opsin, "asciichem/resolver/opsin"
     autoload :CommonChemistry, "asciichem/resolver/common_chemistry"
     autoload :Substance, "asciichem/resolver/substance"