Skip to content

Commit a389722

Browse files
franciscojavierarceofranciscojavierarceo
committed
fix(file-processors): Harden worker-backed jobs.
Signed-off-by: Francisco Javier Arceo <farceo@redhat.com>
1 parent 812751c commit a389722

35 files changed

Lines changed: 1674 additions & 209 deletions

‎client-sdks/stainless/openapi.yml‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3735,22 +3735,44 @@ paths:
37353735
schema:
37363736
$ref: '#/components/schemas/ListProcessFileJobsResponse'
37373737
'400':
3738-
description: Bad Request
37393738
$ref: '#/components/responses/BadRequest400'
3739+
description: Bad Request
37403740
'429':
3741-
description: Too Many Requests
37423741
$ref: '#/components/responses/TooManyRequests429'
3742+
description: Too Many Requests
37433743
'500':
3744-
description: Internal Server Error
37453744
$ref: '#/components/responses/InternalServerError500'
3745+
description: Internal Server Error
37463746
default:
3747-
description: Default Response
37483747
$ref: '#/components/responses/DefaultError'
3748+
description: Default Response
37493749
tags:
37503750
- File Processors
37513751
summary: List file-processing jobs.
37523752
description: List file-processing jobs, most recent first.
37533753
operationId: list_process_file_jobs_v1alpha_file_processors_jobs_get
3754+
parameters:
3755+
- name: after
3756+
in: query
3757+
required: false
3758+
schema:
3759+
anyOf:
3760+
- type: string
3761+
- type: 'null'
3762+
description: Return jobs after this job ID.
3763+
title: After
3764+
description: Return jobs after this job ID.
3765+
- name: limit
3766+
in: query
3767+
required: false
3768+
schema:
3769+
type: integer
3770+
maximum: 100
3771+
minimum: 1
3772+
description: Maximum jobs to return.
3773+
default: 100
3774+
title: Limit
3775+
description: Maximum jobs to return.
37543776
post:
37553777
responses:
37563778
'200':
@@ -3760,17 +3782,17 @@ paths:
37603782
schema:
37613783
$ref: '#/components/schemas/ProcessFileJob'
37623784
'400':
3763-
description: Bad Request
37643785
$ref: '#/components/responses/BadRequest400'
3786+
description: Bad Request
37653787
'429':
3766-
description: Too Many Requests
37673788
$ref: '#/components/responses/TooManyRequests429'
3789+
description: Too Many Requests
37683790
'500':
3769-
description: Internal Server Error
37703791
$ref: '#/components/responses/InternalServerError500'
3792+
description: Internal Server Error
37713793
default:
3772-
description: Default Response
37733794
$ref: '#/components/responses/DefaultError'
3795+
description: Default Response
37743796
tags:
37753797
- File Processors
37763798
summary: Submit a file for asynchronous processing.
@@ -12935,6 +12957,11 @@ components:
1293512957
type: array
1293612958
title: Data
1293712959
description: The list of file-processing jobs.
12960+
has_more:
12961+
type: boolean
12962+
title: Has More
12963+
description: Whether more jobs are available after this page.
12964+
default: false
1293812965
type: object
1293912966
required:
1294012967
- data

‎docs/docs/providers/file_processors/inline_docling.mdx‎

Lines changed: 14 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ description: |
1111
- **Layout preservation** — tables, lists, and nested structures are converted to Markdown
1212
- **Multi-format support** — PDF, DOCX, PPTX, HTML, and images
1313
- **Better RAG quality** — structured chunks with heading metadata produce more relevant retrieval results
14-
- **VLM-based processing** — optionally route Vision Language Model inference through the stack's model-serving
15-
infrastructure for richer document understanding (layout analysis, OCR via vision models)
14+
- **VLM configuration validation** — VLM processing requires worker-side inference routing, which is not yet
15+
supported; configuring `vlm_model` currently produces a clear startup error
1616
1717
## Usage
1818
@@ -33,23 +33,13 @@ description: |
3333
config: {}
3434
```
3535
36-
### Enabling VLM Processing
36+
### VLM Processing
3737
38-
To enable VLM-based document processing, set `vlm_model` to a vision model registered with the
39-
stack's inference API. The VLM pipeline routes inference through the stack's model-serving
40-
infrastructure — no separate GPU resources are needed for document processing.
38+
VLM-based document processing is not currently available while this provider runs in worker
39+
mode because auto-routed inference cannot yet be reconstructed in the worker process. A
40+
configuration with `vlm_model` fails startup rather than silently running a different pipeline.
4141
42-
```yaml
43-
file_processors:
44-
- provider_id: docling
45-
provider_type: inline::docling
46-
config:
47-
vlm_model: granite-docling-258M
48-
vlm_preset: granite_docling
49-
```
50-
51-
When `vlm_model` is not set or no inference provider is available, the processor gracefully
52-
degrades to the standard non-VLM pipeline.
42+
Leave `vlm_model` unset to use the standard non-VLM pipeline.
5343
5444
## Installation
5545
@@ -80,8 +70,8 @@ preserves semantic boundaries. It supports PDF, DOCX, PPTX, HTML, and images.
8070
- **Layout preservation** — tables, lists, and nested structures are converted to Markdown
8171
- **Multi-format support** — PDF, DOCX, PPTX, HTML, and images
8272
- **Better RAG quality** — structured chunks with heading metadata produce more relevant retrieval results
83-
- **VLM-based processing** — optionally route Vision Language Model inference through the stack's model-serving
84-
infrastructure for richer document understanding (layout analysis, OCR via vision models)
73+
- **VLM configuration validation** — VLM processing requires worker-side inference routing, which is not yet
74+
supported; configuring `vlm_model` currently produces a clear startup error
8575

8676
## Usage
8777

@@ -102,23 +92,13 @@ file_processors:
10292
config: {}
10393
```
10494
105-
### Enabling VLM Processing
95+
### VLM Processing
10696
107-
To enable VLM-based document processing, set `vlm_model` to a vision model registered with the
108-
stack's inference API. The VLM pipeline routes inference through the stack's model-serving
109-
infrastructure — no separate GPU resources are needed for document processing.
110-
111-
```yaml
112-
file_processors:
113-
- provider_id: docling
114-
provider_type: inline::docling
115-
config:
116-
vlm_model: granite-docling-258M
117-
vlm_preset: granite_docling
118-
```
97+
VLM-based document processing is not currently available while this provider runs in worker
98+
mode because auto-routed inference cannot yet be reconstructed in the worker process. A
99+
configuration with `vlm_model` fails startup rather than silently running a different pipeline.
119100

120-
When `vlm_model` is not set or no inference provider is available, the processor gracefully
121-
degrades to the standard non-VLM pipeline.
101+
Leave `vlm_model` unset to use the standard non-VLM pipeline.
122102

123103
## Installation
124104

‎docs/static/deprecated-ogx-spec.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6774,6 +6774,11 @@ components:
67746774
type: array
67756775
title: Data
67766776
description: The list of file-processing jobs.
6777+
has_more:
6778+
type: boolean
6779+
title: Has More
6780+
description: Whether more jobs are available after this page.
6781+
default: false
67776782
type: object
67786783
required:
67796784
- data

‎docs/static/experimental-ogx-spec.yaml‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -385,22 +385,44 @@ paths:
385385
schema:
386386
$ref: '#/components/schemas/ListProcessFileJobsResponse'
387387
'400':
388-
description: Bad Request
389388
$ref: '#/components/responses/BadRequest400'
389+
description: Bad Request
390390
'429':
391-
description: Too Many Requests
392391
$ref: '#/components/responses/TooManyRequests429'
392+
description: Too Many Requests
393393
'500':
394-
description: Internal Server Error
395394
$ref: '#/components/responses/InternalServerError500'
395+
description: Internal Server Error
396396
default:
397-
description: Default Response
398397
$ref: '#/components/responses/DefaultError'
398+
description: Default Response
399399
tags:
400400
- File Processors
401401
summary: List file-processing jobs.
402402
description: List file-processing jobs, most recent first.
403403
operationId: list_process_file_jobs_v1alpha_file_processors_jobs_get
404+
parameters:
405+
- name: after
406+
in: query
407+
required: false
408+
schema:
409+
anyOf:
410+
- type: string
411+
- type: 'null'
412+
description: Return jobs after this job ID.
413+
title: After
414+
description: Return jobs after this job ID.
415+
- name: limit
416+
in: query
417+
required: false
418+
schema:
419+
type: integer
420+
maximum: 100
421+
minimum: 1
422+
description: Maximum jobs to return.
423+
default: 100
424+
title: Limit
425+
description: Maximum jobs to return.
404426
post:
405427
responses:
406428
'200':
@@ -410,17 +432,17 @@ paths:
410432
schema:
411433
$ref: '#/components/schemas/ProcessFileJob'
412434
'400':
413-
description: Bad Request
414435
$ref: '#/components/responses/BadRequest400'
436+
description: Bad Request
415437
'429':
416-
description: Too Many Requests
417438
$ref: '#/components/responses/TooManyRequests429'
439+
description: Too Many Requests
418440
'500':
419-
description: Internal Server Error
420441
$ref: '#/components/responses/InternalServerError500'
442+
description: Internal Server Error
421443
default:
422-
description: Default Response
423444
$ref: '#/components/responses/DefaultError'
445+
description: Default Response
424446
tags:
425447
- File Processors
426448
summary: Submit a file for asynchronous processing.
@@ -8122,6 +8144,11 @@ components:
81228144
type: array
81238145
title: Data
81248146
description: The list of file-processing jobs.
8147+
has_more:
8148+
type: boolean
8149+
title: Has More
8150+
description: Whether more jobs are available after this page.
8151+
default: false
81258152
type: object
81268153
required:
81278154
- data

‎docs/static/ogx-spec.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11473,6 +11473,11 @@ components:
1147311473
type: array
1147411474
title: Data
1147511475
description: The list of file-processing jobs.
11476+
has_more:
11477+
type: boolean
11478+
title: Has More
11479+
description: Whether more jobs are available after this page.
11480+
default: false
1147611481
type: object
1147711482
required:
1147811483
- data

‎docs/static/stainless-ogx-spec.yaml‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3735,22 +3735,44 @@ paths:
37353735
schema:
37363736
$ref: '#/components/schemas/ListProcessFileJobsResponse'
37373737
'400':
3738-
description: Bad Request
37393738
$ref: '#/components/responses/BadRequest400'
3739+
description: Bad Request
37403740
'429':
3741-
description: Too Many Requests
37423741
$ref: '#/components/responses/TooManyRequests429'
3742+
description: Too Many Requests
37433743
'500':
3744-
description: Internal Server Error
37453744
$ref: '#/components/responses/InternalServerError500'
3745+
description: Internal Server Error
37463746
default:
3747-
description: Default Response
37483747
$ref: '#/components/responses/DefaultError'
3748+
description: Default Response
37493749
tags:
37503750
- File Processors
37513751
summary: List file-processing jobs.
37523752
description: List file-processing jobs, most recent first.
37533753
operationId: list_process_file_jobs_v1alpha_file_processors_jobs_get
3754+
parameters:
3755+
- name: after
3756+
in: query
3757+
required: false
3758+
schema:
3759+
anyOf:
3760+
- type: string
3761+
- type: 'null'
3762+
description: Return jobs after this job ID.
3763+
title: After
3764+
description: Return jobs after this job ID.
3765+
- name: limit
3766+
in: query
3767+
required: false
3768+
schema:
3769+
type: integer
3770+
maximum: 100
3771+
minimum: 1
3772+
description: Maximum jobs to return.
3773+
default: 100
3774+
title: Limit
3775+
description: Maximum jobs to return.
37543776
post:
37553777
responses:
37563778
'200':
@@ -3760,17 +3782,17 @@ paths:
37603782
schema:
37613783
$ref: '#/components/schemas/ProcessFileJob'
37623784
'400':
3763-
description: Bad Request
37643785
$ref: '#/components/responses/BadRequest400'
3786+
description: Bad Request
37653787
'429':
3766-
description: Too Many Requests
37673788
$ref: '#/components/responses/TooManyRequests429'
3789+
description: Too Many Requests
37683790
'500':
3769-
description: Internal Server Error
37703791
$ref: '#/components/responses/InternalServerError500'
3792+
description: Internal Server Error
37713793
default:
3772-
description: Default Response
37733794
$ref: '#/components/responses/DefaultError'
3795+
description: Default Response
37743796
tags:
37753797
- File Processors
37763798
summary: Submit a file for asynchronous processing.
@@ -12935,6 +12957,11 @@ components:
1293512957
type: array
1293612958
title: Data
1293712959
description: The list of file-processing jobs.
12960+
has_more:
12961+
type: boolean
12962+
title: Has More
12963+
description: Whether more jobs are available after this page.
12964+
default: false
1293812965
type: object
1293912966
required:
1294012967
- data

‎src/ogx/core/admin.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
from pydantic import BaseModel
1212

1313
from ogx.core.datatypes import Api, StackConfig
14+
from ogx.core.jobs.runtime import get_job_runtime
1415
from ogx.core.server.fastapi_router_registry import (
1516
_ROUTER_FACTORIES,
1617
build_fastapi_router,
@@ -227,6 +228,9 @@ def _should_include_router_route(route: Any, router_prefix: str | None) -> bool:
227228
return ListRoutesResponse(data=ret)
228229

229230
async def health(self) -> HealthInfo:
231+
runtime = get_job_runtime()
232+
if runtime is not None and not runtime.pool.is_healthy:
233+
return HealthInfo(status=HealthStatus.ERROR)
230234
return HealthInfo(status=HealthStatus.OK)
231235

232236
async def version(self) -> VersionInfo:

‎src/ogx/core/inspect.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
from pydantic import BaseModel
1111

1212
from ogx.core.datatypes import Api, StackConfig
13+
from ogx.core.jobs.runtime import get_job_runtime
1314
from ogx.core.server.fastapi_router_registry import (
1415
_ROUTER_FACTORIES,
1516
build_fastapi_router,
@@ -103,6 +104,9 @@ def _should_include_router_route(route: Any, router_prefix: str | None) -> bool:
103104
return ListRoutesResponse(data=ret)
104105

105106
async def health(self) -> HealthInfo:
107+
runtime = get_job_runtime()
108+
if runtime is not None and not runtime.pool.is_healthy:
109+
return HealthInfo(status=HealthStatus.ERROR)
106110
return HealthInfo(status=HealthStatus.OK)
107111

108112
async def version(self) -> VersionInfo:

0 commit comments

Comments
 (0)