gliner-haystack 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,85 @@
1
+ Metadata-Version: 2.3
2
+ Name: gliner-haystack
3
+ Version: 0.1.0
4
+ Summary: Haystack entity extractors backed by GLiNER 2.5
5
+ Author: Max Swain
6
+ Requires-Dist: haystack-ai>=3.0,<4
7
+ Requires-Dist: httpx2>=0.1
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+
11
+ # gliner-haystack
12
+
13
+ Serve GLiNER2.5 with vLLM Factory using Docker Compose. GPU and CPU images are available:
14
+
15
+ | Image | Example Compose file | Requirements |
16
+ | --- | --- | --- |
17
+ | `ghcr.io/maxdswain/vllm-gliner:latest` (GPU) | [compose.yaml](compose.yaml) | NVIDIA GPU and NVIDIA Container Toolkit |
18
+ | `ghcr.io/maxdswain/vllm-gliner:latest-cpu` (x86-64 CPU) | [compose.cpu.yaml](compose.cpu.yaml) | x86-64 CPU |
19
+
20
+ ## Haystack components
21
+
22
+ Install with `uv sync --group dev --group test`. The text component returns labeled entity spans;
23
+ the document component stores them in copied documents' `meta["entities"]`:
24
+
25
+ ```python
26
+ from haystack import Document
27
+ from haystack_integrations.components.extractors.gliner import GLiNERDocumentExtractor, GLiNERTextExtractor
28
+
29
+ labels = ["person", "organization", "location"]
30
+ text_extractor = GLiNERTextExtractor(api_base_url="http://localhost:8000", http_client_kwargs={"timeout": 30.0})
31
+ document_extractor = GLiNERDocumentExtractor(max_concurrency=5)
32
+ try:
33
+ entities = text_extractor.run("Alice works at Acme in Paris.", labels)["entities"]
34
+ documents = document_extractor.run([Document(content="Alice works at Acme in Paris.")], labels)["documents"]
35
+ finally:
36
+ text_extractor.close()
37
+ document_extractor.close()
38
+ ```
39
+
40
+ Both components support `run_async` via Haystack 3's `Pipeline.run_async`. Document `run_async` sends requests
41
+ concurrently, with a semaphore enforcing `max_concurrency`; synchronous `run` processes documents sequentially.
42
+ Call `warm_up()` / `warm_up_async()` to prepare reusable HTTP clients if desired (runs also warm up lazily).
43
+ Call `close()` / `close_async()` to release them when done. HTTP client options such as `timeout` can be passed
44
+ via `http_client_kwargs` in either constructor.
45
+
46
+ Offline tests, lint, formatting and type checks: `uv run --group dev --group test poe check`.
47
+ To run tests against a live server:
48
+ `GLINER_INTEGRATION_URL=http://localhost:8000 uv run --group dev --group test poe test-integration`.
49
+ Integration tests skip when the variable is unset.
50
+
51
+ ## Python package releases
52
+
53
+ `.github/workflows/publish-package.yml` runs offline checks on pull requests and pushes to `main`
54
+ (Python 3.11 and 3.13). After successful checks on `main`, git-cliff finds releasable
55
+ Conventional Commits (`feat`, `fix`, `perf`, or breaking changes). If there are any, the
56
+ workflow updates `pyproject.toml` and `uv.lock`, builds distributions, commits the version,
57
+ creates a `vX.Y.Z` tag and GitHub Release with generated notes, then publishes those
58
+ artifacts to PyPI using the `pypi` GitHub environment and PyPI Trusted Publishing. The
59
+ initial release is `v0.1.0`; Docker-scoped commits do not release the Python package.
60
+ The release job needs permission to push its version commit and tag to `main` (check branch
61
+ protection rules). GitHub's `GITHUB_TOKEN` does not trigger another workflow when it creates
62
+ a release, so the PyPI publish job runs in the same workflow after the release job succeeds.
63
+
64
+ ## Quick start
65
+
66
+ Install Docker with Compose, then:
67
+
68
+ ```sh
69
+ git clone https://github.com/maxdswain/gliner-haystack.git
70
+ cd gliner-haystack
71
+
72
+ # GPU (default)
73
+ docker compose up
74
+
75
+ # Or CPU
76
+ docker compose -f compose.cpu.yaml up
77
+ ```
78
+
79
+ The first start downloads the model. Once the server is ready, try:
80
+
81
+ ```sh
82
+ curl http://localhost:8000/pooling \
83
+ -H 'Content-Type: application/json' \
84
+ -d '{"model":"/models/current","data":{"text":"Alice works at Acme in Paris.","schema":{"entities":{"person":"","organization":"","location":""}},"runtime":"classic","include_spans":true}}'
85
+ ```
@@ -0,0 +1,5 @@
1
+ haystack_integrations/components/extractors/gliner/__init__.py,sha256=dKYcQUIAsTLA9feNFdwReNMTWzyvWpzTLsyVMweWg84,243
2
+ haystack_integrations/components/extractors/gliner/extractors.py,sha256=9Zr2FeGLGsQPt2UHmtnCCdOPPs9O8trPvU-F3EpRXWo,7645
3
+ gliner_haystack-0.1.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
4
+ gliner_haystack-0.1.0.dist-info/METADATA,sha256=02jMirUIsVfeS4QeWim-7qK50eUfqwJ5Z0lqN8Z0BXI,3802
5
+ gliner_haystack-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.12.23
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,5 @@
1
+ """vLLM GLiNER entity extraction components for Haystack."""
2
+
3
+ from haystack_integrations.components.extractors.gliner.extractors import GLiNERDocumentExtractor, GLiNERTextExtractor
4
+
5
+ __all__ = ["GLiNERDocumentExtractor", "GLiNERTextExtractor"]
@@ -0,0 +1,180 @@
1
+ """Haystack entity extractors backed by vLLM Factory's GLiNER2.5 pooling API."""
2
+
3
+ import asyncio
4
+ from dataclasses import replace
5
+ from typing import Any
6
+
7
+ import httpx2
8
+ from haystack import Document, component
9
+
10
+
11
+ def _validate_labels(labels: list[str]) -> None:
12
+ if not labels or any(not isinstance(label, str) or not label.strip() for label in labels):
13
+ raise ValueError("labels must be a non-empty list of non-empty strings")
14
+
15
+
16
+ @component
17
+ class GLiNERTextExtractor:
18
+ """Extract labeled entities from text using the vLLM GLiNER2.5 server.
19
+
20
+ The ``entities`` mapping has one list per label. Each record includes
21
+ ``text``, ``start``, ``end``, and ``confidence`` when provided by the server.
22
+ """
23
+
24
+ def __init__(
25
+ self,
26
+ api_base_url: str = "http://localhost:8000",
27
+ model: str = "/models/current",
28
+ threshold: float = 0.5,
29
+ http_client_kwargs: dict[str, Any] | None = None,
30
+ ) -> None:
31
+ if not 0 <= threshold <= 1:
32
+ raise ValueError("threshold must be between 0 and 1")
33
+ self.api_base_url = api_base_url.rstrip("/")
34
+ self.model = model
35
+ self.threshold = threshold
36
+ self.http_client_kwargs = dict(http_client_kwargs) if http_client_kwargs is not None else {"timeout": 30.0}
37
+ self.client: httpx2.Client | None = None
38
+ self.async_client: httpx2.AsyncClient | None = None
39
+
40
+ def warm_up(self) -> None:
41
+ """Create and retain the synchronous HTTP client."""
42
+ if self.client is None:
43
+ self.client = httpx2.Client(**self.http_client_kwargs)
44
+
45
+ async def warm_up_async(self) -> None:
46
+ """Create and retain the asynchronous HTTP client."""
47
+ if self.async_client is None:
48
+ self.async_client = httpx2.AsyncClient(**self.http_client_kwargs)
49
+
50
+ def close(self) -> None:
51
+ """Release the synchronous client's connections."""
52
+ if self.client is not None:
53
+ self.client.close()
54
+ self.client = None
55
+
56
+ async def close_async(self) -> None:
57
+ """Release the asynchronous client's connections."""
58
+ if self.async_client is not None:
59
+ await self.async_client.aclose()
60
+ self.async_client = None
61
+
62
+ def _payload(self, text: str, labels: list[str]) -> dict[str, Any]:
63
+ _validate_labels(labels)
64
+ return {
65
+ "model": self.model,
66
+ "data": {
67
+ "text": text,
68
+ "schema": {"entities": {label: "" for label in labels}},
69
+ "runtime": "classic",
70
+ "threshold": self.threshold,
71
+ "include_spans": True,
72
+ "include_confidence": True,
73
+ },
74
+ }
75
+
76
+ @staticmethod
77
+ def _entities(response: httpx2.Response) -> dict[str, list[dict[str, Any]]]:
78
+ response.raise_for_status()
79
+ payload = response.json()
80
+ if not isinstance(payload, dict) or not isinstance(payload.get("data"), dict):
81
+ raise ValueError("Invalid vLLM GLiNER pooling response: expected a data object") # noqa: TRY004
82
+ entities = payload["data"].get("entities")
83
+ if not isinstance(entities, dict) or any(
84
+ not isinstance(label, str)
85
+ or not isinstance(records, list)
86
+ or any(not isinstance(record, dict) for record in records)
87
+ for label, records in entities.items()
88
+ ):
89
+ raise ValueError("Invalid vLLM GLiNER pooling response: expected labeled entity lists")
90
+ return entities
91
+
92
+ @component.output_types(entities=dict[str, list[dict[str, Any]]])
93
+ def run(self, text: str, labels: list[str]) -> dict[str, dict[str, list[dict[str, Any]]]]:
94
+ """Call ``POST /pooling`` synchronously."""
95
+ payload = self._payload(text, labels)
96
+ self.warm_up()
97
+ assert self.client is not None
98
+ response = self.client.post(f"{self.api_base_url}/pooling", json=payload)
99
+ return {"entities": self._entities(response)}
100
+
101
+ @component.output_types(entities=dict[str, list[dict[str, Any]]])
102
+ async def run_async(self, text: str, labels: list[str]) -> dict[str, dict[str, list[dict[str, Any]]]]:
103
+ """Call ``POST /pooling`` without blocking the event loop."""
104
+ payload = self._payload(text, labels)
105
+ await self.warm_up_async()
106
+ assert self.async_client is not None
107
+ response = await self.async_client.post(f"{self.api_base_url}/pooling", json=payload)
108
+ return {"entities": self._entities(response)}
109
+
110
+
111
+ @component
112
+ class GLiNERDocumentExtractor:
113
+ """Return copies of documents with labeled entities in ``meta['entities']``."""
114
+
115
+ def __init__(
116
+ self,
117
+ api_base_url: str = "http://localhost:8000",
118
+ model: str = "/models/current",
119
+ threshold: float = 0.5,
120
+ http_client_kwargs: dict[str, Any] | None = None,
121
+ max_concurrency: int = 5,
122
+ ) -> None:
123
+ if isinstance(max_concurrency, bool) or not isinstance(max_concurrency, int) or max_concurrency < 1:
124
+ raise ValueError("max_concurrency must be a positive integer")
125
+ self.text_extractor = GLiNERTextExtractor(api_base_url, model, threshold, http_client_kwargs)
126
+ self.max_concurrency = max_concurrency
127
+
128
+ def warm_up(self) -> None:
129
+ """Prepare the synchronous HTTP client."""
130
+ self.text_extractor.warm_up()
131
+
132
+ async def warm_up_async(self) -> None:
133
+ """Prepare the asynchronous HTTP client."""
134
+ await self.text_extractor.warm_up_async()
135
+
136
+ def close(self) -> None:
137
+ """Close the synchronous HTTP client."""
138
+ self.text_extractor.close()
139
+
140
+ async def close_async(self) -> None:
141
+ """Close the asynchronous HTTP client."""
142
+ await self.text_extractor.close_async()
143
+
144
+ @component.output_types(documents=list[Document])
145
+ def run(self, documents: list[Document], labels: list[str]) -> dict[str, list[Document]]:
146
+ """Extract entities synchronously per document, without mutating inputs."""
147
+ _validate_labels(labels)
148
+ result = []
149
+ for document in documents:
150
+ if document.content is None:
151
+ raise ValueError("GLiNERDocumentExtractor requires text document content")
152
+ entities = self.text_extractor.run(document.content, labels)["entities"]
153
+ result.append(replace(document, meta={**document.meta, "entities": entities}))
154
+ return {"documents": result}
155
+
156
+ @component.output_types(documents=list[Document])
157
+ async def run_async(self, documents: list[Document], labels: list[str]) -> dict[str, list[Document]]:
158
+ """Extract concurrently, bounding in-flight requests with a semaphore."""
159
+ _validate_labels(labels)
160
+ for document in documents:
161
+ if document.content is None:
162
+ raise ValueError("GLiNERDocumentExtractor requires text document content")
163
+
164
+ semaphore = asyncio.Semaphore(self.max_concurrency)
165
+ extractor = self.text_extractor
166
+ if not documents:
167
+ return {"documents": []}
168
+ await self.warm_up_async()
169
+ assert extractor.async_client is not None
170
+ client = extractor.async_client
171
+
172
+ async def extract(document: Document) -> Document:
173
+ async with semaphore:
174
+ response = await client.post(
175
+ f"{extractor.api_base_url}/pooling", json=extractor._payload(document.content or "", labels)
176
+ )
177
+ entities = extractor._entities(response)
178
+ return replace(document, meta={**document.meta, "entities": entities})
179
+
180
+ return {"documents": list(await asyncio.gather(*(extract(document) for document in documents)))}