How to Use the GLiNER2 Bridge for Named Entity Recognition in Sieves

Set model_type=ModelType.gliner when initializing the NER task to automatically instantiate the GliNERBridge, which adapts the GLiNER2 model to Sieves' unified predictive interface for extracting entities without custom prompts.

The mantisai/sieves library provides a unified framework for predictive NLP tasks through its Pipeline API. When you require fast, accurate Named Entity Recognition without LLM overhead, the GLiNER2 bridge offers a specialized backend that converts GLiNER2 model outputs into the standard Sieves result schema. This integration allows you to treat GLiNER2 exactly like any other predictive model while preserving its native entity-type descriptions.

Installation and Prerequisites

GLiNER2 is included as a core dependency in Sieves, requiring no additional extras for basic functionality. The underlying gliner2 package installs automatically with the library.

pip install sieves

Alternatively, you can explicitly install with the optional extra:

pip install "sieves[gliner]"

Initializing the GLiNER2 NER Task

To activate the bridge, import the NER task from sieves.tasks.predictive.ner and specify ModelType.gliner. In sieves/tasks/predictive/ner/core.py, the _init_bridge method detects this model type and instantiates GliNERBridge with inference_mode=gliner_.InferenceMode.entities.

from sieves import Pipeline, ModelType
from sieves.tasks.predictive.ner import NER
from sieves.data import Doc

# Define entity types with descriptions

ner_task = NER(
    entities={
        "PERSON": "Names of people",
        "ORG": "Companies and organizations",
        "GPE": "Geopolitical entities like countries and cities"
    },
    model_type=ModelType.gliner,
    task_id="gliner_ner"
)

The entities dictionary maps type names to descriptions that GLiNER2 uses for zero-shot recognition.

Processing Documents

Wrap your text in Doc objects and pass them through a Pipeline. The GliNERBridge in sieves/tasks/predictive/gliner_bridge.py handles prompt conversion and result integration automatically.

# Create documents

docs = [Doc(text="Alice from Acme Corp visited Berlin.")]

# Build pipeline

pipeline = Pipeline([ner_task])

# Execute

processed_docs = pipeline(docs)

Accessing Extraction Results

Retrieve results from the doc.results dictionary using your task ID. The bridge converts raw GLiNER2 output dictionaries into NERResult objects containing validated NEREntity instances.

result = processed_docs[0].results["gliner_ner"]

for entity in result.entities:
    print(f"{entity.text} [{entity.entity_type}] score: {entity.score:.2f}")

Sample output:

Alice [PERSON] score: 0.97
Acme Corp [ORG] score: 0.91
Berlin [GPE] score: 0.94

Architecture: How the Bridge Works

Bridge Construction

When model_type=ModelType.gliner is specified, the NER task's _init_bridge method (lines 176-187 in sieves/tasks/predictive/ner/core.py) creates a GliNERBridge instance. This bridge implements the unified Bridge protocol required by all Sieves predictive tasks, connecting the high-level task API to the GLiNER2 model wrapper.

Schema Conversion

The GliNERBridge.prompt_signature property (lines 81-119 in sieves/tasks/predictive/gliner_bridge.py) uses convert_to_signature from sieves/tasks/predictive/utils.py to translate the unified Pydantic model into GLiNER2's native schema format. It specifically maps InferenceMode.entities to GLiNER2's "entities" extraction mode.

Execution and Integration

The GliNER wrapper in sieves/model_wrappers/gliner_.py exposes the model's batch_extract capability via its execute method. After inference, GliNERBridge.integrate (lines 144-176) transforms raw results into NEREntity objects, renaming the confidence field to score and storing a NERResult in doc.results. For chunked documents, GliNERBridge.consolidate (lines 258-400) merges per-chunk entities, deduplicates overlapping spans, and aggregates scores.

Limitations of the GLiNER2 Bridge

The GLiNER2 bridge operates differently from LLM-based bridges. According to the source code in sieves/model_wrappers/gliner_.py, the wrapper sets supports_few_shotting = False, meaning few-shot examples are not supported. Additionally, GliNERBridge._default_prompt_instructions returns an empty string because GLiNER2 does not utilize custom prompt templates. If you require custom prompting or few-shot learning, you must switch to ModelType.outlines or another LLM-based backend.

Complete Working Example

This runnable script demonstrates the full workflow from document creation to entity extraction using the GLiNER2 bridge.

from sieves import Pipeline, ModelType
from sieves.tasks.predictive.ner import NER
from sieves.data import Doc

# Initialize document

doc = Doc(text="Barack Obama was born in Hawaii and later moved to Washington D.C.")

# Configure NER with GLiNER2 bridge

ner = NER(
    entities={"PERSON": "Names of people", "GPE": "Geopolitical locations"},
    model_type=ModelType.gliner,
    task_id="ner_gliner"
)

# Create and run pipeline

pipeline = Pipeline([ner])
processed = pipeline([doc])

# Display results

output = processed[0].results["ner_gliner"]
print("Extracted entities:")
for entity in output.entities:
    print(f"- {entity.text!r} [{entity.entity_type}] (score={entity.score:.2f})")

Expected output:

Extracted entities:
- 'Barack Obama' [PERSON] (score=0.98)
- 'Hawaii' [GPE] (score=0.94)
- 'Washington D.C.' [GPE] (score=0.92)

Summary

• Set model_type=ModelType.gliner in the NER task to activate the GLiNER2 bridge
• The bridge auto-instantiates via _init_bridge in sieves/tasks/predictive/ner/core.py
• Results are stored as NERResult objects containing NEREntity instances with text, entity_type, and score attributes
• GLiNER2 does not support custom prompt instructions or few-shot examples
• Use InferenceMode.entities for standard named entity recognition tasks

Frequently Asked Questions

Do I need to install extra dependencies to use the GLiNER2 bridge in Sieves?

No. GLiNER2 is included as a core dependency in the mantisai/sieves package. The gliner2 library installs automatically with Sieves, though you can explicitly install with pip install "sieves[gliner]" if needed.

Can I use custom prompt templates with the GLiNER2 bridge?

No. The GliNERBridge explicitly disables custom prompts by returning an empty string from _default_prompt_instructions. GLiNER2 operates on entity type descriptions rather than free-form prompts. For custom prompting, switch to ModelType.outlines or another LLM-based model type.

How does the bridge handle document chunking and overlapping entities?

The GliNERBridge.consolidate method in sieves/tasks/predictive/gliner_bridge.py (lines 258-400) automatically merges entities from chunked document segments. It deduplicates overlapping spans and aggregates confidence scores when the same entity appears in multiple chunks.

Why can't I pass few-shot examples to the GLiNER2 NER task?

The GliNER wrapper in sieves/model_wrappers/gliner_.py sets supports_few_shotting = False because GLiNER2 is a zero-shot entity recognition model that uses entity type descriptions rather than example-based learning. Passing fewshot_examples will trigger a warning but not an error.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}