content-core 2.2.1__tar.gz → 2.3.0__tar.gz

{content_core-2.2.1 → content_core-2.3.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "content-core",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Extract text content from URLs, documents, YouTube videos, Reddit posts, and audio/video files — via CLI (uvx) or MCP.",
   "author": {
     "name": "Luis Novo",

{content_core-2.2.1 → content_core-2.3.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "content-core",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Extract text content from URLs, documents, YouTube videos, Reddit posts, and audio/video files — via CLI (uvx) or MCP.",
   "skills": "./skills/"
 }

{content_core-2.2.1 → content_core-2.3.0}/AGENTS.md

@@ -134,6 +134,8 @@ Key settings: `url_engine`, `document_engine`, `audio_provider`, `audio_model`,
 
 Docling enrichment flags (`docling_ocr`, `docling_formulas`, `docling_vision`) control OCR, formula extraction, and image/chart processing when `document_engine="docling"`. These are also exposed as CLI flags (`--formulas`, `--pictures`, `--no-ocr`) and MCP parameters.
 
+`docling_vision_url` (plus `docling_vision_model`, `_api_key`, `_prompt`, `_max_tokens`, `_timeout`, `_token_param`) sends Docling's image descriptions to an OpenAI-compatible endpoint instead of the inline model. It only applies when `docling_vision` is on; without the URL, nothing is sent over the network.
+
 Priority: constructor args > env vars (`CCORE_*`) > config file (`~/.content-core/config.toml`) > defaults
 
 ## Code Style

{content_core-2.2.1 → content_core-2.3.0}/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-11-07
+
+### Added
+- Docling image descriptions can use any OpenAI-compatible chat completions endpoint (vLLM, Ollama, LM Studio, MLX servers...) instead of Docling's small inline model (#111, building on #104 by PhantombrainM). Set `docling_vision_url` (`CCORE_DOCLING_VISION_URL`), with optional `docling_vision_model`, `docling_vision_api_key`, `docling_vision_prompt`, `docling_vision_max_tokens` (default 400), `docling_vision_timeout` (default 20s) and `docling_vision_token_param` (`max_completion_tokens` or `max_tokens`). Applies only when `docling_vision` is on; without the URL, behavior is unchanged and nothing leaves the machine. Chart data extraction still uses Docling's own model. All settings work from the constructor, env vars and `content-core config set`.
+
 ## [2.2.1] - 2026-11-03
 
 ### Security

{content_core-2.2.1 → content_core-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: content-core
-Version: 2.2.1
+Version: 2.3.0
 Summary: Extract what matters from any media source. Available as Python Library, macOS Service, CLI and MCP Server
 Author-email: LUIS NOVO <lfnovo@gmail.com>
 License-File: LICENSE
@@ -285,6 +285,7 @@ Content Core uses `ContentCoreConfig` powered by pydantic-settings. Settings are
 | `CCORE_YOUTUBE_LANGUAGES` | Preferred YouTube transcript languages | - |
 | `CCORE_YOUTUBE_COOKIES_FILE` | Path to a Netscape `cookies.txt` for YouTube transcripts (missing file raises `ConfigurationError`) | - |
 | `CCORE_YOUTUBE_PROXY` | Proxy URL for YouTube transcripts, e.g. `http://user:pass@host:port` | - |
+| `CCORE_DOCLING_VISION_URL` | OpenAI-compatible endpoint (vLLM, Ollama, LM Studio...) for Docling image descriptions; unset keeps Docling's inline model. Related: `CCORE_DOCLING_VISION_MODEL`, `_API_KEY`, `_PROMPT`, `_MAX_TOKENS`, `_TIMEOUT`, `_TOKEN_PARAM` ([details](docs/usage.md#image-descriptions-via-an-openai-compatible-endpoint)) | - |
 
 API keys for external services are set via their standard environment variables (e.g., `OPENAI_API_KEY`, `FIRECRAWL_API_KEY`, `JINA_API_KEY`).
 

{content_core-2.2.1 → content_core-2.3.0}/README.md

@@ -240,6 +240,7 @@ Content Core uses `ContentCoreConfig` powered by pydantic-settings. Settings are
 | `CCORE_YOUTUBE_LANGUAGES` | Preferred YouTube transcript languages | - |
 | `CCORE_YOUTUBE_COOKIES_FILE` | Path to a Netscape `cookies.txt` for YouTube transcripts (missing file raises `ConfigurationError`) | - |
 | `CCORE_YOUTUBE_PROXY` | Proxy URL for YouTube transcripts, e.g. `http://user:pass@host:port` | - |
+| `CCORE_DOCLING_VISION_URL` | OpenAI-compatible endpoint (vLLM, Ollama, LM Studio...) for Docling image descriptions; unset keeps Docling's inline model. Related: `CCORE_DOCLING_VISION_MODEL`, `_API_KEY`, `_PROMPT`, `_MAX_TOKENS`, `_TIMEOUT`, `_TOKEN_PARAM` ([details](docs/usage.md#image-descriptions-via-an-openai-compatible-endpoint)) | - |
 
 API keys for external services are set via their standard environment variables (e.g., `OPENAI_API_KEY`, `FIRECRAWL_API_KEY`, `JINA_API_KEY`).
 

{content_core-2.2.1 → content_core-2.3.0}/docs/cli.md

@@ -162,6 +162,13 @@ content-core config delete llm_provider
 | `docling_ocr` | Enable OCR for scanned PDFs | `true` |
 | `docling_output_format` | Docling output format | `markdown` |
 | `docling_vision` | Enable image description + chart data extraction | `false` |
+| `docling_vision_url` | OpenAI-compatible chat completions URL for image descriptions (see [usage](usage.md#image-descriptions-via-an-openai-compatible-endpoint)) | — |
+| `docling_vision_model` | Model name sent to `docling_vision_url` | — |
+| `docling_vision_api_key` | Bearer token for `docling_vision_url` | — |
+| `docling_vision_prompt` | Prompt for image descriptions | Docling's prompt |
+| `docling_vision_max_tokens` | Token limit per image description | `400` |
+| `docling_vision_timeout` | Request timeout in seconds | `20` |
+| `docling_vision_token_param` | Token limit field name (`max_completion_tokens`, `max_tokens`) | `max_completion_tokens` |
 | `document_engine` | Document extraction engine (`auto`, `simple`, `docling`) | `auto` |
 | `firecrawl_api_url` | Firecrawl API URL | `https://api.firecrawl.dev` |
 | `firecrawl_proxy` | Firecrawl proxy mode (`auto`, `basic`, `stealth`) | `auto` |

{content_core-2.2.1 → content_core-2.3.0}/docs/usage.md

@@ -476,6 +476,37 @@ extract_content(file_path="paper.pdf", engine="docling", formulas=true, pictures
 
 > **Note:** Enrichment flags are only applied when `document_engine="docling"`. A warning is logged if flags are set without the Docling engine.
 
+### Image descriptions via an OpenAI-compatible endpoint
+
+By default, `docling_vision` describes images with Docling's small inline model, which often produces vague descriptions. You can send image descriptions to any OpenAI-compatible `/v1/chat/completions` endpoint instead (vLLM, Ollama, LM Studio, MLX servers, a hosted API...). Setting `docling_vision_url` is the switch: without it, nothing leaves the machine and the other settings below are ignored. `docling_vision` must still be on.
+
+| Setting | Env var | What it does | Default |
+|---------|---------|-------------|---------|
+| `docling_vision_url` | `CCORE_DOCLING_VISION_URL` | Chat completions endpoint | — (inline model) |
+| `docling_vision_model` | `CCORE_DOCLING_VISION_MODEL` | Model name sent in the request | — (server default) |
+| `docling_vision_api_key` | `CCORE_DOCLING_VISION_API_KEY` | Bearer token; no `Authorization` header when unset | — |
+| `docling_vision_prompt` | `CCORE_DOCLING_VISION_PROMPT` | Prompt sent with each image, e.g. to describe in another language | Docling's prompt |
+| `docling_vision_max_tokens` | `CCORE_DOCLING_VISION_MAX_TOKENS` | Token limit per image | `400` |
+| `docling_vision_timeout` | `CCORE_DOCLING_VISION_TIMEOUT` | Request timeout in seconds | `20` |
+| `docling_vision_token_param` | `CCORE_DOCLING_VISION_TOKEN_PARAM` | Name of the token limit field: `max_completion_tokens`, or `max_tokens` for servers that don't accept the newer field | `max_completion_tokens` |
+
+```bash
+export CCORE_DOCLING_VISION_URL=http://localhost:11434/v1/chat/completions
+export CCORE_DOCLING_VISION_MODEL=qwen2.5vl:7b
+content-core extract --engine docling --pictures report.pdf
+```
+
+```python
+config = ContentCoreConfig(
+    document_engine="docling",
+    docling_vision=True,
+    docling_vision_url="http://localhost:11434/v1/chat/completions",
+    docling_vision_model="qwen2.5vl:7b",
+)
+```
+
+Only image descriptions go to the endpoint. Chart data extraction keeps using Docling's own model, because it depends on special output tokens that a general-purpose vision model does not produce.
+
 ## Proxy Configuration
 
 Content Core uses standard HTTP proxy environment variables:

{content_core-2.2.1 → content_core-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "content-core"
-version = "2.2.1"
+version = "2.3.0"
 description = "Extract what matters from any media source. Available as Python Library, macOS Service, CLI and MCP Server"
 readme = "README.md"
 homepage = "https://github.com/lfnovo/content-core"

{content_core-2.2.1 → content_core-2.3.0}/src/content_core/cli.py

@@ -130,6 +130,13 @@ def config():
       docling_formulas     Enable formula extraction (default: false)
       docling_ocr          Enable OCR for scanned PDFs (default: true)
       docling_vision       Enable image description + chart extraction (default: false)
+      docling_vision_url   OpenAI-compatible chat completions URL for image descriptions (default: none, inline model)
+      docling_vision_model Model name sent to docling_vision_url
+      docling_vision_api_key  Bearer token for docling_vision_url
+      docling_vision_prompt   Prompt for image descriptions (default: docling's)
+      docling_vision_max_tokens  Token limit per image description (default: 400)
+      docling_vision_timeout     Request timeout in seconds (default: 20)
+      docling_vision_token_param Token limit field: max_completion_tokens or max_tokens (default: max_completion_tokens)
     """
     pass
 

{content_core-2.2.1 → content_core-2.3.0}/src/content_core/config.py

@@ -94,6 +94,19 @@ class ContentCoreConfig(BaseSettings):
     docling_formulas: bool = False
     docling_vision: bool = False
 
+    # Docling picture description via an OpenAI-compatible endpoint (vLLM,
+    # LM Studio, Ollama, ...). Only used when docling_vision is on; with no
+    # URL, docling's inline default model describes the pictures.
+    docling_vision_url: Optional[str] = None
+    docling_vision_model: Optional[str] = None
+    docling_vision_api_key: Optional[str] = None
+    docling_vision_prompt: Optional[str] = None  # None keeps docling's prompt
+    docling_vision_max_tokens: int = Field(default=400, ge=1)
+    docling_vision_timeout: float = Field(default=20.0, gt=0)
+    docling_vision_token_param: Literal["max_completion_tokens", "max_tokens"] = (
+        "max_completion_tokens"
+    )
+
     @classmethod
     def settings_customise_sources(
         cls,
@@ -155,7 +168,7 @@ def _write_config_file(data: dict) -> None:
     for key, value in sorted(data.items()):
         if isinstance(value, bool):
             lines.append(f"{key} = {str(value).lower()}")
-        elif isinstance(value, int):
+        elif isinstance(value, (int, float)):
             lines.append(f"{key} = {value}")
         elif isinstance(value, list):
             items = ", ".join(f'"{_escape_toml_string(str(v))}"' for v in value)
@@ -206,6 +219,8 @@ def config_set(key: str, value: str) -> None:
     annotation = field.annotation
     if annotation is int or (hasattr(annotation, "__origin__") and annotation is int):
         data[key] = int(value)
+    elif annotation is float:
+        data[key] = float(value)
     elif annotation is bool:
         token = value.lower()
         if token not in _TRUE_TOKENS | _FALSE_TOKENS:

{content_core-2.2.1 → content_core-2.3.0}/src/content_core/processors/document/docling.py

@@ -2,20 +2,28 @@
 Docling-based document extraction processor.
 """
 
+from typing import Optional
+from urllib.parse import urlsplit
+
 from content_core.config import ContentCoreConfig
 from content_core.common.messages import DOCLING_MISSING_MESSAGE
 from content_core.common.state import ExtractionOutput
+from content_core.logging import logger
 
 DOCLING_AVAILABLE = False
 try:
     from docling.datamodel.base_models import InputFormat
-    from docling.datamodel.pipeline_options import PdfPipelineOptions
+    from docling.datamodel.pipeline_options import (
+        PdfPipelineOptions,
+        PictureDescriptionApiOptions,
+    )
     from docling.document_converter import DocumentConverter, PdfFormatOption
 
     DOCLING_AVAILABLE = True
 except ImportError:
     InputFormat = None  # type: ignore
     PdfPipelineOptions = None  # type: ignore
+    PictureDescriptionApiOptions = None  # type: ignore
     PdfFormatOption = None  # type: ignore
 
     class DocumentConverter:  # type: ignore[no-redef]
@@ -45,14 +53,67 @@ DOCLING_SUPPORTED = {
 }
 
 
+def _picture_description_api_options(
+    config: ContentCoreConfig,
+) -> Optional["PictureDescriptionApiOptions"]:
+    """Build the options that send picture description to an OpenAI-compatible
+    endpoint, or return None to keep docling's inline default model.
+
+    ``docling_vision_url`` is the switch: without it, nothing leaves the
+    machine and the other ``docling_vision_*`` settings are ignored.
+    """
+    if not config.docling_vision_url or PictureDescriptionApiOptions is None:
+        return None
+
+    # The token limit field name differs across OpenAI-compatible servers:
+    # newer ones expect max_completion_tokens, older ones only accept
+    # max_tokens. docling_vision_token_param selects the name.
+    params: dict = {config.docling_vision_token_param: config.docling_vision_max_tokens}
+    if config.docling_vision_model:
+        params["model"] = config.docling_vision_model
+
+    # Only send an Authorization header when a key is configured; keyless
+    # local servers may reject an empty bearer token.
+    headers = {}
+    if config.docling_vision_api_key:
+        headers["Authorization"] = f"Bearer {config.docling_vision_api_key}"
+
+    kwargs = {}
+    if config.docling_vision_prompt:
+        kwargs["prompt"] = config.docling_vision_prompt
+
+    # Log only scheme and host: the URL may carry credentials in its
+    # userinfo or query string.
+    endpoint = urlsplit(config.docling_vision_url)
+    logger.debug(
+        f"Docling picture description via {endpoint.scheme}://{endpoint.hostname} "
+        f"(model={config.docling_vision_model or 'server default'})"
+    )
+    return PictureDescriptionApiOptions(
+        url=config.docling_vision_url,
+        headers=headers,
+        params=params,
+        timeout=config.docling_vision_timeout,
+        **kwargs,
+    )
+
+
 async def extract_docling(source: str, config: ContentCoreConfig) -> ExtractionOutput:
     """Extract content using Docling."""
     if DOCLING_AVAILABLE and PdfPipelineOptions is not None:
+        pipeline_kwargs = {}
+        api_vision_options = None
+        if config.docling_vision:
+            api_vision_options = _picture_description_api_options(config)
+            if api_vision_options is not None:
+                pipeline_kwargs["picture_description_options"] = api_vision_options
         pipeline_options = PdfPipelineOptions(
             do_ocr=config.docling_ocr,
             do_formula_enrichment=config.docling_formulas,
             do_picture_description=config.docling_vision,
             do_chart_extraction=config.docling_vision,
+            enable_remote_services=api_vision_options is not None,
+            **pipeline_kwargs,
         )
         converter = DocumentConverter(
             format_options={

{content_core-2.2.1 → content_core-2.3.0}/tests/unit/test_config_file.py

@@ -54,6 +54,24 @@ class TestConfigSet:
         config_set("stt_timeout", "1800")
         assert config_list()["stt_timeout"] == 1800
 
+    def test_set_float_value(self, config_dir):
+        config_set("docling_vision_timeout", "45.5")
+        assert config_list()["docling_vision_timeout"] == 45.5
+        assert ContentCoreConfig().docling_vision_timeout == 45.5
+
+    def test_set_docling_vision_endpoint(self, config_dir):
+        config_set("docling_vision_url", "http://localhost:1234/v1/chat/completions")
+        config_set("docling_vision_max_tokens", "800")
+        config_set("docling_vision_token_param", "max_tokens")
+        config = ContentCoreConfig()
+        assert config.docling_vision_url == "http://localhost:1234/v1/chat/completions"
+        assert config.docling_vision_max_tokens == 800
+        assert config.docling_vision_token_param == "max_tokens"
+
+    def test_set_invalid_token_param_raises(self, config_dir):
+        with pytest.raises(ValueError, match="max_completion_tokens"):
+            config_set("docling_vision_token_param", "max_length")
+
     def test_set_list_value(self, config_dir):
         config_set("youtube_languages", "en,pt,fr")
         assert config_list()["youtube_languages"] == ["en", "pt", "fr"]

content_core-2.3.0/tests/unit/test_docling_vision_api.py

@@ -0,0 +1,138 @@
+"""Unit tests for Docling picture description via an OpenAI-compatible endpoint
+(docling_vision_* settings / CCORE_DOCLING_VISION_* env vars)."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+from pydantic import ValidationError
+
+from content_core.config import ContentCoreConfig
+from content_core.processors.document import docling as docling_module
+
+pytest.importorskip("docling")
+
+URL = "http://localhost:1234/v1/chat/completions"
+
+
+@pytest.fixture(autouse=True)
+def isolated_settings(monkeypatch, tmp_path):
+    """Keep the caller's CCORE_DOCLING_VISION_* env vars and config file out."""
+    for var in list(os.environ):
+        if var.startswith("CCORE_DOCLING_VISION_"):
+            monkeypatch.delenv(var)
+    monkeypatch.setattr("content_core.config.CONFIG_FILE", tmp_path / "config.toml")
+
+
+def test_url_with_credentials_is_not_logged():
+    config = ContentCoreConfig(docling_vision_url="https://user:pw@vlm.example.com/v1/chat/completions?key=abc")
+    with patch.object(docling_module, "logger") as logger:
+        docling_module._picture_description_api_options(config)
+    logged = " ".join(str(c) for c in logger.debug.call_args_list)
+    assert "vlm.example.com" in logged
+    assert "pw" not in logged and "abc" not in logged
+
+
+def test_no_url_keeps_inline_default():
+    # URL is the switch: a model name alone must not enable the API path
+    config = ContentCoreConfig(docling_vision_url=None, docling_vision_model="some-model")
+    assert docling_module._picture_description_api_options(config) is None
+
+
+def test_url_builds_api_options():
+    config = ContentCoreConfig(
+        docling_vision_url=URL,
+        docling_vision_model="my-local-vlm",
+        docling_vision_api_key="secret",
+        docling_vision_max_tokens=800,
+        docling_vision_timeout=120,
+        docling_vision_prompt="Describe it.",
+    )
+
+    options = docling_module._picture_description_api_options(config)
+
+    assert options is not None
+    assert "localhost:1234" in str(options.url)
+    assert options.params["model"] == "my-local-vlm"
+    assert options.params["max_completion_tokens"] == 800
+    assert options.headers["Authorization"] == "Bearer secret"
+    assert options.timeout == 120
+    assert options.prompt == "Describe it."
+
+
+def test_defaults_keep_docling_prompt_and_timeout():
+    config = ContentCoreConfig(docling_vision_url=URL, docling_vision_api_key=None)
+    options = docling_module._picture_description_api_options(config)
+    default = docling_module.PictureDescriptionApiOptions()
+
+    assert options is not None
+    assert "Authorization" not in options.headers
+    assert "model" not in options.params
+    assert options.params["max_completion_tokens"] == 400
+    assert options.prompt == default.prompt
+    assert options.timeout == 20
+
+
+def test_token_param_name_is_selectable():
+    config = ContentCoreConfig(docling_vision_url=URL, docling_vision_token_param="max_tokens")
+    options = docling_module._picture_description_api_options(config)
+    assert options is not None
+    assert "max_tokens" in options.params
+    assert "max_completion_tokens" not in options.params
+
+
+def test_settings_read_from_env(monkeypatch):
+    monkeypatch.setenv("CCORE_DOCLING_VISION_URL", URL)
+    monkeypatch.setenv("CCORE_DOCLING_VISION_MODEL", "env-vlm")
+    monkeypatch.setenv("CCORE_DOCLING_VISION_MAX_TOKENS", "256")
+    monkeypatch.setenv("CCORE_DOCLING_VISION_TIMEOUT", "45.5")
+    monkeypatch.setenv("CCORE_DOCLING_VISION_TOKEN_PARAM", "max_tokens")
+
+    options = docling_module._picture_description_api_options(ContentCoreConfig())
+
+    assert options is not None
+    assert options.params == {"max_tokens": 256, "model": "env-vlm"}
+    assert options.timeout == 45.5
+
+
+@pytest.mark.parametrize(
+    "field,value",
+    [
+        ("docling_vision_max_tokens", "banana"),
+        ("docling_vision_max_tokens", 0),
+        ("docling_vision_timeout", "not-a-number"),
+        ("docling_vision_token_param", "max_length"),
+    ],
+)
+def test_invalid_settings_are_rejected(field, value):
+    with pytest.raises(ValidationError):
+        ContentCoreConfig(**{field: value})
+
+
+async def _run_extract(config):
+    mock_result = MagicMock()
+    mock_result.document.export_to_markdown.return_value = "content"
+    pipeline_cls = MagicMock()
+    with patch.object(docling_module, "DocumentConverter") as converter_cls, patch.object(
+        docling_module, "DOCLING_AVAILABLE", True
+    ), patch.object(docling_module, "PdfPipelineOptions", pipeline_cls), patch.object(
+        docling_module, "PdfFormatOption", MagicMock()
+    ), patch.object(docling_module, "InputFormat", MagicMock()):
+        converter_cls.return_value.convert.return_value = mock_result
+        await docling_module.extract_docling("/fake/doc.pdf", config)
+    return pipeline_cls.call_args[1]
+
+
+async def test_extract_wires_api_options_when_url_set():
+    config = ContentCoreConfig(docling_vision=True, docling_vision_url=URL)
+    kwargs = await _run_extract(config)
+    assert kwargs["enable_remote_services"] is True
+    assert "localhost:1234" in str(kwargs["picture_description_options"].url)
+
+
+async def test_extract_stays_local_without_vision():
+    # The URL alone does not turn picture description on
+    config = ContentCoreConfig(docling_vision=False, docling_vision_url=URL)
+    kwargs = await _run_extract(config)
+    assert kwargs["enable_remote_services"] is False
+    assert "picture_description_options" not in kwargs

{content_core-2.2.1 → content_core-2.3.0}/uv.lock

@@ -940,7 +940,7 @@ wheels = [
 
 [[package]]
 name = "content-core"
-version = "2.2.1"
+version = "2.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "ai-prompter" },