Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

Pipelex kernel 1/3 — the `pipelex.kernel` package and the LLM vertical slice (#1081)

Louis Choquel77aae9e6ab5e
diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.toml
index b794f1345..23d11e989 100644
--- a/.drift/acks/hub-layering-convention.toml
+++ b/.drift/acks/hub-layering-convention.toml
@@ -1,10 +1,10 @@
contract = "hub-layering-convention"
-digest = "sha256:2b509c7efe7ebaa99dcf1fce041dcf141b94e516dd91cda75b13deba982538f9"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-07-30T05:25:03Z"
-rationale = "Trigger is a one-paragraph docstring accuracy fix on RuntimeHub.setup_config's config_dir parameter: it said 'project/global layering is bypassed and only this directory is read', which contradicted config_loader (the package defaults layer always applies) and the two make() docstrings that already said 'package defaults + this directory'. Reviewed docs/contribute/hub-layering.md: it does not describe setup_config, config_dir, or config layering anywhere — grep for config_dir/setup_config/'only this directory' returns nothing — so the page carries no copy of the claim that was wrong and nothing is stale. Re-ran the prescribed mechanical check anyway (every name in the guard's RUNTIME_LAYER_PACKAGES appears under 'The rule'): all fourteen present, including pipelex.runtime_boot from the previous ack, so the enumeration that has been the rot seven rounds running is clean this time. No doc change needed."
+digest = "sha256:3e809663f592cb1454c7f5b1d7c0d480b63a18c6eed7d710970e7866da27c205"
+reviewed_by = "Claude (Opus 5)"
+reviewed_at = "2026-08-09T15:30:30Z"
+rationale = "Trigger is the rename of the kernel façade class to PipelexKernel, which changed exactly one word in runtime_hub.py: the class named in resolve_run_mode_for_boot's docstring. Reviewed docs/contribute/hub-layering.md and it is already current — the rename commit updated the page atomically, so the paragraph under 'Which hub does a new symbol belong to?' already reads PipelexKernel.make; only the ack digest was stale. Ran both prescribed mechanical checks rather than re-reading the tables, per the standing note in the dogfood log: all 15 packages in RUNTIME_LAYER_PACKAGES are named under Enforcement (the enumeration that rotted seven rounds running is clean — it now includes pipelex.kernel and pipelex.runtime_boot), and all 34 + 32 public module-level hub symbols appear in the partition tables. Also verified the page's concrete references still resolve: resolve_run_mode_for_boot sits beside is_dry_run_forced under 'run mode', and tests/unit/pipelex/kernel/test_kernel_boot_contract.py exists at the path the Enforcement section cites. No doc change needed. The review also turned up six references to the class's old name outside this contract's targets, in wip/parity/README.md and wip/parity/parity-gaps-plan.md, which arrived via the dev merge; those were renamed in the same change, so the old name is now gone from the working tree entirely."
[trigger_files]
-"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:a602008dabb5b1ce81496513c37253ef6f5c0765"
+"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:151bee2b65ca3717b09f754d2e30aad830894f43"
"pipelex/interpreter_hub.py" = "blob:b7ac885d348d32f1aa4b1e660da5b03533fb305b"
-"pipelex/runtime_hub.py" = "blob:81fb34f097b440293b8b68f9eefb7289778c911b"
+"pipelex/runtime_hub.py" = "blob:b5eab6810174435eb1e40aa1b1cd29a103af58be"
diff --git a/.test_durations b/.test_durations
index f028b0326..51d60f2e6 100644
--- a/.test_durations
+++ b/.test_durations
@@ -5478,6 +5478,31 @@
"tests/unit/pipelex/graph/test_trace_context_emit_flags.py::TestTraceContextEmitFlags::test_copy_for_child_preserves_costs_only_flags": 0.0021417919924715534,
"tests/unit/pipelex/graph/test_trace_context_emit_flags.py::TestTraceContextEmitFlags::test_copy_for_child_preserves_graph_only_flags": 0.08134074999543373,
"tests/unit/pipelex/graph/test_trace_context_emit_flags.py::TestTraceContextEmitFlags::test_defaults_emit_both_streams": 0.6790959579957416,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReference::test_create_direct_list_reference": 0.0003171250136801973,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReference::test_create_direct_reference": 1.1507495830301195,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReference::test_nested_path_variable": 0.00035941600799560547,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReference::test_str_representation_direct": 0.0004061250074300915,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReference::test_str_representation_direct_list": 0.00048820899974089116,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReferenceKind::test_all_kinds_have_string_values[direct-direct]": 0.0017300839972449467,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReferenceKind::test_all_kinds_have_string_values[direct_list-direct_list]": 0.1325309579842724,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReferenceKind::test_direct_list_value": 0.00024762599787209183,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReferenceKind::test_direct_value": 0.0009079590090550482,
+ "tests/unit/pipelex/kernel/test_document_reference.py::TestDocumentReferenceKind::test_kind_is_strenum": 0.0008493339992128313,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_create_direct_list_reference": 0.0006540410104207695,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_create_direct_reference": 0.9803414169873577,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_create_nested_reference_with_paths": 0.0007082079973770306,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_create_nested_reference_without_paths": 0.0005360000068321824,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_nested_path_variable": 0.0006186669925227761,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_str_representation_direct": 0.0005804170068586245,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_str_representation_direct_list": 0.00046420701255556196,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReference::test_str_representation_nested": 0.0005520839913515374,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_all_kinds_have_string_values[direct-direct]": 0.0003241669910494238,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_all_kinds_have_string_values[direct_list-direct_list]": 0.0012349169846856967,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_all_kinds_have_string_values[nested-nested]": 0.1500053339987062,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_direct_list_value": 0.0005667910008924082,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_direct_value": 0.0004937919875374064,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_kind_is_strenum": 0.0002890840114559978,
+ "tests/unit/pipelex/kernel/test_image_reference.py::TestImageReferenceKind::test_nested_value": 0.0005025419959565625,
"tests/unit/pipelex/kit/test_index_loader.py::TestKitIndexLoader::test_index_has_required_structure": 0.0013431680126814172,
"tests/unit/pipelex/kit/test_index_loader.py::TestKitIndexLoader::test_index_has_valid_default_set": 0.11361804202897474,
"tests/unit/pipelex/kit/test_index_loader.py::TestKitIndexLoader::test_index_sets_contain_expected_files": 0.0012913760001538321,
@@ -6225,31 +6250,6 @@
"tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py::TestResolveDefaultSize::test_resolve_default_size[no-default-stays-none]": 0.15100087500468362,
"tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py::TestResolveDefaultSize::test_resolve_default_size[tier-default-applies-without-ratio]": 0.0010004179930547252,
"tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_size_default.py::TestResolveDefaultSize::test_resolve_default_size[tier-default-composes-with-explicit-ratio]": 0.0004727919877041131,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReference::test_create_direct_list_reference": 0.0003171250136801973,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReference::test_create_direct_reference": 1.1507495830301195,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReference::test_nested_path_variable": 0.00035941600799560547,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReference::test_str_representation_direct": 0.0004061250074300915,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReference::test_str_representation_direct_list": 0.00048820899974089116,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReferenceKind::test_all_kinds_have_string_values[direct-direct]": 0.0017300839972449467,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReferenceKind::test_all_kinds_have_string_values[direct_list-direct_list]": 0.1325309579842724,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReferenceKind::test_direct_list_value": 0.00024762599787209183,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReferenceKind::test_direct_value": 0.0009079590090550482,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py::TestDocumentReferenceKind::test_kind_is_strenum": 0.0008493339992128313,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_create_direct_list_reference": 0.0006540410104207695,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_create_direct_reference": 0.9803414169873577,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_create_nested_reference_with_paths": 0.0007082079973770306,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_create_nested_reference_without_paths": 0.0005360000068321824,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_nested_path_variable": 0.0006186669925227761,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_str_representation_direct": 0.0005804170068586245,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_str_representation_direct_list": 0.00046420701255556196,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReference::test_str_representation_nested": 0.0005520839913515374,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_all_kinds_have_string_values[direct-direct]": 0.0003241669910494238,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_all_kinds_have_string_values[direct_list-direct_list]": 0.0012349169846856967,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_all_kinds_have_string_values[nested-nested]": 0.1500053339987062,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_direct_list_value": 0.0005667910008924082,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_direct_value": 0.0004937919875374064,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_kind_is_strenum": 0.0002890840114559978,
- "tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py::TestImageReferenceKind::test_nested_value": 0.0005025419959565625,
"tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py::TestLLMPromptBlueprintRequiredVariables::test_required_variables_deduplicates_same_root": 0.001239625024027191,
"tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py::TestLLMPromptBlueprintRequiredVariables::test_required_variables_excludes_internal_variables": 0.0012199170014355332,
"tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py::TestLLMPromptBlueprintRequiredVariables::test_required_variables_excludes_place_holder": 0.13840670901117846,
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d781f2a1b..849290876 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,16 @@
## [Unreleased]
+### Added
+
+- **Pipelex kernel (`pipelex.kernel`)**: A new public subpackage holding operator-execution semantics as importable functions, so what a `PipeLLM` step *does* — deck resolution, templating-style derivation, prompt assembly, generation, memory write-back — is no longer reachable only through a fully booted interpreter with a loaded library. Every kernel call is servable on a runtime-only boot with zero `.mthds` loaded, which is pinned by a permanent test. This first release covers the LLM operator; the remaining operators follow.
+
+### Changed
+
+- **Prompt reference types moved (Breaking)**: `ImageReference` and `DocumentReference` (with their `*Kind` enums) moved from `pipelex.pipe_operators.shared.image_reference` / `pipelex.pipe_operators.llm.document_reference` to `pipelex.kernel.prompt_references`. They describe how a prompt resolves an image or document out of working memory, which is execution semantics rather than a language artifact.
+- **`LLMPromptBlueprintValueError` replaced (Breaking)**: The error raised when a prompt's image or document reference cannot be resolved is now `pipelex.kernel.exceptions.PromptContentError`, moved with the code that raises it. `LLMPromptBlueprint` keeps its fields, its validation and its `make_llm_prompt` signature.
+- **Keyless-boot forced-DRY rule has one home**: `pipelex.runtime_hub.resolve_run_mode_for_boot` now owns the coercion that a keyless boot (`needs_inference=False`) applies to a requested run mode. Both run-params factories call it — the pipe tier's `PipeRunParamsFactory.make_run_params`, whose behavior is unchanged, and the kernel tier's `PipelexKernel.make`, which previously minted a LIVE `CogtRunParams` on an offline boot. A programmatic kernel caller on a keyless boot now gets the same forced DRY and the same warning as a pipe run.
+
### Fixed
- **Cross-domain pipe refs in normalized crates (Breaking)**: A bare pipe ref calling a pipe declared in another domain was normalized by prefixing the *caller's* domain, naming a pipe the crate does not hold — while the live library resolves the same ref by searching every domain. The crate fingerprinted the wrong content and a crate round-trip broke the method at run time with `PipeNotFoundError`, with nothing raised on the way in. Normalization now resolves a bare pipe ref against the whole crate exactly as `PipeLibrary` does, and raises `CrateNormalizationError` when the ref is ambiguous or matches no pipe instead of emitting a dangling ref.
diff --git a/TODOS.md b/TODOS.md
deleted file mode 100644
index 5aeb8a6f1..000000000
--- a/TODOS.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# The follow-ups #1076 deferred, in the order they had to happen
-
-Branch `refactor/Follow-ups`, off `dev` at #1076. Three items, ruled to run 2 → 4 → 3 for a reason worth stating up front: item 4 *removes* an in-process conversion, so item 3's audit of the surviving conversions is only meaningful after it — and item 2 first, because both of the others needed a single home for the contract they were about to change. (The numbering is #1076's, kept so the deferral notes still line up. Its item 1 — func-registry entries outliving their library — is untouched here and stays its own later PR.)
-
-This file is the review guide. The part most worth a reviewer's time is at the end of item 4: the live structured-search path turned out to be **broken today**, in a way none of the deferral notes predicted, and fixing it is what makes item 4 correct rather than merely wider.
-
----
-
-## Item 2 — one home for "convert a leaf result into the caller's class"
-
-### What was wrong
-
-The same conversion existed four times across two repos: `_revalidate_against_object_class` in `content_generator.py`, a copy of it in our distributed-execution plugin's workflow arm, and a dict-shaped inline in each repo's `make_search_structured`. All four implement one contract — validate the leaf's data against the caller's original class, and on the dry path re-raise the `ValidationError` as `DryRunObjectFidelityError` naming the class and the `examples` / `mock_format` remedy.
-
-The copies existed for one reason only: the original was `_`-private, so the plugin could not import it — even though it already imports `assignment_models`, `content_generator_protocol` and `exceptions` from that same package.
-
-#1076 then made them **diverge**: core's copy gained the `isinstance` short-circuit, the plugin's did not. That is correct today — across `workflow.execute_activity` the object is always an instance of the class kajson rebuilt from `__kajson_class_source__`, never of `object_class` — but it is a latent trap, and the reasoning for why the check is `isinstance` and not `type(...) is` lived only in core's docstring.
-
-### What landed
-
-`pipelex/cogt/content_generation/object_revalidation.py`, a leaf module beside `object_class_resolution.py`. The two are the down leg and the up leg of the same journey, which is why they are siblings rather than one module.
-
-- `revalidate_leaf_object(raw_obj, *, object_class, is_mock_built, dump_mode="python")` — the object arm, carrying the short-circuit.
-- `revalidate_leaf_data(raw_data, *, object_class, is_mock_built)` — the data arm. Data is never an instance of anything, so there is no short-circuit to make and its validation is the single one on its path.
-
-The object arm delegates to the data arm, so the tree has exactly one `model_validate` call and one `except ValidationError` for this contract. The dry/live split is a branch inside that single `except`, rather than the two separate validate calls all four copies carried.
-
-**`dump_mode` is a parameter, not a unification.** Json mode coerces values (`datetime` → `str` and back); the in-process path must keep `"python"`. That was the deferral note's explicit instruction, and item 3 is why.
-
-### Worth a reviewer's attention
-
-- **The short-circuit now reaches the plugin's boundary path, where it never fires.** Intentional, not an oversight: it is dead code there today and exists so that a boundary which ever *does* hand back the caller's real class — a local activity, an in-process shortcut, a converter change — cannot silently reinstate the double validation. `test_instance_short_circuits_in_either_dump_mode` pins it in both modes.
-- **A LIVE `ValidationError` passes through untouched, on purpose.** The plugin's `make_search_structured` catches exactly that to convert it into a terminal typed error, because a bare `ValidationError` raised in workflow code is neither a workflow-execution error nor a `PipelexError`, so the host runtime treats it as a workflow-task failure and retries it forever — hanging the submitter. Had the shared helper swallowed or re-typed it, that conversion would have gone quiet. `test_live_data_failure_keeps_its_validation_error` pins the half of the contract that lives here.
-- **The plugin still carries its copies, and must.** It pins a released `pipelex` from PyPI, so it cannot import the new module until this ships. The swap is written up in the workspace notes, outside this repo.
-
----
-
-## Item 4 — the in-process structured-*search* path still rebuilt the output class
-
-### What was wrong
-
-`make_search_structured` held the caller's `output_structure_class` and never threaded it down, so `PipeSearch` with a structured output still handed the provider a class rebuilt from JSON schema — losing the custom validators, the `json_schema_extra` hints, and the output structure's own description, exactly as #1076 established for the object paths. Same defect, same shape, one remaining path.
-
-### Why it was not "four lines"
-
-The search leaf is **dict-out by contract** — that is what keeps a dynamic class off a distributed orchestrator's wire — and the submitter's re-validation of that dict is the single validation on the live path. Mirroring the object path naively breaks that in the dry arm: `dry_search_gen_structured` builds the mock and *dumps it*, so a mock built from the real class would have the caller's validators run at build **and again** on the dump. A transforming validator would produce `INV-INV-…` — the defect #1076 fixed on the object path with the `isinstance` short-circuit, which cannot apply once the instance has become a dict.
-
-### What landed
-
-Two entry points rather than one nullable parameter, because the two arms genuinely return different things:
-
-- `search_gen_structured(search_object_assignment) -> dict[str, Any]` — the boundary arm. Unchanged signature, unchanged return, so **the activity that calls it needs no change at all**.
-- `search_gen_structured_object(search_assignment, *, output_class) -> BaseModelTypeVar` — the in-process arm. The class goes down to the provider; an instance of it comes back, validated once at the leaf. It takes the plain `SearchAssignment`, not the wire model: nothing crosses a boundary in-process, so there is no schema to ship — and building the `SearchObjectAssignment` anyway would pay a `model_json_schema()` per call for a field nothing reads.
-
-`dry_search_gen_structured_object` is the dry counterpart and returns the mock *instance*, not a dump of it. That is the double-validation fix, and its docstring says so in those terms.
-
-No search-side resolution helper survived review: once the in-process arm carries the class outright, a `resolve_search_output_class` would have had no caller that ever passes a live class — a nullable arm that cannot fire. The boundary sites call `SchemaToModelFactory.make_from_json_schema` directly, and `resolve_object_class` keeps its genuinely dual-armed nullable parameter (exercised by `llm_generate`).
-
-`ContentGenerator.make_search_structured` now returns the leaf's instance directly. It no longer re-validates, and therefore no longer raises `DryRunObjectFidelityError` — in-process the mock is built from the real class, so a constrained class fails earlier and louder as `DryRunMockBuildError`, exactly as the object path has since #1076. `test_dry_search_structured_fidelity_gap_raises_typed_error` was re-scoped to the boundary composition and renamed for it; the in-process build-error arm and an `INV-INV-` once-only arm are new tests beside it.
-
-### ⚠ The live search path was broken, and threading the class down would have made it worse
-
-The deferral note flagged the live arm as "unverified: check whether the SDK internally instantiates the schema class". It does — and checking turned up something else first.
-
-**The Linkup backend asked for `include_sources=True`.** With that flag the SDK returns a `LinkupSearchStructuredResponse`, and the worker dumped the whole thing — so `search_structured` returned `{"data": {...}, "sources": [...]}` rather than the structured payload. The submitter then validated that envelope against the caller's output structure class, which has no `data` and no `sources` field. **Structured search through Linkup could not have worked.** The only test covering it is a live worker-level one written to assert the envelope, so it documented the shape rather than catching it. And the gateway backend had the same defect one hop removed: the relay's `WebSearcher.search_structured` also passes `include_sources=True` and returns the SDK response's `model_dump()`, so the gateway worker handed the leaf the same envelope — the default routing profile ships `all_pipelex_gateway`, so this was the arm users actually hit. The direct backend now asks for the payload alone; the gateway worker unwraps the relay's envelope on receipt (loudly, so a relay contract change surfaces as a classified error), and both backends hand the leaf the bare payload.
-
-**And the SDK does instantiate the class.** `_parse_search_response` calls `structured_output_schema.model_validate(...)` whenever it was handed a class rather than a string. Threading the caller's real class in would therefore have run the caller's validators inside the SDK and then again at the leaf — the same `INV-INV-…` defect, arriving through the provider instead of through the mock.
-
-Both are fixed at the worker, and the fix for the second is the one to check: **the schema crosses as a JSON string.** `_get_search_params` sends `json.dumps(cls.model_json_schema())` when handed a class and the string verbatim when handed a string, so `json.dumps(schema.model_json_schema())` is byte-for-byte the same request — while the parse branch that instantiates is guarded by `not isinstance(..., str)`, so the response comes back raw. The caller's real schema still reaches the provider in full; the single validation stays at the leaf, where the run mode and the fidelity contract live. `include_sources` is now `False`, matching what the contract can actually carry.
-
-`tests/unit/pipelex/providers/linkup/test_linkup_structured_search_contract.py` pins all three properties against a mocked client, and the live worker test's assertions were corrected to the payload shape.
-
----
-
-## Item 3 — auditing the boundary dump→validate round trip
-
-The deferral said: audit what actually crosses this conversion, add a round-trip property test over the models that do, and *if the audit finds a real loss*, consider having the boundary return raw data instead of a reconstructed instance. It found one. The fix turned out to be one keyword, not a redesign.
-
-### Who reaches the conversion
-
-**Nothing in this repo does.** Every branch of `make_object` / `make_object_list` returns an `isinstance` of `object_class`, so the short-circuit always fires:
-
-- **DRY** — `resolve_object_class` returns the caller's class unchanged and polyfactory's `build()` instantiates `__model__` itself, so the mock is exactly `object_class`.
-- **LIVE** — checked against every concrete LLM worker, not a sample: the OpenAI (completions + responses), Anthropic, Mistral and Google workers all return instructor's object untouched, and Bedrock raises `LLMCapabilityError` rather than returning. Gateway / Portkey / Azure / OpenRouter are those same workers under a different factory. Instructor's wrapper is `create_model(cls.__name__, __base__=(cls, OpenAISchema))`, a subclass — which is why the check is `isinstance`.
-- **The list path** wraps only the top-level `ListSchema`; its `items` are constructed by pydantic against `list[item_class]`.
-
-**The distributed boundary always reaches it**, and cannot short-circuit: the activity calls the leaves without a class, and kajson re-execs the rebuilt class on the workflow side from `__kajson_class_source__`, so what comes back is never a subclass of `object_class`. That is the split the design intends, now established rather than assumed.
-
-### The loss
-
-`object_class` is always a `StuffContent` subclass resolved **by name** from the class registry, so the set is open — any field name a user writes in a concept structure crosses this conversion.
-
-`datamodel-code-generator` cannot name a field `json`, `copy`, `schema` or `construct` (they shadow `BaseModel` attributes), nor use a python keyword. It renames the field and records the schema's property name as an alias. Dumping **by field name** emitted `construct_` for a field the caller's class calls `construct`, and re-validation failed with a bare `Field required` — on a field the caller had supplied.
-
-`by_alias=True` on the dump fixes it: the schema's property names are what the class was serialized as and what it accepts back, and where nothing was renamed the alias *is* the field name, so nothing else moves. The same one-word fix was needed on `dry_search_gen_structured`, which dumps its mock for the wire. `test_boundary_roundtrip_fidelity.py` fails on every shadowing field without it, in both dump modes, and carries the native content classes as controls.
-
-**The old note had the mechanism wrong, and it matters.** It supposed `PipeSearchSpec` / `PipeComposeSpec` survive thanks to `populate_by_name=True`. `PipeComposeSpec` did **not** survive — its `construct` property is exactly a shadowed name, and `populate_by_name` cannot help when the emitted key (`construct_`) matches neither the field name nor the alias. `PipeSearchSpec` survived only because `query` happens to be a legal field name.
-
-### What turned out to be safe, and now has a test
-
-- **Plain aliases need no compensation at all.** `model_json_schema()` emits by alias, so the rebuilt class's field name *is* the alias — with or without `populate_by_name`.
-- **Subclass erasure is structurally unreachable**, not merely unobserved: the crossing object is built from `object_class`'s own schema so it cannot carry extra fields, and the one object that *is* a subclass hits the short-circuit and is never dumped. No test, because the case cannot be constructed through this path.
-- **`CompositeContent` survives** — `extra="allow"` comes through the rebuild, so its components are preserved rather than dropped as unknown keys.
-
-### Left open, deliberately
-
-- **Instructor's `PARALLEL_TOOLS` modes return a generator, not an instance** — which would break the short-circuit's premise. Reachable from `StructureMethod`, but no model in the shipped TOMLs selects them. A config-reachable hazard, not a live one; worth a guard when one is configured, not before.
-- **Json-mode losslessness for arbitrary user field types** on the distributed arm. The residue of the original note, now narrowed to that.
-
-Both are recorded in `wip/refactoring/boundary-revalidation-round-trip-audit.md`, which replaces the "unaudited" note.
-
----
-
-## What the pre-landing review changed
-
-A full `/review` pass on this branch found production holes the deferral notes did not anticipate, and they are fixed here: the **direct Linkup backend could silently return wrong answers** (its only guard was `isinstance(response, dict)`, which the `{data, sources}` envelope passes — and an output structure whose fields all carry defaults validates that envelope *successfully* into an all-defaults object); a **billed search whose shape was rejected vanished from the cost report** (both new guards raise after the provider answered and after usage was recorded, and the worker only reported on the success path); and **`pipelex validate` stopped catching an output class that cannot emit a JSON schema** (dropping `SearchObjectAssignment.make_for_class` in-process also dropped the only `model_json_schema()` call on that path, so a dry run passed and the live run died inside the worker on a bare `RuntimeError`).
-
-Both backends now recognise the envelope **structurally** — via `pipelex/cogt/search/structured_search_payload.py` — rather than inferring the response shape from their own request. That also decouples the deploy: when the relay stops asking Linkup for sources, the gateway keeps working on the bare payload instead of rejecting every search. Alongside: reporting moved into `finally` in both search methods; a schema-generability check with a typed `OutputStructureSchemaError` on the in-process dry arm; `json.loads` wrapped so a non-JSON relay body is classified; an empty result now says so and points at the query instead of advising "try a different model"; and `linkup/exceptions.py` became `linkup_exceptions.py` with a `LinkupError` base, matching the sibling providers.
-
-## Still deferred
-
-The items the review surfaced and did **not** fix are written up, with their evidence and the command that produced it, in [`wip/refactoring/leaf-conversion-and-search-follow-ups.md`](wip/refactoring/leaf-conversion-and-search-follow-ups.md) — cite them as **RF-1** … **RF-7**. **RF-1 is the one to settle before the plugin sweep:** the bare live re-raise documented above as deliberate is right, but the plugin's *own* two arms disagree about it — its object helper lets a live `ValidationError` escape workflow code, while its search submitter converts it to a terminal typed error with a comment explaining that letting it escape retries forever and hangs the submitter. Both run in workflow code, so they cannot both be right, and swapping in the shared helper as-is would carry that unresolved disagreement into the shared home.
-
-- **Func-registry entries outliving their library** (#1076's item 1). Ruled to be its own later PR, after these. `wip/refactoring/func-registry-entries-outlive-their-library.md`.
-- **Our distributed-execution plugin's copies of the revalidation helper.** Release-gated on shipping `object_revalidation` — but no longer just a swap: see **RF-1** (the live-error contract blocks adoption) and **RF-2** (the copies now diverge on the `by_alias` fix this branch announces, which is reachable only on the plugin's arm).
-- **Dry search leaves report no usage.** Pre-existing, not introduced here; a small design rather than a mechanical patch, because it means choosing the synthetic-search-job conventions. Now recorded as **RF-6** rather than living only in this file.
-- **The remaining test gaps, the missing Linkup request timeout, and a coupled optimisation trap on the LLM path** — **RF-3**, **RF-4**, **RF-5**. RF-5 is worth reading before anyone "cleans up" the unused `model_json_schema()` call in `ObjectAssignment.make_for_class`: that call is what still implicitly guards the LLM path.
-
-## Cross-repo
-
-The sweep was done by enumerating the workspace's sibling repos one directory at a time. ⚠ A workspace-rooted `grep -r … .` silently returns zero matches here; exactly one consumer holds affected code, and every other hit is another worktree of this same repo.
-
-**Our distributed-execution plugin** — carries the copies item 2 replaces, and needs no change for item 4: the structured-search activity calls the boundary arm, whose signature and return type did not move. Release-gated on this shipping; the swap is written up in the workspace notes, outside this repo.
-
-**`pipelex-relay`** — optional alignment, not required for correctness, and **no longer a coordinated two-sided change**: the relay's structured route still passes `include_sources=True`, making Linkup gather sources the structured contract cannot carry, and wraps the payload in the `{data, sources}` envelope. The gateway worker now recognises that envelope *structurally* rather than demanding it, so the relay can stop requesting sources and return the payload alone on its own schedule — the worker handles either shape. What is left is that nothing on the producing side pins the contract, and the relay's own unit test asserts the opposite shape; that is **RF-7**.
-
-**`cocode` breaks on upgrade — still open, carried over from #1076, needs a follow-up PR in that repo.** `cocode/cocode/pipelines/doc_proofread/file_utils.py` carries `@pipe_func()` *and* a redundant module-level `func_registry.register_function(read_file_content, name="read_file_content")`. `cocode/cocode/swe/swe_cmd.py:18` dotted-imports that module at CLI startup, registering object **A**; `PIPELINE_LIBRARY_DIRS` then makes the same directory a library dir, so the boot scan re-imports the file under a path-mangled `sys.modules` key, the module-level call fires again with object **B**, and #1076's collision check raises. Every `cocode` command would die at first `load_libraries`. Shielded only by cocode's `pipelex==0.41.0` pin. The fix belongs in cocode and is a deletion: the `@pipe_func()` decorator already covers the registration. ⚠ `cocode/cocode/pipelines/text_utils.py:81` is *not* the same fix — it has no decorator, so its explicit call is its only registration.
diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.md
index cf0efc494..1baeaad09 100644
--- a/docs/contribute/hub-layering.md
+++ b/docs/contribute/hub-layering.md
@@ -43,7 +43,7 @@ There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as a
| inference | `get_inference_manager`, `get_llm_worker`, `get_img_gen_worker`, `get_extract_worker` |
| content generation | `get_content_generator`, `scoped_content_generator` |
| reporting | `get_report_delegate`, `is_in_isolated_execution` |
-| run mode | `is_dry_run_forced` |
+| run mode | `is_dry_run_forced`, `resolve_run_mode_for_boot` |
| tracing | `scoped_event_log`, `get_event_log_override` |
| plugin registries | `get_inference_backend_registry`, `get_model_lister_registry`, `get_orchestrator_registry`, `get_bundle_validator_registry`, `get_storage_provider_registry`, `get_secrets_provider_registry` |
@@ -75,6 +75,8 @@ Placement is decided by *kind*, not by who currently imports it. Several accesso
`get_pipe_func_executor_registry` is the one placement worth flagging: it is a plugin registry by kind (which would put it in the runtime layer) but its protocol lives in `pipe_operators/func/` (which puts it in the interpreter layer). It is **interpreter-layer**. See [Known inversions](#known-inversions) for the underlying wart.
+Not everything a hub module exports is an accessor. `resolve_run_mode_for_boot` *applies* the keyless-boot forced-DRY flag rather than reading it, and it lives beside `is_dry_run_forced`, the accessor it consumes. The lifecycle question above still decides placement — the flag is set once at boot and identical for every method the process runs, so the rule that interprets it is runtime-layer by kind. What makes the *module* the right home rather than either caller is that there are now two: the pipe tier's `PipeRunParamsFactory.make_run_params` and the kernel tier's `PipelexKernel.make` both mint run params, and a boot-scoped invariant copied into each is one that drifts. When a rule over hub state acquires a second caller, move the rule to the hub — do not let the second caller reimplement it.
+
## Why the boundary exists
`runtime_hub` must not name anything from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `interpreter_plugins`, `pipe_machinery`, `pipe_signature`, `mthds_parsing`, `pipeline` or `pipe_run` at module level. That list is now stated in whole top-level packages, which is the point of the modularity moves: it used to have to trail "…or the Pipe-touching modules of `core.pipes`", because some of what it forbids lived under a runtime-named package. Those module-level imports exist only to type the getters, but they are what made a single hub drag the entire method interpreter into every consumer that just wanted `get_console()`.
@@ -234,9 +236,9 @@ make check-hub-layering # alias: make chl
An AST guard (`pipelex-dev check-hub-layering`, core in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`) that runs in `make agent-check`, in the `make check` aggregate, and in CI. It checks three rules over `pipelex/` and `tests/`:
-1. **The layer rule.** A module in the declared runtime layer — `pipelex.cogt`, `pipelex.core`, `pipelex.errors`, `pipelex.graph`, `pipelex.observer`, `pipelex.plugins`, `pipelex.providers`, `pipelex.reporting`, `pipelex.system`, `pipelex.test_extras`, `pipelex.tools`, `pipelex.tracing`, plus the `pipelex.runtime_hub` and `pipelex.runtime_boot` modules themselves — may not import `pipelex.interpreter_hub`. The declaration is compliant with an empty exception list, so the guard hard-blocks on **any** violation. Entries are matched exact-or-dotted-prefix, which is why a bare *module* is a legal entry beside the packages: without `pipelex.runtime_hub` spelled out, the module at the centre of the rule would be exempt from it, and without `pipelex.runtime_boot` the runtime layer's own composition root would be — see [Where the boot splits](#where-the-boot-splits). `pipelex.core` was six entries until its interpreter tenants moved out — see [Where core splits](#where-core-splits) for what that enumeration was working around.
+1. **The layer rule.** A module in the declared runtime layer — `pipelex.cogt`, `pipelex.core`, `pipelex.errors`, `pipelex.graph`, `pipelex.kernel`, `pipelex.observer`, `pipelex.plugins`, `pipelex.providers`, `pipelex.reporting`, `pipelex.system`, `pipelex.test_extras`, `pipelex.tools`, `pipelex.tracing`, plus the `pipelex.runtime_hub` and `pipelex.runtime_boot` modules themselves — may not import `pipelex.interpreter_hub`. The declaration is compliant with an empty exception list, so the guard hard-blocks on **any** violation. Entries are matched exact-or-dotted-prefix, which is why a bare *module* is a legal entry beside the packages: without `pipelex.runtime_hub` spelled out, the module at the centre of the rule would be exempt from it, and without `pipelex.runtime_boot` the runtime layer's own composition root would be — see [Where the boot splits](#where-the-boot-splits). `pipelex.core` was six entries until its interpreter tenants moved out — see [Where core splits](#where-core-splits) for what that enumeration was working around.
- `graph`, `tracing`, `observer` and `errors` joined the list late, and the delay cost something — see [Known inversions](#known-inversions). They are the run-graph data model with its tracer and renderers, the trace-event assembler feeding it, the run-observation hooks, and the error taxonomy: machinery present at execution time whatever is loaded, which is the runtime layer's own definition. `pipelex.test_extras` is on the list for the same reason: it ships, `runtime_boot.py` imports it at boot, and it measures clean. `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all measure dirty and are interpreter-side by construction. That is every top-level package accounted for — which is the point, because the rule of thumb is that a measured-clean package should be *declared*, not left undeclared: **an undeclared package is not neutral, it is unpoliced.**
+ `graph`, `tracing`, `observer` and `errors` joined the list late, and the delay cost something — see [Known inversions](#known-inversions). They are the run-graph data model with its tracer and renderers, the trace-event assembler feeding it, the run-observation hooks, and the error taxonomy: machinery present at execution time whatever is loaded, which is the runtime layer's own definition. `pipelex.test_extras` is on the list for the same reason: it ships, `runtime_boot.py` imports it at boot, and it measures clean. `pipelex.kernel` is the same rule applied *ahead* of a breach instead of behind one: it was declared in the commit that created the package, because it holds the operator-execution semantics the interpreter's operator classes call into, and a single `interpreter_hub` reach anywhere in it would put the interpreter back into every programmatic caller — the property the package exists to provide. `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all measure dirty and are interpreter-side by construction. That is every top-level package accounted for — which is the point, because the rule of thumb is that a measured-clean package should be *declared*, not left undeclared: **an undeclared package is not neutral, it is unpoliced.**
2. **The dead-module rule.** *No* scanned module may reference `pipelex.hub`. It was deleted rather than aliased so a stale import fails loudly; this closes the one hole in that guarantee.
3. **The transitive rule.** No runtime-layer module may *reach* `pipelex.interpreter_hub` either, through any chain of module-level imports. Rules 1 and 2 are per-file and see one hop; this one resolves the whole module-level import graph of `pipelex/` and does reachability over it, reporting the shortest chain and the line of its first hop. It exists because the one-hop rules missed a live breach for a whole release: four modules of the declared runtime-layer `pipelex.plugins` package reached the interpreter hub through `runtime_bridge`, `pipeline` and `pipe_operators`, and both gates stayed green (see [Known inversions](#known-inversions)). A *direct* import is left to rule 1, which names the more specific remedy, rather than reported twice.
@@ -284,6 +286,8 @@ Each subprocess is time-bounded, because an unbounded one turns a deadlock into
Alongside them, `tests/unit/pipelex/test_hub_lifecycle.py` pins that a boot installs both singletons, and that the production `Pipelex.teardown` — not a stand-in calling `class_registry_scoping.reset()` directly — really releases the scoping an `InterpreterHub` installed, and that the next boot re-installs it. `tests/unit/pipelex/test_runtime_boot_closure.py` pins the boot-time half of the property: it *runs* `RuntimeBoot.make()` in a subprocess and asserts zero interpreter modules loaded, no `InterpreterHub` installed, and scoping left unscoped. A subprocess is required rather than preferred — both hubs are sticky class-attribute singletons that teardown never clears, so an in-process check would answer with a stale hub and pass vacuously. Booting rather than importing is what catches a boot step resolving out of an interpreter-contributed registry that is empty on that boot.
+`tests/unit/pipelex/kernel/test_kernel_boot_contract.py` takes the same escalation one step further and is the only gate that closes the function-local blind spot [the aggregate inversion](#known-inversions) exposed. It boots runtime-only, *calls* a Pipelex-kernel op on that boot, and sweeps `sys.modules` **after** the call rather than after the import. The order is the whole mechanism: a deferred import inside a kernel function lands in `sys.modules` during the call and nowhere else, so the static guard and the import-closure test both stay green on it — verified by injecting one, not assumed. For `pipelex.kernel` this is also the package's contract rather than a consequence of it, since the reason the kernel exists is that a programmatic caller can run operator semantics with no interpreter and no library loaded.
+
### This document — the `hub-layering-convention` drift contract
The guard and the closure test keep the *code* honest; neither can tell whether **this page** still describes it. That is a [drift contract](drift-contracts.md): `hub-layering-convention` names the guard and both hub modules as triggers and this document as the review target, so adding or moving a hub accessor — or changing the declared runtime layer — obliges a recorded review here before the change can land. It carries no verify command, because `check-hub-layering` already gates `make check` and CI.
diff --git a/docs/under-the-hood/image-handling-in-llm-prompts.md b/docs/under-the-hood/image-handling-in-llm-prompts.md
index 20597258d..5aec04739 100644
--- a/docs/under-the-hood/image-handling-in-llm-prompts.md
+++ b/docs/under-the-hood/image-handling-in-llm-prompts.md
@@ -437,7 +437,8 @@ Pages:
| File | Purpose |
|------|---------|
-| `pipelex/pipe_operators/shared/image_reference.py` | `ImageReference` and `ImageReferenceKind` models |
+| `pipelex/kernel/prompt_references.py` | `ImageReference` and `ImageReferenceKind` models |
+| `pipelex/kernel/llm_prompt_content.py` | Run-time prompt assembly — image collection, registry, placeholders |
| `pipelex/pipe_operators/shared/template_image_analyzer.py` | Factory-time template analysis |
| `pipelex/tools/jinja2/image_registry.py` | Runtime image tracking |
| `pipelex/tools/jinja2/jinja2_with_images_filter.py` | The `with_images` filter implementation |
@@ -447,7 +448,7 @@ Pages:
| File | Purpose |
|------|---------|
| `pipelex/tools/jinja2/jinja2_required_variables.py` | `VariableReference` for filter detection |
-| `pipelex/pipe_operators/llm/llm_prompt_blueprint.py` | Prompt building with image collection |
+| `pipelex/pipe_operators/llm/llm_prompt_blueprint.py` | The parsed `.mthds` prompt, holding the image references and mapping down to the kernel |
---
diff --git a/pipelex/cli/dev_cli/commands/hub_layering_guard.py b/pipelex/cli/dev_cli/commands/hub_layering_guard.py
index a602008da..151bee2b6 100644
--- a/pipelex/cli/dev_cli/commands/hub_layering_guard.py
+++ b/pipelex/cli/dev_cli/commands/hub_layering_guard.py
@@ -136,9 +136,18 @@ SCAN_ROOTS: tuple[Path, ...] = (SOURCE_ROOT, TESTS_ROOT)
#: feeding them, `observer` the run-observation hooks, `errors` the error taxonomy — all machinery
#: present at execution time whatever is loaded, which is the runtime layer's own definition.
#: `pipelex.test_extras` is here for the same reason: it ships, `pipelex.py` imports it at boot, and it
-#: measures clean — leaving it out would repeat the omission this entry documents. `pipelex.kit` is data
-#: files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all
-#: measure dirty and are interpreter-side by construction. That is every top-level package accounted for.
+#: measures clean — leaving it out would repeat the omission this entry documents.
+#:
+#: `pipelex.kernel` is declared from its first commit rather than after the fact, which is the whole
+#: lesson of the two entries above applied ahead of the breach instead of behind it. It holds the
+#: operator-execution semantics the interpreter's operator classes call into, so a single
+#: `interpreter_hub` reach anywhere in it would put the interpreter back into every programmatic
+#: caller — the exact property the package exists to provide. Declaring it also enrols it in the
+#: `pipelex.exceptions` aggregate gate, whose domain *is* this tuple.
+#:
+#: `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge`
+#: and `pipelex.cli` all measure dirty and are interpreter-side by construction. That is every
+#: top-level package accounted for.
#: That the declaration is a claim rather than a hope is why it is asserted by a test.
#: See the "Where core splits" section of ``docs/contribute/hub-layering.md``.
RUNTIME_LAYER_PACKAGES: tuple[str, ...] = (
@@ -146,6 +155,7 @@ RUNTIME_LAYER_PACKAGES: tuple[str, ...] = (
"pipelex.core",
"pipelex.errors",
"pipelex.graph",
+ "pipelex.kernel",
"pipelex.observer",
"pipelex.plugins",
"pipelex.providers",
diff --git a/pipelex/kernel/__init__.py b/pipelex/kernel/__init__.py
new file mode 100644
index 000000000..e7cc464b3
--- /dev/null
+++ b/pipelex/kernel/__init__.py
@@ -0,0 +1,68 @@
+"""The Pipelex kernel: operator-execution semantics as importable functions.
+
+What a `PipeLLM` step actually *does* — deck resolution, templating-style derivation, prompt
+assembly, generation, memory write-back — used to be reachable only through a fully booted
+interpreter with a loaded library. This package holds that semantics once, so it has **one
+implementation with multiple callers**: the interpreter's operator classes, and any programmatic
+caller invoking the same functions on a ``RuntimeBoot``-only process with zero ``.mthds`` loaded.
+Single-sourcing is the point — two callers with two copies drift.
+
+The doctrine below is what keeps that true. Each rule exists because its absence has already cost
+this repo something; see ``docs/contribute/hub-layering.md``.
+
+**Layering.** The caller-facing API is hub-free: an explicit :class:`~pipelex.kernel.pipelex_kernel.PipelexKernel`
+and explicit arguments, never an ambient lookup. Kernel *internals* may use ``pipelex.runtime_hub``
+— never ``pipelex.interpreter_hub``, directly or transitively. ``pipelex.kernel`` is declared in the
+guard's ``RUNTIME_LAYER_PACKAGES`` and pinned by a test, because **an undeclared package is not
+neutral, it is unpoliced**: both the layer rule and the transitive rule filter their candidates
+through that declaration, so omitting the entry makes the guard quieter rather than louder.
+
+**Import from definition sites only.** Never from ``pipelex.exceptions`` or any other cross-layer
+re-export aggregate, and never let this ``__init__.py`` become one. For most of the tree that is a
+style rule (the repo's "direct full-path imports everywhere"); here it is a *layering* property — a
+module that re-exports across layers is a layer boundary with the sign filed off, and importing one
+symbol from it drags every interpreter package it re-exports into the runtime closure. Five vendor
+adapters once loaded interpreter modules apiece through exactly that hole with every gate green.
+The mechanical half is bought by the declaration above:
+``tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py`` walks every declared package
+and fails on imports and bare strings alike, module-level or function-local.
+
+**Every import stays at module top level.** A function-local import is invisible to the static
+import graph and to the import-closure test at the same time, so it hides a breach from both gates
+at once. If one ever seems necessary here, the placement is wrong and the type should move instead.
+
+**Concept resolution goes through the pure tiers.** Kernel run paths answer concept compatibility
+with :meth:`~pipelex.core.concepts.concept.Concept.are_compatible_by_declaration` (no registry; a
+caller without a loaded library supplies its own ``concept_resolver``, or omits it where no
+``refines`` crosses a package boundary) and ``are_structure_classes_compatible`` (which takes
+resolved types). It never calls ``ConceptLibrary.is_compatible`` or
+``ConceptProviderAbstract.get_structure_class`` — that is where resolution, and therefore the
+ambient registry read, legitimately lives. Passing the concrete class alongside the concept is the
+preferred shape, which is why the object entry point takes ``output_class`` outright.
+
+**Calls are activity-shaped.** Explicit, serializable-leaning inputs and outputs; ``WorkingMemory``
+threaded explicitly (taken and returned); no hidden shared state. The memory contract, stated once
+so both caller classes read the same thing: **a kernel call may mutate the memory it is passed and
+returns it — callers must treat the returned memory as the result and must not rely on aliasing of
+the argument**, because inline execution aliases the two today and a serialization boundary will
+not. This is a design constraint, not a deliverable: it keeps a future distributed-activity wrapping
+a re-decoration rather than a rewrite.
+
+**Functions carry the semantics; the class is a façade.** Module-level functions hold the shared
+implementation. ``PipelexKernel`` is a thin ergonomic façade over them, holding the per-run state a
+caller would otherwise thread through every call. The interpreter's operators call the functions
+directly.
+
+**The API is fully keyword-only — zero subject grants.** Only a first parameter may be positional,
+and strictly only when it is obviously the subject. Nothing here clears that bar: ``llm_text`` and
+``llm_object`` name what they *produce*, and ``memory`` is threaded state, not the operand. So
+``pipelex/kernel/`` records no entries in ``subject_grants.toml`` and every call site names every
+argument.
+
+**Boot contract.** Every kernel call must be servable on ``RuntimeBoot.make()``
+(``pipelex/runtime_boot.py``) with no interpreter constructed and no library loaded. The
+import-closure test guards that structurally; a booted-runtime test proves it dynamically.
+
+Per the repo-wide rule, this module holds **no re-exports** — import each symbol from the module
+that defines it.
+"""
diff --git a/pipelex/kernel/exceptions.py b/pipelex/kernel/exceptions.py
new file mode 100644
index 000000000..45e9ad60c
--- /dev/null
+++ b/pipelex/kernel/exceptions.py
@@ -0,0 +1,7 @@
+class PromptContentError(ValueError):
+ """A prompt's image or document reference could not be resolved out of working memory.
+
+ A `ValueError` rather than a `PipelexError` subclass, matching what the prompt-assembly code
+ raised before it moved into the kernel: callers that already handle it as a value error keep
+ working, and nothing in the error taxonomy changes.
+ """
diff --git a/pipelex/kernel/llm_ops.py b/pipelex/kernel/llm_ops.py
new file mode 100644
index 000000000..da797eb87
--- /dev/null
+++ b/pipelex/kernel/llm_ops.py
@@ -0,0 +1,251 @@
+"""LLM operator semantics: deck resolution, style derivation, generation, memory write-back.
+
+These are the functions the interpreter's `PipeLLM` and `PipeStructure` call, and the ones a
+programmatic caller invokes on a `RuntimeBoot`-only process. They read the runtime hub for the
+services a runtime boot stands up (the model deck, the content generator) — sanctioned kernel
+internals — and take everything else as an explicit argument.
+
+Two seams are deliberately *not* here, because they are the caller's job by construction:
+
+- **Text-vs-object dispatch.** The two entry points below are that fork made explicit. Deciding
+ which one a step wants is a question about the declared output concept, and answering it is what
+ a loaded library is for.
+- **Error context.** These functions raise the same cogt-level errors the code they were extracted
+ from raised — `LLMCompletionError` from a generation call, `ValidationError` from constructing the
+ output class. The interpreter re-wraps them into `PipeRunError` with the pipe stack, exactly as it
+ always has; the kernel has no pipe to name.
+"""
+
+from typing import Any
+
+from pipelex import log
+from pipelex.cogt.content_generation.cogt_run_params import CogtRunParams
+from pipelex.cogt.llm.llm_prompt import LLMPrompt
+from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting
+from pipelex.cogt.model_backends.model_type import ModelType
+from pipelex.cogt.templating.template_rendering import render_template
+from pipelex.config import get_config
+from pipelex.core.concepts.concept import Concept
+from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.stuffs.list_content import ListContent
+from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.core.stuffs.stuff_factory import StuffFactory
+from pipelex.kernel.llm_prompt_content import LlmPromptContent, assemble_llm_prompt
+from pipelex.kernel.llm_results import LlmObjectResult, LlmTextResult, StructuringPath
+from pipelex.runtime_hub import get_content_generator, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TemplatingStyle
+from pipelex.tools.typing.structure_printer import StructurePrinter
+
+
+def resolve_llm_setting_for_text(*, llm_choice: LLMModelChoice | None = None) -> LLMSetting:
+ """The deck chain for a text output: the step's own choice, then the deck's override, then its default."""
+ model_deck = get_model_deck()
+ resolved_choice = llm_choice or model_deck.llm_choice_overrides.for_text or model_deck.llm_choice_defaults.for_text
+ return model_deck.get_llm_setting(llm_choice=resolved_choice)
+
+
+def resolve_llm_setting_for_object(*, llm_choice: LLMModelChoice | None = None, llm_choice_for_text: LLMModelChoice | None = None) -> LLMSetting:
+ """The deck chain for a structured output.
+
+ One rung longer than the text chain, and the extra rung is the point: a step that names a model
+ for text only still generates its objects with that model, so `llm_choice_for_text` is consulted
+ before the deck's own object override. A caller with no text choice (a step that only ever
+ produces objects) leaves it unset and gets the plain override-then-default chain.
+ """
+ model_deck = get_model_deck()
+ resolved_choice = llm_choice or llm_choice_for_text or model_deck.llm_choice_overrides.for_object or model_deck.llm_choice_defaults.for_object
+ return model_deck.get_llm_setting(llm_choice=resolved_choice)
+
+
+def derive_templating_style(*, llm_setting: LLMSetting) -> TemplatingStyle | None:
+ """The configured prompting style for a resolved setting, via its prompting target.
+
+ Derived per call and never cached: the deck and the config can both change under a live process,
+ and a cached style would shadow that with whatever the first call saw.
+
+ Returns `None` when the deck has no inference model for the handle, which is what an external
+ LLM plugin looks like from here — the model is real, it is just not in the deck.
+ """
+ inference_model = get_model_deck().get_optional_inference_model(model_handle=llm_setting.model, model_type=ModelType.LLM)
+ if inference_model is None:
+ return None
+ prompting_target = llm_setting.prompting_target or inference_model.prompting_target
+ return get_config().pipelex.prompting_config.get_prompting_style(prompting_target=prompting_target)
+
+
+async def derive_structure_prompt(*, output_class: type[StuffContent]) -> str | None:
+ """Render the structure-description prompt for an output class.
+
+ Derived from the class in hand — no concept-to-class registry hop, because the caller already
+ holds the class. Returns `None` when structure prompts are disabled in config, or when the class
+ has no printable structure (a bare text content has none).
+ """
+ llm_config = get_config().cogt.llm_config
+ if not llm_config.is_structure_prompt_enabled:
+ return None
+ class_structure = StructurePrinter().get_type_structure(tp=output_class, base_class=StuffContent)
+ if not class_structure:
+ return None
+ return await render_template(
+ template=llm_config.get_template(template_name="output_structure_prompt"),
+ category=TemplateCategory.LLM_PROMPT,
+ context={"class_structure_str": "\n".join(class_structure)},
+ )
+
+
+async def generate_object_content(
+ *,
+ job_metadata: JobMetadata,
+ cogt_run_params: CogtRunParams,
+ llm_prompt: LLMPrompt,
+ llm_setting: LLMSetting,
+ output_class: type[StuffContent],
+ is_multiple_output: bool = False,
+ fixed_nb_output: int | None = None,
+) -> StuffContent:
+ """Generate one object, or a `ListContent` of them when several were asked for.
+
+ Takes the concrete class rather than a name: it is threaded straight through to the content
+ generator, so nothing rebuilds a class from a schema when the class already exists. The schema
+ round-trip further down still serves the distributed-activity boundary and is untouched.
+ """
+ content_generator = get_content_generator()
+ if is_multiple_output:
+ count_desc = f"{fixed_nb_output}x" if fixed_nb_output else "list of "
+ log.verbose(f"Kernel generating {count_desc}{output_class.__name__} by object_direct")
+ generated_objects = await content_generator.make_object_list(
+ job_metadata=job_metadata,
+ cogt_run_params=cogt_run_params,
+ object_class=output_class,
+ llm_prompt_for_object_list=llm_prompt,
+ llm_setting_for_object_list=llm_setting,
+ nb_items=fixed_nb_output,
+ )
+ return ListContent(items=generated_objects)
+
+ log.verbose(f"Kernel generating a single {output_class.__name__} by object_direct")
+ return await content_generator.make_object(
+ job_metadata=job_metadata,
+ cogt_run_params=cogt_run_params,
+ object_class=output_class,
+ llm_prompt_for_object=llm_prompt,
+ llm_setting_for_object=llm_setting,
+ )
+
+
+def store_result(
+ *,
+ memory: WorkingMemory,
+ concept: Concept,
+ content: StuffContent,
+ result_name: str | None = None,
+ result_code: str | None = None,
+) -> WorkingMemory:
+ """Write a produced content into memory as the new main stuff, and return the memory.
+
+ Returning it is the contract, not a convenience: the argument is mutated today because inline
+ execution aliases the two, and a caller that relies on that aliasing breaks the moment a
+ serialization boundary sits between them.
+ """
+ stuff = StuffFactory.make_stuff(concept=concept, content=content, name=result_name, code=result_code)
+ memory.set_new_main_stuff(stuff=stuff, name=result_name)
+ return memory
+
+
+async def run_llm_text(
+ *,
+ memory: WorkingMemory,
+ prompt_content: LlmPromptContent,
+ llm_setting: LLMSetting,
+ concept: Concept,
+ output_class: type[StuffContent],
+ job_metadata: JobMetadata,
+ cogt_run_params: CogtRunParams,
+ templating_style: TemplatingStyle | None = None,
+ extra_params: dict[str, Any] | None = None,
+ result_name: str | None = None,
+ result_code: str | None = None,
+) -> LlmTextResult:
+ """A whole LLM step with a text output: assemble, generate, store, report.
+
+ `templating_style` is an argument rather than derived here because a caller may hold more than
+ one resolved setting for a step and has to say which one governs rendering — `PipeLLM` derives
+ it from its text setting even on its object path.
+ """
+ llm_prompt = await assemble_llm_prompt(
+ prompt_content=prompt_content,
+ context_provider=memory,
+ output_structure_prompt=None,
+ extra_params=extra_params,
+ templating_style=templating_style,
+ )
+ generated_text = await get_content_generator().make_llm_text(
+ job_metadata=job_metadata,
+ cogt_run_params=cogt_run_params,
+ llm_prompt_for_text=llm_prompt,
+ llm_setting_main=llm_setting,
+ )
+ # `model_validate` rather than `output_class(text=...)`: the class arrives typed as
+ # `type[StuffContent]`, whose declared fields do not include `text` — the subclasses that a
+ # Text-compatible concept resolves to are what carry it. Validation, and the `ValidationError`
+ # a mismatch raises, are identical either way.
+ content = output_class.model_validate({"text": generated_text})
+ return LlmTextResult(
+ memory=store_result(memory=memory, concept=concept, content=content, result_name=result_name, result_code=result_code),
+ text=generated_text,
+ rendered_prompt=llm_prompt,
+ llm_setting=llm_setting,
+ structuring_path=StructuringPath.TEXT,
+ )
+
+
+async def run_llm_object(
+ *,
+ memory: WorkingMemory,
+ prompt_content: LlmPromptContent,
+ llm_setting: LLMSetting,
+ concept: Concept,
+ output_class: type[StuffContent],
+ job_metadata: JobMetadata,
+ cogt_run_params: CogtRunParams,
+ structure_prompt: str | None = None,
+ is_multiple_output: bool = False,
+ fixed_nb_output: int | None = None,
+ templating_style: TemplatingStyle | None = None,
+ extra_params: dict[str, Any] | None = None,
+ result_name: str | None = None,
+ result_code: str | None = None,
+) -> LlmObjectResult:
+ """A whole LLM step with a structured output: assemble, generate, store, report.
+
+ `structure_prompt` overrides the description the kernel would otherwise derive from
+ `output_class`. Leaving it unset is the normal path and is what keeps both callers producing the
+ same prompt by default — a prompt supplied only from outside would have left the derivation at
+ each caller and let the two defaults fork.
+ """
+ output_structure_prompt = structure_prompt if structure_prompt is not None else await derive_structure_prompt(output_class=output_class)
+ llm_prompt = await assemble_llm_prompt(
+ prompt_content=prompt_content,
+ context_provider=memory,
+ output_structure_prompt=output_structure_prompt,
+ extra_params=extra_params,
+ templating_style=templating_style,
+ )
+ content = await generate_object_content(
+ job_metadata=job_metadata,
+ cogt_run_params=cogt_run_params,
+ llm_prompt=llm_prompt,
+ llm_setting=llm_setting,
+ output_class=output_class,
+ is_multiple_output=is_multiple_output,
+ fixed_nb_output=fixed_nb_output,
+ )
+ return LlmObjectResult(
+ memory=store_result(memory=memory, concept=concept, content=content, result_name=result_name, result_code=result_code),
+ content=content,
+ rendered_prompt=llm_prompt,
+ llm_setting=llm_setting,
+ structuring_path=StructuringPath.OBJECT_LIST if is_multiple_output else StructuringPath.OBJECT_DIRECT,
+ )
diff --git a/pipelex/kernel/llm_prompt_content.py b/pipelex/kernel/llm_prompt_content.py
new file mode 100644
index 000000000..d1d44863a
--- /dev/null
+++ b/pipelex/kernel/llm_prompt_content.py
@@ -0,0 +1,408 @@
+"""Prompt assembly: templates plus memory-borne images and documents, into one `LLMPrompt`.
+
+This is the runtime-layer home of what `LLMPromptBlueprint.make_llm_prompt` used to do inline.
+`LLMPromptBlueprint` stays where it is — it is a language artifact, what `.mthds` parses into, and it
+keeps its parse-and-validate role — but it now maps down onto :func:`assemble_llm_prompt` rather than
+holding the semantics, so the interpreter and a programmatic caller assemble prompts through the
+same code.
+
+The ordering here is load-bearing and is preserved exactly: system-prompt images are registered
+before user-prompt ones, and the system text renders before the user text, so the `[Image N]` tokens
+a template interpolates match the positions of the images handed to the model.
+"""
+
+from typing import TYPE_CHECKING, Any, Self, cast
+
+from pydantic import BaseModel
+
+from pipelex import log
+from pipelex.cogt.document.prompt_document import PromptDocument
+from pipelex.cogt.document.prompt_document_factory import PromptDocumentFactory
+from pipelex.cogt.image.prompt_image_factory import PromptImageFactory
+from pipelex.cogt.llm.llm_prompt import LLMPrompt
+from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
+from pipelex.cogt.templating.template_rendering import render_template
+from pipelex.core.stuffs.document_content import DocumentContent
+from pipelex.core.stuffs.image_content import ImageContent
+from pipelex.kernel.exceptions import PromptContentError
+from pipelex.kernel.prompt_references import DocumentReference, DocumentReferenceKind, ImageReference, ImageReferenceKind
+from pipelex.tools.jinja2.image_registry import ImageRegistry
+from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract
+from pipelex.tools.misc.dict_utils import substitute_nested_in_context
+from pipelex.tools.misc.exceptions import ContextProviderError
+from pipelex.tools.templating.templating_style import TemplatingStyle
+
+if TYPE_CHECKING:
+ from pipelex.cogt.image.prompt_image import PromptImage
+
+
+class LlmPromptContent(BaseModel):
+ """What a prompt is made of, before anything is rendered: two templates and their references.
+
+ The reference lists are how images and documents enter a prompt — the templates interpolate
+ `[Image N]` / `[Document N]` tokens, and the referenced content is fetched out of the context
+ provider (working memory) at assembly time.
+ """
+
+ user_template: TemplateBlueprint | None = None
+ system_template: TemplateBlueprint | None = None
+ user_image_references: list[ImageReference] | None = None
+ user_document_references: list[DocumentReference] | None = None
+ system_image_references: list[ImageReference] | None = None
+ system_document_references: list[DocumentReference] | None = None
+
+ @classmethod
+ def make_from_text(cls, *, user: str, system: str | None = None) -> Self:
+ """Text-only prompt content from two template strings, rendered against the caller's memory.
+
+ No image or document references: a caller that needs those builds the model directly, which
+ is what the interpreter's blueprint mapping does.
+ """
+ return cls(
+ user_template=TemplateBlueprint(template=user, category=TemplateCategory.LLM_PROMPT),
+ system_template=TemplateBlueprint(template=system, category=TemplateCategory.LLM_PROMPT) if system is not None else None,
+ )
+
+
+async def assemble_llm_prompt(
+ *,
+ prompt_content: LlmPromptContent,
+ context_provider: ContextProviderAbstract,
+ output_structure_prompt: str | None = None,
+ extra_params: dict[str, Any] | None = None,
+ templating_style: TemplatingStyle | None = None,
+) -> LLMPrompt:
+ """Render both templates against the context and collect the images and documents they reference."""
+ ############################################################
+ # Image Registry and Direct Image Extraction
+ # Extract system prompt images FIRST, then user prompt images
+ ############################################################
+ image_registry = ImageRegistry()
+ # Maps image variable name to its 0-based registry index (for placeholder generation)
+ image_registry_indices: dict[str, int] = {}
+ # Track which variable paths are lists, so we can substitute the whole list
+ list_image_refs: list[ImageReference] = []
+
+ # Process system prompt image references first (so they get lower numbers), then the user ones.
+ for image_references in (prompt_content.system_image_references, prompt_content.user_image_references):
+ if not image_references:
+ continue
+ for image_ref in image_references:
+ match image_ref.kind:
+ case ImageReferenceKind.DIRECT:
+ # Single ImageContent reference
+ _extract_direct_image(
+ image_ref=image_ref,
+ context_provider=context_provider,
+ image_registry=image_registry,
+ image_registry_indices=image_registry_indices,
+ )
+ case ImageReferenceKind.DIRECT_LIST:
+ # List of ImageContent reference
+ _extract_direct_list_images(
+ image_ref=image_ref,
+ context_provider=context_provider,
+ image_registry=image_registry,
+ image_registry_indices=image_registry_indices,
+ )
+ list_image_refs.append(image_ref)
+ case ImageReferenceKind.NESTED:
+ # Nested images will be extracted by the | with_images filter
+ # during template rendering - the registry is passed in context
+ pass
+
+ ############################################################
+ # Direct Document Extraction
+ # Extract system prompt documents FIRST, then user prompt documents
+ ############################################################
+ prompt_user_documents: dict[str, PromptDocument] = {}
+ list_document_refs: list[DocumentReference] = []
+
+ for document_references in (prompt_content.system_document_references, prompt_content.user_document_references):
+ if not document_references:
+ continue
+ for doc_ref in document_references:
+ match doc_ref.kind:
+ case DocumentReferenceKind.DIRECT:
+ _extract_direct_document(
+ doc_ref=doc_ref,
+ context_provider=context_provider,
+ prompt_user_documents=prompt_user_documents,
+ )
+ case DocumentReferenceKind.DIRECT_LIST:
+ _extract_direct_list_documents(
+ doc_ref=doc_ref,
+ context_provider=context_provider,
+ prompt_user_documents=prompt_user_documents,
+ )
+ list_document_refs.append(doc_ref)
+
+ ############################################################
+ # User text
+ ############################################################
+ # Add image placeholders to extra_params for substitution in template
+ # - Direct images (non-dotted paths like "image"): add placeholder directly
+ # - List images: add list variable with all tokens joined
+ # - Dotted paths (e.g., "page.page_view"): handled by tag filter via ImageRegistry.get_image_placeholder()
+ # because dotted paths cannot be substituted in immutable StuffArtefacts
+ extra_params = extra_params or {}
+ if image_registry_indices:
+ # Collect list variable paths for exclusion from direct substitution
+ list_variable_paths = {list_ref.variable_path for list_ref in list_image_refs}
+
+ # Add placeholders for direct (non-dotted, non-list) images
+ for image_name, registry_index in image_registry_indices.items():
+ # Skip list item references (e.g., "images[1]")
+ if "[" in image_name:
+ continue
+ # Skip dotted paths (e.g., "page.page_view") - handled by finalize/filter at render time
+ if "." in image_name:
+ continue
+ # Skip list variable references (handled separately below)
+ if image_name in list_variable_paths:
+ continue
+ # Add direct image placeholder
+ extra_params[image_name] = f"[Image {registry_index + 1}]"
+
+ # For list image references, substitute the list variable itself
+ # with a string containing all the [Image N] tokens for items in that list
+ for list_ref in list_image_refs:
+ list_tokens: list[str] = []
+ for image_name, registry_index in image_registry_indices.items():
+ # Check if this image belongs to this list (e.g., "collection_a[1]" belongs to "collection_a")
+ if image_name.startswith(f"{list_ref.variable_path}["):
+ list_tokens.append(f"[Image {registry_index + 1}]")
+ if list_tokens:
+ extra_params[list_ref.variable_path] = ", ".join(list_tokens)
+
+ # Replace direct document variables with numbered tags
+ if prompt_user_documents:
+ document_names = list(prompt_user_documents.keys())
+ for document_index, document_name in enumerate(document_names):
+ extra_params[document_name] = f"[Document {document_index + 1}]"
+
+ # For list document references, also substitute the list variable itself
+ for doc_list_ref in list_document_refs:
+ doc_list_tokens: list[str] = []
+ for document_name in document_names:
+ if document_name.startswith(f"{doc_list_ref.variable_path}["):
+ doc_list_tokens.append(extra_params[document_name])
+ if doc_list_tokens:
+ extra_params[doc_list_ref.variable_path] = "\n".join(doc_list_tokens)
+
+ ############################################################
+ # System text (rendered FIRST so nested images get lower numbers)
+ ############################################################
+ system_text: str | None = None
+ if prompt_content.system_template:
+ system_text = await _unravel_text(
+ context_provider=context_provider,
+ jinja2_blueprint=prompt_content.system_template,
+ extra_params=extra_params,
+ image_registry=image_registry,
+ templating_style=templating_style,
+ )
+
+ ############################################################
+ # User text (rendered AFTER system text for consistent image ordering)
+ ############################################################
+ user_text: str | None = None
+ if prompt_content.user_template:
+ user_text = await _unravel_text(
+ context_provider=context_provider,
+ jinja2_blueprint=prompt_content.user_template,
+ extra_params=extra_params,
+ image_registry=image_registry,
+ templating_style=templating_style,
+ )
+ if output_structure_prompt:
+ user_text += output_structure_prompt
+ else:
+ user_text = output_structure_prompt
+ # Note that output_structure_prompt can be None
+ # it's OK to have a null user_text
+
+ ############################################################
+ # Collect all images from registry (single source of truth)
+ ############################################################
+ # The registry contains all images (direct + nested) in the correct order,
+ # already deduplicated by URL. This ensures [Image N] tokens match positions.
+ all_images: list[PromptImage] = [PromptImageFactory.make_prompt_image(uri=registry_image.url) for registry_image in image_registry.images]
+
+ ############################################################
+ # Collect all documents
+ ############################################################
+ all_documents: list[PromptDocument] = list(prompt_user_documents.values())
+
+ ############################################################
+ # Full LLMPrompt
+ ############################################################
+ return LLMPrompt(
+ system_text=system_text,
+ user_text=user_text,
+ user_images=all_images,
+ user_documents=all_documents,
+ )
+
+
+def _extract_direct_image(
+ *,
+ image_ref: ImageReference,
+ context_provider: ContextProviderAbstract,
+ image_registry: ImageRegistry,
+ image_registry_indices: dict[str, int],
+) -> None:
+ """Extract a single ImageContent from context and register it."""
+ log.verbose(f"Getting direct image '{image_ref.variable_path}' from context")
+ try:
+ prompt_image_content = context_provider.get_typed_object_or_attribute(
+ name=image_ref.variable_path,
+ wanted_type=ImageContent,
+ accept_list=False,
+ )
+ if isinstance(prompt_image_content, ImageContent):
+ registry_index = image_registry.register_image(prompt_image_content)
+ image_registry_indices[image_ref.variable_path] = registry_index
+ else:
+ msg = f"Image reference '{image_ref.variable_path}' is of type '{type(prompt_image_content).__name__}', expected ImageContent"
+ raise PromptContentError(msg)
+ except ContextProviderError as exc:
+ msg = f"Could not find image '{image_ref.variable_path}' in context: {exc}"
+ raise PromptContentError(msg) from exc
+
+
+def _extract_direct_list_images(
+ *,
+ image_ref: ImageReference,
+ context_provider: ContextProviderAbstract,
+ image_registry: ImageRegistry,
+ image_registry_indices: dict[str, int],
+) -> None:
+ """Extract a list of ImageContent from context and register them."""
+ log.verbose(f"Getting image list '{image_ref.variable_path}' from context")
+ try:
+ prompt_image_content = context_provider.get_typed_object_or_attribute(
+ name=image_ref.variable_path,
+ wanted_type=ImageContent,
+ accept_list=True,
+ )
+ if isinstance(prompt_image_content, (list, tuple)):
+ image_items = cast("list[Any] | tuple[Any, ...]", prompt_image_content)
+ for list_position, image_item in enumerate(image_items, start=1):
+ if not isinstance(image_item, ImageContent):
+ msg = f"Item of '{image_ref.variable_path}' is of type '{type(image_item).__name__}', expected ImageContent"
+ raise PromptContentError(msg)
+ registry_index = image_registry.register_image(image_item)
+ # Use list position (1-based) for variable name, registry index for image number
+ image_item_name = f"{image_ref.variable_path}[{list_position}]"
+ image_registry_indices[image_item_name] = registry_index
+ else:
+ msg = (
+ f"Image list reference '{image_ref.variable_path}' is of type '{type(prompt_image_content).__name__}', "
+ "expected list or tuple of ImageContent"
+ )
+ raise PromptContentError(msg)
+ except ContextProviderError as exc:
+ msg = f"Could not find image list '{image_ref.variable_path}' in context: {exc}"
+ raise PromptContentError(msg) from exc
+
+
+def _extract_direct_document(
+ *,
+ doc_ref: DocumentReference,
+ context_provider: ContextProviderAbstract,
+ prompt_user_documents: dict[str, PromptDocument],
+) -> None:
+ """Extract a single DocumentContent from context."""
+ log.verbose(f"Getting direct document '{doc_ref.variable_path}' from context")
+ try:
+ prompt_document_content = context_provider.get_typed_object_or_attribute(
+ name=doc_ref.variable_path,
+ wanted_type=DocumentContent,
+ accept_list=False,
+ )
+ if isinstance(prompt_document_content, DocumentContent):
+ user_document = PromptDocumentFactory.make_prompt_document(
+ uri=prompt_document_content.url,
+ mime_type=prompt_document_content.mime_type,
+ )
+ prompt_user_documents[doc_ref.variable_path] = user_document
+ else:
+ msg = f"Document reference '{doc_ref.variable_path}' is of type '{type(prompt_document_content).__name__}', expected DocumentContent"
+ raise PromptContentError(msg)
+ except ContextProviderError as exc:
+ msg = f"Could not find document '{doc_ref.variable_path}' in context: {exc}"
+ raise PromptContentError(msg) from exc
+
+
+def _extract_direct_list_documents(
+ *,
+ doc_ref: DocumentReference,
+ context_provider: ContextProviderAbstract,
+ prompt_user_documents: dict[str, PromptDocument],
+) -> None:
+ """Extract a list of DocumentContent from context."""
+ log.verbose(f"Getting document list '{doc_ref.variable_path}' from context")
+ try:
+ prompt_document_content = context_provider.get_typed_object_or_attribute(
+ name=doc_ref.variable_path,
+ wanted_type=DocumentContent,
+ accept_list=True,
+ )
+ if isinstance(prompt_document_content, (list, tuple)):
+ document_items = cast("list[Any] | tuple[Any, ...]", prompt_document_content)
+ for doc_index, doc_item in enumerate(document_items, start=1):
+ if not isinstance(doc_item, DocumentContent):
+ msg = f"Item of '{doc_ref.variable_path}' is of type '{type(doc_item).__name__}', expected DocumentContent"
+ raise PromptContentError(msg)
+ user_document = PromptDocumentFactory.make_prompt_document(
+ uri=doc_item.url,
+ mime_type=doc_item.mime_type,
+ )
+ user_document_item_name = f"{doc_ref.variable_path}[{doc_index}]"
+ prompt_user_documents[user_document_item_name] = user_document
+ else:
+ msg = (
+ f"Document list reference '{doc_ref.variable_path}' is of type '{type(prompt_document_content).__name__}', "
+ "expected list or tuple of DocumentContent"
+ )
+ raise PromptContentError(msg)
+ except ContextProviderError as exc:
+ msg = f"Could not find document list '{doc_ref.variable_path}' in context: {exc}"
+ raise PromptContentError(msg) from exc
+
+
+async def _unravel_text(
+ *,
+ context_provider: ContextProviderAbstract,
+ jinja2_blueprint: TemplateBlueprint,
+ extra_params: dict[str, Any] | None = None,
+ image_registry: ImageRegistry | None = None,
+ templating_style: TemplatingStyle | None = None,
+) -> str:
+ # A style declared on the blueprint wins over the run-derived one. Kept as a local: writing
+ # it onto `jinja2_blueprint` would mutate an object the pipe library holds and hands out.
+ effective_style = jinja2_blueprint.templating_style or templating_style
+ log.verbose(f"Rendering with prompting style {effective_style}")
+
+ context: dict[str, Any] = context_provider.generate_context()
+ if extra_params:
+ context = substitute_nested_in_context(context=context, extra_params=extra_params)
+ if jinja2_blueprint.extra_context:
+ context.update(**jinja2_blueprint.extra_context)
+
+ # Add image registry to context for | with_images and | format filters
+ if image_registry is not None:
+ context[Jinja2ContextKey.IMAGE_REGISTRY] = image_registry
+
+ finalize = image_registry.make_finalize() if image_registry and image_registry.images else None
+
+ return await render_template(
+ template=jinja2_blueprint.template,
+ category=jinja2_blueprint.category,
+ context=context,
+ templating_style=effective_style,
+ finalize=finalize,
+ )
diff --git a/pipelex/kernel/llm_results.py b/pipelex/kernel/llm_results.py
new file mode 100644
index 000000000..2df6462b6
--- /dev/null
+++ b/pipelex/kernel/llm_results.py
@@ -0,0 +1,63 @@
+"""What a kernel LLM call hands back.
+
+More than the produced value, because the interpreter's execution-graph tracer consumes the
+intermediates — the rendered prompts, the resolved model setting, the structuring path — and
+recomputing them outside the kernel would mean a second assembly path, which is the drift this
+extraction exists to kill.
+
+The memory contract, restated where callers meet it: **the returned `memory` is the result.** A
+kernel call may mutate the memory it was passed, and today inline execution aliases the two — but a
+serialization boundary will not, so no caller may rely on the argument having been updated.
+
+**Serializing a result: use `kajson`, not `model_dump()`.** `content` is annotated with the base
+`StuffContent`, so a plain `model_dump()` drops the concrete subclass's fields — `NumberContent(number=3)`
+dumps as `{}`. That is not specific to this model: `Stuff.content` is annotated the same way and behaves
+the same way, and the project's answer at both sites is the same one — `kajson` records the class and
+reconstructs it, and `model_dump(serialize_as_any=True)` is the escape hatch for a one-off dump. Nothing
+serializes these results today (the interpreter unwraps them inline), so this is a note for the
+programmatic caller, not a description of a live path.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from pipelex.cogt.llm.llm_prompt import LLMPrompt
+from pipelex.cogt.llm.llm_setting import LLMSetting
+from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.stuffs.stuff_content import StuffContent
+
+
+class StructuringPath(StrEnum):
+ """How the output was produced — the tracer's vocabulary, owned here rather than at each caller."""
+
+ TEXT = "text"
+ OBJECT_DIRECT = "object_direct"
+ OBJECT_LIST = "object_list"
+
+
+class LlmTextResult(BaseModel):
+ """The outcome of a kernel LLM call with a text output."""
+
+ model_config = ConfigDict(frozen=True)
+
+ memory: WorkingMemory
+ text: str
+ rendered_prompt: LLMPrompt
+ llm_setting: LLMSetting
+ structuring_path: StructuringPath
+
+
+class LlmObjectResult(BaseModel):
+ """The outcome of a kernel LLM call with a structured output.
+
+ `content` is the generated object, or a `ListContent` of them when several were requested.
+ """
+
+ model_config = ConfigDict(frozen=True)
+
+ memory: WorkingMemory
+ content: StuffContent
+ rendered_prompt: LLMPrompt
+ llm_setting: LLMSetting
+ structuring_path: StructuringPath
diff --git a/pipelex/kernel/pipelex_kernel.py b/pipelex/kernel/pipelex_kernel.py
new file mode 100644
index 000000000..97bac6c48
--- /dev/null
+++ b/pipelex/kernel/pipelex_kernel.py
@@ -0,0 +1,163 @@
+"""The kernel façade: per-run state, so a caller does not thread it through every call.
+
+The semantics live in the module-level ops functions beside this one; the interpreter's operator
+classes call those directly, because they already hold everything the façade would supply. This
+class exists for the *other* caller — the programmatic one, embedding the runtime — and it holds
+exactly two things, both of them run-scoped identity:
+
+- ``job_metadata`` — the **run-level** metadata. It is not what a step runs under: each call mints
+ a per-step copy via :meth:`make_step_metadata`, mirroring the interpreter's pass-down-a-modified-copy
+ pattern, so trace and usage attribution stay per-step.
+- ``cogt_run_params`` — the execution-mode contract (``run_mode``, ``is_mock_usage``) every cogt
+ leaf reads off the assignment it is handed.
+
+What it deliberately does **not** hold is anything derived from config or the model deck — resolved
+LLM settings, prompting style. Those are computed per call and never cached here, exactly as
+``pipe_llm.py`` derives them per run today: cached derived state is hidden shared state, it makes a
+later config or deck change invisible to a live kernel, and it breaks per-call variation.
+"""
+
+from typing import Self
+from uuid import uuid4
+
+from pipelex.cogt.content_generation.cogt_run_params import CogtRunParams
+from pipelex.cogt.llm.llm_setting import LLMModelChoice
+from pipelex.core.concepts.concept import Concept
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.kernel.llm_ops import (
+ derive_templating_style,
+ resolve_llm_setting_for_object,
+ resolve_llm_setting_for_text,
+ run_llm_object,
+ run_llm_text,
+)
+from pipelex.kernel.llm_prompt_content import LlmPromptContent
+from pipelex.kernel.llm_results import LlmObjectResult, LlmTextResult
+from pipelex.runtime_hub import resolve_run_mode_for_boot
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
+class PipelexKernel:
+ """Façade over the module-level kernel ops; holds per-run state."""
+
+ def __init__(self, *, job_metadata: JobMetadata, cogt_run_params: CogtRunParams) -> None:
+ self.job_metadata = job_metadata
+ self.cogt_run_params = cogt_run_params
+
+ @classmethod
+ def make(cls, *, run_mode: PipeRunMode = PipeRunMode.LIVE, user_id: str) -> Self:
+ """Mint a kernel for one run: a fresh run id, and the execution-mode contract for it.
+
+ This is a run-params factory, so it owes the same keyless-boot contract as the pipe tier's:
+ a process booted with ``needs_inference=False`` forces every run it initiates to DRY, and a
+ kernel that skipped that would spend real money on the exact boot this package documents as
+ its target. Applied through the shared ``resolve_run_mode_for_boot`` — a second copy of the
+ rule at a second factory is how the two would drift.
+ """
+ return cls(
+ job_metadata=JobMetadata(user_id=user_id, pipeline_run_id=str(uuid4())),
+ cogt_run_params=CogtRunParams(run_mode=resolve_run_mode_for_boot(requested=run_mode)),
+ )
+
+ def make_step_metadata(self) -> JobMetadata:
+ """A per-step copy of the run-level metadata, carrying its own ``pipe_run_id``.
+
+ ``otel_context`` is passed explicitly as ``None`` rather than left to inherit, which is the
+ contract ``copy_with_update`` states: the field is computed fresh per step by whoever opens
+ the span, and a kernel call opens none. Span and trace-context wiring for a kernel-driven
+ run is a separate concern from minting the identity, and is not wired here.
+ """
+ return self.job_metadata.copy_with_update(otel_context=None, pipe_run_id=str(uuid4()))
+
+ async def llm_text(
+ self,
+ *,
+ memory: WorkingMemory,
+ model: LLMModelChoice | None = None,
+ user: str,
+ system: str | None = None,
+ concept: Concept | None = None,
+ output_class: type[StuffContent] | None = None,
+ result: str,
+ ) -> LlmTextResult:
+ """The semantics of an LLM step with a Text output.
+
+ `user` and `system` are Jinja2 templates rendered against `memory`; the result carries the
+ returned memory plus the rendered prompts and the resolved setting. Images and documents
+ enter a prompt through references, which this convenience form has none of — build an
+ `LlmPromptContent` and call `run_llm_text` directly for those.
+
+ `concept`, `output_class` and `model` are optional and default to what this method used to
+ hardcode — native `Text`, `TextContent`, and the deck's own choice. They are parameters
+ because the op beneath takes them and the interpreter passes all three: a caller producing a
+ concept that *refines* native `Text` must be able to store the declared concept and its
+ generated class, or the memory it hands back differs from an interpreted run's for the same
+ step and anything reading the result back raises `StuffContentTypeError`. Omitting `model`
+ is the ordinary authored case, not an edge one — it defers to the deck exactly as a `$preset`
+ does. `llm_object` below has taken all three from the start; this is the same convenience.
+ """
+ llm_setting = resolve_llm_setting_for_text(llm_choice=model)
+ return await run_llm_text(
+ memory=memory,
+ prompt_content=LlmPromptContent.make_from_text(user=user, system=system),
+ llm_setting=llm_setting,
+ concept=concept or ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT),
+ output_class=output_class or TextContent,
+ job_metadata=self.make_step_metadata(),
+ cogt_run_params=self.cogt_run_params,
+ templating_style=derive_templating_style(llm_setting=llm_setting),
+ result_name=result,
+ )
+
+ async def llm_object(
+ self,
+ *,
+ memory: WorkingMemory,
+ output_class: type[StuffContent],
+ concept: Concept,
+ model: LLMModelChoice,
+ user: str,
+ system: str | None = None,
+ structure_prompt: str | None = None,
+ result: str,
+ is_multiple_output: bool = False,
+ fixed_nb_output: int | None = None,
+ ) -> LlmObjectResult:
+ """The semantics of an LLM step with a structured output.
+
+ The concrete pydantic class is handed over directly — no registry lookup, and no runtime
+ schema-to-class reconstruction, because the class exists. The structure prompt is derived
+ from `output_class` by default; pass `structure_prompt` to override it. As with `llm_text`,
+ prompts carrying image or document references go through `run_llm_object` directly.
+
+ **One `model`, and it carries the interpreter's *text*-choice semantics for templating.** A
+ `PipeLLM` can name two models (`model` → for_text, `model_to_structure` → for_object) and
+ derives the prompting style from the text one. Here the single explicit choice wins
+ `resolve_llm_setting_for_object`'s first rung, so the style comes from that same setting —
+ which is what an interpreted run derives for a pipe naming only a text model. The two agree
+ for every call this form can express; a pipe naming *both* is what it cannot express, and
+ that is deliberate. Do not "fix" this by deriving the style from an object-only resolution:
+ that would introduce the divergence rather than close it. The whole model-derived-style
+ mechanism is slated for replacement by an explicit caller-chosen style — see
+ `wip/prompting-style/README.md`.
+ """
+ llm_setting = resolve_llm_setting_for_object(llm_choice=model)
+ return await run_llm_object(
+ memory=memory,
+ prompt_content=LlmPromptContent.make_from_text(user=user, system=system),
+ llm_setting=llm_setting,
+ concept=concept,
+ output_class=output_class,
+ job_metadata=self.make_step_metadata(),
+ cogt_run_params=self.cogt_run_params,
+ structure_prompt=structure_prompt,
+ is_multiple_output=is_multiple_output,
+ fixed_nb_output=fixed_nb_output,
+ templating_style=derive_templating_style(llm_setting=llm_setting),
+ result_name=result,
+ )
diff --git a/pipelex/pipe_operators/shared/image_reference.py b/pipelex/kernel/prompt_references.py
similarity index 50%
rename from pipelex/pipe_operators/shared/image_reference.py
rename to pipelex/kernel/prompt_references.py
index 13b7c81d3..9af4077ad 100644
--- a/pipelex/pipe_operators/shared/image_reference.py
+++ b/pipelex/kernel/prompt_references.py
@@ -1,7 +1,11 @@
-"""Data structures for representing image references in prompt templates.
+"""How a prompt names the images and documents it wants out of working memory.
-These models describe how images are referenced in templates and guide
-the image resolution process at runtime.
+These describe a *resolution* — "the variable at this path holds an `ImageContent`, fetch it and
+register it" — which is execution semantics, not language. They live here rather than under
+`pipe_operators/` because the kernel is what resolves them, and a runtime-layer module may not
+import an interpreter-layer one; the blueprints that parse `.mthds` into them import upward, which
+is the sanctioned direction. Same move `core/` made with `ConceptProviderAbstract`: the semantics
+migrate to the layer that owns them, and the language artifact keeps its parse-and-validate role.
"""
from enum import StrEnum
@@ -52,3 +56,34 @@ class ImageReference(BaseModel):
case ImageReferenceKind.NESTED:
nested_str = ", ".join(self.nested_image_paths or [])
return f"ImageReference(NESTED: {self.variable_path} -> [{nested_str}])"
+
+
+class DocumentReferenceKind(StrEnum):
+ """The kind of document reference in a template."""
+
+ DIRECT = "direct"
+ """Direct reference to a DocumentContent variable, e.g., {{ report }}"""
+
+ DIRECT_LIST = "direct_list"
+ """Direct reference to a ListContent of DocumentContent, e.g., {{ documents }}"""
+
+
+class DocumentReference(BaseModel):
+ """Represents a document reference found in a template.
+
+ This model captures:
+ - The variable path referenced in the template
+ - The kind of reference (direct or list)
+ """
+
+ variable_path: str = Field(description="The variable path referenced in the template, e.g., 'report', 'submission.pdf', 'documents'")
+
+ kind: DocumentReferenceKind = Field(description="The kind of document reference")
+
+ @override
+ def __str__(self) -> str:
+ match self.kind:
+ case DocumentReferenceKind.DIRECT:
+ return f"DocumentReference(DIRECT: {self.variable_path})"
+ case DocumentReferenceKind.DIRECT_LIST:
+ return f"DocumentReference(DIRECT_LIST: {self.variable_path})"
diff --git a/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py b/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py
index 00f7f19d8..e975f882d 100644
--- a/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py
+++ b/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py
@@ -16,8 +16,8 @@ from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
from pipelex.cogt.templating.template_rendering import render_template
from pipelex.core.stuffs.image_content import ImageContent
+from pipelex.kernel.prompt_references import ImageReference, ImageReferenceKind
from pipelex.pipe_operators.img_gen.exceptions import PipeImgGenFactoryError
-from pipelex.pipe_operators.shared.image_reference import ImageReference, ImageReferenceKind
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
index 12057bfac..adf631124 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
@@ -14,7 +14,7 @@ from pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageA
from pipelex.tools.jinja2.template_category import TemplateCategory
if TYPE_CHECKING:
- from pipelex.pipe_operators.shared.image_reference import ImageReference
+ from pipelex.kernel.prompt_references import ImageReference
class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):
diff --git a/pipelex/pipe_operators/llm/document_reference.py b/pipelex/pipe_operators/llm/document_reference.py
deleted file mode 100644
index eede138e8..000000000
--- a/pipelex/pipe_operators/llm/document_reference.py
+++ /dev/null
@@ -1,41 +0,0 @@
-"""Data structures for representing document references in LLM prompt templates.
-
-These models describe how documents are referenced in templates and guide
-the document resolution process at runtime.
-"""
-
-from enum import StrEnum
-
-from pydantic import BaseModel, Field
-from typing_extensions import override
-
-
-class DocumentReferenceKind(StrEnum):
- """The kind of document reference in a template."""
-
- DIRECT = "direct"
- """Direct reference to a DocumentContent variable, e.g., {{ report }}"""
-
- DIRECT_LIST = "direct_list"
- """Direct reference to a ListContent of DocumentContent, e.g., {{ documents }}"""
-
-
-class DocumentReference(BaseModel):
- """Represents a document reference found in a template.
-
- This model captures:
- - The variable path referenced in the template
- - The kind of reference (direct or list)
- """
-
- variable_path: str = Field(description="The variable path referenced in the template, e.g., 'report', 'submission.pdf', 'documents'")
-
- kind: DocumentReferenceKind = Field(description="The kind of document reference")
-
- @override
- def __str__(self) -> str:
- match self.kind:
- case DocumentReferenceKind.DIRECT:
- return f"DocumentReference(DIRECT: {self.variable_path})"
- case DocumentReferenceKind.DIRECT_LIST:
- return f"DocumentReference(DIRECT_LIST: {self.variable_path})"
diff --git a/pipelex/pipe_operators/llm/exceptions.py b/pipelex/pipe_operators/llm/exceptions.py
index 039717bc2..3c1e19fa1 100644
--- a/pipelex/pipe_operators/llm/exceptions.py
+++ b/pipelex/pipe_operators/llm/exceptions.py
@@ -1,9 +1,5 @@
from pipelex.base_exceptions import PipelexError
-class LLMPromptBlueprintValueError(ValueError):
- pass
-
-
class PipeLLMFactoryError(PipelexError):
pass
diff --git a/pipelex/pipe_operators/llm/helpers.py b/pipelex/pipe_operators/llm/helpers.py
deleted file mode 100644
index 7dc01e821..000000000
--- a/pipelex/pipe_operators/llm/helpers.py
+++ /dev/null
@@ -1,30 +0,0 @@
-from pipelex.cogt.templating.template_rendering import render_template
-from pipelex.config import get_config
-from pipelex.core.stuffs.stuff_content import StuffContent
-from pipelex.interpreter_hub import get_required_concept
-from pipelex.runtime_hub import get_class_registry
-from pipelex.tools.jinja2.template_category import TemplateCategory
-from pipelex.tools.typing.structure_printer import StructurePrinter
-
-
-async def get_output_structure_prompt(concept_ref: str) -> str | None:
- concept = get_required_concept(concept_ref=concept_ref)
- output_class = get_class_registry().get_class(concept.structure_class_name)
- if not output_class:
- return None
-
- class_structure = StructurePrinter().get_type_structure(tp=output_class, base_class=StuffContent)
-
- if not class_structure:
- return None
- class_structure_str = "\n".join(class_structure)
- llm_config = get_config().cogt.llm_config
- template_source = llm_config.get_template(template_name="output_structure_prompt")
-
- return await render_template(
- template=template_source,
- category=TemplateCategory.LLM_PROMPT,
- context={
- "class_structure_str": class_structure_str,
- },
- )
diff --git a/pipelex/pipe_operators/llm/image_reference.py b/pipelex/pipe_operators/llm/image_reference.py
deleted file mode 100644
index 659139035..000000000
--- a/pipelex/pipe_operators/llm/image_reference.py
+++ /dev/null
@@ -1,10 +0,0 @@
-"""Backwards compatibility re-exports for image reference types.
-
-These types have been moved to pipelex.pipe_operators.shared.image_reference.
-This module re-exports them for backwards compatibility.
-"""
-
-# Re-export from shared module for backwards compatibility
-from pipelex.pipe_operators.shared.image_reference import ImageReference, ImageReferenceKind
-
-__all__ = ["ImageReference", "ImageReferenceKind"]
diff --git a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
index 21ee33cc2..642b2e994 100644
--- a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
+++ b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
@@ -1,32 +1,26 @@
-from typing import TYPE_CHECKING, Any, cast
+from typing import Any
from pydantic import BaseModel
from pipelex import log
-from pipelex.cogt.document.prompt_document import PromptDocument
-from pipelex.cogt.document.prompt_document_factory import PromptDocumentFactory
-from pipelex.cogt.image.prompt_image_factory import PromptImageFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_rendering import render_template
-from pipelex.core.stuffs.document_content import DocumentContent
-from pipelex.core.stuffs.image_content import ImageContent
-from pipelex.pipe_operators.llm.document_reference import DocumentReference, DocumentReferenceKind
-from pipelex.pipe_operators.llm.exceptions import LLMPromptBlueprintValueError
-from pipelex.pipe_operators.llm.image_reference import ImageReference, ImageReferenceKind
-from pipelex.tools.jinja2.image_registry import ImageRegistry
-from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.kernel.llm_prompt_content import LlmPromptContent, assemble_llm_prompt
+from pipelex.kernel.prompt_references import DocumentReference, ImageReference
from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract
-from pipelex.tools.misc.dict_utils import substitute_nested_in_context
-from pipelex.tools.misc.exceptions import ContextProviderError
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
from pipelex.tools.templating.templating_style import TemplatingStyle
-if TYPE_CHECKING:
- from pipelex.cogt.image.prompt_image import PromptImage
-
class LLMPromptBlueprint(BaseModel):
+ """The parsed form of a PipeLLM's prompt: what `.mthds` declares, before anything is rendered.
+
+ A language artifact — it parses and validates, and it answers which variables a pipe's prompt
+ needs, which is what static input checking runs on. Assembling an actual prompt is execution
+ semantics and lives in the kernel, so this maps down onto `LlmPromptContent` rather than holding
+ a second implementation of it.
+ """
+
system_prompt_blueprint: TemplateBlueprint | None = None
prompt_blueprint: TemplateBlueprint | None = None
user_image_references: list[ImageReference] | None = None
@@ -55,8 +49,17 @@ class LLMPromptBlueprint(BaseModel):
required_variables.update(get_root_from_dotted_path(path) for path in self.system_prompt_blueprint.required_variables())
return {variable_name for variable_name in required_variables if not variable_name.startswith("_") and variable_name != "place_holder"}
- # TODO: make this consistent with `LLMPromptFactoryAbstract` or `LLMPromptTemplate`,
- # let's get back to it when we have a better solution for structuring_method
+ def to_prompt_content(self) -> LlmPromptContent:
+ """The kernel-side view of this blueprint — the same content, addressed by what it does at run time."""
+ return LlmPromptContent(
+ user_template=self.prompt_blueprint,
+ system_template=self.system_prompt_blueprint,
+ user_image_references=self.user_image_references,
+ user_document_references=self.user_document_references,
+ system_image_references=self.system_image_references,
+ system_document_references=self.system_document_references,
+ )
+
async def make_llm_prompt(
self,
*,
@@ -66,396 +69,12 @@ class LLMPromptBlueprint(BaseModel):
extra_params: dict[str, Any] | None = None,
templating_style: TemplatingStyle | None = None,
) -> LLMPrompt:
- ############################################################
- # Image Registry and Direct Image Extraction
- # Extract system prompt images FIRST, then user prompt images
- ############################################################
- image_registry = ImageRegistry()
- # Maps image variable name to its 0-based registry index (for placeholder generation)
- image_registry_indices: dict[str, int] = {}
- # Track which variable paths are lists, so we can substitute the whole list
- list_image_refs: list[ImageReference] = []
-
- # Process system prompt image references first (so they get lower numbers)
- if self.system_image_references:
- for image_ref in self.system_image_references:
- match image_ref.kind:
- case ImageReferenceKind.DIRECT:
- self._extract_direct_image(
- image_ref=image_ref,
- context_provider=context_provider,
- image_registry=image_registry,
- image_registry_indices=image_registry_indices,
- )
- case ImageReferenceKind.DIRECT_LIST:
- self._extract_direct_list_images(
- image_ref=image_ref,
- context_provider=context_provider,
- image_registry=image_registry,
- image_registry_indices=image_registry_indices,
- )
- list_image_refs.append(image_ref)
- case ImageReferenceKind.NESTED:
- # Nested images will be extracted by the | with_images filter
- # during template rendering - the registry is passed in context
- pass
-
- # Process user prompt image references (DIRECT and DIRECT_LIST kinds)
- if self.user_image_references:
- for image_ref in self.user_image_references:
- match image_ref.kind:
- case ImageReferenceKind.DIRECT:
- # Single ImageContent reference
- self._extract_direct_image(
- image_ref=image_ref,
- context_provider=context_provider,
- image_registry=image_registry,
- image_registry_indices=image_registry_indices,
- )
- case ImageReferenceKind.DIRECT_LIST:
- # List of ImageContent reference
- self._extract_direct_list_images(
- image_ref=image_ref,
- context_provider=context_provider,
- image_registry=image_registry,
- image_registry_indices=image_registry_indices,
- )
- list_image_refs.append(image_ref)
- case ImageReferenceKind.NESTED:
- # Nested images will be extracted by the | with_images filter
- # during template rendering - the registry is passed in context
- pass
-
- ############################################################
- # Direct Document Extraction
- # Extract system prompt documents FIRST, then user prompt documents
- ############################################################
- prompt_user_documents: dict[str, PromptDocument] = {}
- list_document_refs: list[DocumentReference] = []
-
- # Process system prompt document references first (so they get lower numbers)
- if self.system_document_references:
- for doc_ref in self.system_document_references:
- match doc_ref.kind:
- case DocumentReferenceKind.DIRECT:
- self._extract_direct_document(
- doc_ref=doc_ref,
- context_provider=context_provider,
- prompt_user_documents=prompt_user_documents,
- )
- case DocumentReferenceKind.DIRECT_LIST:
- self._extract_direct_list_documents(
- doc_ref=doc_ref,
- context_provider=context_provider,
- prompt_user_documents=prompt_user_documents,
- )
- list_document_refs.append(doc_ref)
-
- # Process user prompt document references
- if self.user_document_references:
- for doc_ref in self.user_document_references:
- match doc_ref.kind:
- case DocumentReferenceKind.DIRECT:
- self._extract_direct_document(
- doc_ref=doc_ref,
- context_provider=context_provider,
- prompt_user_documents=prompt_user_documents,
- )
- case DocumentReferenceKind.DIRECT_LIST:
- self._extract_direct_list_documents(
- doc_ref=doc_ref,
- context_provider=context_provider,
- prompt_user_documents=prompt_user_documents,
- )
- list_document_refs.append(doc_ref)
-
- ############################################################
- # User text
- ############################################################
- # Add image placeholders to extra_params for substitution in template
- # - Direct images (non-dotted paths like "image"): add placeholder directly
- # - List images: add list variable with all tokens joined
- # - Dotted paths (e.g., "page.page_view"): handled by tag filter via ImageRegistry.get_image_placeholder()
- # because dotted paths cannot be substituted in immutable StuffArtefacts
- extra_params = extra_params or {}
- if image_registry_indices:
- # Collect list variable paths for exclusion from direct substitution
- list_variable_paths = {list_ref.variable_path for list_ref in list_image_refs}
-
- # Add placeholders for direct (non-dotted, non-list) images
- for image_name, registry_index in image_registry_indices.items():
- # Skip list item references (e.g., "images[1]")
- if "[" in image_name:
- continue
- # Skip dotted paths (e.g., "page.page_view") - handled by finalize/filter at render time
- if "." in image_name:
- continue
- # Skip list variable references (handled separately below)
- if image_name in list_variable_paths:
- continue
- # Add direct image placeholder
- extra_params[image_name] = f"[Image {registry_index + 1}]"
-
- # For list image references, substitute the list variable itself
- # with a string containing all the [Image N] tokens for items in that list
- for list_ref in list_image_refs:
- list_tokens: list[str] = []
- for image_name, registry_index in image_registry_indices.items():
- # Check if this image belongs to this list (e.g., "collection_a[1]" belongs to "collection_a")
- if image_name.startswith(f"{list_ref.variable_path}["):
- list_tokens.append(f"[Image {registry_index + 1}]")
- if list_tokens:
- extra_params[list_ref.variable_path] = ", ".join(list_tokens)
-
- # Replace direct document variables with numbered tags
- if prompt_user_documents:
- document_names = list(prompt_user_documents.keys())
- for document_index, document_name in enumerate(document_names):
- extra_params[document_name] = f"[Document {document_index + 1}]"
-
- # For list document references, also substitute the list variable itself
- for doc_list_ref in list_document_refs:
- doc_list_tokens: list[str] = []
- for document_name in document_names:
- if document_name.startswith(f"{doc_list_ref.variable_path}["):
- doc_list_tokens.append(extra_params[document_name])
- if doc_list_tokens:
- extra_params[doc_list_ref.variable_path] = "\n".join(doc_list_tokens)
-
- ############################################################
- # System text (rendered FIRST so nested images get lower numbers)
- ############################################################
- system_text: str | None = None
- if self.system_prompt_blueprint:
- system_text = await self._unravel_text(
- context_provider=context_provider,
- jinja2_blueprint=self.system_prompt_blueprint,
- extra_params=extra_params,
- image_registry=image_registry,
- templating_style=templating_style,
- )
-
- ############################################################
- # User text (rendered AFTER system text for consistent image ordering)
- ############################################################
- user_text: str | None = None
- if self.prompt_blueprint:
- user_text = await self._unravel_text(
- context_provider=context_provider,
- jinja2_blueprint=self.prompt_blueprint,
- extra_params=extra_params,
- image_registry=image_registry,
- templating_style=templating_style,
- )
- if output_structure_prompt:
- user_text += output_structure_prompt
- else:
- user_text = output_structure_prompt
- # Note that output_structure_prompt can be None
- # it's OK to have a null user_text
-
- log.verbose(f"User text with {output_concept_ref=}:\n {user_text}")
-
- ############################################################
- # Collect all images from registry (single source of truth)
- ############################################################
- # The registry contains all images (direct + nested) in the correct order,
- # already deduplicated by URL. This ensures [Image N] tokens match positions.
- all_images: list[PromptImage] = [PromptImageFactory.make_prompt_image(uri=registry_image.url) for registry_image in image_registry.images]
-
- ############################################################
- # Collect all documents
- ############################################################
- all_documents: list[PromptDocument] = list(prompt_user_documents.values())
-
- ############################################################
- # Full LLMPrompt
- ############################################################
- return LLMPrompt(
- system_text=system_text,
- user_text=user_text,
- user_images=all_images,
- user_documents=all_documents,
+ llm_prompt = await assemble_llm_prompt(
+ prompt_content=self.to_prompt_content(),
+ context_provider=context_provider,
+ output_structure_prompt=output_structure_prompt,
+ extra_params=extra_params,
+ templating_style=templating_style,
)
-
- def _extract_direct_image(
- self,
- image_ref: ImageReference,
- *,
- context_provider: ContextProviderAbstract,
- image_registry: ImageRegistry,
- image_registry_indices: dict[str, int],
- ) -> None:
- """Extract a single ImageContent from context and register it."""
- log.verbose(f"Getting direct image '{image_ref.variable_path}' from context")
- try:
- prompt_image_content = context_provider.get_typed_object_or_attribute(
- name=image_ref.variable_path,
- wanted_type=ImageContent,
- accept_list=False,
- )
- if isinstance(prompt_image_content, ImageContent):
- registry_index = image_registry.register_image(prompt_image_content)
- image_registry_indices[image_ref.variable_path] = registry_index
- else:
- msg = f"Image reference '{image_ref.variable_path}' is of type '{type(prompt_image_content).__name__}', expected ImageContent"
- raise LLMPromptBlueprintValueError(msg)
- except ContextProviderError as exc:
- msg = f"Could not find image '{image_ref.variable_path}' in context: {exc}"
- raise LLMPromptBlueprintValueError(msg) from exc
-
- def _extract_direct_list_images(
- self,
- image_ref: ImageReference,
- *,
- context_provider: ContextProviderAbstract,
- image_registry: ImageRegistry,
- image_registry_indices: dict[str, int],
- ) -> None:
- """Extract a list of ImageContent from context and register them."""
- log.verbose(f"Getting image list '{image_ref.variable_path}' from context")
- try:
- prompt_image_content = context_provider.get_typed_object_or_attribute(
- name=image_ref.variable_path,
- wanted_type=ImageContent,
- accept_list=True,
- )
- if isinstance(prompt_image_content, list):
- prompt_image_content = cast("list[Any]", prompt_image_content)
- for list_position, image_item in enumerate(prompt_image_content, start=1):
- if not isinstance(image_item, ImageContent):
- msg = f"Item of '{image_ref.variable_path}' is of type '{type(image_item).__name__}', expected ImageContent"
- raise LLMPromptBlueprintValueError(msg)
- registry_index = image_registry.register_image(image_item)
- # Use list position (1-based) for variable name, registry index for image number
- image_item_name = f"{image_ref.variable_path}[{list_position}]"
- image_registry_indices[image_item_name] = registry_index
- elif isinstance(prompt_image_content, tuple):
- content_tuple: tuple[Any, ...] = cast("tuple[Any, ...]", prompt_image_content)
- for list_position, image_item in enumerate(content_tuple, start=1):
- if not isinstance(image_item, ImageContent):
- msg = f"Item of '{image_ref.variable_path}' is of type '{type(image_item).__name__}', expected ImageContent"
- raise LLMPromptBlueprintValueError(msg)
- registry_index = image_registry.register_image(image_item)
- image_item_name = f"{image_ref.variable_path}[{list_position}]"
- image_registry_indices[image_item_name] = registry_index
- else:
- msg = (
- f"Image list reference '{image_ref.variable_path}' is of type '{type(prompt_image_content).__name__}', "
- "expected list or tuple of ImageContent"
- )
- raise LLMPromptBlueprintValueError(msg)
- except ContextProviderError as exc:
- msg = f"Could not find image list '{image_ref.variable_path}' in context: {exc}"
- raise LLMPromptBlueprintValueError(msg) from exc
-
- async def _unravel_text(
- self,
- *,
- context_provider: ContextProviderAbstract,
- jinja2_blueprint: TemplateBlueprint,
- extra_params: dict[str, Any] | None = None,
- image_registry: ImageRegistry | None = None,
- templating_style: TemplatingStyle | None = None,
- ) -> str:
- # A style declared on the blueprint wins over the run-derived one. Kept as a local: writing
- # it onto `jinja2_blueprint` would mutate an object the pipe library holds and hands out.
- effective_style = jinja2_blueprint.templating_style or templating_style
- log.verbose(f"Rendering with prompting style {effective_style}")
-
- context: dict[str, Any] = context_provider.generate_context()
- if extra_params:
- context = substitute_nested_in_context(context=context, extra_params=extra_params)
- if jinja2_blueprint.extra_context:
- context.update(**jinja2_blueprint.extra_context)
-
- # Add image registry to context for | with_images and | format filters
- if image_registry is not None:
- context[Jinja2ContextKey.IMAGE_REGISTRY] = image_registry
-
- finalize = image_registry.make_finalize() if image_registry and image_registry.images else None
-
- return await render_template(
- template=jinja2_blueprint.template,
- category=jinja2_blueprint.category,
- context=context,
- templating_style=effective_style,
- finalize=finalize,
- )
-
- def _extract_direct_document(
- self,
- doc_ref: DocumentReference,
- *,
- context_provider: ContextProviderAbstract,
- prompt_user_documents: dict[str, PromptDocument],
- ) -> None:
- """Extract a single DocumentContent from context."""
- log.verbose(f"Getting direct document '{doc_ref.variable_path}' from context")
- try:
- prompt_document_content = context_provider.get_typed_object_or_attribute(
- name=doc_ref.variable_path,
- wanted_type=DocumentContent,
- accept_list=False,
- )
- if isinstance(prompt_document_content, DocumentContent):
- user_document = PromptDocumentFactory.make_prompt_document(
- uri=prompt_document_content.url,
- mime_type=prompt_document_content.mime_type,
- )
- prompt_user_documents[doc_ref.variable_path] = user_document
- else:
- msg = f"Document reference '{doc_ref.variable_path}' is of type '{type(prompt_document_content).__name__}', expected DocumentContent"
- raise LLMPromptBlueprintValueError(msg)
- except ContextProviderError as exc:
- msg = f"Could not find document '{doc_ref.variable_path}' in context: {exc}"
- raise LLMPromptBlueprintValueError(msg) from exc
-
- def _extract_direct_list_documents(
- self,
- doc_ref: DocumentReference,
- *,
- context_provider: ContextProviderAbstract,
- prompt_user_documents: dict[str, PromptDocument],
- ) -> None:
- """Extract a list of DocumentContent from context."""
- log.verbose(f"Getting document list '{doc_ref.variable_path}' from context")
- try:
- prompt_document_content = context_provider.get_typed_object_or_attribute(
- name=doc_ref.variable_path,
- wanted_type=DocumentContent,
- accept_list=True,
- )
- if isinstance(prompt_document_content, list):
- prompt_document_content = cast("list[Any]", prompt_document_content)
- for doc_index, doc_item in enumerate(prompt_document_content, start=1):
- if not isinstance(doc_item, DocumentContent):
- msg = f"Item of '{doc_ref.variable_path}' is of type '{type(doc_item).__name__}', expected DocumentContent"
- raise LLMPromptBlueprintValueError(msg)
- user_document = PromptDocumentFactory.make_prompt_document(
- uri=doc_item.url,
- mime_type=doc_item.mime_type,
- )
- user_document_item_name = f"{doc_ref.variable_path}[{doc_index}]"
- prompt_user_documents[user_document_item_name] = user_document
- elif isinstance(prompt_document_content, tuple):
- content_tuple: tuple[Any, ...] = cast("tuple[Any, ...]", prompt_document_content)
- for doc_index, doc_item in enumerate(content_tuple, start=1):
- if not isinstance(doc_item, DocumentContent):
- msg = f"Item of '{doc_ref.variable_path}' is of type '{type(doc_item).__name__}', expected DocumentContent"
- raise LLMPromptBlueprintValueError(msg)
- user_document = PromptDocumentFactory.make_prompt_document(
- uri=doc_item.url,
- mime_type=doc_item.mime_type,
- )
- user_document_item_name = f"{doc_ref.variable_path}[{doc_index}]"
- prompt_user_documents[user_document_item_name] = user_document
- else:
- msg = (
- f"Document list reference '{doc_ref.variable_path}' is of type '{type(prompt_document_content).__name__}', "
- "expected list or tuple of DocumentContent"
- )
- raise LLMPromptBlueprintValueError(msg)
- except ContextProviderError as exc:
- msg = f"Could not find document list '{doc_ref.variable_path}' in context: {exc}"
- raise LLMPromptBlueprintValueError(msg) from exc
+ log.verbose(f"User text with {output_concept_ref=}:\n {llm_prompt.user_text}")
+ return llm_prompt
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index 205ab76cc..2ec6f601f 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -5,13 +5,9 @@ from typing_extensions import override
from pipelex import log
from pipelex.base_exceptions import iter_cause_chain
-from pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocol
from pipelex.cogt.exceptions import LLMCompletionError
-from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting, LLMSettingChoices
-from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.models.model_deck_check import check_llm_choice_with_deck
-from pipelex.config import get_config
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.domains.domain import SpecialDomain
@@ -22,26 +18,31 @@ from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsF
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
-from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_content import StuffContent
-from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept
+from pipelex.kernel.llm_ops import (
+ derive_templating_style,
+ resolve_llm_setting_for_object,
+ resolve_llm_setting_for_text,
+ run_llm_object,
+ run_llm_text,
+)
from pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guards
from pipelex.pipe_machinery.validation import is_input_used_by_variables, is_variable_satisfied_by_inputs
-from pipelex.pipe_operators.llm.helpers import get_output_structure_prompt
from pipelex.pipe_operators.llm.llm_prompt_blueprint import LLMPromptBlueprint
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import (
PipeRunParams,
output_multiplicity_to_apply,
)
-from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_param_key import PipeRunParamKey
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
if TYPE_CHECKING:
- from pipelex.tools.templating.templating_style import TemplatingStyle
+ from pipelex.cogt.llm.llm_prompt import LLMPrompt
+ from pipelex.kernel.llm_results import StructuringPath
class PipeLLMOutput(PipeOutput):
@@ -190,7 +191,6 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
pipe_run_params: PipeRunParams,
output_name: str | None = None,
) -> PipeLLMOutput:
- content_generator = get_content_generator()
# interpret / unwrap the arguments
output_stuff_spec = self.resolve_dynamic_output_stuff_spec(pipe_run_params=pipe_run_params)
@@ -209,43 +209,36 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
llm_for_text_choice = self.llm_choices.for_text
llm_for_object_choice = self.llm_choices.for_object
- model_deck = get_model_deck()
-
- # Choice of main LLM for text first from this PipeLLM setting (self.llm_choices)
- # or from the llm_choice_overrides or fallback on the llm_choice_defaults
- llm_setting_or_preset_id_for_text: LLMModelChoice = (
- llm_for_text_choice or model_deck.llm_choice_overrides.for_text or model_deck.llm_choice_defaults.for_text
- )
- llm_setting_main: LLMSetting = model_deck.get_llm_setting(llm_choice=llm_setting_or_preset_id_for_text)
-
- # Choice of main LLM for object from this PipeLLM setting (self.llm_choices)
- # OR FROM THE llm_for_text_choice (if any)
- # then fallback on the llm_choice_overrides or llm_choice_defaults
- llm_setting_or_preset_id_for_object: LLMModelChoice = (
- llm_for_object_choice or llm_for_text_choice or model_deck.llm_choice_overrides.for_object or model_deck.llm_choice_defaults.for_object
+ # The deck chain and the style derivation are kernel semantics; the settings are derived per
+ # run into locals and never cached onto `self`, because the pipe instance is the one the
+ # library holds and hands out — a write-back would make its serialized form depend on run
+ # order and shadow any later config/deck change with the first run's value.
+ llm_setting_main: LLMSetting = resolve_llm_setting_for_text(llm_choice=llm_for_text_choice)
+ llm_setting_for_object: LLMSetting = resolve_llm_setting_for_object(
+ llm_choice=llm_for_object_choice,
+ llm_choice_for_text=llm_for_text_choice,
)
- llm_setting_for_object: LLMSetting = model_deck.get_llm_setting(llm_choice=llm_setting_or_preset_id_for_object)
-
- # Derived per run into a local, never cached onto `self`: the pipe instance is the one the
- # library holds and hands out, so a write-back here would make its serialized form depend on
- # run order and would shadow any later config/deck change with the first run's value.
- templating_style: TemplatingStyle | None = None
- if inference_model := model_deck.get_optional_inference_model(model_handle=llm_setting_main.model, model_type=ModelType.LLM):
- # Note: the case where we don't get an inference model corresponds to the use of an external LLM plugin
- # TODO: improve this by making it possible to get the inference model for external LLM plugins
- prompting_target = llm_setting_main.prompting_target or inference_model.prompting_target
- templating_style = get_config().pipelex.prompting_config.get_prompting_style(
- prompting_target=prompting_target,
- )
+ # Both paths render under the *text* setting's style: it is the pipe's main model, and the
+ # object path differs only in how the answer comes back, not in how the prompt is written.
+ templating_style = derive_templating_style(llm_setting=llm_setting_main)
llm_prompt_run_params = PipeRunParams.copy_by_injecting_multiplicity(
pipe_run_params=pipe_run_params,
applied_output_multiplicity=applied_output_multiplicity,
)
- the_content: StuffContent
- rendered_llm_prompt: LLMPrompt | None = None
+ # Resolved here rather than inside the kernel: turning a concept into a class is a library's
+ # business, and handing the class over is what spares the kernel a registry read.
+ output_class = get_class_registry().get_required_subclass(
+ name=output_stuff_spec.concept.structure_class_name,
+ base_class=StuffContent,
+ )
+ prompt_content = self.llm_prompt_spec.to_prompt_content()
+ rendered_llm_prompt: LLMPrompt
+ structuring_path: StructuringPath
+ # The library-backed text-vs-object dispatch stays here: the kernel's two entry points are
+ # this fork made explicit, and answering it needs a loaded library.
if (
get_concept_library().is_compatible(
tested_concept=output_stuff_spec.concept,
@@ -254,99 +247,74 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
)
and not is_multiple_output
):
- llm_prompt_1_for_text = await self.llm_prompt_spec.make_llm_prompt(
- output_concept_ref=output_stuff_spec.concept.concept_ref,
- context_provider=working_memory,
- output_structure_prompt=None,
- extra_params=llm_prompt_run_params.params,
- templating_style=templating_style,
- )
- rendered_llm_prompt = llm_prompt_1_for_text
try:
- generated_text: str = await content_generator.make_llm_text(
+ text_result = await run_llm_text(
+ memory=working_memory,
+ prompt_content=prompt_content,
+ llm_setting=llm_setting_main,
+ concept=output_stuff_spec.concept,
+ output_class=output_class,
job_metadata=job_metadata,
cogt_run_params=pipe_run_params.cogt_run_params,
- llm_prompt_for_text=llm_prompt_1_for_text,
- llm_setting_main=llm_setting_main,
+ templating_style=templating_style,
+ extra_params=llm_prompt_run_params.params,
+ result_name=output_name,
+ result_code=pipe_run_params.final_stuff_code,
)
except LLMCompletionError as exc:
location = self._format_error_location(pipe_run_params=pipe_run_params)
error_details = self._format_llm_error(exc=exc, settings=[llm_setting_main])
msg = f"Error generating text with LLM {location}: {error_details}"
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
-
- structure_class = get_class_registry().get_required_subclass(
- name=output_stuff_spec.concept.structure_class_name,
- base_class=StuffContent,
- )
-
- try:
- the_content = structure_class(
- text=generated_text,
- )
except ValidationError as exc:
location = self._format_error_location(pipe_run_params=pipe_run_params)
error_details = format_pydantic_validation_error(exc)
msg = f"Error generating text content in PipeLLM {location}: {error_details}"
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
+ working_memory = text_result.memory
+ rendered_llm_prompt = text_result.rendered_prompt
+ structuring_path = text_result.structuring_path
else:
if is_multiple_output:
log.verbose(f"PipeLLM generating {fixed_nb_output} output(s)" if fixed_nb_output else "PipeLLM generating a list of output(s)")
else:
log.verbose(f"PipeLLM generating a single object output, class name: '{output_stuff_spec.concept.structure_class_name}'")
- output_structure_prompt: str | None = None
- if get_config().cogt.llm_config.is_structure_prompt_enabled:
- output_structure_prompt = await get_output_structure_prompt(
- concept_ref=output_stuff_spec.concept.concept_ref,
+ try:
+ object_result = await run_llm_object(
+ memory=working_memory,
+ prompt_content=prompt_content,
+ llm_setting=llm_setting_for_object,
+ concept=output_stuff_spec.concept,
+ output_class=output_class,
+ job_metadata=job_metadata,
+ cogt_run_params=pipe_run_params.cogt_run_params,
+ is_multiple_output=is_multiple_output,
+ fixed_nb_output=fixed_nb_output,
+ templating_style=templating_style,
+ extra_params=llm_prompt_run_params.params,
+ result_name=output_name,
+ result_code=pipe_run_params.final_stuff_code,
)
- llm_prompt_for_object = await self.llm_prompt_spec.make_llm_prompt(
- output_concept_ref=output_stuff_spec.concept.concept_ref,
- context_provider=working_memory,
- output_structure_prompt=output_structure_prompt,
- extra_params=llm_prompt_run_params.params,
- templating_style=templating_style,
- )
- rendered_llm_prompt = llm_prompt_for_object
- the_content = await self._llm_gen_object_stuff_content(
- job_metadata=job_metadata,
- pipe_run_params=pipe_run_params,
- is_multiple_output=is_multiple_output,
- fixed_nb_output=fixed_nb_output,
- output_class_name=output_stuff_spec.concept.structure_class_name,
- llm_setting_for_object=llm_setting_for_object,
- llm_prompt_for_object=llm_prompt_for_object,
- content_generator=content_generator,
- )
-
- output_stuff = StuffFactory.make_stuff(
- name=output_name,
- concept=output_stuff_spec.concept,
- content=the_content,
- code=pipe_run_params.final_stuff_code,
- )
- working_memory.set_new_main_stuff(
- stuff=output_stuff,
- name=output_name,
- )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ error_details = self._format_llm_error(exc=exc, settings=[llm_setting_for_object])
+ what_failed = "list of objects" if is_multiple_output else "single object"
+ msg = f"Error generating {what_failed} with direct method {location}: {error_details}"
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
+ working_memory = object_result.memory
+ rendered_llm_prompt = object_result.rendered_prompt
+ structuring_path = object_result.structuring_path
# Capture execution data for the graph tracer
execution_data_dict: dict[str, Any] = {
"resolved_model": llm_setting_main.model,
"resolved_model_for_object": llm_setting_for_object.model,
"is_multiple_output": is_multiple_output,
+ "rendered_system_prompt": rendered_llm_prompt.system_text,
+ "rendered_user_prompt": rendered_llm_prompt.user_text,
+ "structuring_path": structuring_path,
}
- execution_data_dict["rendered_system_prompt"] = rendered_llm_prompt.system_text
- execution_data_dict["rendered_user_prompt"] = rendered_llm_prompt.user_text
- if is_multiple_output:
- execution_data_dict["structuring_path"] = "object_list"
- else:
- output_is_text = get_concept_library().is_compatible(
- tested_concept=output_stuff_spec.concept,
- wanted_concept=get_native_concept(NativeConceptCode.TEXT),
- strict=True,
- )
- execution_data_dict["structuring_path"] = "text" if output_is_text else "object_direct"
self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
return PipeLLMOutput(
@@ -354,59 +322,6 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
pipeline_run_id=job_metadata.pipeline_run_id,
)
- async def _llm_gen_object_stuff_content(
- self,
- *,
- job_metadata: JobMetadata,
- pipe_run_params: PipeRunParams,
- is_multiple_output: bool,
- fixed_nb_output: int | None,
- output_class_name: str,
- llm_setting_for_object: LLMSetting,
- llm_prompt_for_object: LLMPrompt,
- content_generator: ContentGeneratorProtocol,
- ) -> StuffContent:
- content_class: type[StuffContent] = get_class_registry().get_required_subclass(name=output_class_name, base_class=StuffContent)
-
- if is_multiple_output:
- if fixed_nb_output:
- task_desc = f"{self.__class__.__name__}_gen_{fixed_nb_output}x{content_class.__name__}"
- else:
- task_desc = f"{self.__class__.__name__}_gen_list_{content_class.__name__}"
- log.verbose(f"{task_desc} by object_direct")
- try:
- generated_objects = await content_generator.make_object_list(
- job_metadata=job_metadata,
- cogt_run_params=pipe_run_params.cogt_run_params,
- object_class=content_class,
- llm_prompt_for_object_list=llm_prompt_for_object,
- llm_setting_for_object_list=llm_setting_for_object,
- nb_items=fixed_nb_output,
- )
- except LLMCompletionError as exc:
- location = self._format_error_location(pipe_run_params=pipe_run_params)
- error_details = self._format_llm_error(exc=exc, settings=[llm_setting_for_object])
- msg = f"Error generating list of objects with direct method {location}: {error_details}"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
-
- return ListContent(items=generated_objects)
-
- task_desc = f"{self.__class__.__name__}_gen_single_{content_class.__name__}"
- log.verbose(f"{task_desc} by object_direct")
- try:
- return await content_generator.make_object(
- job_metadata=job_metadata,
- cogt_run_params=pipe_run_params.cogt_run_params,
- object_class=content_class,
- llm_prompt_for_object=llm_prompt_for_object,
- llm_setting_for_object=llm_setting_for_object,
- )
- except LLMCompletionError as exc:
- location = self._format_error_location(pipe_run_params=pipe_run_params)
- error_details = self._format_llm_error(exc=exc, settings=[llm_setting_for_object])
- msg = f"Error generating single object with direct method {location}: {error_details}"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
-
def _format_error_location(self, pipe_run_params: PipeRunParams) -> str:
return f"in pipe '{pipe_run_params.pipe_stack_str}'"
diff --git a/pipelex/pipe_operators/llm/template_document_analyzer.py b/pipelex/pipe_operators/llm/template_document_analyzer.py
index 50ad8d4b1..9a9df34f6 100644
--- a/pipelex/pipe_operators/llm/template_document_analyzer.py
+++ b/pipelex/pipe_operators/llm/template_document_analyzer.py
@@ -11,7 +11,7 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity
from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept
-from pipelex.pipe_operators.llm.document_reference import DocumentReference, DocumentReferenceKind
+from pipelex.kernel.prompt_references import DocumentReference, DocumentReferenceKind
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_variable_references
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
diff --git a/pipelex/pipe_operators/shared/template_image_analyzer.py b/pipelex/pipe_operators/shared/template_image_analyzer.py
index b92da98bd..efc0d6ffb 100644
--- a/pipelex/pipe_operators/shared/template_image_analyzer.py
+++ b/pipelex/pipe_operators/shared/template_image_analyzer.py
@@ -12,8 +12,8 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity
from pipelex.core.stuffs.image_field_search import search_for_nested_image_fields
from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept
+from pipelex.kernel.prompt_references import ImageReference, ImageReferenceKind
from pipelex.pipe_operators.shared.exceptions import UnusedInputError, WithImagesFilterError
-from pipelex.pipe_operators.shared.image_reference import ImageReference, ImageReferenceKind
from pipelex.tools.jinja2.jinja2_models import Jinja2FilterName
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_variable_references
from pipelex.tools.jinja2.template_category import TemplateCategory
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index e8541b99e..e1157e587 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -16,14 +16,12 @@ from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
-from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_content import StuffContent
-from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.interpreter_hub import get_concept_library, get_native_concept
-from pipelex.pipe_operators.llm.helpers import get_output_structure_prompt
+from pipelex.kernel.llm_ops import derive_structure_prompt, generate_object_content, resolve_llm_setting_for_object, store_result
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_to_apply
-from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.template_category import TemplateCategory
@@ -104,8 +102,6 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
pipe_run_params: PipeRunParams,
output_name: str | None = None,
) -> PipeStructureOutput:
- content_generator = get_content_generator()
-
text_str = working_memory.get_stuff_as_str(name=self.text_input_name)
# Resolve list-vs-single from base + override.
@@ -116,14 +112,13 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
is_multiple_output = multiplicity_resolution.is_multiple_outputs_enabled
fixed_nb_output = multiplicity_resolution.specific_output_count
- # LLM choice: explicit on the pipe → for_object override → for_object default.
- model_deck = get_model_deck()
- llm_choice_for_object: LLMModelChoice = (
- self.llm_choice or model_deck.llm_choice_overrides.for_object or model_deck.llm_choice_defaults.for_object
- )
- llm_setting_for_object: LLMSetting = model_deck.get_llm_setting(llm_choice=llm_choice_for_object)
+ # LLM choice: explicit on the pipe → for_object override → for_object default. This pipe has
+ # no text choice of its own, so the kernel's object chain reduces to exactly those three rungs.
+ llm_setting_for_object: LLMSetting = resolve_llm_setting_for_object(llm_choice=self.llm_choice)
- # Render the structuring prompt template against the input text.
+ # Render the structuring prompt template against the input text. Prompt *assembly* is not
+ # shared with PipeLLM: this pipe has no template of its own and no memory-borne references —
+ # it renders one configured template over one input string.
llm_config = get_config().cogt.llm_config
structuring_template = llm_config.get_template(template_name="structuring_prompt")
rendered_user_prompt = await render_template(
@@ -132,58 +127,43 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
context={"text": text_str},
)
- # Append the schema description, just like PipeLLM does for object generation.
- if llm_config.is_structure_prompt_enabled:
- output_structure_prompt = await get_output_structure_prompt(concept_ref=self.output.concept.concept_ref)
- if output_structure_prompt:
- rendered_user_prompt += output_structure_prompt
-
- llm_prompt = LLMPrompt(user_text=rendered_user_prompt)
-
content_class: type[StuffContent] = get_class_registry().get_required_subclass(
name=self.output.concept.structure_class_name,
base_class=StuffContent,
)
- the_content: StuffContent
- if is_multiple_output:
- try:
- generated_objects = await content_generator.make_object_list(
- job_metadata=job_metadata,
- cogt_run_params=pipe_run_params.cogt_run_params,
- object_class=content_class,
- llm_prompt_for_object_list=llm_prompt,
- llm_setting_for_object_list=llm_setting_for_object,
- nb_items=fixed_nb_output,
- )
- except LLMCompletionError as exc:
- location = self._format_error_location(pipe_run_params=pipe_run_params)
- msg = f"Error generating object list in PipeStructure {location}: {exc}"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
- the_content = ListContent(items=generated_objects)
- else:
- try:
- the_content = await content_generator.make_object(
- job_metadata=job_metadata,
- cogt_run_params=pipe_run_params.cogt_run_params,
- object_class=content_class,
- llm_prompt_for_object=llm_prompt,
- llm_setting_for_object=llm_setting_for_object,
- )
- except LLMCompletionError as exc:
- location = self._format_error_location(pipe_run_params=pipe_run_params)
- msg = f"Error generating single object in PipeStructure {location}: {exc}"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
+ # Append the schema description, from the same kernel derivation PipeLLM's object path uses.
+ output_structure_prompt = await derive_structure_prompt(output_class=content_class)
+ if output_structure_prompt:
+ rendered_user_prompt += output_structure_prompt
+
+ llm_prompt = LLMPrompt(user_text=rendered_user_prompt)
+
+ try:
+ the_content = await generate_object_content(
+ job_metadata=job_metadata,
+ cogt_run_params=pipe_run_params.cogt_run_params,
+ llm_prompt=llm_prompt,
+ llm_setting=llm_setting_for_object,
+ output_class=content_class,
+ is_multiple_output=is_multiple_output,
+ fixed_nb_output=fixed_nb_output,
+ )
+ except LLMCompletionError as exc:
+ location = self._format_error_location(pipe_run_params=pipe_run_params)
+ what_failed = "object list" if is_multiple_output else "single object"
+ msg = f"Error generating {what_failed} in PipeStructure {location}: {exc}"
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
log.verbose(f"PipeStructure '{self.code}' produced {content_class.__name__} (list={is_multiple_output})")
- output_stuff = StuffFactory.make_stuff(
- name=output_name,
+ working_memory = store_result(
+ memory=working_memory,
concept=self.output.concept,
content=the_content,
- code=pipe_run_params.final_stuff_code,
+ result_name=output_name,
+ result_code=pipe_run_params.final_stuff_code,
)
- working_memory.set_new_main_stuff(stuff=output_stuff, name=output_name)
execution_data_dict: dict[str, Any] = {
"resolved_model": llm_setting_for_object.model,
diff --git a/pipelex/pipe_run/pipe_run_params_factory.py b/pipelex/pipe_run/pipe_run_params_factory.py
index cee98a65f..7c8efa137 100644
--- a/pipelex/pipe_run/pipe_run_params_factory.py
+++ b/pipelex/pipe_run/pipe_run_params_factory.py
@@ -1,11 +1,10 @@
from typing import Any
-from pipelex import log
from pipelex.cogt.content_generation.cogt_run_params import check_mock_usage_requires_dry
from pipelex.config import get_config
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
from pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunParams
-from pipelex.runtime_hub import is_dry_run_forced
+from pipelex.runtime_hub import resolve_run_mode_for_boot
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -24,21 +23,18 @@ class PipeRunParamsFactory:
) -> PipeRunParams:
"""Single writer of ``run_mode`` and ``is_mock_usage`` — direct fields on ``PipeRunParams``.
- The keyless-boot forced-DRY flag (eng review D4) is resolved HERE — at the single writer —
- so every execution entry point is covered (``prepare_pipe_job``, the runtime bridge,
- ``PipeJobFactory`` defaults), not just the pipeline-API path.
+ The keyless-boot forced-DRY flag (eng review D4) is applied HERE — at the single writer of
+ those fields — so every pipe-tier execution entry point is covered (``prepare_pipe_job``,
+ the runtime bridge, ``PipeJobFactory`` defaults), not just the pipeline-API path. The rule
+ itself lives in ``resolve_run_mode_for_boot`` rather than inline, because the kernel tier's
+ ``PipelexKernel.make`` mints its own ``CogtRunParams`` and must apply the identical rule.
The REQUESTED mode is validated before the forced-DRY coercion, so a contract violation
(``is_mock_usage`` on a LIVE request) fails loud on every boot — the keyless coercion must
not silently turn an illegal request into a legal one.
"""
check_mock_usage_requires_dry(run_mode=pipe_run_mode, is_mock_usage=is_mock_usage)
- if is_dry_run_forced() and pipe_run_mode.is_live:
- log.warning(
- "LIVE run requested under a keyless boot (needs_inference=False): forcing run_mode to DRY — "
- "outputs will be synthetic mocks, not real inference."
- )
- pipe_run_mode = PipeRunMode.DRY
+ pipe_run_mode = resolve_run_mode_for_boot(requested=pipe_run_mode)
pipe_stack_limit = pipe_stack_limit or get_config().pipelex.pipe_run_config.pipe_stack_limit
return PipeRunParams(
run_mode=pipe_run_mode,
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index 0936c9822..3a13e5d51 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -261,8 +261,8 @@ class Pipelex(RuntimeBoot):
Args:
integration_mode: Integration mode (CLI, FASTAPI, DOCKER, MCP, N8N, PYTHON, PYTEST)
needs_inference: When False, forces every run THIS process initiates to DRY mode
- (consumed at PipeRunParamsFactory.make_run_params, the single writer of run_mode:
- operators dispatch normally and the cogt leaf mocks) and loads backends leniently
+ (applied at runtime_hub.resolve_run_mode_for_boot, which every run-params factory
+ calls: operators dispatch normally and the cogt leaf mocks) and loads backends leniently
(skipping those with missing credentials). This skips gateway terms check and model
deck validation. Useful for commands like validate/show that don't call inference
APIs. Generator selection stays backend-keyed. Submitter-side contract only: it does
diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.py
index 15b881340..e6f3daca9 100644
--- a/pipelex/runtime_boot.py
+++ b/pipelex/runtime_boot.py
@@ -379,10 +379,12 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# ``build_registrar`` discovers external plugins unconditionally, so such a name satisfies this
# check, and a bare runtime boot would then apply the runtime slot claims while silently never
# applying the interpreter ones (``PIPE_ROUTER`` / ``PIPE_RUN`` / ``PIPE_FUNC_EXECUTOR``, all
- # applied in ``Pipelex.setup``). Unreachable today — nothing calls ``RuntimeBoot.make`` yet — and
- # deliberately not guarded here, because every remedy needs a layer signal this layer does not
- # have. Analysed in ``wip/boot-split/runtime-boot-external-interpreter-orchestrator.md``; the first
- # caller of a runtime-only boot is who has to settle it.
+ # applied in ``Pipelex.setup``). Deliberately not guarded here, because every remedy needs a layer
+ # signal this layer does not have. Analysed in
+ # ``wip/boot-split/runtime-boot-external-interpreter-orchestrator.md``, which the first runtime-only
+ # caller (the Pipelex kernel's boot-contract test) has now settled: that caller names no
+ # ``boot_orchestrator``, so this gate is never reached and the hole is not on its path. Reassess
+ # when a runtime-only boot is offered to real callers — that is when naming one becomes reachable.
requested_boot_orchestrator = get_config().plugins.boot_orchestrator
if requested_boot_orchestrator is not None and requested_boot_orchestrator not in plugin_registrar.registered_plugin_names:
raise UnknownBootOrchestratorError(requested=requested_boot_orchestrator)
@@ -524,8 +526,9 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
storage_provider = storage_provider_registry.get_required(method=storage_config.method)(storage_config)
self.runtime_hub.set_storage_provider(storage_provider)
- # Keyless boot forces every run to DRY — consumed at PipeRunParamsFactory.make_run_params,
- # the single writer of run_mode, covering every entry point; generator selection is
+ # Keyless boot forces every run to DRY — applied at runtime_hub.resolve_run_mode_for_boot,
+ # which every run-params factory calls (the pipe tier's PipeRunParamsFactory.make_run_params
+ # and the kernel tier's PipelexKernel.make), covering every entry point; generator selection is
# backend-keyed unconditionally (eng review D4) — a keyless Temporal submitter must still
# dispatch activities and mock inside them, so `needs_inference` plays no role in picking the
# generator. Its other boot roles (gateway/model setup, credentials, telemetry) are unchanged.
diff --git a/pipelex/runtime_hub.py b/pipelex/runtime_hub.py
index 81fb34f09..b5eab6810 100644
--- a/pipelex/runtime_hub.py
+++ b/pipelex/runtime_hub.py
@@ -44,6 +44,7 @@ from pipelex.reporting.reporting_protocol import ReportingProtocol
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.configuration.config_root import ConfigRoot
from pipelex.system.console_target import ConsoleTarget
+from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.registries.class_registry_access import get_class_registry as _get_active_class_registry
from pipelex.system.registries.func_registry import FuncRegistry
from pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract
@@ -526,6 +527,30 @@ def is_dry_run_forced() -> bool:
return get_runtime_hub().is_dry_run_forced()
+def resolve_run_mode_for_boot(*, requested: PipeRunMode) -> PipeRunMode:
+ """Apply the keyless-boot forced-DRY flag to a requested run mode (eng review D4).
+
+ The one place the flag is *applied*, sitting beside the accessor that reads it. Every factory
+ that mints run params for a run **this process initiates** calls it — the pipe tier's
+ ``PipeRunParamsFactory.make_run_params`` and the kernel tier's ``PipelexKernel.make`` — so
+ ``needs_inference=False`` stays a property of the boot rather than of whichever entry point a
+ caller happened to reach for. A second copy of the rule at a second factory is exactly how the
+ two would drift apart.
+
+ Note what this does NOT cover, deliberately: constructing a ``PipeRunParams`` or a
+ ``CogtRunParams`` directly bypasses it, just as it bypasses every other factory-level default.
+ Params handed to a worker over the wire are likewise untouched — the flag is a submitter-side
+ contract, not a constraint on work this process executes for someone else.
+ """
+ if is_dry_run_forced() and requested.is_live:
+ log.warning(
+ "LIVE run requested under a keyless boot (needs_inference=False): forcing run_mode to DRY — "
+ "outputs will be synthetic mocks, not real inference."
+ )
+ return PipeRunMode.DRY
+ return requested
+
+
def get_content_generator() -> ContentGeneratorProtocol:
override = _content_generator_override.get()
if override is not None:
diff --git a/subject_grants.toml b/subject_grants.toml
index 0ee2ea4b6..16f65d1a5 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -4208,26 +4208,6 @@ rationale = "Verb-object: extracts from the image ref; context stays keyword."
param = "image_ref"
rationale = "Verb-object: extracts from the image ref; context stays keyword."
-["pipelex/pipe_operators/llm/helpers.py::get_output_structure_prompt"]
-param = "concept_ref"
-rationale = "Derivation keyed by the concept ref; single operand."
-
-["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_document"]
-param = "doc_ref"
-rationale = "Verb-object: extracts from the document ref; context stays keyword."
-
-["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_image"]
-param = "image_ref"
-rationale = "Verb-object: extracts from the image ref; context stays keyword."
-
-["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_list_documents"]
-param = "doc_ref"
-rationale = "Verb-object: extracts from the document ref; context stays keyword."
-
-["pipelex/pipe_operators/llm/llm_prompt_blueprint.py::LLMPromptBlueprint._extract_direct_list_images"]
-param = "image_ref"
-rationale = "Verb-object: extracts from the image ref; context stays keyword."
-
["pipelex/pipe_operators/llm/pipe_llm.py::PipeLLM._format_error_location"]
param = "pipe_run_params"
rationale = "Derivation from the run params; single operand."
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
index 0047c10fe..b00412264 100644
--- a/tests/CLAUDE.md
+++ b/tests/CLAUDE.md
@@ -23,6 +23,7 @@ Replace `<paths>` with the test directories from the mapping below. Concatenate
| `pipelex/cogt/` | `tests/unit/pipelex/cogt/ tests/integration/pipelex/cogt/` |
| `pipelex/core/` | `tests/unit/pipelex/core/ tests/integration/pipelex/core/ tests/integration/pipelex/pipes/` |
| `pipelex/graph/` | `tests/unit/pipelex/graph/ tests/e2e/pipelex/graph/` |
+| `pipelex/kernel/` | `tests/unit/pipelex/kernel/ tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/` |
| `pipelex/kit/` | `tests/unit/pipelex/kit/ tests/integration/pipelex/kit/` |
| `pipelex/language/` | `tests/unit/pipelex/language/ tests/integration/pipelex/language/` |
| `pipelex/libraries/` | `tests/unit/pipelex/libraries/ tests/integration/pipelex/libraries/` |
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py
index d982d0042..71637ef03 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py
@@ -3,8 +3,8 @@
from pathlib import Path
from typing import Callable
+from pipelex.kernel.prompt_references import DocumentReferenceKind
from pipelex.pipe_machinery.pipe_factory import PipeFactory
-from pipelex.pipe_operators.llm.document_reference import DocumentReferenceKind
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py
index 5eefbe172..243caa088 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py
@@ -3,8 +3,8 @@
from pathlib import Path
from typing import Callable
+from pipelex.kernel.prompt_references import ImageReferenceKind
from pipelex.pipe_machinery.pipe_factory import PipeFactory
-from pipelex.pipe_operators.llm.image_reference import ImageReferenceKind
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py
index 32ea0ce8e..ebbac051d 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py
@@ -14,9 +14,8 @@ from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.interpreter_hub import get_required_concept
+from pipelex.kernel.prompt_references import DocumentReferenceKind, ImageReferenceKind
from pipelex.pipe_machinery.pipe_factory import PipeFactory
-from pipelex.pipe_operators.llm.document_reference import DocumentReferenceKind
-from pipelex.pipe_operators.llm.image_reference import ImageReferenceKind
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from tests.cases import DocumentTestCases, ImageTestCases
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py
index cd6246895..867ef6f2e 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py
@@ -12,9 +12,8 @@ from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.interpreter_hub import get_native_concept
+from pipelex.kernel.prompt_references import DocumentReferenceKind, ImageReferenceKind
from pipelex.pipe_machinery.pipe_factory import PipeFactory
-from pipelex.pipe_operators.llm.document_reference import DocumentReferenceKind
-from pipelex.pipe_operators.llm.image_reference import ImageReferenceKind
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from tests.cases import DocumentTestCases, ImageTestCases
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py
index 9560cc195..5222775cd 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py
@@ -40,7 +40,7 @@ class TestPipeLLMModelNotFoundReroute:
)
fake_content_generator = mocker.MagicMock()
fake_content_generator.make_llm_text = mocker.AsyncMock(side_effect=not_found_error)
- mocker.patch("pipelex.pipe_operators.llm.pipe_llm.get_content_generator", return_value=fake_content_generator)
+ mocker.patch("pipelex.kernel.llm_ops.get_content_generator", return_value=fake_content_generator)
pipe = PipeFactory[PipeLLM].make_from_blueprint(
domain_code="documents",
diff --git a/tests/integration/pipelex/system/test_keyless_boot_forced_dry.py b/tests/integration/pipelex/system/test_keyless_boot_forced_dry.py
index 81ee61739..50351c028 100644
--- a/tests/integration/pipelex/system/test_keyless_boot_forced_dry.py
+++ b/tests/integration/pipelex/system/test_keyless_boot_forced_dry.py
@@ -3,9 +3,16 @@
A keyless boot (``needs_inference=False``) must NOT change generator selection — the backend alone
picks inline vs in-workflow, so a keyless Temporal submitter still dispatches activities (and the
leaf mocks inside them — the Tier 17 no-keys arm depends on it). What keyless boot does instead is
-set the forced-DRY flag, which ``PipeRunParamsFactory.make_run_params`` — the single writer of
-``run_mode`` — consumes by overriding any requested run mode to DRY, covering every execution
-entry point (pipeline API, runtime bridge, factory defaults).
+set the forced-DRY flag, which ``runtime_hub.resolve_run_mode_for_boot`` applies by overriding any
+requested run mode to DRY.
+
+Both run-params factories call it, and both arms are pinned below, because "covers every execution
+entry point" is a claim about the set of factories rather than about one of them: the pipe tier's
+``PipeRunParamsFactory.make_run_params`` (pipeline API, runtime bridge, factory defaults) and the
+kernel tier's ``PipelexKernel.make``, which mints its own ``CogtRunParams`` for a programmatic caller
+driving kernel ops with no method loaded. The kernel arm is the one that would silently spend real
+money if the rule were applied at the pipe factory alone — its default is ``PipeRunMode.LIVE``, and
+a keyless boot is exactly the boot ``pipelex/kernel/`` documents as its target.
"""
from collections.abc import Generator
@@ -15,6 +22,7 @@ import pytest
from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.config import get_config
from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.kernel.pipelex_kernel import PipelexKernel
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.search.pipe_search import PipeSearch
from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
@@ -76,6 +84,24 @@ class TestKeylessBootForcedDry:
finally:
Pipelex.teardown_if_needed()
+ def test_keyless_boot_forces_dry_on_the_kernel_factory_too(self) -> None:
+ """The kernel tier's run-params factory honours the same flag — and its default is LIVE.
+
+ Asserted on the default rather than on an explicit ``run_mode=LIVE`` because the default is
+ the reachable hazard: a programmatic caller writes ``PipelexKernel.make(user_id=...)``,
+ names no mode, and without the coercion gets a LIVE ``CogtRunParams`` that walks straight
+ past the leaf's DRY branch into a real provider call.
+ """
+ try:
+ self._boot_keyless()
+ assert is_dry_run_forced()
+
+ kernel = PipelexKernel.make(user_id="test-user")
+
+ assert kernel.cogt_run_params.run_mode.is_dry
+ finally:
+ Pipelex.teardown_if_needed()
+
def test_keyed_boot_does_not_force_dry(self) -> None:
"""Control arm: a normal boot leaves the flag unset."""
try:
diff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py
index 6a6c980ed..4910cf8f7 100644
--- a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py
+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py
@@ -175,6 +175,29 @@ class TestHubLayeringGuard:
"fail by design. Declare pipelex.runtime_boot instead; that is the half that stays clean."
)
+ def test_the_pipelex_kernel_stays_declared(self) -> None:
+ """`pipelex.kernel` must stay declared — it is the package the whole extraction exists to keep clean.
+
+ The kernel holds the operator-execution semantics the interpreter's operator classes call
+ into, and its contract is that a programmatic caller can invoke them on a `RuntimeBoot`-only
+ process. One `interpreter_hub` reach anywhere inside it breaks that contract for every
+ caller at once — so this is the package where the "undeclared is unpoliced" failure would
+ cost the most, and it was declared in the same commit that created it rather than after a
+ breach, unlike the four above.
+
+ Deleting the entry is the silent regression: the layer rule and the transitive rule both
+ filter through `is_runtime_layer`, and the `pipelex.exceptions` aggregate gate iterates this
+ very tuple — so removing the entry takes the kernel out of *three* checks at once while
+ every one of them keeps reporting PASSED. Membership is the whole assertion, for the reason
+ the neighbouring tests give.
+ """
+ assert "pipelex.kernel" in RUNTIME_LAYER_PACKAGES, (
+ "pipelex.kernel holds the operator-execution semantics that must stay callable on a "
+ "runtime-only boot, and it is no longer declared runtime-layer. Undeclared means "
+ "unchecked, not flagged — restore the entry, or move whatever made it dirty to the "
+ "layer it belongs to."
+ )
+
def test_runtime_layer_may_import_runtime_hub(self) -> None:
"""The permitted direction is never flagged — the runtime layer lives on `runtime_hub`."""
violations = _violate(
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py b/tests/unit/pipelex/kernel/test_document_reference.py
similarity index 97%
rename from tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py
rename to tests/unit/pipelex/kernel/test_document_reference.py
index fb2ea00e2..956247c39 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_document_reference.py
+++ b/tests/unit/pipelex/kernel/test_document_reference.py
@@ -1,6 +1,6 @@
import pytest
-from pipelex.pipe_operators.llm.document_reference import DocumentReference, DocumentReferenceKind
+from pipelex.kernel.prompt_references import DocumentReference, DocumentReferenceKind
class TestDocumentReference:
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py b/tests/unit/pipelex/kernel/test_image_reference.py
similarity index 98%
rename from tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py
rename to tests/unit/pipelex/kernel/test_image_reference.py
index 22bdc2fd4..c0893cc3f 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_image_reference.py
+++ b/tests/unit/pipelex/kernel/test_image_reference.py
@@ -1,6 +1,6 @@
import pytest
-from pipelex.pipe_operators.llm.image_reference import ImageReference, ImageReferenceKind
+from pipelex.kernel.prompt_references import ImageReference, ImageReferenceKind
class TestImageReference:
diff --git a/tests/unit/pipelex/kernel/test_kernel_boot_contract.py b/tests/unit/pipelex/kernel/test_kernel_boot_contract.py
new file mode 100644
index 000000000..0a32fa52c
--- /dev/null
+++ b/tests/unit/pipelex/kernel/test_kernel_boot_contract.py
@@ -0,0 +1,186 @@
+"""A kernel call is servable on a `RuntimeBoot`-only process with zero `.mthds` loaded.
+
+This is the kernel's *contract*, not a consequence of one — the whole point of extracting operator
+semantics out of the interpreter is that a programmatic caller can invoke them without a library, a
+router or a pipeline manager. So it is pinned permanently here rather than proven once by hand.
+
+Three layers already guard neighbouring properties and none of them covers this one. The static
+hub-layering guard proves no kernel *module* imports `interpreter_hub`.
+`test_runtime_layer_import_closure.py` proves `pipelex.kernel.pipelex_kernel` *imports* clean.
+`test_runtime_boot_closure.py` proves `RuntimeBoot.make()` *boots* clean. What none of them does is
+**call** a kernel op on that boot — and a call is where a runtime-only process would actually break:
+by resolving out of a registry the interpreter half fills (`OrchestratorRegistry`,
+`BundleValidatorRegistry`, the PipeFunc executor modes are all empty here), or by reaching the
+interpreter through a function-local import, which is invisible to the static graph and to the
+import-closure test *at once*. The sweep below therefore runs **after** the kernel call, which is
+what makes this test strictly stronger than the import-time one it complements.
+
+Run in a **subprocess** for the reason its two siblings state: a suite-level boot already owns the
+process singletons, and both hubs are sticky class attributes that `teardown` deliberately does not
+clear — so an in-process check would answer from a stale `Pipelex` and pass vacuously.
+
+`needs_inference=False` keeps the boot offline (no gateway terms gate, no model-deck validation), and
+`PipeRunMode.DRY` keeps the call offline: the cogt leaf mocks before any worker is looked up, so the
+`LLMSetting` names a model the deck never has to resolve.
+
+**On the deferred orchestrator question.** `runtime_boot.py`'s orchestrator-rejection comment defers
+the external-interpreter-orchestrator half-application hole to "the first caller of a runtime-only
+boot", which is this test. It is settled, not inherited: this boot names no `boot_orchestrator` and
+its config sets none, so the gate is never reached and the hole is not on this path. The remedy the
+analysis proposes (a `HubSlot.is_interpreter_slot` property plus a `honours_interpreter_slots` class
+attribute) remains unbuilt on purpose — it is real machinery for a path that still has no production
+caller. Recorded in `wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`.
+"""
+
+import subprocess # noqa: S404
+import sys
+import textwrap
+
+from tests.unit.pipelex.test_runtime_layer_import_closure import INTERPRETER_PACKAGES
+
+#: Wall-clock bound on the kernel-call subprocess, matching both sibling harnesses: a boot or a call
+#: that deadlocks must present as a failure, not as a hung suite
+#: (`docs/agents/debugging-hanging-pytest-runs.md`).
+SUBPROCESS_TIMEOUT_SECONDS = 300
+
+#: Boot the runtime layer in a fresh interpreter, run **both** façade calls through the kernel, assert
+#: the typed results, and only then sweep `sys.modules`. The order is the point: a function-local
+#: interpreter import inside a kernel op would land in `sys.modules` during the call and nowhere else.
+#: Both arms run because they share almost nothing below the façade — `resolve_llm_setting_for_text`
+#: vs `_for_object`, and `dry_llm_gen_text` vs `dry_llm_gen_object` — so covering one leaves the
+#: other's closure unproven, and the contract is stated over *a kernel call*, not over one of them.
+_KERNEL_CALL_SCRIPT = textwrap.dedent(
+ """
+ import asyncio
+ import sys
+
+ from pipelex.cogt.llm.llm_setting import LLMSetting
+ from pipelex.core.concepts.concept_factory import ConceptFactory
+ from pipelex.core.concepts.native.concept_native import NativeConceptCode
+ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+ from pipelex.core.stuffs.number_content import NumberContent
+ from pipelex.core.stuffs.text_content import TextContent
+ from pipelex.kernel.llm_results import LlmObjectResult, LlmTextResult
+ from pipelex.kernel.pipelex_kernel import PipelexKernel
+ from pipelex.runtime_boot import RuntimeBoot
+ from pipelex.system.pipe_run_mode import PipeRunMode
+ from pipelex.system.runtime import IntegrationMode
+
+ interpreter_packages = frozenset(sys.argv[1:])
+ # An empty set would make the sweep flag nothing and the test pass vacuously — the same guard both
+ # sibling harnesses carry, for the same reason.
+ if not interpreter_packages:
+ print("no interpreter packages passed — the sweep would match nothing")
+ raise SystemExit(2)
+
+ RuntimeBoot.make(integration_mode=IntegrationMode.PYTEST, needs_inference=False)
+
+ kernel = PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="kernel-boot-contract")
+ model = LLMSetting(model="kernel-boot-contract-model", temperature=0.5)
+
+ object_result = asyncio.run(
+ kernel.llm_object(
+ memory=WorkingMemoryFactory.make_empty(),
+ output_class=NumberContent,
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.NUMBER),
+ model=model,
+ user="Pick a number.",
+ result="answer",
+ )
+ )
+
+ if not isinstance(object_result, LlmObjectResult):
+ print(f"llm_object returned {type(object_result).__name__}, not an LlmObjectResult")
+ raise SystemExit(1)
+ if not isinstance(object_result.content, NumberContent):
+ print(f"llm_object produced {type(object_result.content).__name__}, not the NumberContent it was given")
+ raise SystemExit(1)
+ if object_result.memory.get_main_stuff().content is not object_result.content:
+ print("the memory returned by llm_object does not carry the produced content as its main stuff")
+ raise SystemExit(1)
+
+ text_result = asyncio.run(
+ kernel.llm_text(
+ memory=WorkingMemoryFactory.make_empty(),
+ model=model,
+ user="Say something.",
+ result="reply",
+ )
+ )
+
+ if not isinstance(text_result, LlmTextResult):
+ print(f"llm_text returned {type(text_result).__name__}, not an LlmTextResult")
+ raise SystemExit(1)
+ main_text_content = text_result.memory.get_main_stuff().content
+ if not isinstance(main_text_content, TextContent):
+ print(f"llm_text landed {type(main_text_content).__name__} in memory, not a TextContent")
+ raise SystemExit(1)
+ if main_text_content.text != text_result.text:
+ print("the memory returned by llm_text does not carry the text the result reports")
+ raise SystemExit(1)
+
+ # Swept last, so a function-local interpreter import taken during either call is caught too.
+ offenders = sorted(
+ name
+ for name in sys.modules
+ if name.startswith("pipelex.") and name.split(".")[1] in interpreter_packages
+ )
+ if offenders:
+ print(f"the kernel call loaded {len(offenders)} interpreter module(s): {offenders}")
+ raise SystemExit(1)
+ if "pipelex.interpreter_hub" in sys.modules:
+ print("the kernel call loaded pipelex.interpreter_hub")
+ raise SystemExit(1)
+
+ print("kernel boot contract OK")
+ """
+)
+
+#: The negative control. The sweep lives inside a `textwrap.dedent` string, so nothing type-checks or
+#: lints the logic in it — a broken predicate would leave the real case green forever while flagging
+#: nothing, and the real case cannot detect its own blindness. `cogt` is the control package because
+#: an LLM kernel call loads it by definition, so calling it an "interpreter package" must come back a
+#: failure, reported as offending modules. Both sibling harnesses carry the same control.
+CONTROL_PACKAGE_THE_KERNEL_ALWAYS_LOADS = "cogt"
+
+
+def _run_kernel_call(*, interpreter_packages: tuple[str, ...]) -> subprocess.CompletedProcess[str]:
+ """Boot the runtime layer in a fresh interpreter, call the kernel, and return the verdict."""
+ try:
+ return subprocess.run( # noqa: S603
+ [sys.executable, "-c", _KERNEL_CALL_SCRIPT, *interpreter_packages],
+ capture_output=True,
+ text=True,
+ check=False,
+ timeout=SUBPROCESS_TIMEOUT_SECONDS,
+ )
+ except subprocess.TimeoutExpired as exc:
+ message = f"the kernel boot-contract subprocess did not finish within {SUBPROCESS_TIMEOUT_SECONDS}s"
+ raise AssertionError(message) from exc
+
+
+class TestKernelBootContract:
+ def test_the_sweep_still_detects_a_package_the_kernel_call_really_loads(self) -> None:
+ """The control: same script, opposite verdict. Without this, the real case below is vacuous."""
+ result = _run_kernel_call(interpreter_packages=(CONTROL_PACKAGE_THE_KERNEL_ALWAYS_LOADS,))
+
+ assert result.returncode == 1, (
+ f"treating {CONTROL_PACKAGE_THE_KERNEL_ALWAYS_LOADS!r} as an interpreter package must fail — "
+ "an LLM kernel call loads it by definition. This passing means the sweep has stopped sweeping, "
+ "and the real case below now proves nothing.\n"
+ f"stdout={result.stdout}\nstderr={result.stderr}"
+ )
+ assert "interpreter module(s)" in result.stdout
+ assert "kernel boot contract OK" not in result.stdout
+
+ def test_every_kernel_call_runs_on_a_runtime_only_boot_with_no_library(self) -> None:
+ result = _run_kernel_call(interpreter_packages=INTERPRETER_PACKAGES)
+
+ assert result.returncode == 0, (
+ "every kernel call must be servable on a RuntimeBoot-only process with zero .mthds loaded, and must "
+ "load no interpreter module doing it. This is the kernel's contract — see pipelex/kernel/__init__.py "
+ "for the doctrine and docs/contribute/hub-layering.md for how to find the shortest import path to an "
+ "offender.\n"
+ f"stdout={result.stdout}\nstderr={result.stderr}"
+ )
+ assert "kernel boot contract OK" in result.stdout
diff --git a/tests/unit/pipelex/kernel/test_llm_object_kernel.py b/tests/unit/pipelex/kernel/test_llm_object_kernel.py
new file mode 100644
index 000000000..c52acbfaa
--- /dev/null
+++ b/tests/unit/pipelex/kernel/test_llm_object_kernel.py
@@ -0,0 +1,114 @@
+"""The object path's two kernel-only arms, exercised through the façade in DRY mode.
+
+Neither arm is reachable from the re-pointed interpreter suite, which is why they live here rather
+than being left to the zero-behavior-change backstop:
+
+- **Structure-prompt provenance.** `PipeLLM` never supplies a `structure_prompt` and always rides the
+ kernel's derivation; `PipeStructure` always supplies one and never derives. No interpreter test
+ therefore observes the *choice* between the two on one code path. The sentinel is `is not None`
+ rather than falsiness, so an empty string is a real "no structure prompt at all" override — a
+ rewrite to `structure_prompt or await derive_structure_prompt(...)` would silently turn that arm
+ back into a derivation, and only the empty-string case below would notice.
+- **The memory contract.** A kernel call may mutate the memory it is passed and *returns* it; callers
+ must treat the returned memory as the result. Inline execution aliases the two, so an interpreter
+ test that reads the argument back cannot tell the two apart — which is exactly the aliasing the
+ contract tells callers not to depend on.
+
+DRY mode is what keeps these unit tests: `llm_generate.py` branches to the dry leaf *before* any
+worker lookup, so the `LLMSetting` below names a model the deck never has to resolve.
+"""
+
+import pytest
+
+from pipelex.cogt.llm.llm_setting import LLMSetting
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.kernel.llm_results import StructuringPath
+from pipelex.kernel.pipelex_kernel import PipelexKernel
+from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.test_extras.registry_test_models import FictionCharacter
+
+#: Named but never resolved: the dry leaf short-circuits before a worker is looked up, so this stays
+#: a unit test instead of acquiring a dependency on whatever the deck happens to contain.
+DRY_LLM_SETTING = LLMSetting(model="kernel-unit-test-model", temperature=0.5)
+
+USER_PROMPT = "Invent a character."
+
+SUPPLIED_STRUCTURE_PROMPT = "\n\nAnswer as a character sheet."
+
+#: A field name of `FictionCharacter` that appears in the *derived* structure prompt and nowhere else
+#: in this module — the marker that says which of the two provenances produced the prompt.
+FIELD_ONLY_THE_DERIVATION_NAMES = "backstory"
+
+RESULT_NAME = "character"
+
+
+def _make_dry_kernel() -> PipelexKernel:
+ return PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="kernel-unit-test")
+
+
+class TestLlmObjectKernel:
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_the_structure_prompt_is_derived_from_the_output_class_by_default(self) -> None:
+ result = await _make_dry_kernel().llm_object(
+ memory=WorkingMemoryFactory.make_empty(),
+ output_class=FictionCharacter,
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.ANYTHING),
+ model=DRY_LLM_SETTING,
+ user=USER_PROMPT,
+ result=RESULT_NAME,
+ )
+
+ user_text = result.rendered_prompt.user_text
+ assert user_text is not None
+ assert user_text.startswith(USER_PROMPT)
+ assert FIELD_ONLY_THE_DERIVATION_NAMES in user_text, (
+ "with no structure prompt supplied, the kernel must derive one from `output_class` — this is "
+ "what keeps both callers producing the same prompt by default instead of forking their defaults."
+ )
+
+ @pytest.mark.asyncio(loop_scope="class")
+ @pytest.mark.parametrize(
+ "structure_prompt",
+ [
+ pytest.param(SUPPLIED_STRUCTURE_PROMPT, id="supplied_text_replaces_the_derivation"),
+ pytest.param("", id="empty_string_overrides_with_no_structure_prompt_at_all"),
+ ],
+ )
+ async def test_a_supplied_structure_prompt_replaces_the_derivation(self, structure_prompt: str) -> None:
+ result = await _make_dry_kernel().llm_object(
+ memory=WorkingMemoryFactory.make_empty(),
+ output_class=FictionCharacter,
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.ANYTHING),
+ model=DRY_LLM_SETTING,
+ user=USER_PROMPT,
+ structure_prompt=structure_prompt,
+ result=RESULT_NAME,
+ )
+
+ assert result.rendered_prompt.user_text == USER_PROMPT + structure_prompt
+ assert FIELD_ONLY_THE_DERIVATION_NAMES not in (result.rendered_prompt.user_text or "")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_the_produced_content_lands_in_the_returned_memory(self) -> None:
+ """The returned memory is the result — asserted here, and asserted *only* here.
+
+ That the argument happens to be the same object today is deliberately not asserted: it is the
+ aliasing the contract forbids callers from relying on, and pinning it in a test would make the
+ very change the contract exists to permit (a serialization boundary between the two) look like
+ a regression.
+ """
+ result = await _make_dry_kernel().llm_object(
+ memory=WorkingMemoryFactory.make_empty(),
+ output_class=FictionCharacter,
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.ANYTHING),
+ model=DRY_LLM_SETTING,
+ user=USER_PROMPT,
+ result=RESULT_NAME,
+ )
+
+ assert isinstance(result.content, FictionCharacter)
+ assert result.structuring_path == StructuringPath.OBJECT_DIRECT
+ assert result.memory.get_stuff(name=RESULT_NAME).content is result.content
+ assert result.memory.get_main_stuff().content is result.content
diff --git a/tests/unit/pipelex/kernel/test_llm_text_kernel.py b/tests/unit/pipelex/kernel/test_llm_text_kernel.py
new file mode 100644
index 000000000..4f6145d67
--- /dev/null
+++ b/tests/unit/pipelex/kernel/test_llm_text_kernel.py
@@ -0,0 +1,83 @@
+"""The text path's façade must be as wide as the op beneath it, exercised in DRY mode.
+
+`run_llm_text` takes `concept`, `output_class` and a nullable model choice; the interpreter passes
+all three, with the model routinely unset. A façade that hardcodes them is not a convenience over the
+op — it is a narrower operation wearing the same name, and the narrowing is silent: a caller
+producing a concept that *refines* native `Text` gets `native.Text`/`TextContent` stored where an
+interpreted run stores the declared concept and its generated class. Nothing raises at the call;
+it raises later, as a `StuffContentTypeError`, in whatever reads the memory back expecting the
+declared class. So the gate is on what lands in the returned memory, not on the signature.
+
+DRY mode is what keeps this a unit test: `llm_generate.py` branches to the dry leaf before any worker
+lookup, so the `LLMSetting` below names a model the deck never has to resolve. The unset-model case
+is the one exception and says so at its assertion.
+"""
+
+import pytest
+
+from pipelex.cogt.llm.llm_setting import LLMSetting
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.kernel.pipelex_kernel import PipelexKernel
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+#: Named but never resolved: the dry leaf short-circuits before a worker is looked up.
+DRY_LLM_SETTING = LLMSetting(model="kernel-unit-test-model", temperature=0.5)
+
+USER_PROMPT = "Write a one-line summary."
+
+RESULT_NAME = "summary"
+
+
+class MeetingSummary(TextContent):
+ """A `TextContent` subclass standing in for the class a Text-refining concept generates.
+
+ Declared here rather than pulled from `test_extras` because what matters is only that it is a
+ class the façade could not have guessed — the point is that the caller's choice survives.
+ """
+
+
+def _make_dry_kernel() -> PipelexKernel:
+ return PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="kernel-unit-test")
+
+
+class TestLlmTextKernel:
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_the_callers_concept_and_output_class_reach_the_memory(self) -> None:
+ """The whole point of widening: what the caller declared is what gets stored."""
+ concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.ANYTHING)
+
+ result = await _make_dry_kernel().llm_text(
+ memory=WorkingMemoryFactory.make_empty(),
+ model=DRY_LLM_SETTING,
+ user=USER_PROMPT,
+ concept=concept,
+ output_class=MeetingSummary,
+ result=RESULT_NAME,
+ )
+
+ stuff = result.memory.get_stuff(name=RESULT_NAME)
+ assert type(stuff.content) is MeetingSummary, (
+ "the caller's `output_class` must reach the op — hardcoding `TextContent` stores a class the "
+ "caller never asked for, and only blows up later in whoever reads the memory back."
+ )
+ assert stuff.concept.concept_ref == concept.concept_ref, (
+ "the caller's `concept` must reach the op — an interpreted run stores the declared concept, so "
+ "hardcoding native Text is exactly the two-readers-disagree shape this gate exists to catch."
+ )
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_the_defaults_are_what_the_method_used_to_hardcode(self) -> None:
+ """Widening had to stay additive: omitting both must reproduce the previous behavior exactly."""
+ result = await _make_dry_kernel().llm_text(
+ memory=WorkingMemoryFactory.make_empty(),
+ model=DRY_LLM_SETTING,
+ user=USER_PROMPT,
+ result=RESULT_NAME,
+ )
+
+ stuff = result.memory.get_stuff(name=RESULT_NAME)
+ assert type(stuff.content) is TextContent
+ assert stuff.concept.concept_ref == NativeConceptCode.TEXT.concept_ref
diff --git a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py
index f834c303a..d4b041575 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py
@@ -3,10 +3,10 @@
from pathlib import Path
from typing import Callable
+from pipelex.kernel.prompt_references import ImageReferenceKind
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.img_gen.pipe_img_gen import PipeImgGen
from pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlueprint
-from pipelex.pipe_operators.shared.image_reference import ImageReferenceKind
class TestPipeImgGenFactoryImageReferences:
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py
index ffd1fcc72..bfd73d87a 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py
@@ -3,7 +3,7 @@
from pathlib import Path
from typing import Callable
-from pipelex.pipe_operators.llm.document_reference import DocumentReferenceKind
+from pipelex.kernel.prompt_references import DocumentReferenceKind
from pipelex.pipe_operators.llm.template_document_analyzer import TemplateDocumentAnalyzer
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py
index ae89bdaa3..c631699b1 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py
@@ -5,7 +5,7 @@ from typing import Callable
import pytest
-from pipelex.pipe_operators.llm.image_reference import ImageReferenceKind
+from pipelex.kernel.prompt_references import ImageReferenceKind
from pipelex.pipe_operators.shared.exceptions import UnusedInputError, WithImagesFilterError
from pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageAnalyzer
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py
index c4684ade0..2c6f920ff 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer_cross_package.py
@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Callable, cast
from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.interpreter_hub import get_concept_library
-from pipelex.pipe_operators.shared.image_reference import ImageReferenceKind
+from pipelex.kernel.prompt_references import ImageReferenceKind
from pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageAnalyzer
if TYPE_CHECKING:
diff --git a/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py b/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py
index 42197d627..3c02e7505 100644
--- a/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py
+++ b/tests/unit/pipelex/pipe_run/test_cogt_run_params_carrier.py
@@ -35,8 +35,8 @@ class TestCogtRunParamsCarrier:
def test_forced_dry_coerces_live_and_warns(self, mocker: MockerFixture) -> None:
"""Keyless boot: a LIVE request is coerced to DRY with a warning."""
- mocker.patch("pipelex.pipe_run.pipe_run_params_factory.is_dry_run_forced", return_value=True)
- warning_spy = mocker.patch("pipelex.pipe_run.pipe_run_params_factory.log.warning")
+ mocker.patch("pipelex.runtime_hub.is_dry_run_forced", return_value=True)
+ warning_spy = mocker.patch("pipelex.runtime_hub.log.warning")
run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE)
@@ -47,14 +47,14 @@ class TestCogtRunParamsCarrier:
"""Keyless boot: LIVE + is_mock_usage still fails loud — the factory validates the REQUESTED
mode first, so the coercion cannot silently turn an illegal request into a reportable dry run.
"""
- mocker.patch("pipelex.pipe_run.pipe_run_params_factory.is_dry_run_forced", return_value=True)
+ mocker.patch("pipelex.runtime_hub.is_dry_run_forced", return_value=True)
with pytest.raises(ValueError, match="is_mock_usage"):
PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE, is_mock_usage=True)
def test_forced_dry_keeps_mock_usage_on_dry_request(self, mocker: MockerFixture) -> None:
"""Keyless boot: an explicit DRY + is_mock_usage request is legal and passes through untouched."""
- mocker.patch("pipelex.pipe_run.pipe_run_params_factory.is_dry_run_forced", return_value=True)
+ mocker.patch("pipelex.runtime_hub.is_dry_run_forced", return_value=True)
run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY, is_mock_usage=True)
diff --git a/tests/unit/pipelex/test_runtime_layer_import_closure.py b/tests/unit/pipelex/test_runtime_layer_import_closure.py
index 6e71ca16d..f8ac5daa6 100644
--- a/tests/unit/pipelex/test_runtime_layer_import_closure.py
+++ b/tests/unit/pipelex/test_runtime_layer_import_closure.py
@@ -63,10 +63,20 @@ import pytest
#: interpreter package's errors, each one loaded 15 interpreter modules — inside a package this tuple's
#: sibling declaration already claimed was clean. The import now points at the definition site, per this
#: repo's "direct full-path imports everywhere" rule, and this entry point is what keeps it there.
+#:
+#: `kernel.pipelex_kernel` is the Pipelex kernel's widest module-level closure: the façade imports the
+#: ops modules that hold the operator-execution semantics, so one entry point covers the package.
+#: It earns a place here for a reason none of the others share — the kernel's *contract* is that a
+#: programmatic caller can invoke these functions on a `RuntimeBoot`-only process with zero `.mthds`
+#: loaded, which is this very property rather than a consequence of it. Note the blind spot the
+#: kernel's own doctrine restates: this test sees module-level imports only, so a function-local
+#: import inside a kernel module is invisible to it *and* to the static graph at once, and reviews
+#: have to catch those by hand.
RUNTIME_LAYER_ENTRY_POINTS = [
"pipelex.cogt.content_generation.content_generator",
"pipelex.runtime_hub",
"pipelex.runtime_boot",
+ "pipelex.kernel.pipelex_kernel",
"pipelex.providers.builtins",
"pipelex.core.concepts.structure_generation.generator",
"pipelex.core.memory.input_shaper",
diff --git a/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md b/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md
index cb50a8290..903b220dd 100644
--- a/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md
+++ b/wip/boot-split/runtime-boot-external-interpreter-orchestrator.md
@@ -47,6 +47,14 @@ That check also subsumes the narrower orchestrator question: it catches *any* ex
**Cheaper alternative worth weighing first:** have `build_registrar` take the set of slots the caller will apply and refuse a claim outside it. That pushes the check into the one place that already knows every claim, and removes the class attribute — but it widens `build_registrar`'s signature, and that function is currently a pure discover-and-register with no policy in it, which is a property worth protecting.
+## The first runtime-only caller has arrived — and the verdict is "still not now"
+
+`tests/unit/pipelex/kernel/test_kernel_boot_contract.py` (the pipelex-kernel extraction, Phase 1) is the first thing in the tree to call `RuntimeBoot.make()` for a purpose other than measuring the boot itself: it boots runtime-only and then *runs* both kernel façade calls (`llm_object` and `llm_text`) on it. That is the caller this document deferred the decision to, so the decision is recorded here rather than left open.
+
+**It does not trigger the hole, and not by luck.** The gate is only reached when `get_config().plugins.boot_orchestrator` is non-`None`. That test names no `boot_orchestrator` and the config sets none, so nothing is requested, nothing is matched, and no slot claim is half-applied. The same is true of every runtime-only caller the kernel work adds — the kernel's own doctrine forbids it from reading `HubSlot` at all, and Phase 2's `PipeFunc` op takes its executor as an explicit protocol-typed argument for exactly that reason.
+
+**The remedy stays unbuilt, deliberately.** Both candidates above are real machinery — a `HubSlot.is_interpreter_slot` property plus a `honours_interpreter_slots` class attribute, or a widened `build_registrar` signature — bought for a path that *still* has no production caller. The three preconditions are unchanged: an external interpreter-side orchestrator installed, config or an argument naming it, and a runtime-only boot. A test that names no orchestrator satisfies none of the second two, so implementing the guard now would mean adding a mechanism no code can reach in order to close a hole no code can fall into. Reassess when a runtime-only boot is offered to real callers (a kernel-embedding host, an SDK entry point) — at that moment the second precondition becomes reachable for the first time and the slot-property remedy is the one to build.
+
## What exists today instead
The gate's comment in `runtime_boot.py` states the hole precisely and points here, so the next reader meets the reasoning rather than rediscovering the trap. Nothing silently claims to handle it.
diff --git a/wip/drift-contracts/dogfood-log.md b/wip/drift-contracts/dogfood-log.md
index 5550600d7..3bc3b6f43 100644
--- a/wip/drift-contracts/dogfood-log.md
+++ b/wip/drift-contracts/dogfood-log.md
@@ -54,3 +54,15 @@ The mechanical enumeration check ran clean for the first time in eight rounds
What this round adds to the pilot is a shape none of the previous entries has: **the contract opened on the second half of a fix whose first half had already shipped without opening it.** The identical wrong sentence lived in two places — `RuntimeHub.setup_config` and the `load_config` it delegates to. Correcting the first opened `hub-layering-convention` (fifteenth ack, "no-op, correct silence"); correcting the second opened `config-docs`, also a no-op. Two contracts fired, neither review target was stale, and neither contract could have pointed at the duplication, because a review contract watches code→doc drift and this was code→code drift. The sibling was found by a review pass reading both files, not by the manifest.
The honest reading is not "add a contract for it" — the right instrument for two copies of one sentence is deduplication or a docstring that points at its source, not a review obligation. It is a data point on scope: `drift.toml`'s header says anything mechanizable belongs in a derived check, and this is the mirror case, something neither mechanizable *nor* expressible as a review target. Worth remembering the next time a no-op ack tempts a trigger-set widening.
+
+## 2026-08-09 · hub-layering-convention — the doc was already fixed by the commit that opened the contract
+
+**Verdict: clean-pass (bookkeeping-only opening).** Trigger was the rename of the kernel façade class to `PipelexKernel`, which changed exactly one word in `runtime_hub.py`: the class named in `resolve_run_mode_for_boot`'s docstring. The review target needed that same rename — the page names `PipelexKernel.make` in the paragraph under "Which hub does a new symbol belong to?" — and the rename commit had already made it, in the same commit, alongside the code. Nothing was stale by the time the contract was reviewed.
+
+This is a shape the log does not yet have, and it is the **inverse of the fifteenth ack** rather than a repeat of it. There, the contract fired on a region of `runtime_hub.py` the doc has no stake in (file-granular trigger, region-granular staleness). Here the trigger region is precisely what the doc has a stake in, the doc genuinely did have to change, and it changed atomically with the code. The contract opened anyway, because the digest is per-blob and the *ack* lags the commit — not because the coupling misfired. The coupling was right; only the receipt was missing.
+
+That distinction matters for the recommendation running through this log. A content-aware digest — proposed on 2026-07-28 and reinforced four times since — would **not** have suppressed this opening, and should not have: a class name the review target carries is exactly the content such a digest would still see. Unlike the import-churn and comment-churn entries, there is no narrowing that helps here and none should be sought. The residual cost is one ack on a change whose doc half was already done, which is the system working as designed at its cheapest.
+
+Both prescribed mechanical checks were run rather than reasoned about, and both passed. The Enforcement enumeration is clean for the **second consecutive round** after seven rounds of rot — it now names all 15 declared packages, `pipelex.kernel` among them, which is the payoff of that package having been declared in the commit that created it (praised as "the rule applied ahead of a breach" when it landed, and now visible as an enumeration that did not need catching up). Accessor coverage: 34 + 32 public hub symbols, all present. The standing automation candidate — a test asserting the doc names every declared package — remains the right call and remains unbuilt; two clean rounds are not evidence it is unnecessary, only that the last two changes were not the kind that rots it.
+
+One process note, recorded because the pilot's evidence is only as good as its completeness: **the preceding ack has no entry in this log.** The 2026-08-01 forced-DRY ack (Louis, `resolve_run_mode_for_boot` added to `runtime_hub.py`) is present in `.drift/acks/` with a substantial rationale describing two real doc edits, but the mandatory dogfood entry was never written. That is the second recorded instance of the log being skipped while the ack was recorded (cf. the 2026-07-12 backfill note), and both times the ack itself was sound — so the failure mode is specifically the *second* step, the one with no tooling behind it. `drift ack` gates on its verify commands and stages its own file; nothing gates the log entry. If the pilot wants this evidence to be trustworthy, that asymmetry is the thing to fix.
diff --git a/wip/kernel/README.md b/wip/kernel/README.md
new file mode 100644
index 000000000..a2c6e651e
--- /dev/null
+++ b/wip/kernel/README.md
@@ -0,0 +1,8 @@
+# Pipelex kernel — working notes
+
+Extraction of operator-execution semantics out of the interpreter's operator classes into a public, hub-free `pipelex/kernel/` subpackage, with the interpreter re-pointed onto it — zero behavior change, single-sourced semantics, callable on a `RuntimeBoot`-only process with no `.mthds` loaded.
+
+| Doc | What it holds |
+| --- | --- |
+| [`kernel-extraction-plan.md`](kernel-extraction-plan.md) | The execution plan: goal, doctrine, target API sketch, phases 0–3 with checkpoints, decisions, non-goals, gates. **Start here**; its status block is updated at every checkpoint. |
+| [`deferred-follow-ups.md`](deferred-follow-ups.md) | Items surfaced in review and deliberately kept out of this branch's scope, with pick-up-cold context. |
diff --git a/wip/kernel/deferred-follow-ups.md b/wip/kernel/deferred-follow-ups.md
new file mode 100644
index 000000000..8ca93a1bf
--- /dev/null
+++ b/wip/kernel/deferred-follow-ups.md
@@ -0,0 +1,91 @@
+# Kernel extraction — deferred follow-ups
+
+Items surfaced during the plan's engineering review that are deliberately **not** in this branch's scope. Each carries enough context to pick up cold, and stays here once resolved elsewhere — marked done, rewritten to say what actually landed and what it changes for the plan.
+
+## ✅ KF-1 — Tree-wide mechanical ban on importing from `pipelex.exceptions` in runtime-layer packages — DONE
+
+**What landed.** Done on `dev` (#1080) and merged into this branch — and it went in *tree-wide first* rather than kernel-first, which inverts the dependency this item recorded. `tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py` AST-walks every package declared in `RUNTIME_LAYER_PACKAGES` and fails on any reference to the aggregate: module-level or function-local, absolute or relative, plus any bare string naming it — the `import_module` / `__import__` / `mocker.patch` shape, which no import node records and which this item had not asked for. The feared sweep was empty (the vendor-adapter cleanup had already fixed the only violators), so the gate hard-blocks from day one; the scoping decision came out as predicted — the aggregate stays a legitimate public surface *outside* the runtime layer, and only the layer whose closure it would silently widen is banned. `docs/contribute/hub-layering.md`'s aggregate section now states the rule as mechanical rather than prose.
+
+**What it changes for this branch.** The gate's domain *is* `RUNTIME_LAYER_PACKAGES`, so task 0.1a's declaration of `pipelex.kernel` puts the kernel under it with no kernel-specific test to write — which is why task 0.1c shrank to its prose half. Its negative control survives with a different job: the gate resolves each declared entry to files and silently yields nothing when the path does not resolve, so a mis-declared package is covered by *zero* modules without complaining. That is the "an undeclared package is unpoliced" hazard in a new shape, and the control is what proves the declaration actually bought coverage.
+
+## KF-2 — A library-free caller has no way to mint a `Concept` for its own class
+
+**Surfaced by** writing task 1.7's tests. `llm_object` takes a `concept: Concept` alongside `output_class`, which is the right shape — the kernel must not do a registry hop. But on a process with zero `.mthds` loaded, the only concept a caller can build through a public factory is a native one (`ConceptFactory.make_native_concept`), because everything else resolves through a loaded library. So a caller handing over its own `StuffContent` subclass pairs it with `Native.Anything`, which is what both the unit tests and the boot-contract test do.
+
+**Why it is not a bug today.** For a kernel-only caller the concept is metadata on the produced `Stuff`; nothing in the LLM kernel ops reads it, and nothing answers a compatibility question about it (see the 0.1e vacuity deviation in the plan). The pairing is *loose*, not wrong.
+
+**Why it is deferred rather than fixed here.** The fix is a caller-facing memory-boundary concern, and Phase 3 is where that boundary gets shaped for real (3.1 `shape_inputs`, 3.2 result extraction). Adding a concept-minting factory in Phase 1 would be designing that surface from one test's convenience rather than from the caller experience Phase 3 defines. Revisit at 3.2: if result extraction stays typed on the class, this may need nothing at all; if it keys on concepts, a library-free minting path becomes load-bearing and should be designed then.
+
+## KF-3 — `LLMPromptBlueprint.make_llm_prompt` is now production-dead, held up entirely by its tests
+
+**Surfaced by** the Checkpoint-A cold review, which reported the narrower symptom: the `log.verbose(f"User text with {output_concept_ref=}:\n {user_text}")` diagnostic inside it no longer fires on a live run. That is true, but it is a consequence, not the finding. Verified the real shape: `make_llm_prompt` is defined at `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:63` and called from **tests only** — 38 call sites across `tests/integration/pipelex/pipes/llm_prompt_inputs/` and `tests/unit/pipelex/pipe_operators/pipe_llm/`, and zero in `pipelex/`. The re-point is what killed it: `PipeLLM._live_run_operator_pipe` now calls `to_prompt_content()` and hands that to the kernel, so the blueprint's own assembly method is bypassed.
+
+**Why it is not a bug today.** The method still works and its tests still pass — they are simply testing a path production no longer takes. The equivalent production path is `LlmPromptContent` in the kernel, which those same behaviors are exercised through by the re-pointed interpreter suite. So there is no coverage cliff, only a duplicate.
+
+**Why it is deferred rather than fixed here.** Two reasons, and the second is the load-bearing one. First, deleting a method plus re-homing 38 test call sites is a substantial change inside a PR whose contract is *zero behavior change* — it would make the diff much harder to read against exactly the claim reviewers need to check. Second, and more importantly, **Phase 2 decides the question for us**: `LLMPromptBlueprint` is still a live field on `PipeLLM` (`llm_prompt_spec`, which the operator reads through `to_prompt_content()`), and the img-gen blueprint shares its reference-extraction shape, so what remains of the blueprint after every operator is re-pointed is not knowable yet. Deleting now risks deleting the wrong half. Revisit at the end of Phase 2, when the blueprint's surviving role is settled: at that point either the method is genuinely dead and goes (with its tests re-pointed at `LlmPromptContent`), or it has re-acquired a caller and stays.
+
+**Scope note, because this item is about a method and not a class.** What is production-dead is `make_llm_prompt`, the assembly method — *not* `LLMPromptBlueprint` itself, which `PipeLLM` holds as a field and which parse-and-validate still needs. An earlier revision of this paragraph named `PipeStructure` as the blueprint's remaining consumer. That was never true on any branch, including `dev` before this work: `pipe_structure.py` has never referenced `LLMPromptBlueprint`. Whoever picks this up should look at `PipeLLM`, and should be deleting one method, not a model.
+
+**If the diagnostic itself is wanted back sooner** — independent of the above — it is a one-line addition in `run_llm_text`/`run_llm_object` in `pipelex/kernel/llm_ops.py`. It was dropped deliberately (recorded under the plan's Deviations: moving it meant either duplicating it or carrying a log-only parameter across the layer boundary), and no one has asked for it; the kernel would log without the `output_concept_ref` the old line carried, since the text arm has no concept ref to name.
+
+## KF-4 — Two `TestClass`es per module in the moved reference-type tests
+
+**Surfaced by** the Checkpoint-A cold review. `tests/unit/pipelex/kernel/test_document_reference.py` holds both `TestDocumentReference` and `TestDocumentReferenceKind`; `test_image_reference.py` has the analogous split. The repo's pytest standards say, twice and in caps, never to put more than one `TestClass` in a module.
+
+**Why it is deferred rather than fixed here.** It is pre-existing — both files moved at 97% similarity with only the import line changed, so the violation was inherited, not introduced. And fixing it *now* has a specific cost that will not apply later: splitting each file into two destroys git's rename detection, turning a reviewable "this moved verbatim" into a delete-plus-add in a PR whose entire claim is that the move is behavior-preserving. That is a bad trade in this PR and a free change in any later one. Do it as a standalone tidy after this series lands — it is mechanical, and `.test_durations` will need the same node-id sweep the plan already records for Phase 2 moves.
+
+## KF-5 — What kernel results do at a serialization boundary is a Phase-3 question
+
+**Surfaced by** Codex on PR #1081, as a P1 against `LlmObjectResult.content`: the field is annotated with the base `StuffContent`, so pydantic v2 serializes it by the annotation and a `NumberContent(number=3)` dumps as `{}`.
+
+**The behavior is real; the framing as a new defect is not.** Verified empirically, and the decisive comparison is `Stuff.content` — the codebase's canonical polymorphic content holder, annotated identically, and the one that genuinely crosses Temporal boundaries today:
+
+```
+Stuff.content plain model_dump : {}
+Stuff.content serialize_as_any : {'number': 3}
+Stuff kajson round-trip type : NumberContent 3
+```
+
+So the kernel result is behaving exactly like the type it mirrors, and the project's answer at both sites is already in place: `kajson` (which records the class and reconstructs it) is what actually crosses process boundaries, and `model_dump(serialize_as_any=True)` covers a one-off dump. There are **zero** `SerializeAsAny` annotations in the tree — adding one here alone would introduce a pattern that exists nowhere else and would make the kernel result inconsistent with `Stuff`.
+
+**Why nothing is changed beyond a docstring.** Nothing serializes `LlmObjectResult` or `LlmTextResult` today: they are built in `llm_ops.py` and unwrapped inline by `PipeLLM`/`PipeStructure`, and there is no `model_dump`/`kajson` call anywhere in `pipelex/kernel/`. Fixing a corruption on a path no caller takes is guarding an impossible scenario. What *was* added is a note in the module docstring, because the kernel is aimed at programmatic callers and "call `model_dump()` on the result you were handed" is a plausible caller mistake in a way it is not for an internal type.
+
+**When it becomes real.** Phase 3 shapes the caller-facing boundary (3.1 `shape_inputs`, 3.2 result extraction). If kernel results are ever handed across a process, API or cache boundary there, this is the moment to decide deliberately — and the answer should almost certainly be "serialize with `kajson`, like everything else that crosses", not a bespoke annotation on one field. Revisit at 3.2 alongside KF-2, which is the same boundary seen from the input side.
+
+## KF-6 — `StructuringPath` owns three quarters of the tracer's `structuring_path` vocabulary
+
+**Surfaced by** the PR #1081 arbitration pass, reviewing the re-pointed operators for behavior parity. `StructuringPath`'s docstring calls itself "the tracer's vocabulary, owned here rather than at each caller", but `PipeStructure` writes a bare `"structure"` into the same `execution_data["structuring_path"]` key (`pipelex/pipe_operators/structure/pipe_structure.py:172`), and that value has no enum member. So the key the tracer consumes is fed from an enum on one path and a string literal on another.
+
+**Why it is not a bug today.** The literal is pre-existing — it read `"structure"` on `dev` too, and this branch did not touch it. The consumer chain is `dict[str, Any]` end to end (`_register_execution_data` → `GraphTracerManager.register_execution_data` → `node_data.execution_data`), and `StructuringPath` is a `StrEnum`, so both forms serialize to the same JSON string and nothing downstream can tell them apart. Verified: no test data, snapshot or renderer keys on the value.
+
+**Scheduling note — this has no trigger unless one is added.** An earlier draft said "when Phase 2 re-points `PipeStructure` fully, the answer falls out". Phase 2's task list (2.1–2.5) has no `PipeStructure` task, and the plan's own Deviations argue *against* routing it through `run_llm_object`. So nothing currently schedules this. Fold it into whichever Phase-2 task touches `PipeStructure`'s execution data, or settle it at Phase 3 when the kernel docs page has to describe the vocabulary. Extra evidence for leaving the value alone: our graph UI removed its Structuring row on the grounds that `structuring_path` never carried information, so no renderer branches on it in any repo.
+
+**Why it is deferred rather than fixed here.** The right fix depends on a question Phase 2 answers, not this PR: is `"structure"` a *fourth kernel structuring path*, or a pipe-level label that merely shares a dict key? Today it is the latter — `PipeStructure` calls `generate_object_content` directly and builds its own execution data, so the kernel never produces `"structure"` and adding the member now would put a value into a "what the kernel op did" type that no kernel op can return. When Phase 2 re-points `PipeStructure` fully, the answer falls out: either it starts flowing through a kernel entry point that legitimately returns a fourth path (add the member, drop the literal), or it stays a caller-side label (narrow the enum's docstring to say it names the *LLM* paths, not the whole key). Cheap either way; wrong to guess now.
+
+## KF-16 — The model-derived prompting style is obsolete and should become an explicit choice
+
+**Numbered 16, not 7, deliberately.** This item lands on the *first* PR of a three-PR stack, but the stacked Phase 2 and Phase 3 PRs already add KF-7 through KF-15. Taking the next free number instead of the next sequential one keeps every one of those entries — and the cross-references to them in the plan — exactly as written, so folding this in churns neither of the PRs above it. The gap below is theirs to fill.
+
+**Surfaced by** folding the parity-gaps track's Phase 2 into this stack. That plan listed a gap 2.2 — *"`PipelexKernel.llm_object` renders under the wrong model's prompting style"* — and called it a wrong value. **Re-verified against this branch: that was overstated, and nothing here is broken.**
+
+The façade takes one explicit `model`, which wins `resolve_llm_setting_for_object`'s first rung, so the style is derived from that same setting. That is what an interpreted run derives for a pipe naming only a text model. The two agree for every call this form can express; the divergence needs a pipe naming *both* models, which the façade has no way to say. So 2.2 is the same **narrowness** as the `llm_text` widening that did land here — not a defect.
+
+**Why it is deferred rather than widened.** Giving `llm_object` a second model choice means building the two-setting derivation that the whole mechanism is slated to lose. The owner's call (2026-08-03): deriving the prompting style from the model dates from when models were genuinely sensitive to prompt shape, which no longer holds. The target is an **explicit caller/author-chosen style defaulting to XML**, with the model-derived path removed — which deletes the derivation outright rather than teaching another caller to reproduce it.
+
+**Where the work is written up.** `wip/prompting-style/README.md` — current mechanism, why it goes, target design, open questions (where the choice lives, what happens to `prompting_target`, whether it needs an MTHDS surface and therefore an `mthds/` spec change), and the measured three-case table behind the "not a defect" verdict.
+
+**Recorded in code** as a docstring block on `PipelexKernel.llm_object`, carrying the trap: do *not* "fix" this by deriving the style from an object-only resolution — that would introduce the divergence rather than close it.
+
+## KF-17 — An empty-string model choice falls through to the deck default instead of failing
+
+**Surfaced by** cubic on PR #1081, against `resolve_llm_setting_for_text` / `resolve_llm_setting_for_object` in `pipelex/kernel/llm_ops.py`.
+
+**The gap.** Both resolvers pick the first choice by truthiness — `llm_choice or model_deck.llm_choice_overrides.for_text or model_deck.llm_choice_defaults.for_text`. The parameter is typed `LLMModelChoice | None`, so `is not None` is the check the type describes. The two differ for exactly one value: `""` is falsy, so `llm_text(model="")` runs against the deck default rather than raising.
+
+**Why it is deferred rather than fixed here.** Three reasons, and the first is decisive.
+
+- **It is not this PR's code.** The chain is verbatim what `pipe_llm.py` has on `dev` (`llm_for_text_choice or model_deck.llm_choice_overrides.for_text or …`). The extraction moved it; it did not write it.
+- **There is no divergence.** The interpreter now calls these very functions, so both readers resolve identically by construction. Changing the rung would change both together — this is not a parity gap, which is the bar the surrounding track set.
+- **Every authored path already rejects it.** `""` reaches a resolver only from a direct Python call. Through pydantic — which is how a `.mthds` model choice, a deck default, and a deck override all arrive — the `parse_model_reference` validator raises `ModelReferenceParseError: Model reference cannot be empty`. The remaining hole is `PipelexKernel.llm_text(model="")` in hand-written code.
+
+**What settling it would take.** Not a one-line swap: the object resolver has three rungs, and a faithful `is not None` version of a mixed None/falsy chain reads considerably worse than the `or` it replaces. Worth doing as part of a deliberate pass over model-choice validation — where the real question is whether `LLMModelChoice` should reject `""` at the type boundary once, instead of every consumer re-checking — rather than as a spot fix in a resolver that is only passing the value along.
diff --git a/wip/kernel/kernel-extraction-plan.md b/wip/kernel/kernel-extraction-plan.md
new file mode 100644
index 000000000..640042ad8
--- /dev/null
+++ b/wip/kernel/kernel-extraction-plan.md
@@ -0,0 +1,223 @@
+# Pipelex kernel extraction — `pipelex/kernel/`
+
+## Status block (update at every checkpoint)
+
+- **Current phase:** **Phase 1 COMPLETE — CHECKPOINT A passed. PR #1081 is open against `dev` and must NOT be merged** (the series is stacked: 1/3 here, Phase 2 as 2/3, Phase 3 as 3/3). Branch `refactor/Kernel`, off `dev` with `dev` merged in at `221b8ee0b`. Phase 0 is `23276cecd`, Phase 1 tasks 1.1–1.6 are `3a11d113a`, task 1.7 is `1e6bb1ef2`; three review-driven commits follow (`b7c15aec8`, `9a446e9c5`, `c0815cf7f`). Phase 2 is untouched.
+- **Gates at head (`c0815cf7f`):** `make agent-check` **green**, full `make agent-test` **green**, `make drift-check` **green** (`hub-layering-convention` acked twice — the fix below reopened it). CI green on every check. Two gate failures surfaced at this checkpoint and both are fixed — see "What Phase 1 taught Phase 2" below. Note for the record: this doc once claimed `make agent-check` was green at `3a11d113a`. It was not; the keyword-only gate was red there.
+- **One real bug was found by review and fixed — the PR's only behavior change.** `PipelexKernel.make` minted a LIVE `CogtRunParams` on a keyless boot (`needs_inference=False`), bypassing the forced-DRY coercion `PipeRunParamsFactory` applies. Reachable, not hypothetical: `run_mode` alone gates mocking, so the call reached a real provider, and `needs_inference=False` means backends load *leniently* rather than credential-free. The hazard was the **default** — `PipelexKernel.make(user_id=…)` names no mode. Root cause is this branch's own doing: the factory's docstring called itself "the single writer" of `run_mode`, which stopped being true when the kernel became a second run-params factory. The rule now lives once in `runtime_hub.resolve_run_mode_for_boot`, called by both factories, pinned by a third arm on the D4 contract module. **Phase 2 lesson: any new kernel-side factory of run-scoped state owes the same audit — ask which process-wide invariants the pipe tier applies that the kernel tier now skips.**
+- **Review record:** a cold `/code-review` (no inherited context) found no correctness bug, no layering violation and no stale reference, and confirmed the three past bug fixes in this code (templating-style mutation, the multi-image/document dict-key collision, LLM-error cause unwrapping) preserved verbatim. Bots: Greptile 5/5 on head; cubic found the forced-DRY bug above; Codex raised one item (polymorphic serialization of `LlmObjectResult.content`) four times, independently verified and rejected twice — see KF-5.
+- **Next action:** Phase 2, starting at task 2.1. **Read "What Phase 1 taught Phase 2" below first** — it lists four move-consequence classes and two traps that are not obvious from the task list, one of which (2.5) makes that task not a move at all.
+- **Open decisions:** none blocking. The kernel construction shape (0.2), structure-prompt provenance and the deferred runtime-boot orchestrator question are settled under Decisions; seven deviations from the plan's letter are recorded there. Deferred items are KF-1..KF-6 in [`deferred-follow-ups.md`](deferred-follow-ups.md).
+
+### What Phase 1 taught Phase 2
+
+Read this before starting 2.1. **Moving code has consequences no compiler reports**, and Phase 1 hit four classes of them. Two failed a gate loudly; two are silent and only one of those is caught by CI at all.
+
+**Caught by a gate (will fail your build):**
+
+1. **Dead subject grants.** `subject_grants.toml` still granted positional subjects for defs the move deleted (`pipe_operators/llm/helpers.py::get_output_structure_prompt`) or relocated (the `LLMPromptBlueprint._extract_direct_*` methods). The convention's staleness check is *symmetric* — a grant whose def moved or vanished hard-fails until the registry is cleaned. Remove rather than re-grant: kernel replacements are fully keyword-only, the package's stated zero-grants doctrine. **Sweep the grants for every operator you move.**
+2. **Dead paths in `.test_durations`.** Moved test modules leave the committed shard-balancing artifact pointing at their old home, and `tests/unit/repo/test_test_durations_paths.py` catches it. Rewrite the node ids' path prefix rather than regenerating: the tests moved verbatim, so their recorded durations are still accurate, and `make store-test-durations` would churn every timing in the file for no gain. New modules simply have no entry, which pytest-split treats as average duration.
+
+**Silent (nothing tells you):**
+
+3. **Under-the-hood docs naming moved files.** Phase 1 broke a file path in `docs/under-the-hood/image-handling-in-llm-prompts.md` and nothing noticed — no drift contract has a trigger glob over `pipelex/pipe_operators/**` or `pipelex/kernel/**`, and `mkdocs build --strict` does not validate inline code spans in a table. Grep `docs/` for every path you move. Already known for Phase 2: `docs/under-the-hood/dry-run-mock-generation.md` names `pipe_operators/compose/structured_content_composer.py`, a task-2.4 target, and `docs/under-the-hood/architecture-overview.md` still presents `pipe_operators/` as the sole home of operator behavior.
+4. **`docs/errors/` pages carry the defining module path.** The generator emits ``| Defined in | `<module>` |`` onto each page, so moving a `PipelexError` subclass makes its committed page stale — and `make generate-error-pages` runs in neither `make check` nor CI. Phase 1 escaped this only by luck: `LLMPromptBlueprintValueError` and its replacement `PromptContentError` are bare `ValueError`s, so `tests/data/errors/error_identity.txt` never moved. Phase 2 moves error classes that *are* `PipelexError`s (search, img-gen, compose, extract). Two chores follow: regenerate the pages, and note that the generator's `_SUBSYSTEM_SECTIONS` has no `kernel` key, so a moved error currently falls through to the `platform-and-tooling` fallback under a humanized "Kernel" heading instead of "Execution & runtime".
+
+**Two traps that are not move-consequences:**
+
+5. **The execution-data coverage test cannot see module-level functions.** `tests/unit/pipelex/pipe_machinery/test_execution_data_coverage.py` walks only `self.<method>(...)` call chains to find each pipe's `_register_execution_data` call. A kernel function is invisible to it. Phase 1 survived because that call stayed inline in `pipe_llm.py`; **every Phase-2 operator must keep `_register_execution_data` on its own `self.*` chain**, or the test fails for that pipe.
+6. **Every operator has tracer intermediates, and Phase 2's task list does not mention result envelopes.** The typed result envelope (`LlmTextResult`/`LlmObjectResult`/`StructuringPath`) was Phase 1's real design work beyond the ops, and each remaining operator registers its own execution data with the same kind of intermediates. Decide per operator whether it gets an envelope or the interpreter keeps computing them — but decide deliberately, because "the tracer rides the same functions" is the property that stops the two callers drifting.
+
+### Cold-start: where the code is
+
+`pipelex/kernel/` now holds these modules:
+
+| module | what is in it |
+| --- | --- |
+| `__init__.py` | Doctrine only, no re-exports: layering, definition-site imports, top-level imports, concept-resolution routing, memory contract, keyword-only/zero-grants, boot contract. |
+| `pipelex_kernel.py` | `PipelexKernel` — `__init__`, `make()`, `make_step_metadata()`, and the `llm_text` / `llm_object` façade methods. Holds only the run-level `JobMetadata` and `CogtRunParams`. |
+| `prompt_references.py` | `ImageReference(Kind)` and `DocumentReference(Kind)`, **moved** out of `pipe_operators/` (they could not stay there: a runtime-layer prompt-content model may not import an interpreter-layer type). All importers re-pointed; the two unit-test modules moved to `tests/unit/pipelex/kernel/`. |
+| `llm_prompt_content.py` | `LlmPromptContent` (+ `make_from_text`) and `assemble_llm_prompt` — the whole former `LLMPromptBlueprint.make_llm_prompt` body, images/documents/registry/placeholders included. |
+| `llm_results.py` | `StructuringPath` StrEnum, `LlmTextResult`, `LlmObjectResult`. |
+| `llm_ops.py` | `resolve_llm_setting_for_text`, `resolve_llm_setting_for_object`, `derive_templating_style`, `derive_structure_prompt`, `generate_object_content`, `store_result`, `run_llm_text`, `run_llm_object`. |
+| `exceptions.py` | `PromptContentError(ValueError)` — the former `LLMPromptBlueprintValueError`, moved with the code that raises it. |
+
+Interpreter side: `LLMPromptBlueprint` keeps its fields, `required_variables()` and its `make_llm_prompt` **signature** (its many test call sites depend on it) but now maps down through a new `to_prompt_content()` and delegates; `PipeLLM._live_run_operator_pipe` calls `run_llm_text` / `run_llm_object` and its `_llm_gen_object_stuff_content` is gone; `PipeStructure` calls `resolve_llm_setting_for_object`, `derive_structure_prompt`, `generate_object_content` and `store_result` (not `run_llm_object` — see Decisions); `pipe_operators/llm/helpers.py` (`get_output_structure_prompt`) is deleted.
+
+### Verified in Phase 0 (do not redo)
+
+All three negative controls were run and each failed as intended, then was reverted: deleting the `pipelex.kernel` entry fails `test_the_pipelex_kernel_stays_declared`; a `pipelex.exceptions` import in a kernel module fails the aggregate gate; an `interpreter_hub` import in a kernel module fails both the closure test and the static guard.
+
+### What task 1.7 landed
+
+Three test modules, and one of them turned out to close a gap the tree did not previously cover:
+
+| module | what it pins |
+| --- | --- |
+| `tests/unit/pipelex/kernel/test_llm_object_kernel.py` | The two kernel-only arms, through the façade in DRY. Structure-prompt provenance is three cases, not two: derived-by-default, supplied-text-overrides, and **empty-string-overrides-with-nothing** — the sentinel is `is not None`, so a rewrite to `structure_prompt or await derive_structure_prompt(...)` would silently turn the third back into a derivation and only that case would notice. Plus the memory contract, asserted as "the *returned* memory carries the result" and deliberately **not** as `result.memory is memory`: pinning today's aliasing would make the change the contract exists to permit look like a regression. |
+| `tests/unit/pipelex/kernel/test_kernel_boot_contract.py` | The boot contract, permanently. Subprocess, `RuntimeBoot.make(needs_inference=False)`, `PipelexKernel.make(run_mode=DRY)`, **both** façade calls (`llm_object` and `llm_text` — they share almost nothing below the façade, so covering one leaves the other's closure unproven), typed results asserted — then a `sys.modules` sweep **after** the call, with the usual negative control (`cogt` as an "interpreter package" must fail). |
+| (moved in 1.3) `test_image_reference.py` / `test_document_reference.py` | Followed the reference types into `tests/unit/pipelex/kernel/`. |
+
+**The post-call sweep is a new gate, not a restatement of an old one — verified, not assumed.** Injecting a function-local `from pipelex.pipe_operators.llm.pipe_llm import PipeLLM` into `run_llm_object` leaves `pipelex-dev check-hub-layering` at **exit 0** and the import-closure module at **15 passed**; only the boot-contract test goes red. That is the function-local blind spot both `hub-layering.md` and the kernel's own doctrine warn about, closed mechanically for the first time. `docs/contribute/hub-layering.md` now documents it beside the other three gates.
+
+**The `concept_resolver`-omitted arm was correctly not written** — see the deviation record under Decisions. It does not exist in Phase 1.
+
+## Goal
+
+Pull operator-execution semantics out of the interpreter's operator classes into shared, importable kernel functions under a new public `pipelex/kernel/` subpackage, and re-point the interpreter onto them — **zero behavior change**. Today, what a `PipeLLM` step actually *does* (deck resolution, templating-style derivation, prompt assembly, generation, memory write-back) is only reachable through a fully booted interpreter with a loaded library. After this refactor, operator semantics have **one implementation with multiple callers**: the interpreter's operators, and any programmatic caller — SDK-style embedding, hosts that boot only the runtime layer — invoking them directly on a `RuntimeBoot`-only process with zero `.mthds` loaded.
+
+This completes the runtime/interpreter layering arc: the hub split (#1062/#1064), layer placement (#1071), concept purity (#1072), the boot split that created `RuntimeBoot` (#1073), the templating-style threading fix (#1074), and the concrete-class object path (#1076). It is a pure refactor, valuable on its own: single-sourced operator semantics are what prevent two callers from drifting apart.
+
+## Doctrine
+
+- **Layering.** The caller-facing kernel API is hub-free: an explicit `PipelexKernel` object and explicit arguments, never an ambient lookup. Kernel *internals* may use `pipelex.runtime_hub` — never `pipelex.interpreter_hub`. This is a mechanically enforced rule (the hub-layering guard plus the runtime-layer import-closure test), but #1071's history shows the guard does not hold the line "for free" — see the four sub-tasks under 0.1, which exist because each one closes a hole that episode demonstrated: an *undeclared* package is unpoliced rather than neutral (both guard rules filter through the layer declaration, so omission makes the guard quieter); a declaration with no test pinning it is a comment; a **cross-layer re-export aggregate defeats the guard entirely** (vendor adapters once pulled the interpreter into a declared-clean runtime package by importing from `pipelex.exceptions` instead of the definition site — a module that re-exports across layers is a layer boundary with the sign filed off; that hole is the one now closed mechanically tree-wide, and the kernel inherits the coverage by being declared); and a function-local import is invisible to the static graph and the closure test at once.
+- **Calls are activity-shaped.** Explicit, serializable-leaning inputs and outputs; `WorkingMemory` threaded explicitly (taken and returned); no hidden shared state. This is a design constraint, not a deliverable: it keeps a future Temporal-activity wrapping a re-decoration rather than a rewrite. The memory contract, stated so both caller classes read the same thing: a kernel call may mutate the memory it is passed and returns it — callers must treat the returned memory as the result and must not rely on aliasing of the argument, because inline execution aliases the two today and a serialization boundary will not.
+- **Functions carry the semantics; the class is a façade.** Module-level kernel functions hold the shared implementation. The `PipelexKernel` class is a thin ergonomic façade over them, holding the per-run state a caller would otherwise thread through every call. The interpreter's operators call the functions directly.
+- **The kernel API is fully keyword-only — zero subject grants.** The governing bar, stricter than the general rubric in [`docs/contribute/keyword-only-arguments.md`](../../docs/contribute/keyword-only-arguments.md): only the first parameter may be positional, and strictly only when it is obviously the subject — named in the function, or as unmistakable. Nothing in the kernel clears that bar: `llm_text` and `llm_object` name what they *produce*, and `memory` is threaded state (taken and returned), not the operand. So `pipelex/kernel/` records no entries in `subject_grants.toml`, every call site names every argument, and `make fix-keyword-only` mechanically produces exactly this form — there is no ordering trap. Any future kernel def that wants a positional subject must clear the stated bar in review first, not in the registry.
+- **Boot contract: `RuntimeBoot.make()`** ([`pipelex/runtime_boot.py`](../../pipelex/runtime_boot.py)). Every kernel call must be servable on the runtime-only composition root, with no interpreter constructed and no library loaded. The import-closure test guards this structurally; a live smoke run proves it dynamically.
+- **Zero behavior change.** The full `make agent-test` suite is the gate at every checkpoint — no *behavioral* test rewrites. Import repoints, module moves and `mocker.patch` target updates are expected and are not a red flag: Phase 1 repointed several test modules' imports, moved two, and rewrote patch targets in `test_cogt_run_params_carrier.py` when the code they patch moved.
+
+## Target caller experience
+
+The sketch below is the API shape to preserve while the internals get extracted for real out of `pipe_llm.py` (which is where the deck chain, style derivation, and prompt assembly currently live). Every parameter is keyword-only, including `memory`. Two contracts the sketch elides for brevity, stated here because they are load-bearing: `user` and `system` are prompt *templates* rendered against `memory` inside the kernel — template references are how images and documents enter the prompt (task 1.3's assembly functions do the rendering) — and the return value is a small typed result carrying the updated memory plus the rendered prompts, the resolved model setting, and the structuring path taken, because the interpreter's execution-graph tracer consumes those intermediates after generation and recomputing them outside the kernel would mean a second assembly path. Expect the signatures to grow explicit keyword parameters for setting overrides and output multiplicity as tasks 1.1–1.4 extract the real thing; the shape that must survive is fully-named arguments over explicit state. One limit the sketch does not show, now that Phase 1 has landed: **the façade methods carry no image or document references at all** — both hardcode `LlmPromptContent.make_from_text(...)`, and a caller needing references drops to `run_llm_text` / `run_llm_object` with an `LlmPromptContent` it builds itself. Phase 2 brings image-bearing operators (2.1 `PipeExtract`, 2.2 `PipeImgGen`), so decide there whether `PipelexKernel` grows reference-carrying parameters or stays a deliberately text-only convenience. The sketch above already reflects one growth the plan did not anticipate: folding the parity-gaps track in widened `llm_text` to take an optional `concept` and `output_class`, and made `model` optional too, so the façade can express what the op beneath it always could — see the 2.1 entry in that track and the `llm_text` docstring for why each of the three has to be reachable.
+
+```python
+class PipelexKernel:
+ """Façade over the module-level kernel ops; holds per-run state."""
+
+ def __init__(self, *, job_metadata: JobMetadata, cogt_run_params: CogtRunParams): ...
+
+ @classmethod
+ def make(cls, *, run_mode: PipeRunMode = PipeRunMode.LIVE, user_id: str) -> "PipelexKernel": ...
+
+ async def llm_text(
+ self,
+ *,
+ memory: WorkingMemory,
+ model: LLMModelChoice | None = None,
+ user: str,
+ system: str | None = None,
+ concept: Concept | None = None,
+ output_class: type[StuffContent] | None = None,
+ result: str,
+ ) -> LlmTextResult:
+ """The semantics of a PipeLLM step with a Text output.
+
+ `user`/`system` are templates rendered against `memory`; the result
+ carries the returned memory plus the rendered prompts and resolved
+ setting for the caller's tracing needs.
+ """
+
+ async def llm_object(
+ self,
+ *,
+ memory: WorkingMemory,
+ output_class: type[StuffContentT],
+ concept: Concept,
+ model: LLMModelChoice,
+ user: str,
+ system: str | None = None,
+ structure_prompt: str | None = None,
+ result: str,
+ is_multiple_output: bool = False,
+ fixed_nb_output: int | None = None,
+ ) -> LlmObjectResult:
+ """The semantics of a PipeLLM step with a structured output.
+
+ The concrete pydantic class is handed over directly — no registry lookup,
+ and no runtime schema-to-class reconstruction, because the class exists.
+ The structure prompt is derived from `output_class` by default (same
+ config template as today); pass `structure_prompt` to override it.
+ """
+```
+
+## Phase 0 — scaffolding
+
+- [x] 0.1 Create the `pipelex/kernel/` package skeleton: façade module (the `PipelexKernel` class, thin over module-level functions) plus per-domain ops modules (llm first; extract/img/search/compose/func come in Phase 2), with docstring doctrine stating the layering role. Then, in the **same commit**, the four guard declarations the doctrine section explains:
+ - [x] 0.1a Declare `pipelex.kernel` in `RUNTIME_LAYER_PACKAGES` ([`pipelex/cli/dev_cli/commands/hub_layering_guard.py`](../../pipelex/cli/dev_cli/commands/hub_layering_guard.py)) — an undeclared package is unpoliced, not neutral. In the same commit, add `pipelex.kernel` to the runtime-layer enumeration in [`docs/contribute/hub-layering.md`](../../docs/contribute/hub-layering.md): that doc is the boundary's specification, it claims every top-level package is accounted for, and the `hub-layering-convention` drift contract triggers on the guard file — so the doc review is mandatory either way, and same-commit is this task's own discipline applied to the doc half.
+ - [x] 0.1b Pin that declaration with a test, mirroring `test_the_measured_clean_packages_stay_declared` ([`tests/unit/pipelex/cli/dev/test_hub_layering_guard.py`](../../tests/unit/pipelex/cli/dev/test_hub_layering_guard.py)), and run the negative control: delete the entry, watch it fail, restore it.
+ - [x] 0.1c Write the no-aggregate rule into the kernel's docstring doctrine: import from definition sites only, never from `pipelex.exceptions` or any other cross-layer re-export, and never let `pipelex/kernel/__init__.py` become one (consistent with the repo-wide no-re-exports rule, but stated here because for this package it is a layering property, not a style one). The mechanical half needs no work here: KF-1's tree-wide gate ([`tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py`](../../tests/unit/pipelex/test_runtime_layer_exceptions_aggregate_gate.py)) walks every package in `RUNTIME_LAYER_PACKAGES` and fails on imports and bare strings alike, module-level or function-local, so 0.1a's declaration buys it — including, for this one hazard, the function-local blind spot 0.1d records. Keep the negative control, which now proves the *coupling* rather than the test: the gate silently covers zero modules when a declared path does not resolve, so add a banned import to a kernel module, watch that gate fail, remove it.
+ - [x] 0.1d Add a kernel entry point to `RUNTIME_LAYER_ENTRY_POINTS` in the closure test ([`tests/unit/pipelex/test_runtime_layer_import_closure.py`](../../tests/unit/pipelex/test_runtime_layer_import_closure.py)), with a negative control. Remember its blind spot: it only covers module-level imports — a function-local import is invisible to it *and* to the static graph, so reviews must watch for those by hand.
+ - [x] 0.1e **Concept-resolution routing rule.** Kernel run paths answer concept compatibility with the two *pure* tiers that #1072 created — `Concept.are_compatible_by_declaration` (no registry; a caller without a loaded library supplies its own `concept_resolver`, or omits it where no `refines` crosses a package boundary) and `are_structure_classes_compatible` (takes resolved types) — and never call `ConceptLibrary.is_compatible` or `ConceptProviderAbstract.get_structure_class`, which is where resolution and therefore the ambient registry read legitimately live. Passing the concrete class alongside the concept is the preferred shape, as in the target sketch above.
+- [x] 0.2 Kernel construction shape: `PipelexKernel.make()` mints `JobMetadata` + `CogtRunParams`; decide what the instance holds vs what stays per-call. Two constraints on that decision are settled now. First, the instance holds only identity and run-scoped state (the run-level `JobMetadata`, the `CogtRunParams`); anything derived from config or the model deck — resolved settings, prompting style — is computed per-call and never cached on the instance, exactly the deliberate per-run derivation `pipe_llm.py` documents today, because cached derived state is hidden shared state and breaks per-call `run_mode` variation. Second, the run-level metadata the instance holds is not what a step runs under: each call mints a per-step copy via `copy_with_update` (per-step `pipe_run_id`), matching the interpreter's pass-down-a-modified-copy pattern, so trace and usage attribution stay per-step.
+
+## Phase 1 — LLM vertical slice (the meat)
+
+Each item is a fragment of `PipeLLM` to extract into a kernel function for real:
+
+- [x] 1.1 **Deck-resolution chain**: pipe choice → deck `llm_choice_overrides` → `llm_choice_defaults`, for_text and for_object (including object-falls-back-to-text), → `LLMSetting`. Out of `pipe_llm.py`, into a kernel function.
+- [x] 1.2 **Templating-style derivation**: setting/model → `prompting_target` → configured style.
+- [x] 1.3 **Prompt assembly**: the full `make_llm_prompt` path (text, images and their `ImageRegistry`, documents as the `[Document N]` substitution dict) as kernel functions, so kernel coverage equals PipeLLM coverage — not just a text-only form. The input shapes need a home and it is not the blueprint: `LLMPromptBlueprint` and its reference types live in `pipe_operators/llm/` and are language-side (blueprints are what `.mthds` parses into), so the kernel cannot import them without breaking the closure. The kernel defines its own runtime-layer prompt-content model (template strings, image/document references over memory) and the blueprint's `make_llm_prompt` becomes a thin mapping onto the kernel functions — the same move `core/` made with `ConceptProviderAbstract`: the semantics migrate to the layer that owns them, the language artifact keeps its parse-and-validate role and maps down.
+- [x] 1.4 **`llm_text` / `llm_object` semantics**: structure prompt (settled — see the decision record below: derived in-kernel from `output_class` by default, optional `structure_prompt` argument overrides), output multiplicity (single / variable list / fixed count), result storage into memory, and the typed result envelope the sketch describes (updated memory + rendered prompts + resolved setting + structuring path), which is what lets the interpreter's tracer ride the same functions instead of keeping a parallel path.
+- [x] 1.5 **Concrete-class object path**: the kernel's object call passes its `output_class` through to `ContentGenerator.make_object` (whose parameter is named `object_class`), which threads it down since #1076 — so no schema-to-class rebuild happens inline when the class is in hand. The schema round-trip stays where it serves the distributed activity boundary; do not remove it.
+- [x] 1.6 **Re-point** `PipeLLM` (and `PipeStructure`, which shares the object semantics) onto the kernel functions. The cut line, stated so nobody has to find it by trial: the interpreter retains blueprint resolution, the library-backed text-vs-object dispatch (`is_compatible` against native Text, `pipe_llm.py`), and its error-context wrapping (`PipeRunError` with the pipe stack — the kernel raises the same cogt-level errors the moved code raises today, and the operator rewraps as it always has); it calls `llm_text` or `llm_object` with resolved values, and the kernel never re-asks the library. Dispatch is the caller's job by construction — the kernel's two entry points are the fork made explicit. One quiet arm belongs on the interpreter's side of that line, cheaper remembered than rediscovered: today `get_output_structure_prompt` returns `None` when the concept's structure class is not in the class registry, and generation proceeds without a structure prompt — the kernel's `llm_object` *requires* `output_class`, so the re-point must keep that no-class arm in the interpreter (it is part of blueprint resolution, not of the kernel's semantics) rather than assume class resolution always succeeds. The zero-behavior-change suite is the backstop; this is the arm it would catch.
+- [x] 1.7 Tests: kernel unit tests (dry mode), naming the kernel-only arms explicitly because the re-pointed interpreter suite structurally cannot reach them — the structure-prompt argument supplied vs derived-by-default, the `concept_resolver`-omitted arm (**planned, then correctly not written** — Phase 1's ops answer no concept-compatibility question at all, so the arm has nothing to assert; see the 0.1e vacuity deviation under Decisions, and do not invent it), and the memory mutate-and-return contract; full `make agent-test` green; and the boot contract proven **permanently**, not once: a committed dry-mode pytest boots `RuntimeBoot.make()` in a subprocess (the closure test's isolation pattern — a suite-level boot already holds the process singletons), loads zero `.mthds`, and asserts a kernel `llm_object` call returns a typed result, with a live smoke script kept as the manual Checkpoint C verification. Note for whoever writes that test: it is the first real caller of a runtime-only boot, and `runtime_boot.py`'s orchestrator-rejection comment explicitly defers the external-interpreter-orchestrator half-application question to that first caller (analysed in `wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`) — settle it or guard it there, don't inherit it silently.
+
+**CHECKPOINT A** — LLM slice extracted and re-pointed; gates green (`make agent-check` + full `make agent-test` + `make drift-check`); cold `/code-review` on the diff; update this doc's status block with decisions taken and cold-start state.
+
+## Phase 2 — remaining operators
+
+Same treatment, one operator at a time, interpreter re-pointed as each lands. Each task includes kernel unit tests for that operator's kernel-only arms — the paths the re-pointed interpreter suite never takes are exactly where the two callers could drift undetected.
+
+- [ ] 2.1 `PipeExtract` → kernel extract ops over the `make_extract_pages` seam, including the page-view handling (`should_include_page_views`, `page_views_dpi`, `max_page_images`).
+- [ ] 2.2 `PipeImgGen` → kernel image ops (single / list).
+- [ ] 2.3 `PipeSearch` → kernel search ops (sourced answer / structured).
+- [ ] 2.4 `PipeCompose` → kernel templating + structured-composition ops.
+- [ ] 2.5 `PipeFunc` → kernel function-call op over the **`PipeFuncExecutorProtocol` seam**, not a bare registry lookup. The executor is pluggable — `run_pipe_func` (live objects) and `run_pipe_func_transported` (serialized request/response via `pipe_func_execution_dtos`) are its two arms — and the kernel op must carry **both arms**. But the kernel never reads `HubSlot.PIPE_FUNC_EXECUTOR`: that slot is applied in `Pipelex.setup`, so it does not exist on a runtime-only boot, and an ambient read would break the boot contract for this one op. Instead the executor enters as an explicit protocol-typed argument — the interpreter passes its hub-resolved one (selected by `pipe_func_config.execution_mode`, `direct` by default), a programmatic caller passes the direct executor or its own.
+
+ ⚠ **This is the highest-risk task in Phase 2, and it is not a move.** An earlier draft of this plan said the protocol "needs a runtime-layer home, since it currently lives in `pipe_operators/func/`", framing it as placement. It is not: the protocol and its DTOs are *typed on interpreter-layer models*. `pipe_func_executor_protocol.py` imports `PipeRunParams`; `pipe_func_execution_dtos.py` imports `PipeRunParams` **and** `LibraryCrate`; `pipe_func_execution_transport.py` imports `get_current_library` / `get_library_manager` straight from `interpreter_hub`, which is a flat layering violation the instant it lands in `pipelex/kernel/`. Both `pipe_run` and `libraries` are interpreter packages. The kernel is clean today *because* it uses `CogtRunParams` and never `PipeRunParams`, and the kernel's own doctrine forbids the usual escape hatch ("if a function-local import seems necessary, the placement is wrong and the type should move instead"). So the real task is **re-typing the protocol off `PipeRunParams`/`LibraryCrate`, or keeping an interpreter-side adapter** — not relocating a file. Moving those two models is far outside Phase 2's scope.
+
+ Three further hazards on this task, none of which any gate catches:
+
+ - **`pipelex/config.py` imports the executor registry**, which defers the protocol under `TYPE_CHECKING` for exactly this reason. If you conclude the deferral is now unnecessary and un-defer it, `pipelex.config` starts loading `pipe_run` and `libraries` — failing every closure test at once, from a module almost everything imports.
+ - **Two external plugin repos import these exact modules**: our Daytona sandbox plugin (executor, DTOs, transport) and our Temporal plugin (in-workflow executor and the PipeFunc activity). They are separate repos, so nothing in this tree's CI sees them.
+ - **A module path is held as a bare string and run via `python -m`** in the Daytona plugin (`"pipelex.pipe_operators.func.pipe_func_transported_entrypoint"`, hardcoded in two clients and again in its Dockerfile). No import error, no type checker, no static gate catches a rename — it fails at runtime inside the sandbox. Grep sibling repos for string-held module paths before renaming anything under `pipe_operators/func/`.
+
+ Also relevant: 2.5 must touch `pipelex/interpreter_hub.py`, which reopens the `hub-layering-convention` drift contract — and this time the review target is genuinely falsified, because `docs/contribute/hub-layering.md` states in several places that the pipe-func accessor is interpreter-layer *because* its protocol lives in `pipe_operators/func/`.
+
+**CHECKPOINT B** — all operators riding the kernel; gates green; this doc updated.
+
+## Phase 3 — memory boundary and run-scoped state parity
+
+- [ ] 3.1 Boundary shaping: kernel `shape_inputs` over the existing `InputShaper` (per-signature specialization is out of scope).
+- [ ] 3.2 Result extraction helpers (main-stuff and named-slot, typed).
+- [ ] 3.3 Per-step `JobMetadata` semantics (per-step `pipe_run_id` minted from the instance's run-level metadata via `copy_with_update`, per the 0.2 constraint) as a kernel duty; optional trace-context wiring so cost/usage reporting reaches parity when a caller provides one. This task must also answer the lifecycle-ownership question it implies: the interpreter's run machinery is what opens and closes usage reporting today, so state who owns that lifecycle for a kernel-driven run. **Parity bar, measured not asserted:** a test runs an equivalent step through the re-pointed interpreter and through direct kernel calls (mock usage) and asserts the two produced `TokensUsageRecord` lists ([`pipelex/reporting/usage_records.py`](../../pipelex/reporting/usage_records.py)) match in shape and count — the list `/execute` returns on `pipe_output.tokens_usages` and durable runs persist as `tokens_usages.json`.
+- [ ] 3.4 Docs: a `docs/` page for the kernel — public-API doctrine, the layering contract, what a programmatic caller may import and how it boots.
+
+**CHECKPOINT C = done** — interpreter operator semantics fully single-sourced in the kernel; smoke run live on it; full gates; this doc updated and the `docs/` page landed.
+
+## Decisions
+
+- **Structure-prompt provenance — SETTLED: derived in-kernel, optional override.** The registry was only ever needed for the concept→class hop, and the kernel's object call already holds the class — so the kernel derives the structure prompt from `output_class` itself (same config template, same `StructurePrinter`, same `is_structure_prompt_enabled` gate as today), and an optional `structure_prompt` argument overrides it for callers who want to supply their own. The interpreter drops `get_output_structure_prompt`'s registry hop and rides the kernel derivation, so both callers produce the same prompt by default — the alternative (prompt as argument only) would have left the derivation outside the kernel and forked the two callers' default behavior, which is the drift this extraction exists to kill.
+- **The deferred runtime-boot orchestrator question — SETTLED: recorded, not guarded.** `runtime_boot.py` deferred the external-interpreter-orchestrator half-application hole to "the first caller of a runtime-only boot", which is now the kernel's boot-contract test. That caller does not trigger it, and not by luck: the gate is only reached when `plugins.boot_orchestrator` is non-`None`, and the test names none — as no kernel caller will, since the kernel's doctrine forbids it from reading `HubSlot` at all and Phase 2's `PipeFunc` op takes its executor as an explicit argument for that reason. The remedy stays unbuilt: both candidates are real machinery (a `HubSlot.is_interpreter_slot` property plus a `honours_interpreter_slots` class attribute, or a widened `build_registrar` signature) bought for a path with still no production caller. Reassess when a runtime-only boot is offered to real callers — that is when naming an orchestrator becomes reachable. Written up in [`wip/boot-split/runtime-boot-external-interpreter-orchestrator.md`](../boot-split/runtime-boot-external-interpreter-orchestrator.md), and `runtime_boot.py`'s comment now points at the settlement rather than at an open question.
+- **Kernel construction shape** (task 0.2) — **SETTLED as implemented.** `PipelexKernel` holds exactly `job_metadata` (run-level, fresh `uuid4` `pipeline_run_id`) and `cogt_run_params`. `make_step_metadata()` mints the per-step copy with a fresh `pipe_run_id` and an explicit `otel_context=None`. Nothing config- or deck-derived is cached.
+
+### Deviations from the plan's letter, taken during Phase 1
+
+- **The deck chain is two functions, not one `resolve_llm_settings`.** `resolve_llm_setting_for_text` and `resolve_llm_setting_for_object` (the latter taking the optional `llm_choice_for_text` that makes its chain one rung longer). A single function returning both settings would have made `PipeStructure` — which resolves only the object setting today — newly resolve the text one too, which is a behavior change on the one gate that matters. Two functions keep each caller resolving exactly what it resolved before, and the chain is still single-sourced.
+- **`PipeStructure` rides the kernel's *pieces*, not `run_llm_object`.** It shares the object semantics — structure-prompt derivation, generation, memory write-back — and calls those four kernel functions. It does **not** share prompt assembly: it has no template of its own and no memory-borne references, it renders one configured `structuring_prompt` template over one input string, and forcing that through `assemble_llm_prompt` would have changed the render context from `{"text": …}` to the whole working memory. That is a real behavior change for a cosmetic gain.
+- **`templating_style` is an explicit argument to `run_llm_text` / `run_llm_object`, not derived inside them.** `PipeLLM` derives it from its **text** setting and uses it on both paths; a kernel that derived from its own setting would silently change the object path's rendering style. The derivation itself (`derive_templating_style`) is single-sourced in the kernel; *which* setting governs is the caller's decision, and it has to be, because a caller can hold two.
+- **One deliberate widening, worth watching in review:** `PipeLLM`'s text path used to wrap only `structure_class(text=…)` in `except ValidationError`. That construction is now inside the kernel call, so the handler wraps the whole call. A `ValidationError` raised elsewhere inside it (prompt assembly, result construction) would now surface as `PipeRunError("Error generating text content in PipeLLM …")` instead of propagating raw. Same error class, same wrap, slightly wider scope.
+- **`assemble_llm_prompt` does not log the assembled user text**; `LLMPromptBlueprint.make_llm_prompt` still does, keeping its `output_concept_ref` parameter (whose only job was that log) so its test call sites are untouched. Moving the log into the kernel would have meant either duplicating it or carrying a log-only parameter across the layer boundary.
+- **The no-class arm task 1.6 told the re-point to keep does not exist, and was correctly dropped.** 1.6's text says the interpreter must retain the arm where `get_output_structure_prompt` returns `None` because the concept's structure class is not in the registry, "rather than assume class resolution always succeeds". The re-point does assume it: both `pipe_llm.py` and `pipe_structure.py` now call `get_class_registry().get_required_subclass(...)` eagerly before dispatch, and the soft `get_class(...) -> None` path is gone with `helpers.py`. That is right, and the plan's premise was a half-reading of the old code: the pre-move object path called `get_required_subclass` unconditionally as the first statement of `_llm_gen_object_stuff_content`, so no run ever survived a missing class — the soft arm only ever suppressed the *structure prompt*, never the failure. The only real change is that the error now raises before prompt assembly instead of after. Recorded because a future reader of 1.6 would otherwise think a required arm was dropped silently.
+- **`PipelexKernel.llm_text` ships as wide as the op beneath it** — `concept`, `output_class` and `model` are optional, defaulting to what the method previously hardcoded (native `Text`, `TextContent`, the deck's own choice). Folded in from the parity-gaps track (its gap 2.1) rather than landed as a follow-up PR, because the narrowness is a defect *this* PR would otherwise introduce: `run_llm_text` takes all three and the interpreter passes all three, so a façade hardcoding them stores `native.Text`/`TextContent` where an interpreted run stores the declared concept and its generated class — a silent memory divergence surfacing only later as `StuffContentTypeError` in whoever reads the result back. `llm_object` had all three from the start; the asymmetry was between the façade's own two methods. Purely additive (the only callers are tests), gated by `tests/unit/pipelex/kernel/test_llm_text_kernel.py`, which asserts on what lands in the returned memory rather than on the signature. No changelog entry: the package is new and unreleased, so there is no shipped behavior to note.
+- **The prompting-style question that came with it is deferred, not fixed — see KF-16.** The same parity track listed a gap 2.2 claiming `llm_object` renders under the wrong model's style. Re-verified here as **overstated**: the single explicit `model` wins `resolve_llm_setting_for_object`'s first rung, so the style comes from that setting — which is what an interpreted run derives for a pipe naming only a text model. The two agree for every call the façade can express. What remains is narrowness (a pipe naming *both* models is inexpressible), and widening it would mean building the two-setting derivation the mechanism is slated to lose entirely — `wip/prompting-style/README.md`.
+- **The concept-resolution routing rule (0.1e) is satisfied vacuously in Phase 1.** The LLM kernel ops answer no concept-compatibility question at all — the text-vs-object dispatch stays interpreter-side by construction, which is stronger than routing through the pure tiers. The rule is written into the kernel doctrine and applies to whatever Phase 2 adds; there is no `concept_resolver`-omitted arm to test yet, so task 1.7's third named arm does not exist and should not be invented.
+
+## Non-goals (explicit)
+
+- **Controllers stay interpreter-side.** This effort covers operator semantics only; `pipelex/pipe_controllers/` is untouched.
+- **No standalone PyPI distribution yet.** A separately installable kernel dist is a later milestone, once the cogt hub/plugins coupling is unwound; for now the kernel is a subpackage of `pipelex`.
+- **No behavior changes and no new operator features.** Extraction is behavior-preserving; the full test suite must pass, with only the mechanical churn the Doctrine section describes (import repoints, moved modules, patch-target updates).
+- **No Temporal activity target.** Activity-shaped is a design constraint on call signatures, not a deliverable of this refactor.
+
+## Key runtime files for the extraction
+
+`pipelex/pipe_operators/llm/pipe_llm.py`, `pipelex/pipe_operators/llm/llm_prompt_blueprint.py`, `pipelex/cogt/content_generation/content_generator.py` (+ `assignment_models.py`, `content_generation/llm_generate.py`, `schema_to_model_factory.py`), `pipelex/cogt/models/model_deck.py`, `pipelex/core/memory/working_memory.py`.
+
+## Working setup and gates
+
+- **Branch:** `refactor/Kernel` in the `_kernel/` worktree (treat it as repo root), off `dev`; PR targets `dev` on `Pipelex/pipelex`. The branch's `remote` and `pushRemote` are pinned to `origin`.
+- **First-time setup:** `make install` (fresh worktree, fresh venv). `derived/mthds_schema.json` is gitignored — regenerate with `.venv/bin/pipelex-dev generate-mthds-schema` if plxt lint complains.
+- **Gates at every checkpoint:** `make agent-check`, full `make agent-test`, `make drift-check`. ⚠ **`make agent-check` does not run `drift-check`** — only `make check` and CI do, so an agent following `CLAUDE.md` will not see an open contract locally and will discover it as a red CI job. Run it explicitly. The contract this work trips is **`hub-layering-convention`** (triggers on the layering guard and on both hub modules), *not* `keyword-only-convention`, which an earlier draft of this section named: that one triggers only on `keyword_only_guard.py`, and editing `subject_grants.toml` trips nothing. Workflow: `make drift-plan` → review → `git add` the trigger files (the digest reads the **index**, so an unstaged tree reports a false green) → `make drift-ack CONTRACT=<id> RATIONALE="…"`.
+- **Checkpoint discipline:** at each checkpoint, update the status block at the top of this doc with completed phases, decisions taken, open questions, and the current state of the code, so the work hands off cleanly into a fresh session.
diff --git a/wip/parity/README.md b/wip/parity/README.md
index a869ff929..04af4d530 100644
--- a/wip/parity/README.md
+++ b/wip/parity/README.md
@@ -11,8 +11,8 @@ This track fixes a family of defects that share one shape: a single authored fac
| Bare cross-domain pipe refs | `crate_normalization` qualifies with the owner domain; the live `PipeLibrary` searches every domain | now |
| Structureless concept base class | runtime promotes to a `TextContent` refinement; the `python-structures` projection emits `StructuredContent` + `extra="allow"` | now |
| Import-block format stability | `render_import_block` never wraps; a consumer's `ruff format` wraps past 88 columns | now |
-| `MethodKernel.llm_text` narrowness | the façade hardcodes concept/class and requires a model; `run_llm_text` and the interpreter take all three | ✅ fixed **in** #1081 |
-| `MethodKernel.llm_object` prompting style | the façade derives style from the object setting and drops the `for_text` rung; the interpreter derives style from the text setting | ⚠️ withdrawn — not a live defect |
+| `PipelexKernel.llm_text` narrowness | the façade hardcodes concept/class and requires a model; `run_llm_text` and the interpreter take all three | ✅ fixed **in** #1081 |
+| `PipelexKernel.llm_object` prompting style | the façade derives style from the object setting and drops the `for_text` rung; the interpreter derives style from the text setting | ⚠️ withdrawn — not a live defect |
| Img-gen prompt constructor | `kernel/prompt_references.py` says the kernel resolves image references; only the interpreter-layer blueprint can actually build an `ImgGenPrompt` | ✅ fixed **in** #1082 |
## Phasing
diff --git a/wip/parity/parity-gaps-plan.md b/wip/parity/parity-gaps-plan.md
index 61c4f80e9..a0a81603a 100644
--- a/wip/parity/parity-gaps-plan.md
+++ b/wip/parity/parity-gaps-plan.md
@@ -1,6 +1,6 @@
# Parity-gaps plan — fix the places where two readers disagree about one authored fact
-**Thesis.** pipelex has several surfaces that each claim to be a faithful reading of the same authored source: the live library vs the normalized crate, the runtime concept factory vs the `python-structures` projection, the emitted bytes vs the consumer's formatter, and (once the kernel extraction merges) the `MethodKernel` façade vs the ops the interpreter actually calls. Where two of them disagree, the result is a *wrong value with no error attached* — both sides succeed, and only downstream behavior reveals the split. This plan fixes every such disagreement currently known, each with the regression gate that would have caught it.
+**Thesis.** pipelex has several surfaces that each claim to be a faithful reading of the same authored source: the live library vs the normalized crate, the runtime concept factory vs the `python-structures` projection, the emitted bytes vs the consumer's formatter, and (once the kernel extraction merges) the `PipelexKernel` façade vs the ops the interpreter actually calls. Where two of them disagree, the result is a *wrong value with no error attached* — both sides succeed, and only downstream behavior reveals the split. This plan fixes every such disagreement currently known, each with the regression gate that would have caught it.
**Standing rules for this branch:**
@@ -94,7 +94,7 @@ These three are written against the open kernel-extraction PRs and share a theme
The re-verification the plan asked for happened against each PR's own branch rather than against a merged result, which is stricter in one way (the code is exactly what will merge) and weaker in another (it cannot see interactions with a later PR in the stack). Nothing in the stack touches these paths after #1082, so the weakness is not live here.
-### 2.1 `MethodKernel.llm_text` is narrower than the op beneath it
+### 2.1 `PipelexKernel.llm_text` is narrower than the op beneath it
**The defect** (against #1081's code). The façade's text method hardcodes what the op parameterizes, in three ways: output concept (op takes `concept: Concept`; façade hardcodes native `Text`), output class (op takes `output_class`; façade hardcodes `TextContent`), and model (op's resolution accepts `None` and defers to the deck; façade requires a `model`). Its sibling `llm_object` has none of these limits — the asymmetry is between the façade's own two methods. The interpreter passes all three through, with the model choice routinely `None`.
@@ -104,7 +104,7 @@ The re-verification the plan asked for happened against each PR's own branch rat
**✅ Done — *make llm_text as wide as the op beneath it*, on `refactor/Kernel` (#1081).** Re-verified against that branch and held exactly as written: all three widenings were needed. Pre-fix the façade declared `model: LLMModelChoice` with no default — required — and it now declares `model: LLMModelChoice | None = None` alongside the newly optional `concept` and `output_class`. Gated by `tests/unit/pipelex/kernel/test_llm_text_kernel.py`, which asserts on what lands in the returned memory (`type(stuff.content) is MeetingSummary`, the stuff's `concept_ref`) rather than on the signature — a signature assertion would pass on a façade that accepted the arguments and dropped them. No changelog entry: the package is new and unreleased, so there is no shipped behavior to note.
-### 2.2 `MethodKernel.llm_object` renders under the wrong model's prompting style
+### 2.2 `PipelexKernel.llm_object` renders under the wrong model's prompting style
**The defect** (against #1081's code). A `PipeLLM` carries two model choices (`model` → for_text, `model_to_structure` → for_object). The interpreter resolves **two** settings and derives the templating style from the **text** one (`pipe_llm.py:219–237` on dev — the pipe's main model governs how the prompt is written; the object path differs only in how the answer comes back). The façade collapses to one choice, drops the object chain's `for_text` fallback rung, and derives the style from the **object** setting. Unlike 2.1 this is not narrowness visible in a signature — it is a wrong value.
@@ -147,5 +147,5 @@ Deferred as **KF-16** in `wip/kernel/deferred-follow-ups.md`, with the design in
## Out of scope
- The runtime's structureless *promotion* semantics (D-2 option (b)) and the bare-ref *language rule* (D-1 option (b)) — both are author-facing language decisions, flagged for Louis, not taken here.
-- `MethodKernel` growing façade methods for the non-LLM operators — a design conversation for after the kernel PRs settle, not a parity defect.
+- `PipelexKernel` growing façade methods for the non-LLM operators — a design conversation for after the kernel PRs settle, not a parity defect.
- Anything in the open kernel PRs themselves — they are finalized and stacked; this branch follows them, it does not amend them.
diff --git a/wip/prompting-style/README.md b/wip/prompting-style/README.md
new file mode 100644
index 000000000..e058020a5
--- /dev/null
+++ b/wip/prompting-style/README.md
@@ -0,0 +1,58 @@
+# Deferred — make the prompting style an explicit choice, not a model-derived one
+
+**Status: deferred, not started.** Raised 2026-08-03 while folding the parity-gap fixes into the kernel-extraction PRs. Owner decision (Louis): the feature this plan replaces is **obsolete**, so patching it to match the interpreter would be throwaway work. Nothing here blocks the kernel extraction.
+
+## What exists today
+
+The prompting style is **derived from the model**, per call, in exactly one place — `derive_templating_style` in `pipelex/kernel/llm_ops.py` — which both callers go through:
+
+- interpreter — `pipelex/pipe_operators/llm/pipe_llm.py` resolves the pipe's text setting and calls `derive_templating_style` with it (`pipe_llm.py:223`), passing the result to both the text and the object generation paths.
+- kernel — the ops call the same function over whichever `LLMSetting` the caller supplied.
+
+**That single site is the extraction's doing.** Before it, the interpreter carried its own copy of the lookup, and an earlier draft of this doc described two readers that must be kept in agreement. There is now one, so the parity hazard is already gone — none of the reasons below depend on it.
+
+The chain is `llm_setting.prompting_target` when set, otherwise the inference model's own `prompting_target`, then `prompting_config.get_prompting_style(...)` → `TemplatingStyle`. The setting-level override is the first branch and is easy to miss: a caller can steer the style without changing the model. Note also the silent arm — `derive_templating_style` returns `None` when the deck holds no inference model for the handle, which is what an external LLM plugin looks like from there.
+
+## Why it should go
+
+The mechanism dates from when models were genuinely sensitive to prompt shape and each family wanted its own markup. That no longer holds — current models are not meaningfully sensitive to the difference, so deriving the style from the model spends real complexity on a distinction that no longer pays.
+
+What the indirection actually costs:
+
+- **The derivation is invisible to every caller.** Nothing at a call site says which style a prompt will render under; it falls out of a deck lookup two hops away. That invisibility is why the parity-gaps track's 2.2 took real work to adjudicate — and why it was initially, and wrongly, called a live defect.
+- **The style is unstateable.** A caller who wants a specific style has no way to say so — they must pick a *model* whose prompting target maps to it.
+- **A deck/config change silently changes prompt text** for a method nobody edited.
+
+## The target design
+
+Make the prompting style an **explicit choice**, defaulting to **XML**:
+
+- an explicit setting a caller/author can state directly, defaulting to XML when unstated;
+- the model-derived path removed, along with `prompting_target` plumbing that exists only to feed it (check what else reads it before deleting — it may have non-style consumers);
+- no derivation site at all, rather than the single one that survives today;
+- `TemplatingStyle | None` at the op boundary reconsidered: with an explicit default, `None` may stop being a reachable state, which would let `run_llm_*` take a plain `TemplatingStyle`.
+
+Open questions for whoever picks this up:
+
+- Where does the explicit choice live — `.mthds` pipe-level, deck-level, config-level, or more than one with a precedence chain?
+- Is it per-pipe or per-run? A pipe-level override implies a language surface (`prompting_style = "xml"`), which is an MTHDS spec change and belongs with the `mthds/` repo, not just here.
+- What happens to `prompting_target` on `LLMSetting` and on inference models — deleted, or kept for another purpose?
+- Migration: methods relying on a non-XML style today would change prompt text. Given the premise (models no longer sensitive), that is expected to be a no-op in output quality, but it *is* a wire-visible change to rendered prompts and should be called out in the changelog.
+
+## What was silenced in the meantime, and what was not
+
+The parity-gaps plan listed this as gap **2.2 — "`PipelexKernel.llm_object` renders under the wrong model's prompting style"**, and called it *a wrong value*. **That was overstated.** Re-verified 2026-08-03 against `refactor/Kernel`:
+
+| Call | Style derived from |
+| --- | --- |
+| `PipelexKernel.llm_object(model=X)` | `X` |
+| interpreter, pipe declares `for_text = X` only | `X` — **identical** |
+| interpreter, pipe declares `for_object = X` only | the deck's **text** default — differs |
+
+The façade takes one explicit `model`, which wins `resolve_llm_setting_for_object`'s first rung, so the style comes from that same setting. That matches the interpreter's single-text-choice reading — the natural reading of a parameter called `model`. **For every call the façade can express, the two agree.** The divergence needs a pipe naming *both* models, which the façade has no way to say.
+
+So 2.2 is not a wrong value; it is the same **narrowness** as 2.1 — a two-choice form that is inexpressible. It is left alone deliberately: widening the façade to take a second choice would mean building the two-setting derivation this plan is about to delete.
+
+**Recorded in code** as a docstring block on `PipelexKernel.llm_object`, including the trap: do *not* "fix" it by deriving the style from an object-only resolution — that would *introduce* the divergence rather than close it.
+
+**Not silenced, still open:** nothing. There is no live defect to carry. This document exists so the obsolete mechanism gets deleted deliberately rather than discovered again by the next person who compares the two readers.