Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format follows

## [Unreleased]

## [0.1.1] - 2026-11-03

### Fixed

- Every labelled series (`ocr_documents_total{status}`, `ocr_pages_total{source}`,
`ocr_errors_total{type}`, `ocr_page_seconds{source}`) is exported from startup, at zero. Before,
a series appeared only after its first observation, so a freshly (re)started adapter exported
none of them and a Grafana panel showed "No data" instead of zero until the next document.

### Changed

- The image carries the `LICENSE` file in the package metadata.
Expand Down Expand Up @@ -34,5 +43,6 @@ Osnabrück University since 2026-10-16.
- Container image `ghcr.io/virtuos/librechat-ocr-adapter` for `linux/amd64` and `linux/arm64`,
installed from `uv.lock`.

[Unreleased]: https://github.com/virtUOS/librechat-ocr-adapter/compare/v0.1.0...HEAD
[Unreleased]: https://github.com/virtUOS/librechat-ocr-adapter/compare/v0.1.1...HEAD
[0.1.1]: https://github.com/virtUOS/librechat-ocr-adapter/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/virtUOS/librechat-ocr-adapter/releases/tag/v0.1.0
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,14 +113,14 @@ URL, `/ocr`, delete) and prints the Markdown joined like LibreChat (`# PAGE n` h
raw JSON with `--json`. Page count, time and per-page sources go to stderr.

```
uvx --from git+https://github.com/virtUOS/librechat-ocr-adapter@v0.1.0 librechat-ocr \
uvx --from git+https://github.com/virtUOS/librechat-ocr-adapter@v0.1.1 librechat-ocr \
document.pdf --base-url https://ocr.example.org --key "$OCR_API_KEY" [--pages 115-121] [--json]
```

The same from the image:

```
docker run --rm -v "$PWD:/data" ghcr.io/virtuos/librechat-ocr-adapter:0.1.0 \
docker run --rm -v "$PWD:/data" ghcr.io/virtuos/librechat-ocr-adapter:0.1.1 \
librechat-ocr /data/document.pdf --base-url https://ocr.example.org --key "$OCR_API_KEY"
```

Expand Down Expand Up @@ -156,6 +156,9 @@ Errors are JSON `{"message", "type"}`: 400 `invalid_request`, 404 `not_found`, 4
| `ocr_page_seconds{source}` | histogram of per-page processing time |
| `ocr_document_seconds` | histogram of per-document processing time |

Every labelled series exists from startup, at zero, so a restart shows as a counter reset rather
than as a gap.

Put the route behind authentication too (basic auth on the proxy, as in the Caddy example's
style) before pointing a Prometheus at it.

Expand Down
2 changes: 1 addition & 1 deletion examples/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ services:
retries: 3

ocr-adapter:
image: ghcr.io/virtuos/librechat-ocr-adapter:0.1.0
image: ghcr.io/virtuos/librechat-ocr-adapter:0.1.1
environment:
OCR_VLLM_URL: http://vllm:8000
OCR_PUBLIC_URL: https://ocr.example.org
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "librechat-ocr-adapter"
version = "0.1.0"
version = "0.1.1"
description = "Mistral-OCR-compatible document OCR service for LibreChat on top of vLLM and LightOnOCR"
readme = "README.md"
license = "MIT"
Expand Down
28 changes: 28 additions & 0 deletions src/ocr_adapter/metrics.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,27 @@
generate_latest,
)

from ocr_adapter.errors import AdapterError

# Every labelled series is created at startup, at zero. prometheus_client emits
# a labelled series only after its first observation, so a freshly started
# adapter would otherwise export no ocr_documents_total, ocr_pages_total,
# ocr_errors_total or ocr_page_seconds at all, and a dashboard would show
# "No data" instead of zero until the first document arrives.
PAGE_SOURCES = ("text", "ocr")
# "ok", the document deadline, and the errors a page task can raise
# (Pipeline.process reports the first of them as the document's status).
DOCUMENT_STATUSES = (
"ok",
"timeout",
"client_disconnected",
"too_large",
"unprocessable",
"upstream_error",
"upstream_unavailable",
)
ERROR_TYPES = tuple(cls.type for cls in (AdapterError, *AdapterError.__subclasses__()))


class Metrics:
"""One registry per instance so tests never collide on metric names."""
Expand Down Expand Up @@ -40,6 +61,13 @@ def __init__(self, registry: CollectorRegistry | None = None):
buckets=(0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600, 1200),
registry=r,
)
for status in DOCUMENT_STATUSES:
self.documents.labels(status=status)
for source in PAGE_SOURCES:
self.pages.labels(source=source)
self.page_seconds.labels(source=source)
for type_ in ERROR_TYPES:
self.errors.labels(type=type_)

def render(self) -> bytes:
return generate_latest(self.registry)
14 changes: 14 additions & 0 deletions tests/test_metrics.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
"""The labelled series exist from the first scrape, at zero."""

from ocr_adapter.metrics import Metrics


def test_labelled_series_exist_before_the_first_observation():
text = Metrics().render().decode()
assert 'ocr_documents_total{status="ok"} 0.0' in text
assert 'ocr_documents_total{status="timeout"} 0.0' in text
assert 'ocr_pages_total{source="text"} 0.0' in text
assert 'ocr_pages_total{source="ocr"} 0.0' in text
assert 'ocr_page_seconds_count{source="ocr"} 0.0' in text
assert 'ocr_errors_total{type="upstream_error"} 0.0' in text
assert 'ocr_errors_total{type="internal_error"} 0.0' in text
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading