asciichem 0.31.12 → 0.31.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02ee049d5ed6b808972e18f4ecf7bbf6723b39b8ba7a6342c38a06cd24b3673a
-  data.tar.gz: d455c3156215f27e7509fa610769b573a6bb0e6592097f7c4c67357738095e1d
+  metadata.gz: 380b64ab12e3ccc18a554a5d1dc7793046bfa7ea5ba80d51330bb5d713ea618f
+  data.tar.gz: 4b3ec1535d5854626b5e2976adb060b4432bfb7f9d20331e79717ae0db4cdf73
 SHA512:
-  metadata.gz: e83e9ce16a0ed8a1b22491c1964d15fc906467c152a5afec383ce4774d073beb591d8011a481216033855abc76e7f3febd377437f8808a6c1620448e17c60539
-  data.tar.gz: caeddc2cb2db07543e3ca9b49932a9ed2a0f68461f2f20eb7c6693914d9bf185b8c44cd7f27e5b2d107e0c9cf7ff704bf63a261180f5b6b112e0d2cc8326b28c
+  metadata.gz: 49ca402649027d0091acb25b77848e46a9ffaa5bf876e16512f14378d507a3bf32a6dbbb6245967bc54d1eb6728f0672a530db0e92c8db476ca9bfbdb87497f6
+  data.tar.gz: 1741914b553ebe4f1828fa3a294c3ed0249a22072dd90f57185d92aafea717a97eaded37236c97ac3b406032f2919cd449818ba6cf7a6094fdd37a81c7f5c44e

data/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.31.14] - 2026-11-12
+
+### Added
+- The Common Chemistry adapter accepts a user-provided API key:
+  `CommonChemistry.new(api_key: ...)` or the
+  `COMMON_CHEMISTRY_API_KEY` environment variable (sent as the
+  `apikey` query parameter). CAS key-gated the API — without a key
+  live lookups answer 401 and the resolver skips the source.
+
+## [0.31.13] - 2026-11-11
+
+### Fixed
+- `Resolver.resolve_all` isolates source-level failures: a live probe
+  found the Common Chemistry API now answers 401 without an API key
+  (CAS key-gated the endpoint); with it registered by default, that
+  401 raised through the multi-source fan-out and took the other
+  sources down with it. A source-level error now skips that source —
+  callers see what answered.
+
+### Changed
+- The README documents the full capability surface: structures,
+  lint, local identity, resolution with provenance, citations, and
+  the command line.
+
 ## [0.31.12] - 2026-11-11
 
 ### Changed

data/README.adoc

@@ -45,6 +45,96 @@ formula.to_mathml  # => "<math>...</math>"
 formula.to_text    # => "H_2O"  (round trip)
 ----
 
+The parsed model is the canonical form: MathML, HTML, LaTeX, text,
+linear and 2D structural SVG, and CML are views over the same tree.
+
+=== Structures: SMILES and molfile in, AsciiChem out
+
+[source,ruby]
+----
+formula = AsciiChem.parse_smiles("CC(=O)Oc1ccccc1C(=O)O")
+formula.to_structural_svg   # 2D depiction, deterministic layout
+formula.to_smiles           # canonical aromatic SMILES
+formula.to_text             # AsciiChem text
+
+formula = AsciiChem.parse_molfile(molfile_text)   # V2000 in and out
+----
+
+=== Lint
+
+[source,ruby]
+----
+AsciiChem::Linter.run(formula)   # chemistry diagnostics: balance,
+                                 # valence, charge, isotopes, rings,
+                                 # identifier consistency, ...
+AsciiChem::Linter.errors?(formula) # => true/false
+----
+
+=== Local identity: InChI, AuxInfo, InChIKey
+
+[source,ruby]
+----
+require "asciichem/inchi"
+
+# the native chemomer engine (byte-exact vs the IUPAC oracle;
+# CHEMOMER_LIB points at the built cdylib) or the IUPAC binary:
+AsciiChem::Inchi.engine = AsciiChem::Inchi::NativeEngine.new
+
+identity = AsciiChem::Inchi.identity_for(molecule)
+identity.inchi     # "InChI=1S/C9H8O4/..."
+identity.inchikey  # "BSYNRYMUTXBXSQ-UHFFFAOYSA-N"
+----
+
+=== Resolution: identifiers to substance records
+
+[source,ruby]
+----
+require "asciichem/resolver"
+
+substance = AsciiChem::Resolver.resolve(value: "50-78-2", convention: "cas")
+substance.preferred_name        # => "Aspirin"
+substance.structure.to_smiles   # from the source record
+substance.identifiers.first.provenance.source   # "common_chemistry"
+
+# all shipped sources (PubChem, OPSIN, CAS Common Chemistry) resolve
+# by default; attribution rides every record. Limit the set when a
+# use must stay NC-free:
+AsciiChem::Resolver.resolve(value: "50-78-2", convention: "cas",
+                            sources: [:pubchem, :opsin])
+----
+
+CAS key-gated the Common Chemistry API: live lookups there need a
+key (request one at cas.org/services/commonchemistry-api) exported
+as `COMMON_CHEMISTRY_API_KEY`. Without it, that source answers 401
+and is skipped — PubChem and OPSIN keep resolving.
+
+=== Citations: dataset bibitems with provenance
+
+[source,ruby]
+----
+require "asciichem/citation"
+
+molecule = AsciiChem.parse("CC(=O)OC1=CC=CC=C1C(=O)O @cas(\"50-78-2\") @cite(\"pubchem\")").nodes.first
+AsciiChem::Citation.for_molecule(molecule)
+# => [["pubchem", #<Relaton bibitem>]] - one dataset-type bibitem per
+# (substance, source), anchored by InChIKey, with a provenance note
+# (retrieved from, version, attribution).
+----
+
+== Command line
+
+[source,sh]
+----
+asciichem convert -i "H_2O" -t mathml        # also: --from smiles|molfile
+asciichem identity -i aspirin.smiles --from smiles
+asciichem resolve --cas 50-78-2 --source common_chemistry
+asciichem validate -i 'H_2O @cas("50-78-2")'
+asciichem cite --cas 50-78-2 -t model-json
+asciichem lint -i "2H_2 + O_2 -> 2H_2O"
+asciichem roundtrip -i "C_6H_12O_6"
+asciichem parse-cml -i formula.xml
+----
+
 == Conformance
 
 The reference implementation of https://www.asciichem.org[the AsciiChem

data/lib/asciichem/resolver/common_chemistry.rb

@@ -14,14 +14,32 @@ module AsciiChem
     # that must stay NC-free limit sources with the
     # `asciichem-sources` attribute (metanorma-plugin-asciichem) or
     # `Resolver.resolve(sources:)`.
+    #
+    # API access: CAS key-gated the API (401 without a key; request
+    # one at cas.org/services/commonchemistry-api — the exact contract
+    # arrives with the access email). The adapter sends the key as the
+    # `apikey` query parameter; set it per instance (`api_key:`) or
+    # through COMMON_CHEMISTRY_API_KEY, which the resolver's own
+    # instantiation picks up. Without a key, live lookups answer 401
+    # and the resolver skips this source (the other sources still
+    # resolve; seeded caches keep working).
     class CommonChemistry < Adapter
       source_name :common_chemistry
       supports "cas"
 
       BASE = "https://commonchemistry.cas.org/api/detail"
 
+      attr_reader :api_key
+
+      def initialize(api_key: ENV.fetch("COMMON_CHEMISTRY_API_KEY", nil))
+        super()
+        @api_key = api_key
+      end
+
       def fetch_record(value:, convention:, fetch:)
-        body = fetch.get("#{BASE}?cas_rn=#{CGI.escape(value.to_s)}")
+        url = "#{BASE}?cas_rn=#{CGI.escape(value.to_s)}"
+        url = "#{url}&apikey=#{CGI.escape(api_key)}" if api_key
+        body = fetch.get(url)
         return nil unless body
 
         data = JSON.parse(body)

data/lib/asciichem/resolver.rb

@@ -43,16 +43,23 @@ module AsciiChem
         raise Error, "unknown resolver source #{name.inspect} (registered: #{adapters.keys.sort.join(', ')})"
       end
 
-      # Resolves against every opt-in source, returning one Substance
-      # per source that answers (nil entries dropped). Sources answer
-      # in registration order.
+      # Resolves against every registered source (or the selected
+      # subset), returning one Substance per source that answers (nil
+      # entries dropped). Sources answer in registration order. A
+      # source-level failure (HTTP error, rejected request) skips that
+      # source — one dead or key-gated endpoint must not poison the
+      # others; callers see what answered.
       def resolve_all(value:, convention:, sources: nil, fetch: nil, cache: nil, refresh: false)
         selected = sources ? Array(sources).map { |s| self[s] } : adapters.values
         selected.filter_map do |adapter_class|
           adapter = adapter_class.new
           next unless adapter.supports?(convention)
 
-          adapter.resolve(value: value, convention: convention, fetch: fetch, cache: cache, refresh: refresh)
+          begin
+            adapter.resolve(value: value, convention: convention, fetch: fetch, cache: cache, refresh: refresh)
+          rescue AsciiChem::Error
+            nil
+          end
         end
       end
 

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.31.12"
+  VERSION = "0.31.14"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.31.12
+  version: 0.31.14
 platform: ruby
 authors:
 - Ribose Inc.