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.
Let a kernel step identify itself, and choose where its id comes from (#1103)
Louis Choquel91a055d681da
diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex c729aa4c7..c6ef31887 100644--- a/.drift/acks/pipelex-kernel-docs.toml+++ b/.drift/acks/pipelex-kernel-docs.toml@@ -1,8 +1,8 @@contract = "pipelex-kernel-docs"-digest = "sha256:73aafaa2a6d3151a0d8f775cd90e8648f4b8b57ac9808cdb94579a2ae59fd0f8"-reviewed_by = "Claude (Fable 5)"-reviewed_at = "2026-08-13T12:05:20Z"-rationale = "Trigger is the search_domain_codes to search_scope rename passing through shape_inputs (memory_ops.py) and the boot-contract mock swapping get_required_concept_from_concept_ref_or_code for get_required_entry_concept. Reviewed docs/under-the-hood/pipelex-kernel.md: its shape_inputs paragraph and code example name neither the renamed parameter nor the replaced provider method, and the smallest-provider description does not enumerate resolver method names, so every claim still holds. Reviewed, no doc change needed."+digest = "sha256:5ec1035b41c34141c61a699d4310d73f2999c3d8cd6c4cc6d95fc930ab2101d9"+reviewed_by = "Louis Choquel"+reviewed_at = "2026-08-14T06:58:58Z"+rationale = "Cherry-pick of the step-identity change: make_step_metadata gains pipe_code and PipelexKernel.make gains an injectable step_id_source. Updated the doc's run-scoped-state section: the façade now holds identity plus the step_id_source seam, the job_metadata bullet documents pipe_code naming with its omit-not-None contract and the façade's deliberate anonymity."[trigger_files]"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"@@ -20,7 +20,7 @@ rationale = "Trigger is the search_domain_codes to search_scope rename passing t"pipelex/kernel/llm_prompt_content.py" = "blob:26dfce734de582320c0ea7b9a09b01f2d1ca8627""pipelex/kernel/llm_results.py" = "blob:6e3b8a2878b5bb284ece5fac10262fb59ac2029d""pipelex/kernel/memory_ops.py" = "blob:f6a5745e804ac08f19c70f1beb1f78baf50d51cd"-"pipelex/kernel/pipelex_kernel.py" = "blob:ad13e02168590a1173d7db1e210b3cecd7059651"+"pipelex/kernel/pipelex_kernel.py" = "blob:fde22aedea2ad8ca41e12a4f1a67e2189dc3fbce""pipelex/kernel/prompt_references.py" = "blob:03ec9ef67ae84f141d072ca2d2c3ef888549ccc0""pipelex/kernel/search_ops.py" = "blob:01be4bef28f98342678cba16ac8c4b21fadcaae1""pipelex/kernel/search_results.py" = "blob:101b70dc96cc5ee1721c9f6b1cb725a5ca78ff70"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ff350572e..ec0ca2117 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## [Unreleased]++### Added++- **Kernel step identity**: `PipelexKernel.make_step_metadata` now accepts `pipe_code` to name the pipe a step is running, mirroring what the interpreter stamps on its live and dry paths — so log correlation, usage accounting, and per-step labelling see a named step for kernel-driven runs. The key is omitted from the metadata update when not supplied, so a run-level `pipe_code` is never silently erased; the direct-call façade (`llm_text`/`llm_object`) stays deliberately anonymous. `PipelexKernel.make` also accepts an injectable `step_id_source` for per-step ids, defaulting to `uuid4`, so a kernel hosted inside a replay-based executor can supply a replay-safe source.+## [v0.44.0] - 2026-08-13### Addeddiff --git a/docs/under-the-hood/pipelex-kernel.md b/docs/under-the-hood/pipelex-kernel.mdindex cc4924895..f17f1fd8d 100644--- a/docs/under-the-hood/pipelex-kernel.md+++ b/docs/under-the-hood/pipelex-kernel.md@@ -118,10 +118,11 @@ summaries = extract_main_content_as_list(memory=result.memory, item_type=Summary## Run-scoped state, and who owns the usage lifecycle-`PipelexKernel` holds exactly two things, both run-scoped identity:+`PipelexKernel` holds run-scoped identity, plus the one seam that identity needs:-- **`job_metadata`** — the run-level metadata. It is not what a step runs under: every call mints a per-step copy through `make_step_metadata()`, carrying a fresh `pipe_run_id` and inheriting the trace context, so trace and usage attribution stay per-step. This mirrors the interpreter's pass-down-a-modified-copy pattern.+- **`job_metadata`** — the run-level metadata. It is not what a step runs under: every call mints a per-step copy through `make_step_metadata()`, carrying a fresh `pipe_run_id` and inheriting the trace context, so trace and usage attribution stay per-step. This mirrors the interpreter's pass-down-a-modified-copy pattern. `make_step_metadata(pipe_code=…)` names the pipe the step is running — mirroring what the interpreter stamps on its live and dry paths — so log correlation, usage accounting, and the per-step labelling a distributed backend derives see a named step. When no `pipe_code` is supplied the key is omitted from the update rather than passed as `None`, so a run-level `pipe_code` is never silently erased; the direct-call façade (`llm_text`/`llm_object`) stays deliberately anonymous, because the caller ran no pipe.- **`cogt_run_params`** — the execution-mode contract (`run_mode`, and the DRY-only `is_mock_usage` sub-flag) that every cogt leaf reads off the assignment it is handed.+- **`step_id_source`** — where each step's `pipe_run_id` comes from, defaulting to a fresh `uuid4`, which is what every in-process run wants. It exists for a kernel hosted inside a replay-based executor, where ids minted from a non-replay-safe source take different values each re-execution; such a host injects its own replay-safe source via `PipelexKernel.make(step_id_source=…)`. It is a seam, not state — the kernel never inspects what it returns.Nothing derived from config or the model deck is cached on the instance — resolved settings and prompting styles are computed per call, because cached derived state would shadow a later config or deck change and break per-call variation.diff --git a/pipelex/kernel/pipelex_kernel.py b/pipelex/kernel/pipelex_kernel.pyindex ad13e0216..fde22aede 100644--- a/pipelex/kernel/pipelex_kernel.py+++ b/pipelex/kernel/pipelex_kernel.py@@ -3,13 +3,16 @@The semantics live in the module-level ops functions beside this one; the interpreter's operatorclasses call those directly, because they already hold everything the façade would supply. Thisclass exists for the *other* caller — the programmatic one, embedding the kernel — and it holds-exactly two things, both of them run-scoped identity:+only run-scoped identity plus the one seam that identity needs:- ``job_metadata`` — the **run-level** metadata. It is not what a step runs under: each call mintsa per-step copy via :meth:`make_step_metadata`, mirroring the interpreter's pass-down-a-modified-copypattern, so trace and usage attribution stay per-step.- ``cogt_run_params`` — the execution-mode contract (``run_mode``, ``is_mock_usage``) every cogtleaf reads off the assignment it is handed.+- ``step_id_source`` — where a step's ``pipe_run_id`` comes from, defaulting to ``uuid4``. A caller+ hosting the kernel inside a replay-based executor injects a replay-safe source; see+ :meth:`make`. It is a seam, not state — the kernel never inspects what it returns.What it deliberately does **not** hold is anything derived from config or the model deck — resolvedLLM settings, prompting style. Those are computed per call and never cached here, exactly as@@ -29,7 +32,8 @@ both halves a caller needs (``make_event_log``, ``UsageAggregator``) and is kernthis costs the boot contract. See ``docs/under-the-hood/pipelex-kernel.md``."""-from typing import Self+from collections.abc import Callable+from typing import Any, Selffrom uuid import uuid4from pipelex.cogt.content_generation.cogt_run_params import CogtRunParams, check_mock_usage_requires_dry@@ -55,12 +59,24 @@ from pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.trace_context import TraceContext+def _mint_step_id() -> str:+ """The default per-step id source: a fresh uuid4, which is what every in-process run wants."""+ return str(uuid4())++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:+ def __init__(+ self,+ *,+ job_metadata: JobMetadata,+ cogt_run_params: CogtRunParams,+ step_id_source: Callable[[], str] | None = None,+ ) -> None:self.job_metadata = job_metadataself.cogt_run_params = cogt_run_params+ self.step_id_source = step_id_source or _mint_step_id@classmethoddef make(@@ -70,6 +86,7 @@ class PipelexKernel:user_id: str,is_mock_usage: bool = False,trace_context: TraceContext | None = None,+ step_id_source: Callable[[], str] | None = None,) -> Self:"""Mint a kernel for one run: a run id, the execution-mode contract, and optional tracing.@@ -88,6 +105,13 @@ class PipelexKernel:the two are one identity, and letting them diverge would scatter a single run's usage eventsacross two ids (the registered-context emit path stamps the event log's id, the runnerfallback stamps the metadata's), so the read-back would silently miss half of them.++ ``step_id_source`` overrides where each step's ``pipe_run_id`` comes from; it defaults to a+ fresh ``uuid4``, which is what every in-process run wants. It exists for a kernel hosted+ inside a **replay-based** executor, where identifiers minted from a non-replay-safe source+ take different values each time the host re-executes the code. Such a host injects its own+ replay-safe source here; the kernel stays ignorant of it, which is the point of this tier —+ nothing about a durable backend reaches the runtime or the code it runs."""check_mock_usage_requires_dry(run_mode=run_mode, is_mock_usage=is_mock_usage)return cls(@@ -97,9 +121,10 @@ class PipelexKernel:trace_context=trace_context,),cogt_run_params=CogtRunParams(run_mode=resolve_run_mode_for_boot(requested=run_mode), is_mock_usage=is_mock_usage),+ step_id_source=step_id_source,)- def make_step_metadata(self) -> JobMetadata:+ def make_step_metadata(self, *, pipe_code: str | None = None) -> 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@@ -107,8 +132,25 @@ class PipelexKernel:the span, and a kernel call opens none. ``trace_context`` is left to inherit, which is thesame method's other contract and the reason usage events from every step of a kernel runattribute to the one context the caller supplied.++ ``pipe_code`` names the pipe this step is running, mirroring what the interpreter stamps in+ ``pipe_abstract``'s run paths. Anything that attributes work by it — log correlation, usage+ accounting, the per-step labelling a distributed backend derives from the metadata — sees an+ anonymous step without it.++ ⚠ It is **omitted from the update rather than passed as ``None``** when the caller supplies+ none. ``copy_with_update`` applies whatever it is handed, so an unconditional pass would+ overwrite a run-level ``pipe_code`` with ``None`` — turning an optional enrichment into a+ silent erasure for every caller that never asked for it.++ **The façade's own callers below stay anonymous, and that is the honest answer rather than+ an oversight**: ``llm_text`` and ``llm_object`` are the direct-call form, where there is no+ pipe because the caller did not run one. Do not "finish the job" by inventing a name there."""- return self.job_metadata.copy_with_update(otel_context=None, pipe_run_id=str(uuid4()))+ updates: dict[str, Any] = {"pipe_run_id": self.step_id_source()}+ if pipe_code is not None:+ updates["pipe_code"] = pipe_code+ return self.job_metadata.copy_with_update(otel_context=None, **updates)async def llm_text(self,diff --git a/tests/integration/pipelex/kernel/test_usage_parity.py b/tests/integration/pipelex/kernel/test_usage_parity.pyindex 3ef1bb02e..3fb40c317 100644--- a/tests/integration/pipelex/kernel/test_usage_parity.py+++ b/tests/integration/pipelex/kernel/test_usage_parity.py@@ -12,12 +12,20 @@ So this measures rather than asserts. Both sides run the same step (one LLM textshape ``/execute`` returns on ``pipe_output.tokens_usages`` and durable runs persist as``tokens_usages.json`` — are then compared field by field.-``pipe_code`` is the one field that legitimately differs: the interpreter names the pipe it ran, and a-kernel call has no pipe to name. Both halves are asserted rather than excluded quietly, because that-difference is the honest scope of what the comparison proves. It only reads that way because-``dry_run_pipe`` stamps the running pipe onto the metadata it hands down — until it did, the field was-``None`` on both sides and this measurement could not observe it at all (KF-13). Timestamps differ-because the two runs happen at different times.+``pipe_code`` used to be the one field that legitimately differed, and it no longer does. The+interpreter stamps it on the DRY path too — ``dry_run_pipe`` identifies the pipe it is running,+exactly as ``live_run_pipe`` already did — which closed the interpreter half of KF-13 (a+``--dry-run --mock-usage`` cost report used to carry no pipe attribution at all). **The kernel tier+has since got the same fix**: ``make_step_metadata(pipe_code=…)`` names the step, so attribution+reaches the usage record on both sides and ``pipe_code`` is compared rather than excluded. Only the+timestamps differ, because the two runs happen at different times.++⚠ **Which makes the kernel side's shape load-bearing.** It calls the *ops* with a named step, the way+a compiled artifact does — not ``PipelexKernel.llm_text``. The façade is the direct-call form, where+there is no pipe because the caller did not run one, so it stays deliberately anonymous; comparing it+against an interpreter run that *did* run a pipe would compare two different situations and read the+difference as a gap. ``test_the_direct_call_facade_stays_deliberately_anonymous`` pins that half, so+neither behaviour can drift into the other unnoticed.Transport ownership is visible in the setup itself. The interpreter half needs NDJSON tracing enabledbecause its run machinery builds the event log off the config; the kernel half hands its own@@ -33,7 +41,12 @@ from pytest_mock import MockerFixturefrom pipelex.cogt.content_generation.dry_mock import MOCK_USAGE_MODEL_NAMEfrom pipelex.cogt.llm.llm_setting import LLMSettingfrom pipelex.config import get_config+from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactory+from pipelex.core.stuffs.text_content import TextContent+from pipelex.kernel.llm_ops import derive_templating_style, resolve_llm_setting_for_text, run_llm_text+from pipelex.kernel.llm_prompt_content import LlmPromptContentfrom pipelex.kernel.pipelex_kernel import PipelexKernelfrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.reporting.reporting_types import AnyTokensUsage@@ -59,16 +72,16 @@ output = "Text"prompt = "{_USER_PROMPT}""""-#: The fields two separate runs cannot share — the wall-clock ones — plus ``pipe_code``, which the two-#: callers fill differently by design rather than by accident. Everything else is the shape parity is-#: measured on, and each excluded field is asserted on its own below.-_UNCOMPARABLE_FIELDS = ("pipe_code", "started_at", "completed_at")+#: The record fields that carry the run's wall-clock, which two separate runs cannot share.+#: Everything else is the shape parity is measured on — ``pipe_code`` included, since the kernel tier+#: learned to name its steps.+_RUN_SPECIFIC_FIELDS = ("started_at", "completed_at")@pytest.mark.asyncio(loop_scope="class")class TestKernelUsageParity:def _comparable(self, record: TokensUsageRecord) -> dict[str, Any]:- return {key: value for key, value in record.model_dump().items() if key not in _UNCOMPARABLE_FIELDS}+ return {key: value for key, value in record.model_dump().items() if key not in _RUN_SPECIFIC_FIELDS}def _records(self, tokens_usages: list[AnyTokensUsage]) -> list[TokensUsageRecord]:return [make_tokens_usage_record(tokens_usage) for tokens_usage in tokens_usages]@@ -89,7 +102,13 @@ class TestKernelUsageParity:assert response.pipe_output.tokens_usages is not None, "the interpreter run assembled no usage at all"return self._records(response.pipe_output.tokens_usages)- async def _run_through_the_kernel(self) -> list[TokensUsageRecord]:+ async def _run_through_the_kernel(self, *, name_the_step: bool) -> list[TokensUsageRecord]:+ """One kernel LLM step, either artifact-shaped (named) or through the façade (anonymous).++ The named arm renders the ops call the way the emitter does, rather than going through+ ``PipelexKernel.llm_text`` — that is the whole distinction the two callers of this helper+ exist to hold apart.+ """# The caller's transport, and the caller's lifecycle: build the event log, register it for the# run, read the events back, clear the registration. The kernel is handed only the context.event_log = InMemoryEventLog()@@ -112,12 +131,27 @@ class TestKernelUsageParity:is_mock_usage=True,trace_context=trace_context,)- await kernel.llm_text(- memory=WorkingMemoryFactory.make_empty(),- model=LLMSetting(model="kernel-usage-parity-model", temperature=0.5),- user=_USER_PROMPT,- result="written",- )+ model = LLMSetting(model="kernel-usage-parity-model", temperature=0.5)+ if name_the_step:+ llm_setting = resolve_llm_setting_for_text(llm_choice=model)+ await run_llm_text(+ memory=WorkingMemoryFactory.make_empty(),+ prompt_content=LlmPromptContent.make_from_text(user=_USER_PROMPT, system=None),+ llm_setting=llm_setting,+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT),+ output_class=TextContent,+ job_metadata=kernel.make_step_metadata(pipe_code=_PIPE_CODE),+ cogt_run_params=kernel.cogt_run_params,+ templating_style=derive_templating_style(llm_setting=llm_setting),+ result_name="written",+ )+ else:+ await kernel.llm_text(+ memory=WorkingMemoryFactory.make_empty(),+ model=model,+ user=_USER_PROMPT,+ result="written",+ )return self._records(UsageAggregator.aggregate(event_log.read_events(trace_context.graph_id)))finally:get_report_delegate().clear_event_log(context_key=trace_context.lookup_key)@@ -125,7 +159,7 @@ class TestKernelUsageParity:async def test_both_callers_produce_the_same_usage_records(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:"""One LLM step, two callers, one usage shape."""interpreter_records = await self._run_through_the_interpreter(mocker, str(tmp_path_factory.mktemp("traces_parity")))- kernel_records = await self._run_through_the_kernel()+ kernel_records = await self._run_through_the_kernel(name_the_step=True)assert len(kernel_records) == len(interpreter_records) == 1, (f"one LLM step must report exactly one usage record on each side, got interpreter={len(interpreter_records)} kernel={len(kernel_records)}"@@ -138,8 +172,19 @@ class TestKernelUsageParity:assert record.inference_model_name == MOCK_USAGE_MODEL_NAMEassert sum(record.nb_tokens_by_category.values()) > 0- # The scope of what was measured, pinned rather than left implicit: the one field excluded- # from the comparison above is excluded because the two callers fill it differently — the- # interpreter names the pipe it ran, a kernel call has no pipe to name.- assert interpreter_records[0].pipe_code == _PIPE_CODE- assert kernel_records[0].pipe_code is None+ # Attribution reaches the usage record on both sides, and reaches the SAME value. Stated here+ # as well as inside `_comparable` because it is the property this comparison exists for: a+ # field silently dropped from `_RUN_SPECIFIC_FIELDS` would weaken the check above in a way+ # nothing else would notice.+ assert kernel_records[0].pipe_code == interpreter_records[0].pipe_code == _PIPE_CODE++ async def test_the_direct_call_facade_stays_deliberately_anonymous(self) -> None:+ """`PipelexKernel.llm_text` names no pipe, because the caller ran none — by design, not by gap.++ Pinned so that "finish the job by naming it too" cannot land unnoticed: a façade call that+ invented a pipe code would attribute work to a pipe that never ran.+ """+ records = await self._run_through_the_kernel(name_the_step=False)++ assert len(records) == 1+ assert records[0].pipe_code is Nonediff --git a/tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.py b/tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.pyindex e1cc71e76..90109a595 100644--- a/tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.py+++ b/tests/unit/pipelex/kernel/test_pipelex_kernel_run_state.py@@ -5,6 +5,8 @@ interpreter run's. These pin the links, because a parity failure there says "nosaying which link dropped: the run-level metadata, the per-step copy, or the run mode."""+from uuid import UUID+import pytestfrom pipelex.core.concepts.concept_factory import ConceptFactory@@ -80,6 +82,55 @@ class TestPipelexKernelRunState:# Computed fresh per step by whoever opens the span, and a kernel call opens none.assert first_step.otel_context is None+ def test_a_step_names_the_pipe_it_is_running_when_told_which(self) -> None:+ """The kernel tier's half of what the interpreter already does in `pipe_abstract`.++ Anything that attributes work by `pipe_code` — log correlation, usage accounting, the+ per-step labelling a distributed backend derives — sees an anonymous step without this.+ """+ kernel = PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="test-user")++ assert kernel.make_step_metadata(pipe_code="answer_question").pipe_code == "answer_question"++ def test_an_unnamed_step_does_not_erase_the_runs_own_pipe_code(self) -> None:+ """The erasure trap: `copy_with_update` applies whatever it is handed, `None` included.++ Passing `pipe_code=None` through unconditionally would turn an optional enrichment into a+ silent wipe of the run-level value for every caller that never asked for the feature. The+ key must be omitted, not passed as None — so this constructs a run that HAS a run-level+ `pipe_code`, which no caller in the tree does today.+ """+ kernel = PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="test-user")+ kernel.job_metadata.pipe_code = "set_at_run_level"++ assert kernel.make_step_metadata().pipe_code == "set_at_run_level"++ def test_the_step_id_source_is_injectable_and_defaults_to_uuid(self) -> None:+ """A workflow-hosted kernel must be able to supply a replay-safe id source.++ The kernel cannot import `temporalio` — that is the whole point of the tier — so the+ replay-safe source arrives from outside. ⚠ Measured 2026-08-07: `uuid4()` in workflow code+ does NOT currently raise on replay (see `kernel-step-identity-plan.md`), so this closes a+ latent trap rather than a live defect; Phase 3's usage wiring is the consumer that would+ first observe the drift.+ """+ minted: list[str] = []++ def _source() -> str:+ minted.append(f"step-{len(minted)}")+ return minted[-1]++ kernel = PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="test-user", step_id_source=_source)++ assert kernel.make_step_metadata().pipe_run_id == "step-0"+ assert kernel.make_step_metadata().pipe_run_id == "step-1"++ default_kernel = PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="test-user")+ first_default = default_kernel.make_step_metadata().pipe_run_id+ assert first_default is not None+ assert UUID(first_default).version == 4+ assert first_default != default_kernel.make_step_metadata().pipe_run_id+def test_mock_usage_rides_the_execution_mode_contract(self) -> None:"""The DRY sub-flag lands on the carrier every cogt leaf reads off its assignment."""kernel = PipelexKernel.make(run_mode=PipeRunMode.DRY, user_id="test-user", is_mock_usage=True)