AbstractRuntime 0.4.25__tar.gz → 0.4.28__tar.gz

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/ACKNOWLEDGMENTS.md

@@ -10,12 +10,10 @@ The canonical dependency list lives in `pyproject.toml`.
 - **abstractsemantics** (`>=0.0.3`) — structured schema registry support (declared in `pyproject.toml`, used in `src/abstractruntime/integrations/abstractmemory/effect_handlers.py` and VisualFlow execution wiring).
 - **AbstractMemory** (`>=0.2.6`) — TripleStore models and store contract used by Runtime's `MEMORY_KG_*` effects. Durable/vector backend dependencies such as LanceDB remain selected by hosts.
 
-## Optional integrations (extras)
-
-Installed only when you opt in to extras:
-- **abstractcore** (`>=2.13.12`) — LLM + tools integration used by `abstractruntime[abstractcore]` (declared in `pyproject.toml`, implementation under `src/abstractruntime/integrations/abstractcore/*`, docs: `docs/integrations/abstractcore.md`).
+## Runtime integrations
+- **abstractcore** (`>=2.13.31`) — LLM, tools, media, and capability integration used by the base `abstractruntime` install (declared in `pyproject.toml`, implementation under `src/abstractruntime/integrations/abstractcore/*`, docs: `docs/integrations/abstractcore.md`).
   - The AbstractCore integration uses **httpx** for remote mode (`src/abstractruntime/integrations/abstractcore/llm_client.py`) and **pydantic** for structured validation (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). These are provided by AbstractCore’s dependency set.
-- **abstractcore[tools]** (`>=2.13.12`) — toolchain extra used by `abstractruntime[mcp-worker]` (declared in `pyproject.toml`) and intended to include HTML parsing dependencies (see comments in `pyproject.toml`).
+- **abstractcore[tools]** (`>=2.13.31`) — toolchain extra used by the base Runtime and `abstractruntime-mcp-worker` entry point (declared in `pyproject.toml`) and intended to include HTML parsing dependencies (see comments in `pyproject.toml`).
 - **RestrictedPython** (optional) — used for sandboxed execution of VisualFlow “Code” nodes when available (`src/abstractruntime/visualflow_compiler/visual/code_executor.py`).
 
 ## Build & test tooling

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.28] - 2026-06-06
+
+### Added
+- VisualFlow `read_pdf` and `write_pdf` document nodes. `read_pdf` extracts PDF text/metadata with `pypdf`; `write_pdf` renders text or Markdown-style content to real PDF bytes with `reportlab` while keeping run state JSON-safe.
+- Runtime discovery now exposes installed compatible vision adapters through `list_vision_adapters(...)`.
+- Runtime's local/remote image and video media helpers now preserve task-specific batch generation controls (`count` / `n`, `seeds`) and ordered `lora_adapters`, and VisualFlow media nodes now lower those fields for image generation, image edit, text-to-video, and image-to-video.
+
+### Changed
+- Runtime's base dependency path no longer selects AbstractCore's media extra or direct PyMuPDF/PyMuPDF4LLM/PyMuPDF-layout packages for VisualFlow PDF support.
+- Raised the AbstractCore dependency floor to `abstractcore>=2.13.37`, matching the released Core/Vision adapter, batch-generation, and media-parameter contract used by Runtime's base and hardware profiles.
+- Forwarded newer Core/Vision controls such as `guidance_2`, `flow_shift`, and image-upscaler parameters through generated-media execution.
+- The per-turn `<runtime_metadata>` prompt envelope is now temporal-only by default (`local_datetime` plus a country-free `display`). Full grounding remains in result metadata (`runtime_grounding`); operators can opt fields back into the prompt with `ABSTRACTRUNTIME_GROUNDING_PROMPT_FIELDS` (comma-separated subset of `local_datetime,timezone,country,user,display`).
+- When the runtime injects a `<runtime_metadata>` envelope into the user turn, it now also appends a stable "RUNTIME GROUNDING" contract to the system prompt explaining that the envelope is machine context, not a user language/locale preference.
+
+### Fixed
+- Markdown-to-PDF rendering now handles ATX heading levels 1 through 6, preventing deeper headings such as `####` from appearing as literal paragraph text in generated PDFs.
+- VisualFlow LLM Call and Agent structured outputs now expose the parsed object on the `data` output while preserving the existing textual `response` output.
+- VisualFlow LLM Call nodes now preserve inline `resp_schema` / `response_schema` constraints when provider and model are left on Auto, so Gateway/Core default routing still receives a structured-output `response_model`.
+- VisualFlow `answer_user` lowering now always emits a string `message` payload, preventing connected-but-null message inputs from creating invalid `ANSWER_USER` effects.
+- Structured-output field descriptions from JSON Schema now survive Runtime's Pydantic response-model conversion, so providers receive the same guidance authored in Flow.
+- Local subprocess media execution now supports task-compatible image edit and image upscaling inputs under the same durable image/video contract as in-process Runtime media calls.
+- Runtime now ships its own workspace-path and file-filter helper modules instead of importing unreleased AbstractCore internals, so published installs and release CI use the same supported dependency surface.
+
+## [0.4.27] - 2026-06-03
+
+### Changed
+- Raised the AbstractCore dependency floor to `abstractcore>=2.13.32` so Runtime hosts inherit provider endpoint profiles, route-specific multimodal defaults, and updated audio-understanding model metadata.
+- Updated AbstractCore discovery integration to expose Gateway/Core capability defaults, provider endpoint profiles, and route-specific media catalogs to thin clients.
+
+### Fixed
+- LLM and generated-media execution now resolves Gateway/Core default provider and model selections when VisualFlow nodes leave provider/model on Auto.
+- Media artifact resolution and VisualFlow generated-media calls now preserve uploaded artifacts and progress callbacks across Runtime/AbstractCore boundaries.
+
+## [0.4.26] - 2026-05-31
+
+### Changed
+- Moved AbstractCore remote/tool/media capability integration and the MCP worker dependency set into the base `pip install abstractruntime` profile. Runtime now exposes only the base, `abstractruntime[apple]`, and `abstractruntime[gpu]` user install profiles for functionality vs. local-inferencer selection; the `abstractcore`, `multimodal`, `mcp-worker`, `all-apple`, and `all-gpu` extras are no longer part of the supported install surface.
+- Raised the AbstractCore dependency floor to `abstractcore>=2.13.31` so Runtime installs inherit the latest remote-light media and Wan A14B vision contracts.
+
+### Fixed
+- Local text-to-video and image-to-video media-only calls now run in an isolated subprocess, preserving progress callbacks while preventing native MLX/Metal video failures from killing the Gateway/Runtime parent process.
+
 ## [0.4.25] - 2026-05-29
 
 ### Added
@@ -570,7 +612,10 @@ AbstractRuntime is the durable execution substrate designed to pair with Abstrac
 
 Initial development version with basic proof-of-concept features.
 
-[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.25...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.28...HEAD
+[0.4.28]: https://github.com/lpalbou/abstractruntime/compare/v0.4.27...v0.4.28
+[0.4.27]: https://github.com/lpalbou/abstractruntime/compare/v0.4.26...v0.4.27
+[0.4.26]: https://github.com/lpalbou/abstractruntime/compare/v0.4.25...v0.4.26
 [0.4.25]: https://github.com/lpalbou/abstractruntime/compare/v0.4.24...v0.4.25
 [0.4.24]: https://github.com/lpalbou/abstractruntime/compare/v0.4.23...v0.4.24
 [0.4.23]: https://github.com/lpalbou/abstractruntime/compare/v0.4.22...v0.4.23

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/CONTRIBUTING.md

@@ -16,8 +16,8 @@ python -m venv .venv
 source .venv/bin/activate
 python -m pip install -U pip
 
-# Full dev install (kernel + optional integrations used by tests/examples)
-python -m pip install -e ".[abstractcore,mcp-worker]"
+# Full dev install (runtime + docs/test tooling)
+python -m pip install -e ".[test,docs]"
 
 python -m pytest -q
 ```
@@ -30,7 +30,7 @@ If you cloned **only** this repo (without the AbstractFramework workspace), make
 - Core kernel (durable semantics): `src/abstractruntime/core/`
 - Durability backends: `src/abstractruntime/storage/`
 - Driver loop (in-process): `src/abstractruntime/scheduler/`
-- Optional integrations (extras): `src/abstractruntime/integrations/`
+- Runtime integrations: `src/abstractruntime/integrations/`
 - Tests: `tests/`
 
 Docs entrypoints:

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.25
+Version: 0.4.28
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime
@@ -20,57 +20,28 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
+Requires-Dist: abstractcore[audio,music,remote,tools,vision,voice]>=2.13.37
 Requires-Dist: abstractmemory>=0.2.6
 Requires-Dist: abstractsemantics>=0.0.3
-Provides-Extra: abstractcore
-Requires-Dist: abstractcore>=2.13.30; extra == 'abstractcore'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'abstractcore'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'abstractcore'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'abstractcore'
-Provides-Extra: all-apple
-Requires-Dist: abstractcore[all-apple]>=2.13.30; extra == 'all-apple'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'all-apple'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'all-apple'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all-apple'
-Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'all-apple'
-Provides-Extra: all-gpu
-Requires-Dist: abstractcore[all-gpu]>=2.13.30; extra == 'all-gpu'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'all-gpu'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'all-gpu'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all-gpu'
-Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'all-gpu'
+Requires-Dist: anyio<5.0.0,>=4.12.1
+Requires-Dist: httpx<1.0.0,>=0.28.1
+Requires-Dist: openai<2.0.0,>=1.109.1
+Requires-Dist: pandas<3.0.0,>=1.0.0
+Requires-Dist: pillow<13.0.0,>=10.0.0
+Requires-Dist: pypdf<7.0.0,>=6.0.0
+Requires-Dist: python-pptx<2.0.0,>=1.0.2
+Requires-Dist: reportlab<5.0.0,>=4.0.0
+Requires-Dist: unstructured[docx,odt,pptx,rtf,xlsx]<0.19.0,>=0.18.32
 Provides-Extra: apple
-Requires-Dist: abstractcore[apple]>=2.13.30; extra == 'apple'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'apple'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'apple'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.37; extra == 'apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'apple'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[gpu]>=2.13.30; extra == 'gpu'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'gpu'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'gpu'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.37; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'gpu'
-Provides-Extra: mcp-worker
-Requires-Dist: abstractcore[tools]>=2.13.30; extra == 'mcp-worker'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'mcp-worker'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'mcp-worker'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'mcp-worker'
-Provides-Extra: multimodal
-Requires-Dist: abstractcore[audio,music,remote,vision,voice]>=2.13.30; extra == 'multimodal'
-Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'multimodal'
-Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'multimodal'
-Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'multimodal'
-Requires-Dist: pandas<3.0.0,>=1.0.0; extra == 'multimodal'
-Requires-Dist: pillow<13.0.0,>=10.0.0; extra == 'multimodal'
-Requires-Dist: pymupdf-layout<2.0.0,>=1.26.6; extra == 'multimodal'
-Requires-Dist: pymupdf4llm<1.0.0,>=0.0.20; extra == 'multimodal'
-Requires-Dist: python-pptx<2.0.0,>=1.0.2; extra == 'multimodal'
-Requires-Dist: unstructured[docx,odt,pptx,rtf,xlsx]<0.19.0,>=0.18.32; extra == 'multimodal'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
@@ -81,7 +52,7 @@ Description-Content-Type: text/markdown
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.4.25 • **Python:** 3.10+
+**Version:** 0.4.28 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -103,31 +74,34 @@ flowchart LR
 
 ## Install
 
-Core runtime:
+Remote-light runtime:
 
 ```bash
 pip install abstractruntime
 ```
 
-AbstractCore integration (LLM + tools):
+The base install includes AbstractCore 2.13.37 or newer with remote provider,
+tool, vision, voice, audio, and music integration, plus the
+`abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
+default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and
+sentence-transformer embeddings are not selected unless you choose a hardware
+profile or another package-specific local extra.
 
-```bash
-pip install "abstractruntime[abstractcore]"
-```
-
-The `abstractcore` extra installs AbstractCore 2.13.30 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, task-aware model residency for text/image/video/TTS/STT, video generation endpoints, and the public local vision-cache catalog helper used by Runtime discovery remain aligned. Use `abstractruntime[multimodal]` when you need common media dependencies and capability plugins (installs `abstractcore[remote,vision,voice,audio,music]>=2.13.30`, including `abstractmusic>=0.1.12`).
+VisualFlow PDF document nodes use permissive dependencies in Runtime's base
+install: `Read PDF` extracts text and metadata with `pypdf`, and `Write PDF`
+renders text or Markdown-style report content to real PDF bytes with
+`reportlab`.
 
-Hardware profile cascades are available for native Python installs:
-`abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
-and `abstractruntime[all-gpu]` delegate to the matching AbstractCore profile
-without making the runtime kernel itself hardware-specific.
-
-MCP worker entrypoint (default toolsets over stdio):
+Native Python hardware profiles add local inferencer stacks:
 
 ```bash
-pip install "abstractruntime[mcp-worker]"
+pip install "abstractruntime[apple]"
+pip install "abstractruntime[gpu]"
 ```
 
+`abstractruntime[apple]` delegates to AbstractCore's native Apple aggregate;
+`abstractruntime[gpu]` delegates to AbstractCore's GPU aggregate.
+
 ## Quick start (pause + resume)
 
 ```python
@@ -169,9 +143,9 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.25)
+## What’s included (v0.4.26)
 
-Kernel (dependency-light):
+Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
 - durable execution: `Runtime.start/tick/resume` (`src/abstractruntime/core/runtime.py`)
 - durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
@@ -190,9 +164,20 @@ Drivers + distribution:
 - scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
 - VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
 - VisualFlow multi-entry execution lowering for fan-in routes and per-entry input overrides (`docs/workflow-bundles.md`)
+- VisualFlow LLM Call and Agent nodes propagate Core generation params such as
+  `thinking` through Runtime effects. Provider Models nodes can apply Core
+  `capability_route` filters so run-time model discovery matches Gateway/Flow
+  authoring.
+- VisualFlow image/video nodes and Runtime media helpers preserve task-specific
+  Core media controls, including `count`/`n`, `seeds`, ordered
+  `lora_adapters`, and video `flow_shift`, while keeping provider/model/task
+  truth in AbstractCore and AbstractVision.
+- VisualFlow structured LLM/Agent results preserve `response` as text and expose
+  the schema-conformant object on `data`, so Break Object and Switch can consume
+  fields without reparsing the response string.
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
-Optional integrations:
+Runtime-owned integrations:
 - AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/video/voice/music outputs with progress events, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers and the standalone email comms facade remain host-local and nondurable.
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
@@ -256,7 +241,7 @@ sr = create_scheduled_runtime(
 python -m venv .venv
 source .venv/bin/activate
 python -m pip install -U pip
-python -m pip install -e ".[abstractcore,mcp-worker,test,docs]"
+python -m pip install -e ".[test,docs]"
 python -m pytest -q
 ```
 

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/README.md

@@ -4,7 +4,7 @@
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.4.25 • **Python:** 3.10+
+**Version:** 0.4.28 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -26,31 +26,34 @@ flowchart LR
 
 ## Install
 
-Core runtime:
+Remote-light runtime:
 
 ```bash
 pip install abstractruntime
 ```
 
-AbstractCore integration (LLM + tools):
+The base install includes AbstractCore 2.13.37 or newer with remote provider,
+tool, vision, voice, audio, and music integration, plus the
+`abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
+default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and
+sentence-transformer embeddings are not selected unless you choose a hardware
+profile or another package-specific local extra.
 
-```bash
-pip install "abstractruntime[abstractcore]"
-```
-
-The `abstractcore` extra installs AbstractCore 2.13.30 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, task-aware model residency for text/image/video/TTS/STT, video generation endpoints, and the public local vision-cache catalog helper used by Runtime discovery remain aligned. Use `abstractruntime[multimodal]` when you need common media dependencies and capability plugins (installs `abstractcore[remote,vision,voice,audio,music]>=2.13.30`, including `abstractmusic>=0.1.12`).
+VisualFlow PDF document nodes use permissive dependencies in Runtime's base
+install: `Read PDF` extracts text and metadata with `pypdf`, and `Write PDF`
+renders text or Markdown-style report content to real PDF bytes with
+`reportlab`.
 
-Hardware profile cascades are available for native Python installs:
-`abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
-and `abstractruntime[all-gpu]` delegate to the matching AbstractCore profile
-without making the runtime kernel itself hardware-specific.
-
-MCP worker entrypoint (default toolsets over stdio):
+Native Python hardware profiles add local inferencer stacks:
 
 ```bash
-pip install "abstractruntime[mcp-worker]"
+pip install "abstractruntime[apple]"
+pip install "abstractruntime[gpu]"
 ```
 
+`abstractruntime[apple]` delegates to AbstractCore's native Apple aggregate;
+`abstractruntime[gpu]` delegates to AbstractCore's GPU aggregate.
+
 ## Quick start (pause + resume)
 
 ```python
@@ -92,9 +95,9 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.25)
+## What’s included (v0.4.26)
 
-Kernel (dependency-light):
+Kernel (import-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
 - durable execution: `Runtime.start/tick/resume` (`src/abstractruntime/core/runtime.py`)
 - durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
@@ -113,9 +116,20 @@ Drivers + distribution:
 - scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
 - VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
 - VisualFlow multi-entry execution lowering for fan-in routes and per-entry input overrides (`docs/workflow-bundles.md`)
+- VisualFlow LLM Call and Agent nodes propagate Core generation params such as
+  `thinking` through Runtime effects. Provider Models nodes can apply Core
+  `capability_route` filters so run-time model discovery matches Gateway/Flow
+  authoring.
+- VisualFlow image/video nodes and Runtime media helpers preserve task-specific
+  Core media controls, including `count`/`n`, `seeds`, ordered
+  `lora_adapters`, and video `flow_shift`, while keeping provider/model/task
+  truth in AbstractCore and AbstractVision.
+- VisualFlow structured LLM/Agent results preserve `response` as text and expose
+  the schema-conformant object on `data`, so Break Object and Switch can consume
+  fields without reparsing the response string.
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
-Optional integrations:
+Runtime-owned integrations:
 - AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, local-only prompt-cache export/import admin, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/video/voice/music outputs with progress events, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
 - For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers and the standalone email comms facade remain host-local and nondurable.
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
@@ -179,7 +193,7 @@ sr = create_scheduled_runtime(
 python -m venv .venv
 source .venv/bin/activate
 python -m pip install -U pip
-python -m pip install -e ".[abstractcore,mcp-worker,test,docs]"
+python -m pip install -e ".[test,docs]"
 python -m pytest -q
 ```
 

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/docs/README.md

@@ -26,8 +26,10 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `faq.md` — common questions (recommended)
 - `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes
 - `manual_testing.md` — manual smoke tests and how to run the test suite
+- `artifacts.md` — Runtime artifact identity, descriptors, provenance, catalog search, and access stats
 - `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, cached sessions, durable bloc prompt-cache control, media inputs, generated media outputs, video progress events, and tool approval waits via AbstractCore
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
+- `api.md#workflowbundles-flow-and-visualflow-distribution` — VisualFlow compiler APIs, media nodes, and PDF document nodes (`read_pdf` / `write_pdf`)
 
 ## Features (reference)
 

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/docs/api.md

@@ -33,7 +33,7 @@ Scheduler convenience wrapper:
 from abstractruntime import create_scheduled_runtime
 ```
 
-Optional integration (requires `abstractruntime[abstractcore]`):
+AbstractCore integration (included in the base `abstractruntime` install):
 
 ```python
 from abstractruntime.integrations.abstractcore import (
@@ -117,11 +117,17 @@ These APIs are exported at the package root (see `src/abstractruntime/__init__.p
 ## Artifacts (store by reference)
 
 Implementation: `src/abstractruntime/storage/artifacts.py`.
+Deep dive: `artifacts.md`.
 
 Key types:
 - `ArtifactStore` (interface), `InMemoryArtifactStore`, `FileArtifactStore`
 - helpers: `artifact_ref(...)`, `resolve_artifact(...)`, `is_artifact_ref(...)`
 
+The store keeps payload bytes out of run state and persists structured metadata:
+- `ArtifactDescriptor` is the Runtime-owned descriptor used by Gateway and Observer. It separates `semantic_kind` such as `voice`, `music`, `sound`, or `image` from `render_kind` such as `audio`, `markdown`, `html`, or `json`, and can carry workflow/node/turn links, media facts, generation/provenance data, source refs, security, and action links.
+- `ArtifactAccessStats` records explicit metadata/content/preview/download/export actions when HTTP or UI layers call `record_access(...)`. Plain `load(...)` and `get_metadata(...)` remain side-effect free.
+- `search(...)`, `count(...)`, `facet_counts(...)`, and `stats(...)` provide metadata queries for host control planes. `FileArtifactStore` serves these from a repairable SQLite catalog when possible, including exact `total`, `total_bytes`, and requested facet counts without forcing Gateway/Observer to load every matching artifact.
+
 Artifacts are used by:
 - offloading wrappers (`src/abstractruntime/storage/offloading.py`)
 - evidence capture (`docs/evidence.md`, `src/abstractruntime/evidence/recorder.py`)
@@ -156,9 +162,23 @@ VisualFlow compiler helpers are available from `abstractruntime.visualflow_compi
 - `visual_to_flow(...)` lowers VisualFlow into the internal Flow IR.
 - `compile_visualflow(...)` and `compile_visualflow_tree(...)` compile VisualFlow JSON into executable `WorkflowSpec` objects.
 
-VisualFlow authoring note (media nodes):
-- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `generate_video`, `text_to_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, and `listen_voice`.
+VisualFlow authoring note (media and document nodes):
+- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `upscale_image`, `image_upscale`, `generate_video`, `text_to_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, and `listen_voice`.
 - Generated-media and transcription nodes lower to a durable `EffectType.LLM_CALL` with an `output` selector (for example `{"modality":"music","task":"music_generation"}`), while `listen_voice` lowers to `WAIT_EVENT`. Hosts should persist the authoring node type rather than pre-lowering to `llm_call`.
+- Runtime also recognizes file/document nodes. `read_file` and `write_file`
+  handle UTF-8 text/JSON workspace paths. In Gateway-hosted runs, those paths
+  follow the shared canonical contract: `rel/path` for the main workspace root
+  and `mount_alias/rel/path` for approved mounts. `read_pdf` extracts text and
+  metadata from PDF paths with `pypdf`; `write_pdf` renders text or
+  Markdown-style content to real PDF bytes with `reportlab`; `list_folder_files`
+  enumerates workspace-scoped folders with family/extension filters;
+  `import_workspace_file` snapshots a workspace file into a durable artifact;
+  `read_artifact` projects saved file content back out as text/JSON/bounded
+  binary metadata; and `export_artifact` writes a durable artifact back to a
+  workspace path. PDF bytes are written to the workspace path and only
+  JSON-safe metadata/path values are stored in run state. In local Runtime-only
+  runs with no workspace scope, relative file-node paths still fall back to the
+  process working directory.
 
 Public bundle APIs are exported from `src/abstractruntime/workflow_bundle/__init__.py` and re-exported in `src/abstractruntime/__init__.py`:
 - open: `open_workflow_bundle(...)`
@@ -176,11 +196,11 @@ Implementation: `src/abstractruntime/history_bundle.py`.
 
 This produces a portable record of a run’s state + ledger + artifacts suitable for debugging/review.
 
-## Optional integrations
+## Runtime-owned integrations
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.30 or newer).
+Requires: `pip install abstractruntime` (AbstractCore 2.13.37 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -193,11 +213,14 @@ Entry points:
 - public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`)
 - effect handler wiring: `build_effect_handlers(...)` (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`)
 - tool executors: `MappingToolExecutor`, `AbstractCoreToolExecutor`, `PassthroughToolExecutor`, `ApprovalToolExecutor`, `ToolApprovalPolicy` (`src/abstractruntime/integrations/abstractcore/tool_executor.py`)
-- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`)
+- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
 - host-facade client delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules`, `upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`, `get_model_residency_capabilities`, `list_model_residency`, `load_model_residency`, `unload_model_residency`)
 - host-local prompt-cache export/import admin also lives on the host facade and client delegation layer (`list_prompt_cache_exports`, `prompt_cache_export`, `prompt_cache_import`) and is intentionally local-only
 - host-facade email helpers delegate to Runtime's host-local comms facade/export layer (`list_email_accounts`, `list_emails`, `read_email`, `send_email`)
-- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
+- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `upscale_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
+- task-specific image/video helpers preserve batch and adapter controls such as
+  `count`/`n`, `seeds`, ordered `lora_adapters`, and video `flow_shift`; local
+  subprocess isolation stays within the same public contract.
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
@@ -206,14 +229,14 @@ Entry points:
 - `params`: provider/model routing, generation controls, prompt-cache keys or `prompt_cache_binding`, structured-output schema options, and tracing metadata
 
 Multimodal support:
-- install `abstractruntime[multimodal]` for common AbstractCore media, vision, voice, audio, and music dependencies
+- common remote-light AbstractCore media, vision, voice, audio, and music dependencies are part of the base Runtime install
 - local clients call AbstractCore's unified `generate(..., media=..., output=...)`
-- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, text-to-video, image-to-video, speech, music generation, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
+- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, image upscaling, text-to-video, image-to-video, speech, music generation, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
 - remote transcription requires one audio media item that resolves to a local file path or artifact-backed temporary file
 - generated image/video/voice/music/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
 - media-only normalized results expose `runtime_provider` / `runtime_model` separately from `media_provider` / `media_model`
-- optional local media residency failures complete with `status_hint="warning"` and `degraded=true`; unsupported local media warmup for `image_generation`, `video_generation`, `text_to_video`, `image_to_video`, `tts`, `stt`, and `music_generation` reports `requires_long_lived_server=true`, and generated image/video tasks also report `execution_mode="local_one_shot_subprocess"`
-- Gateway/hosts remain responsible for explicit Core server URLs, Core server auth headers, provider/model defaults, selected Core/capability install profiles, and translation of Gateway-owned env/config into explicit Runtime inputs; Runtime persists only JSON-safe routing metadata and artifact refs
+- optional local media residency failures complete with `status_hint="warning"` and `degraded=true`; unsupported local media warmup for `image_generation`, `image_upscale`, `video_generation`, `text_to_video`, `image_to_video`, `tts`, `stt`, and `music_generation` reports `requires_long_lived_server=true`, and generated image/video tasks also report `execution_mode="local_one_shot_subprocess"`
+- Gateway/hosts remain responsible for explicit Core server URLs, Core server auth headers, provider/model defaults, selected local-inference profiles, and translation of Gateway-owned env/config into explicit Runtime inputs; Runtime persists only JSON-safe routing metadata and artifact refs
 
 Prompt cache / cached sessions:
 - LLM clients expose cache control methods listed above for host-side preparation and inspection

{abstractruntime-0.4.25 → abstractruntime-0.4.28}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-23
-> Version: 0.4.24
+> Updated: 2026-06-13
+> Version: 0.4.28
 > Scope: this describes **what is implemented in this repository**.
 
 AbstractRuntime is a **durable workflow runtime**: it executes workflow graphs as a persisted state machine with explicit waits (user, time, events, jobs, subworkflows). A run can pause for hours/days and resume **without** keeping Python stacks/coroutines alive.
@@ -38,7 +38,7 @@ The boundary is intentionally narrow:
 - Provider sessions and prompt-cache objects are not runtime state. Runtime may carry stable cache keys, while AbstractCore clients/servers manage warm caches.
 - Hosts should use Runtime-owned AbstractCore facades for discovery snapshots, prompt-cache/model-residency control operations, and durable run-scoped media/comms child runs instead of reaching through private runtime attachments or importing Core internals directly.
 - Local execution can use richer AbstractCore capability plugins. Remote and hybrid execution map the common media cases to AbstractCore Server endpoints and OpenAI-compatible content arrays, while hybrid keeps tool execution local.
-- Gateway and other hosts compose Runtime with the desired Core/capability/memory profile. Runtime's base package includes the AbstractMemory contract but not backend extras such as LanceDB; hosts choose storage, embeddings, and readiness policy. Hardware profile extras such as `apple`, `gpu`, `all-apple`, and `all-gpu` cascade through AbstractCore when a host selects them.
+- Gateway and other hosts compose Runtime with the desired memory and local-inference profile. Runtime's base package includes the AbstractMemory contract, AbstractCore remote/tool capability integration, Runtime-owned permissive PDF read/write support, and the MCP worker entry point, but not backend extras such as LanceDB, Core media document stacks, or local inferencer stacks. Hosts choose storage, embeddings, readiness policy, and whether to add `abstractruntime[apple]` or `abstractruntime[gpu]`.
 - Remote and hybrid clients use explicit Core server URLs and auth headers supplied by the host. Runtime does not read Gateway auth environment variables for provider/model/auth decisions or treat Gateway bearer tokens as Core server/provider credentials.
 
 This keeps the runtime usable by `../abstractgateway` and application layers such as `../abstractflow`, `../abstractassistant`, `../abstractobserver`, and `../abstractcode` without embedding provider-specific model logic in the durable kernel.
@@ -213,6 +213,10 @@ The scheduler is an in-process driver loop that resumes due waits and can delive
 AbstractRuntime includes a compiler and a portable bundle format:
 - VisualFlow compiler: `src/abstractruntime/visualflow_compiler/*` (VisualFlow JSON -> `WorkflowSpec`)
 - Multi-entry VisualFlow authoring routes are lowered into internal `join_exec` and `path_mux` nodes when a target has multiple incoming `exec-in` edges plus per-route input overrides. This keeps authoring JSON clean while making runtime behavior explicit and restart-safe. See `workflow-bundles.md` for the concrete metadata shape.
+- VisualFlow document nodes include `read_pdf` and `write_pdf`. They use
+  workspace-scoped paths, keep PDF bytes out of checkpoints, and store only
+  JSON-safe extracted text, metadata, hashes, content types, and file paths in
+  node outputs.
 - WorkflowBundles (`.flow`): `src/abstractruntime/workflow_bundle/*` (manifest + flows + assets)
   - pack/unpack helpers: `pack_workflow_bundle(...)`, `open_workflow_bundle(...)`