Release abstractcore 2.13.33

Author: lpalbou

ACKNOWLEDGEMENTS.md

@@ -25,7 +25,7 @@ Features:
 - **Tools / web**: **requests**, **beautifulsoup4**, **lxml**, **ddgs** / **duckduckgo-search**, **psutil**
 - **Embeddings**: **sentence-transformers**, **numpy**
 - **Tokens**: **tiktoken**
-- **Media / documents**: **Pillow**, **pymupdf4llm**, **pymupdf-layout**, **unstructured**, **pandas**
+- **Media / documents**: **Pillow**, **pypdf**, **unstructured**, **pandas**. PyMuPDF-family PDF tooling is available only through the explicit commercial-license opt-in extra.
 - **Compression**: **Pillow** (glyph rendering)
 - **Server**: **fastapi**, **uvicorn**, **python-multipart**, **sse-starlette**
 - **Vision plugin integration**: **abstractvision**

CHANGELOG.md

@@ -7,12 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.13.33] - 2026-06-07
+
 ### Added
+- **Image upscaling routes**: added `/v1/images/upscale`, `/{provider}/v1/images/upscale`, and async `/v1/vision/jobs/images/upscale` with polling/progress support.
+- **Generated image upscaling**: `generate(..., output={"task": "image_upscale"})` routes source images through the AbstractVision upscaler capability.
 - **HTTP server CLI**: added `abstractcore serve` as the first-class command for starting the OpenAI-compatible AbstractCore server. Existing module and uvicorn entrypoints remain available for compatibility.
+- **MLX-Gen reference-image edits**: `/v1/images/edits` and async `/v1/vision/jobs/images/edits` now accept repeated multipart `reference_images` files and forward them to AbstractVision backends for composition/style-reference image edits.
+- **Image progress events**: async image generation/edit jobs now capture AbstractVision `on_progress(event)` payloads in `progress.last_event`, matching the existing video job surface.
+- **Wan A14B second guidance**: video generation routes, async video jobs, and generated-video output specs now accept typed `guidance_2` for dual-transformer video models.
 
 ### Removed
 - **Capability default CLI compatibility flags**: removed the top-level `abstractcore --set-capability-default` / `--clear-capability-default` form. Use `abstractcore config set-default`, `abstractcore config defaults`, and `abstractcore config clear-default` instead.
 
+### Changed
+- **Permissive PDF media path**: moved the default `PDFProcessor` and `media`/aggregate install profiles from PyMuPDF-family packages to the BSD-licensed `pypdf` baseline. PyMuPDF4LLM and `pymupdf-layout` remain available only through the explicit `pdf-pymupdf-commercial` opt-in extra.
+- **Vision plugin floor**: raised AbstractVision integration requirements to `abstractvision>=0.3.22` so Core installs pick up MLX-Gen `0.18.13`, SeedVR2 image upscaling, canonical q8/q4 upscaler packages, and the current upscaler progress event surface.
+- **Vision job progress semantics**: normalized server job payloads now preserve AbstractVision `step_progress` and `frame_progress`; `progress` follows the backend event's canonical progress value, which is denoise-step progress for MLX-Gen.
+- **Generated media examples**: updated Core docs and OpenAPI examples to use task-specific MLX-Gen A14B text-to-video and image-to-video model ids.
+
+### Fixed
+- **PDF capability truth**: the default `pypdf` processor no longer advertises image extraction support, and page-level text extraction errors are reported as warnings instead of aborting the whole document.
+- **Vision upscaler discovery**: local vision catalogs now surface MLX-Gen models that only support `image_upscale`, including canonical `AbstractFramework/seedvr2-{3b,7b}-{8bit,4bit}` packages.
+- **Generated image callback forwarding**: server-local generated image/edit dispatch now forwards top-level progress callbacks and backend-specific parameters through the same AbstractVision `extra` path used for video generation.
+- **Reference media routing**: unified Python image-edit generation forwards `media` items with `reference`, `style`, or `context` roles as AbstractVision `reference_images`.
+
 ## [2.13.32] - 2026-06-03
 
 ### Added

README.md

@@ -52,7 +52,7 @@ Generative vision uses `abstractvision` when installed. In server mode, omit
 `model` only when the server has a configured default, or use explicit
 provider/model ids such as `diffusers/default`, `diffusers/<huggingface-repo>`,
 `mlx-gen/AbstractFramework/qwen-image-2512-4bit`,
-`mlx-gen/Wan-AI/Wan2.2-TI2V-5B-Diffusers`, `sdcpp/default`, or
+`mlx-gen/AbstractFramework/wan2.2-t2v-a14b-diffusers-8bit`, `sdcpp/default`, or
 `openai-compatible/<model>`. Quantized MLX-Gen models are selected by their
 published repo id; Core does not add a separate quant override.
 
@@ -339,11 +339,40 @@ Optional capability plugins can also generate media through the normal
 image = llm.generate("A red ceramic mug on a white table.", output="image")
 png_bytes = image.outputs["image"][0].data
 
-# Image edit: image media + image output infers image-to-image.
-edited = llm.generate("Make the mug blue.", media="mug.png", output="image")
+# Image edit: source plus optional reference/style media infers image-to-image.
+edited = llm.generate(
+    "Make the mug blue using the second image as a style reference.",
+    media=[
+        {"type": "image", "path": "mug.png", "role": "source"},
+        {"type": "image", "path": "style.png", "role": "style"},
+    ],
+    output="image",
+)
 
 def progress(event):
-    print("video progress", event)
+    print("media progress", event)
+
+# Image upscale via the AbstractVision plugin. Canonical q8 packages do not
+# need runtime quantize; pass a local prepared folder as model when needed.
+upscaled_direct = llm.vision.upscale_image(
+    "mug.png",
+    provider="mlx-gen",
+    model="AbstractFramework/seedvr2-3b-8bit",
+    scale="2x",
+    on_progress=progress,
+)
+
+upscaled = llm.generate(
+    media={"type": "image", "path": "mug.png", "role": "source"},
+    on_progress=progress,
+    output={
+        "task": "image_upscale",
+        "provider": "mlx-gen",
+        "model": "AbstractFramework/seedvr2-3b-8bit",
+        "scale": "2x",
+    },
+)
+upscaled_png = upscaled.outputs["image"][0].data
 
 # Text-to-video via abstractvision. The callback is forwarded to the plugin.
 video = llm.generate(
@@ -353,9 +382,15 @@ video = llm.generate(
         "modality": "video",
         "task": "text_to_video",
         "provider": "mlx-gen",
-        "model": "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
-        "num_frames": 121,
+        "model": "AbstractFramework/wan2.2-t2v-a14b-diffusers-8bit",
+        "width": 432,
+        "height": 240,
+        "num_frames": 41,
         "fps": 24,
+        "steps": 20,
+        "guidance_scale": 4.0,
+        "guidance_2": 3.0,
+        "extra": {"max_sequence_length": 256},
     },
 )
 mp4_bytes = video.outputs["video"][0].data
@@ -367,9 +402,15 @@ i2v = llm.generate(
     output={
         "task": "image_to_video",
         "provider": "mlx-gen",
-        "model": "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
-        "num_frames": 121,
+        "model": "AbstractFramework/wan2.2-i2v-a14b-diffusers-8bit",
+        "width": 432,
+        "height": 240,
+        "num_frames": 41,
         "fps": 24,
+        "steps": 20,
+        "guidance_scale": 3.5,
+        "guidance_2": 3.5,
+        "extra": {"max_sequence_length": 256},
     },
 )
 
@@ -394,7 +435,7 @@ Text-only `generate(...)` is unchanged. For advanced/provider-specific work,
 the direct `llm.vision.*`, `llm.voice.*`, `llm.audio.*`, and `llm.music.*` facades remain
 available. Configure `abstractvision` and `abstractvoice` backends first for
 real generation; configure `abstractmusic` for music generation. With
-`abstractmusic>=0.1.12`, the default music backend is the lightweight remote
+`abstractmusic>=0.1.13`, the default music backend is the lightweight remote
 ACE Music path; set `ACEMUSIC_API_KEY` before use. Local music engines remain
 optional plugin extras.
 
@@ -416,8 +457,8 @@ The HTTP server exposes equivalent discovery at
 Generated media HTTP routes include `/v1/images/generations`,
 `/v1/images/edits`, `/v1/videos/generations`, `/v1/videos/edits`, and
 async polling routes under `/v1/vision/jobs/images/*` and
-`/v1/vision/jobs/videos/*`; video jobs include the latest backend progress event
-when the selected backend reports it.
+`/v1/vision/jobs/videos/*`; image and video jobs include the latest backend
+progress event when the selected backend reports it.
 `/v1/models` remains focused on LLM and embedding provider models.
 Use `capability_route` to filter those models by precise route-keyed support:
 `/v1/models?capability_route=input.image,output.text`,

abstractcore/capabilities/registry.py

@@ -1098,6 +1098,20 @@ def backend_id(self) -> Optional[str]:
     def t2i(self, prompt: str, **kwargs: Any) -> Any:
         return self._registry.get_vision().t2i(prompt, **kwargs)
 
+    def upscale_image(self, image: Any, **kwargs: Any) -> Any:
+        backend = self._registry.get_vision()
+        method = getattr(backend, "upscale_image", None)
+        if not callable(method):
+            method = getattr(backend, "image_upscale", None)
+        if not callable(method):
+            raise CapabilityUnavailableError(
+                capability="vision",
+                reason="The selected vision capability backend does not expose image_upscale.",
+                install_hint=self._registry._default_install_hint("vision"),
+                details={"backend_id": getattr(backend, "backend_id", None)},
+            )
+        return method(image, **kwargs)
+
     def load_resident_model(self, request: Mapping[str, Any]) -> Dict[str, Any]:
         return _call_residency_mapping_method(
             self._registry.get_vision(),

abstractcore/capabilities/types.py

@@ -366,6 +366,17 @@ def i2i(
         **kwargs: Any,
     ) -> BytesOrArtifactRef: ...
 
+    def upscale_image(
+        self,
+        image: Union[bytes, ArtifactRef, str],
+        *,
+        artifact_store: Optional[ArtifactStoreLike] = None,
+        run_id: Optional[str] = None,
+        tags: Optional[Dict[str, str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> BytesOrArtifactRef: ...
+
     def t2v(
         self,
         prompt: str,

abstractcore/capabilities/vision_catalog.py

@@ -434,7 +434,13 @@ def get_local_vision_cache_catalog() -> Dict[str, Any]:
     for model_id in model_ids:
         spec = registry.get(model_id)
         supported_tasks = sorted(spec.tasks.keys())
-        if not {"text_to_image", "image_to_image", "text_to_video", "image_to_video"}.intersection(spec.tasks):
+        if not {
+            "text_to_image",
+            "image_to_image",
+            "image_upscale",
+            "text_to_video",
+            "image_to_video",
+        }.intersection(spec.tasks):
             continue
 
         for download in list(getattr(spec, "downloads", []) or []):

abstractcore/core/output_specs.py

@@ -11,6 +11,9 @@
     "transcript",
     "transcription",
     "image",
+    "upscale",
+    "image_upscale",
+    "upscale_image",
     "video",
     "t2v",
     "i2v",
@@ -40,6 +43,9 @@
     "image",
     "image_generation",
     "image_edit",
+    "upscale",
+    "image_upscale",
+    "upscale_image",
     "t2i",
     "i2i",
     "image_to_image",
@@ -78,6 +84,9 @@
     "i2i": ("image", "image_edit"),
     "image_to_image": ("image", "image_edit"),
     "image_edit": ("image", "image_edit"),
+    "upscale": ("image", "image_upscale"),
+    "image_upscale": ("image", "image_upscale"),
+    "upscale_image": ("image", "image_upscale"),
     "video": ("video", "video_generation"),
     "video_generation": ("video", "video_generation"),
     "t2v": ("video", "text_to_video"),
@@ -107,6 +116,8 @@
     "t2i": "image_generation",
     "i2i": "image_edit",
     "image_to_image": "image_edit",
+    "upscale": "image_upscale",
+    "upscale_image": "image_upscale",
     "t2v": "text_to_video",
     "i2v": "image_to_video",
     "song": "music_generation",
@@ -120,6 +131,7 @@
     "transcription": "text",
     "image_generation": "image",
     "image_edit": "image",
+    "image_upscale": "image",
     "video_generation": "video",
     "text_to_video": "video",
     "image_to_video": "video",

abstractcore/media/README.md

@@ -13,7 +13,7 @@ The media module provides unified, provider-agnostic multimodal processing capab
 | File Type | Processor | Best For | Requirements |
 |-----------|-----------|----------|--------------|
 | Images (jpg, png) | ImageProcessor | Vision models, analysis | PIL/Pillow |
-| PDF (text-heavy) | PDFProcessor | Text extraction | PyMuPDF4LLM |
+| PDF (text-heavy) | PDFProcessor | Text/metadata extraction | pypdf |
 | PDF (math/tables) | DirectPDFProcessor | Visual fidelity | pdf2image |
 | Office docs | OfficeProcessor | DOCX, XLSX, PPTX | unstructured |
 | Text/CSV/JSON | TextProcessor | Data files | Built-in |
@@ -122,7 +122,7 @@ media/
 │
 ├── processors/                  # Media type processors
 │   ├── image_processor.py       # Image processing with PIL (resize, optimize)
-│   ├── pdf_processor.py         # PDF extraction with PyMuPDF4LLM (markdown)
+│   ├── pdf_processor.py         # PDF extraction with pypdf by default
 │   ├── direct_pdf_processor.py  # Direct PDF→image conversion (Glyph)
 │   ├── glyph_pdf_processor.py   # Glyph-optimized PDF extraction (math/tables)
 │   ├── text_processor.py        # Text/CSV/JSON/Markdown processing
@@ -226,7 +226,7 @@ caps = get_media_capabilities("gpt-4o", provider="openai")
 
 **Features**:
 - Lazy processor initialization
-- Dependency checking (PIL, PyMuPDF4LLM, unstructured)
+- Dependency checking (PIL, pypdf, unstructured)
 - Glyph compression integration
 - Fallback processing
 
@@ -247,7 +247,7 @@ if result.success:
 **Processor Selection Logic**:
 ```python
 .jpg/.png → ImageProcessor (if PIL available)
-.pdf → PDFProcessor (if PyMuPDF4LLM) else TextProcessor
+.pdf → PDFProcessor (pypdf by default; PyMuPDF4LLM requires explicit opt-in)
 .docx/.xlsx/.pptx → OfficeProcessor (if unstructured) else TextProcessor
 .txt/.md/.csv → TextProcessor (always available)
 ```
@@ -325,7 +325,7 @@ result = processor.process_file("photo.jpg", model_name="gpt-4o")
 
 #### 7. `pdf_processor.py` - PDF Extraction
 
-**Dependencies**: PyMuPDF4LLM, PyMuPDF
+**Dependencies**: pypdf by default. Optional PyMuPDF4LLM / PyMuPDF support requires `abstractcore[pdf-pymupdf-commercial]` after license review.
 
 **Features**:
 - LLM-optimized markdown output
@@ -392,7 +392,7 @@ result = processor.process_file("research.pdf")
 
 #### 9. `glyph_pdf_processor.py` - Glyph-Optimized PDF Extraction
 
-**Dependencies**: PyMuPDF
+**Dependencies**: PyMuPDF from the explicit `abstractcore[pdf-pymupdf-commercial]` opt-in extra.
 
 **Purpose**: Extracts PDF content while preserving compact mathematical notation and table layouts for optimal Glyph visual compression.
 
@@ -1182,7 +1182,7 @@ result = handler.process_file("report.docx")
 
 # ✓ Good: Install media extras
 # $ pip install "abstractcore[media]"
-# Includes PIL, PyMuPDF4LLM, unstructured
+# Includes PIL, pypdf, unstructured
 ```
 
 ### 6. PDF Processing Choice
@@ -1397,7 +1397,7 @@ print(result.media_content.content)
 **Module Statistics**:
 - **Total Files**: 15 (5 root + 6 processors + 3 handlers + 1 util)
 - **Total Lines**: ~7,500
-- **Dependencies**: PIL, PyMuPDF4LLM, PyMuPDF, pdf2image, unstructured, pandas (optional)
+- **Dependencies**: PIL, pypdf, pdf2image, unstructured, pandas (optional). PyMuPDF-family tooling is an explicit commercial-license opt-in.
 - **Supported Formats**: Images (8), Documents (3), Text (8), Office (3)
 - **Providers**: OpenAI, Anthropic, Ollama, MLX, LMStudio, HuggingFace
 

abstractcore/media/__init__.py

@@ -13,7 +13,7 @@
 from __future__ import annotations
 
 # NOTE: Keep this package import-safe for minimal installs.
-# Many submodules have optional dependencies (Pillow, PyMuPDF4LLM, unstructured, ...).
+# Many submodules have optional dependencies (Pillow, pypdf, unstructured, ...).
 # Import them lazily so `from abstractcore.media.capabilities import ...` works without extras.
 
 from importlib import import_module

abstractcore/media/auto_handler.py

@@ -86,9 +86,9 @@ def _check_processor_availability(self) -> Dict[str, bool]:
         # TextProcessor (always available - uses built-in libraries)
         availability['text'] = True
 
-        # PDFProcessor (requires PyMuPDF4LLM)
+        # PDFProcessor (requires pypdf by default; PyMuPDF is explicit opt-in)
         try:
-            import pymupdf4llm
+            import pypdf
             availability['pdf'] = True
         except ImportError:
             availability['pdf'] = False
@@ -182,9 +182,10 @@ def _select_processor(self, file_path: Path, media_type: MediaType) -> Optional[
                 if self._available_processors.get('pdf', False):
                     return self._get_pdf_processor()
                 else:
-                    self.logger.warning("PDF processing requested but PyMuPDF4LLM not available")
-                    # Fall back to text processor for basic extraction
-                    return self._get_text_processor()
+                    self.logger.warning("PDF processing requested but pypdf not available")
+                    # Let PDFProcessor raise the actionable dependency error instead of
+                    # pretending a binary PDF can be handled as plain text.
+                    return self._get_pdf_processor()
 
             # Office documents
             elif file_extension in {'.docx', '.xlsx', '.pptx'}: