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.

refactor(hub): split pipelex.hub into runtime_hub + interpreter_hub (#1062)

Louis Choquel6fbdcb2fd1a4
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 1a1609022..0192884b1 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,20 +1,20 @@
contract = "cli-docs"
-digest = "sha256:e7bb78cd62dab12872fe04e1a52cc790f03cd5f34ed277c377ceb2837938640b"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-07-11T15:45:13Z"
-rationale = "Trigger changes are the subject-grant regrind's internal signature demotes plus the pipelex-dev --seed removal; docs/tools/cli/ and agent_cli/CLAUDE.md document neither pipelex-dev nor any changed command flag or output contract — reviewed, no doc change needed."
+digest = "sha256:951772e532e83bafefb42f75214b9c65098a722c290ec1e36f943a4b3e23ac6e"
+reviewed_by = "Claude (Opus 5)"
+reviewed_at = "2026-07-26T09:35:23Z"
+rationale = "All 28 triggers changed by hub import lines only — the runtime/interpreter rename (service_hub -> runtime_hub, method_hub -> interpreter_hub). Verified mechanically: diffed all 28 trigger files together and filtered out every changed line naming a hub; nothing remained, so no CLI argument, flag, format value, default, or command behavior moved. The vocabulary and identifier edits of this rename (LOW_LAYER_PACKAGES -> RUNTIME_LAYER_PACKAGES, the guard's success panel) live under pipelex/cli/dev_cli/**, which this contract excludes. Opened both review targets: docs/tools/cli/ and pipelex/cli/agent_cli/CLAUDE.md contain zero references to pipelex.hub, service_hub, method_hub, or either new hub module — they document the user-facing command surface, not Python import paths, so the rename is invisible to them. Nothing to update."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
-"pipelex/cli/_cli.py" = "blob:dec199a605168d168b512805f03a81cbe75d8bc9"
+"pipelex/cli/_cli.py" = "blob:6bb9f12c984501a7cc365168c9053e15bb08638d"
"pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/_agent_cli.py" = "blob:bbbb33d750a93df1a5afd72b43e0a381d5081279"
"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:a1fc438119dd10607252c08390ebd6384d999678"
-"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:8ea8729c402874fa760c46670da5ebd6967648b5"
+"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:caba5ab957e4a2bbb62e329ba6722a441dff781e"
"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:8868104d882e160a5b5a95d3f6c7642499488786"
"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0"
-"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:2e3bb5be7e0fd72c43bf43e1faa3eb9d5c8353b2"
+"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:1d5a66d03e6fec2d8673959857ace87b78db03ac"
"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:0f3daa4a3962273c4b347a619dd99bef72f735be"
"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:bacfda014d158c9a4e9de5f8ca03ba9628b6b102"
@@ -27,11 +27,11 @@ rationale = "Trigger changes are the subject-grant regrind's internal signature
"pipelex/cli/agent_cli/commands/fmt_cmd.py" = "blob:97d6fb6c328e0b718b1293bd6b73cba03edcb7dc"
"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:3ed36d13bddebbadb90272b689a15e9ebdbcabf7"
"pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:459e29b581f873a92195723d7f4e9293497b398c"
+"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:09f4771b327cb6a6e5bb11b8bb07b6f63b4472d4"
"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"
-"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:c6ad6a69bf161573617fb1c2eaa1367d6d63239d"
-"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:516cf6fc7030d59792cef4b6e3a30448e21f6cff"
-"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:08cf0c6d2a0c2aa41a3c61b0b97b02989c79395f"
+"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:535680905fd85258f4a71568d1d5eb8e36143d74"
+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:f71014584e3051ca514765631349e0dbfad3ae4c"
+"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:038c82cf9777de5e0c87131c22ac64d910b8c897"
"pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"
"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:90d30128fe924677ee84f926fc733b2016333297"
"pipelex/cli/agent_cli/commands/pipe_cmd.py" = "blob:0be9fb13dbec21da0958ed66b45748291b4e5e2d"
@@ -46,7 +46,7 @@ rationale = "Trigger changes are the subject-grant regrind's internal signature
"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:31ce470e603a5b28207d176a5ae2820216b199e0"
"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690"
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:94c86636f1b8494263e1dd49dc6168834996e39e"
+"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:c07252202265806ebe3512370152d2ebce8a7e78"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"
"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:31b5210e5495b8687ea7029c2d3660d25167eea7"
"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:24ddeef224fa2d88781141467ef80c414d34f77a"
@@ -57,19 +57,19 @@ rationale = "Trigger changes are the subject-grant regrind's internal signature
"pipelex/cli/commands/build/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/build/app.py" = "blob:fabe555870e61d147d0bf01e49de6e5cc9719d34"
"pipelex/cli/commands/build/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/build/inputs/_inputs_core.py" = "blob:60aa8704f384feb4314a32ff390027479a7f03d8"
+"pipelex/cli/commands/build/inputs/_inputs_core.py" = "blob:2e91d50b6e547e76b7d429085d584e4cbc77b0df"
"pipelex/cli/commands/build/inputs/app.py" = "blob:2a7770c8294b8c2c1b4420ac00d6ffdfa50609bf"
-"pipelex/cli/commands/build/inputs/bundle_cmd.py" = "blob:9ab5ff3eaaefb8cc0102ee4dfd6001f67fbd4863"
-"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:5a7d0a53f926cb5648fbbc1beb8bce20b86bc200"
-"pipelex/cli/commands/build/inputs/pipe_cmd.py" = "blob:4ac82731c730940b7fe4f80002610beb16488d65"
+"pipelex/cli/commands/build/inputs/bundle_cmd.py" = "blob:c096689e014c3a0fab000ab63abcfef99f0b4fd7"
+"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:1f88399bb8b557779630472d5624e9a1f1d51c13"
+"pipelex/cli/commands/build/inputs/pipe_cmd.py" = "blob:c8e0722c7cfc7ea340fd6a143211460687d19795"
"pipelex/cli/commands/build/output/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/build/output/_output_core.py" = "blob:12e0966394f28a70645d63e024dd76678f220bc2"
+"pipelex/cli/commands/build/output/_output_core.py" = "blob:2df512eeaea4e87c60997612848139d63cfd7d77"
"pipelex/cli/commands/build/output/app.py" = "blob:67996650b99551fbd58be30e692688204d16935a"
"pipelex/cli/commands/build/output/bundle_cmd.py" = "blob:a4a04ce555e0bbf2178206269fe769c13a0bd0f7"
"pipelex/cli/commands/build/output/method_cmd.py" = "blob:f43bd91fd9007358f725dc489212bec35a1e223d"
"pipelex/cli/commands/build/output/pipe_cmd.py" = "blob:eb0db8279c93fcff9d5fe4546f593d753282acb5"
"pipelex/cli/commands/build/runner/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/build/runner/_runner_core.py" = "blob:dd0ce14f5286bacfb6468875186449a01c93f2d7"
+"pipelex/cli/commands/build/runner/_runner_core.py" = "blob:c33eec4a86bc33b799e441cc205ec895194c07bb"
"pipelex/cli/commands/build/runner/app.py" = "blob:b5aa321ed93dc2cb9b138e4a26bae9eb75c732b7"
"pipelex/cli/commands/build/runner/bundle_cmd.py" = "blob:d18b32232d45010150cce2779242057adb8dc51a"
"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:0f497ffcae50d89483d8cf953c6dc03599bc2a5f"
@@ -78,23 +78,23 @@ rationale = "Trigger changes are the subject-grant regrind's internal signature
"pipelex/cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/codegen/app.py" = "blob:9158084a89da23654e122e9df3a0a9c726401642"
"pipelex/cli/commands/codegen/check_cmd.py" = "blob:d73d0c73e82fa50e072058caf0ca92e52fe17b0f"
-"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:02049944149cac3d2b2f59b14be0d74271a20010"
-"pipelex/cli/commands/codegen/types_cmd.py" = "blob:944541cdf040bf63ee3ebbd6c74d15dc523dbee2"
-"pipelex/cli/commands/crate_loading.py" = "blob:1b62ace3a8c439ae6a84612b503dced2e89c01b6"
-"pipelex/cli/commands/doctor_cmd.py" = "blob:0823f00388f32e9f32ae0e709a4412784cd14dd4"
+"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:9ff33033b25b61a9d4719d4d19c10c461b59ce3f"
+"pipelex/cli/commands/codegen/types_cmd.py" = "blob:1cb3b607a0269e12461e85ad1e6f19b2b3aa5584"
+"pipelex/cli/commands/crate_loading.py" = "blob:aaf739abef2b84807483907365455ce2b8179aa6"
+"pipelex/cli/commands/doctor_cmd.py" = "blob:3cc70c2844c48aa73b91cdf085864589f30bc7f8"
"pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:c9a899c68653bab4082fbe81a5f8af571919d87a"
-"pipelex/cli/commands/fix/_fix_core.py" = "blob:5bd7ba061fe2c00932279db7af2b419c6f5e06f2"
+"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:2113f7e7ffd373177a3104ce5b5dfb7f657dd186"
+"pipelex/cli/commands/fix/_fix_core.py" = "blob:8f6a187a0fb42c498629b177753d81620800b0da"
"pipelex/cli/commands/fix/app.py" = "blob:6f019930e8e3e0043ee46d87493ba4602eb33a76"
"pipelex/cli/commands/fix/bundle_cmd.py" = "blob:427364cc453957dfe0cec879f019050329c13b3c"
-"pipelex/cli/commands/graph_cmd.py" = "blob:4363d3b9320e352244883f5fa1fe94dffc6faee8"
+"pipelex/cli/commands/graph_cmd.py" = "blob:7433b3ca88e0052ef43ee360e0994f22d7bddb8e"
"pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/init/backends.py" = "blob:69ceaa1edef130a38214423956b839741e243614"
-"pipelex/cli/commands/init/command.py" = "blob:80ad0831db0688a02aeac916ea6b87ccae4a093b"
+"pipelex/cli/commands/init/backends.py" = "blob:1618d4f7f16c6d5a814680b17185501fade9f3fd"
+"pipelex/cli/commands/init/command.py" = "blob:21c700c66b9c608e14e6bb373c40d37c241ea509"
"pipelex/cli/commands/init/config_files.py" = "blob:6e926eb3beb3c12a38d25f34c10e7b5ab6a7a99a"
"pipelex/cli/commands/init/credentials.py" = "blob:7475c3082b8ee7530a76a52a8ab8bf18a7e21209"
"pipelex/cli/commands/init/ide_extension.py" = "blob:b1ff7341253a56a8cbccfccce7b14d9053cd5b16"
-"pipelex/cli/commands/init/routing.py" = "blob:224e4e46c519edb7d64060d32395c4332099560f"
+"pipelex/cli/commands/init/routing.py" = "blob:e8206196776ae43c12804ac74f770e72a681e1b6"
"pipelex/cli/commands/init/telemetry.py" = "blob:da0c79bdf04b97f0655c42bc9cea98e9e40ea256"
"pipelex/cli/commands/init/ui/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/init/ui/backends_ui.py" = "blob:16006c2efa81640ef196986a527b629b4d91fbda"
@@ -103,30 +103,30 @@ rationale = "Trigger changes are the subject-grant regrind's internal signature
"pipelex/cli/commands/init/ui/routing_ui.py" = "blob:640bd0d11d1879ead83fd9f3d1736d2735c1abfa"
"pipelex/cli/commands/init/ui/types.py" = "blob:1361f29ca95bacc90bca90ea6c0e39f44b6734ab"
"pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/login/command.py" = "blob:6ae5c3db3d6da208be955ff9ab66022ee162a2b8"
-"pipelex/cli/commands/plugins_cmd.py" = "blob:2987904797831cdff476d1034d513320051cbb5a"
-"pipelex/cli/commands/resolve_cmd.py" = "blob:7b3f61ee79619a90e8428d9bc376d3b43c2816dc"
+"pipelex/cli/commands/login/command.py" = "blob:ace1db9879626cc1722adaac12761aadaa6b24ed"
+"pipelex/cli/commands/plugins_cmd.py" = "blob:4ad42bd78b117985f2d7478939e4cabc5b64dc4b"
+"pipelex/cli/commands/resolve_cmd.py" = "blob:2233ab12b7cd5ef0bce697d9599d13a09e242dde"
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049"
"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
-"pipelex/cli/commands/run/_run_core.py" = "blob:2862ba63bc6571b60cf9b37a0d1132c95400d344"
+"pipelex/cli/commands/run/_run_core.py" = "blob:b258aa23453b7e552cfbc1ebe03d3b369dbfbd1a"
"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"
"pipelex/cli/commands/run/bundle_cmd.py" = "blob:2c0233ff88988038cc6f4189499ef1744a9579c3"
"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
"pipelex/cli/commands/run/method_cmd.py" = "blob:828bd9b9c72a0e1132e54241817e388c97d9adad"
"pipelex/cli/commands/run/pipe_cmd.py" = "blob:88878cb413b406612d16140ec1b1b9bed8c90d94"
-"pipelex/cli/commands/show_cmd.py" = "blob:5687ac523a7e22168b5db5bc622f70cf284fb031"
-"pipelex/cli/commands/update_cmd.py" = "blob:ca40a94d5756ee9bfb89251b931026bb39b9901e"
+"pipelex/cli/commands/show_cmd.py" = "blob:73eca220d97e0d3bac3b713b109b477b9e6fd4c8"
+"pipelex/cli/commands/update_cmd.py" = "blob:06100ec3b9d6c66ca89a8c1536aa27983ae409ca"
"pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/validate/_validate_core.py" = "blob:4613d20bc67d8b1b917cc70b50834b8f912338d9"
+"pipelex/cli/commands/validate/_validate_core.py" = "blob:4b07f6dabd7841b1502446f39077dfbb6dd805a3"
"pipelex/cli/commands/validate/app.py" = "blob:309061423af13f2f6c496a024306ad696af567ab"
"pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9"
"pipelex/cli/commands/validate/method_cmd.py" = "blob:2cb68d5c371a5b45841fce9c26da5e4622e6b042"
"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:5720f3a3f4f3c555e772a2dbb335c3139ae4457e"
-"pipelex/cli/commands/which_cmd.py" = "blob:539c708523b4adf723ef58c79d9de66c365231d4"
-"pipelex/cli/deck_notice.py" = "blob:ff0caeb50971f1b9828b2b4336ebc40312fe1b5f"
-"pipelex/cli/error_handlers.py" = "blob:9b69c4de9d95999b666ce47e52eaa95c3efb481f"
+"pipelex/cli/commands/which_cmd.py" = "blob:95fe153d65364449e26e9408c53441aa5fb4cf06"
+"pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"
+"pipelex/cli/error_handlers.py" = "blob:ec4005ac908fac151275db3b28cc1685edd585b0"
"pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a"
"pipelex/cli/installed_methods.py" = "blob:2a1adeda25082bd2bef44887b9af60c29dab8d7b"
"pipelex/cli/method_resolver.py" = "blob:850ad43ee2c6fb0ffc3f449f62ceea1ab6f17297"
-"pipelex/cli/readiness.py" = "blob:16393528f294750878d2381d151ddc3da36e6bb2"
+"pipelex/cli/readiness.py" = "blob:6d185324ed0784663e1dc78d1194a28312c54798"
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index d63e71734..1c6b76fae 100644
--- a/.drift/acks/config-docs.toml
+++ b/.drift/acks/config-docs.toml
@@ -1,20 +1,20 @@
contract = "config-docs"
-digest = "sha256:5edb794b698cc0513be0e904c3a2f82a1a7ff470e86d05df5e710dd30368ee25"
-reviewed_by = "Claude (Fable 5)"
-reviewed_at = "2026-07-16T09:45:00Z"
-rationale = "Trigger diff: configs.py wires the new pipe_func section onto the main config model (PipeFuncConfig import + pipe_func_config field on Pipelex), plus comment-only wording in pipelex.toml + pipe_func_config.py: removed the stale claim of a core 'local_sandbox' execution mode (nobody registers it; core ships only 'direct', our Daytona plugin ships 'daytona') and switched plugin mentions to the 'our Daytona sandbox plugin' style. No default changed. Reviewed docs/configuration: pipe_func_config (incl. its new attachment on the root model) deliberately has no page, like its internal siblings; library-config.md's @pipe_func registration prose is unaffected; no configuration doc mentions local_sandbox — nothing to update. (Rationale amended 2026-07-17: the original wrongly described the trigger diff as comment-only, omitting the configs.py field wiring; the reviewed conclusion is unchanged.)"
+digest = "sha256:821341693eb86945913565bae7d9689c023cb0c6d60992aade1711b8c295a188"
+reviewed_by = "Claude (Opus 5)"
+reviewed_at = "2026-07-26T09:35:13Z"
+rationale = "Trigger diff is import-path-only: config_check.py and aws_config.py each changed exactly one line, 'from pipelex.service_hub import' -> 'from pipelex.runtime_hub import', from the runtime/interpreter hub rename. Verified by diffing both files and filtering out every line naming a hub — nothing remained. No config field, default, validator, or TOML key moved. Opened and read docs/configuration/: its only reference to either trigger is aws-config.md, which documents the TOML section '[pipelex.aws_config]' and cites no Python import path anywhere in the tree. Nothing to update."
[trigger_files]
"pipelex/cogt/config_cogt.py" = "blob:fca7b96f9147122b6b8300471cac637b05fed1ee"
"pipelex/cogt/img_gen/img_gen_job_components.py" = "blob:084985080413fd8d6c3b1b9b0747020cb0161858"
"pipelex/pipelex.toml" = "blob:e646e431b5db2e467bc962b738be7bc9f3b3ffb8"
"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
-"pipelex/system/configuration/config_check.py" = "blob:12cf96754989b59ffced39521e3fe11606058d8f"
+"pipelex/system/configuration/config_check.py" = "blob:efa78599c08e5e003d975cc54978ea5d267214a0"
"pipelex/system/configuration/config_loader.py" = "blob:af3ba71ed4e589cec42cb197d7d11539cea50ecd"
"pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339"
"pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160"
-"pipelex/system/configuration/configs.py" = "blob:281f0674f4403d636ad4a99d1954004849939157"
+"pipelex/system/configuration/configs.py" = "blob:99c936343aab7bcd4dee78631164ef10a32ebfe9"
"pipelex/system/configuration/pipe_func_config.py" = "blob:df1cbd3698d51c96d8fa8a8c6fdf1c6be57e5771"
"pipelex/system/telemetry/telemetry_config.py" = "blob:b6912e8be8932b65213dab23ac66372b8b45ca58"
-"pipelex/tools/aws/aws_config.py" = "blob:4c0b30c6f500aaf0f4c25395fc361a20d2e7f828"
+"pipelex/tools/aws/aws_config.py" = "blob:c1aeafeae08d3921464db33795f11a29ff3892ba"
"pipelex/tools/log/log_config.py" = "blob:7b6d032ffea29d6ce60e8af7106f2d935bc18348"
diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.toml
new file mode 100644
index 000000000..222b91dc8
--- /dev/null
+++ b/.drift/acks/hub-layering-convention.toml
@@ -0,0 +1,10 @@
+contract = "hub-layering-convention"
+digest = "sha256:236faf135b429372b9f93c0f750a55726db9e23d6dcd18943c30db7de7e131b0"
+reviewed_by = "Claude (Opus 5 1M context)"
+reviewed_at = "2026-07-26T17:04:11Z"
+rationale = "Guard-only trigger change, and it tightens a carve-out rather than churning imports: `_is_type_checking_test` matched `ast.Attribute(attr=...)` with an unconstrained receiver, so any `settings.TYPE_CHECKING:` block claimed the layer-rule exemption while being an ordinary runtime condition. The attributed form is now rooted at `typing` (new TYPING_MODULE_NAME constant), with a test asserting three unrelated receivers stay violations; verified by mutation that reverting the predicate fails that test and nothing else. Re-ran both mechanical checks the last ack prescribes: 33 + 32 public module-level hub symbols, all still present in the doc's partition tables, and all 12 declared runtime-layer entries still named under Enforcement — neither hub module changed here, so no table could have moved. Updated the doc's TYPE_CHECKING carve-out bullet to state the receiver constraint, since as written it read as exempting any attribute merely named TYPE_CHECKING. Also refreshed the two test-module sentences in the same section, which the same change made stale: the closure test now carries a negative control (its detector lives in a dedent string that nothing lints, so a typo would make every entry point pass vacuously) plus a subprocess timeout, and the lifecycle test now pins the real `Pipelex.teardown` rather than a stand-in calling `class_registry_scoping.reset()` directly. Rest of the page re-read: the two rules, the string-literal half, the core split, Known inversions and the F1 measurement are all unaffected by this change and remain accurate."
+
+[trigger_files]
+"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:93d985daadb6323335090caa3a1fd2ba6050496e"
+"pipelex/interpreter_hub.py" = "blob:4081f279518a8ed82fe425f035a916f8053edd5c"
+"pipelex/runtime_hub.py" = "blob:02f910112ad53872b2f6760bd601fdafc5161058"
diff --git a/.drift/acks/keyword-only-convention.toml b/.drift/acks/keyword-only-convention.toml
index caa281a5c..ef985a02b 100644
--- a/.drift/acks/keyword-only-convention.toml
+++ b/.drift/acks/keyword-only-convention.toml
@@ -1,8 +1,8 @@
contract = "keyword-only-convention"
-digest = "sha256:2d2a8228601e1fa98d483b5c1d162ddcb8037ac02391d1c0409f8bd48d203571"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-07-11T15:45:25Z"
-rationale = "Phase 5 closed the transitional door: --seed and the seeded field are deleted, the registry schema is strict (param + rationale only). Rewrote the doc's transitional-state section as the post-transitional Registry schema section and fixed the --report description."
+digest = "sha256:0814e13945bbe89a6d731218e5324ef877bcaa6354b101d409d7981b93a213fd"
+reviewed_by = "Claude (Opus 5)"
+reviewed_at = "2026-07-26T09:35:34Z"
+rationale = "The trigger diff in keyword_only_guard.py is docstring-only: two prose references to pipelex.service_hub renamed to pipelex.runtime_hub by the runtime/interpreter rename. No guard behavior changed — no new violation kind, no registry schema change, no carve-out, no CLI flag, no change to the stdlib-only constraint the docstring describes. Opened docs/contribute/keyword-only-arguments.md: it names the presentation layer generically ('no Typer/hub import'), which stays accurate with two hubs under any name; its one worked grant example keys off pipelex/builder/build.py, not a hub module; and it carries no hardcoded grant count, so this change's registry migration (55 hub grants re-keyed from pipelex/service_hub.py and pipelex/method_hub.py to pipelex/runtime_hub.py and pipelex/interpreter_hub.py, with the ServiceHub./MethodHub. qualnames and the two set_instance param names rewritten) needed no doc edit. That migration is itself the doc's documented 'staleness is symmetric' path, exercised as specified — done before any check ran, and make cko passes. Nothing to update."
[trigger_files]
-"pipelex/cli/dev_cli/commands/keyword_only_guard.py" = "blob:c998cfc324c7f1096e974133b75db59c6190c117"
+"pipelex/cli/dev_cli/commands/keyword_only_guard.py" = "blob:c1d6ae57b3814ed57eff2169109db1ddb3fe0d58"
diff --git a/.github/workflows/lint-check.yml b/.github/workflows/lint-check.yml
index 7b9f8524d..ad54db297 100644
--- a/.github/workflows/lint-check.yml
+++ b/.github/workflows/lint-check.yml
@@ -132,7 +132,31 @@ jobs:
run: make check-keyword-only
# --------------------------------------------------------------------------
-# 5. Drift contracts — single job, version-independent
+# 5. Hub layering boundary — single job, version-independent
+# --------------------------------------------------------------------------
+ lint-hub-layering:
+ name: Lint (hub layering)
+ runs-on: ubuntu-latest
+ env:
+ VIRTUAL_ENV: ${{ github.workspace }}/.venv
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install uv (with cache)
+ uses: astral-sh/setup-uv@v7
+ with:
+ enable-cache: true
+ cache-dependency-glob: "uv.lock"
+
+ - name: Install dependencies
+ run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+
+ - name: Run hub layering check
+ run: make check-hub-layering
+
+# --------------------------------------------------------------------------
+# 6. Drift contracts — single job, version-independent
# ADVISORY: deliberately NOT in lint-all's `needs`, so an open contract is
# visible on the PR but does not block merges. Promote it into lint-all's
# `needs` once the current open-PR backlog has landed.
@@ -159,12 +183,12 @@ jobs:
run: make drift-check
# --------------------------------------------------------------------------
-# 6. Aggregator job — the *single* required status check
+# 7. Aggregator job — the *single* required status check
# --------------------------------------------------------------------------
lint-all:
name: Lint (all)
runs-on: ubuntu-latest
- needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only]
+ needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only, lint-hub-layering]
if: always()
steps:
@@ -173,7 +197,8 @@ jobs:
if [ "${{ needs.lint-ruff-plxt.result }}" != "success" ] || \
[ "${{ needs.lint-typecheck.result }}" != "success" ] || \
[ "${{ needs.lint-config-sync.result }}" != "success" ] || \
- [ "${{ needs.lint-keyword-only.result }}" != "success" ]; then
+ [ "${{ needs.lint-keyword-only.result }}" != "success" ] || \
+ [ "${{ needs.lint-hub-layering.result }}" != "success" ]; then
echo "::error::At least one lint job failed."
exit 1
fi
diff --git a/.github/workflows/lint-fresh-check.yml b/.github/workflows/lint-fresh-check.yml
index c04344a1a..dbf2bf314 100644
--- a/.github/workflows/lint-fresh-check.yml
+++ b/.github/workflows/lint-fresh-check.yml
@@ -61,6 +61,9 @@ jobs:
- name: Run keyword-only convention check
run: make check-keyword-only
+ - name: Run hub layering check
+ run: make check-hub-layering
+
- name: Run drift contracts check
run: make drift-check
diff --git a/.pipelex/inference/backends/pipelex_gateway_models.md b/.pipelex/inference/backends/pipelex_gateway_models.md
index 99d8f2a01..645adda83 100644
--- a/.pipelex/inference/backends/pipelex_gateway_models.md
+++ b/.pipelex/inference/backends/pipelex_gateway_models.md
@@ -101,6 +101,14 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
<td style="text-align:center;background-color:rgba(76,175,80,0.15)">✅</td>
</tr>
<tr>
+<td>claude-5-sonnet</td>
+<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(76,175,80,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(76,175,80,0.15)">✅</td>
+</tr>
+<tr>
<td>deepseek-v3.2</td>
<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
<td style="text-align:center;background-color:rgba(33,150,243,0.15)">❌</td>
@@ -612,6 +620,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
> **AUTO-GENERATED FILE** - Do not edit manually.
-> Last updated: 2026-07-06T14:28:01Z
+> Last updated: 2026-07-27T01:18:06Z
>
> Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.
\ No newline at end of file
diff --git a/.pipelex/inference/backends/pipelex_gateway_models_plain.md b/.pipelex/inference/backends/pipelex_gateway_models_plain.md
index 9ba8afa22..45ceaff0e 100644
--- a/.pipelex/inference/backends/pipelex_gateway_models_plain.md
+++ b/.pipelex/inference/backends/pipelex_gateway_models_plain.md
@@ -37,6 +37,9 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
- **claude-4.8-opus**
- inputs: text, images, pdf
- outputs: text, structured
+- **claude-5-sonnet**
+ - inputs: text, images, pdf
+ - outputs: text, structured
- **deepseek-v3.2**
- inputs: text
- outputs: text, structured
@@ -229,6 +232,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
> **AUTO-GENERATED FILE** - Do not edit manually.
-> Last updated: 2026-07-06T14:28:01Z
+> Last updated: 2026-07-27T01:18:06Z
>
> Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17b623bb8..b941e39d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,18 @@
# Changelog
+## [Unreleased]
+
+### Changed
+
+- **Breaking: `pipelex.hub` is gone, split into `pipelex.runtime_hub` and `pipelex.interpreter_hub`.** The split names the two layers it separates, on the textbook language-implementation division: the **runtime** is the machinery present at execution time whatever is loaded, the **interpreter** reads a method and executes it. There is no alias shim — a stale import fails loudly at import time rather than silently resolving to the wrong layer. `runtime_hub` holds process-scoped infrastructure (config, console, secrets, storage, telemetry, models, inference, content generation, reporting, run mode, tracing, the plugin registries, `get_class_registry`); `interpreter_hub` holds the loaded method's machinery (library manager and lookups, the current-library contextvar, library dirs, pipe router, pipe run and pipeline manager, the PipeFunc executor). `get_pipelex_hub` splits into `get_runtime_hub` / `get_interpreter_hub`, so every external call site must pick the container it actually meant. The rule is one-way and mechanically enforced (`make check-hub-layering`, alias `chl`, in `make agent-check` and CI): `interpreter_hub` may import `runtime_hub`, never the reverse, and no module anywhere may reference `pipelex.hub` — in an import *or* a string literal (dynamic import, mock patch target, config path). The payoff is measurable and pinned by a subprocess import-closure test: importing the Pipelex runtime now loads **zero** interpreter modules, down from 50 — you can embed the inference engine without loading a line of the MTHDS interpreter. See [Hub layering convention](contribute/hub-layering.md).
+- **Breaking: misplaced types moved to the package that actually owns them.** `JobMetadata` / `JobCategory` / `UnitJobId` → `pipelex.system.job_metadata`, `JobMetadataError` → `pipelex.system.exceptions`, `TraceContext` → `pipelex.system.trace_context`, `DataInclusionConfig` → `pipelex.system.data_inclusion_config`, `TextFormat` → `pipelex.tools.templating.text_format`, `TemplatingStyle` / `TagStyle` → `pipelex.tools.templating.templating_style`, `TemplateCategory` → `pipelex.tools.jinja2.template_category`, and the neutral resolved-field layer → `pipelex.core.concepts.resolved_fields`. The TOML config shape is unchanged throughout (`[...graph_config.data_inclusion]` still parses); only the Python homes moved. The two pipe renderers regrouped into `pipelex.core.pipes.rendering` (`input_renderer` from `core.pipes.inputs`, `output_renderer` from `core.pipes.output`).
+- **Breaking: `core/`'s data model resolves concepts and pipes through injected providers instead of reaching into the hub.** `StuffFactory.make_stuff_from_stuff_content_or_data` / `make_from_blueprint` / `make_from_concept_ref`, `InputShaper.shape` / `resolve_input_kind`, `WorkingMemoryFactory.make_from_pipeline_inputs`, `InputStuffSpecsFactory.make_from_blueprint` / `make_from_string`, and `StuffSpecFactory.make_from_blueprint` all take a required `concept_provider`. A new read-side contract owns that surface — `ConceptProviderAbstract` (`pipelex.core.concepts.concept_provider_abstract`), which `ConceptLibraryAbstract` now extends, keeping library management in the interpreter layer. There is no pipe counterpart: nothing in core's runtime half resolves a pipe, so `get_required_pipe` stays on `PipeLibraryAbstract`. `pipelex.core`'s data-model packages join the enforced runtime layer as a result; the half that names a `Pipe` stays in the interpreter layer by construction.
+
+### Fixed
+
+- **`hub.set_observer()` was documented as the way to register a custom observer, and never worked.** The value was written to the hub and never read — the live path is `Pipelex.make(observers={...})` → `MultiObserver` → `PipeRouter`, so anyone following that page got a silently ignored observer. The write-only state is deleted and both `docs/advanced/observer-provider-injection.md` and `docs/advanced/index.md` are rewritten to the mechanism that actually works, with a warning against hand-constructing a hub.
+- **A duplicate `set_library_manager` pair in `Pipelex.setup` built, registered, then silently discarded a first `LibraryManager()`** when the caller passed none. Removed.
+
## [v0.40.0] - 2026-07-19
### Added
diff --git a/Makefile b/Makefile
index 20d2def1d..e5ce5eaaf 100644
--- a/Makefile
+++ b/Makefile
@@ -156,6 +156,8 @@ make fix-keyword-only - Auto-fix keyword-only-args violations (insert a
make fko - Shorthand -> fix-keyword-only
make subject-grant - Record a subject grant (FUNC="<path>::<qualname>" RATIONALE="…")
make sgr - Shorthand -> subject-grant
+make check-hub-layering - Enforce the runtime_hub / interpreter_hub layering boundary
+make chl - Shorthand -> check-hub-layering
make check-TODOs - Check for TODOs
make docs - Serve documentation locally with mkdocs
@@ -195,7 +197,7 @@ export HELP
.PHONY: \
all help env env-verbose check-uv check-uv-verbose lock install update build \
format lint ruff-format ruff-lint pyright mypy pylint plxt plxt-format plxt-lint \
- rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko subject-grant sgr check-rules check-urls cu insert-skeleton \
+ rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko subject-grant sgr check-hub-layering chl check-rules check-urls cu insert-skeleton \
drift-plan dp drift-check dc drift-ack da \
cleanderived cleanenv cleanall \
test test-xdist t test-quiet tq test-with-prints tp test-inference ti \
@@ -356,6 +358,13 @@ subject-grant: env
sgr: subject-grant
@echo "> done: sgr = subject-grant"
+check-hub-layering: env
+ $(call PRINT_TITLE,"Enforcing the runtime_hub / interpreter_hub layering boundary")
+ $(VENV_PIPELEX_DEV) check-hub-layering --quiet
+
+chl: check-hub-layering
+ @echo "> done: chl = check-hub-layering"
+
drift-plan: env
$(VENV_PIPELEX_DEV) drift plan $(CONTRACT)
@@ -1133,10 +1142,10 @@ cc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update
up: generate-mthds-schema-quiet update-gateway-models-quiet up-kit-configs rules
@echo "> done: up = generate-mthds-schema update-gateway-models up-kit-configs rules"
-check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema check-keyword-only drift-check format lint pyright mypy pylint
+check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema check-keyword-only check-hub-layering drift-check format lint pyright mypy pylint
@echo "> done: check"
-agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-keyword-only
+agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-keyword-only check-hub-layering
@echo "> done: agent-check"
v: validate
diff --git a/TODOS.md b/TODOS.md
new file mode 100644
index 000000000..6f6935a1e
--- /dev/null
+++ b/TODOS.md
@@ -0,0 +1,683 @@
+# TODOS — split `pipelex.hub` into `runtime_hub` + `interpreter_hub`
+
+**Worktree:** `_hub/` · **Branch:** `refactor/Hub` (off `origin/dev`, base `f23fda7a0` = v0.40.0) · **PR:** [#1062 → `dev`](https://github.com/Pipelex/pipelex/pull/1062), open.
+
+**Status:** **ALL PHASES DONE + THE RENAME LANDED + PHASES A AND B OF THE REVIEW FOLLOW-UPS APPLIED — all gates green.** PR #1062 is open. **Jump to [Checkpoint B record](#checkpoint-b-record--test-hardening) first**, then [Checkpoint A record](#checkpoint-a-record--pr-1062-review-follow-ups), then [▶ Resume here](#-resume-here-the-rename-is-landed) for the state they build on.
+
+> ⚠ **The `/review` follow-ups are partially applied.** The executable plan is [`wip/hub/pr-1062-review-followups.md`](wip/hub/pr-1062-review-followups.md) — read it before touching this branch. **Phase A (A1's doc-honesty fix + A2–A8) is done**, recorded at [Checkpoint A](#checkpoint-a-record--pr-1062-review-follow-ups); **Phase B (test hardening, B1–B7) is done**, recorded at [Checkpoint B](#checkpoint-b-record--test-hardening) — every item mutation-verified. **Phase C (release-wave additions) is not started**, and neither is the F1 remedy.
+>
+> **The defect Phase A documents is still live**, deliberately: the layer rule is enforced only one hop deep, so four modules of the *declared runtime-layer* `pipelex.plugins` package load `interpreter_hub` (plus 57–67 interpreter modules) with both gates green. Re-verified twice — 2026-07-26 by the review, and again at Checkpoint A before publishing the numbers. Three things about it are settled and worth not re-deriving: the blast radius is exactly 4 of 476 declared runtime-layer modules, all in `plugins` (the other ten packages are clean across 345 modules); there are three transitive routes, not just the `runtime_bridge` one named in the first draft, and only two of the four modules are leaves; and **the shipped 0-interpreter-modules headline property is *not* damaged** — the inference layer and `runtime_hub` still measure 0 and never reach the breaching modules. What was false was the doc's *scope claim*, and A1 fixed exactly that.
+>
+> **D-R4 is DECIDED (2026-07-27): remedy (d) paired with a minimal (c), in its own PR after #1062 merges** — the built-ins split by layer, the two interpreter-touching plugins relocate to a single interpreter-side home (e.g. `pipelex/interpreter_plugins/`), the weld moves to where welding is legal, and the guard learns the transitive check. Simulated: `pipelex.plugins` goes to 0 of 128 breaching with 3 modules relocated, so the declaration keeps its single line and becomes true. The full decision record and resolutions are in the plan (D-R4 + "Remedy (d) — resolutions").
+>
+> The plan also carries additions the [cross-repo sweep](#cross-repo-sweep) tables below are missing — five consumer repos, and the `docs/specs/` + `conformance/` governed surface that names `pipelex.hub` explicitly. Those are Phase C, folded into the release-gated sweep per D-R1.
+
+The split is landed, the boundary is mechanically enforced (`make check-hub-layering` + a subprocess import-closure test over eight entry points), the misplaced types are moved, and core's data model has joined the runtime layer behind injected providers. Every runtime-layer entry point measures **0 interpreter modules**. Docs and the CHANGELOG breaking-change note are written, and the [runtime/interpreter rename](wip/hub/layer-and-hub-renaming.md) is applied throughout.
+
+**What is left is not a phase** — it is the release-gated [cross-repo sweep](#cross-repo-sweep) (three waves). Nothing else is open.
+
+### Cold start — read in this order
+
+1. [The one rule](#the-one-rule) and [Symbol partition](#symbol-partition) — the settled boundary.
+2. [Checkpoint H-4 record](#checkpoint-h-4-record) — **start here**: why the plan's "all of `core/` goes low" premise was wrong, the `if it names a Pipe, it is high` rule that replaced it, and the injected-provider pattern.
+3. [Checkpoint H-3 record](#checkpoint-h-3-record) — the two type moves, why `TraceContext` had to travel with `JobMetadata`, and why the templating primitives split across two packages.
+4. [Checkpoint H-2 record](#checkpoint-h-2-record) — what the guard actually enforces (two rules, not one), its two carve-outs, and two CI wiring traps.
+5. [Checkpoint H-1 record](#checkpoint-h-1-record) — the split itself, including the two places reality forced a change to the plan (the D5 slot could not live on `RuntimeHub`; boot was deliberately not reordered).
+6. [`docs/contribute/hub-layering.md`](docs/contribute/hub-layering.md) — the shipped specification: the two halves, "Where core splits", enforcement, and "Placement, not coupling".
+
+Three notes for whoever picks this up:
+
+- **The cross-repo sweep is the only substantial work remaining, and it is release-gated.** Three waves now: the `pipelex.hub` split ([table](#cross-repo-sweep)), the Phase 3 type moves ([table](#cross-repo-impact-added-by-phase-3)), and the Phase 4 moves + signature changes ([table](#cross-repo-impact-added-by-phase-4)). Do all three in one pass per repo.
+- **The `hub-layering-convention` drift contract is now in the manifest.** Louis gave explicit say-so; it was added, reviewed, and acked — see [Proposed, reverted, then landed](#proposed-reverted-then-landed).
+- **`core.pipes.pipe_output → pipeline.pipeline_models` was NOT removed.** H-3 predicted Phase 4 would take it out; it did not. It remains one of the two edges pulling non-inference modules into the inference closure, which is why the module/SLOC rows are flat at H-4. The reason recorded at H-4 — "`pipe_output` is on the Pipe-touching (high) side of the core split" — was **wrong**, and the PR #1062 review corrected it: `pipe_output` names no `Pipe`, imports zero interpreter modules, and sits inside `runtime_hub`'s own closure. It is runtime-layer. What survives is the edge itself: `SpecialPipelineId` is a leaf constant filed in an interpreter-named package. See [`wip/pr-1062-review-notes.md`](wip/pr-1062-review-notes.md).
+- **The PR #1062 agent-review pass is recorded in [`wip/pr-1062-review-notes.md`](wip/pr-1062-review-notes.md).** It fixed the `pipe_output` misclassification above, widened the import-closure predicate to name core's Pipe machinery (closing a real `core.pipes.pipe_blueprint` blind spot), and deferred one item: `pipeline` / `pipe_run` / `graph` leak leaf models into every runtime closure, so the predicate cannot name them yet.
+
+Design rationale, alternatives considered, and the full measured argument live in [`wip/hub/hub-split-refactor.md`](wip/hub/hub-split-refactor.md). This file is the executable tracker: what to do, in what order, with the concrete tables the work needs. Where the two disagree, this file wins — it carries the settled decisions and the re-measured numbers.
+
+ℹ **The names in this document are the final ones.** Louis challenged the Phase 0–4 naming at the close of H-4 and settled on a rename, which has since **landed as its own commit**: the layers are **runtime** / **interpreter**, and the hubs are `runtime_hub` (`RuntimeHub`) / `interpreter_hub` (`InterpreterHub`). This tracker has been swept to those names — including the cross-repo tables, so the sweep rewrites external repos exactly once, straight to the final names. The intermediate `service_hub` / `method_hub` names never shipped. The decision, the rejected alternatives, and the mechanical plan are in [`wip/hub/layer-and-hub-renaming.md`](wip/hub/layer-and-hub-renaming.md); [D1](#decisions) keeps the original naming decision's reasoning verbatim.
+
+Note that the prose below still uses "low layer" / "high layer" in the historical checkpoint records (H-1 through H-4), because that was the vocabulary at the time. Read *low* as **runtime** and *high* as **interpreter**; the shipped code, tests, guard and docs use only the new terms.
+
+## The one rule
+
+`interpreter_hub` may import `runtime_hub`. **`runtime_hub` must never import `interpreter_hub`.** That single arrow is the whole architecture, and it is what the Phase 2 guard checks.
+
+> At H-1 only the forbidden direction is load-bearing; the permitted one turned out to be unused, because the one low-layer thing `interpreter_hub` needs (the class-registry scoping slot) lives below *both* hubs. Importing either hub loads the other in neither direction — stronger than the rule requires. Phase 2's guard should still check the forbidden direction, not assert the permitted one exists.
+
+`pipelex/hub.py` is deleted outright — not kept as an alias for either half. A stale import must fail loudly at import time rather than silently resolve to the wrong layer.
+
+## Baseline — measured on the base commit
+
+Reproduce with the snippet in [Exit criteria](#exit-criteria--measured-not-asserted). Re-taken at CHECKPOINT H-1 — the after is in [Measured after](#measured-after).
+
+| | baseline | target after Phase 1 |
+| --- | --- | --- |
+| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | **0** |
+| pipelex modules loaded | 357 | ≤ 260 |
+| SLOC loaded | 29,193 | ≤ 19,000 |
+
+Call-site inventory (`ast`-parsed over `pipelex/` + `tests/`, zero symbols left unclassified by the partition below):
+
+| | count |
+| --- | --- |
+| files importing `pipelex.hub` | 309 |
+| — low-only | 134 |
+| — high-only | 139 |
+| — straddling (gain a second import line) | 36 |
+| parenthesized multi-line import blocks | 29 |
+| `PipelexHub()` construction sites | 5 (2 production, 3 test) |
+| `importlib.import_module("pipelex.hub")` hacks | 3 |
+
+## Decisions
+
+**D1 — module names. SUPERSEDED by the [runtime/interpreter rename](wip/hub/layer-and-hub-renaming.md); the modules are now `pipelex/runtime_hub.py` + `pipelex/interpreter_hub.py`.** The original decision, kept because its rejected alternatives are still live reasoning: *SETTLED: `pipelex/service_hub.py` + `pipelex/method_hub.py`, both flat at the package root, `pipelex/hub.py` deleted. Rejected: keeping `hub.py` for one half (a stale import would silently succeed); `library_hub` (the high half also holds the router, the runner, and the pipeline manager); a `pipelex/hubs/` package (`pipelex.hubs.services` reads worse than `pipelex.service_hub` at 300+ call sites). Noted for review: `method_hub` borrows the MTHDS noun for a runtime container — acceptable because the object genuinely holds the loaded method's libraries, but it is a conscious call against the brand-boundary rule.* That last note is exactly what Louis acted on at the close of H-4: the flat-at-the-root shape and the no-alias deletion survive unchanged, only the two names moved. `library_hub` was re-proposed and re-rejected during the rename, on the same grounds plus one more — a library is inert, while the container is active machinery.
+
+**D2 — one container or two. SETTLED: two** — `RuntimeHub` and `InterpreterHub`, each its own singleton, each with its own module-level accessors. One container would have to live in the low module, forcing every high-level slot to a quoted `TYPE_CHECKING` annotation — that keeps the god-object and adds a fig leaf. Two is affordable: the construction surface is five sites total.
+
+**D3 — where `get_pipe_func_executor_registry` lands. SETTLED: high (`interpreter_hub`).** It is a plugin registry by kind but its protocol lives in `pipe_operators/func/`. The underlying inversion — `pipelex/plugins/pipe_func_executor_registry.py` importing from `pipe_operators/` — is recorded as a follow-up (see [Known inversions](#known-inversions-not-fixed-here)), not fixed here.
+
+**D4 — does `core/` join the low layer now? SETTLED: no, not in Phase 1.** Five `core/` modules use high-hub symbols; converting them means passing resolved concepts in rather than looking them up, which is design work, not mechanical. Phase 4 does it, and the guard's low-layer set widens only when that lands.
+
+**D5 — `get_class_registry` is low but reads the library manager. SETTLED: callable resolver slot, defaulting to "no scoping", installed downward at boot.** Not in the design doc; surfaced while building the partition table. It is the decision that makes Phase 1.6 possible at all, so it is recorded here in full.
+
+> **Amended at implementation (H-1): the slot does not live on `RuntimeHub`.** It lives in a new leaf module, `pipelex/system/registries/class_registry_access.py`, reached through the `class_registry_scoping` module singleton. The mechanism, the default, and the downward-at-boot crossing are all exactly as designed below — only the physical home moved, and it was forced by a measured cycle rather than chosen. See [Checkpoint H-1 record → D5 amendment](#d5-amendment-the-resolver-slot-could-not-live-on-servicehub).
+
+Today's body reaches straight into the high layer:
+
+```python
+def get_class_registry() -> ClassRegistryAbstract:
+ library_id = _library_id.get()
+ if library_id is not None:
+ registry = get_library_manager().get_library_class_registry(library_id) # ← HIGH
+ if registry is not None:
+ return registry
+ return KajsonManager.get_class_registry()
+```
+
+`get_class_registry` is the single symbol all three `importlib` hacks want, and it has 29 importers spread across both layers — so it must be low, and it must keep its library scoping (Phase 1 is zero-behavior-change).
+
+Resolution: `RuntimeHub` grows a `Callable[[], ClassRegistryAbstract | None]` slot — default returns `None`, and boot installs the library-scoped resolver once `InterpreterHub` is populated. `get_class_registry` calls the slot and falls back to `KajsonManager.get_class_registry()`. The `_library_id` ContextVar stays in `interpreter_hub` with the rest of its family; the resolver closure is what crosses, and it crosses downward at boot, not as an import.
+
+This is not a new pattern — it is exactly how `_isolated_execution_probe` already works (`HubSlot.ISOLATED_EXECUTION_PROBE`, defaulting to `_never_in_isolated_execution`), so the precedent, the naming, and the plugin-claim machinery are all in place.
+
+Alternative considered and rejected: move the whole `_library_id` contextvar family down into `runtime_hub`. Simpler (no indirection) but it splits the "current library" concept across both modules and makes `pipelex.runtime_hub` export `set_current_library`, which reads wrong. Also rejected: drop the scoping from `get_class_registry` and expose a separate high `get_scoped_class_registry` — that is a behavior change, and `tests/unit/pipelex/test_class_registry_scoping.py` pins the current semantics.
+
+`tests/unit/pipelex/test_class_registry_scoping.py` is the regression guard for D5 — it must keep passing unmodified except for its import lines.
+
+## Symbol partition
+
+Complete and verified: an `ast` sweep of every `from pipelex.hub import …` across `pipelex/` and `tests/` classified every imported name against these two sets with nothing left over.
+
+### → `pipelex/runtime_hub.py` (runtime layer)
+
+| group | symbols |
+| --- | --- |
+| container | `RuntimeHub`, `get_runtime_hub`, `set_runtime_hub` |
+| config | `get_required_config`, `get_optional_config` |
+| console | `get_console` |
+| secrets | `get_secrets_provider`, `get_secret` |
+| system registries | `get_class_registry` (see D5), `get_func_registry` |
+| storage | `get_storage_provider` |
+| telemetry | `get_telemetry_manager`, `get_otel_tracer` |
+| models | `get_models_manager`, `get_model_deck`, `get_sdk_client_manager` |
+| 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` |
+| 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` |
+
+### → `pipelex/interpreter_hub.py` (interpreter layer)
+
+| group | symbols |
+| --- | --- |
+| container | `InterpreterHub`, `get_interpreter_hub`, `set_interpreter_hub` |
+| library manager | `get_library_manager`, `get_library` |
+| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_required_pipe`, `get_optional_pipe`, `get_pipe_source` |
+| current-library contextvar | `set_current_library`, `get_current_library`, `get_current_library_id_or_none`, `clear_current_library`, `scoped_current_library` |
+| library dirs | `resolve_library_dirs`, `get_default_library_dirs` |
+| pipe router | `get_pipe_router`, `set_pipe_router`, `teardown_current_pipe_router`, `scoped_pipe_router` |
+| run | `get_pipe_run`, `get_pipeline_manager`, `get_pipeline` |
+| pipe func (D3) | `get_pipe_func_executor`, `scoped_pipe_func_executor`, `get_pipe_func_executor_registry` |
+
+Setter methods follow their getters onto the matching container. Do **not** delete the accessors with no in-tree importers (`get_bundle_validator_registry`, `get_orchestrator_registry`, `get_pipe_func_executor_registry`, `get_default_library_dirs`, `get_func_registry`, `scoped_pipe_func_executor`) — they are reached internally via the container and several are live external plugin contract (see [Cross-repo sweep](#cross-repo-sweep)). Placement is decided by kind, not by in-tree usage.
+
+### Straddling files — hand-review list for step 1.4
+
+These are the only files that gain a second import line. Everything else is a one-line module swap.
+
+| file | low symbols | high symbols |
+| --- | --- | --- |
+| `pipelex/cli/commands/build/inputs/_inputs_core.py` | `get_telemetry_manager` | `get_library_manager`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
+| `pipelex/cli/commands/build/output/_output_core.py` | `get_telemetry_manager` | `get_library_manager`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
+| `pipelex/cli/commands/build/runner/_runner_core.py` | `get_telemetry_manager` | `get_current_library_id_or_none`, `get_library_manager`, `get_required_pipe` |
+| `pipelex/cli/commands/codegen/inputs_cmd.py` | `get_telemetry_manager` | `get_required_pipe` |
+| `pipelex/cli/commands/show_cmd.py` | `get_console`, `get_models_manager`, `get_secrets_provider`, `get_telemetry_manager` | `get_library_manager`, `get_pipe_library`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
+| `pipelex/cli/commands/validate/_validate_core.py` | `get_console`, `get_telemetry_manager` | `get_library_manager`, `get_pipe_library`, `get_pipes`, `get_required_pipe`, `resolve_library_dirs`, `set_current_library` |
+| `pipelex/cli/commands/which_cmd.py` | `get_console`, `get_telemetry_manager` | `get_library_manager`, `get_optional_pipe`, `get_pipe_source`, `resolve_library_dirs`, `set_current_library` |
+| `pipelex/core/stuffs/stuff_factory.py` | `get_class_registry` | `get_concept_library`, `get_native_concept`, `get_required_concept` |
+| `pipelex/libraries/library_manager.py` | `get_class_registry` | `get_current_library`, `get_current_library_id_or_none`, `scoped_current_library` |
+| `pipelex/pipe_operators/compose/pipe_compose.py` | `get_class_registry` | `get_concept_library`, `get_native_concept` |
+| `pipelex/pipe_operators/extract/pipe_extract.py` | `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept` |
+| `pipelex/pipe_operators/func/pipe_func.py` | `get_class_registry` | `get_pipe_func_executor` |
+| `pipelex/pipe_operators/img_gen/pipe_img_gen.py` | `get_class_registry`, `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept` |
+| `pipelex/pipe_operators/llm/helpers.py` | `get_class_registry` | `get_required_concept` |
+| `pipelex/pipe_operators/llm/pipe_llm.py` | `get_class_registry`, `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept`, `get_required_concept` |
+| `pipelex/pipe_operators/structure/pipe_structure.py` | `get_class_registry`, `get_content_generator`, `get_model_deck` | `get_concept_library`, `get_native_concept` |
+| `pipelex/pipe_run/dry_run_in_process.py` | `scoped_content_generator`, `scoped_event_log` | `get_library_manager`, `scoped_pipe_router` |
+| `pipelex/pipeline/bundle_validator.py` | `get_telemetry_manager`, `scoped_content_generator` | `clear_current_library`, `get_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipe_library`, `scoped_pipe_router`, `set_current_library` |
+| `pipelex/pipeline/pipeline_run_setup.py` | `get_event_log_override`, `get_otel_tracer`, `get_report_delegate`, `get_telemetry_manager` | `clear_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipeline_manager`, `get_required_pipe`, `set_current_library` |
+| `pipelex/pipeline/runner.py` | `get_report_delegate`, `get_telemetry_manager` | `clear_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipe_run`, `get_pipeline_manager`, `set_current_library` |
+| `tests/integration/pipelex/pipeline/test_bundle_validator.py` | `get_telemetry_manager` | `clear_current_library`, `get_library_manager`, `get_required_pipe` |
+| `tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py` | `get_report_delegate`, `get_telemetry_manager` | `clear_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_pipeline_manager`, `set_current_library` |
+| `tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py` | `get_report_delegate` | `clear_current_library`, `get_library_manager` |
+| `tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
+| `tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_branch_type_validation.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
+| `tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_unresolvable_structure_class.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
+| `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py` | `get_class_registry` | `get_native_concept`, `get_pipe_library`, `get_pipe_router` |
+| `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py` | `get_content_generator` | `get_pipe_library`, `get_pipe_router` |
+| `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py` | `get_content_generator` | `get_pipe_library`, `get_pipe_router` |
+| `tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py` | `get_report_delegate` | `get_native_concept`, `get_pipe_router`, `get_required_pipe` |
+| `tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py` | `get_report_delegate` | `get_native_concept`, `get_pipe_router`, `get_required_pipe` |
+| `tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py` | `get_class_registry` | `get_concept_library`, `get_pipe_library` |
+| `tests/integration/pipelex/system/test_hub_slot_injection_precedence.py` | `get_content_generator` | `get_pipe_router` |
+| `tests/unit/pipelex/core/memory/input_shaper/conftest.py` | `get_class_registry` | `get_concept_library` |
+| `tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py` | `get_class_registry` | `get_concept_library` |
+| `tests/unit/pipelex/test_class_registry_scoping.py` | `get_class_registry` | `clear_current_library`, `get_library_manager`, `set_current_library` |
+
+Note the shape of the `pipe_operators/` rows: every one of them straddles for the same reason — `get_class_registry` / `get_content_generator` / `get_model_deck` (low) next to `get_concept_library` / `get_native_concept` (high). That is the D4 boundary showing through, and it is what Phase 4 dissolves.
+
+## Phases
+
+### Phase 0 — declare the boundary ✅
+
+- [x] 0.1 Confirm **D5**. Settled as recorded above, and amended at implementation (the slot's home moved; the mechanism did not).
+- [x] 0.2 Baseline re-taken on the branch tip and confirmed identical to the table above (357 / 29,193 / 50).
+- [x] 0.3 Wrote [`docs/contribute/hub-layering.md`](docs/contribute/hub-layering.md) — the two hubs, the partition, how to place a new symbol, the class-registry exception, the measurement, enforcement, and the known inversions. Modelled on `keyword-only-arguments.md`. Its "Enforcement" section describes what is true at H-1 and is rewritten by Phase 2 when the guard lands.
+- [x] 0.4 Updated `docs/under-the-hood/architecture-overview.md` with a "What Keeps The Layers Apart: The Two Hubs" section naming the boundary and the one-arrow rule, linking to the contributor doc. Added both pages to the `mkdocs.yml` nav.
+
+### Phase 1 — the split ✅
+
+- [x] 1.1 Created `pipelex/runtime_hub.py`. Module-level imports verified to name nothing from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `core.bundles`, `core.concepts`, or `core.pipes`.
+- [x] 1.2 Created `pipelex/interpreter_hub.py`, importing `runtime_hub`'s layer for the D5 install. `set_interpreter_hub` installs the resolver, so scoping is live exactly when a InterpreterHub exists and a caller cannot forget to wire it.
+- [x] 1.3 Deleted `pipelex/hub.py`.
+- [x] 1.4 Rewrote all 309 call sites via an `ast` pass over the whole import statement (the 29 parenthesized blocks came through intact). The 36 straddlers each gained a second import line, as predicted. **Two string-literal references the AST pass could not see broke the suite and had to be found by running it** — see the record below.
+- [x] 1.5 Re-wired boot. Both hubs are constructed and installed at the top of `Pipelex.__init__`; every setter was retargeted to its own container. **The setter sequence was deliberately NOT reordered** — see the record below.
+- [x] 1.6 Replaced all three `importlib.import_module("pipelex.hub")` hacks with plain top-level imports and deleted the `_get_class_registry` shims. The import target is the new leaf module, not `runtime_hub` — that is the D5 amendment.
+- [x] 1.7 `Pipelex.teardown` and the `make()` failure path now release both hubs' process-global state. Pinned by `tests/unit/pipelex/test_hub_lifecycle.py`, which asserts a boot installs both singletons and that the reset really drops the scoping a InterpreterHub installed.
+
+**CHECKPOINT H-1** — zero behavior change.
+
+Gates: `make agent-check` + **full** `make agent-test` (no test edits beyond import lines) + `make drift-check`. Expect the **`cli-docs` drift contract to fire** — `pipelex/cli/**/*.py` is a trigger and the rewrite touches many CLI files. Review `docs/tools/cli/` and `pipelex/cli/agent_cli/CLAUDE.md`, then `make drift-ack` with an honest rationale ("import-path-only change, CLI surface unaffected" is legitimate if that is what the review found). Re-take the measurement and record the after against the target table.
+
+### Checkpoint H-1 record
+
+Written at the checkpoint so Phase 2 can start cold. Everything below is what actually happened, including where the plan was wrong.
+
+#### Measured after
+
+| | baseline | target | **after H-1** |
+| --- | --- | --- | --- |
+| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | **0** | **0** ✅ |
+| pipelex modules loaded | 357 | ≤ 260 | 275 |
+| SLOC loaded | 29,193 | ≤ 19,000 | 21,186 |
+
+The headline property is met exactly: the inference layer now loads **zero** `libraries` / `pipe_operators` / `pipe_controllers` / `codegen` / `builder` modules. The module and SLOC targets were missed, and the reason is that the estimate was wrong rather than the change: those targets were derived from "236 modules / 17,683 SLOC *plus headroom for cogt's own modules*", and the real headroom is ~40 modules / ~3,500 SLOC, not the ~24 / ~1,300 assumed. A low-only hub's own closure measures 235 modules / 17,675 SLOC on this branch — within 1 of the estimate — so the partition is exactly as tight as designed; only the headroom guess was low. **Do not treat the module/SLOC rows as open work.** Squeezing them further means attacking `cogt`'s own dependency weight (`system.telemetry.otel_factory` → `core.pipes.pipe_output` → `core.stuffs.stuff` is the fattest edge), which is Phase 3/4 territory, not the hub boundary.
+
+#### D5 amendment: the resolver slot could not live on `RuntimeHub`
+
+D5 assumed `core/concepts/` could reach `get_class_registry` from `pipelex.runtime_hub`. It cannot. `core.concepts.concept` is **inside `runtime_hub`'s own import closure**:
+
+```
+runtime_hub → cogt.llm.llm_worker_abstract → system.telemetry.otel_factory
+ → core.pipes.pipe_output → core.stuffs.stuff → core.concepts.concept
+```
+
+so a module-level `from pipelex.runtime_hub import get_class_registry` in `concept.py` is a hard cycle — and it fails in *both* import orders, which is why it could not simply be ordered around. The design doc's claim that "a hub that does not import `Concept` has no cycle with `concept.py`" was half right: the cycle is not via `Concept`, it is via `cogt → system → core`.
+
+Resolution, which preserves every property D5 was chosen for:
+
+- `pipelex/system/registries/class_registry_access.py` — a new leaf module importing nothing from `pipelex`. Holds the real `get_class_registry` plus the `class_registry_scoping` slot (a module singleton in the `config_manager` style; the resolver default returns `None`, so a RuntimeHub-only process degrades to the global registry rather than raising, exactly as [Risks](#risks-and-containment) requires).
+- `pipelex.runtime_hub.get_class_registry` delegates to it and stays the **public** accessor — so the symbol partition table above is unchanged and the cross-repo contract is still "low symbols come from `runtime_hub`".
+- The three `core/concepts/` modules import the leaf directly, because they are the one place the public accessor is unreachable.
+- `interpreter_hub.set_interpreter_hub` installs the library-scoped resolver; `Pipelex.teardown` calls `class_registry_scoping.reset()`.
+
+`tests/unit/pipelex/test_class_registry_scoping.py` (the D5 regression guard) passes unmodified except for its import lines, as required.
+
+#### Boot was not reordered — deliberately
+
+Step 1.5 predicted the setter sequence would "split cleanly at line 475 with no reordering" once the duplicate pair was deleted. It does not, and cannot: **D3 puts the PipeFunc executor on the high hub**, so `set_pipe_func_executor_registry` and `set_pipe_func_executor` are InterpreterHub calls sitting in the middle of the RuntimeHub run, and `set_isolated_execution_probe` is a RuntimeHub call sitting after the InterpreterHub ones.
+
+Reordering to force a clean split would have moved setters across documented ordering dependencies (the storage-provider block explicitly resolves *after* secrets is on the hub so the GCP factory's secret read works) — a real behavior risk at a checkpoint whose bar is zero behavior change. So: **both hubs are constructed and installed at the top of `__init__`, and the setter sequence is otherwise byte-identical in order.** That delivers what "populate RuntimeHub fully before InterpreterHub" was actually protecting against — no setter can ever run against a missing hub — without touching execution order. Untangling the interleave belongs with D3's inversion, not here.
+
+#### Findings in passing — both resolved, one bigger than recorded
+
+- **Duplicate `set_library_manager` deleted** ✅. Confirmed dead: nothing between the two pairs reads it, and `make tb` plus the full suite pass without it.
+- **`_observer` deleted** ✅ — but the tracker's "confirm no external consumer sets it" check turned up something worse than dead code. `docs/advanced/observer-provider-injection.md` **documented `hub.set_observer()` as the public way to register a custom observer**, and that documented API never worked: the value was written and never read, while the live path is `Pipelex.make(observers={...})` → `MultiObserver` → `PipeRouter`. Anyone following that page got a silently ignored observer. Both that page and `docs/advanced/index.md` (which showed a bare `PipelexHub()` being constructed and configured — equally inert) are rewritten to the mechanism that actually works, with a warning against hand-constructing a hub. Verified across the workspace: no repo sets `set_observer`.
+
+#### One fix outside the plan, required by the exit criterion
+
+After the split the measurement still reported 3 interpreter modules, via `content_generator → pipelex.config → plugins.pipe_func_executor_registry → pipe_operators.func.pipe_func_executor_protocol` — D3's underlying inversion, which [Known inversions](#known-inversions-not-fixed-here) had scheduled as "not fixed here". But the exit criterion demands 0 and instructs that the printed offender is what to fix, and Phase 2.5's closure regression test would fail on it regardless. The import is **type-only**, so it was deferred under `TYPE_CHECKING` with a string annotation on the type alias. The placement inversion itself is untouched and stays recorded.
+
+#### Landmines the AST rewrite could not see
+
+`pipelex.hub` ceasing to exist turns a missed *import* into an immediate `ImportError` — but not a missed **string literal**. Two of those existed, and neither is reachable by an import-graph tool:
+
+- `tests/helpers/init_cmd_helpers.py` — `mocker.patch("pipelex.hub.get_console", ...)`. This broke **36 tests** across the init CLI suites, and the failure surfaced as `AttributeError: module 'pipelex' has no attribute 'hub'` from `pkgutil.resolve_name`, nowhere near the hub.
+- `tests/unit/pipelex/cli/test_agent_cli_output_discipline.py` — `mocker.patch("...agent_cli_factory.PipelexHub.get_optional_instance")`, caught by grep before the run.
+
+If Phase 2's guard is meant to catch "the string-literal `importlib.import_module` form", it should also be pointed at `mocker.patch` targets — that is where this class of reference actually lives in this repo.
+
+#### Housekeeping done at H-1
+
+- **Subject grants migrated**: 54 `pipelex/hub.py::` entries → 55 under `pipelex/runtime_hub.py::` / `pipelex/interpreter_hub.py::` (`set_instance` and `set_pipelex_hub` each split in two; `set_observer` dropped with the state). `make cko` is green, and staleness is symmetric so a missed entry would have failed.
+- **Doc references swept**: `docs/under-the-hood/{pipe-routing-and-execution,runtime-bridge-and-transport,execution-graph-tracing}.md`, `docs/advanced/{index,observer-provider-injection}.md`, `tests/CLAUDE.md`, and in-code docstrings in `signature_walk.py` / the keyword-only guard modules. CHANGELOG history entries were left alone (they are release records). No live `pipelex.hub` reference remains anywhere in `pipelex/`, `tests/`, or `docs/`.
+
+#### Still open at H-1
+
+- **The CHANGELOG breaking-change note is not written yet** — it stays scheduled at H-4 per the plan, but `pipelex.hub` is *already* gone as of this checkpoint. If this branch is ever merged before H-4, write it first.
+- The **cross-repo sweep** is untouched and still release-gated.
+- One semantic edge worth knowing: `class_registry_scoping` is process-global, so the doctor path (which installs a fresh `RuntimeHub` but leaves any existing `InterpreterHub` in place) now keeps library scoping alive where the single hub would have raised. Strictly more coherent — the InterpreterHub genuinely is still installed — and unreachable in practice, since doctor runs in its own process. Noted rather than fixed.
+
+### Phase 2 — enforce it ✅
+
+- [x] 2.1 Added `pipelex-dev check-hub-layering` — guard in `pipelex/cli/dev_cli/commands/hub_layering_guard.py` (stdlib-only AST core), command in `check_hub_layering_cmd.py` (rich presentation), following the `keyword_only_guard.py` / `check_keyword_only_cmd.py` split exactly. Catches imports **and** string literals, and resolves relative imports against the importing module's own package. **The guard grew a second rule beyond the plan** — see the record below.
+- [x] 2.2 Low layer declared as `pipelex.cogt`, `pipelex.plugins`, `pipelex.reporting`, `pipelex.system`, `pipelex.tools`. All five compliant; the guard hard-blocks with an empty exception list (one escape-hatch marker exists, on the guard's own declaration of the forbidden path).
+- [x] 2.3 Wired into `make agent-check`, the `make check` aggregate, and both CI lint workflows, with the `chl` alias.
+- [x] 2.4 `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` — layer membership, both directions of the arrow, every import spelling (plain / aliased / `from pipelex import interpreter_hub` / relative), both string forms, the prose-is-not-a-reference and `runtime_hub`-is-not-`hub` boundary cases, the `TYPE_CHECKING` carve-out and its three non-exempt neighbours, the escape hatch, and the dead-module rule across all three layers.
+- [x] 2.5 `tests/unit/pipelex/test_runtime_layer_import_closure.py` — imports each low-layer entry point in a subprocess and asserts zero interpreter modules **and** no `pipelex.interpreter_hub` in `sys.modules`. Parametrized over two entry points: the inference layer and `runtime_hub` itself.
+
+**CHECKPOINT H-2** — boundary declared, enforced, and regression-tested.
+
+### Checkpoint H-2 record
+
+Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,352 files, keyword-only PASSED, hub-layering PASSED) · `make agent-test` ✅ (full suite) · `make drift-check` ✅ (no contract opened — see below).
+
+#### The guard enforces two rules, not one
+
+The plan specified one rule (no `interpreter_hub` in the low layer). The guard ships with a second: **no module anywhere in `pipelex/` or `tests/` may reference `pipelex.hub`.** That is the H-1 note about `mocker.patch` targets, generalized — and generalizing it is what makes it work. The plan framed the string check as an `importlib.import_module` special case; scanning *every* string constant for an exact-or-boundary match on the module path catches `importlib`, `mocker.patch`, `pkgutil.resolve_name`, and any config-driven dotted path in one mechanism, with no call-site special-casing.
+
+Scope follows from the two rules being different: `tests/` is scanned for the dead-module rule **only**. `tests.*` is in no declared layer, so a test may still freely patch `pipelex.interpreter_hub` — while a stale `pipelex.hub` patch target, the thing that actually broke 36 tests, now fails the check.
+
+Matching is exact-or-boundary (`==`, or a `.`/`:` suffix), which is why `pipelex.runtime_hub` does not match `pipelex.hub` and why a docstring that merely *mentions* a module is not a reference. Two in-tree docstrings do exactly that and are correctly ignored. A path assembled at runtime from f-strings is beyond any AST scan; nothing does that today, and it is noted in the module docstring rather than defended against.
+
+#### Two carve-outs, both deliberate
+
+- **`if TYPE_CHECKING:` is exempt from the layer rule, not from the dead-module rule.** The rule is about what *loads*; a type-only import loads nothing, and H-1's own out-of-plan fix used exactly this deferral. Its `else` branch, `if not TYPE_CHECKING:`, and any `pipelex.hub` import inside a `TYPE_CHECKING` block all stay violations — each is pinned by a test.
+- **`# hub-layering: ignore`** mirrors `# kw-only: ignore`. There is exactly one in `pipelex/` and one in the test suite, both on lines that *declare* the forbidden path as data. The guard flagged its own configuration on first run, which is a good sign about the matcher and the reason the hatch exists.
+
+#### Verified by breaking it, not only by unit tests
+
+Both forms were injected into a real low-layer module (`cogt/content_generation/content_generator.py`) and the CLI was confirmed to report them at the right lines with the right kinds, then the file was restored byte-identically. Snippet-level unit tests would not have caught a filesystem-walk or layer-membership mistake.
+
+#### Two wiring traps worth knowing
+
+- **The CI aggregator gates on an explicit bash result check, not on `needs`.** Adding `lint-hub-layering` to `lint-all`'s `needs` list is *not* enough — `if: always()` means the aggregator runs regardless, and the `[ "${{ needs.<job>.result }}" != "success" ]` chain is what actually fails the build. Both were updated. A new lint job added without touching that chain would be silently advisory.
+- **A new job, not a step on `lint-keyword-only`.** Folding both AST guards into one job would have meant renaming it, and that job name may be a required status check — a rename silently un-requires it. The repo already runs one job per guard; this follows that.
+
+#### Proposed, reverted, then landed
+
+A `hub-layering-convention` drift contract (triggers: the guard + both hub modules; review: `docs/contribute/hub-layering.md`) is the exact analogue of the existing `keyword-only-convention` contract, and it mechanizes the doc obligation Phase 4 and the rename both carried. It was added at H-2, confirmed to open correctly, then **reverted**: `.claude/skills/drift-review` states that during the pilot the manifest must not grow without the user's explicit say-so, because ack friction is the thing being measured. Left as a decision for Louis rather than a silent addition. Note that `cli-docs` legitimately did not fire on this work — it excludes `pipelex/cli/dev_cli/**`.
+
+**Louis approved it after the rename landed, and it is now in `drift.toml`, reviewed and acked.** It carries no verify command, matching `keyword-only-convention`: `check-hub-layering` already gates `make check` and CI, so re-running it before an ack would add the unstaged-file hard error without adding a guarantee. The initial review is mechanical and worth repeating rather than re-reading — extract every public module-level symbol from both hubs and confirm each appears in the doc's partition tables, then import `RUNTIME_LAYER_PACKAGES` from the guard and confirm every declared package is named under Enforcement. The closure test was deliberately left out of the triggers; it is the obvious first addition if the contract ever proves under-triggered.
+
+#### Docs updated
+
+- `docs/contribute/hub-layering.md` — the "Enforcement" section was rewritten from "a guard is the next step" to the shipped two-rule specification: what each rule checks, why the string half is the load-bearing one, both carve-outs, the `tests/` scoping, and the rule-vs-property split.
+- `docs/under-the-hood/architecture-overview.md` — one sentence stating the boundary is mechanically enforced rather than held up by review.
+
+### Phase 3 — the placement residue ✅
+
+Neither item was coupling; both were types living in the wrong package, and each was independently correct. Both are **resolved by moving the type**, not by adding indirection — no resolver slot, no protocol, no `TYPE_CHECKING` deferral was needed for either.
+
+- [x] 3.1 **`JobMetadata`** → `pipelex/system/job_metadata.py` (with `JobCategory`, `UnitJobId`); `JobMetadataError` → `pipelex/system/exceptions.py`. `TraceContext` moved with it → `pipelex/system/trace_context.py`, and `DataInclusionConfig` moved down to `pipelex/system/data_inclusion_config.py` so `trace_context` no longer imports `graph_config`. **`cogt → pipeline` is now 0 statements.**
+- [x] 3.2 **`cogt.templating.*`** → moved down to `tools`. `TextFormat` / `TemplatingStyle` / `TagStyle` → `pipelex/tools/templating/`; `TemplateCategory` → `pipelex/tools/jinja2/`. **`tools → cogt` drops from 15 statements to 3** (the `tools/pdf` renderer only).
+
+**CHECKPOINT H-3** — placement residue resolved.
+
+### Checkpoint H-3 record
+
+Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,354 files, keyword-only PASSED, hub-layering PASSED) · `make agent-test` ✅ (full suite) · `make drift-check` ✅ (no contract opened).
+
+#### Measured after
+
+| | baseline | H-1 | **after H-3** |
+| --- | --- | --- | --- |
+| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | 0 | **0** ✅ |
+| pipelex modules loaded | 357 | 275 | **268** † |
+| SLOC loaded | 29,193 | 21,186 | **20,304** † |
+
+† Recorded from a stale run, caught by the PR #1062 review and re-verified at [Checkpoint A](#checkpoint-a-record--pr-1062-review-follow-ups): the tree measures **269 / 20,305**, not 268 / 20,304. The baseline and H-1 rows reproduce to the digit, so the method is sound and only the recording was off. The 0-interpreter-modules row — the one that matters — is exact.
+
+Cross-package import statements, the number Phase 3 was actually aimed at:
+
+| edge | before | after |
+| --- | --- | --- |
+| `cogt → pipeline` | 18 | **0** |
+| `tools → cogt` | 15 | **3** |
+| `graph → cogt` | 2 | **0** |
+| `reporting → graph` | 1 | **0** |
+| `system → graph` | 1 | 1 (by design — see below) |
+
+The module/SLOC rows moved only a little because the fat edge was never `cogt → pipeline` alone. Two edges still pull `graph` and `pipeline` modules into the inference closure, and **both are out of Phase 3's scope by construction**:
+
+- `system.configuration.configs → graph.graph_config` (→ `mermaid_config`, `reactflow_config`): the main config model must name every subconfig, and the repo's convention is that submodels live in their own sub-packages. This is inherent to the one-big-config design, not a layering defect. It is the surviving `system → graph` edge.
+- `core.pipes.pipe_output → pipeline.pipeline_models`: a `core → pipeline` edge, which is **Phase 4 territory**.
+
+Together they account for the 7 `graph.*` and 2 `pipeline.*` modules still in the closure. Do not chase them here.
+
+#### 3.1 — where things landed, and why
+
+`JobMetadata` had to go somewhere `cogt` may import, which means a declared low-layer package. `pipelex/system/` is that package and it already houses `telemetry/otel_context.py` — the sibling transport `JobMetadata` carries alongside `TraceContext`.
+
+`TraceContext` moved **with** it rather than staying in `graph/`. Leaving it would only have renamed the inversion: `system/job_metadata.py → pipelex.graph.trace_context` is a `system → graph` edge, exactly the direction being removed. Its one graph dependency was `DataInclusionConfig`, so that class moved down to `pipelex/system/data_inclusion_config.py` and `graph_config.py` now imports it from there. **The TOML shape is unchanged** — the key is still `[pipelex.pipeline_execution_config.graph_config.data_inclusion]`; only the Python class's home moved. `pipelex.system.trace_context` now has a leaf closure: no `graph`, no `pipeline`.
+
+Two homes were considered and rejected for `TraceContext`: `pipelex/tracing/` (would have created a `system ⇄ tracing` package cycle, since `tracing → system` already exists) and `pipelex/system/telemetry/` (that package is OTel + PostHog; `TraceContext` is the pipelex-native node-tree transport, and conflating them would mislead).
+
+#### 3.2 — why the templating primitives split across two packages
+
+None of the three moved modules named anything from `cogt`, so this was pure misfiling. But they could not all land in one new package:
+
+- `TextFormat`, `TemplatingStyle`, `TagStyle` → `pipelex/tools/templating/`. That package imports nothing from `pipelex` beyond its own sibling — a genuine leaf.
+- `TemplateCategory` → `pipelex/tools/jinja2/`, because its entire payload is a map of jinja2 filters (`jinja2_filters`, `jinja2_models`, `jinja2_with_images_filter`). Filing it in `tools/templating/` would have made that package import `tools/jinja2` while `tools/jinja2` imports it back — a cycle inside one layer. As placed, the edges run one way: `tools/mermaid → tools/jinja2 → tools/templating`.
+
+What stays in `cogt/templating/` — `TemplateBlueprint`, the sigil preprocessor, `template_rendering` — belongs there: a blueprint is language-layer, and the rest imports `tools/jinja2` downward.
+
+#### Housekeeping done at H-3
+
+- **Subject grant migrated**: `pipelex/graph/trace_context.py::TraceContext.copy_for_child` → `pipelex/system/trace_context.py::…`. Recorded **before** running any check, per the `fko`-silently-rewrites warning in `CLAUDE.md`. No grants existed for the moved templating modules (the two that do, on `template_preprocessor` / `template_rendering`, did not move).
+- **Tests**: `tests/unit/pipelex/pipeline/test_job_metadata_request_id.py` → `tests/unit/pipelex/system/` (self-contained, so the move is free). The two `TraceContext` test modules **stayed** in `tests/unit/pipelex/graph/` — they consume `make_trace_context` and the `data_inclusion_config` / `graph_config` fixtures from that directory's `conftest.py`, which the graph tests use heavily. Splitting the fixture module to mirror the source move would cost more than the tidiness is worth.
+- **Docs**: `docs/contribute/hub-layering.md` gained a "Placement, not coupling" section recording both moves and the generalizable lesson, and its "Known inversions" bullet was corrected (`tools → cogt` is now the pdf renderer only). `docs/under-the-hood/execution-graph-tracing.md`'s file-reference table was updated for the two moved modules.
+- **`make cleanderived` deletes `tests/integration/pipelex/fixtures/_generated_model_sets.py`**, and pyright then fails on 12 unresolved-import errors that have nothing to do with your change. `make regenerate-test-models-quiet` restores it. Worth knowing before debugging a phantom failure.
+
+#### Cross-repo impact added by Phase 3
+
+These are **new** breakages on top of the `pipelex.hub` split, and they land in the same release-gated sweep:
+
+| repo | files touched by the Phase 3 moves |
+| --- | --- |
+| `pipelex-temporal/` (private) | 22 |
+| `pipelex-mistralai-workflows/` | 6 |
+| `pipelex-api/` | 1 |
+
+The import lines to rewrite, in full:
+
+| old | new |
+| --- | --- |
+| `pipelex.pipeline.job_metadata` | `pipelex.system.job_metadata` |
+| `pipelex.graph.trace_context` | `pipelex.system.trace_context` |
+| `pipelex.graph.graph_config import DataInclusionConfig` | `pipelex.system.data_inclusion_config import DataInclusionConfig` |
+| `pipelex.pipeline.exceptions import JobMetadataError` | `pipelex.system.exceptions import JobMetadataError` |
+| `pipelex.cogt.templating.text_format` | `pipelex.tools.templating.text_format` |
+| `pipelex.cogt.templating.templating_style` | `pipelex.tools.templating.templating_style` |
+| `pipelex.cogt.templating.template_category` | `pipelex.tools.jinja2.template_category` |
+
+Clean (no action): `pipelex-cookbook/`, `cocode/`, `pipelex-worker/`, `pipelex-starter-python/`, `pipelex-relay/`, `sandbox/`.
+
+### Phase 4 — core's data model joins the low layer ✅
+
+- [x] 4.1 Converted the `core/` straddlers to injected providers. **The plan's premise was wrong** — `core/` is two layers, not one, and only its *data model* can be low. See the H-4 record.
+- [x] 4.2 Widened the guard's low layer with core's six data-model packages, and added six `pipelex.core.*` entry points to `RUNTIME_LAYER_ENTRY_POINTS`.
+
+**CHECKPOINT H-4** — the boundary is complete, enforced, and measured.
+
+### Checkpoint H-4 record
+
+Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,356 files, keyword-only PASSED, hub-layering PASSED) · `make agent-test` ✅ (full suite, no test edits beyond the mechanical ones recorded below) · `make drift-check` ✅ (both contracts reviewed and acked — see below).
+
+## ▶ Resume here — the rename is landed
+
+All four phases **and** the runtime/interpreter rename are landed, with all three gates green. The rename's own record is [below](#the-runtimeinterpreter-rename-record); the rest of this section is the H-4 close-out it followed.
+
+The two contracts that were left open on purpose at the H-4 pause were reviewed and acked:
+
+- **`config-docs` — clean-pass.** The only trigger change was one import line in `configs.py` (`TemplatingStyle` moving `cogt.templating` → `tools.templating`, the Phase 3 placement fix); every other trigger file was byte-identical. No config field, default, validator, or TOML key moved. `docs/configuration/` documents no import path, and every Python path the docs *do* cite still resolves.
+- **`cli-docs` — clean-pass.** All 10 triggers changed by exactly one import line each (the Phase 4 renderer regroup). Verified against the **live CLI** rather than by reading alone — `pipelex build inputs pipe`, `pipelex build output pipe`, `pipelex-agent inputs pipe` — arguments, flags, format values and defaults all match `docs/tools/cli/`. The behavior-adjacent half of Phase 4 was checked too: no CLI doc cites a Python import path or calls a factory that gained a required `concept_provider`, and the runner codegen emits none. `agent_cli/CLAUDE.md`'s layout map lists only `agent_cli`'s own modules, none of which moved.
+
+Also swept `docs/` and `wip/` for stale references to the H-4 moves (`core.pipes.output.*`, `codegen.resolved_fields`, `core.pipes.inputs.input_renderer`): every remaining hit is intentional historical prose in `hub-layering.md` or this tracker.
+
+**One observation is worth carrying forward, because it is now a pattern rather than an anecdote.** This refactor opened **four contracts across three different ids**, and every one of them was import-path churn. The narrowing proposed in the earlier `config-docs` dogfood entry (scope the trigger to files that define settings) would **not** have prevented today's opening — `configs.py` is squarely inside that narrowed set. The mechanism that would prevent all four is a content-aware digest that ignores changes confined to import statements (and, for `keyword-only-convention`, to comments/docstrings): one manifest-wide change instead of three separate glob surgeries. Recorded in `wip/drift-contracts/dogfood-log.md` as the thing to weigh before any per-contract narrowing — it is evidence for the pilot's keep/narrow/mechanize verdict, not a change to make now.
+
+**Next: [PR #1062](https://github.com/Pipelex/pipelex/pull/1062) is open against `dev`** (base was still exactly `f23fda7a0` at open time, so no merge was needed). The only thing outstanding after it lands is the release-gated cross-repo sweep, already retargeted to the final names. Louis' drift-contract decision is resolved — `hub-layering-convention` is in the manifest, reviewed and acked.
+
+The PR body carries a **reviewer map**, which this diff needs: 528 files, of which ~490 are mechanical import churn. It names the dozen files where the judgment actually lives, and pre-empts the two things that look wrong at a glance — `subject_grants.toml`'s 221/221 re-sort (the registry is machine-written sorted, and was not in sort order before; the parsed mapping is identical modulo renames) and the deliberately un-swept old names in D1, the checkpoint records, and `.drift/acks/`.
+
+### The runtime/interpreter rename — record
+
+Landed as its own commit after H-4, per [`wip/hub/layer-and-hub-renaming.md`](wip/hub/layer-and-hub-renaming.md). Gates: `make agent-check` ✅ · full `make agent-test` ✅ · `make drift-check` ✅.
+
+**Pre-flight was clean.** Grepping the whole workspace — including the private `pipelex-temporal`, the heaviest consumer — turned up **zero** collisions on `runtime_hub` / `RuntimeHub` / `interpreter_hub` / `InterpreterHub`. The only hits were the plan documents themselves.
+
+**A token substitution was the right tool here, and the plan's AST warning did not apply.** Phase 1 needed an `ast` rewrite because it was *splitting* one module into two: each import line had to be classified symbol by symbol, and 29 parenthesized multi-line blocks were the hazard. This rename is 1:1 — no import splits, no classification — so the question is only whether the four tokens ever appear where they must not. They do not: enumerating every whole word in `pipelex/` and `tests/` containing any of them returned exactly the identifiers that should change (`get_method_hub`, `set_service_hub`, the hub-named test functions, and the bare class names). Substring replacement across 332 files, then a re-parse of every file in both trees, was safer than a formatting-preserving AST rewrite and left zero residuals.
+
+**The string-literal landmine was real again, and pre-enumerated.** The H-1 lesson (a missed `mocker.patch` target is invisible to every import-graph tool) held: `tests/helpers/init_cmd_helpers.py` carried `mocker.patch("pipelex.service_hub.get_console", ...)` — the same file, the same shape that broke 36 tests at H-1. Because the sweep was token-based over the whole file rather than import-based, it was caught for free. The other string references were the guard's own configuration, the closure test's entry-point list, and the guard test's patch-target fixtures.
+
+**What the plan under-specified: the enum members in the *test* file.** Step 4 lists the guard's `HubLayeringViolationKind` renames but step 5 lists only the test's constants and patch targets, so a first pass renamed the members in the source and left `HubLayeringViolationKind.METHOD_HUB_IMPORT` in the test — 7 failures. Mechanical to fix, but worth recording: when an enum member is renamed, its *references* live wherever the enum is asserted on, and the plan's per-file checklists split that pair across two steps.
+
+**Vocabulary, not just identifiers.** `LOW_LAYER_PACKAGES` → `RUNTIME_LAYER_PACKAGES` and `is_low_layer` → `is_runtime_layer` were in the plan; the prose was not, and it was the larger edit. "Low layer" / "high layer" was swept out of the guard, both hub docstrings, `class_registry_access.py`, the guard's success panel (it printed `Low layer: …` to the user), `hub-layering.md`, `architecture-overview.md` and the CHANGELOG. The historical checkpoint records in *this* file deliberately keep the old vocabulary, with a reading key in the header note — rewriting them would falsify what was decided when.
+
+**Judgment calls made while sweeping the docs**, none of them mechanical:
+
+- `hub-layering.md` gained an opening section naming the two layers as the language-implementation split, so a reader meets the vocabulary before the rule. The headline property was restated from "importing the inference layer must not load the interpreter" to **"importing the Pipelex runtime loads zero interpreter modules"** — the same measurement, phrased as the outward-facing claim.
+- The `runtime_bridge` clarifier the plan asked for landed in two places, not one: `hub-layering.md`'s intro and the guard's module docstring, since `plugins → runtime_bridge` appears in that file's Known-inversions list.
+- **D1 was preserved verbatim rather than swept.** Mechanically renaming it would have produced a decision record whose rejected alternatives argued about names that were no longer the subject. It is now marked SUPERSEDED, quotes the original in full, and notes that its own "conscious call against the brand-boundary rule" caveat is precisely what Louis acted on.
+- `.drift/acks/keyword-only-convention.toml` was **left alone** — an ack is an on-the-record review decision, and rewriting the rationale of a past review to mention a module that did not exist at review time would be falsifying the record.
+
+**One trigger file changed, so `keyword-only-convention` re-opened** — `keyword_only_guard.py`'s docstring names the hub. Reviewed and acked as import-path/prose-only; no guard behavior, registry schema, or carve-out changed.
+
+**Cross-repo is retargeted, not extended.** The sweep tables in this file now name `pipelex.runtime_hub` / `pipelex.interpreter_hub` directly. External repos still import `pipelex.hub`, so they are rewritten exactly once — the intermediate names never reach them, and never shipped.
+
+#### The plan's premise was wrong: `core/` is two layers
+
+Phase 4 assumed all of `pipelex/core/` could join the low layer once five straddlers were converted. Measurement said otherwise, and the correction is the main finding of this checkpoint.
+
+Beyond the five hub straddlers, **seven `core/` modules import the interpreter *directly*** — no hub involved, so no amount of dependency injection touches them:
+
+| module | pulls | why it is irreducible |
+| --- | --- | --- |
+| `core/registry_models.py` | every pipe + factory | it *is* the registry of pipe kinds |
+| `core/bundles/pipelex_bundle_blueprint.py` | 12 pipe blueprints | a discriminated union over every pipe kind |
+| `core/interpreter/bundle_elaborator.py` | 4 pipe blueprints | it is the interpreter |
+| `core/pipes/pipe_abstract.py` | `libraries.library_crate`, `pipe_signature.exceptions` | the base class every pipe extends |
+
+Measured: `pipelex.core.pipes.pipe_abstract` alone loads **30** interpreter modules while importing no hub at all. So the honest boundary is not `pipelex.core` — it is **"if it names a `Pipe`, it is high."**
+
+Louis' call (option A of three): declare core's data-model packages low, leave the Pipe-touching remainder high. Rejected: threading a provider through `PipeFactory.make_from_blueprint` too — that is **337 call sites (332 in tests, ~85 files)** and buys *no* additional closure property, since `pipe_factory` stays interpreter-bound either way.
+
+#### What landed
+
+**Two read-side contracts, new in `core/`:**
+
+- `ConceptProviderAbstract` (`core/concepts/concept_provider_abstract.py`) — `get_required_concept`, `get_native_concept`, `get_required_concept_from_concept_ref_or_code`, `is_compatible`.
+- ~~`PipeProviderAbstract` (`core/pipes/pipe_provider_abstract.py`) — `get_required_pipe`.~~ **Deleted at [Checkpoint A](#checkpoint-a-record--pr-1062-review-follow-ups) (A5)**: it had zero consumers and its docstring described the opposite of what the code does. `get_required_pipe` is back on `PipeLibraryAbstract`.
+
+`ConceptLibraryAbstract` now **extends** the provider abstract, keeping add/remove/list/setup/teardown high. The split is the point: core depends on resolution, never on a library lifecycle. Both abstracts already named only `core` types, so this was an inverted dependency waiting to be undone.
+
+**Injected, not looked up.** `StuffFactory.{make_stuff_from_stuff_content_or_data, make_from_blueprint, make_from_concept_ref}`, `InputShaper.{shape, resolve_input_kind}`, `WorkingMemoryFactory.make_from_pipeline_inputs`, `InputStuffSpecsFactory.{make_from_blueprint, make_from_string}`, `StuffSpecFactory.make_from_blueprint` all take a required `concept_provider`. Injection happens in the high half: `pipe_factory`, `input_renderer`, `output_renderer` call the hub themselves and hand the result down, as does `pipeline/execution_seams.py`.
+
+**One import was simply wrong**: `stuff_factory.py` imported `ConceptLibraryConceptNotFoundError` from `libraries.concept.concept_library` — a re-export path. The class already lived in `core/concepts/exceptions.py`. A one-line fix deleted a whole interpreter edge.
+
+**Two placement fixes** (the H-3 pattern again):
+
+- `codegen/resolved_fields.py` → `core/concepts/resolved_fields.py`. It names nothing outside `pipelex.core`, yet put `pipelex.codegen` into the closure of every core module reaching structure generation.
+- `core/pipes/inputs/input_renderer.py` + `core/pipes/output/output_renderer.py` → **`core/pipes/rendering/`**. Both render a `PipeAbstract`, so both are high; leaving `input_renderer` beside the low input-spec modules would have forced the low-layer declaration to enumerate *modules* instead of packages. `core/pipes/output/` is gone. Tests mirrored to `tests/unit/pipelex/core/pipes/rendering/`.
+
+#### Measured after
+
+| | baseline | H-1 | H-3 | H-4 | **Checkpoint A** |
+| --- | --- | --- | --- | --- | --- |
+| interpreter modules loaded by `cogt.content_generation.content_generator` | 50 | 0 | 0 | 0 | **0** ✅ |
+| pipelex modules loaded | 357 | 275 | 268 † | 268 † | **269** |
+| SLOC loaded | 29,193 | 21,186 | 20,304 † | 20,304 † | **20,299** |
+
+† The H-3 / H-4 module and SLOC cells were recorded from a stale run — the same tree measures **269 / 20,305**, confirmed by re-reading every closure module at both revisions. The Checkpoint A column is a fresh measurement after the [Phase A follow-ups](#checkpoint-a-record--pr-1062-review-follow-ups); the 6-SLOC drop is those edits (chiefly A3's deletion in `runtime_hub.py`, which is itself in the closure), not a module leaving it. Baseline and H-1 reproduce to the digit.
+
+The inference-layer numbers are unchanged by design — Phase 4 widened *which* modules are guaranteed clean, it did not touch `cogt`'s own weight. The new numbers are the six core entry points, each measured at **0 interpreter modules and no `pipelex.interpreter_hub`**, up from 50 each before this phase:
+
+| entry point | interpreter modules before → after |
+| --- | --- |
+| `core.stuffs.stuff_factory` | 50 → **0** |
+| `core.memory.input_shaper` | 50 → **0** |
+| `core.memory.working_memory_factory` | 50 → **0** |
+| `core.pipes.stuff_spec.stuff_spec_factory` | 50 → **0** |
+| `core.pipes.inputs.input_stuff_specs_factory` | 50 → **0** |
+| `core.concepts.structure_generation.generator` | 2 → **0** |
+
+#### Housekeeping done at H-4
+
+- **Grants**: 4 new (the provider-abstract getters), recorded **before** any check ran; 6 migrated with `resolved_fields`; 15 migrated with the two renderers; **4 deleted as dead** (`ConceptLibraryAbstract.get_{native_concept,required_concept,required_concept_from_concept_ref_or_code}`, `PipeLibraryAbstract.get_required_pipe`) — those defs moved to the provider abstracts, and staleness is symmetric so `make cko` hard-failed until the registry was cleaned.
+- **Test call sites**: 74 across 12 files gained `concept_provider=get_concept_library()`, applied by an AST-driven fixer keyed off pyright's own `Argument missing` report so no unrelated `make_from_blueprint` was touched. ⚠ The first pass mangled 3 files: for a multi-line call the closing-paren line is whitespace-only, so a "does the preceding text end in a comma?" check must look back **across newlines**, not within the line. Reverted and redone.
+- **Docs**: `docs/contribute/hub-layering.md` gained a "Where core splits" section (the two halves, the `if it names a Pipe, it is high` rule, and the injected-provider pattern), two new "Placement, not coupling" entries, a corrected low-layer list under Enforcement, and a rewritten `core/` bullet under Known inversions. `docs/under-the-hood/architecture-overview.md` gained a paragraph on core straddling the line. `docs/under-the-hood/codegen-projections.md` updated for the `resolved_fields` move.
+- **CHANGELOG**: the breaking-change note that had been deferred since H-1 is now written under `[Unreleased]`, covering all four phases — the `pipelex.hub` split, the moved types, and the injected providers.
+
+#### Still open
+
+- **The cross-repo sweep is still untouched and release-gated.** It now has a **third** wave on top of the `pipelex.hub` split and the Phase 3 type moves — see [Cross-repo impact added by Phase 4](#cross-repo-impact-added-by-phase-4).
+- ~~**The `hub-layering-convention` drift contract decision is still Louis'**~~ — **resolved: approved and landed** after the rename. See [Proposed, reverted, then landed](#proposed-reverted-then-landed).
+- A plausible sequel, now much cheaper to argue for than at H-2: a general layering ratchet. The remaining measured inversions are in [Known inversions](#known-inversions-not-fixed-here).
+
+#### Cross-repo impact added by Phase 4
+
+| old | new |
+| --- | --- |
+| `pipelex.codegen.resolved_fields` | `pipelex.core.concepts.resolved_fields` |
+| `pipelex.core.pipes.inputs.input_renderer` | `pipelex.core.pipes.rendering.input_renderer` |
+| `pipelex.core.pipes.output.output_renderer` | `pipelex.core.pipes.rendering.output_renderer` |
+
+Plus the signature changes: any external caller of `StuffFactory.make_stuff_from_stuff_content_or_data`, `WorkingMemoryFactory.make_from_pipeline_inputs`, `InputShaper.shape`, `InputStuffSpecsFactory.make_from_*` or `StuffSpecFactory.make_from_blueprint` must now pass `concept_provider=get_concept_library()`. Do all three waves in one pass per repo.
+
+### Checkpoint A record — PR #1062 review follow-ups
+
+Phase A of [`wip/hub/pr-1062-review-followups.md`](wip/hub/pr-1062-review-followups.md) is applied: A1's doc-honesty fix plus A2–A8. Per **D-R4** the [F1](wip/hub/pr-1062-review-followups.md#f1--the-layer-rule-is-only-enforced-one-hop-deep) *remedy* is deliberately **not** here — it is its own PR after #1062 merges — so this checkpoint makes the shipped documentation true about a defect that still exists, rather than fixing the defect.
+
+#### What landed
+
+- **A1 — the scope claim is corrected.** `docs/contribute/hub-layering.md`'s "Every declared package is compliant" now says what it means: the declaration is compliant *with the direct-import rule*, which the guard does not follow transitively. Known inversions carries the measurement (the four `pipelex.plugins` modules, their interpreter-module counts, and which two are leaves versus aggregators), states plainly that the headline property is unaffected, and describes the decided fix. Re-measured on the working tree before publishing: 57 / 67 / 67 / 58, reproducing the review exactly.
+- **A2 — `pipelex.runtime_hub` joined `RUNTIME_LAYER_PACKAGES`.** The module at the centre of the rule was exempt from it, since no tuple entry was a prefix of it. Verified zero-risk both ways: still 0 violations tree-wide, and an `interpreter_hub` import injected into `runtime_hub.py` in memory is caught at the injected line. `is_runtime_layer`'s docstring now records that matching is exact-or-dotted-prefix, so a bare module is a legal entry beside the packages.
+- **A3 — write-only `RuntimeHub._class_registry` deleted**, with `set_class_registry`, `get_required_class_registry`, the `pipelex.py` call site and the subject grant. Zero callers here or in any sibling repo. It was the twin of the `_observer` state H-1 deleted for exactly this reason, and a live trap besides: it returned the boot-time global while the module-level `get_class_registry()` returns the library-scoped one, so the two diverged under `scoped_current_library(...)`.
+- **A4 — the loop-invariant `get_concept_library()` in `_delighten_template` is hoisted** above the loop.
+- **A5 — `PipeProviderAbstract` deleted; `get_required_pipe` is back on `PipeLibraryAbstract`.** The follow-up plan left this a two-way choice (delete, or keep for symmetry and rewrite the docstring). Deleted, because the abstract had zero consumers, bought no closure property (`core.pipes` is not runtime-layer), and its docstring asserted the opposite of the code — it claimed core takes pipe resolution as a parameter, while the only two sites that follow a pipe reference (`core/pipes/rendering/output_renderer.py:51` and `:84`) call `interpreter_hub.get_required_pipe` directly. Symmetry with `ConceptProviderAbstract` is not a reason to ship an unused abstraction. The absence is now documented where it will be questioned — on `PipeLibraryAbstract` and in `hub-layering.md` — so the next reader does not "restore" it.
+- **A6 — five accuracy fixes.** `runtime_hub.py`'s docstring stopped forbidding `core.concepts` / `core.pipes` wholesale (`core.concepts` is a *declared runtime-layer package* and sits in `runtime_hub`'s own closure); `pipelex.py`'s boot comment stopped claiming the InterpreterHub install "needs a RuntimeHub already in place" (it stores a lazily-resolved callable and needs nothing); the CHANGELOG names the exact templating modules, since `pipelex.tools.templating.__init__` is 0 bytes and the path it printed raised `ImportError` for the external consumers who read that file; and the low/high vocabulary survivors are swept — **four**, not the two the review found (`concept_library_abstract.py` and `pipe_library_abstract.py` carried "stays here, high" too).
+- **A7 — `make generate-error-pages` re-run.** `job-metadata-error.md` had followed neither of Phase 3's moves; it now reports `pipelex.system.exceptions`, and the generator also re-filed its index entry from "execution and runtime" to "platform and tooling", which is the subsystem grouping following the class.
+- **A8 — the class-registry leaf-import rule is restated.** It said "import the leaf only from inside `runtime_hub`'s import closure", which is false for two of the three in-tree importers (verified: `concept.py` is inside, `concept_factory.py` and `structure_generation/generator.py` are not). The real criterion is a module that must stay import-light *with respect to* `runtime_hub`. As written, the rule invited someone to "fix" `concept_factory.py` into re-coupling `core.concepts` to the whole cogt/plugin stack — and neither gate would have noticed, because the closure test measures interpreter modules, not weight.
+- **Batched in:** the published doc's pointer to `wip/pr-1062-review-notes.md` is folded into an in-place sentence. `wip/` is outside `docs_dir`, so it was unreachable for a reader on docs.pipelex.com and would dangle once the file is archived.
+
+#### The measurement
+
+Re-taken here rather than copied — see the [H-4 table](#measured-after-1) for the full row and the stale-recording footnote. The closure is **269 modules / 20,299 SLOC / 0 interpreter modules**. The 6-SLOC drop against the pre-Phase-A tree is A3's deletion in `runtime_hub.py` (itself in the closure), confirmed by re-reading every closure module at both revisions; no module left the closure.
+
+#### Not in this checkpoint
+
+- **The F1 remedy** — (d) split the built-ins by layer + (c) teach the guard the transitive check. Its own PR after #1062 merges, per D-R4. Until it lands, Known inversions is the record that keeps the breach visible.
+- **[Phase C](wip/hub/pr-1062-review-followups.md#phase-c--release-wave-additions)** — folded into the release-gated cross-repo sweep per D-R1. It adds a governed `docs/specs/` + `conformance/` surface and five consumer repos the [sweep tables](#cross-repo-sweep) below are missing, including `pipelex-transport`, whose `bridge.py` calls a changed signature in production code.
+
+[Phase B](#checkpoint-b-record--test-hardening) followed immediately and is now applied too.
+
+### Checkpoint B record — test hardening
+
+Gates: `make agent-check` ✅ (pyright 0 errors, mypy 2,358 files, keyword-only PASSED, hub-layering PASSED) · full `make agent-test` ✅ · `make drift-check` ✅ (one contract re-opened, reviewed and acked — see below).
+
+Phase B of [`wip/hub/pr-1062-review-followups.md`](wip/hub/pr-1062-review-followups.md) is applied in full: B1–B7. Three new test modules, three hardened ones, one guard fix.
+
+**Every item was verified by mutation.** Watching a new test go green proves nothing about what it pins, and two of these items exist precisely because an existing test *appeared* to pin something it did not. So for each one the pinned behavior was removed, the new test confirmed to fail, and the mutation reverted. What that turned up is worth keeping:
+
+- **B1's mutation is the finding, restated as a fact.** Deleting `class_registry_scoping.reset()` from `Pipelex.teardown` fails the new test and *only* it — the three other tests in the module, including the pre-existing one that calls `reset()` directly under a `# what Pipelex.teardown does` comment, stay green. That comment was the whole safety net. The simulation test is kept, because it does pin `reset()`'s own semantics; its comment now says so instead of overclaiming.
+- **B2 needed a stronger assertion than the plan specified.** The plan said to assert `returncode == 1` on a known-dirty entry point. That would **not** have worked: the closure script's *second* check (`pipelex.interpreter_hub in sys.modules`) exits 1 for `pipelex.interpreter_hub` whatever the offender predicate does, so the control would have passed over a completely broken detector. The test asserts the offender *message* too. Confirmed by mutation: typo-ing `INTERPRETER_PACKAGES` and emptying `INTERPRETER_CORE` fails the control while all eight real entry points pass vacuously — the exact failure mode the item was written against.
+- **B5's mutation reproduces the regression the finding describes.** Making `resolve_input_kind` accept `concept_provider` and then call `get_concept_library()` anyway fails the new test alone, with the other 69 `input_shaper` tests green. Before it, that regression failed nothing anywhere.
+- **B3 and B4** fail 4-of-6 and 2-of-5 respectively when their gates are removed (`sys.exit(1)` deleted from both command paths; the `__pycache__` skip dropped from `iter_source_files`).
+- **B6 is a fix, not just a test.** `_is_type_checking_test` matched `ast.Attribute(attr=...)` with an unconstrained receiver, so `settings.TYPE_CHECKING:` — an ordinary runtime condition — claimed the layer-rule exemption. Tightened to require the receiver to be `typing`. Verified safe before tightening: nothing in `pipelex/` or `tests/` uses the attributed form at all, so there was no alias (`import typing as t`) to break.
+
+**B6 re-opened the `hub-layering-convention` drift contract**, which the plan had said Phase B would not do — `hub_layering_guard.py` is one of its triggers. Reviewed and acked. Both prescribed mechanical checks were re-run (33 + 32 public module-level hub symbols all present in the partition tables; all 12 declared runtime-layer entries named under Enforcement), and `docs/contribute/hub-layering.md` gained the receiver constraint on its `TYPE_CHECKING` bullet.
+
+**One observation from that ack is worth carrying forward.** The read-through caught staleness the contract's triggers structurally cannot see: B1/B2/B7 changed the two test modules the doc has sections on, and neither test file is a trigger — deliberately, per the contract's initial scoping. So the contract fired on the guard, and the review found the spillover. That is not an argument for widening the triggers (the scoping was Louis' call, and the spillover was caught anyway); it is evidence that a review target's value is bounded by what the reviewer reads, not by what opened the contract. Recorded in `wip/drift-contracts/dogfood-log.md` as this contract's second consecutive `real-catch`.
+
+**Two things caught in passing, both fixed here:**
+
+- **The plan's B2 instruction would not have worked as written** — see the bullet above. Recorded because it generalizes: a negative control that asserts only an exit code is only as strong as the *first* thing that can produce it.
+- **Two dead anchor links in `hub-layering.md`**, pre-existing since the page was written and invisible to every gate the branch runs — `make docs-check` reports them as `INFO`, not a failure. The heading is `### The rule — \`make check-hub-layering\``, and Python-Markdown strips the em dash rather than turning it into a second hyphen, so `#the-rule--make-check-hub-layering` never resolved. Confirmed against the built site's real `id`, and confirmed pre-existing by re-running the check with Phase B stashed.
+
+**No CHANGELOG entry.** Phase B adds tests and tightens a `pipelex-dev` guard, and `pipelex/cli/dev_cli` is excluded from both wheel and sdist — nothing here reaches a release consumer.
+
+The measurement is untouched by Phase B — no production module changed except the guard, which is dev-CLI-only and outside every closure. The [Checkpoint A column](#measured-after-1) stands.
+
+## Exit criteria — measured, not asserted
+
+The headline property is that the inference layer must stop importing the interpreter. Measure it directly, from the repo root on a synced venv:
+
+```bash
+.venv/bin/python - <<'PY'
+import sys
+from pathlib import Path
+
+import pipelex.cogt.content_generation.content_generator # noqa: F401
+
+INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
+loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
+interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
+sloc = 0
+for mod in loaded.values():
+ file = getattr(mod, "__file__", None)
+ if file:
+ sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
+print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
+print("offenders:", interpreter)
+PY
+```
+
+If Phase 1 lands and `interpreter modules` is not 0, the snippet prints the offenders: something imports the interpreter outside the hub, and the shortest import path to it is what to fix. Swap the imported module to measure any other entry point (`pipelex.pipelex`, `pipelex.runtime_hub`, …).
+
+The module/SLOC targets come from importing exactly the types a low-only hub would annotate — 236 modules / 17,683 SLOC with the interpreter subpackages at zero — plus headroom for cogt's own modules.
+
+## Findings in passing
+
+> **Both are resolved as of H-1** — see [Findings in passing — both resolved, one bigger than recorded](#findings-in-passing--both-resolved-one-bigger-than-recorded). The `_observer` one turned out to be more than dead code: a public doc page documented the inert setter as the supported API.
+
+Both surfaced while inventorying the boot sequence. Neither is caused by this refactor; both are in its blast radius, and the repo's flag-and-fix rule applies.
+
+- **Duplicate `set_library_manager` in `Pipelex.setup`.** Lines 364–365 and 474–475 are the identical pair `self.library_manager = library_manager or LibraryManager()` + `self.pipelex_hub.set_library_manager(...)`. Nothing between them touches `library_manager` (verified), so when the caller passes no manager the first `LibraryManager()` is constructed, registered, and then silently discarded and replaced by a second instance. Delete the earlier pair — it is dead, and removing it is what makes the low/high boot split clean with no reordering (step 1.5).
+- **`_observer` is write-only state.** `PipelexHub.set_observer` is called at `pipelex.py:503`, but there is no `get_observer` on the container and no module-level accessor — the live observer reaches its consumer directly via `PipeRouter(observer=multi_observer)` at line 531. The design doc lists "observer" among the `interpreter_hub` contents; it should be **deleted rather than moved**. Confirm no external consumer sets it before removing (see [Cross-repo sweep](#cross-repo-sweep)).
+
+## Risks and containment
+
+- **Big mechanical diff.** Contained by: the rewrite is scriptable from the partition table; `pipelex.hub` ceasing to exist means a missed site is an import error, not a silent wrong-layer resolution; and full `make agent-test` is the zero-behavior-change bar. The 29 multi-line import blocks are the one place a careless script does real damage — rewrite via `ast`, not regex.
+- **Two singletons, two lifecycles, two teardowns.** Contained by the tiny construction surface. Watch `Pipelex.teardown` / `teardown_if_needed` and the fixtures that reset hub state — a half-reset hub between tests is the realistic failure mode, and it surfaces as cross-test pollution rather than a clean failure. Step 1.7 exists for this; make the "both hubs reset" assertion explicit rather than implied.
+- **D5's resolver slot is installed at boot, not imported.** If a consumer builds a `RuntimeHub` without ever populating a `InterpreterHub` (the doctor path, some tests), `get_class_registry` must degrade to the unscoped `KajsonManager` registry rather than raise. Default the slot to a function returning `None`, never to an unset attribute.
+
+## Cross-repo sweep
+
+Release-gated follow-up — `pipelex.hub` is imported outside this repo and every one of these breaks the moment the module disappears.
+
+| repo | files importing `pipelex.hub` |
+| --- | --- |
+| `pipelex-temporal/` (private) | 35 |
+| `pipelex-mistralai-workflows/` | 11 |
+| `pipelex-api/` | 9 |
+| `pipelex-cookbook/` | 2 |
+| `cocode/` | 2 |
+
+Clean (no action): `pipelex-worker/`, `pipelex-starter-python/`, `pipelex-relay/`, `n8n-nodes-pipelex/`, `sandbox/`.
+
+Symbols crossing the repo boundary today, which is the surface whose new home is a published contract change:
+
+`clear_current_library`, `get_bundle_validator_registry`, `get_class_registry`, `get_console`, `get_content_generator`, `get_current_library`, `get_current_library_id_or_none`, `get_library_manager`, `get_model_deck`, `get_orchestrator_registry`, `get_pipe_func_executor_registry`, `get_pipe_library`, `get_pipe_router`, `get_pipelex_hub`, `get_report_delegate`, `get_required_concept`, `get_required_pipe`, `get_secret`, `get_storage_provider`, `get_storage_provider_registry`, `is_dry_run_forced`, `scoped_current_library`, `set_current_library`
+
+Two notes on that list: `get_pipelex_hub` splits into two accessors, so every external site must pick a half; and `set_pipe_router` / `teardown_current_pipe_router` / `scoped_pipe_router` are documented as depended upon by our Mistral Workflows plugin, so their move is a contract change to announce, not just to make.
+
+**Rewrite straight to the final names — there is no intermediate step.** `service_hub` / `method_hub` never shipped, so external repos go directly from `pipelex.hub` to:
+
+| old | new |
+| --- | --- |
+| `from pipelex.hub import <runtime symbol>` | `from pipelex.runtime_hub import …` — everything in the [`runtime_hub` partition table](#-pipelexruntime_hubpy-runtime-layer) |
+| `from pipelex.hub import <interpreter symbol>` | `from pipelex.interpreter_hub import …` — everything in the [`interpreter_hub` partition table](#-pipelexinterpreter_hubpy-interpreter-layer) |
+| `get_pipelex_hub` | `get_runtime_hub` **or** `get_interpreter_hub` — pick the container the call site actually meant |
+| `PipelexHub` | `RuntimeHub` **or** `InterpreterHub` |
+
+**Phase 3 added a second wave of breakage to the same sweep** — the moved types, not the hub accessors. The per-repo counts and the complete old→new import table are in [Cross-repo impact added by Phase 3](#cross-repo-impact-added-by-phase-3). Do both waves in one pass per repo.
+
+## Known inversions — not fixed here
+
+Named so the docs stay honest, not scheduled.
+
+- `plugins/pipe_func/pipe_func_plugin.py` and `plugins/pipe_func_executor_registry.py` import from `pipe_operators/`; `plugins/direct/direct_plugin.py` imports from `pipeline/`. None import the hub, so the guard will not flag them — but they mean "plugins is a low layer" is not yet unconditionally true. This is D3's underlying inversion.
+- A general layering ratchet ("no low module may import any high module", with an allowlist) is out of scope. The measured inversion set is real but larger than this change should carry. **Re-measured at H-3**, after Phase 3 removed the two biggest clusters: `cogt → core` (21), `system → cogt` (7), `plugins → runtime_bridge` (6), `tools → cogt` (3 — the pdf renderer reaching for `cogt.extract` / `cogt.image` types, the same misfiling pattern Phase 3 fixed elsewhere), and one genuine wart — `cogt/model_backends/model_lists.py` importing `pipelex.cli.exceptions.PipelexCLIError`. `cogt → pipeline` (18) is gone. The general rule is now a more plausible sequel than it was at H-2.
+- Eager optional-SDK imports: `pipelex/tracing/event_log_factory.py` imports `dynamodb_event_log` at module level, which runs a module-level `try: import boto3`, so `boto3`/`botocore`/`jmespath`/`dateutil`/`six` load in every process that touches the tracing factory. A three-line fix (import `DynamoDBEventLog` inside the factory branch, the pattern already used for `pypdfium2` in `cogt/content_generation/render_generate.py`), entirely independent of this plan. Most other heavy roots (`posthog`, `pypdfium2`, `pillow`, `polyfactory`, `datamodel-code-generator`) are **base** dependencies, not extras — not the same kind of finding.
diff --git a/docs/advanced/index.md b/docs/advanced/index.md
index b5a12f221..8e62bc392 100644
--- a/docs/advanced/index.md
+++ b/docs/advanced/index.md
@@ -8,11 +8,9 @@ description: "Extend Pipelex through dependency injection — swap in custom sec
Pipelex uses dependency injection to manage service dependencies and make components more modular and testable. The system allows you to customize and extend Pipelex's functionality by injecting your own implementations of various services.
-## Injection Methods
+## Injecting your implementation
-There are two main ways to inject custom implementations:
-
-### 1. During Initialization
+Inject at boot, by passing your implementation to `Pipelex.make()`:
```python
from pipelex.pipelex import Pipelex
@@ -25,16 +23,31 @@ pipelex = Pipelex.make(
)
```
-### 2. Through the Hub
+This is the supported path. `Pipelex.make()` builds the hubs, applies your overrides in the right order, and wires the results into the components that consume them.
+
+## Reading a dependency: the two hubs
+
+Injection happens at boot; *lookup* happens through a hub. Pipelex has two, split by lifecycle:
+
+- `pipelex.runtime_hub` — process-scoped infrastructure: config, console, secrets, storage, telemetry, the model deck, inference workers, the content generator, the plugin registries.
+- `pipelex.interpreter_hub` — library-scoped method machinery: the library manager and the concept/domain/pipe libraries, the current-library binding, the pipe router, the pipeline manager.
+
+Read a dependency through the module-level accessor for the half that owns it:
```python
-from pipelex.hub import PipelexHub
+from pipelex.interpreter_hub import get_required_pipe
+from pipelex.runtime_hub import get_model_deck, get_secrets_provider
-hub = PipelexHub()
-hub.set_report_delegate(MyReportingDelegate())
-# ... and so on for other components
+secrets = get_secrets_provider()
+deck = get_model_deck()
+pipe = get_required_pipe(pipe_code="my_domain.my_pipe")
```
+!!! warning "Don't construct a hub yourself"
+ Building a `RuntimeHub()` or `InterpreterHub()` by hand and calling setters on it has no effect on a running Pipelex — the instance you build is not the one the process resolves. Inject through `Pipelex.make()` instead.
+
+Contributors adding a new dependency should read [Hub Layering](../contribute/hub-layering.md), which specifies which half a symbol belongs on and why the boundary is enforced.
+
## Protocol Compliance
All custom implementations MUST:
diff --git a/docs/advanced/observer-provider-injection.md b/docs/advanced/observer-provider-injection.md
index 0d9999153..3427d23a7 100644
--- a/docs/advanced/observer-provider-injection.md
+++ b/docs/advanced/observer-provider-injection.md
@@ -103,21 +103,25 @@ class MyCustomObserver(ObserverProtocol):
print(f"Failed pipe: {pipe_job.pipe.code}")
```
-### Step 2: Register Your Observer with Dependency Injection
+### Step 2: Register Your Observer at Boot
-The observer is injected through the PipelexHub dependency injection system:
+Observers are injected at boot, through `Pipelex.make()`. Pass a dict keyed by a name of your choosing — Pipelex wraps the whole dict in a `MultiObserver` and hands it to the pipe router, so every observer you register is notified:
```python
-from pipelex.hub import get_pipelex_hub
+from pipelex.pipelex import Pipelex
# Create your observer instance
my_observer = MyCustomObserver(config_param="production")
-# Inject it into the hub
-hub = get_pipelex_hub()
-hub.set_observer(my_observer)
+# Inject it at boot
+Pipelex.make(observers={"my_observer": my_observer})
```
+!!! warning "Observers must be registered at boot"
+ Passing `observers` to `Pipelex.make()` is the only way to register one. The router receives its observer when it is constructed during setup, so there is no supported way to swap an observer on a already-running instance.
+
+Registering your own `observers` dict **replaces** the defaults (a no-op observer and the telemetry observer). Include the built-ins explicitly if you want to keep them alongside your own.
+
### Step 3: Ensure Proper Integration
The observer is automatically called by the PipeRouterProtocol during pipe execution:
@@ -140,7 +144,7 @@ local_observer = LocalObserver()
local_observer = LocalObserver(storage_dir="/path/to/custom/dir")
# Inject the observer
-get_pipelex_hub().set_observer(local_observer)
+Pipelex.make(observers={"local": local_observer})
```
The LocalObserver creates separate JSONL files for each event type:
@@ -209,20 +213,13 @@ class MetricsObserver(ObserverProtocol):
For automatic observer setup, integrate with your Pipelex initialization:
```python
-from pipelex.hub import get_pipelex_hub
from pipelex.pipelex import Pipelex
from my_project.observers import MyCustomObserver
def setup_pipelex():
- # Initialize Pipelex
- pipelex_instance = Pipelex.make()
-
- # Setup custom observer
- observer = MyCustomObserver()
- get_pipelex_hub().set_observer(observer)
-
- return pipelex_instance
+ # Initialize Pipelex with the observer wired in from the start
+ return Pipelex.make(observers={"my_observer": MyCustomObserver()})
```
The observer system provides powerful insights into your pipeline execution patterns and is essential for monitoring, debugging, and optimizing your Pipelex methods.
\ No newline at end of file
diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.md
new file mode 100644
index 000000000..b6d8d0ab8
--- /dev/null
+++ b/docs/contribute/hub-layering.md
@@ -0,0 +1,241 @@
+---
+title: "Hub Layering"
+description: "The runtime_hub / interpreter_hub boundary — what lives in each layer, the one-arrow rule, and how it is enforced."
+---
+
+# Hub layering convention
+
+Pipelex resolves its cross-cutting dependencies through a *hub*: a singleton container plus a set of module-level accessor functions, so a component can reach the config, a worker, or the pipe library without importing the module that owns it. There are **two** hubs, one per layer, and which one a symbol lives on is an architectural boundary, not a filing preference. This document is the canonical specification of that boundary.
+
+The two layers are the textbook language-implementation split:
+
+- **The runtime layer** is the machinery present at execution time whatever is loaded — config, console, secrets, storage, telemetry, the model deck and inference workers, the content generator, reporting, and the value data model. Its hub is `runtime_hub`.
+- **The interpreter layer** reads a method and executes it — the libraries, the pipes, the router, the pipeline manager. Its hub is `interpreter_hub`.
+
+Do not read `runtime_hub` as related to the `pipelex.runtime_bridge` package: they share a word, but the hub is the runtime layer's service container while `runtime_bridge` is a transport.
+
+## The one rule
+
+> `interpreter_hub` may import `runtime_hub`. **`runtime_hub` must never import `interpreter_hub`.**
+
+That single arrow is the whole architecture. Everything below is a consequence of it.
+
+Only the *forbidden* direction is load-bearing. The permitted one is currently unused: the one runtime-layer thing `interpreter_hub` needs is the class-registry scoping slot, which lives below *both* hubs (see [The class-registry exception](#the-class-registry-exception)). So today, importing either hub loads the other in neither direction — which is stronger than the rule requires, not a violation of it.
+
+There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as an alias for either layer, so a stale import fails loudly at import time instead of silently resolving to the wrong layer.
+
+## The two layers
+
+### `pipelex/runtime_hub.py` — process-scoped infrastructure
+
+`RuntimeHub` holds what is configured once at boot and never varies per method:
+
+| group | symbols |
+| --- | --- |
+| container | `RuntimeHub`, `get_runtime_hub`, `set_runtime_hub` |
+| config | `get_required_config`, `get_optional_config` |
+| console | `get_console` |
+| secrets | `get_secrets_provider`, `get_secret` |
+| system registries | `get_class_registry`, `get_func_registry` |
+| storage | `get_storage_provider` |
+| telemetry | `get_telemetry_manager`, `get_otel_tracer` |
+| models | `get_models_manager`, `get_model_deck`, `get_sdk_client_manager` |
+| 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` |
+| 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` |
+
+### `pipelex/interpreter_hub.py` — library-scoped method machinery
+
+`InterpreterHub` holds what belongs to the *loaded method*:
+
+| group | symbols |
+| --- | --- |
+| container | `InterpreterHub`, `get_interpreter_hub`, `set_interpreter_hub` |
+| library manager | `get_library_manager`, `get_library` |
+| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_required_pipe`, `get_optional_pipe`, `get_pipe_source` |
+| current-library contextvar | `set_current_library`, `get_current_library`, `get_current_library_id_or_none`, `clear_current_library`, `scoped_current_library` |
+| library dirs | `resolve_library_dirs`, `get_default_library_dirs` |
+| pipe router | `get_pipe_router`, `set_pipe_router`, `teardown_current_pipe_router`, `scoped_pipe_router` |
+| run | `get_pipe_run`, `get_pipeline_manager`, `get_pipeline` |
+| pipe func | `get_pipe_func_executor`, `scoped_pipe_func_executor`, `get_pipe_func_executor_registry` |
+
+Setters follow their getters onto the matching container.
+
+### Which hub does a new symbol belong to?
+
+Ask **what its lifecycle is**, not what package it happens to be typed by:
+
+- Configured once at boot from config + plugin registration, identical for every method the process runs → `runtime_hub`.
+- Tied to a loaded method's libraries, or varying with the current library → `interpreter_hub`.
+
+Placement is decided by *kind*, not by who currently imports it. Several accessors have no in-tree importer (`get_bundle_validator_registry`, `get_orchestrator_registry`, `get_default_library_dirs`, …) — they are live plugin contract and are reached through the container. Do not relocate or delete one because a grep looks empty.
+
+`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.
+
+## Why the boundary exists
+
+`runtime_hub` must not name anything from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `core.bundles`, `core.interpreter`, or the Pipe-touching modules of `core.pipes` at module level. 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()`.
+
+The property that matters is measurable: **importing the Pipelex runtime loads zero interpreter modules.** That is both the assertion the closure test pins and the outward-facing claim — the inference engine does not know the MTHDS language exists, so you can embed it without loading a line of the interpreter. Verify it from the repo root on a synced venv:
+
+```bash
+.venv/bin/python - <<'PY'
+import sys
+from pathlib import Path
+
+import pipelex.cogt.content_generation.content_generator # noqa: F401
+
+INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
+loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
+interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
+sloc = 0
+for mod in loaded.values():
+ file = getattr(mod, "__file__", None)
+ if file:
+ sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
+print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
+print("offenders:", interpreter)
+PY
+```
+
+`interpreter modules` must print **0**. When it does not, the `offenders` list names the modules that leaked, and the shortest import path to one of them is what to fix. Swap the imported module to measure any other entry point.
+
+## Where core splits
+
+`pipelex/core/` is not one layer, and trying to declare it one was the mistake this section records. It holds two different kinds of thing:
+
+- **The data model — runtime.** `core.concepts`, `core.domains`, `core.stuffs`, `core.memory`, the input/output *specs* under `core.pipes.inputs` and `core.pipes.stuff_spec`, and `core.pipes.pipe_output`. These describe what a method's values *are*. Nothing in them needs a loaded method, and each measures **zero** interpreter modules. `pipe_output` reads as Pipe machinery but is not: it names no `Pipe` — it holds the working memory, graph spec and usage a run *produced* — and it sits inside `runtime_hub`'s own closure (the chain under [The class-registry exception](#the-class-registry-exception) passes straight through it). It is a runtime-layer module the [guard's declaration](#the-rule-make-check-hub-layering) does not cover, because that declaration is package-granular and `core.pipes` as a whole is not runtime; the closure test covers it instead, since an `interpreter_hub` import there would fail the `pipelex.runtime_hub` entry point.
+- **The Pipe machinery — interpreter.** `core.pipes.pipe_abstract`, `pipe_blueprint`, `pipe_factory`, `core.pipes.rendering`, `core.bundles`, `core.interpreter`, and `core.registry_models`. Every one of them names a `Pipe`, and a pipe is the interpreter's own object — they import `pipe_operators` / `pipe_controllers` / `libraries` **directly**, not through a hub. `core.bundles.pipelex_bundle_blueprint` is a discriminated union over every pipe blueprint; `core.registry_models` is a registry of every pipe kind. No amount of dependency injection makes those runtime.
+
+So the runtime-layer declaration lists core's data-model packages by name. `pipelex.core` itself is deliberately *not* a declared package: writing it would claim a property the measurement contradicts.
+
+The dividing line is worth stating as a rule of thumb: **if it names a `Pipe`, it belongs to the interpreter layer.**
+
+### Injected providers, not ambient lookups
+
+The data-model half used to reach for `get_concept_library()` / `get_native_concept()` / `get_required_concept()` — ambient lookups into a loaded method, which is exactly what made `core/` inseparable from the interpreter. It now takes what it needs as a parameter, through one read-side contract: `ConceptProviderAbstract` (`pipelex/core/concepts/concept_provider_abstract.py`) — resolve a ref, a code, or a native code into a `Concept`, and answer compatibility questions.
+
+It is **read-side only**. Managing a library — adding, removing, listing, setup/teardown — stays in the interpreter layer: `ConceptLibraryAbstract` *extends* it, keeping its management half in `libraries/`. Splitting read from write is what lets a core module state its dependency honestly ("I need something that can resolve concepts") without inheriting a library lifecycle it has no business touching.
+
+**There is deliberately no pipe counterpart.** Nothing in core's runtime half resolves a pipe. The two places that follow a pipe reference found *inside* a pipe graph — a condition's mapped pipes, a sequence's last step — live in `core/pipes/rendering/`, which is interpreter-layer and calls `interpreter_hub.get_required_pipe` directly; a provider parameter there would buy no closure property. `get_required_pipe` therefore stays on `PipeLibraryAbstract`. Split a read half out when a runtime-layer caller actually needs one, not for symmetry with concepts.
+
+The injection point is the interpreter layer. `pipe_factory`, `input_renderer` and `output_renderer` — already interpreter-bound, so nothing is lost — resolve the concept library themselves and pass it down; `pipeline/execution_seams.py` does the same for `WorkingMemoryFactory`. That is the one-way arrow the whole design rests on, applied inside `core/`: **the half that knows about a loaded method resolves the collaborator and hands it downward.**
+
+When you add a core data-model function that needs a concept, add a `concept_provider` parameter. Do not add a hub import — the guard will reject it, and the closure test will tell you which entry point you broke.
+
+## Placement, not coupling
+
+Splitting the hub removes the *lookups* that crossed the boundary. It does not move a type that was simply filed in the wrong package — and a misfiled type drags its whole package into every closure that names it. Two were resolved this way; both are worth knowing as the pattern to apply to the next one.
+
+**`JobMetadata` moved to `pipelex/system/`.** It is an argument to essentially every `cogt` call, yet it lived in `pipelex/pipeline/` — which made `cogt → pipeline` the fattest remaining edge and pulled `graph.trace_context` into every closure that touched inference. `JobMetadata`, `JobCategory` and `UnitJobId` now live in `pipelex/system/job_metadata.py`, and `JobMetadataError` moved from `pipeline/exceptions.py` to `pipelex/system/exceptions.py`. `cogt → pipeline` is now **zero statements**.
+
+`TraceContext` moved with it, to `pipelex/system/trace_context.py`: it is the transport `JobMetadata` carries, so leaving it in `graph/` would only have renamed the inversion to `system → graph`. Its one dependency on the graph package — `DataInclusionConfig`, nested under `[...graph_config.data_inclusion]` in the TOML — moved down to `pipelex/system/data_inclusion_config.py`, which `graph_config.py` now imports. The TOML shape is unchanged; only the class's home moved, which is what keeps `trace_context` from re-importing `mermaid_config` and `reactflow_config` through `GraphConfig`.
+
+**The templating primitives moved down into `tools/`.** `TemplateCategory`, `TemplatingStyle`, `TagStyle` and `TextFormat` sat under `cogt/templating/` while eight `tools/jinja2/` and `tools/mermaid/` modules imported them — so `tools`, the intended bottom layer, depended on `cogt`. None of the three modules holding them named anything from `cogt`, so this was pure misfiling:
+
+- `TextFormat` and `TemplatingStyle` / `TagStyle` → `pipelex/tools/templating/`, which imports nothing from `pipelex` beyond its own sibling. It is a leaf.
+- `TemplateCategory` → `pipelex/tools/jinja2/`, because its entire payload is a map of jinja2 filters. Filing it in `tools/templating/` would have made that package import `tools/jinja2` while `tools/jinja2` imports it back — a cycle inside one layer. As placed, the edges run one way: `tools/mermaid → tools/jinja2 → tools/templating`.
+
+What stays in `cogt/templating/` — `TemplateBlueprint`, the sigil preprocessor, the rendering entrypoint — belongs there: a blueprint is language-layer, and the rest imports `tools/jinja2` downward.
+
+**`resolved_fields` moved down into `core/concepts/`.** The neutral resolved-field layer — one structure field becoming a `ResolvedType` tree — lived under `pipelex/codegen/` while `core/concepts/structure_generation/generator.py` imported it, which put `pipelex.codegen` into the closure of every core module that reached structure generation. It names nothing outside `pipelex.core`, so this was misfiling again: it now lives at `pipelex/core/concepts/resolved_fields.py`, and the codegen emitters import it upward.
+
+**The two renderers regrouped into `core/pipes/rendering/`.** `input_renderer` sat in `core/pipes/inputs/` beside genuinely runtime-layer modules while `output_renderer` sat alone in `core/pipes/output/`. Both render a `PipeAbstract` for a human or an agent, so both belong to the interpreter layer — and leaving `input_renderer` where it was would have forced the runtime-layer declaration to be a list of *modules* rather than packages. Regrouping them made the boundary fall on package lines, which is the difference between a rule you can state and a rule you have to enumerate.
+
+The lesson generalizes: when a runtime-layer package imports an interpreter-layer one, check whether the *type* is misplaced before designing an indirection. None of these needed a resolver slot or a protocol — only a `git mv` and an import rewrite. And when a package straddles the boundary, moving the odd module out is usually cheaper than teaching the guard about exceptions.
+
+## The class-registry exception
+
+`get_class_registry` is the one runtime-layer accessor that is *not* implemented in `runtime_hub`. Its implementation lives in `pipelex/system/registries/class_registry_access.py`, and `pipelex.runtime_hub.get_class_registry` delegates to it.
+
+The reason is a genuine cycle. `core.concepts.concept` needs the active class registry, and it sits **inside** `runtime_hub`'s own import closure:
+
+```
+runtime_hub → cogt.llm.llm_worker_abstract → system.telemetry.otel_factory
+ → core.pipes.pipe_output → core.stuffs.stuff → core.concepts.concept
+```
+
+so `concept.py` cannot import `runtime_hub` at module level. Hosting the accessor in a module that imports nothing from `pipelex` is what lets `core/concepts/` use a plain top-level import — replacing three identical `importlib.import_module("pipelex.hub")` shims that were invisible to every import lint and to pyright's module graph.
+
+**Use `pipelex.runtime_hub.get_class_registry` everywhere.** The exception is a module that must stay import-light *with respect to* `runtime_hub` — that one imports the leaf directly. `core/concepts/` is the case, for two different reasons: `concept.py` sits **inside** `runtime_hub`'s own closure, so the public accessor is literally unreachable there; `concept_factory.py` and `structure_generation/generator.py` sit outside it, and routing them through `runtime_hub` would re-couple `core.concepts` — a declared runtime-layer package — to the whole cogt/plugin stack for one function. Do not "fix" those two to the public accessor: nothing checks this mechanically, and the closure test would not catch it either, since it measures interpreter modules rather than weight.
+
+### Library scoping crosses downward, at install time
+
+A run may pin a per-library `ClassRegistry` rather than the process-global Kajson one. Knowing *which* library is current is method-layer knowledge, so the runtime layer holds only a slot: `class_registry_scoping`, defaulting to a resolver that returns `None`. `set_interpreter_hub` installs the real resolver, which means scoping is live exactly when a `InterpreterHub` exists — an invariant a caller cannot forget to wire. `Pipelex.teardown` calls `class_registry_scoping.reset()` so a torn-down library manager is never reachable through a still-pinned library id.
+
+This is the same shape as `HubSlot.ISOLATED_EXECUTION_PROBE`: a defaulted callable a higher layer replaces at boot, never an unset attribute. A process that only ever builds a `RuntimeHub` (the doctor path, most unit tests) therefore degrades to the process-global registry instead of raising.
+
+## Enforcement
+
+The boundary is enforced mechanically. Two things are checked, because the rule and the property it buys can fail independently.
+
+### The rule — `make check-hub-layering`
+
+```bash
+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 two rules over `pipelex/` and `tests/`:
+
+1. **The layer rule.** A module in the declared runtime layer — `pipelex.cogt`, `pipelex.plugins`, `pipelex.reporting`, `pipelex.system`, `pipelex.tools`, the `pipelex.runtime_hub` module itself, plus core's data-model packages `pipelex.core.concepts`, `pipelex.core.domains`, `pipelex.core.memory`, `pipelex.core.pipes.inputs`, `pipelex.core.pipes.stuff_spec` and `pipelex.core.stuffs` — 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.
+
+ Read that compliance claim as exactly what it is. **The rule is about a *direct* import, and the guard does not follow the import graph.** A declared runtime-layer module can still reach `interpreter_hub` through an undeclared intermediary — `runtime_bridge`, `pipeline`, `pipe_run`, `config`, … — with both gates green. Four modules under `pipelex.plugins` do exactly that today; see [Known inversions](#known-inversions) for the measurement and the planned fix. Why `core/` is listed package by package rather than wholesale is [below](#where-core-splits).
+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.
+
+Both rules match **imports and bare string literals**, and the string half is the load-bearing one. A missed *import* of a deleted module is an immediate `ImportError`; a missed *string* is not, and it is invisible to every import-graph tool and to pyright's module graph. Both forms that actually occurred here were strings: three `importlib.import_module("pipelex.hub")` shims hiding a cycle from every lint, and one `mocker.patch("pipelex.hub.get_console", ...)` that broke a whole CLI test suite with an `AttributeError` raised nowhere near a hub. Matching is exact-or-boundary against the module path, so `pipelex.runtime_hub` never matches `pipelex.hub` and prose that merely *mentions* a module is not a reference.
+
+The guard resolves relative imports (`from ...interpreter_hub import …`) against the importing module's own package, so the forbidden arrow cannot be spelled around. A path assembled at runtime from f-strings or concatenation is beyond any AST scan; nothing in the tree does that.
+
+Two deliberate carve-outs:
+
+- **`if TYPE_CHECKING:` blocks are exempt from the layer rule** — the rule is about what *loads*, and a type-only import loads nothing. Only `TYPE_CHECKING` and `typing.TYPE_CHECKING` open such a block: an attribute of any other receiver (`settings.TYPE_CHECKING:`) is an ordinary runtime condition and earns no exemption. The `else` branch is not exempt either, nor is `if not TYPE_CHECKING:`, and the dead-module rule applies inside `TYPE_CHECKING` too (a deleted module exists in no phase).
+- An inline `# hub-layering: ignore` comment anywhere on the offending statement suppresses it, mirroring `# kw-only: ignore`. There is exactly one in the tree, on the guard's own declaration of the forbidden path.
+
+`tests/` is scanned for the dead-module rule only. `tests.*` sits in no declared layer, so a test may freely patch `pipelex.interpreter_hub` — while a stale `pipelex.hub` patch target, the landmine above, still fails the check.
+
+### The property — the import-closure test
+
+`tests/unit/pipelex/test_runtime_layer_import_closure.py` imports each runtime-layer entry point in a **subprocess** and asserts that zero interpreter modules — and no `pipelex.interpreter_hub` — landed in `sys.modules`. This is the [measurement above](#why-the-boundary-exists), pinned. It exists separately from the lint because the two fail independently: a runtime-layer module reaching directly into `pipe_operators`, without touching a hub, breaks the property while the lint stays green.
+
+Its predicate is stricter than the one-liner above: besides the five interpreter top-level packages it names core's Pipe-machinery modules one by one, because most of them only get caught *transitively* — through the `pipe_operators` / `libraries` they pull in — and `core.pipes.pipe_blueprint` pulls in none of it, so a runtime-layer import of it would otherwise pass. Naming them is what makes the predicate state the boundary rather than approximate it. What the predicate deliberately cannot name yet is `pipeline`, `pipe_run` and `core.bundles.exceptions`: interpreter-named homes whose leaf models already land in every runtime closure — `core.pipes.pipe_output` reaches `pipeline.pipeline_models` for a single leaf constant, for instance. Naming them today would fail every entry point on a placement wart rather than a broken arrow. Move the leaves to a runtime-layer home first, then widen the predicate.
+
+The detector lives inside a `textwrap.dedent` string, so no linter or type checker sees the names in it and a typo would make every entry point pass *vacuously*. A negative control closes that: `pipelex.interpreter_hub` is dirty by definition, and the test asserts it comes back reported as offending modules — so a detector that has stopped detecting fails rather than going quietly green. Each subprocess is time-bounded, because an unbounded one turns a deadlock into a hung suite instead of a failure.
+
+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.
+
+### 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.
+
+Two checks make that review mechanical rather than a re-read, and are the ones to run:
+
+- Extract every public module-level symbol from `runtime_hub` and `interpreter_hub` and confirm each appears in the partition tables above. An undocumented accessor is the failure mode this contract exists to catch.
+- Import `RUNTIME_LAYER_PACKAGES` from the guard and confirm every declared package is named under [The rule](#the-rule-make-check-hub-layering).
+
+## Known inversions
+
+Named so this document stays honest. Not one of them imports `interpreter_hub` *directly*, so the guard does not flag them — but four reach it transitively, which is why "`plugins` is a runtime layer" is not yet unconditionally true. This is measured, not suspected:
+
+```
+pipelex.plugins.direct.direct_plugin interpreter_hub=True interpreter modules= 57
+pipelex.plugins.discovery interpreter_hub=True interpreter modules= 67
+pipelex.plugins.builtins interpreter_hub=True interpreter modules= 67
+pipelex.plugins.pipe_func.pipe_func_plugin interpreter_hub=True interpreter modules= 58
+```
+
+**The headline property is unaffected**, and that is why the closure test stays green: nothing on the inference-layer or `runtime_hub` path reaches these four. They load only on the full boot path, where the interpreter is loaded anyway. A static sweep of every declared runtime-layer module puts the blast radius at exactly these four of 476 — the other ten declared packages are clean across 345 modules.
+
+- **`plugins/direct/direct_plugin.py` and `plugins/pipe_func/pipe_func_plugin.py` are the two leaves**, and they breach for the same reason: their job is to *construct interpreter-layer objects*. `direct_plugin` registers a `DirectOrchestrator` and a `DirectBundleValidator`, reaching `interpreter_hub` by two independent routes (`runtime_bridge/` and `pipeline/`), so cutting either one alone changes nothing. `pipe_func_plugin` imports the concrete `DirectPipeFuncExecutor` from `pipe_operators/` at module level — it needs the class at runtime, because it constructs it.
+- **`plugins/builtins.py` and `plugins/discovery.py` breach purely as aggregators.** `builtins.py` imports every built-in plugin including those two; `discovery.py` imports `builtins`, and sits on the boot path. Neither carries an edge of its own, so fixing the two leaves clears all four.
+- `plugins/pipe_func_executor_registry.py` is typed by a protocol from `pipe_operators/` and defers that import under `TYPE_CHECKING` precisely because `pipelex.config` imports it and the inference layer imports `pipelex.config` — a module-level import there would drag the interpreter back into every inference closure. Being type-only it loads nothing, so it is not one of the four above — the sanctioned deferral pattern. The placement inversion itself is unfixed.
+
+**The fix is decided and scheduled as its own change**, because it is a relocation rather than a declaration edit: split `builtins.py` by layer, move the two interpreter-touching plugins to an interpreter-side home, invert `discovery`'s dependency so the plugin list arrives as a parameter, and let the boot entrypoint — which sits in no declared layer and is free to weld — compose the two halves. That is the seam external plugins already use: an out-of-tree orchestrator or PipeFunc executor arrives through the entry-point mechanism without welding anything, and the in-tree built-ins are the only ones that weld. Alongside it, the guard learns to follow the import graph, so this class of breach cannot recur silently.
+- `core/`'s Pipe-touching half — `pipe_abstract`, `pipe_blueprint`, `pipe_factory`, `pipes/rendering/`, `bundles/`, `interpreter/`, `registry_models` — imports the interpreter directly. That is not an inversion to fix but a fact about what a pipe is (see [Where core splits](#where-core-splits)); it is listed here only so nobody re-reads the runtime-layer declaration as an oversight. Three of those modules import `interpreter_hub` on purpose, to inject downward.
+- Broader measured inversions, out of scope for the hub boundary: `cogt → core`, `system → cogt`, `plugins → runtime_bridge`, and `cogt/model_backends/model_lists.py` importing `pipelex.cli.exceptions.PipelexCLIError`. What remains of `tools → cogt` is `tools/pdf/pypdfium2_renderer.py` reaching for `cogt.extract` and `cogt.image` types; the templating half of that cluster is gone (see [Placement, not coupling](#placement-not-coupling)).
+
+## For consumers outside this repo
+
+`pipelex.hub` is gone; there is no shim. Every external importer must choose a layer. The symbols that crossed the repo boundary are split as follows — runtime-layer ones now come from `pipelex.runtime_hub`, interpreter-layer ones from `pipelex.interpreter_hub`, per the tables above. `get_pipelex_hub` splits into `get_runtime_hub` and `get_interpreter_hub`, so each call site must pick the container it actually meant.
diff --git a/docs/errors/execution-and-runtime.md b/docs/errors/execution-and-runtime.md
index 36c48e4c4..349ff7bea 100644
--- a/docs/errors/execution-and-runtime.md
+++ b/docs/errors/execution-and-runtime.md
@@ -28,7 +28,6 @@ own page. Classes are grouped by subsystem.
- [`FixTransactionError`](fix-transaction-error.md) — Fix transaction
- [`FixWriteConflictError`](fix-write-conflict-error.md) — Fix write conflict
-- [`JobMetadataError`](job-metadata-error.md) — Job metadata
- [`PipeExecutionError`](pipe-execution-error.md) — Pipe execution
- [`PipeIOContractError`](pipe-io-contract-error.md) — Pipe IO contract
- [`PipeStackOverflowError`](pipe-stack-overflow-error.md) — Pipe stack overflow
diff --git a/docs/errors/job-metadata-error.md b/docs/errors/job-metadata-error.md
index 5a59b3b10..29f0a1bbd 100644
--- a/docs/errors/job-metadata-error.md
+++ b/docs/errors/job-metadata-error.md
@@ -13,7 +13,7 @@ description: "Reference for the `JobMetadataError` Pipelex error class."
| `title` | Job metadata |
| `type_uri` | `https://docs.pipelex.com/latest/errors/job-metadata-error/` |
| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
+| Defined in | `pipelex.system.exceptions` |
| Parent class | [`PipelexUnexpectedError`](pipelex-unexpected-error.md) |
[Back to Error Reference](index.md)
diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.md
index efffbd1c6..96d08233c 100644
--- a/docs/errors/platform-and-tooling.md
+++ b/docs/errors/platform-and-tooling.md
@@ -72,6 +72,7 @@ own page. Classes are grouped by subsystem.
- [`GatewayTelemetryManagerInjectedError`](gateway-telemetry-manager-injected-error.md) — Gateway telemetry manager injected
- [`GatewayTermsNotAcceptedError`](gateway-terms-not-accepted-error.md) — Gateway terms not accepted
- [`InferenceSetupRequiredError`](inference-setup-required-error.md) — Inference setup required
+- [`JobMetadataError`](job-metadata-error.md) — Job metadata
- [`LangfuseCredentialsError`](langfuse-credentials-error.md) — Langfuse credentials
- [`MissingDependencyError`](missing-dependency-error.md) — Missing dependency
- [`NestedKeyConflictError`](nested-key-conflict-error.md) — Nested key conflict
diff --git a/docs/under-the-hood/architecture-overview.md b/docs/under-the-hood/architecture-overview.md
index 66fe12205..5a50706e1 100644
--- a/docs/under-the-hood/architecture-overview.md
+++ b/docs/under-the-hood/architecture-overview.md
@@ -92,6 +92,30 @@ Each plugin translates Pipelex's unified interface into provider-specific API ca
---
+## What Keeps The Layers Apart: The Two Hubs
+
+The two layers above would be a diagram rather than an architecture if nothing enforced the split. What enforces it is the **hub** — the mechanism every component uses to reach a shared dependency (the config, a model deck, the pipe library) without importing the module that owns it.
+
+There are two hubs, and the boundary between them *is* the boundary between the layers:
+
+- [**`pipelex/runtime_hub.py`**](https://github.com/Pipelex/pipelex/tree/main/pipelex/runtime_hub.py) — process-scoped infrastructure. Config, console, secrets, storage, telemetry, the model deck, the inference workers, the content generator, the plugin registries. Configured once at boot; identical for every method the process runs.
+- [**`pipelex/interpreter_hub.py`**](https://github.com/Pipelex/pipelex/tree/main/pipelex/interpreter_hub.py) — library-scoped method machinery. The library manager and the concept/domain/pipe libraries, the current-library binding, the pipe router, the pipeline manager, the PipeFunc executor. Tied to the method that is loaded.
+
+One rule governs them:
+
+!!! note "The one arrow"
+ `interpreter_hub` imports `runtime_hub`. **`runtime_hub` never imports `interpreter_hub`.**
+
+The practical consequence is that the runtime layer cannot reach the interpreter layer. Importing the inference stack loads no `libraries`, `pipe_operators`, `pipe_controllers`, or `codegen` module at all — so anything that just wants a secret, the console, or the model deck (a health check, `pipelex --version`, a plugin's registration module) does not pay for the method interpreter, and a change to a pipe blueprint structurally cannot perturb the import graph of `cogt`.
+
+That is not a convention held up by review: `make check-hub-layering` fails the build if a runtime-layer module imports — or merely names in a string — the interpreter hub, and an import-closure test pins the property itself in a subprocess.
+
+`pipelex/core/` sits on both sides of the line, deliberately. Its data model — concepts, domains, stuffs, working memory, the input/output specs — belongs to the runtime layer: it describes what a method's values *are*, needs no loaded method, and takes the concept or pipe it needs as an injected argument. Everything in `core/` that names a **`Pipe`** belongs to the interpreter layer, because a pipe is the interpreter's own object.
+
+Contributors: the full specification — what lives on each hub, how to place a new symbol, and how the boundary is enforced — is in [Hub Layering](../contribute/hub-layering.md).
+
+---
+
## How It All Fits Together
```mermaid
diff --git a/docs/under-the-hood/codegen-projections.md b/docs/under-the-hood/codegen-projections.md
index 19f84e72f..982c6b97c 100644
--- a/docs/under-the-hood/codegen-projections.md
+++ b/docs/under-the-hood/codegen-projections.md
@@ -8,7 +8,7 @@ This page describes the projection engine in `pipelex/codegen/` and the contract
The engine reads the crate through two neutral, language-agnostic layers, so every emitter consumes the same resolved shape rather than re-deriving the semantic mapping:
-- **Resolved fields** (`pipelex/codegen/resolved_fields.py`) — one structure field becomes a `ResolvedType` tree (`text`/`number`/`concept`/`list`/`dict`/`literal`/…). Inline `choices` become a literal; a bare concept ref is promoted to its domain; natives are flagged. Where the source under-specifies a shape — a `list` with no `item_type`, a `concept` field with no ref — the resolved type is `ANY` carrying an explicit **imprecision marker** (never a guess).
+- **Resolved fields** (`pipelex/core/concepts/resolved_fields.py`) — one structure field becomes a `ResolvedType` tree (`text`/`number`/`concept`/`list`/`dict`/`literal`/…). Inline `choices` become a literal; a bare concept ref is promoted to its domain; natives are flagged. Where the source under-specifies a shape — a `list` with no `item_type`, a `concept` field with no ref — the resolved type is `ANY` carrying an explicit **imprecision marker** (never a guess).
- **Resolved concepts** (`pipelex/codegen/resolved_concepts.py`) — one crate concept becomes a `ResolvedConcept`: its type name inputs (domain, code, collision flag), its description, its refinement base, and either its resolved fields, or a structureless/opaque marker. Class naming is decided here once: a concept code that is unique across the crate stays bare (`Report`); a code that collides across domains is domain-qualified so a definition and every reference agree.
An emitter then walks the `ResolvedLibrary` and renders text. Emitters live in `pipelex/codegen/emitters/`, dispatched by `emit_types(crate, target=...)`.
diff --git a/docs/under-the-hood/execution-graph-tracing.md b/docs/under-the-hood/execution-graph-tracing.md
index 4ef6d53fe..86afd6f20 100644
--- a/docs/under-the-hood/execution-graph-tracing.md
+++ b/docs/under-the-hood/execution-graph-tracing.md
@@ -264,10 +264,10 @@ Trace events travel through an `EventLogProtocol` backend (`pipelex/tracing/`):
The assembled usage rides back on `pipe_output.tokens_usages` (with any assembly failure on `usage_assembly_error`), which the sync `/execute` response returns directly. For delivery-enabled runs (a storage target set), the delivery executor (`pipelex/pipe_run/delivery_executor.py`) also persists it as a `tokens_usages.json` result artifact — `{"tokens_usages": [...], "usage_assembly_error": null}` — next to `working_memory.json`, the `main_stuff.*` renders, and the graph outputs, so a durable client polling result files gets the same usage records a sync caller does. The artifact is written unconditionally on every successful result delivery: explicit nulls mean usage assembly was off for that run. A failed run stores no result files at all, so an absent `tokens_usages.json` means either the run failed or it was delivered before the artifact existed — tell those apart from the delivery status, not from the file's presence.
-For fully in-process runs, `pipelex.hub.scoped_event_log` pins one shared instance for both sides instead:
+For fully in-process runs, `pipelex.runtime_hub.scoped_event_log` pins one shared instance for both sides instead:
```python
-from pipelex.hub import scoped_event_log
+from pipelex.runtime_hub import scoped_event_log
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
with scoped_event_log(InMemoryEventLog()):
@@ -520,7 +520,8 @@ validate_graphspec(graph_spec)
| `pipelex/graph/graph_tracer.py` | GraphTracer implementation |
| `pipelex/graph/graph_tracer_manager.py` | Singleton manager for tracers |
| `pipelex/graph/graph_tracer_protocol.py` | Protocol + NoOp implementation |
-| `pipelex/graph/trace_context.py` | Serializable tracing context |
+| `pipelex/system/trace_context.py` | Serializable tracing context — sits below `graph/` because it rides in every job's metadata |
+| `pipelex/system/data_inclusion_config.py` | Data-capture flags carried by the trace context, surfaced in the TOML under `graph_config.data_inclusion` |
| `pipelex/graph/graph_analysis.py` | Pre-computed graph analysis |
| `pipelex/graph/graph_factory.py` | Output generation factory |
| `pipelex/graph/graph_config.py` | Configuration models |
diff --git a/docs/under-the-hood/pipe-routing-and-execution.md b/docs/under-the-hood/pipe-routing-and-execution.md
index 1dd04ac75..4b2343a7f 100644
--- a/docs/under-the-hood/pipe-routing-and-execution.md
+++ b/docs/under-the-hood/pipe-routing-and-execution.md
@@ -304,7 +304,8 @@ flowchart TB
| LibraryCrate model | `pipelex/libraries/library_crate.py` |
| LibraryCrate factory | `pipelex/libraries/library_crate_factory.py` |
| Deferred hydration utility (open core) | `pipelex/runtime_bridge/primitives/hydration.py` |
-| Hub (get_required_pipe, get_class_registry) | `pipelex/hub.py` |
+| Interpreter hub (get_required_pipe) | `pipelex/interpreter_hub.py` |
+| Runtime hub (get_class_registry) | `pipelex/runtime_hub.py` |
| PipeSequence | `pipelex/pipe_controllers/sequence/pipe_sequence.py` |
| PipeCondition | `pipelex/pipe_controllers/condition/pipe_condition.py` |
| PipeBatch | `pipelex/pipe_controllers/batch/pipe_batch.py` |
diff --git a/docs/under-the-hood/runtime-bridge-and-transport.md b/docs/under-the-hood/runtime-bridge-and-transport.md
index 66955b4de..1a5804651 100644
--- a/docs/under-the-hood/runtime-bridge-and-transport.md
+++ b/docs/under-the-hood/runtime-bridge-and-transport.md
@@ -123,7 +123,7 @@ A single worker may process many concurrent jobs. If two jobs define a concept n
3. **Lookup chain** — `hub.get_class_registry()` reads the `ContextVar`, returns the scoped library's registry, and falls back to the global registry when no library is set (e.g. a data converter running outside the job scope — which is exactly why output uses deferred hydration).
4. **Cleanup** — `library_manager.teardown(library_id)` drops the library and its registry; the `ContextVar` is reset. No manual GC needed.
-The hub's class-registry and library scoping (`pipelex/hub.py`, `pipelex/libraries/library.py`, `pipelex/libraries/library_manager.py`) is open core — the same machinery serves direct execution, the open runner, and any host-runtime plugin.
+The class-registry accessor and its library scoping (`pipelex/runtime_hub.py`, `pipelex/system/registries/class_registry_access.py`, `pipelex/interpreter_hub.py`, `pipelex/libraries/library.py`, `pipelex/libraries/library_manager.py`) is open core — the same machinery serves direct execution, the open runner, and any host-runtime plugin.
---
diff --git a/drift.toml b/drift.toml
index c26deba6a..098359e2b 100644
--- a/drift.toml
+++ b/drift.toml
@@ -54,3 +54,20 @@ review = [
"docs/contribute/keyword-only-arguments.md",
]
verify_commands = []
+
+[contracts.hub-layering-convention]
+description = "The hub-layering doc is the boundary's specification and must track the guard and the two hubs."
+# The guard owns the rule (declared runtime layer, violation kinds, carve-outs); the two hub
+# modules own the symbol partition the doc tabulates accessor by accessor. A symbol added to or
+# moved between them silently falsifies those tables, which is the staleness this contract exists
+# to catch. No verify command: `check-hub-layering` already gates `make check` and CI, so re-running
+# it here would only add the unstaged-file hard error without adding a guarantee.
+triggers = [
+ "pipelex/cli/dev_cli/commands/hub_layering_guard.py",
+ "pipelex/runtime_hub.py",
+ "pipelex/interpreter_hub.py",
+]
+review = [
+ "docs/contribute/hub-layering.md",
+]
+verify_commands = []
diff --git a/mkdocs.yml b/mkdocs.yml
index 3983dd0ea..955faed52 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -329,6 +329,7 @@ plugins:
- contributing.md: "Contributing"
- contribute/configuration-defaults-and-overrides.md: "Configuration Internals"
- contribute/keyword-only-arguments.md: "Keyword-Only Arguments"
+ - contribute/hub-layering.md: "Hub Layering"
- contribute/drift-contracts.md: "Drift Contracts"
- changelog.md: "Changelog"
@@ -567,6 +568,7 @@ nav:
- Contributing: contributing.md
- Configuration Internals: contribute/configuration-defaults-and-overrides.md
- Keyword-Only Arguments: contribute/keyword-only-arguments.md
+ - Hub Layering: contribute/hub-layering.md
- Drift Contracts: contribute/drift-contracts.md
- Code of Conduct: CODE_OF_CONDUCT.md
- License: license.md
diff --git a/pipelex/builder/operations/inputs_ops.py b/pipelex/builder/operations/inputs_ops.py
index ec63528c3..91a56c778 100644
--- a/pipelex/builder/operations/inputs_ops.py
+++ b/pipelex/builder/operations/inputs_ops.py
@@ -5,14 +5,9 @@ from __future__ import annotations
import json
from typing import TYPE_CHECKING, Any
-from pipelex.core.pipes.inputs.input_renderer import build_concept_comments, render_inputs
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import (
- get_library_manager,
- get_required_pipe,
- resolve_library_dirs,
- set_current_library,
-)
+from pipelex.core.pipes.rendering.input_renderer import build_concept_comments, render_inputs
+from pipelex.interpreter_hub import get_library_manager, get_required_pipe, resolve_library_dirs, set_current_library
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.validate_bundle import validate_bundle
diff --git a/pipelex/builder/operations/models_ops.py b/pipelex/builder/operations/models_ops.py
index dfeb12fce..55e819aa4 100644
--- a/pipelex/builder/operations/models_ops.py
+++ b/pipelex/builder/operations/models_ops.py
@@ -6,7 +6,7 @@ from typing import Any
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.models.model_deck import ModelDeck
-from pipelex.hub import get_model_deck
+from pipelex.runtime_hub import get_model_deck
# TODO: get this from somewhere else, not hardcoded here.
diff --git a/pipelex/builder/operations/output_ops.py b/pipelex/builder/operations/output_ops.py
index a9ca8066a..cb16a7596 100644
--- a/pipelex/builder/operations/output_ops.py
+++ b/pipelex/builder/operations/output_ops.py
@@ -6,8 +6,8 @@ import json
from typing import Any
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
-from pipelex.core.pipes.output.output_renderer import render_output
-from pipelex.hub import get_required_pipe
+from pipelex.core.pipes.rendering.output_renderer import render_output
+from pipelex.interpreter_hub import get_required_pipe
from pipelex.pipeline.validate_bundle import validate_bundle
diff --git a/pipelex/builder/operations/runner_code_ops.py b/pipelex/builder/operations/runner_code_ops.py
index 1af0c0e2e..4196e39b8 100644
--- a/pipelex/builder/operations/runner_code_ops.py
+++ b/pipelex/builder/operations/runner_code_ops.py
@@ -4,13 +4,7 @@ from __future__ import annotations
from pipelex.builder.runner_code import generate_runner_code
from pipelex.core.interpreter.interpreter import PipelexInterpreter
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- get_required_pipe,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library
from pipelex.pipeline.bundle_validator import BundleValidator
diff --git a/pipelex/builder/operations/validate_ops.py b/pipelex/builder/operations/validate_ops.py
index 89bae1e1a..1516c76f5 100644
--- a/pipelex/builder/operations/validate_ops.py
+++ b/pipelex/builder/operations/validate_ops.py
@@ -4,7 +4,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
get_library_manager,
diff --git a/pipelex/builder/pipe/pipe_compose_spec.py b/pipelex/builder/pipe/pipe_compose_spec.py
index 679822f0a..82ae017a4 100644
--- a/pipelex/builder/pipe/pipe_compose_spec.py
+++ b/pipelex/builder/pipe/pipe_compose_spec.py
@@ -10,11 +10,11 @@ from typing_extensions import override
from pipelex.builder.pipe.pipe_spec import PipeSpec
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.pretty import PrettyPrintable
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
class TargetFormat(StrEnum):
diff --git a/pipelex/builder/runner_code.py b/pipelex/builder/runner_code.py
index b2d5e6d4e..eaa8a0f3f 100644
--- a/pipelex/builder/runner_code.py
+++ b/pipelex/builder/runner_code.py
@@ -22,7 +22,7 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
STRUCTURES_MODULE = "structures.structures"
"""Module path of the emitted types projection, relative to the generated script's directory."""
diff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.py
index dec199a60..6bb9f12c9 100644
--- a/pipelex/cli/_cli.py
+++ b/pipelex/cli/_cli.py
@@ -23,7 +23,7 @@ from pipelex.cli.commands.which_cmd import which_cmd
from pipelex.cli.deck_notice import warn_if_deck_stale
from pipelex.cli.error_handlers import set_traceback_requested
from pipelex.cli.readiness import check_readiness
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.tools.misc.package_utils import get_package_version
# Core commands in display order (natural ordering doesn't work between Typer groups and commands).
diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
index 8ea8729c4..caba5ab95 100644
--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py
+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
@@ -12,8 +12,8 @@ import typer
from pipelex.cli.agent_cli.commands.agent_output import agent_error, record_setup_warning
from pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetValidatonError
-from pipelex.hub import PipelexHub
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import RuntimeHub
from pipelex.system.console_target import ConsoleTarget
from pipelex.system.pipelex_service.exceptions import (
GatewayApiKeyMissingError,
@@ -155,7 +155,7 @@ def apply_agent_cli_output_discipline() -> None:
"""
log.redirect_to_stderr()
PrettyPrinter.mode = PrettyPrintMode.SILENT
- hub = PipelexHub.get_optional_instance()
+ hub = RuntimeHub.get_optional_instance()
if hub is not None:
hub.set_console_print_target(target=ConsoleTarget.STDERR)
@@ -190,7 +190,7 @@ def make_pipelex_for_agent_cli(
``~/.pipelex/pipelex.toml`` sets ``pipelex = "DEBUG"``.
2. ``PrettyPrinter.mode = SILENT`` neutralizes ``pretty_print(...)`` entirely.
3. Post-init ``log.redirect_to_stderr()`` and
- ``get_pipelex_hub().set_console_print_target(STDERR)`` defense-in-depth.
+ ``get_runtime_hub().set_console_print_target(STDERR)`` defense-in-depth.
Args:
library_dirs: Optional library directories to use for the Pipelex instance.
diff --git a/pipelex/cli/agent_cli/commands/check_model_cmd.py b/pipelex/cli/agent_cli/commands/check_model_cmd.py
index 2e3bb5be7..1d5a66d03 100644
--- a/pipelex/cli/agent_cli/commands/check_model_cmd.py
+++ b/pipelex/cli/agent_cli/commands/check_model_cmd.py
@@ -14,8 +14,8 @@ from pipelex.cogt.models.model_suggestion import (
get_collection_keys,
suggest_model_alternatives,
)
-from pipelex.hub import get_model_deck
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_model_deck
def _format_check_markdown(result: dict[str, Any]) -> str:
diff --git a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
index 459e29b58..09f4771b3 100644
--- a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
+++ b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any, cast
from pipelex.builder.operations.inputs_ops import build_inputs_for_pipe
from pipelex.cli.agent_cli.commands.agent_output import agent_success
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat, serialize_inputs_template_to_toml
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat, serialize_inputs_template_to_toml
if TYPE_CHECKING:
from pathlib import Path
diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
index c6ad6a69b..535680905 100644
--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
@@ -15,7 +15,7 @@ from pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_resul
from pipelex.core.interpreter.helpers import MTHDS_EXTENSION, is_pipelex_file
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
from pipelex.pipeline.exceptions import ValidateBundleError
diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
index 516cf6fc7..f71014584 100644
--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
@@ -14,7 +14,7 @@ from pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_resul
from pipelex.cli.method_resolver import resolve_method_target
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
from pipelex.pipeline.exceptions import ValidateBundleError
diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
index 08cf0c6d2..038c82cf9 100644
--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
@@ -15,7 +15,7 @@ from pipelex.cli.method_resolver import resolve_pipe_from_exports
from pipelex.core.interpreter.helpers import MTHDS_EXTENSION, is_pipelex_file
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
from pipelex.pipeline.exceptions import ValidateBundleError
diff --git a/pipelex/cli/agent_cli/commands/validate/_validate_core.py b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
index 94c86636f..c07252202 100644
--- a/pipelex/cli/agent_cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
@@ -4,7 +4,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
get_library_manager,
diff --git a/pipelex/cli/commands/build/inputs/_inputs_core.py b/pipelex/cli/commands/build/inputs/_inputs_core.py
index 60aa8704f..2e91d50b6 100644
--- a/pipelex/cli/commands/build/inputs/_inputs_core.py
+++ b/pipelex/cli/commands/build/inputs/_inputs_core.py
@@ -15,12 +15,13 @@ from pipelex.cli.error_handlers import (
)
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.inputs.exceptions import PipeInputError
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat, NoInputsRequiredError, render_inputs, render_inputs_toml
-from pipelex.hub import get_library_manager, get_required_pipe, get_telemetry_manager, resolve_library_dirs, set_current_library
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat, NoInputsRequiredError, render_inputs, render_inputs_toml
+from pipelex.interpreter_hub import get_library_manager, get_required_pipe, resolve_library_dirs, set_current_library
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import PACKAGE_VERSION
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.file_utils import (
diff --git a/pipelex/cli/commands/build/inputs/bundle_cmd.py b/pipelex/cli/commands/build/inputs/bundle_cmd.py
index 9ab5ff3ea..c096689e0 100644
--- a/pipelex/cli/commands/build/inputs/bundle_cmd.py
+++ b/pipelex/cli/commands/build/inputs/bundle_cmd.py
@@ -8,7 +8,7 @@ import typer
from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME
from pipelex.cli.commands.build.inputs._inputs_core import execute_generate_inputs
from pipelex.core.interpreter.helpers import MTHDS_EXTENSION, is_pipelex_file
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
def build_inputs_bundle_cmd(
diff --git a/pipelex/cli/commands/build/inputs/method_cmd.py b/pipelex/cli/commands/build/inputs/method_cmd.py
index 5a7d0a53f..1f88399bb 100644
--- a/pipelex/cli/commands/build/inputs/method_cmd.py
+++ b/pipelex/cli/commands/build/inputs/method_cmd.py
@@ -8,7 +8,7 @@ import typer
from pipelex.builder.conventions import DEFAULT_INPUTS_FILE_NAME, DEFAULT_INPUTS_TOML_FILE_NAME
from pipelex.cli.commands.build.inputs._inputs_core import execute_generate_inputs
from pipelex.cli.method_resolver import resolve_method_target
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
def build_inputs_method_cmd(
diff --git a/pipelex/cli/commands/build/inputs/pipe_cmd.py b/pipelex/cli/commands/build/inputs/pipe_cmd.py
index 4ac82731c..c8e0722c7 100644
--- a/pipelex/cli/commands/build/inputs/pipe_cmd.py
+++ b/pipelex/cli/commands/build/inputs/pipe_cmd.py
@@ -6,7 +6,7 @@ from typing import Annotated
import typer
from pipelex.cli.commands.build.inputs._inputs_core import execute_generate_inputs
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
def build_inputs_pipe_cmd(
diff --git a/pipelex/cli/commands/build/output/_output_core.py b/pipelex/cli/commands/build/output/_output_core.py
index 12e096639..2df512eea 100644
--- a/pipelex/cli/commands/build/output/_output_core.py
+++ b/pipelex/cli/commands/build/output/_output_core.py
@@ -15,12 +15,13 @@ from pipelex.cli.error_handlers import (
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.inputs.exceptions import PipeInputError
-from pipelex.core.pipes.output.output_renderer import render_output
-from pipelex.hub import get_library_manager, get_required_pipe, get_telemetry_manager, resolve_library_dirs, set_current_library
+from pipelex.core.pipes.rendering.output_renderer import render_output
+from pipelex.interpreter_hub import get_library_manager, get_required_pipe, resolve_library_dirs, set_current_library
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import PACKAGE_VERSION
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.file_utils import (
diff --git a/pipelex/cli/commands/build/runner/_runner_core.py b/pipelex/cli/commands/build/runner/_runner_core.py
index dd0ce14f5..c33eec4a8 100644
--- a/pipelex/cli/commands/build/runner/_runner_core.py
+++ b/pipelex/cli/commands/build/runner/_runner_core.py
@@ -22,17 +22,13 @@ from pipelex.codegen.resolved_concepts import resolve_concepts_from_crate
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.inputs.exceptions import PipeInputError
from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity
-from pipelex.hub import (
- get_current_library_id_or_none,
- get_library_manager,
- get_required_pipe,
- get_telemetry_manager,
-)
+from pipelex.interpreter_hub import get_current_library_id_or_none, get_library_manager, get_required_pipe
from pipelex.libraries.crate_normalization import normalize_crate
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import PACKAGE_VERSION
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.file_utils import (
diff --git a/pipelex/cli/commands/codegen/inputs_cmd.py b/pipelex/cli/commands/codegen/inputs_cmd.py
index 020499441..9ff33033b 100644
--- a/pipelex/cli/commands/codegen/inputs_cmd.py
+++ b/pipelex/cli/commands/codegen/inputs_cmd.py
@@ -18,12 +18,13 @@ from pipelex.builder.conventions import DEFAULT_INPUTS_FILE_NAME, DEFAULT_INPUTS
from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.commands.crate_loading import load_normalized_crate_or_exit
from pipelex.cli.error_handlers import ErrorContext
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat, NoInputsRequiredError, render_inputs, render_inputs_toml
from pipelex.core.pipes.pipe_abstract import PipeAbstract
-from pipelex.hub import get_required_pipe, get_telemetry_manager
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat, NoInputsRequiredError, render_inputs, render_inputs_toml
+from pipelex.interpreter_hub import get_required_pipe
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe.exceptions import PipeLibraryError
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.file_utils import ensure_directory_for_file_path, save_text_to_path
diff --git a/pipelex/cli/commands/codegen/types_cmd.py b/pipelex/cli/commands/codegen/types_cmd.py
index 944541cdf..1cb3b607a 100644
--- a/pipelex/cli/commands/codegen/types_cmd.py
+++ b/pipelex/cli/commands/codegen/types_cmd.py
@@ -20,8 +20,8 @@ from pipelex.cli.error_handlers import ErrorContext
from pipelex.codegen.emission import write_stamped_projection
from pipelex.codegen.emitters.target import CodegenKind, CodegenTarget
from pipelex.codegen.emitters.types_emitter import emit_types
-from pipelex.hub import get_telemetry_manager
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.package_utils import get_package_version
diff --git a/pipelex/cli/commands/crate_loading.py b/pipelex/cli/commands/crate_loading.py
index 1b62ace3a..aaf739abe 100644
--- a/pipelex/cli/commands/crate_loading.py
+++ b/pipelex/cli/commands/crate_loading.py
@@ -17,7 +17,7 @@ from pathlib import Path
import typer
from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.crate_normalization import normalize_crate
from pipelex.libraries.exceptions import LibraryLoadingError
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.py
index 0823f0038..3cc70c284 100644
--- a/pipelex/cli/commands/doctor_cmd.py
+++ b/pipelex/cli/commands/doctor_cmd.py
@@ -38,8 +38,8 @@ from pipelex.cogt.models.deck_manifest import DeckFileStatus, DeckSyncReport, co
from pipelex.cogt.models.model_manager import ModelManager
from pipelex.config import get_config
from pipelex.core.validation import report_validation_error
-from pipelex.hub import PipelexHub, get_console, set_pipelex_hub
from pipelex.kit.paths import get_kit_configs_dir
+from pipelex.runtime_hub import RuntimeHub, get_console, set_runtime_hub
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.configuration.configs import PipelexConfig
from pipelex.system.environment import get_optional_env
@@ -739,7 +739,7 @@ def check_deck_sync(*, config_dir: Path | None = None) -> tuple[bool, DeckSyncRe
def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = None, config_dir: Path | None = None) -> None:
- """Spin up a fresh PipelexHub and configure logging for doctor checks.
+ """Spin up a fresh RuntimeHub and configure logging for doctor checks.
Doctor intentionally bypasses ``Pipelex.make`` so it can diagnose a broken config
without crashing during full init. This helper performs the minimum runtime setup
@@ -771,10 +771,10 @@ def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = Non
PipelexConfigError: If config validation fails. Translation of
``pydantic.ValidationError`` to keep doctor's error surface stable.
"""
- pipelex_hub = PipelexHub()
- set_pipelex_hub(pipelex_hub)
+ runtime_hub = RuntimeHub()
+ set_runtime_hub(runtime_hub)
try:
- pipelex_hub.setup_config(config_cls=PipelexConfig, config_dir=config_dir)
+ runtime_hub.setup_config(config_cls=PipelexConfig, config_dir=config_dir)
except ValidationError as validation_error:
validation_error_msg = report_validation_error(category="config", validation_error=validation_error)
msg = f"Could not setup config because of: {validation_error_msg}"
@@ -785,7 +785,7 @@ def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = Non
merged = log_config.model_dump()
deep_update(merged, updates=log_config_overrides)
log_config = LogConfig.model_validate(merged)
- pipelex_hub.set_console_print_target(target=log_config.console_print_target)
+ runtime_hub.set_console_print_target(target=log_config.console_print_target)
log.configure_if_unset(log_config=log_config)
diff --git a/pipelex/cli/commands/fix/_diff_sandbox.py b/pipelex/cli/commands/fix/_diff_sandbox.py
index c9a899c68..2113f7e7f 100644
--- a/pipelex/cli/commands/fix/_diff_sandbox.py
+++ b/pipelex/cli/commands/fix/_diff_sandbox.py
@@ -18,7 +18,7 @@ from pathlib import Path
from typing import NamedTuple
from pipelex.config import get_config
-from pipelex.hub import resolve_library_dirs
+from pipelex.interpreter_hub import resolve_library_dirs
def _excluded_copy_entries( # kw-only: ignore - shutil.copytree invokes ignore callbacks positionally
diff --git a/pipelex/cli/commands/fix/_fix_core.py b/pipelex/cli/commands/fix/_fix_core.py
index 5bd7ba061..8f6a187a0 100644
--- a/pipelex/cli/commands/fix/_fix_core.py
+++ b/pipelex/cli/commands/fix/_fix_core.py
@@ -20,10 +20,10 @@ from pipelex.cli.error_handlers import (
print_traceback_if_requested,
)
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
-from pipelex.hub import get_console, get_telemetry_manager
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
from pipelex.pipeline.fixes.fix_loop import fix_bundle_file
+from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.package_utils import get_package_version
diff --git a/pipelex/cli/commands/graph_cmd.py b/pipelex/cli/commands/graph_cmd.py
index 4363d3b93..7433b3ca8 100644
--- a/pipelex/cli/commands/graph_cmd.py
+++ b/pipelex/cli/commands/graph_cmd.py
@@ -21,8 +21,8 @@ from pipelex.cli.error_handlers import ErrorContext
from pipelex.config import get_config
from pipelex.graph.graph_rendering import render_graph_from_spec
from pipelex.graph.graphspec import GraphSpec
-from pipelex.hub import get_console, get_telemetry_manager
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventName, EventProperty
from pipelex.tools.misc.chart_utils import FlowchartDirection
diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.py
index 69ceaa1ed..1618d4f7f 100644
--- a/pipelex/cli/commands/init/backends.py
+++ b/pipelex/cli/commands/init/backends.py
@@ -21,8 +21,8 @@ from pipelex.cli.commands.init.ui.gateway_ui import (
prompt_gateway_acceptance,
)
from pipelex.cogt.model_backends.backend import PipelexBackend
-from pipelex.hub import get_console
from pipelex.kit.paths import get_kit_configs_dir
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.pipelex_service.pipelex_service_agreement import update_service_terms_acceptance
from pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_with_tomlkit, save_toml_to_path
diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.py
index 80ad0831d..21c700c66 100644
--- a/pipelex/cli/commands/init/command.py
+++ b/pipelex/cli/commands/init/command.py
@@ -28,8 +28,8 @@ from pipelex.cli.commands.init.ui.general_ui import build_initialization_panel
from pipelex.cli.commands.init.ui.types import InitFocus
from pipelex.cogt.model_backends.backend import PipelexBackend
from pipelex.cogt.models.deck_manifest import compute_kit_manifest, write_manifest
-from pipelex.hub import get_console
from pipelex.kit.paths import get_kit_configs_dir
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import BACKENDS_FILE_NAME, INFERENCE_DIR_NAME, config_manager
from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError
from pipelex.system.pipelex_service.pipelex_service_agreement import update_service_terms_acceptance
diff --git a/pipelex/cli/commands/init/routing.py b/pipelex/cli/commands/init/routing.py
index 224e4e46c..e82061967 100644
--- a/pipelex/cli/commands/init/routing.py
+++ b/pipelex/cli/commands/init/routing.py
@@ -17,8 +17,8 @@ from pipelex.cli.commands.init.ui.routing_ui import (
)
from pipelex.cogt.model_backends.backend import PipelexBackend
from pipelex.cogt.model_routing.routing_profile import PipelexRoutingProfile
-from pipelex.hub import get_console
from pipelex.kit.paths import get_kit_configs_dir
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
diff --git a/pipelex/cli/commands/login/command.py b/pipelex/cli/commands/login/command.py
index 6ae5c3db3..ace1db987 100644
--- a/pipelex/cli/commands/login/command.py
+++ b/pipelex/cli/commands/login/command.py
@@ -11,7 +11,7 @@ from urllib.parse import parse_qs, urlparse
from typing_extensions import override
from pipelex.cli.commands.init.credentials import get_global_env_path, read_env_file, write_env_file
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.urls import URLs
LOGIN_TIMEOUT_SECONDS = 120
diff --git a/pipelex/cli/commands/plugins_cmd.py b/pipelex/cli/commands/plugins_cmd.py
index 298790479..4ad42bd78 100644
--- a/pipelex/cli/commands/plugins_cmd.py
+++ b/pipelex/cli/commands/plugins_cmd.py
@@ -2,8 +2,8 @@ import typer
from rich import box
from rich.table import Table
-from pipelex.hub import get_console
from pipelex.plugins.discovery import build_registrar
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.configuration.configs import PipelexConfig
diff --git a/pipelex/cli/commands/resolve_cmd.py b/pipelex/cli/commands/resolve_cmd.py
index 7b3f61ee7..2233ab12b 100644
--- a/pipelex/cli/commands/resolve_cmd.py
+++ b/pipelex/cli/commands/resolve_cmd.py
@@ -19,8 +19,8 @@ from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.commands.crate_loading import load_normalized_crate_or_exit
from pipelex.cli.error_handlers import ErrorContext
from pipelex.codegen.crate_encoding import CrateEncoding, encode_crate
-from pipelex.hub import get_telemetry_manager
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.package_utils import get_package_version
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
index 2862ba63b..b258aa234 100644
--- a/pipelex/cli/commands/run/_run_core.py
+++ b/pipelex/cli/commands/run/_run_core.py
@@ -29,13 +29,13 @@ from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_viewer import render_stuff_viewer
from pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dir
-from pipelex.hub import get_console, get_telemetry_manager
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipelex import Pipelex
from pipelex.pipeline.exceptions import PipelineExecutionError
from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.reporting.cost_report_renderer import render_cost_report_for_output
+from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.exceptions import JsonTypeError, TomlError
diff --git a/pipelex/cli/commands/show_cmd.py b/pipelex/cli/commands/show_cmd.py
index 5687ac523..73eca220d 100644
--- a/pipelex/cli/commands/show_cmd.py
+++ b/pipelex/cli/commands/show_cmd.py
@@ -19,18 +19,9 @@ from pipelex.cli.error_handlers import ErrorContext
from pipelex.cli.exceptions import PipelexCLIError
from pipelex.cogt.model_backends.backend_library import InferenceBackendLibrary
from pipelex.cogt.model_backends.model_lists import ModelLister
-from pipelex.hub import (
- get_console,
- get_library_manager,
- get_models_manager,
- get_pipe_library,
- get_required_pipe,
- get_secrets_provider,
- get_telemetry_manager,
- resolve_library_dirs,
- set_current_library,
-)
+from pipelex.interpreter_hub import get_library_manager, get_pipe_library, get_required_pipe, resolve_library_dirs, set_current_library
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_console, get_models_manager, get_secrets_provider, get_telemetry_manager
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventName, EventProperty
diff --git a/pipelex/cli/commands/update_cmd.py b/pipelex/cli/commands/update_cmd.py
index ca40a94d5..06100ec3b 100644
--- a/pipelex/cli/commands/update_cmd.py
+++ b/pipelex/cli/commands/update_cmd.py
@@ -27,7 +27,7 @@ from pipelex.cogt.models.deck_manifest import (
suggest_x_custom_filename,
write_manifest,
)
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.py
index 4613d20bc..4b07f6dab 100644
--- a/pipelex/cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/commands/validate/_validate_core.py
@@ -15,16 +15,7 @@ from pipelex.cli.error_handlers import (
handle_validate_bundle_error,
)
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
-from pipelex.hub import (
- get_console,
- get_library_manager,
- get_pipe_library,
- get_pipes,
- get_required_pipe,
- get_telemetry_manager,
- resolve_library_dirs,
- set_current_library,
-)
+from pipelex.interpreter_hub import get_library_manager, get_pipe_library, get_pipes, get_required_pipe, resolve_library_dirs, set_current_library
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_signature.signature_walk import collect_signature_refs
@@ -35,6 +26,7 @@ from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.execution_seams import load_libraries_and_activate
from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.pipeline.validate_bundle import build_pending_signatures, validate_bundle
+from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.package_utils import get_package_version
diff --git a/pipelex/cli/commands/which_cmd.py b/pipelex/cli/commands/which_cmd.py
index 539c70852..95fe153d6 100644
--- a/pipelex/cli/commands/which_cmd.py
+++ b/pipelex/cli/commands/which_cmd.py
@@ -10,16 +10,9 @@ from posthog import tag
from pipelex import log
from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.error_handlers import ErrorContext
-from pipelex.hub import (
- get_console,
- get_library_manager,
- get_optional_pipe,
- get_pipe_source,
- get_telemetry_manager,
- resolve_library_dirs,
- set_current_library,
-)
+from pipelex.interpreter_hub import get_library_manager, get_optional_pipe, get_pipe_source, resolve_library_dirs, set_current_library
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventName, EventProperty
from pipelex.tools.misc.package_utils import get_package_version
diff --git a/pipelex/cli/deck_notice.py b/pipelex/cli/deck_notice.py
index ff0caeb50..542877125 100644
--- a/pipelex/cli/deck_notice.py
+++ b/pipelex/cli/deck_notice.py
@@ -9,7 +9,7 @@ from __future__ import annotations
import os
from pipelex.cogt.models.deck_manifest import is_deck_stale_fast
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
DECK_NOTICE_SUPPRESS_ENV_VAR = "PIPELEX_NO_DECK_NOTICE"
diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.py
index 20d207017..1bf37a2b2 100644
--- a/pipelex/cli/dev_cli/_dev_cli.py
+++ b/pipelex/cli/dev_cli/_dev_cli.py
@@ -12,6 +12,7 @@ from typing_extensions import override
from pipelex.cli.dev_cli.commands.check_config_sync_cmd import LeadingConfig, check_config_sync_cmd
from pipelex.cli.dev_cli.commands.check_gateway_models_cmd import check_gateway_models_cmd
+from pipelex.cli.dev_cli.commands.check_hub_layering_cmd import check_hub_layering_cmd
from pipelex.cli.dev_cli.commands.check_keyword_only_cmd import check_keyword_only_cmd
from pipelex.cli.dev_cli.commands.check_mthds_schema_cmd import check_mthds_schema_cmd
from pipelex.cli.dev_cli.commands.check_rules_sync_cmd import check_rules_sync_cmd
@@ -26,7 +27,7 @@ from pipelex.cli.dev_cli.commands.subject_grant_cmd import subject_grant_cmd
from pipelex.cli.dev_cli.commands.sync_kit_configs_cmd import sync_kit_configs_cmd
from pipelex.cli.dev_cli.commands.sync_main_config_cmd import SyncTarget, sync_main_config_cmd
from pipelex.cli.dev_cli.commands.update_gateway_models_cmd import update_gateway_models_cmd
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.tools.misc.package_utils import get_package_version
@@ -39,6 +40,7 @@ class PipelexDevCLI(TyperGroup):
return [
"check-config-sync",
"check-gateway-models",
+ "check-hub-layering",
"check-keyword-only",
"check-mthds-schema",
"check-rules",
@@ -253,6 +255,28 @@ def check_mthds_schema_command(
sys.exit(1)
[email protected](name="check-hub-layering", help="Enforce the runtime_hub / interpreter_hub layering boundary")
+def check_hub_layering_command(
+ quiet: Annotated[
+ bool, typer.Option("--quiet", "-q", help="Light output on success (single line); the full violation list still prints on failure")
+ ] = False,
+) -> None:
+ """Enforce the runtime_hub / interpreter_hub layering boundary."""
+ try:
+ check_hub_layering_cmd(quiet=quiet)
+ except (typer.Exit, typer.Abort):
+ # Typer control-flow exits carry an intended exit code — not a failure. Let them through.
+ raise
+ except Exception: # noqa: BLE001
+ # Dev CLI command root: print a traceback for any unexpected failure and exit non-zero.
+ console = get_console()
+ console.print()
+ console.print("[bold red]Unexpected error occurred[/bold red]")
+ console.print()
+ console.print(Traceback())
+ sys.exit(1)
+
+
@app.command(name="check-keyword-only", help="Enforce the keyword-only-arguments convention across pipelex/ source")
def check_keyword_only_command(
report: Annotated[bool, typer.Option("--report", help="Print the full violation inventory grouped by package")] = False,
diff --git a/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py b/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
index 996bd51ae..f7d385125 100644
--- a/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
@@ -9,8 +9,8 @@ from pathlib import Path
from rich.markup import escape
from rich.panel import Panel
-from pipelex.hub import get_console
from pipelex.kit.paths import CONFIG_SYNC_EXCLUDED_FILES, GIT_IGNORED_CONFIG_DIRS
+from pipelex.runtime_hub import get_console
from pipelex.tools.misc.diff import has_diff_dirs, make_diff_dirs_pretty
diff --git a/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py b/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
index 3786864bf..c3e0b075a 100644
--- a/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
@@ -16,7 +16,7 @@ from pipelex.cli.dev_cli.commands.gateway_models_generator import (
normalize_for_comparison,
)
from pipelex.cli.dev_cli.commands.update_gateway_models_cmd import gateway_models_reference_files
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError, RemoteConfigValidationError
if TYPE_CHECKING:
diff --git a/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.py b/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.py
new file mode 100644
index 000000000..62375a70c
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/check_hub_layering_cmd.py
@@ -0,0 +1,120 @@
+"""Command enforcing the two-hub layering boundary across ``pipelex/`` source and ``tests/``.
+
+`interpreter_hub` may import `runtime_hub`; **`runtime_hub` must never import `interpreter_hub`.** The guard
+checks the forbidden direction — a declared runtime-layer module may not import or name
+``pipelex.interpreter_hub`` — plus the dead-module rule: nothing anywhere may still reference the deleted
+``pipelex.hub``. The canonical human-readable specification lives in ``docs/contribute/hub-layering.md``.
+
+The pure-AST collection logic lives in the stdlib-only ``hub_layering_guard`` module; this module is
+the ``rich``/``pipelex.runtime_hub`` presentation layer wired into the ``pipelex-dev`` Typer app
+(``make check-hub-layering`` / ``make agent-check`` / CI). The tree is fully compliant, so the guard
+hard-blocks on ANY violation; the only sanctioned exceptions are a ``TYPE_CHECKING``-deferred type-only
+import and the inline ``# hub-layering: ignore`` escape hatch.
+
+The guard checks the *rule*. The *property* it protects — importing the inference layer loads zero
+interpreter modules — is pinned separately by ``tests/unit/pipelex/test_runtime_layer_import_closure.py``, because
+a stray import somewhere else entirely could break the property without touching a hub import.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.markup import escape
+from rich.panel import Panel
+
+from pipelex.cli.dev_cli.commands.hub_layering_guard import (
+ RUNTIME_LAYER_PACKAGES,
+ SCAN_ROOTS,
+ HubLayeringViolation,
+ collect_all_violations,
+)
+from pipelex.runtime_hub import get_console
+
+# --------------------------------------------------------------------------------------
+# Command entrypoint
+# --------------------------------------------------------------------------------------
+
+
+def check_hub_layering_cmd(*, quiet: bool = False) -> None:
+ """Enforce the ``runtime_hub`` / ``interpreter_hub`` layering boundary.
+
+ Args:
+ quiet: If True, keep the success output to a single line (for Make targets / CI). Quiet only
+ trims the happy path — a failure still prints the full actionable violation list.
+ """
+ console = get_console()
+
+ missing = [root for root in SCAN_ROOTS if not root.exists()]
+ if missing:
+ # An error is always loud — quiet only trims success output, never failures.
+ roots = ", ".join(f"[cyan]{escape(root.as_posix())}/[/cyan]" for root in missing)
+ console.print(f"[red]✗ Hub-layering check: FAILED[/red] - scan root(s) {roots} do not exist")
+ sys.exit(1)
+
+ violations = collect_all_violations(roots=SCAN_ROOTS)
+
+ if not violations:
+ # Success is the only thing quiet trims: one line in quiet mode, a panel otherwise.
+ if quiet:
+ console.print("[green]✓ Hub-layering check: PASSED[/green]")
+ else:
+ _print_success_panel()
+ return
+
+ # Failure is always actionable: list the offending sites so no re-run is needed — in quiet mode
+ # too, since the Make targets and CI invoke the guard quietly.
+ if quiet:
+ console.print(f"[red]✗ Hub-layering check: FAILED[/red] - {len(violations)} violation(s):")
+ else:
+ _print_failure_panel(violations=violations)
+ _print_violations_by_kind(violations=violations)
+ sys.exit(1)
+
+
+def _print_success_panel() -> None:
+ """Verbose success output (no violations)."""
+ console = get_console()
+ layers = ", ".join(RUNTIME_LAYER_PACKAGES)
+ console.print()
+ console.print(
+ Panel(
+ f"[green]✓[/green] No hub-layering violations.\n\n[dim]Runtime layer: {escape(layers)}[/dim]",
+ title="[bold green]Hub-layering Check: PASSED[/bold green]",
+ border_style="green",
+ padding=(1, 2),
+ )
+ )
+ console.print()
+
+
+def _print_failure_panel(*, violations: list[HubLayeringViolation]) -> None:
+ """Verbose failure output header."""
+ console = get_console()
+ console.print()
+ console.print(
+ Panel(
+ f"[red]✗[/red] {len(violations)} hub-layering violation(s) found.\n\n"
+ "[dim]The runtime layer must stay importable without loading the method interpreter — "
+ "each violation kind below names its remedy.[/dim]",
+ title="[bold red]Hub-layering Check: FAILED[/bold red]",
+ border_style="red",
+ padding=(1, 2),
+ )
+ )
+ console.print()
+
+
+def _print_violations_by_kind(*, violations: list[HubLayeringViolation]) -> None:
+ """Print the violations grouped by kind, each group headed by its remedy."""
+ console = get_console()
+ grouped: dict[str, list[HubLayeringViolation]] = {}
+ for violation in violations:
+ grouped.setdefault(violation.kind, []).append(violation)
+ for kind_value in sorted(grouped):
+ kind_violations = grouped[kind_value]
+ kind = kind_violations[0].kind
+ console.print(f"[bold]{escape(kind_value)}[/bold] ({len(kind_violations)}) — [dim]{escape(kind.remedy)}[/dim]")
+ for violation in kind_violations:
+ console.print(f" [red]{escape(violation.relative_path)}:{violation.lineno}[/red] [yellow]{escape(violation.detail)}[/yellow]")
+ console.print("[dim]See docs/contribute/hub-layering.md[/dim]")
diff --git a/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py b/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
index 0975bc688..d5c2cd443 100644
--- a/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
@@ -7,7 +7,7 @@ subject is legal only under an explicit grant recorded in ``subject_grants.toml`
The canonical human-readable specification lives in ``docs/contribute/keyword-only-arguments.md``.
The pure-AST collection logic lives in the stdlib-only ``keyword_only_guard`` module; this module
-is the ``rich``/``pipelex.hub`` presentation layer wired into the ``pipelex-dev`` Typer app
+is the ``rich``/``pipelex.runtime_hub`` presentation layer wired into the ``pipelex-dev`` Typer app
(``make check-keyword-only`` / ``make agent-check`` / CI). The ``pipelex/`` source tree is fully
compliant, so the guard hard-blocks on ANY violation (a bare ``*`` after the subject, a recorded
subject grant, or a ``# kw-only: ignore`` escape hatch with a justification, is required).
@@ -34,7 +34,7 @@ from pipelex.cli.dev_cli.commands.keyword_only_guard import (
fix_all_violations,
load_subject_grants,
)
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
if TYPE_CHECKING:
from pipelex.cli.dev_cli.commands.keyword_only_guard import SubjectGrant
@@ -47,7 +47,7 @@ if TYPE_CHECKING:
def _package_of(key_or_path: str) -> str:
"""The top-level package of a ``pipelex/...`` path or ``<path>::<qualname>`` key, for report grouping.
- Files sitting directly under the source root (``pipelex/hub.py``) group under ``(root)`` rather than
+ Files sitting directly under the source root (``pipelex/runtime_hub.py``) group under ``(root)`` rather than
each filename becoming its own one-off "package" line in the report.
"""
path = key_or_path.partition("::")[0]
diff --git a/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py b/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
index a59d8f36b..30b4437c3 100644
--- a/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
@@ -11,8 +11,8 @@ from rich.markup import escape
from rich.panel import Panel
from pipelex.cli.dev_cli.commands.generate_mthds_schema_cmd import MTHDS_SCHEMA_PATH
-from pipelex.hub import get_console
from pipelex.language.mthds_schema_generator import generate_mthds_schema
+from pipelex.runtime_hub import get_console
if TYPE_CHECKING:
from rich.console import Console
diff --git a/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py b/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
index df34804b4..a1f55adf7 100644
--- a/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
@@ -9,9 +9,9 @@ from typing import TYPE_CHECKING
from rich.markup import escape
from rich.panel import Panel
-from pipelex.hub import get_console
from pipelex.kit.index_loader import load_index
from pipelex.kit.single_file_agent_rules import build_merged_rules, unified_diff
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.configs import AgentTarget
from pipelex.tools.misc.toml_utils import load_toml_from_path
diff --git a/pipelex/cli/dev_cli/commands/check_urls_cmd.py b/pipelex/cli/dev_cli/commands/check_urls_cmd.py
index ae64d85e1..9e5d7e530 100644
--- a/pipelex/cli/dev_cli/commands/check_urls_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_urls_cmd.py
@@ -12,7 +12,7 @@ from rich.markup import escape
from rich.panel import Panel
from rich.table import Table
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.urls import URLs
# Default timeout in seconds for HTTP requests
diff --git a/pipelex/cli/dev_cli/commands/drift/drift_cmd.py b/pipelex/cli/dev_cli/commands/drift/drift_cmd.py
index 312ca6c36..1d658ed41 100644
--- a/pipelex/cli/dev_cli/commands/drift/drift_cmd.py
+++ b/pipelex/cli/dev_cli/commands/drift/drift_cmd.py
@@ -43,7 +43,7 @@ from pipelex.cli.dev_cli.commands.drift.models import (
load_manifest,
save_ack,
)
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
if TYPE_CHECKING:
from collections.abc import Sequence
diff --git a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
index c3a04605a..066e2c767 100644
--- a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
@@ -7,8 +7,8 @@ from pathlib import Path
from rich.panel import Panel
from pipelex.errors.error_pages_generator import generate_error_pages
-from pipelex.hub import get_console
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_console
ERROR_PAGES_DIR = Path("docs/errors")
diff --git a/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py b/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
index a6b6ae785..65eda6f22 100644
--- a/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
@@ -8,8 +8,8 @@ from pathlib import Path
from rich.panel import Panel
-from pipelex.hub import get_console
from pipelex.language.mthds_schema_generator import generate_mthds_schema
+from pipelex.runtime_hub import get_console
# Path to the generated schema file, in the derived/ directory (gitignored)
MTHDS_SCHEMA_PATH = Path("derived/mthds_schema.json")
diff --git a/pipelex/cli/dev_cli/commands/hub_layering_guard.py b/pipelex/cli/dev_cli/commands/hub_layering_guard.py
new file mode 100644
index 000000000..93d985daa
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/hub_layering_guard.py
@@ -0,0 +1,368 @@
+"""Pure-stdlib AST core for the two-hub layering boundary guard.
+
+Pipelex has two layers and one hub each. The **interpreter** layer reads a method and executes it; the
+**runtime** layer is the machinery present at execution time whatever is loaded. `interpreter_hub` may
+import `runtime_hub`; **`runtime_hub` must never import `interpreter_hub`**. That single arrow is the
+whole architecture, and the property it buys is measurable: importing the Pipelex runtime loads zero
+interpreter modules. The canonical human-readable specification lives in
+``docs/contribute/hub-layering.md``.
+
+This module holds the AST collection logic that mechanically enforces two rules:
+
+1. **The layer rule.** A module in the declared runtime layer (:data:`RUNTIME_LAYER_PACKAGES`) may not
+ import ``pipelex.interpreter_hub``. Since `runtime_hub`'s own closure is what the runtime layer is,
+ an import anywhere in it puts the interpreter back into every inference consumer.
+2. **The dead-module rule.** *No* scanned module may reference ``pipelex.hub``. That module was
+ deleted rather than kept as an alias for either half, precisely so a stale import fails loudly —
+ this rule closes the one hole in that guarantee (see below).
+
+Both rules match **imports and bare string literals**. The string form is not a nicety: a missed
+*import* of a deleted module is an immediate ``ImportError``, but a missed *string* is not, and it is
+invisible to every import-graph tool and to pyright's module graph. The two forms that actually
+occurred in this repo are ``importlib.import_module("pipelex.hub")`` (three of them, hiding a cycle
+from every lint) and ``mocker.patch("pipelex.hub.get_console", ...)`` (which broke a whole CLI test
+suite with an ``AttributeError`` raised nowhere near a hub). Matching is exact-or-dotted-prefix
+against the module path — a docstring or comment that merely *mentions* ``pipelex.interpreter_hub`` in
+prose is not a reference and is not flagged. A path assembled at runtime from f-strings or
+concatenation is out of reach of any AST scan; nothing in the tree does that today.
+
+Note that ``runtime_hub`` is unrelated to the ``pipelex.runtime_bridge`` package despite the shared
+word: the hub is the runtime layer's service container, while ``runtime_bridge`` is a transport.
+
+Two deliberate carve-outs:
+
+- **``if TYPE_CHECKING:`` blocks are exempt from the layer rule** (but not from the dead-module rule).
+ The rule is about what *loads*, and a type-only import loads nothing — deferring a type-only need
+ under ``TYPE_CHECKING`` is this repo's sanctioned pattern for it (see the ``pipe_func_executor_registry``
+ note in ``docs/contribute/hub-layering.md``). Only ``TYPE_CHECKING`` and ``typing.TYPE_CHECKING``
+ open such a block — an attribute of anything else is an ordinary runtime condition and earns no
+ exemption. A ``pipelex.hub`` import stays a violation there, since the module does not exist in any
+ phase.
+- An inline ``# hub-layering: ignore`` comment anywhere on the offending statement suppresses it,
+ mirroring the ``# kw-only: ignore`` escape hatch of the sibling keyword-only guard.
+
+The filesystem helpers below are duplicated from ``keyword_only_guard`` on purpose rather than shared:
+that module is also invoked *by file path* under a cold-start budget, so it must not import anything
+from the ``pipelex`` package chain — extracting a shared helper module would defeat it.
+
+This module depends on **stdlib only** — no ``rich``, ``pipelex.runtime_hub``, or ``typer``. The
+presentation layer wired into the ``pipelex-dev`` Typer app lives in ``check_hub_layering_cmd.py``.
+"""
+
+from __future__ import annotations
+
+import ast
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, NamedTuple
+
+from typing_extensions import override
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator, Sequence
+
+# --------------------------------------------------------------------------------------
+# Configuration
+# --------------------------------------------------------------------------------------
+
+#: Source root holding the layered packages (relative to the repo root / cwd).
+SOURCE_ROOT = Path("pipelex")
+
+#: Test root. Scanned for the dead-module rule only — `tests.*` is in no declared layer, so the
+#: layer rule never applies to it and a test may freely patch `pipelex.interpreter_hub`.
+TESTS_ROOT = Path("tests")
+
+#: The roots the full-tree check scans.
+SCAN_ROOTS: tuple[Path, ...] = (SOURCE_ROOT, TESTS_ROOT)
+
+#: The declared runtime layer: packages that must stay importable without loading the method interpreter.
+#:
+#: Entries are matched exact-or-dotted-prefix, so a bare *module* is a legal entry alongside the packages.
+#: `pipelex.runtime_hub` is one: the module at the centre of the rule would otherwise be exempt from it,
+#: since nothing in the tuple is a prefix of it. Its closure *is* what the runtime layer means, so an
+#: `interpreter_hub` import there is the one that would break the property outright.
+#:
+#: `pipelex/core/**` is listed **package by package**, not wholesale, because `core/` is genuinely two
+#: layers. Its data model — concepts, domains, stuffs, working memory, the input/output *specs* — is
+#: runtime: it describes what a method's values are, and nothing in it needs a loaded method. The
+#: remainder names a `Pipe`, and a pipe is the interpreter's own object: `pipe_abstract`,
+#: `pipe_blueprint`, `pipe_factory`, `registry_models`, `bundles/` (a discriminated union over every
+#: pipe blueprint), `interpreter/`, and `pipes/rendering/` all import the interpreter *directly*, so
+#: declaring them runtime would be a claim the measurement contradicts. Those modules resolve their
+#: collaborators from the hub and inject them downward into the runtime half — the one-way arrow the
+#: whole design rests on. See the "Where core splits" section of ``docs/contribute/hub-layering.md``.
+RUNTIME_LAYER_PACKAGES: tuple[str, ...] = (
+ "pipelex.cogt",
+ "pipelex.plugins",
+ "pipelex.reporting",
+ "pipelex.system",
+ "pipelex.tools",
+ # the runtime layer's own hub — a module, not a package; see the note above
+ "pipelex.runtime_hub",
+ # core's data model; the Pipe-touching remainder of `core/` stays in the interpreter layer
+ "pipelex.core.concepts",
+ "pipelex.core.domains",
+ "pipelex.core.memory",
+ "pipelex.core.pipes.inputs",
+ "pipelex.core.pipes.stuff_spec",
+ "pipelex.core.stuffs",
+)
+
+#: The interpreter layer's hub, which no runtime-layer module may import.
+INTERPRETER_HUB_MODULE = "pipelex.interpreter_hub"
+
+#: The single hub that was split and deleted. Every reference to it is dead, in every layer.
+#: The marker below is the escape hatch dogfooding itself: this line *declares* the forbidden path,
+#: so the guard would otherwise flag its own configuration.
+DELETED_HUB_MODULE = "pipelex.hub" # hub-layering: ignore
+
+#: Inline comment that suppresses a single violation on the statement it sits on.
+ESCAPE_HATCH_MARKER = "# hub-layering: ignore"
+
+#: The ``typing.TYPE_CHECKING`` flag name, matched bare (``TYPE_CHECKING``) or attributed (``typing.TYPE_CHECKING``).
+TYPE_CHECKING_NAME = "TYPE_CHECKING"
+
+#: The only receiver the attributed form may be rooted at, so an unrelated ``x.TYPE_CHECKING`` earns no exemption.
+TYPING_MODULE_NAME = "typing"
+
+
+class HubLayeringViolationKind(StrEnum):
+ """The distinct hub-layering violation kinds — each names its own remedy."""
+
+ INTERPRETER_HUB_IMPORT = "interpreter-hub-import"
+ INTERPRETER_HUB_REFERENCE = "interpreter-hub-reference"
+ DEAD_HUB_REFERENCE = "dead-hub-reference"
+
+ @property
+ def remedy(self) -> str:
+ """One actionable sentence naming how to fix this violation kind."""
+ match self:
+ case HubLayeringViolationKind.INTERPRETER_HUB_IMPORT:
+ return (
+ "a runtime-layer module may not import `pipelex.interpreter_hub` — take the value as an argument, "
+ "or have the interpreter layer install it downward at boot (the `class_registry_scoping` pattern)"
+ )
+ case HubLayeringViolationKind.INTERPRETER_HUB_REFERENCE:
+ return (
+ "a runtime-layer module may not name `pipelex.interpreter_hub` in a string either — a dynamic "
+ "import or patch target is the same dependency, just invisible to the import graph"
+ )
+ case HubLayeringViolationKind.DEAD_HUB_REFERENCE:
+ return f"`{DELETED_HUB_MODULE}` no longer exists — point at `pipelex.runtime_hub` or `pipelex.interpreter_hub`"
+
+
+class HubLayeringViolation(NamedTuple):
+ """One offending import or string literal, located for a report line."""
+
+ relative_path: str
+ lineno: int
+ kind: HubLayeringViolationKind
+ detail: str
+
+ @property
+ def key(self) -> str:
+ """Stable sort key: file, then line, then kind."""
+ return f"{self.relative_path}:{self.lineno:06d}:{self.kind}"
+
+
+# --------------------------------------------------------------------------------------
+# Layer membership and module matching
+# --------------------------------------------------------------------------------------
+
+
+def references_module(*, candidate: str, target: str) -> bool:
+ """Whether a dotted candidate names ``target`` or something inside it.
+
+ Exact-or-boundary matching, so ``pipelex.runtime_hub`` never matches ``pipelex.hub`` and a prose
+ sentence mentioning a module is never a reference. The ``:`` form covers ``module:attr`` paths.
+ """
+ return candidate == target or candidate.startswith((f"{target}.", f"{target}:"))
+
+
+def is_runtime_layer(*, module_qname: str) -> bool:
+ """Whether a module sits in the declared runtime layer.
+
+ Matching is exact-or-dotted-prefix, so despite its name :data:`RUNTIME_LAYER_PACKAGES` may hold a
+ bare module as well as a package — an entry covers itself and everything under it.
+ """
+ return any(module_qname == package or module_qname.startswith(f"{package}.") for package in RUNTIME_LAYER_PACKAGES)
+
+
+def targets_for(*, module_qname: str) -> frozenset[str]:
+ """The forbidden module paths for one module: the dead hub always, plus the interpreter hub in the runtime layer."""
+ if is_runtime_layer(module_qname=module_qname):
+ return frozenset({DELETED_HUB_MODULE, INTERPRETER_HUB_MODULE})
+ return frozenset({DELETED_HUB_MODULE})
+
+
+def _is_type_checking_test(*, test: ast.expr) -> bool:
+ """Whether an ``if`` test is the bare ``TYPE_CHECKING`` / ``typing.TYPE_CHECKING`` flag.
+
+ Only the bare forms count: ``if not TYPE_CHECKING:`` guards a *runtime* branch and is not exempt.
+ The attributed form must be rooted at ``typing`` itself — matching the attribute name alone would
+ hand the layer-rule exemption to any ``some_object.TYPE_CHECKING:`` block, which is a runtime
+ condition like any other.
+ """
+ match test:
+ case ast.Name(id=name):
+ return name == TYPE_CHECKING_NAME
+ case ast.Attribute(value=ast.Name(id=receiver), attr=attr):
+ return receiver == TYPING_MODULE_NAME and attr == TYPE_CHECKING_NAME
+ case _:
+ return False
+
+
+# --------------------------------------------------------------------------------------
+# AST collection
+# --------------------------------------------------------------------------------------
+
+
+class _Collector(ast.NodeVisitor):
+ """Walks one module, recording every forbidden import or string reference."""
+
+ def __init__(self, *, relative_path: str, package_qname: str, targets: frozenset[str], source_lines: list[str]) -> None:
+ self.relative_path = relative_path
+ self.package_qname = package_qname
+ self.targets = targets
+ self.source_lines = source_lines
+ self.violations: list[HubLayeringViolation] = []
+ self._type_checking_depth = 0
+
+ def _active_targets(self) -> frozenset[str]:
+ """The targets in force here: inside a ``TYPE_CHECKING`` block the layer rule is lifted, the dead-module rule is not."""
+ if self._type_checking_depth > 0:
+ return self.targets - {INTERPRETER_HUB_MODULE}
+ return self.targets
+
+ def _is_suppressed(self, *, lineno: int, end_lineno: int | None) -> bool:
+ """Whether the escape-hatch marker sits anywhere on the offending statement's lines."""
+ for line_number in range(lineno, (end_lineno or lineno) + 1):
+ index = line_number - 1
+ if 0 <= index < len(self.source_lines) and ESCAPE_HATCH_MARKER in self.source_lines[index]:
+ return True
+ return False
+
+ def _matched_target(self, *, candidate: str) -> str | None:
+ """The forbidden target this candidate names, if any."""
+ for target in sorted(self._active_targets()):
+ if references_module(candidate=candidate, target=target):
+ return target
+ return None
+
+ def _record(self, *, node: ast.AST, target: str, detail: str, import_kind: HubLayeringViolationKind) -> None:
+ """Append one violation, unless the statement carries the escape hatch."""
+ lineno = getattr(node, "lineno", 0)
+ if self._is_suppressed(lineno=lineno, end_lineno=getattr(node, "end_lineno", None)):
+ return
+ kind = HubLayeringViolationKind.DEAD_HUB_REFERENCE if target == DELETED_HUB_MODULE else import_kind
+ self.violations.append(HubLayeringViolation(relative_path=self.relative_path, lineno=lineno, kind=kind, detail=detail))
+
+ def _absolute_module_for(self, *, node: ast.ImportFrom) -> str | None:
+ """Resolve an ``ImportFrom``'s module to an absolute dotted path, walking up for relative levels."""
+ if node.level == 0:
+ return node.module
+ parts = self.package_qname.split(".") if self.package_qname else []
+ climb = node.level - 1
+ if climb > len(parts):
+ return None
+ base_parts = parts[: len(parts) - climb]
+ if node.module:
+ base_parts = [*base_parts, *node.module.split(".")]
+ return ".".join(base_parts) or None
+
+ @override
+ def visit_Import(self, node: ast.Import) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name
+ """``import pipelex.interpreter_hub`` / ``import pipelex.interpreter_hub as hub``."""
+ for alias in node.names:
+ target = self._matched_target(candidate=alias.name)
+ if target is not None:
+ self._record(node=node, target=target, detail=f"imports `{alias.name}`", import_kind=HubLayeringViolationKind.INTERPRETER_HUB_IMPORT)
+ return
+
+ @override
+ def visit_ImportFrom(self, node: ast.ImportFrom) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name
+ """``from pipelex.interpreter_hub import x``, ``from pipelex import interpreter_hub``, and the relative forms."""
+ base = self._absolute_module_for(node=node)
+ if base is None:
+ return
+ for candidate in [base, *(f"{base}.{alias.name}" for alias in node.names)]:
+ target = self._matched_target(candidate=candidate)
+ if target is not None:
+ self._record(node=node, target=target, detail=f"imports `{candidate}`", import_kind=HubLayeringViolationKind.INTERPRETER_HUB_IMPORT)
+ return
+
+ @override
+ def visit_If(self, node: ast.If) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name
+ """Track ``if TYPE_CHECKING:`` depth so its body is exempt from the layer rule."""
+ if not _is_type_checking_test(test=node.test):
+ self.generic_visit(node)
+ return
+ self._type_checking_depth += 1
+ for statement in node.body:
+ self.visit(statement)
+ self._type_checking_depth -= 1
+ for statement in node.orelse:
+ self.visit(statement)
+
+ @override
+ def visit_Constant(self, node: ast.Constant) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name
+ """A bare string naming a forbidden module — an ``import_module`` argument, a ``mocker.patch`` target, a config value."""
+ value = node.value
+ if not isinstance(value, str):
+ return
+ target = self._matched_target(candidate=value)
+ if target is not None:
+ self._record(node=node, target=target, detail=f'string literal "{value}"', import_kind=HubLayeringViolationKind.INTERPRETER_HUB_REFERENCE)
+
+
+# --------------------------------------------------------------------------------------
+# Entry points
+# --------------------------------------------------------------------------------------
+
+
+def module_qname_for(*, path: Path) -> str:
+ """The dotted module name for a ``.py`` file, relative to the repo root."""
+ parts = list(path.with_suffix("").parts)
+ if parts and parts[-1] == "__init__":
+ parts = parts[:-1]
+ return ".".join(parts)
+
+
+def iter_source_files(*, root: Path) -> Iterator[Path]:
+ """Yield every ``.py`` file under ``root``, excluding ``__pycache__``."""
+ for path in sorted(root.rglob("*.py")):
+ if "__pycache__" in path.parts:
+ continue
+ yield path
+
+
+def find_violations_in_source(*, source: str, relative_path: str) -> list[HubLayeringViolation]:
+ """Scan one module's source and return its violations.
+
+ Args:
+ source: The module's full source text.
+ relative_path: Its repo-root-relative posix path — it decides both which layer the module is
+ in and how its relative imports resolve, so it must be the real path, not a label.
+
+ Raises:
+ SyntaxError: If the source does not parse. Never swallowed: an unparseable module in the
+ scanned tree is a real problem, and silently skipping it would create a blind spot.
+ """
+ path = Path(relative_path)
+ collector = _Collector(
+ relative_path=relative_path,
+ package_qname=".".join(path.parent.parts),
+ targets=targets_for(module_qname=module_qname_for(path=path)),
+ source_lines=source.splitlines(),
+ )
+ collector.visit(ast.parse(source))
+ return sorted(collector.violations, key=lambda violation: violation.key)
+
+
+def collect_all_violations(*, roots: Sequence[Path]) -> list[HubLayeringViolation]:
+ """Scan every ``.py`` file under each root and return all violations, sorted by location."""
+ violations: list[HubLayeringViolation] = []
+ for root in roots:
+ for path in iter_source_files(root=root):
+ violations.extend(find_violations_in_source(source=path.read_text(encoding="utf-8"), relative_path=path.as_posix()))
+ return sorted(violations, key=lambda violation: violation.key)
diff --git a/pipelex/cli/dev_cli/commands/keyword_only_guard.py b/pipelex/cli/dev_cli/commands/keyword_only_guard.py
index c998cfc32..c1d6ae57b 100644
--- a/pipelex/cli/dev_cli/commands/keyword_only_guard.py
+++ b/pipelex/cli/dev_cli/commands/keyword_only_guard.py
@@ -5,11 +5,11 @@ Non-subject function parameters must be keyword-only so call sites are self-docu
human-readable specification lives in ``docs/contribute/keyword-only-arguments.md``.
This module holds the AST collection logic that mechanically enforces the convention. It depends
-on **stdlib only** (``ast``/``re``/``pathlib``) — no ``rich``, ``pipelex.hub``, or ``typer`` — so it
+on **stdlib only** (``ast``/``re``/``pathlib``) — no ``rich``, ``pipelex.runtime_hub``, or ``typer`` — so it
can be loaded in two cold-start budgets:
- The full-tree command (``pipelex-dev check-keyword-only``) imports from here and adds the
- ``rich``/``pipelex.hub`` presentation layer (see ``check_keyword_only_cmd.py``).
+ ``rich``/``pipelex.runtime_hub`` presentation layer (see ``check_keyword_only_cmd.py``).
- The lean single-file entry below, invoked **by file path** (``python
pipelex/cli/dev_cli/commands/keyword_only_guard.py <file>``), skips the whole Typer/hub import
graph so a ``PostToolUse`` hook can check just the edited file in a few tens of milliseconds. Run
diff --git a/pipelex/cli/dev_cli/commands/kit_cmd.py b/pipelex/cli/dev_cli/commands/kit_cmd.py
index 1ae5f9b5d..ddab08970 100644
--- a/pipelex/cli/dev_cli/commands/kit_cmd.py
+++ b/pipelex/cli/dev_cli/commands/kit_cmd.py
@@ -11,12 +11,12 @@ from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.error_handlers import ErrorContext
from pipelex.cli.exceptions import PipelexCLIError
from pipelex.config import get_config
-from pipelex.hub import get_telemetry_manager
from pipelex.kit.cursor_rules import remove_cursor_rules, update_cursor_rules
from pipelex.kit.index_loader import load_index
from pipelex.kit.index_models import KitIndex, Target
from pipelex.kit.single_file_agent_rules import remove_from_targets, update_single_file_agent_rules
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.configuration.configs import AgentTarget
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
diff --git a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py
index 3012348b2..7f2a4a05b 100644
--- a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py
@@ -13,7 +13,7 @@ from rich.markup import escape
from rich.panel import Panel
from rich.table import Table
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.configuration.configs import ConfigPaths
from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError, RemoteConfigValidationError
diff --git a/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py b/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
index de2c70cec..99dede58b 100644
--- a/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
+++ b/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
@@ -17,7 +17,7 @@ from urllib.request import urlopen
from pipelex.cli.exceptions import PipelexCLIError
from pipelex.graph.reactflow import standalone_assets as current_pins
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
_DEFAULT_OUTPUT_PATH = Path(current_pins.__file__)
diff --git a/pipelex/cli/dev_cli/commands/subject_grant_cmd.py b/pipelex/cli/dev_cli/commands/subject_grant_cmd.py
index f267db7fe..dc037aa99 100644
--- a/pipelex/cli/dev_cli/commands/subject_grant_cmd.py
+++ b/pipelex/cli/dev_cli/commands/subject_grant_cmd.py
@@ -28,7 +28,7 @@ from pipelex.cli.dev_cli.commands.keyword_only_guard import (
load_subject_grants,
module_qname_for,
)
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.tools.misc.toml_utils import save_toml_to_path
diff --git a/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py b/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
index 9f7fee80f..8fdd2783b 100644
--- a/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
+++ b/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
@@ -9,8 +9,8 @@ from rich.markup import escape
from rich.panel import Panel
from rich.table import Table
-from pipelex.hub import get_console
from pipelex.kit.paths import CONFIG_SYNC_EXCLUDED_FILES, GIT_IGNORED_CONFIG_DIRS
+from pipelex.runtime_hub import get_console
from pipelex.tools.misc.file_utils import MirrorDirResult, mirror_dir
PIPELEX_DIR = ".pipelex"
diff --git a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
index 75ab95c46..8f41af372 100644
--- a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
+++ b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
@@ -10,7 +10,7 @@ from rich.markup import escape
from rich.panel import Panel
from rich.table import Table
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.tools.misc.toml_sync import TomlSyncResult, sync_toml_values
# Config file paths
diff --git a/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py b/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
index 2ae835803..922e13bf1 100644
--- a/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
@@ -14,7 +14,7 @@ from pipelex.cli.dev_cli.commands.gateway_models_generator import (
generate_reference_pure_markdown,
normalize_for_comparison,
)
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError, RemoteConfigValidationError
# The reference files live in two places that must stay identical: the repo's
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index 9b69c4de9..ec4005ac9 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -12,10 +12,10 @@ from rich.traceback import Traceback
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
from pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetValidatonError
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
-from pipelex.hub import get_console
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes
+from pipelex.runtime_hub import get_console
from pipelex.system.pipelex_service.exceptions import (
GatewayApiKeyMissingError,
GatewayDoNotTrackConflictError,
diff --git a/pipelex/cli/readiness.py b/pipelex/cli/readiness.py
index 16393528f..6d185324e 100644
--- a/pipelex/cli/readiness.py
+++ b/pipelex/cli/readiness.py
@@ -10,7 +10,7 @@ from rich.markup import escape
import pipelex
from pipelex.cli.exceptions import ReadinessCheckError
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
def _is_in_virtual_environment() -> bool:
diff --git a/pipelex/codegen/emitters/python_common.py b/pipelex/codegen/emitters/python_common.py
index 1a0acd8f4..46b3a322f 100644
--- a/pipelex/codegen/emitters/python_common.py
+++ b/pipelex/codegen/emitters/python_common.py
@@ -11,7 +11,7 @@ from datetime import date, datetime, time
from typing import Any, cast
from pipelex.codegen.resolved_concepts import ResolvedConcept
-from pipelex.codegen.resolved_fields import ResolvedField, iter_imprecision_reasons
+from pipelex.core.concepts.resolved_fields import ResolvedField, iter_imprecision_reasons
def python_header(*, target: str) -> str:
diff --git a/pipelex/codegen/emitters/python_pydantic.py b/pipelex/codegen/emitters/python_pydantic.py
index fb871d9f9..a9221aa36 100644
--- a/pipelex/codegen/emitters/python_pydantic.py
+++ b/pipelex/codegen/emitters/python_pydantic.py
@@ -13,7 +13,7 @@ from pipelex.codegen.emitters.naming import python_class_name
from pipelex.codegen.emitters.python_common import any_annotation, class_docstring, field_line, order_by_base, python_header
from pipelex.codegen.emitters.target import EmittedFile
from pipelex.codegen.resolved_concepts import ResolvedConcept, ResolvedLibrary
-from pipelex.codegen.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind
+from pipelex.core.concepts.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind
_FILENAME = "models.py"
diff --git a/pipelex/codegen/emitters/python_structures.py b/pipelex/codegen/emitters/python_structures.py
index 7a1572668..b7bad2b94 100644
--- a/pipelex/codegen/emitters/python_structures.py
+++ b/pipelex/codegen/emitters/python_structures.py
@@ -14,8 +14,8 @@ from pipelex.codegen.emitters.naming import python_class_name
from pipelex.codegen.emitters.python_common import any_annotation, class_docstring, field_line, order_by_base, python_header
from pipelex.codegen.emitters.target import EmittedFile
from pipelex.codegen.resolved_concepts import ResolvedConcept, ResolvedLibrary
-from pipelex.codegen.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind
from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind
from pipelex.core.qualified_ref import QualifiedRef
_FILENAME = "structures.py"
diff --git a/pipelex/codegen/emitters/ts_zod.py b/pipelex/codegen/emitters/ts_zod.py
index 9a0a37a54..0acebc842 100644
--- a/pipelex/codegen/emitters/ts_zod.py
+++ b/pipelex/codegen/emitters/ts_zod.py
@@ -25,7 +25,7 @@ from typing import Any
from pipelex.codegen.emitters.naming import allocate_ts_type_names
from pipelex.codegen.emitters.target import EmittedFile
from pipelex.codegen.resolved_concepts import ResolvedConcept, ResolvedLibrary
-from pipelex.codegen.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind, iter_imprecision_reasons
+from pipelex.core.concepts.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind, iter_imprecision_reasons
from pipelex.tools.misc.json_utils import clean_json_content
_FILENAME = "types.ts"
diff --git a/pipelex/codegen/resolved_concepts.py b/pipelex/codegen/resolved_concepts.py
index a9da926fa..f9579c6d9 100644
--- a/pipelex/codegen/resolved_concepts.py
+++ b/pipelex/codegen/resolved_concepts.py
@@ -14,10 +14,10 @@ from collections import Counter
from pydantic import BaseModel, ConfigDict
-from pipelex.codegen.resolved_fields import ResolvedField, resolve_structure_fields
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.concepts.helpers import normalize_structure_blueprint
from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.resolved_fields import ResolvedField, resolve_structure_fields
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/pipelex/cogt/content_generation/assignment_models.py b/pipelex/cogt/content_generation/assignment_models.py
index dc8c79ea6..899d1c201 100644
--- a/pipelex/cogt/content_generation/assignment_models.py
+++ b/pipelex/cogt/content_generation/assignment_models.py
@@ -12,9 +12,9 @@ from pipelex.cogt.llm.llm_job_components import LLMJobParams
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.cogt.search.search_setting import SearchSetting
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TemplatingStyle
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TemplatingStyle
class LLMAssignment(BaseModel):
diff --git a/pipelex/cogt/content_generation/content_generator.py b/pipelex/cogt/content_generation/content_generator.py
index 86f6817da..428fd5495 100644
--- a/pipelex/cogt/content_generation/content_generator.py
+++ b/pipelex/cogt/content_generation/content_generator.py
@@ -30,14 +30,14 @@ from pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobConfig, ImgGenJ
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.config import get_config
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.search_result_content import SearchResultContent
-from pipelex.hub import get_storage_provider
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_storage_provider
+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.pydantic_utils import BaseModelTypeVar
diff --git a/pipelex/cogt/content_generation/content_generator_protocol.py b/pipelex/cogt/content_generation/content_generator_protocol.py
index 15b6edc9a..7135e82bd 100644
--- a/pipelex/cogt/content_generation/content_generator_protocol.py
+++ b/pipelex/cogt/content_generation/content_generator_protocol.py
@@ -10,12 +10,12 @@ from pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobConfig, ImgGenJ
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.search_result_content import SearchResultContent
-from pipelex.pipeline.job_metadata import JobMetadata
+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.pydantic_utils import BaseModelTypeVar
F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
diff --git a/pipelex/cogt/content_generation/dry_mock.py b/pipelex/cogt/content_generation/dry_mock.py
index 1f664b070..a5e2a0668 100644
--- a/pipelex/cogt/content_generation/dry_mock.py
+++ b/pipelex/cogt/content_generation/dry_mock.py
@@ -66,8 +66,8 @@ from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.search_result_content import SearchResultContent
from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_report_delegate
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_report_delegate
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsing
from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
diff --git a/pipelex/cogt/content_generation/extract_generate.py b/pipelex/cogt/content_generation/extract_generate.py
index f40f6b8aa..a6b974ab0 100644
--- a/pipelex/cogt/content_generation/extract_generate.py
+++ b/pipelex/cogt/content_generation/extract_generate.py
@@ -4,7 +4,7 @@ from pipelex.cogt.content_generation.generated_content_factory import GeneratedC
from pipelex.cogt.extract.extract_job_factory import ExtractJobFactory
from pipelex.cogt.extract.extract_output import ExtractOutput
from pipelex.core.stuffs.page_content import PageContent
-from pipelex.hub import get_extract_worker
+from pipelex.runtime_hub import get_extract_worker
async def extract_gen_pages(extract_assignment: ExtractAssignment) -> ExtractOutput:
diff --git a/pipelex/cogt/content_generation/img_gen_generate.py b/pipelex/cogt/content_generation/img_gen_generate.py
index 0d817e7a8..052cd848b 100644
--- a/pipelex/cogt/content_generation/img_gen_generate.py
+++ b/pipelex/cogt/content_generation/img_gen_generate.py
@@ -5,7 +5,7 @@ from pipelex.cogt.content_generation.generated_content_factory import GeneratedC
from pipelex.cogt.image.generated_image import GeneratedImageRawDetails
from pipelex.cogt.img_gen.img_gen_job_factory import ImgGenJobFactory
from pipelex.core.stuffs.image_content import ImageContent
-from pipelex.hub import get_img_gen_worker
+from pipelex.runtime_hub import get_img_gen_worker
async def img_gen_single_image(img_gen_assignment: ImgGenAssignment) -> GeneratedImageRawDetails:
diff --git a/pipelex/cogt/content_generation/llm_generate.py b/pipelex/cogt/content_generation/llm_generate.py
index a160b44e9..6619df46a 100644
--- a/pipelex/cogt/content_generation/llm_generate.py
+++ b/pipelex/cogt/content_generation/llm_generate.py
@@ -12,7 +12,7 @@ from pipelex.cogt.content_generation.dry_mock import (
from pipelex.cogt.content_generation.schema_to_model_factory import SchemaToModelFactory
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_utils import dump_prompt, dump_response_from_text_gen
-from pipelex.hub import get_llm_worker
+from pipelex.runtime_hub import get_llm_worker
async def llm_gen_text(llm_assignment: LLMAssignment) -> str:
diff --git a/pipelex/cogt/content_generation/search_generate.py b/pipelex/cogt/content_generation/search_generate.py
index 5756d8c0c..17b211f25 100644
--- a/pipelex/cogt/content_generation/search_generate.py
+++ b/pipelex/cogt/content_generation/search_generate.py
@@ -19,7 +19,7 @@ from pipelex.cogt.search.search_job_factory import SearchJobFactory
from pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstract
from pipelex.cogt.search.search_worker_factory import SearchWorkerFactory
from pipelex.core.stuffs.search_result_content import SearchResultContent
-from pipelex.hub import get_model_deck, get_report_delegate
+from pipelex.runtime_hub import get_model_deck, get_report_delegate
def _make_search_worker(search_assignment: SearchAssignment) -> SearchWorkerAbstract:
diff --git a/pipelex/cogt/document/prompt_document_utils.py b/pipelex/cogt/document/prompt_document_utils.py
index 0e06f0ed1..cc1b476be 100644
--- a/pipelex/cogt/document/prompt_document_utils.py
+++ b/pipelex/cogt/document/prompt_document_utils.py
@@ -14,7 +14,7 @@ from pipelex.cogt.document.prompt_document import (
PromptDocumentBinary,
PromptDocumentUri,
)
-from pipelex.hub import get_storage_provider
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx
from pipelex.tools.misc.file_utils import load_binary_async
from pipelex.tools.misc.filetype_utils import detect_file_type_from_base64, detect_file_type_from_bytes
diff --git a/pipelex/cogt/extract/extract_job_factory.py b/pipelex/cogt/extract/extract_job_factory.py
index 8f70b094a..0ee55d977 100644
--- a/pipelex/cogt/extract/extract_job_factory.py
+++ b/pipelex/cogt/extract/extract_job_factory.py
@@ -1,7 +1,7 @@
from pipelex.cogt.extract.extract_input import ExtractInput
from pipelex.cogt.extract.extract_job import ExtractJob
from pipelex.cogt.extract.extract_job_components import ExtractJobConfig, ExtractJobParams, ExtractJobReport
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class ExtractJobFactory:
diff --git a/pipelex/cogt/extract/extract_report.py b/pipelex/cogt/extract/extract_report.py
index 4da8330da..2466aa8ab 100644
--- a/pipelex/cogt/extract/extract_report.py
+++ b/pipelex/cogt/extract/extract_report.py
@@ -5,7 +5,7 @@ from pydantic import BaseModel
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class ExtractTokenCostReportField(StrEnum):
diff --git a/pipelex/cogt/extract/extract_worker_abstract.py b/pipelex/cogt/extract/extract_worker_abstract.py
index 82461a38f..3df1c983e 100644
--- a/pipelex/cogt/extract/extract_worker_abstract.py
+++ b/pipelex/cogt/extract/extract_worker_abstract.py
@@ -10,8 +10,8 @@ from pipelex.cogt.extract.extract_output import ExtractOutput
from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import UnitJobId
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.system.job_metadata import UnitJobId
class ExtractWorkerAbstract(InferenceWorkerAbstract):
diff --git a/pipelex/cogt/extract/extract_worker_factory.py b/pipelex/cogt/extract/extract_worker_factory.py
index 7bfb022c9..864f54166 100644
--- a/pipelex/cogt/extract/extract_worker_factory.py
+++ b/pipelex/cogt/extract/extract_worker_factory.py
@@ -2,10 +2,10 @@ from typing import cast
from pipelex.cogt.extract.extract_worker_abstract import ExtractWorkerAbstract
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
-from pipelex.hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
from pipelex.plugins.inference_backend_registry import InferenceFamily
from pipelex.plugins.model_handle import ModelHandle
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
class ExtractWorkerFactory:
diff --git a/pipelex/cogt/file/file_preparation_utils.py b/pipelex/cogt/file/file_preparation_utils.py
index 2da6aa28b..d8ac6dfd5 100644
--- a/pipelex/cogt/file/file_preparation_utils.py
+++ b/pipelex/cogt/file/file_preparation_utils.py
@@ -7,7 +7,7 @@ instances that can be consumed by various APIs.
import base64
from pathlib import Path
-from pipelex.hub import get_storage_provider
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx
from pipelex.tools.misc.file_utils import load_binary_async
from pipelex.tools.misc.filetype_utils import detect_file_type_from_base64, detect_file_type_from_bytes
diff --git a/pipelex/cogt/image/prompt_image_utils.py b/pipelex/cogt/image/prompt_image_utils.py
index 253607297..45753f7a6 100644
--- a/pipelex/cogt/image/prompt_image_utils.py
+++ b/pipelex/cogt/image/prompt_image_utils.py
@@ -14,7 +14,7 @@ from pipelex.cogt.image.prompt_image import (
PromptImageBinary,
PromptImageUri,
)
-from pipelex.hub import get_storage_provider
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx
from pipelex.tools.misc.file_utils import load_binary_async
from pipelex.tools.misc.filetype_utils import detect_file_type_from_base64, detect_file_type_from_bytes
diff --git a/pipelex/cogt/img_gen/img_gen_job_factory.py b/pipelex/cogt/img_gen/img_gen_job_factory.py
index e71671b40..86bc0ffc9 100644
--- a/pipelex/cogt/img_gen/img_gen_job_factory.py
+++ b/pipelex/cogt/img_gen/img_gen_job_factory.py
@@ -2,7 +2,7 @@ from pipelex.cogt.img_gen.img_gen_job import ImgGenJob
from pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobConfig, ImgGenJobParams, ImgGenJobReport
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.config import get_config
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class ImgGenJobFactory:
diff --git a/pipelex/cogt/img_gen/img_gen_report.py b/pipelex/cogt/img_gen/img_gen_report.py
index 19867c598..65b424f83 100644
--- a/pipelex/cogt/img_gen/img_gen_report.py
+++ b/pipelex/cogt/img_gen/img_gen_report.py
@@ -5,7 +5,7 @@ from pydantic import BaseModel
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class ImgGenTokenCostReportField(StrEnum):
diff --git a/pipelex/cogt/img_gen/img_gen_worker_abstract.py b/pipelex/cogt/img_gen/img_gen_worker_abstract.py
index 08b557e59..fb36966fd 100644
--- a/pipelex/cogt/img_gen/img_gen_worker_abstract.py
+++ b/pipelex/cogt/img_gen/img_gen_worker_abstract.py
@@ -8,8 +8,8 @@ from pipelex.cogt.image.generated_image import GeneratedImageRawDetails
from pipelex.cogt.img_gen.img_gen_job import ImgGenJob
from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
-from pipelex.pipeline.job_metadata import UnitJobId
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.system.job_metadata import UnitJobId
class ImgGenWorkerAbstract(InferenceWorkerAbstract):
diff --git a/pipelex/cogt/img_gen/img_gen_worker_factory.py b/pipelex/cogt/img_gen/img_gen_worker_factory.py
index 72e2c877f..0b53beeaa 100644
--- a/pipelex/cogt/img_gen/img_gen_worker_factory.py
+++ b/pipelex/cogt/img_gen/img_gen_worker_factory.py
@@ -2,10 +2,10 @@ from typing import cast
from pipelex.cogt.img_gen.img_gen_worker_abstract import ImgGenWorkerAbstract
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
-from pipelex.hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
from pipelex.plugins.inference_backend_registry import InferenceFamily
from pipelex.plugins.model_handle import ModelHandle
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
class ImgGenWorkerFactory:
diff --git a/pipelex/cogt/inference/inference_job_abstract.py b/pipelex/cogt/inference/inference_job_abstract.py
index da5dd2b2f..b8044323e 100644
--- a/pipelex/cogt/inference/inference_job_abstract.py
+++ b/pipelex/cogt/inference/inference_job_abstract.py
@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
from pydantic import BaseModel
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class InferenceJobAbstract(ABC, BaseModel):
diff --git a/pipelex/cogt/inference/inference_manager.py b/pipelex/cogt/inference/inference_manager.py
index df04a1985..2a0a37e02 100644
--- a/pipelex/cogt/inference/inference_manager.py
+++ b/pipelex/cogt/inference/inference_manager.py
@@ -9,7 +9,7 @@ from pipelex.cogt.inference.inference_manager_protocol import InferenceManagerPr
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
from pipelex.cogt.llm.llm_worker_factory import LLMWorkerFactory
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.hub import get_models_manager, get_report_delegate
+from pipelex.runtime_hub import get_models_manager, get_report_delegate
class InferenceManager(InferenceManagerProtocol):
diff --git a/pipelex/cogt/llm/llm_job_factory.py b/pipelex/cogt/llm/llm_job_factory.py
index bdb04cae9..7265e9599 100644
--- a/pipelex/cogt/llm/llm_job_factory.py
+++ b/pipelex/cogt/llm/llm_job_factory.py
@@ -2,7 +2,7 @@ from pipelex.cogt.llm.llm_job import LLMJob
from pipelex.cogt.llm.llm_job_components import LLMJobConfig, LLMJobParams
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.config import get_config
-from pipelex.pipeline.job_metadata import JobCategory, JobMetadata
+from pipelex.system.job_metadata import JobCategory, JobMetadata
class LLMJobFactory:
diff --git a/pipelex/cogt/llm/llm_prompt_template.py b/pipelex/cogt/llm/llm_prompt_template.py
index a441a9b28..b5ab1b43a 100644
--- a/pipelex/cogt/llm/llm_prompt_template.py
+++ b/pipelex/cogt/llm/llm_prompt_template.py
@@ -8,11 +8,11 @@ from pipelex.cogt.image.prompt_image import PromptImage
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_prompt_factory_abstract import LLMPromptFactoryAbstract
from pipelex.cogt.llm.llm_prompt_template_inputs import LLMPromptTemplateInputs
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_rendering import render_template
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import is_none_or_has_text
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
def make_empty_prompt() -> LLMPrompt:
diff --git a/pipelex/cogt/llm/llm_report.py b/pipelex/cogt/llm/llm_report.py
index 5db86cd70..35fa503be 100644
--- a/pipelex/cogt/llm/llm_report.py
+++ b/pipelex/cogt/llm/llm_report.py
@@ -5,7 +5,7 @@ from pydantic import BaseModel
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class LLMTokenCostReportField(StrEnum):
diff --git a/pipelex/cogt/llm/llm_worker_abstract.py b/pipelex/cogt/llm/llm_worker_abstract.py
index ef235658c..f9e79425f 100644
--- a/pipelex/cogt/llm/llm_worker_abstract.py
+++ b/pipelex/cogt/llm/llm_worker_abstract.py
@@ -14,8 +14,8 @@ from pipelex.cogt.inference.inference_constants import InferenceOutputType
from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract
from pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraint
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.pipeline.exceptions import JobMetadataError
-from pipelex.pipeline.job_metadata import UnitJobId
+from pipelex.system.exceptions import JobMetadataError
+from pipelex.system.job_metadata import UnitJobId
from pipelex.system.telemetry.otel_constants import (
GenAISpanAttr,
LangfuseSpanAttr,
diff --git a/pipelex/cogt/llm/llm_worker_factory.py b/pipelex/cogt/llm/llm_worker_factory.py
index 2a4754619..9019b6fb8 100644
--- a/pipelex/cogt/llm/llm_worker_factory.py
+++ b/pipelex/cogt/llm/llm_worker_factory.py
@@ -2,10 +2,10 @@ from typing import cast
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
-from pipelex.hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
from pipelex.plugins.inference_backend_registry import InferenceFamily
from pipelex.plugins.model_handle import ModelHandle
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
class LLMWorkerFactory:
diff --git a/pipelex/cogt/model_backends/model_lists.py b/pipelex/cogt/model_backends/model_lists.py
index f1c759561..39b19a4c8 100644
--- a/pipelex/cogt/model_backends/model_lists.py
+++ b/pipelex/cogt/model_backends/model_lists.py
@@ -4,7 +4,7 @@ from rich.markup import escape
from pipelex.cli.exceptions import PipelexCLIError
from pipelex.cogt.exceptions import ModelListingUnsupportedError, ModelManagerError
-from pipelex.hub import get_console, get_model_lister_registry, get_models_manager
+from pipelex.runtime_hub import get_console, get_model_lister_registry, get_models_manager
class ModelLister:
diff --git a/pipelex/cogt/models/model_deck_check.py b/pipelex/cogt/models/model_deck_check.py
index 8ff023488..57589d58b 100644
--- a/pipelex/cogt/models/model_deck_check.py
+++ b/pipelex/cogt/models/model_deck_check.py
@@ -11,7 +11,7 @@ from pipelex.cogt.models.model_deck import ModelDeck
from pipelex.cogt.models.model_reference import ModelReferenceKind, ensure_model_reference
from pipelex.cogt.models.model_suggestion import suggest_model_alternatives
from pipelex.cogt.search.search_setting import SearchModelChoice, SearchSetting
-from pipelex.hub import get_model_deck
+from pipelex.runtime_hub import get_model_deck
def _raise_model_choice_not_found(
diff --git a/pipelex/cogt/search/search_job_factory.py b/pipelex/cogt/search/search_job_factory.py
index 35290e97e..e4da68d96 100644
--- a/pipelex/cogt/search/search_job_factory.py
+++ b/pipelex/cogt/search/search_job_factory.py
@@ -1,6 +1,6 @@
from pipelex.cogt.search.search_job import SearchJob, SearchJobParams
from pipelex.cogt.search.search_setting import SearchSetting
-from pipelex.pipeline.job_metadata import JobCategory, JobMetadata
+from pipelex.system.job_metadata import JobCategory, JobMetadata
class SearchJobFactory:
diff --git a/pipelex/cogt/search/search_report.py b/pipelex/cogt/search/search_report.py
index 2f9ea3cfd..bc167002d 100644
--- a/pipelex/cogt/search/search_report.py
+++ b/pipelex/cogt/search/search_report.py
@@ -5,7 +5,7 @@ from pydantic import BaseModel
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class SearchTokenCostReportField(StrEnum):
diff --git a/pipelex/cogt/search/search_worker_abstract.py b/pipelex/cogt/search/search_worker_abstract.py
index 6928518aa..08c903a56 100644
--- a/pipelex/cogt/search/search_worker_abstract.py
+++ b/pipelex/cogt/search/search_worker_abstract.py
@@ -9,8 +9,8 @@ from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbst
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.search.search_job import SearchJob
from pipelex.core.stuffs.search_result_content import SearchResultContent
-from pipelex.pipeline.job_metadata import UnitJobId
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.system.job_metadata import UnitJobId
from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
diff --git a/pipelex/cogt/search/search_worker_factory.py b/pipelex/cogt/search/search_worker_factory.py
index 88e0ad2d2..ef671ccdc 100644
--- a/pipelex/cogt/search/search_worker_factory.py
+++ b/pipelex/cogt/search/search_worker_factory.py
@@ -2,10 +2,10 @@ from typing import cast
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstract
-from pipelex.hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
from pipelex.plugins.inference_backend_registry import InferenceFamily
from pipelex.plugins.model_handle import ModelHandle
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_inference_backend_registry, get_models_manager, get_sdk_client_manager
class SearchWorkerFactory:
diff --git a/pipelex/cogt/templating/template_blueprint.py b/pipelex/cogt/templating/template_blueprint.py
index 70f64a436..ee387faff 100644
--- a/pipelex/cogt/templating/template_blueprint.py
+++ b/pipelex/cogt/templating/template_blueprint.py
@@ -2,12 +2,12 @@ from typing import Any
from pydantic import BaseModel, Field, model_validator
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
from pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsing
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TemplatingStyle
class TemplateBlueprint(BaseModel):
diff --git a/pipelex/cogt/templating/template_rendering.py b/pipelex/cogt/templating/template_rendering.py
index b8898960e..2be065b1a 100644
--- a/pipelex/cogt/templating/template_rendering.py
+++ b/pipelex/cogt/templating/template_rendering.py
@@ -1,10 +1,10 @@
from collections.abc import Callable
from typing import Any
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TemplatingStyle
async def render_template(
diff --git a/pipelex/cogt/usage/cost_registry.py b/pipelex/cogt/usage/cost_registry.py
index d11e511d7..b4dd9dd74 100644
--- a/pipelex/cogt/usage/cost_registry.py
+++ b/pipelex/cogt/usage/cost_registry.py
@@ -16,7 +16,7 @@ from pipelex.cogt.search.search_report import SearchTokenCostReport, SearchToken
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
from pipelex.cogt.usage.costs_per_token import model_cost_per_token
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
TokensUsage = LLMTokensUsage | ImgGenTokensUsage | ExtractTokensUsage | SearchTokensUsage
diff --git a/pipelex/config.py b/pipelex/config.py
index bee2698b4..a47fe3518 100644
--- a/pipelex/config.py
+++ b/pipelex/config.py
@@ -1,5 +1,5 @@
-from pipelex.hub import get_optional_config, get_required_config
from pipelex.plugins.pipe_func_executor_registry import DIRECT_PIPE_FUNC_EXECUTION_MODE
+from pipelex.runtime_hub import get_optional_config, get_required_config
from pipelex.system.configuration.configs import PipelexConfig
diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.py
index ad94627b3..88d37f579 100644
--- a/pipelex/core/concepts/concept.py
+++ b/pipelex/core/concepts/concept.py
@@ -1,6 +1,5 @@
from typing import Any, Callable
-from kajson.class_registry_abstract import ClassRegistryAbstract
from mthds.protocol.concept import ConceptAbstract
from pydantic import field_validator
@@ -19,18 +18,11 @@ from pipelex.core.domains.validation import validate_domain_code
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.image_field_search import search_for_nested_image_fields
from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.system.registries.class_registry_access import get_class_registry
from pipelex.tools.misc.string_utils import pascal_case_to_sentence
from pipelex.tools.typing.class_utils import are_classes_equivalent, has_compatible_field
-def _get_class_registry() -> ClassRegistryAbstract:
- """Lazy import to break circular dependency between concept.py and hub.py."""
- import importlib # noqa: PLC0415
-
- hub = importlib.import_module("pipelex.hub")
- return hub.get_class_registry() # type: ignore[no-any-return]
-
-
class Concept(ConceptAbstract):
@field_validator("code")
@classmethod
@@ -138,8 +130,8 @@ class Concept(ConceptAbstract):
# Check class-based compatibility
# This now works even when one or both concepts have refines, since we generate
# structure classes that inherit from the refined concept's class
- concept_1_class = _get_class_registry().get_class(name=concept_1.structure_class_name)
- concept_2_class = _get_class_registry().get_class(name=concept_2.structure_class_name)
+ concept_1_class = get_class_registry().get_class(name=concept_1.structure_class_name)
+ concept_2_class = get_class_registry().get_class(name=concept_2.structure_class_name)
if concept_1_class is None or concept_2_class is None:
return False
@@ -165,9 +157,9 @@ class Concept(ConceptAbstract):
@classmethod
def is_valid_structure_class(cls, structure_class_name: str) -> bool:
- if _get_class_registry().has_subclass(name=structure_class_name, base_class=StuffContent):
+ if get_class_registry().has_subclass(name=structure_class_name, base_class=StuffContent):
return True
- if _get_class_registry().has_class(name=structure_class_name):
+ if get_class_registry().has_class(name=structure_class_name):
log.warning(f"Concept class '{structure_class_name}' is registered but it's not a subclass of StuffContent")
return False
@@ -177,7 +169,7 @@ class Concept(ConceptAbstract):
Returns:
The StuffContent subclass, or None if not found
"""
- structure_class = _get_class_registry().get_class(name=self.structure_class_name)
+ structure_class = get_class_registry().get_class(name=self.structure_class_name)
if structure_class is None:
msg = f"Concept class '{self.structure_class_name}' not found"
raise ConceptValueError(msg)
@@ -185,7 +177,7 @@ class Concept(ConceptAbstract):
def search_for_nested_image_fields_in_structure_class(self) -> list[str]:
"""Recursively search for image fields in a structure class."""
- structure_class = _get_class_registry().get_required_subclass(name=self.structure_class_name, base_class=StuffContent)
+ structure_class = get_class_registry().get_required_subclass(name=self.structure_class_name, base_class=StuffContent)
if not issubclass(structure_class, StuffContent):
msg = f"Concept class '{self.structure_class_name}' is not a subclass of StuffContent"
raise PipelexUnexpectedError(msg)
diff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.py
index d6d0e4d88..c2f6994d9 100644
--- a/pipelex/core/concepts/concept_factory.py
+++ b/pipelex/core/concepts/concept_factory.py
@@ -1,7 +1,6 @@
from enum import StrEnum
from typing import NamedTuple, cast
-from kajson.class_registry_abstract import ClassRegistryAbstract
from pydantic import BaseModel
from pipelex.core.concepts.concept import Concept
@@ -19,14 +18,7 @@ from pipelex.core.concepts.validation import validate_concept_ref_or_code
from pipelex.core.domains.domain import SpecialDomain
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.text_content import TextContent
-
-
-def _get_class_registry() -> ClassRegistryAbstract:
- """Lazy import to break circular dependency with hub.py."""
- import importlib # noqa: PLC0415
-
- hub = importlib.import_module("pipelex.hub")
- return hub.get_class_registry() # type: ignore[no-any-return]
+from pipelex.system.registries.class_registry_access import get_class_registry
class StructureNameAndRefine(NamedTuple):
@@ -358,7 +350,7 @@ class ConceptFactory:
raise ConceptFactoryError(msg) from exc
# Register the generated class
- _get_class_registry().register_class(the_generated_class)
+ get_class_registry().register_class(the_generated_class)
return qualified_class_name
@@ -399,7 +391,7 @@ class ConceptFactory:
msg = f"Error generating structure class for concept '{concept_code}' in domain '{domain_code}': {exc}"
raise ConceptFactoryError(msg) from exc
# Register the generated class
- _get_class_registry().register_class(the_generated_class)
+ get_class_registry().register_class(the_generated_class)
return StructureNameAndRefine(structure_class_name=qualified_class_name, refine_string=NativeConceptCode.TEXT.concept_ref)
@@ -445,7 +437,7 @@ class ConceptFactory:
)
raise ConceptFactoryError(msg) from exc
- _get_class_registry().register_class(the_generated_class)
+ get_class_registry().register_class(the_generated_class)
return StructureNameAndRefine(structure_class_name=qualified_class_name, refine_string=current_refine)
# Get the refined concept's structure class name
@@ -476,7 +468,7 @@ class ConceptFactory:
raise ConceptFactoryError(msg) from exc
# Register the generated class
- _get_class_registry().register_class(the_generated_class)
+ get_class_registry().register_class(the_generated_class)
return StructureNameAndRefine(structure_class_name=qualified_class_name, refine_string=current_refine)
diff --git a/pipelex/core/concepts/concept_provider_abstract.py b/pipelex/core/concepts/concept_provider_abstract.py
new file mode 100644
index 000000000..64dc5eaf3
--- /dev/null
+++ b/pipelex/core/concepts/concept_provider_abstract.py
@@ -0,0 +1,37 @@
+"""The read-side concept-resolution contract, owned by `core/` rather than by the library.
+
+`core/` needs to *resolve* concepts — turn a ref, a code, or a native code into a `Concept`, and
+ask whether two of them are compatible. It has no business *managing* a concept library (adding,
+removing, listing, setup/teardown); that half is the loaded method's concern and stays in the
+interpreter layer, on `ConceptLibraryAbstract`, which extends this.
+
+Splitting the two is what lets `core/` state its dependency honestly: a core module declares "I
+need something that can resolve concepts" as a parameter, instead of reaching for
+`interpreter_hub.get_concept_library()` and dragging the whole interpreter into its import closure.
+See ``docs/contribute/hub-layering.md``.
+"""
+
+from abc import ABC, abstractmethod
+
+from pipelex.core.concepts.concept import Concept
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+
+
+class ConceptProviderAbstract(ABC):
+ """Resolves concept references into concepts, and answers compatibility questions about them."""
+
+ @abstractmethod
+ def get_required_concept(self, concept_ref: str) -> Concept:
+ """Resolve a fully-qualified concept ref, raising when it is not known."""
+
+ @abstractmethod
+ def get_native_concept(self, native_concept: NativeConceptCode) -> Concept:
+ """Resolve one of the native concepts."""
+
+ @abstractmethod
+ def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, *, search_domain_codes: list[str] | None = None) -> Concept:
+ """Resolve a ref *or* a bare code, optionally restricting the domains searched for a bare code."""
+
+ @abstractmethod
+ def is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:
+ """Whether `tested_concept` satisfies `wanted_concept` (refinement only when `strict`)."""
diff --git a/pipelex/codegen/resolved_fields.py b/pipelex/core/concepts/resolved_fields.py
similarity index 100%
rename from pipelex/codegen/resolved_fields.py
rename to pipelex/core/concepts/resolved_fields.py
diff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.py
index 1c96dfa6f..1f2ec8077 100644
--- a/pipelex/core/concepts/structure_generation/generator.py
+++ b/pipelex/core/concepts/structure_generation/generator.py
@@ -4,16 +4,16 @@ from datetime import date, datetime, time
from enum import Enum
from typing import Any, List, Literal, Optional, cast
-from kajson.class_registry_abstract import ClassRegistryAbstract
from pydantic import Field
-from pipelex.codegen.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind, resolve_structure_fields
from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint
from pipelex.core.concepts.helpers import extract_concept_code_from_concept_ref_or_code, make_qualified_structure_class_name
from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.resolved_fields import ResolvedField, ResolvedType, ResolvedTypeKind, resolve_structure_fields
from pipelex.core.concepts.structure_generation.exceptions import ConceptStructureGeneratorError, ConceptStructureValidationError, SyntaxErrorData
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.system.registries.class_registry_access import get_class_registry
# Target line length for emitted code (matches the project's ruff config).
# Each emitted line stays under this so ruff E501 doesn't trigger on long descriptions.
@@ -21,14 +21,6 @@ _MAX_LINE_LENGTH = 150
_WRAP_WIDTH = 120 # conservative: leaves headroom for indentation and syntax overhead
-def _get_class_registry() -> ClassRegistryAbstract:
- """Lazy import to break circular dependency with hub.py."""
- import importlib # noqa: PLC0415
-
- hub = importlib.import_module("pipelex.hub")
- return hub.get_class_registry() # type: ignore[no-any-return]
-
-
class StructureGenerator:
"""Generate Pydantic BaseModel classes from concept structure blueprints."""
@@ -276,7 +268,7 @@ class StructureGenerator:
self.imports.add(f"from {cls.__module__} import {cls.__name__}")
elif base_class != "StructuredContent":
# Cross-package refines: base class lives in another already-installed package — recover its module via the class registry.
- registered_cls = _get_class_registry().get_class(name=base_class)
+ registered_cls = get_class_registry().get_class(name=base_class)
if registered_cls is not None and registered_cls.__name__ == base_class and registered_cls.__module__ not in {"__main__", "builtins"}:
self.imports.add(f"from {registered_cls.__module__} import {base_class}")
@@ -421,7 +413,7 @@ class StructureGenerator:
if base_class_name:
if not NativeConceptCode.is_native_structure_class(base_class_name):
# Not a native class, provide it from registry
- custom_base_class = _get_class_registry().get_class(name=base_class_name)
+ custom_base_class = get_class_registry().get_class(name=base_class_name)
if custom_base_class is None:
msg = f"Base class '{base_class_name}' not found in native classes or class registry"
raise ConceptStructureValidationError(msg)
diff --git a/pipelex/core/memory/input_shaper.py b/pipelex/core/memory/input_shaper.py
index 59268d928..e3305fe37 100644
--- a/pipelex/core/memory/input_shaper.py
+++ b/pipelex/core/memory/input_shaper.py
@@ -25,6 +25,7 @@ from pydantic import ValidationError
from pipelex.base_exceptions import PipelexUnexpectedError
from pipelex.core.concepts.concept import Concept
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
from pipelex.core.concepts.exceptions import ConceptValueError
from pipelex.core.concepts.native.concept_native import NativeConceptCode
@@ -48,7 +49,6 @@ from pipelex.core.stuffs.stuff import DictStuff, Stuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_content_factory import StuffContentFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_concept_library, get_native_concept
from pipelex.tools.uri.uri_resolver import resolve_local_path_reference
@@ -98,6 +98,7 @@ class InputShaper:
cls,
pipeline_inputs: PipelineInputs,
*,
+ concept_provider: ConceptProviderAbstract,
input_specs: InputStuffSpecs,
search_domain_codes: list[str] | None = None,
inputs_base_dir: Path | None = None,
@@ -106,6 +107,9 @@ class InputShaper:
Args:
pipeline_inputs: The caller-provided inputs (name -> value/envelope/object).
+ concept_provider: Resolves concepts and answers compatibility questions. Injected rather
+ than looked up so this module stays out of the method interpreter's import closure
+ (see hub-layering); the caller holds the loaded method's library.
input_specs: The entry pipe's declared inputs (name -> StuffSpec).
search_domain_codes: Domain codes used to resolve envelope/object concepts.
inputs_base_dir: Directory that bare *relative local* file paths resolve against (D3) —
@@ -124,6 +128,7 @@ class InputShaper:
stuff_spec = input_specs.get_required_stuff_spec(variable_name=variable_name)
stuff = cls._shape_one(
value,
+ concept_provider=concept_provider,
stuff_spec=stuff_spec,
variable_name=variable_name,
search_domain_codes=search_domain_codes,
@@ -146,6 +151,7 @@ class InputShaper:
cls,
value: Any,
*,
+ concept_provider: ConceptProviderAbstract,
stuff_spec: StuffSpec,
variable_name: str,
search_domain_codes: list[str] | None,
@@ -158,6 +164,7 @@ class InputShaper:
if cls._is_explicit(value):
return cls._shape_explicit(
value,
+ concept_provider=concept_provider,
declared_concept=declared_concept,
stuff_spec=stuff_spec,
variable_name=variable_name,
@@ -173,13 +180,14 @@ class InputShaper:
)
# (D5) Bare value: dispatch on the declared concept's nature.
- input_kind = cls.resolve_input_kind(declared_concept)
+ input_kind = cls.resolve_input_kind(declared_concept, concept_provider=concept_provider)
match input_kind:
case InputKind.DYNAMIC:
# The signature genuinely does not know how to shape this — hand the whole raw value
# to the bottom-up factory (today's behavior, including its own list handling).
return StuffFactory.make_stuff_from_stuff_content_or_data(
stuff_content_or_data=value,
+ concept_provider=concept_provider,
name=variable_name,
search_domain_codes=search_domain_codes,
)
@@ -195,6 +203,7 @@ class InputShaper:
):
content = cls._shape_with_multiplicity(
value,
+ concept_provider=concept_provider,
stuff_spec=stuff_spec,
input_kind=input_kind,
variable_name=variable_name,
@@ -204,7 +213,7 @@ class InputShaper:
return StuffFactory.make_stuff(concept=declared_concept, content=content, name=variable_name)
@classmethod
- def resolve_input_kind(cls, concept: Concept) -> InputKind:
+ def resolve_input_kind(cls, concept: Concept, *, concept_provider: ConceptProviderAbstract) -> InputKind:
"""Map a declared concept to its interpretation arm via ordered strict-compatibility checks (D5).
``strict=True`` means refinement / structural-equivalence only — a concept refining ``Number``
@@ -213,7 +222,6 @@ class InputShaper:
if NativeConceptCode.is_dynamic_concept(concept_code=concept.code):
return InputKind.DYNAMIC
- concept_library = get_concept_library()
ordered_natives: list[tuple[NativeConceptCode, InputKind]] = [
(NativeConceptCode.YES_NO, InputKind.YES_NO),
(NativeConceptCode.DATE, InputKind.DATE),
@@ -224,8 +232,8 @@ class InputShaper:
(NativeConceptCode.TEXT, InputKind.TEXT),
]
for native_code, input_kind in ordered_natives:
- wanted_concept = get_native_concept(native_concept=native_code)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=wanted_concept, strict=True):
+ wanted_concept = concept_provider.get_native_concept(native_concept=native_code)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=wanted_concept, strict=True):
return input_kind
# A user (non-native) concept whose structure is StructuredContent dispatches its dict
@@ -259,6 +267,7 @@ class InputShaper:
cls,
value: Any,
*,
+ concept_provider: ConceptProviderAbstract,
stuff_spec: StuffSpec,
input_kind: InputKind,
variable_name: str,
@@ -287,6 +296,7 @@ class InputShaper:
if is_list:
return cls._shape_list(
value,
+ concept_provider=concept_provider,
stuff_spec=stuff_spec,
input_kind=input_kind,
variable_name=variable_name,
@@ -305,6 +315,7 @@ class InputShaper:
)
return cls._build_item_content(
value,
+ concept_provider=concept_provider,
input_kind=input_kind,
stuff_spec=stuff_spec,
variable_name=variable_name,
@@ -358,6 +369,7 @@ class InputShaper:
cls,
value: Any,
*,
+ concept_provider: ConceptProviderAbstract,
stuff_spec: StuffSpec,
input_kind: InputKind,
variable_name: str,
@@ -379,6 +391,7 @@ class InputShaper:
items = [
cls._build_item_content(
item_value,
+ concept_provider=concept_provider,
input_kind=input_kind,
stuff_spec=stuff_spec,
variable_name=variable_name,
@@ -394,6 +407,7 @@ class InputShaper:
cls,
value: Any,
*,
+ concept_provider: ConceptProviderAbstract,
input_kind: InputKind,
stuff_spec: StuffSpec,
variable_name: str,
@@ -412,9 +426,9 @@ class InputShaper:
concept = stuff_spec.concept
if isinstance(value, StuffContent):
built = StuffFactory.make_stuff_from_stuff_content_or_data(
- stuff_content_or_data=value, name=variable_name, search_domain_codes=search_domain_codes
+ stuff_content_or_data=value, concept_provider=concept_provider, name=variable_name, search_domain_codes=search_domain_codes
)
- if not get_concept_library().is_compatible(tested_concept=built.concept, wanted_concept=concept):
+ if not concept_provider.is_compatible(tested_concept=built.concept, wanted_concept=concept):
raise ExplicitConceptIncompatibleError.make(
variable_name=variable_name,
declared_concept_ref=concept.concept_ref,
@@ -507,6 +521,7 @@ class InputShaper:
cls,
value: Any,
*,
+ concept_provider: ConceptProviderAbstract,
declared_concept: Concept,
stuff_spec: StuffSpec,
variable_name: str,
@@ -521,10 +536,11 @@ class InputShaper:
"""
stuff = StuffFactory.make_stuff_from_stuff_content_or_data(
stuff_content_or_data=cast("StuffContentOrData", value),
+ concept_provider=concept_provider,
name=variable_name,
search_domain_codes=search_domain_codes,
)
- if not get_concept_library().is_compatible(tested_concept=stuff.concept, wanted_concept=declared_concept):
+ if not concept_provider.is_compatible(tested_concept=stuff.concept, wanted_concept=declared_concept):
raise ExplicitConceptIncompatibleError.make(
variable_name=variable_name,
declared_concept_ref=declared_concept.concept_ref,
diff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.py
index 2db7bba6f..3a652706e 100644
--- a/pipelex/core/memory/working_memory_factory.py
+++ b/pipelex/core/memory/working_memory_factory.py
@@ -8,6 +8,7 @@ from pydantic import BaseModel, ValidationError
from pipelex import log
from pipelex.cogt.content_generation.dry_mock import stamp_mock_main_coordination
from pipelex.cogt.content_generation.dry_run_factory import DryRunFactory
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
from pipelex.core.memory.exceptions import WorkingMemoryFactoryError
from pipelex.core.memory.input_shaper import InputShaper
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, StuffDict, WorkingMemory
@@ -18,7 +19,7 @@ from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
# Field names that require snake_case format for pipelex bundle specs
# Note: main_pipe is NOT included here because BundleHeaderSpec.main_pipe has
@@ -72,6 +73,7 @@ class WorkingMemoryFactory(BaseModel):
cls,
pipeline_inputs: PipelineInputs,
*,
+ concept_provider: ConceptProviderAbstract,
input_specs: InputStuffSpecs | None = None,
search_domain_codes: list[str] | None = None,
inputs_base_dir: Path | None = None,
@@ -87,6 +89,9 @@ class WorkingMemoryFactory(BaseModel):
Args:
pipeline_inputs: Dictionary in the format from API serialization
+ concept_provider: Resolves concepts and answers compatibility questions. Injected rather
+ than looked up so this module stays out of the method interpreter's import closure
+ (see hub-layering); the caller holds the loaded method's library.
input_specs: The entry pipe's declared inputs; ``None`` disables signature-driven shaping
search_domain_codes: List of domain codes to search for concepts
inputs_base_dir: Directory that bare *relative local* file paths resolve against (D3);
@@ -101,6 +106,7 @@ class WorkingMemoryFactory(BaseModel):
if input_specs is not None:
return InputShaper.shape(
pipeline_inputs,
+ concept_provider=concept_provider,
input_specs=input_specs,
search_domain_codes=search_domain_codes,
inputs_base_dir=inputs_base_dir,
@@ -112,6 +118,7 @@ class WorkingMemoryFactory(BaseModel):
stuff = StuffFactory.make_stuff_from_stuff_content_or_data(
name=stuff_key,
stuff_content_or_data=stuff_content_or_data,
+ concept_provider=concept_provider,
search_domain_codes=search_domain_codes,
)
working_memory.add_new_stuff(name=stuff_key, stuff=stuff)
diff --git a/pipelex/core/pipes/inputs/input_stuff_specs_factory.py b/pipelex/core/pipes/inputs/input_stuff_specs_factory.py
index bd717f639..9b6e60cce 100644
--- a/pipelex/core/pipes/inputs/input_stuff_specs_factory.py
+++ b/pipelex/core/pipes/inputs/input_stuff_specs_factory.py
@@ -2,13 +2,13 @@ import re
from typing import TYPE_CHECKING
from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
from pipelex.core.concepts.exceptions import ConceptStringError
from pipelex.core.concepts.validation import validate_concept_ref_or_code
from pipelex.core.pipes.inputs.exceptions import InputStuffSpecsFactoryError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs, PipeInputsRoot
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import PresenceMarker
-from pipelex.hub import get_required_concept
if TYPE_CHECKING:
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
@@ -26,12 +26,14 @@ class InputStuffSpecsFactory:
def make_from_blueprint(
cls,
*,
+ concept_provider: ConceptProviderAbstract,
domain_code: str,
blueprint: dict[str, str],
) -> InputStuffSpecs:
stuff_specs: PipeInputsRoot = {}
for var_name, stuff_spec_str in blueprint.items():
stuff_spec = InputStuffSpecsFactory.make_from_string(
+ concept_provider=concept_provider,
domain_code=domain_code,
stuff_spec_str=stuff_spec_str,
)
@@ -42,6 +44,7 @@ class InputStuffSpecsFactory:
def make_from_string(
cls,
*,
+ concept_provider: ConceptProviderAbstract,
domain_code: str,
stuff_spec_str: str,
) -> StuffSpec:
@@ -54,6 +57,8 @@ class InputStuffSpecsFactory:
- "ConceptCode[5]" -> multiplicity = 5 (resolved with domain)
Args:
+ concept_provider: Resolves the parsed concept ref. Injected rather than looked up so this
+ module stays out of the method interpreter's import closure (see hub-layering).
domain_code: The domain code to use for resolving concept codes without domain prefix
stuff_spec_str: String in the format "domain.ConceptCode" or "ConceptCode" with optional "[multiplicity]"
@@ -100,5 +105,5 @@ class InputStuffSpecsFactory:
multiplicity = int(multiplicity_str)
# else: No brackets, multiplicity stays None
- concept = get_required_concept(concept_ref=concept_ref_with_domain)
+ concept = concept_provider.get_required_concept(concept_ref=concept_ref_with_domain)
return StuffSpec(concept=concept, multiplicity=multiplicity, presence=PresenceMarker.from_symbol(marker_symbol))
diff --git a/pipelex/core/pipes/pipe_abstract.py b/pipelex/core/pipes/pipe_abstract.py
index 358489558..94341e13d 100644
--- a/pipelex/core/pipes/pipe_abstract.py
+++ b/pipelex/core/pipes/pipe_abstract.py
@@ -29,8 +29,8 @@ from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_to_apply
from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError
-from pipelex.pipeline.job_metadata import JobMetadata, OtelContext
from pipelex.pipeline.pipeline_factory import PipelineFactory
+from pipelex.system.job_metadata import JobMetadata, OtelContext
from pipelex.system.telemetry.otel_constants import (
LangfuseSpanAttr,
OTelConstants,
@@ -44,7 +44,7 @@ from pipelex.tools.misc.package_utils import get_package_version
from pipelex.tools.misc.string_utils import is_snake_case
if TYPE_CHECKING:
- from pipelex.graph.trace_context import TraceContext
+ from pipelex.system.trace_context import TraceContext
PipeAbstractType = type["PipeAbstract"]
diff --git a/pipelex/core/pipes/pipe_factory.py b/pipelex/core/pipes/pipe_factory.py
index e5b5772c5..8e9224573 100644
--- a/pipelex/core/pipes/pipe_factory.py
+++ b/pipelex/core/pipes/pipe_factory.py
@@ -12,7 +12,8 @@ from pipelex.core.pipes.pipe_blueprint import PipeBlueprint, PipeCategory, PipeT
from pipelex.core.pipes.stuff_spec.exceptions import StuffSpecFactoryError
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.stuff_spec.stuff_spec_factory import StuffSpecFactory
-from pipelex.hub import get_class_registry
+from pipelex.interpreter_hub import get_concept_library
+from pipelex.runtime_hub import get_class_registry
if TYPE_CHECKING:
from pipelex.core.pipes.pipe_abstract import PipeAbstract
@@ -95,11 +96,14 @@ class PipeFactory(Generic[PipeAbstractType]):
# Parse common attributes
try:
- parsed_output = StuffSpecFactory.make_from_blueprint(domain_code=domain_code, output_string=blueprint.output)
+ parsed_output = StuffSpecFactory.make_from_blueprint(
+ concept_provider=get_concept_library(), domain_code=domain_code, output_string=blueprint.output
+ )
except StuffSpecFactoryError as exc:
msg = f"Error parsing output string '{blueprint.output}': {exc}"
raise PipeFactoryError(msg) from exc
parsed_inputs = InputStuffSpecsFactory.make_from_blueprint(
+ concept_provider=get_concept_library(),
domain_code=domain_code,
blueprint=blueprint.inputs or {},
)
diff --git a/pipelex/core/pipes/output/__init__.py b/pipelex/core/pipes/rendering/__init__.py
similarity index 100%
rename from pipelex/core/pipes/output/__init__.py
rename to pipelex/core/pipes/rendering/__init__.py
diff --git a/pipelex/core/pipes/inputs/input_renderer.py b/pipelex/core/pipes/rendering/input_renderer.py
similarity index 98%
rename from pipelex/core/pipes/inputs/input_renderer.py
rename to pipelex/core/pipes/rendering/input_renderer.py
index fe0a54127..0f3f055db 100644
--- a/pipelex/core/pipes/inputs/input_renderer.py
+++ b/pipelex/core/pipes/rendering/input_renderer.py
@@ -8,6 +8,7 @@ from pipelex.core.memory.input_shaper import InputKind, InputShaper
from pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_abstract import PipeAbstract
+from pipelex.interpreter_hub import get_concept_library
class InputsTemplateFormat(StrEnum):
@@ -128,9 +129,10 @@ def serialize_inputs_template_to_toml(
def _delighten_template(envelope_template: dict[str, Any], *, input_specs: InputStuffSpecs) -> dict[str, Any]:
"""Transform every envelope entry into its light value, dispatched on the declared concept's kind."""
light_template: dict[str, Any] = {}
+ concept_provider = get_concept_library()
for variable_name, entry in envelope_template.items():
stuff_spec = input_specs.get_required_stuff_spec(variable_name=variable_name)
- kind = InputShaper.resolve_input_kind(stuff_spec.concept)
+ kind = InputShaper.resolve_input_kind(stuff_spec.concept, concept_provider=concept_provider)
light_template[variable_name] = _delighten_entry(entry, kind=kind)
return light_template
diff --git a/pipelex/core/pipes/output/output_renderer.py b/pipelex/core/pipes/rendering/output_renderer.py
similarity index 99%
rename from pipelex/core/pipes/output/output_renderer.py
rename to pipelex/core/pipes/rendering/output_renderer.py
index 4866f694c..710e9cbcf 100644
--- a/pipelex/core/pipes/output/output_renderer.py
+++ b/pipelex/core/pipes/rendering/output_renderer.py
@@ -6,7 +6,7 @@ from pipelex.core.concepts.concept_representation_generator import ConceptRepres
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.core.pipes.pipe_blueprint import PipeType
-from pipelex.hub import get_required_pipe
+from pipelex.interpreter_hub import get_required_pipe
if TYPE_CHECKING:
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
diff --git a/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py b/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py
index f30a88176..54a1864b9 100644
--- a/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py
+++ b/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py
@@ -1,10 +1,10 @@
from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
from pipelex.core.concepts.exceptions import ConceptFactoryError
from pipelex.core.pipes.exceptions import PipeVariableMultiplicityError
from pipelex.core.pipes.stuff_spec.exceptions import StuffSpecFactoryError
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity
-from pipelex.hub import get_required_concept
class StuffSpecFactory:
@@ -12,12 +12,15 @@ class StuffSpecFactory:
def make_from_blueprint(
cls,
*,
+ concept_provider: ConceptProviderAbstract,
domain_code: str,
output_string: str,
) -> StuffSpec:
"""Parse an output string and return a StuffSpec with concept and multiplicity.
Args:
+ concept_provider: Resolves the parsed concept ref. Injected rather than looked up so this
+ module stays out of the method interpreter's import closure (see hub-layering).
domain_code: The domain code to use for resolving concept codes without domain prefix
output_string: String in the format "ConceptCode" or "domain.ConceptCode"
with optional "[multiplicity]" (e.g., "Text", "Text[]", "Text[3]")
@@ -45,7 +48,7 @@ class StuffSpecFactory:
msg = f"Error resolving concept from output string '{output_string}': {exc}"
raise StuffSpecFactoryError(msg) from exc
- concept = get_required_concept(
+ concept = concept_provider.get_required_concept(
concept_ref=ConceptFactory.make_concept_ref_with_domain(
domain_code=domain_and_code.domain_code,
concept_code=domain_and_code.concept_code,
diff --git a/pipelex/core/pipes/template_guard_lint.py b/pipelex/core/pipes/template_guard_lint.py
index c52300726..77ee36a3c 100644
--- a/pipelex/core/pipes/template_guard_lint.py
+++ b/pipelex/core/pipes/template_guard_lint.py
@@ -4,12 +4,12 @@ expressions): each reference to a declared-optional (`?`) input must be guarded,
validation fails with `OPTIONAL_INPUT_UNGUARDED` and the precise fix.
"""
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_optional_guards import detect_unguarded_optional_references
+from pipelex.tools.jinja2.template_category import TemplateCategory
def lint_optional_input_guards(
diff --git a/pipelex/core/stuffs/document_content.py b/pipelex/core/stuffs/document_content.py
index bebfa101f..68cd01c07 100644
--- a/pipelex/core/stuffs/document_content.py
+++ b/pipelex/core/stuffs/document_content.py
@@ -4,9 +4,9 @@ from pydantic import Field, model_validator
from rich.text import Text
from typing_extensions import override
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_sync
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.http_utils import validate_url_resource_exists
from pipelex.tools.misc.pretty import PrettyPrintable
from pipelex.tools.uri.uri_resolver import extract_filename_from_uri, resolve_uri
diff --git a/pipelex/core/stuffs/html_content.py b/pipelex/core/stuffs/html_content.py
index 650d42cf0..359cc4288 100644
--- a/pipelex/core/stuffs/html_content.py
+++ b/pipelex/core/stuffs/html_content.py
@@ -3,9 +3,9 @@ import json
from pydantic import Field
from typing_extensions import override
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_sync
+from pipelex.tools.jinja2.template_category import TemplateCategory
class HtmlContent(StuffContent):
diff --git a/pipelex/core/stuffs/image_content.py b/pipelex/core/stuffs/image_content.py
index 0e59796d6..156d0b3a1 100644
--- a/pipelex/core/stuffs/image_content.py
+++ b/pipelex/core/stuffs/image_content.py
@@ -6,13 +6,13 @@ from rich.markdown import Markdown
from rich.text import Text
from typing_extensions import override
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_sync
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.http_utils import validate_url_resource_exists
from pipelex.tools.misc.pretty import PrettyPrintable
+from pipelex.tools.templating.text_format import TextFormat
from pipelex.tools.uri.uri_resolver import describe_uri, extract_filename_from_uri
diff --git a/pipelex/core/stuffs/list_content.py b/pipelex/core/stuffs/list_content.py
index d259091c0..c5aa1e784 100644
--- a/pipelex/core/stuffs/list_content.py
+++ b/pipelex/core/stuffs/list_content.py
@@ -4,11 +4,11 @@ from rich.pretty import Pretty
from rich.table import Table
from typing_extensions import override
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.stuffs.stuff_content import StuffContent, StuffContentType
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.image_renderable import ImageRenderable
from pipelex.tools.misc.pretty import MAX_RENDER_DEPTH, PrettyPrintable, PrettyPrinter
+from pipelex.tools.templating.text_format import TextFormat
class ListContent(StuffContent, Generic[StuffContentType]):
diff --git a/pipelex/core/stuffs/mermaid_content.py b/pipelex/core/stuffs/mermaid_content.py
index 480b2db5d..7fa086560 100644
--- a/pipelex/core/stuffs/mermaid_content.py
+++ b/pipelex/core/stuffs/mermaid_content.py
@@ -2,9 +2,9 @@ import json
from typing_extensions import override
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_sync
+from pipelex.tools.jinja2.template_category import TemplateCategory
class MermaidContent(StuffContent):
diff --git a/pipelex/core/stuffs/structured_content.py b/pipelex/core/stuffs/structured_content.py
index 74ae724ee..effba109e 100644
--- a/pipelex/core/stuffs/structured_content.py
+++ b/pipelex/core/stuffs/structured_content.py
@@ -5,13 +5,13 @@ from rich.pretty import Pretty
from rich.table import Table
from typing_extensions import override
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.stuffs.html_rendering import render_value_html
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.image_renderable import ImageRenderable
from pipelex.tools.misc.markdown_utils import convert_to_markdown
from pipelex.tools.misc.pretty import MAX_RENDER_DEPTH, PrettyPrintable, PrettyPrinter
+from pipelex.tools.templating.text_format import TextFormat
from pipelex.tools.typing.pydantic_utils import clean_model_to_dict
diff --git a/pipelex/core/stuffs/stuff_artefact.py b/pipelex/core/stuffs/stuff_artefact.py
index cae8995dc..797f28ddb 100644
--- a/pipelex/core/stuffs/stuff_artefact.py
+++ b/pipelex/core/stuffs/stuff_artefact.py
@@ -19,9 +19,9 @@ from typing import TYPE_CHECKING, Any, Iterator
from typing_extensions import override
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.stuffs.list_content import ListContent
from pipelex.tools.jinja2.image_renderable import ImageRenderable
+from pipelex.tools.templating.text_format import TextFormat
if TYPE_CHECKING:
from pipelex.core.stuffs.stuff import Stuff
diff --git a/pipelex/core/stuffs/stuff_content.py b/pipelex/core/stuffs/stuff_content.py
index 4059c19e8..4524bdc8b 100644
--- a/pipelex/core/stuffs/stuff_content.py
+++ b/pipelex/core/stuffs/stuff_content.py
@@ -5,8 +5,8 @@ from mthds.protocol.stuff import StuffContentAbstract
from rich.json import JSON
from typing_extensions import override
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.tools.misc.pretty import PrettyPrintable, PrettyPrinter, PrettyRenderable, pretty_print
+from pipelex.tools.templating.text_format import TextFormat
from pipelex.tools.typing.pydantic_utils import CustomBaseModel
StuffContentType = TypeVar("StuffContentType", bound="StuffContent")
diff --git a/pipelex/core/stuffs/stuff_content_factory.py b/pipelex/core/stuffs/stuff_content_factory.py
index 1d72237d5..4e791ffcb 100644
--- a/pipelex/core/stuffs/stuff_content_factory.py
+++ b/pipelex/core/stuffs/stuff_content_factory.py
@@ -9,7 +9,7 @@ from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.core.stuffs.time_content import TimeContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
class StuffContentFactory:
diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.py
index 92bda09e0..faca2848d 100644
--- a/pipelex/core/stuffs/stuff_factory.py
+++ b/pipelex/core/stuffs/stuff_factory.py
@@ -9,7 +9,8 @@ from pydantic import BaseModel, ValidationError, field_validator
from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.concept_factory import ConceptFactory
-from pipelex.core.concepts.exceptions import ConceptValueError
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
+from pipelex.core.concepts.exceptions import ConceptLibraryConceptNotFoundError, ConceptValueError
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.concepts.validation import validate_concept_ref
from pipelex.core.stuffs.exceptions import StuffFactoryError
@@ -18,8 +19,7 @@ from pipelex.core.stuffs.stuff import DictStuff, Stuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_content_factory import StuffContentFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry, get_concept_library, get_native_concept, get_required_concept
-from pipelex.libraries.concept.concept_library import ConceptLibraryConceptNotFoundError
+from pipelex.runtime_hub import get_class_registry
from pipelex.tools.tabular.csv_codec import is_tabular_path, list_content_from_csv
from pipelex.tools.tabular.exceptions import CsvError
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
@@ -57,9 +57,9 @@ class StuffFactory:
)
@classmethod
- def make_from_concept_ref(cls, concept_ref: str, *, name: str, content: StuffContent) -> Stuff:
+ def make_from_concept_ref(cls, concept_ref: str, *, concept_provider: ConceptProviderAbstract, name: str, content: StuffContent) -> Stuff:
validate_concept_ref(concept_ref)
- concept = get_required_concept(concept_ref=concept_ref)
+ concept = concept_provider.get_required_concept(concept_ref=concept_ref)
return cls.make_stuff(
concept=concept,
content=content,
@@ -89,24 +89,23 @@ class StuffFactory:
)
@classmethod
- def make_from_blueprint(cls, blueprint: StuffBlueprint) -> "Stuff":
- concept_library = get_concept_library()
- if isinstance(blueprint.content, str) and concept_library.is_compatible(
- tested_concept=concept_library.get_required_concept(concept_ref=blueprint.concept_ref),
- wanted_concept=get_native_concept(native_concept=NativeConceptCode.TEXT),
+ def make_from_blueprint(cls, blueprint: StuffBlueprint, *, concept_provider: ConceptProviderAbstract) -> "Stuff":
+ if isinstance(blueprint.content, str) and concept_provider.is_compatible(
+ tested_concept=concept_provider.get_required_concept(concept_ref=blueprint.concept_ref),
+ wanted_concept=concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT),
):
the_stuff = cls.make_stuff(
- concept=get_native_concept(native_concept=NativeConceptCode.TEXT),
+ concept=concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT),
content=TextContent(text=blueprint.content),
name=blueprint.stuff_name,
)
else:
the_stuff_content = StuffContentFactory.make_stuff_content_from_concept_required(
- concept=concept_library.get_required_concept(concept_ref=blueprint.concept_ref),
+ concept=concept_provider.get_required_concept(concept_ref=blueprint.concept_ref),
value=blueprint.content,
)
the_stuff = cls.make_stuff(
- concept=concept_library.get_required_concept(concept_ref=blueprint.concept_ref),
+ concept=concept_provider.get_required_concept(concept_ref=blueprint.concept_ref),
content=the_stuff_content,
name=blueprint.stuff_name,
)
@@ -248,6 +247,7 @@ class StuffFactory:
cls,
stuff_content_or_data: StuffContentOrData,
*,
+ concept_provider: ConceptProviderAbstract,
name: str | None = None,
code: str | None = None,
search_domain_codes: list[str] | None = None,
@@ -277,14 +277,12 @@ class StuffFactory:
2.5: {"concept": "...", "content": dict} → Create StuffContent from dict
2.6: {"concept": "...", "content": list[dict]} → ListContent[StuffContent] from dicts
"""
- concept_library = get_concept_library()
-
# ==================== CASE 1: Direct content (no concept key) ====================
if not isinstance(stuff_content_or_data, dict):
# Case 1.1: str → TextContent with Text concept
if isinstance(stuff_content_or_data, str):
return cls.make_stuff(
- concept=get_native_concept(native_concept=NativeConceptCode.TEXT),
+ concept=concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT),
content=TextContent(text=stuff_content_or_data),
name=name,
code=code,
@@ -327,10 +325,10 @@ class StuffFactory:
if "Content" in content_class_name and NativeConceptCode.is_native_concept_ref_or_code(
concept_ref_or_code=content_class_name.split("Content")[0]
):
- concept = get_native_concept(native_concept=NativeConceptCode(content_class_name.split("Content")[0]))
+ concept = concept_provider.get_native_concept(native_concept=NativeConceptCode(content_class_name.split("Content")[0]))
else:
try:
- concept = concept_library.get_required_concept_from_concept_ref_or_code(
+ concept = concept_provider.get_required_concept_from_concept_ref_or_code(
concept_ref_or_code=content_class_name, search_domain_codes=search_domain_codes
)
except ConceptLibraryConceptNotFoundError as exc:
@@ -357,11 +355,11 @@ class StuffFactory:
concept_ref_or_code=content_class_name.split("Content")[0]
):
# It's a native concept like TextContent, ImageContent, etc.
- concept = get_native_concept(native_concept=NativeConceptCode(content_class_name.split("Content")[0]))
+ concept = concept_provider.get_native_concept(native_concept=NativeConceptCode(content_class_name.split("Content")[0]))
else:
# It's a StructuredContent, try to find the concept
try:
- concept = concept_library.get_required_concept_from_concept_ref_or_code(
+ concept = concept_provider.get_required_concept_from_concept_ref_or_code(
concept_ref_or_code=content_class_name, search_domain_codes=search_domain_codes
)
except ConceptLibraryConceptNotFoundError as exc:
@@ -398,7 +396,7 @@ class StuffFactory:
items = [TextContent(text=item) for item in cast("list[str]", stuff_content_or_data)]
return cls.make_stuff(
- concept=get_native_concept(native_concept=NativeConceptCode.TEXT),
+ concept=concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT),
content=ListContent(items=items),
name=name,
code=code,
@@ -423,10 +421,10 @@ class StuffFactory:
if "Content" in content_class_name and NativeConceptCode.is_native_concept_ref_or_code(
concept_ref_or_code=content_class_name.split("Content")[0]
):
- concept = get_native_concept(native_concept=NativeConceptCode(content_class_name.split("Content")[0]))
+ concept = concept_provider.get_native_concept(native_concept=NativeConceptCode(content_class_name.split("Content")[0]))
else:
try:
- concept = concept_library.get_required_concept_from_concept_ref_or_code(
+ concept = concept_provider.get_required_concept_from_concept_ref_or_code(
concept_ref_or_code=content_class_name, search_domain_codes=search_domain_codes
)
except ConceptLibraryConceptNotFoundError as exc:
@@ -477,7 +475,7 @@ class StuffFactory:
# Get the concept from the library
try:
- concept = concept_library.get_required_concept_from_concept_ref_or_code(
+ concept = concept_provider.get_required_concept_from_concept_ref_or_code(
concept_ref_or_code=concept_ref, search_domain_codes=search_domain_codes
)
except ConceptLibraryConceptNotFoundError as exc:
@@ -491,8 +489,8 @@ class StuffFactory:
# Checked BEFORE the str/int-ish arms (bool is a subclass of int) so a boolean never falls through to
# the final "unexpected type" error. No string coercion: "yes"/"no" strings take the str path and fail there.
if isinstance(content, bool):
- yes_no_concept = get_native_concept(native_concept=NativeConceptCode.YES_NO)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=yes_no_concept, strict=True):
+ yes_no_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.YES_NO)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=yes_no_concept, strict=True):
return cls.make_stuff(
concept=concept,
content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),
@@ -508,8 +506,8 @@ class StuffFactory:
# Case 2.1: content is a string
if isinstance(content, str):
# Check if concept is strictly compatible with Text (refinement = strict compatibility)
- text_concept = get_native_concept(native_concept=NativeConceptCode.TEXT)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=text_concept, strict=True):
+ text_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=text_concept, strict=True):
return cls.make_stuff(
concept=concept,
content=TextContent(text=content),
@@ -518,8 +516,8 @@ class StuffFactory:
)
# Case 2.1f: a strict-ISO date/datetime string under a Date-compatible concept builds a DateContent
# (routed through the concept resolver so a refining subclass is honored, like the YesNo arm).
- date_concept = get_native_concept(native_concept=NativeConceptCode.DATE)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=date_concept, strict=True):
+ date_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.DATE)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=date_concept, strict=True):
return cls.make_stuff(
concept=concept,
content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),
@@ -527,8 +525,8 @@ class StuffFactory:
code=code,
)
# Case 2.1g: a strict-ISO time string under a Time-compatible concept builds a TimeContent.
- time_concept = get_native_concept(native_concept=NativeConceptCode.TIME)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=time_concept, strict=True):
+ time_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.TIME)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=time_concept, strict=True):
return cls.make_stuff(
concept=concept,
content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),
@@ -544,8 +542,8 @@ class StuffFactory:
# Case 2.1e: content is a bare date/datetime object (a TOML temporal literal used as envelope content)
# → DateContent for a Date-compatible concept. isinstance(date) covers datetime (its subclass).
if isinstance(content, datetime.date):
- date_concept = get_native_concept(native_concept=NativeConceptCode.DATE)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=date_concept, strict=True):
+ date_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.DATE)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=date_concept, strict=True):
return cls.make_stuff(
concept=concept,
content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),
@@ -560,8 +558,8 @@ class StuffFactory:
# Case 2.1g: content is a bare time object (a TOML time literal used as envelope content).
if isinstance(content, datetime.time):
- time_concept = get_native_concept(native_concept=NativeConceptCode.TIME)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=time_concept, strict=True):
+ time_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.TIME)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=time_concept, strict=True):
return cls.make_stuff(
concept=concept,
content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),
@@ -632,8 +630,8 @@ class StuffFactory:
)
raise StuffFactoryError(msg)
- text_concept = get_native_concept(native_concept=NativeConceptCode.TEXT)
- if concept_library.is_compatible(tested_concept=concept, wanted_concept=text_concept, strict=True):
+ text_concept = concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT)
+ if concept_provider.is_compatible(tested_concept=concept, wanted_concept=text_concept, strict=True):
items = [TextContent(text=item) for item in list_content_2]
return cls.make_stuff(
concept=concept,
diff --git a/pipelex/core/stuffs/stuff_viewer.py b/pipelex/core/stuffs/stuff_viewer.py
index d8898365c..9e5e20f61 100644
--- a/pipelex/core/stuffs/stuff_viewer.py
+++ b/pipelex/core/stuffs/stuff_viewer.py
@@ -8,10 +8,10 @@ from typing import Any
from kajson import dumps
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.stuffs.stuff import Stuff
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async
from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.pretty import PRETTY_WIDTH_FOR_EXPORT
# Template registry key
diff --git a/pipelex/core/stuffs/text_and_images_content.py b/pipelex/core/stuffs/text_and_images_content.py
index b31b6eb02..063fecef5 100644
--- a/pipelex/core/stuffs/text_and_images_content.py
+++ b/pipelex/core/stuffs/text_and_images_content.py
@@ -5,12 +5,12 @@ from rich.table import Table
from rich.text import Text
from typing_extensions import override
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.misc.pretty import PrettyPrintable
+from pipelex.tools.templating.text_format import TextFormat
class TextAndImagesContent(StuffContent):
diff --git a/pipelex/core/validation.py b/pipelex/core/validation.py
index 08d11eeab..554029f12 100644
--- a/pipelex/core/validation.py
+++ b/pipelex/core/validation.py
@@ -1,6 +1,6 @@
from pydantic import ValidationError
-from pipelex.hub import get_optional_config
+from pipelex.runtime_hub import get_optional_config
from pipelex.system.configuration.configs import MigrationConfig, PipelexConfig
from pipelex.tools.typing.pydantic_utils import analyze_pydantic_validation_error
diff --git a/pipelex/graph/graph_config.py b/pipelex/graph/graph_config.py
index e555ca3bf..ad853fe15 100644
--- a/pipelex/graph/graph_config.py
+++ b/pipelex/graph/graph_config.py
@@ -1,16 +1,7 @@
from pipelex.graph.mermaidflow.mermaid_config import MermaidRenderingConfig
from pipelex.graph.reactflow.reactflow_config import ReactFlowRenderingConfig
from pipelex.system.configuration.config_model import ConfigModel
-
-
-class DataInclusionConfig(ConfigModel):
- """Controls which data is included in graph outputs."""
-
- stuff_json_content: bool
- stuff_text_content: bool
- stuff_html_content: bool
- error_stack_traces: bool
- pipe_and_concept_registry: bool
+from pipelex.system.data_inclusion_config import DataInclusionConfig
class GraphsInclusionConfig(ConfigModel):
diff --git a/pipelex/graph/graph_tracer.py b/pipelex/graph/graph_tracer.py
index 62685cec3..ea4755e86 100644
--- a/pipelex/graph/graph_tracer.py
+++ b/pipelex/graph/graph_tracer.py
@@ -5,7 +5,6 @@ from typing import Any
from typing_extensions import override
-from pipelex.graph.graph_config import DataInclusionConfig
from pipelex.graph.graph_tracer_protocol import GraphTracerProtocol
from pipelex.graph.graphspec import (
EdgeKind,
@@ -23,7 +22,8 @@ from pipelex.graph.graphspec import (
make_graphspec_meta,
output_digest_is_optional,
)
-from pipelex.graph.trace_context import TraceContext
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.event_log_protocol import EventLogProtocol # noqa: TC001 - used in __init__ annotations
from pipelex.tracing.trace_events import (
BatchAggregateEvent,
diff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.py
index a4a6c3bfc..909953f8b 100644
--- a/pipelex/graph/graph_tracer_manager.py
+++ b/pipelex/graph/graph_tracer_manager.py
@@ -4,12 +4,12 @@ from datetime import datetime
from typing import Any
from pipelex import log
-from pipelex.graph.graph_config import DataInclusionConfig
from pipelex.graph.graph_tracer import GraphTracer
from pipelex.graph.graph_tracer_protocol import GraphTracerProtocol
from pipelex.graph.graphspec import GraphSpec, GraphSpecMode, IOSpec, NodeKind
-from pipelex.graph.trace_context import TraceContext
+from pipelex.system.data_inclusion_config import DataInclusionConfig
from pipelex.system.registries.singleton import ABCSingletonMeta, MetaSingleton
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.event_log_protocol import EventLogProtocol # noqa: TC001 - used in open_tracer signature
diff --git a/pipelex/graph/graph_tracer_protocol.py b/pipelex/graph/graph_tracer_protocol.py
index daaf94e1f..4833d646c 100644
--- a/pipelex/graph/graph_tracer_protocol.py
+++ b/pipelex/graph/graph_tracer_protocol.py
@@ -3,9 +3,9 @@ from typing import Any, Protocol
from typing_extensions import override
-from pipelex.graph.graph_config import DataInclusionConfig
from pipelex.graph.graphspec import EdgeKind, GraphSpec, GraphSpecMode, IOSpec, NodeKind
-from pipelex.graph.trace_context import TraceContext
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.event_log_protocol import EventLogProtocol # noqa: TC001 - used in setup signature
diff --git a/pipelex/graph/mermaidflow/mermaid_html.py b/pipelex/graph/mermaidflow/mermaid_html.py
index dd5fb7fc0..0cf991a5b 100644
--- a/pipelex/graph/mermaidflow/mermaid_html.py
+++ b/pipelex/graph/mermaidflow/mermaid_html.py
@@ -8,10 +8,10 @@ from typing import Any
from kajson import dumps
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.graph.csp import CSP_NONCE_SENTINEL
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async, render_jinja2_sync
from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
+from pipelex.tools.jinja2.template_category import TemplateCategory
# Template registry keys
_BASIC_TEMPLATE_KEY = "mermaid/basic.html.jinja2"
diff --git a/pipelex/graph/reactflow/reactflow_html.py b/pipelex/graph/reactflow/reactflow_html.py
index 8682b4c4a..ce1b9bfe8 100644
--- a/pipelex/graph/reactflow/reactflow_html.py
+++ b/pipelex/graph/reactflow/reactflow_html.py
@@ -7,12 +7,12 @@ injection, consistent with mermaid rendering.
import json
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.graph.graphspec import GraphSpec
from pipelex.graph.reactflow.reactflow_config import ReactFlowRenderingConfig
from pipelex.graph.reactflow.standalone_assets import ELKJS, MTHDS_UI_CSS, MTHDS_UI_JS
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async, render_jinja2_sync
from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
+from pipelex.tools.jinja2.template_category import TemplateCategory
_REACTFLOW_TEMPLATE_KEY = "reactflow/main.html.jinja2"
diff --git a/pipelex/interpreter_hub.py b/pipelex/interpreter_hub.py
new file mode 100644
index 000000000..4081f2795
--- /dev/null
+++ b/pipelex/interpreter_hub.py
@@ -0,0 +1,480 @@
+"""The interpreter layer's dependency hub: library-scoped method machinery.
+
+``InterpreterHub`` brokers everything tied to the *loaded method* rather than to the process: the
+library manager and the domain/concept/pipe libraries, the current-library contextvar family, the
+pipe router, the pipe runner, the pipeline manager, and the PipeFunc executor. That is the half
+that reads the program and executes it — hence *interpreter*.
+
+**The one rule:** this module MAY import ``runtime_hub``; ``runtime_hub`` must never import this
+one. As it happens the arrow is currently unused — the only runtime-layer thing this module needs
+is the class-registry scoping slot, which lives below both hubs in
+``system.registries.class_registry_access``. See ``docs/contribute/hub-layering.md``.
+"""
+
+from collections.abc import Generator, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Optional
+
+from kajson.class_registry_abstract import ClassRegistryAbstract
+
+from pipelex.core.concepts.concept import Concept
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.domains.domain import Domain
+from pipelex.core.pipes.pipe_abstract import PipeAbstract
+from pipelex.libraries.concept.concept_library_abstract import ConceptLibraryAbstract
+from pipelex.libraries.domain.domain_library_abstract import DomainLibraryAbstract
+from pipelex.libraries.library import Library
+from pipelex.libraries.library_manager_abstract import LibraryManagerAbstract
+from pipelex.libraries.pipe.pipe_library_abstract import PipeLibraryAbstract
+from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutorProtocol
+from pipelex.pipeline.pipeline import Pipeline
+from pipelex.pipeline.pipeline_manager_abstract import PipelineManagerAbstract
+from pipelex.system.environment import PIPELEXPATH_ENV_KEY, get_pipelexpath_dirs
+from pipelex.system.registries.class_registry_access import class_registry_scoping
+from pipelex.tools.misc.file_utils import reject_bare_str_or_path
+
+if TYPE_CHECKING:
+ from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocol
+ from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
+ from pipelex.plugins.pipe_func_executor_registry import PipeFuncExecutorRegistry
+
+
+class InterpreterHub:
+ """Central dependency manager for the method-interpretation layer.
+
+ Holds the libraries of the currently loaded method plus the machinery that runs it. Its
+ lifecycle is library-scoped — the ``_library_id`` contextvar below selects which library is
+ current — whereas ``pipelex.runtime_hub.RuntimeHub`` is process-scoped.
+ """
+
+ _instance: ClassVar[Optional["InterpreterHub"]] = None
+
+ def __init__(self):
+ # libraries
+ self._library_manager: LibraryManagerAbstract | None = None
+ self._default_library_dirs: list[Path] | None = None
+ self._domain_library: DomainLibraryAbstract | None = None
+ self._concept_library: ConceptLibraryAbstract | None = None
+ self._pipe_library: PipeLibraryAbstract | None = None
+ # run
+ self._pipe_router: PipeRouterProtocol | None = None
+ self._pipe_run: PipeRunProtocol | None = None
+ self._pipe_func_executor: PipeFuncExecutorProtocol | None = None
+ self._pipe_func_executor_registry: PipeFuncExecutorRegistry | None = None
+ # pipeline
+ self._pipeline_manager: PipelineManagerAbstract | None = None
+
+ ############################################################
+ # Class methods for singleton management
+ ############################################################
+
+ @classmethod
+ def get_optional_instance(cls) -> "InterpreterHub | None":
+ return cls._instance
+
+ @classmethod
+ def get_instance(cls) -> "InterpreterHub":
+ if cls._instance is None:
+ msg = "InterpreterHub is not initialized"
+ raise RuntimeError(msg)
+ return cls._instance
+
+ @classmethod
+ def set_instance(cls, interpreter_hub: "InterpreterHub") -> None:
+ cls._instance = interpreter_hub
+
+ ############################################################
+ # Setters
+ ############################################################
+
+ def set_library_manager(self, library_manager: LibraryManagerAbstract):
+ self._library_manager = library_manager
+
+ def set_default_library_dirs(self, library_dirs: list[Path] | None) -> None:
+ self._default_library_dirs = library_dirs
+
+ def set_domain_library(self, domain_library: DomainLibraryAbstract):
+ self._domain_library = domain_library
+
+ def set_concept_library(self, concept_library: ConceptLibraryAbstract):
+ self._concept_library = concept_library
+
+ def set_pipe_library(self, pipe_library: PipeLibraryAbstract):
+ self._pipe_library = pipe_library
+
+ def set_pipe_router(self, pipe_router: "PipeRouterProtocol"):
+ self._pipe_router = pipe_router
+
+ def set_pipe_run(self, pipe_run: "PipeRunProtocol") -> None:
+ self._pipe_run = pipe_run
+
+ def set_pipe_func_executor(self, pipe_func_executor: PipeFuncExecutorProtocol):
+ self._pipe_func_executor = pipe_func_executor
+
+ def set_pipe_func_executor_registry(self, pipe_func_executor_registry: "PipeFuncExecutorRegistry"):
+ self._pipe_func_executor_registry = pipe_func_executor_registry
+
+ def set_pipeline_manager(self, pipeline_manager: PipelineManagerAbstract):
+ self._pipeline_manager = pipeline_manager
+
+ ############################################################
+ # Getters
+ ############################################################
+
+ def get_library_manager(self) -> LibraryManagerAbstract:
+ if self._library_manager is None:
+ msg = "LibraryManager is not initialized"
+ raise RuntimeError(msg)
+ return self._library_manager
+
+ def get_default_library_dirs(self) -> list[Path] | None:
+ return self._default_library_dirs
+
+ def get_library(self) -> Library:
+ if self._library_manager is not None:
+ return self._library_manager.get_current_library()
+ msg = "Library is not initialized"
+ raise RuntimeError(msg)
+
+ def get_required_domain_library(self) -> DomainLibraryAbstract:
+ if self._library_manager is not None:
+ return self._library_manager.get_current_library().domain_library
+ if self._domain_library is None:
+ msg = "DomainLibrary is not initialized"
+ raise RuntimeError(msg)
+ return self._domain_library
+
+ def get_required_concept_library(self) -> ConceptLibraryAbstract:
+ if self._library_manager is not None:
+ return self._library_manager.get_current_library().concept_library
+ if self._concept_library is None:
+ msg = "ConceptLibrary is not initialized"
+ raise RuntimeError(msg)
+ return self._concept_library
+
+ def get_required_pipe_library(self) -> PipeLibraryAbstract:
+ if self._library_manager is not None:
+ return self._library_manager.get_current_library().pipe_library
+ if self._pipe_library is None:
+ msg = "PipeLibrary is not initialized"
+ raise RuntimeError(msg)
+ return self._pipe_library
+
+ def get_required_pipe_router(self) -> "PipeRouterProtocol":
+ if self._pipe_router is None:
+ msg = "PipeRouter is not initialized"
+ raise RuntimeError(msg)
+ return self._pipe_router
+
+ def get_required_pipe_run(self) -> "PipeRunProtocol":
+ if self._pipe_run is None:
+ msg = "PipeRun is not initialized"
+ raise RuntimeError(msg)
+ return self._pipe_run
+
+ def get_required_pipe_func_executor(self) -> PipeFuncExecutorProtocol:
+ if self._pipe_func_executor is None:
+ msg = "PipeFuncExecutor is not initialized"
+ raise RuntimeError(msg)
+ return self._pipe_func_executor
+
+ def get_pipe_func_executor_registry(self) -> "PipeFuncExecutorRegistry":
+ if self._pipe_func_executor_registry is None:
+ msg = "PipeFuncExecutorRegistry is not initialized"
+ raise RuntimeError(msg)
+ return self._pipe_func_executor_registry
+
+ def get_required_pipeline_manager(self) -> PipelineManagerAbstract:
+ if self._pipeline_manager is None:
+ msg = "PipelineManager is not initialized"
+ raise RuntimeError(msg)
+ return self._pipeline_manager
+
+
+# Shorthand functions for accessing the singleton
+
+
+def get_interpreter_hub() -> InterpreterHub:
+ return InterpreterHub.get_instance()
+
+
+def set_interpreter_hub(interpreter_hub: InterpreterHub):
+ """Install ``interpreter_hub`` as the process singleton, and hand the runtime layer its scoping resolver.
+
+ Installing the resolver here rather than at an explicit boot step means library scoping is
+ active exactly when an InterpreterHub exists — the invariant ``get_class_registry`` relies on, and
+ one a caller cannot forget to wire. The resolver crosses downward at install time, never as an
+ import from ``runtime_hub``.
+ """
+ InterpreterHub.set_instance(interpreter_hub)
+ class_registry_scoping.install(resolver=_resolve_scoped_class_registry)
+
+
+def _resolve_scoped_class_registry() -> ClassRegistryAbstract | None:
+ """Resolve the current library's ClassRegistry, or None when nothing narrows the lookup.
+
+ Returns None both when no library is pinned in the current async context and when the pinned
+ library carries no registry of its own; ``get_class_registry`` then serves the process-global
+ Kajson registry.
+ """
+ library_id = _library_id.get()
+ if library_id is None:
+ return None
+ return get_library_manager().get_library_class_registry(library_id)
+
+
+# libraries
+
+
+_library_id: ContextVar[str | None] = ContextVar("library_id", default=None)
+
+
+def set_current_library(library_id: str) -> None:
+ """Set the library_id for the current async context."""
+ _library_id.set(library_id)
+
+
+def get_current_library() -> str:
+ """Get the library_id from the current async context."""
+ library_id = _library_id.get()
+ if library_id is None:
+ msg = "No current library set. Must call set_current_library() first."
+ raise RuntimeError(msg)
+ return library_id
+
+
+def get_current_library_id_or_none() -> str | None:
+ """Return the current library_id, or ``None`` if none is set."""
+ return _library_id.get()
+
+
+def get_default_library_dirs() -> list[Path] | None:
+ return get_interpreter_hub().get_default_library_dirs()
+
+
+def clear_current_library() -> None:
+ """Clear the current-library binding (the ``None`` case of :func:`set_current_library`).
+
+ Resets the ``_library_id`` ContextVar to ``None`` for the current async context. This only
+ drops the *pointer* to which library is current — it does **not** free the ``Library`` object
+ from the ``LibraryManager``. To release the library itself, call
+ ``library_manager.teardown(library_id=...)`` (the two are distinct and a full cleanup typically
+ does both).
+ """
+ _library_id.set(None)
+
+
+@contextmanager
+def scoped_current_library(library_id: str) -> Generator[None, None, None]:
+ """Set ``library_id`` for the scope, then restore the prior value on exit.
+
+ Captures the prior ``_library_id`` ContextVar value before setting the new
+ one. On exit — success or exception — restores the prior value (or clears
+ the var if there wasn't one). Use this whenever a function temporarily
+ needs a current library for a nested operation without clobbering an
+ outer caller's library_id.
+ """
+ prev = _library_id.get()
+ _library_id.set(library_id)
+ try:
+ yield
+ finally:
+ _library_id.set(prev)
+
+
+def resolve_library_dirs(library_dirs: Sequence[str | Path] | None = None) -> tuple[list[Path], str]:
+ """Resolve library directories following the standard 3-tier priority.
+
+ Resolution priority:
+ 1. Per-call library_dirs (explicit override)
+ 2. Instance-level defaults from Pipelex.make()
+ 3. PIPELEXPATH environment variable (fallback)
+
+ Note: An empty list [] is a valid explicit value that disables library loading.
+
+ Args:
+ library_dirs: Optional per-call override. If provided (even if empty),
+ takes precedence over instance defaults and PIPELEXPATH.
+
+ Returns:
+ A tuple of (effective_dirs, source_label) where:
+ - effective_dirs: The resolved list of Path objects
+ - source_label: A string describing the source for logging (e.g., "per-call")
+ """
+ reject_bare_str_or_path(library_dirs, param_name="library_dirs")
+ if library_dirs is not None:
+ return [Path(lib_dir) for lib_dir in library_dirs], "per-call"
+
+ hub_defaults = get_interpreter_hub().get_default_library_dirs()
+ if hub_defaults is not None:
+ return hub_defaults, "instance default"
+
+ pipelexpath_dirs = get_pipelexpath_dirs()
+ if pipelexpath_dirs is not None:
+ return pipelexpath_dirs, PIPELEXPATH_ENV_KEY
+
+ return [], "none configured"
+
+
+def get_library_manager() -> LibraryManagerAbstract:
+ return get_interpreter_hub().get_library_manager()
+
+
+def get_library() -> Library:
+ return get_interpreter_hub().get_library()
+
+
+def get_required_domain(domain_code: str) -> Domain:
+ return get_interpreter_hub().get_required_domain_library().get_required_domain(domain_code=domain_code)
+
+
+def get_optional_domain(domain_code: str) -> Domain | None:
+ return get_interpreter_hub().get_required_domain_library().get_domain(domain_code=domain_code)
+
+
+def get_pipe_library() -> PipeLibraryAbstract:
+ return get_interpreter_hub().get_required_pipe_library()
+
+
+def get_pipes() -> list[PipeAbstract]:
+ return get_interpreter_hub().get_required_pipe_library().get_pipes()
+
+
+def get_required_pipe(pipe_code: str) -> PipeAbstract:
+ return get_interpreter_hub().get_required_pipe_library().get_required_pipe(pipe_code=pipe_code)
+
+
+def get_optional_pipe(pipe_code: str) -> PipeAbstract | None:
+ return get_interpreter_hub().get_required_pipe_library().get_optional_pipe(pipe_code=pipe_code)
+
+
+def get_pipe_source(pipe_code: str) -> str | None:
+ """Get the source identifier for a pipe.
+
+ Args:
+ pipe_code: The pipe code to look up.
+
+ Returns:
+ The source the pipe was loaded from — a filesystem path or a logical URI,
+ preserved verbatim — or None if unknown.
+ """
+ return get_interpreter_hub().get_library_manager().get_pipe_source(pipe_code=pipe_code)
+
+
+def get_concept_library() -> ConceptLibraryAbstract:
+ return get_interpreter_hub().get_library().concept_library
+
+
+def get_required_concept(concept_ref: str) -> Concept:
+ return get_interpreter_hub().get_library().concept_library.get_required_concept(concept_ref=concept_ref)
+
+
+def get_native_concept(native_concept: NativeConceptCode) -> Concept:
+ return get_interpreter_hub().get_required_concept_library().get_native_concept(native_concept=native_concept)
+
+
+# pipe router
+
+
+_current_pipe_router: ContextVar["PipeRouterProtocol | None"] = ContextVar("current_pipe_router", default=None)
+
+
+def set_pipe_router(pipe_router: "PipeRouterProtocol") -> None:
+ """Override the active pipe router for the current async context.
+
+ Used by host runtimes that want controllers to dispatch sub-pipes
+ through their own router (e.g. Mistral Workflows mode swaps in a router
+ that turns sub-pipe calls into child workflows / activities). The
+ override is contextvar-scoped, so concurrent runs on the same hub
+ don't leak into each other. Pass ``None`` via
+ ``teardown_current_pipe_router()`` to restore the hub default.
+ """
+ _current_pipe_router.set(pipe_router)
+
+
+def teardown_current_pipe_router() -> None:
+ """Clear any contextvar-scoped router override set by ``set_pipe_router``."""
+ _current_pipe_router.set(None)
+
+
+@contextmanager
+def scoped_pipe_router(pipe_router: "PipeRouterProtocol") -> Generator[None, None, None]:
+ """Set ``pipe_router`` as the active router for the scope, then restore the prior value on exit.
+
+ Captures the prior ``_current_pipe_router`` ContextVar value before setting
+ the new one. On exit — success or exception — restores the prior override
+ (or clears it if there wasn't one). Use this whenever a call needs its own
+ router for the *whole* run (root pipe + nested controller sub-pipes, which
+ resolve :func:`get_pipe_router`) without clobbering an outer caller's
+ override. Mirrors :func:`scoped_current_library`.
+
+ Prefer this over the raw ``set_pipe_router`` / ``teardown_current_pipe_router``
+ pair internally: the raw teardown unconditionally resets the override to
+ ``None`` and so does not restore an outer override. The raw pair is kept
+ because our Mistral Workflows plugin depends on it.
+ """
+ prev = _current_pipe_router.get()
+ _current_pipe_router.set(pipe_router)
+ try:
+ yield
+ finally:
+ _current_pipe_router.set(prev)
+
+
+def get_pipe_router() -> "PipeRouterProtocol":
+ override = _current_pipe_router.get()
+ if override is not None:
+ return override
+ return get_interpreter_hub().get_required_pipe_router()
+
+
+# pipe func
+
+
+_pipe_func_executor_override: ContextVar[PipeFuncExecutorProtocol | None] = ContextVar("pipe_func_executor_override", default=None)
+
+
+@contextmanager
+def scoped_pipe_func_executor(pipe_func_executor: PipeFuncExecutorProtocol) -> Generator[None, None, None]:
+ """Set ``pipe_func_executor`` as the active executor for the scope, then restore the prior value on exit.
+
+ The PipeFunc counterpart of :func:`pipelex.runtime_hub.scoped_content_generator`: in a process
+ whose hub default executor dispatches PipeFunc steps out-of-process (a distributed-orchestrator
+ worker), this scope lets an in-process run force a specific executor — e.g. the local one, so
+ its PipeFunc steps run here instead of being re-dispatched. ContextVar-scoped like
+ :func:`scoped_pipe_router`, so concurrent runs never cross-contaminate.
+ """
+ prev = _pipe_func_executor_override.get()
+ _pipe_func_executor_override.set(pipe_func_executor)
+ try:
+ yield
+ finally:
+ _pipe_func_executor_override.set(prev)
+
+
+def get_pipe_func_executor() -> PipeFuncExecutorProtocol:
+ override = _pipe_func_executor_override.get()
+ if override is not None:
+ return override
+ return get_interpreter_hub().get_required_pipe_func_executor()
+
+
+def get_pipe_func_executor_registry() -> "PipeFuncExecutorRegistry":
+ return get_interpreter_hub().get_pipe_func_executor_registry()
+
+
+# run
+
+
+def get_pipe_run() -> "PipeRunProtocol":
+ return get_interpreter_hub().get_required_pipe_run()
+
+
+def get_pipeline_manager() -> PipelineManagerAbstract:
+ return get_interpreter_hub().get_required_pipeline_manager()
+
+
+def get_pipeline(pipeline_run_id: str) -> Pipeline:
+ return get_pipeline_manager().get_pipeline(pipeline_run_id=pipeline_run_id)
diff --git a/pipelex/kit/configs/inference/backends/pipelex_gateway_models.md b/pipelex/kit/configs/inference/backends/pipelex_gateway_models.md
index 99d8f2a01..645adda83 100644
--- a/pipelex/kit/configs/inference/backends/pipelex_gateway_models.md
+++ b/pipelex/kit/configs/inference/backends/pipelex_gateway_models.md
@@ -101,6 +101,14 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
<td style="text-align:center;background-color:rgba(76,175,80,0.15)">✅</td>
</tr>
<tr>
+<td>claude-5-sonnet</td>
+<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(76,175,80,0.15)">✅</td>
+<td style="text-align:center;background-color:rgba(76,175,80,0.15)">✅</td>
+</tr>
+<tr>
<td>deepseek-v3.2</td>
<td style="text-align:center;background-color:rgba(33,150,243,0.15)">✅</td>
<td style="text-align:center;background-color:rgba(33,150,243,0.15)">❌</td>
@@ -612,6 +620,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
> **AUTO-GENERATED FILE** - Do not edit manually.
-> Last updated: 2026-07-06T14:28:01Z
+> Last updated: 2026-07-27T01:18:06Z
>
> Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.
\ No newline at end of file
diff --git a/pipelex/kit/configs/inference/backends/pipelex_gateway_models_plain.md b/pipelex/kit/configs/inference/backends/pipelex_gateway_models_plain.md
index 9ba8afa22..45ceaff0e 100644
--- a/pipelex/kit/configs/inference/backends/pipelex_gateway_models_plain.md
+++ b/pipelex/kit/configs/inference/backends/pipelex_gateway_models_plain.md
@@ -37,6 +37,9 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
- **claude-4.8-opus**
- inputs: text, images, pdf
- outputs: text, structured
+- **claude-5-sonnet**
+ - inputs: text, images, pdf
+ - outputs: text, structured
- **deepseek-v3.2**
- inputs: text
- outputs: text, structured
@@ -229,6 +232,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
> **AUTO-GENERATED FILE** - Do not edit manually.
-> Last updated: 2026-07-06T14:28:01Z
+> Last updated: 2026-07-27T01:18:06Z
>
> Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.
\ No newline at end of file
diff --git a/pipelex/libraries/concept/concept_library_abstract.py b/pipelex/libraries/concept/concept_library_abstract.py
index 51d6a5f57..92273733c 100644
--- a/pipelex/libraries/concept/concept_library_abstract.py
+++ b/pipelex/libraries/concept/concept_library_abstract.py
@@ -1,10 +1,17 @@
-from abc import ABC, abstractmethod
+from abc import abstractmethod
from pipelex.core.concepts.concept import Concept
-from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
-class ConceptLibraryAbstract(ABC):
+class ConceptLibraryAbstract(ConceptProviderAbstract):
+ """A loaded method's concept library: resolution (inherited) plus the management half.
+
+ The resolution methods live on :class:`ConceptProviderAbstract` in `core/`, so a core module can
+ depend on resolution alone. Everything below is library management and stays here, in the
+ interpreter layer.
+ """
+
@abstractmethod
def add_new_concept(self, concept: Concept) -> None:
pass
@@ -25,14 +32,6 @@ class ConceptLibraryAbstract(ABC):
def list_concepts(self) -> list[Concept]:
pass
- @abstractmethod
- def get_required_concept(self, concept_ref: str) -> Concept:
- pass
-
- @abstractmethod
- def is_compatible(self, *, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:
- pass
-
@abstractmethod
def setup(self) -> None:
pass
@@ -44,11 +43,3 @@ class ConceptLibraryAbstract(ABC):
@abstractmethod
def teardown(self) -> None:
pass
-
- @abstractmethod
- def get_native_concept(self, native_concept: NativeConceptCode) -> Concept:
- pass
-
- @abstractmethod
- def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, *, search_domain_codes: list[str] | None = None) -> Concept:
- pass
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index 35e52038f..722549256 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -29,7 +29,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.validation import report_validation_error
-from pipelex.hub import get_class_registry, get_current_library, get_current_library_id_or_none, scoped_current_library
+from pipelex.interpreter_hub import get_current_library, get_current_library_id_or_none, scoped_current_library
from pipelex.libraries.collision_messages import duplicate_ref_msg
from pipelex.libraries.concept.exceptions import ConceptLibraryError
from pipelex.libraries.concept_reference_validation import validate_concept_references_in_blueprints
@@ -47,6 +47,7 @@ from pipelex.libraries.library_utils import (
)
from pipelex.libraries.pipe.exceptions import PipeLibraryError
from pipelex.libraries.visibility_utils import check_visibility_for_blueprints, make_visibility_checker
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
from pipelex.system.registries.func_registry_utils import FuncRegistryUtils
from pipelex.tools.misc.semver import SemVerError, parse_constraint, parse_version, version_satisfies
diff --git a/pipelex/libraries/pipe/pipe_library_abstract.py b/pipelex/libraries/pipe/pipe_library_abstract.py
index 6764e1339..a96b835d3 100644
--- a/pipelex/libraries/pipe/pipe_library_abstract.py
+++ b/pipelex/libraries/pipe/pipe_library_abstract.py
@@ -4,6 +4,20 @@ from pipelex.core.pipes.pipe_abstract import PipeAbstract
class PipeLibraryAbstract(ABC):
+ """A loaded method's pipe library: pipe resolution plus the management half.
+
+ There is deliberately no read-side `PipeProviderAbstract` in `core/` mirroring
+ :class:`~pipelex.core.concepts.concept_provider_abstract.ConceptProviderAbstract`: no core module
+ takes pipe resolution as a parameter. The two places that follow a pipe reference found *inside* a
+ pipe graph — a condition's mapped pipes and a sequence's last step, both in
+ `core/pipes/rendering/` — are interpreter-layer and call `interpreter_hub.get_required_pipe`
+ directly. Split the read half out if and when a runtime-layer caller needs it.
+ """
+
+ @abstractmethod
+ def get_required_pipe(self, pipe_code: str) -> PipeAbstract:
+ """Resolve a pipe code, raising when it is not known."""
+
@abstractmethod
def setup(self) -> None:
pass
@@ -17,10 +31,6 @@ class PipeLibraryAbstract(ABC):
self.teardown()
self.setup()
- @abstractmethod
- def get_required_pipe(self, pipe_code: str) -> PipeAbstract:
- pass
-
@abstractmethod
def get_optional_pipe(self, pipe_code: str) -> PipeAbstract | None:
pass
diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.py
index 42f3b224c..d23bd695c 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch.py
@@ -14,12 +14,12 @@ from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.graph.graph_tracer_manager import GraphTracerManager
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.async_utils import gather_bounded
from pipelex.urls import URLs
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index c79f30f39..8f41b18b0 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -3,7 +3,6 @@ from typing import TYPE_CHECKING, Any, Literal
from typing_extensions import override
from pipelex import log
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_rendering import render_template
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
@@ -13,15 +12,16 @@ 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.template_guard_lint import lint_optional_input_guards
-from pipelex.hub import get_optional_pipe, get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_optional_pipe, get_pipe_router, get_required_pipe
from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.py
index 319ae18c5..b2df75421 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py
@@ -22,7 +22,7 @@ from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.graph.graph_tracer_manager import GraphTracerManager
from pipelex.graph.graphspec import IOSpec
-from pipelex.hub import get_optional_pipe, get_required_pipe
+from pipelex.interpreter_hub import get_optional_pipe, get_required_pipe
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_controllers.absence_taint import (
ForceConsumptionInfo,
@@ -36,7 +36,7 @@ from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.pipe_controllers.sub_pipe import SubPipe
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
diff --git a/pipelex/pipe_controllers/pipe_controller.py b/pipelex/pipe_controllers/pipe_controller.py
index 40dcc20b3..afe179792 100644
--- a/pipelex/pipe_controllers/pipe_controller.py
+++ b/pipelex/pipe_controllers/pipe_controller.py
@@ -7,7 +7,7 @@ from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.py
index 056772726..c337e0e75 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py
@@ -12,7 +12,7 @@ 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 PresenceMarker, is_multiplicity_compatible
from pipelex.core.qualified_ref import QualifiedRef
-from pipelex.hub import get_concept_library, get_optional_pipe, get_required_pipe
+from pipelex.interpreter_hub import get_concept_library, get_optional_pipe, get_required_pipe
from pipelex.pipe_controllers.absence_taint import (
ForceConsumptionInfo,
LiftableStepInfo,
@@ -26,7 +26,7 @@ from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.pipe_controllers.sequence.exceptions import PipeSequenceValueError
from pipelex.pipe_controllers.sub_pipe import SubPipe
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
diff --git a/pipelex/pipe_controllers/sub_pipe.py b/pipelex/pipe_controllers/sub_pipe.py
index 3661e7919..34a0cec0f 100644
--- a/pipelex/pipe_controllers/sub_pipe.py
+++ b/pipelex/pipe_controllers/sub_pipe.py
@@ -12,13 +12,13 @@ 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.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
diff --git a/pipelex/pipe_operators/compose/construct_blueprint.py b/pipelex/pipe_operators/compose/construct_blueprint.py
index e134e8157..b5b9e643e 100644
--- a/pipelex/pipe_operators/compose/construct_blueprint.py
+++ b/pipelex/pipe_operators/compose/construct_blueprint.py
@@ -13,11 +13,11 @@ from typing import Any, Self, cast
from pydantic import BaseModel, ConfigDict, SerializationInfo, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validator
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.pipe_operators.compose.exceptions import ConstructFieldBlueprintTypeError, ConstructFieldBlueprintValueError
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+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/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index 654a21c08..00d652df0 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -5,10 +5,8 @@ from typing_extensions import override
from pipelex import log
from pipelex.cogt.content_generation.dry_run_factory import DryRunFactory
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
from pipelex.cogt.templating.template_rendering import render_template
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.config import get_config
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
@@ -20,16 +18,19 @@ from pipelex.core.pipes.template_guard_lint import lint_optional_input_guards
from pipelex.core.stuffs.html_content import HtmlContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_class_registry, get_concept_library, get_native_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprint
from pipelex.pipe_operators.compose.exceptions import PipeComposeError, StructuredContentComposerValueError
from pipelex.pipe_operators.compose.structured_content_composer import StructuredContentComposer
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.tools.templating.templating_style import TemplatingStyle
class PipeComposeOutput(PipeOutput):
diff --git a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
index e8447f300..da82a7b96 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
@@ -5,16 +5,16 @@ from typing_extensions import override
from pipelex.cogt.templating.exceptions import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicity
from pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprint
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
from pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsing
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.tools.templating.templating_style import TemplatingStyle
class PipeComposeBlueprint(PipeBlueprint):
diff --git a/pipelex/pipe_operators/compose/structured_content_composer.py b/pipelex/pipe_operators/compose/structured_content_composer.py
index d68c9895d..8ea104b31 100644
--- a/pipelex/pipe_operators/compose/structured_content_composer.py
+++ b/pipelex/pipe_operators/compose/structured_content_composer.py
@@ -5,7 +5,6 @@ from typing import Any, NamedTuple, TypeAlias, cast, get_args, get_origin
from pydantic import ValidationError
from pipelex import log
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_rendering import render_template
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.stuffs.date_content import DateContent
@@ -21,6 +20,7 @@ from pipelex.pipe_operators.compose.exceptions import (
StructuredContentComposerValueError,
)
from pipelex.pipe_run.pipe_run_params import PipeRunParams
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.typing.annotation_utils import unwrap_optional
from pipelex.tools.typing.class_utils import are_classes_equivalent
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
diff --git a/pipelex/pipe_operators/extract/pipe_extract.py b/pipelex/pipe_operators/extract/pipe_extract.py
index d0d0abd20..35bddbd2c 100644
--- a/pipelex/pipe_operators/extract/pipe_extract.py
+++ b/pipelex/pipe_operators/extract/pipe_extract.py
@@ -15,15 +15,11 @@ from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import (
- get_concept_library,
- get_content_generator,
- get_model_deck,
- get_native_concept,
-)
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_content_generator, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.core.stuffs.page_content import PageContent
diff --git a/pipelex/pipe_operators/extract/pipe_extract_factory.py b/pipelex/pipe_operators/extract/pipe_extract_factory.py
index 0ba25a202..16aeddc77 100644
--- a/pipelex/pipe_operators/extract/pipe_extract_factory.py
+++ b/pipelex/pipe_operators/extract/pipe_extract_factory.py
@@ -6,7 +6,7 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactoryProtocol
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
-from pipelex.hub import get_concept_library, get_native_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_operators.extract.exceptions import PipeExtractFactoryError
from pipelex.pipe_operators.extract.pipe_extract import PipeExtract
from pipelex.pipe_operators.extract.pipe_extract_blueprint import PipeExtractBlueprint
diff --git a/pipelex/pipe_operators/func/direct_pipe_func_executor.py b/pipelex/pipe_operators/func/direct_pipe_func_executor.py
index 2ed9c1ced..fbb78c7cd 100644
--- a/pipelex/pipe_operators/func/direct_pipe_func_executor.py
+++ b/pipelex/pipe_operators/func/direct_pipe_func_executor.py
@@ -17,13 +17,13 @@ from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.pipe_operators.func.exceptions import PipeFuncExecutionError
from pipelex.pipe_operators.func.pipe_func_execution_dtos import PipeFuncExecutionRequest, PipeFuncExecutionResponse
from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutionResult, PipeFuncExecutorProtocol
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.runtime_bridge.primitives.rehydration import rehydrate_library_and_memory
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
from pipelex.system.registries.func_registry import func_registry
from pipelex.system.registries.func_registry_utils import FuncRegistryUtils
diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.py
index 9f6a38620..b39d199bf 100644
--- a/pipelex/pipe_operators/func/pipe_func.py
+++ b/pipelex/pipe_operators/func/pipe_func.py
@@ -14,11 +14,12 @@ from pipelex.core.pipes.pipe_output import PipeOutput
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.hub import get_class_registry, get_pipe_func_executor
+from pipelex.interpreter_hub import get_pipe_func_executor
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
diff --git a/pipelex/pipe_operators/func/pipe_func_execution_dtos.py b/pipelex/pipe_operators/func/pipe_func_execution_dtos.py
index 78ff026b0..768bce4f9 100644
--- a/pipelex/pipe_operators/func/pipe_func_execution_dtos.py
+++ b/pipelex/pipe_operators/func/pipe_func_execution_dtos.py
@@ -4,7 +4,7 @@ from pydantic import BaseModel, ConfigDict, Field
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
# The serialization-only transport DTOs for out-of-process PipeFunc execution. Deliberately a LEAF
# module — it imports only pure data types (no hub, no protocol, no builder), so the executor protocol
diff --git a/pipelex/pipe_operators/func/pipe_func_execution_transport.py b/pipelex/pipe_operators/func/pipe_func_execution_transport.py
index 50cc26719..e542d53bb 100644
--- a/pipelex/pipe_operators/func/pipe_func_execution_transport.py
+++ b/pipelex/pipe_operators/func/pipe_func_execution_transport.py
@@ -1,5 +1,5 @@
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.hub import get_current_library, get_library_manager
+from pipelex.interpreter_hub import get_current_library, get_library_manager
from pipelex.pipe_operators.func.exceptions import PipeFuncTransportError
from pipelex.pipe_operators.func.pipe_func_execution_dtos import (
DEFAULT_PIPE_FUNC_TIMEOUT_SECONDS,
@@ -8,8 +8,8 @@ from pipelex.pipe_operators.func.pipe_func_execution_dtos import (
)
from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutionResult
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.runtime_bridge.primitives.hydration import hydrate_working_memory
+from pipelex.system.job_metadata import JobMetadata
# The transport DTOs (``PipeFuncExecutionRequest`` / ``PipeFuncExecutionResponse``) live in the leaf
# ``pipe_func_execution_dtos`` module so the executor protocol can reference them without a hub cycle;
diff --git a/pipelex/pipe_operators/func/pipe_func_executor_protocol.py b/pipelex/pipe_operators/func/pipe_func_executor_protocol.py
index ade57257f..fb70a98f3 100644
--- a/pipelex/pipe_operators/func/pipe_func_executor_protocol.py
+++ b/pipelex/pipe_operators/func/pipe_func_executor_protocol.py
@@ -5,7 +5,7 @@ from pydantic import BaseModel, ConfigDict
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
# Import from the LEAF dtos module (not the transport builder module, which reaches the hub) so the
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index 3a4d96af6..65d0d941e 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -23,13 +23,14 @@ from pipelex.core.stuffs.exceptions import StuffContentTypeError
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.hub import get_class_registry, get_concept_library, get_content_generator, get_model_deck, get_native_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_operators.img_gen.exceptions import PipeImgGenFactoryError, PipeImgGenRunError
from pipelex.pipe_operators.img_gen.img_gen_prompt_blueprint import ImgGenPromptBlueprint, ImgGenPromptBlueprintValueError
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.exceptions import PipeRunParamsError
from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_to_apply
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.image_utils import ImageFormat
if TYPE_CHECKING:
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
index e77772d65..bb7f02191 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
@@ -7,12 +7,12 @@ from pipelex.cogt.image.image_size import ImageSize
from pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, Background, ImgGenSize, SizeTier
from pipelex.cogt.img_gen.img_gen_setting import ImgGenModelChoice
from pipelex.cogt.templating.exceptions import TemplateSigilSyntaxError
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
from pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsing
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.image_utils import ImageFormat
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
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 8466998d6..e9ba42b7d 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
@@ -3,7 +3,6 @@ from typing import TYPE_CHECKING, Any
from typing_extensions import override
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactoryProtocol
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
@@ -12,6 +11,7 @@ from pipelex.pipe_operators.img_gen.img_gen_prompt_blueprint import ImgGenPrompt
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.template_image_analyzer import TemplateImageAnalyzer
+from pipelex.tools.jinja2.template_category import TemplateCategory
if TYPE_CHECKING:
from pipelex.pipe_operators.shared.image_reference import ImageReference
diff --git a/pipelex/pipe_operators/llm/helpers.py b/pipelex/pipe_operators/llm/helpers.py
index 55c5e2beb..7dc01e821 100644
--- a/pipelex/pipe_operators/llm/helpers.py
+++ b/pipelex/pipe_operators/llm/helpers.py
@@ -1,11 +1,9 @@
-from pipelex.cogt.templating.template_category import TemplateCategory
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.hub import (
- get_class_registry,
- get_required_concept,
-)
+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
diff --git a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
index a2be1913b..24458a952 100644
--- a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
+++ b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
@@ -9,7 +9,6 @@ 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.cogt.templating.templating_style import TemplatingStyle
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
@@ -21,6 +20,7 @@ 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
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index c0b1ca834..ae87f51a3 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -28,14 +28,7 @@ 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.hub import (
- get_class_registry,
- get_concept_library,
- get_content_generator,
- get_model_deck,
- get_native_concept,
- get_required_concept,
-)
+from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept
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
@@ -45,7 +38,8 @@ from pipelex.pipe_run.pipe_run_params import (
PipeRunParams,
output_multiplicity_to_apply,
)
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
diff --git a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
index 0e88a430e..c0604fa0a 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
@@ -6,7 +6,6 @@ from typing_extensions import override
from pipelex.cogt.llm.llm_setting import LLMModelChoice
from pipelex.cogt.templating.exceptions import TemplateSigilSyntaxError
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
@@ -15,6 +14,7 @@ from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multipli
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+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/llm/pipe_llm_factory.py b/pipelex/pipe_operators/llm/pipe_llm_factory.py
index df413c9c9..ecd1001d6 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_factory.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_factory.py
@@ -5,12 +5,11 @@ from typing_extensions import override
from pipelex.cogt.llm.llm_setting import LLMSettingChoices
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactoryProtocol
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import make_variable_multiplicity, parse_concept_with_multiplicity
-from pipelex.hub import get_optional_domain
+from pipelex.interpreter_hub import get_optional_domain
from pipelex.pipe_operators.llm.exceptions import PipeLLMFactoryError
from pipelex.pipe_operators.llm.llm_prompt_blueprint import LLMPromptBlueprint
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
@@ -18,6 +17,7 @@ from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_operators.llm.template_document_analyzer import TemplateDocumentAnalyzer
from pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageAnalyzer
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
+from pipelex.tools.jinja2.template_category import TemplateCategory
class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
diff --git a/pipelex/pipe_operators/llm/template_document_analyzer.py b/pipelex/pipe_operators/llm/template_document_analyzer.py
index 8fa8aa32f..bb0ae74d2 100644
--- a/pipelex/pipe_operators/llm/template_document_analyzer.py
+++ b/pipelex/pipe_operators/llm/template_document_analyzer.py
@@ -5,15 +5,15 @@ to determine which variables reference documents (directly or as lists) and how
should be extracted at runtime.
"""
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
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.pipes.variable_multiplicity import parse_concept_with_multiplicity
-from pipelex.hub import get_native_concept, get_required_concept
+from pipelex.interpreter_hub import get_native_concept, get_required_concept
from pipelex.pipe_operators.llm.document_reference 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/pipe_operator.py b/pipelex/pipe_operators/pipe_operator.py
index 29c7f75e3..d45416e8d 100644
--- a/pipelex/pipe_operators/pipe_operator.py
+++ b/pipelex/pipe_operators/pipe_operator.py
@@ -9,7 +9,7 @@ from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.core.stuffs.list_content import ListContent
diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.py
index 586d65b7e..d0a8c83c9 100644
--- a/pipelex/pipe_operators/search/pipe_search.py
+++ b/pipelex/pipe_operators/search/pipe_search.py
@@ -15,10 +15,10 @@ from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.pipes.template_guard_lint import lint_optional_input_guards
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_content_generator, get_model_deck
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_content_generator, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
diff --git a/pipelex/pipe_operators/search/pipe_search_blueprint.py b/pipelex/pipe_operators/search/pipe_search_blueprint.py
index 90e6fb188..bfae143a3 100644
--- a/pipelex/pipe_operators/search/pipe_search_blueprint.py
+++ b/pipelex/pipe_operators/search/pipe_search_blueprint.py
@@ -6,12 +6,12 @@ from typing_extensions import override
from pipelex.cogt.search.search_setting import SearchModelChoice
from pipelex.cogt.templating.exceptions import TemplateSigilSyntaxError
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
from pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsing
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+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/search/pipe_search_factory.py b/pipelex/pipe_operators/search/pipe_search_factory.py
index b0b168d10..26ddf16c3 100644
--- a/pipelex/pipe_operators/search/pipe_search_factory.py
+++ b/pipelex/pipe_operators/search/pipe_search_factory.py
@@ -3,14 +3,14 @@ from typing import Any
from typing_extensions import override
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactoryProtocol
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
-from pipelex.hub import get_concept_library, get_native_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_operators.search.pipe_search import PipeSearch
from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
+from pipelex.tools.jinja2.template_category import TemplateCategory
class PipeSearchFactory(PipeFactoryProtocol[PipeSearchBlueprint, PipeSearch]):
diff --git a/pipelex/pipe_operators/shared/template_image_analyzer.py b/pipelex/pipe_operators/shared/template_image_analyzer.py
index 88007718d..6ede53331 100644
--- a/pipelex/pipe_operators/shared/template_image_analyzer.py
+++ b/pipelex/pipe_operators/shared/template_image_analyzer.py
@@ -5,17 +5,17 @@ to determine which variables reference images (directly or nested) and how they
should be extracted at runtime.
"""
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
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.pipes.variable_multiplicity import parse_concept_with_multiplicity
-from pipelex.hub import get_native_concept, get_required_concept
+from pipelex.interpreter_hub import get_native_concept, get_required_concept
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
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index 08a41021f..5657525ad 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -7,7 +7,6 @@ from pipelex.cogt.exceptions import LLMCompletionError
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting
from pipelex.cogt.models.model_deck_check import check_llm_choice_with_deck
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_rendering import render_template
from pipelex.config import get_config
from pipelex.core.concepts.native.concept_native import NativeConceptCode
@@ -20,18 +19,14 @@ 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.hub import (
- get_class_registry,
- get_concept_library,
- get_content_generator,
- get_model_deck,
- get_native_concept,
-)
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_operators.llm.helpers import get_output_structure_prompt
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_to_apply
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.template_category import TemplateCategory
class PipeStructureOutput(PipeOutput):
diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.py
index 0350399da..7a9231f9d 100644
--- a/pipelex/pipe_run/delivery_executor.py
+++ b/pipelex/pipe_run/delivery_executor.py
@@ -18,10 +18,10 @@ from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_viewer import render_stuff_viewer
from pipelex.graph.graph_factory import generate_graph_outputs
-from pipelex.hub import get_class_registry, get_storage_provider
from pipelex.pipe_run.exceptions import PipeJobError, StorageDeliveryError, WebhookDeliveryError
from pipelex.reporting.usage_records import dump_tokens_usage_records
from pipelex.runtime_bridge.primitives.hydration import hydrate_content
+from pipelex.runtime_hub import get_class_registry, get_storage_provider
from pipelex.tools.misc.json_utils import clean_json_dumps
from pipelex.tools.network.ssrf_guard import SsrfGuardedTransport
diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.py
index a1b5d68e0..1f89f4d18 100644
--- a/pipelex/pipe_run/dry_run_in_process.py
+++ b/pipelex/pipe_run/dry_run_in_process.py
@@ -18,7 +18,7 @@ from pipelex.config import get_config
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.graph.graph_tracer_manager import GraphTracerManager
from pipelex.graph.graphspec import GraphSpec, GraphSpecMode
-from pipelex.hub import get_library_manager, scoped_content_generator, scoped_event_log, scoped_pipe_router
+from pipelex.interpreter_hub import get_library_manager, scoped_pipe_router
from pipelex.observer.observer_protocol import ObserverNoOp
from pipelex.pipe_run.exceptions import DryRunGraphNotProducedError
from pipelex.pipe_run.pipe_router import PipeRouter
@@ -26,6 +26,7 @@ from pipelex.pipe_run.pipe_run import PipeRun
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.execution_seams import prepare_pipe_job
from pipelex.pipeline.pipeline_factory import PipelineFactory
+from pipelex.runtime_hub import scoped_content_generator, scoped_event_log
from pipelex.system.telemetry.otel_constants import OTelConstants
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
diff --git a/pipelex/pipe_run/pipe_job.py b/pipelex/pipe_run/pipe_job.py
index 7e44dbde9..0883dcd08 100644
--- a/pipelex/pipe_run/pipe_job.py
+++ b/pipelex/pipe_run/pipe_job.py
@@ -7,7 +7,7 @@ from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_run.exceptions import PipeJobError
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class PipeJob(BaseModel):
diff --git a/pipelex/pipe_run/pipe_job_factory.py b/pipelex/pipe_run/pipe_job_factory.py
index 3c7638773..e08f37d3a 100644
--- a/pipelex/pipe_run/pipe_job_factory.py
+++ b/pipelex/pipe_run/pipe_job_factory.py
@@ -5,7 +5,7 @@ from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class PipeJobFactory:
diff --git a/pipelex/pipe_run/pipe_run_params_factory.py b/pipelex/pipe_run/pipe_run_params_factory.py
index c9b7cdf22..2d160e3bc 100644
--- a/pipelex/pipe_run/pipe_run_params_factory.py
+++ b/pipelex/pipe_run/pipe_run_params_factory.py
@@ -4,9 +4,9 @@ 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.hub import is_dry_run_forced
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunParams
+from pipelex.runtime_hub import is_dry_run_forced
class PipeRunParamsFactory:
diff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.py
index 357df0ebe..78da7de26 100644
--- a/pipelex/pipe_run/tracing_assembly.py
+++ b/pipelex/pipe_run/tracing_assembly.py
@@ -19,9 +19,9 @@ from pipelex.base_exceptions import PipelexConfigError
from pipelex.config import get_config
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.graph.graphspec import GraphSpec, PipelineRef
-from pipelex.hub import get_event_log_override
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.reporting.reporting_types import AnyTokensUsage
+from pipelex.runtime_hub import get_event_log_override
from pipelex.system.exceptions import MissingDependencyError
from pipelex.tracing.event_log_factory import make_event_log
from pipelex.tracing.exceptions import EventLogError
diff --git a/pipelex/pipe_signature/pipe_signature.py b/pipelex/pipe_signature/pipe_signature.py
index bf54d2ca0..ab00d8bb0 100644
--- a/pipelex/pipe_signature/pipe_signature.py
+++ b/pipelex/pipe_signature/pipe_signature.py
@@ -10,7 +10,7 @@ from pipelex.core.pipes.pipe_blueprint import PipeType
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/pipelex/pipe_signature/signature_walk.py b/pipelex/pipe_signature/signature_walk.py
index bacb3a874..724871251 100644
--- a/pipelex/pipe_signature/signature_walk.py
+++ b/pipelex/pipe_signature/signature_walk.py
@@ -2,13 +2,13 @@
These two functions walk a pipe's dependency graph to find every reachable signature.
They live outside `PipeAbstract` on purpose: the walk needs `get_optional_pipe` to
-resolve dependency codes to pipes, and `pipe_abstract` importing `pipelex.hub` would
+resolve dependency codes to pipes, and `pipe_abstract` importing `pipelex.interpreter_hub` would
form an import cycle (`pipe_abstract → hub → library → pipe_library → pipe_abstract`).
Keeping the walk here — downstream of `hub` — keeps `pipe_abstract` cycle-free.
"""
from pipelex.core.pipes.pipe_abstract import PipeAbstract
-from pipelex.hub import get_optional_pipe
+from pipelex.interpreter_hub import get_optional_pipe
def collect_signature_refs(pipe: PipeAbstract, *, visited: set[str] | None = None) -> set[str]:
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index a7d8ab389..3f53ba718 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -38,7 +38,7 @@ from pipelex.core.stuffs.stuff_template_set import STUFF_TEMPLATE_SET
from pipelex.core.validation import report_validation_error
from pipelex.graph.mermaidflow.template_set import MERMAID_TEMPLATE_SET
from pipelex.graph.reactflow.template_set import REACTFLOW_TEMPLATE_SET
-from pipelex.hub import PipelexHub, set_pipelex_hub
+from pipelex.interpreter_hub import InterpreterHub, set_interpreter_hub
from pipelex.libraries.library_manager import LibraryManager
from pipelex.libraries.library_manager_abstract import LibraryManagerAbstract
from pipelex.observer.multi_observer import MultiObserver
@@ -62,6 +62,7 @@ from pipelex.plugins.secrets_provider_registry import SecretsProviderRegistry
from pipelex.plugins.storage_provider_registry import StorageProviderRegistry
from pipelex.reporting.reporting_manager import ReportingManager
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import RuntimeHub, set_runtime_hub
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.configuration.config_root import ConfigRoot
from pipelex.system.configuration.configs import PipelexConfig
@@ -76,6 +77,7 @@ from pipelex.system.pipelex_service.pipelex_service_config import (
load_pipelex_service_config_if_exists,
)
from pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcher
+from pipelex.system.registries.class_registry_access import class_registry_scoping
from pipelex.system.registries.func_registry import FuncRegistry, func_registry
from pipelex.system.registries.singleton import MetaSingleton
from pipelex.system.runtime import IntegrationMode, runtime_manager
@@ -117,19 +119,25 @@ class Pipelex(metaclass=MetaSingleton):
self.is_ready: bool = False
self.is_pipelex_service_enabled = False # Will be set during setup
self.config_dir_path = config_dir_path or config_manager.pipelex_config_dir
- self.pipelex_hub = PipelexHub()
- set_pipelex_hub(self.pipelex_hub)
+ # Two hubs, two lifecycles: RuntimeHub is process-scoped infrastructure, InterpreterHub is the
+ # library-scoped method machinery. Runtime is constructed first because it is the lower layer,
+ # so it reads first — not because installing the InterpreterHub needs it: that install only
+ # stores the class-registry scoping resolver, which resolves lazily at call time.
+ self.runtime_hub = RuntimeHub()
+ set_runtime_hub(self.runtime_hub)
+ self.interpreter_hub = InterpreterHub()
+ set_interpreter_hub(self.interpreter_hub)
# tools
try:
- self.pipelex_hub.setup_config(config_cls=config_cls or PipelexConfig, config_overrides=config_overrides)
+ self.runtime_hub.setup_config(config_cls=config_cls or PipelexConfig, config_overrides=config_overrides)
except ValidationError as validation_error:
validation_error_msg = report_validation_error(category="config", validation_error=validation_error)
msg = f"Could not setup config because of: {validation_error_msg}"
raise PipelexConfigError(msg) from validation_error
log_config = get_config().pipelex.log_config
- self.pipelex_hub.set_console_print_target(target=log_config.console_print_target)
+ self.runtime_hub.set_console_print_target(target=log_config.console_print_target)
log.configure(log_config=log_config)
log.verbose("Logs are configured")
@@ -141,7 +149,7 @@ class Pipelex(metaclass=MetaSingleton):
self._plugin_registrar: PluginRegistrar | None = None
# cogt
self.sdk_client_manager = SdkClientManager()
- self.pipelex_hub.set_sdk_client_manager(self.sdk_client_manager)
+ self.runtime_hub.set_sdk_client_manager(self.sdk_client_manager)
self.reporting_delegate: ReportingProtocol | None = None
self.telemetry_manager: TelemetryManagerAbstract | None = None
@@ -304,7 +312,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# The built-in SecretsPlugin supplies the "env" method, so there is no separate core default.
# Resolved here because the telemetry factory just below (and the model setup further down) consume it.
secrets_provider_registry = SecretsProviderRegistry(plugin_registrar.secrets_providers)
- self.pipelex_hub.set_secrets_provider_registry(secrets_provider_registry)
+ self.runtime_hub.set_secrets_provider_registry(secrets_provider_registry)
if secrets_provider is None:
secrets_config = get_config().pipelex.secrets_config
secrets_provider = secrets_provider_registry.get_required(method=secrets_config.method)(secrets_config)
@@ -324,17 +332,16 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
injected_telemetry_manager=telemetry_manager,
)
self.telemetry_manager.setup(integration_mode=integration_mode)
- self.pipelex_hub.set_telemetry_manager(telemetry_manager=self.telemetry_manager)
+ self.runtime_hub.set_telemetry_manager(telemetry_manager=self.telemetry_manager)
# --- Tools ----------------------------------------------------------------------------
self.class_registry = class_registry or ClassRegistry()
- self.pipelex_hub.set_class_registry(self.class_registry)
self.kajson_manager = KajsonManager(class_registry=self.class_registry)
self.func_registry = func_registry or FuncRegistry()
- self.pipelex_hub.set_func_registry(func_registry=self.func_registry)
- self.pipelex_hub.set_secrets_provider(secrets_provider=secrets_provider)
+ self.runtime_hub.set_func_registry(func_registry=self.func_registry)
+ self.runtime_hub.set_secrets_provider(secrets_provider=secrets_provider)
# Storage is selected from the config-driven StorageProviderRegistry, built from the plugin
# registrar (constructed above, just before the telemetry factory). Its resolution and hub-set
# still happen later at the plugin-derived-registries block — after secrets is on the hub here,
@@ -361,15 +368,12 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
)
TemplateLoader.load_all()
- self.library_manager = library_manager or LibraryManager()
- self.pipelex_hub.set_library_manager(library_manager=self.library_manager)
-
# --- AI Models and Inference Management ------------------------------------------------
self.sdk_client_manager.setup()
self.models_manager: ModelManagerAbstract = models_manager or ModelManager()
- self.pipelex_hub.set_models_manager(models_manager=self.models_manager)
+ self.runtime_hub.set_models_manager(models_manager=self.models_manager)
try:
self.models_manager.setup(
@@ -420,23 +424,23 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# accumulated contributions into the hub registries here — after the gateway/model setup checks
# and before the hub setup points below — the family worker factories look their backends up on
# these at run time.
- self.pipelex_hub.set_inference_backend_registry(InferenceBackendRegistry(plugin_registrar.inference_backends))
- self.pipelex_hub.set_model_lister_registry(ModelListerRegistry(plugin_registrar.model_listers))
- self.pipelex_hub.set_orchestrator_registry(OrchestratorRegistry(plugin_registrar.orchestrators))
- self.pipelex_hub.set_bundle_validator_registry(BundleValidatorRegistry(plugin_registrar.bundle_validators))
+ self.runtime_hub.set_inference_backend_registry(InferenceBackendRegistry(plugin_registrar.inference_backends))
+ self.runtime_hub.set_model_lister_registry(ModelListerRegistry(plugin_registrar.model_listers))
+ self.runtime_hub.set_orchestrator_registry(OrchestratorRegistry(plugin_registrar.orchestrators))
+ self.runtime_hub.set_bundle_validator_registry(BundleValidatorRegistry(plugin_registrar.bundle_validators))
storage_provider_registry = StorageProviderRegistry(plugin_registrar.storage_providers)
- self.pipelex_hub.set_storage_provider_registry(storage_provider_registry)
+ self.runtime_hub.set_storage_provider_registry(storage_provider_registry)
pipe_func_executor_registry = PipeFuncExecutorRegistry(plugin_registrar.pipe_func_executors)
- self.pipelex_hub.set_pipe_func_executor_registry(pipe_func_executor_registry)
+ self.interpreter_hub.set_pipe_func_executor_registry(pipe_func_executor_registry)
# Storage provider precedence: explicit setup() param > config-selected registry factory.
# The built-in StoragePlugin supplies every method, so there is no separate core default.
# Resolves here (after secrets is on the hub) so the GCP factory's secret read works.
if storage_provider is None:
storage_config = get_config().pipelex.storage_config
storage_provider = storage_provider_registry.get_required(method=storage_config.method)(storage_config)
- self.pipelex_hub.set_storage_provider(storage_provider)
+ self.runtime_hub.set_storage_provider(storage_provider)
- self.pipelex_hub.set_dry_run_forced(is_forced=not needs_inference)
+ self.runtime_hub.set_dry_run_forced(is_forced=not needs_inference)
# Injection precedence (codex C8): explicit setup() param > plugin slot-claim thunk > core default.
# A boot-orchestrator plugin (Temporal worker) claims the CONTENT_GENERATOR slot; its thunk runs
# only here, never at register, so booting a non-worker process imports no host-runtime SDK.
@@ -445,7 +449,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
slot=HubSlot.CONTENT_GENERATOR,
default=lambda: ContentGenerator(generated_content_factory=GeneratedContentFactory(storage_provider=storage_provider)),
)
- self.pipelex_hub.set_content_generator(content_generator)
+ self.runtime_hub.set_content_generator(content_generator)
# Injection precedence: explicit setup() param > plugin slot-claim thunk > config-selected
# registry factory. The PipeFunc execution axis is orthogonal to orchestration: a Temporal
@@ -460,32 +464,32 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
slot=HubSlot.PIPE_FUNC_EXECUTOR,
default=lambda: pipe_func_executor_registry.get_required(mode=execution_mode)(pipe_func_config),
)
- self.pipelex_hub.set_pipe_func_executor(pipe_func_executor)
+ self.interpreter_hub.set_pipe_func_executor(pipe_func_executor)
self.inference_manager = inference_manager or InferenceManager()
- self.pipelex_hub.set_inference_manager(self.inference_manager)
+ self.runtime_hub.set_inference_manager(self.inference_manager)
# --- Libraries & Registries -------------------------------------------------------------
self.reporting_delegate = reporting_delegate or ReportingManager()
- self.pipelex_hub.set_report_delegate(self.reporting_delegate)
+ self.runtime_hub.set_report_delegate(self.reporting_delegate)
self.reporting_delegate.setup()
self.library_manager = library_manager or LibraryManager()
- self.pipelex_hub.set_library_manager(library_manager=self.library_manager)
+ self.interpreter_hub.set_library_manager(library_manager=self.library_manager)
# Resolve library_dirs: explicit value replaces PIPELEXPATH, otherwise use env var as fallback
# When library_dirs is explicitly provided (even if empty), it overrides the env var
if library_dirs is not None:
resolved_library_dirs = [Path(dir_path) for dir_path in library_dirs]
- self.pipelex_hub.set_default_library_dirs(resolved_library_dirs)
+ self.interpreter_hub.set_default_library_dirs(resolved_library_dirs)
else:
pipelexpath_dirs = get_pipelexpath_dirs()
if pipelexpath_dirs is not None:
- self.pipelex_hub.set_default_library_dirs(pipelexpath_dirs)
+ self.interpreter_hub.set_default_library_dirs(pipelexpath_dirs)
self.pipeline_manager = pipeline_manager or PipelineManager()
- self.pipelex_hub.set_pipeline_manager(pipeline_manager=self.pipeline_manager)
+ self.interpreter_hub.set_pipeline_manager(pipeline_manager=self.pipeline_manager)
self.pipeline_manager.setup()
self.class_registry.register_classes(CoreRegistryModels.get_all_models())
@@ -500,7 +504,6 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
observer_telemetry = ObserverTelemetry(telemetry_manager=self.telemetry_manager)
observers = {"noop": no_op_observer, "telemetry": observer_telemetry}
multi_observer = MultiObserver(observers=observers)
- self.pipelex_hub.set_observer(observer=multi_observer)
# --- Task Manager ----------------------------------------------------------------------
# The TASK_MANAGER slot is claimed only by a boot-orchestrator plugin running this process as
@@ -520,21 +523,23 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# reports "never isolated", so no wiring is needed here.
isolated_execution_probe_factory = plugin_registrar.slot_claims.get(HubSlot.ISOLATED_EXECUTION_PROBE)
if isolated_execution_probe_factory is not None:
- self.pipelex_hub.set_isolated_execution_probe(isolated_execution_probe_factory())
+ self.runtime_hub.set_isolated_execution_probe(isolated_execution_probe_factory())
# --- Pipe Router -----------------------------------------------------------------------
# Injection precedence (codex C8): explicit setup() param > plugin slot-claim thunk > core default.
if pipe_router:
- self.pipelex_hub.set_pipe_router(pipe_router)
+ self.interpreter_hub.set_pipe_router(pipe_router)
else:
- self.pipelex_hub.set_pipe_router(self._resolve_hub_slot(slot=HubSlot.PIPE_ROUTER, default=lambda: PipeRouter(observer=multi_observer)))
+ self.interpreter_hub.set_pipe_router(
+ self._resolve_hub_slot(slot=HubSlot.PIPE_ROUTER, default=lambda: PipeRouter(observer=multi_observer))
+ )
# --- Pipe Run --------------------------------------------------------------------------
# No explicit param for pipe_run: plugin slot-claim thunk > core default.
- self.pipelex_hub.set_pipe_run(
- self._resolve_hub_slot(slot=HubSlot.PIPE_RUN, default=lambda: PipeRun(pipe_router=self.pipelex_hub.get_required_pipe_router()))
+ self.interpreter_hub.set_pipe_run(
+ self._resolve_hub_slot(slot=HubSlot.PIPE_RUN, default=lambda: PipeRun(pipe_router=self.interpreter_hub.get_required_pipe_router()))
)
log.verbose(f"{PACKAGE_NAME} version {PACKAGE_VERSION} setup done")
@@ -582,7 +587,11 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
TemplateRegistry.clear()
log.verbose(f"{PACKAGE_NAME} version {PACKAGE_VERSION} teardown done (except config & logs)")
- self.pipelex_hub.reset_config()
+ # Both hubs release their process-global state: the RuntimeHub drops its config, and the
+ # class-registry scoping resolver the InterpreterHub installed at boot goes back to its unscoped
+ # default so a torn-down library manager can never be reached through it.
+ self.runtime_hub.reset_config()
+ class_registry_scoping.reset()
# Clear the singleton instance from metaclass
if self.__class__ in MetaSingleton.instances:
del MetaSingleton.instances[self.__class__]
@@ -709,7 +718,8 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# partial setup never assigned). Without this the next boot raises "LogConfig is already
# set" and serves a stale, half-populated class registry (the KajsonManager singleton
# ignores a fresh registry once created).
- pipelex_instance.pipelex_hub.reset_config()
+ pipelex_instance.runtime_hub.reset_config()
+ class_registry_scoping.reset()
KajsonManager.teardown()
TemplateLoader.reset()
TemplateRegistry.clear()
diff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.py
index 10762d81e..d553e917c 100644
--- a/pipelex/pipeline/bundle_validator.py
+++ b/pipelex/pipeline/bundle_validator.py
@@ -38,14 +38,12 @@ from pipelex.base_exceptions import PipelexError
from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.config import get_config
from pipelex.core.pipes.pipe_abstract import PipeAbstract
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library,
get_current_library_id_or_none,
get_library_manager,
get_pipe_library,
- get_telemetry_manager,
- scoped_content_generator,
scoped_pipe_router,
set_current_library,
)
@@ -57,6 +55,7 @@ from pipelex.pipe_run.pipe_run import PipeRun
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_job
from pipelex.pipeline.pipeline_factory import PipelineFactory
+from pipelex.runtime_hub import get_telemetry_manager, scoped_content_generator
from pipelex.system.configuration.configs import PipelineExecutionConfig
from pipelex.system.telemetry.events import EventName, EventProperty
from pipelex.system.telemetry.otel_constants import OTelConstants
diff --git a/pipelex/pipeline/dry_run_pipeline.py b/pipelex/pipeline/dry_run_pipeline.py
index 308ac381d..5787d23ff 100644
--- a/pipelex/pipeline/dry_run_pipeline.py
+++ b/pipelex/pipeline/dry_run_pipeline.py
@@ -15,11 +15,11 @@ from pipelex.config import get_config
from pipelex.core.interpreter.exceptions import PipelexInterpreterError
from pipelex.core.interpreter.interpreter import PipelexInterpreter
from pipelex.graph.graphspec import GraphSpec
-from pipelex.hub import scoped_event_log
from pipelex.pipe_run.exceptions import DryRunGraphNotProducedError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.runtime_hub import scoped_event_log
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.py
index 98d1332f9..e6bb81bf5 100644
--- a/pipelex/pipeline/exceptions.py
+++ b/pipelex/pipeline/exceptions.py
@@ -57,10 +57,6 @@ class PipeStackOverflowError(PipelexError):
super().__init__(message)
-class JobMetadataError(PipelexUnexpectedError):
- pass
-
-
class PipelineManagerNotFoundError(PipelexError):
pass
diff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.py
index 94f302740..6de827db5 100644
--- a/pipelex/pipeline/execution_seams.py
+++ b/pipelex/pipeline/execution_seams.py
@@ -30,8 +30,9 @@ from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_abstract import PipeAbstract
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
+ get_concept_library,
get_current_library_id_or_none,
get_library_manager,
resolve_library_dirs,
@@ -44,13 +45,13 @@ from pipelex.pipe_run.pipe_run_params import VariableMultiplicity
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.input_normalizer import normalize_data_urls_to_storage
-from pipelex.pipeline.job_metadata import JobMetadata, OtelContext
from pipelex.system.configuration.configs import PipelineExecutionConfig
+from pipelex.system.job_metadata import JobMetadata, OtelContext
from pipelex.tools.misc.file_utils import reject_bare_str_or_path
if TYPE_CHECKING:
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
- from pipelex.graph.trace_context import TraceContext
+ from pipelex.system.trace_context import TraceContext
def acquire_library(
@@ -201,6 +202,7 @@ async def prepare_pipe_job(
# source the Optionals pass reads below — not the aggregated `needed_inputs()`.
working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(
pipeline_inputs=inputs,
+ concept_provider=get_concept_library(),
input_specs=pipe.inputs,
search_domain_codes=search_domain_codes,
inputs_base_dir=inputs_base_dir,
diff --git a/pipelex/pipeline/fixes/fix_loop.py b/pipelex/pipeline/fixes/fix_loop.py
index e748400e0..c848f3add 100644
--- a/pipelex/pipeline/fixes/fix_loop.py
+++ b/pipelex/pipeline/fixes/fix_loop.py
@@ -36,7 +36,7 @@ from pydantic import BaseModel, ConfigDict, Field
from pipelex.base_exceptions import ValidationErrorItem
from pipelex.config import get_config
from pipelex.core.pipes.pipe_blueprint import SIGNATURE_ONLY_KEYS
-from pipelex.hub import resolve_library_dirs
+from pipelex.interpreter_hub import resolve_library_dirs
from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
from pipelex.pipeline.exceptions import FixTransactionError, FixWriteConflictError, ValidateBundleError
from pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scope
diff --git a/pipelex/pipeline/input_normalizer.py b/pipelex/pipeline/input_normalizer.py
index c0423bdcd..045e3f746 100644
--- a/pipelex/pipeline/input_normalizer.py
+++ b/pipelex/pipeline/input_normalizer.py
@@ -17,8 +17,8 @@ from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.structured_content import StructuredContent
-from pipelex.hub import get_storage_provider
from pipelex.pipeline.exceptions import PipelineInputContentError
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_utils import load_binary_async
from pipelex.tools.misc.filetype_utils import detect_file_type_from_bytes
from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index e3e8798a9..014c17a47 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -7,16 +7,12 @@ from pipelex import log
from pipelex.config import get_config
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.graph.graph_tracer_manager import GraphTracerManager
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
- get_event_log_override,
get_library_manager,
- get_otel_tracer,
get_pipeline_manager,
- get_report_delegate,
get_required_pipe,
- get_telemetry_manager,
set_current_library,
)
from pipelex.pipe_run.pipe_job import PipeJob
@@ -27,9 +23,10 @@ from pipelex.pipe_run.pipe_run_params import (
)
from pipelex.pipeline.exceptions import PipeExecutionError
from pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_job
-from pipelex.pipeline.job_metadata import OtelContext
+from pipelex.runtime_hub import get_event_log_override, get_otel_tracer, get_report_delegate, get_telemetry_manager
from pipelex.system.configuration.configs import PipelineExecutionConfig
from pipelex.system.environment import get_optional_env
+from pipelex.system.job_metadata import OtelContext
from pipelex.system.telemetry.events import EventName, EventProperty
from pipelex.system.telemetry.otel_constants import OTelConstants
from pipelex.system.telemetry.otel_factory import OtelFactory
@@ -37,7 +34,7 @@ from pipelex.tracing.event_log_factory import make_event_log
if TYPE_CHECKING:
from pipelex.core.pipes.pipe_abstract import PipeAbstract
- from pipelex.graph.trace_context import TraceContext
+ from pipelex.system.trace_context import TraceContext
from pipelex.tracing.event_log_protocol import EventLogProtocol
@@ -129,7 +126,7 @@ async def pipeline_run_setup(
Optional inbound ``X-Request-ID`` from the dispatcher (the value the
external HTTP caller can use to correlate every log line and every
``ErrorReport`` back to its originating request). Threaded onto
- :class:`pipelex.pipeline.job_metadata.JobMetadata.request_id` so it
+ :class:`pipelex.system.job_metadata.JobMetadata.request_id` so it
crosses the Temporal serialization boundary intact.
inputs_base_dir:
Directory that bare *relative local* file paths in ``inputs`` resolve against (Smart
diff --git a/pipelex/pipeline/resolve_bundle.py b/pipelex/pipeline/resolve_bundle.py
index a9f9b4343..b635f7aa1 100644
--- a/pipelex/pipeline/resolve_bundle.py
+++ b/pipelex/pipeline/resolve_bundle.py
@@ -20,12 +20,7 @@ from pipelex.base_exceptions import PipelexUnexpectedError
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.core.interpreter.interpreter import PipelexInterpreter
from pipelex.core.qualified_ref import QualifiedRef
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.libraries.crate_normalization import normalize_crate
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe.exceptions import PipeLibraryError
diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.py
index b7a80d180..4da3cc5ed 100644
--- a/pipelex/pipeline/runner.py
+++ b/pipelex/pipeline/runner.py
@@ -18,14 +18,12 @@ from pipelex.base_exceptions import PipelexError
from pipelex.builder.operations.models_ops import ModelCategory, list_models
from pipelex.config import get_config
from pipelex.graph.graph_tracer_manager import GraphTracerManager
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
get_library_manager,
get_pipe_run,
get_pipeline_manager,
- get_report_delegate,
- get_telemetry_manager,
set_current_library,
)
from pipelex.pipe_run.exceptions import PipeRouterError
@@ -33,6 +31,7 @@ from pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionErr
from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRunResultStart, RunState
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
from pipelex.pipeline.validate_in_process import validate_bundles_in_process
+from pipelex.runtime_hub import get_report_delegate, get_telemetry_manager
from pipelex.system.telemetry.events import EventName, EventProperty, Outcome
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
diff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.py
index 751fb8ab2..c936ab641 100644
--- a/pipelex/pipeline/validate_bundle.py
+++ b/pipelex/pipeline/validate_bundle.py
@@ -24,7 +24,7 @@ from pipelex.core.pipes.handle_pipe_errors import (
from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.validation import report_validation_error
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
get_library_manager,
diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.py
index e7b4fdc8c..d33bc05cb 100644
--- a/pipelex/pipeline/validate_in_process.py
+++ b/pipelex/pipeline/validate_in_process.py
@@ -25,12 +25,7 @@ from typing import TYPE_CHECKING
from pipelex import log
from pipelex.base_exceptions import PipelexError, ValidationErrorItem
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
diff --git a/pipelex/pipeline/validation_render.py b/pipelex/pipeline/validation_render.py
index 8d78dbdf0..e73a95bb5 100644
--- a/pipelex/pipeline/validation_render.py
+++ b/pipelex/pipeline/validation_render.py
@@ -31,7 +31,7 @@ from pathlib import Path
from typing import Any, cast
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
-from pipelex.hub import resolve_library_dirs
+from pipelex.interpreter_hub import resolve_library_dirs
from pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scope
from pipelex.tools.misc.string_utils import count_with_noun
diff --git a/pipelex/plugins/anthropic/anthropic_list.py b/pipelex/plugins/anthropic/anthropic_list.py
index 42329f283..58708cdff 100644
--- a/pipelex/plugins/anthropic/anthropic_list.py
+++ b/pipelex/plugins/anthropic/anthropic_list.py
@@ -8,8 +8,8 @@ from rich.table import Table
from pipelex.cli.exceptions import PipelexCLIError
from pipelex.exceptions import MissingDependencyError
-from pipelex.hub import get_console
from pipelex.plugins.model_handle import ModelHandle
+from pipelex.runtime_hub import get_console
if TYPE_CHECKING:
from anthropic.types import ModelInfo
diff --git a/pipelex/plugins/azure_rest/azure_img_gen_worker.py b/pipelex/plugins/azure_rest/azure_img_gen_worker.py
index 4553a84c0..7744c3aae 100644
--- a/pipelex/plugins/azure_rest/azure_img_gen_worker.py
+++ b/pipelex/plugins/azure_rest/azure_img_gen_worker.py
@@ -21,10 +21,10 @@ from pipelex.cogt.inference.transport_retry import request_with_transport_retry
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
from pipelex.config import get_config
-from pipelex.hub import get_models_manager
from pipelex.plugins.azure_rest.azure_exceptions import AzureCredentialsError
from pipelex.plugins.model_handle import ModelHandle
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_models_manager
from pipelex.tools.log.log import log
diff --git a/pipelex/plugins/bedrock/bedrock_list.py b/pipelex/plugins/bedrock/bedrock_list.py
index baf2fde2f..bea0dd594 100644
--- a/pipelex/plugins/bedrock/bedrock_list.py
+++ b/pipelex/plugins/bedrock/bedrock_list.py
@@ -9,8 +9,8 @@ from rich.table import Table
from pipelex.cli.exceptions import PipelexCLIError
from pipelex.config import get_config
from pipelex.exceptions import MissingDependencyError
-from pipelex.hub import get_console
from pipelex.plugins.model_handle import ModelHandle
+from pipelex.runtime_hub import get_console
from pipelex.tools.aws.exceptions import AwsCredentialsError
if TYPE_CHECKING:
diff --git a/pipelex/plugins/gateway/gateway_extract_worker.py b/pipelex/plugins/gateway/gateway_extract_worker.py
index 7ff76ed9e..f9ac9bec8 100644
--- a/pipelex/plugins/gateway/gateway_extract_worker.py
+++ b/pipelex/plugins/gateway/gateway_extract_worker.py
@@ -18,13 +18,13 @@ from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inf
from pipelex.cogt.inference.inference_constants import InferenceOutputType
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.hub import get_storage_provider
from pipelex.plugins.gateway.gateway_completions_factory import GatewayCompletionsFactory
from pipelex.plugins.gateway.gateway_deck import GatewayDeck
from pipelex.plugins.gateway.gateway_factory import GatewayFactory
from pipelex.plugins.gateway.gateway_protocols import GatewayExtractProtocol
from pipelex.plugins.gateway.gateway_search_schemas import GatewayFetchRequestParams
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.uri.uri_resolver import make_base64_url_from_any_uri
diff --git a/pipelex/plugins/gateway/gateway_factory.py b/pipelex/plugins/gateway/gateway_factory.py
index d1cd77286..383959eda 100644
--- a/pipelex/plugins/gateway/gateway_factory.py
+++ b/pipelex/plugins/gateway/gateway_factory.py
@@ -13,12 +13,12 @@ from pipelex.cogt.extract.extract_job import ExtractJob
from pipelex.cogt.img_gen.img_gen_job import ImgGenJob
from pipelex.cogt.inference.inference_constants import InferenceOutputType
from pipelex.cogt.llm.llm_job import LLMJob
-from pipelex.hub import get_telemetry_manager
from pipelex.plugins.gateway.gateway_exceptions import GatewayCredentialsError
from pipelex.plugins.gateway.gateway_protocols import GatewayExtractProtocol
from pipelex.plugins.gateway.gateway_schemas import GatewayExtractRequestParams
from pipelex.plugins.google.google_img_gen_factory import GoogleImgGenFactory
from pipelex.plugins.portkey.portkey_constants import PortkeyHeaderKey
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.telemetry.otel_constants import OTelConstants
if TYPE_CHECKING:
diff --git a/pipelex/plugins/google/google_list.py b/pipelex/plugins/google/google_list.py
index 30b2b80a0..8843e8ef6 100644
--- a/pipelex/plugins/google/google_list.py
+++ b/pipelex/plugins/google/google_list.py
@@ -7,7 +7,7 @@ from rich import box
from rich.table import Table
from pipelex.exceptions import MissingDependencyError
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
if TYPE_CHECKING:
from pipelex.cogt.model_backends.backend import InferenceBackend
diff --git a/pipelex/plugins/linkup/linkup_extract_worker.py b/pipelex/plugins/linkup/linkup_extract_worker.py
index 57e5d7322..82ed0da6b 100644
--- a/pipelex/plugins/linkup/linkup_extract_worker.py
+++ b/pipelex/plugins/linkup/linkup_extract_worker.py
@@ -24,8 +24,8 @@ from pipelex.cogt.inference.error_classify import classify_inference_error
from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.hub import get_secrets_provider
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_secrets_provider
class LinkupExtractWorker(ExtractWorkerAbstract):
diff --git a/pipelex/plugins/linkup/linkup_search_worker.py b/pipelex/plugins/linkup/linkup_search_worker.py
index 56f5daa05..77f069e38 100644
--- a/pipelex/plugins/linkup/linkup_search_worker.py
+++ b/pipelex/plugins/linkup/linkup_search_worker.py
@@ -24,8 +24,8 @@ from pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstract
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.search_result_content import SearchResultContent
-from pipelex.hub import get_secrets_provider
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_secrets_provider
from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
diff --git a/pipelex/plugins/mistral/mistral_list.py b/pipelex/plugins/mistral/mistral_list.py
index af704e9f3..921bedc0b 100644
--- a/pipelex/plugins/mistral/mistral_list.py
+++ b/pipelex/plugins/mistral/mistral_list.py
@@ -7,7 +7,7 @@ from rich import box
from rich.table import Table
from pipelex.exceptions import MissingDependencyError
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
def list_mistral_models(
diff --git a/pipelex/plugins/mistral/mistral_llms.py b/pipelex/plugins/mistral/mistral_llms.py
index 2d57da586..f606f6778 100644
--- a/pipelex/plugins/mistral/mistral_llms.py
+++ b/pipelex/plugins/mistral/mistral_llms.py
@@ -1,8 +1,8 @@
from mistralai.models import Data
-from pipelex.hub import get_models_manager
from pipelex.plugins.mistral.mistral_exceptions import MistralModelListingError
from pipelex.plugins.mistral.mistral_factory import MistralFactory
+from pipelex.runtime_hub import get_models_manager
def mistral_list_available_models() -> list[Data]:
diff --git a/pipelex/plugins/openai/openai_list.py b/pipelex/plugins/openai/openai_list.py
index 20be6e9d1..67b56c5f3 100644
--- a/pipelex/plugins/openai/openai_list.py
+++ b/pipelex/plugins/openai/openai_list.py
@@ -6,9 +6,9 @@ from typing import TYPE_CHECKING
from rich import box
from rich.table import Table
-from pipelex.hub import get_console
from pipelex.plugins.model_handle import ModelHandle
from pipelex.plugins.openai.openai_llms import openai_list_available_models
+from pipelex.runtime_hub import get_console
if TYPE_CHECKING:
from openai.types import Model
diff --git a/pipelex/plugins/pipe_func_executor_registry.py b/pipelex/plugins/pipe_func_executor_registry.py
index 0041d38b3..bf6f3d3a8 100644
--- a/pipelex/plugins/pipe_func_executor_registry.py
+++ b/pipelex/plugins/pipe_func_executor_registry.py
@@ -1,9 +1,18 @@
from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeAlias
-from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutorProtocol
from pipelex.plugins.exceptions import UnknownPipeFuncExecutionModeError
from pipelex.system.configuration.pipe_func_config import PipeFuncConfig
+if TYPE_CHECKING:
+ # Deferred on purpose: the protocol lives under ``pipe_operators`` (the method-interpretation
+ # layer) but this registry is imported from ``pipelex.config``, which the inference layer loads.
+ # A module-level import here would drag the interpreter into every closure that touches
+ # inference — the exact coupling the runtime_hub / interpreter_hub split removes. The underlying
+ # placement inversion (a ``plugins`` module typed by a ``pipe_operators`` protocol) is recorded
+ # in docs/contribute/hub-layering.md as a known inversion.
+ from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutorProtocol
+
# The one in-process execution mode core always owns. Every other mode is a remote/sandbox backend
# contributed by a plugin (e.g. an out-of-tree ``daytona`` backend) and, by the seam's invariant,
# transports the customer's source to run it out-of-process rather than importing it here.
@@ -12,7 +21,7 @@ DIRECT_PIPE_FUNC_EXECUTION_MODE = "direct"
# A plugin's factory for one PipeFunc execution mode: the pipe_func config in, an executor out. The
# whole ``PipeFuncConfig`` (not a pre-resolved value) is passed so a factory can read whatever it
# needs at the boot apply-point, never at registration — mirrors ``StorageProviderFactoryFn``.
-PipeFuncExecutorFactoryFn = Callable[[PipeFuncConfig], PipeFuncExecutorProtocol]
+PipeFuncExecutorFactoryFn: TypeAlias = Callable[[PipeFuncConfig], "PipeFuncExecutorProtocol"]
class PipeFuncExecutorRegistry:
diff --git a/pipelex/plugins/portkey/portkey_factory.py b/pipelex/plugins/portkey/portkey_factory.py
index f30af3987..2f6fac3f2 100644
--- a/pipelex/plugins/portkey/portkey_factory.py
+++ b/pipelex/plugins/portkey/portkey_factory.py
@@ -6,10 +6,10 @@ from portkey_ai import PORTKEY_GATEWAY_URL
from pipelex.cogt.inference.inference_constants import InferenceOutputType
from pipelex.cogt.llm.llm_job import LLMJob
-from pipelex.hub import get_telemetry_manager
from pipelex.plugins.openai.openai_constants import OpenAIBodyKey
from pipelex.plugins.portkey.portkey_constants import PortkeyHeaderKey
from pipelex.plugins.portkey.portkey_exceptions import PortkeyCredentialsError
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.telemetry.otel_constants import OTelConstants
from pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract
diff --git a/pipelex/plugins/pypdfium2/pypdfium2_worker.py b/pipelex/plugins/pypdfium2/pypdfium2_worker.py
index c38964e1a..1edb522fc 100644
--- a/pipelex/plugins/pypdfium2/pypdfium2_worker.py
+++ b/pipelex/plugins/pypdfium2/pypdfium2_worker.py
@@ -13,8 +13,8 @@ from pipelex.cogt.inference.error_classify import classify_inference_error
from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error
from pipelex.cogt.inference.provider_name import ProviderName
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
-from pipelex.hub import get_storage_provider
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx
from pipelex.tools.pdf.pypdfium2_renderer import PdfInput, pypdfium2_renderer
from pipelex.tools.uri.resolved_uri import (
diff --git a/pipelex/plugins/storage/storage_plugin.py b/pipelex/plugins/storage/storage_plugin.py
index bd7141088..114059f76 100644
--- a/pipelex/plugins/storage/storage_plugin.py
+++ b/pipelex/plugins/storage/storage_plugin.py
@@ -1,9 +1,9 @@
from pathlib import Path
from pipelex import log
-from pipelex.hub import get_secrets_provider
from pipelex.plugins.contract import PLUGIN_API_VERSION
from pipelex.plugins.registrar import PluginRegistrar
+from pipelex.runtime_hub import get_secrets_provider
from pipelex.tools.storage.exceptions import StorageConfigError
from pipelex.tools.storage.gcp_storage_provider import GcpStorageProvider
from pipelex.tools.storage.in_memory_storage_provider import InMemoryStorageProvider
diff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.py
index 0ddc53fe1..5b6a60d12 100644
--- a/pipelex/reporting/reporting_manager.py
+++ b/pipelex/reporting/reporting_manager.py
@@ -11,11 +11,11 @@ from pipelex.cogt.inference.inference_job_abstract import InferenceJobAbstract
from pipelex.cogt.llm.llm_job import LLMJob
from pipelex.cogt.search.search_job import SearchJob
from pipelex.config import get_config
-from pipelex.graph.trace_context import TraceContext
-from pipelex.hub import is_in_isolated_execution
from pipelex.reporting.reporting_protocol import ReportingProtocol
from pipelex.reporting.reporting_types import AnyTokensUsage
+from pipelex.runtime_hub import is_in_isolated_execution
from pipelex.system.exceptions import MissingDependencyError
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.activity_event_log import ActivityEventLogCache
from pipelex.tracing.event_log_protocol import EventLogProtocol
from pipelex.tracing.trace_events import UsageReportEvent
diff --git a/pipelex/runtime_bridge/direct_orchestrator.py b/pipelex/runtime_bridge/direct_orchestrator.py
index 37f72ffff..0b7bc07fd 100644
--- a/pipelex/runtime_bridge/direct_orchestrator.py
+++ b/pipelex/runtime_bridge/direct_orchestrator.py
@@ -10,7 +10,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING
-from pipelex.hub import scoped_pipe_router
+from pipelex.interpreter_hub import scoped_pipe_router
from pipelex.pipe_run.pipe_router import PipeRouter
from pipelex.pipe_run.pipe_run import PipeRun
from pipelex.runtime_bridge.exceptions import PipelexBridgeDispatchError
diff --git a/pipelex/runtime_bridge/primitives/hydration.py b/pipelex/runtime_bridge/primitives/hydration.py
index 12a5830dd..6a6921508 100644
--- a/pipelex/runtime_bridge/primitives/hydration.py
+++ b/pipelex/runtime_bridge/primitives/hydration.py
@@ -12,8 +12,8 @@ from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_content_factory import StuffContentFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry
from pipelex.pipe_run.exceptions import PipeJobError
+from pipelex.runtime_hub import get_class_registry
def _validate_as_known_class(*, item_class: type[StuffContent], raw_item: StuffContent | dict[str, Any]) -> StuffContent:
diff --git a/pipelex/runtime_bridge/primitives/rehydration.py b/pipelex/runtime_bridge/primitives/rehydration.py
index 336efc3d2..58be5537e 100644
--- a/pipelex/runtime_bridge/primitives/rehydration.py
+++ b/pipelex/runtime_bridge/primitives/rehydration.py
@@ -4,7 +4,7 @@ from kajson.class_registry import ClassRegistry
from kajson.kajson_manager import KajsonManager
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.hub import get_library_manager, set_current_library
+from pipelex.interpreter_hub import get_library_manager, set_current_library
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.runtime_bridge.primitives.hydration import hydrate_working_memory
diff --git a/pipelex/hub.py b/pipelex/runtime_hub.py
similarity index 52%
rename from pipelex/hub.py
rename to pipelex/runtime_hub.py
index 4e6fd0801..02f910112 100644
--- a/pipelex/hub.py
+++ b/pipelex/runtime_hub.py
@@ -1,12 +1,27 @@
+"""The runtime layer's dependency hub: process-scoped infrastructure services.
+
+``RuntimeHub`` brokers everything that is configured once at boot and never varies per method:
+config, console, secrets, storage, telemetry, the model deck and inference workers, the content
+generator, the reporting delegate, and the plugin registries. That is the machinery present at
+execution time whatever is loaded — hence *runtime*, in the language-implementation sense.
+
+**The one rule:** ``interpreter_hub`` imports ``runtime_hub``; ``runtime_hub`` must never import
+``interpreter_hub``. Nothing here may name ``libraries``, ``pipe_operators``, ``pipe_controllers``,
+``codegen``, ``builder``, ``core.bundles``, ``core.interpreter``, or the Pipe-touching modules of
+``core.pipes`` at module level — that is what makes importing the Pipelex runtime load zero
+interpreter modules. Core's data model is *not* on that list: ``core.concepts`` and its siblings are
+declared runtime-layer packages, and this module's own closure runs straight through them. See
+``docs/contribute/hub-layering.md``.
+"""
+
import sys
-from collections.abc import Callable, Generator, Sequence
+from collections.abc import Callable, Generator
from contextlib import contextmanager
from contextvars import ContextVar
from pathlib import Path
from typing import TYPE_CHECKING, Any, ClassVar, Optional
from kajson.class_registry_abstract import ClassRegistryAbstract
-from kajson.kajson_manager import KajsonManager
from rich.console import Console
from pipelex import log
@@ -19,28 +34,14 @@ from pipelex.cogt.inference.inference_manager_protocol import InferenceManagerPr
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
from pipelex.cogt.models.model_deck import ModelDeck
from pipelex.cogt.models.model_manager_abstract import ModelManagerAbstract
-from pipelex.core.concepts.concept import Concept
-from pipelex.core.concepts.native.concept_native import NativeConceptCode
-from pipelex.core.domains.domain import Domain
-from pipelex.core.pipes.pipe_abstract import PipeAbstract
-from pipelex.libraries.concept.concept_library_abstract import ConceptLibraryAbstract
-from pipelex.libraries.domain.domain_library_abstract import DomainLibraryAbstract
-from pipelex.libraries.library import Library
-from pipelex.libraries.library_manager_abstract import LibraryManagerAbstract
-from pipelex.libraries.pipe.pipe_library_abstract import PipeLibraryAbstract
-from pipelex.observer.observer_protocol import ObserverProtocol
-from pipelex.pipe_operators.func.pipe_func_executor_protocol import PipeFuncExecutorProtocol
-from pipelex.pipeline.pipeline import Pipeline
-from pipelex.pipeline.pipeline_manager_abstract import PipelineManagerAbstract
from pipelex.plugins.sdk_client_manager import SdkClientManager
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.environment import PIPELEXPATH_ENV_KEY, get_pipelexpath_dirs
+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
-from pipelex.tools.misc.file_utils import reject_bare_str_or_path
from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract
@@ -48,13 +49,10 @@ if TYPE_CHECKING:
# Deferred import: avoid pulling heavy SDK at module-load time
from opentelemetry.trace import Tracer as OTelTracer
- from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocol
- from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
from pipelex.plugins.bundle_validator_registry import BundleValidatorRegistry
from pipelex.plugins.inference_backend_registry import InferenceBackendRegistry
from pipelex.plugins.model_lister_registry import ModelListerRegistry
from pipelex.plugins.orchestrator_registry import OrchestratorRegistry
- from pipelex.plugins.pipe_func_executor_registry import PipeFuncExecutorRegistry
from pipelex.plugins.secrets_provider_registry import SecretsProviderRegistry
from pipelex.plugins.storage_provider_registry import StorageProviderRegistry
from pipelex.tracing.event_log_protocol import EventLogProtocol
@@ -69,20 +67,22 @@ def _never_in_isolated_execution() -> bool:
return False
-class PipelexHub:
- """PipelexHub serves as a central dependency manager to break cyclic imports between components.
- It provides access to core providers and factories through a singleton instance,
- allowing components to retrieve dependencies based on protocols without direct imports that could create cycles.
+class RuntimeHub:
+ """Central dependency manager for process-scoped infrastructure services.
+
+ Provides access to core providers and factories through a singleton instance, allowing
+ components to retrieve dependencies based on protocols without direct imports that could
+ create cycles. Its counterpart for method-scoped machinery (libraries, router, pipeline) is
+ ``pipelex.interpreter_hub.InterpreterHub``.
"""
- _instance: ClassVar[Optional["PipelexHub"]] = None
+ _instance: ClassVar[Optional["RuntimeHub"]] = None
def __init__(self):
# tools
self._config: ConfigRoot | None = None
self._console: Console | None = None
self._secrets_provider: SecretsProviderAbstract | None = None
- self._class_registry: ClassRegistryAbstract | None = None
self._storage_provider: StorageProviderAbstract | None = None
self._telemetry_manager: TelemetryManagerAbstract | None = None
self._func_registry: FuncRegistry | None = None
@@ -95,52 +95,37 @@ class PipelexHub:
self._bundle_validator_registry: BundleValidatorRegistry | None = None
self._storage_provider_registry: StorageProviderRegistry | None = None
self._secrets_provider_registry: SecretsProviderRegistry | None = None
- self._pipe_func_executor_registry: PipeFuncExecutorRegistry | None = None
self._inference_manager: InferenceManagerProtocol
self._report_delegate: ReportingProtocol
self._content_generator: ContentGeneratorProtocol | None = None
- self._pipe_func_executor: PipeFuncExecutorProtocol | None = None
# Keyless boot (``Pipelex.make(needs_inference=False)``) forces every run to DRY (eng
# review D4): the backend still picks inline vs in-workflow on its own; the leaf mocks.
# Consumed by ``PipeRunParamsFactory.make_run_params`` (the single writer of run_mode).
self._is_dry_run_forced: bool = False
-
- # pipelex
- self._library_manager: LibraryManagerAbstract | None = None
- self._default_library_dirs: list[Path] | None = None
- self._domain_library: DomainLibraryAbstract | None = None
- self._concept_library: ConceptLibraryAbstract | None = None
- self._pipe_library: PipeLibraryAbstract | None = None
- self._pipe_router: PipeRouterProtocol | None = None
- self._pipe_run: PipeRunProtocol | None = None
# Ambient probe claimed by a boot-orchestrator plugin (ISOLATED_EXECUTION_PROBE): True when
# the current call runs inside an isolated sub-execution (a Temporal activity) whose emissions
# must bypass the parent run's registered buffer. Core default never isolated (see
# _never_in_isolated_execution); consumed by ReportingManager to route usage emissions.
self._isolated_execution_probe: Callable[[], bool] = _never_in_isolated_execution
- # pipeline
- self._pipeline_manager: PipelineManagerAbstract | None = None
- self._observer: ObserverProtocol | None = None
-
############################################################
# Class methods for singleton management
############################################################
@classmethod
- def get_optional_instance(cls) -> "PipelexHub | None":
+ def get_optional_instance(cls) -> "RuntimeHub | None":
return cls._instance
@classmethod
- def get_instance(cls) -> "PipelexHub":
+ def get_instance(cls) -> "RuntimeHub":
if cls._instance is None:
- msg = "PipelexHub is not initialized"
+ msg = "RuntimeHub is not initialized"
raise RuntimeError(msg)
return cls._instance
@classmethod
- def set_instance(cls, pipelex_hub: "PipelexHub") -> None:
- cls._instance = pipelex_hub
+ def set_instance(cls, runtime_hub: "RuntimeHub") -> None:
+ cls._instance = runtime_hub
############################################################
# Setters
@@ -194,9 +179,6 @@ class PipelexHub:
def set_storage_provider(self, storage_provider: StorageProviderAbstract | None):
self._storage_provider = storage_provider
- def set_class_registry(self, class_registry: ClassRegistryAbstract):
- self._class_registry = class_registry
-
def set_telemetry_manager(self, telemetry_manager: TelemetryManagerAbstract):
self._telemetry_manager = telemetry_manager
@@ -226,9 +208,6 @@ class PipelexHub:
def set_secrets_provider_registry(self, secrets_provider_registry: "SecretsProviderRegistry"):
self._secrets_provider_registry = secrets_provider_registry
- def set_pipe_func_executor_registry(self, pipe_func_executor_registry: "PipeFuncExecutorRegistry"):
- self._pipe_func_executor_registry = pipe_func_executor_registry
-
def set_inference_manager(self, inference_manager: InferenceManagerProtocol):
self._inference_manager = inference_manager
@@ -238,40 +217,17 @@ class PipelexHub:
def set_content_generator(self, content_generator: ContentGeneratorProtocol):
self._content_generator = content_generator
- def set_pipe_func_executor(self, pipe_func_executor: PipeFuncExecutorProtocol):
- self._pipe_func_executor = pipe_func_executor
-
def set_dry_run_forced(self, *, is_forced: bool) -> None:
self._is_dry_run_forced = is_forced
def is_dry_run_forced(self) -> bool:
return self._is_dry_run_forced
- # pipelex
-
- def set_domain_library(self, domain_library: DomainLibraryAbstract):
- self._domain_library = domain_library
-
- def set_concept_library(self, concept_library: ConceptLibraryAbstract):
- self._concept_library = concept_library
-
- def set_pipe_library(self, pipe_library: PipeLibraryAbstract):
- self._pipe_library = pipe_library
-
- def set_pipe_router(self, pipe_router: "PipeRouterProtocol"):
- self._pipe_router = pipe_router
-
- def set_pipe_run(self, pipe_run: "PipeRunProtocol") -> None:
- self._pipe_run = pipe_run
-
def set_isolated_execution_probe(self, probe: Callable[[], bool]) -> None:
self._isolated_execution_probe = probe
- def set_pipeline_manager(self, pipeline_manager: PipelineManagerAbstract):
- self._pipeline_manager = pipeline_manager
-
- def set_observer(self, observer: ObserverProtocol):
- self._observer = observer
+ def set_func_registry(self, func_registry: FuncRegistry):
+ self._func_registry = func_registry
############################################################
# Getters
@@ -317,12 +273,6 @@ class PipelexHub:
raise RuntimeError(msg)
return self._secrets_provider
- def get_required_class_registry(self) -> ClassRegistryAbstract:
- if self._class_registry is None:
- msg = "ClassRegistry is not initialized"
- raise RuntimeError(msg)
- return self._class_registry
-
def get_storage_provider(self) -> StorageProviderAbstract:
if self._storage_provider is None:
msg = "StorageProvider is not initialized"
@@ -335,6 +285,12 @@ class PipelexHub:
raise RuntimeError(msg)
return self._telemetry_manager
+ def get_func_registry(self) -> FuncRegistry:
+ if self._func_registry is None:
+ msg = "FuncRegistry is not initialized"
+ raise RuntimeError(msg)
+ return self._func_registry
+
# cogt
def get_required_models_manager(self) -> ModelManagerAbstract:
@@ -385,12 +341,6 @@ class PipelexHub:
raise RuntimeError(msg)
return self._secrets_provider_registry
- def get_pipe_func_executor_registry(self) -> "PipeFuncExecutorRegistry":
- if self._pipe_func_executor_registry is None:
- msg = "PipeFuncExecutorRegistry is not initialized"
- raise RuntimeError(msg)
- return self._pipe_func_executor_registry
-
def get_inference_manager(self) -> InferenceManagerProtocol:
return self._inference_manager
@@ -403,50 +353,6 @@ class PipelexHub:
raise RuntimeError(msg)
return self._content_generator
- def get_required_pipe_func_executor(self) -> PipeFuncExecutorProtocol:
- if self._pipe_func_executor is None:
- msg = "PipeFuncExecutor is not initialized"
- raise RuntimeError(msg)
- return self._pipe_func_executor
-
- # pipelex
-
- def get_required_domain_library(self) -> DomainLibraryAbstract:
- if self._library_manager is not None:
- return self._library_manager.get_current_library().domain_library
- if self._domain_library is None:
- msg = "DomainLibrary is not initialized"
- raise RuntimeError(msg)
- return self._domain_library
-
- def get_required_concept_library(self) -> ConceptLibraryAbstract:
- if self._library_manager is not None:
- return self._library_manager.get_current_library().concept_library
- if self._concept_library is None:
- msg = "ConceptLibrary is not initialized"
- raise RuntimeError(msg)
- return self._concept_library
-
- def get_required_pipe_library(self) -> PipeLibraryAbstract:
- if self._library_manager is not None:
- return self._library_manager.get_current_library().pipe_library
- if self._pipe_library is None:
- msg = "PipeLibrary is not initialized"
- raise RuntimeError(msg)
- return self._pipe_library
-
- def get_required_pipe_router(self) -> "PipeRouterProtocol":
- if self._pipe_router is None:
- msg = "PipeRouter is not initialized"
- raise RuntimeError(msg)
- return self._pipe_router
-
- def get_required_pipe_run(self) -> "PipeRunProtocol":
- if self._pipe_run is None:
- msg = "PipeRun is not initialized"
- raise RuntimeError(msg)
- return self._pipe_run
-
def is_in_isolated_execution(self) -> bool:
"""True when the current call runs inside an isolated sub-execution whose side-effecting
emissions must not be written into the parent run's registered (replay-deterministic) buffer.
@@ -456,52 +362,16 @@ class PipelexHub:
"""
return self._isolated_execution_probe()
- def get_required_pipeline_manager(self) -> PipelineManagerAbstract:
- if self._pipeline_manager is None:
- msg = "PipelineManager is not initialized"
- raise RuntimeError(msg)
- return self._pipeline_manager
-
- def get_library_manager(self) -> LibraryManagerAbstract:
- if self._library_manager is None:
- msg = "LibraryManager is not initialized"
- raise RuntimeError(msg)
- return self._library_manager
-
- def set_library_manager(self, library_manager: LibraryManagerAbstract):
- self._library_manager = library_manager
-
- def set_default_library_dirs(self, library_dirs: list[Path] | None) -> None:
- self._default_library_dirs = library_dirs
-
- def get_default_library_dirs(self) -> list[Path] | None:
- return self._default_library_dirs
-
- def get_library(self) -> Library:
- if self._library_manager is not None:
- return self._library_manager.get_current_library()
- msg = "Library is not initialized"
- raise RuntimeError(msg)
-
- def get_func_registry(self) -> FuncRegistry:
- if self._func_registry is None:
- msg = "FuncRegistry is not initialized"
- raise RuntimeError(msg)
- return self._func_registry
-
- def set_func_registry(self, func_registry: FuncRegistry):
- self._func_registry = func_registry
-
# Shorthand functions for accessing the singleton
-def get_pipelex_hub() -> PipelexHub:
- return PipelexHub.get_instance()
+def get_runtime_hub() -> RuntimeHub:
+ return RuntimeHub.get_instance()
-def set_pipelex_hub(pipelex_hub: PipelexHub):
- PipelexHub.set_instance(pipelex_hub)
+def set_runtime_hub(runtime_hub: RuntimeHub):
+ RuntimeHub.set_instance(runtime_hub)
# root convenience functions
@@ -510,21 +380,21 @@ def set_pipelex_hub(pipelex_hub: PipelexHub):
def get_required_config() -> ConfigRoot:
- return get_pipelex_hub().get_required_config()
+ return get_runtime_hub().get_required_config()
def get_optional_config() -> ConfigRoot | None:
"""Non-raising by contract: also covers the no-hub-at-all state, not just hub-without-config."""
- pipelex_hub = PipelexHub.get_optional_instance()
- return pipelex_hub.get_optional_config() if pipelex_hub is not None else None
+ runtime_hub = RuntimeHub.get_optional_instance()
+ return runtime_hub.get_optional_config() if runtime_hub is not None else None
def get_secrets_provider() -> SecretsProviderAbstract:
- return get_pipelex_hub().get_required_secrets_provider()
+ return get_runtime_hub().get_required_secrets_provider()
def get_storage_provider() -> StorageProviderAbstract:
- return get_pipelex_hub().get_storage_provider()
+ return get_runtime_hub().get_storage_provider()
def get_class_registry() -> ClassRegistryAbstract:
@@ -532,21 +402,20 @@ def get_class_registry() -> ClassRegistryAbstract:
When a library_id is set in the current async context (e.g. inside a Temporal workflow),
returns the library's scoped ClassRegistry. Otherwise, returns the global registry.
+
+ Delegates to ``pipelex.system.registries.class_registry_access``, which sits below this module
+ so that ``core.concepts`` — inside this module's own import closure — can reach the same
+ accessor without a cycle. This is the public entry point; prefer it.
"""
- library_id = _library_id.get()
- if library_id is not None:
- registry = get_library_manager().get_library_class_registry(library_id)
- if registry is not None:
- return registry
- return KajsonManager.get_class_registry()
+ return _get_active_class_registry()
def get_func_registry() -> FuncRegistry:
- return get_pipelex_hub().get_func_registry()
+ return get_runtime_hub().get_func_registry()
def get_telemetry_manager() -> TelemetryManagerAbstract:
- return get_pipelex_hub().get_telemetry_manager()
+ return get_runtime_hub().get_telemetry_manager()
def get_otel_tracer() -> "OTelTracer | None":
@@ -557,7 +426,7 @@ def get_otel_tracer() -> "OTelTracer | None":
def get_models_manager() -> ModelManagerAbstract:
- return get_pipelex_hub().get_required_models_manager()
+ return get_runtime_hub().get_required_models_manager()
def get_model_deck() -> ModelDeck:
@@ -565,39 +434,35 @@ def get_model_deck() -> ModelDeck:
def get_sdk_client_manager() -> SdkClientManager:
- return get_pipelex_hub().get_sdk_client_manager()
+ return get_runtime_hub().get_sdk_client_manager()
def get_inference_backend_registry() -> "InferenceBackendRegistry":
- return get_pipelex_hub().get_inference_backend_registry()
+ return get_runtime_hub().get_inference_backend_registry()
def get_model_lister_registry() -> "ModelListerRegistry":
- return get_pipelex_hub().get_model_lister_registry()
+ return get_runtime_hub().get_model_lister_registry()
def get_orchestrator_registry() -> "OrchestratorRegistry":
- return get_pipelex_hub().get_orchestrator_registry()
+ return get_runtime_hub().get_orchestrator_registry()
def get_bundle_validator_registry() -> "BundleValidatorRegistry":
- return get_pipelex_hub().get_bundle_validator_registry()
+ return get_runtime_hub().get_bundle_validator_registry()
def get_storage_provider_registry() -> "StorageProviderRegistry":
- return get_pipelex_hub().get_storage_provider_registry()
+ return get_runtime_hub().get_storage_provider_registry()
def get_secrets_provider_registry() -> "SecretsProviderRegistry":
- return get_pipelex_hub().get_secrets_provider_registry()
-
-
-def get_pipe_func_executor_registry() -> "PipeFuncExecutorRegistry":
- return get_pipelex_hub().get_pipe_func_executor_registry()
+ return get_runtime_hub().get_secrets_provider_registry()
def get_inference_manager() -> InferenceManagerProtocol:
- return get_pipelex_hub().get_inference_manager()
+ return get_runtime_hub().get_inference_manager()
def get_llm_worker(
@@ -619,12 +484,12 @@ def get_extract_worker(
def get_report_delegate() -> ReportingProtocol:
- return get_pipelex_hub().get_report_delegate()
+ return get_runtime_hub().get_report_delegate()
def is_in_isolated_execution() -> bool:
- """Module-level accessor — see :meth:`PipelexHub.is_in_isolated_execution`."""
- return get_pipelex_hub().is_in_isolated_execution()
+ """Module-level accessor — see :meth:`RuntimeHub.is_in_isolated_execution`."""
+ return get_runtime_hub().is_in_isolated_execution()
_content_generator_override: ContextVar[ContentGeneratorProtocol | None] = ContextVar("content_generator_override", default=None)
@@ -640,7 +505,7 @@ def scoped_content_generator(content_generator: ContentGeneratorProtocol) -> Gen
dry-run/validation activity body) wraps itself in this scope with an inline generator so its
leaves never dispatch — the DRY mock lives at the cogt leaf, so the inline generator's leaves
mock without dispatching and without storage IO. ContextVar-scoped like
- :func:`scoped_pipe_router`, so concurrent runs don't cross-contaminate.
+ :func:`pipelex.interpreter_hub.scoped_pipe_router`, so concurrent runs don't cross-contaminate.
"""
prev = _content_generator_override.get()
_content_generator_override.set(content_generator)
@@ -652,241 +517,20 @@ def scoped_content_generator(content_generator: ContentGeneratorProtocol) -> Gen
def is_dry_run_forced() -> bool:
"""True when the boot was keyless (``needs_inference=False``): every run is forced to DRY (D4)."""
- return get_pipelex_hub().is_dry_run_forced()
+ return get_runtime_hub().is_dry_run_forced()
def get_content_generator() -> ContentGeneratorProtocol:
override = _content_generator_override.get()
if override is not None:
return override
- return get_pipelex_hub().get_required_content_generator()
-
-
-_pipe_func_executor_override: ContextVar[PipeFuncExecutorProtocol | None] = ContextVar("pipe_func_executor_override", default=None)
-
-
-@contextmanager
-def scoped_pipe_func_executor(pipe_func_executor: PipeFuncExecutorProtocol) -> Generator[None, None, None]:
- """Set ``pipe_func_executor`` as the active executor for the scope, then restore the prior value on exit.
-
- The PipeFunc counterpart of :func:`scoped_content_generator`: in a process whose hub default
- executor dispatches PipeFunc steps out-of-process (a distributed-orchestrator worker), this scope
- lets an in-process run force a specific executor — e.g. the local one, so its PipeFunc steps run
- here instead of being re-dispatched. ContextVar-scoped like :func:`scoped_pipe_router`, so
- concurrent runs never cross-contaminate.
- """
- prev = _pipe_func_executor_override.get()
- _pipe_func_executor_override.set(pipe_func_executor)
- try:
- yield
- finally:
- _pipe_func_executor_override.set(prev)
-
-
-def get_pipe_func_executor() -> PipeFuncExecutorProtocol:
- override = _pipe_func_executor_override.get()
- if override is not None:
- return override
- return get_pipelex_hub().get_required_pipe_func_executor()
-
-
-# pipelex
+ return get_runtime_hub().get_required_content_generator()
def get_secret(secret_id: str) -> str:
return get_secrets_provider().get_secret(secret_id=secret_id)
-# libraries
-
-
-_library_id: ContextVar[str | None] = ContextVar("library_id", default=None)
-
-
-def set_current_library(library_id: str) -> None:
- """Set the library_id for the current async context."""
- _library_id.set(library_id)
-
-
-def get_current_library() -> str:
- """Get the library_id from the current async context."""
- library_id = _library_id.get()
- if library_id is None:
- msg = "No current library set. Must call set_current_library() first."
- raise RuntimeError(msg)
- return library_id
-
-
-def get_current_library_id_or_none() -> str | None:
- """Return the current library_id, or ``None`` if none is set."""
- return _library_id.get()
-
-
-def get_default_library_dirs() -> list[Path] | None:
- return get_pipelex_hub().get_default_library_dirs()
-
-
-def clear_current_library() -> None:
- """Clear the current-library binding (the ``None`` case of :func:`set_current_library`).
-
- Resets the ``_library_id`` ContextVar to ``None`` for the current async context. This only
- drops the *pointer* to which library is current — it does **not** free the ``Library`` object
- from the ``LibraryManager``. To release the library itself, call
- ``library_manager.teardown(library_id=...)`` (the two are distinct and a full cleanup typically
- does both).
- """
- _library_id.set(None)
-
-
-@contextmanager
-def scoped_current_library(library_id: str) -> Generator[None, None, None]:
- """Set ``library_id`` for the scope, then restore the prior value on exit.
-
- Captures the prior ``_library_id`` ContextVar value before setting the new
- one. On exit — success or exception — restores the prior value (or clears
- the var if there wasn't one). Use this whenever a function temporarily
- needs a current library for a nested operation without clobbering an
- outer caller's library_id.
- """
- prev = _library_id.get()
- _library_id.set(library_id)
- try:
- yield
- finally:
- _library_id.set(prev)
-
-
-def resolve_library_dirs(library_dirs: Sequence[str | Path] | None = None) -> tuple[list[Path], str]:
- """Resolve library directories following the standard 3-tier priority.
-
- Resolution priority:
- 1. Per-call library_dirs (explicit override)
- 2. Instance-level defaults from Pipelex.make()
- 3. PIPELEXPATH environment variable (fallback)
-
- Note: An empty list [] is a valid explicit value that disables library loading.
-
- Args:
- library_dirs: Optional per-call override. If provided (even if empty),
- takes precedence over instance defaults and PIPELEXPATH.
-
- Returns:
- A tuple of (effective_dirs, source_label) where:
- - effective_dirs: The resolved list of Path objects
- - source_label: A string describing the source for logging (e.g., "per-call")
- """
- reject_bare_str_or_path(library_dirs, param_name="library_dirs")
- if library_dirs is not None:
- return [Path(lib_dir) for lib_dir in library_dirs], "per-call"
-
- hub_defaults = get_pipelex_hub().get_default_library_dirs()
- if hub_defaults is not None:
- return hub_defaults, "instance default"
-
- pipelexpath_dirs = get_pipelexpath_dirs()
- if pipelexpath_dirs is not None:
- return pipelexpath_dirs, PIPELEXPATH_ENV_KEY
-
- return [], "none configured"
-
-
-def get_required_domain(domain_code: str) -> Domain:
- return get_pipelex_hub().get_required_domain_library().get_required_domain(domain_code=domain_code)
-
-
-def get_optional_domain(domain_code: str) -> Domain | None:
- return get_pipelex_hub().get_required_domain_library().get_domain(domain_code=domain_code)
-
-
-def get_pipe_library() -> PipeLibraryAbstract:
- return get_pipelex_hub().get_required_pipe_library()
-
-
-def get_pipes() -> list[PipeAbstract]:
- return get_pipelex_hub().get_required_pipe_library().get_pipes()
-
-
-def get_required_pipe(pipe_code: str) -> PipeAbstract:
- return get_pipelex_hub().get_required_pipe_library().get_required_pipe(pipe_code=pipe_code)
-
-
-def get_optional_pipe(pipe_code: str) -> PipeAbstract | None:
- return get_pipelex_hub().get_required_pipe_library().get_optional_pipe(pipe_code=pipe_code)
-
-
-def get_pipe_source(pipe_code: str) -> str | None:
- """Get the source identifier for a pipe.
-
- Args:
- pipe_code: The pipe code to look up.
-
- Returns:
- The source the pipe was loaded from — a filesystem path or a logical URI,
- preserved verbatim — or None if unknown.
- """
- return get_pipelex_hub().get_library_manager().get_pipe_source(pipe_code=pipe_code)
-
-
-def get_concept_library() -> ConceptLibraryAbstract:
- return get_pipelex_hub().get_library().concept_library
-
-
-def get_required_concept(concept_ref: str) -> Concept:
- return get_pipelex_hub().get_library().concept_library.get_required_concept(concept_ref=concept_ref)
-
-
-_current_pipe_router: ContextVar["PipeRouterProtocol | None"] = ContextVar("current_pipe_router", default=None)
-
-
-def set_pipe_router(pipe_router: "PipeRouterProtocol") -> None:
- """Override the active pipe router for the current async context.
-
- Used by host runtimes that want controllers to dispatch sub-pipes
- through their own router (e.g. Mistral Workflows mode swaps in a router
- that turns sub-pipe calls into child workflows / activities). The
- override is contextvar-scoped, so concurrent runs on the same hub
- don't leak into each other. Pass ``None`` via
- ``teardown_current_pipe_router()`` to restore the hub default.
- """
- _current_pipe_router.set(pipe_router)
-
-
-def teardown_current_pipe_router() -> None:
- """Clear any contextvar-scoped router override set by ``set_pipe_router``."""
- _current_pipe_router.set(None)
-
-
-@contextmanager
-def scoped_pipe_router(pipe_router: "PipeRouterProtocol") -> Generator[None, None, None]:
- """Set ``pipe_router`` as the active router for the scope, then restore the prior value on exit.
-
- Captures the prior ``_current_pipe_router`` ContextVar value before setting
- the new one. On exit — success or exception — restores the prior override
- (or clears it if there wasn't one). Use this whenever a call needs its own
- router for the *whole* run (root pipe + nested controller sub-pipes, which
- resolve :func:`get_pipe_router`) without clobbering an outer caller's
- override. Mirrors :func:`scoped_current_library`.
-
- Prefer this over the raw ``set_pipe_router`` / ``teardown_current_pipe_router``
- pair internally: the raw teardown unconditionally resets the override to
- ``None`` and so does not restore an outer override. The raw pair is kept
- because our Mistral Workflows plugin depends on it.
- """
- prev = _current_pipe_router.get()
- _current_pipe_router.set(pipe_router)
- try:
- yield
- finally:
- _current_pipe_router.set(prev)
-
-
-def get_pipe_router() -> "PipeRouterProtocol":
- override = _current_pipe_router.get()
- if override is not None:
- return override
- return get_pipelex_hub().get_required_pipe_router()
-
-
_event_log_override: ContextVar["EventLogProtocol | None"] = ContextVar("event_log_override", default=None)
@@ -907,7 +551,7 @@ def scoped_event_log(event_log: "EventLogProtocol") -> Generator[None, None, Non
event log's ``close()`` must therefore be safe to call mid-lifecycle — idempotent or a
no-op, as ``InMemoryEventLog``'s is. Scoping a backend whose ``close()`` releases a real
resource (NDJSON file handle, DynamoDB client) would break its own assembly read. Mirrors
- :func:`scoped_pipe_router`.
+ :func:`pipelex.interpreter_hub.scoped_pipe_router`.
"""
prev = _event_log_override.get()
_event_log_override.set(event_log)
@@ -922,33 +566,9 @@ def get_event_log_override() -> "EventLogProtocol | None":
return _event_log_override.get()
-def get_pipe_run() -> "PipeRunProtocol":
- return get_pipelex_hub().get_required_pipe_run()
-
-
-def get_pipeline_manager() -> PipelineManagerAbstract:
- return get_pipelex_hub().get_required_pipeline_manager()
-
-
-def get_pipeline(pipeline_run_id: str) -> Pipeline:
- return get_pipeline_manager().get_pipeline(pipeline_run_id=pipeline_run_id)
-
-
-def get_library_manager() -> LibraryManagerAbstract:
- return get_pipelex_hub().get_library_manager()
-
-
-def get_library() -> Library:
- return get_pipelex_hub().get_library()
-
-
-def get_native_concept(native_concept: NativeConceptCode) -> Concept:
- return get_pipelex_hub().get_required_concept_library().get_native_concept(native_concept=native_concept)
-
-
def get_console() -> Console:
- pipelex_hub = PipelexHub.get_optional_instance()
- if pipelex_hub:
- return pipelex_hub.get_console()
+ runtime_hub = RuntimeHub.get_optional_instance()
+ if runtime_hub:
+ return runtime_hub.get_console()
else:
return Console(stderr=True)
diff --git a/pipelex/system/configuration/config_check.py b/pipelex/system/configuration/config_check.py
index 12cf96754..efa78599c 100644
--- a/pipelex/system/configuration/config_check.py
+++ b/pipelex/system/configuration/config_check.py
@@ -1,6 +1,6 @@
from rich.panel import Panel
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import CONFIG_NAME, config_manager
from pipelex.tools.misc.file_utils import path_exists
from pipelex.urls import URLs
diff --git a/pipelex/system/configuration/configs.py b/pipelex/system/configuration/configs.py
index 281f0674f..99c936343 100644
--- a/pipelex/system/configuration/configs.py
+++ b/pipelex/system/configuration/configs.py
@@ -7,7 +7,6 @@ from pydantic import Field, field_validator, model_validator
from pipelex.base_exceptions import PipelexConfigError
from pipelex.cogt.config_cogt import Cogt
from pipelex.cogt.model_backends.prompting_target import PromptingTarget
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.graph.graph_config import GraphConfig
from pipelex.language.mthds_config import MthdsConfig
from pipelex.system.configuration.config_model import ConfigModel
@@ -17,6 +16,7 @@ from pipelex.tools.aws.aws_config import AwsConfig
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.secrets.secrets_config import SecretsProviderConfig
from pipelex.tools.storage.storage_config import StorageConfig
+from pipelex.tools.templating.templating_style import TemplatingStyle
class ConfigPaths:
diff --git a/pipelex/system/data_inclusion_config.py b/pipelex/system/data_inclusion_config.py
new file mode 100644
index 000000000..35d147fea
--- /dev/null
+++ b/pipelex/system/data_inclusion_config.py
@@ -0,0 +1,21 @@
+"""Data-capture configuration for the per-execution trace streams.
+
+Lives below both ``graph`` and ``tracing`` because it rides in every job's
+``TraceContext`` — the transport that reaches the inference layer — while the
+TOML nests it under ``[...graph_config.data_inclusion]``, which is where an
+operator expects to tune it. Keeping the class here is what lets
+:mod:`pipelex.system.trace_context` stay independent of the graph rendering
+configs (``mermaid_config`` / ``reactflow_config``) that ``GraphConfig`` pulls in.
+"""
+
+from pipelex.system.configuration.config_model import ConfigModel
+
+
+class DataInclusionConfig(ConfigModel):
+ """Controls which data is included in graph outputs."""
+
+ stuff_json_content: bool
+ stuff_text_content: bool
+ stuff_html_content: bool
+ error_stack_traces: bool
+ pipe_and_concept_registry: bool
diff --git a/pipelex/system/exceptions.py b/pipelex/system/exceptions.py
index 8387c3c5f..0710191ac 100644
--- a/pipelex/system/exceptions.py
+++ b/pipelex/system/exceptions.py
@@ -2,13 +2,17 @@ import logging
from enum import StrEnum
from typing import ClassVar
-from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError, PipelexUnexpectedError
class ToolError(PipelexError):
_declared_title = "Tool error"
+class JobMetadataError(PipelexUnexpectedError):
+ pass
+
+
class NestedKeyConflictError(ToolError):
"""Raised when attempting to create nested keys under a non-dict value."""
diff --git a/pipelex/pipeline/job_metadata.py b/pipelex/system/job_metadata.py
similarity index 98%
rename from pipelex/pipeline/job_metadata.py
rename to pipelex/system/job_metadata.py
index 6332f1464..2aa10f92f 100644
--- a/pipelex/pipeline/job_metadata.py
+++ b/pipelex/system/job_metadata.py
@@ -4,8 +4,8 @@ from typing import Any
from pydantic import BaseModel, Field
-from pipelex.graph.trace_context import TraceContext
from pipelex.system.telemetry.otel_context import OtelContext
+from pipelex.system.trace_context import TraceContext
class JobCategory(StrEnum):
diff --git a/pipelex/system/registries/class_registry_access.py b/pipelex/system/registries/class_registry_access.py
new file mode 100644
index 000000000..652b43e98
--- /dev/null
+++ b/pipelex/system/registries/class_registry_access.py
@@ -0,0 +1,66 @@
+"""Process-global access to the active class registry, with an optional library-scoping resolver.
+
+This module deliberately sits *below* both hubs and imports nothing from ``pipelex``, so any layer
+can import it directly. That is not stylistic: ``pipelex.core.concepts.concept`` needs the active
+class registry and is itself inside ``runtime_hub``'s import closure
+(``runtime_hub`` -> ``cogt.llm.llm_worker_abstract`` -> ``system.telemetry.otel_factory`` ->
+``core.pipes.pipe_output`` -> ``core.stuffs.stuff`` -> ``core.concepts.concept``), so it cannot
+import ``runtime_hub`` at module level without forming a cycle. Hosting the accessor here is what
+lets those modules use a plain top-level import instead of a lazy ``importlib`` shim.
+
+``pipelex.runtime_hub.get_class_registry`` is the public accessor and delegates here; prefer it
+everywhere except inside this module's own import closure.
+
+Scoping: a run may pin a per-library ClassRegistry (a workflow's own registry) rather than the
+process-global Kajson one. Resolving *which* library is current is interpreter-layer knowledge, so
+the runtime layer holds only a slot — ``pipelex.interpreter_hub.set_interpreter_hub`` installs the real
+resolver at boot. Unresolved, or with no library pinned, callers get the process-global registry.
+"""
+
+from collections.abc import Callable
+
+from kajson.class_registry_abstract import ClassRegistryAbstract
+from kajson.kajson_manager import KajsonManager
+
+
+def _no_library_scoping() -> ClassRegistryAbstract | None:
+ """Core default resolver: with no InterpreterHub installed there is no per-library scoping."""
+ return None
+
+
+class ClassRegistryScoping:
+ """Process-global slot holding the library-scoped class-registry resolver.
+
+ Mirrors the ``HubSlot.ISOLATED_EXECUTION_PROBE`` pattern: a defaulted callable that a higher
+ layer replaces at boot, never an unset attribute — so a process that only ever builds a
+ RuntimeHub (the doctor path, most unit tests) degrades to the process-global registry instead
+ of raising. Reached through the ``class_registry_scoping`` module singleton below, in the same
+ style as ``config_manager``.
+ """
+
+ def __init__(self) -> None:
+ self._resolver: Callable[[], ClassRegistryAbstract | None] = _no_library_scoping
+
+ def install(self, *, resolver: Callable[[], ClassRegistryAbstract | None]) -> None:
+ self._resolver = resolver
+
+ def reset(self) -> None:
+ self._resolver = _no_library_scoping
+
+ def resolve(self) -> ClassRegistryAbstract | None:
+ return self._resolver()
+
+
+class_registry_scoping = ClassRegistryScoping()
+
+
+def get_class_registry() -> ClassRegistryAbstract:
+ """Return the active class registry, respecting per-workflow library scoping.
+
+ When a library_id is set in the current async context (e.g. inside a Temporal workflow),
+ returns the library's scoped ClassRegistry. Otherwise, returns the global registry.
+ """
+ scoped_class_registry = class_registry_scoping.resolve()
+ if scoped_class_registry is not None:
+ return scoped_class_registry
+ return KajsonManager.get_class_registry()
diff --git a/pipelex/system/registries/class_registry_utils.py b/pipelex/system/registries/class_registry_utils.py
index 55172e4cf..72e97b58b 100644
--- a/pipelex/system/registries/class_registry_utils.py
+++ b/pipelex/system/registries/class_registry_utils.py
@@ -6,7 +6,7 @@ from typing import Any
from pipelex import log
from pipelex.config import get_config
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
from pipelex.tools.misc.file_utils import find_files_in_dir
from pipelex.tools.typing.exceptions import ModuleFileError
from pipelex.tools.typing.module_inspector import (
diff --git a/pipelex/graph/trace_context.py b/pipelex/system/trace_context.py
similarity index 98%
rename from pipelex/graph/trace_context.py
rename to pipelex/system/trace_context.py
index 7988c2144..06c5eb4aa 100644
--- a/pipelex/graph/trace_context.py
+++ b/pipelex/system/trace_context.py
@@ -16,7 +16,7 @@ The node tree is always built when either stream is on — including costs-only
from pydantic import BaseModel, ConfigDict, Field
-from pipelex.graph.graph_config import DataInclusionConfig
+from pipelex.system.data_inclusion_config import DataInclusionConfig
class TraceContext(BaseModel):
diff --git a/pipelex/test_extras/shared_pytest_plugins.py b/pipelex/test_extras/shared_pytest_plugins.py
index 4dca8f85c..a0727c241 100644
--- a/pipelex/test_extras/shared_pytest_plugins.py
+++ b/pipelex/test_extras/shared_pytest_plugins.py
@@ -6,8 +6,8 @@ from pytest import Config, FixtureRequest, Parser
from rich.console import Console
from rich.panel import Panel
-from pipelex.hub import get_console
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
+from pipelex.runtime_hub import get_console
from pipelex.system.environment import is_env_var_set, is_env_var_truthy, set_env
from pipelex.system.runtime import CODEX_CLOUD_ENV_VAR_KEY, RunMode, runtime_manager
from pipelex.tools.misc.placeholder import make_placeholder_value, value_is_placeholder
diff --git a/pipelex/tools/aws/aws_config.py b/pipelex/tools/aws/aws_config.py
index 4c0b30c6f..c1aeafeae 100644
--- a/pipelex/tools/aws/aws_config.py
+++ b/pipelex/tools/aws/aws_config.py
@@ -3,7 +3,7 @@ from enum import StrEnum
from pydantic import Field
from pipelex import log
-from pipelex.hub import get_secret
+from pipelex.runtime_hub import get_secret
from pipelex.system.configuration.config_model import ConfigModel
from pipelex.system.environment import get_required_env
from pipelex.system.exceptions import EnvVarNotFoundError
diff --git a/pipelex/tools/jinja2/image_renderable.py b/pipelex/tools/jinja2/image_renderable.py
index c80095012..bd7c86ffd 100644
--- a/pipelex/tools/jinja2/image_renderable.py
+++ b/pipelex/tools/jinja2/image_renderable.py
@@ -13,8 +13,8 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Protocol, runtime_checkable
if TYPE_CHECKING:
- from pipelex.cogt.templating.text_format import TextFormat
from pipelex.tools.jinja2.image_registry import ImageRegistry
+ from pipelex.tools.templating.text_format import TextFormat
@runtime_checkable
diff --git a/pipelex/tools/jinja2/jinja2_environment.py b/pipelex/tools/jinja2/jinja2_environment.py
index a46180104..fcac6a628 100644
--- a/pipelex/tools/jinja2/jinja2_environment.py
+++ b/pipelex/tools/jinja2/jinja2_environment.py
@@ -2,8 +2,8 @@ import inspect
from jinja2 import BaseLoader, Environment
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
+from pipelex.tools.jinja2.template_category import TemplateCategory
def make_jinja2_env_from_loader(
diff --git a/pipelex/tools/jinja2/jinja2_filters.py b/pipelex/tools/jinja2/jinja2_filters.py
index 41adb5c52..b445f23f1 100644
--- a/pipelex/tools/jinja2/jinja2_filters.py
+++ b/pipelex/tools/jinja2/jinja2_filters.py
@@ -5,13 +5,13 @@ from typing import Any
from jinja2 import pass_context
from jinja2.runtime import Context, Undefined
-from pipelex.cogt.templating.templating_style import TagStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.tools.jinja2.exceptions import Jinja2ContextError
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
from pipelex.tools.jinja2.tag_renderable import TagRenderable
from pipelex.tools.jinja2.text_format_renderable import TextFormatRenderable
+from pipelex.tools.templating.templating_style import TagStyle
+from pipelex.tools.templating.text_format import TextFormat
########################################################################################
# Jinja2 filters
diff --git a/pipelex/tools/jinja2/jinja2_optional_guards.py b/pipelex/tools/jinja2/jinja2_optional_guards.py
index 3e73e650d..15afcf7aa 100644
--- a/pipelex/tools/jinja2/jinja2_optional_guards.py
+++ b/pipelex/tools/jinja2/jinja2_optional_guards.py
@@ -25,9 +25,9 @@ from jinja2 import nodes
from jinja2.exceptions import TemplateSyntaxError
from pydantic.dataclasses import dataclass
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_loader
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
# Test names that safely probe presence on an undefined variable.
diff --git a/pipelex/tools/jinja2/jinja2_parsing.py b/pipelex/tools/jinja2/jinja2_parsing.py
index cae2b6956..8b48b4c78 100644
--- a/pipelex/tools/jinja2/jinja2_parsing.py
+++ b/pipelex/tools/jinja2/jinja2_parsing.py
@@ -1,8 +1,8 @@
import jinja2
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_loader
+from pipelex.tools.jinja2.template_category import TemplateCategory
def check_jinja2_parsing(
diff --git a/pipelex/tools/jinja2/jinja2_rendering.py b/pipelex/tools/jinja2/jinja2_rendering.py
index 1a0642502..ab8890e54 100644
--- a/pipelex/tools/jinja2/jinja2_rendering.py
+++ b/pipelex/tools/jinja2/jinja2_rendering.py
@@ -7,8 +7,6 @@ from jinja2.exceptions import (
UndefinedError,
)
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.tools.jinja2.exceptions import (
Jinja2ContextError,
Jinja2StuffError,
@@ -19,6 +17,8 @@ from pipelex.tools.jinja2.jinja2_environment import (
make_jinja2_env_without_loader,
)
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TemplatingStyle
def _add_to_templating_context(templating_context: dict[str, Any], *, jinja2_context_key: Jinja2ContextKey, value: Any) -> None:
diff --git a/pipelex/tools/jinja2/jinja2_required_variables.py b/pipelex/tools/jinja2/jinja2_required_variables.py
index 492f597b1..899137a1a 100644
--- a/pipelex/tools/jinja2/jinja2_required_variables.py
+++ b/pipelex/tools/jinja2/jinja2_required_variables.py
@@ -7,9 +7,9 @@ from jinja2.exceptions import (
)
from pydantic.dataclasses import dataclass
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError, Jinja2StuffError
from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_loader
+from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
diff --git a/pipelex/tools/jinja2/jinja2_with_images_filter.py b/pipelex/tools/jinja2/jinja2_with_images_filter.py
index a9946774f..24fb7dc5d 100644
--- a/pipelex/tools/jinja2/jinja2_with_images_filter.py
+++ b/pipelex/tools/jinja2/jinja2_with_images_filter.py
@@ -5,11 +5,11 @@ from typing import Any
from jinja2 import pass_context
from jinja2.runtime import Context, Undefined
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.tools.jinja2.exceptions import Jinja2ContextError
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.image_renderable import ImageRenderable
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.tools.templating.text_format import TextFormat
@pass_context
diff --git a/pipelex/cogt/templating/template_category.py b/pipelex/tools/jinja2/template_category.py
similarity index 100%
rename from pipelex/cogt/templating/template_category.py
rename to pipelex/tools/jinja2/template_category.py
diff --git a/pipelex/tools/jinja2/text_format_renderable.py b/pipelex/tools/jinja2/text_format_renderable.py
index abfc508f7..65e8fe6fd 100644
--- a/pipelex/tools/jinja2/text_format_renderable.py
+++ b/pipelex/tools/jinja2/text_format_renderable.py
@@ -13,7 +13,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Protocol, runtime_checkable
if TYPE_CHECKING:
- from pipelex.cogt.templating.text_format import TextFormat
+ from pipelex.tools.templating.text_format import TextFormat
@runtime_checkable
diff --git a/pipelex/tools/log/log_dispatch.py b/pipelex/tools/log/log_dispatch.py
index 9f4c03f10..28a437776 100644
--- a/pipelex/tools/log/log_dispatch.py
+++ b/pipelex/tools/log/log_dispatch.py
@@ -39,7 +39,7 @@ class LogDispatch:
"""
if self._log_config_instance is None:
- msg = "LogConfig is not set. You must call pipelex_hub.set_config()."
+ msg = "LogConfig is not set. You must call runtime_hub.set_config()."
raise RuntimeError(msg)
return self._log_config_instance
diff --git a/pipelex/tools/mermaid/mermaid_utils.py b/pipelex/tools/mermaid/mermaid_utils.py
index d36b544e1..4afde5442 100644
--- a/pipelex/tools/mermaid/mermaid_utils.py
+++ b/pipelex/tools/mermaid/mermaid_utils.py
@@ -15,9 +15,9 @@ import json
import zlib
from pipelex import pretty_print
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async, render_jinja2_sync
from pipelex.tools.jinja2.jinja2_template_loader import load_template
+from pipelex.tools.jinja2.template_category import TemplateCategory
# Template package and name for generic Mermaid HTML
_TEMPLATE_PACKAGE = "pipelex.tools.mermaid.templates"
diff --git a/pipelex/tools/pdf/pypdfium2_renderer.py b/pipelex/tools/pdf/pypdfium2_renderer.py
index 62ce42200..bd614c151 100644
--- a/pipelex/tools/pdf/pypdfium2_renderer.py
+++ b/pipelex/tools/pdf/pypdfium2_renderer.py
@@ -12,7 +12,7 @@ from pypdfium2.raw import FPDF_PAGEOBJ_IMAGE, FPDFBitmap_BGRA
from pipelex.cogt.extract.bounding_box import BoundingBox
from pipelex.cogt.extract.extract_output import ExtractedImageFromPage
from pipelex.cogt.image.image_size import ImageSize
-from pipelex.hub import get_storage_provider
+from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx
from pipelex.tools.misc.image_utils import ImageFormat, pil_image_to_bytes
from pipelex.tools.uri.resolved_uri import (
diff --git a/pipelex/tools/templating/__init__.py b/pipelex/tools/templating/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pipelex/cogt/templating/templating_style.py b/pipelex/tools/templating/templating_style.py
similarity index 91%
rename from pipelex/cogt/templating/templating_style.py
rename to pipelex/tools/templating/templating_style.py
index b1fad07fb..a8f8c0e39 100644
--- a/pipelex/cogt/templating/templating_style.py
+++ b/pipelex/tools/templating/templating_style.py
@@ -4,7 +4,7 @@ from typing import Self
from pydantic import BaseModel, Field
from typing_extensions import override
-from pipelex.cogt.templating.text_format import TextFormat
+from pipelex.tools.templating.text_format import TextFormat
class TagStyle(StrEnum):
diff --git a/pipelex/cogt/templating/text_format.py b/pipelex/tools/templating/text_format.py
similarity index 100%
rename from pipelex/cogt/templating/text_format.py
rename to pipelex/tools/templating/text_format.py
diff --git a/pipelex/tools/typing/structure_printer.py b/pipelex/tools/typing/structure_printer.py
index 92f77aff2..0d60c6c8f 100644
--- a/pipelex/tools/typing/structure_printer.py
+++ b/pipelex/tools/typing/structure_printer.py
@@ -4,7 +4,7 @@ from typing import Any, Union, get_args, get_origin, get_type_hints
from pydantic import BaseModel
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
def _build_type_hints_namespace() -> dict[str, Any]:
diff --git a/subject_grants.toml b/subject_grants.toml
index a32498ec5..d7ee477fb 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -1172,30 +1172,6 @@ rationale = "Verb-object: resolves the concept_ref; the rest is context."
param = "crate"
rationale = "Factory from source: resolves the whole crate into a library."
-["pipelex/codegen/resolved_fields.py::_resolve_concept"]
-param = "concept_ref"
-rationale = "Verb-object: resolves the concept_ref; local_domain is context."
-
-["pipelex/codegen/resolved_fields.py::_resolve_list_item"]
-param = "blueprint"
-rationale = "Verb-object: resolves the list-item blueprint; local_domain is context."
-
-["pipelex/codegen/resolved_fields.py::_resolve_scalar_type_name"]
-param = "type_name"
-rationale = "Verb-object: resolves the type name; the rest is context."
-
-["pipelex/codegen/resolved_fields.py::_resolve_type"]
-param = "blueprint"
-rationale = "Verb-object: resolves the blueprint's type; local_domain is context."
-
-["pipelex/codegen/resolved_fields.py::iter_imprecision_reasons"]
-param = "resolved_type"
-rationale = "Noun-named derivation: the imprecision reasons of the resolved type; single operand."
-
-["pipelex/codegen/resolved_fields.py::resolve_structure_fields"]
-param = "structure_blueprint"
-rationale = "Verb-object: resolves the structure blueprint's fields; local_domain is context."
-
["pipelex/codegen/stamp.py::_kind_from_value"]
param = "value"
rationale = "Single-operand parse of the value."
@@ -2384,6 +2360,18 @@ rationale = "Factory keyed by the native concept code; single operand."
param = "refine"
rationale = "Verb-object: normalizes the refine string; domain stays keyword."
+["pipelex/core/concepts/concept_provider_abstract.py::ConceptProviderAbstract.get_native_concept"]
+param = "native_concept"
+rationale = "Resolver getter: the native concept being fetched; single operand."
+
+["pipelex/core/concepts/concept_provider_abstract.py::ConceptProviderAbstract.get_required_concept"]
+param = "concept_ref"
+rationale = "Resolver getter keyed by the concept ref; single operand."
+
+["pipelex/core/concepts/concept_provider_abstract.py::ConceptProviderAbstract.get_required_concept_from_concept_ref_or_code"]
+param = "concept_ref_or_code"
+rationale = "Resolver getter keyed by the ref-or-code; single operand."
+
["pipelex/core/concepts/concept_representation_generator.py::ConceptRepresentationGenerator._format_python_value"]
param = "value"
rationale = "Transforms the value; single operand."
@@ -2500,6 +2488,30 @@ rationale = "Noun-named derivation: the pinned structure for the native code; si
param = "native_code"
rationale = "Factory from source: builds the blueprint for the native code; single operand."
+["pipelex/core/concepts/resolved_fields.py::_resolve_concept"]
+param = "concept_ref"
+rationale = "Verb-object: resolves the concept_ref; local_domain is context."
+
+["pipelex/core/concepts/resolved_fields.py::_resolve_list_item"]
+param = "blueprint"
+rationale = "Verb-object: resolves the list-item blueprint; local_domain is context."
+
+["pipelex/core/concepts/resolved_fields.py::_resolve_scalar_type_name"]
+param = "type_name"
+rationale = "Verb-object: resolves the type name; the rest is context."
+
+["pipelex/core/concepts/resolved_fields.py::_resolve_type"]
+param = "blueprint"
+rationale = "Verb-object: resolves the blueprint's type; local_domain is context."
+
+["pipelex/core/concepts/resolved_fields.py::iter_imprecision_reasons"]
+param = "resolved_type"
+rationale = "Noun-named derivation: the imprecision reasons of the resolved type; single operand."
+
+["pipelex/core/concepts/resolved_fields.py::resolve_structure_fields"]
+param = "structure_blueprint"
+rationale = "Verb-object: resolves the structure blueprint's fields; local_domain is context."
+
["pipelex/core/concepts/structure_generation/exceptions.py::SyntaxErrorData.from_syntax_error"]
param = "syntax_error"
rationale = "Factory from source: builds from the syntax error; single operand."
@@ -2920,46 +2932,6 @@ rationale = "Verb-object: categorizes the pipe error; context stays keyword."
param = "error"
rationale = "Verb-object: unwraps the error; single operand."
-["pipelex/core/pipes/inputs/input_renderer.py::_delighten_entry"]
-param = "entry"
-rationale = "Single-operand transformation of the entry; kind is a mode and stays keyword."
-
-["pipelex/core/pipes/inputs/input_renderer.py::_delighten_template"]
-param = "envelope_template"
-rationale = "Single-operand transformation of the template; specs stay keyword."
-
-["pipelex/core/pipes/inputs/input_renderer.py::_substitute_none_values"]
-param = "value"
-rationale = "Single-operand transformation of the value."
-
-["pipelex/core/pipes/inputs/input_renderer.py::_to_toml_value"]
-param = "value"
-rationale = "Single-operand conversion of the value."
-
-["pipelex/core/pipes/inputs/input_renderer.py::_unwrap_scalar_content"]
-param = "content"
-rationale = "Single-operand unwrap of the content; envelope is context."
-
-["pipelex/core/pipes/inputs/input_renderer.py::build_concept_comments"]
-param = "input_specs"
-rationale = "Noun-named derivation: the comments mapping for the input specs; single operand."
-
-["pipelex/core/pipes/inputs/input_renderer.py::build_inputs_template"]
-param = "the_pipe"
-rationale = "Noun-named derivation: the inputs template for the pipe; explicit is a mode."
-
-["pipelex/core/pipes/inputs/input_renderer.py::render_inputs"]
-param = "the_pipe"
-rationale = "Verb-object: renders the pipe's inputs; format stays keyword."
-
-["pipelex/core/pipes/inputs/input_renderer.py::render_inputs_toml"]
-param = "the_pipe"
-rationale = "Verb-object: renders the pipe's inputs; explicit is a mode."
-
-["pipelex/core/pipes/inputs/input_renderer.py::serialize_inputs_template_to_toml"]
-param = "template"
-rationale = "Single-operand serialization of the template; options stay keyword."
-
["pipelex/core/pipes/inputs/input_stuff_specs.py::InputStuffSpecs.get_required_stuff_spec"]
param = "variable_name"
rationale = "Specs getter keyed by the variable name; single operand."
@@ -2976,26 +2948,6 @@ rationale = "Setter: installs the default domain code; single operand."
param = "named"
rationale = "Factory from source: builds from the named spec; context stays keyword."
-["pipelex/core/pipes/output/output_renderer.py::_collect_possible_outputs"]
-param = "the_pipe"
-rationale = "Verb-object: collects from the pipe; single operand."
-
-["pipelex/core/pipes/output/output_renderer.py::_render_json_output"]
-param = "the_pipe"
-rationale = "Verb-object: renders the pipe's output; single operand."
-
-["pipelex/core/pipes/output/output_renderer.py::_render_python_output"]
-param = "the_pipe"
-rationale = "Verb-object: renders the pipe's output; single operand."
-
-["pipelex/core/pipes/output/output_renderer.py::_render_schema_output"]
-param = "the_pipe"
-rationale = "Verb-object: renders the pipe's output; single operand."
-
-["pipelex/core/pipes/output/output_renderer.py::render_output"]
-param = "the_pipe"
-rationale = "Verb-object: renders the pipe's output; format stays keyword."
-
["pipelex/core/pipes/pipe_abstract.py::PipeAbstract._end_pipe_span_error"]
param = "span"
rationale = "Verb-object: ends the span; error fields stay keyword."
@@ -3036,6 +2988,66 @@ rationale = "Type-directed accessor: the target item type; single operand."
param = "item_type"
rationale = "Type-directed accessor: the target item type; single operand."
+["pipelex/core/pipes/rendering/input_renderer.py::_delighten_entry"]
+param = "entry"
+rationale = "Single-operand transformation of the entry; kind is a mode and stays keyword."
+
+["pipelex/core/pipes/rendering/input_renderer.py::_delighten_template"]
+param = "envelope_template"
+rationale = "Single-operand transformation of the template; specs stay keyword."
+
+["pipelex/core/pipes/rendering/input_renderer.py::_substitute_none_values"]
+param = "value"
+rationale = "Single-operand transformation of the value."
+
+["pipelex/core/pipes/rendering/input_renderer.py::_to_toml_value"]
+param = "value"
+rationale = "Single-operand conversion of the value."
+
+["pipelex/core/pipes/rendering/input_renderer.py::_unwrap_scalar_content"]
+param = "content"
+rationale = "Single-operand unwrap of the content; envelope is context."
+
+["pipelex/core/pipes/rendering/input_renderer.py::build_concept_comments"]
+param = "input_specs"
+rationale = "Noun-named derivation: the comments mapping for the input specs; single operand."
+
+["pipelex/core/pipes/rendering/input_renderer.py::build_inputs_template"]
+param = "the_pipe"
+rationale = "Noun-named derivation: the inputs template for the pipe; explicit is a mode."
+
+["pipelex/core/pipes/rendering/input_renderer.py::render_inputs"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's inputs; format stays keyword."
+
+["pipelex/core/pipes/rendering/input_renderer.py::render_inputs_toml"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's inputs; explicit is a mode."
+
+["pipelex/core/pipes/rendering/input_renderer.py::serialize_inputs_template_to_toml"]
+param = "template"
+rationale = "Single-operand serialization of the template; options stay keyword."
+
+["pipelex/core/pipes/rendering/output_renderer.py::_collect_possible_outputs"]
+param = "the_pipe"
+rationale = "Verb-object: collects from the pipe; single operand."
+
+["pipelex/core/pipes/rendering/output_renderer.py::_render_json_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; single operand."
+
+["pipelex/core/pipes/rendering/output_renderer.py::_render_python_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; single operand."
+
+["pipelex/core/pipes/rendering/output_renderer.py::_render_schema_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; single operand."
+
+["pipelex/core/pipes/rendering/output_renderer.py::render_output"]
+param = "the_pipe"
+rationale = "Verb-object: renders the pipe's output; format stays keyword."
+
["pipelex/core/pipes/validation.py::is_input_used_by_variables"]
param = "input_name"
rationale = "Predicate on the input named; the variables stay keyword."
@@ -3456,10 +3468,6 @@ rationale = "Verb-object: renders the graph spec to HTML; options stay keyword."
param = "graphspec"
rationale = "Verb-object: renders the graph spec to HTML; options stay keyword."
-["pipelex/graph/trace_context.py::TraceContext.copy_for_child"]
-param = "child_node_id"
-rationale = "Verb-object: copies the context for the child node; sequence stays keyword."
-
["pipelex/graph/validation.py::_validate_edge_references"]
param = "graph"
rationale = "Verb-object: validates the graph; single operand."
@@ -3480,222 +3488,110 @@ rationale = "Verb-object: validates the graph; single operand."
param = "graph"
rationale = "Verb-object: validates the graph spec; single operand."
-["pipelex/hub.py::PipelexHub.set_bundle_validator_registry"]
-param = "bundle_validator_registry"
-rationale = "Hub setter: installs the bundle validator registry; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_class_registry"]
-param = "class_registry"
-rationale = "Hub setter: installs the class registry; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_concept_library"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_concept_library"]
param = "concept_library"
rationale = "Hub setter: installs the concept library; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_config"]
-param = "config"
-rationale = "Hub setter: installs the config; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_console"]
-param = "console"
-rationale = "Hub setter: installs the console; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_console_print_target"]
-param = "target"
-rationale = "Hub setter: installs the print target; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_content_generator"]
-param = "content_generator"
-rationale = "Hub setter: installs the content generator; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_default_library_dirs"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_default_library_dirs"]
param = "library_dirs"
rationale = "Hub setter: installs the default library dirs; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_domain_library"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_domain_library"]
param = "domain_library"
rationale = "Hub setter: installs the domain library; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_func_registry"]
-param = "func_registry"
-rationale = "Hub setter: installs the func registry; single self-labelling operand."
+["pipelex/interpreter_hub.py::InterpreterHub.set_instance"]
+param = "interpreter_hub"
+rationale = "Hub setter: installs the InterpreterHub singleton; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_inference_backend_registry"]
-param = "inference_backend_registry"
-rationale = "Hub setter: installs the inference backend registry; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_inference_manager"]
-param = "inference_manager"
-rationale = "Hub setter: installs the inference manager; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_instance"]
-param = "pipelex_hub"
-rationale = "Hub setter: installs the hub singleton; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_isolated_execution_probe"]
-param = "probe"
-rationale = "Hub setter: installs the execution probe; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_library_manager"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_library_manager"]
param = "library_manager"
rationale = "Hub setter: installs the library manager; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_model_lister_registry"]
-param = "model_lister_registry"
-rationale = "Hub setter: installs the model lister registry; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_models_manager"]
-param = "models_manager"
-rationale = "Hub setter: installs the models manager; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_observer"]
-param = "observer"
-rationale = "Hub setter: installs the observer; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_orchestrator_registry"]
-param = "orchestrator_registry"
-rationale = "Hub setter: installs the orchestrator registry; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_pipe_func_executor"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_pipe_func_executor"]
param = "pipe_func_executor"
rationale = "Hub setter: installs the pipe-func executor; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_pipe_func_executor_registry"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_pipe_func_executor_registry"]
param = "pipe_func_executor_registry"
rationale = "Hub setter: installs the pipe-func executor registry; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_pipe_library"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_pipe_library"]
param = "pipe_library"
rationale = "Hub setter: installs the pipe library; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_pipe_router"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_pipe_router"]
param = "pipe_router"
rationale = "Hub setter: installs the pipe router; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_pipe_run"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_pipe_run"]
param = "pipe_run"
rationale = "Hub setter: installs the pipe-run holder; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_pipeline_manager"]
+["pipelex/interpreter_hub.py::InterpreterHub.set_pipeline_manager"]
param = "pipeline_manager"
rationale = "Hub setter: installs the pipeline manager; single self-labelling operand."
-["pipelex/hub.py::PipelexHub.set_report_delegate"]
-param = "reporting_delegate"
-rationale = "Hub setter: installs the reporting delegate; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_sdk_client_manager"]
-param = "sdk_client_manager"
-rationale = "Hub setter: installs the SDK client manager; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_secrets_provider"]
-param = "secrets_provider"
-rationale = "Hub setter: installs the secrets provider; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_secrets_provider_registry"]
-param = "secrets_provider_registry"
-rationale = "Hub setter: the registry is the operand being installed."
-
-["pipelex/hub.py::PipelexHub.set_storage_provider"]
-param = "storage_provider"
-rationale = "Hub setter: installs the storage provider; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.set_storage_provider_registry"]
-param = "storage_provider_registry"
-rationale = "Hub setter: the registry is the operand being installed."
-
-["pipelex/hub.py::PipelexHub.set_telemetry_manager"]
-param = "telemetry_manager"
-rationale = "Hub setter: installs the telemetry manager; single self-labelling operand."
-
-["pipelex/hub.py::PipelexHub.setup_config"]
-param = "config_cls"
-rationale = "Sets up config from the given config class; single operand."
-
-["pipelex/hub.py::get_extract_worker"]
-param = "extract_handle"
-rationale = "Hub getter keyed by the worker's handle; single operand."
-
-["pipelex/hub.py::get_img_gen_worker"]
-param = "img_gen_handle"
-rationale = "Hub getter keyed by the worker's handle; single operand."
-
-["pipelex/hub.py::get_llm_worker"]
-param = "llm_handle"
-rationale = "Hub getter keyed by the worker's handle; single operand."
-
-["pipelex/hub.py::get_native_concept"]
+["pipelex/interpreter_hub.py::get_native_concept"]
param = "native_concept"
rationale = "Hub getter: the native concept being fetched; single operand."
-["pipelex/hub.py::get_optional_domain"]
+["pipelex/interpreter_hub.py::get_optional_domain"]
param = "domain_code"
rationale = "Hub getter keyed by the domain code; single operand."
-["pipelex/hub.py::get_optional_pipe"]
+["pipelex/interpreter_hub.py::get_optional_pipe"]
param = "pipe_code"
rationale = "Hub getter keyed by the pipe code; single operand."
-["pipelex/hub.py::get_pipe_source"]
+["pipelex/interpreter_hub.py::get_pipe_source"]
param = "pipe_code"
rationale = "Hub getter keyed by the pipe code; single operand."
-["pipelex/hub.py::get_pipeline"]
+["pipelex/interpreter_hub.py::get_pipeline"]
param = "pipeline_run_id"
rationale = "Hub getter keyed by the pipeline run id; single operand."
-["pipelex/hub.py::get_required_concept"]
+["pipelex/interpreter_hub.py::get_required_concept"]
param = "concept_ref"
rationale = "Hub getter keyed by the concept ref; single operand."
-["pipelex/hub.py::get_required_domain"]
+["pipelex/interpreter_hub.py::get_required_domain"]
param = "domain_code"
rationale = "Hub getter keyed by the domain code; single operand."
-["pipelex/hub.py::get_required_pipe"]
+["pipelex/interpreter_hub.py::get_required_pipe"]
param = "pipe_code"
rationale = "Hub getter keyed by the pipe code; single operand."
-["pipelex/hub.py::get_secret"]
-param = "secret_id"
-rationale = "Hub getter keyed by the secret id; single operand."
-
-["pipelex/hub.py::resolve_library_dirs"]
+["pipelex/interpreter_hub.py::resolve_library_dirs"]
param = "library_dirs"
rationale = "Verb-object: resolves the given library dirs; single operand."
-["pipelex/hub.py::scoped_content_generator"]
-param = "content_generator"
-rationale = "Context manager scoping the given content generator; single self-labelling operand."
-
-["pipelex/hub.py::scoped_current_library"]
+["pipelex/interpreter_hub.py::scoped_current_library"]
param = "library_id"
rationale = "Context manager scoping to the library named by the id; single operand."
-["pipelex/hub.py::scoped_event_log"]
-param = "event_log"
-rationale = "Context manager scoping the given event log; single self-labelling operand."
-
-["pipelex/hub.py::scoped_pipe_func_executor"]
+["pipelex/interpreter_hub.py::scoped_pipe_func_executor"]
param = "pipe_func_executor"
rationale = "Scoped-binding context manager: binds the pipe-func executor for the block; single self-labelling operand."
-["pipelex/hub.py::scoped_pipe_router"]
+["pipelex/interpreter_hub.py::scoped_pipe_router"]
param = "pipe_router"
rationale = "Context manager scoping the given pipe router; single self-labelling operand."
-["pipelex/hub.py::set_current_library"]
+["pipelex/interpreter_hub.py::set_current_library"]
param = "library_id"
rationale = "Module-level setter: selects the library named by the id; single operand."
-["pipelex/hub.py::set_pipe_router"]
+["pipelex/interpreter_hub.py::set_interpreter_hub"]
+param = "interpreter_hub"
+rationale = "Module-level setter: installs the InterpreterHub singleton; single self-labelling operand."
+
+["pipelex/interpreter_hub.py::set_pipe_router"]
param = "pipe_router"
rationale = "Module-level setter: installs the pipe router; single self-labelling operand."
-["pipelex/hub.py::set_pipelex_hub"]
-param = "pipelex_hub"
-rationale = "Module-level setter: installs the hub singleton; single self-labelling operand."
-
["pipelex/kit/cursor_rules.py::_is_pipelex_managed"]
param = "mdc_path"
rationale = "Predicate on the .mdc file path; single operand."
@@ -3832,18 +3728,6 @@ rationale = "Verb-object: adds the concepts; single operand."
param = "concept"
rationale = "Verb-object: adds the concept; single operand."
-["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.get_native_concept"]
-param = "native_concept"
-rationale = "Library getter: the native concept being fetched; single operand."
-
-["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.get_required_concept"]
-param = "concept_ref"
-rationale = "Library getter keyed by the concept ref; single operand."
-
-["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.get_required_concept_from_concept_ref_or_code"]
-param = "concept_ref_or_code"
-rationale = "Library getter keyed by the ref-or-code; single operand."
-
["pipelex/libraries/concept/concept_library_abstract.py::ConceptLibraryAbstract.list_concepts_by_domain"]
param = "domain_code"
rationale = "Query keyed by the domain code it lists; single operand."
@@ -4094,7 +3978,7 @@ rationale = "Library getter keyed by the pipe code; single operand."
["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.get_required_pipe"]
param = "pipe_code"
-rationale = "Library getter keyed by the pipe code; single operand."
+rationale = "Resolver getter keyed by the pipe code; single operand."
["pipelex/libraries/pipe/pipe_library_abstract.py::PipeLibraryAbstract.remove_pipes_by_refs"]
param = "pipe_refs"
@@ -5384,6 +5268,118 @@ rationale = "Verb-object: serializes the pipe output; workflow_id stays keyword.
param = "pipe_output"
rationale = "Verb-object: serializes the pipe output; single operand."
+["pipelex/runtime_hub.py::RuntimeHub.set_bundle_validator_registry"]
+param = "bundle_validator_registry"
+rationale = "Hub setter: installs the bundle validator registry; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_config"]
+param = "config"
+rationale = "Hub setter: installs the config; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_console"]
+param = "console"
+rationale = "Hub setter: installs the console; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_console_print_target"]
+param = "target"
+rationale = "Hub setter: installs the print target; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_content_generator"]
+param = "content_generator"
+rationale = "Hub setter: installs the content generator; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_func_registry"]
+param = "func_registry"
+rationale = "Hub setter: installs the func registry; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_inference_backend_registry"]
+param = "inference_backend_registry"
+rationale = "Hub setter: installs the inference backend registry; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_inference_manager"]
+param = "inference_manager"
+rationale = "Hub setter: installs the inference manager; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_instance"]
+param = "runtime_hub"
+rationale = "Hub setter: installs the RuntimeHub singleton; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_isolated_execution_probe"]
+param = "probe"
+rationale = "Hub setter: installs the execution probe; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_model_lister_registry"]
+param = "model_lister_registry"
+rationale = "Hub setter: installs the model lister registry; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_models_manager"]
+param = "models_manager"
+rationale = "Hub setter: installs the models manager; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_orchestrator_registry"]
+param = "orchestrator_registry"
+rationale = "Hub setter: installs the orchestrator registry; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_report_delegate"]
+param = "reporting_delegate"
+rationale = "Hub setter: installs the reporting delegate; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_sdk_client_manager"]
+param = "sdk_client_manager"
+rationale = "Hub setter: installs the SDK client manager; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_secrets_provider"]
+param = "secrets_provider"
+rationale = "Hub setter: installs the secrets provider; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_secrets_provider_registry"]
+param = "secrets_provider_registry"
+rationale = "Hub setter: the registry is the operand being installed."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_storage_provider"]
+param = "storage_provider"
+rationale = "Hub setter: installs the storage provider; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_storage_provider_registry"]
+param = "storage_provider_registry"
+rationale = "Hub setter: the registry is the operand being installed."
+
+["pipelex/runtime_hub.py::RuntimeHub.set_telemetry_manager"]
+param = "telemetry_manager"
+rationale = "Hub setter: installs the telemetry manager; single self-labelling operand."
+
+["pipelex/runtime_hub.py::RuntimeHub.setup_config"]
+param = "config_cls"
+rationale = "Sets up config from the given config class; single operand."
+
+["pipelex/runtime_hub.py::get_extract_worker"]
+param = "extract_handle"
+rationale = "Hub getter keyed by the worker's handle; single operand."
+
+["pipelex/runtime_hub.py::get_img_gen_worker"]
+param = "img_gen_handle"
+rationale = "Hub getter keyed by the worker's handle; single operand."
+
+["pipelex/runtime_hub.py::get_llm_worker"]
+param = "llm_handle"
+rationale = "Hub getter keyed by the worker's handle; single operand."
+
+["pipelex/runtime_hub.py::get_secret"]
+param = "secret_id"
+rationale = "Hub getter keyed by the secret id; single operand."
+
+["pipelex/runtime_hub.py::scoped_content_generator"]
+param = "content_generator"
+rationale = "Context manager scoping the given content generator; single self-labelling operand."
+
+["pipelex/runtime_hub.py::scoped_event_log"]
+param = "event_log"
+rationale = "Context manager scoping the given event log; single self-labelling operand."
+
+["pipelex/runtime_hub.py::set_runtime_hub"]
+param = "runtime_hub"
+rationale = "Module-level setter: installs the RuntimeHub singleton; single self-labelling operand."
+
["pipelex/system/configuration/config_loader.py::ConfigLoader._override_files_for_dir"]
param = "config_dir"
rationale = "Derivation from the config dir; single operand."
@@ -5740,6 +5736,10 @@ rationale = "Positional Callable protocol: replaces client.capture_exception, in
param = "event_name"
rationale = "Verb-object: tracks the event named; properties stay keyword."
+["pipelex/system/trace_context.py::TraceContext.copy_for_child"]
+param = "child_node_id"
+rationale = "Verb-object: copies the context for the child node; sequence stays keyword."
+
["pipelex/test_extras/shared_pytest_plugins.py::_cleanup_placeholder_env_vars"]
param = "env_var_keys"
rationale = "Verb-object: the env-var keys being cleaned up; single operand."
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
index dbd45fd09..f63ac1aaf 100644
--- a/tests/CLAUDE.md
+++ b/tests/CLAUDE.md
@@ -49,7 +49,7 @@ Fall back to the full suite when:
- Changes span 3+ source areas from the mapping above
- Changes touch `pyproject.toml`, `tests/conftest.py`, or `tests/helpers/`
-- Changes touch root-level modules: `pipelex/__init__.py`, `pipelex/hub.py`
+- Changes touch root-level modules: `pipelex/__init__.py`, `pipelex/runtime_hub.py`, `pipelex/interpreter_hub.py`
- Changes touch `pipelex/system/configuration/` (config loading affects everything)
- Refactors touching base exceptions or shared base classes
- Preparing a release, a push, or a commit intended for remote (e.g. `/release`, `/commit-push`, `/ship`, or when the context makes it obvious the work is about to land)
diff --git a/tests/cases/jinja2_templates.py b/tests/cases/jinja2_templates.py
index dd33c9612..623f9f894 100644
--- a/tests/cases/jinja2_templates.py
+++ b/tests/cases/jinja2_templates.py
@@ -2,8 +2,8 @@
from typing import Any, ClassVar
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
from tests.cases.registry import Fruit
diff --git a/tests/conftest.py b/tests/conftest.py
index a31fbaf84..70bd9347e 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -7,9 +7,9 @@ import shortuuid
from pytest_mock import MockerFixture
from pipelex import log
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipelex import Pipelex
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipelex_service.pipelex_service_config import (
PipelexServiceConfig,
)
diff --git a/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py b/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py
index d5683e418..9948ff51d 100644
--- a/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py
+++ b/tests/e2e/pipelex/concepts/nested_concepts/test_structure_generator_cli.py
@@ -26,7 +26,7 @@ from pipelex.codegen.emission import write_stamped_projection
from pipelex.codegen.emitters.target import CodegenKind, CodegenTarget
from pipelex.codegen.emitters.types_emitter import emit_types
from pipelex.codegen.lock import CODEGEN_LOCK_FILENAME
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.libraries.crate_normalization import normalize_crate
from pipelex.pipeline.execution_seams import load_libraries_and_activate
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_1.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_1.py
index 728b90340..f04cd9cd6 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_1.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_1.py
@@ -7,11 +7,11 @@ from pipelex import pretty_print
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition import CategoryInput
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_2.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_2.py
index c7c62eeb5..684df3e22 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_2.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_2.py
@@ -7,11 +7,11 @@ from pipelex import pretty_print
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition import CategoryInput
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_simple.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_simple.py
index ee9aa6d61..e06b716fb 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_simple.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_condition/test_pipe_condition_simple.py
@@ -16,7 +16,7 @@ from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeCond
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition import CategoryInput
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_1.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_1.py
index 6ee5d6624..28073008c 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_1.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_1.py
@@ -7,11 +7,11 @@ from pipelex import pretty_print
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_parallel.pipe_parallel import ContentAnalysis, DocumentInput, LengthAnalysis
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py
index b0a5afd8a..6a6019241 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_batching.py
@@ -10,11 +10,11 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.inputs.input_stuff_specs import TypedNamedStuffSpec
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_required_pipe
+from pipelex.interpreter_hub import get_required_pipe
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_sequence.pipe_sequence import Document, ProductRating
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_simple.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_simple.py
index d00e5cf67..bc2149408 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_simple.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_sequence/test_pipe_sequence_simple.py
@@ -10,10 +10,10 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_required_pipe
+from pipelex.interpreter_hub import get_required_pipe
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py
index 762b9d8e4..aacd5898e 100644
--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py
+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py
@@ -18,10 +18,10 @@ import pytest
from pytest import MonkeyPatch
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.hub import get_console, get_model_deck
from pipelex.pipelex import Pipelex
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.runtime_hub import get_console, get_model_deck
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
diff --git a/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py
index 8d5a93037..8f6d57f67 100644
--- a/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py
+++ b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py
@@ -18,8 +18,8 @@ from typing import TYPE_CHECKING, Any
import pytest
-from pipelex.core.pipes.inputs.input_renderer import render_inputs
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library
+from pipelex.core.pipes.rendering.input_renderer import render_inputs
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.pipeline_response import RunState
from pipelex.pipeline.runner import PipelexMTHDSProtocol
diff --git a/tests/helpers/init_cmd_helpers.py b/tests/helpers/init_cmd_helpers.py
index 612388ee7..dee8e3022 100644
--- a/tests/helpers/init_cmd_helpers.py
+++ b/tests/helpers/init_cmd_helpers.py
@@ -200,7 +200,7 @@ class MockedInitEnvironment:
self.mock_console = self.mocker.MagicMock()
# Patch modules that use the Pipelex hub console provider
- self.mocker.patch("pipelex.hub.get_console", return_value=self.mock_console)
+ self.mocker.patch("pipelex.runtime_hub.get_console", return_value=self.mock_console)
self.mocker.patch("pipelex.cli.commands.init.command.get_console", return_value=self.mock_console)
self.mocker.patch("pipelex.cli.commands.init.backends.get_console", return_value=self.mock_console)
self.mocker.patch("pipelex.cli.commands.init.routing.get_console", return_value=self.mock_console)
diff --git a/tests/integration/pipelex/builder/concept/test_concept_spec_generation.py b/tests/integration/pipelex/builder/concept/test_concept_spec_generation.py
index a9603c42c..f1b0f4584 100644
--- a/tests/integration/pipelex/builder/concept/test_concept_spec_generation.py
+++ b/tests/integration/pipelex/builder/concept/test_concept_spec_generation.py
@@ -5,8 +5,8 @@ from pipelex.builder.concept.concept_spec import ConceptSpec
from pipelex.cogt.llm.llm_job_components import LLMJobConfig, LLMJobParams
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_llm_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.builder.concept.integration_test_data import ConceptSpecGenerationTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/builder/operations/test_runner_code_ops_library_lifecycle.py b/tests/integration/pipelex/builder/operations/test_runner_code_ops_library_lifecycle.py
index b18e091ea..da5cdb309 100644
--- a/tests/integration/pipelex/builder/operations/test_runner_code_ops_library_lifecycle.py
+++ b/tests/integration/pipelex/builder/operations/test_runner_code_ops_library_lifecycle.py
@@ -15,12 +15,7 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.builder.operations.runner_code_ops import build_runner_code_for_pipe
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
_RC_DOMAIN = "runner_code_lifecycle"
diff --git a/tests/integration/pipelex/builder/operations/test_validate_pipe_library_lifecycle.py b/tests/integration/pipelex/builder/operations/test_validate_pipe_library_lifecycle.py
index c3f075492..4f53f60f5 100644
--- a/tests/integration/pipelex/builder/operations/test_validate_pipe_library_lifecycle.py
+++ b/tests/integration/pipelex/builder/operations/test_validate_pipe_library_lifecycle.py
@@ -17,12 +17,7 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.builder.operations.validate_ops import validate_pipe
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
_LIFECYCLE_DOMAIN = "validate_pipe_lifecycle"
diff --git a/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py b/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py
index 734b0a1cd..b8a7f2971 100644
--- a/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py
+++ b/tests/integration/pipelex/cli/agent_cli/test_run_cost_report.py
@@ -19,7 +19,7 @@ from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemory
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
_RUN_CORE_MODULE = "pipelex.cli.agent_cli.commands.run._run_core"
diff --git a/tests/integration/pipelex/cli/commands/test_build_runner_flow.py b/tests/integration/pipelex/cli/commands/test_build_runner_flow.py
index 5bfc5aa2f..8f3a1625e 100644
--- a/tests/integration/pipelex/cli/commands/test_build_runner_flow.py
+++ b/tests/integration/pipelex/cli/commands/test_build_runner_flow.py
@@ -13,7 +13,7 @@ import pytest
from pipelex.cli.commands.build.runner._runner_core import _prepare_runner_core # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
from pipelex.codegen.lock import CODEGEN_LOCK_FILENAME
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager
_BUNDLE_MTHDS = """\
domain = "runnerflow"
diff --git a/tests/integration/pipelex/cli/test_agent_validate_pipe_core_library_lifecycle.py b/tests/integration/pipelex/cli/test_agent_validate_pipe_core_library_lifecycle.py
index e76b598ac..7cbfefcde 100644
--- a/tests/integration/pipelex/cli/test_agent_validate_pipe_core_library_lifecycle.py
+++ b/tests/integration/pipelex/cli/test_agent_validate_pipe_core_library_lifecycle.py
@@ -19,12 +19,7 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.cli.agent_cli.commands.validate._validate_core import validate_pipe_core # noqa: PLC2701
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
_LIFECYCLE_DOMAIN = "agent_validate_pipe_core_lifecycle"
diff --git a/tests/integration/pipelex/codegen/test_resolve_flow.py b/tests/integration/pipelex/codegen/test_resolve_flow.py
index 59d980a50..64ba36eb5 100644
--- a/tests/integration/pipelex/codegen/test_resolve_flow.py
+++ b/tests/integration/pipelex/codegen/test_resolve_flow.py
@@ -13,7 +13,7 @@ from pipelex.codegen.emitters.target import CodegenTarget
from pipelex.codegen.emitters.types_emitter import emit_types
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.crate_normalization import normalize_crate
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
diff --git a/tests/integration/pipelex/cogt/config_coverage/test_cc_extract.py b/tests/integration/pipelex/cogt/config_coverage/test_cc_extract.py
index 050ad2296..5dd7d2e6d 100644
--- a/tests/integration/pipelex/cogt/config_coverage/test_cc_extract.py
+++ b/tests/integration/pipelex/cogt/config_coverage/test_cc_extract.py
@@ -4,8 +4,8 @@ from pipelex import log, pretty_print
from pipelex.cogt.extract.extract_input import ExtractInput
from pipelex.cogt.extract.extract_job_components import ExtractJobParams
from pipelex.cogt.extract.extract_job_factory import ExtractJobFactory
-from pipelex.hub import get_extract_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_extract_worker
+from pipelex.system.job_metadata import JobMetadata
from tests.cases.documents import DocumentTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/config_coverage/test_cc_img_gen.py b/tests/integration/pipelex/cogt/config_coverage/test_cc_img_gen.py
index e2dc4b051..d7df3ad23 100644
--- a/tests/integration/pipelex/cogt/config_coverage/test_cc_img_gen.py
+++ b/tests/integration/pipelex/cogt/config_coverage/test_cc_img_gen.py
@@ -3,8 +3,8 @@ import pytest
from pipelex import log, pretty_print
from pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobParams
from pipelex.cogt.img_gen.img_gen_job_factory import ImgGenJobFactory
-from pipelex.hub import get_img_gen_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_img_gen_worker
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/config_coverage/test_cc_llm.py b/tests/integration/pipelex/cogt/config_coverage/test_cc_llm.py
index 248569b1f..f83db2316 100644
--- a/tests/integration/pipelex/cogt/config_coverage/test_cc_llm.py
+++ b/tests/integration/pipelex/cogt/config_coverage/test_cc_llm.py
@@ -4,8 +4,8 @@ from pipelex import log, pretty_print
from pipelex.cogt.llm.llm_job_components import LLMJobParams
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_inference_manager
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_inference_manager
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/config_coverage/test_cc_search.py b/tests/integration/pipelex/cogt/config_coverage/test_cc_search.py
index 9749f6a25..05b9c0798 100644
--- a/tests/integration/pipelex/cogt/config_coverage/test_cc_search.py
+++ b/tests/integration/pipelex/cogt/config_coverage/test_cc_search.py
@@ -5,8 +5,8 @@ from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.search.search_job_factory import SearchJobFactory
from pipelex.cogt.search.search_setting import SearchSetting
from pipelex.cogt.search.search_worker_factory import SearchWorkerFactory
-from pipelex.hub import get_model_deck
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py b/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py
index c16ff1c59..066418838 100644
--- a/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py
+++ b/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py
@@ -20,7 +20,7 @@ from pipelex.cogt.content_generation.exceptions import DryRunObjectFidelityError
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.content_generation.test_data import ConstrainedName, PlainName
diff --git a/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py b/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py
index 2956e7a95..4fbeac320 100644
--- a/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py
+++ b/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py
@@ -28,7 +28,7 @@ from pipelex.cogt.search.search_setting import SearchSetting
from pipelex.config import get_config
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.content_generation.test_data import ConstrainedName
diff --git a/tests/integration/pipelex/cogt/test_content_generator.py b/tests/integration/pipelex/cogt/test_content_generator.py
index d632139d3..4b42fe774 100644
--- a/tests/integration/pipelex/cogt/test_content_generator.py
+++ b/tests/integration/pipelex/cogt/test_content_generator.py
@@ -11,9 +11,9 @@ from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.page_content import PageContent
-from pipelex.hub import get_model_deck
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from tests.cases import DocumentTestCases, ImageTestCases
from tests.integration.pipelex.cogt.test_data import Employee
diff --git a/tests/integration/pipelex/cogt/test_extract.py b/tests/integration/pipelex/cogt/test_extract.py
index 7dc5f26ea..eb1974064 100644
--- a/tests/integration/pipelex/cogt/test_extract.py
+++ b/tests/integration/pipelex/cogt/test_extract.py
@@ -5,8 +5,8 @@ from pipelex.cogt.content_generation.generated_content_factory import GeneratedC
from pipelex.cogt.extract.extract_input import ExtractInput
from pipelex.cogt.extract.extract_job_components import ExtractJobParams
from pipelex.cogt.extract.extract_job_factory import ExtractJobFactory
-from pipelex.hub import get_extract_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_extract_worker
+from pipelex.system.job_metadata import JobMetadata
from tests.cases import DocumentTestCases, ImageTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_img2img.py b/tests/integration/pipelex/cogt/test_img2img.py
index e4595c052..826aac4c0 100644
--- a/tests/integration/pipelex/cogt/test_img2img.py
+++ b/tests/integration/pipelex/cogt/test_img2img.py
@@ -10,8 +10,8 @@ from pipelex.cogt.image.prompt_image import PromptImage, PromptImageUri
from pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, Background, ImgGenJobParams
from pipelex.cogt.img_gen.img_gen_job_factory import ImgGenJobFactory
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
-from pipelex.hub import get_img_gen_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_img_gen_worker
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.image_utils import ImageFormat
from tests.cases import ImageTestCases
from tests.integration.pipelex.fixtures.img_gen_fixtures import skip_if_img_gen_params_unsupported
diff --git a/tests/integration/pipelex/cogt/test_img_gen.py b/tests/integration/pipelex/cogt/test_img_gen.py
index 5dfeb1abe..aea40fa39 100644
--- a/tests/integration/pipelex/cogt/test_img_gen.py
+++ b/tests/integration/pipelex/cogt/test_img_gen.py
@@ -4,8 +4,8 @@ from pipelex import pretty_print, pretty_print_url
from pipelex.cogt.content_generation.generated_content_factory import GeneratedContentFactory
from pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, Background, ImgGenJobParams
from pipelex.cogt.img_gen.img_gen_job_factory import ImgGenJobFactory
-from pipelex.hub import get_img_gen_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_img_gen_worker
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.image_utils import ImageFormat
from tests.integration.pipelex.fixtures.img_gen_fixtures import skip_if_img_gen_params_unsupported
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_img_gen_param_support.py b/tests/integration/pipelex/cogt/test_img_gen_param_support.py
index dcd177008..900db33cb 100644
--- a/tests/integration/pipelex/cogt/test_img_gen_param_support.py
+++ b/tests/integration/pipelex/cogt/test_img_gen_param_support.py
@@ -17,7 +17,7 @@ from pipelex.cogt.img_gen.img_gen_job_components import (
)
from pipelex.cogt.img_gen.img_gen_param_support import ImgGenParamSupport
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.hub import get_model_deck
+from pipelex.runtime_hub import get_model_deck
from pipelex.tools.misc.image_utils import ImageFormat
diff --git a/tests/integration/pipelex/cogt/test_llm_document.py b/tests/integration/pipelex/cogt/test_llm_document.py
index 152dc618c..14bc9cb79 100644
--- a/tests/integration/pipelex/cogt/test_llm_document.py
+++ b/tests/integration/pipelex/cogt/test_llm_document.py
@@ -8,8 +8,8 @@ from pipelex.cogt.exceptions import LLMCapabilityError
from pipelex.cogt.llm.llm_job_components import LLMJobParams
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_llm_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import LLMDocumentTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_llm_gen_object.py b/tests/integration/pipelex/cogt/test_llm_gen_object.py
index 3810f6d4a..ea8884bfb 100644
--- a/tests/integration/pipelex/cogt/test_llm_gen_object.py
+++ b/tests/integration/pipelex/cogt/test_llm_gen_object.py
@@ -7,8 +7,8 @@ from pipelex import pretty_print
from pipelex.cogt.llm.llm_job_components import LLMJobConfig, LLMJobParams
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_llm_worker, get_model_deck
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import LLMTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_llm_gen_text.py b/tests/integration/pipelex/cogt/test_llm_gen_text.py
index 8f64cea7d..bf547defc 100644
--- a/tests/integration/pipelex/cogt/test_llm_gen_text.py
+++ b/tests/integration/pipelex/cogt/test_llm_gen_text.py
@@ -9,8 +9,8 @@ from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
from pipelex.cogt.model_backends.constraints import ListedConstraint, ValuedConstraint
-from pipelex.hub import get_llm_worker, get_model_deck
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import LLMTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_llm_generate_security.py b/tests/integration/pipelex/cogt/test_llm_generate_security.py
index 3b0277853..785c17850 100644
--- a/tests/integration/pipelex/cogt/test_llm_generate_security.py
+++ b/tests/integration/pipelex/cogt/test_llm_generate_security.py
@@ -16,7 +16,7 @@ from pipelex.cogt.content_generation.llm_generate import llm_gen_object, llm_gen
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
def _make_stub_llm_assignment() -> LLMAssignment:
diff --git a/tests/integration/pipelex/cogt/test_llm_inference.py b/tests/integration/pipelex/cogt/test_llm_inference.py
index e6379c40d..7716e1b23 100644
--- a/tests/integration/pipelex/cogt/test_llm_inference.py
+++ b/tests/integration/pipelex/cogt/test_llm_inference.py
@@ -7,8 +7,8 @@ from pipelex.cogt.image.prompt_image import PromptImageUri
from pipelex.cogt.llm.llm_job_components import LLMJobParams
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_inference_manager
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_inference_manager
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import ImageDescription, LLMTestConstants, LLMVisionTestCases, Person
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_llm_reasoning.py b/tests/integration/pipelex/cogt/test_llm_reasoning.py
index eafd77ccb..1daaf619d 100644
--- a/tests/integration/pipelex/cogt/test_llm_reasoning.py
+++ b/tests/integration/pipelex/cogt/test_llm_reasoning.py
@@ -5,8 +5,8 @@ from pipelex.cogt.exceptions import LLMCapabilityError
from pipelex.cogt.llm.llm_job_components import LLMJobConfig, LLMJobParams, ReasoningEffort
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_llm_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import LLMReasoningTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_llm_report.py b/tests/integration/pipelex/cogt/test_llm_report.py
index a232b67ab..98fc7d6f1 100644
--- a/tests/integration/pipelex/cogt/test_llm_report.py
+++ b/tests/integration/pipelex/cogt/test_llm_report.py
@@ -6,8 +6,8 @@ from pipelex import pretty_print
from pipelex.cogt.llm.llm_job_components import LLMJobConfig
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_llm_worker, get_model_deck
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker, get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import LLMTestCases
diff --git a/tests/integration/pipelex/cogt/test_llm_vision.py b/tests/integration/pipelex/cogt/test_llm_vision.py
index bf1b4ad7c..c2bb0eb5f 100644
--- a/tests/integration/pipelex/cogt/test_llm_vision.py
+++ b/tests/integration/pipelex/cogt/test_llm_vision.py
@@ -9,8 +9,8 @@ from pipelex.cogt.image.prompt_image_factory import PromptImageFactory
from pipelex.cogt.llm.llm_job_components import LLMJobParams
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
-from pipelex.hub import get_llm_worker
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_llm_worker
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.base64_utils import load_binary_as_base64
from tests.integration.pipelex.cogt.test_data import LLMVisionTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_search.py b/tests/integration/pipelex/cogt/test_search.py
index 22e0b7cdc..3f1c39a08 100644
--- a/tests/integration/pipelex/cogt/test_search.py
+++ b/tests/integration/pipelex/cogt/test_search.py
@@ -6,8 +6,8 @@ from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.search.search_job_factory import SearchJobFactory
from pipelex.cogt.search.search_setting import SearchSetting
from pipelex.cogt.search.search_worker_factory import SearchWorkerFactory
-from pipelex.hub import get_model_deck
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_model_deck
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.cogt.test_data import SearchTestCases
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
diff --git a/tests/integration/pipelex/cogt/test_setup_inference_workers.py b/tests/integration/pipelex/cogt/test_setup_inference_workers.py
index 72e36abf4..19ac73373 100644
--- a/tests/integration/pipelex/cogt/test_setup_inference_workers.py
+++ b/tests/integration/pipelex/cogt/test_setup_inference_workers.py
@@ -1,5 +1,5 @@
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.hub import get_inference_manager, get_model_deck
+from pipelex.runtime_hub import get_inference_manager, get_model_deck
class TestSetupInferenceWorkers:
diff --git a/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py b/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py
index e0eada7cb..b482b4ec7 100644
--- a/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py
+++ b/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py
@@ -4,7 +4,7 @@ from collections.abc import Callable
from pathlib import Path
from pipelex.core.concepts.concept import Concept
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
class TestRefinesCustomConcept:
diff --git a/tests/integration/pipelex/core/memory/test_working_memory_factory.py b/tests/integration/pipelex/core/memory/test_working_memory_factory.py
index a6222dc47..dc386e65a 100644
--- a/tests/integration/pipelex/core/memory/test_working_memory_factory.py
+++ b/tests/integration/pipelex/core/memory/test_working_memory_factory.py
@@ -9,7 +9,7 @@ from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from tests.cases.images import ImageTestCases
if TYPE_CHECKING:
@@ -26,7 +26,7 @@ class TestWorkingMemoryFactory:
},
}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, concept_provider=get_concept_library())
assert working_memory is not None
assert "text_item" in working_memory.root
@@ -62,7 +62,7 @@ class TestWorkingMemoryFactory:
},
}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, concept_provider=get_concept_library())
assert working_memory is not None
assert "complex_page" in working_memory.root
@@ -111,7 +111,7 @@ class TestWorkingMemoryFactory:
"""Test deserialization of empty compact memory."""
pipeline_inputs: PipelineInputs = {}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, concept_provider=get_concept_library())
assert working_memory is not None
assert len(working_memory.root) == 0
@@ -130,7 +130,7 @@ class TestWorkingMemoryFactory:
},
}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, concept_provider=get_concept_library())
assert working_memory is not None
assert len(working_memory.root) == 2
@@ -154,7 +154,9 @@ class TestWorkingMemoryFactory:
# A bare string is narrower than the PipelineInputs alias formally admits, but flows at runtime.
pipeline_inputs: dict[str, Any] = {"greeting": "hello"}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, input_specs=None)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(
+ pipeline_inputs=pipeline_inputs, input_specs=None, concept_provider=get_concept_library()
+ )
stuff = working_memory.root["greeting"]
assert stuff.concept.code == NativeConceptCode.TEXT
@@ -170,7 +172,9 @@ class TestWorkingMemoryFactory:
input_specs = InputStuffSpecs(root={"count": StuffSpec(concept=number_concept)})
pipeline_inputs: dict[str, Any] = {"count": 42}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, input_specs=input_specs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(
+ pipeline_inputs=pipeline_inputs, input_specs=input_specs, concept_provider=get_concept_library()
+ )
stuff = working_memory.root["count"]
assert stuff.concept.code == NativeConceptCode.NUMBER
diff --git a/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py b/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py
index 2a0403c45..c9894c4b8 100644
--- a/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py
+++ b/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py
@@ -21,8 +21,8 @@ from typing import TYPE_CHECKING, Any, cast
import pytest
import tomli
-from pipelex.core.pipes.inputs.input_renderer import render_inputs, render_inputs_toml
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library
+from pipelex.core.pipes.rendering.input_renderer import render_inputs, render_inputs_toml
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library
from pipelex.pipeline.validate_bundle import validate_bundle
if TYPE_CHECKING:
diff --git a/tests/integration/pipelex/csv/test_csv_input_detection.py b/tests/integration/pipelex/csv/test_csv_input_detection.py
index 81560403b..3761ee4de 100644
--- a/tests/integration/pipelex/csv/test_csv_input_detection.py
+++ b/tests/integration/pipelex/csv/test_csv_input_detection.py
@@ -21,6 +21,7 @@ import pytest
from pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths # noqa: PLC2701
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.list_content import ListContent
+from pipelex.interpreter_hub import get_concept_library
from pipelex.tools.tabular.exceptions import CsvError
if TYPE_CHECKING:
@@ -59,7 +60,7 @@ class TestCsvInputDetection:
load_test_library([BUNDLE_DIR])
inputs: PipelineInputs = {"people": {"concept": "csv_demo.Person", "content": {"url": remote_url}}}
with pytest.raises(CsvError) as exc_info:
- WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
message = str(exc_info.value)
assert "local" in message.lower()
# The path is preserved so the user can identify the offending input...
@@ -79,7 +80,7 @@ class TestCsvInputDetection:
assert resolved["people"]["content"]["url"] == "s3://bucket/people.csv" # not rewritten
inputs = cast("PipelineInputs", resolved)
with pytest.raises(CsvError) as exc_info:
- WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
assert "local" in str(exc_info.value).lower()
def test_xlsx_input_routes_to_tabular_seam(self, load_test_library: Callable[[list[Path]], None]) -> None:
@@ -88,7 +89,7 @@ class TestCsvInputDetection:
# raises a clear "needs pipelex[tabular]" CsvError (the Excel backend isn't built in v1).
inputs: PipelineInputs = {"people": {"concept": "csv_demo.Person", "content": {"url": "people.xlsx"}}}
with pytest.raises(CsvError) as exc_info:
- WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
assert "pipelex[tabular]" in str(exc_info.value)
def test_unparseable_url_rejected_without_leak(self, load_test_library: Callable[[list[Path]], None]) -> None:
@@ -98,7 +99,7 @@ class TestCsvInputDetection:
bad_url = "https://[bad/people.csv?token=abc"
inputs: PipelineInputs = {"people": {"concept": "csv_demo.Person", "content": {"url": bad_url}}}
with pytest.raises(CsvError) as exc_info:
- WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
message = str(exc_info.value)
assert "local" in message.lower()
# The unparseable url can't be sanitized, so it is not echoed at all — the token must not leak.
@@ -108,7 +109,7 @@ class TestCsvInputDetection:
load_test_library([URL_FIELD_DIR])
# url field value that is NOT a tabular suffix → ordinary single record, not a CSV table.
inputs: PipelineInputs = {"link": {"concept": "url_field_concept.Link", "content": {"label": "Home", "url": "https://example.com"}}}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
content = working_memory.get_stuff("link").content
assert not isinstance(content, ListContent)
@@ -121,7 +122,7 @@ class TestCsvInputDetection:
# A record that has sibling keys alongside a .csv-suffixed `url` is NOT a table reference:
# detection is gated to the bare {"url": ...} wrapper, so the siblings are never dropped.
inputs: PipelineInputs = {"link": {"concept": "url_field_concept.Link", "content": {"label": "Home", "url": "report.csv"}}}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
content = working_memory.get_stuff("link").content
assert not isinstance(content, ListContent)
@@ -133,7 +134,7 @@ class TestCsvInputDetection:
load_test_library([URL_FIELD_DIR])
# The file-level url ends .csv → read as a table; the inner `url` column is plain data.
inputs: PipelineInputs = {"links": {"concept": "url_field_concept.Link", "content": {"url": str(LINKS_CSV)}}}
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
content = working_memory.get_stuff("links").content
assert isinstance(content, ListContent)
@@ -148,7 +149,7 @@ class TestCsvInputDetection:
people_csv.write_text(PEOPLE_CSV.read_text(encoding="utf-8"), encoding="utf-8")
inputs: PipelineInputs = {"people": {"concept": "csv_demo.Person", "content": {"url": str(people_csv)}}}
- first = WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ first = WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
first_people = cast("ListContent[StuffContent]", first.get_stuff("people").content)
assert len(first_people.items) == 3
@@ -157,6 +158,6 @@ class TestCsvInputDetection:
"name,job,country,birth_year,death_year\nAda Lovelace,Mathematician,United Kingdom,1815,1852\n",
encoding="utf-8",
)
- second = WorkingMemoryFactory.make_from_pipeline_inputs(inputs)
+ second = WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library())
second_people = cast("ListContent[StuffContent]", second.get_stuff("people").content)
assert len(second_people.items) == 1
diff --git a/tests/integration/pipelex/csv/test_csv_roundtrip.py b/tests/integration/pipelex/csv/test_csv_roundtrip.py
index 1e965e51c..ad723093f 100644
--- a/tests/integration/pipelex/csv/test_csv_roundtrip.py
+++ b/tests/integration/pipelex/csv/test_csv_roundtrip.py
@@ -25,7 +25,7 @@ from mthds.protocol.pipeline_inputs import PipelineInputs
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.list_content import ListContent
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_concept_library, get_library_manager
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.tools.tabular.csv_codec import csv_from_list_content
@@ -52,7 +52,7 @@ class TestCsvRoundtrip:
def test_csv_input_builds_typed_list(self, load_test_library: Callable[[list[Path]], None]) -> None:
load_test_library([BUNDLE_DIR])
- working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(people_inputs())
+ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(people_inputs(), concept_provider=get_concept_library())
people = working_memory.get_stuff("people").content
assert isinstance(people, ListContent)
diff --git a/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py b/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py
index d34ea945d..3de727085 100644
--- a/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py
+++ b/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py
@@ -20,7 +20,7 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.cogt.content_generation.content_generator import ContentGenerator
-from pipelex.hub import get_pipe_router
+from pipelex.interpreter_hub import get_pipe_router
from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
diff --git a/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py b/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py
index b4994a67b..8625b9ed4 100644
--- a/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py
+++ b/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py
@@ -18,7 +18,7 @@ from pytest_mock import MockerFixture
from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.cogt.exceptions import SearchJobFailureError
-from pipelex.hub import get_pipe_router
+from pipelex.interpreter_hub import get_pipe_router
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from tests.integration.pipelex.error_handling.test_data import SearchErrorReportParityTestData
diff --git a/tests/integration/pipelex/fixtures/combo_fixtures.py b/tests/integration/pipelex/fixtures/combo_fixtures.py
index 81aff787e..05d445386 100644
--- a/tests/integration/pipelex/fixtures/combo_fixtures.py
+++ b/tests/integration/pipelex/fixtures/combo_fixtures.py
@@ -24,8 +24,8 @@ from pathlib import Path
import pytest
from pytest import MonkeyPatch
-from pipelex.hub import get_console
from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import get_console
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
diff --git a/tests/integration/pipelex/fixtures/extract_fixtures.py b/tests/integration/pipelex/fixtures/extract_fixtures.py
index 38469edc0..d96907d21 100644
--- a/tests/integration/pipelex/fixtures/extract_fixtures.py
+++ b/tests/integration/pipelex/fixtures/extract_fixtures.py
@@ -6,7 +6,7 @@ import pytest
from pipelex.cogt.extract.extract_job_components import ExtractJobParams
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.hub import get_model_deck
+from pipelex.runtime_hub import get_model_deck
from pipelex.system.configuration.configs import ConfigPaths
from pipelex.tools.misc.toml_utils import load_toml_from_path
diff --git a/tests/integration/pipelex/fixtures/generator_fixtures.py b/tests/integration/pipelex/fixtures/generator_fixtures.py
index 352a864d5..697cd2234 100644
--- a/tests/integration/pipelex/fixtures/generator_fixtures.py
+++ b/tests/integration/pipelex/fixtures/generator_fixtures.py
@@ -6,7 +6,7 @@ from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocol
from pipelex.cogt.content_generation.generated_content_factory import GeneratedContentFactory
from pipelex.config import get_config
-from pipelex.hub import get_storage_provider_registry
+from pipelex.runtime_hub import get_storage_provider_registry
from pipelex.tools.storage.storage_config import StorageMethod
S3_TEST_BUCKET = "pipelex-storage-test"
diff --git a/tests/integration/pipelex/fixtures/llm_fixtures.py b/tests/integration/pipelex/fixtures/llm_fixtures.py
index 3bb8fb89a..205d459c0 100644
--- a/tests/integration/pipelex/fixtures/llm_fixtures.py
+++ b/tests/integration/pipelex/fixtures/llm_fixtures.py
@@ -6,7 +6,7 @@ from pipelex import log
from pipelex.cogt.image.prompt_image import PromptImageDetail
from pipelex.cogt.llm.llm_job_components import LLMJobParams
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.hub import get_model_deck
+from pipelex.runtime_hub import get_model_deck
# ================================================================================================
# LLM model collections are now defined in .pipelex-dev/test_profiles.toml
diff --git a/tests/integration/pipelex/fixtures/pipe_job_helpers.py b/tests/integration/pipelex/fixtures/pipe_job_helpers.py
index 0994c90d0..8864426ee 100644
--- a/tests/integration/pipelex/fixtures/pipe_job_helpers.py
+++ b/tests/integration/pipelex/fixtures/pipe_job_helpers.py
@@ -6,14 +6,14 @@ from pipelex.core.interpreter.interpreter import PipelexInterpreter
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_abstract import PipeAbstract
-from pipelex.hub import clear_current_library, get_library_manager, get_required_pipe, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_library_manager, get_required_pipe, set_current_library
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.pipeline.pipeline_models import SpecialPipelineId
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.telemetry.otel_constants import OTelConstants
PIPE_JOB_HELPERS_PIPELINE_RUN_ID_PREFIX = "pipe_job_helpers_test"
diff --git a/tests/integration/pipelex/libraries/test_concept_to_concept_references.py b/tests/integration/pipelex/libraries/test_concept_to_concept_references.py
index 0069729f7..3786bf23b 100644
--- a/tests/integration/pipelex/libraries/test_concept_to_concept_references.py
+++ b/tests/integration/pipelex/libraries/test_concept_to_concept_references.py
@@ -6,7 +6,7 @@ from pathlib import Path
import pytest
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
class TestConceptToConceptReferences:
diff --git a/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py b/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py
index d8c2ce796..b449a4099 100644
--- a/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py
+++ b/tests/integration/pipelex/libraries/test_crate_normalization_round_trip.py
@@ -3,7 +3,7 @@ from collections.abc import Callable
from pathlib import Path
from pipelex.core.interpreter.interpreter import PipelexInterpreter
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.crate_normalization import normalize_crate
from pipelex.libraries.library_crate_factory import LibraryCrateFactory
diff --git a/tests/integration/pipelex/libraries/test_cross_file_concept_references.py b/tests/integration/pipelex/libraries/test_cross_file_concept_references.py
index 616d30a14..3c44223d4 100644
--- a/tests/integration/pipelex/libraries/test_cross_file_concept_references.py
+++ b/tests/integration/pipelex/libraries/test_cross_file_concept_references.py
@@ -12,7 +12,7 @@ from collections.abc import Callable
import pytest
from pipelex.core.interpreter.interpreter import PipelexInterpreter
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.concept.exceptions import ConceptLibraryError
CONCEPT_MTHDS = """
diff --git a/tests/integration/pipelex/libraries/test_hosted_pipe_func_load.py b/tests/integration/pipelex/libraries/test_hosted_pipe_func_load.py
index d42d0ad5f..251ea60fb 100644
--- a/tests/integration/pipelex/libraries/test_hosted_pipe_func_load.py
+++ b/tests/integration/pipelex/libraries/test_hosted_pipe_func_load.py
@@ -5,7 +5,7 @@ from pathlib import Path
import pytest
from pipelex.config import get_config
-from pipelex.hub import get_library_manager, scoped_current_library
+from pipelex.interpreter_hub import get_library_manager, scoped_current_library
from pipelex.libraries.exceptions import LibraryError
from pipelex.system.registries.func_registry import func_registry
diff --git a/tests/integration/pipelex/libraries/test_load_from_crate.py b/tests/integration/pipelex/libraries/test_load_from_crate.py
index e90a238eb..cfe50f751 100644
--- a/tests/integration/pipelex/libraries/test_load_from_crate.py
+++ b/tests/integration/pipelex/libraries/test_load_from_crate.py
@@ -3,7 +3,7 @@ from collections.abc import Callable
from pathlib import Path
from pipelex.core.interpreter.interpreter import PipelexInterpreter
-from pipelex.hub import clear_current_library, get_current_library, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library, get_library_manager, set_current_library
from pipelex.libraries.library_crate_factory import LibraryCrateFactory
SCORING_MTHDS = """\
diff --git a/tests/integration/pipelex/libraries/test_pipe_namespace.py b/tests/integration/pipelex/libraries/test_pipe_namespace.py
index d68efe9ca..97fbe9b75 100644
--- a/tests/integration/pipelex/libraries/test_pipe_namespace.py
+++ b/tests/integration/pipelex/libraries/test_pipe_namespace.py
@@ -6,7 +6,7 @@ from pathlib import Path
import pytest
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.concept.exceptions import ConceptLibraryError
from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundError
diff --git a/tests/integration/pipelex/pipe_signature/conftest.py b/tests/integration/pipelex/pipe_signature/conftest.py
index 4f51b01c7..0e870c1e4 100644
--- a/tests/integration/pipelex/pipe_signature/conftest.py
+++ b/tests/integration/pipelex/pipe_signature/conftest.py
@@ -4,7 +4,7 @@ import pytest
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.concepts.concept_factory import ConceptFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_signature.pipe_signature_blueprint import PipeSignatureBlueprint
SIGNATURES_DOMAIN_CODE = "sigtests"
diff --git a/tests/integration/pipelex/pipe_signature/test_collect_signature_refs.py b/tests/integration/pipelex/pipe_signature/test_collect_signature_refs.py
index b35eb4318..8ff3ee80a 100644
--- a/tests/integration/pipelex/pipe_signature/test_collect_signature_refs.py
+++ b/tests/integration/pipelex/pipe_signature/test_collect_signature_refs.py
@@ -1,7 +1,7 @@
from typing import Callable
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
diff --git a/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py b/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py
index 7cdb9a702..4f3bb5753 100644
--- a/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py
+++ b/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py
@@ -5,7 +5,7 @@ import pytest
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_current_library, get_pipe_library
+from pipelex.interpreter_hub import get_current_library, get_pipe_library
from pipelex.language.mthds_factory import MthdsFactory
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
diff --git a/tests/integration/pipelex/pipe_signature/test_pipe_signature.py b/tests/integration/pipelex/pipe_signature/test_pipe_signature.py
index f5d6e640c..47233d0ed 100644
--- a/tests/integration/pipelex/pipe_signature/test_pipe_signature.py
+++ b/tests/integration/pipelex/pipe_signature/test_pipe_signature.py
@@ -5,15 +5,15 @@ import pytest
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.list_content import ListContent
-from pipelex.hub import get_current_library
+from pipelex.interpreter_hub import get_current_library
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError
from pipelex.pipe_signature.pipe_signature import PipeSignature
from pipelex.pipe_signature.pipe_signature_blueprint import PipeSignatureBlueprint
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.pipeline.pipeline_models import SpecialPipelineId
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.telemetry.otel_constants import OTelConstants
from tests.integration.pipelex.pipe_signature.conftest import SIGNATURES_DOMAIN_CODE
diff --git a/tests/integration/pipelex/pipeline/test_acquire_and_validate.py b/tests/integration/pipelex/pipeline/test_acquire_and_validate.py
index 431870d1f..4a1316226 100644
--- a/tests/integration/pipelex/pipeline/test_acquire_and_validate.py
+++ b/tests/integration/pipelex/pipeline/test_acquire_and_validate.py
@@ -14,7 +14,7 @@ from typing import TYPE_CHECKING, Callable
import pytest
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
diff --git a/tests/integration/pipelex/pipeline/test_bundle_validator.py b/tests/integration/pipelex/pipeline/test_bundle_validator.py
index b7f75dff2..a2d8fe2dd 100644
--- a/tests/integration/pipelex/pipeline/test_bundle_validator.py
+++ b/tests/integration/pipelex/pipeline/test_bundle_validator.py
@@ -17,19 +17,14 @@ from pytest_mock import MockerFixture
from typing_extensions import override
from pipelex.core.pipes.pipe_output import PipeOutput
-from pipelex.hub import (
- clear_current_library,
- get_library_manager,
- get_pipelex_hub,
- get_required_pipe,
- get_telemetry_manager,
-)
+from pipelex.interpreter_hub import clear_current_library, get_interpreter_hub, get_library_manager, get_required_pipe
from pipelex.observer.observer_protocol import ObserverNoOp
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_router import PipeRouter
from pipelex.pipeline import bundle_validator
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
from pipelex.pipeline.execution_seams import acquire_library
+from pipelex.runtime_hub import get_telemetry_manager
from pipelex.system.telemetry.events import EventName
@@ -261,7 +256,7 @@ class TestBundleValidatorIntegration:
# Temporal router (the leak that produced HTTP 422). We install a hub default that raises if its
# run is ever reached, then assert the batch (and its branch leaf) classify SUCCESS without the
# hub default ever being touched.
- hub = get_pipelex_hub()
+ hub = get_interpreter_hub()
original_router = hub.get_required_pipe_router()
sentinel = _RaisingPipeRouter()
library_manager = get_library_manager()
diff --git a/tests/integration/pipelex/pipeline/test_cost_report_rendering.py b/tests/integration/pipelex/pipeline/test_cost_report_rendering.py
index 6f51e06cc..ce9dded3f 100644
--- a/tests/integration/pipelex/pipeline/test_cost_report_rendering.py
+++ b/tests/integration/pipelex/pipeline/test_cost_report_rendering.py
@@ -23,10 +23,10 @@ from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.reporting.cost_report_renderer import render_run_cost_report
from pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend
+from pipelex.system.job_metadata import JobMetadata
_DOMAIN = "cost_report_rendering"
_MTHDS = f"""
diff --git a/tests/integration/pipelex/pipeline/test_execution_seams.py b/tests/integration/pipelex/pipeline/test_execution_seams.py
index caf7c823f..54d9b61e9 100644
--- a/tests/integration/pipelex/pipeline/test_execution_seams.py
+++ b/tests/integration/pipelex/pipeline/test_execution_seams.py
@@ -11,12 +11,7 @@ from mthds.protocol.pipeline_inputs import PipelineInputs
from pytest_mock import MockerFixture
from pipelex.config import get_config
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- get_required_pipe,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline import execution_seams as execution_seams_module
from pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_job
diff --git a/tests/integration/pipelex/pipeline/test_optional_method_inputs.py b/tests/integration/pipelex/pipeline/test_optional_method_inputs.py
index 37385790f..e606695a2 100644
--- a/tests/integration/pipelex/pipeline/test_optional_method_inputs.py
+++ b/tests/integration/pipelex/pipeline/test_optional_method_inputs.py
@@ -21,7 +21,7 @@ from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipeline.execution_seams import prepare_pipe_job
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
diff --git a/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py b/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py
index 8a3924709..f804cadb0 100644
--- a/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py
+++ b/tests/integration/pipelex/pipeline/test_pipe_io_contracts.py
@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING
import pytest
from pydantic import PydanticUserError
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipeline.exceptions import PipeIOContractError
from pipelex.pipeline.pipe_io_contracts import IOMultiplicity, build_pipe_io_contracts
from pipelex.pipeline.validate_bundle import validate_bundle
diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py b/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py
index 330d19077..a19055883 100644
--- a/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py
+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py
@@ -27,12 +27,7 @@ from typing_extensions import override
from pipelex.config import get_config
from pipelex.graph.graph_tracer import GraphTracer
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- get_pipeline_manager,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_pipeline_manager
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py
index 26790714f..81887cf2b 100644
--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py
+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_characterization.py
@@ -52,13 +52,11 @@ from mthds.protocol.pipeline_inputs import PipelineInputs
from pytest_mock import MockerFixture
from pipelex.config import get_config
-from pipelex.hub import (
+from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
get_library_manager,
get_pipeline_manager,
- get_report_delegate,
- get_telemetry_manager,
set_current_library,
)
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
@@ -66,6 +64,7 @@ from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.reporting.reporting_manager import ReportingManager
+from pipelex.runtime_hub import get_report_delegate, get_telemetry_manager
from pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend
from pipelex.system.telemetry.events import EventName
diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py
index 66399653f..34da87a5b 100644
--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py
+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_emit_gates.py
@@ -18,9 +18,10 @@ from pytest_mock import MockerFixture
from pipelex.config import get_config
from pipelex.graph.graph_tracer_manager import GraphTracerManager
-from pipelex.hub import clear_current_library, get_library_manager, get_report_delegate
+from pipelex.interpreter_hub import clear_current_library, get_library_manager
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
+from pipelex.runtime_hub import get_report_delegate
from pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend
_GATE_DOMAIN = "prs_emit_gates"
diff --git a/tests/integration/pipelex/pipeline/test_protocol_validate.py b/tests/integration/pipelex/pipeline/test_protocol_validate.py
index 16ae69258..aa32b7de8 100644
--- a/tests/integration/pipelex/pipeline/test_protocol_validate.py
+++ b/tests/integration/pipelex/pipeline/test_protocol_validate.py
@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING
import pytest
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.libraries.exceptions import LibraryError
from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipeline.bundle_validator import DryRunStatus
diff --git a/tests/integration/pipelex/pipeline/test_public_validation_api.py b/tests/integration/pipelex/pipeline/test_public_validation_api.py
index f7a1cccdf..4aa12e014 100644
--- a/tests/integration/pipelex/pipeline/test_public_validation_api.py
+++ b/tests/integration/pipelex/pipeline/test_public_validation_api.py
@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING
import pytest
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_pipes
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_pipes
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
from pipelex.pipeline.execution_seams import load_libraries_and_activate
diff --git a/tests/integration/pipelex/pipeline/test_resolve_bundle.py b/tests/integration/pipelex/pipeline/test_resolve_bundle.py
index 1b39d9694..c0cb60c47 100644
--- a/tests/integration/pipelex/pipeline/test_resolve_bundle.py
+++ b/tests/integration/pipelex/pipeline/test_resolve_bundle.py
@@ -13,7 +13,7 @@ from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION
from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexUnexpectedError
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.resolve_bundle import resolve_crate_from_contents
diff --git a/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py b/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py
index df2df32a3..6c29ade3e 100644
--- a/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py
+++ b/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py
@@ -22,12 +22,7 @@ import pytest
from typing_extensions import override
from pipelex.config import get_config
-from pipelex.hub import (
- clear_current_library,
- get_current_library_id_or_none,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
diff --git a/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py b/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py
index 46d90acc4..d192402b8 100644
--- a/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py
+++ b/tests/integration/pipelex/pipeline/test_scoped_in_memory_tracing.py
@@ -19,9 +19,9 @@ from pytest_mock import MockerFixture
from pipelex.config import get_config
from pipelex.core.pipes.pipe_output import PipeOutput
-from pipelex.hub import scoped_event_log
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.runtime_hub import scoped_event_log
from pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackend
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py b/tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py
index 2d42d5e24..b3cce95a4 100644
--- a/tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py
@@ -30,7 +30,7 @@ import pytest
from pydantic import BaseModel
from pytest_mock import MockerFixture
-from pipelex.hub import clear_current_library, get_current_library, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_current_library, get_library_manager, set_current_library
from pipelex.pipeline import validate_bundle as validate_bundle_module
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import (
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_loaded_on_success.py b/tests/integration/pipelex/pipeline/test_validate_bundle_loaded_on_success.py
index 348495746..699e062b0 100644
--- a/tests/integration/pipelex/pipeline/test_validate_bundle_loaded_on_success.py
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_loaded_on_success.py
@@ -13,7 +13,7 @@ from __future__ import annotations
import pytest
from pipelex.builder.operations.runner_code_ops import build_runner_code_for_pipe
-from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe
from pipelex.pipeline.validate_bundle import validate_bundle
_LOADED_DOMAIN = "loaded_on_success"
diff --git a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py
index 654b62252..ad95a02b0 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_compaction.py
@@ -17,7 +17,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
@@ -27,7 +27,7 @@ from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
_DOMAIN_CODE = "test_optionals_batch"
diff --git a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_simple.py b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_simple.py
index b631d073a..b65342ca2 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_simple.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_batch/test_pipe_batch_simple.py
@@ -13,12 +13,12 @@ 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.core.stuffs.text_content import TextContent
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/integration/pipelex/pipes/controller/pipe_batch_dotted_path/test_dotted_batch.py b/tests/integration/pipelex/pipes/controller/pipe_batch_dotted_path/test_dotted_batch.py
index 46fba4200..1d9a4e14e 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_batch_dotted_path/test_dotted_batch.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_batch_dotted_path/test_dotted_batch.py
@@ -13,12 +13,12 @@ from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.search_result_content import SearchResultContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_required_pipe
+from pipelex.interpreter_hub import get_required_pipe
from pipelex.pipe_controllers.sub_pipe import SubPipe
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import BatchParams
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_complex.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_complex.py
index 894504013..3d2fbceed 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_complex.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_complex.py
@@ -12,12 +12,12 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.inputs.exceptions import PipeRunInputsError
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition_complex import (
DocumentRequest,
UserProfile,
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py
index e6fbca5b2..bc3b13368 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_delivery.py
@@ -26,7 +26,7 @@ from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
def _make_continue_only_condition() -> PipeCondition:
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py
index 46a426d84..88824fffd 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py
@@ -19,11 +19,11 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition_continue_output_type import (
Constraint,
VerifiedLink,
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_simple.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_simple.py
index 1ee19d743..f6dd8705f 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_simple.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_simple.py
@@ -12,7 +12,7 @@ from pipelex.core.pipes.inputs.exceptions import PipeRunInputsError
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
@@ -20,7 +20,7 @@ from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition import CategoryInput
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_validation.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_validation.py
index 5d4d08cc5..9b5acecd2 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_validation.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_validation.py
@@ -3,7 +3,7 @@ from typing import Callable
from pipelex.core.concepts.concept_factory import ConceptBlueprint, ConceptFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py
index bb60342a3..994180f0c 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_absence.py
@@ -27,7 +27,7 @@ from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry, get_concept_library, get_pipe_library
+from pipelex.interpreter_hub import get_concept_library, get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
@@ -36,7 +36,8 @@ from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
_DOMAIN_CODE = "test_optionals_par"
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_branch_type_validation.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_branch_type_validation.py
index 1a01c0705..e3fda5830 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_branch_type_validation.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_branch_type_validation.py
@@ -10,12 +10,13 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry, get_concept_library, get_pipe_library
+from pipelex.interpreter_hub import get_concept_library, get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
+from pipelex.runtime_hub import get_class_registry
class BtvCombinedResult(StructuredContent):
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_final_stuff_code.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_final_stuff_code.py
index 43f912073..f910527be 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_final_stuff_code.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_final_stuff_code.py
@@ -23,7 +23,7 @@ from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParall
from pipelex.pipe_controllers.sub_pipe_factory import SubPipeBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
_REQUESTED_CODE = "requested-final-stuff-code"
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py
index 7f2a9da2f..b52b2ef4d 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py
@@ -9,7 +9,7 @@ a runtime combine failure.
import pytest
from pipelex.core.pipes.exceptions import PipeValidationError
-from pipelex.hub import clear_current_library, get_library_manager
+from pipelex.interpreter_hub import clear_current_library, get_library_manager
from pipelex.pipeline.execution_seams import acquire_library
_BUNDLE_HEADER = """
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_simple.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_simple.py
index b874939d8..f9821ddcd 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_simple.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_simple.py
@@ -16,7 +16,7 @@ from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParall
from pipelex.pipe_controllers.sub_pipe_factory import SubPipeBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_unresolvable_structure_class.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_unresolvable_structure_class.py
index 80b6cf4ed..68eafc3b8 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_unresolvable_structure_class.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_unresolvable_structure_class.py
@@ -8,12 +8,13 @@ from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry, get_concept_library, get_pipe_library
+from pipelex.interpreter_hub import get_concept_library, get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
+from pipelex.runtime_hub import get_class_registry
DOMAIN_CODE = "test_usc"
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_validation.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_validation.py
index d4d0fdf9a..12c4aee5b 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_validation.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_validation.py
@@ -4,7 +4,7 @@ from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library, get_pipe_library
+from pipelex.interpreter_hub import get_concept_library, get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sub_pipe_factory import SubPipeBlueprint
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_creation.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_creation.py
index 15f0d4711..11300d4ee 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_creation.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_creation.py
@@ -3,7 +3,7 @@ from typing import Callable
from pipelex.core.concepts.concept_factory import ConceptBlueprint, ConceptFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_factory import SubPipeBlueprint
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py
index 8470b9aed..b51ab0089 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_dry_run.py
@@ -9,11 +9,11 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.json_utils import load_json_list_from_path
from tests.integration.pipelex.pipes.controller.pipe_sequence.discord_newsletter import ChannelSummary, DiscordChannelUpdate
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py
index 2182fdc08..efb863e32 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py
@@ -13,7 +13,7 @@ from typing import ClassVar
import pytest
-from pipelex.hub import get_current_library, get_required_pipe
+from pipelex.interpreter_hub import get_current_library, get_required_pipe
from pipelex.pipeline.bundle_validator import BundleValidator
from pipelex.pipeline.validate_bundle import validate_bundle
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_multiple_steps.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_multiple_steps.py
index d34e5292a..2bbb471f5 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_multiple_steps.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_multiple_steps.py
@@ -3,7 +3,7 @@ from typing import Callable
from pipelex.core.concepts.concept_factory import ConceptBlueprint, ConceptFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_factory import SubPipeBlueprint
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py
index cd5814ac0..62706210d 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_output_multiplicity.py
@@ -6,7 +6,7 @@ import pytest
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_simple.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_simple.py
index 1d8ed299a..f609953c3 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_simple.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_simple.py
@@ -11,13 +11,13 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_concept_library, get_native_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_inputs_inference.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_inputs_inference.py
index d9761685c..0d4fc65dd 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_inputs_inference.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_inputs_inference.py
@@ -14,11 +14,11 @@ from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.cases import ImageTestCases
from tests.integration.pipelex.pipes.pipelines.test_structures import Article
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py
index 5672c07b5..e8b28af29 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py
@@ -12,7 +12,7 @@ from pipelex.core.stuffs.document_content import DocumentContent
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.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.urls import URLs
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py
index 284d18cb3..9a73fdded 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py
@@ -11,7 +11,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.urls import URLs
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py
index eae760bfc..dbafad84d 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py
@@ -16,7 +16,7 @@ from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_operators.shared.exceptions import WithImagesFilterError
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py
index c17ce88a3..dceb09055 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py
@@ -11,7 +11,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
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.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from tests.cases import ImageTestCases
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 2550d6d8c..0697dfc31 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,7 +14,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
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.hub import get_required_concept
+from pipelex.interpreter_hub import get_required_concept
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
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 1a0ed450f..3ee9bc8be 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,7 +12,7 @@ from pipelex.core.stuffs.document_content import DocumentContent
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.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
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
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_class_compatibility.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_class_compatibility.py
index 5b656f50b..fa22fc98d 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_class_compatibility.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_class_compatibility.py
@@ -18,13 +18,13 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_compose_structured.models_for_pipe_compose import (
DiscountedProduct,
Employee,
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_content_conversions.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_content_conversions.py
index 9c12c1f9d..5214e135a 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_content_conversions.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_content_conversions.py
@@ -20,13 +20,13 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_compose_structured.models_for_pipe_compose import (
MarkdownText,
TeamMember,
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
index 8f9dbe61e..5d108cd6e 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
@@ -26,14 +26,14 @@ from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.exceptions import PipeComposeError
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_compose_structured.test_data import NativeScalarConversionTestData
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured.py
index 7237e05aa..8882a8137 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured.py
@@ -16,13 +16,13 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_compose_structured.models_for_pipe_compose import (
Address,
Deal,
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py
index 2265c162d..cef9ac445 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py
@@ -18,14 +18,14 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.exceptions import PipeComposeError
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_compose_structured.models_for_pipe_compose import (
Employee,
Location,
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_stuff_content_subclasses.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_stuff_content_subclasses.py
index b8e941b79..df5f8ab39 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_stuff_content_subclasses.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_stuff_content_subclasses.py
@@ -28,13 +28,13 @@ from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.mermaid_content import MermaidContent
from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.urls import URLs
from tests.integration.pipelex.pipes.operator.pipe_compose_structured.test_data import StuffContentSubclassTestData
diff --git a/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract.py b/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract.py
index 91431ab46..4976c3232 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract.py
@@ -12,13 +12,13 @@ from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.page_content import PageContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_concept_library, get_pipe_router
+from pipelex.interpreter_hub import get_concept_library, get_pipe_router
from pipelex.pipe_operators.extract.pipe_extract import PipeExtract
from pipelex.pipe_operators.extract.pipe_extract_blueprint import PipeExtractBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.test_data import PipeExtractTestCases
diff --git a/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py
index 00a4ca75a..4fe7def52 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py
@@ -11,14 +11,14 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_library, get_pipe_router
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.extract.pipe_extract import PipeExtract
from pipelex.pipe_operators.extract.pipe_extract_blueprint import PipeExtractBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_func/test_pipe_func.py b/tests/integration/pipelex/pipes/operator/pipe_func/test_pipe_func.py
index 57be3214a..d7b665f93 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_func/test_pipe_func.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_func/test_pipe_func.py
@@ -9,13 +9,13 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_router
+from pipelex.interpreter_hub import get_pipe_router
from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
from tests.cases.source_code import wrap_lines
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py
index fdd47a56a..04c66e640 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py
@@ -26,10 +26,10 @@ from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_console, get_model_deck
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.pipelex import Pipelex
+from pipelex.runtime_hub import get_console, get_model_deck
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py
index cf4413391..5bd42842c 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py
@@ -27,10 +27,10 @@ from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_console, get_model_deck
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.pipelex import Pipelex
+from pipelex.runtime_hub import get_console, get_model_deck
from pipelex.system.configuration.config_loader import config_manager
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py
index d453b59cb..219da9d45 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py
@@ -7,14 +7,14 @@ from pipelex.cogt.exceptions import ImgGenGenerationError, ImgGenModelNotFoundEr
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_library, get_pipe_router
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
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_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py
index 2b5803c79..ea9d3e928 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py
@@ -6,13 +6,13 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_router
+from pipelex.interpreter_hub import get_pipe_router
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_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
from tests.integration.pipelex.test_data import ImageGenTestCases
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py
index 7465f80a6..ba9a0e578 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py
@@ -10,13 +10,14 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry, get_native_concept, get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_library, get_pipe_router
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint, StructuringMethod
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_class_registry
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.test_data import BasicStructuredDataTestCases, PipeTestCases
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py
index a2c4d7e0b..8a1e60791 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py
@@ -16,13 +16,14 @@ from pytest_mock import MockerFixture
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.date_content import DateContent
-from pipelex.hub import get_content_generator, get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_library, get_pipe_router
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_content_generator
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
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 f0b5c840b..c3bd0589c 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
@@ -8,14 +8,14 @@ from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError,
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_library, get_pipe_router
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py
index b5dfca262..9c25cd6dd 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py
@@ -16,13 +16,14 @@ from pytest_mock import MockerFixture
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.yes_no_content import YesNoContent
-from pipelex.hub import get_content_generator, get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_library, get_pipe_router
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_content_generator
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py
index b303d53d8..4f36fe724 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py
@@ -7,14 +7,14 @@ from pipelex.cogt.exceptions import InferenceErrorCategory, SearchJobFailureErro
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_library, get_pipe_router
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.search.pipe_search import PipeSearch
from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure.py b/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure.py
index 94a65e205..5e27ecee6 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure.py
@@ -9,13 +9,13 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_library, get_pipe_router
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStructureBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_batch.py b/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_batch.py
index 9b3e9a2a1..ad4c2f1bc 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_batch.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_batch.py
@@ -11,7 +11,7 @@ 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.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_library, get_pipe_router
from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
@@ -19,7 +19,7 @@ from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStruct
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_structure.test_structures_basic import RestaurantReview
diff --git a/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_sequence.py b/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_sequence.py
index 272361e36..c5496d103 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_sequence.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_sequence.py
@@ -9,7 +9,7 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_library, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_library, get_pipe_router
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
@@ -18,7 +18,7 @@ from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStruct
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_structure.test_structures_basic import RestaurantReview
diff --git a/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py b/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py
index 39c1cb954..d289cb6b4 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py
@@ -10,13 +10,14 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router, get_report_delegate, get_required_pipe
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router, get_required_pipe
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_report_delegate
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.pipes.operator.pipe_structure.test_structures_basic import RestaurantReview
diff --git a/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py b/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py
index 57f7ce754..39dea89b1 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py
@@ -11,13 +11,14 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router, get_report_delegate, get_required_pipe
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router, get_required_pipe
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_report_delegate
+from pipelex.system.job_metadata import JobMetadata
def _count_llm_report_calls(report_spy: MockType) -> int:
diff --git a/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py b/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py
index a48fa2779..f555c0044 100644
--- a/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py
+++ b/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py
@@ -17,7 +17,7 @@ from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErr
from pipelex.core.pipes.handle_pipe_errors import extract_wrapped_pipe_validation_error
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
from pipelex.pipe_operators.func.pipe_func import PipeFunc
diff --git a/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py b/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py
index 8f98223ca..31af9793e 100644
--- a/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py
+++ b/tests/integration/pipelex/pipes/optionals/test_lift_sequence.py
@@ -16,7 +16,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
@@ -25,7 +25,7 @@ from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipeline.execution_seams import prepare_pipe_job
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
_DOMAIN_CODE = "test_optionals_seq"
diff --git a/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py b/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py
index 6c66132b3..19fb6ae4f 100644
--- a/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py
+++ b/tests/integration/pipelex/pipes/optionals/test_lift_skip_trichotomy.py
@@ -26,7 +26,7 @@ from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
from tests.unit.pipelex.graph.conftest import make_trace_context
diff --git a/tests/integration/pipelex/pipes/optionals/test_liftable_pipes_inventory.py b/tests/integration/pipelex/pipes/optionals/test_liftable_pipes_inventory.py
index 2affcd638..01de69620 100644
--- a/tests/integration/pipelex/pipes/optionals/test_liftable_pipes_inventory.py
+++ b/tests/integration/pipelex/pipes/optionals/test_liftable_pipes_inventory.py
@@ -8,7 +8,7 @@ from typing import Callable
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
diff --git a/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py b/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py
index 4e58ad0e3..271401569 100644
--- a/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py
+++ b/tests/integration/pipelex/pipes/optionals/test_lifted_parallel_companion_slots.py
@@ -16,7 +16,7 @@ from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
@@ -26,7 +26,7 @@ from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.system.registries.func_registry import func_registry
_DOMAIN_CODE = "test_optionals_companion"
diff --git a/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py b/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py
index 067adf27b..70d35475b 100644
--- a/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py
+++ b/tests/integration/pipelex/pipes/optionals/test_optional_gate_tolerates_missing.py
@@ -13,7 +13,7 @@ from pipelex.config import get_config
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
@@ -23,7 +23,7 @@ from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
_DOMAIN_CODE = "test_optionals_gate"
diff --git a/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py b/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py
index 0f9637df0..71b8cd362 100644
--- a/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py
+++ b/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py
@@ -15,12 +15,13 @@ from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErr
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_class_registry, get_concept_library, get_pipe_library
+from pipelex.interpreter_hub import get_concept_library, get_pipe_library
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
from pipelex.pipe_controllers.parallel.pipe_parallel_blueprint import PipeParallelBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.registries.func_registry import func_registry
_DOMAIN_CODE = "test_optionals_par_static"
diff --git a/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py b/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py
index ddc662d34..95a63f3f0 100644
--- a/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py
+++ b/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py
@@ -11,7 +11,7 @@ from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
diff --git a/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py b/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py
index ea03088ba..12fb252d3 100644
--- a/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py
+++ b/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py
@@ -12,7 +12,7 @@ from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_pipe_library
+from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallel
diff --git a/tests/integration/pipelex/pipes/test_bracket_notation_controllers.py b/tests/integration/pipelex/pipes/test_bracket_notation_controllers.py
index a4c18d1f3..8f3866834 100644
--- a/tests/integration/pipelex/pipes/test_bracket_notation_controllers.py
+++ b/tests/integration/pipelex/pipes/test_bracket_notation_controllers.py
@@ -3,7 +3,7 @@ from typing import Callable
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
diff --git a/tests/integration/pipelex/pipes/test_image_out_in.py b/tests/integration/pipelex/pipes/test_image_out_in.py
index 756cf77e7..875c56e3d 100644
--- a/tests/integration/pipelex/pipes/test_image_out_in.py
+++ b/tests/integration/pipelex/pipes/test_image_out_in.py
@@ -3,11 +3,11 @@ from typing import Callable
import pytest
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/integration/pipelex/pipes/test_pipe_compose.py b/tests/integration/pipelex/pipes/test_pipe_compose.py
index eca76bb6c..2f18ea91e 100644
--- a/tests/integration/pipelex/pipes/test_pipe_compose.py
+++ b/tests/integration/pipelex/pipes/test_pipe_compose.py
@@ -4,21 +4,21 @@ import pytest
from pipelex import pretty_print
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose, PipeComposeOutput
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
from tests.cases import JINJA2TestCases
diff --git a/tests/integration/pipelex/pipes/test_pipe_running_variants.py b/tests/integration/pipelex/pipes/test_pipe_running_variants.py
index 511fe0870..64475d3bb 100644
--- a/tests/integration/pipelex/pipes/test_pipe_running_variants.py
+++ b/tests/integration/pipelex/pipes/test_pipe_running_variants.py
@@ -7,12 +7,12 @@ from pipelex import log, pretty_print
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
from pipelex.core.stuffs.stuff import Stuff
-from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.interpreter_hub import get_pipe_router, get_required_pipe
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.pipeline.exceptions import PipeStackOverflowError
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.integration.pipelex.test_data import PipeTestCases
diff --git a/tests/integration/pipelex/plugins/conftest.py b/tests/integration/pipelex/plugins/conftest.py
index 9f8a8a13a..65f9f8d48 100644
--- a/tests/integration/pipelex/plugins/conftest.py
+++ b/tests/integration/pipelex/plugins/conftest.py
@@ -1,7 +1,7 @@
import pytest
from pipelex.cogt.exceptions import ModelManagerError
-from pipelex.hub import get_models_manager
+from pipelex.runtime_hub import get_models_manager
def is_backend_available(backend_name: str) -> bool:
diff --git a/tests/integration/pipelex/plugins/test_anthropic.py b/tests/integration/pipelex/plugins/test_anthropic.py
index bffac6a6f..2001ec531 100644
--- a/tests/integration/pipelex/plugins/test_anthropic.py
+++ b/tests/integration/pipelex/plugins/test_anthropic.py
@@ -3,10 +3,10 @@ from anthropic import AuthenticationError
from rich import box
from rich.table import Table
-from pipelex.hub import get_console, get_models_manager
from pipelex.plugins.anthropic.anthropic_exceptions import AnthropicSDKUnsupportedError
from pipelex.plugins.anthropic.anthropic_llms import anthropic_list_available_models
from pipelex.plugins.model_handle import ModelHandle
+from pipelex.runtime_hub import get_console, get_models_manager
from pipelex.system.environment import all_env_vars_are_set, any_env_var_is_placeholder
from tests.integration.pipelex.plugins.conftest import is_backend_available
diff --git a/tests/integration/pipelex/plugins/test_bedrock.py b/tests/integration/pipelex/plugins/test_bedrock.py
index 20de72917..cfd542638 100644
--- a/tests/integration/pipelex/plugins/test_bedrock.py
+++ b/tests/integration/pipelex/plugins/test_bedrock.py
@@ -6,7 +6,7 @@ import pytest
from rich import box
from rich.table import Table
-from pipelex.hub import get_console
+from pipelex.runtime_hub import get_console
from pipelex.system.environment import all_env_vars_are_set, any_env_var_is_placeholder
warnings.filterwarnings(
diff --git a/tests/integration/pipelex/plugins/test_external_plugin.py b/tests/integration/pipelex/plugins/test_external_plugin.py
index cf7e28cf0..0fb5daaba 100644
--- a/tests/integration/pipelex/plugins/test_external_plugin.py
+++ b/tests/integration/pipelex/plugins/test_external_plugin.py
@@ -14,8 +14,8 @@ from pipelex.cogt.llm.thinking_mode import ThinkingMode
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.hub import get_report_delegate
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.runtime_hub import get_report_delegate
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
from tests.integration.pipelex.cogt.test_data import LLMTestConstants, Person
diff --git a/tests/integration/pipelex/plugins/test_mistral.py b/tests/integration/pipelex/plugins/test_mistral.py
index 24b793224..426899cde 100644
--- a/tests/integration/pipelex/plugins/test_mistral.py
+++ b/tests/integration/pipelex/plugins/test_mistral.py
@@ -3,8 +3,8 @@ from rich import box
from rich.table import Table
from pipelex import pretty_print
-from pipelex.hub import get_console
from pipelex.plugins.mistral.mistral_llms import mistral_list_available_models
+from pipelex.runtime_hub import get_console
from pipelex.system.environment import all_env_vars_are_set, any_env_var_is_placeholder
from tests.integration.pipelex.plugins.conftest import is_backend_available
diff --git a/tests/integration/pipelex/plugins/test_openai.py b/tests/integration/pipelex/plugins/test_openai.py
index 047901a58..92b8b9520 100644
--- a/tests/integration/pipelex/plugins/test_openai.py
+++ b/tests/integration/pipelex/plugins/test_openai.py
@@ -1,9 +1,9 @@
import pytest
from pipelex import pretty_print
-from pipelex.hub import get_models_manager
from pipelex.plugins.model_handle import ModelHandle
from pipelex.plugins.openai.openai_llms import openai_list_available_models
+from pipelex.runtime_hub import get_models_manager
from pipelex.system.environment import all_env_vars_are_set, any_env_var_is_placeholder
from tests.integration.pipelex.plugins.conftest import is_backend_available
diff --git a/tests/integration/pipelex/plugins/test_secrets_external_plugin.py b/tests/integration/pipelex/plugins/test_secrets_external_plugin.py
index aca8949a2..51880c58b 100644
--- a/tests/integration/pipelex/plugins/test_secrets_external_plugin.py
+++ b/tests/integration/pipelex/plugins/test_secrets_external_plugin.py
@@ -17,9 +17,9 @@ from typing import TYPE_CHECKING
import pytest
from typing_extensions import override
-from pipelex.hub import get_secrets_provider, get_secrets_provider_registry, get_storage_provider
from pipelex.pipelex import Pipelex
from pipelex.plugins.contract import PLUGIN_API_VERSION
+from pipelex.runtime_hub import get_secrets_provider, get_secrets_provider_registry, get_storage_provider
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
diff --git a/tests/integration/pipelex/plugins/test_storage_external_plugin.py b/tests/integration/pipelex/plugins/test_storage_external_plugin.py
index 94fd2c36b..d942532ef 100644
--- a/tests/integration/pipelex/plugins/test_storage_external_plugin.py
+++ b/tests/integration/pipelex/plugins/test_storage_external_plugin.py
@@ -14,9 +14,9 @@ from typing import TYPE_CHECKING
import pytest
from typing_extensions import override
-from pipelex.hub import get_storage_provider, get_storage_provider_registry
from pipelex.pipelex import Pipelex
from pipelex.plugins.contract import PLUGIN_API_VERSION
+from pipelex.runtime_hub import get_storage_provider, get_storage_provider_registry
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredData
diff --git a/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py b/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py
index de4c8d6c9..1a3aae907 100644
--- a/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py
+++ b/tests/integration/pipelex/system/test_hub_slot_injection_precedence.py
@@ -14,11 +14,12 @@ from typing import TYPE_CHECKING, cast
import pytest
from pytest_mock import MockerFixture
-from pipelex.hub import get_content_generator, get_pipe_router
+from pipelex.interpreter_hub import get_pipe_router
from pipelex.pipelex import Pipelex
from pipelex.plugins.contract import PLUGIN_API_VERSION
from pipelex.plugins.pipe_func.pipe_func_plugin import PipeFuncPlugin
from pipelex.plugins.registrar import HubSlot, PluginOrigin, PluginRegistrar
+from pipelex.runtime_hub import get_content_generator
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
from pipelex.tools.storage.in_memory_storage_provider import InMemoryStorageProvider
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 977b7ccf4..85506455a 100644
--- a/tests/integration/pipelex/system/test_keyless_boot_forced_dry.py
+++ b/tests/integration/pipelex/system/test_keyless_boot_forced_dry.py
@@ -16,12 +16,12 @@ 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.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_content_generator, is_dry_run_forced
from pipelex.pipe_operators.search.pipe_search import PipeSearch
from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipelex import Pipelex
from pipelex.pipeline.execution_seams import load_libraries_and_activate, prepare_pipe_job
+from pipelex.runtime_hub import get_content_generator, is_dry_run_forced
from pipelex.system.runtime import IntegrationMode, runtime_manager
diff --git a/tests/integration/pipelex/test_inline_structure_concepts.py b/tests/integration/pipelex/test_inline_structure_concepts.py
index e2e6ec428..34926fb77 100644
--- a/tests/integration/pipelex/test_inline_structure_concepts.py
+++ b/tests/integration/pipelex/test_inline_structure_concepts.py
@@ -10,7 +10,7 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprintFieldType
from pipelex.core.concepts.exceptions import ConceptFactoryError
from pipelex.core.stuffs.structured_content import StructuredContent
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
class TestInlineStructureConcepts:
diff --git a/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py b/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py
index 7af7e302a..a3973ff5a 100644
--- a/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py
+++ b/tests/integration/pipelex/tools/class_registry/test_class_registry_utils.py
@@ -3,7 +3,7 @@ from pathlib import Path
import pytest
from pipelex.core.stuffs.stuff_content import StuffContent
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
from tests.cases import ClassRegistryTestCases
diff --git a/tests/integration/pipelex/tools/jinja2/test_jinja2_list_iteration.py b/tests/integration/pipelex/tools/jinja2/test_jinja2_list_iteration.py
index 1e06f3497..b7ad72ce5 100644
--- a/tests/integration/pipelex/tools/jinja2/test_jinja2_list_iteration.py
+++ b/tests/integration/pipelex/tools/jinja2/test_jinja2_list_iteration.py
@@ -4,15 +4,15 @@ from __future__ import annotations
from typing import TYPE_CHECKING
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.text_content import TextContent
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_sync
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
if TYPE_CHECKING:
from pipelex.core.stuffs.stuff_artefact import StuffArtefact
diff --git a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_data.py b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_data.py
index 9270ca809..a70776365 100644
--- a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_data.py
+++ b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_data.py
@@ -2,10 +2,10 @@ from typing import ClassVar
from pipelex.builder.pipe.pipe_compose_spec import PipeComposeSpec
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
class PipeComposeTestCases:
diff --git a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py
index 59fe59758..9e6e842fe 100644
--- a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py
+++ b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_pipe_llm.py
@@ -6,7 +6,7 @@ from pipelex import pretty_print
from pipelex.builder.pipe.pipe_llm_spec import PipeLLMSpec
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from tests.unit.pipelex.builder.pipe.pipe_operator.pipe_llm.test_data import PipeLLMTestCases
diff --git a/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py b/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py
index e8092a242..f61885446 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py
@@ -7,7 +7,7 @@ import inspect
from pipelex.cli.agent_cli.commands.inputs.bundle_cmd import inputs_bundle_cmd
from pipelex.cli.agent_cli.commands.inputs.method_cmd import inputs_method_cmd
from pipelex.cli.agent_cli.commands.inputs.pipe_cmd import inputs_pipe_cmd
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
class TestInputsFormatUnaffected:
diff --git a/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py b/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py
index 5151a2834..65ab5d2f6 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py
@@ -10,7 +10,7 @@ import tomli
from pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_result # noqa: PLC2701
from pipelex.cli.agent_cli.commands.inputs.pipe_cmd import inputs_pipe_cmd
from pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
if TYPE_CHECKING:
import pytest
diff --git a/tests/unit/pipelex/cli/commands/build/test_inputs_core_toml.py b/tests/unit/pipelex/cli/commands/build/test_inputs_core_toml.py
index 150cb0eff..1b61f2611 100644
--- a/tests/unit/pipelex/cli/commands/build/test_inputs_core_toml.py
+++ b/tests/unit/pipelex/cli/commands/build/test_inputs_core_toml.py
@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any
import pytest
from pipelex.cli.commands.build.inputs._inputs_core import _generate_inputs_core # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
if TYPE_CHECKING:
from pathlib import Path
diff --git a/tests/unit/pipelex/cli/commands/run/test_inputs_template_roundtrip.py b/tests/unit/pipelex/cli/commands/run/test_inputs_template_roundtrip.py
index f250df057..6475f6281 100644
--- a/tests/unit/pipelex/cli/commands/run/test_inputs_template_roundtrip.py
+++ b/tests/unit/pipelex/cli/commands/run/test_inputs_template_roundtrip.py
@@ -13,7 +13,7 @@ import json
from typing import TYPE_CHECKING
from pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_path # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
-from pipelex.core.pipes.inputs.input_renderer import serialize_inputs_template_to_toml
+from pipelex.core.pipes.rendering.input_renderer import serialize_inputs_template_to_toml
if TYPE_CHECKING:
from pathlib import Path
diff --git a/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py b/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py
new file mode 100644
index 000000000..aaa995e37
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py
@@ -0,0 +1,129 @@
+"""Unit tests for the command-layer control flow of `check_hub_layering_cmd`.
+
+The AST core is exercised from inline snippets in `test_hub_layering_guard.py`; these pin the layer
+that turns its findings into a gate. Four things matter and none of them are covered by a snippet
+test: the command *exits 1* on any violation (that exit code is what `make check` and CI read),
+`quiet` trims only the happy path so a CI failure stays actionable without a re-run, each violation
+kind is headed by its own remedy, and a missing scan root fails loudly instead of scanning nothing
+and reporting a pass. The filesystem scan is mocked so each branch is driven deterministically
+without touching the real `pipelex/` tree.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING
+
+import pytest
+from rich.console import Console
+
+from pipelex.cli.dev_cli.commands import check_hub_layering_cmd as cmd_mod
+from pipelex.cli.dev_cli.commands.check_hub_layering_cmd import check_hub_layering_cmd
+from pipelex.cli.dev_cli.commands.hub_layering_guard import (
+ RUNTIME_LAYER_PACKAGES,
+ HubLayeringViolation,
+ HubLayeringViolationKind,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+#: Wide enough that no assertion below depends on where rich decides to wrap.
+CONSOLE_WIDTH = 400
+
+
+def _violation(*, kind: HubLayeringViolationKind, lineno: int = 7) -> HubLayeringViolation:
+ return HubLayeringViolation(
+ relative_path="pipelex/cogt/sample/worker.py",
+ lineno=lineno,
+ kind=kind,
+ detail="imports `pipelex.interpreter_hub`",
+ )
+
+
+class TestCheckHubLayeringCmd:
+ @pytest.fixture
+ def console_buffer(self, mocker: MockerFixture) -> io.StringIO:
+ """Route every `get_console()` call in the command module to one StringIO-backed console."""
+ buffer = io.StringIO()
+ mocker.patch.object(cmd_mod, "get_console", return_value=Console(file=buffer, force_terminal=False, width=CONSOLE_WIDTH))
+ return buffer
+
+ def test_quiet_success_is_one_line(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """The Make targets and CI invoke the guard quietly: a clean tree must cost one line."""
+ mocker.patch.object(cmd_mod, "collect_all_violations", return_value=[])
+ check_hub_layering_cmd(quiet=True) # returns normally (exit 0)
+ output = console_buffer.getvalue()
+ assert "Hub-layering check: PASSED" in output
+ assert "Runtime layer:" not in output
+
+ def test_verbose_success_names_every_declared_runtime_package(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """The success panel is where a reader learns what the declaration covers, so it must be complete."""
+ mocker.patch.object(cmd_mod, "collect_all_violations", return_value=[])
+ check_hub_layering_cmd(quiet=False)
+ output = console_buffer.getvalue()
+ assert "Hub-layering Check: PASSED" in output
+ for package in RUNTIME_LAYER_PACKAGES:
+ assert package in output, package
+
+ def test_violations_exit_1_and_locate_every_site(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """The gate: any violation is a non-zero exit, with every offending line located."""
+ violations = [
+ _violation(kind=HubLayeringViolationKind.INTERPRETER_HUB_IMPORT, lineno=7),
+ _violation(kind=HubLayeringViolationKind.DEAD_HUB_REFERENCE, lineno=42),
+ ]
+ mocker.patch.object(cmd_mod, "collect_all_violations", return_value=violations)
+
+ with pytest.raises(SystemExit) as exit_info:
+ check_hub_layering_cmd(quiet=False)
+
+ assert exit_info.value.code == 1
+ output = console_buffer.getvalue()
+ assert "Hub-layering Check: FAILED" in output
+ assert "pipelex/cogt/sample/worker.py:7" in output
+ assert "pipelex/cogt/sample/worker.py:42" in output
+
+ def test_quiet_failure_stays_actionable(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """Quiet trims success only — a CI failure must carry its sites and remedy, or it needs a re-run."""
+ mocker.patch.object(cmd_mod, "collect_all_violations", return_value=[_violation(kind=HubLayeringViolationKind.INTERPRETER_HUB_IMPORT)])
+
+ with pytest.raises(SystemExit) as exit_info:
+ check_hub_layering_cmd(quiet=True)
+
+ assert exit_info.value.code == 1
+ output = console_buffer.getvalue()
+ assert "Hub-layering check: FAILED" in output
+ assert "1 violation(s)" in output
+ assert "pipelex/cogt/sample/worker.py:7" in output
+ assert "take the value as an argument" in output # the kind's remedy travels with the failure
+
+ def test_violations_are_grouped_by_kind_each_under_its_remedy(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """Kinds name different remedies, so a mixed run must not present them as one undifferentiated list."""
+ violations = [
+ _violation(kind=HubLayeringViolationKind.INTERPRETER_HUB_IMPORT, lineno=7),
+ _violation(kind=HubLayeringViolationKind.INTERPRETER_HUB_IMPORT, lineno=9),
+ _violation(kind=HubLayeringViolationKind.DEAD_HUB_REFERENCE, lineno=42),
+ ]
+ mocker.patch.object(cmd_mod, "collect_all_violations", return_value=violations)
+
+ with pytest.raises(SystemExit):
+ check_hub_layering_cmd(quiet=True)
+
+ output = console_buffer.getvalue()
+ assert f"{HubLayeringViolationKind.INTERPRETER_HUB_IMPORT} (2)" in output
+ assert f"{HubLayeringViolationKind.DEAD_HUB_REFERENCE} (1)" in output
+ assert HubLayeringViolationKind.DEAD_HUB_REFERENCE.remedy in output
+
+ def test_missing_scan_root_fails_without_scanning(self, mocker: MockerFixture, console_buffer: io.StringIO, tmp_path: Path) -> None:
+ """A vanished scan root must never read as a pass: scanning nothing finds nothing."""
+ mocker.patch.object(cmd_mod, "SCAN_ROOTS", (tmp_path / "ghost_root",))
+ scanner = mocker.patch.object(cmd_mod, "collect_all_violations", return_value=[])
+
+ with pytest.raises(SystemExit) as exit_info:
+ check_hub_layering_cmd(quiet=True)
+
+ assert exit_info.value.code == 1
+ assert "ghost_root" in console_buffer.getvalue()
+ scanner.assert_not_called()
diff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py
new file mode 100644
index 000000000..d7a4ec7ff
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py
@@ -0,0 +1,248 @@
+"""Unit tests for the `pipelex-dev check-hub-layering` AST guard."""
+
+from __future__ import annotations
+
+import textwrap
+
+from pipelex.cli.dev_cli.commands.hub_layering_guard import (
+ HubLayeringViolation,
+ HubLayeringViolationKind,
+ find_violations_in_source,
+ is_runtime_layer,
+)
+
+#: A runtime-layer module path, and a interpreter-layer one, for the same snippet.
+RUNTIME_PATH = "pipelex/cogt/sample/worker.py"
+INTERPRETER_PATH = "pipelex/pipeline/sample/runner.py"
+TEST_PATH = "tests/helpers/sample_helpers.py"
+
+#: The deleted single hub. This line *declares* the dead path as test data rather than referencing it,
+#: so it carries the guard's own escape hatch — without it, the guard flags its own test suite.
+DEAD_HUB = "pipelex.hub" # hub-layering: ignore
+
+
+def _violate(source: str, *, relative_path: str = RUNTIME_PATH) -> list[HubLayeringViolation]:
+ """Run the guard over an inline snippet and return its violations."""
+ return find_violations_in_source(source=textwrap.dedent(source), relative_path=relative_path)
+
+
+def _kinds(violations: list[HubLayeringViolation]) -> set[HubLayeringViolationKind]:
+ return {violation.kind for violation in violations}
+
+
+class TestHubLayeringGuard:
+ def test_runtime_layer_membership(self) -> None:
+ """The declared runtime layer is matched on package boundaries, and `pipeline` is outside it."""
+ assert is_runtime_layer(module_qname="pipelex.cogt.llm.llm_worker_abstract")
+ assert is_runtime_layer(module_qname="pipelex.tools")
+ assert not is_runtime_layer(module_qname="pipelex.pipeline.runner")
+ # A package whose name merely starts with a runtime-layer name is not in the runtime layer.
+ assert not is_runtime_layer(module_qname="pipelex.toolsmith.thing")
+
+ def test_core_is_split_between_the_layers(self) -> None:
+ """`core/` is declared package by package: its data model is runtime, its Pipe machinery is not."""
+ assert is_runtime_layer(module_qname="pipelex.core.stuffs.stuff_factory")
+ assert is_runtime_layer(module_qname="pipelex.core.concepts.concept_provider_abstract")
+ assert is_runtime_layer(module_qname="pipelex.core.memory.input_shaper")
+ assert is_runtime_layer(module_qname="pipelex.core.pipes.inputs.input_stuff_specs_factory")
+ assert is_runtime_layer(module_qname="pipelex.core.pipes.stuff_spec.stuff_spec_factory")
+ # Everything that names a `Pipe` imports the interpreter directly and stays in the interpreter layer.
+ assert not is_runtime_layer(module_qname="pipelex.core.pipes.pipe_factory")
+ assert not is_runtime_layer(module_qname="pipelex.core.pipes.rendering.output_renderer")
+ assert not is_runtime_layer(module_qname="pipelex.core.registry_models")
+ assert not is_runtime_layer(module_qname="pipelex.core.bundles.pipelex_bundle_blueprint")
+ assert not is_runtime_layer(module_qname="pipelex.core.interpreter.bundle_elaborator")
+ # `pipelex.core` itself is not a declared package — the split is deliberate, not an omission.
+ assert not is_runtime_layer(module_qname="pipelex.core.qualified_ref")
+
+ 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(
+ """
+ from pipelex.runtime_hub import get_console, get_model_deck
+ """
+ )
+ assert violations == []
+
+ def test_runtime_layer_importing_interpreter_hub_is_a_violation(self) -> None:
+ """`from pipelex.interpreter_hub import …` in the runtime layer is the forbidden arrow."""
+ violations = _violate(
+ """
+ from pipelex.interpreter_hub import get_pipe_router
+ """
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+ assert violations[0].relative_path == RUNTIME_PATH
+ assert violations[0].lineno == 2
+
+ def test_plain_import_and_from_package_forms_are_caught(self) -> None:
+ """`import pipelex.interpreter_hub` and `from pipelex import interpreter_hub` both resolve to the interpreter hub."""
+ assert _kinds(_violate("import pipelex.interpreter_hub\n")) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+ assert _kinds(_violate("import pipelex.interpreter_hub as hub\n")) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+ assert _kinds(_violate("from pipelex import interpreter_hub\n")) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+
+ def test_relative_import_of_interpreter_hub_is_caught(self) -> None:
+ """A relative import is resolved against the file's own package, not taken at face value."""
+ violations = _violate(
+ """
+ from ...interpreter_hub import get_library_manager
+ """,
+ relative_path="pipelex/cogt/sample/worker.py",
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+
+ def test_multi_name_import_reports_one_violation(self) -> None:
+ """One offending statement yields one violation, not one per imported name."""
+ violations = _violate(
+ """
+ from pipelex.interpreter_hub import get_library_manager, get_pipe_library, get_required_pipe
+ """
+ )
+ assert len(violations) == 1
+
+ def test_string_literal_import_module_form_is_caught(self) -> None:
+ """The `importlib.import_module` string form — invisible to every import-graph tool — is a violation."""
+ violations = _violate(
+ """
+ import importlib
+
+ def resolve():
+ return importlib.import_module("pipelex.interpreter_hub")
+ """
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_REFERENCE}
+
+ def test_string_literal_attribute_path_is_caught(self) -> None:
+ """A dotted attribute path under the interpreter hub — a `mocker.patch` target's shape — is a violation."""
+ violations = _violate(
+ """
+ PATCH_TARGET = "pipelex.interpreter_hub.get_pipe_router"
+ """
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_REFERENCE}
+
+ def test_prose_mentioning_the_hub_is_not_a_reference(self) -> None:
+ """A docstring or message that merely names the module is not a reference — matching is exact-or-boundary."""
+ violations = _violate(
+ '''
+ """The resolver `pipelex.interpreter_hub.set_interpreter_hub` installs at boot."""
+
+ MESSAGE = "see pipelex.interpreter_hub for the interpreter half"
+ '''
+ )
+ assert violations == []
+
+ def test_runtime_hub_is_not_matched_by_the_dead_hub_rule(self) -> None:
+ """`pipelex.runtime_hub` must not match `pipelex.hub` — boundary matching, not a substring test."""
+ violations = _violate(
+ """
+ PATCH_TARGET = "pipelex.runtime_hub.get_console"
+ """
+ )
+ assert violations == []
+
+ def test_interpreter_layer_may_import_interpreter_hub(self) -> None:
+ """Outside the declared runtime layer the layer rule does not apply."""
+ violations = _violate(
+ """
+ from pipelex.interpreter_hub import get_pipe_router
+ """,
+ relative_path=INTERPRETER_PATH,
+ )
+ assert violations == []
+
+ def test_type_checking_import_is_exempt_from_the_layer_rule(self) -> None:
+ """A type-only import loads nothing, so it does not break the property the rule protects."""
+ for test_expression in ("TYPE_CHECKING", "typing.TYPE_CHECKING"):
+ violations = _violate(
+ f"""
+ if {test_expression}:
+ from pipelex.interpreter_hub import InterpreterHub
+ """
+ )
+ assert violations == []
+
+ def test_runtime_else_branch_of_type_checking_is_not_exempt(self) -> None:
+ """The exemption covers the `TYPE_CHECKING` body only — its `else` runs at import time."""
+ violations = _violate(
+ """
+ if TYPE_CHECKING:
+ from pipelex.interpreter_hub import InterpreterHub
+ else:
+ from pipelex.interpreter_hub import InterpreterHub
+ """
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+ assert violations[0].lineno == 5
+
+ def test_type_checking_on_an_unrelated_receiver_is_not_exempt(self) -> None:
+ """The attributed form must be rooted at `typing` — any other receiver is a runtime condition.
+
+ Matching the attribute name alone would let `settings.TYPE_CHECKING:` or a stub module's flag
+ open an exempt block, which is a real import at runtime.
+ """
+ for receiver in ("settings", "compat", "not_typing"):
+ violations = _violate(
+ f"""
+ if {receiver}.TYPE_CHECKING:
+ from pipelex.interpreter_hub import InterpreterHub
+ """
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}, receiver
+
+ def test_negated_type_checking_is_not_exempt(self) -> None:
+ """`if not TYPE_CHECKING:` guards a runtime branch, so it earns no exemption."""
+ violations = _violate(
+ """
+ if not TYPE_CHECKING:
+ from pipelex.interpreter_hub import InterpreterHub
+ """
+ )
+ assert _kinds(violations) == {HubLayeringViolationKind.INTERPRETER_HUB_IMPORT}
+
+ def test_escape_hatch_suppresses_a_violation(self) -> None:
+ """The inline marker suppresses one statement, including across a parenthesized block."""
+ assert _violate("from pipelex.interpreter_hub import get_pipe_router # hub-layering: ignore\n") == []
+ assert (
+ _violate(
+ """
+ from pipelex.interpreter_hub import ( # hub-layering: ignore
+ get_pipe_router,
+ )
+ """
+ )
+ == []
+ )
+
+ def test_dead_hub_import_is_a_violation_in_every_layer(self) -> None:
+ """`pipelex.hub` is gone, so an import of it is dead code wherever it sits."""
+ source = f"from {DEAD_HUB} import get_console\n"
+ for relative_path in (RUNTIME_PATH, INTERPRETER_PATH, TEST_PATH):
+ violations = _violate(source, relative_path=relative_path)
+ assert _kinds(violations) == {HubLayeringViolationKind.DEAD_HUB_REFERENCE}
+
+ def test_dead_hub_string_literal_is_a_violation_in_tests_too(self) -> None:
+ """The `mocker.patch("pipelex.hub.get_console")` landmine: a string an ImportError never catches."""
+ violations = _violate(f'mocker.patch("{DEAD_HUB}.get_console")\n', relative_path=TEST_PATH)
+ assert _kinds(violations) == {HubLayeringViolationKind.DEAD_HUB_REFERENCE}
+
+ def test_dead_hub_is_not_exempt_inside_type_checking(self) -> None:
+ """The `TYPE_CHECKING` carve-out is for the layer rule only — a deleted module exists in no phase."""
+ violations = _violate(f"if TYPE_CHECKING:\n from {DEAD_HUB} import PipelexHub\n", relative_path=INTERPRETER_PATH)
+ assert _kinds(violations) == {HubLayeringViolationKind.DEAD_HUB_REFERENCE}
+
+ def test_tests_may_reference_the_interpreter_hub(self) -> None:
+ """A test legitimately patches the interpreter hub; `tests.*` is in no declared layer."""
+ violations = _violate(
+ """
+ mocker.patch("pipelex.interpreter_hub.get_pipe_router")
+ from pipelex.interpreter_hub import get_library_manager
+ """,
+ relative_path=TEST_PATH,
+ )
+ assert violations == []
+
+ def test_every_kind_names_a_remedy(self) -> None:
+ """Each violation kind carries an actionable remedy, so a failure needs no re-run to act on."""
+ for kind in HubLayeringViolationKind:
+ assert kind.remedy
diff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py b/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py
new file mode 100644
index 000000000..80ba2fa90
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py
@@ -0,0 +1,115 @@
+"""Unit tests for the filesystem surface of the hub-layering guard.
+
+`find_violations_in_source` is exercised from inline snippets in `test_hub_layering_guard.py`, where
+every path is a synthetic string. These pin the layer that actually walks a tree: which files get
+picked up, which get skipped, and how a path becomes the module qname that decides layer membership.
+A mistake here is invisible to a snippet test and silently shrinks what the guard covers — a skipped
+directory, a stale `__pycache__` copy scanned as if it were source, or an `__init__.py` resolving to
+the wrong package and so falling out of its own layer.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.hub_layering_guard import (
+ HubLayeringViolationKind,
+ collect_all_violations,
+ iter_source_files,
+ module_qname_for,
+)
+
+#: The deleted single hub. This line *declares* the dead path as test data rather than referencing
+#: it, so it carries the guard's own escape hatch — without it, the guard flags its own test suite.
+DEAD_HUB = "pipelex.hub" # hub-layering: ignore
+
+INTERPRETER_HUB_IMPORT = "from pipelex.interpreter_hub import get_pipe_router\n"
+RUNTIME_HUB_IMPORT = "from pipelex.runtime_hub import get_console\n"
+DEAD_HUB_PATCH = f'mocker.patch("{DEAD_HUB}.get_console")\n'
+
+
+def _make_tree(root: Path) -> None:
+ """A miniature repo covering every branch the walk has to get right.
+
+ `cogt/` is a declared runtime-layer package, so its breach is a violation; `pipeline/` is not, so
+ the identical import there is legal and must stay unreported; `__pycache__` holds a stale copy of
+ the offender; and `tests/` is scanned for the dead-module rule only.
+ """
+ sample = root / "pipelex" / "cogt" / "sample"
+ sample.mkdir(parents=True)
+ (sample / "__init__.py").write_text("", encoding="utf-8")
+ (sample / "clean.py").write_text(RUNTIME_HUB_IMPORT, encoding="utf-8")
+ (sample / "worker.py").write_text(INTERPRETER_HUB_IMPORT, encoding="utf-8")
+ cache = sample / "__pycache__"
+ cache.mkdir()
+ (cache / "worker.py").write_text(INTERPRETER_HUB_IMPORT, encoding="utf-8")
+
+ pipeline = root / "pipelex" / "pipeline"
+ pipeline.mkdir(parents=True)
+ (pipeline / "runner.py").write_text(INTERPRETER_HUB_IMPORT, encoding="utf-8")
+
+ tests_root = root / "tests"
+ tests_root.mkdir()
+ (tests_root / "helper.py").write_text(DEAD_HUB_PATCH, encoding="utf-8")
+
+
+class TestHubLayeringGuardFilesystem:
+ def test_full_scan_reports_exactly_the_real_offenders(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Both roots are walked, both rules applied, and layer membership decided per file.
+
+ Mirrors production, where the scan runs against the *relative* `SCAN_ROOTS`, so reported
+ paths are repo-root-relative.
+ """
+ _make_tree(tmp_path)
+ monkeypatch.chdir(tmp_path)
+
+ violations = collect_all_violations(roots=(Path("pipelex"), Path("tests")))
+
+ assert [(violation.relative_path, violation.kind) for violation in violations] == [
+ ("pipelex/cogt/sample/worker.py", HubLayeringViolationKind.INTERPRETER_HUB_IMPORT),
+ ("tests/helper.py", HubLayeringViolationKind.DEAD_HUB_REFERENCE),
+ ]
+
+ def test_pycache_is_never_walked(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A stale compiled-source copy is not source: scanning it would report a phantom file."""
+ _make_tree(tmp_path)
+ monkeypatch.chdir(tmp_path)
+
+ paths = [path.as_posix() for path in iter_source_files(root=Path("pipelex"))]
+
+ assert paths == [
+ "pipelex/cogt/sample/__init__.py",
+ "pipelex/cogt/sample/clean.py",
+ "pipelex/cogt/sample/worker.py",
+ "pipelex/pipeline/runner.py",
+ ]
+
+ def test_a_runtime_layer_package_init_is_inside_its_own_layer(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """`__init__`-stripping is load-bearing: without it `pipelex/cogt/__init__.py` would resolve to
+ `pipelex.cogt.__init__`, still match the layer by prefix — but a top-level `pipelex/__init__.py`
+ would resolve to `pipelex.__init__` and land in no layer at all. Pin the package form end to end.
+ """
+ cogt = tmp_path / "pipelex" / "cogt"
+ cogt.mkdir(parents=True)
+ (cogt / "__init__.py").write_text(INTERPRETER_HUB_IMPORT, encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+
+ violations = collect_all_violations(roots=(Path("pipelex"),))
+
+ assert [violation.kind for violation in violations] == [HubLayeringViolationKind.INTERPRETER_HUB_IMPORT]
+ assert violations[0].relative_path == "pipelex/cogt/__init__.py"
+
+ @pytest.mark.parametrize(
+ ("relative_path", "expected_qname"),
+ [
+ ("pipelex/cogt/sample/worker.py", "pipelex.cogt.sample.worker"),
+ ("pipelex/cogt/sample/__init__.py", "pipelex.cogt.sample"),
+ ("pipelex/__init__.py", "pipelex"),
+ ("tests/helper.py", "tests.helper"),
+ ],
+ )
+ def test_module_qname_for(self, relative_path: str, expected_qname: str) -> None:
+ """A package's `__init__.py` is the package itself, not a submodule named `__init__`."""
+ assert module_qname_for(path=Path(relative_path)) == expected_qname
diff --git a/tests/unit/pipelex/cli/test_agent_cli_output_discipline.py b/tests/unit/pipelex/cli/test_agent_cli_output_discipline.py
index b7ce52060..530cba6f8 100644
--- a/tests/unit/pipelex/cli/test_agent_cli_output_discipline.py
+++ b/tests/unit/pipelex/cli/test_agent_cli_output_discipline.py
@@ -92,7 +92,7 @@ class TestAgentCliOutputDiscipline:
mock_redirect = mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.log.redirect_to_stderr")
mock_hub = mocker.MagicMock()
mocker.patch(
- "pipelex.cli.agent_cli.commands.agent_cli_factory.PipelexHub.get_optional_instance",
+ "pipelex.cli.agent_cli.commands.agent_cli_factory.RuntimeHub.get_optional_instance",
return_value=mock_hub,
)
@@ -108,7 +108,7 @@ class TestAgentCliOutputDiscipline:
"""
mock_redirect = mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.log.redirect_to_stderr")
mocker.patch(
- "pipelex.cli.agent_cli.commands.agent_cli_factory.PipelexHub.get_optional_instance",
+ "pipelex.cli.agent_cli.commands.agent_cli_factory.RuntimeHub.get_optional_instance",
return_value=None,
)
diff --git a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
index a0ee65d61..cd79df817 100644
--- a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
+++ b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
@@ -26,7 +26,7 @@ class TestAgentDoctorCmd:
"""Stub the runtime bootstrap so unit tests don't load real config or mutate
global logging / PrettyPrinter state.
- ``setup_doctor_runtime`` instantiates a PipelexHub, loads config from disk, and
+ ``setup_doctor_runtime`` instantiates a RuntimeHub, loads config from disk, and
calls ``log.configure`` (once-per-process). ``apply_agent_cli_output_discipline``
mutates global PrettyPrinter mode and the hub's console target.
``silence_logging_for_agent_cli`` arms ``logging.disable`` at ``sys.maxsize``
diff --git a/tests/unit/pipelex/cli/test_codegen_cli.py b/tests/unit/pipelex/cli/test_codegen_cli.py
index 3eab8c950..abda90310 100644
--- a/tests/unit/pipelex/cli/test_codegen_cli.py
+++ b/tests/unit/pipelex/cli/test_codegen_cli.py
@@ -20,7 +20,7 @@ from pipelex.cli.commands.codegen.types_cmd import codegen_types_cmd
from pipelex.codegen.emitters.target import CodegenTarget, EmittedFile
from pipelex.codegen.lock import CODEGEN_LOCK_FILENAME
from pipelex.core.domains.domain_blueprint import DomainBlueprint
-from pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat
+from pipelex.core.pipes.rendering.input_renderer import InputsTemplateFormat
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe.exceptions import PipeLibraryError
diff --git a/tests/unit/pipelex/codegen/test_resolved_concepts.py b/tests/unit/pipelex/codegen/test_resolved_concepts.py
index 95e9d380c..c896da3c6 100644
--- a/tests/unit/pipelex/codegen/test_resolved_concepts.py
+++ b/tests/unit/pipelex/codegen/test_resolved_concepts.py
@@ -1,6 +1,6 @@
from pipelex.codegen.resolved_concepts import resolve_concepts_from_crate
-from pipelex.codegen.resolved_fields import ResolvedTypeKind, iter_imprecision_reasons
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.resolved_fields import ResolvedTypeKind, iter_imprecision_reasons
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/tests/unit/pipelex/cogt/content_generation/test_assignment_models_schema.py b/tests/unit/pipelex/cogt/content_generation/test_assignment_models_schema.py
index 0acb75055..f4847643c 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_assignment_models_schema.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_assignment_models_schema.py
@@ -7,7 +7,7 @@ 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 LLMSetting
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class SampleOutputModel(BaseModel):
diff --git a/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py b/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py
index 00e1caeb9..ae2e1a1f9 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py
@@ -14,7 +14,7 @@ from pipelex.cogt.content_generation.schema_to_model_factory import SchemaToMode
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
def _make_stub_job_metadata() -> JobMetadata:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_dry_mock.py b/tests/unit/pipelex/cogt/content_generation/test_dry_mock.py
index 518c8a2fb..e899f4c76 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_dry_mock.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_dry_mock.py
@@ -26,7 +26,7 @@ from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.cogt.usage.cost_registry import CostRegistry
from pipelex.core.stuffs.text_content import TextContent
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
def _dry_object_assignment() -> ObjectAssignment:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_dry_report_tz.py b/tests/unit/pipelex/cogt/content_generation/test_dry_report_tz.py
index dbdacaf49..63497ea7b 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_dry_report_tz.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_dry_report_tz.py
@@ -16,7 +16,7 @@ from pipelex.cogt.content_generation.dry_mock import report_dry_llm_job
from pipelex.cogt.llm.llm_job import LLMJob
from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestDryReportTimezone:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_extract_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_extract_generate_dry_branch.py
index d5bd39597..d157adde5 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_extract_generate_dry_branch.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_extract_generate_dry_branch.py
@@ -16,7 +16,7 @@ from pipelex.cogt.extract.extract_input import ExtractInput
from pipelex.cogt.extract.extract_job_components import ExtractJobConfig, ExtractJobParams
from pipelex.config import get_config
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestExtractGenerateDryBranch:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_img_gen_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_img_gen_generate_dry_branch.py
index d30251099..810ca1756 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_img_gen_generate_dry_branch.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_img_gen_generate_dry_branch.py
@@ -15,7 +15,7 @@ from pipelex.cogt.content_generation.img_gen_generate import img_gen_image_list_
from pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, Background, ImgGenJobConfig, ImgGenJobParams
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestImgGenGenerateDryBranch:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_llm_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_llm_generate_dry_branch.py
index 0c3ccb9df..51f8babf5 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_llm_generate_dry_branch.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_llm_generate_dry_branch.py
@@ -23,7 +23,7 @@ from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_setting import LLMSetting
from pipelex.cogt.usage.cost_registry import CostRegistry
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestLlmGenerateDryBranch:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py
index 622e6578c..f60f2e0bf 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py
@@ -12,7 +12,7 @@ from pipelex.cogt.content_generation.cogt_run_params import CogtRunParams
from pipelex.cogt.content_generation.render_generate import render_page_views_and_store
from pipelex.config import get_config
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestRenderGenerateDryBranch:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_scoped_content_generator.py b/tests/unit/pipelex/cogt/content_generation/test_scoped_content_generator.py
index 0d62e8574..490b6c221 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_scoped_content_generator.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_scoped_content_generator.py
@@ -1,4 +1,4 @@
-"""Unit tests for the `scoped_content_generator` ContextVar scope in `pipelex.hub`.
+"""Unit tests for the `scoped_content_generator` ContextVar scope in `pipelex.runtime_hub`.
The scope lets an in-process run (the validation sweep, the in-process graph dry-run)
pin an inline content generator so its inference leaves resolve it through
@@ -15,7 +15,7 @@ import pytest
from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocol
from pipelex.cogt.content_generation.generated_content_factory import GeneratedContentFactory
-from pipelex.hub import get_content_generator, scoped_content_generator
+from pipelex.runtime_hub import get_content_generator, scoped_content_generator
from pipelex.tools.storage.in_memory_storage_provider import InMemoryStorageProvider
diff --git a/tests/unit/pipelex/cogt/content_generation/test_search_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_search_generate_dry_branch.py
index 1888cbab4..091e360cb 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_search_generate_dry_branch.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_search_generate_dry_branch.py
@@ -16,7 +16,7 @@ from pipelex.cogt.search.search_setting import SearchSetting
from pipelex.config import get_config
from pipelex.core.stuffs.search_result_content import SearchResultContent
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestSearchGenerateDryBranch:
diff --git a/tests/unit/pipelex/cogt/content_generation/test_templating_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_templating_generate_dry_branch.py
index ca38e6655..ddc2117c7 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_templating_generate_dry_branch.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_templating_generate_dry_branch.py
@@ -11,10 +11,10 @@ from pytest_mock import MockerFixture
from pipelex.cogt.content_generation.assignment_models import TemplatingAssignment
from pipelex.cogt.content_generation.cogt_run_params import CogtRunParams
from pipelex.cogt.content_generation.templating_generate import templating_gen_text
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
+from pipelex.tools.jinja2.template_category import TemplateCategory
class TestTemplatingGenerateDryBranch:
diff --git a/tests/unit/pipelex/cogt/extract/test_extract_worker_usage_capture.py b/tests/unit/pipelex/cogt/extract/test_extract_worker_usage_capture.py
index 518a3a123..882a1deb9 100644
--- a/tests/unit/pipelex/cogt/extract/test_extract_worker_usage_capture.py
+++ b/tests/unit/pipelex/cogt/extract/test_extract_worker_usage_capture.py
@@ -23,7 +23,7 @@ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
_PER_PAGE_TOKENS = 1_000_000
diff --git a/tests/unit/pipelex/cogt/img_gen/conftest.py b/tests/unit/pipelex/cogt/img_gen/conftest.py
index bada8632c..56ee9a2e7 100644
--- a/tests/unit/pipelex/cogt/img_gen/conftest.py
+++ b/tests/unit/pipelex/cogt/img_gen/conftest.py
@@ -15,7 +15,7 @@ from pipelex.cogt.img_gen.img_gen_job_components import (
Quality,
)
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.image_utils import ImageFormat
if TYPE_CHECKING:
diff --git a/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_factory.py b/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_factory.py
index 311b97475..8089ebe7e 100644
--- a/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_factory.py
+++ b/tests/unit/pipelex/cogt/img_gen/test_img_gen_args_factory.py
@@ -45,8 +45,8 @@ from pipelex.cogt.llm.thinking_mode import ThinkingMode
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.usage.cost_category import CostCategory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.plugins.openai.openai_img_gen_worker import OpenAIImgGenWorker
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.filetype_utils import FileType
from pipelex.tools.misc.image_utils import ImageFormat
from pipelex.tools.uri.prepared_file import PreparedFileBase64
diff --git a/tests/unit/pipelex/cogt/templating/test_template_pipeline.py b/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
index cef4b1d68..cc81496bd 100644
--- a/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
+++ b/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
@@ -9,9 +9,9 @@ from typing import ClassVar
import pytest
from pipelex.cogt.templating.exceptions import TemplateSigilSyntaxError
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.jinja2.template_category import TemplateCategory
class TestData:
diff --git a/tests/unit/pipelex/cogt/usage/test_cost_registry.py b/tests/unit/pipelex/cogt/usage/test_cost_registry.py
index 1a981a37a..8f8ed5b6c 100644
--- a/tests/unit/pipelex/cogt/usage/test_cost_registry.py
+++ b/tests/unit/pipelex/cogt/usage/test_cost_registry.py
@@ -9,7 +9,7 @@ from pipelex.cogt.llm.llm_report import LLMTokenCostReportField, LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.cost_registry import CostRegistry
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestCostRegistry:
diff --git a/tests/unit/pipelex/cogt/usage/test_data.py b/tests/unit/pipelex/cogt/usage/test_data.py
index 4bf44683b..86515377b 100644
--- a/tests/unit/pipelex/cogt/usage/test_data.py
+++ b/tests/unit/pipelex/cogt/usage/test_data.py
@@ -6,8 +6,8 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.search.search_report import SearchTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
-from pipelex.pipeline.job_metadata import JobCategory, JobMetadata, UnitJobId
from pipelex.reporting.reporting_types import AnyTokensUsage
+from pipelex.system.job_metadata import JobCategory, JobMetadata, UnitJobId
RATED_NB_TOKENS: NbTokensByCategoryDict = {
TokenCategory.INPUT: 1000,
diff --git a/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py b/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py
index 169ae4515..74b09b087 100644
--- a/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py
+++ b/tests/unit/pipelex/core/concepts/test_concept_find_image_field_paths.py
@@ -6,7 +6,7 @@ import pytest
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.stuffs.structured_content import StructuredContent
-from pipelex.hub import get_concept_library, get_native_concept, get_required_concept
+from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
from tests.unit.pipelex.core.concepts import data
from tests.unit.pipelex.core.concepts.data import TestData
diff --git a/tests/unit/pipelex/core/concepts/test_special_args_concept.py b/tests/unit/pipelex/core/concepts/test_special_args_concept.py
index 71e1d0672..3e941e235 100644
--- a/tests/unit/pipelex/core/concepts/test_special_args_concept.py
+++ b/tests/unit/pipelex/core/concepts/test_special_args_concept.py
@@ -12,13 +12,13 @@ from pipelex.core.concepts.concept_structure_blueprint import (
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.stuff_factory import StuffContentFactory, StuffFactory
-from pipelex.hub import get_concept_library, get_pipe_router
+from pipelex.interpreter_hub import get_concept_library, get_pipe_router
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.dry_runnable
diff --git a/tests/unit/pipelex/core/memory/input_shaper/conftest.py b/tests/unit/pipelex/core/memory/input_shaper/conftest.py
index e2f235a94..1de5157bc 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/conftest.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/conftest.py
@@ -12,7 +12,8 @@ import pytest
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.stuffs.structured_content import StructuredContent
-from pipelex.hub import get_class_registry, get_concept_library
+from pipelex.interpreter_hub import get_concept_library
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
from tests.unit.pipelex.core.memory.input_shaper.data import CONCEPT_DEFS, CONCEPT_REFS, REFINING_CLASSES, SHAPER_TEST_DOMAIN
diff --git a/tests/unit/pipelex/core/memory/input_shaper/data.py b/tests/unit/pipelex/core/memory/input_shaper/data.py
index e5f4250e0..077d1fa13 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/data.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/data.py
@@ -98,7 +98,7 @@ def build_input_specs(entries: list[tuple[str, str, VariableMultiplicity | None]
Concepts are resolved against the current concept library, so this must run after the
``shaper_library`` fixture has registered the test concepts.
"""
- from pipelex.hub import get_concept_library # noqa: PLC0415
+ from pipelex.interpreter_hub import get_concept_library # noqa: PLC0415
library = get_concept_library()
root: dict[str, StuffSpec] = {}
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py b/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py
index c9bffda83..77494c332 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py
@@ -14,6 +14,7 @@ from pipelex.core.memory.exceptions import MultiplicityCountMismatchError, Struc
from pipelex.core.memory.input_shaper import InputShaper
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.interpreter_hub import get_concept_library
from pipelex.tools.tabular.exceptions import CsvError
from tests.unit.pipelex.core.memory.input_shaper.data import ShaperPerson, build_input_specs
@@ -35,7 +36,7 @@ class TestInputShaperCsvBySignature:
def test_bare_csv_path_under_declared_list(self, people_csv: Path):
"""A bare absolute CSV path under `ShaperPerson[]` reads rows into ListContent[ShaperPerson]."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
- working_memory = InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs, concept_provider=get_concept_library())
people_stuff = working_memory.get_stuff("people")
assert people_stuff.concept.concept_ref == "shaper_test.ShaperPerson"
@@ -45,7 +46,7 @@ class TestInputShaperCsvBySignature:
"""The exact {"url": <csv>} wrapper under `ShaperPerson[]` reads the same table — no envelope."""
value: dict[str, Any] = {"url": str(people_csv)}
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
- working_memory = InputShaper.shape({"people": value}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"people": value}, input_specs=input_specs, concept_provider=get_concept_library())
people_stuff = working_memory.get_stuff("people")
assert people_stuff.concept.concept_ref == "shaper_test.ShaperPerson"
@@ -55,14 +56,16 @@ class TestInputShaperCsvBySignature:
def test_relative_csv_resolves_against_base_dir(self, tmp_path: Path):
"""A bare relative CSV path resolves against inputs_base_dir before the table is read."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
- working_memory = InputShaper.shape({"people": "people.csv"}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"people": "people.csv"}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
self._assert_people_list(working_memory.get_stuff("people").content)
def test_fixed_count_matching_rows(self, people_csv: Path):
"""A `ShaperPerson[2]` input accepts a two-row CSV."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", 2)])
- working_memory = InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs, concept_provider=get_concept_library())
self._assert_people_list(working_memory.get_stuff("people").content)
@@ -70,29 +73,29 @@ class TestInputShaperCsvBySignature:
"""A `ShaperPerson[3]` input rejects a two-row CSV with the D2 count-mismatch error."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", 3)])
with pytest.raises(MultiplicityCountMismatchError, match="'people'"):
- InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)
+ InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs, concept_provider=get_concept_library())
def test_csv_under_singular_is_wrong_scalar_kind(self, people_csv: Path):
"""A CSV names a TABLE; under a singular `ShaperPerson` a bare path is a wrong-kind error."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", None)])
with pytest.raises(WrongScalarKindError, match="'people'"):
- InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)
+ InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs, concept_provider=get_concept_library())
def test_non_tabular_string_falls_through(self):
"""A bare non-tabular string under `ShaperPerson[]` is NOT hijacked as a table — normal D5 error."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
with pytest.raises(WrongScalarKindError, match="'people'"):
- InputShaper.shape({"people": "people.txt"}, input_specs=input_specs)
+ InputShaper.shape({"people": "people.txt"}, input_specs=input_specs, concept_provider=get_concept_library())
def test_url_dict_with_sibling_keys_stays_record(self, people_csv: Path):
"""A record dict that merely HAS a url field is not a table ref — validated as a record."""
value: dict[str, Any] = {"url": str(people_csv), "label": "roster"}
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
with pytest.raises(StructureValidationError, match="'people'"):
- InputShaper.shape({"people": value}, input_specs=input_specs)
+ InputShaper.shape({"people": value}, input_specs=input_specs, concept_provider=get_concept_library())
def test_remote_csv_url_raises_csv_error(self):
"""A remote tabular url is rejected loudly (local paths only in v1), not read or ignored."""
input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
with pytest.raises(CsvError, match="local file paths only"):
- InputShaper.shape({"people": "https://example.com/people.csv"}, input_specs=input_specs)
+ InputShaper.shape({"people": "https://example.com/people.csv"}, input_specs=input_specs, concept_provider=get_concept_library())
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_errors.py b/tests/unit/pipelex/core/memory/input_shaper/test_errors.py
index 884c63f6f..85622b322 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_errors.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_errors.py
@@ -15,6 +15,7 @@ from pipelex.core.memory.exceptions import (
)
from pipelex.core.memory.input_shaper import InputShaper
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
+from pipelex.interpreter_hub import get_concept_library
from tests.unit.pipelex.core.memory.input_shaper.data import build_input_specs
# (test_name, concept_ref, multiplicity, provided_value, expected_exception, error_match)
@@ -68,7 +69,7 @@ class TestInputShaperErrors:
input_specs = build_input_specs([("my_input", concept_ref, multiplicity)])
with pytest.raises(expected_exception, match=error_match) as exc_info:
- InputShaper.shape({"my_input": provided_value}, input_specs=input_specs)
+ InputShaper.shape({"my_input": provided_value}, input_specs=input_specs, concept_provider=get_concept_library())
# D4 mandates the rendered expected-shape template appears in every shaping-error message.
assert "Expected shape:" in str(exc_info.value), f"Missing rendered shape for {test_name}"
@@ -78,7 +79,7 @@ class TestInputShaperErrors:
input_specs = build_input_specs([("question", "native.Text", None)])
with pytest.raises(UnknownInputNameError, match="not declared") as exc_info:
- InputShaper.shape({"quesion": "typo"}, input_specs=input_specs)
+ InputShaper.shape({"quesion": "typo"}, input_specs=input_specs, concept_provider=get_concept_library())
message = str(exc_info.value)
assert "'question'" in message, "Unknown-name error should list the declared inputs"
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py
index c1eedaf73..f037de9d7 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py
@@ -12,6 +12,7 @@ from pipelex.core.memory.input_shaper import InputShaper
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.core.stuffs.time_content import TimeContent
+from pipelex.interpreter_hub import get_concept_library
from tests.unit.pipelex.core.memory.input_shaper.data import OpeningTime, Question, ShaperInvoice, ShaperWeird, build_input_specs
@@ -21,7 +22,7 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("invoice", "shaper_test.ShaperInvoice", None)])
provided = {"concept": "shaper_test.ShaperInvoice", "content": {"invoice_number": "INV-001", "amount": 1250.0}}
- working_memory = InputShaper.shape({"invoice": provided}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"invoice": provided}, input_specs=input_specs, concept_provider=get_concept_library())
stuff = working_memory.root["invoice"]
pretty_print(stuff, title="envelope structured")
@@ -33,7 +34,7 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("answer", "native.Text", None)])
provided = {"concept": "shaper_test.Question", "content": "What are the fees?"}
- working_memory = InputShaper.shape({"answer": provided}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"answer": provided}, input_specs=input_specs, concept_provider=get_concept_library())
stuff = working_memory.root["answer"]
pretty_print(stuff, title="envelope refining wins")
@@ -50,7 +51,7 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("opening", "native.Time", None)])
provided = {"concept": concept_ref, "content": "15:40:00+02:00"}
- working_memory = InputShaper.shape({"opening": provided}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"opening": provided}, input_specs=input_specs, concept_provider=get_concept_library())
stuff = working_memory.root["opening"]
assert stuff.concept.concept_ref == concept_ref
@@ -60,7 +61,7 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("opening", "native.Time", None)])
provided = {"concept": "native.Time", "content": datetime.time(15, 40)}
- working_memory = InputShaper.shape({"opening": provided}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"opening": provided}, input_specs=input_specs, concept_provider=get_concept_library())
assert working_memory.root["opening"].content == TimeContent(time=datetime.time(15, 40))
@@ -69,7 +70,9 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("invoice", "shaper_test.ShaperInvoice", None)])
provided = ShaperInvoice(invoice_number="INV-002", amount=99.0)
- working_memory = InputShaper.shape({"invoice": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ working_memory = InputShaper.shape(
+ {"invoice": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
stuff = working_memory.root["invoice"]
pretty_print(stuff, title="prebuilt object")
@@ -85,7 +88,9 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("questions", "shaper_test.Question", True)])
provided = [Question(text="a"), Question(text="b")]
- working_memory = InputShaper.shape({"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ working_memory = InputShaper.shape(
+ {"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
stuff = working_memory.root["questions"]
pretty_print(stuff, title="list of prebuilt StuffContent")
@@ -98,7 +103,9 @@ class TestInputShaperExplicitForms:
provided = [Question(text="a")]
with pytest.raises(ExplicitConceptIncompatibleError, match="not compatible"):
- InputShaper.shape({"priorities": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ InputShaper.shape(
+ {"priorities": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
def test_explicit_list_into_singular_raises(self) -> None:
"""D2: an explicit ListContent (or envelope-with-list) must not fill a singular-declared slot.
@@ -110,7 +117,9 @@ class TestInputShaperExplicitForms:
provided: ListContent[Question] = ListContent(items=[Question(text="a"), Question(text="b")])
with pytest.raises(ListWhereSingularError, match="declares a single"):
- InputShaper.shape({"question": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ InputShaper.shape(
+ {"question": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
def test_explicit_list_wrong_fixed_count_raises(self) -> None:
"""D2: an explicit ListContent whose length differs from a declared [N] count is a D4 error."""
@@ -118,14 +127,18 @@ class TestInputShaperExplicitForms:
provided: ListContent[Question] = ListContent(items=[Question(text="only-one")])
with pytest.raises(MultiplicityCountMismatchError, match="exactly 2 items"):
- InputShaper.shape({"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ InputShaper.shape(
+ {"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
def test_explicit_list_into_list_slot_ok(self) -> None:
"""D2/D6: an explicit ListContent whose length matches a declared list slot shapes cleanly."""
input_specs = build_input_specs([("questions", "shaper_test.Question", True)])
provided: ListContent[Question] = ListContent(items=[Question(text="a"), Question(text="b")])
- working_memory = InputShaper.shape({"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ working_memory = InputShaper.shape(
+ {"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
stuff = working_memory.root["questions"]
pretty_print(stuff, title="explicit list into list slot")
@@ -137,7 +150,9 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("payload", "native.Dynamic", None)])
provided: ListContent[Question] = ListContent(items=[Question(text="a"), Question(text="b")])
- working_memory = InputShaper.shape({"payload": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])
+ working_memory = InputShaper.shape(
+ {"payload": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"], concept_provider=get_concept_library()
+ )
stuff = working_memory.root["payload"]
pretty_print(stuff, title="explicit list into Dynamic slot")
@@ -154,7 +169,7 @@ class TestInputShaperExplicitForms:
input_specs = build_input_specs([("weird", "shaper_test.ShaperWeird", None)])
provided = {"concept": "shaper_test.ShaperWeird", "content": {"concept": "x", "content": "y"}}
- working_memory = InputShaper.shape({"weird": provided}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"weird": provided}, input_specs=input_specs, concept_provider=get_concept_library())
stuff = working_memory.root["weird"]
pretty_print(stuff, title="collision rule")
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py b/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py
index 5a2d9123f..72459d5d9 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py
@@ -11,6 +11,7 @@ import pytest
from pipelex.core.memory.input_shaper import InputShaper
from pipelex.core.stuffs.list_content import ListContent
+from pipelex.interpreter_hub import get_concept_library
from tests.unit.pipelex.core.memory.input_shaper.data import Exhibit, Photo, build_input_specs
if TYPE_CHECKING:
@@ -21,7 +22,9 @@ class TestInputShaperFilePaths:
def test_bare_relative_path_resolves_against_base_dir(self, tmp_path: Path):
"""A bare relative path for an Image-refining input becomes the base_dir-resolved path."""
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": "photo.jpg"}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"photo": "photo.jpg"}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
photo_stuff = working_memory.get_stuff("photo")
assert photo_stuff.concept.concept_ref == "shaper_test.Photo"
@@ -32,7 +35,9 @@ class TestInputShaperFilePaths:
"""An absolute path is never rewritten, base_dir or not."""
absolute_path = str(tmp_path / "elsewhere" / "photo.jpg")
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": absolute_path}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"photo": absolute_path}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
photo_stuff = working_memory.get_stuff("photo")
assert isinstance(photo_stuff.content, Photo)
@@ -41,7 +46,7 @@ class TestInputShaperFilePaths:
def test_bare_relative_path_without_base_dir_untouched(self):
"""No base_dir (in-process / inline-JSON callers): a relative path keeps today's CWD contract."""
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": "photo.jpg"}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"photo": "photo.jpg"}, input_specs=input_specs, concept_provider=get_concept_library())
photo_stuff = working_memory.get_stuff("photo")
assert isinstance(photo_stuff.content, Photo)
@@ -59,7 +64,9 @@ class TestInputShaperFilePaths:
def test_remote_and_scheme_urls_untouched(self, tmp_path: Path, url_value: str):
"""Remote URLs and scheme-qualified URIs are not local paths — never rewritten."""
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": url_value}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"photo": url_value}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
photo_stuff = working_memory.get_stuff("photo")
assert isinstance(photo_stuff.content, Photo)
@@ -69,7 +76,9 @@ class TestInputShaperFilePaths:
"""Each bare relative item of a Document[] input resolves; absolute items stay untouched."""
absolute_path = str(tmp_path / "other" / "b.pdf")
input_specs = build_input_specs([("exhibits", "shaper_test.Exhibit", True)])
- working_memory = InputShaper.shape({"exhibits": ["a.pdf", absolute_path]}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"exhibits": ["a.pdf", absolute_path]}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
exhibits_stuff = working_memory.get_stuff("exhibits")
assert exhibits_stuff.concept.concept_ref == "shaper_test.Exhibit"
@@ -82,7 +91,9 @@ class TestInputShaperFilePaths:
"""The {"url": ...} dict form is owned by the CLI's url-key walk — the shaper leaves it as-is."""
value: dict[str, Any] = {"url": "photo.jpg"}
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": value}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"photo": value}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
photo_stuff = working_memory.get_stuff("photo")
assert isinstance(photo_stuff.content, Photo)
@@ -91,7 +102,9 @@ class TestInputShaperFilePaths:
def test_bare_tilde_path_expands_to_home_not_base_dir(self, tmp_path: Path):
"""A ~-prefixed path is home-anchored: it expands to the home dir, never joined onto base_dir."""
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": "~/photo.jpg"}, input_specs=input_specs, inputs_base_dir=tmp_path)
+ working_memory = InputShaper.shape(
+ {"photo": "~/photo.jpg"}, input_specs=input_specs, inputs_base_dir=tmp_path, concept_provider=get_concept_library()
+ )
photo_stuff = working_memory.get_stuff("photo")
assert isinstance(photo_stuff.content, Photo)
@@ -100,7 +113,7 @@ class TestInputShaperFilePaths:
def test_bare_tilde_path_expands_without_base_dir(self):
"""No base_dir: a ~-prefixed path still expands to home (~ is home-anchored, not CWD-relative)."""
input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])
- working_memory = InputShaper.shape({"photo": "~/photo.jpg"}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"photo": "~/photo.jpg"}, input_specs=input_specs, concept_provider=get_concept_library())
photo_stuff = working_memory.get_stuff("photo")
assert isinstance(photo_stuff.content, Photo)
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py b/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py
index 244561feb..e28152d13 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py
@@ -9,6 +9,7 @@ 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.text_content import TextContent
+from pipelex.interpreter_hub import get_concept_library
from tests.unit.pipelex.core.memory.input_shaper.data import Deadline, Question, ShaperPerson, build_input_specs
# (test_name, concept_ref, multiplicity, provided_value, expected_concept_ref, expected_list_content)
@@ -105,7 +106,7 @@ class TestInputShaperMultiplicity:
log.info(f"Testing multiplicity case: {test_name}")
input_specs = build_input_specs([("my_input", concept_ref, multiplicity)])
- working_memory = InputShaper.shape({"my_input": provided_value}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"my_input": provided_value}, input_specs=input_specs, concept_provider=get_concept_library())
stuff = working_memory.root["my_input"]
pretty_print(stuff, title=f"Result for {test_name}")
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_provider_injection.py b/tests/unit/pipelex/core/memory/input_shaper/test_provider_injection.py
new file mode 100644
index 000000000..d91e636df
--- /dev/null
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_provider_injection.py
@@ -0,0 +1,53 @@
+"""The injected `concept_provider` is consulted, not merely accepted.
+
+Phase 4 of the hub split converted `core/`'s straddlers to take a `ConceptProviderAbstract` as a
+parameter instead of calling `interpreter_hub.get_concept_library()` — that inversion is what lets
+core's data model measure zero interpreter modules. But every call site in the suite passes the
+identical `get_concept_library()`, so the parameter is only ever proven *accepted*: a regression that
+took the provider and then reached for the hub anyway would produce the same answers everywhere and
+fail nothing. These pass a provider that answers *differently* from the real library, so an ignored
+parameter changes the result.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pipelex.core.concepts.concept_provider_abstract import ConceptProviderAbstract
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.memory.input_shaper import InputKind, InputShaper
+from pipelex.interpreter_hub import get_concept_library
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+ from pipelex.core.concepts.concept import Concept
+
+
+class TestConceptProviderInjection:
+ def test_resolve_input_kind_reads_the_injected_provider(self, mocker: MockerFixture) -> None:
+ """A stub answering compatibility differently must select a different arm.
+
+ `resolve_input_kind` walks the natives in a fixed order and takes the first `is_compatible`
+ hit, so a stub that only ever matches `Number` moves a `Text` concept off the TEXT arm — an
+ outcome unreachable through the real library, and unreachable at all if the parameter were
+ ignored.
+ """
+ library = get_concept_library()
+ text_concept = library.get_native_concept(native_concept=NativeConceptCode.TEXT)
+ number_concept = library.get_native_concept(native_concept=NativeConceptCode.NUMBER)
+
+ # Baseline through the real provider, so the contrast below is not an artefact of the fixture.
+ assert InputShaper.resolve_input_kind(text_concept, concept_provider=library) is InputKind.TEXT
+
+ def _only_number_is_compatible(*, wanted_concept: Concept, **_kwargs: object) -> bool:
+ """Disagree with the real library on purpose: nothing but `Number` ever matches."""
+ return wanted_concept == number_concept
+
+ stub = mocker.Mock(spec=ConceptProviderAbstract)
+ stub.get_native_concept.side_effect = library.get_native_concept
+ stub.is_compatible.side_effect = _only_number_is_compatible
+
+ assert InputShaper.resolve_input_kind(text_concept, concept_provider=stub) is InputKind.NUMBER
+ assert stub.is_compatible.called
+ assert stub.get_native_concept.called
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.py b/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.py
index 79e081bc8..9b8771f3b 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.py
@@ -11,6 +11,7 @@ from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
+from pipelex.interpreter_hub import get_concept_library
from tests.unit.pipelex.core.memory.input_shaper.data import (
Deadline,
Exhibit,
@@ -72,7 +73,7 @@ class TestInputShaperScalarArms:
log.info(f"Testing scalar arm case: {test_name}")
input_specs = build_input_specs([("my_input", concept_ref, None)])
- working_memory = InputShaper.shape({"my_input": provided_value}, input_specs=input_specs)
+ working_memory = InputShaper.shape({"my_input": provided_value}, input_specs=input_specs, concept_provider=get_concept_library())
stuff = working_memory.root["my_input"]
pretty_print(stuff, title=f"Result for {test_name}")
diff --git a/tests/unit/pipelex/core/pipes/test_input_renderer_light.py b/tests/unit/pipelex/core/pipes/rendering/test_input_renderer_light.py
similarity index 99%
rename from tests/unit/pipelex/core/pipes/test_input_renderer_light.py
rename to tests/unit/pipelex/core/pipes/rendering/test_input_renderer_light.py
index 32214f71d..2f6f86ae0 100644
--- a/tests/unit/pipelex/core/pipes/test_input_renderer_light.py
+++ b/tests/unit/pipelex/core/pipes/rendering/test_input_renderer_light.py
@@ -21,7 +21,7 @@ from typing import Any
import tomli
from pipelex.core.memory.input_shaper import InputKind
-from pipelex.core.pipes.inputs.input_renderer import (
+from pipelex.core.pipes.rendering.input_renderer import (
_delighten_entry, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
serialize_inputs_template_to_toml,
)
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer.py b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer.py
similarity index 98%
rename from tests/unit/pipelex/core/pipes/output/test_output_renderer.py
rename to tests/unit/pipelex/core/pipes/rendering/test_output_renderer.py
index 0c3f4ff53..85a39decf 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer.py
+++ b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer.py
@@ -12,8 +12,8 @@ from pytest_mock import MockerFixture
from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
-from pipelex.core.pipes.output.output_renderer import render_output
from pipelex.core.pipes.pipe_abstract import PipeAbstract
+from pipelex.core.pipes.rendering.output_renderer import render_output
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.stuffs.image_content import ImageContent
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer_anything_formats.py
similarity index 96%
rename from tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py
rename to tests/unit/pipelex/core/pipes/rendering/test_output_renderer_anything_formats.py
index 207d0eedf..09e5e7a12 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_anything_formats.py
+++ b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer_anything_formats.py
@@ -5,9 +5,9 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
-from pipelex.core.pipes.output.output_renderer import render_output
+from pipelex.core.pipes.rendering.output_renderer import render_output
-GET_REQUIRED_PIPE_TARGET = "pipelex.core.pipes.output.output_renderer.get_required_pipe"
+GET_REQUIRED_PIPE_TARGET = "pipelex.core.pipes.rendering.output_renderer.get_required_pipe"
def _make_anything_condition_pipe(mocker: MockerFixture, mapped_pipe_code: str) -> Any:
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer_collect_condition.py
similarity index 95%
rename from tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
rename to tests/unit/pipelex/core/pipes/rendering/test_output_renderer_collect_condition.py
index c1c3c92f1..cf1e4ebda 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
+++ b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer_collect_condition.py
@@ -5,9 +5,9 @@ from pytest_mock import MockerFixture
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
from pipelex.core.concepts.exceptions import ConceptError
-from pipelex.core.pipes.output.output_renderer import _collect_possible_outputs # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
+from pipelex.core.pipes.rendering.output_renderer import _collect_possible_outputs # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
-GET_REQUIRED_PIPE_TARGET = "pipelex.core.pipes.output.output_renderer.get_required_pipe"
+GET_REQUIRED_PIPE_TARGET = "pipelex.core.pipes.rendering.output_renderer.get_required_pipe"
def _make_condition_pipe(mocker: MockerFixture, dependencies: set[str]) -> Any:
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer_collect_sequence.py
similarity index 95%
rename from tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
rename to tests/unit/pipelex/core/pipes/rendering/test_output_renderer_collect_sequence.py
index c9017ec5b..fd65ca1f4 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
+++ b/tests/unit/pipelex/core/pipes/rendering/test_output_renderer_collect_sequence.py
@@ -5,9 +5,9 @@ from pytest_mock import MockerFixture
from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat
from pipelex.core.concepts.exceptions import ConceptError
-from pipelex.core.pipes.output.output_renderer import _collect_possible_outputs # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
+from pipelex.core.pipes.rendering.output_renderer import _collect_possible_outputs # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
-GET_REQUIRED_PIPE_TARGET = "pipelex.core.pipes.output.output_renderer.get_required_pipe"
+GET_REQUIRED_PIPE_TARGET = "pipelex.core.pipes.rendering.output_renderer.get_required_pipe"
def _make_sequence_pipe(mocker: MockerFixture, sub_pipe_codes: list[str]) -> Any:
diff --git a/tests/unit/pipelex/core/pipes/test_input_requirements_factory.py b/tests/unit/pipelex/core/pipes/test_input_requirements_factory.py
index f94c57f21..6e019058c 100644
--- a/tests/unit/pipelex/core/pipes/test_input_requirements_factory.py
+++ b/tests/unit/pipelex/core/pipes/test_input_requirements_factory.py
@@ -6,6 +6,7 @@ from pipelex.core.concepts.exceptions import ConceptStringError
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory, InputStuffSpecsFactoryError
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import PresenceMarker
+from pipelex.interpreter_hub import get_concept_library
from pipelex.libraries.concept.exceptions import ConceptLibraryError
from tests.unit.pipelex.core.pipes.data import (
CONCEPT_CODE_RESOLUTION_TEST_CASES,
@@ -35,7 +36,9 @@ class TestMakeInputRequirementsFromString:
):
"""Test parsing a concept string without brackets (single item, default)."""
load_empty_library()
- result = InputStuffSpecsFactory.make_from_string(domain_code=domain_code, stuff_spec_str=stuff_spec_str)
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
+ )
assert isinstance(result, StuffSpec)
assert result.concept.concept_ref == expected_concept_ref
@@ -50,7 +53,9 @@ class TestMakeInputRequirementsFromString:
):
load_empty_library()
"""Test parsing a concept string with empty brackets (multiple items)."""
- result = InputStuffSpecsFactory.make_from_string(domain_code=domain_code, stuff_spec_str=stuff_spec_str)
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
+ )
assert isinstance(result, StuffSpec)
assert result.concept.concept_ref == expected_concept_ref
@@ -65,7 +70,9 @@ class TestMakeInputRequirementsFromString:
):
"""Test parsing a concept string with a number in brackets (fixed count)."""
load_empty_library()
- result = InputStuffSpecsFactory.make_from_string(domain_code=domain_code, stuff_spec_str=stuff_spec_str)
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
+ )
assert isinstance(result, StuffSpec)
assert result.concept.concept_ref == expected_concept_ref
@@ -80,7 +87,9 @@ class TestMakeInputRequirementsFromString:
):
load_empty_library()
"""Test parsing concept strings with various numbers in brackets."""
- result = InputStuffSpecsFactory.make_from_string(domain_code=domain_code, stuff_spec_str=stuff_spec_str)
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
+ )
assert result.multiplicity == expected_multiplicity, f"Failed for {stuff_spec_str}"
assert result.concept.concept_ref == expected_concept_ref
@@ -91,7 +100,9 @@ class TestMakeInputRequirementsFromString:
def test_different_concept_codes(self, domain_code: str, stuff_spec_str: str, expected_concept_ref: str, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test parsing various concept codes without multiplicity."""
- result = InputStuffSpecsFactory.make_from_string(domain_code=domain_code, stuff_spec_str=stuff_spec_str)
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
+ )
assert result.concept.concept_ref == expected_concept_ref
assert result.multiplicity is None
@@ -100,7 +111,9 @@ class TestMakeInputRequirementsFromString:
"""Test parsing concept codes from custom domains."""
# Note: This test will only work if these concepts exist in the system
# For now, we'll test with native concepts, but the pattern should work for any domain
- result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[3]")
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code="native", stuff_spec_str="native.Text[3]", concept_provider=get_concept_library()
+ )
assert result.concept.concept_ref == "native.Text"
assert result.multiplicity == 3
@@ -121,7 +134,7 @@ class TestMakeInputRequirementsFromString:
):
"""Test parsing presence markers on input stuff spec strings."""
load_empty_library()
- result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str=stuff_spec_str)
+ result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library())
assert result.concept.concept_ref == "native.Text"
assert result.multiplicity == expected_multiplicity
assert result.presence == expected_presence
@@ -130,19 +143,23 @@ class TestMakeInputRequirementsFromString:
load_empty_library()
"""Test that an invalid concept code raises ConceptLibraryConceptNotFoundError."""
with pytest.raises(ConceptLibraryError):
- InputStuffSpecsFactory.make_from_string(domain_code="nonexistent", stuff_spec_str="nonexistent.InvalidConcept")
+ InputStuffSpecsFactory.make_from_string(
+ domain_code="nonexistent", stuff_spec_str="nonexistent.InvalidConcept", concept_provider=get_concept_library()
+ )
def test_concept_not_found_with_multiplicity_raises_error(self, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test that an invalid concept code with multiplicity raises ConceptLibraryConceptNotFoundError."""
with pytest.raises(ConceptLibraryError):
- InputStuffSpecsFactory.make_from_string(domain_code="nonexistent", stuff_spec_str="nonexistent.InvalidConcept[5]")
+ InputStuffSpecsFactory.make_from_string(
+ domain_code="nonexistent", stuff_spec_str="nonexistent.InvalidConcept[5]", concept_provider=get_concept_library()
+ )
def test_empty_string_raises_value_error(self, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test that an empty string raises InputStuffSpecsFactorySyntaxError."""
with pytest.raises(InputStuffSpecsFactoryError, match="Invalid input stuff spec string") as exc_info:
- InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="")
+ InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="", concept_provider=get_concept_library())
# This error is raised directly without a cause
assert exc_info.value.__cause__ is None
@@ -152,14 +169,16 @@ class TestMakeInputRequirementsFromString:
# The regex will match "native.Text[abc]" as concept="native.Text[abc]", multiplicity=None
# This will then fail during concept validation with ConceptCodeError
with pytest.raises(InputStuffSpecsFactoryError) as exc_info:
- InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[abc]")
+ InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[abc]", concept_provider=get_concept_library())
assert exc_info.value.__cause__ is not None
assert isinstance(exc_info.value.__cause__, ConceptStringError)
def test_multiplicity_zero_in_brackets(self, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test parsing a concept string with 0 in brackets."""
- result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[0]")
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code="native", stuff_spec_str="native.Text[0]", concept_provider=get_concept_library()
+ )
assert isinstance(result, StuffSpec)
assert result.concept.concept_ref == "native.Text"
@@ -168,13 +187,15 @@ class TestMakeInputRequirementsFromString:
def test_return_type(self, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test that the method returns an StuffSpec instance."""
- result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text")
+ result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text", concept_provider=get_concept_library())
assert isinstance(result, StuffSpec)
def test_concept_attribute_access(self, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test that the returned StuffSpec has proper concept attributes."""
- result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[5]")
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code="native", stuff_spec_str="native.Text[5]", concept_provider=get_concept_library()
+ )
assert hasattr(result, "concept")
assert hasattr(result, "multiplicity")
@@ -184,7 +205,9 @@ class TestMakeInputRequirementsFromString:
def test_edge_case_very_long_number(self, load_empty_library: Callable[[], None]):
load_empty_library()
"""Test parsing with a very long number in brackets."""
- result = InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[999999]")
+ result = InputStuffSpecsFactory.make_from_string(
+ domain_code="native", stuff_spec_str="native.Text[999999]", concept_provider=get_concept_library()
+ )
assert result.multiplicity == 999999
assert result.concept.concept_ref == "native.Text"
@@ -194,13 +217,13 @@ class TestMakeInputRequirementsFromString:
"""Test that whitespace is not automatically trimmed."""
# Whitespace should cause domain validation to fail
with pytest.raises(InputStuffSpecsFactoryError) as exc_info:
- InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str=" native.Text")
+ InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str=" native.Text", concept_provider=get_concept_library())
assert exc_info.value.__cause__ is not None
assert isinstance(exc_info.value.__cause__, ConceptStringError)
# Trailing whitespace should cause concept code validation to fail
with pytest.raises(InputStuffSpecsFactoryError) as exc_info:
- InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text ")
+ InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text ", concept_provider=get_concept_library())
assert exc_info.value.__cause__ is not None
assert isinstance(exc_info.value.__cause__, ConceptStringError)
@@ -210,7 +233,7 @@ class TestMakeInputRequirementsFromString:
# "native.Text[5][10]" should match as concept="native.Text[5]", multiplicity=10
# This will fail during concept code validation
with pytest.raises(InputStuffSpecsFactoryError) as exc_info:
- InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[5][10]")
+ InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="native.Text[5][10]", concept_provider=get_concept_library())
assert exc_info.value.__cause__ is not None
assert isinstance(exc_info.value.__cause__, ConceptStringError)
@@ -219,7 +242,7 @@ class TestMakeInputRequirementsFromString:
"""Test that brackets at the start are part of the concept name."""
# This will fail during domain validation
with pytest.raises(InputStuffSpecsFactoryError) as exc_info:
- InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="[5]native.Text")
+ InputStuffSpecsFactory.make_from_string(domain_code="native", stuff_spec_str="[5]native.Text", concept_provider=get_concept_library())
assert exc_info.value.__cause__ is not None
assert isinstance(exc_info.value.__cause__, ConceptStringError)
@@ -244,8 +267,7 @@ class TestMakeInputRequirementsFromString:
"""
load_empty_library()
result = InputStuffSpecsFactory.make_from_string(
- domain_code=domain_code,
- stuff_spec_str=stuff_spec_str,
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
)
assert isinstance(result, StuffSpec)
@@ -267,8 +289,7 @@ class TestMakeInputRequirementsFromString:
"""Test that explicitly specifying a domain in the requirement string works correctly."""
load_empty_library()
result = InputStuffSpecsFactory.make_from_string(
- domain_code=domain_code,
- stuff_spec_str=stuff_spec_str,
+ domain_code=domain_code, stuff_spec_str=stuff_spec_str, concept_provider=get_concept_library()
)
assert isinstance(result, StuffSpec)
diff --git a/tests/unit/pipelex/core/pipes/test_inputs_template_toml.py b/tests/unit/pipelex/core/pipes/test_inputs_template_toml.py
index fbbfce48e..705f02af0 100644
--- a/tests/unit/pipelex/core/pipes/test_inputs_template_toml.py
+++ b/tests/unit/pipelex/core/pipes/test_inputs_template_toml.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import tomli
-from pipelex.core.pipes.inputs.input_renderer import serialize_inputs_template_to_toml
+from pipelex.core.pipes.rendering.input_renderer import serialize_inputs_template_to_toml
class TestSerializeInputsTemplateToml:
diff --git a/tests/unit/pipelex/core/pipes/test_pipe_validate_before_run.py b/tests/unit/pipelex/core/pipes/test_pipe_validate_before_run.py
index 3bd49626f..1d6153106 100644
--- a/tests/unit/pipelex/core/pipes/test_pipe_validate_before_run.py
+++ b/tests/unit/pipelex/core/pipes/test_pipe_validate_before_run.py
@@ -10,11 +10,12 @@ import pytest
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.inputs.exceptions import PipeRunInputsError
from pipelex.core.pipes.pipe_factory import PipeFactory
+from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
@pytest.mark.asyncio(loop_scope="class")
@@ -113,7 +114,7 @@ class TestPipeValidateBeforeRun:
# Provide only one input
working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(
- pipeline_inputs={"topic": "Python programming"},
+ pipeline_inputs={"topic": "Python programming"}, concept_provider=get_concept_library()
)
pipe_run_params = PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE)
diff --git a/tests/unit/pipelex/core/pipes/test_run_pipe_tracer_metadata.py b/tests/unit/pipelex/core/pipes/test_run_pipe_tracer_metadata.py
index fb22ac3bb..e95929081 100644
--- a/tests/unit/pipelex/core/pipes/test_run_pipe_tracer_metadata.py
+++ b/tests/unit/pipelex/core/pipes/test_run_pipe_tracer_metadata.py
@@ -14,7 +14,7 @@ from pipelex.core.stuffs.text_content import TextContent
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from tests.unit.pipelex.graph.conftest import make_trace_context
diff --git a/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.py b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.py
index f4343d271..66791af5f 100644
--- a/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.py
+++ b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.py
@@ -3,7 +3,7 @@ import datetime
from kajson import kajson
from pipelex.core.stuffs.date_content import DateContent
-from pipelex.hub import get_class_registry
+from pipelex.runtime_hub import get_class_registry
from tests.unit.pipelex.core.stuffs.date_content.test_data import TestData
diff --git a/tests/unit/pipelex/core/stuffs/test_special_args.py b/tests/unit/pipelex/core/stuffs/test_special_args.py
index 68e67a7ff..9949969b4 100644
--- a/tests/unit/pipelex/core/stuffs/test_special_args.py
+++ b/tests/unit/pipelex/core/stuffs/test_special_args.py
@@ -12,7 +12,7 @@ from pipelex.core.concepts.concept_structure_blueprint import (
ConceptStructureBlueprintFieldType,
)
from pipelex.core.stuffs.stuff_factory import StuffContentFactory, StuffFactory
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
class TestSpecialArgsStuff:
diff --git a/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py b/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
index 871a9c793..b54cee15e 100644
--- a/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
+++ b/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
@@ -5,7 +5,6 @@ from typing import Callable
import pytest
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.page_content import PageContent
@@ -14,8 +13,9 @@ from pipelex.core.stuffs.stuff_artefact import StuffArtefact
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.tools.jinja2.image_registry import ImageRegistry
+from pipelex.tools.templating.text_format import TextFormat
from pipelex.urls import URLs
diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py b/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py
index 0803042e9..89c518d86 100644
--- a/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py
+++ b/tests/unit/pipelex/core/stuffs/test_stuff_factory_combine_stuffs.py
@@ -9,7 +9,7 @@ from pipelex.core.stuffs.exceptions import StuffFactoryError
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_concept_library
+from pipelex.interpreter_hub import get_concept_library
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
if TYPE_CHECKING:
diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py b/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py
index d88b5c4d0..985b0182d 100644
--- a/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py
+++ b/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py
@@ -9,7 +9,8 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_class_registry, get_concept_library
+from pipelex.interpreter_hub import get_concept_library
+from pipelex.runtime_hub import get_class_registry
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
from tests.unit.pipelex.core.stuffs.data import ERROR_TEST_CASES, SEARCH_DOMAIN_TEST_CASES, TEST_CASES, DueDate, UrgencyFlag
@@ -132,9 +133,7 @@ class TestStuffFactoryImplicitMemory:
log.verbose(f"setup_test_concept: {setup_test_concept}")
result = StuffFactory.make_stuff_from_stuff_content_or_data(
- name=stuff_name,
- code=stuff_code,
- stuff_content_or_data=stuff_content_or_data,
+ name=stuff_name, code=stuff_code, stuff_content_or_data=stuff_content_or_data, concept_provider=get_concept_library()
)
pretty_print(result, title=f"Result for test case: {test_name}")
pretty_print(expected_stuff, title=f"Expected stuff for test case: {test_name}")
@@ -169,6 +168,7 @@ class TestStuffFactoryImplicitMemoryWithSearchDomains:
code=stuff_code,
stuff_content_or_data=stuff_content_or_data,
search_domain_codes=search_domain_codes,
+ concept_provider=get_concept_library(),
)
pretty_print(result, title=f"Result for test case: {test_name}")
@@ -207,4 +207,5 @@ class TestStuffFactoryImplicitMemoryErrors:
code=stuff_code,
stuff_content_or_data=stuff_content_or_data,
search_domain_codes=search_domain_codes,
+ concept_provider=get_concept_library(),
)
diff --git a/tests/unit/pipelex/core/test_data/pipes/operators/compose/pipe_compose.py b/tests/unit/pipelex/core/test_data/pipes/operators/compose/pipe_compose.py
index 4230dae80..e64d2eb29 100644
--- a/tests/unit/pipelex/core/test_data/pipes/operators/compose/pipe_compose.py
+++ b/tests/unit/pipelex/core/test_data/pipes/operators/compose/pipe_compose.py
@@ -1,8 +1,8 @@
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.tools.jinja2.template_category import TemplateCategory
PIPE_COMPOSE_WITHOUT_CATEGORY = (
"pipe_compose_without_category",
diff --git a/tests/unit/pipelex/core/test_validation_report.py b/tests/unit/pipelex/core/test_validation_report.py
index e16aff6dc..5f893baf6 100644
--- a/tests/unit/pipelex/core/test_validation_report.py
+++ b/tests/unit/pipelex/core/test_validation_report.py
@@ -16,7 +16,7 @@ import pytest
from pydantic import BaseModel, ValidationError
from pipelex.core.validation import report_validation_error
-from pipelex.hub import PipelexHub
+from pipelex.runtime_hub import RuntimeHub
if TYPE_CHECKING:
from pytest_mock import MockerFixture
@@ -47,7 +47,7 @@ class TestReportValidationError:
"""
# Ensure the hub singleton is None for this test — mirrors a fresh process
# where Pipelex.make hasn't run yet.
- mocker.patch.object(PipelexHub, "_instance", None)
+ mocker.patch.object(RuntimeHub, "_instance", None)
validation_error = _make_validation_error()
report = report_validation_error(category="config", validation_error=validation_error)
@@ -60,8 +60,8 @@ class TestReportValidationError:
get_optional_config() returns None; migration hints are omitted; the error
translation still flows.
"""
- hub_without_config = PipelexHub()
- mocker.patch.object(PipelexHub, "_instance", hub_without_config)
+ hub_without_config = RuntimeHub()
+ mocker.patch.object(RuntimeHub, "_instance", hub_without_config)
validation_error = _make_validation_error()
report = report_validation_error(category="config", validation_error=validation_error)
diff --git a/tests/unit/pipelex/graph/conftest.py b/tests/unit/pipelex/graph/conftest.py
index 993267ef3..82869fe46 100644
--- a/tests/unit/pipelex/graph/conftest.py
+++ b/tests/unit/pipelex/graph/conftest.py
@@ -3,8 +3,9 @@
import pytest
from pipelex.config import get_config
-from pipelex.graph.graph_config import DataInclusionConfig, GraphConfig
-from pipelex.graph.trace_context import TraceContext
+from pipelex.graph.graph_config import GraphConfig
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.trace_context import TraceContext
def make_defaulted_data_inclusion_config(
diff --git a/tests/unit/pipelex/graph/test_graph_tracer_manager.py b/tests/unit/pipelex/graph/test_graph_tracer_manager.py
index 568542bcc..1c17e0b2b 100644
--- a/tests/unit/pipelex/graph/test_graph_tracer_manager.py
+++ b/tests/unit/pipelex/graph/test_graph_tracer_manager.py
@@ -3,9 +3,9 @@
import pytest
from pytest_mock import MockerFixture
-from pipelex.graph.graph_config import DataInclusionConfig
from pipelex.graph.graph_tracer import GraphTracer
from pipelex.graph.graph_tracer_manager import GraphTracerManager
+from pipelex.system.data_inclusion_config import DataInclusionConfig
def _make_data_inclusion() -> DataInclusionConfig:
diff --git a/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py b/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py
index 8c97e9e5f..5b1395e31 100644
--- a/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py
+++ b/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py
@@ -13,8 +13,8 @@ import logging
import pytest
from pytest_mock import MockerFixture
-from pipelex.graph.graph_config import DataInclusionConfig
from pipelex.graph.graph_tracer_manager import GraphTracerManager
+from pipelex.system.data_inclusion_config import DataInclusionConfig
_DATA_INCLUSION_OFF = DataInclusionConfig(
pipe_and_concept_registry=False,
diff --git a/tests/unit/pipelex/graph/test_trace_context_emit_flags.py b/tests/unit/pipelex/graph/test_trace_context_emit_flags.py
index 989fb8bfe..59362d27b 100644
--- a/tests/unit/pipelex/graph/test_trace_context_emit_flags.py
+++ b/tests/unit/pipelex/graph/test_trace_context_emit_flags.py
@@ -5,8 +5,8 @@ Pins that ``emit_graph_events`` / ``emit_usage_events`` default to True (backwar
carried — so a costs-only or graph-only run keeps its gating as nested pipes spawn children.
"""
-from pipelex.graph.graph_config import DataInclusionConfig
-from pipelex.graph.trace_context import TraceContext
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.trace_context import TraceContext
DATA_INCLUSION_OFF = DataInclusionConfig(
pipe_and_concept_registry=False,
diff --git a/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py b/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py
index 4a6d1eab9..a7ec3abf6 100644
--- a/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py
+++ b/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py
@@ -14,7 +14,7 @@ from mthds.package.dependency_resolver import ResolvedDependency
from mthds.package.manifest.schema import MethodsManifest
from pytest_mock import MockerFixture
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.library_factory import LibraryFactory
from pipelex.libraries.library_manager import LibraryManager
from pipelex.libraries.pipe.exceptions import PipeLibraryError
diff --git a/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py b/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py
index 63cbb9c3b..ac62d5c7d 100644
--- a/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py
+++ b/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py
@@ -12,7 +12,7 @@ from mthds.package.dependency_resolver import ResolvedDependency
from mthds.package.manifest.schema import MethodsManifest
from pytest_mock import MockerFixture
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.library_factory import LibraryFactory
from pipelex.libraries.library_manager import LibraryManager
diff --git a/tests/unit/pipelex/libraries/test_library_crate_accumulation.py b/tests/unit/pipelex/libraries/test_library_crate_accumulation.py
index 9af0e00be..1227570c1 100644
--- a/tests/unit/pipelex/libraries/test_library_crate_accumulation.py
+++ b/tests/unit/pipelex/libraries/test_library_crate_accumulation.py
@@ -5,7 +5,7 @@ from typing import cast
import pytest
from pytest_mock import MockerFixture
-from pipelex.hub import clear_current_library, get_library_manager, set_current_library
+from pipelex.interpreter_hub import clear_current_library, get_library_manager, set_current_library
from pipelex.libraries.library import Library
from pipelex.libraries.library_manager import LibraryManager
from tests.unit.pipelex.libraries.test_library_crate_data import BlueprintSamples
diff --git a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
index 105d27a0b..bec6f5a9c 100644
--- a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
+++ b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
@@ -8,7 +8,7 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_concept_library, get_pipe_library
+from pipelex.interpreter_hub import get_concept_library, get_pipe_library
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/data.py b/tests/unit/pipelex/pipe_operators/pipe_compose/data.py
index 56ef984c0..ff93e2958 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_compose/data.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/data.py
@@ -1,8 +1,8 @@
from typing import ClassVar
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.tools.jinja2.template_category import TemplateCategory
class PipeComposeInputTestCases:
diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/test_composer_field_resolutions.py b/tests/unit/pipelex/pipe_operators/pipe_compose/test_composer_field_resolutions.py
index 867327f00..2ca9f15e4 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_compose/test_composer_field_resolutions.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/test_composer_field_resolutions.py
@@ -15,7 +15,7 @@ from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprint, ConstructFieldMethod
from pipelex.pipe_operators.compose.structured_content_composer import StructuredContentComposer
diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py b/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py
index f6d00573c..a71a0ee1b 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py
@@ -16,7 +16,7 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.core.stuffs.text_content import TextContent
-from pipelex.hub import get_native_concept
+from pipelex.interpreter_hub import get_native_concept
from pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprint
from pipelex.pipe_operators.compose.exceptions import StructuredContentComposerValidationError, StructuredContentComposerValueError
from pipelex.pipe_operators.compose.structured_content_composer import StructuredContentComposer
diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py
index 1daf28041..b3c77e0c1 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py
@@ -9,14 +9,14 @@ from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexError
from pipelex.config import get_config
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
-from pipelex.hub import get_library_manager, scoped_current_library, set_current_library
+from pipelex.interpreter_hub import get_library_manager, scoped_current_library, set_current_library
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_operators.func import direct_pipe_func_executor
from pipelex.pipe_operators.func.direct_pipe_func_executor import DirectPipeFuncExecutor
from pipelex.pipe_operators.func.pipe_func_execution_dtos import PipeFuncExecutionRequest
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
# A method whose ONLY custom source is the PipeFunc — its output structure (Greeting) is a concept
# declared in the .mthds, NOT a shipped .py. The box must regenerate `structures.py` from the crate's
diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py
index c4c3b158a..55b295d73 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_execution_transport.py
@@ -17,7 +17,7 @@ from pipelex.pipe_operators.func.pipe_func_execution_transport import (
)
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestPipeFuncExecutionTransport:
diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py
index 875dd8608..722e8d138 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_hosted_mode.py
@@ -11,7 +11,7 @@ from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
_UNREGISTERED = PipeFuncBlueprint(
description="Hosted-mode case: function lives only in the sandbox, never in this process.",
diff --git a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_compose_drops_embedded_image.py b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_compose_drops_embedded_image.py
index 343b4000b..bc02a0ca7 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_compose_drops_embedded_image.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_compose_drops_embedded_image.py
@@ -26,22 +26,22 @@ import pytest
from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.pipe_factory import PipeFactory
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.hub import get_native_concept, get_pipe_router
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose, PipeComposeOutput
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
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_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
# A recognizable token in the reference image URL so we can detect when the image was
# silently degraded into prompt text.
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py
index 13fe198c1..8f7079256 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py
@@ -1,6 +1,6 @@
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.pipe_operators.llm.llm_prompt_blueprint import LLMPromptBlueprint
+from pipelex.tools.jinja2.template_category import TemplateCategory
class TestLLMPromptBlueprintRequiredVariables:
diff --git a/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py b/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py
index 416ae3bd5..2b1619cde 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py
@@ -5,7 +5,7 @@ import pytest
from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_library_manager
+from pipelex.interpreter_hub import get_library_manager
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStructureBlueprint
diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.py
index 4517d0f1f..537472178 100644
--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py
+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py
@@ -24,7 +24,7 @@ from pipelex.pipe_run.delivery_assignment import (
)
from pipelex.pipe_run.delivery_executor import DeliveryExecutor
from pipelex.pipe_run.exceptions import PipeJobError, StorageDeliveryError, WebhookDeliveryError
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.network.exceptions import SsrfBlockedError
@@ -344,7 +344,7 @@ class TestDeliveryExecutor:
async def test_try_local_hydrate_stuff_returns_typed_for_builtin(self) -> None:
from pipelex.core.stuffs.text_content import TextContent # noqa: PLC0415
- from pipelex.hub import get_class_registry # noqa: PLC0415
+ from pipelex.runtime_hub import get_class_registry # noqa: PLC0415
registry = get_class_registry()
if not registry.has_class(name="TextContent"):
diff --git a/tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py b/tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py
index 3b54d593f..a759065f1 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py
@@ -7,7 +7,7 @@ from pipelex.libraries.library_crate import LibraryCrate
from pipelex.pipe_run.exceptions import PipeJobError
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.core.pipes.pipe_abstract import PipeAbstract
diff --git a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py b/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
index 0843f0ce1..f7a94cb97 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
@@ -11,7 +11,7 @@ from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocol
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.core.pipes.pipe_abstract import PipeAbstract
diff --git a/tests/unit/pipelex/pipe_run/test_scoped_pipe_router.py b/tests/unit/pipelex/pipe_run/test_scoped_pipe_router.py
index 792c2d59d..56ad51052 100644
--- a/tests/unit/pipelex/pipe_run/test_scoped_pipe_router.py
+++ b/tests/unit/pipelex/pipe_run/test_scoped_pipe_router.py
@@ -1,11 +1,6 @@
import pytest
-from pipelex.hub import (
- get_pipe_router,
- scoped_pipe_router,
- set_pipe_router,
- teardown_current_pipe_router,
-)
+from pipelex.interpreter_hub import get_pipe_router, scoped_pipe_router, set_pipe_router, teardown_current_pipe_router
from pipelex.pipe_run.pipe_router import PipeRouter
diff --git a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py
index ac9a9179d..4d605103d 100644
--- a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py
+++ b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py
@@ -13,8 +13,8 @@ from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.graph.graphspec import GraphSpecMode
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.tracing_assembly import TracingAssembly, assemble_tracing, assemble_tracing_on_output
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.system.exceptions import MissingDependencyError
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tracing.exceptions import EventLogReadError, EventLogSetupError
from pipelex.tracing.trace_events import UsageReportEvent
diff --git a/tests/unit/pipelex/plugins/openai/test_openai_completions_usage_capture.py b/tests/unit/pipelex/plugins/openai/test_openai_completions_usage_capture.py
index c6fbca167..4b58ef025 100644
--- a/tests/unit/pipelex/plugins/openai/test_openai_completions_usage_capture.py
+++ b/tests/unit/pipelex/plugins/openai/test_openai_completions_usage_capture.py
@@ -20,9 +20,9 @@ from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.plugins.openai.openai_completions_factory import OpenAICompletionsFactory
from pipelex.plugins.openai.openai_completions_llm_worker import OpenAICompletionsLLMWorker
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from typing import Any
diff --git a/tests/unit/pipelex/plugins/openai/test_openai_img_gen_worker_usage_capture.py b/tests/unit/pipelex/plugins/openai/test_openai_img_gen_worker_usage_capture.py
index 8e8a651b8..ed939d6c4 100644
--- a/tests/unit/pipelex/plugins/openai/test_openai_img_gen_worker_usage_capture.py
+++ b/tests/unit/pipelex/plugins/openai/test_openai_img_gen_worker_usage_capture.py
@@ -28,8 +28,8 @@ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.plugins.openai.openai_img_gen_worker import OpenAIImgGenWorker
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.image_utils import ImageFormat
if TYPE_CHECKING:
diff --git a/tests/unit/pipelex/plugins/openai/test_openai_responses_usage_capture.py b/tests/unit/pipelex/plugins/openai/test_openai_responses_usage_capture.py
index 03ddd5f22..f7ac0bf94 100644
--- a/tests/unit/pipelex/plugins/openai/test_openai_responses_usage_capture.py
+++ b/tests/unit/pipelex/plugins/openai/test_openai_responses_usage_capture.py
@@ -19,9 +19,9 @@ from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.plugins.openai.openai_responses_factory import OpenAIResponsesFactory
from pipelex.plugins.openai.openai_responses_llm_worker import OpenAIResponsesLLMWorker
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from typing import Any
diff --git a/tests/unit/pipelex/reporting/test_cost_report_renderer.py b/tests/unit/pipelex/reporting/test_cost_report_renderer.py
index a093a6312..66a89917f 100644
--- a/tests/unit/pipelex/reporting/test_cost_report_renderer.py
+++ b/tests/unit/pipelex/reporting/test_cost_report_renderer.py
@@ -15,8 +15,8 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.reporting.cost_report_renderer import render_run_cost_report
+from pipelex.system.job_metadata import JobMetadata
_RUN_ID = "test-run"
diff --git a/tests/unit/pipelex/reporting/test_emit_runner_fallback.py b/tests/unit/pipelex/reporting/test_emit_runner_fallback.py
index 397255341..4b8313bb0 100644
--- a/tests/unit/pipelex/reporting/test_emit_runner_fallback.py
+++ b/tests/unit/pipelex/reporting/test_emit_runner_fallback.py
@@ -25,12 +25,12 @@ from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.cost_registry import CostRegistry
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
-from pipelex.graph.graph_config import DataInclusionConfig
-from pipelex.graph.trace_context import TraceContext
-from pipelex.pipeline.job_metadata import JobMetadata, UnitJobId
from pipelex.reporting.reporting_manager import ReportingManager
from pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackend
+from pipelex.system.data_inclusion_config import DataInclusionConfig
from pipelex.system.exceptions import MissingDependencyError
+from pipelex.system.job_metadata import JobMetadata, UnitJobId
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing import activity_event_log
from pipelex.tracing.activity_event_log import ActivityEventLogCache
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
diff --git a/tests/unit/pipelex/reporting/test_emit_runner_fallback_non_llm.py b/tests/unit/pipelex/reporting/test_emit_runner_fallback_non_llm.py
index 2af673bba..5cd5550b4 100644
--- a/tests/unit/pipelex/reporting/test_emit_runner_fallback_non_llm.py
+++ b/tests/unit/pipelex/reporting/test_emit_runner_fallback_non_llm.py
@@ -33,11 +33,11 @@ from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.cost_registry import CostRegistry
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
-from pipelex.graph.graph_config import DataInclusionConfig
-from pipelex.graph.trace_context import TraceContext
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.reporting.reporting_manager import ReportingManager
from pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackend
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.trace_context import TraceContext
from pipelex.tools.misc.image_utils import ImageFormat
from pipelex.tracing.activity_event_log import ActivityEventLogCache
from pipelex.tracing.ndjson_event_log import NdjsonEventLog
diff --git a/tests/unit/pipelex/reporting/test_emit_usage_event_gating.py b/tests/unit/pipelex/reporting/test_emit_usage_event_gating.py
index f51758514..2547086a9 100644
--- a/tests/unit/pipelex/reporting/test_emit_usage_event_gating.py
+++ b/tests/unit/pipelex/reporting/test_emit_usage_event_gating.py
@@ -19,11 +19,11 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
-from pipelex.graph.graph_config import DataInclusionConfig
-from pipelex.graph.trace_context import TraceContext
-from pipelex.pipeline.job_metadata import JobMetadata, UnitJobId
from pipelex.reporting.reporting_manager import ReportingManager
from pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackend
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.job_metadata import JobMetadata, UnitJobId
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.activity_event_log import ActivityEventLogCache
from pipelex.tracing.ndjson_event_log import NdjsonEventLog
from pipelex.tracing.trace_events import UsageReportEvent
diff --git a/tests/unit/pipelex/reporting/test_isolated_execution_probe.py b/tests/unit/pipelex/reporting/test_isolated_execution_probe.py
index 2a9943009..0b03b6cbf 100644
--- a/tests/unit/pipelex/reporting/test_isolated_execution_probe.py
+++ b/tests/unit/pipelex/reporting/test_isolated_execution_probe.py
@@ -3,21 +3,21 @@
Detecting whether the current call runs inside an isolated sub-execution (an orchestrator's
worker activity) is an orchestrator concern, not core's. A boot-orchestrator plugin claims
``HubSlot.ISOLATED_EXECUTION_PROBE`` with an ambient predicate; core consults it through
-``PipelexHub.is_in_isolated_execution`` and names no orchestrator.
+``RuntimeHub.is_in_isolated_execution`` and names no orchestrator.
"""
-from pipelex.hub import PipelexHub
+from pipelex.runtime_hub import RuntimeHub
class TestIsolatedExecutionProbe:
def test_default_is_never_isolated(self) -> None:
"""A fresh hub (no boot-orchestrator claim) reports the in-process default: never isolated."""
- hub = PipelexHub()
+ hub = RuntimeHub()
assert hub.is_in_isolated_execution() is False
def test_claimed_probe_is_honored_and_consulted_each_call(self) -> None:
"""A claimed probe replaces the default and is ambient — consulted on every call, not cached."""
- hub = PipelexHub()
+ hub = RuntimeHub()
flag = {"isolated": True}
hub.set_isolated_execution_probe(lambda: flag["isolated"])
assert hub.is_in_isolated_execution() is True
diff --git a/tests/unit/pipelex/reporting/test_render_cost_report_for_output.py b/tests/unit/pipelex/reporting/test_render_cost_report_for_output.py
index 5ddec0b03..b6eecd7aa 100644
--- a/tests/unit/pipelex/reporting/test_render_cost_report_for_output.py
+++ b/tests/unit/pipelex/reporting/test_render_cost_report_for_output.py
@@ -13,8 +13,8 @@ from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
from pipelex.core.pipes.pipe_output import PipeOutput
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.reporting.cost_report_renderer import render_cost_report_for_output
+from pipelex.system.job_metadata import JobMetadata
_RUN_ID = "output-helper-run"
diff --git a/tests/unit/pipelex/reporting/test_reporting_event_emission.py b/tests/unit/pipelex/reporting/test_reporting_event_emission.py
index e40ad5985..cad0f0b02 100644
--- a/tests/unit/pipelex/reporting/test_reporting_event_emission.py
+++ b/tests/unit/pipelex/reporting/test_reporting_event_emission.py
@@ -18,10 +18,10 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.config import get_config
-from pipelex.graph.graph_config import DataInclusionConfig
-from pipelex.graph.trace_context import TraceContext
-from pipelex.pipeline.job_metadata import JobMetadata, UnitJobId
from pipelex.reporting.reporting_manager import ReportingManager
+from pipelex.system.data_inclusion_config import DataInclusionConfig
+from pipelex.system.job_metadata import JobMetadata, UnitJobId
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
from pipelex.tracing.trace_events import UsageReportEvent
diff --git a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py
index d79bd1117..9ef82fa87 100644
--- a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py
+++ b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py
@@ -14,12 +14,12 @@ from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.text_content import TextContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
-from pipelex.hub import get_class_registry
from pipelex.pipe_run.exceptions import PipeJobError
from pipelex.runtime_bridge.primitives.hydration import (
_hydrate_list_item, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
hydrate_working_memory,
)
+from pipelex.runtime_hub import get_class_registry
def _make_text_concept() -> Concept:
diff --git a/tests/unit/pipelex/runtime_bridge/test_direct_orchestrator.py b/tests/unit/pipelex/runtime_bridge/test_direct_orchestrator.py
index 75e84b9a5..5f7a50072 100644
--- a/tests/unit/pipelex/runtime_bridge/test_direct_orchestrator.py
+++ b/tests/unit/pipelex/runtime_bridge/test_direct_orchestrator.py
@@ -4,9 +4,9 @@ import pytest
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.runtime_bridge.direct_orchestrator import DirectOrchestrator
from pipelex.runtime_bridge.exceptions import PipelexBridgeDispatchError
+from pipelex.system.job_metadata import JobMetadata
if TYPE_CHECKING:
from pipelex.core.pipes.pipe_abstract import PipeAbstract
diff --git a/tests/unit/pipelex/pipeline/test_job_metadata_request_id.py b/tests/unit/pipelex/system/test_job_metadata_request_id.py
similarity index 98%
rename from tests/unit/pipelex/pipeline/test_job_metadata_request_id.py
rename to tests/unit/pipelex/system/test_job_metadata_request_id.py
index 514deb1de..a76264caf 100644
--- a/tests/unit/pipelex/pipeline/test_job_metadata_request_id.py
+++ b/tests/unit/pipelex/system/test_job_metadata_request_id.py
@@ -5,7 +5,7 @@ that rides the workflow input across the Temporal serialization boundary.
import pytest
from pydantic import ValidationError
-from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.system.job_metadata import JobMetadata
class TestJobMetadataRequestId:
diff --git a/tests/unit/pipelex/test_hub_class_registry.py b/tests/unit/pipelex/test_class_registry_scoping.py
similarity index 95%
rename from tests/unit/pipelex/test_hub_class_registry.py
rename to tests/unit/pipelex/test_class_registry_scoping.py
index b8bd8a805..89c79c3a1 100644
--- a/tests/unit/pipelex/test_hub_class_registry.py
+++ b/tests/unit/pipelex/test_class_registry_scoping.py
@@ -2,13 +2,9 @@ from kajson.class_registry import ClassRegistry
from kajson.kajson_manager import KajsonManager
from pydantic import BaseModel
-from pipelex.hub import (
- clear_current_library,
- get_class_registry,
- get_library_manager,
- set_current_library,
-)
+from pipelex.interpreter_hub import clear_current_library, get_library_manager, set_current_library
from pipelex.libraries.library_factory import LibraryFactory
+from pipelex.runtime_hub import get_class_registry
class ScopedModel(BaseModel):
diff --git a/tests/unit/pipelex/test_config_pre_boot.py b/tests/unit/pipelex/test_config_pre_boot.py
index 28d8d833b..62aad4104 100644
--- a/tests/unit/pipelex/test_config_pre_boot.py
+++ b/tests/unit/pipelex/test_config_pre_boot.py
@@ -1,20 +1,20 @@
from pytest_mock import MockerFixture
from pipelex.config import get_pipe_func_execution_mode, is_pipe_func_sandbox_hosted
-from pipelex.hub import PipelexHub, get_optional_config
from pipelex.plugins.pipe_func_executor_registry import DIRECT_PIPE_FUNC_EXECUTION_MODE
+from pipelex.runtime_hub import RuntimeHub, get_optional_config
class TestConfigPreBoot:
"""The optional config accessors honor their non-raising contract before any hub exists."""
def test_get_optional_config_returns_none_without_hub(self, mocker: MockerFixture):
- """With no PipelexHub instance at all, the optional getter returns None instead of raising."""
- mocker.patch.object(PipelexHub, "_instance", None)
+ """With no RuntimeHub instance at all, the optional getter returns None instead of raising."""
+ mocker.patch.object(RuntimeHub, "_instance", None)
assert get_optional_config() is None
def test_pipe_func_execution_mode_defaults_to_direct_without_hub(self, mocker: MockerFixture):
"""Pre-boot PipeFunc validation must default to direct, not crash on the missing hub."""
- mocker.patch.object(PipelexHub, "_instance", None)
+ mocker.patch.object(RuntimeHub, "_instance", None)
assert get_pipe_func_execution_mode() == DIRECT_PIPE_FUNC_EXECUTION_MODE
assert is_pipe_func_sandbox_hosted() is False
diff --git a/tests/unit/pipelex/test_hub_lifecycle.py b/tests/unit/pipelex/test_hub_lifecycle.py
new file mode 100644
index 000000000..16b688018
--- /dev/null
+++ b/tests/unit/pipelex/test_hub_lifecycle.py
@@ -0,0 +1,131 @@
+"""The two hubs are installed and released together.
+
+Splitting one god-object into two singletons introduces a lifecycle risk the single hub did not
+have: a boot or a teardown that touches one half and forgets the other leaves a half-reset process,
+which surfaces as cross-test pollution rather than a clean failure. These tests pin both ends —
+that a boot installs both singletons, and that the reset ``Pipelex.teardown`` performs really does
+release the class-registry scoping the InterpreterHub installed.
+"""
+
+from kajson.class_registry import ClassRegistry
+from kajson.kajson_manager import KajsonManager
+from pydantic import BaseModel
+
+from pipelex.interpreter_hub import (
+ InterpreterHub,
+ clear_current_library,
+ get_current_library_id_or_none,
+ get_interpreter_hub,
+ get_library_manager,
+ set_current_library,
+ set_interpreter_hub,
+)
+from pipelex.pipelex import Pipelex
+from pipelex.runtime_hub import RuntimeHub, get_class_registry
+from pipelex.system.registries.class_registry_access import class_registry_scoping
+from pipelex.system.runtime import IntegrationMode, runtime_manager
+
+
+class LifecycleScopedModel(BaseModel):
+ lifecycle_field: str
+
+
+def _test_integration_mode() -> IntegrationMode:
+ """The boot mode the session conftest uses, so a re-boot here matches the one it replaces."""
+ return IntegrationMode.CI if runtime_manager.is_ci_testing else IntegrationMode.PYTEST
+
+
+class TestHubLifecycle:
+ def test_boot_installs_both_hub_singletons(self) -> None:
+ """A booted Pipelex owns both hubs and has installed each as its process singleton."""
+ pipelex = Pipelex.get_instance()
+
+ assert RuntimeHub.get_optional_instance() is pipelex.runtime_hub
+ assert InterpreterHub.get_optional_instance() is pipelex.interpreter_hub
+
+ def test_installing_the_interpreter_hub_installs_the_class_registry_scoping(self) -> None:
+ """Library scoping is live exactly because a InterpreterHub was installed (the D5 resolver)."""
+ library_manager = get_library_manager()
+ library_id, library = library_manager.open_library()
+ scoped_registry = ClassRegistry()
+ scoped_registry.register_class(LifecycleScopedModel)
+ library.set_class_registry(scoped_registry)
+
+ set_current_library(library_id=library_id)
+ try:
+ assert get_class_registry() is scoped_registry
+ finally:
+ clear_current_library()
+ library_manager.teardown(library_id=library_id)
+
+ def test_reset_releases_the_class_registry_scoping(self) -> None:
+ """The reset primitive drops scoping, so a torn-down manager is unreachable.
+
+ Without it, a still-pinned library_id would keep routing ``get_class_registry`` through a
+ library manager whose libraries have been released. This pins ``reset()``'s own semantics;
+ that ``Pipelex.teardown`` actually calls it is pinned by the last test in this class.
+ """
+ library_manager = get_library_manager()
+ library_id, library = library_manager.open_library()
+ scoped_registry = ClassRegistry()
+ scoped_registry.register_class(LifecycleScopedModel)
+ library.set_class_registry(scoped_registry)
+
+ set_current_library(library_id=library_id)
+ try:
+ assert get_class_registry() is scoped_registry
+
+ class_registry_scoping.reset() # what Pipelex.teardown does
+
+ assert get_class_registry() is KajsonManager.get_class_registry()
+ finally:
+ # Re-install the resolver exactly as a fresh boot would, so this test leaves no
+ # unscoped hub behind for the rest of the worker's session.
+ set_interpreter_hub(get_interpreter_hub())
+ clear_current_library()
+ library_manager.teardown(library_id=library_id)
+
+ assert get_class_registry() is KajsonManager.get_class_registry()
+
+ def test_the_real_teardown_releases_scoping_and_a_fresh_boot_reinstalls_it(self) -> None:
+ """The production ``Pipelex.teardown`` path, not a stand-in for it — and the boot that follows.
+
+ The sibling test above calls ``class_registry_scoping.reset()`` directly, which pins the
+ primitive but nothing about the wiring: delete the ``reset()`` line from ``Pipelex.teardown``
+ and every other test still passes, because a stale ``_library_id`` resolves to ``None`` and
+ falls back to the global registry rather than raising. This test is the one that notices, and
+ it also pins the other half — that a fresh boot re-installs the resolver rather than leaving
+ the process permanently unscoped.
+
+ Runs last in this class: it tears the process singleton down and rebuilds it, so it must not
+ run ahead of the tests that read the booted instance.
+ """
+ library_manager = get_library_manager()
+ library_id, library = library_manager.open_library()
+ scoped_registry = ClassRegistry()
+ scoped_registry.register_class(LifecycleScopedModel)
+ library.set_class_registry(scoped_registry)
+ set_current_library(library_id=library_id)
+ assert get_class_registry() is scoped_registry
+
+ Pipelex.teardown_if_needed()
+
+ # Teardown does not clear the contextvar, so the library stays pinned — releasing the
+ # resolver is the whole of what makes the torn-down library unreachable through it.
+ assert get_current_library_id_or_none() == library_id
+ assert get_class_registry() is KajsonManager.get_class_registry()
+
+ clear_current_library()
+ Pipelex.make(integration_mode=_test_integration_mode())
+
+ fresh_manager = get_library_manager()
+ fresh_library_id, fresh_library = fresh_manager.open_library()
+ fresh_registry = ClassRegistry()
+ fresh_registry.register_class(LifecycleScopedModel)
+ fresh_library.set_class_registry(fresh_registry)
+ set_current_library(library_id=fresh_library_id)
+ try:
+ assert get_class_registry() is fresh_registry
+ finally:
+ clear_current_library()
+ fresh_manager.teardown(library_id=fresh_library_id)
diff --git a/tests/unit/pipelex/test_runtime_layer_import_closure.py b/tests/unit/pipelex/test_runtime_layer_import_closure.py
new file mode 100644
index 000000000..03f176e48
--- /dev/null
+++ b/tests/unit/pipelex/test_runtime_layer_import_closure.py
@@ -0,0 +1,149 @@
+"""Importing the Pipelex runtime loads zero interpreter modules — the property, not the rule.
+
+`pipelex-dev check-hub-layering` guards the *rule* (no runtime-layer module imports `pipelex.interpreter_hub`).
+This guards the *property* the rule exists to buy: importing the inference layer, or the runtime hub
+itself, must pull in zero interpreter modules. The distinction matters because a stray import somewhere
+else entirely — a runtime-layer module reaching into `pipe_operators` directly, without touching a hub —
+would break the property while the lint stays green.
+
+"Interpreter module" is spelled out twice below, because the five interpreter top-level packages alone
+under-state it: core's Pipe-machinery modules are interpreter-layer too, and most of them only get
+caught *transitively*, through the `pipe_operators` / `libraries` they happen to pull in.
+`core.pipes.pipe_blueprint` pulls in none of it, so a runtime-layer import of it would pass a
+package-only predicate. Naming them makes the predicate state the boundary instead of approximating it.
+
+Two documented interpreter homes are deliberately absent, and their absence is a known wart rather than
+an oversight: `pipeline` and `pipe_run` (plus `core.bundles.exceptions`) already leak leaf models into
+every runtime closure — `SpecialPipelineId`, `PipeRunMode`, the bundle validation-error data. Naming
+them here would fail the test over a *placement* problem, not a broken hub arrow. See
+`wip/pr-1062-review-notes.md`.
+
+Run in a subprocess so the closure is exactly what the entry point pulls in: an in-process
+`sys.modules` check would see everything the test session already imported.
+"""
+
+from __future__ import annotations
+
+import subprocess # noqa: S404
+import sys
+import textwrap
+
+import pytest
+
+#: Entry points that must never load the interpreter: the inference layer, the runtime hub itself, and the
+#: heaviest module of each runtime-layer `core/` package — the ones that historically reached for a library
+#: and now take a `ConceptProviderAbstract` instead. `core/`'s Pipe-touching remainder is deliberately
+#: absent; it names the interpreter's own object and belongs to the interpreter layer by construction (see
+#: the guard's `RUNTIME_LAYER_PACKAGES` note).
+RUNTIME_LAYER_ENTRY_POINTS = [
+ "pipelex.cogt.content_generation.content_generator",
+ "pipelex.runtime_hub",
+ "pipelex.core.concepts.structure_generation.generator",
+ "pipelex.core.memory.input_shaper",
+ "pipelex.core.memory.working_memory_factory",
+ "pipelex.core.pipes.inputs.input_stuff_specs_factory",
+ "pipelex.core.pipes.stuff_spec.stuff_spec_factory",
+ "pipelex.core.stuffs.stuff_factory",
+]
+
+#: The negative control, and the reason it is needed: the detector below is a `textwrap.dedent`
+#: string, so nothing type-checks or lints the names inside it. A typo in `INTERPRETER_PACKAGES` or
+#: `is_interpreter` would make every entry point above pass *vacuously*, forever, and the suite would
+#: stay green while guarding nothing. This entry point is dirty by definition — the interpreter hub
+#: is the interpreter — so it must come back a failure, *reported as offending modules*, whatever
+#: else changes. Asserting the offender message and not merely the exit code is what pins the
+#: predicate: the `sys.modules` check below would exit 1 for this entry point either way.
+DIRTY_ENTRY_POINT = "pipelex.interpreter_hub"
+
+#: Wall-clock bound on one closure subprocess. Each case spawns a fresh interpreter importing heavy
+#: modules; without a bound, a deadlock presents as a hung suite rather than a failure, which this
+#: repo has a documented history of (`docs/agents/debugging-hanging-pytest-runs.md`).
+SUBPROCESS_TIMEOUT_SECONDS = 300
+
+_CLOSURE_SCRIPT = textwrap.dedent(
+ """
+ import importlib
+ import sys
+
+ target = sys.argv[1]
+ importlib.import_module(target)
+
+ INTERPRETER_PACKAGES = ("libraries", "pipe_operators", "pipe_controllers", "codegen", "builder")
+
+ # Core's Pipe machinery: interpreter-layer by construction, but not under a top-level package of its own.
+ INTERPRETER_CORE = (
+ "pipelex.core.bundles",
+ "pipelex.core.interpreter",
+ "pipelex.core.registry_models",
+ "pipelex.core.pipes.pipe_abstract",
+ "pipelex.core.pipes.pipe_blueprint",
+ "pipelex.core.pipes.pipe_factory",
+ "pipelex.core.pipes.rendering",
+ )
+ # The one straddler: structured bundle validation-error data that `pipeline/` imports, so it lands in
+ # every runtime closure -- dragging the empty `core.bundles` package placeholder in with it. A placement
+ # wart, not a hub violation -- see wip/pr-1062-review-notes.md. Matched exactly, never as a prefix, so
+ # the rest of `core.bundles` stays flagged.
+ INTERPRETER_CORE_EXCLUDED = ("pipelex.core.bundles", "pipelex.core.bundles.exceptions")
+
+ def is_interpreter(name):
+ if name.split(".")[1] in INTERPRETER_PACKAGES:
+ return True
+ if name in INTERPRETER_CORE_EXCLUDED:
+ return False
+ return any(name == module or name.startswith(module + ".") for module in INTERPRETER_CORE)
+
+ offenders = sorted(name for name in sys.modules if name.startswith("pipelex.") and is_interpreter(name))
+ if offenders:
+ print(f"{target} loaded {len(offenders)} interpreter module(s): {offenders}")
+ raise SystemExit(1)
+
+ # The interpreter hub must not be reachable from the runtime layer at all — the forbidden arrow, measured.
+ if "pipelex.interpreter_hub" in sys.modules:
+ print(f"{target} loaded pipelex.interpreter_hub")
+ raise SystemExit(1)
+
+ print("closure OK")
+ """
+)
+
+
+def _run_closure(*, entry_point: str) -> subprocess.CompletedProcess[str]:
+ """Import one entry point in a fresh interpreter and return the detector's verdict."""
+ try:
+ return subprocess.run( # noqa: S603
+ [sys.executable, "-c", _CLOSURE_SCRIPT, entry_point],
+ capture_output=True,
+ text=True,
+ check=False,
+ timeout=SUBPROCESS_TIMEOUT_SECONDS,
+ )
+ except subprocess.TimeoutExpired as exc:
+ message = f"the closure subprocess for {entry_point} did not finish within {SUBPROCESS_TIMEOUT_SECONDS}s"
+ raise AssertionError(message) from exc
+
+
+class TestHubImportClosure:
+ @pytest.mark.parametrize(
+ ("entry_point", "expected_returncode"),
+ [
+ *((entry_point, 0) for entry_point in RUNTIME_LAYER_ENTRY_POINTS),
+ # The negative control: same detector, opposite verdict. See DIRTY_ENTRY_POINT above.
+ (DIRTY_ENTRY_POINT, 1),
+ ],
+ )
+ def test_closure_verdict_for_entry_point(self, entry_point: str, expected_returncode: int) -> None:
+ result = _run_closure(entry_point=entry_point)
+ assert result.returncode == expected_returncode, (
+ f"unexpected hub import-closure verdict for {entry_point} (wanted exit {expected_returncode}).\n"
+ "Exit 0 means the entry point loaded no interpreter module; exit 1 means the detector found one. "
+ "A runtime-layer entry point failing is a real breach — see docs/contribute/hub-layering.md for how "
+ "to find the shortest import path to an offender. The dirty entry point passing instead means the "
+ "detector has stopped detecting, and every other case above is now vacuous.\n"
+ f"stdout={result.stdout}\nstderr={result.stderr}"
+ )
+ if expected_returncode == 0:
+ assert "closure OK" in result.stdout
+ else:
+ assert "closure OK" not in result.stdout
+ assert "interpreter module(s)" in result.stdout
diff --git a/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py b/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py
index 2bfaecbd9..b3edc6320 100644
--- a/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py
+++ b/tests/unit/pipelex/tools/misc/test_reject_bare_str_or_path.py
@@ -8,7 +8,7 @@ from pathlib import Path
import pytest
-from pipelex.hub import resolve_library_dirs
+from pipelex.interpreter_hub import resolve_library_dirs
from pipelex.tools.misc.file_utils import reject_bare_str_or_path
from pipelex.tools.misc.toml_utils import load_toml_from_path_and_merge_with_overrides
diff --git a/tests/unit/pipelex/tools/test_jinja2.py b/tests/unit/pipelex/tools/test_jinja2.py
index 45706b219..5dacb7e04 100644
--- a/tests/unit/pipelex/tools/test_jinja2.py
+++ b/tests/unit/pipelex/tools/test_jinja2.py
@@ -3,10 +3,10 @@ from typing import Any
import pytest
from pipelex import log, pretty_print
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
from tests.cases import Fruit, JINJA2TestCases
PLACE_HOLDER = "place_holder"
diff --git a/tests/unit/pipelex/tools/test_jinja2_environment.py b/tests/unit/pipelex/tools/test_jinja2_environment.py
index 1056f55ab..1afc2cab5 100644
--- a/tests/unit/pipelex/tools/test_jinja2_environment.py
+++ b/tests/unit/pipelex/tools/test_jinja2_environment.py
@@ -6,11 +6,11 @@ silent corruption (coroutine objects rendered as strings instead of actual conte
import pytest
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_loader
from pipelex.tools.jinja2.jinja2_filters import tag as async_tag_filter
from pipelex.tools.jinja2.jinja2_filters import text_format as async_text_format_filter
from pipelex.tools.jinja2.jinja2_models import Jinja2FilterName
+from pipelex.tools.jinja2.template_category import TemplateCategory
CATEGORIES_WITH_ASYNC_FILTERS = [
TemplateCategory.BASIC,
diff --git a/tests/unit/pipelex/tools/test_jinja2_optional_guards.py b/tests/unit/pipelex/tools/test_jinja2_optional_guards.py
index cc46df286..ef79a66e4 100644
--- a/tests/unit/pipelex/tools/test_jinja2_optional_guards.py
+++ b/tests/unit/pipelex/tools/test_jinja2_optional_guards.py
@@ -6,8 +6,8 @@ walker reports each unguarded reference so validation can name the precise fix.
import pytest
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.jinja2_optional_guards import detect_unguarded_optional_references
+from pipelex.tools.jinja2.template_category import TemplateCategory
class TestDetectUnguardedOptionalReferences:
diff --git a/tests/unit/pipelex/tools/test_jinja2_required_variables.py b/tests/unit/pipelex/tools/test_jinja2_required_variables.py
index 794100aaa..3f1375f31 100644
--- a/tests/unit/pipelex/tools/test_jinja2_required_variables.py
+++ b/tests/unit/pipelex/tools/test_jinja2_required_variables.py
@@ -2,12 +2,12 @@ from typing import ClassVar
import pytest
-from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import (
detect_jinja2_required_variables,
detect_jinja2_variable_references,
)
+from pipelex.tools.jinja2.template_category import TemplateCategory
class TestData:
diff --git a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
index c4fee3b51..ea694b729 100644
--- a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
+++ b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
@@ -9,11 +9,11 @@ import pytest
from jinja2.runtime import Context, Undefined
from pytest_mock import MockerFixture
-from pipelex.cogt.templating.templating_style import TagStyle
from pipelex.tools.jinja2.exceptions import Jinja2ContextError
from pipelex.tools.jinja2.jinja2_filters import apply_tag_style, tag
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
from pipelex.tools.jinja2.tag_renderable import TagRenderable
+from pipelex.tools.templating.templating_style import TagStyle
@pytest.mark.asyncio(loop_scope="class")
diff --git a/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py b/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py
index 1b7751b91..98a282c06 100644
--- a/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py
+++ b/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py
@@ -10,7 +10,6 @@ import pytest
from jinja2.runtime import Context, Undefined
from pytest_mock import MockerFixture, MockType
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.tools.jinja2.exceptions import Jinja2ContextError
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
@@ -18,6 +17,7 @@ from pipelex.tools.jinja2.jinja2_with_images_filter import (
_render_sequence_with_images, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
with_images,
)
+from pipelex.tools.templating.text_format import TextFormat
class TestWithImagesFilterValidation:
diff --git a/tests/unit/pipelex/tools/test_template_content_rendering.py b/tests/unit/pipelex/tools/test_template_content_rendering.py
index 368374cc5..8b2f7c6a2 100644
--- a/tests/unit/pipelex/tools/test_template_content_rendering.py
+++ b/tests/unit/pipelex/tools/test_template_content_rendering.py
@@ -7,15 +7,15 @@ object representations like 'StuffArtefact(name)'.
import pytest
-from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.templating_style import TagStyle, TemplatingStyle
-from pipelex.cogt.templating.text_format import TextFormat
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_artefact import StuffArtefact
from pipelex.core.stuffs.text_content import TextContent
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
def _make_text_stuff(text: str, name: str = "test_text") -> Stuff:
diff --git a/tests/unit/pipelex/tracing/test_assembler_equivalence.py b/tests/unit/pipelex/tracing/test_assembler_equivalence.py
index 9228696f8..6875ae24a 100644
--- a/tests/unit/pipelex/tracing/test_assembler_equivalence.py
+++ b/tests/unit/pipelex/tracing/test_assembler_equivalence.py
@@ -16,7 +16,7 @@ import pytest
from pipelex.graph.graph_tracer import GraphTracer
from pipelex.graph.graphspec import EdgeKind, EdgeSpec, GraphSpec, IOSpec, NodeKind, NodeSpec
-from pipelex.graph.trace_context import TraceContext
+from pipelex.system.trace_context import TraceContext
from pipelex.tracing.graphspec_assembler import GraphSpecAssembler
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
from tests.unit.pipelex.graph.conftest import make_defaulted_data_inclusion_config
diff --git a/tests/unit/pipelex/tracing/test_non_llm_usage_aggregation.py b/tests/unit/pipelex/tracing/test_non_llm_usage_aggregation.py
index 770d078be..093b75921 100644
--- a/tests/unit/pipelex/tracing/test_non_llm_usage_aggregation.py
+++ b/tests/unit/pipelex/tracing/test_non_llm_usage_aggregation.py
@@ -19,8 +19,8 @@ from pipelex.cogt.search.search_report import SearchTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.cost_registry import CostRegistry
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.reporting.reporting_types import AnyTokensUsage
+from pipelex.system.job_metadata import JobMetadata
from pipelex.tracing.trace_events import UsageReportEvent
from pipelex.tracing.usage_aggregator import UsageAggregator
diff --git a/tests/unit/pipelex/tracing/test_scoped_event_log.py b/tests/unit/pipelex/tracing/test_scoped_event_log.py
index 39b3ffa6d..f2e3ed813 100644
--- a/tests/unit/pipelex/tracing/test_scoped_event_log.py
+++ b/tests/unit/pipelex/tracing/test_scoped_event_log.py
@@ -1,4 +1,4 @@
-"""Unit tests for the `scoped_event_log` ContextVar scope in `pipelex.hub`.
+"""Unit tests for the `scoped_event_log` ContextVar scope in `pipelex.runtime_hub`.
The scope lets a caller pin a specific `EventLogProtocol` instance for the duration
of a run so the write side (tracer emission) and the read side (tracing assembly)
@@ -10,7 +10,7 @@ import asyncio
import pytest
-from pipelex.hub import get_event_log_override, scoped_event_log
+from pipelex.runtime_hub import get_event_log_override, scoped_event_log
from pipelex.tracing.event_log_protocol import EventLogProtocol
from pipelex.tracing.in_memory_event_log import InMemoryEventLog
diff --git a/tests/unit/pipelex/tracing/test_trace_events.py b/tests/unit/pipelex/tracing/test_trace_events.py
index 34644258a..0452ae74c 100644
--- a/tests/unit/pipelex/tracing/test_trace_events.py
+++ b/tests/unit/pipelex/tracing/test_trace_events.py
@@ -10,7 +10,7 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.graph.graphspec import EdgeKind, ErrorSpec, IOSpec, NodeKind
-from pipelex.pipeline.job_metadata import JobCategory, JobMetadata, UnitJobId
+from pipelex.system.job_metadata import JobCategory, JobMetadata, UnitJobId
from pipelex.tracing.trace_events import (
AnyTraceEvent,
BatchAggregateEvent,
diff --git a/tests/unit/pipelex/tracing/test_usage_aggregator.py b/tests/unit/pipelex/tracing/test_usage_aggregator.py
index 603bfdab0..15d1ff17c 100644
--- a/tests/unit/pipelex/tracing/test_usage_aggregator.py
+++ b/tests/unit/pipelex/tracing/test_usage_aggregator.py
@@ -7,7 +7,7 @@ from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
from pipelex.graph.graphspec import NodeKind
-from pipelex.pipeline.job_metadata import JobCategory, JobMetadata, UnitJobId
+from pipelex.system.job_metadata import JobCategory, JobMetadata, UnitJobId
from pipelex.tracing.trace_events import PipeStartEvent, TraceEvent, UsageReportEvent
from pipelex.tracing.usage_aggregator import UsageAggregator
diff --git a/wip/drift-contracts/dogfood-log.md b/wip/drift-contracts/dogfood-log.md
index b2fee5956..8093c7d0b 100644
--- a/wip/drift-contracts/dogfood-log.md
+++ b/wip/drift-contracts/dogfood-log.md
@@ -6,3 +6,14 @@ One entry per ack. Verdicts: **real-catch** (the review found actual staleness),
- **2026-07-10 · cli-docs · clean-pass** — the keyword-only sweep touched many pipelex/cli files (kwonly'd internal signatures, two escape hatches, call-site keywords); reviewed docs/tools/cli/ and the agent-CLI CLAUDE.md — no command, flag, or output changed, both targets stay accurate.
- **2026-07-11 · config-docs · clean-pass** — opened by dev's Python-3.10 drop reaching the branch via the Phase-M merge (StrEnum import swap in `img_gen_job_components.py`); reviewed docs/configuration/ — no config field, default, or documented behavior changed. *(Backfilled 2026-07-12: the ack was recorded during the subject-grants regrind without its mandatory log entry — process slip, not a review slip.)*
- **2026-07-16 · config-docs · clean-pass** — opened by the pipe_func config wiring in `configs.py` (PipeFuncConfig import + `pipe_func_config` field on the Pipelex model) plus comment-only wording fixes in `pipelex.toml` + `pipe_func_config.py` (dropped the stale core-`local_sandbox` mode claim, "our Daytona plugin" naming); reviewed docs/configuration/ — no default or documented behavior changed, pipe_func_config deliberately has no page, and the stale mode was never documented there. Note: the trigger correctly caught a *comment* fix in the shipped defaults file, which is user-readable surface — not friction. *(Amended 2026-07-17: the ack rationale originally described the trigger diff as comment-only, omitting the `configs.py` field wiring — caught by a PR-review bot on #1052; review conclusion unchanged.)*
+- **2026-07-26 · config-docs · friction** — opened by the `pipelex.hub` → `pipelex.runtime_hub` split, which rewrote one import line in `config_check.py` and `aws_config.py`. Neither file's *configuration surface* moved at all — no model field, default, or TOML key — so no `docs/configuration/` page could have gone stale. Narrowing that would have prevented it: the trigger set matches whole files under the config packages, so any edit to them (including a pure import-path swap) opens the contract; scoping the trigger to the files that actually define settings (`configs.py`, `*_config.py`, `pipelex.toml`, the shipped `.pipelex/` defaults) and dropping incidental members like `config_check.py` / `aws_config.py` would keep the real coupling and drop this class of opening.
+- **2026-07-26 · cli-docs · clean-pass** — the same split rewrote import lines across 28 `pipelex/cli/**` files plus an internal `PipelexHub` → `RuntimeHub` rename inside doctor's private setup helper. Reviewed `docs/tools/cli/` and `pipelex/cli/agent_cli/CLAUDE.md`: no command, flag, help text, output string, or exit code changed, and neither target mentions the hub. Logged as clean-pass rather than friction on purpose — a 28-file sweep across the CLI package is exactly the shape that *could* have moved the surface, so the contract opening was proportionate even though the verdict was "nothing stale". This is the second consecutive clean-pass for cli-docs on a mechanical sweep (cf. 2026-07-10); a third would be worth weighing against narrowing.
+- **2026-07-26 · keyword-only-convention · friction** — opened by the hub split renaming two *docstring* mentions of `pipelex.hub` inside `keyword_only_guard.py`; no guard behavior, violation kind, registry schema, or flag changed, and the convention doc refers to the presentation layer only generically ("Typer/hub import"). Worth noting what the contract did *not* fire on: the same change re-recorded all 54 `pipelex/hub.py` grants under the two new modules — a 55-entry registry rewrite — because `subject_grants.toml` is not a trigger, and correctly so (a grant migration is data, not convention). Narrowing that would have prevented this opening: the trigger matches the whole guard module, so a comment-only edit opens it; restricting the digest to the guard's *code* (ignoring docstrings/comments) — or accepting that this module is small enough that prose edits are rare — is the tradeoff to weigh.
+- **2026-07-26 · config-docs · clean-pass** — opened by H-4/H-3 landing: `configs.py` swapped its `TemplatingStyle` import from `pipelex.cogt.templating` to `pipelex.tools.templating` (the Phase 3 placement fix), one line, every other trigger file byte-identical. Reviewed `docs/configuration/` — no page documents an import path, every Python path the docs do cite still resolves, and the `pipe_func` example is untouched by the Phase 4 `concept_provider` injection. Logged clean-pass, not friction, on purpose: `configs.py` is the module that *defines* every setting, so an edit there is the shape that genuinely could move the documented surface. Worth recording against the narrowing proposed in the entry above — scoping the trigger to "files that actually define settings" would **not** have prevented this opening, because `configs.py` is squarely inside that narrowed set. File-level triggers cannot distinguish an import swap from a field change; only a content-aware digest could.
+- **2026-07-26 · cli-docs · clean-pass** — opened by the Phase 4 renderer regroup: 10 CLI command-core files, each changed by exactly one import line (`core.pipes.inputs.input_renderer` / `core.pipes.output.output_renderer` → `core.pipes.rendering.*`). Reviewed both targets and verified the documented surface against the *live* CLI (`pipelex build inputs pipe`, `pipelex build output pipe`, `pipelex-agent inputs pipe`) rather than by reading alone: arguments, flags, format values and defaults all match `docs/tools/cli/`; `agent_cli/CLAUDE.md`'s layout map lists only `agent_cli`'s own modules, none of which moved. Also checked the behavior-adjacent half of Phase 4 — no CLI doc cites a Python import path or calls a factory that gained a required `concept_provider`, and the runner codegen emits none. **This is the third consecutive clean-pass for cli-docs on a mechanical sweep** (cf. 2026-07-10, 2026-07-26), which the previous entry said would be worth weighing. Weighed: the shape of these three openings is not "CLI files changed" but "a repo-wide refactor rewrote import lines", and that is now visible across *three different contracts* in four openings. The narrowing that would have prevented all of them is not a trigger-glob edit — it is a content-aware digest that ignores changes confined to import statements (and, for `keyword-only-convention`, to comments/docstrings). That is one mechanism, applicable manifest-wide, versus three separate glob surgeries; recommend it be evaluated as such before any per-contract narrowing.
+- **2026-07-26 · config-docs · friction** — opened by the runtime/interpreter rename, which rewrote exactly one import line in `config_check.py` and `aws_config.py` (`pipelex.service_hub` → `pipelex.runtime_hub`). This is a **verbatim repeat** of the first `config-docs` friction entry above: same two files, same incidental-member shape, same pure import-path swap, same "no configuration surface could have moved" verdict. The narrowing proposed there (drop incidental members like `config_check.py` / `aws_config.py`) *would* have prevented this one — unlike the `configs.py` opening logged between them, which it would not have. Together the three entries bound the problem precisely: a glob narrowing fixes the incidental-member case only, and a content-aware digest fixes all of them.
+- **2026-07-26 · cli-docs · clean-pass** — opened by the runtime/interpreter rename: 28 `pipelex/cli/**` files, each changed only by hub import lines. Reviewed both targets; neither `docs/tools/cli/` nor `pipelex/cli/agent_cli/CLAUDE.md` contains a single reference to any hub module, so the rename is structurally invisible to them. **Fourth consecutive clean-pass on a mechanical sweep.** One methodological note worth keeping: the review was cheap and *mechanical* this time — diffing all 28 triggers together and filtering out every changed line naming a hub left nothing, which proves import-only in one command rather than by reading 28 diffs. That check is precisely the predicate a content-aware digest would automate, which is further evidence for the recommendation in the entry above rather than a new argument.
+- **2026-07-26 · keyword-only-convention · friction** — opened by the runtime/interpreter rename touching **the same two docstring lines** in `keyword_only_guard.py` that the hub split touched (the "no `rich`, `pipelex.<hub>`, or `typer`" stdlib-only note, and the presentation-layer pointer). Same contract, same two lines, same non-reason, second time in one refactor track — the strongest single piece of evidence in this log that file-level digests over prose are the wrong granularity. The convention doc needed no edit for the same reason as last time: it names the presentation layer only generically. Note the asymmetry this exposes: the change *did* re-key all 55 hub subject grants (paths, `ServiceHub.`/`MethodHub.` qualnames, and two `set_instance` param names), which is the registry migration the doc actually specifies — and `subject_grants.toml` is correctly not a trigger, so the contract fired on the prose it could ignore and stayed silent on the data it describes.
+- **2026-07-26 · hub-layering-convention · clean-pass (initial)** — **new contract**, added on Louis' explicit say-so after being built, verified, and deliberately reverted at H-2. Triggers are the layering guard plus both hub modules; review target is `docs/contribute/hub-layering.md`. No verify command: `check-hub-layering` already gates `make check` and CI, so re-running it pre-ack would add the unstaged-file hard error without adding a guarantee. Initial review was mechanical rather than a read-through — extracted all 65 public module-level symbols from the two hubs and confirmed every one appears in the doc's partition tables, then imported `RUNTIME_LAYER_PACKAGES` from the guard and confirmed all 11 declared packages are named in Enforcement. Both checks are cheap and repeatable; whoever reviews this contract next should run them rather than re-read the tables. Deliberately **not** made a trigger: `tests/unit/pipelex/test_runtime_layer_import_closure.py`, even though the doc has a section on it — that stays within the scope Louis approved, and it is the obvious first candidate if this contract ever proves under-triggered. Watch item for the pilot verdict: both hub modules are type-annotated with most of the tree, so a *type move* elsewhere edits their import blocks and opens this contract — the same import-churn shape logged four times above. If that is what its first few openings look like, this contract is evidence for the content-aware digest, not against it.
+- **2026-07-27 · hub-layering-convention · real-catch** — first opening after the initial baseline, and it **answers that entry's watch item in the negative**: this was not the import-churn shape. Both triggers changed semantically — the guard's declared runtime layer gained `pipelex.runtime_hub` (closing a gap where the module at the centre of the rule was exempt from it), and `runtime_hub.py` shed write-only class-registry state. The review found four stale claims in `docs/contribute/hub-layering.md`, none of which the contract's two prescribed mechanical checks can see: they verify *coverage* (every hub symbol appears, every declared package is named) and are blind to a covered claim being **false**. Three of the four were exactly that — a compliance claim that read as a claim about the property when the guard only checks direct imports; a "the one module not covered" sentence wrong on both halves; and a leaf-import rule whose stated criterion contradicts two of its three in-tree importers. That is the case *for* a prose review target with a human-or-agent reader, and the sharpest evidence in this log that the mechanical checks are a floor, not the review. Note also what this says about the content-aware-digest recommendation running through the entries above: it would have opened this contract too (the trigger diffs are code, not imports), so the recommendation costs nothing here — the two are not in tension.
+- **2026-07-27 · hub-layering-convention · real-catch (second)** — opened by a *behavioral* guard change, the second consecutive non-import-churn opening for this contract: `_is_type_checking_test` matched `ast.Attribute(attr=...)` with an unconstrained receiver, so any `settings.TYPE_CHECKING:` block claimed the layer-rule exemption; the attributed form is now rooted at `typing`. The doc's carve-out bullet was under-specified rather than false, and needed the constraint stated. **The more interesting half is what the review caught that the triggers cannot see.** The same commit hardened both test modules the review target has sections on — the closure test gained a negative control and a subprocess timeout, the lifecycle test now pins the real `Pipelex.teardown` instead of a stand-in — and *neither test file is a trigger*, deliberately, per the initial baseline entry above. So the contract fired on the guard and the review then found staleness caused by changes it is structurally blind to. Two readings, and the honest one matters: this is **not** an argument for adding the test modules as triggers (the initial entry's scoping decision was Louis', and the spillover was caught anyway), but it *is* evidence that a review target's value is bounded by what a reviewer reads, not by what opened the contract. A narrower trigger set that had stayed closed here would have shipped two stale doc sentences.
diff --git a/wip/hub/README.md b/wip/hub/README.md
new file mode 100644
index 000000000..b0b17f43b
--- /dev/null
+++ b/wip/hub/README.md
@@ -0,0 +1,12 @@
+# Hub layering — working docs
+
+Working notes for the `refactor/Hub` track: splitting `pipelex.hub` into two hubs and drawing an enforced layering boundary between them.
+
+| doc | what it is |
+| --- | --- |
+| [`hub-split-refactor.md`](hub-split-refactor.md) | The original design rationale — why one hub was a problem, alternatives considered, the measured argument. Written before Phase 0. Where it disagrees with `TODOS.md`, the tracker wins (it carries the settled decisions and the re-measured numbers). |
+| [`layer-and-hub-renaming.md`](layer-and-hub-renaming.md) | The decision to rename the layers to *runtime* / *interpreter* and the hubs to `runtime_hub` / `interpreter_hub`, with the full rationale, the rejected alternatives, and the mechanical plan. **Landed** as its own commit after H-4. |
+| [`hub-split-explained.html`](hub-split-explained.html) | **Read this first if you are new to the track.** A self-contained walkthrough for co-developers: what was wrong, what we built, the measured gains (import cost, agentic work, docs and plugin contract), the critical code diffs, how the boundary is enforced, what to import from where, and the cross-repo migration table. Open it in a browser — no network needed. Also published as a shareable artifact: <https://claude.ai/code/artifact/b34e68eb-3ee1-44e1-a2ca-00a7f0ac8339>. |
+| [`pr-1062-review-followups.md`](pr-1062-review-followups.md) | **Pending work — start here.** The executable follow-up plan from the full `/review` pass on PR #1062: the transitive hole in the layer rule, the in-PR fixes, the test hardening, and the additions the release-gated sweep is missing. Phases A and B are applied; what is left is the F1 remedy (its own PR, after #1062 merges) and the release-gated Phase C. |
+
+The executable tracker is [`../../TODOS.md`](../../TODOS.md) — start at its "▶ Resume here" section. The shipped specification of the boundary is [`docs/contribute/hub-layering.md`](../../docs/contribute/hub-layering.md). The earlier single-thread triage is [`../pr-1062-review-notes.md`](../pr-1062-review-notes.md).
diff --git a/wip/hub/hub-split-explained.html b/wip/hub/hub-split-explained.html
new file mode 100644
index 000000000..f96439b11
--- /dev/null
+++ b/wip/hub/hub-split-explained.html
@@ -0,0 +1,812 @@
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Splitting pipelex.hub</title>
+<style>
+ :root{
+ --paper:#f6f7f8; --card:#ffffff; --sunk:#eef1f3;
+ --ink:#12161b; --ink-2:#4a5560; --ink-3:#78838d;
+ --rule:#dfe3e7; --rule-2:#cbd2d8;
+ --rt:#0d7a6f; --rt-soft:#e2f1ee; --rt-line:#0d7a6f;
+ --it:#6d43d6; --it-soft:#eee8fc; --it-line:#6d43d6;
+ --stop:#b3261e; --stop-soft:#fbeae8;
+ --code-bg:#f1f4f6; --code-fg:#1a2027;
+ --add-bg:#e3f1e9; --del-bg:#fbeae8;
+ --shadow:0 1px 1px rgba(18,22,27,.04), 0 10px 30px -22px rgba(18,22,27,.5);
+ --serif:"Iowan Old Style","Charter","Bitstream Charter","Sitka Text",Cambria,Georgia,serif;
+ --sans:ui-sans-serif,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;
+ --mono:ui-monospace,"SF Mono",SFMono-Regular,"JetBrains Mono","Cascadia Mono",Menlo,Consolas,monospace;
+ --measure:68ch;
+ }
+ @media (prefers-color-scheme: dark){
+ :root{
+ --paper:#0f1216; --card:#161b21; --sunk:#12171c;
+ --ink:#e7ecf0; --ink-2:#a3aeb8; --ink-3:#7d8892;
+ --rule:#252d35; --rule-2:#333d47;
+ --rt:#5eead4; --rt-soft:#0c2b28; --rt-line:#2dd4bf;
+ --it:#c0aaf9; --it-soft:#1e1836; --it-line:#a78bfa;
+ --stop:#f5a3a0; --stop-soft:#301a1a;
+ --code-bg:#0c1015; --code-fg:#dde3e9;
+ --add-bg:#0f2a1d; --del-bg:#301a1a;
+ --shadow:0 1px 1px rgba(0,0,0,.5), 0 10px 30px -22px rgba(0,0,0,.9);
+ }
+ }
+ :root[data-theme="light"]{
+ --paper:#f6f7f8; --card:#ffffff; --sunk:#eef1f3;
+ --ink:#12161b; --ink-2:#4a5560; --ink-3:#78838d;
+ --rule:#dfe3e7; --rule-2:#cbd2d8;
+ --rt:#0d7a6f; --rt-soft:#e2f1ee; --rt-line:#0d7a6f;
+ --it:#6d43d6; --it-soft:#eee8fc; --it-line:#6d43d6;
+ --stop:#b3261e; --stop-soft:#fbeae8;
+ --code-bg:#f1f4f6; --code-fg:#1a2027;
+ --add-bg:#e3f1e9; --del-bg:#fbeae8;
+ --shadow:0 1px 1px rgba(18,22,27,.04), 0 10px 30px -22px rgba(18,22,27,.5);
+ }
+ :root[data-theme="dark"]{
+ --paper:#0f1216; --card:#161b21; --sunk:#12171c;
+ --ink:#e7ecf0; --ink-2:#a3aeb8; --ink-3:#7d8892;
+ --rule:#252d35; --rule-2:#333d47;
+ --rt:#5eead4; --rt-soft:#0c2b28; --rt-line:#2dd4bf;
+ --it:#c0aaf9; --it-soft:#1e1836; --it-line:#a78bfa;
+ --stop:#f5a3a0; --stop-soft:#301a1a;
+ --code-bg:#0c1015; --code-fg:#dde3e9;
+ --add-bg:#0f2a1d; --del-bg:#301a1a;
+ --shadow:0 1px 1px rgba(0,0,0,.5), 0 10px 30px -22px rgba(0,0,0,.9);
+ }
+
+ *{box-sizing:border-box}
+ body{
+ margin:0; background:var(--paper); color:var(--ink); font-family:var(--sans);
+ font-size:16.5px; line-height:1.68; -webkit-font-smoothing:antialiased;
+ }
+ .frame{max-width:1040px; margin:0 auto; padding:0 1.25rem 6rem}
+ p,ul,ol,figcaption,.note,.tldr,blockquote{max-width:var(--measure)}
+
+ a{color:inherit; text-decoration:underline; text-decoration-thickness:1px;
+ text-decoration-color:var(--rule-2); text-underline-offset:3px}
+ a:hover{text-decoration-color:currentColor}
+ a:focus-visible,summary:focus-visible,input:focus-visible + label{outline:2px solid var(--rt-line); outline-offset:2px; border-radius:3px}
+ @media (prefers-reduced-motion: reduce){*{animation:none !important; transition:none !important; scroll-behavior:auto !important}}
+
+ /* ── masthead ─────────────────────────────────────────── */
+ .masthead{padding:3.2rem 0 1.6rem; border-bottom:1px solid var(--rule)}
+ .eyebrow{font-family:var(--mono); font-size:.74rem; letter-spacing:.14em; text-transform:uppercase; color:var(--ink-3); margin:0 0 .9rem}
+ h1{font-family:var(--serif); font-weight:600; letter-spacing:-.02em; text-wrap:balance;
+ font-size:clamp(2.15rem,1.55rem + 2.2vw,3rem); line-height:1.1; margin:0 0 .6rem}
+ h1 .mono{font-family:var(--mono); font-size:.82em; font-weight:500; letter-spacing:-.01em}
+ .deck{font-size:1.12rem; color:var(--ink-2); margin:0 0 1.6rem; max-width:60ch; text-wrap:pretty}
+ .deck b{color:var(--ink); font-weight:600}
+ .meta{display:flex; flex-wrap:wrap; gap:.4rem; list-style:none; margin:0; padding:0; max-width:none}
+ .meta li{font-family:var(--mono); font-size:.74rem; letter-spacing:.01em; color:var(--ink-2);
+ border:1px solid var(--rule); background:var(--card); border-radius:2px; padding:.24rem .55rem}
+ .meta li b{color:var(--ink); font-weight:600}
+ .meta li.live{border-color:var(--rt); color:var(--rt)}
+
+ /* ── sticky section rail ─────────────────────────────── */
+ .rail{position:sticky; top:0; z-index:9; display:flex; gap:.15rem; overflow-x:auto; scrollbar-width:none;
+ padding:.5rem 0; margin:0 0 .4rem; border-bottom:1px solid var(--rule);
+ background:color-mix(in srgb, var(--paper) 88%, transparent); backdrop-filter:blur(8px)}
+ .rail::-webkit-scrollbar{display:none}
+ .rail a{font-family:var(--mono); font-size:.72rem; letter-spacing:.04em; text-transform:uppercase;
+ color:var(--ink-3); text-decoration:none; white-space:nowrap; padding:.28rem .5rem; border-radius:3px}
+ .rail a:hover{color:var(--ink); background:var(--sunk)}
+
+ /* ── headings ────────────────────────────────────────── */
+ h2{font-family:var(--serif); font-weight:600; font-size:1.6rem; letter-spacing:-.015em; text-wrap:balance;
+ margin:3.4rem 0 1rem; scroll-margin-top:4rem; display:flex; align-items:baseline; gap:.7rem}
+ h2 .n{font-family:var(--mono); font-size:.72rem; font-weight:500; letter-spacing:.1em; color:var(--rt);
+ border:1px solid var(--rule); border-radius:2px; padding:.1rem .38rem; flex:none; position:relative; top:-.25em}
+ h3{font-size:1.02rem; font-weight:650; margin:2rem 0 .4rem; letter-spacing:-.005em}
+ h4{font-family:var(--mono); font-size:.74rem; font-weight:500; letter-spacing:.12em; text-transform:uppercase;
+ color:var(--ink-3); margin:1.6rem 0 .3rem}
+ p{margin:.75rem 0} ul,ol{margin:.75rem 0; padding-left:1.15rem} li{margin:.32rem 0}
+
+ code,kbd{font-family:var(--mono); font-size:.86em}
+ :is(p,li,td,th,summary,figcaption,.deck) code{background:var(--code-bg); padding:.08em .32em; border-radius:3px; white-space:nowrap}
+
+ /* ── TL;DR ───────────────────────────────────────────── */
+ .tldr{margin:2.2rem 0; padding:1.3rem 1.5rem 1.4rem; background:var(--card);
+ border:1px solid var(--rule); border-top:2px solid var(--ink); border-radius:3px; box-shadow:var(--shadow)}
+ .tldr h2{font-family:var(--mono); font-size:.78rem; font-weight:600; letter-spacing:.16em; text-transform:uppercase;
+ color:var(--ink-3); margin:0 0 .7rem; display:block}
+ .tldr ul{margin:0; padding-left:1.05rem; max-width:none}
+ .tldr li{margin:.5rem 0}
+ .tldr li::marker{color:var(--rule-2)}
+
+ /* ── figures / stats ─────────────────────────────────── */
+ .stats{display:grid; grid-template-columns:repeat(auto-fit,minmax(158px,1fr)); gap:.6rem; margin:1.6rem 0}
+ .stat{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.75rem .9rem .8rem}
+ .stat .n{display:block; font-family:var(--mono); font-variant-numeric:tabular-nums; font-size:1.4rem;
+ font-weight:600; letter-spacing:-.03em; line-height:1.2}
+ .stat .n s{color:var(--ink-3); font-weight:400; font-size:.62em; text-decoration-color:var(--rule-2)}
+ .stat .n em{font-style:normal; color:var(--rt)}
+ .stat .l{display:block; font-size:.78rem; line-height:1.4; color:var(--ink-2); margin-top:.25rem}
+
+ figure{margin:1.8rem 0; padding:1.1rem 1.1rem .75rem; background:var(--card);
+ border:1px solid var(--rule); border-radius:3px; box-shadow:var(--shadow)}
+ figure svg{display:block; width:100%; height:auto}
+ figcaption{font-size:.83rem; line-height:1.55; color:var(--ink-2); margin-top:.7rem; padding-top:.7rem; border-top:1px solid var(--rule)}
+
+ .s-box{fill:var(--card); stroke:var(--rule-2)}
+ .s-rt{fill:var(--rt-soft); stroke:var(--rt-line)}
+ .s-it{fill:var(--it-soft); stroke:var(--it-line)}
+ .s-bad{fill:var(--stop-soft); stroke:var(--stop)}
+ .s-t{fill:var(--ink); font:600 13px var(--sans)}
+ .s-ts{fill:var(--ink-2); font:400 11.5px var(--mono)}
+ .s-tm{fill:var(--ink-2); font:400 11.5px var(--sans)}
+ .s-trt{fill:var(--rt); font:600 10.5px var(--mono); letter-spacing:.1em}
+ .s-tit{fill:var(--it); font:600 10.5px var(--mono); letter-spacing:.1em}
+ .s-tbad{fill:var(--stop); font:600 11.5px var(--sans)}
+ .s-tok{fill:var(--rt); font:600 12px var(--sans)}
+ .s-line{stroke:var(--rule-2); fill:none}
+ .s-badline{stroke:var(--stop); fill:none}
+ .s-okline{stroke:var(--rt-line); fill:none}
+ .s-barwas{fill:var(--rule)}
+ .s-barnow{fill:var(--rt-line)}
+
+ /* ── tables ──────────────────────────────────────────── */
+ .scroll{overflow-x:auto; margin:1.2rem 0; border:1px solid var(--rule); border-radius:3px; background:var(--card)}
+ table{border-collapse:collapse; width:100%; font-size:.89rem; font-variant-numeric:tabular-nums}
+ th,td{padding:.55rem .7rem; text-align:left; vertical-align:top; border-bottom:1px solid var(--rule)}
+ th{font-family:var(--mono); font-size:.72rem; font-weight:600; letter-spacing:.08em; text-transform:uppercase;
+ color:var(--ink-3); background:var(--sunk); white-space:nowrap}
+ tbody tr:last-child td{border-bottom:0}
+
+ /* ── code ────────────────────────────────────────────── */
+ pre{background:var(--code-bg); color:var(--code-fg); border:1px solid var(--rule); border-radius:3px;
+ padding:.9rem 1rem; overflow-x:auto; font-size:.8rem; line-height:1.6; margin:1rem 0}
+ pre code{font-family:var(--mono)}
+ .diff .del{display:block; margin:0 -1rem; padding:0 1rem; background:var(--del-bg); color:var(--stop)}
+ .diff .add{display:block; margin:0 -1rem; padding:0 1rem; background:var(--add-bg); color:var(--rt)}
+ .diff .hdr{display:block; color:var(--ink-3)}
+ .cmt{color:var(--ink-3)}
+
+ /* ── tabs ────────────────────────────────────────────── */
+ .tabs{display:flex; flex-wrap:wrap; gap:.3rem; margin:1.3rem 0}
+ .tabs input{position:absolute; width:1px; height:1px; opacity:0; clip-path:inset(50%)}
+ .tabs label{cursor:pointer; font-family:var(--mono); font-size:.74rem; letter-spacing:.02em;
+ border:1px solid var(--rule); background:var(--card); color:var(--ink-2);
+ border-radius:2px; padding:.3rem .6rem; user-select:none}
+ .tabs label:hover{color:var(--ink); border-color:var(--rule-2)}
+ .tabs .panels{flex:1 0 100%; margin-top:.35rem}
+ .tabs .panel{display:none}
+ .tabs .panel > :first-child{margin-top:0}
+ #d1:checked ~ label[for="d1"],#d2:checked ~ label[for="d2"],#d3:checked ~ label[for="d3"],
+ #d4:checked ~ label[for="d4"],#d5:checked ~ label[for="d5"],#d6:checked ~ label[for="d6"]
+ {background:var(--ink); color:var(--paper); border-color:var(--ink)}
+ #d1:focus-visible ~ label[for="d1"],#d2:focus-visible ~ label[for="d2"],#d3:focus-visible ~ label[for="d3"],
+ #d4:focus-visible ~ label[for="d4"],#d5:focus-visible ~ label[for="d5"],#d6:focus-visible ~ label[for="d6"]
+ {outline:2px solid var(--rt-line); outline-offset:2px}
+ #d1:checked ~ .panels > .panel:nth-child(1),
+ #d2:checked ~ .panels > .panel:nth-child(2),
+ #d3:checked ~ .panels > .panel:nth-child(3),
+ #d4:checked ~ .panels > .panel:nth-child(4),
+ #d5:checked ~ .panels > .panel:nth-child(5),
+ #d6:checked ~ .panels > .panel:nth-child(6){display:block}
+
+ /* ── misc blocks ─────────────────────────────────────── */
+ details{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.75rem 1rem; margin:1.2rem 0}
+ details[open]{padding-bottom:1rem}
+ summary{cursor:pointer; font-weight:600; font-size:.92rem}
+ summary::marker{color:var(--rule-2)}
+ details > :nth-child(2){margin-top:.85rem}
+
+ .note{border-left:2px solid var(--rule-2); padding:.1rem 0 .1rem .95rem; color:var(--ink-2); font-size:.93rem; margin:1.1rem 0}
+ .note.stop{border-left-color:var(--stop)}
+ .note.go{border-left-color:var(--rt-line)}
+
+ .cards{display:grid; grid-template-columns:repeat(auto-fit,minmax(255px,1fr)); gap:.7rem; margin:1.4rem 0}
+ .cards .card{background:var(--card); border:1px solid var(--rule); border-radius:3px; padding:.9rem 1rem}
+ .cards h3{margin:0 0 .3rem; font-size:.95rem}
+ .cards p{margin:.3rem 0; font-size:.88rem; color:var(--ink-2); max-width:none}
+ .cards p strong{color:var(--ink)}
+
+ .legend{display:flex; flex-wrap:wrap; gap:1rem; margin:1.4rem 0 0; font-family:var(--mono); font-size:.74rem; color:var(--ink-2)}
+ .legend span{display:flex; align-items:center; gap:.4rem}
+ .legend i{width:10px; height:10px; border-radius:2px; display:block}
+ .legend .k-rt{background:var(--rt-line)} .legend .k-it{background:var(--it-line)} .legend .k-stop{background:var(--stop)}
+
+ footer{margin-top:3.5rem; padding-top:1.2rem; border-top:1px solid var(--rule); color:var(--ink-3); font-size:.83rem}
+ footer p{max-width:none}
+</style>
+
+<div class="frame">
+
+<header class="masthead">
+ <p class="eyebrow">Pipelex · refactor/Hub · architecture note</p>
+ <h1>Splitting <span class="mono">pipelex.hub</span></h1>
+ <p class="deck">One god-object became two hubs with a single enforced arrow between them — and importing the Pipelex runtime now loads <b>zero</b> interpreter modules.</p>
+ <ul class="meta">
+ <li>branch <b>refactor/Hub</b></li>
+ <li>base <b>v0.40.0</b></li>
+ <li class="live">PR <b><a href="https://github.com/Pipelex/pipelex/pull/1062">#1062 → dev</a></b> open</li>
+ <li>follow-ups <b><a href="https://github.com/Pipelex/pipelex/pull/1063">#1063</a></b> merged</li>
+ <li>535 files · ~490 mechanical</li>
+ <li>measured <b>2026-07-27</b></li>
+ </ul>
+</header>
+
+<nav class="rail" aria-label="Sections">
+ <a href="#s1">01 · Problem</a>
+ <a href="#s2">02 · What we built</a>
+ <a href="#s3">03 · The code</a>
+ <a href="#s4">04 · Where core splits</a>
+ <a href="#s5">05 · What we gained</a>
+ <a href="#s6">06 · Enforcement</a>
+ <a href="#s7">07 · For you</a>
+ <a href="#s8">08 · Limits</a>
+</nav>
+
+<div class="tldr">
+ <h2>TL;DR</h2>
+ <ul>
+ <li><strong>What was wrong.</strong> <code>pipelex/hub.py</code> brokered <em>every</em> cross-cutting dependency — config, console, secrets, storage, the model deck, the inference workers — <em>and</em> the concept/pipe libraries, the router, the pipeline manager. Four module-level imports meant that asking it for <code>get_console()</code> loaded the entire MTHDS interpreter. It also formed a real import cycle, papered over by three <code>importlib.import_module("pipelex.hub")</code> hacks that no lint and no type checker can see.</li>
+ <li><strong>What we did.</strong> Deleted <code>pipelex/hub.py</code> outright — no alias — and replaced it with <code>pipelex/runtime_hub.py</code> (<code>RuntimeHub</code>) and <code>pipelex/interpreter_hub.py</code> (<code>InterpreterHub</code>). One rule: <em>the interpreter hub may import the runtime hub; the runtime hub must never import the interpreter hub.</em> Then the misplaced types moved down, and core's data model got injected providers so it could join the runtime layer.</li>
+ <li><strong>What it bought.</strong> The inference layer went from 50 interpreter modules to <strong>0</strong>; the runtime closure from 357 modules / 29,193 SLOC to <strong>269 / 20,299</strong>. Six <code>core.*</code> entry points went 50 → 0 each. The cycle and its three hacks are gone.</li>
+ <li><strong>It is mechanically enforced, not review-enforced.</strong> An AST guard (<code>make check-hub-layering</code>, in <code>make agent-check</code> and CI) checks the rule on imports <em>and on string literals</em>; a subprocess closure test pins the <em>property</em> across eight runtime entry points, with a negative control so it can never pass vacuously.</li>
+ <li><strong>What changes for you.</strong> Pick your hub by what you need: infrastructure → <code>pipelex.runtime_hub</code>; anything about the loaded method → <code>pipelex.interpreter_hub</code>. A stale <code>from pipelex.hub import …</code> fails loudly at import time, by design.</li>
+ <li><strong>Not done yet.</strong> The layer rule is enforced only one hop deep — 4 of 476 declared runtime-layer modules breach it transitively, all in <code>pipelex.plugins</code>, and the headline property is unaffected. Remedy decided, its own PR after #1062. The cross-repo sweep is release-gated: external repos still import <code>pipelex.hub</code> and break the moment this ships.</li>
+ </ul>
+</div>
+
+<div class="stats">
+ <div class="stat"><span class="n"><s>50</s> <em>0</em></span><span class="l">interpreter modules loaded by the inference layer</span></div>
+ <div class="stat"><span class="n"><s>357</s> <em>269</em></span><span class="l">pipelex modules in the runtime closure</span></div>
+ <div class="stat"><span class="n"><s>29,193</s> <em>20,299</em></span><span class="l">SLOC parsed and executed at import</span></div>
+ <div class="stat"><span class="n"><s>3</s> <em>0</em></span><span class="l"><code>importlib</code> cycle hacks in <code>core/concepts/</code></span></div>
+</div>
+
+<div class="legend" aria-hidden="true">
+ <span><i class="k-rt"></i> runtime layer</span>
+ <span><i class="k-it"></i> interpreter layer</span>
+ <span><i class="k-stop"></i> forbidden / deleted</span>
+</div>
+
+<h2 id="s1"><span class="n">01</span> The problem</h2>
+
+<p>One module brokered everything, so everything imported it: 309 files. Because the hub annotated its own getters with <code>Library</code>, <code>LibraryManagerAbstract</code>, <code>PipeAbstract</code> and <code>Concept</code>, those annotations dragged the whole interpretation layer into the import graph of every consumer — including consumers that only ever wanted a console handle.</p>
+
+<figure>
+<svg viewBox="0 0 760 250" role="img" aria-label="Before: every runtime-layer caller reaches the interpreter through pipelex.hub">
+ <rect class="s-box" x="8" y="52" width="176" height="120" rx="3"/>
+ <text class="s-trt" x="24" y="76">RUNTIME CALLERS</text>
+ <text class="s-ts" x="24" y="98">cogt · tools · system</text>
+ <text class="s-ts" x="24" y="116">plugins · reporting</text>
+ <text class="s-tm" x="24" y="142">“I just want</text>
+ <text class="s-tm" x="24" y="158">get_console()”</text>
+
+ <path class="s-line" d="M188 112 H244" stroke-width="1.5" marker-end="url(#ar)"/>
+
+ <rect class="s-bad" x="248" y="46" width="184" height="132" rx="3" stroke-width="1.5"/>
+ <text class="s-t" x="268" y="76">pipelex/hub.py</text>
+ <text class="s-ts" x="268" y="98">one module</text>
+ <text class="s-ts" x="268" y="116">309 importers</text>
+ <text class="s-tbad" x="268" y="146">god object</text>
+ <text class="s-ts" x="268" y="164">323 modules on import</text>
+
+ <path class="s-badline" d="M436 112 H520" stroke-width="1.5" marker-end="url(#arb)"/>
+ <text class="s-tbad" x="437" y="102">4 module-level imports</text>
+ <text class="s-ts" x="437" y="132">(type annotations only)</text>
+
+ <rect class="s-it" x="524" y="34" width="228" height="156" rx="3" stroke-width="1.5"/>
+ <text class="s-tit" x="544" y="58">INTERPRETER</text>
+ <text class="s-ts" x="544" y="82">libraries</text>
+ <text class="s-ts" x="544" y="100">pipe_operators</text>
+ <text class="s-ts" x="544" y="118">pipe_controllers</text>
+ <text class="s-ts" x="544" y="136">codegen</text>
+ <text class="s-ts" x="544" y="154">builder</text>
+ <text class="s-tbad" x="544" y="178">50 modules pulled in</text>
+
+ <path class="s-badline" d="M600 190 C600 224, 360 236, 340 186" stroke-width="1.3" stroke-dasharray="4 3" marker-end="url(#arb)"/>
+ <text class="s-tbad" x="366" y="228">↺ cycle: core/concepts/concept.py ⇄ hub.py — 3 × importlib.import_module("pipelex.hub")</text>
+
+ <defs>
+ <marker id="ar" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0 0 L10 5 L0 10 z" fill="var(--rule-2)"/>
+ </marker>
+ <marker id="arb" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0 0 L10 5 L0 10 z" fill="var(--stop)"/>
+ </marker>
+ </defs>
+</svg>
+<figcaption>Before. Traced on the base commit: <code>cogt.content_generation.content_generator</code> reached <code>pipe_controllers</code>, <code>libraries</code>, <code>pipe_operators</code> and <code>codegen</code> <em>only</em> via <code>pipelex.hub</code> — never independently. The hub was the single edge holding the two halves together.</figcaption>
+</figure>
+
+<p>Three consequences, all of them daily costs:</p>
+
+<ul>
+ <li><strong>An unanalyzable cycle.</strong> <code>core/concepts/concept.py</code>, <code>concept_factory.py</code> and <code>structure_generation/generator.py</code> each carried an identical lazy-import shim to break a circular dependency with the hub. All three wanted exactly one symbol — <code>get_class_registry</code>, an infrastructure-level one. Those shims are invisible to every import lint and to pyright's module graph: real coupling, load-bearing, unanalyzable.</li>
+ <li><strong>A layer boundary that existed but could not be expressed.</strong> Of the 309 importers, 134 used only infrastructure symbols, 139 only method-machinery ones, and just 36 straddled. Every package below <code>core</code> used infrastructure symbols exclusively, with zero exceptions. The architecture was already layered — the hub was the one place the layering was unstateable, and therefore the one place it silently rotted.</li>
+ <li><strong>Import cost paid by everyone.</strong> <code>pipelex-api</code>'s health check, the CLI's <code>--version</code>, every plugin registration module and every test touching <code>get_console</code> paid for the full interpreter.</li>
+</ul>
+
+<h2 id="s2"><span class="n">02</span> What we built</h2>
+
+<p><code>pipelex/hub.py</code> is <strong>deleted</strong>, not aliased. That is deliberate: a stale import must fail loudly at import time rather than silently resolve to the wrong layer, and it matches the repo's no-backward-compatibility principle. In its place, two containers with genuinely different lifecycles.</p>
+
+<figure>
+<svg viewBox="0 0 760 330" role="img" aria-label="After: two hubs, one permitted arrow, one forbidden arrow">
+ <rect class="s-rt" x="8" y="20" width="340" height="236" rx="3" stroke-width="1.5"/>
+ <text class="s-trt" x="28" y="46">RUNTIME LAYER — PROCESS-SCOPED</text>
+ <rect class="s-box" x="28" y="60" width="300" height="46" rx="3" stroke-width="1.5"/>
+ <text class="s-t" x="44" y="80">pipelex/runtime_hub.py</text>
+ <text class="s-ts" x="44" y="97">RuntimeHub · get_runtime_hub()</text>
+ <text class="s-ts" x="28" y="128">cogt · tools · system · plugins · reporting</text>
+ <text class="s-ts" x="28" y="146">core.concepts · core.domains · core.memory</text>
+ <text class="s-ts" x="28" y="164">core.stuffs · core.pipes.inputs · …stuff_spec</text>
+ <text class="s-tm" x="28" y="192">config · console · secrets · storage · telemetry</text>
+ <text class="s-tm" x="28" y="210">model deck · inference workers · content generator</text>
+ <text class="s-tm" x="28" y="228">reporting · run mode · plugin registries</text>
+ <text class="s-tok" x="28" y="248">0 interpreter modules — measured, per entry point</text>
+
+ <rect class="s-it" x="412" y="20" width="340" height="236" rx="3" stroke-width="1.5"/>
+ <text class="s-tit" x="432" y="46">INTERPRETER LAYER — LIBRARY-SCOPED</text>
+ <rect class="s-box" x="432" y="60" width="300" height="46" rx="3" stroke-width="1.5"/>
+ <text class="s-t" x="448" y="80">pipelex/interpreter_hub.py</text>
+ <text class="s-ts" x="448" y="97">InterpreterHub · get_interpreter_hub()</text>
+ <text class="s-ts" x="432" y="128">libraries · pipe_operators · pipe_controllers</text>
+ <text class="s-ts" x="432" y="146">codegen · builder · core.bundles · core.interpreter</text>
+ <text class="s-ts" x="432" y="164">core.pipes.pipe_abstract · core.pipes.rendering</text>
+ <text class="s-tm" x="432" y="192">library manager · concept / domain / pipe libraries</text>
+ <text class="s-tm" x="432" y="210">current-library contextvars · pipe router</text>
+ <text class="s-tm" x="432" y="228">pipe run · pipeline manager · PipeFunc executor</text>
+
+ <path class="s-okline" d="M430 84 H352" stroke-width="2" marker-end="url(#ar2)"/>
+ <text class="s-tm" x="391" y="76" text-anchor="middle">may import</text>
+
+ <path class="s-badline" d="M330 148 H430" stroke-width="2" stroke-dasharray="6 4"/>
+ <line class="s-badline" x1="372" y1="138" x2="388" y2="158" stroke-width="2.5"/>
+ <line class="s-badline" x1="388" y1="138" x2="372" y2="158" stroke-width="2.5"/>
+ <text class="s-tbad" x="380" y="176" text-anchor="middle">never</text>
+
+ <rect class="s-box" x="8" y="272" width="744" height="46" rx="3"/>
+ <text class="s-t" x="28" y="292">The one rule</text>
+ <text class="s-tm" x="28" y="310">interpreter_hub may import runtime_hub · runtime_hub must never import interpreter_hub · pipelex.hub no longer exists</text>
+
+ <defs>
+ <marker id="ar2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0 0 L10 5 L0 10 z" fill="var(--rt-line)"/>
+ </marker>
+ </defs>
+</svg>
+<figcaption>After. Two containers, two singletons, two lifecycles: the runtime hub is built once at boot from config plus plugin registration and never varies; the interpreter hub is bound to the loaded method, and already had contextvar machinery for exactly that. Today the permitted arrow is not even used — the one runtime-layer thing the interpreter hub needs lives <em>below</em> both hubs — which is stronger than the rule requires.</figcaption>
+</figure>
+
+<h4>Why these names</h4>
+<p>It is the textbook language-implementation split, so it explains itself to anyone who has implemented a language: the <strong>runtime</strong> is the machinery present at execution time (allocator, stdlib, FFI — here: models, workers, config, values); the <strong>interpreter</strong> reads the program and executes it (here: reads <code>.mthds</code>, builds pipes, routes them). It also gives one word across both layer and hub. The earlier working names <code>service_hub</code> / <code>method_hub</code> <strong>never shipped</strong> — <em>service</em> collides with the hosted product (<code>from pipelex.service_hub import get_secret</code> inside <code>pipelex-platform</code> reads two ways one line apart), and <em>method</em> borrows an MTHDS language noun for a Pipelex runtime container, against the brand-boundary rule.</p>
+
+<details>
+<summary>Names considered and rejected — so nobody re-proposes them</summary>
+<div class="scroll">
+<table>
+<thead><tr><th>Candidate</th><th>For</th><th>Why not</th></tr></thead>
+<tbody>
+<tr><td><code>inference</code> (layer)</td><td>Names the valuable half</td><td>A subset masquerading as the whole — <code>tools</code>, <code>system</code>, <code>reporting</code> and the value data model are not inference. It also collides with live usage: “the inference layer” already means <code>cogt</code> specifically.</td></tr>
+<tr><td><code>foundation</code> (layer)</td><td>Genuinely viable; the fallback</td><td>Less informative than <code>runtime</code>, and shares no word with the hub.</td></tr>
+<tr><td><code>core</code> (layer)</td><td>—</td><td>Catastrophic: <code>pipelex/core/</code> exists and straddles both layers.</td></tr>
+<tr><td><code>library_hub</code></td><td>Names the biggest occupant</td><td>A library is inert; the container is active machinery (router, pipeline manager). Undersells it.</td></tr>
+<tr><td><code>pipe_hub</code></td><td>Short, concrete</td><td>Narrower than its contents — a meaningful share is concepts and domains, and <code>get_native_concept()</code> on a <code>pipe_hub</code> reads wrong.</td></tr>
+<tr><td>keep <code>hub.py</code> for one half</td><td>Smaller diff</td><td>A stale import would silently succeed and resolve to the wrong layer. The whole point is that it must not.</td></tr>
+</tbody>
+</table>
+</div>
+</details>
+
+<h2 id="s3"><span class="n">03</span> The critical code</h2>
+
+<p>Six changes carry the design; everything else in the 535-file diff is import churn.</p>
+
+<div class="tabs">
+ <input type="radio" name="diffs" id="d1" checked>
+ <input type="radio" name="diffs" id="d2">
+ <input type="radio" name="diffs" id="d3">
+ <input type="radio" name="diffs" id="d4">
+ <input type="radio" name="diffs" id="d5">
+ <input type="radio" name="diffs" id="d6">
+ <label for="d1">1 · the cause</label>
+ <label for="d2">2 · the cycle</label>
+ <label for="d3">3 · resolver slot</label>
+ <label for="d4">4 · a straddler</label>
+ <label for="d5">5 · injected providers</label>
+ <label for="d6">6 · boot</label>
+
+ <div class="panels">
+
+ <div class="panel">
+ <h3>Four imports, serving nothing but type annotations</h3>
+ <p>This is the entire cause. Each annotated a getter's return type, and each dragged a subtree behind it.</p>
+ <pre class="diff"><code><span class="hdr">--- a/pipelex/hub.py (deleted)</span>
+<span class="del">-from pipelex.libraries.library import Library # concrete → concept_library, pipe_controllers, codegen</span>
+<span class="del">-from pipelex.libraries.library_manager_abstract import LibraryManagerAbstract # → core.bundles → all twelve pipe blueprints</span>
+<span class="del">-from pipelex.core.pipes.pipe_abstract import PipeAbstract # → graph.graph_tracer_manager</span>
+<span class="del">-from pipelex.core.concepts.concept import Concept # ← the cycle behind the three importlib hacks</span></code></pre>
+ <p class="note">Deferring them under <code>TYPE_CHECKING</code> would not have been the fix — that keeps the god object and adds a fig leaf. The four annotations belong to getters that are <em>interpreter</em> concerns, so they moved to the module where naming them is free.</p>
+ </div>
+
+ <div class="panel">
+ <h3>Three identical lazy-import shims become one plain import</h3>
+ <pre class="diff"><code><span class="hdr">--- a/pipelex/core/concepts/concept.py (also concept_factory.py, structure_generation/generator.py)</span>
+<span class="del">-def _get_class_registry() -&gt; ClassRegistryAbstract:</span>
+<span class="del">- """Lazy import to break circular dependency between concept.py and hub.py."""</span>
+<span class="del">- import importlib # noqa: PLC0415</span>
+<span class="del">-</span>
+<span class="del">- hub = importlib.import_module("pipelex.hub")</span>
+<span class="del">- return hub.get_class_registry() # type: ignore[no-any-return]</span>
+<span class="add">+from pipelex.system.registries.class_registry_access import get_class_registry</span></code></pre>
+ <p>Note where the import points: <strong>not</strong> at <code>runtime_hub</code>. <code>core.concepts.concept</code> sits <em>inside</em> <code>runtime_hub</code>'s own closure (<code>runtime_hub → cogt.llm.llm_worker_abstract → system.telemetry.otel_factory → core.pipes.pipe_output → core.stuffs.stuff → core.concepts.concept</code>), so importing the hub from there is a hard cycle in <em>both</em> orders. The accessor lives one level below both hubs instead.</p>
+ </div>
+
+ <div class="panel">
+ <h3>Library scoping crosses <em>downward at boot</em>, never as an import</h3>
+ <p><code>get_class_registry()</code> must stay library-scoped — a Temporal workflow pins its own registry — but resolving <em>which</em> library is current is interpreter knowledge. So the runtime side holds a defaulted callable slot, and the interpreter installs the real resolver when it is constructed.</p>
+ <pre><code><span class="cmt"># pipelex/system/registries/class_registry_access.py — imports nothing from pipelex</span>
+class ClassRegistryScoping:
+ def __init__(self) -&gt; None:
+ self._resolver: Callable[[], ClassRegistryAbstract | None] = _no_library_scoping
+
+ def install(self, *, resolver: Callable[[], ClassRegistryAbstract | None]) -&gt; None:
+ self._resolver = resolver
+
+ def reset(self) -&gt; None:
+ self._resolver = _no_library_scoping
+
+class_registry_scoping = ClassRegistryScoping()
+
+def get_class_registry() -&gt; ClassRegistryAbstract:
+ scoped = class_registry_scoping.resolve()
+ if scoped is not None:
+ return scoped
+ return KajsonManager.get_class_registry() <span class="cmt"># degrade, never raise</span>
+
+<span class="cmt"># pipelex/interpreter_hub.py — set_interpreter_hub() installs the library-scoped resolver.</span>
+<span class="cmt"># pipelex.runtime_hub.get_class_registry delegates here and stays the public accessor.</span></code></pre>
+ <p class="note go">The default matters: a process that only ever builds a <code>RuntimeHub</code> — the doctor path, most unit tests — degrades to the process-global registry instead of raising. A defaulted callable, never an unset attribute; the same shape as the existing <code>HubSlot.ISOLATED_EXECUTION_PROBE</code>.</p>
+ </div>
+
+ <div class="panel">
+ <h3>What a straddling call site looks like now</h3>
+ <p>36 of the 309 files used symbols from both halves. Those are the only ones that gained a second import line — and the line itself now says which layer each symbol belongs to.</p>
+ <pre class="diff"><code><span class="hdr">--- a/pipelex/pipe_operators/llm/pipe_llm.py</span>
+<span class="del">-from pipelex.hub import (</span>
+<span class="del">- get_class_registry,</span>
+<span class="del">- get_concept_library,</span>
+<span class="del">- get_content_generator,</span>
+<span class="del">- get_model_deck,</span>
+<span class="del">- get_native_concept,</span>
+<span class="del">- get_required_concept,</span>
+<span class="del">-)</span>
+<span class="add">+from pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_concept</span>
+<span class="add">+from pipelex.runtime_hub import get_class_registry, get_content_generator, get_model_deck</span></code></pre>
+ <p>Everything else was a one-line module swap, applied by an AST pass over whole import statements — not a regex, because 29 of the blocks were parenthesized and multi-line.</p>
+ </div>
+
+ <div class="panel">
+ <h3>Core's data model stopped reaching upward</h3>
+ <p>Five <code>core/</code> modules looked concepts up through the hub. They now <em>declare</em> what they need as a parameter, which is what lets them join the runtime layer.</p>
+ <pre class="diff"><code><span class="hdr">--- a/pipelex/core/stuffs/stuff_factory.py</span>
+<span class="del">-def make_from_blueprint(cls, blueprint: StuffBlueprint) -&gt; "Stuff":</span>
+<span class="del">- concept_library = get_concept_library() # ← reaches into the interpreter</span>
+<span class="del">- if isinstance(blueprint.content, str) and concept_library.is_compatible(</span>
+<span class="del">- tested_concept=concept_library.get_required_concept(concept_ref=blueprint.concept_ref),</span>
+<span class="del">- wanted_concept=get_native_concept(native_concept=NativeConceptCode.TEXT),</span>
+<span class="add">+def make_from_blueprint(cls, blueprint: StuffBlueprint, *, concept_provider: ConceptProviderAbstract) -&gt; "Stuff":</span>
+<span class="add">+ if isinstance(blueprint.content, str) and concept_provider.is_compatible(</span>
+<span class="add">+ tested_concept=concept_provider.get_required_concept(concept_ref=blueprint.concept_ref),</span>
+<span class="add">+ wanted_concept=concept_provider.get_native_concept(native_concept=NativeConceptCode.TEXT),</span>
+ ):</code></pre>
+ <p><code>ConceptProviderAbstract</code> is a new <em>read-side</em> contract owned by <code>core/</code>: resolve a ref, resolve a native code, answer compatibility. <code>ConceptLibraryAbstract</code> <strong>extends</strong> it, keeping add/remove/list/setup/teardown in the interpreter layer. The split is the point — core depends on <em>resolution</em>, never on a library <em>lifecycle</em>. Injection happens on the interpreter side: <code>pipe_factory</code>, the renderers and <code>pipeline/execution_seams.py</code> call the hub themselves and hand the result down.</p>
+ </div>
+
+ <div class="panel">
+ <h3>Boot builds both, then changes nothing else</h3>
+ <pre><code><span class="cmt"># pipelex/pipelex.py — Pipelex.__init__</span>
+self.runtime_hub = RuntimeHub()
+set_runtime_hub(self.runtime_hub)
+self.interpreter_hub = InterpreterHub()
+set_interpreter_hub(self.interpreter_hub) <span class="cmt"># also installs the class-registry resolver</span></code></pre>
+ <p class="note stop">The setter sequence after this is <strong>byte-identical in order</strong>, deliberately. Reordering to get a clean “runtime first, then interpreter” run would have moved setters across documented ordering dependencies — the storage-provider block resolves <em>after</em> secrets is on the hub, so the GCP factory's secret read works — a real behavior risk at a checkpoint whose bar was zero behavior change. Constructing both hubs up front already delivers what the ordering was protecting: no setter can run against a missing hub.</p>
+ <p>Teardown releases both, and drops any scoping the interpreter hub installed — pinned by <code>tests/unit/pipelex/test_hub_lifecycle.py</code>.</p>
+ </div>
+
+ </div>
+</div>
+
+<h2 id="s4"><span class="n">04</span> Where <code>core/</code> splits</h2>
+
+<p>The original plan assumed all of <code>pipelex/core/</code> could join the runtime layer once the five hub-straddling modules were converted. Measurement said otherwise, and this is the main finding of the work: beyond those five, seven <code>core/</code> modules import the interpreter <em>directly</em> — no hub involved, so no amount of dependency injection touches them. <code>core.pipes.pipe_abstract</code> alone loads 30 interpreter modules while importing no hub at all.</p>
+
+<figure>
+<svg viewBox="0 0 760 250" role="img" aria-label="pipelex/core splits between the two layers along the Pipe-touching line">
+ <text class="s-t" x="8" y="22">pipelex/core/ — one package, two layers</text>
+
+ <rect class="s-rt" x="8" y="38" width="360" height="150" rx="3" stroke-width="1.5"/>
+ <text class="s-trt" x="26" y="62">RUNTIME — THE VALUE DATA MODEL</text>
+ <text class="s-ts" x="26" y="86">concepts/ · domains/ · memory/ · stuffs/</text>
+ <text class="s-ts" x="26" y="104">pipes/inputs/ · pipes/stuff_spec/</text>
+ <text class="s-tm" x="26" y="132">Takes resolution as a parameter:</text>
+ <text class="s-ts" x="26" y="150">concept_provider: ConceptProviderAbstract</text>
+ <text class="s-tok" x="26" y="174">6 entry points measured 50 → 0</text>
+
+ <rect class="s-it" x="392" y="38" width="360" height="150" rx="3" stroke-width="1.5"/>
+ <text class="s-tit" x="410" y="62">INTERPRETER — EVERYTHING NAMING A PIPE</text>
+ <text class="s-ts" x="410" y="86">registry_models · bundles/ · interpreter/</text>
+ <text class="s-ts" x="410" y="104">pipes/pipe_abstract · pipes/rendering/</text>
+ <text class="s-tm" x="410" y="132">Irreducible: a discriminated union over</text>
+ <text class="s-tm" x="410" y="150">every pipe kind, the base class every pipe</text>
+ <text class="s-tm" x="410" y="168">extends, the registry of pipe kinds.</text>
+
+ <path class="s-okline" d="M392 113 H370" stroke-width="2" marker-end="url(#ar3)"/>
+ <text class="s-tm" x="381" y="106" text-anchor="middle">injects</text>
+
+ <rect class="s-box" x="8" y="200" width="744" height="42" rx="3"/>
+ <text class="s-t" x="28" y="226">The honest boundary is not “pipelex.core” — it is: if it names a Pipe, it is interpreter-layer.</text>
+
+ <defs>
+ <marker id="ar3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0 0 L10 5 L0 10 z" fill="var(--rt-line)"/>
+ </marker>
+ </defs>
+</svg>
+<figcaption>Threading a provider through <code>PipeFactory.make_from_blueprint</code> as well was considered and rejected: 337 call sites for <em>no</em> additional closure property, since <code>pipe_factory</code> stays interpreter-bound either way.</figcaption>
+</figure>
+
+<h2 id="s5"><span class="n">05</span> What we gained</h2>
+
+<h3>Import cost — the measurable part</h3>
+
+<figure>
+<svg viewBox="0 0 760 210" role="img" aria-label="Before and after: modules, SLOC and interpreter modules in the runtime closure">
+ <text class="s-tm" x="8" y="18">runtime closure · entry point pipelex.cogt.content_generation.content_generator</text>
+
+ <text class="s-ts" x="8" y="52">modules</text>
+ <rect class="s-barwas" x="110" y="38" width="360" height="14" rx="2"/>
+ <text class="s-tm" x="480" y="50">357 before</text>
+ <rect class="s-barnow" x="110" y="58" width="271" height="14" rx="2"/>
+ <text class="s-tok" x="480" y="70">269 after</text>
+
+ <text class="s-ts" x="8" y="116">SLOC</text>
+ <rect class="s-barwas" x="110" y="102" width="360" height="14" rx="2"/>
+ <text class="s-tm" x="480" y="114">29,193 before</text>
+ <rect class="s-barnow" x="110" y="122" width="250" height="14" rx="2"/>
+ <text class="s-tok" x="480" y="134">20,299 after</text>
+
+ <text class="s-ts" x="8" y="180">interpreter</text>
+ <rect class="s-barwas" x="110" y="166" width="360" height="14" rx="2"/>
+ <text class="s-tm" x="480" y="178">50 before</text>
+ <rect class="s-barnow" x="110" y="186" width="4" height="14" rx="2"/>
+ <text class="s-tok" x="480" y="198">0 after — the headline property</text>
+</svg>
+<figcaption>Reproduced on the branch tip on 2026-07-27: <strong>269 modules / 20,299 SLOC / 0 interpreter modules</strong>. The closure test runs this measurement over eight entry points on every CI run.</figcaption>
+</figure>
+
+<p>Be precise about what this buys: <strong>it does not make pipeline execution faster.</strong> It removes import cost from every consumer that never needed the interpreter. Measured today as a proxy — adding <code>pipelex.interpreter_hub</code> on top of the runtime entry point costs <strong>+90 pipelex modules and ~50 ms</strong> of in-process import time (median of seven runs, warm cache, one machine). Before the split that was unavoidable: every caller of <code>get_console()</code> paid it. Who collects the refund:</p>
+
+<ul>
+ <li><code>pipelex-api</code>'s health and version paths, and any cold container or Lambda start that imports the runtime before serving.</li>
+ <li>The CLI's fast paths — <code>--version</code>, <code>which</code>, anything that does not load a method.</li>
+ <li>Every plugin registration module, which by definition runs at import time inside a host process.</li>
+ <li>The test suite: hundreds of unit tests that touch the runtime no longer parse and execute ~9,000 lines of interpreter to do it.</li>
+</ul>
+
+<p class="note">On that timing figure: the before/after wall clock was never captured at the base commit, so the number above is measured <em>today</em> as “what the interpreter half costs to load”. The durable, reproducible numbers are the module and SLOC counts.</p>
+
+<h3>Working on this codebase with agents</h3>
+
+<div class="cards">
+ <div class="card">
+ <h3>Blast radius is now structural</h3>
+ <p>A change to a pipe blueprint's module-level imports <strong>cannot</strong> perturb the import graph of <code>cogt</code> any more. Before, it could — silently. That is the difference between “please be careful” and “the arrow does not exist”.</p>
+ </div>
+ <div class="card">
+ <h3>Failures are loud and local</h3>
+ <p>Deleting <code>pipelex.hub</code> outright means stale knowledge — a model's memory of the old API, a copied snippet, an old branch — produces an <strong>ImportError at import time</strong>, not a wrong-layer resolution that works until it doesn't.</p>
+ </div>
+ <div class="card">
+ <h3>Placement has a mechanical answer</h3>
+ <p>“Which hub does this new accessor go on?” used to be taste. Now it is two partition tables plus one rule — <em>if it names a Pipe, it is interpreter-layer</em> — and getting it wrong fails a check rather than a review.</p>
+ </div>
+ <div class="card">
+ <h3>String references are caught too</h3>
+ <p>The guard scans <em>string constants</em>, not just imports. That is the class of edit tooling gets wrong most often: <code>mocker.patch("pipelex.hub.get_console", …)</code> broke 36 tests once, and is invisible to every import-graph tool and to pyright.</p>
+ </div>
+ <div class="card">
+ <h3>Smaller closure, smaller context</h3>
+ <p>Reasoning about the runtime layer no longer means reasoning about the interpreter. Fewer modules in the graph is fewer files to read before an answer is trustworthy.</p>
+ </div>
+ <div class="card">
+ <h3>The property is tested, not just the rule</h3>
+ <p>A stray import elsewhere can re-drag the interpreter without touching a hub. The subprocess closure test catches exactly that, and prints the offending modules so the shortest path to the fix is in the failure message.</p>
+ </div>
+</div>
+
+<h3>Cleaner dev docs and a real plugin contract</h3>
+
+<ul>
+ <li><strong>The partition tables are the contract.</strong> A plugin author or external consumer reads one of two scoped tables instead of a 300-symbol god module. Placement is decided by <em>kind</em>, not by in-tree usage — which is why accessors with no in-tree importers were kept rather than deleted: several are live external plugin contract.</li>
+ <li><strong>Plugin registries are filed by layer.</strong> <code>inference_backend</code>, <code>model_lister</code>, <code>orchestrator</code>, <code>bundle_validator</code>, <code>storage_provider</code>, <code>secrets_provider</code> are runtime-layer; the PipeFunc executor and its registry are interpreter-layer, because their protocol lives in <code>pipe_operators/func/</code>. That call is recorded with its underlying inversion rather than quietly rounded off.</li>
+ <li><strong>The spec is shipped, not tribal.</strong> <code>docs/contribute/hub-layering.md</code> follows the shape the repo already uses for a mechanically-enforced convention, and <code>docs/under-the-hood/architecture-overview.md</code> names the boundary. A <code>hub-layering-convention</code> drift contract keeps both from rotting: touch the guard or either hub, and you owe a review.</li>
+ <li><strong>One outward-facing claim, now true and pinned:</strong> <em>importing the Pipelex runtime loads zero interpreter modules</em> — the inference engine does not know the MTHDS language exists, so it can be embedded without loading a line of the interpreter.</li>
+ <li><strong>Two documented-but-inert APIs were found and fixed in passing.</strong> <code>docs/advanced/observer-provider-injection.md</code> documented <code>hub.set_observer()</code> as the supported way to register an observer — the value was written and never read, so anyone following that page got a silently ignored observer. That page and <code>docs/advanced/index.md</code>, which showed a bare hub being hand-constructed and was equally inert, were rewritten to the mechanism that actually works.</li>
+</ul>
+
+<h3>Placement fixes that fell out of the same measurement</h3>
+
+<div class="scroll">
+<table>
+<thead><tr><th>Moved</th><th>From → to</th><th>Effect</th></tr></thead>
+<tbody>
+<tr><td><code>JobMetadata</code>, <code>JobCategory</code>, <code>UnitJobId</code>, <code>TraceContext</code>, <code>DataInclusionConfig</code></td><td><code>pipeline/</code> and <code>graph/</code> → <code>pipelex/system/</code></td><td><code>cogt → pipeline</code>: 18 statements → <strong>0</strong>. <code>TraceContext</code> had to travel with <code>JobMetadata</code> — leaving it behind would only have renamed the inversion. The TOML shape is unchanged.</td></tr>
+<tr><td><code>TextFormat</code>, <code>TemplatingStyle</code>, <code>TagStyle</code>, <code>TemplateCategory</code></td><td><code>cogt/templating/</code> → <code>tools/templating/</code> and <code>tools/jinja2/</code></td><td><code>tools → cogt</code>: 15 → <strong>3</strong>, the pdf renderer only. They split across two packages on purpose: <code>TemplateCategory</code>'s payload is jinja2 filters, so filing it beside the others would have created a cycle inside one layer.</td></tr>
+</tbody>
+</table>
+</div>
+
+<details>
+<summary>Reproduce the measurement yourself</summary>
+<pre><code>.venv/bin/python - &lt;&lt;'PY'
+import sys
+from pathlib import Path
+
+import pipelex.cogt.content_generation.content_generator # noqa: F401
+
+INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
+loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
+interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
+sloc = 0
+for mod in loaded.values():
+ file = getattr(mod, "__file__", None)
+ if file:
+ sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
+print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
+print("offenders:", interpreter)
+PY</code></pre>
+<p>Swap the imported module to measure any other entry point. If <code>interpreter modules</code> is not 0, the offenders it prints are what to fix — the shortest import path to one of them is the defect.</p>
+</details>
+
+<h2 id="s6"><span class="n">06</span> How it stays true</h2>
+
+<figure>
+<svg viewBox="0 0 760 230" role="img" aria-label="Three gates: the AST guard, the closure test, and where they run">
+ <rect class="s-box" x="8" y="30" width="232" height="130" rx="3" stroke-width="1.5"/>
+ <text class="s-t" x="26" y="54">1 · The guard</text>
+ <text class="s-ts" x="26" y="74">pipelex-dev check-hub-layering</text>
+ <text class="s-tm" x="26" y="98">Rule A — no runtime-layer module</text>
+ <text class="s-tm" x="26" y="114">may import pipelex.interpreter_hub</text>
+ <text class="s-tm" x="26" y="136">Rule B — no module anywhere may</text>
+ <text class="s-tm" x="26" y="152">reference pipelex.hub (deleted)</text>
+
+ <path class="s-line" d="M244 95 H272" stroke-width="1.5" marker-end="url(#ar4)"/>
+
+ <rect class="s-box" x="276" y="30" width="232" height="130" rx="3" stroke-width="1.5"/>
+ <text class="s-t" x="294" y="54">2 · The closure test</text>
+ <text class="s-ts" x="294" y="74">test_runtime_layer_import_closure</text>
+ <text class="s-tm" x="294" y="98">8 runtime entry points, each in a</text>
+ <text class="s-tm" x="294" y="114">subprocess → 0 interpreter modules</text>
+ <text class="s-tm" x="294" y="136">+ 1 dirty negative control, so the</text>
+ <text class="s-tm" x="294" y="152">suite can never pass vacuously</text>
+
+ <path class="s-line" d="M512 95 H540" stroke-width="1.5" marker-end="url(#ar4)"/>
+
+ <rect class="s-box" x="544" y="30" width="208" height="130" rx="3" stroke-width="1.5"/>
+ <text class="s-t" x="562" y="54">3 · Where it runs</text>
+ <text class="s-ts" x="562" y="74">make agent-check</text>
+ <text class="s-ts" x="562" y="92">make check</text>
+ <text class="s-ts" x="562" y="110">CI job lint-hub-layering</text>
+ <text class="s-tm" x="562" y="134">Hard block, empty exception</text>
+ <text class="s-tm" x="562" y="150">list — the tree is compliant</text>
+
+ <rect class="s-box" x="8" y="176" width="744" height="46" rx="3"/>
+ <text class="s-tm" x="26" y="196">Both rules match imports AND bare string literals — importlib, mocker.patch, any config-driven dotted path.</text>
+ <text class="s-tm" x="26" y="214">Carve-outs: if TYPE_CHECKING (layer rule only, receiver must be typing) · inline # hub-layering: ignore</text>
+
+ <defs>
+ <marker id="ar4" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0 0 L10 5 L0 10 z" fill="var(--rule-2)"/>
+ </marker>
+ </defs>
+</svg>
+<figcaption>The lint guards the <em>rule</em>; the closure test guards the <em>property</em>, which is what actually matters and which a stray import elsewhere could break without touching a hub.</figcaption>
+</figure>
+
+<pre><code><span class="cmt"># pipelex/cli/dev_cli/commands/hub_layering_guard.py</span>
+RUNTIME_LAYER_PACKAGES: tuple[str, ...] = (
+ "pipelex.cogt", "pipelex.plugins", "pipelex.reporting", "pipelex.system", "pipelex.tools",
+ "pipelex.runtime_hub", <span class="cmt"># a module, not a package — the rule now covers the hub itself</span>
+ "pipelex.core.concepts", "pipelex.core.domains", "pipelex.core.memory",
+ "pipelex.core.pipes.inputs", "pipelex.core.pipes.stuff_spec", "pipelex.core.stuffs",
+)
+
+INTERPRETER_HUB_MODULE = "pipelex.interpreter_hub" <span class="cmt"># rule A: forbidden above</span>
+DELETED_HUB_MODULE = "pipelex.hub" # hub-layering: ignore <span class="cmt"># rule B: dead everywhere, tests/ included</span></code></pre>
+
+<details>
+<summary>Two things the guard taught us, worth stealing for the next one</summary>
+<p><strong>Generalizing the string check is what made it work.</strong> The plan framed it as an <code>importlib.import_module</code> special case. Scanning <em>every</em> string constant for an exact-or-boundary match on the module path catches <code>importlib</code>, <code>mocker.patch</code>, <code>pkgutil.resolve_name</code> and any config-driven dotted path in one mechanism, with no call-site special-casing. Matching is exact-or-dotted-prefix, which is why <code>pipelex.runtime_hub</code> does not match <code>pipelex.hub</code>, and why a docstring that merely <em>mentions</em> a module is not a reference.</p>
+<p><strong>A negative control has to assert the message, not the exit code.</strong> The closure test's dirty entry point exits 1 for a second reason — <code>pipelex.interpreter_hub in sys.modules</code> — whatever the offender predicate does. An exit-code-only control would have passed over a completely broken detector, leaving all eight real entry points green and vacuous forever. It asserts the offender message too. Confirmed by mutation: typo the package set, and the control fails while everything else stays green.</p>
+<p>Every item in the test-hardening pass was verified <em>by mutation</em> — remove the pinned behavior, watch the new test fail, revert. Watching a new test go green proves nothing about what it pins, and two of those items existed precisely because an existing test appeared to pin something it did not.</p>
+</details>
+
+<h2 id="s7"><span class="n">07</span> What this means for you</h2>
+
+<h3>Picking a hub</h3>
+<div class="scroll">
+<table>
+<thead><tr><th>You need…</th><th>Import from</th></tr></thead>
+<tbody>
+<tr><td>config, console, secrets, storage, telemetry / OTel tracer, class registry, func registry</td><td><code>pipelex.runtime_hub</code></td></tr>
+<tr><td>models manager, model deck, SDK clients, inference manager, LLM / img-gen / extract workers, content generator</td><td><code>pipelex.runtime_hub</code></td></tr>
+<tr><td>report delegate, run mode, event log, and the plugin registries (backend, model lister, orchestrator, bundle validator, storage, secrets)</td><td><code>pipelex.runtime_hub</code></td></tr>
+<tr><td>library manager, concept / domain / pipe lookups, the current-library contextvars, library dirs</td><td><code>pipelex.interpreter_hub</code></td></tr>
+<tr><td>pipe router, pipe run, pipeline manager, the PipeFunc executor and its registry</td><td><code>pipelex.interpreter_hub</code></td></tr>
+</tbody>
+</table>
+</div>
+
+<h3>What failure looks like</h3>
+<div class="scroll">
+<table>
+<thead><tr><th>You did</th><th>You get</th></tr></thead>
+<tbody>
+<tr><td><code>from pipelex.hub import get_console</code></td><td><code>ModuleNotFoundError</code> at import time. The module is gone on purpose — pick a half.</td></tr>
+<tr><td>Imported <code>interpreter_hub</code> from a runtime-layer module</td><td><code>make check-hub-layering</code> fails with the file, the line, the kind and the remedy. Also fails <code>make agent-check</code> and the <code>lint-hub-layering</code> CI job.</td></tr>
+<tr><td>Left a <code>"pipelex.hub"</code> string in a <code>mocker.patch</code> target</td><td>Same guard, dead-module rule — inside <code>tests/</code> too.</td></tr>
+<tr><td>Added an import that re-drags the interpreter without touching a hub</td><td><code>tests/unit/pipelex/test_runtime_layer_import_closure.py</code> fails and prints the offending modules.</td></tr>
+<tr><td>Genuinely need an exception</td><td><code>if TYPE_CHECKING:</code> for a type-only import (layer rule only), or an inline <code>&#35; hub-layering: ignore</code> on the statement.</td></tr>
+</tbody>
+</table>
+</div>
+
+<h3>Cross-repo — release-gated, three waves, one pass per repo</h3>
+<p>External repos still import <code>pipelex.hub</code> and break the moment this ships. The sweep is deliberately <strong>not</strong> in PR #1062; it lands with the release, already retargeted to the final names, so each repo is rewritten exactly once.</p>
+
+<div class="scroll">
+<table>
+<thead><tr><th>Wave</th><th>Old</th><th>New</th></tr></thead>
+<tbody>
+<tr><td rowspan="4">1 · the split</td><td><code>from pipelex.hub import &lt;runtime symbol&gt;</code></td><td><code>from pipelex.runtime_hub import …</code></td></tr>
+<tr><td><code>from pipelex.hub import &lt;interpreter symbol&gt;</code></td><td><code>from pipelex.interpreter_hub import …</code></td></tr>
+<tr><td><code>get_pipelex_hub</code></td><td><code>get_runtime_hub</code> <strong>or</strong> <code>get_interpreter_hub</code> — pick the container the call site meant</td></tr>
+<tr><td><code>PipelexHub</code></td><td><code>RuntimeHub</code> <strong>or</strong> <code>InterpreterHub</code></td></tr>
+<tr><td rowspan="4">2 · moved types</td><td><code>pipelex.pipeline.job_metadata</code></td><td><code>pipelex.system.job_metadata</code></td></tr>
+<tr><td><code>pipelex.graph.trace_context</code> · <code>pipelex.graph.graph_config:DataInclusionConfig</code></td><td><code>pipelex.system.trace_context</code> · <code>pipelex.system.data_inclusion_config</code></td></tr>
+<tr><td><code>pipelex.pipeline.exceptions:JobMetadataError</code></td><td><code>pipelex.system.exceptions</code></td></tr>
+<tr><td><code>pipelex.cogt.templating.{text_format,templating_style}</code> · <code>…template_category</code></td><td><code>pipelex.tools.templating.…</code> · <code>pipelex.tools.jinja2.template_category</code></td></tr>
+<tr><td rowspan="2">3 · moves + signatures</td><td><code>pipelex.codegen.resolved_fields</code> · <code>core.pipes.inputs.input_renderer</code> · <code>core.pipes.output.output_renderer</code></td><td><code>core.concepts.resolved_fields</code> · <code>core.pipes.rendering.{input,output}_renderer</code></td></tr>
+<tr><td><code>StuffFactory.make_stuff_from_stuff_content_or_data</code>, <code>WorkingMemoryFactory.make_from_pipeline_inputs</code>, <code>InputShaper.shape</code>, <code>InputStuffSpecsFactory.make_from_*</code>, <code>StuffSpecFactory.make_from_blueprint</code></td><td>all now require <code>concept_provider=get_concept_library()</code></td></tr>
+</tbody>
+</table>
+</div>
+
+<details>
+<summary>Which repos, and which one bites first</summary>
+<div class="scroll">
+<table>
+<thead><tr><th>Repo</th><th><code>pipelex.hub</code> files</th><th>moved-type files</th><th>note</th></tr></thead>
+<tbody>
+<tr><td><code>pipelex-temporal</code> (private)</td><td>35</td><td>22</td><td>Heaviest consumer. Runner and worker must roll forward together — worth a changelog sentence.</td></tr>
+<tr><td><code>pipelex-mistralai-workflows</code></td><td>11</td><td>6</td><td><code>set_pipe_router</code> / <code>teardown_current_pipe_router</code> / <code>scoped_pipe_router</code> are documented as depended upon here — a contract change to <em>announce</em>, not just make.</td></tr>
+<tr><td><code>pipelex-api</code></td><td>9</td><td>1</td><td></td></tr>
+<tr><td><code>pipelex-transport</code></td><td>8 (2 production)</td><td>7</td><td><strong>The sharp one.</strong> <code>bridge.py</code> calls <code>WorkingMemoryFactory.make_from_pipeline_inputs</code> without the now-required <code>concept_provider</code> — the only production call site of a changed signature outside this repo. Also missing from the workspace repo table, which is why it was missed.</td></tr>
+<tr><td><code>pipelex-daytona-sandbox</code></td><td>1</td><td>3</td><td>An entry-point plugin, so it fails inside a <em>host</em> pipelex process at registration, not in its own tests.</td></tr>
+<tr><td><code>pipelex-demo-mistral</code> · <code>pipelex-demo-vibe</code></td><td>9 each</td><td>5 each</td><td>Example workflows call the changed signatures.</td></tr>
+<tr><td><code>pipelex-cookbook</code> · <code>cocode</code></td><td>2 each</td><td>—</td><td></td></tr>
+<tr><td><code>conformance</code> + <code>docs/specs/</code></td><td>—</td><td>1</td><td><code>docs/specs/pipelex-transport-boundary.md</code> §A declares <code>pipelex.hub</code> a stable cross-boundary seam, verified by an <em>active</em> conformance test. Spec and test move in lockstep with the sweep, then <code>make check-spec-links</code>.</td></tr>
+</tbody>
+</table>
+</div>
+<p>Clean, no action: <code>pipelex-worker</code>, <code>pipelex-starter-python</code>, <code>pipelex-relay</code>, <code>n8n-nodes-pipelex</code>, <code>sandbox</code>. Version-pinned and therefore safe for now: <code>pipelex-workshop</code>, <code>pipelex-demos</code>, <code>pipelex-demo-frostbeam</code>.</p>
+</details>
+
+<h2 id="s8"><span class="n">08</span> Known limits — stated, not hidden</h2>
+
+<ul>
+ <li><strong>The layer rule is enforced only one hop deep.</strong> The guard checks direct imports, so a runtime-layer module can reach <code>interpreter_hub</code> transitively with both gates green. Blast radius measured exactly: <strong>4 of 476</strong> declared runtime-layer modules, all in <code>pipelex.plugins</code> — the other ten declared packages are clean across 345 modules — via three transitive routes. <em>The headline property is not damaged</em>: the inference layer and <code>runtime_hub</code> still measure 0 and never reach the breaching modules. The remedy is decided — split the built-in plugins by layer, give the two interpreter-touching ones a single interpreter-side home, and teach the guard the transitive check. Its own PR after #1062 merges; simulated at 0 of 128 breaching once three modules relocate.</li>
+ <li><strong>Known inversions, named so the docs stay honest.</strong> Two <code>plugins/</code> modules import from <code>pipe_operators/</code> and one from <code>pipeline/</code>. They import no hub, so the guard does not flag them — which is exactly why they are written down. Remaining measured cross-layer edges: <code>cogt → core</code> (21), <code>system → cogt</code> (7), <code>plugins → runtime_bridge</code> (6), <code>tools → cogt</code> (3), and one genuine wart, <code>cogt/model_backends/model_lists.py</code> importing a CLI exception.</li>
+ <li><strong>A general layering ratchet is a sequel, not this change.</strong> “No runtime module may import any interpreter module, with an allowlist” is a much cheaper argument now that the two biggest clusters are gone — but it is a bigger change than this one should carry.</li>
+ <li><strong>One eager optional-SDK import is out of scope but worth knowing:</strong> <code>tracing/event_log_factory.py</code> imports the DynamoDB event log at module level, which runs a module-level <code>try: import boto3</code>, so boto3 and friends load in every process that touches the tracing factory. Three-line fix, entirely independent of this work.</li>
+</ul>
+
+<footer>
+ <p>Branch <code>refactor/Hub</code> off <code>dev</code> at v0.40.0 · PR <a href="https://github.com/Pipelex/pipelex/pull/1062">#1062</a> open, follow-ups merged via <a href="https://github.com/Pipelex/pipelex/pull/1063">#1063</a> · gates green: <code>make agent-check</code>, full <code>make agent-test</code>, <code>make drift-check</code> · numbers re-measured 2026-07-27 on the branch tip. The shipped specification of the boundary is <code>docs/contribute/hub-layering.md</code>; the executable tracker with every checkpoint record is <code>TODOS.md</code>.</p>
+</footer>
+
+</div>
diff --git a/wip/hub/hub-split-refactor.md b/wip/hub/hub-split-refactor.md
new file mode 100644
index 000000000..60d86c773
--- /dev/null
+++ b/wip/hub/hub-split-refactor.md
@@ -0,0 +1,139 @@
+# Splitting `pipelex.hub` into a service hub and a method hub
+
+**Status:** plan, drafted 2026-07-26 against the v0.40.0 base (`dev` at `f23fda7a0`). Nothing implemented. Every number below was measured, and the recipe to reproduce it is in this document — no external tooling required.
+
+Branch off `dev` (e.g. `refactor/Hub-split`), normal PR back to `dev`.
+
+## The problem, in one paragraph
+
+`pipelex/hub.py` is a single god-object that brokers *every* cross-cutting dependency in the codebase — the config, the console, secrets, storage, the class registry, the model deck and inference workers, the plugin registries, and also the concept/domain/pipe libraries, the pipe router, the pipeline manager. Because it is one module, importing it for `get_console()` also imports the entire method-interpretation layer. Measured: `import pipelex.hub` alone loads **323 modules / 26,288 SLOC**, including all of `libraries`, `pipe_operators`, `pipe_controllers`, and `codegen`. Every path from the inference layer to the interpreter runs through it — traced, `pipelex.cogt.content_generation.content_generator` reaches `pipe_controllers`, `libraries`, `pipe_operators`, and `codegen` *only* via `pipelex.hub`, never independently.
+
+Four module-level imports in `hub.py`, all serving type annotations on getters, are the whole cause:
+
+```
+from pipelex.libraries.library import Library # CONCRETE — drags concept_library, pipe_controllers, and via concept_factory → codegen
+from pipelex.libraries.library_manager_abstract import ... # → core.bundles.pipelex_bundle_blueprint → all twelve pipe blueprints
+from pipelex.core.pipes.pipe_abstract import PipeAbstract # → graph.graph_tracer_manager
+from pipelex.core.concepts.concept import Concept # the cycle that forces three importlib string-literal hacks
+```
+
+## Why this is worth doing
+
+1. **It removes a real import cycle and the three hacks that paper over it.** `core/concepts/concept.py`, `concept_factory.py`, and `structure_generation/generator.py` each carry an identical `importlib.import_module("pipelex.hub")` function with the comment *"Lazy import to break circular dependency with hub.py"*. All three want exactly one symbol: `get_class_registry` — a low-level one. A hub that does not import `Concept` has no cycle with `concept.py`, so all three become plain top-level imports. These hacks are also invisible to every import lint and to pyright's module graph, so they are the worst kind of coupling: real, load-bearing, and unanalyzable.
+
+2. **It makes a layer boundary that already exists become enforceable.** Measured across all 309 files that import the hub: 134 use only low-level symbols, 139 use only high-level ones, and just **36 straddle**. Every package below `core` — `cogt`, `tools`, `system`, `plugins`, `reporting` — uses low-level symbols *exclusively*, today, with zero exceptions. The architecture is already layered; the hub is the one place the layering is not expressible, and therefore the one place it silently rots.
+
+3. **It replaces one god-object with two objects that have genuinely different lifecycles.** The low half is process-scoped: constructed once at boot from config + plugin registration, never changes. The high half is *library-scoped* — it already has contextvar machinery for exactly that (`set_current_library`, `clear_current_library`, `scoped_current_library`). Today those two lifecycles share one container and one setup path, which is why boot interleaves `set_library_manager` between `set_secrets_provider` and `set_models_manager` with no way to tell that the ordering is meaningful.
+
+4. **It cuts import cost for every consumer.** Anything that wants the console, a secret, or the model deck currently pays for the interpreter. That is `pipelex-api`'s health check, the CLI's `--version`, every plugin's registration module, and every test that touches `get_console`.
+
+5. **It reduces the blast radius of changes to the interpreter.** Today a change to a pipe blueprint's module-level imports can perturb the import graph of `cogt`. After the split it structurally cannot.
+
+## Target shape
+
+Delete `pipelex/hub.py`. Create two modules, each with its own container class and its own module-level accessor functions:
+
+**`pipelex/runtime_hub.py`** — process-scoped infrastructure. Config, console, secrets provider + `get_secret`, class registry, func registry, storage provider, telemetry manager + OTel tracer, models manager + model deck, SDK client manager, inference manager + the three worker getters, content generator (+ its scoped override), report delegate, the isolated-execution probe, the dry-run-forced flag, the event-log override, and the plugin registries (`inference_backend`, `model_lister`, `orchestrator`, `bundle_validator`, `storage_provider`, `secrets_provider`).
+
+**`pipelex/interpreter_hub.py`** — library-scoped method machinery. Library manager + `Library`, the domain/concept/pipe libraries and their lookups (`get_required_pipe`, `get_native_concept`, …), the current-library contextvar family (`set_current_library`, `scoped_current_library`, `resolve_library_dirs`, `get_default_library_dirs`), the pipe router (+ scoped override), pipe run, pipeline manager, observer, and the pipe-func executor (+ its registry and scoped override).
+
+`interpreter_hub` imports `runtime_hub`; **`runtime_hub` must never import `interpreter_hub`.** That single arrow is the whole architecture, and it is what the guard checks.
+
+Deleting the `pipelex.hub` name entirely — rather than keeping it as an alias for either half — is deliberate: every stale import then fails loudly at import time instead of silently resolving to the wrong layer. It is also consistent with the no-backward-compatibility principle.
+
+## Decisions to settle before coding
+
+- **D1 — module names.** Recommended: `pipelex/runtime_hub.py` and `pipelex/interpreter_hub.py`, both flat at the package root, `pipelex/hub.py` deleted. Alternatives considered: keeping `pipelex/hub.py` for one half (rejected — a stale import would silently succeed); `library_hub` for the high one (rejected — it also holds the router, the runner, and the pipeline manager); a `pipelex/hubs/` package (workable, but `pipelex.hubs.services` reads worse than `pipelex.runtime_hub` at 300+ call sites). Note for review: `interpreter_hub` borrows MTHDS's noun for a runtime container — acceptable here because the object genuinely holds the loaded method's libraries, but worth a conscious nod given the brand-boundary rule.
+- **D2 — one container or two.** Recommended: **two** (`RuntimeHub` and `InterpreterHub`, each its own singleton). One container would have to live in the low module, which forces every high-level slot to a quoted `TYPE_CHECKING` annotation — that keeps the god-object and adds a fig leaf. Two is affordable: `PipelexHub()` is constructed in exactly two production sites (`pipelex/pipelex.py:120`, `pipelex/cli/commands/doctor_cmd.py:774`) and three test sites, and `get_pipelex_hub`/`set_pipelex_hub` appear in five files total.
+- **D3 — where `get_pipe_func_executor_registry` lands.** It is a plugin registry (low by kind) whose protocol lives in `pipe_operators/func/` (high by location). Recommended: **high**, with the underlying inversion — `pipelex/plugins/pipe_func_executor_registry.py` importing from `pipe_operators/` — recorded as a follow-up rather than fixed here.
+- **D4 — does `core/` join the low layer in this change?** Recommended: **no, not in phase 1.** Five `core/` modules use high-hub symbols (`stuff_factory`, `memory/input_shaper`, `pipes/stuff_spec/stuff_spec_factory`, `pipes/inputs/input_stuff_specs_factory`, `pipes/output/output_renderer`); converting them means passing resolved concepts in rather than looking them up, which is design work, not mechanical. Phase 4 does it; the guard's low-layer set widens to include those modules only when it lands.
+
+## Phases
+
+### Phase 0 — declare the boundary
+
+- [ ] 0.1 Settle D1–D4.
+- [ ] 0.2 Take the **baseline measurement** below and record it in this file, so phase 1 has a before to compare against.
+- [ ] 0.3 Write `docs/contribute/hub-layering.md` — the two hubs, what lives in each, the one-arrow rule, how the guard enforces it, and how to record an exception. Model it on `docs/contribute/keyword-only-arguments.md`, which is the repo's established shape for a mechanically-enforced convention.
+- [ ] 0.4 Update `docs/under-the-hood/architecture-overview.md` to name the boundary (it currently walks `pipe_controllers` → `pipe_operators` → `core` → `cogt` → `plugins` without ever mentioning the hub).
+
+### Phase 1 — the split
+
+- [ ] 1.1 Create `pipelex/runtime_hub.py`: the `RuntimeHub` container + the low accessors. Verify its module-level imports name nothing from `libraries`, `pipe_operators`, `pipe_controllers`, `codegen`, `builder`, `core.bundles`, `core.concepts`, or `core.pipes`.
+- [ ] 1.2 Create `pipelex/interpreter_hub.py`: the `InterpreterHub` container + the high accessors, importing `runtime_hub` for anything it needs.
+- [ ] 1.3 Delete `pipelex/hub.py`.
+- [ ] 1.4 Rewrite the call sites — 309 files, 29 of them with parenthesized multi-line import blocks. Script the rewrite from the symbol→module partition, then hand-review the 36 straddling files, which are the only ones that gain a second import line.
+- [ ] 1.5 Re-wire boot: `Pipelex.setup` constructs and populates both hubs; the low one fully before the high one (today the setter calls interleave). Same for `doctor_cmd` and the three test sites.
+- [ ] 1.6 Replace the three `importlib.import_module("pipelex.hub")` hacks in `core/concepts/` with plain `from pipelex.runtime_hub import get_class_registry`, and delete the `_get_class_registry` shims.
+
+**CHECKPOINT H-1** — zero behavior change. Gates: `make agent-check` + **full** `make agent-test` (no test rewrites beyond import lines) + `make drift-check`. Expect the **`cli-docs` drift contract to fire** — 45 CLI files import the hub and `pipelex/cli/**/*.py` is a trigger; review `docs/tools/cli/` and `pipelex/cli/agent_cli/CLAUDE.md`, then `make drift-ack`. Re-take the measurement and record the after.
+
+### Phase 2 — enforce it
+
+- [ ] 2.1 Add `pipelex-dev check-hub-layering` (guard in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`, command in `check_hub_layering_cmd.py`), following the `check-keyword-only` precedent exactly. Rule: a module in the declared low layer may not import `pipelex.interpreter_hub`. It must catch the string-literal `importlib.import_module("pipelex.interpreter_hub")` form too — that is precisely how the current cycle hides.
+- [ ] 2.2 Declare the low layer: `pipelex/tools/**`, `pipelex/system/**`, `pipelex/cogt/**`, `pipelex/plugins/**`, `pipelex/reporting/**`. All five are 100% compliant today, so the guard hard-blocks from day one with an empty exception list.
+- [ ] 2.3 Wire into `make agent-check`, the `make check` aggregate, and CI, with a `chl` alias.
+- [ ] 2.4 Unit tests for the guard (positive, negative, and the `importlib` string form), mirroring `tests/unit/pipelex/cli/dev/test_keyword_only_guard_*.py`.
+- [ ] 2.5 A closure regression test: import `pipelex.cogt.content_generation.content_generator` in a subprocess and assert no `pipelex.libraries.*`, `pipelex.pipe_operators.*`, `pipelex.pipe_controllers.*`, or `pipelex.codegen.*` module is in `sys.modules`. The lint guards the *rule*; this guards the *property*, which is what actually matters and which a future stray import elsewhere could break without touching a hub import.
+
+**CHECKPOINT H-2** — boundary declared, enforced, and regression-tested.
+
+### Phase 3 — the placement residue
+
+Neither of these is coupling; both are types living in the wrong package, and each is independently correct.
+
+- [ ] 3.1 **`JobMetadata`.** It lives in `pipelex/pipeline/job_metadata.py` but is an argument to essentially every cogt call — it accounts for 17 of the 18 `cogt → pipeline` import statements, and it drags `graph.trace_context` → `graph.graph_config` into every closure that touches inference. Move `job_metadata`, and decide whether `trace_context` moves with it or stops depending on `graph_config`. Also move `JobMetadataError` out of `pipeline/exceptions.py` (the sole remaining `cogt → pipeline` edge, in `llm_worker_abstract.py`).
+- [ ] 3.2 **`cogt.templating.*`.** `TemplateCategory`, `TemplatingStyle`, `TextFormat`, and `TagStyle` are imported by eight `tools/jinja2/` and `tools/mermaid/` modules — they are templating primitives sitting under `cogt/`, making `tools` (the intended bottom layer) depend on `cogt`. Decide: move them down to `tools`, or accept `cogt` as below `tools` and document that.
+
+**CHECKPOINT H-3** — placement residue resolved or explicitly deferred with a recorded rationale.
+
+### Phase 4 — `core/` joins the low layer
+
+- [ ] 4.1 Convert the five `core/` straddlers to take resolved concepts/pipes as arguments instead of reaching for `get_concept_library` / `get_native_concept` / `get_required_concept` / `get_required_pipe`. Callers that have a library pass the resolved value; callers that do not are, by construction, in the high layer already.
+- [ ] 4.2 Widen the guard's low layer to include `pipelex/core/**`.
+
+**CHECKPOINT H-4 = done** — update `docs/contribute/hub-layering.md` with the final layer set, and the CHANGELOG with a breaking-change note (`pipelex.hub` is gone; importers must choose `pipelex.runtime_hub` or `pipelex.interpreter_hub`).
+
+## Exit criteria — measured, not asserted
+
+The headline property is that the inference layer must stop importing the interpreter. Measure it directly, from the repo root on a synced venv:
+
+```bash
+.venv/bin/python - <<'PY'
+import sys
+from pathlib import Path
+
+import pipelex.cogt.content_generation.content_generator # noqa: F401
+
+INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}
+loaded = {name: mod for name, mod in sys.modules.items() if name.startswith("pipelex.")}
+interpreter = sorted(n for n in loaded if n.split(".")[1] in INTERPRETER)
+sloc = 0
+for mod in loaded.values():
+ file = getattr(mod, "__file__", None)
+ if file:
+ sloc += sum(1 for line in Path(file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.strip().startswith("#"))
+print(f"pipelex modules: {len(loaded)} | sloc: {sloc} | interpreter modules: {len(interpreter)}")
+print("offenders:", interpreter)
+PY
+```
+
+| | today | target after phase 1 |
+| --- | --- | --- |
+| interpreter modules loaded | 50 | **0** |
+| pipelex modules loaded | 357 | ≤ 260 |
+| SLOC loaded | 29,193 | ≤ 19,000 |
+
+The module/SLOC targets come from importing exactly the types a low-only hub would annotate — 236 modules / 17,683 SLOC, with the interpreter subpackages at zero — plus headroom for cogt's own modules. If phase 1 lands and `interpreter modules` is not 0, the snippet prints the offenders: something imports the interpreter outside the hub, and the shortest import path to it is what to fix. Swap the imported module in the snippet to measure any other entry point (`pipelex.pipelex`, `pipelex.runtime_hub`, …).
+
+## Risks and containment
+
+- **Big mechanical diff (309 files).** Contained by: the rewrite is scriptable from a symbol→module table; `pipelex.hub` ceasing to exist means any missed site is an import error, not a silent wrong-layer resolution; and the full `make agent-test` suite is the zero-behavior-change bar.
+- **Two singletons, two lifecycles, two teardowns.** Contained by the tiny construction surface (five sites total). Watch `Pipelex.teardown` / `teardown_if_needed` and the test fixtures that reset hub state — a half-reset hub between tests is the realistic failure mode, and it shows up as cross-test pollution rather than a clean failure. Worth an explicit "both hubs reset" assertion in the shared fixture.
+- **Cross-repo breakage.** `pipelex.hub` is imported by our plugins and by consumers of the runtime. Grep `pipelex-api/`, `pipelex-worker/`, our orchestrator plugins, and `pipelex-mistralai-workflows/` before merging, and stage the follow-ups as a release-gated sweep. `scoped_pipe_router` / `set_pipe_router` / `teardown_current_pipe_router` are documented as depended upon by our Mistral Workflows plugin, so their new home is a published contract change.
+- **`plugins/` reaching up.** `plugins/pipe_func/pipe_func_plugin.py` and `plugins/pipe_func_executor_registry.py` import from `pipe_operators/`, and `plugins/direct/direct_plugin.py` from `pipeline/`. These do not import the hub, so the guard will not flag them — but they mean "plugins is a low layer" is not yet unconditionally true. Named here so the claim in the docs stays honest; fixing them is out of scope.
+
+## Explicitly out of scope
+
+- **A general layering ratchet** ("no low module may import any high module", with an allowlist). The measured inversion set is real but larger than this change should carry — `tools → cogt` (15 statements), `cogt → core` (21), `system → cogt` (8), `plugins → runtime_bridge` (6), and one genuine wart, `cogt/model_backends/model_lists.py` importing `pipelex.cli.exceptions.PipelexCLIError`. Phase 3 removes the two biggest clusters; the general rule is a sequel worth considering once they are gone.
+- **Eager optional-SDK imports.** `pipelex/tracing/event_log_factory.py` imports `dynamodb_event_log` at module level, which runs a module-level `try: import boto3`, so `boto3`/`botocore`/`jmespath`/`dateutil`/`six` load in every process that touches the tracing factory — including runs that will never touch DynamoDB. A three-line fix (import `DynamoDBEventLog` inside the factory branch, the pattern already used for `pypdfium2` in `cogt/content_generation/render_generate.py`), entirely independent of this plan. Note that most other heavy roots (`posthog`, `pypdfium2`, `pillow`, `polyfactory`, `datamodel-code-generator`) are **base** dependencies, not extras — so they are not the same kind of finding.
diff --git a/wip/hub/layer-and-hub-renaming.md b/wip/hub/layer-and-hub-renaming.md
new file mode 100644
index 000000000..bbb5aefc5
--- /dev/null
+++ b/wip/hub/layer-and-hub-renaming.md
@@ -0,0 +1,214 @@
+# Renaming the layers and the hubs — `runtime` / `interpreter`
+
+**Status: EXECUTED.** Landed as its own commit after H-4, with all three gates green. The outcome record — what the plan got right, the two places it under-specified, and the judgment calls made while sweeping the docs — is in [`TODOS.md` → The runtime/interpreter rename, record](../../TODOS.md#the-runtimeinterpreter-rename--record). This document stays as the decision record: it is the *why*, and its old→new tables are deliberately not swept.
+
+Two corrections to the mechanical plan below, for anyone reading it as a template:
+
+- **§2's "rewrite via `ast`, not regex" did not apply.** That warning was inherited from Phase 1, which *split* a module and so had to classify each imported symbol. A 1:1 rename has no classification step, so the safe method is a whole-word audit (enumerate every word in `pipelex/` and `tests/` containing each token, confirm every hit should change) followed by substring replacement and a re-parse of every file. Token-based sweeping also catches the string literals for free, rather than needing §2's separate grep.
+- **§4 and §5 split a pair that must move together.** §4 renames `HubLayeringViolationKind`'s members; §5 lists the test's constants and patch targets but not those members' *references* in `test_hub_layering_guard.py`. Renaming one without the other left 7 failing tests.
+
+Decided by Louis on 2026-07-26, at the close of the hub-split refactor, after challenging the naming that Phases 0–4 shipped. This document is the record of *what* was decided and *why*, plus the mechanical plan. Read [Why](#why-the-current-names-are-wrong) before executing — the rationale is what stops a future session relitigating this or half-applying it.
+
+## The decision
+
+| | was | becomes |
+| --- | --- | --- |
+| the low layer | "low layer" | **the runtime layer** |
+| the high layer | "high layer" (mostly unnamed) | **the interpreter layer** |
+| the low hub | `pipelex/service_hub.py` · `ServiceHub` | `pipelex/runtime_hub.py` · **`RuntimeHub`** |
+| the high hub | `pipelex/method_hub.py` · `MethodHub` | `pipelex/interpreter_hub.py` · **`InterpreterHub`** |
+
+The one rule, restated — and note it now needs no gloss:
+
+> **The interpreter hub may import the runtime hub. The runtime hub must never import the interpreter hub.**
+
+The headline property, restated in the same vocabulary:
+
+> **Importing the Pipelex runtime loads zero interpreter modules.**
+
+That second sentence is both the measurement the closure test pins and the outward-facing claim: *the inference engine does not know the MTHDS language exists — you can embed it without loading a line of the interpreter.*
+
+## Why the current names are wrong
+
+### "Low" / "high" — the tell is that only one side got a name
+
+Low/high is fine for a *lint* (the guard checks arrow direction, and direction is relational). It is wrong as the *conceptual* vocabulary, for three reasons:
+
+1. **Only one side was ever enumerated**, so the other side has no handle. Across the Phase 3 and Phase 4 docs the same concept got coined fresh every time it was needed: "the Pipe-touching remainder", "the high half", "the interpreter". When every author invents a term, the term is missing.
+2. **"Low-level" connotes primitive / plumbing / the boring part.** That is exactly backwards: the low half is the inference engine, arguably the most valuable code in the repo.
+3. **It is contentless.** "Our low layer does not import our high layer" describes our dependency graph. It tells a reader nothing about what either layer *is*, and it sells nothing.
+
+**The codebase had already converged on the right word for one side and nobody noticed.** The measurement snippet, the closure test and the guard docstrings all say *interpreter* (`INTERPRETER = {"libraries", "pipe_operators", "pipe_controllers", "codegen", "builder"}`), and `pipelex/core/interpreter/` exists. Only the guard identifiers and the doc headings still said "high".
+
+### Rejected alternatives for the low layer, with reasons
+
+Recording these so they are not re-proposed:
+
+- **`inference`** — a subset masquerading as the whole. `tools`, `system`, `reporting` and the entire value data model are not inference. It also collides with live usage: the docs and closure test already say "the inference layer" to mean `cogt` specifically ("importing the inference layer must not load the interpreter"). Widening the term makes that sentence ambiguous.
+- **`INTERPRETER_FREE_*`** — defined by exclusion. Louis' objection, and correct: a layer should be named for what it is.
+- **`foundation`** — genuinely viable, and the fallback if the nesting cost below ever bites. Positive, no collision, sells fine. Passed over only because it is less informative than `runtime` and does not share a word with the hub.
+- **`engine`** — same defect as `inference`: console, secrets, storage and the value data model are not engine.
+- **`platform`** — collides with `pipelex-platform`, our hosted CRUD API.
+- **`core`** — catastrophic: `pipelex/core/` exists and *straddles both layers*.
+- **`kernel`** / **`base`** / **`substrate`** — respectively OS-loaded (and `pipelex/kit/` exists), flat (and `base_exceptions.py` exists), and cold jargon.
+
+### Why `runtime` / `interpreter` won
+
+It is the textbook language-implementation split, so it explains itself to any developer who has implemented a language: the **runtime** is the machinery present at execution time (allocator, stdlib, FFI — here: models, workers, config, values); the **interpreter** reads the program and executes it (here: reads `.mthds`, builds pipes, routes them).
+
+It also gives **one word across layer and hub** rather than two vocabularies: `runtime_hub` lives in the runtime layer, `interpreter_hub` in the interpreter layer.
+
+**Known cost, accepted:** the workspace `CLAUDE.md` calls all of `pipelex/` "the Python runtime", so "the runtime layer" nests inside "the runtime". Mild, and identical to the tension in `runtime_hub`, which Louis accepted explicitly.
+
+### `service_hub` → `runtime_hub`
+
+Two reasons.
+
+1. **Commercial collision.** Once "the Pipelex service" means the hosted product, `from pipelex.service_hub import get_secret` is ambiguous — and after the cross-repo sweep that exact line lands in `pipelex-platform`, `pipelex-api` and `pipelex-api-hosted`, repos that *are* the service. The word means two different things one line apart.
+2. **"Runtime" names the role, "service" named the mechanism.** The container holds config, console, secrets, storage, telemetry, the model deck, the inference workers, the content generator, reporting, run mode, tracing and the plugin registries — ambient machinery that lives for the process and is needed to execute anything, whatever is loaded. That is a runtime. "Service" only described how it is injected.
+
+Louis waved off the proximity to the existing `runtime_bridge` package. Worth one clarifying sentence in `hub-layering.md` anyway, because `plugins → runtime_bridge` appears in the Known-inversions list, so the two names will sit near each other and a reader may infer a relationship.
+
+### `method_hub` → `interpreter_hub`
+
+`method_hub` was **already flagged as a knowing concession** at D1 of the original plan: *"`method_hub` borrows the MTHDS noun for a runtime container — acceptable because the object genuinely holds the loaded method's libraries, but it is a conscious call against the brand-boundary rule."* Three defects:
+
+1. **"Method" is an MTHDS/product noun, not a Pipelex runtime noun.** Inside `pipelex/` the vocabulary is bundle / library / pipe / domain / concept; "method" lives at the language and hosted-product level (`method_id`, `mt_…`, `mthds_run`). The brand rule in the workspace `CLAUDE.md` says MTHDS owns the language nouns and Pipelex owns the runtime ones — this borrows in the forbidden direction.
+2. **It misdescribes the contents** — the container holds a `LibraryManager`, the concept/domain/pipe libraries, a current-library binding, the router, the pipeline manager, the PipeFunc executor.
+3. **The singular is misleading.** Multiple libraries can be open, bound per async context; "method hub" implies one method.
+
+Two alternatives were considered and rejected **in this order**, so do not circle back to either:
+
+- **`library_hub`** — rejected by Louis: a library is *inert*, while the container is active machinery (router, pipeline manager). Naming it for the passive artifact undersells it.
+- **`pipe_hub`** — proposed by Louis, rejected on evidence: it is **narrower than its contents**. A meaningful share of the hub is concepts and domains, not pipes (`get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`), plus the library binding and dirs. `get_native_concept()` on a `pipe_hub` reads wrong, and those concept accessors are load-bearing — they are exactly what the runtime layer consumes through `ConceptProviderAbstract` after Phase 4. `pipe_hub` makes the same class of error as `library_hub`, in the opposite direction: one too passive, the other too narrow.
+
+`interpreter_hub` covers pipes, concepts, domains and the execution machinery under one true idea: *everything bound to the method you loaded, and the thing that runs it.*
+
+**On the `pipelex/core/interpreter/` collision** — this was raised as an objection and then withdrawn, deliberately. It only holds if the layers keep the low/high names. Once the layer is *called* the interpreter layer, `core/interpreter/` sitting inside it is a part-of relationship, exactly as consistent as `runtime_hub` living inside "the runtime". Not a collision.
+
+## Sequencing — why this window matters
+
+**Land H-4 green first** (`make agent-test` + both drift contracts), so there is a known-good commit, then do the rename as its own commit *before* the release and *before* the cross-repo sweep.
+
+The load-bearing fact: **the cross-repo sweep has not happened yet.** External repos still import `pipelex.hub` — they are broken either way and get rewritten exactly once. Renaming now costs **zero** extra cross-repo churn. Renaming after the sweep means doing it twice, and the second time is a published-contract break with no cover story. The CHANGELOG entry is written but unreleased, so the announcement absorbs it for free.
+
+Doing it as a separate commit (not amended into H-4) keeps a clean bisect point, since it touches ~300 files mechanically.
+
+## Before you start — verify no collisions
+
+Not checked exhaustively when the decision was taken. Do this first:
+
+```bash
+# in the workspace root, not just _hub
+grep -rn "runtime_hub\|RuntimeHub\|interpreter_hub\|InterpreterHub" --include="*.py" --include="*.md" .
+```
+
+`pipelex-temporal/` is private — check it out and grep it too; it is the heaviest consumer (35 files import `pipelex.hub` today).
+
+## The mechanical plan
+
+Counts below are files, measured at commit `46e76c953`.
+
+### 1. The two modules
+
+- `git mv pipelex/service_hub.py pipelex/runtime_hub.py`
+- `git mv pipelex/method_hub.py pipelex/interpreter_hub.py`
+- Class renames: `ServiceHub` → `RuntimeHub`, `MethodHub` → `InterpreterHub`.
+- Accessor renames: `get_service_hub` / `set_service_hub` → `get_runtime_hub` / `set_runtime_hub`; `get_method_hub` / `set_method_hub` → `get_interpreter_hub` / `set_interpreter_hub`.
+- Update both module docstrings — they open with the layering rationale.
+
+### 2. Call sites
+
+| import | files in `pipelex/` | files in `tests/` |
+| --- | --- | --- |
+| `pipelex.service_hub` | 113 | 66 |
+| `pipelex.method_hub` | 55 | 135 |
+
+Rewrite via an `ast` pass over whole import statements, **not regex** — the same hazard as Phase 1: parenthesized multi-line import blocks. Phase 1's rewriter is the model.
+
+⚠ **String literals are the landmine, again.** This is the lesson that cost 36 broken tests at H-1: an import rewrite is blind to `mocker.patch("pipelex.service_hub.get_console", ...)`, `importlib.import_module(...)`, and any config-driven dotted path. Sweep for the string forms separately:
+
+```bash
+grep -rn '"pipelex\.service_hub\|"pipelex\.method_hub\|'"'"'pipelex\.service_hub\|'"'"'pipelex\.method_hub' pipelex tests
+```
+
+### 3. Also rename these attributes / locals
+
+- `pipelex/pipelex.py:125-128` — `self.service_hub` / `self.method_hub` instance attributes (and every reader of them).
+- `pipelex/system/registries/class_registry_access.py` — the `class_registry_scoping` slot is installed by `set_method_hub`; its docstring names the hub.
+- `pipelex/plugins/registrar.py` — `HubSlot` is *not* affected (its members are capability names: `CONTENT_GENERATOR`, `PIPE_ROUTER`, …). Leave it. `HubSlotAlreadyClaimedError` likewise.
+
+### 4. The guard — `pipelex/cli/dev_cli/commands/hub_layering_guard.py`
+
+| identifier | becomes |
+| --- | --- |
+| `LOW_LAYER_PACKAGES` | `RUNTIME_LAYER_PACKAGES` |
+| `is_low_layer(...)` | `is_runtime_layer(...)` |
+| `METHOD_HUB_MODULE` | `INTERPRETER_HUB_MODULE` (value `"pipelex.interpreter_hub"`) |
+| `HubLayeringViolationKind.METHOD_HUB_IMPORT` | `INTERPRETER_HUB_IMPORT` (wire value `"interpreter-hub-import"`) |
+| `HubLayeringViolationKind.METHOD_HUB_REFERENCE` | `INTERPRETER_HUB_REFERENCE` (wire value `"interpreter-hub-reference"`) |
+
+`DELETED_HUB_MODULE = "pipelex.hub"` **stays exactly as is** — that rule is about the module that was deleted in Phase 1 and is unrelated to this rename. Keep its `# hub-layering: ignore` marker.
+
+Also update the module docstring (it states both rules and the carve-outs) and `HubLayeringViolationKind.remedy`, whose strings name the hubs.
+
+Leave the escape hatch spelling `# hub-layering: ignore` alone — "hub layering" is still accurate, and changing it would silently un-suppress the two lines that carry it.
+
+### 5. Tests
+
+Contents first — every one of these needs its import lines, constants and patch-target strings swept:
+
+- `tests/unit/pipelex/test_hub_import_closure.py` — `LOW_LAYER_ENTRY_POINTS` → `RUNTIME_LAYER_ENTRY_POINTS`; the module docstring states the property.
+- `tests/unit/pipelex/cli/dev/test_hub_layering_guard.py` — `test_low_layer_membership` → `test_runtime_layer_membership`; `test_core_is_split_between_the_layers` keeps its name but its assertions call the renamed predicate.
+- `tests/unit/pipelex/test_hub_lifecycle.py`, `tests/unit/pipelex/test_hub_class_registry.py` — import lines and any patch-target strings.
+
+**Module renames — Louis' call: rename them as part of this work.** Note first that `test_hub_*` is not *stale*: "hub" survives the rename (there are still two hubs, and `hub_layering_guard.py` / `check-hub-layering` / `hub-layering.md` are all unchanged). So apply the repo's actual convention — a test module mirrors its source module, or else names the property it pins — which moves two and leaves two:
+
+| module | action | why |
+| --- | --- | --- |
+| `test_hub_import_closure.py` | → **`test_runtime_layer_import_closure.py`** | It pins a property, not a module: *the runtime layer loads no interpreter*. Naming the layer makes the file findable from the vocabulary. |
+| `test_hub_class_registry.py` | → **`test_class_registry_scoping.py`** | It is the D5 regression guard for the `class_registry_scoping` slot, not a test of "the hub". The current name has always been imprecise. |
+| `test_hub_lifecycle.py` | **keep** | It pins that a boot installs *both* hub singletons and that teardown drops the scoping one installed. "Hub lifecycle" is exactly what that is, and both hubs still exist. |
+| `cli/dev/test_hub_layering_guard.py` | **keep** | Mirrors its source module `hub_layering_guard.py`, which is not renamed. Moving it would break the mirror. |
+
+⚠ **Renaming test modules needs a cache reset.** Per the repo `CLAUDE.md`, moving or deleting tests confuses pytest collection and the linters — run `make cleanderived` afterwards. That deletes `tests/integration/pipelex/fixtures/_generated_model_sets.py`, after which pyright fails with unresolved-import errors unrelated to your change; `make regenerate-test-models-quiet` restores it. Do this *before* concluding anything failed.
+
+### 6. `subject_grants.toml`
+
+29 entries under `pipelex/service_hub.py::`, 26 under `pipelex/method_hub.py::`.
+
+⚠ **Migrate the grants BEFORE running any check.** Two independent traps, both hit this session:
+- `make fko` runs early in `agent-check` and will silently make an ungranted subject keyword-only.
+- Staleness is symmetric: a grant whose def moved hard-fails `make cko` until the registry is fixed.
+
+The path prefix and the class name both change (`ServiceHub.` → `RuntimeHub.`, `MethodHub.` → `InterpreterHub.`).
+
+### 7. Build and CI
+
+- `Makefile` — the `check-hub-layering` target's `PRINT_TITLE` says "Enforcing the service_hub / method_hub layering boundary" (line ~362) and the help text at line ~159. The target name and the `chl` alias can stay: "hub layering" is still what it checks.
+- `.github/workflows/lint-check.yml` — job `lint-hub-layering` (line ~137). **Do not rename the job**: it may be a required status check, and a rename silently un-requires it. Nothing to change here unless the target name changes.
+- `.github/workflows/lint-fresh-check.yml` — runs `make check-hub-layering`; unaffected.
+
+### 8. Docs
+
+- `docs/contribute/hub-layering.md` — the largest edit. Retitle the layers throughout, rewrite "The two halves" headings, update the Enforcement rule list, and add the `runtime_bridge` clarifying sentence. Keep the "Where core splits" section's *content* — only its layer vocabulary changes.
+- `docs/under-the-hood/architecture-overview.md` — "What Keeps The Layers Apart: The Two Hubs" section and the paragraph on core straddling the line.
+- `CHANGELOG.md` — amend the `[Unreleased]` breaking-change entry rather than adding a second one. It currently announces `pipelex.hub → pipelex.service_hub / pipelex.method_hub`; it should announce the final names directly, since `service_hub` / `method_hub` will never have shipped.
+- Grep the rest: `docs/under-the-hood/{pipe-routing-and-execution,runtime-bridge-and-transport,execution-graph-tracing}.md`, `docs/advanced/`, `tests/CLAUDE.md` (its "root-level modules" trigger list names both hubs), and in-code docstrings.
+- `tests/CLAUDE.md` also lists `pipelex/service_hub.py` / `pipelex/method_hub.py` under "When to run full `make agent-test`".
+
+### 9. This branch's own tracker
+
+`TODOS.md` and `wip/hub/hub-split-refactor.md` are dense with `service_hub` / `method_hub`. They are historical records of the refactor, so a mechanical sweep is fine — but keep D1's rejected-alternatives reasoning intact and add a pointer to this document.
+
+## Gates
+
+`make agent-check` · full `make agent-test` (a rename of this size touches root modules, so per `tests/CLAUDE.md` the full suite is the correct gate) · `make drift-check`.
+
+Expect **`cli-docs` to fire** — the rename touches many CLI modules' import lines. `config-docs` will likely fire too. Both are import-path-only for this change, but review honestly against the targets before acking, per the `drift-review` skill.
+
+## Cross-repo
+
+This **replaces**, not adds to, the first wave of the [cross-repo sweep](../../TODOS.md#cross-repo-sweep): external repos go straight from `pipelex.hub` to `pipelex.runtime_hub` / `pipelex.interpreter_hub`, never touching the intermediate names. Update the sweep tables in `TODOS.md` to the final names as part of this work, so the sweep is done once with the right target.
+
+Affected: `pipelex-temporal` (35 files, private), `pipelex-mistralai-workflows` (11), `pipelex-api` (9), `pipelex-cookbook` (2), `cocode` (2). `get_pipelex_hub` splits into `get_runtime_hub` / `get_interpreter_hub`.
diff --git a/wip/hub/pr-1062-review-followups.md b/wip/hub/pr-1062-review-followups.md
new file mode 100644
index 000000000..4b210e4e5
--- /dev/null
+++ b/wip/hub/pr-1062-review-followups.md
@@ -0,0 +1,443 @@
+# PR #1062 — `/review` follow-ups
+
+**Status: [Phase A](#phase-a--in-pr-fixes) and [Phase B](#phase-b--test-hardening) are APPLIED**, recorded at [Checkpoint A](../../TODOS.md#checkpoint-a-record--pr-1062-review-follow-ups) and [Checkpoint B](../../TODOS.md#checkpoint-b-record--test-hardening) in the tracker. [Phase C](#phase-c--release-wave-additions) and the [F1](#f1--the-layer-rule-is-only-enforced-one-hop-deep) remedy (the A1-PR) are **not** started. PR [#1062](https://github.com/Pipelex/pipelex/pull/1062) is open against `dev`. This document is the executable follow-up plan from a full `/review` pass, written so it can be picked up cold in a new session.
+
+**Related:** [`../pr-1062-review-notes.md`](../pr-1062-review-notes.md) records the earlier Codex thread triage (the closure-predicate widening, the `pipe_output` reclassification, and one deliberately-deferred item). That file is about *one* review thread; this one is the whole review. They do not overlap except where noted.
+
+## Cold start — read in this order
+
+1. This section, then [Decisions taken](#decisions-taken) — what was chosen and what was declined. Every decision is now taken, including [D-R4](#decisions-taken) (decided 2026-07-27).
+2. [F1](#f1-the-layer-rule-is-only-enforced-one-hop-deep) — the biggest finding, and the only one that changes how the boundary is enforced. It invalidates a claim the shipped doc makes. **It was re-verified on 2026-07-26 and three specifics in the first draft were corrected**; read the section as it now stands, not any summary of it elsewhere.
+3. [Phase A](#phase-a--in-pr-fixes) — the code changes, in dependency order. A1 is now split per D-R4: only its doc-honesty fix stayed in #1062; the remedy itself is its own follow-up PR. Everything else in the phase is applied.
+4. [Phase B](#phase-b--test-hardening) — applied, every item mutation-verified. [Phase C](#phase-c--release-wave-additions) is the only phase left here, and it is release-gated.
+
+Every finding below was **verified by running it**, not by reading alone. The reproduction command is quoted with each one; re-run it first if you doubt a claim, because several of them contradict what the tracker and the shipped docs currently say.
+
+## What the review confirmed as sound
+
+Recorded so nobody re-audits it. Each of these was independently re-measured, not taken on trust:
+
+- `make check-hub-layering`, `make drift-check`, `make tb`, the new hub tests, and all PR CI checks pass.
+- **The headline property reproduces exactly**: importing `cogt.content_generation.content_generator` loads **0** interpreter modules, down from 50. All eight closure-test entry points measure 0.
+- **`subject_grants.toml`'s 221/221 churn is a faithful re-sort.** 1758 → 1759 grants; the six dropped and six added pair up exactly as the tracker documents (four library-abstract methods moving to the provider abstracts, `set_observer` deleted, `set_pipelex_hub` splitting in two). No grant lost, no rationale silently rewritten.
+- **The TOML config shape is unchanged** — `pipelex.toml` is byte-identical to base.
+- Enum completeness is clean: one new enum (`HubLayeringViolationKind`), exhaustive `match`, no unhandled consumer.
+- Of 498 changed `.py` files, 437 are pure import-line churn. The reviewer map in the PR body is accurate about where judgment lives.
+
+## Decisions taken
+
+- **D-R1 — the cross-repo/spec work is recorded, not done.** Louis' call: keep PR #1062 as-is and fold [Phase C](#phase-c--release-wave-additions) into the existing release-gated sweep rather than widening this PR. The sweep tables in `TODOS.md` stay as they are for now; this document is the delta.
+- **D-R2 — the in-PR fixes ([Phase A](#phase-a--in-pr-fixes)) and the full test hardening ([Phase B](#phase-b--test-hardening)) are approved to apply.** They were deferred out of this session only because they want a cold context, not because they were declined.
+- **D-R3 — `Pipelex.teardown`'s process-global scoping reset is accepted as designed.** See [Considered and not changed](#considered-and-not-changed).
+- **D-R4 — DECIDED 2026-07-27: the [F1](#f1-the-layer-rule-is-only-enforced-one-hop-deep) remedy is [(d)](#remedy-d--split-the-built-ins-by-layer) paired with a minimal (c), in its own PR after #1062 merges.** Rationale: (d) is the only option that *removes* the defect — (a) re-describes it (enumerate ~24 subpackages and maintain the list forever), (b) hides it behind deferred imports with the false claim standing, (c) alone cannot land (red on today's tree). (d) deletes a weld rather than adding machinery, and moves the built-ins onto the seam external plugins (Temporal, Daytona) already use from outside the repo. (c) rides along because this exact failure mode — transitive breach with both gates green — already occurred invisibly in the PR that introduced the guard, so prevention is not speculative; at ~0.8 s it is cheaper than the guard's current run. The two formerly-blocking questions are settled: **the relocated plugins get one interpreter-side home** (e.g. `pipelex/interpreter_plugins/`, matching the `runtime_hub`/`interpreter_hub` vocabulary) — see [Resolutions](#remedy-d--resolutions-2026-07-27) under Remedy (d) for why "next to what they adapt" was never actually available and how the two-places-to-look smell dissolves; and **(d)+(c) is its own PR** — #1062 carries only [A1](#phase-a--in-pr-fixes)'s doc-honesty fix. A1.1's broad entry-point additions are **superseded by (c)** and consciously skipped; the (d) PR adds a single `pipelex.plugins` entry point as a runtime-truth check. All four candidates and their measurements remain under [Remedy options](#remedy-options-with-what-was-measured-about-each) for the record.
+
+## F1 — the layer rule is only enforced one hop deep
+
+**This is the finding that matters most, and it is not what the earlier review thread was about.**
+
+The guard checks whether a runtime-layer module *directly* imports `pipelex.interpreter_hub`. It does not follow the import graph. `pipelex.plugins` is a declared runtime-layer package, and four of its modules reach `interpreter_hub` transitively. Both gates stay green.
+
+> **Re-verified 2026-07-26**, two independent ways — runtime import measurement, and a static module-level import graph over all of `pipelex/`. The defect is confirmed, but three specifics in the original write-up were wrong and are corrected below. Re-read this section rather than the first draft; the corrections change what the remedy has to cover.
+
+Measured on the branch tip:
+
+```
+pipelex.plugins.direct.direct_plugin interpreter_hub=True interp_modules= 57 total=462
+pipelex.plugins.discovery interpreter_hub=True interp_modules= 67 total=516
+pipelex.plugins.builtins interpreter_hub=True interp_modules= 67 total=515
+pipelex.plugins.pipe_func.pipe_func_plugin interpreter_hub=True interp_modules= 58 total=371
+
+$ .venv/bin/pipelex-dev check-hub-layering --quiet
+✓ Hub-layering check: PASSED
+```
+
+### F1.a — the blast radius is exactly `pipelex.plugins`
+
+A static sweep of **every** declared runtime-layer module (module-level imports only, `TYPE_CHECKING` and function-body imports excluded, matching what actually loads):
+
+```
+declared runtime-layer modules scanned: 476
+reaching pipelex.interpreter_hub transitively: 4
+
+ pipelex.cogt 0 / 130 pipelex.core.concepts 0 / 18
+ pipelex.plugins 4 / 131 ← pipelex.core.domains 0 / 6
+ pipelex.reporting 0 / 6 pipelex.core.memory 0 / 7
+ pipelex.system 0 / 46 pipelex.core.pipes.inputs 0 / 4
+ pipelex.tools 0 / 96 pipelex.core.pipes.stuff_spec 0 / 4
+ pipelex.core.stuffs 0 / 28
+```
+
+Ten of the eleven declared packages are clean across 345 modules; the uncovered ones were also spot-checked at runtime (`reporting.reporting_manager`, `system.configuration.configs`, `core.domains.domain_factory` — all `interp=0`). **The remedy decision is only ever about `plugins`.**
+
+### F1.b — there are three routes, not one
+
+The original write-up named `pipelex.runtime_bridge` as *the* intermediary. It is one of three, and **cutting it alone fixes nothing**:
+
+```
+plugins.direct.direct_plugin → runtime_bridge.direct_orchestrator → interpreter_hub
+plugins.direct.direct_plugin → pipeline.direct_bundle_validator → pipeline.validate_in_process → interpreter_hub
+plugins.pipe_func.pipe_func_plugin → pipe_operators.func.direct_pipe_func_executor → interpreter_hub
+plugins.builtins → both plugins above (builtins.py:6, builtins.py:16)
+plugins.discovery → builtins (discovery.py:5; on the boot path, pipelex.py:53)
+```
+
+`direct_plugin` has **two independent routes** (`direct_plugin.py:1` and `:4`), so severing the `runtime_bridge` one leaves it breaching through `pipeline`. And `pipe_func_plugin.py:1-2` imports `pipe_operators` **directly** — no hub, no `runtime_bridge`, never touched by that cut.
+
+The structure simplifies the remedy, though: **only two modules are leaves.** `builtins` and `discovery` breach purely as aggregators — `builtins.py` imports every built-in plugin, `discovery.py` imports `builtins` — so they carry no edge of their own. Fix `direct_plugin` and `pipe_func_plugin` and all four clear; leave either one and both aggregators stay breached.
+
+### F1.c — the headline property is *not* damaged
+
+The original write-up called this "a live breach of the property the guard exists to protect," which reads as if the shipped 0-interpreter-modules measurement is invalidated. It is not:
+
+```
+pipelex.config interp=0 plugins.builtins loaded=False
+pipelex.cogt.content_generation.content_generator interp=0 plugins.builtins loaded=False
+pipelex.runtime_hub interp=0 plugins.builtins loaded=False
+```
+
+Nothing on the inference-layer or `runtime_hub` path reaches the four modules; they are reachable only from full boot, where the interpreter loads anyway. What is actually wrong is narrower and still worth fixing:
+
+- **The scope claim is false.** `docs/contribute/hub-layering.md:184` — *"Every declared package is compliant"* — is true of the direct-import rule only, and reads as a claim about the property. The Known-inversions preamble at `:217` is honest that *"`plugins` is a runtime layer is not yet unconditionally true"*, but files it as placement; it does not say the inversion loads `interpreter_hub` and 67 interpreter modules today. It also understates both instances: `pipe_func_plugin` is described as *"typed by protocols from `pipe_operators/`"* when it imports the concrete `DirectPipeFuncExecutor` at module level, and `direct_plugin` is described as importing *"from `pipeline/`"* with no mention of the `runtime_bridge` route. `plugins/discovery.py` and `plugins/builtins.py` are not listed at all.
+- **The guard cannot see this class of breach at all.** Any future runtime-layer module can reach `interpreter_hub` through any undeclared intermediary (`runtime_bridge`, `pipeline`, `pipe_run`, `graph`, `observer`, `tracing`, `config`, `libraries`) with both gates green. This is the generalizable defect; the four modules are just today's instance.
+
+### F1.d — why it was invisible: the closure test covers 6 of 11 packages
+
+The closure test is the only thing that checks the property, and it does so at eight hand-picked entry points. Mapped against the declaration:
+
+```
+pipelex.cogt COVERED pipelex.core.concepts COVERED
+pipelex.plugins NO ENTRY POINT pipelex.core.domains NO ENTRY POINT
+pipelex.reporting NO ENTRY POINT pipelex.core.memory COVERED
+pipelex.system NO ENTRY POINT pipelex.core.pipes.inputs COVERED
+pipelex.tools NO ENTRY POINT pipelex.core.pipes.stuff_spec COVERED
+ pipelex.core.stuffs COVERED
+```
+
+`pipelex.plugins` is the largest declared package (131 modules) and has no entry point. The four uncovered-but-clean packages are a latent gap, not a live one — but they are the reason nothing caught `plugins`.
+
+### The structural read that should inform the remedy
+
+The two leaf modules ([F1.b](#f1b--there-are-three-routes-not-one)) are precisely the ones whose job is to **construct interpreter-layer objects**: `direct_plugin` registers a `DirectOrchestrator` + `DirectBundleValidator`, `pipe_func_plugin` registers a `DirectPipeFuncExecutor`. The other ~127 modules in `plugins/` are inference backends (anthropic, openai, bedrock, gateway, …) and are genuinely runtime. That is not an arbitrary line — it is the same one as *"if it names a `Pipe`, it belongs to the interpreter layer."*
+
+The repo already sanctions the deferral pattern one level down: `pipe_func_executor_registry.py:7-14` defers its `pipe_operators` protocol under `TYPE_CHECKING`, with a comment stating exactly this reasoning. The *plugin* cannot use that trick — it needs the concrete class at runtime, because it constructs it.
+
+### Remedy options, with what was measured about each
+
+**Decided 2026-07-27 — (d) paired with a minimal (c); see [D-R4](#decisions-taken).** The four candidates and their measurements are kept for the record.
+
+- **(a) Declare `plugins` subpackage-by-subpackage**, the treatment `pipelex.core` already got for the same reason. Honest about what the package is, and the structural read above says the split falls on a real line. Wrinkle the original draft did not mention: `builtins.py` imports *every* plugin, so it cannot be runtime-layer while any built-in plugin is interpreter-touching, and `discovery.py` imports `builtins`. So (a) means enumerating `plugins`' ~14 backend subpackages + ~10 registry modules and excluding `direct/`, `pipe_func/`, `builtins.py`, `discovery.py` — noticeably more churn than `core`'s six lines.
+- **(b) Defer the imports in the four modules.** Largely **cosmetic**: the modules still load at boot, in the same process, one call later — `register()` runs on the boot path either way. Nothing that does not already import the interpreter would import less; the closure test would go green on an unchanged property. Also needs ~4 function-level imports with `# noqa`, against the house import rule, and must cover all three routes from F1.b.
+- **(c) Teach the guard the transitive check** — resolve each runtime-layer module's module-level `pipelex` import closure and flag any path reaching `interpreter_hub`. The only option that closes the generalizable hole. **Cheaper than "a real feature" suggests**: a prototype builds the whole graph and does reachability over all 476 modules in **0.83 s**, against the current guard's own 2.79 s run. It does not stand alone — it would fail on the four modules today, so it forces (a), (b) or (d) alongside it.
+- **(d) Split the built-ins by layer and move the weld to the composition root** — Louis' proposal, and a strictly better (a). See [Remedy (d) in full](#remedy-d--split-the-built-ins-by-layer) below; it is the leading candidate.
+
+Whichever is chosen, `docs/contribute/hub-layering.md:184` and the Known-inversions preamble at `:217` need correcting per F1.c.
+
+### Remedy (d) — split the built-ins by layer
+
+**The smell it names.** `builtins.py` is a *composition root smuggled into a leaf package*. Welding the two layers is legitimate work — something has to do it — but it belongs at the boot entrypoint, which sits in no declared layer and is free to weld. Instead it happens inside a module the declaration claims is runtime, which is exactly why both gates stay green while the claim is false.
+
+**The boundary already exists in the code; (d) only makes it visible.** The registrar's slots are *ports* — `OrchestratorProtocol`, `BundleValidatorProtocol` and `PipeFuncExecutorFactoryFn` all live in runtime-layer modules under `plugins/*_registry.py` — and `pipelex.py:427-433` sets every derived registry, orchestrators and bundle validators included, on **`self.runtime_hub`**. So the runtime hub already holds slots whose *adapters* are interpreter-layer. That is ports-and-adapters, and it is what the guard's own remedy text already prescribes: *"have the interpreter layer install it downward at boot"* (`hub_layering_guard.py:130-132`).
+
+**The consistency argument that clinches it.** External plugins already use this seam: our Temporal plugin contributes an orchestrator and our Daytona plugin a PipeFunc executor — both interpreter-touching, both living entirely outside this repo, both arriving through the entry-point mechanism without welding anything. The in-tree built-ins are the *only* ones welding. (d) makes them use the seam externals already use.
+
+**Four moves.** Splitting `builtins.py` alone is *not* enough — `direct/` and `pipe_func/` still sit under `pipelex.plugins` and still breach on their own ([F1.b](#f1b--there-are-three-routes-not-one)):
+
+1. Split `builtins.py`; the runtime half keeps the seventeen backend / storage / secrets plugins.
+2. Relocate `plugins/direct/` and `plugins/pipe_func/` to the interpreter side (3 modules).
+3. Invert `discovery`'s dependency: `build_registrar` takes the plugin list as a **parameter** instead of importing `BUILTIN_PLUGINS` — the same injection pattern this refactor already applied to `concept_provider` in `core`.
+4. `pipelex.py` composes both halves. It is in no declared layer (verified) — the composition root, where welding belongs.
+
+**Simulated against the real import graph** (same graph builder as the [F1.a sweep](#reproduction-commands), with those edges rewritten):
+
+```
+AFTER the simulated split+relocation:
+ pipelex.plugins modules in scope : 128 (relocated out: 3)
+ still reaching interpreter_hub : 0
+ interpreter-package leaks : 0
+```
+
+That is the payoff over (a): it converts *"drop `pipelex.plugins` and enumerate ~24 subpackages"* into **"keep the one declared line and make it true."** Three modules move instead of two dozen getting enumerated.
+
+**Honest counterarguments, so this is not adopted on enthusiasm:**
+
+- **The immediate payoff is honesty and enforceability, not a smaller closure.** `pipelex.py` is the only caller of `build_registrar` and needs everything, so nothing loads less on day one — the same criticism levelled at (b). The difference is real but should be stated precisely: (b) hides the weld behind a deferred import and leaves the false claim standing; (d) removes the weld and makes the claim true. Removing a false claim is not a speculative addition — but do not expect boot to get faster.
+- **Where the relocated plugins live was unresolved, and was the weakest part.** A `pipelex/interpreter_plugins/` sibling creates two places to look for a plugin, which is its own smell; housing them next to what they adapt scatters them. **Resolved — see [Resolutions](#remedy-d--resolutions-2026-07-27) below.**
+- **`CORE_UNCONDITIONAL_PLUGIN_NAMES` splits along the same line** — `{direct, pipe_func}` interpreter, `{storage, secrets, openai}` runtime — and is consumed by `discovery._skip_if_disabled`, so it must be injected or split alongside move 3. A second thing welded in the same file.
+- **It constrains the plugin contract.** (d) assumes no single plugin contributes both a runtime and an interpreter adapter. True today; one that wanted both would have to become two plugin classes. Probably healthy, but it is a real constraint and should be written into the contract rather than left implicit.
+- **It does not replace (c).** Nothing in (d) stops the *next* runtime-layer module from welding the same way. (d) fixes today's instance properly; (c) prevents recurrence. Pair them.
+- **Scope.** Relocating packages is a real refactor with import churn across the tree. #1062 is already 498 files and green, so (d) most likely wants its own PR rather than widening this one.
+
+### Remedy (d) — resolutions (2026-07-27)
+
+The decisions that unblocked D-R4, so the (d) PR starts from settled ground:
+
+- **Location: one interpreter-side home, not scattered next to the adapters.** The "house them next to what they adapt" option was never actually available — `DirectOrchestratorPlugin` spans two packages (its orchestrator lives in `runtime_bridge`, its bundle validator in `pipeline`), so it has no single adapter-adjacent home. A small dedicated package (e.g. `pipelex/interpreter_plugins/`, consistent with the `runtime_hub`/`interpreter_hub` vocabulary) is the right shape.
+- **The two-places-to-look smell dissolves.** The interpreter-side package is *allowed* to import downward, so its builtins module imports the runtime half and exports the single composed list. Exactly one place still answers "what are the built-in plugins" — it just lives in the layer permitted to do the welding. Both callers of `build_registrar` (boot in `pipelex.py`, and the `pipelex plugins list` diagnostic) consume that one list, so the composition is not duplicated.
+- **`CORE_UNCONDITIONAL_PLUGIN_NAMES` is passed as a parameter** alongside the plugin list — the same inversion as move 3, two lines more. No split constant left behind in a runtime module.
+- **The one-plugin-one-layer constraint is one sentence in `contract.py`'s docstring**, not machinery. If a plugin ever genuinely needs adapters in both layers, decide then.
+- **(c) stays minimal**: module-level imports only, with today's `TYPE_CHECKING` carve-outs — matching what actually loads, per the sweep script that found F1. No exclusion/allowlist machinery in the guard to keep `direct/`/`pipe_func/` under `pipelex.plugins`; relocation is the fix, not declaration surgery.
+- **Entry points: one, not five.** With (c) doing static transitive coverage of all declared runtime-layer modules, the broad A1.1 additions are redundant cost. The (d) PR adds a single `pipelex.plugins` closure-test entry point as a runtime-truth check (static analysis cannot see dynamic imports) for the package that bit us, and skips the other four uncovered packages.
+- **Own PR, after #1062 merges.** #1062 is 498 files, green, and reviewed; widening it re-opens the review for no benefit. #1062 carries only the A1.3 doc-honesty fix; the (d) PR rewrites that doc section again when the inversion actually disappears — a few sentences, acceptable churn.
+
+## F2 — the guard does not enforce its own rule on `runtime_hub.py`
+
+Narrower than F1 and independent of it. `RUNTIME_LAYER_PACKAGES` omits `pipelex.runtime_hub`, so `is_runtime_layer(module_qname="pipelex.runtime_hub")` is `False` and the module at the centre of the rule is exempt from it. Verified by injecting the forbidden import in memory (the file on disk was not touched):
+
+```
+runtime_hub.py WITH a forbidden interpreter_hub import -> NONE (guard says PASS)
+same import in a real runtime-layer module -> [(35, 'interpreter-hub-import')]
+```
+
+18 modules in `runtime_hub`'s real 225-module closure sit outside the layer rule. The closure test does catch this one (`pipelex.runtime_hub` is an entry point asserting `pipelex.interpreter_hub not in sys.modules`), so the architecture holds — the hole is in the fast, well-named gate.
+
+The fix is one tuple entry and was verified zero-risk: with `"pipelex.runtime_hub"` added, violations across `pipelex/` + `tests/` are still **0**, and the injected import is caught at line 35.
+
+Also correct `docs/contribute/hub-layering.md:110`, which says `pipe_output` is *"the one runtime-layer module the guard's declaration does not cover"*. `runtime_hub` itself is another, and it is the load-bearing one.
+
+## Phase A — in-PR fixes
+
+Ordered so each step leaves the tree green. **A1, A2 and A6 touch `hub-layering-convention` drift triggers** (`pipelex/cli/dev_cli/commands/hub_layering_guard.py`, `pipelex/runtime_hub.py`), so the contract re-opens: `git add` the trigger files, then `make drift-ack CONTRACT=hub-layering-convention RATIONALE="…"` with an honest sentence.
+
+**A1 is the only item that changes what the boundary actually guarantees. Per [D-R4](#decisions-taken) (decided 2026-07-27) it is now split: only the doc-honesty fix below stays in #1062; the remedy — (d)+(c) — is its own follow-up PR.** Everything else in the phase is independent of A1 and of each other, and can be done in any order.
+
+- [x] **A1 (in #1062) — correct the doc.** ✅ Applied. Per [F1.c](#f1c--the-headline-property-is-not-damaged): `docs/contribute/hub-layering.md:184` ("Every declared package is compliant") is true only of the direct-import rule and reads as a claim about the property — the branch must not merge shipping a claim the measurement contradicts; the Known-inversions preamble at `:217` needs the measurement (the inversion loads `interpreter_hub` and 67 interpreter modules today), not just the placement note, and understates both listed instances; `plugins/discovery.py` + `plugins/builtins.py` are not listed there at all despite pulling `builder` and `codegen`. State that the fix is decided and planned ([D-R4](#decisions-taken)). Do **not** repeat the original draft's framing that the headline property is broken — it is not.
+- [ ] **A1-PR (own follow-up PR, after #1062 merges) — apply remedy (d)+(c).** Scope per [D-R4](#decisions-taken) and the [Resolutions](#remedy-d--resolutions-2026-07-27): the four moves of [(d)](#remedy-d--split-the-built-ins-by-layer) with the interpreter-side home and parameter-passed `CORE_UNCONDITIONAL_PLUGIN_NAMES`; the transitive check [(c)](#remedy-options-with-what-was-measured-about-each) in the guard; one `pipelex.plugins` closure-test entry point (the broad five-package addition from the original A1.1 is consciously skipped — superseded by (c)); the contract-docstring sentence; and the `hub-layering.md` rewrite removing the inversion from Known-inversions once it is actually gone.
+- [x] **A2 — close the [F2](#f2-the-guard-does-not-enforce-its-own-rule-on-runtime_hubpy) guard gap.** ✅ Applied; re-verified both ways (0 violations tree-wide, injected import caught). Add `"pipelex.runtime_hub"` to `RUNTIME_LAYER_PACKAGES`; fix the `:110` sentence in `hub-layering.md`. Note the tuple is named `..._PACKAGES` but `is_runtime_layer` matches a bare module fine (`==` or `startswith(pkg + ".")`); add a line to its docstring saying so. Verified zero-risk: still 0 violations, and it catches an injected `interpreter_hub` import at line 35.
+- [x] **A3 — delete write-only `RuntimeHub._class_registry`.** ✅ Applied, grant dropped. Remove the field, `set_class_registry`, `get_required_class_registry`, the `pipelex/pipelex.py:339` call, and the now-stale grant `pipelex/runtime_hub.py::RuntimeHub.set_class_registry` (grant staleness is symmetric — `make cko` hard-fails until the registry is cleaned). `get_required_class_registry` has **zero callers** in this repo or any sibling repo; verified. It is pre-existing, but this PR deleted `_observer` for exactly this reason, so the twin is a missed sweep. It is also a live trap: it returns the boot-time global while the module-level `get_class_registry()` returns the **library-scoped** registry, so under `scoped_current_library(...)` the two differ — and the PR's own new test pins that divergence.
+- [x] **A4 — hoist the loop-invariant lookup.** ✅ Applied. `pipelex/core/pipes/rendering/input_renderer.py:134` calls `get_concept_library()` once per `_delighten_template` iteration. Hoist it above the `for`. It also defeats `resolve_input_kind`'s `DYNAMIC` early return, which used to skip the lookup entirely.
+- [x] **A5 — resolve `PipeProviderAbstract`.** ✅ **Deleted** (the first of the two options), `get_required_pipe` back on `PipeLibraryAbstract`, grant re-recorded there, docstring + `hub-layering.md` + CHANGELOG updated to state the absence is deliberate. Rationale in the [Checkpoint A record](../../TODOS.md). It has zero consumers, and its docstring describes the opposite of what the code does: it says core declares pipe resolution *"as a parameter instead of reaching for `interpreter_hub.get_required_pipe`"*, while `core/pipes/rendering/output_renderer.py:51` (a condition's mapped pipes) and `:84` (a sequence's last step) — the two cases the docstring names — both call `interpreter_hub.get_required_pipe` directly. It buys no closure property either, since `core.pipes` is not runtime-layer. **Either delete it** and put `get_required_pipe` back on `PipeLibraryAbstract` (smallest correct surface, consistent with the repo's no-speculative-additions rule), **or** keep it for symmetry with `ConceptProviderAbstract` and rewrite the docstring to say it is not consumed yet. Deleting also means dropping its subject grant.
+- [x] **A6 — doc/comment/CHANGELOG accuracy.** ✅ Applied. Five independent one-liners:
+ - `pipelex/runtime_hub.py:9-11` forbids naming `core.concepts` and `core.pipes`, but `core.concepts` is a **declared runtime-layer package** and is in `runtime_hub`'s own closure — as line 415 of the same file says. Match the canonical doc: `core.bundles`, `core.interpreter`, and the Pipe-touching modules of `core.pipes`.
+ - `pipelex/pipelex.py:122-124` claims RuntimeHub must be installed first because the scoping install *"needs a RuntimeHub already in place"*. It does not — `class_registry_scoping.install` lives in a module that imports nothing from `pipelex`, and `_resolve_scoped_class_registry` reads only the contextvar and the library manager, lazily. State the real reason (runtime is the lower layer, so it reads first) or drop the clause.
+ - `CHANGELOG.md:8` maps `TextFormat` / `TemplatingStyle` / `TagStyle` to `pipelex.tools.templating`, whose `__init__.py` is **0 bytes**: `from pipelex.tools.templating import TextFormat` raises `ImportError`. Name the exact modules, as every other entry in the same sentence does. This is the artifact external consumers read.
+ - `concept_provider_abstract.py:5` and `pipe_provider_abstract.py:8` still say *"stays high"* — the only two survivors of the low/high → runtime/interpreter vocabulary sweep. **Correction found while applying: there were four.** `libraries/concept/concept_library_abstract.py:11` and `libraries/pipe/pipe_library_abstract.py:11` carried "stays here, high"; the grep that found the first two did not match that phrasing. All four are swept (`pipe_provider_abstract.py` via A5's deletion).
+ - `TODOS.md:339` and `:500-501` are off by one. Measured at HEAD: **269 modules / 20,305 SLOC** (claimed 268 / 20,304). The base and H-1 rows reproduce to the digit, so this is a stale re-take, not environment drift. The 0-interpreter-modules row is exact. **Confirmed at Checkpoint A** by re-reading every closure module at both revisions; both tables now carry the correction plus a fresh post-Phase-A column (269 / 20,299).
+- [x] **A7 — regenerate the stale error page.** ✅ Applied; the generator also re-filed the index entry into "platform and tooling", following the class's new subsystem. `JobMetadataError` moved to `pipelex/system/exceptions.py`, but `docs/errors/job-metadata-error.md:16` still reports `pipelex.pipeline.exceptions`. It is the only stale page in the set, i.e. `make generate-error-pages` (alias `gep`) was never run in this PR. That page is the `type_uri` target users land on from a runtime error.
+- [x] **A8 — restate the class-registry leaf-import rule.** ✅ Applied; the three-importer split was re-verified at HEAD (`concept.py` inside the closure, the other two outside). `docs/contribute/hub-layering.md:164` says to import `class_registry_access` directly *"only from inside `runtime_hub`'s import closure"* — but two of the three in-tree importers are **not** in that closure (`concept_factory.py` and `structure_generation/generator.py`; only `concept.py` is). The code is right and the rule is wrong: the real criterion is "a module that must stay import-light with respect to `runtime_hub` uses the leaf". As written the rule invites someone to "fix" `concept_factory.py` to import from `runtime_hub`, silently re-coupling `core.concepts` to the whole cogt/plugin stack. Nothing checks this mechanically.
+
+> **CHECKPOINT A** — run `make agent-check`, then the full `make agent-test`, then `make drift-check` and ack the re-opened contract. Re-take the two `Measured after` tables in `TODOS.md` at that point rather than copying A6's numbers, since A2–A5 may move them. Push and let CI confirm before starting Phase B.
+>
+> Per [D-R4](#decisions-taken), the checkpoint covers A1's doc fix plus A2–A8 only — **no red entry point is added in #1062**; the remedy lands in the A1-PR after merge. [F1](#f1-the-layer-rule-is-only-enforced-one-hop-deep) plus the corrected Known-inversions section are the record that keeps the breach visible in the meantime.
+
+## Phase B — test hardening
+
+Additive; landed in one commit after Checkpoint A. B1 and B2 are the two that pin things the current tests only *appear* to pin.
+
+**Every item was verified by mutation, not by watching it go green** — the pinned behavior was removed, the new test was confirmed to fail, and the mutation reverted. What each mutation showed is recorded per item.
+
+- [x] **B1 — test the real teardown, not a simulation.** ✅ Applied. `tests/unit/pipelex/test_hub_lifecycle.py:70` calls `class_registry_scoping.reset() # what Pipelex.teardown does`. Nothing pinned that the production lines in `Pipelex.teardown` / `teardown_if_needed` do anything — delete them and the suite stayed green, because a stale `_library_id` resolves to `None` and falls back to the global registry rather than raising. Added a real boot → pin a scoped library → `Pipelex.teardown_if_needed()` → assert unscoped → fresh `Pipelex.make()` → assert the resolver is re-installed. The simulation test is kept (it pins `reset()`'s own semantics) with its comment corrected so it no longer claims to cover the wiring. **Mutation-verified**: deleting `class_registry_scoping.reset()` from `Pipelex.teardown` fails the new test and *only* it — the other three in the module still pass, which is exactly the finding.
+- [x] **B2 — give the closure detector a negative control.** ✅ Applied. `_CLOSURE_SCRIPT` is a `textwrap.dedent` string, so no linter sees `INTERPRETER_PACKAGES` / `is_interpreter`; a typo makes all entry points pass vacuously, forever. Parametrized `(entry_point, expected_returncode)` with `pipelex.interpreter_hub` as the dirty case. **One thing the plan did not anticipate, and it changes the assertion**: asserting `returncode == 1` alone would *not* have pinned the predicate, because the script's second check (`pipelex.interpreter_hub in sys.modules`) exits 1 for that entry point regardless. The test asserts the **offender message** as well, so the control fails when `is_interpreter` stops working. **Mutation-verified**: typo-ing `INTERPRETER_PACKAGES` and emptying `INTERPRETER_CORE` fails the control while all eight clean entry points pass vacuously — the exact failure mode.
+- [x] **B3 — cover `check_hub_layering_cmd`.** ✅ Applied as `tests/unit/pipelex/cli/dev/test_check_hub_layering_cmd.py`, mirroring `test_check_keyword_only_cmd_fix.py`'s mocked-console/mocked-scanner shape. Covers both `sys.exit(1)` paths, the quiet/panel split both ways, the per-kind grouping with its remedy, and that the success panel names every declared runtime-layer package. The missing-root case asserts the scanner is **never called** — scanning nothing must not read as a pass. **Mutation-verified**: removing both `sys.exit(1)` calls fails four of the six tests.
+- [x] **B4 — cover the guard's filesystem surface.** ✅ Applied as `tests/unit/pipelex/cli/dev/test_hub_layering_guard_filesystem.py`, a tmp tree in the style of `test_keyword_only_guard_single_file.py`. Covers `collect_all_violations` over both roots (a runtime-layer breach reported, the identical import in `pipeline/` correctly *not*, a `tests/` dead-hub string reported), `iter_source_files`' `__pycache__` exclusion, and `module_qname_for`'s `__init__`-stripping both directly and end to end through a real scan. **Mutation-verified**: dropping the `__pycache__` skip fails two tests.
+- [x] **B5 — test `concept_provider` as an actual injection.** ✅ Applied as `tests/unit/pipelex/core/memory/input_shaper/test_provider_injection.py`. A `mocker.Mock(spec=ConceptProviderAbstract)` whose `is_compatible` only ever matches `Number` moves a `Text` concept from the TEXT arm to the NUMBER arm — an outcome unreachable through the real library. **Mutation-verified**: making `resolve_input_kind` accept the parameter and then call `get_concept_library()` anyway fails this test alone, with all 69 other `input_shaper` tests green.
+- [x] **B6 — tighten the `TYPE_CHECKING` carve-out.** ✅ Applied — tightened, not pinned-as-deliberate. `_is_type_checking_test` now requires the receiver to be `Name(id="typing")` (new `TYPING_MODULE_NAME` constant), with a test asserting three unrelated receivers stay violations. Verified safe first: nothing in `pipelex/` or `tests/` uses the attributed form at all, let alone under an alias. **Mutation-verified**: reverting to `ast.Attribute(attr=attr)` fails the new test and nothing else.
+- [x] **B7 — bound the closure subprocess.** ✅ Applied. `subprocess.run` gained `timeout=SUBPROCESS_TIMEOUT_SECONDS`, wrapped in a `_run_closure` helper that turns `TimeoutExpired` into an `AssertionError` naming the entry point and the bound.
+
+> **CHECKPOINT B** ✅ **CLEARED** — `make agent-check` ✅ · full `make agent-test` ✅ · `make drift-check` ✅.
+>
+> **Correction to this plan: B6 *does* re-open a drift contract.** `pipelex/cli/dev_cli/commands/hub_layering_guard.py` is a `hub-layering-convention` trigger, so the note that said "nothing here re-opens a drift contract" was wrong. Reviewed and acked: `docs/contribute/hub-layering.md`'s `TYPE_CHECKING` bullet now states the receiver constraint, and its two test-module sentences were refreshed for B1/B2/B7. Worth carrying forward — the review caught staleness the contract's own triggers **cannot** see: the two test modules are deliberately not triggers, so the contract fired on the guard and the read-through found the spillover. Logged in `wip/drift-contracts/dogfood-log.md` as the second consecutive `real-catch` for this contract.
+>
+> Per [D-R4](#decisions-taken) the property-side fix is in the A1-PR, not here: no new green entry point landed in #1062, and B2's control is dirty by definition so it survives the remedy unchanged.
+
+## Phase C — release-wave additions
+
+Per **D-R1**, none of this lands in PR #1062. Fold it into the existing release-gated cross-repo sweep in `TODOS.md`.
+
+### C1 — `pipelex.hub` is a governed, spec'd, conformance-tested surface
+
+`docs/specs/pipelex-transport-boundary.md` §A declares it: *"The `pipelex.hub` module is the intended cross-boundary seam; these accessors are stable by design."* It is verified by `conformance/tests/pipelex_transport/test_provider_surface.py`, which carries **no skip marker** — it is active. Running that suite's own `ALLOWED_SURFACE` against this branch:
+
+```
+governed surface entries: 41
+BROKEN by this branch: 7
+ MODULE DELETED pipelex.hub::get_orchestrator_registry
+ MODULE DELETED pipelex.hub::get_required_pipe
+ MODULE DELETED pipelex.hub::get_library_manager
+ MODULE DELETED pipelex.hub::scoped_current_library
+ MODULE DELETED pipelex.hub::get_current_library_id_or_none
+ MODULE DELETED pipelex.pipeline.job_metadata::JobMetadata
+ MODULE DELETED pipelex.graph.trace_context::TraceContext
+```
+
+The workspace `CLAUDE.md` rule is explicit: *"When you change a documented surface in `docs/specs/` or its verifying test in `conformance/`, update both sides in the same change and run `make check-spec-links`."* Strictly, this PR is already out of compliance with that rule; D-R1 accepts that consciously because the whole consumer sweep is release-gated and splitting spec-from-consumers would be worse. **The release wave must update section A of the spec** (all five accessors are interpreter-layer), retarget the `JobMetadata` / `TraceContext` rows to `pipelex.system.*`, update `conformance/tests/pipelex_transport/test_data.py` in lockstep, and run `make check-spec-links` in `conformance/`.
+
+### C2 — five consumer repos are missing from the sweep tables
+
+Every count the tables *do* list reproduces exactly (temporal 35, mistralai-workflows 11, api 9, cookbook 2, cocode 2). They are simply incomplete:
+
+| repo | `pipelex.hub` files | moved-type files | pipelex pin | why it matters |
+| --- | --- | --- | --- | --- |
+| `pipelex-transport` | **8** (2 production) | 7 | `>=0.40.0` | `pipelex_transport/bridge.py:165` calls `WorkingMemoryFactory.make_from_pipeline_inputs` **without the now-required `concept_provider`** — the only production call site of a changed signature outside this repo |
+| `pipelex-daytona-sandbox` | 1 | 3 | `>=0.40.0` | **entry-point plugin** (`[project.entry-points."pipelex.plugins"]`), so it fails inside a *host* pipelex process at registration, not in its own tests |
+| `pipelex-demo-mistral` | 9 | 5 | `>=0.35.0` | 4+ example workflows call the changed signature |
+| `pipelex-demo-vibe` | 9 | 5 | `>=0.35.0` | same (both are checkouts of `pipelex-demos.git`) |
+| `conformance` | — | 1 | dynamic | C1 above |
+
+All unbounded `>=` pins, so all resolve to the new release. `pipelex-workshop` (`==0.20.3`) and `pipelex-demos` / `pipelex-demo-frostbeam` (`==0.34.0`) also import `pipelex.hub` but are version-pinned, so they are safe — list them for completeness, not urgency. `test-bed` has one test-only import at `>=0.18.3`.
+
+Note that `pipelex-transport` and `pipelex-daytona-sandbox` are **absent from the workspace `CLAUDE.md` repo table too**, which is why they were missed. Adding them there is the durable fix; otherwise the next sweep misses them again.
+
+### C3 — the moved types are a wire-format change, not only an import change
+
+`CHANGELOG.md:8` says *"only the Python homes moved."* For `JobMetadata` and `TraceContext` that undersells it: kajson embeds `__module__` in the serialized payload, and the Temporal data converter kajson-encodes every `BaseModel` crossing the workflow/activity boundary — `PipeJob.job_metadata: JobMetadata` is on that path. Verified: encoding now emits `"__module__": "pipelex.system.job_metadata"`, and decoding an old payload raises `KajsonDecoderError`.
+
+**This is not a bug** — Temporal has never shipped to production, and the repo's no-backward-compat policy is explicit. It is worth one changelog sentence so a plugin maintainer knows the runner and worker must roll forward together rather than independently.
+
+## Considered and not changed
+
+Recorded so these are not re-litigated. Each was investigated and is a deliberate tradeoff, not an oversight:
+
+- **`class_registry_scoping.reset()` in `Pipelex.teardown` is process-global while `_library_id` is a ContextVar.** A run still in flight when teardown fires loses its per-run scoped registry and falls back to the shared one (which `KajsonManager.teardown()`, twelve lines earlier, has already re-minted empty). Pre-refactor this window did not exist. Reachability is narrow — process shutdown or a failed boot with concurrent in-flight runs — and everything else is being demolished at that moment anyway. **D-R3: accepted as designed**; the reset is what makes a torn-down library unreachable, which is the property step 1.7 was written for.
+- **boto3 loads eagerly in every booted process.** `pipelex/tracing/event_log_factory.py:5` imports `dynamodb_event_log`, which runs a module-level `try: import boto3` unconditionally — even for the default NDJSON backend. It is **not** in the guarded runtime closure, so the headline property is unaffected, but it *is* in `import pipelex.pipelex`'s closure: ~41 ms and ~150 modules, against the ~27 ms this entire refactor buys on full boot. A three-line fix (move the import into the `case TracingBackend.DYNAMODB:` branch, the pattern `render_generate.py` already uses for pypdfium2). Out of scope here, but the tracker should stop filing it under "not scheduled" when it dominates the number the tracker headlines.
+- **The D5 indirection costs ~32 ns per `get_class_registry()` call** (213 ns → 245 ns, three frames instead of one). Not on any hot path — the call sites are per-concept-resolution, not per-item. No action; recorded so nobody collapses the layering later on a hunch, since the indirection is what makes the zero-interpreter closure possible.
+- **Wall-clock is a smaller win than the module count suggests.** `content_generator` improves 412 ms → 359 ms (-13%), but `import pipelex.pipelex` only 718 ms → 691 ms (-4%), because third-party imports dominate and are untouched (767 non-pipelex modules remain: pydantic 70, faker 66, rich 63, markdown_it 62, polyfactory 28). Nothing in the PR overstates this; the tracker simply does not state it. The win is architectural and accrues to runtime-only embedders, not to CLI startup.
+- **The published `hub-layering.md` points at `wip/pr-1062-review-notes.md`**, and two test docstrings do the same. `wip/` is outside `docs_dir`, so the reference is unreachable for a reader on docs.pipelex.com, and the file is by convention archived once the PR lands. Fold the wart into one in-place sentence in the published doc and keep the pointer only in `TODOS.md`. Low priority; batch it with A5 if convenient.
+- **`drift.toml`'s `hub-layering-convention` omits `pipelex/system/registries/class_registry_access.py`** from its triggers, though the doc it protects devotes a named section to that module. Renaming `class_registry_scoping` or changing the default-resolver semantics would silently falsify it. One line to add whenever the contract is next touched.
+- **`hub_layering_guard` duplicates two filesystem helpers from `keyword_only_guard`.** The stated rationale is half right: `keyword_only_guard` genuinely is stdlib-only and has a by-path `__main__` entry, so a shared third module would defeat its cold-start budget — but that does not explain why `hub_layering_guard` could not import *from* it, since it has no `__main__` and its only importer already pulls `pipelex.runtime_hub`. The copies have already drifted (positional vs keyword-only signatures). Either import them or correct the docstring.
+
+## Reproduction commands
+
+Everything above was measured with these. Run from `_hub/`.
+
+```bash
+# F1 — a declared runtime-layer module reaching interpreter_hub transitively.
+# Swap in pipelex.config / pipelex.cogt.content_generation.content_generator / pipelex.runtime_hub
+# for the F1.c control: those measure interp=0 and never load plugins.builtins.
+for m in pipelex.plugins.direct.direct_plugin pipelex.plugins.discovery; do
+ .venv/bin/python -c "
+import sys, importlib
+importlib.import_module('$m')
+INTERP={'libraries','pipe_operators','pipe_controllers','codegen','builder'}
+mods=[n for n in sys.modules if n.startswith('pipelex.')]
+print('$m', 'interpreter_hub=', 'pipelex.interpreter_hub' in sys.modules,
+ 'interp=', len([n for n in mods if n.split('.')[1] in INTERP]),
+ 'builtins=', 'pipelex.plugins.builtins' in sys.modules)"
+done
+.venv/bin/pipelex-dev check-hub-layering --quiet # still PASSED
+
+# F1.b — the shortest real import path to each offender, traced rather than guessed
+.venv/bin/python -c "
+import importlib, sys
+chain, stack = {}, []
+real = importlib._bootstrap._find_and_load
+def traced(name, import_):
+ if stack and name not in chain: chain[name] = stack[-1]
+ stack.append(name)
+ try: return real(name, import_)
+ finally: stack.pop()
+importlib._bootstrap._find_and_load = traced
+importlib.import_module('pipelex.plugins.discovery')
+for target in ('pipelex.interpreter_hub', 'pipelex.libraries', 'pipelex.builder', 'pipelex.codegen'):
+ path, cur = [target], target
+ while cur in chain: cur = chain[cur]; path.append(cur)
+ print(' <- '.join(path))"
+
+# F1.a / F1.d — the static sweep: which declared runtime-layer modules reach interpreter_hub,
+# and which declared packages have no closure-test entry point.
+.venv/bin/python - <<'PY'
+import ast, sys
+from collections import deque
+from pathlib import Path
+sys.path.insert(0, ".")
+from pipelex.cli.dev_cli.commands.hub_layering_guard import RUNTIME_LAYER_PACKAGES, is_runtime_layer
+
+def qname(p):
+ parts = list(p.with_suffix("").parts)
+ return ".".join(parts[:-1] if parts[-1] == "__init__" else parts)
+
+class V(ast.NodeVisitor):
+ def __init__(self, pkg): self.pkg, self.out, self.tc = pkg, set(), 0
+ def visit_If(self, n):
+ t = n.test
+ if (isinstance(t, ast.Name) and t.id == "TYPE_CHECKING") or (isinstance(t, ast.Attribute) and t.attr == "TYPE_CHECKING"):
+ self.tc += 1
+ for s in n.body: self.visit(s)
+ self.tc -= 1
+ for s in n.orelse: self.visit(s)
+ else: self.generic_visit(n)
+ def visit_FunctionDef(self, n): pass # deferred imports do not load
+ def visit_AsyncFunctionDef(self, n): pass
+ def visit_Import(self, n):
+ if not self.tc:
+ self.out.update(a.name for a in n.names if a.name.startswith("pipelex"))
+ def visit_ImportFrom(self, n):
+ if self.tc: return
+ if n.level:
+ parts = self.pkg.split(".") if self.pkg else []
+ base = ".".join(parts[: len(parts) - (n.level - 1)])
+ base = f"{base}.{n.module}" if n.module else base
+ else: base = n.module or ""
+ if base.startswith("pipelex"):
+ self.out.add(base); self.out.update(f"{base}.{a.name}" for a in n.names)
+
+edges, all_mods = {}, set()
+for p in sorted(Path("pipelex").rglob("*.py")):
+ if "__pycache__" in p.parts: continue
+ q = qname(p); all_mods.add(q)
+ v = V(".".join(p.parent.parts)); v.visit(ast.parse(p.read_text(encoding="utf-8")))
+ edges[q] = v.out
+
+def resolve(c):
+ while c:
+ if c in all_mods: return c
+ if "." not in c: return None
+ c = c.rsplit(".", 1)[0]
+
+TARGET = "pipelex.interpreter_hub"
+runtime_mods = sorted(m for m in all_mods if is_runtime_layer(module_qname=m))
+
+# --- Remedy (d) simulation: uncomment the four edits to measure the split+relocation ----
+# Must run BEFORE the BFS below, since it rewrites the edges the BFS walks.
+# Expect: 128 scanned, 0 reaching interpreter_hub (against 476 / 4 unsimulated).
+# RELOCATED = {m for m in all_mods if m.startswith(("pipelex.plugins.direct", "pipelex.plugins.pipe_func."))}
+# edges["pipelex.plugins.builtins"] = {e for e in edges["pipelex.plugins.builtins"]
+# if not e.startswith(("pipelex.plugins.direct", "pipelex.plugins.pipe_func."))} # builtins splits
+# edges["pipelex.plugins.discovery"] = {e for e in edges["pipelex.plugins.discovery"]
+# if not e.startswith("pipelex.plugins.builtins")} # discovery takes a param
+# runtime_mods = [m for m in runtime_mods if m.startswith("pipelex.plugins") and m not in RELOCATED]
+
+bad = {}
+for start in runtime_mods:
+ seen, q = {start}, deque([(start, [start])])
+ while q and start not in bad:
+ cur, path = q.popleft()
+ for raw in edges.get(cur, ()):
+ m = resolve(raw)
+ if m is None or m in seen: continue
+ if m == TARGET: bad[start] = path + [m]; break
+ seen.add(m); q.append((m, path + [m]))
+
+print(f"scanned {len(runtime_mods)} declared runtime-layer modules; {len(bad)} reach {TARGET}")
+EPS = ["pipelex.cogt.content_generation.content_generator", "pipelex.runtime_hub",
+ "pipelex.core.concepts.structure_generation.generator", "pipelex.core.memory.input_shaper",
+ "pipelex.core.memory.working_memory_factory", "pipelex.core.pipes.inputs.input_stuff_specs_factory",
+ "pipelex.core.pipes.stuff_spec.stuff_spec_factory", "pipelex.core.stuffs.stuff_factory"]
+for pkg in RUNTIME_LAYER_PACKAGES:
+ inside = lambda m: m == pkg or m.startswith(pkg + ".")
+ n = len([m for m in bad if inside(m)])
+ tot = len([m for m in runtime_mods if inside(m)])
+ ep = "COVERED" if any(inside(e) for e in EPS) else "NO ENTRY POINT"
+ print(f" {pkg:38s} {n:4d} / {tot:4d} breaching {ep}")
+for m, path in sorted(bad.items()): print(" ", " -> ".join(path))
+PY
+
+# F2 — the guard exempts runtime_hub.py from its own rule
+.venv/bin/python -c "
+import sys; sys.path.insert(0, '.')
+from pipelex.cli.dev_cli.commands.hub_layering_guard import is_runtime_layer
+print('runtime_hub is runtime layer:', is_runtime_layer(module_qname='pipelex.runtime_hub'))"
+
+# C1 — the governed surface, broken
+.venv/bin/python -c "
+import ast, importlib
+from pathlib import Path
+p = Path('/Users/lchoquel/repos/Pipelex/conformance/tests/pipelex_transport/test_data.py')
+for node in ast.walk(ast.parse(p.read_text())):
+ if isinstance(node, ast.AnnAssign) and getattr(node.target, 'id', '') == 'ALLOWED_SURFACE':
+ surface = [tuple(ast.literal_eval(e)) for e in node.value.elts]; break
+for mod, sym, _ in surface:
+ try: importlib.import_module(mod)
+ except ModuleNotFoundError: print('MODULE DELETED', f'{mod}::{sym}')"
+
+# The headline property (unchanged, still exact) — full snippet in TODOS.md 'Exit criteria'
+```
diff --git a/wip/pr-1062-review-notes.md b/wip/pr-1062-review-notes.md
new file mode 100644
index 000000000..dcdf73520
--- /dev/null
+++ b/wip/pr-1062-review-notes.md
@@ -0,0 +1,26 @@
+# PR #1062 review notes — deferred items
+
+Triage record for the SWE-agent review threads on [PR #1062](https://github.com/Pipelex/pipelex/pull/1062) (the `pipelex.hub` split into `runtime_hub` / `interpreter_hub`, plus the layering guard and the import-closure test). One unresolved thread, from Codex ([`PRRT_kwDOOwmMFc6T2CA7`](https://github.com/Pipelex/pipelex/pull/1062#discussion_r3652317405)), on `tests/unit/pipelex/test_runtime_layer_import_closure.py`: the closure predicate only recognised five interpreter top-level packages, which is narrower than the interpreter layer `docs/contribute/hub-layering.md` describes.
+
+Two of the three parts were fixed in-place — the doc's `pipe_output` misclassification, and the predicate widening that closes the real `core.pipes.pipe_blueprint` blind spot. This file captures the part deliberately **deferred**. Its thread is left **open**.
+
+## 1. Interpreter-named packages leak leaf models into every runtime closure
+
+- **Reporter:** Codex (thread `PRRT_kwDOOwmMFc6T2CA7`), on `tests/unit/pipelex/test_runtime_layer_import_closure.py`. Codex asked for the predicate to cover "the complete documented interpreter layer", naming `pipeline` and `pipe_run` among the gaps.
+- **Verdict:** confirmed as a fact, but it is a *placement* problem, not a broken hub arrow — so naming those packages in the closure predicate would turn the test red without any code being wrong in the sense the test measures.
+- **What is actually loaded.** Measured in a clean subprocess:
+ - `pipelex.runtime_hub`'s own closure pulls `pipelex.pipeline.pipeline_models` (`SpecialPipelineId`), `pipelex.pipe_run.pipe_run_mode` (`PipeRunMode`) and `pipelex.graph.graphspec` (`GraphSpec`) — all three reached through `pipelex.core.pipes.pipe_output`, which names them as fields.
+ - `pipelex.core.stuffs.stuff_factory` additionally pulls `pipelex.pipeline.exceptions`, `pipelex.pipeline.validation_errors` and `pipelex.pipeline.fixes.planner`, which in turn pull `pipelex.core.bundles.exceptions` (`PipelexBundleBlueprintValidationErrorData`) and, as collateral, the empty `pipelex.core.bundles` package placeholder.
+- **Why deferred:** every one of those is a leaf model or an exception type — a `StrEnum`, a run-id constant, a graph spec, structured validation-error data. None of them imports the interpreter; none of them needs a loaded method. They are interpreter-layer only by virtue of *which package they were filed in*. Resolving that means relocating types across package boundaries, which changes public import paths (`GraphSpec` and `PipeRunMode` are both consumed outside this repo) — a refactor with cross-repo churn, not something a PR-review pass should decide unilaterally.
+- **Current state in the test.** The predicate covers the five interpreter top-level packages plus core's Pipe-machinery modules by name (`core.bundles`, `core.interpreter`, `core.registry_models`, `core.pipes.pipe_abstract` / `pipe_blueprint` / `pipe_factory` / `rendering`). `core.bundles.exceptions` and the bare `core.bundles` placeholder are excluded by **exact** match, so the rest of `core.bundles` stays flagged. `pipeline`, `pipe_run` and `graph` are absent entirely.
+- **Recommendation — two candidate resolutions, pick one deliberately:**
+ 1. **Relocate the leaves down**, mirroring the `JobMetadata` / `TraceContext` moves this PR already records under "Placement, not coupling": `SpecialPipelineId` and `PipeRunMode` into `pipelex/system/`, and decide a home for `GraphSpec` that is not `graph/` (which also carries mermaid/reactflow rendering). Then the predicate can name `pipeline` and `pipe_run` wholesale and the exclusion tuple disappears. This is the resolution consistent with the doc's own stated lesson — "when a package straddles the boundary, moving the odd module out is usually cheaper than teaching the guard about exceptions."
+ 2. **Declare them straddling**, i.e. accept that `pipeline` / `pipe_run` / `graph` are not single-layer packages the way `core/` is not, and say so explicitly in "Where core splits" (renaming it accordingly). Cheaper, but it weakens the claim that the boundary falls on package lines.
+- **Note on `core.bundles.exceptions` specifically:** the reason it is imported from `pipeline/` at all is that `PipelexBundleBlueprintValidationErrorData` is the payload of `pipeline`'s validation-error types. If option 1 is taken, that one is the awkward case — the data shape genuinely belongs with the bundle blueprint, and the importer is the thing in the wrong layer.
+
+## Not deferred — fixed on this branch
+
+Recorded here only so the thread's three parts are traceable:
+
+- **`pipe_output` was misclassified in the doc.** `docs/contribute/hub-layering.md` listed `core.pipes.pipe_output` under "The Pipe machinery — interpreter" with the justification "Every one of them names a `Pipe`". It names no `Pipe`: it holds the working memory, graph spec and token usage a run *produced*. It imports zero interpreter modules, and it sits inside `runtime_hub`'s own closure — which the same document shows three sections later, in the class-registry import chain. The guard's own docstring (the enforcement source of truth) correctly omitted it. Moved to the runtime data-model bullet.
+- **`core.pipes.pipe_blueprint` was a genuine blind spot.** Documented interpreter-layer by both the doc and the guard, yet it loads zero heavy packages and no hub — so a runtime-layer import of it passed a package-only predicate. Every other documented interpreter module was caught only *transitively*, through the `pipe_operators` / `libraries` it happens to drag in. The widened predicate now names them, so it states the boundary instead of approximating it.