MAINT: Frontend core refactor (#1753)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: rlundeen2

doc/code/scenarios/0_scenarios.ipynb

@@ -392,9 +392,11 @@
     }
    ],
    "source": [
-    "from pyrit.cli.frontend_core import FrontendCore, print_scenarios_list_async\n",
+    "from pyrit.backend.services.scenario_service import get_scenario_service\n",
+    "from pyrit.cli._output import print_scenario_list\n",
     "\n",
-    "await print_scenarios_list_async(context=FrontendCore())  # type: ignore"
+    "response = await get_scenario_service().list_scenarios_async(limit=200)  # type: ignore\n",
+    "print_scenario_list(items=[s.model_dump() for s in response.items])"
    ]
   },
   {

doc/code/scenarios/0_scenarios.py

@@ -165,9 +165,11 @@ def _build_display_group(self, *, technique_name: str, seed_group_name: str) ->
 # ## Existing Scenarios
 
 # %%
-from pyrit.cli.frontend_core import FrontendCore, print_scenarios_list_async
+from pyrit.backend.services.scenario_service import get_scenario_service
+from pyrit.cli._output import print_scenario_list
 
-await print_scenarios_list_async(context=FrontendCore())  # type: ignore
+response = await get_scenario_service().list_scenarios_async(limit=200)  # type: ignore
+print_scenario_list(items=[s.model_dump() for s in response.items])
 
 # %% [markdown]
 #

doc/code/scenarios/2_custom_scenario_parameters.ipynb

@@ -290,15 +290,14 @@
     }
    ],
    "source": [
-    "from pyrit.cli.frontend_core import format_scenario_metadata\n",
-    "from pyrit.registry import ScenarioRegistry\n",
+    "from pyrit.backend.services.scenario_service import get_scenario_service\n",
+    "from pyrit.cli._output import print_scenario_list\n",
     "\n",
     "# Show scam (declares a parameter) and red_team_agent (none), so the\n",
     "# Supported Parameters section is visible in one and absent in the other.\n",
     "demo_names = {\"airt.scam\", \"foundry.red_team_agent\"}\n",
-    "for metadata in ScenarioRegistry.get_registry_singleton().list_metadata():\n",
-    "    if metadata.registry_name in demo_names:\n",
-    "        format_scenario_metadata(scenario_metadata=metadata)"
+    "response = await get_scenario_service().list_scenarios_async(limit=200)  # type: ignore\n",
+    "print_scenario_list(items=[s.model_dump() for s in response.items if s.scenario_name in demo_names])"
    ]
   },
   {

doc/code/scenarios/2_custom_scenario_parameters.py

@@ -182,15 +182,14 @@
 # CLI uses is callable programmatically:
 
 # %%
-from pyrit.cli.frontend_core import format_scenario_metadata
-from pyrit.registry import ScenarioRegistry
+from pyrit.backend.services.scenario_service import get_scenario_service
+from pyrit.cli._output import print_scenario_list
 
 # Show scam (declares a parameter) and red_team_agent (none), so the
 # Supported Parameters section is visible in one and absent in the other.
 demo_names = {"airt.scam", "foundry.red_team_agent"}
-for metadata in ScenarioRegistry.get_registry_singleton().list_metadata():
-    if metadata.registry_name in demo_names:
-        format_scenario_metadata(scenario_metadata=metadata)
+response = await get_scenario_service().list_scenarios_async(limit=200)  # type: ignore
+print_scenario_list(items=[s.model_dump() for s in response.items if s.scenario_name in demo_names])
 
 # %% [markdown]
 # Notice the `Supported Parameters:` section under `airt.scam`. It's absent

doc/myst.yml

@@ -203,11 +203,11 @@ project:
       children:
         - file: api/pyrit_analytics.md
         - file: api/pyrit_auth.md
-        - file: api/pyrit_cli_frontend_core.md
-        - file: api/pyrit_cli_pyrit_backend.md
+        - file: api/pyrit_cli_api_client.md
         - file: api/pyrit_cli_pyrit_scan.md
         - file: api/pyrit_cli_pyrit_shell.md
         - file: api/pyrit_common.md
+        - file: api/pyrit_common_cli_helpers.md
         - file: api/pyrit_datasets.md
         - file: api/pyrit_embedding.md
         - file: api/pyrit_exceptions.md

docker/start.sh

@@ -57,25 +57,33 @@ if [ "$PYRIT_MODE" = "jupyter" ]; then
     exec jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --notebook-dir=/app/notebooks
 elif [ "$PYRIT_MODE" = "gui" ]; then
     echo "Starting PyRIT GUI on port 8000..."
-    # Use Azure SQL if AZURE_SQL_SERVER is set (injected by Bicep), otherwise default to SQLite.
-    # Note: AZURE_SQL_DB_CONNECTION_STRING is in the .env file (loaded by Python dotenv),
-    # but we use AZURE_SQL_SERVER here because it's a direct env var from the Bicep template.
-    # Build CLI arguments
-    BACKEND_ARGS="--host 0.0.0.0 --port 8000"
+    # The thin backend only takes --host/--port/--config-file/--log-level.
+    # Translate AZURE_SQL_SERVER and PYRIT_INITIALIZER into a runtime config file
+    # so the FastAPI lifespan (ConfigurationLoader) picks them up on startup.
+    RUNTIME_CONFIG=/tmp/pyrit_runtime.yaml
+    {
+        if [ -n "$AZURE_SQL_SERVER" ]; then
+            echo "Using Azure SQL database (server: $AZURE_SQL_SERVER)" >&2
+            echo "memory_db_type: AzureSQL"
+        else
+            echo "Using SQLite database (AZURE_SQL_SERVER not set)" >&2
+            echo "memory_db_type: SQLite"
+        fi
+        if [ -n "$PYRIT_INITIALIZER" ]; then
+            echo "Using initializer: $PYRIT_INITIALIZER" >&2
+            echo "initializers:"
+            # Split comma-separated initializer names into a YAML list.
+            IFS=',' read -ra INIT_NAMES <<<"$PYRIT_INITIALIZER"
+            for name in "${INIT_NAMES[@]}"; do
+                echo "  - $(echo "$name" | xargs)"
+            done
+        fi
+    } >"$RUNTIME_CONFIG"
 
-    if [ -n "$AZURE_SQL_SERVER" ]; then
-        echo "Using Azure SQL database (server: $AZURE_SQL_SERVER)"
-        BACKEND_ARGS="$BACKEND_ARGS --database AzureSQL"
-    else
-        echo "Using SQLite database (AZURE_SQL_SERVER not set)"
-    fi
-
-    if [ -n "$PYRIT_INITIALIZER" ]; then
-        echo "Using initializer: $PYRIT_INITIALIZER"
-        BACKEND_ARGS="$BACKEND_ARGS --initializers $PYRIT_INITIALIZER"
-    fi
-
-    exec python -m pyrit.cli.pyrit_backend $BACKEND_ARGS
+    exec python -m pyrit.backend.pyrit_backend \
+        --host 0.0.0.0 \
+        --port 8000 \
+        --config-file "$RUNTIME_CONFIG"
 else
     echo "ERROR: Invalid PYRIT_MODE '$PYRIT_MODE'. Must be 'jupyter' or 'gui'"
     exit 1

frontend/dev.py

@@ -141,7 +141,7 @@ def _find_pids_on_port(port):
 def stop_servers():
     """Stop all running servers"""
     print("🛑 Stopping servers...")
-    backend_pids = find_pids_by_pattern("pyrit.cli.pyrit_backend")
+    backend_pids = find_pids_by_pattern("pyrit.backend.pyrit_backend")
     frontend_pids = find_pids_by_pattern("node.*vite")
     # Also find any parent dev.py processes (detached wrappers)
     wrapper_pids = find_pids_by_pattern("frontend/dev.py")
@@ -163,6 +163,10 @@ def start_backend(*, config_file: str | None = None, initializers: list[str] | N
     Configuration (initializers, database, env files) is read automatically
     from ~/.pyrit/.pyrit_conf by the pyrit_backend CLI via ConfigurationLoader,
     unless overridden with *config_file*.
+
+    When *initializers* is supplied without a *config_file*, a tiny temporary
+    runtime config is written to forward those names — ``pyrit_backend`` only
+    accepts ``--config-file`` now (no ``--initializers`` flag).
     """
     print("🚀 Starting backend on port 8000...")
 
@@ -178,20 +182,30 @@ def start_backend(*, config_file: str | None = None, initializers: list[str] | N
     cmd = [
         sys.executable,
         "-m",
-        "pyrit.cli.pyrit_backend",
+        "pyrit.backend.pyrit_backend",
         "--host",
         "localhost",
         "--port",
         "8000",
         "--log-level",
         "info",
     ]
-    if config_file:
-        cmd.extend(["--config-file", config_file])
 
-    # Add initializers if specified
-    if initializers:
-        cmd.extend(["--initializers"] + initializers)
+    # Resolve config-file: explicit wins; otherwise synthesize one from initializers.
+    effective_config_file = config_file
+    if effective_config_file is None and initializers:
+        import tempfile
+
+        fd, synthesized_path = tempfile.mkstemp(suffix=".yaml", prefix="pyrit_dev_", text=True)
+        with os.fdopen(fd, "w") as synthesized:
+            synthesized.write("initializers:\n")
+            for name in initializers:
+                synthesized.write(f"  - {name}\n")
+        effective_config_file = synthesized_path
+        print(f"   Wrote initializer overrides to {effective_config_file}")
+
+    if effective_config_file:
+        cmd.extend(["--config-file", effective_config_file])
 
     # Pipe stdout/stderr so dev.py controls output ordering
     return subprocess.Popen(cmd, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
@@ -456,7 +470,7 @@ def main():
         elif command == "backend":
             print("🚀 Starting backend only...")
             # Kill stale backend processes
-            stale = find_pids_by_pattern("pyrit.cli.pyrit_backend")
+            stale = find_pids_by_pattern("pyrit.backend.pyrit_backend")
             if stale:
                 print(f"   Killing stale backend PIDs: {stale}")
                 kill_pids(stale)

pyproject.toml

@@ -157,7 +157,7 @@ all = [
 ]
 
 [project.scripts]
-pyrit_backend = "pyrit.cli.pyrit_backend:main"
+pyrit_backend = "pyrit.backend.pyrit_backend:main"
 pyrit_scan = "pyrit.cli.pyrit_scan:main"
 pyrit_shell = "pyrit.cli.pyrit_shell:main"
 

pyrit/backend/main.py

@@ -30,7 +30,7 @@
     targets,
     version,
 )
-from pyrit.memory import CentralMemory
+from pyrit.setup.configuration_loader import ConfigurationLoader
 
 # Check for development mode from environment variable
 DEV_MODE = os.getenv("PYRIT_DEV_MODE", "false").lower() == "true"
@@ -40,17 +40,38 @@
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
-    """Manage application startup and shutdown lifecycle."""
-    # Initialization is handled by the pyrit_backend CLI before uvicorn starts.
-    # Running 'uvicorn pyrit.backend.main:app' directly is not supported;
-    # use 'pyrit_backend' instead.
-    try:
-        CentralMemory.get_memory_instance()
-    except ValueError:
-        logger.warning(
-            "CentralMemory is not initialized. "
-            "Start the server via 'pyrit_backend' CLI instead of running uvicorn directly."
-        )
+    """
+    Initialize PyRIT on startup using the config file, then yield.
+
+    Config resolution order:
+    1. ``PYRIT_CONFIG_FILE`` env var (if set)
+    2. ``~/.pyrit/.pyrit_conf`` (if it exists)
+    3. Built-in defaults (SQLite, no initializers)
+    """
+    config_file_env = os.getenv("PYRIT_CONFIG_FILE")
+    config_file = Path(config_file_env) if config_file_env else None
+
+    config = ConfigurationLoader.load_with_overrides(config_file=config_file)
+    await config.initialize_pyrit_async()
+
+    # Expose config values to route handlers via app.state
+    default_labels: dict[str, str] = {}
+    if config.operator:
+        default_labels["operator"] = config.operator
+    if config.operation:
+        default_labels["operation"] = config.operation
+    app.state.default_labels = default_labels
+    app.state.max_concurrent_scenario_runs = config.max_concurrent_scenario_runs
+    app.state.allow_custom_initializers = config.allow_custom_initializers
+
+    if config.allow_custom_initializers:
+        logger.warning("Custom initializer registration is ENABLED (allow_custom_initializers: true).")
+
+    # Mount the bundled frontend (or print a dev/missing-frontend notice).
+    # Done here rather than at module load so test imports of `pyrit.backend.main`
+    # don't emit noise and don't perform filesystem side effects.
+    setup_frontend()
+
     yield
 
 
@@ -124,7 +145,3 @@ def setup_frontend() -> None:
         print("   The frontend must be built and included in the package.")
         print("   Run: python build_scripts/prepare_package.py")
         print("   API endpoints will still work but the UI won't be available.")
-
-
-# Set up frontend at module load time (needed when running via uvicorn)
-setup_frontend()

pyrit/backend/models/scenarios.py

@@ -14,7 +14,6 @@
 
 from pydantic import BaseModel, Field
 
-from pyrit.backend.models.attacks import AttackSummary
 from pyrit.backend.models.common import PaginationInfo
 
 
@@ -25,7 +24,8 @@ class ScenarioParameterSummary(BaseModel):
     description: str = Field(..., description="Human-readable description of the parameter")
     default: str | None = Field(None, description="Default value as a display string, or None if required")
     param_type: str = Field(..., description="Type of the parameter as a display string (e.g., 'int', 'str')")
-    choices: str | None = Field(None, description="Allowed values as a display string, or None if unconstrained")
+    choices: list[str] | None = Field(None, description="Allowed values as strings, or None if unconstrained")
+    is_list: bool = Field(False, description="True when the parameter accepts a list of values (e.g., list[str])")
 
 
 class RegisteredScenario(BaseModel):
@@ -124,28 +124,3 @@ class ScenarioRunListResponse(BaseModel):
     """Response for listing scenario runs."""
 
     items: list[ScenarioRunSummary] = Field(..., description="List of scenario runs")
-
-
-# ============================================================================
-# Scenario Results Detail Models
-# ============================================================================
-
-
-class AtomicAttackResults(BaseModel):
-    """Results grouped by atomic attack name."""
-
-    atomic_attack_name: str = Field(..., description="Name of the atomic attack (strategy)")
-    display_group: str | None = Field(None, description="Display group label for UI grouping")
-    results: list[AttackSummary] = Field(..., description="Individual attack results")
-    success_count: int = Field(0, ge=0, description="Number of successful attacks")
-    failure_count: int = Field(0, ge=0, description="Number of failed attacks")
-    total_count: int = Field(0, ge=0, description="Total number of attack results")
-    total_retries: int = Field(0, ge=0, description="Sum of retries across all attacks in this group")
-    error_count: int = Field(0, ge=0, description="Number of attacks with errors")
-
-
-class ScenarioRunDetail(BaseModel):
-    """Full detailed results of a scenario run."""
-
-    run: ScenarioRunSummary = Field(..., description="The scenario run summary")
-    attacks: list[AtomicAttackResults] = Field(..., description="Results grouped by atomic attack")