llm-ie 1.2.2__tar.gz → 1.2.4__tar.gz

{llm_ie-1.2.2 → llm_ie-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: llm-ie
-Version: 1.2.2
+Version: 1.2.4
 Summary: A comprehensive toolkit that provides building blocks for LLM-based named entity recognition, attribute extraction, and relation extraction pipelines.
 License: MIT
 Author: Enshuo (David) Hsu

{llm_ie-1.2.2 → llm_ie-1.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "llm-ie"
-version = "1.2.2"
+version = "1.2.4"
 description = "A comprehensive toolkit that provides building blocks for LLM-based named entity recognition, attribute extraction, and relation extraction pipelines."
 authors = ["Enshuo (David) Hsu"]
 license = "MIT"

{llm_ie-1.2.2 → llm_ie-1.2.4}/src/llm_ie/__init__.py

@@ -1,11 +1,12 @@
 from .data_types import LLMInformationExtractionFrame, LLMInformationExtractionDocument
-from .engines import BasicLLMConfig, ReasoningLLMConfig, Qwen3LLMConfig, OpenAIReasoningLLMConfig, LlamaCppInferenceEngine, OllamaInferenceEngine, HuggingFaceHubInferenceEngine, OpenAIInferenceEngine, AzureOpenAIInferenceEngine, LiteLLMInferenceEngine
+from .engines import BasicLLMConfig, ReasoningLLMConfig, Qwen3LLMConfig, OpenAIReasoningLLMConfig 
+from .engines import LlamaCppInferenceEngine, OllamaInferenceEngine, HuggingFaceHubInferenceEngine, VLLMInferenceEngine, SGLangInferenceEngine, OpenRouterInferenceEngine, OpenAIInferenceEngine, AzureOpenAIInferenceEngine, LiteLLMInferenceEngine
 from .extractors import DirectFrameExtractor, ReviewFrameExtractor, BasicFrameExtractor, BasicReviewFrameExtractor, SentenceFrameExtractor, SentenceReviewFrameExtractor, AttributeExtractor, BinaryRelationExtractor, MultiClassRelationExtractor
-from .chunkers import UnitChunker, WholeDocumentUnitChunker, SentenceUnitChunker, TextLineUnitChunker, ContextChunker, NoContextChunker, WholeDocumentContextChunker, SlideWindowContextChunker
+from .chunkers import UnitChunker, WholeDocumentUnitChunker, SentenceUnitChunker, TextLineUnitChunker, SeparatorUnitChunker, LLMUnitChunker, ContextChunker, NoContextChunker, WholeDocumentContextChunker, SlideWindowContextChunker
 from .prompt_editor import PromptEditor
 
 __all__ = ["LLMInformationExtractionFrame", "LLMInformationExtractionDocument",
-           "BasicLLMConfig", "ReasoningLLMConfig", "Qwen3LLMConfig", "OpenAIReasoningLLMConfig", "LlamaCppInferenceEngine", "OllamaInferenceEngine", "HuggingFaceHubInferenceEngine", "OpenAIInferenceEngine", "AzureOpenAIInferenceEngine", "LiteLLMInferenceEngine",
+           "BasicLLMConfig", "ReasoningLLMConfig", "Qwen3LLMConfig", "OpenAIReasoningLLMConfig", "LlamaCppInferenceEngine", "OllamaInferenceEngine", "HuggingFaceHubInferenceEngine", "VLLMInferenceEngine", "SGLangInferenceEngine", "OpenRouterInferenceEngine", "OpenAIInferenceEngine", "AzureOpenAIInferenceEngine", "LiteLLMInferenceEngine",
            "DirectFrameExtractor", "ReviewFrameExtractor", "BasicFrameExtractor", "BasicReviewFrameExtractor", "SentenceFrameExtractor", "SentenceReviewFrameExtractor", "AttributeExtractor", "BinaryRelationExtractor", "MultiClassRelationExtractor",
-           "UnitChunker", "WholeDocumentUnitChunker", "SentenceUnitChunker", "TextLineUnitChunker", "ContextChunker", "NoContextChunker", "WholeDocumentContextChunker", "SlideWindowContextChunker",
+           "UnitChunker", "WholeDocumentUnitChunker", "SentenceUnitChunker", "TextLineUnitChunker", "SeparatorUnitChunker", "LLMUnitChunker", "ContextChunker", "NoContextChunker", "WholeDocumentContextChunker", "SlideWindowContextChunker",
            "PromptEditor"]

llm_ie-1.2.4/src/llm_ie/asset/default_prompts/LLMUnitChunker_user_prompt.txt

@@ -0,0 +1,129 @@
+### Task description
+You are a helpful assistant that breaks down a text document into semantic units or chunks. Each chunk should represent a coherent section of the text, such as a paragraph, subsection, or topic.
+
+### Schema definition
+You will output a JSON array of objects. Each object should have the following fields:
+    - "title": Generate a brief title summarizing the content of the chunk.
+    - "anchor_text": the first line of text in the chunk used to locate it in the original document. Must be an exact match.
+        - if there is a title or heading for the chunk, use that as the anchor_text.
+        - if there is no title or heading, use the first sentence of the chunk as the anchor_text.
+
+```JSON
+[
+    {
+        "title": "<your title here>",
+        "anchor_text": "<the anchor text of the chunk here>"
+    },
+    {
+        "title": "<your title here>",
+        "anchor_text": "<the anchor text of the chunk here>"
+    }
+]
+```
+
+### Examples
+
+**Input**:
+"# Clinical Note
+
+**Patient Name**: Michael Green  
+**Medical Record Number**: 1122334455  
+**Date of Visit**: January 5, 2025  
+**Provider**: Dr. Emily Carter, MD  
+
+## Reason for Visit  
+Follow-up for poorly controlled type 2 diabetes and complaints of occasional dizziness and blurred vision.
+
+## Summary of Visit  
+Michael Green, a 62-year-old male with a known history of type 2 diabetes, hypertension, and obesity, presents for follow-up regarding his glycemic control. Despite recent adjustments to his treatment plan, his glucose readings have remained elevated, averaging 180-220 mg/dL. He reports occasional episodes of dizziness and blurred vision, particularly in the morning before meals. He denies chest pain, palpitations, or recent falls. He reports compliance with his medication regimen but admits to difficulty following a consistent low-carbohydrate diet.
+
+Michael has been using a glucose meter to monitor his blood sugar levels and logs them daily. His last hemoglobin A1c, performed three months ago, was 9.2%. He reports no recent hospitalizations, infections, or significant stressors.
+
+## Notable History  
+- **Chronic Conditions**:  
+  - Type 2 diabetes mellitus, diagnosed 10 years ago.  
+  - Hypertension, well-controlled on medication.  
+  - Hyperlipidemia, on statin therapy.  
+- **Past Surgical History**:  
+  - Knee arthroscopy for a meniscal tear, age 50.  
+- **Family History**:  
+  - Mother: Deceased at 75, complications from diabetes.  
+  - Father: Deceased at 70, myocardial infarction."
+
+**Output**:
+```JSON
+[
+    {
+        "title": "Patient Information",
+        "anchor_text": "# Clinical Note"
+    },
+    {
+        "title": "Reason for Visit",
+        "anchor_text": "## Reason for Visit"
+    },
+    {
+        "title": "Summary of Visit",
+        "anchor_text": "## Summary of Visit"
+    },
+    {
+        "title": "Notable History",
+        "anchor_text": "## Notable History"
+    }
+]
+```
+
+**Input**:
+"In the [**Hospital1 18**] ED, 35.3 102 133/58 100%AC 500x20, 5, 1.0 with an
+ABG 7.16/66/162. He had a CTH which was unremarkable. He then
+had a CTA chest, afterwhich he went into PEA arrest.
+Rescucitation last approximately 10-15 minutes with multiple
+rounds of epi and bicarb, with ROSC. He was then admitted to the
+MICU for further management.
+.
+Currently, the patient is intubated, sedated, and parlyzed.
+
+Past Medical History:
+Asthma
+Dilated cardiomyopathy
+Multiple admissions for dyspnea this winter ([**1-26**]).
+Anxiety/depression
+CKD
+HLD
+Obesity
+HTN
+
+Social History:
+Unknown
+
+Family History:
+Unknown"
+
+**Output**:
+```JSON
+[
+    {
+        "title": "Patient Presentation and Initial Management",
+        "anchor_text": "In the [**Hospital1 18**] ED, 35.3 102 133/58 100%AC 500x20, 5, 1.0 with an"
+    },
+    {
+        "title": "Current Status of the Patient",
+        "anchor_text": "Currently, the patient is intubated, sedated, and parlyzed."
+    },
+    {
+        "title": "Past Medical History",
+        "anchor_text": "Past Medical History:"
+    },
+    {
+        "title": "Social History",
+        "anchor_text": "Social History:"
+    },
+    {
+        "title": "Family History",
+        "anchor_text": "Family History:"
+    }
+]
+```
+
+### Document text
+
+"{{document_text}}"

{llm_ie-1.2.2 → llm_ie-1.2.4}/src/llm_ie/chunkers.py

@@ -1,6 +1,11 @@
 import abc
-from typing import Set, List, Dict, Tuple, Union, Callable
+from typing import List
+import asyncio
+import uuid
+import importlib.resources
+from llm_ie.utils import extract_json, apply_prompt_template
 from llm_ie.data_types import FrameExtractionUnit
+from llm_ie.engines import InferenceEngine
 
 
 class UnitChunker(abc.ABC):
@@ -11,7 +16,8 @@ class UnitChunker(abc.ABC):
         """
         pass
 
-    def chunk(self, text:str) -> List[FrameExtractionUnit]:
+    @abc.abstractmethod
+    def chunk(self, text:str, doc_id:str=None) -> List[FrameExtractionUnit]:
         """
         Parameters:
         ----------
@@ -20,6 +26,12 @@ class UnitChunker(abc.ABC):
         """
         return NotImplemented
 
+    async def chunk_async(self, text:str, doc_id:str=None, executor=None) -> List[FrameExtractionUnit]:
+        """
+        asynchronous version of chunk method.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(executor, self.chunk, text, doc_id)
 
 class WholeDocumentUnitChunker(UnitChunker):
     def __init__(self):
@@ -28,7 +40,7 @@ class WholeDocumentUnitChunker(UnitChunker):
         """
         super().__init__()
 
-    def chunk(self, text:str) -> List[FrameExtractionUnit]:
+    def chunk(self, text:str, doc_id:str=None) -> List[FrameExtractionUnit]:
         """
         Parameters:
         ----------
@@ -36,6 +48,7 @@ class WholeDocumentUnitChunker(UnitChunker):
             The document text.
         """
         return [FrameExtractionUnit(
+            doc_id=doc_id if doc_id is not None else str(uuid.uuid4()),
             start=0,
             end=len(text),
             text=text
@@ -57,19 +70,21 @@ class SeparatorUnitChunker(UnitChunker):
 
         self.sep = sep
 
-    def chunk(self, text:str) -> List[FrameExtractionUnit]:
+    def chunk(self, text:str, doc_id:str=None) -> List[FrameExtractionUnit]:
         """
         Parameters:
         ----------
         text : str
             The document text.
         """
+        doc_id = doc_id if doc_id is not None else str(uuid.uuid4())
         paragraphs = text.split(self.sep)
         paragraph_units = []
         start = 0
         for paragraph in paragraphs:
             end = start + len(paragraph)
             paragraph_units.append(FrameExtractionUnit(
+                doc_id=doc_id,
                 start=start,
                 end=end,
                 text=paragraph
@@ -77,6 +92,7 @@ class SeparatorUnitChunker(UnitChunker):
             start = end + len(self.sep)
         return paragraph_units
 
+
 class SentenceUnitChunker(UnitChunker):
     from nltk.tokenize.punkt import PunktSentenceTokenizer
     def __init__(self):
@@ -85,16 +101,18 @@ class SentenceUnitChunker(UnitChunker):
         """
         super().__init__()
 
-    def chunk(self, text:str) -> List[FrameExtractionUnit]:
+    def chunk(self, text:str, doc_id:str=None) -> List[FrameExtractionUnit]:
         """
         Parameters:
         ----------
         text : str
             The document text.
         """
+        doc_id = doc_id if doc_id is not None else str(uuid.uuid4())
         sentences = []
         for start, end in self.PunktSentenceTokenizer().span_tokenize(text):
             sentences.append(FrameExtractionUnit(
+                doc_id=doc_id,
                 start=start,
                 end=end,
                 text=text[start:end]
@@ -109,19 +127,21 @@ class TextLineUnitChunker(UnitChunker):
         """
         super().__init__()
 
-    def chunk(self, text:str) -> List[FrameExtractionUnit]:
+    def chunk(self, text:str, doc_id:str=None) -> List[FrameExtractionUnit]:
         """
         Parameters:
         ----------
         text : str
             The document text.
         """
+        doc_id = doc_id if doc_id is not None else str(uuid.uuid4())
         lines = text.split('\n')
         line_units = []
         start = 0
         for line in lines:
             end = start + len(line)
             line_units.append(FrameExtractionUnit(
+                doc_id=doc_id,
                 start=start,
                 end=end,
                 text=line
@@ -129,6 +149,100 @@ class TextLineUnitChunker(UnitChunker):
             start = end + 1 
         return line_units
     
+class LLMUnitChunker(UnitChunker):
+    def __init__(self, inference_engine:InferenceEngine, prompt_template:str=None, system_prompt:str=None):
+        """
+        This class prompt an LLM for document segmentation (e.g., sections, paragraphs).
+
+        Parameters:
+        ----------
+        inference_engine : InferenceEngine
+            the LLM inferencing engine object.
+        prompt_template : str
+            the prompt template that defines how to chunk the document. Must define a JSON schema with 
+            ```json
+            [
+                {
+                    "title": "<your title here>",
+                    "anchor_text": "<the anchor text of the chunk here>"
+                },
+                {
+                    "title": "<your title here>",
+                    "anchor_text": "<the anchor text of the chunk here>"
+                }
+            ]
+            ```
+        system_prompt : str, optional
+            The system prompt.
+        """
+        self.inference_engine = inference_engine
+
+        if prompt_template is None:
+            file_path = importlib.resources.files('llm_ie.asset.default_prompts').joinpath("LLMUnitChunker_user_prompt.txt")
+            with open(file_path, 'r', encoding="utf-8") as f:
+                self.prompt_template = f.read()
+        else:
+            self.prompt_template = prompt_template
+        
+        self.system_prompt = system_prompt
+
+    def chunk(self, text, doc_id=None) -> List[FrameExtractionUnit]:
+        """
+        Parameters:
+        -----------
+        text : str
+            the document text.
+        doc_id : str, optional
+            the document id.
+        """
+        doc_id = doc_id if doc_id is not None else str(uuid.uuid4())
+        user_prompt = apply_prompt_template(prompt_template=self.prompt_template, text_content=text)
+        messages = []
+        if self.system_prompt is not None:
+            messages.append({'role': 'system', 'content': self.system_prompt})
+        messages.append({'role': 'user', 'content': user_prompt})
+
+        gen_text = self.inference_engine.chat(messages=messages)
+
+        header_list = extract_json(gen_text=gen_text["response"])
+        units = []
+        start = 0
+        prev_end = 0
+        for header in header_list:
+            if "anchor_text" not in header:
+                Warning.warn(f"Missing anchor_text in header: {header}. Skipping this header.")
+                continue
+            if not isinstance(header["anchor_text"], str):
+                Warning.warn(f"Invalid anchor_text: {header['anchor_text']}. Skipping this header.")
+                continue
+
+            start = prev_end
+            # find the first instandce of the leading sentence in the rest of the text
+            end = text.find(header["anchor_text"], start)
+            # if not found, skip this header
+            if end == -1:
+                continue
+            # if start == end (empty text), skip this header
+            if start == end:
+                continue
+            # create a frame extraction unit
+            units.append(FrameExtractionUnit(
+                doc_id=doc_id,
+                start=start,
+                end=end,
+                text=text[start:end]
+            ))
+            prev_end = end
+        # add the last section
+        if prev_end < len(text):
+            units.append(FrameExtractionUnit(
+                doc_id=doc_id,
+                start=prev_end,
+                end=len(text),
+                text=text[prev_end:]
+            ))
+        return units
+
 
 class ContextChunker(abc.ABC):
     def __init__(self):
@@ -138,6 +252,24 @@ class ContextChunker(abc.ABC):
         """
         pass
 
+    @abc.abstractmethod
+    def fit(self, text:str, units:List[FrameExtractionUnit]):
+        """
+        Parameters:
+        ----------
+        text : str
+            The document text.
+        """
+        pass
+
+    async def fit_async(self, text:str, units:List[FrameExtractionUnit], executor=None):
+        """
+        asynchronous version of fit method.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(executor, self.fit, text, units)
+
+    @abc.abstractmethod
     def chunk(self, unit:FrameExtractionUnit) -> str:
         """
         Parameters:
@@ -150,6 +282,13 @@ class ContextChunker(abc.ABC):
         """
         return NotImplemented
     
+    async def chunk_async(self, unit:FrameExtractionUnit, executor=None) -> str:
+        """
+        asynchronous version of chunk method.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(executor, self.chunk, unit)
+    
 
 class NoContextChunker(ContextChunker):
     def __init__(self):

{llm_ie-1.2.2 → llm_ie-1.2.4}/src/llm_ie/data_types.py

@@ -7,13 +7,15 @@ import json
 
 @dataclass
 class FrameExtractionUnit:
-    def __init__(self, start:int, end:int, text:str):
+    def __init__(self, doc_id:str, start:int, end:int, text:str):
         """
         This class holds the unit text for frame extraction, for example, a sentence. 
         FrameExtractor prompt it one at a time to extract frames. 
         
         Parameters
         ----------
+        doc_id : str, Optional
+            document ID.
         start : int
             start character position of the unit text, relative to the whole document
         end : int
@@ -21,9 +23,28 @@ class FrameExtractionUnit:
         text : str
             the unit text. Should be the exact string by [start:end]
         """
+        self.doc_id = doc_id
         self.start = start
         self.end = end
         self.text = text
+        # status: "pending", "success", "fail"
+        self.status = "pending"
+        # generated text by LLM
+        self.gen_text = None
+
+    def get_status(self) -> str:
+        return self.status
+    
+    def set_status(self, status:str):
+        if status not in {"pending", "success", "fail"}:
+            raise ValueError('status must be one of {"pending", "success", "fail"}.')
+        self.status = status
+
+    def get_generated_text(self) -> str:
+        return self.gen_text
+
+    def set_generated_text(self, gen_text:str):
+        self.gen_text = gen_text
 
     def __eq__(self, other):
             if not isinstance(other, FrameExtractionUnit):
@@ -39,43 +60,8 @@ class FrameExtractionUnit:
         return self.start < other.start
         
     def __repr__(self):
-        return f"FrameExtractionUnit(start={self.start}, end={self.end}, text='{self.text[:100]}...')"
-
-
-@dataclass
-class FrameExtractionUnitResult:
-    def __init__(self, start:int, end:int, text:str, gen_text:str):
-        """
-        This class holds the unit text for frame extraction, for example, a sentence. 
-        FrameExtractor prompt it one at a time to extract frames. 
-        
-        Parameters
-        ----------
-        start : int
-            start character position of the unit text, relative to the whole document
-        end : int
-            end character position of the unit text, relative to the whole document
-        text : str
-            the unit text. Should be the exact string by [start:end]
-        gen_text : str
-            the generated text by LLM (ideally) following '[{"entity_text": "xxx", "attr": {"key": "value"}}]' format. Does not contain spans (start/end).
-        """
-        self.start = start
-        self.end = end
-        self.text = text
-        self.gen_text = gen_text
-        
-    def __eq__(self, other):
-            if not isinstance(other, FrameExtractionUnit):
-                return NotImplemented
-            return (self.start == other.start and self.end == other.end and self.text == other.text and self.gen_text == other.gen_text)
+        return f"FrameExtractionUnit(doc_id={self.doc_id}, start={self.start}, end={self.end}, status={self.status}, text='{self.text[:100]}...')"
 
-    def __hash__(self):
-        return hash((self.start, self.end, self.text, self.gen_text))
-
-    def __repr__(self):
-        return f"FrameExtractionUnitResult(start={self.start}, end={self.end}, text='{self.text[:100]}...', gen_text='{self.gen_text[:100]}...')"
-    
 
 @dataclass
 class LLMInformationExtractionFrame: