Add complete model card: pipeline overview, adapter/full-model explanation, download and usage instructions with exact prompt formats and label mappings

README.md

@@ -1,199 +1,148 @@
 ---
 library_name: transformers
-tags: []
+base_model: meta-llama/Meta-Llama-3-8B
+license: llama3
+language:
+- en
+pipeline_tag: text-generation
+tags:
+- argument-mining
+- topic-extraction
+- claim-extraction
+- computational-social-science
+- llama
+- wiba
 ---
 
-# Model Card for Model ID
+# WIBA Claim Topic Extraction (Llama-3-8B, full model)
+
+**Topic extraction** model: given an argumentative sentence or passage, it generates the **topic being argued** (a short phrase naming the person, place, thing, entity, or idea at issue), or **`No Topic`** if the text is not an argument. The topic may be explicit in the text or implicit and inferred from context.
+
+This is **Stage 2** of the [WIBA (What Is Being Argued?)](https://arxiv.org/abs/2405.00828) argument mining pipeline:
+
+| Stage | Task | Model | Type |
+|---|---|---|---|
+| 1. Detect | Is this text an argument? | [armaniii/llama-3-8b-argument-detection](https://huggingface.co/armaniii/llama-3-8b-argument-detection) | LoRA adapter (sequence classification, 2 labels) |
+| **2. Extract** | What topic is being argued? | **this repo** | Full fine-tuned causal LM |
+| 3. Stance | What position does it take on the topic? | [armaniii/llama-stance-classification](https://huggingface.co/armaniii/llama-stance-classification) | LoRA adapter (sequence classification, 3 labels) |
+
+- 📄 Paper: [WIBA: What Is Being Argued? A Comprehensive Approach to Argument Mining](https://arxiv.org/abs/2405.00828)
+- 💻 Code: [github.com/Armaniii/WIBA](https://github.com/Armaniii/WIBA)
+- 🌐 Platform: [wiba.dev](https://wiba.dev)
 
-<!-- Provide a quick summary of what the model is/does. -->
+## What this repo contains (full model, not an adapter)
 
+Unlike the detect and stance stages, this repo is a **complete, self-contained fine-tuned model** (`LlamaForCausalLM`, ~16 GB of float16 safetensors in two shards). You do **not** need to download the base Llama-3 weights or merge any adapter — `from_pretrained` on this repo alone is enough.
 
+| File | Purpose |
+|---|---|
+| `model-0000*-of-00002.safetensors` + index | Full fine-tuned weights (float16) |
+| `config.json` | Model config — **note: ships with a bitsandbytes 4-bit (nf4) `quantization_config` baked in** (see below) |
+| `generation_config.json` | Default generation settings |
+| `tokenizer.json`, `tokenizer_config.json`, `special_tokens_map.json` | Llama-3 tokenizer |
+
+> **Quantization note:** because `config.json` includes a `quantization_config`, `from_pretrained` will automatically load the model 4-bit quantized (~6 GB VRAM) when `bitsandbytes` is installed — this matches the production WIBA deployment. To load in full fp16 instead, strip the quantization config (snippet below).
 
-## Model Details
+## Quickstart
 
-### Model Description
+```bash
+pip install torch transformers accelerate bitsandbytes
+```
 
-<!-- Provide a longer summary of what this model is. -->
+```python
+import torch
+from transformers import AutoTokenizer, AutoModelForCausalLM
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+REPO = "armaniii/llama-3-8b-claim-topic-extraction"
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+tokenizer = AutoTokenizer.from_pretrained(REPO, use_fast=False)
+tokenizer.pad_token_id = tokenizer.eos_token_id
+tokenizer.padding_side = "left"
 
-### Model Sources [optional]
+# Loads 4-bit (nf4) automatically via the config's quantization_config (~6 GB VRAM)
+model = AutoModelForCausalLM.from_pretrained(
+    REPO, torch_dtype=torch.float16, device_map="auto", low_cpu_mem_usage=True
+)
+model.eval()
+```
 
-<!-- Provide the basic links for the model. -->
+To load **full fp16** (~16 GB VRAM) instead of 4-bit:
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+```python
+from transformers import AutoConfig
 
-## Uses
+config = AutoConfig.from_pretrained(REPO)
+if hasattr(config, "quantization_config"):
+    delattr(config, "quantization_config")
+model = AutoModelForCausalLM.from_pretrained(
+    REPO, config=config, torch_dtype=torch.float16, device_map="auto"
+)
+```
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+### Prompt format (must match training)
 
-### Direct Use
+The model expects the Llama-3 chat header format with the WIBA topic-extraction system prompt, and the generation cut off after a few tokens (topics are short):
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+```python
+SYSTEM_PROMPT = """You are a helpful assistant that is specialized in a single task. If the sentence provided is an argument, decide what the topic being argued is using the rules and steps below.
+Rules: 
+1. An argument is a sentence that must contain a claim AND AT LEAST ONE premise(i.e evidence) supporting that assertion or claim. 
+2. A claim is the position being taken in the argument.
+3. A premise is a statement that provides evidence to support the claim.
+4. In order for a sentence to be an argument it must contain a claim AND at least one premise.
+5. If the sentence does not contain a claim AND does not provide any premises to support the claim, then it is a non-argument.
+6. If the sentence provided is an argument, then there must be a single topic being argued that is regarding a person, place, thing, entity, or abstract idea. The topic being argued may be explicitly stated OR it may be implicit and must be inferred from the context of the argument.  
+7. If the sentence provided is a non-argument, then there is no topic being argued. 
 
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure 
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-(https://arxiv.org/abs/2405.00828)
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
+Steps:
+1. Decide if the sentence provided is an argument or non-argument using the Rules provided.
+2. If the sentence is an argument, output only the topic being argued and your task is finished.
+3. If the sentence is a non-argument, only output: No Topic and your task is finished.
+4. If the sentence provided is a non-argument, then there is no topic being argued and you should only output: No Topic
+5. Let us think through the problem step by step carefully following all the rules outlined."""
 
+def extract_topic(text: str) -> str:
+    prompt = (
+        "<|begin_of_text|><|start_header_id|>system<|end_header_id|>\n\n"
+        + SYSTEM_PROMPT
+        + "<|eot_id|><|start_header_id|>user<|end_header_id|>\n\n"
+        + text
+        + "<|eot_id|><|start_header_id|>assistant<|end_header_id|>\n\n"
+    )
+    enc = tokenizer(prompt, return_tensors="pt").to(model.device)
+    with torch.no_grad():
+        out = model.generate(**enc, max_new_tokens=8, pad_token_id=128009)
+    return tokenizer.decode(out[0, enc.input_ids.shape[1]:], skip_special_tokens=True).strip()
 
+print(extract_topic("We must act on climate change because temperatures are rising."))
+# -> a topic phrase, e.g. "Climate change"
+print(extract_topic("The weather is nice today."))
+# -> "No Topic"
+```
+
+The original implementation uses the equivalent `pipeline("text-generation", ..., max_new_tokens=8, pad_token_id=128009)` and takes the text after the final `assistant<|end_header_id|>\n\n` marker — the function above does the same thing with `generate`.
+
+### Output
+
+- An argumentative input → a short topic phrase (e.g. `Climate change`, `Gun control`)
+- A non-argument input → the literal string `No Topic`
+
+## How it's used in the WIBA implementation
+
+In the WIBA serving code, this model backs the `/api/extract` endpoint at [wiba.dev](https://wiba.dev). Texts that Stage 1 classified as `Argument` are passed here to name the topic; the (text, topic) pair is then passed to Stage 3 ([stance classification](https://huggingface.co/armaniii/llama-stance-classification)) to determine whether the argument is in favor of or against that topic. For batch processing the implementation streams prompts through the pipeline with `batch_size=2` and left-padding.
+
+## Citation
+
+```bibtex
+@article{irani2024wiba,
+  title={WIBA: What Is Being Argued? A Comprehensive Approach to Argument Mining},
+  author={Irani, Arman and Park, Ju Yeon and Esterling, Kevin and Faloutsos, Michalis},
+  journal={arXiv preprint arXiv:2405.00828},
+  year={2024}
+}
+```
+
+## Notes
+
+- Fine-tuned from `meta-llama/Meta-Llama-3-8B` (Llama 3 license applies). The weights here are already fine-tuned; the base model is not required.
+- Internal fine-tune lineage: `llama_cte_v3`.