codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/log_paths.py

@@ -0,0 +1,113 @@
+"""Centralized log path resolution.
+
+All log file names include project code and user ID for traceability.
+Environment variables:
+  - HDSP_PRJ_ID: project code
+  - JUPYTERHUB_USER / HDSP_BDP_ID: user identifier
+  - HDSP_USER_TEAM: team name (for idle shutdown logs)
+  - ANALYTICS_LOG_DIR: override for analytics log directory
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import os
+from pathlib import Path
+
+from .team_access import resolve_team
+
+logger = logging.getLogger(__name__)
+
+_PROJECT = os.environ.get("HDSP_PRJ_ID", "unknown")
+_USER = os.environ.get("JUPYTERHUB_USER", "") or os.environ.get(
+    "HDSP_BDP_ID", "unknown"
+)
+_TEAM = resolve_team()
+
+
+def get_log_dir() -> Path:
+    """Return the log directory, creating it if necessary.
+
+    Resolution order:
+      1. ANALYTICS_LOG_DIR env var
+      2. /home/sagemaker-user/.action_logs (SageMaker — auto-created)
+      3. <project_root>/logs  (extensions/jupyter/jupyter_ext -> parents[3])
+    """
+    env = os.environ.get("ANALYTICS_LOG_DIR")
+    if env:
+        d = Path(env)
+    else:
+        sagemaker = Path("/home/sagemaker-user")
+        if sagemaker.is_dir():
+            d = sagemaker / ".action_logs"
+        else:
+            d = Path(__file__).resolve().parents[3] / ".action_logs"
+    try:
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+    except OSError:
+        logger.warning("Failed to create log directory: %s", d)
+    # Local fallback
+    fallback = Path(__file__).resolve().parents[3] / ".action_logs"
+    try:
+        fallback.mkdir(parents=True, exist_ok=True)
+        return fallback
+    except OSError:
+        logger.warning("Log directory unavailable: %s", fallback)
+        return fallback
+
+
+_LOG_DIR = get_log_dir()
+
+
+def get_debug_log_path() -> str:
+    """Return path for agent_debug_{project}_{user}.log."""
+    return str(_LOG_DIR / f"agent_debug_{_PROJECT}_{_USER}.log")
+
+
+def get_structured_log_path() -> Path:
+    """Return path for agent_structured_{project}_{user}.jsonl."""
+    return _LOG_DIR / f"agent_structured_{_PROJECT}_{_USER}.jsonl"
+
+
+def get_analytics_log_path(event_type: str, date_str: str) -> Path:
+    """Return path for analytics_{type}_{project}_{user}_{YYYYMMDD}.jsonl."""
+    return _LOG_DIR / f"analytics_{event_type}_{_PROJECT}_{_USER}_{date_str}.jsonl"
+
+
+def write_idle_shutdown_log(
+    idle_seconds: float,
+    timeout_setting: int,
+    trigger_source: str,
+) -> None:
+    """Write idle shutdown event to a JSONL file.
+
+    File: idle_shutdown_{project}_{user}_{YYYYMMDD_HHMMSS}.jsonl
+    """
+    now = datetime.datetime.now()
+    ts_file = now.strftime("%Y%m%d_%H%M%S")
+    filename = f"idle_shutdown_{_PROJECT}_{_USER}_{ts_file}.jsonl"
+    path = _LOG_DIR / filename
+    event = {
+        "event": "idle_shutdown",
+        "ts": now.isoformat(timespec="seconds"),
+        "project": _PROJECT,
+        "user_id": _USER,
+        "team": _TEAM,
+        "idle_seconds": round(idle_seconds, 1),
+        "timeout_setting": timeout_setting,
+        "trigger_source": trigger_source,
+    }
+    try:
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(event, ensure_ascii=False) + "\n")
+    except OSError:
+        logger.warning("Failed to write idle shutdown log: %s", path)
+
+    # pod 가 곧 죽으므로 여기만 동기 플러시다 (이슈 #30). 지연 상한은 2초이고
+    # 실패해도 예외가 나가지 않는다 — 종료 경로를 막으면 안 된다.
+    from .analytics_ingest import enqueue_session_end
+
+    enqueue_session_end(event)

jupyter_ext/resource_usage.py

@@ -0,0 +1,519 @@
+"""
+Resource Usage Utilities for the Jupyter server host.
+
+Collects CPU, memory, disk, and GPU usage to guide client-side execution.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import Optional
+
+try:
+    import psutil
+except ImportError:  # pragma: no cover - optional dependency fallback
+    psutil = None
+
+
+def _read_cgroup_value(path: str) -> Optional[str]:
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            return handle.read().strip()
+    except Exception:
+        return None
+
+
+def _format_gb(value_bytes: float) -> float:
+    return round(value_bytes / (1024**3), 2)
+
+
+def _safe_float(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _safe_cpu_count() -> Optional[int]:
+    count = os.cpu_count()
+    return int(count) if count is not None else None
+
+
+def get_integrated_resources(
+    env_type: str = "auto", workspace_root: str = "."
+) -> dict[str, object]:
+    """
+    Collect resource usage snapshot for the Jupyter server host.
+
+    Args:
+        env_type: "auto", "pod", or "host" (auto detects Kubernetes)
+        workspace_root: Path used to compute disk usage
+
+    Returns:
+        JSON-serializable resource snapshot dict.
+    """
+    is_pod = False
+    if env_type == "auto":
+        is_pod = os.path.exists("/var/run/secrets/kubernetes.io") or bool(
+            os.environ.get("KUBERNETES_SERVICE_HOST")
+        )
+    else:
+        is_pod = env_type.lower() == "pod"
+
+    environment = "Kubernetes Pod" if is_pod else "Host/VM"
+    cpu: dict[str, Optional[float]] = {"cores": None, "usage_percent": None}
+    memory: dict[str, Optional[float]] = {
+        "total_gb": None,
+        "available_gb": None,
+        "used_gb": None,
+    }
+    disk: dict[str, Optional[object]] = {
+        "path": None,
+        "total_gb": None,
+        "free_gb": None,
+        "used_gb": None,
+    }
+    gpus: list[dict[str, Optional[object]]] = []
+    gpu_status = "not_detected"
+
+    if is_pod:
+        try:
+            cpu_max = _read_cgroup_value("/sys/fs/cgroup/cpu.max")
+            if cpu_max:
+                quota, period = cpu_max.split()
+                if quota != "max":
+                    cpu_limit = float(quota) / float(period)
+                else:
+                    cpu_limit = psutil.cpu_count() if psutil else _safe_cpu_count() or 0
+            else:
+                cpu_limit = psutil.cpu_count() if psutil else _safe_cpu_count() or 0
+
+            mem_limit_raw = _read_cgroup_value("/sys/fs/cgroup/memory.max")
+            mem_current_raw = _read_cgroup_value("/sys/fs/cgroup/memory.current")
+
+            if mem_limit_raw and mem_limit_raw != "max":
+                mem_limit_gb = _format_gb(float(mem_limit_raw))
+            else:
+                mem_limit_gb = (
+                    _format_gb(psutil.virtual_memory().total) if psutil else 0.0
+                )
+
+            mem_used_gb = _format_gb(float(mem_current_raw)) if mem_current_raw else 0.0
+
+            cpu["cores"] = round(cpu_limit, 2)
+            memory["total_gb"] = mem_limit_gb
+            memory["used_gb"] = mem_used_gb
+            if mem_limit_gb is not None and mem_used_gb is not None:
+                memory["available_gb"] = round(mem_limit_gb - mem_used_gb, 2)
+        except Exception:
+            cpu_count = psutil.cpu_count() if psutil else _safe_cpu_count()
+            cpu["cores"] = float(cpu_count) if cpu_count is not None else None
+            if psutil:
+                vm = psutil.virtual_memory()
+                memory["total_gb"] = _format_gb(vm.total)
+                memory["available_gb"] = _format_gb(vm.available)
+                memory["used_gb"] = _format_gb(vm.total - vm.available)
+    else:
+        cpu_count = psutil.cpu_count() if psutil else _safe_cpu_count()
+        cpu_percent = psutil.cpu_percent() if psutil else None
+        cpu["cores"] = float(cpu_count) if cpu_count is not None else None
+        cpu["usage_percent"] = cpu_percent
+        if psutil:
+            vm = psutil.virtual_memory()
+            memory["total_gb"] = _format_gb(vm.total)
+            memory["available_gb"] = _format_gb(vm.available)
+            memory["used_gb"] = _format_gb(vm.total - vm.available)
+
+    disk_path = workspace_root if workspace_root else "."
+    if not os.path.exists(disk_path):
+        disk_path = "."
+    disk["path"] = os.path.abspath(disk_path)
+    try:
+        total, used, free = shutil.disk_usage(disk_path)
+        disk["total_gb"] = _format_gb(total)
+        disk["free_gb"] = _format_gb(free)
+        disk["used_gb"] = _format_gb(used)
+    except Exception:
+        pass
+
+    if shutil.which("nvidia-smi"):
+        gpu_status = "available"
+        try:
+            result = subprocess.check_output(
+                [
+                    "nvidia-smi",
+                    "--query-gpu=name,utilization.gpu,memory.used,memory.total",
+                    "--format=csv,noheader,nounits",
+                ],
+                encoding="utf-8",
+                timeout=2,
+            ).strip()
+            if result:
+                for line in result.split("\n"):
+                    name, gpu_util, mem_used, mem_total = [
+                        value.strip() for value in line.split(",")
+                    ]
+                    gpus.append(
+                        {
+                            "name": name,
+                            "utilization_percent": _safe_float(gpu_util),
+                            "memory_used_mb": _safe_float(mem_used),
+                            "memory_total_mb": _safe_float(mem_total),
+                        }
+                    )
+        except Exception:
+            gpu_status = "unavailable"
+    else:
+        gpu_status = "not_detected"
+
+    return {
+        "environment": environment,
+        "cpu": cpu,
+        "memory": memory,
+        "disk": disk,
+        "gpus": gpus,
+        "gpu_status": gpu_status,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Resource Tier Classification & Guidance Generation
+# ---------------------------------------------------------------------------
+
+
+def _classify_cpu(cores: Optional[float]) -> str:
+    """Classify CPU into a tier based on core count."""
+    if cores is None:
+        return "unknown"
+    c = int(cores)
+    if c <= 3:
+        return "low"
+    if c <= 7:
+        return "medium"
+    if c <= 31:
+        return "high"
+    return "very_high"
+
+
+def _classify_memory(total_gb: Optional[float]) -> str:
+    """Classify memory into a tier based on total capacity."""
+    if total_gb is None:
+        return "unknown"
+    if total_gb < 4:
+        return "constrained"
+    if total_gb < 16:
+        return "limited"
+    if total_gb < 64:
+        return "comfortable"
+    if total_gb < 256:
+        return "large"
+    return "very_large"
+
+
+def _classify_single_gpu(name: str, vram_mb: Optional[float]) -> str:
+    """Classify a single GPU into a tier based on model name and VRAM."""
+    vram_gb = (vram_mb or 0) / 1024
+    upper = name.upper()
+
+    # Model-specific overrides (inference-optimized GPUs are entry-tier for training)
+    if "L4" in upper or "T4" in upper:
+        return "entry"
+    if "H200" in upper or "H100" in upper:
+        return "ultra"
+    # A100/V100: differentiate by VRAM
+    if "A100" in upper:
+        return "ultra" if vram_gb >= 48 else "high"
+    if "V100" in upper:
+        return "high" if vram_gb >= 24 else "mid"
+
+    # Fallback: classify by VRAM size
+    if vram_gb < 16:
+        return "entry"
+    if vram_gb < 24:
+        return "mid"
+    if vram_gb < 48:
+        return "high"
+    return "ultra"
+
+
+def _classify_gpu(gpus: list) -> dict:
+    """Classify GPU setup into a tier dict."""
+    if not gpus:
+        return {"tier": "none", "count": 0, "details": []}
+
+    details = []
+    for g in gpus:
+        name = g.get("name", "GPU")
+        vram_mb = g.get("memory_total_mb")
+        tier = _classify_single_gpu(name, vram_mb)
+        details.append({"name": name, "vram_mb": vram_mb, "tier": tier})
+
+    count = len(details)
+    # Overall GPU tier: use the best single-GPU tier
+    tier_order = ["entry", "mid", "high", "ultra"]
+    best_tier = max(details, key=lambda d: tier_order.index(d["tier"]))["tier"]
+
+    return {
+        "tier": best_tier,
+        "count": count,
+        "multi_gpu": count > 1,
+        "details": details,
+    }
+
+
+def classify_resource_tiers(data: dict) -> dict:
+    """Classify hardware resources into granular tiers for LLM guidance.
+
+    Args:
+        data: Output of ``get_integrated_resources()``.
+
+    Returns:
+        Dict with ``cpu_tier``, ``mem_tier``, ``gpu`` (sub-dict), and raw values.
+    """
+    cpu = data.get("cpu", {})
+    mem = data.get("memory", {})
+    gpus = data.get("gpus", [])
+
+    cores = cpu.get("cores")
+    total_gb = mem.get("total_gb")
+    avail_gb = mem.get("available_gb")
+
+    return {
+        "cpu_tier": _classify_cpu(cores),
+        "mem_tier": _classify_memory(total_gb),
+        "gpu": _classify_gpu(gpus),
+        "cores": cores,
+        "total_gb": total_gb,
+        "avail_gb": avail_gb,
+    }
+
+
+# --- Guidance text generators ------------------------------------------------
+
+_CPU_GUIDANCE = {
+    "low": (
+        "- CPU {cores}코어 (저사양): 병렬처리 오버헤드가 이득을 초과합니다. "
+        "알고리즘 복잡도 개선(O(n²)→O(n log n))과 벡터 연산(numpy/pandas vectorized ops)에 집중하세요. "
+        "multiprocessing/joblib 사용을 지양하세요."
+    ),
+    "medium": (
+        "- CPU {cores}코어 (중간): joblib(n_jobs={n_jobs})로 sklearn 교차검증·하이퍼파라미터 탐색을 병렬화하세요. "
+        "CPU 바운드 전처리는 multiprocessing.Pool(processes={n_jobs})로 분할 가능합니다. "
+        "I/O 바운드 작업은 threading 또는 asyncio가 더 효과적입니다."
+    ),
+    "high": (
+        "- CPU {cores}코어 (고사양): joblib(n_jobs=-1)로 모든 sklearn 병렬 연산을 최대화하세요. "
+        "대용량 DataFrame 처리 시 Dask LocalCluster(n_workers={workers}, threads_per_worker=2)를 활용하세요. "
+        "Polars의 자동 멀티스레딩이 {cores}코어를 완전히 활용합니다. "
+        "교차검증·앙상블 학습을 병렬 실행하세요."
+    ),
+    "very_high": (
+        "- CPU {cores}코어 (서버급): Dask/Ray 분산 스케줄러로 DataFrame 연산을 병렬화하세요. "
+        "Ray를 사용한 분산 하이퍼파라미터 튜닝(ray.tune)을 권장합니다. "
+        "Spark DataFrame으로 대규모 ETL 파이프라인을 구성하세요. "
+        "멀티 모델 앙상블을 동시 학습하세요(joblib n_jobs=-1 또는 Ray)."
+    ),
+}
+
+_MEM_GUIDANCE = {
+    "constrained": (
+        "- 가용 메모리 {avail_gb:.1f}GB / 전체 {total_gb:.1f}GB (제한적): "
+        "OOM 위험 높음. pd.read_csv(chunksize=10000) 필수, DataFrame 전체 로드 금지. "
+        "del df; gc.collect() 적극 사용. generator/iterator 패턴 우선. "
+        "float64→float32, object→category로 dtypes 즉시 변환."
+    ),
+    "limited": (
+        "- 가용 메모리 {avail_gb:.1f}GB / 전체 {total_gb:.1f}GB (보통): "
+        "dtypes 최적화 필수(float64→float32: ~50% 절감, object→category). "
+        "usecols로 필요 컬럼만 로드. 불필요한 중간 DataFrame 즉시 del. "
+        "데이터셋이 가용 메모리의 30% 초과 시 chunked 처리 권장."
+    ),
+    "comfortable": (
+        "- 가용 메모리 {avail_gb:.1f}GB / 전체 {total_gb:.1f}GB (여유): "
+        "~{safe_size:.0f}GB 이하 데이터셋은 전체 로드 가능. "
+        "Polars를 pandas 대신 사용하면 메모리 효율 2-5배 개선. "
+        "dtypes 최적화 권장(필수 아님). 대규모 조인 시 메모리 피크 주의."
+    ),
+    "large": (
+        "- 가용 메모리 {avail_gb:.1f}GB / 전체 {total_gb:.1f}GB (대용량): "
+        "대부분의 DS 데이터셋을 전체 로드 가능. "
+        "Polars를 pandas 대신 사용하면 처리 속도 2-10배 개선(멀티스레드 활용). "
+        "pd.read_parquet(engine='pyarrow')로 병렬 읽기. "
+        "메모리 여유가 있으므로 캐싱·memoization 적극 활용."
+    ),
+    "very_large": (
+        "- 가용 메모리 {avail_gb:.1f}GB / 전체 {total_gb:.1f}GB (초대용량): "
+        "메모리 부족은 사실상 없음. 분산 컴퓨팅은 속도를 위해 사용(OOM 방지가 아님). "
+        "Dask/Spark로 병렬 I/O와 연산을 가속하세요. "
+        "Polars/cuDF로 단일 머신 최대 성능을 추출하세요. "
+        "대규모 피처 엔지니어링을 인메모리로 자유롭게 수행 가능."
+    ),
+}
+
+_GPU_GUIDANCE = {
+    "entry": (
+        "- GPU {name} ({vram_gb:.0f}GB VRAM, entry급): "
+        "mixed precision(fp16/bf16) 필수. gradient checkpointing 필수. batch_size 최소화. "
+        "큰 모델 학습 불가→파인튜닝 시 LoRA/QLoRA 필수. "
+        "cuDF는 소규모 데이터에만 사용 가능."
+    ),
+    "mid": (
+        "- GPU {name} ({vram_gb:.0f}GB VRAM, mid급): "
+        "mixed precision 강력 권장. 중간 규모 모델 학습 가능. "
+        "gradient accumulation으로 effective batch size 확대. "
+        "DeepSpeed ZeRO Stage 1 활용. cuDF로 중간 규모 DataFrame GPU 가속."
+    ),
+    "high": (
+        "- GPU {name} ({vram_gb:.0f}GB VRAM, high급): "
+        "full precision 가능하나 fp16 권장(속도 이점). 대부분의 모델 학습 가능. "
+        "cuDF로 DataFrame GPU 가속. RAPIDS(cuML, cuGraph) 활용으로 "
+        "sklearn 대비 10-100배 가속."
+    ),
+    "ultra": (
+        "- GPU {name} ({vram_gb:.0f}GB VRAM, ultra급): "
+        "대규모 모델 학습/추론 가능. flash attention 활용. "
+        "cuDF/cuML 적극 활용으로 전체 DS 파이프라인 GPU 가속. "
+        "모델 병렬처리(tensor parallelism) 가능."
+    ),
+}
+
+
+def _gpu_guidance_lines(gpu_info: dict) -> list[str]:
+    """Generate GPU-specific guidance lines."""
+    lines: list[str] = []
+    if gpu_info["tier"] == "none":
+        lines.append(
+            "- GPU 미감지: GPU 의존 코드가 있다면 device='cpu' 폴백 확인. "
+            "sklearn/XGBoost CPU 버전 사용. cuDF/RAPIDS 사용 불가."
+        )
+        return lines
+
+    # Per-GPU guidance
+    for detail in gpu_info["details"]:
+        name = detail["name"]
+        vram_gb = (detail["vram_mb"] or 0) / 1024
+        tier = detail["tier"]
+        template = _GPU_GUIDANCE.get(tier, _GPU_GUIDANCE["entry"])
+        lines.append(template.format(name=name, vram_gb=vram_gb))
+
+    # Multi-GPU additional guidance
+    if gpu_info["multi_gpu"]:
+        count = gpu_info["count"]
+        lines.append(
+            f"- 멀티GPU ({count}장): 데이터 병렬처리(DDP) 기본 적용. "
+            f"GPU {count}장 활용 시 FSDP 또는 DeepSpeed ZeRO Stage 3 권장. "
+            "NCCL 통신 최적화. 대규모 모델은 tensor/pipeline parallelism 적용."
+        )
+
+    return lines
+
+
+def _combined_tech_recommendation(cpu_tier: str, mem_tier: str, gpu_info: dict) -> str:
+    """Generate cross-cutting technology stack recommendation."""
+    gpu_tier = gpu_info["tier"]
+
+    # DataFrame library recommendation
+    if gpu_tier in ("high", "ultra"):
+        df_rec = "cuDF(GPU 가속) 기본. Polars(CPU 폴백). pandas는 소규모 탐색에만."
+    elif mem_tier in ("large", "very_large") and cpu_tier in ("high", "very_high"):
+        df_rec = "Polars(기본) — 멀티스레드로 대용량 고속 처리. pandas는 소규모에만."
+    elif mem_tier in ("comfortable", "large"):
+        df_rec = "Polars 권장(속도 이점). pandas도 적정 규모에서 사용 가능."
+    elif mem_tier == "limited":
+        df_rec = "pandas + dtypes 최적화. 대용량 시 Dask DataFrame으로 전환."
+    else:
+        df_rec = "pandas chunked 처리 필수. 가능하면 Polars(메모리 효율 우수)."
+
+    # Parallelism recommendation
+    if cpu_tier == "very_high":
+        par_rec = "Ray/Dask 분산 처리. joblib(n_jobs=-1) + Ray 백엔드."
+    elif cpu_tier == "high":
+        par_rec = "joblib(n_jobs=-1). 대규모 작업은 Dask LocalCluster."
+    elif cpu_tier == "medium":
+        par_rec = "joblib(n_jobs=cores-1). multiprocessing.Pool 선택적."
+    else:
+        par_rec = "병렬처리 비권장. 벡터 연산으로 대체."
+
+    # ML training recommendation
+    if gpu_tier == "ultra" and gpu_info.get("multi_gpu"):
+        ml_rec = "FSDP/DeepSpeed 분산 학습. 대규모 모델 full training 가능."
+    elif gpu_tier == "ultra":
+        ml_rec = "단일 GPU로 대부분의 모델 full training. flash attention 활용."
+    elif gpu_tier == "high":
+        ml_rec = "full training 가능. RAPIDS cuML로 전통 ML 가속."
+    elif gpu_tier == "mid":
+        ml_rec = "mixed precision 학습. gradient accumulation 필수."
+    elif gpu_tier == "entry":
+        ml_rec = "LoRA/QLoRA 파인튜닝만. 큰 모델 full training 불가."
+    else:
+        ml_rec = "CPU 학습. sklearn n_jobs 활용. XGBoost hist/gpu_hist 불가."
+
+    return (
+        f"- 📊 권장 DataFrame 라이브러리: {df_rec}\n"
+        f"- ⚡ 병렬 처리 전략: {par_rec}\n"
+        f"- 🧠 ML 학습 전략: {ml_rec}"
+    )
+
+
+def generate_tier_guidance(tiers: dict, mode: str = "review") -> str:
+    """Generate Korean guidance text based on classified resource tiers.
+
+    Args:
+        tiers: Output of ``classify_resource_tiers()``.
+        mode: ``"review"`` for code review diagnostics,
+              ``"codegen"`` for imperative code generation instructions.
+
+    Returns:
+        Multi-line Korean guidance string.
+    """
+    lines: list[str] = []
+    cpu_tier = tiers.get("cpu_tier", "unknown")
+    mem_tier = tiers.get("mem_tier", "unknown")
+    gpu_info = tiers.get("gpu", {"tier": "none", "count": 0, "details": []})
+    cores = tiers.get("cores")
+    total_gb = tiers.get("total_gb") or 0
+    avail_gb = tiers.get("avail_gb") or 0
+
+    # CPU guidance
+    cpu_template = _CPU_GUIDANCE.get(cpu_tier)
+    if cpu_template and cores is not None:
+        n_jobs = max(1, int(cores) - 1)
+        workers = max(1, int(cores) // 2)
+        lines.append(
+            cpu_template.format(cores=int(cores), n_jobs=n_jobs, workers=workers)
+        )
+
+    # Memory guidance
+    mem_template = _MEM_GUIDANCE.get(mem_tier)
+    if mem_template:
+        safe_size = total_gb * 0.3
+        lines.append(
+            mem_template.format(
+                avail_gb=avail_gb, total_gb=total_gb, safe_size=safe_size
+            )
+        )
+
+    # Memory pressure warning (avail < 30% of total)
+    if total_gb > 0 and avail_gb > 0 and avail_gb < total_gb * 0.3:
+        lines.append(
+            f"- ⚠️ 메모리 압박: 가용 {avail_gb:.1f}GB / 전체 {total_gb:.1f}GB "
+            f"({avail_gb / total_gb * 100:.0f}%). 현재 상태에서는 "
+            "한 단계 낮은 메모리 전략을 적용하세요."
+        )
+
+    # GPU guidance
+    lines.extend(_gpu_guidance_lines(gpu_info))
+
+    # Combined technology recommendation
+    lines.append("")
+    header = (
+        "**환경 맞춤 기술 스택 권장**:" if mode == "review" else "**기술 스택 지침**:"
+    )
+    lines.append(header)
+    lines.append(_combined_tech_recommendation(cpu_tier, mem_tier, gpu_info))
+
+    return "\n".join(lines)