evalvault 1.58.0__py3-none-any.whl → 1.60.0__py3-none-any.whl

evalvault/adapters/inbound/api/adapter.py

@@ -15,6 +15,13 @@ from urllib.request import urlopen
 from evalvault.config.phoenix_support import PhoenixExperimentResolver
 from evalvault.config.settings import Settings
 from evalvault.domain.entities.prompt import PromptSetBundle
+from evalvault.domain.metrics.registry import (
+    get_metric_descriptions as registry_metric_descriptions,
+)
+from evalvault.domain.metrics.registry import (
+    list_metric_names,
+    list_metric_specs,
+)
 from evalvault.domain.services.cluster_map_builder import build_cluster_map
 from evalvault.domain.services.prompt_registry import (
     PromptInput,
@@ -42,21 +49,6 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# 지원하는 메트릭 목록
-AVAILABLE_METRICS = [
-    "faithfulness",
-    "answer_relevancy",
-    "context_precision",
-    "context_recall",
-    "factual_correctness",
-    "semantic_similarity",
-    "summary_score",
-    "summary_faithfulness",
-    "insurance_term_accuracy",
-    "entity_preservation",
-    "contextual_relevancy",
-]
-
 
 @dataclass
 class GateResult:
@@ -978,19 +970,15 @@ class WebUIAdapter:
 
     def get_available_metrics(self) -> list[str]:
         """사용 가능한 메트릭 목록 반환."""
-        return AVAILABLE_METRICS.copy()
+        return list_metric_names()
+
+    def get_metric_specs(self) -> list[dict[str, object]]:
+        """메트릭 스펙 목록 반환."""
+        return [spec.to_dict() for spec in list_metric_specs()]
 
     def get_metric_descriptions(self) -> dict[str, str]:
         """메트릭별 설명 반환."""
-        return {
-            "faithfulness": "답변이 컨텍스트에 충실한지 평가",
-            "answer_relevancy": "답변이 질문과 관련있는지 평가",
-            "context_precision": "검색된 컨텍스트의 정밀도 평가",
-            "context_recall": "필요한 정보가 검색되었는지 평가",
-            "factual_correctness": "ground_truth 대비 사실적 정확성 평가",
-            "semantic_similarity": "답변과 ground_truth 간 의미적 유사도 평가",
-            "insurance_term_accuracy": "보험 용어 정확성 평가",
-        }
+        return registry_metric_descriptions()
 
     def create_dataset_from_upload(
         self,

evalvault/adapters/inbound/api/routers/pipeline.py

@@ -11,6 +11,7 @@ from evalvault.adapters.outbound.llm import get_llm_adapter
 from evalvault.adapters.outbound.storage.sqlite_adapter import SQLiteStorageAdapter
 from evalvault.config.settings import get_settings
 from evalvault.domain.entities.analysis_pipeline import AnalysisIntent
+from evalvault.domain.metrics.analysis_registry import list_analysis_metric_specs
 from evalvault.domain.services.pipeline_orchestrator import AnalysisPipelineService
 
 router = APIRouter(tags=["pipeline"])
@@ -71,6 +72,54 @@ INTENT_CATALOG = {
         "description": "시간에 따른 추세를 분석합니다.",
         "sample_query": "메트릭 추세를 분석해줘",
     },
+    AnalysisIntent.ANALYZE_STATISTICAL: {
+        "label": "기술 통계량",
+        "category": "analysis",
+        "description": "메트릭별 기초 통계량을 계산합니다.",
+        "sample_query": "기초 통계 분석해줘",
+    },
+    AnalysisIntent.ANALYZE_NLP: {
+        "label": "NLP 분석",
+        "category": "analysis",
+        "description": "질문/답변 텍스트를 분석합니다.",
+        "sample_query": "텍스트 분석해줘",
+    },
+    AnalysisIntent.ANALYZE_CAUSAL: {
+        "label": "인과 관계 분석",
+        "category": "analysis",
+        "description": "요인별 영향도와 인과 관계를 분석합니다.",
+        "sample_query": "인과 관계 분석해줘",
+    },
+    AnalysisIntent.ANALYZE_NETWORK: {
+        "label": "네트워크 분석",
+        "category": "analysis",
+        "description": "메트릭 간 상관관계 네트워크를 분석합니다.",
+        "sample_query": "메트릭 네트워크 분석해줘",
+    },
+    AnalysisIntent.ANALYZE_PLAYBOOK: {
+        "label": "플레이북 분석",
+        "category": "analysis",
+        "description": "개선 플레이북 기반 진단을 수행합니다.",
+        "sample_query": "플레이북으로 분석해줘",
+    },
+    AnalysisIntent.DETECT_ANOMALIES: {
+        "label": "이상 탐지",
+        "category": "timeseries",
+        "description": "시계열 이상 패턴을 탐지합니다.",
+        "sample_query": "이상 탐지해줘",
+    },
+    AnalysisIntent.FORECAST_PERFORMANCE: {
+        "label": "성능 예측",
+        "category": "timeseries",
+        "description": "미래 성능을 예측합니다.",
+        "sample_query": "성능 예측해줘",
+    },
+    AnalysisIntent.GENERATE_HYPOTHESES: {
+        "label": "가설 생성",
+        "category": "generation",
+        "description": "성능 저하 원인에 대한 가설을 생성합니다.",
+        "sample_query": "가설 생성해줘",
+    },
     AnalysisIntent.BENCHMARK_RETRIEVAL: {
         "label": "검색 벤치마크",
         "category": "benchmark",
@@ -172,6 +221,15 @@ class PipelineResultResponse(PipelineResultSummary):
     final_output: dict[str, Any] | None = None
 
 
+class AnalysisMetricSpecResponse(BaseModel):
+    key: str
+    label: str
+    description: str
+    signal_group: str
+    module_id: str
+    output_path: list[str]
+
+
 def _serialize_payload(value: Any) -> Any:
     try:
         return jsonable_encoder(value)
@@ -318,6 +376,12 @@ async def list_intents():
         raise HTTPException(status_code=500, detail=str(exc)) from exc
 
 
+@router.get("/options/analysis-metric-specs", response_model=list[AnalysisMetricSpecResponse])
+async def list_analysis_metric_specs_endpoint():
+    """List analysis metric specs for pipeline outputs."""
+    return [spec.to_dict() for spec in list_analysis_metric_specs()]
+
+
 @router.post("/results", response_model=PipelineResultSummary)
 async def save_pipeline_result(payload: PipelineResultPayload):
     """Save a pipeline analysis result for history."""

evalvault/adapters/inbound/api/routers/runs.py

@@ -113,6 +113,16 @@ class ModelItemResponse(BaseModel):
     supports_tools: bool | None = None
 
 
+class MetricSpecResponse(BaseModel):
+    name: str
+    description: str
+    requires_ground_truth: bool
+    requires_embeddings: bool
+    source: str
+    category: str
+    signal_group: str
+
+
 class ClusterMapItemResponse(BaseModel):
     test_case_id: str
     cluster_id: str
@@ -395,6 +405,12 @@ def list_metrics(adapter: AdapterDep):
     return adapter.get_available_metrics()
 
 
+@router.get("/options/metric-specs", response_model=list[MetricSpecResponse])
+def list_metric_specs(adapter: AdapterDep):
+    """Get available metrics with metadata."""
+    return adapter.get_metric_specs()
+
+
 @router.get("/options/cluster-maps", response_model=list[ClusterMapFileResponse])
 def list_cluster_maps():
     """List available cluster map CSV files."""

evalvault/adapters/inbound/cli/app.py

@@ -14,6 +14,8 @@ import typer
 from rich import print as rprint
 from rich.console import Console
 
+from evalvault.domain.metrics.registry import list_metric_names
+
 from .commands import attach_sub_apps, register_all_commands
 
 
@@ -32,19 +34,7 @@ app = typer.Typer(
 )
 console = Console()
 
-AVAILABLE_METRICS: list[str] = [
-    "faithfulness",
-    "answer_relevancy",
-    "context_precision",
-    "context_recall",
-    "factual_correctness",
-    "semantic_similarity",
-    "summary_score",
-    "summary_faithfulness",
-    "insurance_term_accuracy",
-    "entity_preservation",
-    "contextual_relevancy",
-]
+AVAILABLE_METRICS = list_metric_names()
 
 register_all_commands(app, console, available_metrics=AVAILABLE_METRICS)
 attach_sub_apps(app, console)

evalvault/adapters/inbound/cli/commands/analyze.py

@@ -12,15 +12,18 @@ from rich.table import Table
 
 from evalvault.adapters.outbound.analysis import (
     CausalAnalysisAdapter,
+    HypothesisGeneratorModule,
+    NetworkAnalyzerModule,
     NLPAnalysisAdapter,
     StatisticalAnalysisAdapter,
+    TimeSeriesAdvancedModule,
 )
 from evalvault.adapters.outbound.analysis.pipeline_factory import (
     build_analysis_pipeline_service,
 )
 from evalvault.adapters.outbound.cache import MemoryCacheAdapter
 from evalvault.adapters.outbound.llm import get_llm_adapter
-from evalvault.adapters.outbound.report import MarkdownReportAdapter
+from evalvault.adapters.outbound.report import DashboardGenerator, MarkdownReportAdapter
 from evalvault.adapters.outbound.storage.sqlite_adapter import SQLiteStorageAdapter
 from evalvault.config.phoenix_support import get_phoenix_trace_url
 from evalvault.config.settings import Settings, apply_profile
@@ -64,6 +67,37 @@ def register_analyze_commands(app: typer.Typer, console: Console) -> None:
             "-L",
             help="플레이북 분석에서 LLM 인사이트 생성",
         ),
+        dashboard: bool = typer.Option(False, "--dashboard", help="시각화 대시보드 생성"),
+        dashboard_format: str = typer.Option(
+            "png", "--dashboard-format", help="대시보드 출력 형식 (png, svg, pdf)"
+        ),
+        anomaly_detect: bool = typer.Option(
+            False, "--anomaly-detect", "-A", help="이상치 탐지 실행 (Phase 2)"
+        ),
+        window_size: int = typer.Option(
+            200, "--window-size", "-w", help="이상치 탐지 윈도 크기", min=50, max=500
+        ),
+        forecast: bool = typer.Option(False, "--forecast", "-F", help="성능 예측 실행 (Phase 2)"),
+        forecast_horizon: int = typer.Option(
+            3, "--forecast-horizon", help="예측 범위(런 개수)", min=1, max=10
+        ),
+        network: bool = typer.Option(
+            False, "--network", help="메트릭 상관관계 네트워크 생성 (Phase 3)"
+        ),
+        min_correlation: float = typer.Option(
+            0.5, "--min-correlation", help="네트워크 최소 상관계수", min=0, max=1
+        ),
+        generate_hypothesis: bool = typer.Option(
+            False, "--generate-hypothesis", "-H", help="가설 자동 생성 (Phase 4)"
+        ),
+        hypothesis_method: str = typer.Option(
+            "heuristic",
+            "--hypothesis-method",
+            help="가설 생성 방식 (heuristic, hyporefine, union)",
+        ),
+        num_hypotheses: int = typer.Option(
+            5, "--num-hypotheses", help="생성할 가설 수", min=1, max=20
+        ),
         output: Path | None = typer.Option(None, "--output", "-o", help="JSON 출력 파일"),
         report: Path | None = typer.Option(
             None, "--report", "-r", help="리포트 출력 파일 (*.md 또는 *.html)"
@@ -77,6 +111,9 @@ def register_analyze_commands(app: typer.Typer, console: Console) -> None:
         """평가 실행 결과를 분석하고 통계 인사이트를 표시합니다."""
 
         resolved_db_path = db_path or Settings().evalvault_db_path
+        if resolved_db_path is None:
+            _console.print("[red]오류: DB 경로가 설정되지 않았습니다.[/red]")
+            raise typer.Exit(1)
         storage = SQLiteStorageAdapter(db_path=resolved_db_path)
 
         try:
@@ -161,6 +198,97 @@ def register_analyze_commands(app: typer.Typer, console: Console) -> None:
             storage.save_analysis(analysis)
             _console.print(f"\n[green]분석 결과 DB 저장: {resolved_db_path}[/green]")
 
+        if dashboard:
+            dashboard_gen = DashboardGenerator()
+            _console.print("\n[bold cyan]Generating visualization dashboard...[/bold cyan]")
+
+            fig = dashboard_gen.generate_evaluation_dashboard(run_id)
+
+            output_dir = Path("reports/dashboard")
+            output_dir.mkdir(parents=True, exist_ok=True)
+
+            output_path = output_dir / f"dashboard_{run_id[:8]}.{dashboard_format}"
+            fig.savefig(output_path, dpi=300, bbox_inches="tight")
+            _console.print(f"\n[green]Dashboard saved to: {output_path}[/green]")
+
+        if anomaly_detect or forecast:
+            ts_analyzer = TimeSeriesAdvancedModule(window_size=window_size)
+            run_history = storage.list_runs(limit=50)
+
+            if not run_history or len(run_history) < 5:
+                _console.print("[yellow]Need at least 5 runs for time series analysis.[/yellow]")
+            else:
+                if anomaly_detect:
+                    _console.print("\n[bold cyan]Running anomaly detection...[/bold cyan]")
+                    history_data = [
+                        {
+                            "run_id": r.run_id,
+                            "pass_rate": r.pass_rate,
+                            "timestamp": r.started_at,
+                        }
+                        for r in run_history
+                    ]
+                    anomaly_result = ts_analyzer.detect_anomalies(history_data)
+                    _display_anomaly_detection(anomaly_result)
+
+                if forecast:
+                    _console.print("\n[bold cyan]Running performance forecasting...[/bold cyan]")
+                    history_data = [
+                        {"run_id": r.run_id, "pass_rate": r.pass_rate} for r in run_history
+                    ]
+                    forecast_result = ts_analyzer.forecast_performance(
+                        history_data, horizon=forecast_horizon
+                    )
+                    _display_forecast_result(forecast_result)
+
+        if network:
+            _console.print("\n[bold cyan]Building metric correlation network...[/bold cyan]")
+            net_analyzer = NetworkAnalyzerModule()
+
+            if not bundle.statistical or not bundle.statistical.significant_correlations:
+                _console.print("[yellow]No significant correlations for network analysis.[/yellow]")
+            else:
+                correlations_data = [
+                    {
+                        "variable1": corr.variable1,
+                        "variable2": corr.variable2,
+                        "correlation": corr.correlation,
+                        "p_value": corr.p_value,
+                        "is_significant": corr.is_significant,
+                    }
+                    for corr in bundle.statistical.significant_correlations
+                ]
+                graph = net_analyzer.build_correlation_network(
+                    correlations_data, min_correlation=min_correlation
+                )
+                net_result = net_analyzer.analyze_metric_network(graph)
+                _display_network_analysis(net_result)
+
+        if generate_hypothesis:
+            _console.print(
+                f"\n[bold cyan]Generating hypotheses ({hypothesis_method})...[/bold cyan]"
+            )
+            hyp_gen = HypothesisGeneratorModule(
+                method=hypothesis_method, num_hypotheses=num_hypotheses
+            )
+
+            metric_scores = {}
+            for metric_name, stats in analysis.metrics_summary.items():
+                metric_scores[metric_name] = stats.mean
+
+            low_performers_data = [
+                {
+                    "question": lp.test_case_id,
+                    "metric_name": lp.metric_name,
+                }
+                for lp in (analysis.low_performers or [])
+            ]
+
+            hypotheses = hyp_gen.generate_simple_hypotheses(
+                run_id, metric_scores, low_performers_data
+            )
+            _display_hypothesis_generation(hypotheses, hypothesis_method)
+
         if output:
             _export_analysis_json(analysis, output, bundle.nlp if nlp else None, improvement_report)
             _console.print(f"\n[green]분석 결과 내보냄: {output}[/green]")
@@ -192,6 +320,9 @@ def register_analyze_commands(app: typer.Typer, console: Console) -> None:
         """두 실행을 통계적으로 비교합니다."""
 
         resolved_db_path = db_path or Settings().evalvault_db_path
+        if resolved_db_path is None:
+            _console.print("[red]오류: DB 경로가 설정되지 않았습니다.[/red]")
+            raise typer.Exit(1)
         storage = SQLiteStorageAdapter(db_path=resolved_db_path)
 
         try:
@@ -220,7 +351,15 @@ def register_analyze_commands(app: typer.Typer, console: Console) -> None:
             _console.print(f"    Phoenix 트레이스: {trace_b}")
         _console.print(f"  검정: {test}\n")
 
-        comparisons = service.compare_runs(run_a, run_b, metrics=metric_list, test_type=test)
+        if test == "t-test":
+            test_type = "t-test"
+        elif test == "mann-whitney":
+            test_type = "mann-whitney"
+        else:
+            _console.print(f"[red]Error: Unsupported test type: {test}[/red]")
+            raise typer.Exit(1)
+
+        comparisons = service.compare_runs(run_a, run_b, metrics=metric_list, test_type=test_type)
 
         if not comparisons:
             _console.print("[yellow]비교할 공통 메트릭이 없습니다.[/yellow]")
@@ -942,6 +1081,123 @@ def _generate_report(
         file.write(content)
 
 
+def _display_anomaly_detection(anomaly_result) -> None:
+    _console.print("\n[bold]Anomaly Detection Results[/bold]")
+    _console.print(f"Detection method: {anomaly_result.detection_method}")
+    _console.print(f"Threshold: {anomaly_result.threshold:.2f}")
+    _console.print(f"Total runs: {anomaly_result.total_runs}")
+
+    if anomaly_result.anomalies:
+        detected = [a for a in anomaly_result.anomalies if a.is_anomaly]
+        if detected:
+            _console.print(f"\n[red]Detected {len(detected)} anomalies:[/red]")
+            table = Table(show_header=True, header_style="bold cyan")
+            table.add_column("Run ID")
+            table.add_column("Score", justify="right")
+            table.add_column("Pass Rate", justify="right")
+            table.add_column("Severity")
+
+            for anomaly in detected[:10]:
+                severity_color = (
+                    "red"
+                    if anomaly.severity == "high"
+                    else "yellow"
+                    if anomaly.severity == "medium"
+                    else "green"
+                )
+                table.add_row(
+                    anomaly.run_id[:12] + "...",
+                    f"{anomaly.anomaly_score:.2f}",
+                    f"{anomaly.pass_rate:.1%}",
+                    f"[{severity_color}]{anomaly.severity}[/{severity_color}]",
+                )
+            _console.print(table)
+        else:
+            _console.print("[green]No anomalies detected.[/green]")
+
+    if anomaly_result.insights:
+        _console.print("\n[bold]Insights:[/bold]")
+        for insight in anomaly_result.insights:
+            _console.print(f"  • {insight}")
+
+
+def _display_forecast_result(forecast_result) -> None:
+    _console.print("\n[bold]Forecast Results[/bold]")
+    _console.print(f"Method: {forecast_result.method}")
+    _console.print(f"Horizon: {forecast_result.horizon} runs")
+
+    if forecast_result.predicted_values:
+        _console.print("\n[bold]Predicted Pass Rates:[/bold]")
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Run")
+        table.add_column("Predicted", justify="right")
+
+        for i, value in enumerate(forecast_result.predicted_values, 1):
+            table.add_row(f"+{i}", f"{value:.1%}")
+        _console.print(table)
+
+        avg_forecast = sum(forecast_result.predicted_values) / len(forecast_result.predicted_values)
+        _console.print(f"\nAverage forecast: {avg_forecast:.1%}")
+
+
+def _display_network_analysis(net_result) -> None:
+    _console.print("\n[bold]Network Analysis Results[/bold]")
+    _console.print(f"Nodes (metrics): {net_result.node_count}")
+    _console.print(f"Edges (correlations): {net_result.edge_count}")
+    _console.print(f"Density: {net_result.density:.3f}")
+    _console.print(f"Avg clustering: {net_result.avg_clustering:.3f}")
+
+    if net_result.communities:
+        _console.print(f"\n[bold]Communities ({len(net_result.communities)}):[/bold]")
+        for i, community in enumerate(net_result.communities):
+            if len(community) > 1:
+                _console.print(f"  Community {i + 1}: {', '.join(community)}")
+
+    if net_result.hub_metrics:
+        _console.print("\n[bold]Hub Metrics:[/bold]")
+        for metric in net_result.hub_metrics:
+            _console.print(f"  • {metric}")
+
+    if net_result.insights:
+        _console.print("\n[bold]Insights:[/bold]")
+        for insight in net_result.insights:
+            _console.print(f"  • {insight}")
+
+
+def _display_hypothesis_generation(hypotheses, method: str) -> None:
+    _console.print("\n[bold]Hypothesis Generation Results[/bold]")
+    _console.print(f"Method: {method}")
+    _console.print(f"Total hypotheses: {len(hypotheses)}")
+
+    if hypotheses:
+        _console.print("\n[bold]Generated Hypotheses:[/bold]")
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("#")
+        table.add_column("Hypothesis")
+        table.add_column("Metric")
+        table.add_column("Confidence", justify="right")
+        table.add_column("Evidence")
+
+        for i, hyp in enumerate(hypotheses[:10], 1):
+            confidence_color = (
+                "green" if hyp.confidence >= 0.8 else "yellow" if hyp.confidence >= 0.6 else "red"
+            )
+            table.add_row(
+                str(i),
+                hyp.text[:60] + "..." if len(hyp.text) > 60 else hyp.text,
+                hyp.metric_name or "-",
+                f"[{confidence_color}]{hyp.confidence:.2f}[/{confidence_color}]",
+                hyp.evidence[:30] + "..." if len(hyp.evidence) > 30 else hyp.evidence,
+            )
+        _console.print(table)
+
+        high_conf = [h for h in hypotheses if h.confidence >= 0.8]
+        if high_conf:
+            _console.print(
+                f"\n[green]High confidence hypotheses: {len(high_conf)}/{len(hypotheses)}[/green]"
+            )
+
+
 __all__ = [
     "register_analyze_commands",
     "_perform_playbook_analysis",

evalvault/adapters/inbound/cli/commands/config.py

@@ -7,6 +7,7 @@ from rich.console import Console
 from rich.table import Table
 
 from evalvault.config.settings import Settings, apply_profile
+from evalvault.domain.metrics.registry import list_metric_specs
 
 
 def register_config_commands(app: typer.Typer, console: Console) -> None:
@@ -22,46 +23,9 @@ def register_config_commands(app: typer.Typer, console: Console) -> None:
         table.add_column("Description")
         table.add_column("Requires Ground Truth", justify="center")
 
-        table.add_row(
-            "faithfulness",
-            "Measures factual accuracy of the answer based on contexts",
-            "[red]No[/red]",
-        )
-        table.add_row(
-            "answer_relevancy",
-            "Measures how relevant the answer is to the question",
-            "[red]No[/red]",
-        )
-        table.add_row(
-            "context_precision",
-            "Measures ranking quality of retrieved contexts",
-            "[green]Yes[/green]",
-        )
-        table.add_row(
-            "context_recall",
-            "Measures if all relevant info is in retrieved contexts",
-            "[green]Yes[/green]",
-        )
-        table.add_row(
-            "summary_score",
-            "Measures summary coverage and conciseness against contexts",
-            "[red]No[/red]",
-        )
-        table.add_row(
-            "summary_faithfulness",
-            "Measures whether summary statements are grounded in contexts",
-            "[red]No[/red]",
-        )
-        table.add_row(
-            "entity_preservation",
-            "Measures preservation of key insurance entities in summaries",
-            "[red]No[/red]",
-        )
-        table.add_row(
-            "insurance_term_accuracy",
-            "Measures if insurance terms in answer are grounded in contexts",
-            "[red]No[/red]",
-        )
+        for spec in list_metric_specs():
+            needs_gt = "[green]Yes[/green]" if spec.requires_ground_truth else "[red]No[/red]"
+            table.add_row(spec.name, spec.description, needs_gt)
 
         console.print(table)
         console.print("\n[dim]Use --metrics flag with 'run' command to specify metrics.[/dim]")

evalvault/adapters/inbound/cli/commands/pipeline.py

@@ -13,6 +13,7 @@ from evalvault.adapters.outbound.storage.sqlite_adapter import SQLiteStorageAdap
 from evalvault.config.phoenix_support import ensure_phoenix_instrumentation
 from evalvault.config.settings import Settings
 
+from ..utils.analysis_io import serialize_pipeline_result
 from ..utils.options import db_option
 
 
@@ -36,7 +37,7 @@ def register_pipeline_commands(app: typer.Typer, console) -> None:
             "-o",
             help="Output file for results (JSON format).",
         ),
-        db_path: Path = db_option(help_text="Path to database file."),
+        db_path: Path | None = db_option(help_text="Path to database file."),
     ) -> None:
         """Analyze evaluation results using natural language query."""
         from evalvault.adapters.outbound.analysis.pipeline_factory import (
@@ -52,6 +53,10 @@ def register_pipeline_commands(app: typer.Typer, console) -> None:
         if settings.phoenix_enabled:
             ensure_phoenix_instrumentation(settings, console=console)
 
+        if db_path is None:
+            console.print("[red]Error: Database path is not configured.[/red]")
+            raise typer.Exit(1)
+
         storage = SQLiteStorageAdapter(db_path=db_path)
         llm_adapter = None
         try:
@@ -100,15 +105,10 @@ def register_pipeline_commands(app: typer.Typer, console) -> None:
                     console.print(f"  [red]{node_id}:[/red] {node_result.error}")
 
         if output:
-            data = {
-                "query": query,
-                "intent": result.intent.value if result.intent else None,
-                "is_complete": result.is_complete,
-                "duration_ms": result.total_duration_ms,
-                "final_output": result.final_output,
-            }
+            payload = serialize_pipeline_result(result)
+            payload["query"] = query
             with open(output, "w", encoding="utf-8") as f:
-                json.dump(data, f, ensure_ascii=False, indent=2)
+                json.dump(payload, f, ensure_ascii=False, indent=2)
             console.print(f"\n[green]Results saved to {output}[/green]")
 
         console.print()