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.

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.py
index 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.py
index 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 RunnerType
from typer.core import TyperGroup
from typing_extensions import override
+from pipelex.cli.agent_cli.commands.accept_gateway_terms_cmd import agent_accept_gateway_terms_cmd
from pipelex.cli.agent_cli.commands.check_model_cmd import agent_check_model_cmd
from pipelex.cli.agent_cli.commands.concept_cmd import concept_cmd
from 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 output
app.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.py
new file mode 100644
index 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.py
index 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_error
from pipelex.cogt.exceptions import ModelDeckPresetValidatonError
from 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 None
except 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.py
index 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 PipelexBackend
from pipelex.cogt.model_routing.routing_profile import PipelexRoutingProfile
from pipelex.kit.paths import get_kit_configs_dir
from 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_NAME
from pipelex.tools.misc.file_utils import path_exists
from 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_gateway
is 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 backends
template_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 routing
routing_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 result
agent_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.py
index 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.py
index 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 | N
raise 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.toml
index 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 = false
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index df78946d1..cb105805f 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -55,6 +55,7 @@ from pipelex.system.configuration.configs import PipelexConfig
from pipelex.system.environment import get_pipelexpath_dirs
from 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 accepted
pipelex_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 configuration
remote_config = RemoteConfigFetcher.fetch_remote_config()
diff --git a/pipelex/system/pipelex_service/exceptions.py b/pipelex/system/pipelex_service/exceptions.py
index 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.py
index 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 Path
from pydantic import Field
+from tomlkit import table as tomlkit_table
from pipelex.kit.paths import get_kit_configs_dir
from 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 = No
resolved_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.py
index 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 Path
from typing import Any, cast
-from pydantic import ValidationError
+from pydantic import Field, ValidationError
from pipelex.cogt.model_backends.backend import PipelexBackend
from pipelex.system.configuration.config_loader import config_manager
@@ -10,6 +10,7 @@ from pipelex.system.pipelex_service.exceptions import PipelexServiceConfigValida
from 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_exists
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
@@ -17,6 +18,7 @@ from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
class 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.py
new file mode 100644
index 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.py
index 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 must
NOT 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_CHECKING
import pytest
from 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 PipelexServiceConfig
from pipelex.system.runtime import IntegrationMode
if 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 InferenceSetupRequiredError
try:
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 errors
pass