### Install Build Tools and Clean

Source: https://github.com/fastino-ai/gliner2/blob/main/RELEASE.md

Install necessary build tools like 'build' and 'twine', and clean up previous build artifacts.

```bash
# Install build tools
pip install build twine

# Clean previous builds
rm -rf dist/ build/ *.egg-info/
```

--------------------------------

### Configure Training Parameters

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Basic configuration examples for memory efficiency and worker management.

```python
# 5. Use LoRA (most memory efficient)
config = TrainingConfig(
    use_lora=True,
    lora_r=8,
    batch_size=32  # Can use larger batch with LoRA
)

# 6. Reduce workers
config = TrainingConfig(num_workers=2)
```

--------------------------------

### Install GLiNER2

Source: https://github.com/fastino-ai/gliner2/blob/main/README.md

Install the base package for utilities or the local extra for full inference and training capabilities.

```bash
# Schema validation, API client, training-data utilities — no torch required
pip install gliner2

# Full local inference and training (installs torch, transformers, etc.)
pip install gliner2[local]
```

--------------------------------

### Classify with Examples and Descriptions

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Combine few-shot examples and label descriptions for complex classification scenarios.

```jsonl
{"input": "The algorithm demonstrates linear time complexity.", "output": {"classifications": [{"task": "complexity", "labels": ["constant", "linear", "quadratic", "exponential"], "true_label": ["linear"], "examples": [["O(1) lookup time", "constant"], ["O(n) iteration", "linear"]], "label_descriptions": {"constant": "O(1) - fixed time regardless of input size", "linear": "O(n) - time scales linearly with input", "quadratic": "O(n²) - nested iterations", "exponential": "O(2ⁿ) - recursive branching"}}]}}
```

--------------------------------

### Quick Start Training with InputExample

Source: https://github.com/fastino-ai/gliner2/blob/main/README.md

Initializes a GLiNER2 model and trains it using a list of InputExample objects.

```python
from gliner2 import GLiNER2
from gliner2.training.data import InputExample
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig

# 1. Prepare training data
examples = [
    InputExample(
        text="John works at Google in California.",
        entities={"person": ["John"], "company": ["Google"], "location": ["California"]}
    ),
    InputExample(
        text="Apple released iPhone 15.",
        entities={"company": ["Apple"], "product": ["iPhone 15"]}
    ),
    # Add more examples...
]

# 2. Configure training
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")
config = TrainingConfig(
    output_dir="./output",
    num_epochs=10,
    batch_size=8,
    encoder_lr=1e-5,
    task_lr=5e-4
)

# 3. Train
trainer = GLiNER2Trainer(model, config)
trainer.train(train_data=examples)
```

--------------------------------

### Create Entity Extraction Examples

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Constructs training examples for entity extraction with optional entity descriptions to improve model performance.

```python
from gliner2.training.data import InputExample

# Simple entity extraction
example = InputExample(
    text="John Smith works at Google in San Francisco.",
    entities={
        "person": ["John Smith"],
        "company": ["Google"],
        "location": ["San Francisco"]
    }
)

# With entity descriptions (improves model understanding)
example = InputExample(
    text="BERT was developed by Google AI.",
    entities={
        "model": ["BERT"],
        "organization": ["Google AI"]
    },
    entity_descriptions={
        "model": "Machine learning model or architecture",
        "organization": "Company, research lab, or institution"
    }
)
```

--------------------------------

### Install FlashDeberta

Source: https://github.com/fastino-ai/gliner2/blob/main/README.md

Install the FlashDeberta package to enable GPU acceleration for DebertaV2-based models.

```bash
pip install flashdeberta
```

--------------------------------

### Common Training Configurations

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Examples of common training configurations for GLiNER2, including fast prototyping, production training, and memory-optimized setups.

```APIDOC
## Common Configurations

### Fast Prototyping
```python
config = TrainingConfig(
    output_dir="./quick_test",
    num_epochs=3,
    batch_size=16,
    encoder_lr=1e-5,
    task_lr=5e-4,
    max_train_samples=100,
    eval_strategy="no"
)
```

### Production Training
```python
config = TrainingConfig(
    output_dir="./production_model",
    num_epochs=20,
    batch_size=32,
    gradient_accumulation_steps=2,
    encoder_lr=5e-6,
    task_lr=1e-4,
    weight_decay=0.01,
    warmup_ratio=0.1,
    scheduler_type="cosine",
    fp16=True,
    eval_strategy="steps",  # Evaluates and saves every N steps
    eval_steps=500,
    save_total_limit=5,
    save_best=True,
    early_stopping=True,
    early_stopping_patience=5,
    report_to_wandb=True,
    wandb_project="gliner2-production"
)
```

### Memory-Optimized
```python
config = TrainingConfig(
    output_dir="./large_model",
    num_epochs=10,
    batch_size=8,
    gradient_accumulation_steps=8,
    gradient_checkpointing=True,
    fp16=True,
    encoder_lr=1e-6,
    task_lr=5e-5,
    max_grad_norm=0.5,
    num_workers=2
)
```
```

--------------------------------

### Initialize LoRA Training

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Basic setup for loading a base model for LoRA fine-tuning.

```python
from gliner2 import GLiNER2
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig

# Load base model
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")
```

--------------------------------

### Basic LoRA Training Workflow

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

A standard setup for enabling LoRA, training the model, and loading the resulting adapter weights.

```python
config = TrainingConfig(
    output_dir="./output_lora",
    num_epochs=10,
    batch_size=16,
    
    # Enable LoRA
    use_lora=True,
    lora_r=16,              # Rank (higher = more params, better approximation)
    lora_alpha=32,          # Scaling factor (typically 2*r)
    lora_dropout=0.1,       # Dropout for regularization
    lora_target_modules=["encoder"],  # All encoder layers (query, key, value, dense)
    save_adapter_only=True, # Save only adapter weights (not full model)
    
    # Learning rate (task_lr used for LoRA + task heads when LoRA enabled)
    task_lr=5e-4,
    # encoder_lr is ignored when LoRA is enabled
    
    # Other settings
    fp16=True,
    eval_strategy="epoch",  # Evaluates and saves at end of each epoch
    save_best=True
)

# Train with LoRA
trainer = GLiNER2Trainer(model, config)
results = trainer.train(train_data="train.jsonl", eval_data="val.jsonl")

# Checkpoints contain merged weights (ready for inference)
best_model = GLiNER2.from_pretrained("./output_lora/best")
```

--------------------------------

### Basic LoRA Training Setup

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Demonstrates the initial steps for setting up LoRA (Low-Rank Adaptation) for parameter-efficient fine-tuning of GLiNER2 models.

```APIDOC
## LoRA Training

LoRA (Low-Rank Adaptation) enables parameter-efficient fine-tuning by training only a small number of additional parameters while keeping the base model frozen.

> 📚 **For a comprehensive guide on training and using multiple LoRA adapters**, see [Tutorial 10: LoRA Adapters - Multi-Domain Inference](./10-lora_adapters.md)

### Why Use LoRA?

- **Memory Efficient**: Train with 10-100x fewer parameters
- **Faster Training**: Fewer gradients to compute
- **Multiple Adapters**: Train different adapters for different tasks
- **Easy Deployment**: Checkpoints contain merged weights (ready for inference)
- **Granular Control**: Target specific layers or entire module groups

### LoRA Module Groups

GLiNER2 supports both coarse-grained (module groups) and fine-grained (specific layers) control:

**Module Groups** (apply to entire modules):
- `"encoder"` - All encoder layers (query, key, value, dense)
- `"span_rep"` - All linear layers in span representation
- `"classifier"` - All linear layers in classifier head
- `"count_embed"` - All linear layers in count embedding
- `"count_pred"` - All linear layers in count prediction

**Specific Encoder Layers** (fine-grained control):
- `"encoder.query"` - Only query projection layers
- `"encoder.key"` - Only key projection layers
- `"encoder.value"` - Only value projection layers
- `"encoder.dense"` - Only dense (FFN) layers

**Default**: All modules (`["encoder", "span_rep", "classifier", "count_embed", "count_pred"]`) for maximum adaptation.

### Basic LoRA Training

```python
from gliner2 import GLiNER2
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig

# Load base model
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")

```
```

--------------------------------

### Install GLiNER2

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/7-api.md

Install the required package via pip.

```bash
pip install gliner2
```

--------------------------------

### Very Short Text Inputs

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Examples of minimal input strings.

```jsonl
{"input": "Yes.", "output": {"classifications": [{"task": "response", "labels": ["yes", "no", "maybe"], "true_label": ["yes"]}]}
{"input": "OK", "output": {"entities": {}}}
```

--------------------------------

### Verify GLiNER2 Installation from PyPI

Source: https://github.com/fastino-ai/gliner2/blob/main/RELEASE.md

Install the released version of GLiNER2 from PyPI and verify basic import functionality.

```python
# Install from PyPI
pip install gliner2==1.0.1

# Test basic functionality
python -c "from gliner2 import GLiNER2; print('✓ Import successful')"
```

--------------------------------

### Setup Multi-Task Training

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Imports necessary modules for training models on combined tasks like NER, classification, and relation extraction.

```python
from gliner2 import GLiNER2
from gliner2.training.data import InputExample, Classification, Relation
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig
```

--------------------------------

### Classify with Few-Shot Examples

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Include a list of input-output pairs to provide context for the classification task.

```jsonl
{"input": "This service exceeded all my expectations!", "output": {"classifications": [{"task": "sentiment", "labels": ["positive", "negative", "neutral"], "true_label": ["positive"], "examples": [["Great product, highly recommend!", "positive"], ["Terrible experience, very disappointed.", "negative"], ["It's okay, nothing special.", "neutral"]]}]}}
```

--------------------------------

### Prepare Domain-Specific Training Data with InputExample

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Format your domain-specific text and entity data using the InputExample class for training LoRA adapters. Ensure a sufficient number of examples (100-1000+) for optimal results.

```python
from gliner2.training.data import InputExample

# Legal domain examples
legal_examples = [
    InputExample(
        text="Apple Inc. filed a lawsuit against Samsung Electronics.",
        entities={"company": ["Apple Inc.", "Samsung Electronics"]}
    ),
    InputExample(
        text="The plaintiff Google LLC accused Microsoft Corporation of patent infringement.",
        entities={"company": ["Google LLC", "Microsoft Corporation"]}
    ),
    InputExample(
        text="Tesla Motors settled the case with the Securities and Exchange Commission.",
        entities={
            "company": ["Tesla Motors"],
            "organization": ["Securities and Exchange Commission"]
        }
    ),
    # Add 100-1000+ examples for best results
]
```

--------------------------------

### Best Practices: Relation Naming

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/6-relation_extraction.md

Examples of specific versus generic relation naming conventions.

```python
# Good - Clear and specific
schema.relations(["works_for", "reports_to", "manages"])

# Less ideal - Too generic
schema.relations(["related", "connected", "linked"])
```

--------------------------------

### Define Training Data for Multiple Domains

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Prepare input examples for different domains, specifying text and corresponding entities. Each domain requires a list of InputExample objects.

```python
from gliner2 import GLiNER2
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig
from gliner2.training.data import InputExample

# ============================================================================
# Define Domain Data
# ============================================================================

# Legal domain
legal_examples = [
    InputExample(
        text="Apple Inc. filed a lawsuit against Samsung Electronics.",
        entities={"company": ["Apple Inc.", "Samsung Electronics"]}
    ),
    InputExample(
        text="The plaintiff Google LLC accused Microsoft Corporation of patent infringement.",
        entities={"company": ["Google LLC", "Microsoft Corporation"]}
    ),
    # Add more examples...
]

# Medical domain
medical_examples = [
    InputExample(
        text="Patient diagnosed with Type 2 Diabetes and Hypertension.",
        entities={"disease": ["Type 2 Diabetes", "Hypertension"]}
    ),
    InputExample(
        text="Prescribed Metformin 500mg twice daily and Lisinopril 10mg once daily.",
        entities={
            "drug": ["Metformin", "Lisinopril"],
            "dosage": ["500mg", "10mg"]
        }
    ),
    # Add more examples...
]

# Customer support domain
support_examples = [
    InputExample(
        text="Customer John Smith reported issue with Order #12345.",
        entities={
            "customer": ["John Smith"],
            "order_id": ["Order #12345"]
        }
    ),
    InputExample(
        text="Refund of $99.99 processed for Order #98765 on 2024-01-15.",
        entities={
            "order_id": ["Order #98765"],
            "amount": ["$99.99"],
            "date": ["2024-01-15"]
        }
    ),
    # Add more examples...
]
```

--------------------------------

### Invalid Empty Output

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Examples with no tasks will fail validation.

```jsonl
{"input": "Random text with no specific information.", "output": {"entities": {}, "classifications": [], "json_structures": [], "relations": []}}
```

--------------------------------

### Implement Data Augmentation

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Create augmented versions of input examples, such as shuffling entity order. This function should return a list of augmented `InputExample` objects.

```python
from gliner2.training.data import InputExample, TrainingDataset

def augment_example(example: InputExample) -> List[InputExample]:
    """Create augmented versions of an example."""
    augmented = [example]  # Original
    
    # Shuffle entity order
    if len(example.entities) > 1:
        shuffled_entities = dict(sorted(example.entities.items(), reverse=True))
        augmented.append(InputExample(
            text=example.text,
            entities=shuffled_entities
        ))
    
    return augmented

# Apply augmentation
dataset = TrainingDataset.load("train.jsonl")
augmented_examples = []
for ex in dataset:
    augmented_examples.extend(augment_example(ex))

augmented_dataset = TrainingDataset(augmented_examples)
trainer.train(train_data=augmented_dataset)
```

--------------------------------

### Best Practices: Relation Descriptions

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/6-relation_extraction.md

Examples of providing context for ambiguous relations.

```python
# Good - Clear descriptions
schema.relations({
    "works_for": "Employment relationship where person works at organization",
    "consulted_for": "Consulting relationship where person provides services to organization"
})

# Less ideal - No context
schema.relations(["works_for", "consulted_for"])
```

--------------------------------

### Train LoRA Adapter using GLiNER2Trainer

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Initialize the GLiNER2Trainer with the base model and the configured training parameters, then start the adapter training process using the prepared training data.

```python
# Load base model
base_model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")

# Create trainer
trainer = GLiNER2Trainer(model=base_model, config=config)

# Train adapter
trainer.train(train_data=legal_examples)
```

--------------------------------

### Configure Training with Small Subset

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

For initial testing and debugging, start with a small subset of your training data by configuring `max_train_samples` in `TrainingConfig`.

```python
config = TrainingConfig(max_train_samples=100)
```

--------------------------------

### LoRA Training Scenarios

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Examples of configuring LoRA for specific training requirements like memory constraints, performance, or domain adaptation.

```python
# Train on GPU with limited memory
config = TrainingConfig(
    output_dir="./lora_small_memory",
    use_lora=True,
    lora_r=8,              # Smaller rank for less memory
    lora_alpha=16,
    batch_size=32,         # Can use larger batch with LoRA
    gradient_accumulation_steps=1,
    task_lr=5e-4,
    fp16=True
)

trainer = GLiNER2Trainer(model, config)
trainer.train(train_data="train.jsonl")
```

```python
# Use higher rank and include task heads for better performance
config = TrainingConfig(
    output_dir="./lora_high_perf",
    use_lora=True,
    lora_r=32,             # Higher rank
    lora_alpha=64,
    lora_dropout=0.05,
    lora_target_modules=["encoder", "span_rep", "classifier"],  # Encoder + task heads
    batch_size=16,
    task_lr=1e-3,          # Slightly higher LR
    num_epochs=15
)

trainer = GLiNER2Trainer(model, config)
trainer.train(train_data="train.jsonl")
```

```python
# Fine-tune for specific domain with LoRA
config = TrainingConfig(
    output_dir="./lora_medical",
    use_lora=True,
    lora_r=16,
    lora_alpha=32,
    lora_dropout=0.1,
    batch_size=16,
    task_lr=5e-4,
    num_epochs=20,
    warmup_ratio=0.05
)

trainer = GLiNER2Trainer(model, config)
trainer.train(train_data=medical_examples)
```

--------------------------------

### Define Input Structures

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Create structured data examples with optional choice fields for classification tasks.

```python
example = InputExample(
    text="iPhone 15 Pro costs $999 and comes in titanium color.",
    structures=[
        Structure(
            "product",
            name="iPhone 15 Pro",
            price="$999",
            color="titanium"
        )
    ]
)
```

```python
example = InputExample(
    text="Order #12345 for laptop shipped on 2024-01-15.",
    structures=[
        Structure(
            "order",
            order_id="12345",
            product="laptop",
            date="2024-01-15",
            status=ChoiceField(
                value="shipped",
                choices=["pending", "processing", "shipped", "delivered"]
            )
        )
    ]
)
```

--------------------------------

### Create Classification Examples

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Defines single-label and multi-label classification tasks using the Classification class.

```python
from gliner2.training.data import InputExample, Classification

# Single-label classification
example = InputExample(
    text="This movie is amazing! Best film of the year.",
    classifications=[
        Classification(
            task="sentiment",
            labels=["positive", "negative", "neutral"],
            true_label="positive"
        )
    ]
)

# Multi-label classification
example = InputExample(
    text="Python tutorial covers machine learning and web development.",
    classifications=[
        Classification(
            task="topic",
            labels=["programming", "machine_learning", "web_dev", "data_science"],
            true_label=["programming", "machine_learning", "web_dev"],
            multi_label=True
        )
    ]
)
```

--------------------------------

### Quick Start: Switching LoRA Adapters

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/11-adapter_switching.md

Load the base GLiNER2 model once, then load and switch between domain-specific adapters (legal, medical) for entity extraction without reloading the base model. Unload the adapter to revert to the base model's capabilities.

```python
from gliner2 import GLiNER2

# Load base model once
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")

# Load legal adapter
model.load_adapter("./legal_adapter")
legal_result = model.extract_entities("Apple sued Google", ["company"])

# Switch to medical adapter
model.load_adapter("./medical_adapter")
medical_result = model.extract_entities("Patient has diabetes", ["disease"])

# Use base model (no adapter)
model.unload_adapter()
base_result = model.extract_entities("Some text", ["entity"])
```

--------------------------------

### Entity Extraction with Character Positions

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/7-api.md

Use `include_spans=True` to get character-level start and end positions for each extracted entity. This is useful for precise location tracking within the text.

```python
# Include character-level start/end positions
results = extractor.extract_entities(
    "Apple released the iPhone 15.",
    ["company", "product"],
    include_spans=True
)
# Each entity includes: {'text': '...', 'start': 0, 'end': 5}
```

--------------------------------

### Adapter Pre-loading for Fast Switching

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Illustrative Python code snippet demonstrating how to pre-load adapter weights into memory to enable faster switching between adapters. This approach requires sufficient RAM.

```python
# Pre-load adapters in memory (if you have enough RAM)
adapters = {}
for domain, path in adapter_paths.items():
    # Load adapter weights into memory
    adapters[domain] = load_adapter_to_memory(path)

# Fast switching from memory (not implemented in base API,
# but possible with custom caching layer)
```

--------------------------------

### Load and Use GLiNER2 Adapters

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Shows how to initialize the base model and load a specific adapter for entity extraction.

```python
from gliner2 import GLiNER2

# Load base model once
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")

# Load legal adapter
model.load_adapter("./adapters/legal_adapter/final")

# Use the model
result = model.extract_entities(
    "Apple Inc. sued Samsung over patent rights.",
    ["company", "legal_action"]
)
print(result)
```

--------------------------------

### Swap Between Domain Adapters

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Illustrates switching between different domain adapters and reverting to the base model using unload_adapter().

```python
# Load base model
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")

# Legal domain
print("📋 Legal Analysis:")
model.load_adapter("./adapters/legal_adapter/final")
legal_text = "Google LLC filed a complaint against Oracle Corporation."
legal_result = model.extract_entities(legal_text, ["company", "legal_action"])
print(f"  {legal_result}")

# Swap to medical domain
print("\n🏥 Medical Analysis:")
model.load_adapter("./adapters/medical_adapter/final")
medical_text = "Patient presents with Pneumonia and was prescribed Amoxicillin."
medical_result = model.extract_entities(medical_text, ["disease", "drug"])
print(f"  {medical_result}")

# Swap to support domain
print("\n💬 Support Analysis:")
model.load_adapter("./adapters/support_adapter/final")
support_text = "Customer reported Order #12345 not delivered on time."
support_result = model.extract_entities(support_text, ["order_id", "issue"])
print(f"  {support_result}")

# Use base model without adapter
print("\n🔧 Base Model (no adapter):")
model.unload_adapter()
base_result = model.extract_entities("Some generic text", ["entity"])
print(f"  {base_result}")
```

--------------------------------

### Perform Relation Extraction

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Define binary or custom relations between entities within an input example.

```python
from gliner2.training.data import InputExample, Relation

# Binary relations
example = InputExample(
    text="Elon Musk founded SpaceX in 2002.",
    relations=[
        Relation("founded", head="Elon Musk", tail="SpaceX"),
        Relation("founded_in", head="SpaceX", tail="2002")
    ]
)
```

```python
# Custom relation fields
example = InputExample(
    text="Exercise improves mental health.",
    relations=[
        Relation(
            "causal_relation",
            cause="exercise",
            effect="mental health",
            direction="positive"
        )
    ]
)
```

--------------------------------

### Train Domain Adapters

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/10-lora_adapters.md

Demonstrates the training process for multiple domain-specific adapters using a base GLiNER2 model.

```python
if __name__ == "__main__":
    BASE_MODEL = "fastino/gliner2-base-v1"
    
    # Train adapters for each domain
    legal_adapter_path = train_domain_adapter(
        BASE_MODEL, legal_examples, "legal"
    )
    
    medical_adapter_path = train_domain_adapter(
        BASE_MODEL, medical_examples, "medical"
    )
    
    support_adapter_path = train_domain_adapter(
        BASE_MODEL, support_examples, "support"
    )
    
    print("\n" + "="*60)
    print("🎉 All adapters trained successfully!")
    print("="*60)
    print(f"Legal adapter:    {legal_adapter_path}")
    print(f"Medical adapter:  {medical_adapter_path}")
    print(f"Support adapter:  {support_adapter_path}")
```

--------------------------------

### Configure Learning Rate Schedules

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Set up different learning rate schedules, including linear warmup/decay, cosine annealing, cosine with restarts, and constant LR after warmup.

```python
# Linear warmup + linear decay (default)
config = TrainingConfig(
    scheduler_type="linear",
    warmup_ratio=0.1
)
```

```python
# Cosine annealing
config = TrainingConfig(
    scheduler_type="cosine",
    warmup_ratio=0.05
)
```

```python
# Cosine with restarts
config = TrainingConfig(
    scheduler_type="cosine_restarts",
    warmup_ratio=0.05,
    num_cycles=3
)
```

```python
# Constant LR after warmup
config = TrainingConfig(
    scheduler_type="constant",
    warmup_steps=500
)
```

--------------------------------

### Extracting Email Tags

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/1-classification.md

Example of extracting specific tags from an email text using a predefined schema.

```python
# FYI email example
email_text2 = """
Team,

Just wanted to let everyone know that I'll be out of office next Monday for a 
doctor's appointment. I'll be back Tuesday morning.

Thanks,
Mark
"""

results2 = extractor.extract(email_text2, schema)
print(results2)
```

--------------------------------

### Train a GLiNER2 model

Source: https://github.com/fastino-ai/gliner2/blob/main/README.md

Demonstrates the full pipeline from preparing input data to training and loading a fine-tuned GLiNER2 model.

```python
from gliner2 import GLiNER2
from gliner2.training.data import InputExample, TrainingDataset
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig

# Prepare training data
train_examples = [
    InputExample(
        text="Tim Cook is the CEO of Apple Inc., based in Cupertino, California.",
        entities={
            "person": ["Tim Cook"],
            "company": ["Apple Inc."],
            "location": ["Cupertino", "California"]
        },
        entity_descriptions={
            "person": "Full name of a person",
            "company": "Business organization name",
            "location": "Geographic location or place"
        }
    ),
    # Add more examples...
]

# Create and validate dataset
train_dataset = TrainingDataset(train_examples)
train_dataset.validate(strict=True, raise_on_error=True)
train_dataset.print_stats()

# Split into train/validation
train_data, val_data, _ = train_dataset.split(
    train_ratio=0.8,
    val_ratio=0.2,
    test_ratio=0.0,
    shuffle=True,
    seed=42
)

# Configure training
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")
config = TrainingConfig(
    output_dir="./ner_model",
    experiment_name="ner_training",
    num_epochs=15,
    batch_size=16,
    encoder_lr=1e-5,
    task_lr=5e-4,
    warmup_ratio=0.1,
    scheduler_type="cosine",
    fp16=True,
    eval_strategy="epoch",
    save_best=True,
    early_stopping=True,
    early_stopping_patience=3
)

# Train
trainer = GLiNER2Trainer(model, config)
trainer.train(train_data=train_data, val_data=val_data)

# Load best model
model = GLiNER2.from_pretrained("./ner_model/best")
```

--------------------------------

### Dataset Creation Tips

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Best practices and recommendations for creating high-quality datasets for gliner2.

```APIDOC
## Tips for Dataset Creation

1. **Use diverse examples** to improve model generalization
2. **Include edge cases** - but remember each example must have at least one task
3. **Provide descriptions** when possible to improve accuracy
4. **Balance your classes** in classification tasks
5. **Use realistic text** that matches your target domain
6. **Include multiple instances** for JSON structures when applicable
7. **For negative examples**, include at least one task (e.g., empty entities but a classification, or empty classifications but entities)
8. **Mix task types** to train multi-task capabilities
9. **Use consistent formatting** for similar examples
10. **Include special characters** to ensure robust handling
11. **Validate your dataset** using `TrainingDataset.validate(strict=True)` to catch annotation errors early
12. **Check relation consistency** using `validate_relation_consistency()` to ensure all relation types have consistent field structures
```

--------------------------------

### Single-Label Classification Schema

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/1-classification.md

Example of setting up a single-label classification schema for categories that are mutually exclusive, such as product sizes.

```python
# Should be single-label

schema = extractor.create_schema().classification(
    "size",
    ["small", "medium", "large"],
    multi_label=False  # Sizes are mutually exclusive
)
```

--------------------------------

### Use Descriptive Entity Names

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/2-ner.md

Demonstrates the difference between specific and generic entity naming conventions.

```python
# Good - Clear, specific entity types
schema.entities(["drug_name", "medical_device", "procedure_name"])

# Less ideal - Too generic
schema.entities(["thing", "item", "stuff"])
```

--------------------------------

### Multi-Label Classification Schema

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/1-classification.md

Example of setting up a multi-label classification schema for categories that are not mutually exclusive, such as product features.

```python
# Good use of multi-label

schema = extractor.create_schema().classification(
    "product_features",
    ["waterproof", "wireless", "rechargeable", "portable"],
    multi_label=True
)
```

--------------------------------

### Classify with Custom Prompts

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Inject a custom prompt to guide the model's reasoning process for specific tasks.

```jsonl
{"input": "The patient shows signs of improvement after treatment.", "output": {"classifications": [{"task": "medical_assessment", "labels": ["improving", "stable", "declining", "critical"], "true_label": ["improving"], "prompt": "Assess the patient's medical condition based on the clinical notes."}]}}
```

--------------------------------

### Validate Dataset and Fix Common Errors

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Methods for identifying invalid examples and correcting common entity annotation issues.

```python
# Check specific errors
dataset = TrainingDataset(examples)
report = dataset.validate(raise_on_error=False)

print(f"Invalid examples: {report['invalid_indices']}")
for error in report['errors'][:10]:
    print(error)

# Fix common issues:
# 1. Entity not in text
example = InputExample(
    text="John works here",
    entities={"person": ["John Smith"]}  # ERROR: "John Smith" not in text
)
# Fix: Use exact match
example = InputExample(
    text="John works here",
    entities={"person": ["John"]}  # OK
)

# 2. Empty entities
example = InputExample(
    text="Some text",
    entities={"person": []}  # ERROR: empty list
)
# Fix: Remove empty entity types
example = InputExample(
    text="Some text",
    entities={}  # OK if other tasks present
)

# 3. Use loose validation during development
dataset.validate(strict=False, raise_on_error=False)
```

--------------------------------

### Fine-tune GLiNER2 for Medical NER

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Demonstrates domain-specific fine-tuning using medical entity examples and adjusted learning rates.

```python
from gliner2 import GLiNER2
from gliner2.training.data import InputExample, TrainingDataset
from gliner2.training.trainer import GLiNER2Trainer, TrainingConfig

# Medical domain examples
medical_examples = [
    InputExample(
        text="Patient presented with hypertension and type 2 diabetes mellitus.",
        entities={
            "condition": ["hypertension", "type 2 diabetes mellitus"]
        },
        entity_descriptions={
            "condition": "Medical condition, disease, or symptom"
        }
    ),
    InputExample(
        text="Prescribed metformin 500mg twice daily. Patient to follow up in 2 weeks.",
        entities={
            "medication": ["metformin"],
            "dosage": ["500mg"],
            "frequency": ["twice daily"],
            "duration": ["2 weeks"]
        },
        entity_descriptions={
            "medication": "Prescribed drug or medication name",
            "dosage": "Amount or strength of medication",
            "frequency": "How often medication is taken",
            "duration": "Time period for treatment"
        }
    ),
    # More medical examples...
]

# Fine-tune on medical domain
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")
config = TrainingConfig(
    output_dir="./medical_ner",
    num_epochs=20,
    batch_size=16,
    encoder_lr=5e-6,  # Lower LR for fine-tuning
    task_lr=1e-4,
    warmup_ratio=0.05
)

trainer = GLiNER2Trainer(model, config)
trainer.train(train_data=medical_examples)
```

--------------------------------

### Switching Between Multiple LoRA Adapters

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/11-adapter_switching.md

Demonstrates seamless switching between different domain adapters (legal, medical, support) by calling `load_adapter()` sequentially. Each call automatically unloads the previous adapter.

```python
model = GLiNER2.from_pretrained("fastino/gliner2-base-v1")

# Legal domain
model.load_adapter("./legal_adapter")
result1 = model.extract_entities("Apple Inc. filed suit", ["company"])

# Medical domain (previous adapter auto-unloaded)
model.load_adapter("./medical_adapter")
result2 = model.extract_entities("Patient has diabetes", ["disease"])

# Support domain
model.load_adapter("./support_adapter")
result3 = model.extract_entities("Order #12345 issue", ["order_id"])
```

--------------------------------

### JSONL Training Data Formats

Source: https://github.com/fastino-ai/gliner2/blob/main/README.md

Examples of JSONL structures for entity extraction, classification, structured extraction, and relation extraction tasks.

```jsonl
{"input": "Tim Cook is the CEO of Apple Inc., based in Cupertino, California.", "output": {"entities": {"person": ["Tim Cook"], "company": ["Apple Inc."], "location": ["Cupertino", "California"]}, "entity_descriptions": {"person": "Full name of a person", "company": "Business organization name", "location": "Geographic location or place"}}}
{"input": "OpenAI released GPT-4 in March 2023.", "output": {"entities": {"company": ["OpenAI"], "model": ["GPT-4"], "date": ["March 2023"]}}}
```

```jsonl
{"input": "This movie is absolutely fantastic! I loved every minute of it.", "output": {"classifications": [{"task": "sentiment", "labels": ["positive", "negative", "neutral"], "true_label": ["positive"]}]}
{"input": "The service was terrible and the food was cold.", "output": {"classifications": [{"task": "sentiment", "labels": ["positive", "negative", "neutral"], "true_label": ["negative"]}]}}
```

```jsonl
{"input": "iPhone 15 Pro Max with 256GB storage, priced at $1199.", "output": {"json_structures": [{"product": {"name": "iPhone 15 Pro Max", "storage": "256GB", "price": "$1199"}}]}}
```

```jsonl
{"input": "John works for Apple Inc. and lives in San Francisco.", "output": {"relations": [{"works_for": {"head": "John", "tail": "Apple Inc."}}, {"lives_in": {"head": "John", "tail": "San Francisco"}}]}}
```

--------------------------------

### Extract Basic JSON Structure with GLiNER2

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/3-json_extraction.md

Demonstrates initializing the extractor and performing a simple product information extraction.

```python
from gliner2 import GLiNER2

# Load model
extractor = GLiNER2.from_pretrained("your-model-name")

# Simple product extraction
text = "The MacBook Pro costs $1999 and features M3 chip, 16GB RAM, and 512GB storage."
results = extractor.extract_json(
    text,
    {
        "product": [
            "name::str",
            "price",
            "features"
        ]
    }
)
print(results)
```

--------------------------------

### Multi-Tasking with Descriptions

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/8-train_data.md

Demonstrates combining entity extraction, classification, and structured JSON output with descriptive metadata.

```jsonl
{"input": "Dr. Johnson prescribed medication X for condition Y. Patient shows improvement.", "output": {"entities": {"person": ["Dr. Johnson"], "medication": ["medication X"], "condition": ["condition Y"]}, "entity_descriptions": {"person": "Healthcare provider names", "medication": "Prescribed drugs", "condition": "Medical conditions"}, "classifications": [{"task": "patient_status", "labels": ["improving", "stable", "declining"], "true_label": ["improving"], "label_descriptions": {"improving": "Patient condition getting better", "stable": "No change in condition", "declining": "Patient condition worsening"}}], "json_structures": [{"prescription": {"doctor": "Dr. Johnson", "medication": "medication X", "condition": "condition Y"}}], "json_descriptions": {"prescription": {"doctor": "Prescribing physician", "medication": "Prescribed drug name", "condition": "Diagnosed condition"}}}}
```

--------------------------------

### Email Validation with RegexValidator

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/5-validator.md

Validate email addresses using a RegexValidator. This example demonstrates how to define a pattern for emails and apply it to a text.

```python
email_validator = RegexValidator(r"^[\w\.-]+@[\w\.-]+\.\w+$")

text = "Contact: john@company.com, not-an-email, jane@domain.org"
# Output: ['john@company.com', 'jane@domain.org']
```

--------------------------------

### Complete Training Configuration Reference

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

A comprehensive list of all available parameters for the TrainingConfig class.

```python
config = TrainingConfig(
    # Output
    output_dir="./output",
    experiment_name="gliner2",
    
    # Training steps
    num_epochs=10,
    max_steps=-1,
    
    # Batch size
    batch_size=32,
    eval_batch_size=64,
    gradient_accumulation_steps=1,
    
    # Learning rates
    encoder_lr=1e-5,
    task_lr=5e-4,
    
    # Optimizer
    weight_decay=0.01,
    adam_beta1=0.9,
    adam_beta2=0.999,
    adam_epsilon=1e-8,
    max_grad_norm=1.0,
    
    # Learning rate schedule
    scheduler_type="linear",  # "linear", "cosine", "cosine_restarts", "constant"
    warmup_ratio=0.1,
    warmup_steps=0,
    num_cycles=0.5,
    
    # Mixed precision
    fp16=True,
    bf16=False,
    
    # Checkpointing & Evaluation (saves when evaluating)
    eval_strategy="steps",  # "epoch", "steps", or "no" (default: "steps")
    eval_steps=500,  # Evaluate and save every N steps (when eval_strategy="steps")
    save_total_limit=3,
    save_best=True,
    metric_for_best="eval_loss",
    greater_is_better=False,
    
    # Logging
    logging_steps=50,  # Update progress bar metrics every N steps
    # Metrics (loss, learning rate, throughput) are shown in the progress bar
    logging_first_step=True,
    report_to_wandb=False,  # Enable W&B logging for experiment tracking
    wandb_project=None,
    wandb_entity=None,
    wandb_run_name=None,
    wandb_tags=[],
    wandb_notes=None,
    
    # Early stopping
    early_stopping=False,
    early_stopping_patience=3,
    early_stopping_threshold=0.0,
    
    # DataLoader
    num_workers=4,
    pin_memory=True,
    prefetch_factor=2,
    
    # Other
    seed=42,
    deterministic=False,
    gradient_checkpointing=False,
    max_train_samples=-1,
    max_eval_samples=-1,
    validate_data=True,
    strict_validation=False,
    
    # LoRA (see LoRA section)
    use_lora=False,
    lora_r=16,
    lora_alpha=32.0,
    lora_dropout=0.0,
    lora_target_modules=["encoder", "span_rep", "classifier", "count_embed", "count_pred"],
    save_adapter_only=True,
)
```

--------------------------------

### Supported Training Data Formats

Source: https://github.com/fastino-ai/gliner2/blob/main/tutorial/9-training.md

Shows how to pass different data formats to the trainer, including JSONL files, lists, and datasets.

```python
# Format 1: JSONL file(s)
trainer.train(train_data="train.jsonl")
trainer.train(train_data=["train1.jsonl", "train2.jsonl"])

# Format 2: InputExample list
examples = [InputExample(...), ...]
trainer.train(train_data=examples)

# Format 3: TrainingDataset
dataset = TrainingDataset.load("train.jsonl")
trainer.train(train_data=dataset)

# Format 4: Raw dicts
raw_data = [{"input": "...", "output": {...}}, ...]
trainer.train(train_data=raw_data)
```

--------------------------------

### Extract Structured Data with GLiNER

Source: https://github.com/fastino-ai/gliner2/blob/main/README.md

Examples of using extract_json to parse entities with specific schema definitions, confidence scores, and character spans.

```python
# Product information extraction
text = "iPhone 15 Pro Max with 256GB storage, A17 Pro chip, priced at $1199. Available in titanium and black colors."

result = extractor.extract_json(
    text,
    {
        "product": [
            "name::str::Full product name and model",
            "storage::str::Storage capacity like 256GB or 1TB", 
            "processor::str::Chip or processor information",
            "price::str::Product price with currency",
            "colors::list::Available color options"
        ]
    }
)
# Output: {
#     'product': [{
#         'name': 'iPhone 15 Pro Max',
#         'storage': '256GB', 
#         'processor': 'A17 Pro chip',
#         'price': '$1199',
#         'colors': ['titanium', 'black']
#     }]
# }

# Multiple structured entities
text = "Apple Inc. headquarters in Cupertino launched iPhone 15 for $999 and MacBook Air for $1299."

result = extractor.extract_json(
    text,
    {
        "company": [
            "name::str::Company name",
            "location::str::Company headquarters or office location"
        ],
        "products": [
            "name::str::Product name and model",
            "price::str::Product retail price"
        ]
    }
)
# Output: {
#     'company': [{'name': 'Apple Inc.', 'location': 'Cupertino'}],
#     'products': [
#         {'name': 'iPhone 15', 'price': '$999'},
#         {'name': 'MacBook Air', 'price': '$1299'}
#     ]
# }

# With confidence scores
result = extractor.extract_json(
    "The MacBook Pro costs $1999 and features M3 chip, 16GB RAM, and 512GB storage.",
    {
        "product": [
            "name::str",
            "price",
            "features"
        ]
    },
    include_confidence=True
)
# Output: {
#     'product': [{
#         'name': {'text': 'MacBook Pro', 'confidence': 0.95},
#         'price': [{'text': '$1999', 'confidence': 0.92}],
#         'features': [
#             {'text': 'M3 chip', 'confidence': 0.88},
#             {'text': '16GB RAM', 'confidence': 0.90},
#             {'text': '512GB storage', 'confidence': 0.87}
#         ]
#     }]
# }

# With character positions (spans)
result = extractor.extract_json(
    "The MacBook Pro costs $1999 and features M3 chip.",
    {
        "product": [
            "name::str",
            "price"
        ]
    },
    include_spans=True
)
# Output: {
#     'product': [{
#         'name': {'text': 'MacBook Pro', 'start': 4, 'end': 15},
#         'price': [{'text': '$1999', 'start': 22, 'end': 27}]
#     }]
# }

# With both confidence and spans
result = extractor.extract_json(
    "The MacBook Pro costs $1999 and features M3 chip, 16GB RAM, and 512GB storage.",
    {
        "product": [
            "name::str",
            "price",
            "features"
        ]
    },
    include_confidence=True,
    include_spans=True
)
# Output: {
#     'product': [{
#         'name': {'text': 'MacBook Pro', 'confidence': 0.95, 'start': 4, 'end': 15},
#         'price': [{'text': '$1999', 'confidence': 0.92, 'start': 22, 'end': 27}],
#         'features': [
#             {'text': 'M3 chip', 'confidence': 0.88, 'start': 32, 'end': 39},
#             {'text': '16GB RAM', 'confidence': 0.90, 'start': 41, 'end': 49},
#             {'text': '512GB storage', 'confidence': 0.87, 'start': 55, 'end': 68}
#         ]
#     }]
# }
```