llmflowstack 1.0.0__tar.gz

llmflowstack-1.0.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

llmflowstack-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__
+.vscode
+*.egg-info/
+dist

llmflowstack-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gustavo Henrique Ferreira Cruz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llmflowstack-1.0.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: llmflowstack
+Version: 1.0.0
+Summary: LLMFlowStack is a framework for training and using LLMs (LLaMA, GPT-OSS, Gemma). Supports DAPT, fine-tuning, and distributed inference. Public fork without institution-specific components.
+Author-email: Gustavo Henrique Ferreira Cruz <gustavohferreiracruz@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: accelerate
+Requires-Dist: bert-score
+Requires-Dist: bitsandbytes
+Requires-Dist: chromadb
+Requires-Dist: colorama
+Requires-Dist: datasets
+Requires-Dist: evaluate
+Requires-Dist: huggingface-hub
+Requires-Dist: langchain-chroma
+Requires-Dist: langchain-community
+Requires-Dist: nltk
+Requires-Dist: numpy
+Requires-Dist: openai-harmony
+Requires-Dist: pandas
+Requires-Dist: peft
+Requires-Dist: rouge-score
+Requires-Dist: safetensors
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: sentence-transformers
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: tqdm
+Requires-Dist: transformers
+Requires-Dist: triton
+Requires-Dist: trl
+Description-Content-Type: text/markdown
+
+# LLMFlow
+
+**LLMFlow** is a lightweight framework designed to simplify the use of LLMs (LLaMA, GPT-OSS, and Gemma) for NLP tasks.
+
+> **Note:** LLMFlow is intended for high-performance machines with **one or more NVIDIA H100 GPUs**.
+
+It provides:
+
+- **Training pipelines** with **fine-tuning** or **DAPT** in distributed setups — just provide the data and the process runs automatically;
+- **Distributed inference** made simple;
+- **Evaluation** with standard metrics (BERTScore, ROUGE, Cosine Similarity).
+
+The goal is to make experimentation with LLMs more accessible, without the need to build complex infrastructure from scratch.
+
+## Supported Models
+
+This framework is designed to provide flexibility when working with different open-source and commercial LLMs. Currently, the following models are supported:
+
+- **GPT-OSS**
+
+  - [`GPT-OSS 20B`](https://huggingface.co/openai/gpt-oss-20b)
+  - [`GPT-OSS 120B`](https://huggingface.co/openai/gpt-oss-120b)
+
+- **LLaMA**
+
+  - [`LLaMA 3.1 8B - Instruct`](https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct)
+  - [`LLaMA 3.1 70B - Instruct`](https://huggingface.co/meta-llama/Llama-3.1-70B-Instruct)
+  - [`LLaMA 3.3 70B - Instruct`](https://huggingface.co/meta-llama/Llama-3.3-70B-Instruct)
+  - [`LLaMA 3.3 405B - Instruct`](https://huggingface.co/meta-llama/Llama-3.1-405B-Instruct)
+
+- **Gemma**
+  - [`MedGemma 27B Text - It`](https://huggingface.co/google/medgemma-27b-text-it)
+
+> Compatibility includes both inference and training (Domain-Adaptive Pre-Training — DAPT — and Supervised Fine-Tuning)
+
+---
+
+## Installation
+
+You can install the package directly from [PyPI](https://pypi.org/project/llmflow/):
+
+```bash
+pip install llmflow
+```
+
+## Usage
+
+This section presents a bit of what you can do with the framework.
+
+### Loading models
+
+You can load as many models as your hardware allows (H100 GPU recommended)...
+
+```python
+from llmflow import GPT_OSS, LLaMA3
+
+# Loading a LLaMA model
+first_model = LLaMA3()
+first_model.load_checkpoint(
+  checkpoint="/llama-3.1-8b-Instruct",
+)
+
+# Loading a quantized LLaMA model
+second_model = LLaMA3(
+  checkpoint="/llama-3.3-70b-Instruct",
+  quantization="4bit"
+)
+
+# Loading a GPT-OSS, quantized and with seed
+thrid_model = GPT_OSS(
+  checkpoint="/gpt-oss-20b",
+  quantization=True,
+  seed=1234
+)
+```
+
+### Inference Examples
+
+```python
+> gpt_oss_model = GPT_OSS(checkpoint="/gpt-oss-120b")
+
+> gpt_oss_model.generate("Tell me a joke!")
+'Why did the scarecrow become a successful motivational speaker? Because he was outstanding **in** his field! 🌾😄'
+
+# Exclusive for GPT-OSS
+> gpt_oss_model.set_reasoning_level("High")
+
+> custom_input = gpt_oss_model.build_input(
+    input_text="Tell me another joke!",
+    developer_message="You are a clown and after every joke, you should say 'HONK HONK'"
+  )
+> gpt_oss_model.generate(
+    input=custom_input,
+    params=GenerationParams(
+      max_new_tokens=1024,
+      sample=GenerationSampleParams(
+        temperature=0.3
+      )
+    )
+  )
+'Why did the scarecrow win an award? Because he was outstanding in his field!  \n\nHONK HONK'
+
+> llama_model = LLaMA3(checkpoint="/llama-3.3-70B-Instruct", quantization="4bit")
+> llama_model.generate("Why is the sky blue?")
+'The sky appears blue because of a phenomenon called Rayleigh scattering, which is the scattering of light'
+```
+
+### Training Examples (DAPT & Fine-tune)
+
+```python
+from llmflow import LLaMA3
+from llmflow.schemas import TrainParams
+
+model = LLaMA3(
+  checkpoint="llama-3.1-8b-Instruct"
+)
+
+# Creating the dataset
+dataset = []
+dataset.append(model.build_input(
+  input_text="Chico is a cat, which color he is?",
+  expected_answer="Black!"
+))
+
+dataset.append(model.build_input(
+  input_text="Fred is a dog, which color he is?",
+  expected_answer="White!"
+))
+
+# Does the DAPT in the full model
+model.dapt(
+  train_dataset=dataset,
+  params=TrainParams(
+    batch_size=1,
+    epochs=3,
+    gradient_accumulation=1,
+    lr=2e-5
+  )
+)
+
+# Does the fine-tune this time
+model.fine_tune(
+  train_dataset=dataset,
+  params=TrainParams(
+    batch_size=1,
+    gradient_accumulation=1,
+    lr=2e-5,
+    epochs=50
+  ),
+  save_at_end=True,
+  # It will save the model
+  save_path="./output"
+)
+
+# Saving the final result
+model.save_checkpoint(
+  path="./model-output"
+)
+```
+
+### NLP Evaluation
+
+```python
+> from llmflow import text_evaluation
+> from llmflow.utils import (bert_score_evaluation, cosine_similarity_evaluation, rouge_evaluation)
+
+# Predictions from some model
+> predictions = ["Chico is a dog, and he is orange!", "Fred is a cat, and he is white!"]
+# References text (ground truth)
+> references = ["Chico is a cat, and he is black!", "Fred is a dog, and he is white!"]
+
+# BERTScore Evaluation
+> bert_score_evaluation(predictions, references)
+{'bertscore_precision': 0.9772549867630005, 'bertscore_recall': 0.9772549867630005, 'bertscore_f1': 0.9772549867630005}
+
+# Cosine Similarity Evaluation
+> cosine_similarity_evaluation(predictions, references)
+{'cosine_similarity': 0.7443363666534424}
+
+# RougeScore Evaluation
+> rouge_evaluation(predictions, references)
+{'rouge1': 0.8125, 'rouge2': 0.6428571428571428, 'rougeL': 0.8125}
+
+# All-in-one function
+> text_evaluation(predictions, references, bert=True, cosine=True, rouge=True)
+{'rouge1': 0.8125, 'rouge2': 0.6428571428571428, 'rougeL': 0.8125, 'bertscore_precision': 0.9772549867630005, 'bertscore_recall': 0.9772549867630005, 'bertscore_f1': 0.9772549867630005, 'cosine_similarity': 0.7443363666534424}
+```
+
+---
+
+> **Disclaimer**  
+> This is a public fork of a framework originally developed in a research setting.  
+> Institution-specific components have been removed for confidentiality reasons.

llmflowstack-1.0.0/README.md

@@ -0,0 +1,193 @@
+# LLMFlow
+
+**LLMFlow** is a lightweight framework designed to simplify the use of LLMs (LLaMA, GPT-OSS, and Gemma) for NLP tasks.
+
+> **Note:** LLMFlow is intended for high-performance machines with **one or more NVIDIA H100 GPUs**.
+
+It provides:
+
+- **Training pipelines** with **fine-tuning** or **DAPT** in distributed setups — just provide the data and the process runs automatically;
+- **Distributed inference** made simple;
+- **Evaluation** with standard metrics (BERTScore, ROUGE, Cosine Similarity).
+
+The goal is to make experimentation with LLMs more accessible, without the need to build complex infrastructure from scratch.
+
+## Supported Models
+
+This framework is designed to provide flexibility when working with different open-source and commercial LLMs. Currently, the following models are supported:
+
+- **GPT-OSS**
+
+  - [`GPT-OSS 20B`](https://huggingface.co/openai/gpt-oss-20b)
+  - [`GPT-OSS 120B`](https://huggingface.co/openai/gpt-oss-120b)
+
+- **LLaMA**
+
+  - [`LLaMA 3.1 8B - Instruct`](https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct)
+  - [`LLaMA 3.1 70B - Instruct`](https://huggingface.co/meta-llama/Llama-3.1-70B-Instruct)
+  - [`LLaMA 3.3 70B - Instruct`](https://huggingface.co/meta-llama/Llama-3.3-70B-Instruct)
+  - [`LLaMA 3.3 405B - Instruct`](https://huggingface.co/meta-llama/Llama-3.1-405B-Instruct)
+
+- **Gemma**
+  - [`MedGemma 27B Text - It`](https://huggingface.co/google/medgemma-27b-text-it)
+
+> Compatibility includes both inference and training (Domain-Adaptive Pre-Training — DAPT — and Supervised Fine-Tuning)
+
+---
+
+## Installation
+
+You can install the package directly from [PyPI](https://pypi.org/project/llmflow/):
+
+```bash
+pip install llmflow
+```
+
+## Usage
+
+This section presents a bit of what you can do with the framework.
+
+### Loading models
+
+You can load as many models as your hardware allows (H100 GPU recommended)...
+
+```python
+from llmflow import GPT_OSS, LLaMA3
+
+# Loading a LLaMA model
+first_model = LLaMA3()
+first_model.load_checkpoint(
+  checkpoint="/llama-3.1-8b-Instruct",
+)
+
+# Loading a quantized LLaMA model
+second_model = LLaMA3(
+  checkpoint="/llama-3.3-70b-Instruct",
+  quantization="4bit"
+)
+
+# Loading a GPT-OSS, quantized and with seed
+thrid_model = GPT_OSS(
+  checkpoint="/gpt-oss-20b",
+  quantization=True,
+  seed=1234
+)
+```
+
+### Inference Examples
+
+```python
+> gpt_oss_model = GPT_OSS(checkpoint="/gpt-oss-120b")
+
+> gpt_oss_model.generate("Tell me a joke!")
+'Why did the scarecrow become a successful motivational speaker? Because he was outstanding **in** his field! 🌾😄'
+
+# Exclusive for GPT-OSS
+> gpt_oss_model.set_reasoning_level("High")
+
+> custom_input = gpt_oss_model.build_input(
+    input_text="Tell me another joke!",
+    developer_message="You are a clown and after every joke, you should say 'HONK HONK'"
+  )
+> gpt_oss_model.generate(
+    input=custom_input,
+    params=GenerationParams(
+      max_new_tokens=1024,
+      sample=GenerationSampleParams(
+        temperature=0.3
+      )
+    )
+  )
+'Why did the scarecrow win an award? Because he was outstanding in his field!  \n\nHONK HONK'
+
+> llama_model = LLaMA3(checkpoint="/llama-3.3-70B-Instruct", quantization="4bit")
+> llama_model.generate("Why is the sky blue?")
+'The sky appears blue because of a phenomenon called Rayleigh scattering, which is the scattering of light'
+```
+
+### Training Examples (DAPT & Fine-tune)
+
+```python
+from llmflow import LLaMA3
+from llmflow.schemas import TrainParams
+
+model = LLaMA3(
+  checkpoint="llama-3.1-8b-Instruct"
+)
+
+# Creating the dataset
+dataset = []
+dataset.append(model.build_input(
+  input_text="Chico is a cat, which color he is?",
+  expected_answer="Black!"
+))
+
+dataset.append(model.build_input(
+  input_text="Fred is a dog, which color he is?",
+  expected_answer="White!"
+))
+
+# Does the DAPT in the full model
+model.dapt(
+  train_dataset=dataset,
+  params=TrainParams(
+    batch_size=1,
+    epochs=3,
+    gradient_accumulation=1,
+    lr=2e-5
+  )
+)
+
+# Does the fine-tune this time
+model.fine_tune(
+  train_dataset=dataset,
+  params=TrainParams(
+    batch_size=1,
+    gradient_accumulation=1,
+    lr=2e-5,
+    epochs=50
+  ),
+  save_at_end=True,
+  # It will save the model
+  save_path="./output"
+)
+
+# Saving the final result
+model.save_checkpoint(
+  path="./model-output"
+)
+```
+
+### NLP Evaluation
+
+```python
+> from llmflow import text_evaluation
+> from llmflow.utils import (bert_score_evaluation, cosine_similarity_evaluation, rouge_evaluation)
+
+# Predictions from some model
+> predictions = ["Chico is a dog, and he is orange!", "Fred is a cat, and he is white!"]
+# References text (ground truth)
+> references = ["Chico is a cat, and he is black!", "Fred is a dog, and he is white!"]
+
+# BERTScore Evaluation
+> bert_score_evaluation(predictions, references)
+{'bertscore_precision': 0.9772549867630005, 'bertscore_recall': 0.9772549867630005, 'bertscore_f1': 0.9772549867630005}
+
+# Cosine Similarity Evaluation
+> cosine_similarity_evaluation(predictions, references)
+{'cosine_similarity': 0.7443363666534424}
+
+# RougeScore Evaluation
+> rouge_evaluation(predictions, references)
+{'rouge1': 0.8125, 'rouge2': 0.6428571428571428, 'rougeL': 0.8125}
+
+# All-in-one function
+> text_evaluation(predictions, references, bert=True, cosine=True, rouge=True)
+{'rouge1': 0.8125, 'rouge2': 0.6428571428571428, 'rougeL': 0.8125, 'bertscore_precision': 0.9772549867630005, 'bertscore_recall': 0.9772549867630005, 'bertscore_f1': 0.9772549867630005, 'cosine_similarity': 0.7443363666534424}
+```
+
+---
+
+> **Disclaimer**  
+> This is a public fork of a framework originally developed in a research setting.  
+> Institution-specific components have been removed for confidentiality reasons.

llmflowstack-1.0.0/llmflowstack/__init__.py

@@ -0,0 +1,19 @@
+from .models.Gemma import Gemma
+from .models.GPT_OSS import GPT_OSS
+from .models.LLaMA3 import LLaMA3
+from .rag.pipeline import RAGPipeline
+from .schemas.params import (GenerationBeamsParams, GenerationParams,
+                             GenerationSampleParams, TrainParams)
+from .utils.evaluation_methods import text_evaluation
+
+__all__ = [
+  "Gemma",
+  "LLaMA3",
+  "GPT_OSS",
+  "RAGPipeline",
+  "GenerationBeamsParams",
+  "GenerationParams",
+  "GenerationSampleParams",
+  "TrainParams",
+  "text_evaluation"
+]