openphar 0.1.0

data/lib/openphar/models/base_entity.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    # Base entity class for all pharmacopoeia models.
+    #
+    # Provides model-centric serialization methods where the model IS the schema.
+    # Each model knows how to serialize itself to:
+    # - Neo4j (to_neo4j, to_cypher)
+    # - JSON-LD (to_jsonld)
+    #
+    # Subclasses should override:
+    # - neo4j_labels: Array of Neo4j labels
+    # - jsonld_type: The @type value for JSON-LD
+    #
+    # @example
+    #   class MyMonograph < BaseEntity
+    #     attribute :name, :string
+    #
+    #     def self.neo4j_labels
+    #       ['Monograph', 'MyType']
+    #     end
+    #
+    #     def self.jsonld_type
+    #       'MyMonograph'
+    #     end
+    #   end
+    class BaseEntity < Lutaml::Model::Serializable
+      # Common attributes for all entities
+      attribute :id, :string
+
+      json do
+        map '@id', to: :id
+      end
+
+      class << self
+        # Returns Neo4j labels for this entity type.
+        # Override in subclasses to specify custom labels.
+        #
+        # @return [Array<String>] Neo4j node labels
+        def neo4j_labels
+          ['Entity']
+        end
+
+        # Returns the primary Neo4j label (first in the list).
+        #
+        # @return [String] Primary Neo4j label
+        def neo4j_label
+          neo4j_labels.first
+        end
+
+        # Returns Neo4j label string for Cypher (e.g., "Monograph:CrudeDrug").
+        #
+        # @return [String] Colon-separated labels
+        def neo4j_labels_string
+          neo4j_labels.join(':')
+        end
+
+        # Returns the JSON-LD @type for this entity.
+        # Override in subclasses.
+        #
+        # @return [String] JSON-LD type
+        def jsonld_type
+          name&.split('::')&.last || 'Entity'
+        end
+
+        # Returns the JSON-LD context for this entity.
+        #
+        # @return [String] Context URL
+        def jsonld_context
+          'https://www.openphar.org/ontology/context/pharmacopoeia.jsonld'
+        end
+      end
+
+      # Returns a hash representation for Neo4j node.
+      #
+      # @return [Hash] Node data with id, labels, and properties
+      def to_neo4j_node
+        {
+          id: id,
+          labels: self.class.neo4j_labels,
+          properties: to_neo4j_properties
+        }
+      end
+
+      # Converts model attributes to Neo4j-compatible properties.
+      #
+      # @return [Hash] Neo4j properties
+      def to_neo4j_properties
+        properties = {}
+
+        self.class.attributes.each_key do |attr_name|
+          value = send(attr_name)
+          next if value.nil?
+
+          prop_name = neo4j_property_name(attr_name)
+          properties[prop_name] = neo4j_property_value(value)
+        end
+
+        properties
+      end
+
+      # Returns a JSON-LD representation of this entity.
+      #
+      # @return [Hash] JSON-LD data
+      def to_jsonld
+        data = {
+          '@id' => id,
+          '@type' => self.class.jsonld_type,
+          '@context' => self.class.jsonld_context
+        }
+
+        # Add all attributes except id (already included)
+        self.class.attributes.each_key do |attr_name|
+          next if attr_name == :id
+
+          value = send(attr_name)
+          next if value.nil?
+
+          json_key = jsonld_property_name(attr_name)
+          data[json_key] = value
+        end
+
+        data
+      end
+
+      # Generates a Cypher CREATE or MERGE statement for this entity.
+      #
+      # @param use_merge [Boolean] Use MERGE instead of CREATE
+      # @param variable [String] Cypher variable name (default: 'n')
+      # @return [String] Cypher statement
+      def to_cypher(use_merge: false, variable: 'n')
+        keyword = use_merge ? 'MERGE' : 'CREATE'
+        node = to_neo4j_node
+        labels = node[:labels].join(':')
+        props = cypher_properties_string(node[:properties])
+
+        "#{keyword} (#{variable}:#{labels} {#{props}})"
+      end
+
+      # Generates a Cypher MATCH statement for finding this entity.
+      #
+      # @param variable [String] Cypher variable name
+      # @return [String] Cypher MATCH statement
+      def to_cypher_match(variable: 'n')
+        labels = self.class.neo4j_labels_string
+        "MATCH (#{variable}:#{labels} {id: '#{id}'})"
+      end
+
+      private
+
+      # Converts attribute name to Neo4j property name.
+      #
+      # @param name [Symbol] Attribute name
+      # @return [String] Neo4j property name
+      def neo4j_property_name(name)
+        # Convert snake_case to camelCase for Neo4j
+        name.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+      end
+
+      # Converts attribute name to JSON-LD property name.
+      #
+      # @param name [Symbol] Attribute name
+      # @return [String] JSON-LD property name
+      def jsonld_property_name(name)
+        # Use camelCase for JSON-LD properties
+        neo4j_property_name(name)
+      end
+
+      # Converts a value to Neo4j-compatible format.
+      #
+      # @param value [Object] The value to convert
+      # @return [Object] Neo4j-compatible value
+      def neo4j_property_value(value)
+        case value
+        when Hash
+          value.to_json
+        when Array
+          value.map { |v| neo4j_property_value(v) }
+        when Lutaml::Model::Serializable
+          value.id || value.to_s
+        else
+          value
+        end
+      end
+
+      # Formats properties as Cypher property string.
+      #
+      # @param properties [Hash] Properties hash
+      # @return [String] Cypher property string
+      def cypher_properties_string(properties)
+        properties.map do |key, value|
+          "#{key}: #{cypher_escape_value(value)}"
+        end.join(', ')
+      end
+
+      # Escapes a value for Cypher.
+      #
+      # @param value [Object] The value to escape
+      # @return [String] Escaped Cypher value
+      def cypher_escape_value(value)
+        case value
+        when String
+          "'#{value.gsub("'", "\\'")}'"
+        when NilClass
+          'null'
+        when TrueClass, FalseClass
+          value.to_s
+        when Numeric
+          value.to_s
+        when Array
+          "[#{value.map { |v| cypher_escape_value(v) }.join(', ')}]"
+        when Hash
+          "'#{value.to_json.gsub("'", "\\'")}'"
+        else
+          "'#{value.to_s.gsub("'", "\\'")}'"
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/biological_substance_monograph.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    # Represents a biological substance monograph
+    #
+    # Biological substances are derived from living organisms or
+    # produced by biotechnology methods.
+    class BiologicalSubstanceMonograph < Monograph
+      attribute :biological_source, :hash, default: {}
+      attribute :production_method, :string
+      attribute :potency, :string
+
+      json do
+        map 'biologicalSource', to: :biological_source
+        map 'productionMethod', to: :production_method
+        map 'potency', to: :potency
+      end
+
+      class << self
+        def neo4j_labels
+          %w[Monograph Biological]
+        end
+
+        def jsonld_type
+          'BiologicalSubstanceMonograph'
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chemical_drug_monograph.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    # Represents a chemical drug monograph
+    #
+    # Chemical drugs are synthesized or purified chemical compounds
+    # with defined molecular structures.
+    class ChemicalDrugMonograph < Monograph
+      attribute :molecular_formula, :string
+      attribute :molecular_weight, :decimal
+      attribute :cas_number, :string
+      attribute :systematic_name, :hash, default: {}
+      attribute :inchi, :string
+      attribute :inchi_key, :string
+      attribute :smiles, :string
+
+      json do
+        map 'molecularFormula', to: :molecular_formula
+        map 'molecularWeight', to: :molecular_weight
+        map 'casNumber', to: :cas_number
+        map 'systematicName', to: :systematic_name
+        map 'inchi', to: :inchi
+        map 'inchiKey', to: :inchi_key
+        map 'smiles', to: :smiles
+      end
+
+      class << self
+        def neo4j_labels
+          %w[Monograph ChemicalDrug]
+        end
+
+        def jsonld_type
+          'ChemicalDrugMonograph'
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/biologic.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # Biologic — 生物制品 (Vol III).
+      #
+      # Vaccines, blood products, recombinant proteins, cell therapies, etc.
+      # Maps to the cross-publisher BiologicalSubstance concept.
+      #
+      class Biologic < Monograph
+        class << self
+          def wire_key
+            'biologic'
+          end
+
+          def harmonized_type
+            'BiologicalSubstance'
+          end
+
+          def jsonld_type
+            'ChpBiologic'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/chemical_preparation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # Chemical preparation — 品种正文 第二部分 (Vol II).
+      #
+      # Finished chemical drug products (tablets, injections, etc.). Maps
+      # to the cross-publisher Formulation concept.
+      #
+      class ChemicalPreparation < Monograph
+        class << self
+          def wire_key
+            'chemical_preparation'
+          end
+
+          def harmonized_type
+            'Formulation'
+          end
+
+          def jsonld_type
+            'ChpChemicalPreparation'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/chemical_substance.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # Chemical substance — 品种正文 第一部分 (Vol II).
+      #
+      # Drug substances (APIs) of chemical origin. Maps to the cross-publisher
+      # ChemicalDrug concept.
+      #
+      class ChemicalSubstance < Monograph
+        class << self
+          def wire_key
+            'chemical_substance'
+          end
+
+          def harmonized_type
+            'ChemicalDrug'
+          end
+
+          def jsonld_type
+            'ChpChemicalSubstance'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/general_chapter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # General chapter — 通则/制剂通则/凡例/指导原则 (Vol IV).
+      #
+      # General notices, analytical methods (通则 0100–9900), guiding
+      # principles (9000 series), reagent/test-solution definitions, etc.
+      # No harmonized equivalent in other pharmacopoeias (publisher-specific
+      # structural unit).
+      #
+      class GeneralChapter < Monograph
+        class << self
+          def wire_key
+            'general_chapter'
+          end
+
+          def harmonized_type
+            nil
+          end
+
+          def jsonld_type
+            'ChpGeneralChapter'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/monograph.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # Base class for all Chinese Pharmacopoeia monographs.
+      #
+      # Adds ChP-specific identity fields (entryId from the network-edition
+      # API, bookId 1..4 for volumes I–IV, directoryTitle for the TOC node,
+      # pageNum for the printed-edition cross-reference, pinyin title) on
+      # top of the harmonized Openphar::Models::Monograph.
+      #
+      # Concrete subclasses (TcmCrudeDrug, ChemicalSubstance, Biologic,
+      # GeneralChapter, etc.) declare their semantic @type via class methods.
+      # The classifier at Openphar::Migrators::Chp::Classifier is the
+      # single dispatch point — never use `case/when` on type elsewhere.
+      #
+      class Monograph < Openphar::Models::Monograph
+        attribute :entry_id, :integer
+        attribute :book_id, :integer
+        attribute :book_name, :string
+        attribute :directory_id, :integer
+        attribute :directory_title, :string
+        attribute :title, :string
+        attribute :page_num, :integer
+        attribute :pinyin_title, :string
+        attribute :e_title, :string
+        attribute :html_content, :string
+        attribute :part_titles, :string, collection: true, default: []
+        attribute :sections, Section, collection: true, default: []
+        attribute :visit_count, :integer
+        attribute :edition, :string
+        attribute :fetched_at, :string
+
+        json do
+          map 'entryId', to: :entry_id
+          map 'bookId', to: :book_id
+          map 'bookName', to: :book_name
+          map 'directoryId', to: :directory_id
+          map 'directoryTitle', to: :directory_title
+          map 'title', to: :title
+          map 'pageNum', to: :page_num
+          map 'pinyinTitle', to: :pinyin_title
+          map 'eTitle', to: :e_title
+          map 'htmlContent', to: :html_content
+          map 'partTitle', to: :part_titles
+          map 'section', to: :sections
+          map 'visitCount', to: :visit_count
+          map 'edition', to: :edition
+          map 'fetchedAt', to: :fetched_at
+        end
+
+        class << self
+          # Snake_case identifier used as the JSON-LD node-directory name
+          # and as the wire-key for type routing. Override in subclasses.
+          #
+          # @return [String]
+          def wire_key
+            'monograph'
+          end
+
+          # Harmonized RDF type this ChP type maps to. Override in subclasses
+          # to declare the cross-publisher semantic type (e.g., 'CrudeDrug').
+          #
+          # @return [String, nil]
+          def harmonized_type
+            nil
+          end
+
+          # Array of types to emit in JSON-LD @type. Computed from
+          # jsonld_type + harmonized_type + the base 'Monograph'.
+          #
+          # @return [Array<String>]
+          def jsonld_types
+            types = ['Monograph']
+            types << harmonized_type if harmonized_type
+            types << jsonld_type unless jsonld_type == 'Monograph'
+            types.uniq
+          end
+
+          def neo4j_labels
+            labels = %w[Monograph Chp]
+            labels << harmonized_type if harmonized_type
+            labels << name&.split('::')&.last
+            labels.compact.uniq
+          end
+
+          def jsonld_type
+            'ChpMonograph'
+          end
+        end
+
+        def slug
+          base = (pinyin_title || title || "entry-#{entry_id}")
+            .to_s
+            .downcase
+            .gsub(/\s+/, '-')
+            .gsub(/[^\p{L}\p{N}\-]/, '')
+            .gsub(/\-+/, '-')
+            .gsub(/^\-|\-$/, '')
+          base = "entry-#{entry_id}" if base.empty?
+          "#{base}-#{entry_id}"
+        end
+
+        def iri
+          edition_tag = (edition || 'unknown').to_s.downcase.gsub(/[^a-z0-9]/, '-')
+          "#{Openphar.base_iri}/data/chp/#{edition_tag}/entry/#{entry_id}"
+        end
+
+        def jsonld_filename
+          "#{slug}.jsonld"
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/section.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # Section within a ChP monograph.
+      #
+      # ChP monographs are structured by 【X】 headings (e.g., 【性状】,
+      # 【鉴别】, 【检查】). Each monograph has an ordered list of sections
+      # carrying the heading name + the HTML body + a plain-text rendering.
+      #
+      class Section < Openphar::Models::BaseEntity
+        attribute :name, :string
+        attribute :sequence, :integer
+        attribute :html_content, :string
+        attribute :text_content, :string
+
+        json do
+          map 'sectionName', to: :name
+          map 'sequence', to: :sequence
+          map 'htmlContent', to: :html_content
+          map 'textContent', to: :text_content
+        end
+
+        class << self
+          def neo4j_labels
+            %w[Section ChpSection]
+          end
+
+          def jsonld_type
+            'ChpSection'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/tcm_crude_drug.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # TCM crude drug — 药材和饮片 (Vol I).
+      #
+      # Crude drugs and their decoction pieces. Maps harmonically to the
+      # cross-publisher CrudeDrug concept.
+      #
+      class TcmCrudeDrug < Monograph
+        class << self
+          def wire_key
+            'tcm_crude_drug'
+          end
+
+          def harmonized_type
+            'CrudeDrug'
+          end
+
+          def jsonld_type
+            'TcmCrudeDrug'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/tcm_extract.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # TCM extract — 植物油脂和提取物 (Vol I).
+      #
+      # Processed plant extracts and fixed oils. Semantically a sub-type of
+      # crude drug (processed form) but kept distinct at the ChP layer for
+      # routing fidelity.
+      #
+      class TcmExtract < Monograph
+        class << self
+          def wire_key
+            'tcm_extract'
+          end
+
+          def harmonized_type
+            'CrudeDrug'
+          end
+
+          def jsonld_type
+            'TcmExtract'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp/tcm_formulation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    module Chp
+      # TCM formulation — 成方制剂和单味制剂 (Vol I).
+      #
+      # Classical TCM formulas and single-herb preparations. Maps to the
+      # cross-publisher Formulation concept.
+      #
+      class TcmFormulation < Monograph
+        class << self
+          def wire_key
+            'tcm_formulation'
+          end
+
+          def harmonized_type
+            'Formulation'
+          end
+
+          def jsonld_type
+            'TcmFormulation'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openphar/models/chp.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Openphar
+  module Models
+    # Chinese Pharmacopoeia (ChP) specific models.
+    #
+    # Contains models unique to the Chinese Pharmacopoeia:
+    # - TCM crude drugs (药材和饮片)
+    # - TCM extracts (植物油脂和提取物)
+    # - TCM formulations (成方制剂和单味制剂)
+    # - Chemical substances (品种正文 第一部分)
+    # - Chemical preparations (品种正文 第二部分)
+    # - Biologics (生物制品)
+    # - General chapters (通则/制剂通则/凡例 etc.)
+    #
+    # @example
+    #   Openphar::Models::Chp::TcmCrudeDrug
+    #   Openphar::Models::Chp::ChemicalSubstance
+    #
+    # @see https://2025.chp.org.cn
+    module Chp
+      autoload :Monograph, 'openphar/models/chp/monograph'
+      autoload :Section, 'openphar/models/chp/section'
+      autoload :TcmCrudeDrug, 'openphar/models/chp/tcm_crude_drug'
+      autoload :TcmExtract, 'openphar/models/chp/tcm_extract'
+      autoload :TcmFormulation, 'openphar/models/chp/tcm_formulation'
+      autoload :ChemicalSubstance, 'openphar/models/chp/chemical_substance'
+      autoload :ChemicalPreparation, 'openphar/models/chp/chemical_preparation'
+      autoload :Biologic, 'openphar/models/chp/biologic'
+      autoload :GeneralChapter, 'openphar/models/chp/general_chapter'
+    end
+  end
+end