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.
Handle first-run inference setup as friendly markdown (#811)
Louis Choquelfbf3e696d525
diff --git a/pipelex/builder/operations/pipe_ops.py b/pipelex/builder/operations/pipe_ops.pyindex 61a868843..cc3c3104f 100644--- a/pipelex/builder/operations/pipe_ops.py+++ b/pipelex/builder/operations/pipe_ops.py@@ -127,7 +127,9 @@ def parse_pipe_spec(pipe_type: str, spec_data: dict[str, Any]) -> PipeSpec:# Handle {"type": "ConceptName"} and single-item dicts like {"result": "Text"}.if "output" in spec_data and isinstance(spec_data["output"], dict):output_dict: dict[str, Any] = spec_data["output"]- if "type" in output_dict:+ if "concept_ref" in output_dict:+ spec_data["output"] = output_dict["concept_ref"]+ elif "type" in output_dict:spec_data["output"] = output_dict["type"]elif len(output_dict) == 1:spec_data["output"] = next(iter(output_dict.values()))diff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.pyindex 5813fd118..1601bf91f 100644--- a/pipelex/cli/agent_cli/_agent_cli.py+++ b/pipelex/cli/agent_cli/_agent_cli.py@@ -8,6 +8,7 @@ from mthds.runners.types import RunnerTypefrom typer.core import TyperGroupfrom typing_extensions import override+from pipelex.cli.agent_cli.commands.accept_gateway_terms_cmd import agent_accept_gateway_terms_cmdfrom pipelex.cli.agent_cli.commands.check_model_cmd import agent_check_model_cmdfrom pipelex.cli.agent_cli.commands.concept_cmd import concept_cmdfrom pipelex.cli.agent_cli.commands.doctor_cmd import agent_doctor_cmd@@ -39,6 +40,7 @@ class PipelexAgentCLI(TyperGroup):"pipe","models","check-model",+ "accept-gateway-terms","doctor",]@@ -130,4 +132,5 @@ app.command(name="concept", help="Structure a concept from JSON spec and outputapp.command(name="pipe", help="Structure a pipe from JSON spec and output TOML")(pipe_cmd)app.command(name="models", help="List available model presets, aliases, and waterfalls")(agent_models_cmd)app.command(name="check-model", help="Check if a model reference is valid and suggest alternatives")(agent_check_model_cmd)+app.command(name="accept-gateway-terms", help="Accept Pipelex Gateway terms and mark inference setup complete")(agent_accept_gateway_terms_cmd)app.command(name="doctor", help="Check Pipelex configuration health and auto-fix issues")(agent_doctor_cmd)diff --git a/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py b/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.pynew file mode 100644index 000000000..7c310be8a--- /dev/null+++ b/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py@@ -0,0 +1,39 @@+"""Agent CLI command to accept Pipelex Gateway terms and mark inference setup complete."""++import typer++from pipelex.cli.agent_cli.commands.agent_output import agent_error, agent_success+from pipelex.system.configuration.config_loader import config_manager+from pipelex.system.pipelex_service.pipelex_service_agreement import (+ update_inference_setup_completed,+ update_service_terms_acceptance,+)+++def agent_accept_gateway_terms_cmd() -> None:+ """Accept Pipelex Gateway terms and mark inference setup as completed.++ Records the user's acceptance of the Pipelex Gateway Terms of Service+ and Privacy Policy, and marks inference setup as completed so the+ first-run onboarding flow does not trigger again.+ """+ try:+ config_dir = config_manager.global_config_dir+ config_dir.mkdir(parents=True, exist_ok=True)+ update_service_terms_acceptance(accepted=True, config_dir=config_dir)+ update_inference_setup_completed(completed=True, config_dir=config_dir)+ agent_success(+ {+ "success": True,+ "terms_accepted": True,+ "inference_setup_completed": True,+ }+ )+ except typer.Exit:+ raise+ except Exception as exc:+ agent_error(+ f"Failed to accept gateway terms: {exc}",+ type(exc).__name__,+ cause=exc,+ )diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.pyindex f7f4f4811..813cd7171 100644--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py@@ -2,6 +2,8 @@from pathlib import Path+import typer+from pipelex.cli.agent_cli.commands.agent_output import agent_errorfrom pipelex.cogt.exceptions import ModelDeckPresetValidatonErrorfrom pipelex.pipelex import Pipelex@@ -9,6 +11,7 @@ from pipelex.system.pipelex_service.exceptions import (GatewayApiKeyMissingError,GatewayDoNotTrackConflictError,GatewayTermsNotAcceptedError,+ InferenceSetupRequiredError,RemoteConfigFetchError,RemoteConfigValidationError,)@@ -48,6 +51,17 @@ def make_pipelex_for_agent_cli(pipelex_instance = Pipelex.make(integration_mode=IntegrationMode.CLI, library_dirs=library_dirs, needs_inference=needs_inference, needs_model_specs=needs_model_specs)+ except InferenceSetupRequiredError:+ print(+ "# First-time inference setup required\n"+ "\n"+ "This looks like your first time running a method with live inference.\n"+ "You need to configure an inference backend before running.\n"+ "\n"+ "Use `/mthds-runner-setup` for guided setup, "+ "or run `pipelex-agent init` with appropriate backend configuration."+ )+ raise typer.Exit(0) from Noneexcept TelemetryConfigValidationError as exc:agent_error(exc.message, "TelemetryConfigValidationError", cause=exc)except GatewayTermsNotAcceptedError as exc:diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.pyindex 63638fc49..b77d68a67 100644--- a/pipelex/cli/agent_cli/commands/init_cmd.py+++ b/pipelex/cli/agent_cli/commands/init_cmd.py@@ -17,8 +17,11 @@ from pipelex.cogt.model_backends.backend import PipelexBackendfrom pipelex.cogt.model_routing.routing_profile import PipelexRoutingProfilefrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.system.configuration.config_loader import config_manager-from pipelex.system.pipelex_service.pipelex_service_agreement import update_service_terms_acceptance-from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, PostHogMode+from pipelex.system.pipelex_service.pipelex_service_agreement import (+ update_inference_setup_completed,+ update_service_terms_acceptance,+)+from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAMEfrom pipelex.tools.misc.file_utils import path_existsfrom pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path@@ -119,6 +122,18 @@ def _copy_inference_templates(target_dir: Path) -> None:shutil.copy2(template_routing_path, target_inference_dir / "routing_profiles.toml")+def _copy_telemetry_template(target_dir: Path) -> None:+ """Copy the telemetry template (defaults to off) to the target directory.++ Args:+ target_dir: Target config directory (e.g. .pipelex/).+ """+ template_path = Path(str(get_kit_configs_dir())) / TELEMETRY_CONFIG_FILE_NAME+ target_path = target_dir / TELEMETRY_CONFIG_FILE_NAME+ target_path.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(template_path, target_path)++def _configure_backends(config: dict[str, Any],backends_toml_path: str,@@ -163,11 +178,12 @@ def _configure_backends(update_backends_in_toml(toml_doc, selected_indices, backend_options)save_toml_to_path(toml_doc, backends_toml_path)- # Handle pipelex_gateway terms acceptance+ # Handle pipelex_gateway terms acceptance (only when explicitly provided)if PipelexBackend.GATEWAY in requested_backends:- accept_terms: bool = config.get("accept_gateway_terms", False)- config_manager.global_config_dir.mkdir(parents=True, exist_ok=True)- update_service_terms_acceptance(accepted=accept_terms, config_dir=config_manager.global_config_dir)+ accept_terms = config.get("accept_gateway_terms")+ if accept_terms is not None:+ config_manager.global_config_dir.mkdir(parents=True, exist_ok=True)+ update_service_terms_acceptance(accepted=accept_terms, config_dir=config_manager.global_config_dir)return requested_backends@@ -261,44 +277,6 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],return "custom_routing"-def _configure_telemetry(target_dir: Path, config: dict[str, Any]) -> str:- """Copy telemetry template to target directory and apply telemetry_mode if specified.-- Args:- target_dir: Target config directory.- config: Parsed config dict with optional 'telemetry_mode' key.-- Returns:- The telemetry mode that was set.- """- telemetry_config_path = target_dir / TELEMETRY_CONFIG_FILE_NAME- template_path = Path(str(get_kit_configs_dir() / TELEMETRY_CONFIG_FILE_NAME))-- if not template_path.exists():- agent_error("Telemetry template not found in kit configs", "InitConfigError")-- telemetry_config_path.parent.mkdir(parents=True, exist_ok=True)- shutil.copy(template_path, telemetry_config_path)-- # Apply telemetry_mode if specified- requested_mode: str | None = config.get("telemetry_mode")-- if requested_mode is not None:- valid_modes = [mode.value for mode in PostHogMode]- if requested_mode not in valid_modes:- agent_error(- f"Invalid telemetry_mode: '{requested_mode}'. Valid values: {', '.join(valid_modes)}",- "ArgumentError",- )-- toml_doc = load_toml_with_tomlkit(telemetry_config_path)- toml_doc["custom_posthog"]["mode"] = requested_mode # type: ignore[index]- save_toml_to_path(toml_doc, telemetry_config_path)- return requested_mode-- return PostHogMode.OFF.value--def agent_init_cmd(config: Annotated[str | None,@@ -307,12 +285,11 @@ def agent_init_cmd("-c",help=("Inline JSON string or path to a JSON file. "- 'Schema: {"backends": list[str], "primary_backend": str, "accept_gateway_terms": bool, "telemetry_mode": str}. '+ 'Schema: {"backends": list[str], "primary_backend": str, "accept_gateway_terms": bool}. '"All fields are optional. ""backends: backend keys to enable (e.g. 'openai', 'anthropic', 'pipelex_gateway'). Omit to keep template defaults. ""primary_backend: required only when 2+ backends are selected and pipelex_gateway is not among them. "- "accept_gateway_terms: true/false, required when pipelex_gateway is in backends. "- "telemetry_mode: 'off' (default), 'anonymous', or 'identified'."+ "accept_gateway_terms: true/false, required when pipelex_gateway is in backends."),),] = None,@@ -339,15 +316,15 @@ def agent_init_cmd({"backends": ["pipelex_gateway", "openai"],"accept_gateway_terms": true,- "primary_backend": "openai",- "telemetry_mode": "off"+ "primary_backend": "openai"}- backends: list of backend keys to enable. Omit to keep all template defaults.- accept_gateway_terms: sets gateway terms acceptance (true/false).- primary_backend: required when 2+ backends are selected and pipelex_gatewayis not among them. Auto-derived when only 1 backend or pipelex_gateway is present.- - telemetry_mode: "off", "anonymous", or "identified". Defaults to "off".++ Telemetry is always initialized to "off" (can be changed manually in telemetry.toml)."""try:# Parse config@@ -362,6 +339,9 @@ def agent_init_cmd(# Step 1.5: Copy inference templates (init_config skips inference/)_copy_inference_templates(target_dir)+ # Step 1.6: Copy telemetry template (defaults to off)+ _copy_telemetry_template(target_dir)+# Step 2: Configure backendstemplate_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")backends_toml_path = str(target_dir / "inference" / "backends.toml")@@ -370,8 +350,8 @@ def agent_init_cmd(# Step 3: Configure routingrouting_profile = _configure_routing(backends_enabled, parsed_config, target_dir)- # Step 4: Configure telemetry- telemetry_mode = _configure_telemetry(target_dir, parsed_config)+ # Step 4: Mark inference setup as completed+ update_inference_setup_completed(completed=True, config_dir=config_manager.global_config_dir)# Output resultagent_success(@@ -381,7 +361,7 @@ def agent_init_cmd("config_files_copied": config_files_copied,"backends_enabled": backends_enabled,"routing_profile": routing_profile,- "telemetry_mode": telemetry_mode,+ "inference_setup_completed": True,})diff --git a/pipelex/cli/cli_factory.py b/pipelex/cli/cli_factory.pyindex 1dd111186..aa981112b 100644--- a/pipelex/cli/cli_factory.py+++ b/pipelex/cli/cli_factory.py@@ -7,6 +7,7 @@ from pipelex.cli.error_handlers import (handle_gateway_api_key_missing_error,handle_gateway_do_not_track_conflict_error,handle_gateway_terms_not_accepted_error,+ handle_inference_setup_required_error,handle_model_deck_preset_error,handle_remote_config_fetch_error,handle_remote_config_validation_error,@@ -18,6 +19,7 @@ from pipelex.system.pipelex_service.exceptions import (GatewayApiKeyMissingError,GatewayDoNotTrackConflictError,GatewayTermsNotAcceptedError,+ InferenceSetupRequiredError,RemoteConfigFetchError,RemoteConfigValidationError,)@@ -52,6 +54,8 @@ def make_pipelex_for_cli(return Pipelex.make(integration_mode=IntegrationMode.CLI, library_dirs=library_dirs, needs_inference=needs_inference, needs_model_specs=needs_model_specs)+ except InferenceSetupRequiredError as exc:+ handle_inference_setup_required_error(exc)except TelemetryConfigValidationError as exc:handle_telemetry_config_validation_error(exc)except GatewayTermsNotAcceptedError as exc:diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.pyindex 5b9af8644..4f4513fb8 100644--- a/pipelex/cli/error_handlers.py+++ b/pipelex/cli/error_handlers.py@@ -14,6 +14,7 @@ from pipelex.system.pipelex_service.exceptions import (GatewayApiKeyMissingError,GatewayDoNotTrackConflictError,GatewayTermsNotAcceptedError,+ InferenceSetupRequiredError,RemoteConfigFetchError,RemoteConfigValidationError,)@@ -221,6 +222,31 @@ def handle_validate_bundle_error(exc: ValidateBundleError, bundle_path: Path | Nraise typer.Exit(1) from exc+def handle_inference_setup_required_error(exc: InferenceSetupRequiredError) -> NoReturn:+ """Handle and display InferenceSetupRequiredError with first-run guidance.++ This error occurs on first run when no inference backend has been configured yet.++ Args:+ exc: The inference setup required error exception+ """+ console = get_console()+ console.print("\n[bold yellow]⚠ First-time inference setup required[/bold yellow]\n")++ console.print(+ "This looks like your first time running a method with live inference.\nYou need to configure an inference backend before running.\n"+ )++ console.print("[bold green]💡 To get started:[/bold green]")+ console.print(" • Run [cyan]pipelex init config[/cyan] for interactive setup")+ console.print(" • Or run [cyan]pipelex-agent init[/cyan] with backend configuration")+ console.print()++ console.print(f"[dim]For more information: {URLs.documentation}[/dim]")+ console.print(f"[dim]Join our Discord for help: {URLs.discord}[/dim]\n")+ raise typer.Exit(1) from exc++def handle_telemetry_config_validation_error(exc: TelemetryConfigValidationError) -> NoReturn:"""Handle and display TelemetryConfigValidationError with migration guidance.diff --git a/pipelex/kit/configs/pipelex_service.toml b/pipelex/kit/configs/pipelex_service.tomlindex de17e2380..a12571dd1 100644--- a/pipelex/kit/configs/pipelex_service.toml+++ b/pipelex/kit/configs/pipelex_service.toml@@ -17,3 +17,7 @@ terms_accepted = false# Note: when using pipelex_gateway, telemetry is enabled to monitor service usage.# We collect technical data (model, pipe type...) and quantitative data (token counts...)# but NOT your content, pipe codes, or output class names.++[onboarding]+# Set to true after completing inference setup (gateway or BYOK).+inference_setup_completed = falsediff --git a/pipelex/pipelex.py b/pipelex/pipelex.pyindex df78946d1..cb105805f 100644--- a/pipelex/pipelex.py+++ b/pipelex/pipelex.py@@ -55,6 +55,7 @@ from pipelex.system.configuration.configs import PipelexConfigfrom pipelex.system.environment import get_pipelexpath_dirsfrom pipelex.system.pipelex_service.exceptions import (GatewayTermsNotAcceptedError,+ InferenceSetupRequiredError,)from pipelex.system.pipelex_service.pipelex_service_config import (is_pipelex_gateway_enabled,@@ -206,9 +207,18 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# read-only operations like fetching model specs for validation.# Also skip for CI mode — automated pipelines don't require human consent.if needs_inference and integration_mode.requires_terms_acceptance:- # Check if terms are acceptedpipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)- if pipelex_service_config is None or not pipelex_service_config.agreement.terms_accepted:+ # First-run check: fires if inference has never been configured+ # AND terms were never accepted (terms_accepted=true means existing+ # user who already completed gateway setup before this flag existed).+ if pipelex_service_config is None or (+ not pipelex_service_config.onboarding.inference_setup_completed and not pipelex_service_config.agreement.terms_accepted+ ):+ raise InferenceSetupRequiredError+ # Gateway terms check: this block only runs when gateway is+ # enabled (is_pipelex_service_enabled guard above). BYOK users+ # who disabled gateway via init skip this entire block.+ if not pipelex_service_config.agreement.terms_accepted:raise GatewayTermsNotAcceptedError# Fetch remote configurationremote_config = RemoteConfigFetcher.fetch_remote_config()diff --git a/pipelex/system/pipelex_service/exceptions.py b/pipelex/system/pipelex_service/exceptions.pyindex adcd9ef6b..e571a1f3b 100644--- a/pipelex/system/pipelex_service/exceptions.py+++ b/pipelex/system/pipelex_service/exceptions.py@@ -31,6 +31,25 @@ class RemoteConfigValidationError(PipelexServiceError):"""+class InferenceSetupRequiredError(PipelexServiceError):+ """Raised when inference is requested but no inference setup has been completed.++ This is the first-run signal: the user has not yet configured any+ inference backend (gateway or BYOK). The agent skill should catch this+ error type and guide the user through the onboarding flow.+ """++ def __init__(self) -> None:+ msg = (+ "Inference setup required.\n"+ "This looks like your first time running a method with live inference.\n"+ "You need to configure an inference backend before running.\n"+ "Use /mthds-runner-setup for guided setup,\n"+ "or run `pipelex-agent init` with appropriate backend configuration."+ )+ super().__init__(msg)++class GatewayTermsNotAcceptedError(PipelexServiceError):"""Raised when Pipelex Gateway is enabled but terms are not accepted.diff --git a/pipelex/system/pipelex_service/pipelex_service_agreement.py b/pipelex/system/pipelex_service/pipelex_service_agreement.pyindex b029e79be..1e273fd32 100644--- a/pipelex/system/pipelex_service/pipelex_service_agreement.py+++ b/pipelex/system/pipelex_service/pipelex_service_agreement.py@@ -1,6 +1,7 @@from pathlib import Pathfrom pydantic import Field+from tomlkit import table as tomlkit_tablefrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.system.configuration.config_loader import config_manager@@ -18,6 +19,13 @@ class PipelexServiceAgreement(ConfigModel):)+class PipelexServiceOnboarding(ConfigModel):+ inference_setup_completed: bool = Field(+ default=False,+ description="Whether the user has completed inference setup (gateway or BYOK)",+ )++def update_service_terms_acceptance(accepted: bool, config_dir: Path | None = None) -> None:"""Update the service terms acceptance in pipelex_service.toml.@@ -40,3 +48,30 @@ def update_service_terms_acceptance(accepted: bool, config_dir: Path | None = Noresolved_config_dir.mkdir(parents=True, exist_ok=True)save_toml_to_path(toml_doc, service_config_path)+++def update_inference_setup_completed(completed: bool, config_dir: Path | None = None) -> None:+ """Update the inference setup completed flag in pipelex_service.toml.++ Args:+ completed: Whether inference setup has been completed.+ config_dir: Explicit config directory path. If None, uses config_manager.global_config_dir.+ """+ resolved_config_dir = config_dir or config_manager.global_config_dir+ service_config_path = resolved_config_dir / PIPELEX_SERVICE_CONFIG_FILE_NAME++ if path_exists(service_config_path):+ toml_doc = load_toml_with_tomlkit(service_config_path)+ else:+ # Load from the kit template+ template_path = str(get_kit_configs_dir() / PIPELEX_SERVICE_CONFIG_FILE_NAME)+ toml_doc = load_toml_with_tomlkit(template_path)++ # Ensure [onboarding] section exists+ if "onboarding" not in toml_doc:+ toml_doc["onboarding"] = tomlkit_table()++ toml_doc["onboarding"]["inference_setup_completed"] = completed # type: ignore[index]++ resolved_config_dir.mkdir(parents=True, exist_ok=True)+ save_toml_to_path(toml_doc, service_config_path)diff --git a/pipelex/system/pipelex_service/pipelex_service_config.py b/pipelex/system/pipelex_service/pipelex_service_config.pyindex 43ad552e3..859b02a65 100644--- a/pipelex/system/pipelex_service/pipelex_service_config.py+++ b/pipelex/system/pipelex_service/pipelex_service_config.py@@ -1,7 +1,7 @@from pathlib import Pathfrom typing import Any, cast-from pydantic import ValidationError+from pydantic import Field, ValidationErrorfrom pipelex.cogt.model_backends.backend import PipelexBackendfrom pipelex.system.configuration.config_loader import config_manager@@ -10,6 +10,7 @@ from pipelex.system.pipelex_service.exceptions import PipelexServiceConfigValidafrom pipelex.system.pipelex_service.pipelex_service_agreement import (PIPELEX_SERVICE_CONFIG_FILE_NAME,PipelexServiceAgreement,+ PipelexServiceOnboarding,)from pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_from_path_if_existsfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error@@ -17,6 +18,7 @@ from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_errorclass PipelexServiceConfig(ConfigModel):agreement: PipelexServiceAgreement+ onboarding: PipelexServiceOnboarding = Field(default_factory=PipelexServiceOnboarding)def load_pipelex_service_config_if_exists(config_dir: Path) -> PipelexServiceConfig | None:diff --git a/tests/unit/pipelex/cli/test_cli_factory.py b/tests/unit/pipelex/cli/test_cli_factory.pynew file mode 100644index 000000000..323dceab0--- /dev/null+++ b/tests/unit/pipelex/cli/test_cli_factory.py@@ -0,0 +1,42 @@+"""Regression test: standard CLI factory must handle InferenceSetupRequiredError.++The agent CLI factory catches InferenceSetupRequiredError and prints a friendly+markdown message. The standard CLI factory must also catch it so that first-run+users of ``pipelex run`` get a user-friendly message instead of an unhandled traceback.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+import typer++from pipelex.cli.cli_factory import make_pipelex_for_cli+from pipelex.cli.error_handlers import ErrorContext+from pipelex.system.pipelex_service.exceptions import InferenceSetupRequiredError++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++CLI_FACTORY_MODULE = "pipelex.cli.cli_factory"+++class TestCliFactory:+ """Verify that make_pipelex_for_cli() handles setup errors gracefully."""++ def test_first_run_catches_inference_setup_required(+ self,+ mocker: MockerFixture,+ ) -> None:+ """On first run, InferenceSetupRequiredError must be caught and exit cleanly."""+ mocker.patch(+ f"{CLI_FACTORY_MODULE}.Pipelex.make",+ side_effect=InferenceSetupRequiredError(),+ )++ with pytest.raises(typer.Exit):+ make_pipelex_for_cli(+ context=ErrorContext.VALIDATION_BEFORE_PIPE_RUN,+ needs_inference=True,+ )diff --git a/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py b/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.pyindex ee0f452f6..ab14ade56 100644--- a/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py+++ b/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py@@ -1,8 +1,12 @@-"""Regression test: gateway terms check must be gated on needs_inference, not needs_model_specs.+"""Regression tests for gateway terms check and first-run inference setup check.Commands like ``pipelex-agent validate bundle`` use ``needs_inference=False, needs_model_specs=True``to load model specs for validation without actually calling inference APIs. These commands mustNOT require gateway terms acceptance.++The first-run check (InferenceSetupRequiredError) fires when no service config exists at all,+while the gateway terms check (GatewayTermsNotAcceptedError) fires when the config exists+and inference setup is completed but terms have not been accepted."""from __future__ import annotations@@ -12,7 +16,9 @@ from typing import TYPE_CHECKINGimport pytestfrom pipelex.pipelex import Pipelex-from pipelex.system.pipelex_service.exceptions import GatewayTermsNotAcceptedError+from pipelex.system.pipelex_service.exceptions import GatewayTermsNotAcceptedError, InferenceSetupRequiredError+from pipelex.system.pipelex_service.pipelex_service_agreement import PipelexServiceAgreement, PipelexServiceOnboarding+from pipelex.system.pipelex_service.pipelex_service_config import PipelexServiceConfigfrom pipelex.system.runtime import IntegrationModeif TYPE_CHECKING:@@ -22,19 +28,39 @@ PIPELEX_MODULE = "pipelex.pipelex"class TestGatewayTermsCheck:- """Verify that the terms check in Pipelex.setup() respects needs_inference."""+ """Verify that the terms check and first-run check in Pipelex.setup() behave correctly."""@pytest.fixture- def _gateway_enabled_terms_not_accepted(self, mocker: MockerFixture) -> None:- """Configure mocks: gateway is enabled but terms have NOT been accepted."""+ def _gateway_enabled_no_config(self, mocker: MockerFixture) -> None:+ """Configure mocks: gateway is enabled but no service config exists (first run)."""mocker.patch(f"{PIPELEX_MODULE}.is_pipelex_gateway_enabled", return_value=True)mocker.patch(f"{PIPELEX_MODULE}.load_pipelex_service_config_if_exists", return_value=None)- @pytest.mark.usefixtures("_gateway_enabled_terms_not_accepted")- def test_needs_inference_true_raises_when_terms_not_accepted(- self,- ) -> None:- """With needs_inference=True and terms not accepted, setup must raise GatewayTermsNotAcceptedError."""+ @pytest.fixture+ def _gateway_enabled_setup_done_terms_not_accepted(self, mocker: MockerFixture) -> None:+ """Configure mocks: gateway enabled, inference setup completed, but terms NOT accepted."""+ config = PipelexServiceConfig(+ agreement=PipelexServiceAgreement(terms_accepted=False),+ onboarding=PipelexServiceOnboarding(inference_setup_completed=True),+ )+ mocker.patch(f"{PIPELEX_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{PIPELEX_MODULE}.load_pipelex_service_config_if_exists", return_value=config)++ @pytest.mark.usefixtures("_gateway_enabled_no_config")+ def test_first_run_raises_inference_setup_required(self) -> None:+ """With no service config at all, setup must raise InferenceSetupRequiredError."""+ pipelex_instance = Pipelex.__new__(Pipelex)++ with pytest.raises(InferenceSetupRequiredError):+ pipelex_instance.setup(+ integration_mode=IntegrationMode.CLI,+ needs_inference=True,+ needs_model_specs=True,+ )++ @pytest.mark.usefixtures("_gateway_enabled_setup_done_terms_not_accepted")+ def test_needs_inference_true_raises_when_terms_not_accepted(self) -> None:+ """With inference setup done but terms not accepted, setup must raise GatewayTermsNotAcceptedError."""pipelex_instance = Pipelex.__new__(Pipelex)with pytest.raises(GatewayTermsNotAcceptedError):@@ -44,12 +70,12 @@ class TestGatewayTermsCheck:needs_model_specs=True,)- @pytest.mark.usefixtures("_gateway_enabled_terms_not_accepted")+ @pytest.mark.usefixtures("_gateway_enabled_no_config")def test_needs_inference_false_does_not_raise_when_terms_not_accepted(self,mocker: MockerFixture,) -> None:- """With needs_inference=False and needs_model_specs=True, setup must NOT raise GatewayTermsNotAcceptedError.+ """With needs_inference=False and needs_model_specs=True, setup must NOT raise terms/setup errors.It may fail later (e.g., during remote config fetch), but the terms check itself must be skipped."""@@ -61,16 +87,16 @@ class TestGatewayTermsCheck:pipelex_instance = Pipelex.__new__(Pipelex)# setup() will fail somewhere after the gateway check (telemetry, models, etc.)- # but it must NOT fail with GatewayTermsNotAcceptedError+ # but it must NOT fail with GatewayTermsNotAcceptedError or InferenceSetupRequiredErrortry:pipelex_instance.setup(integration_mode=IntegrationMode.CLI,needs_inference=False,needs_model_specs=True,)- except GatewayTermsNotAcceptedError:- pytest.fail("setup() raised GatewayTermsNotAcceptedError even though needs_inference=False")+ except (GatewayTermsNotAcceptedError, InferenceSetupRequiredError):+ pytest.fail("setup() raised a terms/setup error even though needs_inference=False")except Exception: # noqa: S110# Expected: setup() will fail later in the init chain (telemetry, models, etc.)- # We only care that it did NOT fail with GatewayTermsNotAcceptedError+ # We only care that it did NOT fail with terms/setup errorspass