caption-flow 0.5.6__tar.gz → 0.6.0__tar.gz

{caption_flow-0.5.6 → caption_flow-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caption-flow
-Version: 0.5.6
+Version: 0.6.0
 Summary: Self-contained distributed community captioning system
 Author: bghira
 Author-email: bghira <bghira@users.github.com>
@@ -16,82 +16,83 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.12,<3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: websockets<17.0,>=16.0
-Requires-Dist: pyarrow<26.0.0,>=21.0.0
-Requires-Dist: click<9.0.0,>=8.2.0
-Requires-Dist: pydantic<3.0.0,>=2.12.0
-Requires-Dist: aiofiles<26.0.0,>=24.1.0
-Requires-Dist: rich<16.0.0,>=14.0.0
-Requires-Dist: cryptography<50.0.0,>=45.0.0
-Requires-Dist: PyYAML<7.0.0,>=6.0.2
-Requires-Dist: certbot<6.0.0,>=5.0.0
-Requires-Dist: numpy<3.0.0,>=2.2.0
-Requires-Dist: Pillow<13.0.0,>=11.3.0
+Requires-Dist: websockets<18.0,>=17.4
+Requires-Dist: pyarrow<27.0.0,>=26.0.1
+Requires-Dist: click<9.0.0,>=8.5.1
+Requires-Dist: pydantic<3.0.0,>=2.14.3
+Requires-Dist: aiofiles<26.0.0,>=25.1.0
+Requires-Dist: rich<16.0.0,>=15.0.0
+Requires-Dist: cryptography<51.0.0,>=50.0.2
+Requires-Dist: PyYAML<7.0.0,>=6.0.3
+Requires-Dist: certbot<6.0.0,>=5.10.0
+Requires-Dist: numpy<2.4.0,>=2.3.5; python_version < "3.13"
+Requires-Dist: numpy<2.5.0,>=2.4.6; python_version >= "3.13"
+Requires-Dist: Pillow<14.0.0,>=13.0.0
 Requires-Dist: trainingsample<0.4.0,>=0.3.2
-Requires-Dist: pandas<4.0.0,>=3.0.0
-Requires-Dist: datasets<6.0.0,>=5.0.0
-Requires-Dist: boto3<2.0.0,>=1.43.0
-Requires-Dist: webshart<0.6.0,>=0.5.2
-Requires-Dist: pylance<9.0.0,>=8.0.0
-Requires-Dist: duckdb<2.0.0,>=1.5.0
-Requires-Dist: aiohttp<4.0.0,>=3.13.3
-Requires-Dist: fastapi<0.137.0,>=0.133.0
-Requires-Dist: uvicorn<1.0.0,>=0.35.0
-Requires-Dist: huggingface-hub<2.0.0,>=1.5.0
-Requires-Dist: psutil<8.0.0,>=7.0.0
-Requires-Dist: requests<3.0.0,>=2.32.0
-Requires-Dist: tqdm<5.0.0,>=4.67.0
-Requires-Dist: urwid<5.0.0,>=3.0.2
+Requires-Dist: pandas<4.0.0,>=3.1.1
+Requires-Dist: datasets<6.0.0,>=5.2.0
+Requires-Dist: boto3<2.0.0,>=1.44.3
+Requires-Dist: webshart<0.7.0,>=0.6.0
+Requires-Dist: pylance<9.0.0,>=8.0.1
+Requires-Dist: duckdb<2.0.0,>=1.5.6
+Requires-Dist: aiohttp<4.0.0,>=3.14.5
+Requires-Dist: fastapi<0.137.0,>=0.136.3
+Requires-Dist: uvicorn<1.0.0,>=0.54.0
+Requires-Dist: huggingface-hub<2.0.0,>=1.33.0
+Requires-Dist: psutil<8.0.0,>=7.2.2
+Requires-Dist: requests<3.0.0,>=2.34.2
+Requires-Dist: tqdm<5.0.0,>=4.70.1
+Requires-Dist: urwid<6.0.0,>=5.1.3
 Provides-Extra: vllm
-Requires-Dist: vllm<0.26.0,>=0.25.1; extra == "vllm"
-Requires-Dist: torch==2.11.0; extra == "vllm"
-Requires-Dist: torchvision==0.26.0; extra == "vllm"
+Requires-Dist: vllm<0.34.0,>=0.33.0; extra == "vllm"
+Requires-Dist: torch==2.14.0; extra == "vllm"
+Requires-Dist: torchvision==0.29.0; extra == "vllm"
 Requires-Dist: torchaudio==2.11.0; extra == "vllm"
-Requires-Dist: transformers<6.0.0,>=5.5.3; extra == "vllm"
+Requires-Dist: transformers<5.21.0,>=5.16.1; extra == "vllm"
 Requires-Dist: qwen-vl-utils<0.1.0,>=0.0.14; extra == "vllm"
 Provides-Extra: captioning
-Requires-Dist: vllm<0.26.0,>=0.25.1; extra == "captioning"
-Requires-Dist: torch==2.11.0; extra == "captioning"
-Requires-Dist: torchvision==0.26.0; extra == "captioning"
+Requires-Dist: vllm<0.34.0,>=0.33.0; extra == "captioning"
+Requires-Dist: torch==2.14.0; extra == "captioning"
+Requires-Dist: torchvision==0.29.0; extra == "captioning"
 Requires-Dist: torchaudio==2.11.0; extra == "captioning"
-Requires-Dist: transformers<6.0.0,>=5.5.3; extra == "captioning"
+Requires-Dist: transformers<5.21.0,>=5.16.1; extra == "captioning"
 Requires-Dist: qwen-vl-utils<0.1.0,>=0.0.14; extra == "captioning"
 Provides-Extra: openai
 Provides-Extra: cpu
-Requires-Dist: torch>=2.11.0; extra == "cpu"
-Requires-Dist: torchvision>=0.26.0; extra == "cpu"
+Requires-Dist: torch>=2.14.0; extra == "cpu"
+Requires-Dist: torchvision>=0.29.0; extra == "cpu"
 Requires-Dist: torchaudio>=2.11.0; extra == "cpu"
 Provides-Extra: cuda
-Requires-Dist: torch>=2.11.0; extra == "cuda"
-Requires-Dist: torchvision>=0.26.0; extra == "cuda"
+Requires-Dist: torch>=2.14.0; extra == "cuda"
+Requires-Dist: torchvision>=0.29.0; extra == "cuda"
 Requires-Dist: torchaudio>=2.11.0; extra == "cuda"
 Provides-Extra: cuda13
-Requires-Dist: torch>=2.11.0; extra == "cuda13"
-Requires-Dist: torchvision>=0.26.0; extra == "cuda13"
+Requires-Dist: torch>=2.14.0; extra == "cuda13"
+Requires-Dist: torchvision>=0.29.0; extra == "cuda13"
 Requires-Dist: torchaudio>=2.11.0; extra == "cuda13"
 Provides-Extra: rocm
-Requires-Dist: torch>=2.11.0; extra == "rocm"
-Requires-Dist: torchvision>=0.26.0; extra == "rocm"
+Requires-Dist: torch>=2.14.0; extra == "rocm"
+Requires-Dist: torchvision>=0.29.0; extra == "rocm"
 Requires-Dist: torchaudio>=2.11.0; extra == "rocm"
 Provides-Extra: apple
-Requires-Dist: torch>=2.13.0; extra == "apple"
-Requires-Dist: torchvision>=0.28.0; extra == "apple"
+Requires-Dist: torch>=2.14.0; extra == "apple"
+Requires-Dist: torchvision>=0.29.0; extra == "apple"
 Requires-Dist: torchaudio>=2.11.0; extra == "apple"
-Requires-Dist: vllm-metal==0.1.0; (platform_system == "Darwin" and platform_machine == "arm64" and python_version >= "3.12") and extra == "apple"
+Requires-Dist: qwen-vl-utils<0.1.0,>=0.0.14; extra == "apple"
 Provides-Extra: dev
-Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio<2.0.0,>=1.1.0; extra == "dev"
-Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "dev"
-Requires-Dist: transformers<6.0.0,>=5.5.3; extra == "dev"
-Requires-Dist: black<26.0.0,>=25.0.0; extra == "dev"
-Requires-Dist: ruff<1.0.0,>=0.12.0; extra == "dev"
-Requires-Dist: mypy<2.0.0,>=1.17.0; extra == "dev"
+Requires-Dist: pytest<10.0.0,>=9.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0.0,>=1.5.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=7.1.0; extra == "dev"
+Requires-Dist: transformers<5.21.0,>=5.16.1; extra == "dev"
+Requires-Dist: black<27.0.0,>=26.10.1; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.17.5; extra == "dev"
+Requires-Dist: mypy<3.0.0,>=2.4.1; extra == "dev"
 Provides-Extra: all
-Requires-Dist: vllm<0.26.0,>=0.25.1; extra == "all"
-Requires-Dist: torch==2.11.0; extra == "all"
-Requires-Dist: torchvision==0.26.0; extra == "all"
+Requires-Dist: vllm<0.34.0,>=0.33.0; extra == "all"
+Requires-Dist: torch==2.14.0; extra == "all"
+Requires-Dist: torchvision==0.29.0; extra == "all"
 Requires-Dist: torchaudio==2.11.0; extra == "all"
-Requires-Dist: transformers<6.0.0,>=5.5.3; extra == "all"
+Requires-Dist: transformers<5.21.0,>=5.16.1; extra == "all"
 Requires-Dist: qwen-vl-utils<0.1.0,>=0.0.14; extra == "all"
 Dynamic: author
 Dynamic: license-file
@@ -128,6 +129,18 @@ pip install --upgrade pip
 pip install "caption-flow[vllm]"
 ```
 
+The Linux GPU worker extra targets vLLM 0.33.x with PyTorch 2.14.0,
+torchvision 0.29.0, and torchaudio 2.11.0 (as required by vLLM), plus
+Transformers 5.16.1–5.20.x and Pillow 13. To upgrade an existing worker from a checkout,
+run `pip install --upgrade -e ".[vllm]"` in its environment and restart it.
+
+The tested worker stack uses NumPy 2.3.x on Python 3.12 and 2.4.x
+on Python 3.13, and FastAPI below 0.137. These bounds are shared with the
+base install so adding the worker extra remains compatible. CI resolves
+the full Linux worker and development dependencies on both Python versions.
+Lance 8.x, DuckDB 1.x, and Hugging Face Hub 1.x remain bounded to their
+existing major versions pending separate migration testing.
+
 An OpenAI-compatible API worker does not need the GPU dependencies:
 
 ```bash
@@ -139,26 +152,36 @@ For an orchestrator or monitor-only install, use `pip install -e .`.
 SimpleTuner. Terminal image previews remain optional because the current
 `term-image` release requires an older Pillow major than CaptionFlow uses.
 
-On Apple Silicon, install the MPS-compatible PyTorch chain and pinned Metal
-plugin with:
+On Apple Silicon with macOS 14 or newer, install the MPS-compatible PyTorch
+chain and image utilities with:
 
 ```bash
 pip install -e ".[apple]"
 ```
 
-CaptionFlow can use vLLM on Apple Silicon too, but the normal Linux `vllm`
-wheel is not the Apple install path. The pinned `vllm-metal` dependency is
-selected automatically on native arm64 Python 3.12+. For a ready-to-run
-Metal worker, use the upstream installer, which also builds/installs the
-Apple-specific vLLM core:
+For native vLLM Metal captioning, use **macOS 15+, Apple Silicon, and Python
+3.12**. The current Metal wheels are published on
+[GitHub releases](https://github.com/vllm-project/vllm-metal/releases), while
+PyPI still carries the obsolete 0.1.0 plugin. From this checkout, install the
+matching stable vLLM 0.33.0 core and Metal 0.33.0 wheels into your environment:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash
-source ~/.venv-vllm-metal/bin/activate
-pip install -e .
+python -m pip install --upgrade -r requirements.metal.txt
+python -m pip install -e ".[dev]"
+python -m pip check
+python examples/metal_smoke.py
 ```
 
-Do not combine `.[apple]` with the Linux `.[vllm]` extra.
+The smoke test downloads `mlx-community/Qwen3-VL-2B-Instruct-4bit` on first
+use and runs two images through CaptionFlow's native caption pipeline. It
+checks that the Metal plugin and MLX GPU are active, and that the captions
+identify the images' shapes and different colors. Pass `--model /path/to/model`
+to use a local checkpoint. The test does not connect to an orchestrator.
+
+The stable recipe uses the core wheel's PyTorch 2.14.0 pin. Upstream's installer
+can select newer development builds and override Torch with nightly packages;
+those are separate from this recipe. `.[apple]` alone does not install a vLLM
+runtime, and should not be combined with the Linux `.[vllm]` extra.
 
 For native macOS CPU vLLM instead, follow the
 [official source-build instructions](https://docs.vllm.ai/en/stable/getting_started/installation/cpu/?device=apple).
@@ -220,7 +243,7 @@ Options:
 * **csv**: exports CSV-compatible data columns to the `--output` path containing incomplete metadata
 * **json**: creates a `.json` file for each sample inside the `--output` subdirectory containing **complete** metadata; useful for webdatasets
 * **txt**: creates `.txt` file for each sample inside the `--output` subdirectory containing ONLY captions
-* **webshart**: updates an **existing per-shard metadata `.json` file** by writing captions under the plural `captions` key. for this format, pass `--output` as the path to the existing shard metadata JSON file when exporting one shard. if you export multiple shards, pass `--output` as a directory containing one existing `{shard_name}.json` file per shard.
+* **webshart**: updates an **existing per-shard metadata `.json` file** by writing captions under the plural `captions` key. Strings, native JSON objects, and mixed lists are supported. JSON objects stored as text in Lance output columns are decoded during export, preserving nested values instead of writing Python dictionary representations. Native objects supplied through `Caption.outputs` are encoded as JSON only for Lance persistence. Requires webshart 0.6.0 or newer for native JSON caption support (included in the base dependencies). For this format, pass `--output` as the path to the existing shard metadata JSON file when exporting one shard. If you export multiple shards, pass `--output` as a directory containing one existing `{shard_name}.json` file per shard.
 * **huggingface_hub**: creates a dataset on Hugging Face Hub, possibly `--private` and `--nsfw` where necessary
 * **all**: creates the directory/file-generating export formats in a specified `--output` directory. prefer a directory here; `webshart` is a special case that expects existing per-shard metadata `.json` files rather than creating new metadata files.
 
@@ -279,6 +302,13 @@ prompts, sampling, and output fields. Existing `vllm:` configurations are also
 accepted by API workers for backward compatibility; endpoint-local `model`
 values take precedence over the broadcast model name.
 
+Direct vLLM and API workers share JSON validation, output transformations,
+refusal detection, and semantic retries. Configure those under
+`inference.output_processing`; use `response_format` and `retry_response_format`
+for constrained decoding on either backend. See the
+[structured JSON recipe](recipes/STRUCTURED_JSON.md) for examples and native
+vLLM tuning details.
+
 ---
 
 ## dataset formats
@@ -288,6 +318,15 @@ values take precedence over the broadcast model name.
 * webdatasets shards containing full image data; also can be hosted on the hub
 * local folder filled with images; orchestrator will serve the data to workers
 
+For indexed Webshart reads, set `orchestrator.webshart_prefetch_shards: 1` to
+download the next shard in the background while captioning the current one.
+The default is `0` (disabled). This works with both direct vLLM and API workers,
+does not move the sample cursor, and is ignored for explicit remote-range reads.
+Size `shard_cache_gb` to hold the current shard plus the lookahead. Prefetch
+retries are spaced by `webshart_cache_retry_interval` (30 seconds by default);
+a prefetch failure never marks samples processed or prevents reading the
+current cached shard.
+
 ## configuration path
 
 ### config discovery order

{caption_flow-0.5.6 → caption_flow-0.6.0}/README.md

@@ -27,6 +27,18 @@ pip install --upgrade pip
 pip install "caption-flow[vllm]"
 ```
 
+The Linux GPU worker extra targets vLLM 0.33.x with PyTorch 2.14.0,
+torchvision 0.29.0, and torchaudio 2.11.0 (as required by vLLM), plus
+Transformers 5.16.1–5.20.x and Pillow 13. To upgrade an existing worker from a checkout,
+run `pip install --upgrade -e ".[vllm]"` in its environment and restart it.
+
+The tested worker stack uses NumPy 2.3.x on Python 3.12 and 2.4.x
+on Python 3.13, and FastAPI below 0.137. These bounds are shared with the
+base install so adding the worker extra remains compatible. CI resolves
+the full Linux worker and development dependencies on both Python versions.
+Lance 8.x, DuckDB 1.x, and Hugging Face Hub 1.x remain bounded to their
+existing major versions pending separate migration testing.
+
 An OpenAI-compatible API worker does not need the GPU dependencies:
 
 ```bash
@@ -38,26 +50,36 @@ For an orchestrator or monitor-only install, use `pip install -e .`.
 SimpleTuner. Terminal image previews remain optional because the current
 `term-image` release requires an older Pillow major than CaptionFlow uses.
 
-On Apple Silicon, install the MPS-compatible PyTorch chain and pinned Metal
-plugin with:
+On Apple Silicon with macOS 14 or newer, install the MPS-compatible PyTorch
+chain and image utilities with:
 
 ```bash
 pip install -e ".[apple]"
 ```
 
-CaptionFlow can use vLLM on Apple Silicon too, but the normal Linux `vllm`
-wheel is not the Apple install path. The pinned `vllm-metal` dependency is
-selected automatically on native arm64 Python 3.12+. For a ready-to-run
-Metal worker, use the upstream installer, which also builds/installs the
-Apple-specific vLLM core:
+For native vLLM Metal captioning, use **macOS 15+, Apple Silicon, and Python
+3.12**. The current Metal wheels are published on
+[GitHub releases](https://github.com/vllm-project/vllm-metal/releases), while
+PyPI still carries the obsolete 0.1.0 plugin. From this checkout, install the
+matching stable vLLM 0.33.0 core and Metal 0.33.0 wheels into your environment:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash
-source ~/.venv-vllm-metal/bin/activate
-pip install -e .
+python -m pip install --upgrade -r requirements.metal.txt
+python -m pip install -e ".[dev]"
+python -m pip check
+python examples/metal_smoke.py
 ```
 
-Do not combine `.[apple]` with the Linux `.[vllm]` extra.
+The smoke test downloads `mlx-community/Qwen3-VL-2B-Instruct-4bit` on first
+use and runs two images through CaptionFlow's native caption pipeline. It
+checks that the Metal plugin and MLX GPU are active, and that the captions
+identify the images' shapes and different colors. Pass `--model /path/to/model`
+to use a local checkpoint. The test does not connect to an orchestrator.
+
+The stable recipe uses the core wheel's PyTorch 2.14.0 pin. Upstream's installer
+can select newer development builds and override Torch with nightly packages;
+those are separate from this recipe. `.[apple]` alone does not install a vLLM
+runtime, and should not be combined with the Linux `.[vllm]` extra.
 
 For native macOS CPU vLLM instead, follow the
 [official source-build instructions](https://docs.vllm.ai/en/stable/getting_started/installation/cpu/?device=apple).
@@ -119,7 +141,7 @@ Options:
 * **csv**: exports CSV-compatible data columns to the `--output` path containing incomplete metadata
 * **json**: creates a `.json` file for each sample inside the `--output` subdirectory containing **complete** metadata; useful for webdatasets
 * **txt**: creates `.txt` file for each sample inside the `--output` subdirectory containing ONLY captions
-* **webshart**: updates an **existing per-shard metadata `.json` file** by writing captions under the plural `captions` key. for this format, pass `--output` as the path to the existing shard metadata JSON file when exporting one shard. if you export multiple shards, pass `--output` as a directory containing one existing `{shard_name}.json` file per shard.
+* **webshart**: updates an **existing per-shard metadata `.json` file** by writing captions under the plural `captions` key. Strings, native JSON objects, and mixed lists are supported. JSON objects stored as text in Lance output columns are decoded during export, preserving nested values instead of writing Python dictionary representations. Native objects supplied through `Caption.outputs` are encoded as JSON only for Lance persistence. Requires webshart 0.6.0 or newer for native JSON caption support (included in the base dependencies). For this format, pass `--output` as the path to the existing shard metadata JSON file when exporting one shard. If you export multiple shards, pass `--output` as a directory containing one existing `{shard_name}.json` file per shard.
 * **huggingface_hub**: creates a dataset on Hugging Face Hub, possibly `--private` and `--nsfw` where necessary
 * **all**: creates the directory/file-generating export formats in a specified `--output` directory. prefer a directory here; `webshart` is a special case that expects existing per-shard metadata `.json` files rather than creating new metadata files.
 
@@ -178,6 +200,13 @@ prompts, sampling, and output fields. Existing `vllm:` configurations are also
 accepted by API workers for backward compatibility; endpoint-local `model`
 values take precedence over the broadcast model name.
 
+Direct vLLM and API workers share JSON validation, output transformations,
+refusal detection, and semantic retries. Configure those under
+`inference.output_processing`; use `response_format` and `retry_response_format`
+for constrained decoding on either backend. See the
+[structured JSON recipe](recipes/STRUCTURED_JSON.md) for examples and native
+vLLM tuning details.
+
 ---
 
 ## dataset formats
@@ -187,6 +216,15 @@ values take precedence over the broadcast model name.
 * webdatasets shards containing full image data; also can be hosted on the hub
 * local folder filled with images; orchestrator will serve the data to workers
 
+For indexed Webshart reads, set `orchestrator.webshart_prefetch_shards: 1` to
+download the next shard in the background while captioning the current one.
+The default is `0` (disabled). This works with both direct vLLM and API workers,
+does not move the sample cursor, and is ignored for explicit remote-range reads.
+Size `shard_cache_gb` to hold the current shard plus the lookahead. Prefetch
+retries are spaced by `webshart_cache_retry_interval` (30 seconds by default);
+a prefetch failure never marks samples processed or prevents reading the
+current cached shard.
+
 ## configuration path
 
 ### config discovery order

{caption_flow-0.5.6 → caption_flow-0.6.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=68.0.0", "wheel"]
+requires = ["setuptools>=77.0.3", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]

{caption_flow-0.5.6 → caption_flow-0.6.0}/setup.py

@@ -23,58 +23,61 @@ def get_version() -> str:
 
 
 base_deps = [
-    "websockets>=16.0,<17.0",
-    "pyarrow>=21.0.0,<26.0.0",
-    "click>=8.2.0,<9.0.0",
-    "pydantic>=2.12.0,<3.0.0",
-    "aiofiles>=24.1.0,<26.0.0",
-    "rich>=14.0.0,<16.0.0",
-    "cryptography>=45.0.0,<50.0.0",
-    "PyYAML>=6.0.2,<7.0.0",
-    "certbot>=5.0.0,<6.0.0",
-    "numpy>=2.2.0,<3.0.0",
-    "Pillow>=11.3.0,<13.0.0",
+    "websockets>=17.4,<18.0",
+    "pyarrow>=26.0.1,<27.0.0",
+    "click>=8.5.1,<9.0.0",
+    "pydantic>=2.14.3,<3.0.0",
+    "aiofiles>=25.1.0,<26.0.0",
+    "rich>=15.0.0,<16.0.0",
+    "cryptography>=50.0.2,<51.0.0",
+    "PyYAML>=6.0.3,<7.0.0",
+    "certbot>=5.10.0,<6.0.0",
+    # vLLM's mistral-common requires NumPy <2.4 on Python 3.12;
+    # its pinned numba 0.65 requires NumPy <2.5 on Python 3.13.
+    "numpy>=2.3.5,<2.4.0; python_version < '3.13'",
+    "numpy>=2.4.6,<2.5.0; python_version >= '3.13'",
+    "Pillow>=13.0.0,<14.0.0",
     "trainingsample>=0.3.2,<0.4.0",
-    "pandas>=3.0.0,<4.0.0",
-    "datasets>=5.0.0,<6.0.0",
-    "boto3>=1.43.0,<2.0.0",
-    "webshart>=0.5.2,<0.6.0",
-    "pylance>=8.0.0,<9.0.0",
-    "duckdb>=1.5.0,<2.0.0",
-    "aiohttp>=3.13.3,<4.0.0",
-    "fastapi>=0.133.0,<0.137.0",
-    "uvicorn>=0.35.0,<1.0.0",
-    "huggingface-hub>=1.5.0,<2.0.0",
-    "psutil>=7.0.0,<8.0.0",
-    "requests>=2.32.0,<3.0.0",
-    "tqdm>=4.67.0,<5.0.0",
-    "urwid>=3.0.2,<5.0.0",
+    "pandas>=3.1.1,<4.0.0",
+    "datasets>=5.2.0,<6.0.0",
+    "boto3>=1.44.3,<2.0.0",
+    "webshart>=0.6.0,<0.7.0",
+    "pylance>=8.0.1,<9.0.0",
+    "duckdb>=1.5.6,<2.0.0",
+    "aiohttp>=3.14.5,<4.0.0",
+    # vLLM 0.33 requires FastAPI below 0.137.
+    "fastapi>=0.136.3,<0.137.0",
+    "uvicorn>=0.54.0,<1.0.0",
+    "huggingface-hub>=1.33.0,<2.0.0",
+    "psutil>=7.2.2,<8.0.0",
+    "requests>=2.34.2,<3.0.0",
+    "tqdm>=4.70.1,<5.0.0",
+    "urwid>=5.1.3,<6.0.0",
 ]
 
-# vLLM 0.25.1 currently selects the PyTorch 2.11.0 family. Keep these
-# explicit so a worker install cannot silently combine incompatible torch
-# packages when another dependency broadens its requirements.
+# Match vLLM 0.33's published requirements, including torchaudio 2.11.0.
+# Keep these explicit so a worker install cannot silently combine incompatible
+# torch packages when another dependency broadens its requirements.
 vllm_deps = [
-    "vllm>=0.25.1,<0.26.0",
-    "torch==2.11.0",
-    "torchvision==0.26.0",
+    "vllm>=0.33.0,<0.34.0",
+    "torch==2.14.0",
+    "torchvision==0.29.0",
     "torchaudio==2.11.0",
-    "transformers>=5.5.3,<6.0.0",
+    "transformers>=5.16.1,<5.21.0",
     "qwen-vl-utils>=0.0.14,<0.1.0",
 ]
 
 PYTORCH_DEPENDENCIES = [
-    "torch>=2.11.0",
-    "torchvision>=0.26.0",
+    "torch>=2.14.0",
+    "torchvision>=0.29.0",
     "torchaudio>=2.11.0",
 ]
 
 APPLE_PYTORCH_DEPENDENCIES = [
-    "torch>=2.13.0",
-    "torchvision>=0.28.0",
-    "torchaudio>=2.11.0",
-    # vLLM Metal publishes Apple Silicon wheels for Python 3.12+.
-    "vllm-metal==0.1.0; platform_system == 'Darwin' and platform_machine == 'arm64' and python_version >= '3.12'",
+    *PYTORCH_DEPENDENCIES,
+    "qwen-vl-utils>=0.0.14,<0.1.0",
+    # Install the matching vLLM core and Metal wheels from upstream GitHub
+    # releases separately; PyPI's vllm-metal 0.1.0 is obsolete.
 ]
 
 extras_require = {
@@ -89,13 +92,13 @@ extras_require = {
     "rocm": PYTORCH_DEPENDENCIES,
     "apple": APPLE_PYTORCH_DEPENDENCIES,
     "dev": [
-        "pytest>=8.0.0,<9.0.0",
-        "pytest-asyncio>=1.1.0,<2.0.0",
-        "pytest-cov>=6.0.0,<7.0.0",
-        "transformers>=5.5.3,<6.0.0",
-        "black>=25.0.0,<26.0.0",
-        "ruff>=0.12.0,<1.0.0",
-        "mypy>=1.17.0,<2.0.0",
+        "pytest>=9.2.0,<10.0.0",
+        "pytest-asyncio>=1.5.0,<2.0.0",
+        "pytest-cov>=7.1.0,<8.0.0",
+        "transformers>=5.16.1,<5.21.0",
+        "black>=26.10.1,<27.0.0",
+        "ruff>=0.17.5,<1.0.0",
+        "mypy>=2.4.1,<3.0.0",
     ],
     "all": [*vllm_deps],
 }

{caption_flow-0.5.6 → caption_flow-0.6.0}/src/caption_flow/__init__.py

@@ -1,6 +1,6 @@
 """CaptionFlow - Distributed community captioning system."""
 
-__version__ = "0.5.6"
+__version__ = "0.6.0"
 
 from .monitor import Monitor
 from .orchestrator import Orchestrator

{caption_flow-0.5.6 → caption_flow-0.6.0}/src/caption_flow/models.py

@@ -6,7 +6,7 @@ import os
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 from PIL import Image
 
@@ -128,7 +128,9 @@ class Caption:
     caption_count: int = 1  # Number of captions generated for this item
     caption: Optional[str] = None
     captions: Optional[List[str]] = None
-    outputs: Dict[str, List[str]] = field(default_factory=dict)
+    outputs: Dict[str, Union[str, Dict[str, Any], List[Union[str, Dict[str, Any]]]]] = field(
+        default_factory=dict
+    )
     quality_score: Optional[float] = None
     quality_scores: Optional[List[float]] = None
 
@@ -179,12 +181,13 @@ class ProcessingStage:
     dtype: Optional[str] = None
     gpu_memory_utilization: Optional[float] = None
 
-    # Optional semantic fallback for empty/refused caption responses. API
-    # workers can omit the image on the fallback request when an upstream
-    # provider rejects the image before inference.
+    # Caption policy and recovery apply to every inference backend.
     retry_prompt: Optional[str] = None
     retry_without_image: bool = False
     retry_sampling: Optional[Dict[str, Any]] = None
+    output_processing: Optional[Dict[str, Any]] = None
+    response_format: Optional[Dict[str, Any]] = None
+    retry_response_format: Optional[Dict[str, Any]] = None
 
 
 @dataclass

{caption_flow-0.5.6 → caption_flow-0.6.0}/src/caption_flow/orchestrator.py

@@ -51,7 +51,7 @@ class Orchestrator:
         assert (
             processor_type is not None
         ), "You must supply processor_type in your orchestrator dataset configuration."
-        processor_config = ProcessorConfig(processor_type=processor_type, config=config)
+        self.processor_config = ProcessorConfig(processor_type=processor_type, config=config)
 
         # Initialize processor
         if processor_type == "webdataset":
@@ -70,7 +70,6 @@ class Orchestrator:
             caption_buffer_size=storage_config.get("caption_buffer_size", 1000),
         )
         self.auth = AuthManager(config.get("auth", {}))
-        self.processor.initialize(processor_config, self.storage)
 
         # Processing configuration
         self.chunks_per_request = config.get("chunks_per_request", 2)
@@ -132,6 +131,8 @@ class Orchestrator:
 
         # Initialize storage
         await self.storage.initialize()
+        # Checkpoints can include results that had not reached a durable flush.
+        self.processor.initialize(self.processor_config, self.storage)
 
         # Start background tasks
         asyncio.create_task(self._heartbeat_loop())
@@ -410,7 +411,9 @@ class Orchestrator:
 
         elif msg_type == "work_complete":
             unit_id = data["unit_id"]
-            self.processor.mark_completed(unit_id, worker_id)
+            if self.processor.mark_completed(unit_id, worker_id) is False:
+                logger.warning(f"Work unit {unit_id} reported complete before all results arrived")
+                return
             logger.debug(f"Work unit {unit_id} completed by worker {worker_id}")
             await self._send_activity(f"Chunk completed: {unit_id}")
 
@@ -428,9 +431,8 @@ class Orchestrator:
             logger.debug(f"Heartbeat from {worker_id}: {data}")
 
     async def _handle_results_submission(self, worker_id: str, data: Dict):
-        """Process results submission from worker - fires off async task and returns immediately."""
-        # Fire and forget - process in background
-        asyncio.create_task(self._process_result_async(worker_id, data))
+        """Accept results in connection order before handling a completion message."""
+        await self._process_result_async(worker_id, data)
 
     async def _process_result_async(self, worker_id: str, data: Dict):
         """Actually process the result in background."""
@@ -444,6 +446,9 @@ class Orchestrator:
             shard_name = job_id.shard_id
             chunk_name = job_id.chunk_id
 
+            if data.get("error") or not data.get("outputs"):
+                raise ValueError("A failed result cannot be recorded as completed work")
+
             result = WorkResult(
                 unit_id=data["unit_id"],
                 source_id=shard_name,
@@ -455,11 +460,6 @@ class Orchestrator:
                 processing_time_ms=data.get("processing_time_ms", 0),
             )
 
-            # Let processor handle any custom processing - this updates chunk tracker
-            # IMPORTANT: Call this BEFORE saving to storage so chunk tracker is updated
-            # regardless of whether the item is a duplicate
-            processed = self.processor.handle_result(result)
-
             # Create caption record for storage
             total_outputs = sum(len(v) for v in result.outputs.values())
 
@@ -480,7 +480,7 @@ class Orchestrator:
             caption = Caption(
                 job_id=job_id,
                 dataset=result.dataset,
-                shard=processed["source_id"],
+                shard=result.source_id,
                 chunk_id=chunk_name,
                 item_key=item_key,
                 captions=result.outputs.get("captions", []),
@@ -501,6 +501,11 @@ class Orchestrator:
             # Save to storage (might skip if duplicate)
             saved = await self.storage.save_caption(caption)
 
+            # Progress may only follow storage acceptance. A duplicate is also
+            # accepted: its caption is already present. Startup reconstructs
+            # progress from durable storage if buffered results are lost.
+            self.processor.handle_result(result)
+
             # Update contributor stats only if actually saved
             if saved:
                 contributor = await self.storage.get_contributor(worker_user)
@@ -509,8 +514,11 @@ class Orchestrator:
                     await self.storage.save_contributor(contributor)
 
         except Exception as e:
+            if data.get("unit_id"):
+                self.processor.mark_failed(data["unit_id"], worker_id, "Result acceptance failed")
             logger.error(
-                f"Error processing result from {worker_id} for unit {data.get('unit_id', 'unknown')}: {e}",
+                f"Error processing result from {worker_id} "
+                f"for unit {data.get('unit_id', 'unknown')}: {e}",
                 exc_info=True,
             )