simple_inline_text_annotation 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 725fe23d9066db1aa1846efc6699a8973991cef8a613c8d89b82c5794202fd60
-  data.tar.gz: c2a8671106444d868a1100bd9c07d4ce88c0693d5fb458e8589cbc8a46e1c4af
+  metadata.gz: 54b2eb70ade1f40cc7c1d576c6992dc8dbba0452e95a879e51d090229bcf5011
+  data.tar.gz: c2730f877c0e6e07b06d6f011160ad29e45fce0ce9c7e6c8a4e2b0e004b5499b
 SHA512:
-  metadata.gz: 0c2a831a71afa277bc4703b0c3c7f2f5580750003fb9dd9b7997af76b0761e19fc31f05b643578c7298f281930e6253af5bc1c87c911932bd673cd003591d2b9
-  data.tar.gz: db3c7bf4f78a34e314a173a7eece62aa43222c7f103197e2519dfe27dca4da067afcfc4541756f3655289e4fa64764d117a4e3eaff615b58e6931766bd24842c
+  metadata.gz: 0ef5000debc433f0013102d5dbec539624f437028a5cdbe3e1cfa3351c7de59c2a0a5d284dfbffdf197c9db0f05a131d42daff7301fbf78ae4ffab9488add300
+  data.tar.gz: 4008f849ba4493b9ecf85596a755d7d952c609a64e7a92a4a9d38222494778a675ddf35f32e0330bce3a29765e1147628686e74314f64a3012d2c4283bbd2967

data/README.md

@@ -1,43 +1,162 @@
-# SimpleInlineTextAnnotation
+# SimpleInlineTextAnnotation (Ruby gem)
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/simple_inline_text_annotation`. To experiment with that code, run `bin/console` for an interactive prompt.
+`SimpleInlineTextAnnotation` is a Ruby gem designed for working with inline text annotations. It allows you to parse and generate annotated text in a structured and efficient way.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
+To use this gem in a Rails application, add the following line to your application's `Gemfile`:
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'simple_inline_text_annotation'
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Then, run the following command to install the gem:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+The `SimpleInlineTextAnnotation` gem provides two main methods: `parse` and `generate`. These methods allow you to work with inline text annotations in a structured way.
+
+### `parse` Method
 
-## Development
+The `parse` method takes a string with inline annotations and extracts structured information about the annotations, including the character positions and annotation types.
+
+#### Example
+
+```ruby
+result = SimpleInlineTextAnnotation.parse('[Elon Musk][Person] is a member of the [PayPal Mafia][Organization].')
+puts result
+# => {
+#      text: "Elon Musk is a member of the PayPal Mafia.",
+#      denotations: [
+#        {span: {begin: 0, end: 9}, obj: "Person"},
+#        {span: {begin: 29, end: 41}, obj: "Organization"}
+#      ]
+#    }
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+#### Explanation
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- The input string `[Elon Musk][Person] is a member of the [PayPal Mafia][Organization].` contains two annotations:
+  1. `[Elon Musk][Person]`: The text `Elon Musk` is annotated as `Person`.
+  2. `[PayPal Mafia][Organization]`: The text `PayPal Mafia` is annotated as `Organization`.
 
-## Contributing
+- The method returns a hash with:
+  - `"text"`: The plain text without annotations.
+  - `"denotations"`: An array of hashes, where each hash contains:
+    - `"span"`: The character positions (`begin` and `end`) of the annotated text.
+    - `"obj"`: The annotation type.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/simple_inline_text_annotation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/simple_inline_text_annotation/blob/main/CODE_OF_CONDUCT.md).
+### `generate` Method
 
-## License
+The `generate` method performs the reverse operation of `parse`. It takes a hash containing the plain text and its annotations, and generates a string with inline annotations.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+#### Example
+
+```ruby
+result = SimpleInlineTextAnnotation.generate({
+  "text" => "Elon Musk is a member of the PayPal Mafia.",
+  "denotations" => [
+    { "span" => { "begin" => 0, "end" => 9 }, "obj" => "Person" },
+    { "span" => { "begin" => 29, "end" => 41 }, "obj" => "Organization" }
+  ]
+})
+puts result
+# => "[Elon Musk][Person] is a member of the [PayPal Mafia][Organization]."
+```
+
+#### Explanation
+
+- The input hash contains:
+  - `"text"`: The plain text (`"Elon Musk is a member of the PayPal Mafia."`).
+  - `"denotations"`: An array of hashes, where each hash specifies:
+    - `"span"`: The character positions (`begin` and `end`) of the annotated text.
+    - `"obj"`: The annotation type.
+- The method generates a string where:
+  - The text specified in `"span"` is enclosed in square brackets `[]`.
+  - The annotation type specified in `"obj"` is added in a second set of square brackets `[]`.
+
+## Relation Annotation
+
+The `SimpleInlineTextAnnotation` gem supports advanced relation annotation, allowing you to define relationships between annotated entities. This is achieved by interpreting the second set of square brackets (`[]`) based on the number of elements it contains.
+
+#### Parsing Rules
+
+- If the second `[]` contains **1 element**, it is treated as the annotation type (default behavior).
+- If the second `[]` contains **2 elements**, the first element is interpreted as the `id` of the denotation, and the second element as the `obj` (annotation type).
+- If the second `[]` contains **4 elements**, the elements are interpreted as follows:
+  1. The first element is the `id` of the denotation and the `subj` of the relation.
+  2. The second element is the `obj` (annotation type) of the denotation.
+  3. The third element is the `pred` (predicate) of the relation.
+  4. The fourth element is the `obj` of the relation.
+- Any other cases are ignored.
+
+### Example
+
+```ruby
+source = "[Elon Musk][T1, Person, member_of, T2] is a member of the [PayPal Mafia][T2, Organization]."
+result = SimpleInlineTextAnnotation.parse(source)
+puts result
+# => {
+#      text: "Elon Musk is a member of the PayPal Mafia.",
+#      denotations: [
+#        { id: "T1", span: { begin: 0, end: 9 }, obj: "Person" },
+#        { id: "T2", span: { begin: 29, end: 41 }, obj: "Organization" }
+#      ],
+#      relations: [
+#        { pred: "member_of", subj: "T1", obj: "T2" }
+#      ]
+#    }
+```
+
+### Explanation
+
+- The input string `[Elon Musk][T1, Person, member_of, T2] is a member of the [PayPal Mafia][T2, Organization].` contains:
+  1. Two denotations:
+     - `[Elon Musk][T1, Person, member_of, T2]`: The text `Elon Musk` is annotated as `Person` with `id` `T1`. It also serves as the `subj` of the relation.
+     - `[PayPal Mafia][T2, Organization]`: The text `PayPal Mafia` is annotated as `Organization` with `id` `T2`.
+  2. One relation:
+     - `member_of`: Indicates that `T1` (`Elon Musk`) is a member of `T2` (`PayPal Mafia`).
+
+- The method returns a hash with:
+  - `"text"`: The plain text without annotations.
+  - `"denotations"`: An array of hashes, where each hash contains:
+    - `"id"`: The unique identifier of the denotation.
+    - `"span"`: The character positions (`begin` and `end`) of the annotated text.
+    - `"obj"`: The annotation type.
+  - `"relations"`: An array of hashes, where each hash contains:
+    - `"pred"`: The predicate or type of the relation.
+    - `"subj"`: The `id` of the subject denotation.
+    - `"obj"`: The `id` of the object denotation.
+
+### Generating Relation Annotation
+
+The `generate` method can also create strings with relation annotations from structured data.
+
+```ruby
+result = SimpleInlineTextAnnotation.generate({
+  "text" => "Elon Musk is a member of the PayPal Mafia.",
+  "denotations" => [
+    { "id" => "T1", "span" => { "begin" => 0, "end" => 9 }, "obj" => "Person" },
+    { "id" => "T2", "span" => { "begin" => 29, "end" => 41 }, "obj" => "Organization" }
+  ],
+  "relations" => [
+    { "pred" => "member_of", "subj" => "T1", "obj" => "T2" }
+  ]
+})
+puts result
+# => "[Elon Musk][T1, Person, member_of, T2] is a member of the [PayPal Mafia][T2, Organization]."
+```
 
-## Code of Conduct
+#### Explanation
 
-Everyone interacting in the SimpleInlineTextAnnotation project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/simple_inline_text_annotation/blob/main/CODE_OF_CONDUCT.md).
+- The input hash includes:
+  - `"text"`: The plain text.
+  - `"denotations"`: An array of annotations with `id`, `span`, and `obj`.
+  - `"relations"`: An array of relationships, where:
+    - `"subj"` and `"obj"` reference `id`s in the `denotations` array.
+    - `"pred"` specifies the relationship type.
+- The method generates a string with inline annotations and relationships.

data/lib/simple_inline_text_annotation/denotation.rb

@@ -5,12 +5,13 @@ require_relative "generator_error"
 
 class SimpleInlineTextAnnotation
   class Denotation
-    attr_reader :begin_pos, :end_pos, :obj
+    attr_reader :begin_pos, :end_pos, :obj, :id
 
-    def initialize(begin_pos, end_pos, obj)
+    def initialize(begin_pos, end_pos, obj, id = nil)
       @begin_pos = begin_pos
       @end_pos = end_pos
       @obj = obj
+      @id = id
     end
 
     def span
@@ -18,7 +19,7 @@ class SimpleInlineTextAnnotation
     end
 
     def to_h
-      { span: span, obj: @obj }
+      { id: @id, span: span, obj: @obj }.compact
     end
 
     def nested_within?(other)

data/lib/simple_inline_text_annotation/denotation_validator.rb

@@ -2,7 +2,7 @@
 
 class SimpleInlineTextAnnotation
   module DenotationValidator
-    def validate(denotations, text_length)
+    def validate_denotations(denotations, text_length)
       result = remove_duplicates_from(denotations)
       result = remove_non_integer_positions_from(result)
       result = remove_negative_positions_from(result)

data/lib/simple_inline_text_annotation/entity_type_collection.rb

@@ -6,6 +6,13 @@ class SimpleInlineTextAnnotation
       @source = source
     end
 
+    # get returns the entity type id for a given label.
+    # Example:
+    #   get("Person") => "https://example.com/Person"
+    #
+    # If the label is not found, it returns nil.
+    # Example:
+    #   get("NonExistentLabel") => nil
     def get(label)
       entity_types[label]
     end

data/lib/simple_inline_text_annotation/generator.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "denotation"
+require_relative "relation_validator"
 
 class SimpleInlineTextAnnotation
   class Generator
     include DenotationValidator
+    include RelationValidator
 
     def initialize(source)
       @source = source.dup.freeze
@@ -16,9 +18,10 @@ class SimpleInlineTextAnnotation
       text = @source["text"]
       raise SimpleInlineTextAnnotation::GeneratorError, 'The "text" key is missing.' if text.nil?
 
-      denotations = validate(@denotations, text.length)
+      denotations = validate_denotations(@denotations, text.length)
+      relations = validate_relations(@source["relations"] || [])
 
-      annotated_text = annotate_text(text, denotations)
+      annotated_text = annotate_text(text, denotations, relations)
       label_definitions = build_label_definitions
 
       [annotated_text, label_definitions].compact.join("\n\n")
@@ -27,29 +30,47 @@ class SimpleInlineTextAnnotation
     private
 
     def build_denotations(denotations)
-      denotations.map { |d| Denotation.new(d["span"]["begin"], d["span"]["end"], d["obj"]) }
+      denotations.map { |d| Denotation.new(d["span"]["begin"], d["span"]["end"], d["obj"], d["id"]) }
     end
 
-    def annotate_text(text, denotations)
+    def annotate_text(text, denotations, relations)
       # Annotate text from the end to ensure position calculation.
       denotations.sort_by(&:begin_pos).reverse_each do |denotation|
-        begin_pos = denotation.begin_pos
-        end_pos = denotation.end_pos
-        obj = get_obj(denotation.obj)
-
-        annotated_text = "[#{text[begin_pos...end_pos]}][#{obj}]"
-        text = text[0...begin_pos] + annotated_text + text[end_pos..]
+        text = annotate_text_with_denotation(text, denotation, relations)
       end
 
       text
     end
 
+    def annotate_text_with_denotation(text, denotation, relations)
+      begin_pos = denotation.begin_pos
+      end_pos = denotation.end_pos
+      annotation = if denotation.id && !denotation.id.empty?
+                     get_annotations(denotation, relations)
+                   else
+                     get_obj(denotation.obj)
+                   end
+
+      annotated_text = "[#{text[begin_pos...end_pos]}][#{annotation}]"
+      text[0...begin_pos] + annotated_text + text[end_pos..]
+    end
+
     def labeled_entity_types
       return nil unless @config
 
       @config["entity types"]&.select { |entity_type| entity_type.key?("label") }
     end
 
+    def get_annotations(denotation, relations)
+      relation = relations.find { |rel| rel["subj"] == denotation.id }
+      annotations = [denotation.id, denotation.obj, relation&.dig("pred"), relation&.dig("obj")]
+
+      return annotations.compact.join(", ") unless labeled_entity_types
+
+      annotations[1] = get_obj(denotation.obj)
+      annotations.compact.join(", ")
+    end
+
     def get_obj(obj)
       return obj unless labeled_entity_types
 

data/lib/simple_inline_text_annotation/parser.rb

@@ -7,22 +7,24 @@ class SimpleInlineTextAnnotation
   class Parser
     # DENOTATION_PATTERN matches two consecutive pairs of square brackets.
     # Example: [Annotated Text][Label]
-    DENOTATION_PATTERN = /(?<!\\)\[([^\[]+?)\]\[([^\]]+?)\]/
+    ANNOTATION_PATTERN = /(?<!\\)\[([^\[]+?)\]\[([^\]]+?)\]/
 
     def initialize(source)
       @source = source.dup.freeze
-      @denotations = []
       @entity_type_collection = EntityTypeCollection.new(source)
     end
 
     def parse
+      @denotations = []
+      @relations = []
       full_text = source_without_references
 
-      process_denotations(full_text)
+      process_annotations(full_text)
 
       SimpleInlineTextAnnotation.new(
         full_text,
         @denotations,
+        @relations,
         @entity_type_collection
       )
     end
@@ -40,25 +42,54 @@ class SimpleInlineTextAnnotation
       @entity_type_collection.get(label) || label
     end
 
-    def process_denotations(full_text)
-      while full_text =~ DENOTATION_PATTERN
-        match = Regexp.last_match
-        process_single_denotation(match, full_text)
+    def process_annotations(full_text)
+      current_pos = 0
+
+      while (match = ANNOTATION_PATTERN.match(full_text, current_pos))
+        current_pos = process_annotation_and_update_position(match, full_text)
       end
     end
 
-    def process_single_denotation(match, full_text)
+    def process_annotation_and_update_position(match, full_text)
       target_text = match[1]
-      label = match[2]
-
       begin_pos = match.begin(0)
       end_pos = begin_pos + target_text.length
-      obj = get_obj_for(label)
 
-      @denotations << Denotation.new(begin_pos, end_pos, obj)
+      return match.end(0) unless process_annotation(match[2], begin_pos, end_pos)
 
-      # Replace the processed annotation with its text content
       full_text[match.begin(0)...match.end(0)] = target_text
+      end_pos
+    end
+
+    def process_annotation(annotations, begin_pos, end_pos)
+      annotations_array = annotations.split(", ")
+
+      case annotations_array.size
+      when 1
+        process_denotation(begin_pos, end_pos, annotations_array[0])
+      when 2
+        process_denotation_with_id(begin_pos, end_pos, annotations_array)
+      when 4
+        process_denotation_and_relation(begin_pos, end_pos, annotations_array)
+      end
+    end
+
+    def process_denotation(begin_pos, end_pos, label)
+      obj = get_obj_for(label)
+      @denotations << Denotation.new(begin_pos, end_pos, obj)
+    end
+
+    def process_denotation_with_id(begin_pos, end_pos, annotations)
+      id, label = annotations
+      obj = get_obj_for(label)
+      @denotations << Denotation.new(begin_pos, end_pos, obj, id)
+    end
+
+    def process_denotation_and_relation(begin_pos, end_pos, annotations)
+      subj, label, pred, obj2 = annotations
+      obj = get_obj_for(label)
+      @denotations << Denotation.new(begin_pos, end_pos, obj, subj)
+      @relations << { pred: pred, subj: subj, obj: obj2 }
     end
   end
 end

data/lib/simple_inline_text_annotation/relation_validator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class SimpleInlineTextAnnotation
+  module RelationValidator
+    def validate_relations(relations)
+      remove_incomplete_key_relations(relations)
+    end
+
+    private
+
+    def remove_incomplete_key_relations(relations)
+      relations.select { |relation| relation["subj"] && relation["pred"] && relation["obj"] }
+    end
+  end
+end

data/lib/simple_inline_text_annotation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class SimpleInlineTextAnnotation
-  VERSION = "0.1.0"
+  VERSION = "1.1.0"
 end

data/lib/simple_inline_text_annotation.rb

@@ -20,9 +20,10 @@ class SimpleInlineTextAnnotation
   # Example: \[This is a part of][original text]
   ESCAPE_PATTERN = /\\(?=\[[^\]]+\]\[[^\]]+\])/
 
-  def initialize(text, denotations, entity_type_collection)
+  def initialize(text, denotations, relations, entity_type_collection)
     @text = text
     @denotations = denotations
+    @relations = relations
     @entity_type_collection = entity_type_collection
   end
 
@@ -39,6 +40,7 @@ class SimpleInlineTextAnnotation
     {
       text: format_text(@text),
       denotations: @denotations.map(&:to_h),
+      relations: @relations.empty? ? nil : @relations,
       config: config
     }.compact
   end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_inline_text_annotation
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - xaiBUh29wX
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-03 00:00:00.000000000 Z
+date: 2025-05-08 00:00:00.000000000 Z
 dependencies: []
 description: This gem provides inline text annotation functionality, extracted from
   PubAnnotation, with support for denotations, entity types, and nested spans.
@@ -31,6 +32,7 @@ files:
 - lib/simple_inline_text_annotation/generator.rb
 - lib/simple_inline_text_annotation/generator_error.rb
 - lib/simple_inline_text_annotation/parser.rb
+- lib/simple_inline_text_annotation/relation_validator.rb
 - lib/simple_inline_text_annotation/version.rb
 - sig/simple_inline_text_annotation.rbs
 homepage: https://github.com/Tamada-Arino/simple-inline-text-annotation
@@ -39,6 +41,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/Tamada-Arino/simple-inline-text-annotation
   changelog_uri: https://github.com/Tamada-Arino/simple-inline-text-annotation/blob/master/CHANGELOG.md
+  rubygems_uri: https://rubygems.org/gems/simple_inline_text_annotation
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -53,7 +57,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.4.20
+signing_key:
 specification_version: 4
 summary: A Ruby gem for inline text annotation with denotations and entity types.
 test_files: []