evalgate-sdk 3.3.1__py3-none-any.whl

evalgate_sdk/cli/golden_commands.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from evalgate_sdk.auto import (
+    DEFAULT_AUTO_HISTORY_PATH,
+    DEFAULT_AUTO_REPORT_PATH,
+    AutoOptions,
+    build_auto_report,
+    format_auto_human,
+    run_auto_daemon,
+    write_auto_report,
+)
+from evalgate_sdk.cluster import cluster_run_result, format_cluster_human
+from evalgate_sdk.golden import (
+    DEFAULT_LABELED_DATASET_PATH,
+    DEFAULT_SYNTHETIC_DATASET_PATH,
+    LabeledGoldenCase,
+    analyze_labeled_dataset,
+    format_analyze_human,
+    normalize_run_artifact,
+    parse_labeled_dataset,
+    write_jsonl,
+)
+from evalgate_sdk.replay_decision import NormalizedBudgetConfig, evaluate_replay_outcome
+from evalgate_sdk.synthesize import format_synthesize_human, parse_dimension_matrix, synthesize_labeled_dataset
+
+console = Console()
+
+auto_app = typer.Typer(help="Autonomous prompt-improvement workflow commands.", no_args_is_help=True)
+
+
+def _read_json(file_path: str) -> dict[str, Any]:
+    try:
+        data = json.loads(Path(file_path).read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise typer.BadParameter(f"File not found: {file_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON: {file_path}") from exc
+    if not isinstance(data, dict):
+        raise typer.BadParameter(f"Expected JSON object in {file_path}")
+    return data
+
+
+def _build_labeled_rows_from_cluster_summary(
+    cluster_summary: dict[str, Any],
+    *,
+    default_label: str,
+    failure_mode: str | None,
+    include_passed: bool,
+) -> list[LabeledGoldenCase]:
+    rows: list[LabeledGoldenCase] = []
+    timestamp = datetime.now(timezone.utc).isoformat()
+    for cluster in cluster_summary.get("clusters", []):
+        if not isinstance(cluster, dict):
+            continue
+        cluster_id = cluster.get("id") if isinstance(cluster.get("id"), str) else None
+        cluster_label = cluster.get("clusterLabel") if isinstance(cluster.get("clusterLabel"), str) else None
+        cluster_failure_mode = failure_mode
+        if cluster_failure_mode is None and isinstance(cluster.get("suggestedFailureMode"), str):
+            cluster_failure_mode = cluster["suggestedFailureMode"]
+        for case in cluster.get("cases", []):
+            if not isinstance(case, dict):
+                continue
+            status = case.get("status") if isinstance(case.get("status"), str) else "failed"
+            if status == "passed" and not include_passed:
+                continue
+            label_value = "pass" if status == "passed" and default_label != "fail" else ("pass" if status == "passed" else "fail")
+            rows.append(
+                LabeledGoldenCase(
+                    case_id=str(case.get("caseId") or case.get("id") or case.get("name") or "case"),
+                    input=str(case.get("input") or ""),
+                    expected=str(case.get("expected") or ""),
+                    actual=str(case.get("actual") or ""),
+                    label=label_value,
+                    failure_mode=None if label_value == "pass" else (cluster_failure_mode or status),
+                    labeled_at=timestamp,
+                    cluster_id=cluster_id,
+                    cluster_label=cluster_label,
+                )
+            )
+    return rows
+
+
+@auto_app.command("run")
+def auto_run(
+    objective: str = typer.Option(..., "--objective", help="Target failure mode or objective"),
+    prompt: str | None = typer.Option(None, "--prompt", help="Prompt file being optimized"),
+    hypothesis: str | None = typer.Option(None, "--hypothesis", help="Experiment hypothesis"),
+    baseline_run: str | None = typer.Option(None, "--baseline-run", help="Baseline run artifact"),
+    candidate_run: str | None = typer.Option(None, "--candidate-run", help="Candidate run artifact"),
+    budget: int = typer.Option(1, "--budget", help="Per-iteration budget"),
+    budget_mode: str = typer.Option("traces", "--budget-mode", help="Budget mode: traces or cost"),
+    autonomous: bool = typer.Option(False, "--autonomous", help="Enable autonomous bounded mode"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Plan only"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+    report: str = typer.Option(DEFAULT_AUTO_REPORT_PATH, "--report", help="Auto report output path"),
+) -> None:
+    options = AutoOptions(
+        objective=objective,
+        hypothesis=hypothesis,
+        prompt_path=prompt,
+        baseline_run_path=baseline_run,
+        candidate_run_path=candidate_run,
+        budget=budget,
+        budget_mode="cost" if budget_mode == "cost" else "traces",
+        autonomous=autonomous,
+        dry_run=dry_run,
+        format="json" if fmt == "json" else "human",
+        report_path=report,
+    )
+    auto_report = build_auto_report(options)
+    write_auto_report(auto_report, report)
+    if fmt == "json":
+        console.print_json(json.dumps(auto_report.to_dict()))
+    else:
+        console.print(format_auto_human(auto_report))
+        console.print(f"\nSaved → {Path(report)}")
+
+
+@auto_app.command("daemon")
+def auto_daemon(
+    objective: str = typer.Option(..., "--objective", help="Target failure mode or objective"),
+    prompt: str | None = typer.Option(None, "--prompt", help="Prompt file being optimized"),
+    hypothesis: str | None = typer.Option(None, "--hypothesis", help="Experiment hypothesis"),
+    baseline_run: str | None = typer.Option(None, "--baseline-run", help="Baseline run artifact"),
+    candidate_run: str | None = typer.Option(None, "--candidate-run", help="Candidate run artifact"),
+    budget: int = typer.Option(1, "--budget", help="Per-cycle budget"),
+    cycles: int = typer.Option(1, "--cycles", help="Number of bounded cycles to run"),
+    interval_ms: int = typer.Option(0, "--interval-ms", help="Delay between cycles"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+    history: str = typer.Option(DEFAULT_AUTO_HISTORY_PATH, "--history", help="History JSONL path"),
+) -> None:
+    options = AutoOptions(
+        objective=objective,
+        hypothesis=hypothesis,
+        prompt_path=prompt,
+        baseline_run_path=baseline_run,
+        candidate_run_path=candidate_run,
+        budget=budget,
+        format="json" if fmt == "json" else "human",
+    )
+    reports = run_auto_daemon(options, cycles=cycles, interval_ms=interval_ms, history_path=history)
+    if fmt == "json":
+        console.print_json(json.dumps({"cycles": len(reports), "history": history, "reports": [report.to_dict() for report in reports]}))
+    else:
+        for index, report_item in enumerate(reports, start=1):
+            console.print(f"EvalGate auto daemon cycle {index}/{len(reports)}")
+            console.print(format_auto_human(report_item))
+            console.print()
+        console.print(f"completed {len(reports)} cycle(s) successfully")
+
+
+@auto_app.command("history")
+def auto_history(
+    history: str = typer.Option(DEFAULT_AUTO_HISTORY_PATH, "--history", help="History JSONL path"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+) -> None:
+    path = Path(history)
+    if not path.exists():
+        raise typer.Exit(0)
+    rows = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        rows.append(json.loads(line))
+    if fmt == "json":
+        console.print_json(json.dumps({"history": rows}))
+        return
+    console.print(f"Auto history ({len(rows)})")
+    for row in rows[-10:]:
+        console.print(f"- {row.get('generatedAt', '?')} — {row.get('objective', '?')} ({row.get('executionMode', '?')})")
+
+
+@auto_app.command("init")
+def auto_init(
+    report: str = typer.Option(DEFAULT_AUTO_REPORT_PATH, "--report", help="Initial report path"),
+    history: str = typer.Option(DEFAULT_AUTO_HISTORY_PATH, "--history", help="History JSONL path"),
+) -> None:
+    Path(report).parent.mkdir(parents=True, exist_ok=True)
+    Path(history).parent.mkdir(parents=True, exist_ok=True)
+    Path(history).touch(exist_ok=True)
+    console.print(f"[green]✓[/green] Prepared {Path(report).parent}")
+
+
+def cluster(
+    run: str = typer.Option(..., "--run", help="Run artifact to cluster"),
+    output: str | None = typer.Option(None, "--output", help="Cluster report output path"),
+    clusters: int | None = typer.Option(None, "--clusters", help="Requested cluster count"),
+    include_passed: bool = typer.Option(False, "--include-passed", help="Include passed cases"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+) -> None:
+    run_data = _read_json(run)
+    summary = cluster_run_result(normalize_run_artifact(run_data), clusters=clusters, include_passed=include_passed)
+    if output:
+        output_path = Path(output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(json.dumps(summary.to_dict(), indent=2), encoding="utf-8")
+    if fmt == "json":
+        console.print_json(json.dumps(summary.to_dict()))
+    else:
+        console.print(format_cluster_human(summary))
+
+
+def analyze(
+    dataset: str = typer.Option(DEFAULT_LABELED_DATASET_PATH, "--dataset", help="Labeled dataset JSONL path"),
+    top: int = typer.Option(5, "--top", help="Top N failure modes"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+) -> None:
+    rows = parse_labeled_dataset(Path(dataset).read_text(encoding="utf-8"))
+    summary = analyze_labeled_dataset(rows, top=top)
+    if fmt == "json":
+        console.print_json(json.dumps(summary.to_dict()))
+    else:
+        console.print(format_analyze_human(summary))
+
+
+def label(
+    run: str | None = typer.Option(None, "--run", help="Run artifact to convert into labeled JSONL"),
+    cluster: str | None = typer.Option(None, "--cluster", help="Cluster report to convert into labeled JSONL"),
+    output: str = typer.Option(DEFAULT_LABELED_DATASET_PATH, "--output", help="Output JSONL path"),
+    default_label: str = typer.Option("fail", "--default-label", help="Default label: pass or fail"),
+    failure_mode: str | None = typer.Option(None, "--failure-mode", help="Failure mode for failed rows"),
+    include_passed: bool = typer.Option(False, "--include-passed", help="Include passed cases too"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+) -> None:
+    if bool(run) == bool(cluster):
+        raise typer.BadParameter("Use exactly one of --run or --cluster")
+    rows: list[LabeledGoldenCase] = []
+    if cluster:
+        rows = _build_labeled_rows_from_cluster_summary(
+            _read_json(cluster),
+            default_label=default_label,
+            failure_mode=failure_mode,
+            include_passed=include_passed,
+        )
+    else:
+        normalized = normalize_run_artifact(_read_json(run or ""))
+        timestamp = datetime.now(timezone.utc).isoformat()
+        for case in normalized.cases:
+            if case.status == "passed" and not include_passed:
+                continue
+            label_value = "pass" if case.status == "passed" and default_label != "fail" else ("pass" if case.status == "passed" else "fail")
+            row_failure_mode = None if label_value == "pass" else (failure_mode or case.status)
+            rows.append(
+                LabeledGoldenCase(
+                    case_id=case.case_id,
+                    input=case.input,
+                    expected=case.expected,
+                    actual=case.actual,
+                    label=label_value,
+                    failure_mode=row_failure_mode,
+                    labeled_at=timestamp,
+                )
+            )
+    write_jsonl(output, rows)
+    if fmt == "json":
+        console.print_json(json.dumps({"total": len(rows), "output": output}))
+    else:
+        console.print(f"Wrote {len(rows)} labeled case(s) → {output}")
+
+
+def synthesize(
+    dataset: str = typer.Option(DEFAULT_LABELED_DATASET_PATH, "--dataset", help="Labeled dataset JSONL path"),
+    dimensions: str | None = typer.Option(None, "--dimensions", help="Dimension matrix JSON path"),
+    count: int | None = typer.Option(None, "--count", help="Synthetic case count"),
+    failure_mode: list[str] | None = typer.Option(None, "--failure-mode", help="Requested failure modes"),
+    output: str = typer.Option(DEFAULT_SYNTHETIC_DATASET_PATH, "--output", help="Synthetic dataset output path"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+) -> None:
+    rows = parse_labeled_dataset(Path(dataset).read_text(encoding="utf-8"))
+    dimension_values: dict[str, list[str]] = {}
+    if dimensions:
+        dimension_values = parse_dimension_matrix(Path(dimensions).read_text(encoding="utf-8")).dimensions
+    summary = synthesize_labeled_dataset(
+        rows,
+        dimensions=dimension_values,
+        count=count,
+        failure_modes=failure_mode,
+        output_path=output,
+    )
+    if not summary.selected_failure_modes:
+        raise typer.Exit(2)
+    write_jsonl(output, summary.cases)
+    if fmt == "json":
+        console.print_json(json.dumps(summary.to_dict()))
+    else:
+        console.print(format_synthesize_human(summary))
+        console.print(f"\nSaved → {output}")
+
+
+def replay_decision(
+    previous: str = typer.Option(..., "--previous", help="Previous run artifact"),
+    current: str = typer.Option(..., "--current", help="Current run artifact"),
+    budget_mode: str = typer.Option("traces", "--budget-mode", help="Budget mode: traces or cost"),
+    max_traces: int = typer.Option(100, "--max-traces", help="Trace budget when using traces mode"),
+    max_cost_usd: float = typer.Option(1.0, "--max-cost-usd", help="Cost budget when using cost mode"),
+    fmt: str = typer.Option("human", "--format", help="Output format: human or json"),
+) -> None:
+    previous_run = _read_json(previous)
+    current_run = _read_json(current)
+    config = NormalizedBudgetConfig(
+        mode="cost" if budget_mode == "cost" else "traces",
+        max_traces=max_traces,
+        max_cost_usd=max_cost_usd,
+    )
+    decision = evaluate_replay_outcome(previous_run, current_run, config)
+    if fmt == "json":
+        console.print_json(json.dumps(decision.to_dict()))
+    else:
+        console.print(f"Decision: {decision.action}")
+        console.print(f"Reason: {decision.reason}")
+        console.print(
+            f"Comparison basis: {decision.comparison_basis} ({decision.previous_pass_rate:.4f} → {decision.new_pass_rate:.4f})"
+        )

evalgate_sdk/cli/manifest.py

@@ -0,0 +1,301 @@
+"""Evaluation Manifest Generation.
+
+Turn discovery output into a stable, versioned, machine-consumable artifact
+that becomes the input to run / impact / diff.
+
+Port of ``cli/manifest.ts``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from evalgate_sdk._version import SDK_VERSION
+
+MANIFEST_SCHEMA_VERSION = 1
+
+
+@dataclass
+class SpecFile:
+    """Spec file information."""
+
+    file_path: str = ""
+    file_hash: str = ""
+    spec_count: int = 0
+
+
+@dataclass
+class Spec:
+    """Individual specification."""
+
+    id: str = ""
+    name: str = ""
+    suite_path: list[str] = field(default_factory=list)
+    file_path: str = ""
+    position: dict[str, int] = field(default_factory=lambda: {"line": 1, "column": 1})
+    tags: list[str] = field(default_factory=list)
+    depends_on: dict[str, list[str]] = field(
+        default_factory=lambda: {
+            "prompts": [],
+            "datasets": [],
+            "tools": [],
+            "code": [],
+        }
+    )
+
+
+@dataclass
+class EvaluationManifest:
+    """Evaluation Manifest Schema."""
+
+    schema_version: int = MANIFEST_SCHEMA_VERSION
+    generated_at: int = 0
+    project: dict[str, str] = field(default_factory=dict)
+    runtime: dict[str, str] = field(default_factory=dict)
+    spec_files: list[SpecFile] = field(default_factory=list)
+    specs: list[Spec] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schemaVersion": self.schema_version,
+            "generatedAt": self.generated_at,
+            "project": self.project,
+            "runtime": self.runtime,
+            "specFiles": [
+                {"filePath": sf.file_path, "fileHash": sf.file_hash, "specCount": sf.spec_count}
+                for sf in self.spec_files
+            ],
+            "specs": [
+                {
+                    "id": s.id,
+                    "name": s.name,
+                    "suitePath": s.suite_path,
+                    "filePath": s.file_path,
+                    "position": s.position,
+                    "tags": s.tags,
+                    "dependsOn": s.depends_on,
+                }
+                for s in self.specs
+            ],
+        }
+
+
+@dataclass
+class ManifestLock:
+    """Lock file for caching."""
+
+    generated_at: int = 0
+    file_hashes: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class SpecAnalysis:
+    """Discovery result for a single spec."""
+
+    id: str = ""
+    name: str = ""
+    file: str = ""
+    tags: list[str] = field(default_factory=list)
+
+
+def generate_manifest(
+    specs: list[SpecAnalysis],
+    project_root: str,
+    project_name: str,
+    execution_mode: Any,
+) -> EvaluationManifest:
+    """Generate evaluation manifest from discovery results."""
+    generated_at = int(time.time())
+    namespace = _generate_namespace(project_root)
+
+    specs_by_file: dict[str, list[SpecAnalysis]] = {}
+    for spec in specs:
+        norm = _normalize_path(spec.file, project_root)
+        specs_by_file.setdefault(norm, []).append(spec)
+
+    spec_files: list[SpecFile] = []
+    processed_specs: list[Spec] = []
+
+    for file_path, file_specs in specs_by_file.items():
+        abs_path = os.path.join(project_root, file_path)
+        file_hash = _hash_file(abs_path)
+
+        spec_files.append(SpecFile(file_path=file_path, file_hash=file_hash, spec_count=len(file_specs)))
+
+        for sa in file_specs:
+            content = _read_file_safe(abs_path)
+            position = _extract_position(content, sa.name)
+            depends_on = _extract_dependencies(content)
+            suite_path = _generate_suite_path(sa.tags, file_path)
+
+            processed_specs.append(
+                Spec(
+                    id=sa.id,
+                    name=sa.name,
+                    suite_path=suite_path,
+                    file_path=_normalize_path(sa.file, project_root),
+                    position=position,
+                    tags=sa.tags,
+                    depends_on=depends_on,
+                )
+            )
+
+    mode_str = getattr(execution_mode, "mode", "spec") if execution_mode else "spec"
+
+    return EvaluationManifest(
+        schema_version=MANIFEST_SCHEMA_VERSION,
+        generated_at=generated_at,
+        project={"name": project_name, "root": ".", "namespace": namespace},
+        runtime={"mode": mode_str, "sdkVersion": SDK_VERSION},
+        spec_files=spec_files,
+        specs=processed_specs,
+    )
+
+
+def write_manifest(manifest: EvaluationManifest, project_root: str) -> None:
+    """Write manifest to disk."""
+    evalgate_dir = os.path.join(project_root, ".evalgate")
+    os.makedirs(evalgate_dir, exist_ok=True)
+
+    manifest_path = os.path.join(evalgate_dir, "manifest.json")
+    Path(manifest_path).write_text(json.dumps(manifest.to_dict(), indent=2), encoding="utf-8")
+
+    lock = ManifestLock(
+        generated_at=manifest.generated_at,
+        file_hashes={sf.file_path: sf.file_hash for sf in manifest.spec_files},
+    )
+    lock_path = os.path.join(evalgate_dir, "manifest.lock.json")
+    Path(lock_path).write_text(
+        json.dumps(
+            {
+                "generatedAt": lock.generated_at,
+                "fileHashes": lock.file_hashes,
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+
+def read_manifest(project_root: str) -> EvaluationManifest | None:
+    """Read existing manifest."""
+    manifest_path = os.path.join(project_root, ".evalgate", "manifest.json")
+    try:
+        data = json.loads(Path(manifest_path).read_text(encoding="utf-8"))
+        m = EvaluationManifest(
+            schema_version=data.get("schemaVersion", 1),
+            generated_at=data.get("generatedAt", 0),
+            project=data.get("project", {}),
+            runtime=data.get("runtime", {}),
+        )
+        for sf in data.get("specFiles", []):
+            m.spec_files.append(
+                SpecFile(file_path=sf["filePath"], file_hash=sf["fileHash"], spec_count=sf["specCount"])
+            )
+        for s in data.get("specs", []):
+            m.specs.append(
+                Spec(
+                    id=s["id"],
+                    name=s["name"],
+                    suite_path=s.get("suitePath", []),
+                    file_path=s["filePath"],
+                    position=s.get("position", {"line": 1, "column": 1}),
+                    tags=s.get("tags", []),
+                    depends_on=s.get("dependsOn", {"prompts": [], "datasets": [], "tools": [], "code": []}),
+                )
+            )
+        return m
+    except (OSError, json.JSONDecodeError, KeyError):
+        return None
+
+
+def read_lock(project_root: str) -> ManifestLock | None:
+    """Read existing lock file."""
+    lock_path = os.path.join(project_root, ".evalgate", "manifest.lock.json")
+    try:
+        data = json.loads(Path(lock_path).read_text(encoding="utf-8"))
+        return ManifestLock(generated_at=data["generatedAt"], file_hashes=data.get("fileHashes", {}))
+    except (OSError, json.JSONDecodeError, KeyError):
+        return None
+
+
+# ── Internal helpers ──────────────────────────────────────────────────
+
+
+def _normalize_path(file_path: str, project_root: str) -> str:
+    return os.path.relpath(file_path, project_root).replace("\\", "/")
+
+
+def _generate_namespace(project_root: str) -> str:
+    return hashlib.sha256(project_root.encode("utf-8")).hexdigest()[:8]
+
+
+def _hash_file(file_path: str) -> str:
+    try:
+        content = Path(file_path).read_bytes()
+        return f"sha256:{hashlib.sha256(content).hexdigest()}"
+    except OSError:
+        return "sha256:0"
+
+
+def _read_file_safe(path: str) -> str:
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def _extract_position(content: str, spec_name: str) -> dict[str, int]:
+    pattern = re.compile(r'define_eval\s*\(\s*["\']' + re.escape(spec_name) + r'["\']')
+    for i, line_content in enumerate(content.splitlines()):
+        m = pattern.search(line_content)
+        if m:
+            return {"line": i + 1, "column": m.start() + 1}
+    return {"line": 1, "column": 1}
+
+
+def _extract_dependencies(content: str) -> dict[str, list[str]]:
+    deps: dict[str, list[str]] = {"prompts": [], "datasets": [], "tools": [], "code": []}
+
+    depends_on_match = re.search(r"depends_on\s*=\s*\{([^}]+)\}", content, re.DOTALL)
+    if depends_on_match:
+        try:
+            raw = "{" + depends_on_match.group(1) + "}"
+            parsed = json.loads(raw)
+            return {
+                "prompts": parsed.get("prompts", []),
+                "datasets": parsed.get("datasets", []),
+                "tools": parsed.get("tools", []),
+                "code": parsed.get("code", []),
+            }
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    patterns = {
+        "prompts": re.compile(r'["\']([^"\']*\.md)["\']'),
+        "datasets": re.compile(r'["\']([^"\']*\.json)["\']'),
+        "code": re.compile(r"from\s+([^\s]+)\s+import|import\s+([^\s]+)"),
+    }
+    for key, pat in patterns.items():
+        for m in pat.finditer(content):
+            val = m.group(1) or (m.group(2) if m.lastindex and m.lastindex >= 2 else None)
+            if val:
+                deps[key].append(val)
+
+    return deps
+
+
+def _generate_suite_path(tags: list[str], file_path: str) -> list[str]:
+    if tags:
+        return [tags[0]]
+    parts = file_path.split("/")
+    if len(parts) > 1:
+        return [parts[0]]
+    return ["general"]