BibexPy 2.0.0__py3-none-any.whl

bibexpy/_server/services/filter_engine.py

@@ -0,0 +1,300 @@
+"""Pandas tabanlı filtre motoru — UI'dan gelen filter spec'i datasete uygular.
+
+Plan dosyasındaki şemayı izler:
+    year, doc_type, language, db_source, citation_count, journal, authors,
+    wc_categories, sc_categories, fulltext, quality
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+import pandas as pd
+
+from services import merger
+
+
+# ---------- Dataset yükleme (cache) ----------
+
+_DF_CACHE: dict[tuple[str, float], pd.DataFrame] = {}
+
+
+def _ensure_uid_column(df: pd.DataFrame) -> bool:
+    """Her satıra benzersiz, stabil bir UID atar. UID kolonu yoksa ekler.
+
+    Return: True = ekledi (kaydetmek gerek), False = zaten vardı.
+    """
+    import uuid
+    if "UID" in df.columns:
+        # Eksik / duplicate UID'leri doldur
+        s = df["UID"].astype(str).str.strip()
+        empty = (s == "") | (s.str.upper() == "NAN") | s.isna()
+        dups = s.duplicated(keep="first") & ~empty
+        if not empty.any() and not dups.any():
+            return False
+        # Eksik veya çakışan UID'lere yeni değer ata
+        existing = set(s[~empty & ~dups].tolist())
+        for i in df.index[empty | dups]:
+            while True:
+                nid = f"r_{uuid.uuid4().hex[:10]}"
+                if nid not in existing:
+                    existing.add(nid)
+                    df.at[i, "UID"] = nid
+                    break
+        return True
+    # UID kolonu tamamen yok
+    df["UID"] = [f"r_{uuid.uuid4().hex[:10]}" for _ in range(len(df))]
+    return True
+
+
+def load_merged(project_id: str) -> pd.DataFrame:
+    p = merger.merged_dataset_path(project_id)
+    if p is None:
+        raise FileNotFoundError("Birleştirilmiş veri yok — önce Merge çalıştırın")
+    mtime = p.stat().st_mtime
+    key = (str(p), mtime)
+    if key not in _DF_CACHE:
+        _DF_CACHE.clear()  # tek-kullanıcı, tek-dataset
+        df = pd.read_excel(p)
+        # Tüm string sütunları normalize et — boş hücreler için empty string
+        for col in df.columns:
+            if df[col].dtype == "object":
+                df[col] = df[col].fillna("")
+        # Her satıra UID ata (yoksa) ve kalıcı olarak diske yaz
+        if _ensure_uid_column(df):
+            try:
+                df.to_excel(p, index=False)
+            except Exception:
+                pass  # write hatası ana akışı durdurmasın — UID memory'de yine var
+        _DF_CACHE[key] = df
+    return _DF_CACHE[key]
+
+
+# ---------- Filter spec uygulama ----------
+
+def _has_col(df: pd.DataFrame, col: str) -> bool:
+    return col in df.columns
+
+
+def _coerce_int_series(s: pd.Series) -> pd.Series:
+    return pd.to_numeric(s, errors="coerce")
+
+
+def _apply_range(df: pd.DataFrame, col: str, rng: dict[str, Any]) -> pd.Series:
+    """Hem yıl hem citation gibi numerik aralık filtresi."""
+    if not _has_col(df, col):
+        return pd.Series(True, index=df.index)
+    nums = _coerce_int_series(df[col])
+    mask = pd.Series(True, index=df.index)
+    if rng.get("min") is not None:
+        mask &= nums >= float(rng["min"])
+    if rng.get("max") is not None:
+        mask &= nums <= float(rng["max"])
+    return mask
+
+
+def _apply_in(df: pd.DataFrame, col: str, values: list[str]) -> pd.Series:
+    if not values or not _has_col(df, col):
+        return pd.Series(True, index=df.index)
+    norm = [str(v).strip().upper() for v in values if v]
+    series = df[col].astype(str).str.upper().str.strip()
+    return series.isin(norm)
+
+
+def _apply_contains_any(df: pd.DataFrame, col: str, values: list[str]) -> pd.Series:
+    """Çoklu kategori alanları (WC, SC, AU) — değerler ';' veya ',' ile ayrılmış."""
+    if not values or not _has_col(df, col):
+        return pd.Series(True, index=df.index)
+    needles = [str(v).strip().upper() for v in values if v]
+    if not needles:
+        return pd.Series(True, index=df.index)
+    series = df[col].astype(str).str.upper()
+    pattern = "|".join(re.escape(n) for n in needles)
+    return series.str.contains(pattern, na=False, regex=True)
+
+
+def _fulltext_query(df: pd.DataFrame, query: str, fields: list[str]) -> pd.Series:
+    """Basit AND/OR/NOT desteği. Tırnak içi ifadeler için literal eşleşme.
+
+    Örnek: '(machine OR deep) AND learning NOT survey'
+    """
+    fields = [f for f in fields if _has_col(df, f)] or ["AB", "TI", "DE", "ID"]
+    fields = [f for f in fields if _has_col(df, f)]
+    if not fields:
+        return pd.Series(True, index=df.index)
+
+    combined = df[fields[0]].astype(str).str.upper()
+    for f in fields[1:]:
+        combined = combined + " || " + df[f].astype(str).str.upper()
+
+    q = query.strip().upper()
+    if not q:
+        return pd.Series(True, index=df.index)
+
+    # NOT terimleri çıkar
+    not_terms: list[str] = []
+    def _grab_not(m: re.Match) -> str:
+        not_terms.append(m.group(1).strip().strip('"'))
+        return " "
+    q = re.sub(r"\bNOT\s+(\"[^\"]+\"|\S+)", _grab_not, q)
+
+    # OR ayır (üst seviye)
+    or_clauses = [c.strip() for c in re.split(r"\bOR\b", q) if c.strip()]
+    if not or_clauses:
+        or_clauses = [q]
+
+    or_mask = pd.Series(False, index=df.index)
+    for clause in or_clauses:
+        # AND terimleri
+        and_terms = [t.strip().strip('"') for t in re.split(r"\bAND\b", clause) if t.strip()]
+        # Tek-terimli & parantez temizliği
+        and_terms = [t.strip("() ").strip() for t in and_terms if t.strip("() ").strip()]
+        if not and_terms:
+            continue
+        clause_mask = pd.Series(True, index=df.index)
+        for term in and_terms:
+            clause_mask &= combined.str.contains(re.escape(term), na=False, regex=True)
+        or_mask |= clause_mask
+
+    for nt in not_terms:
+        if nt:
+            or_mask &= ~combined.str.contains(re.escape(nt), na=False, regex=True)
+
+    return or_mask
+
+
+def _apply_quality(df: pd.DataFrame, quality: dict[str, Any]) -> pd.Series:
+    mask = pd.Series(True, index=df.index)
+    for field in quality.get("missing", []) or []:
+        if not _has_col(df, field):
+            continue
+        s = df[field].astype(str).str.strip()
+        mask &= (s == "") | (s.str.upper() == "NAN")
+    for field in quality.get("has", []) or []:
+        if not _has_col(df, field):
+            continue
+        s = df[field].astype(str).str.strip()
+        mask &= (s != "") & (s.str.upper() != "NAN")
+    return mask
+
+
+def apply_filter(df: pd.DataFrame, spec: dict[str, Any]) -> pd.DataFrame:
+    if not spec:
+        return df
+    mask = pd.Series(True, index=df.index)
+    if "year" in spec and spec["year"]:
+        mask &= _apply_range(df, "PY", spec["year"])
+    if "citation_count" in spec and spec["citation_count"]:
+        mask &= _apply_range(df, "TC", spec["citation_count"])
+    if "doc_type" in spec:
+        mask &= _apply_in(df, "DT", spec["doc_type"])
+    if "language" in spec:
+        mask &= _apply_in(df, "LA", spec["language"])
+    if "db_source" in spec:
+        mask &= _apply_in(df, "DB", spec["db_source"])
+    if "journal" in spec:
+        mask &= _apply_contains_any(df, "SO", spec["journal"])
+    if "authors" in spec:
+        mask &= _apply_contains_any(df, "AU", spec["authors"])
+    if "wc_categories" in spec:
+        mask &= _apply_contains_any(df, "WC", spec["wc_categories"])
+    if "sc_categories" in spec:
+        mask &= _apply_contains_any(df, "SC", spec["sc_categories"])
+    if "fulltext" in spec and spec["fulltext"] and spec["fulltext"].get("query"):
+        fields = spec["fulltext"].get("fields") or ["AB", "TI", "DE", "ID"]
+        mask &= _fulltext_query(df, spec["fulltext"]["query"], fields)
+    if "quality" in spec and spec["quality"]:
+        mask &= _apply_quality(df, spec["quality"])
+    return df.loc[mask]
+
+
+# ---------- Facets ----------
+
+DEFAULT_FACET_FIELDS = ["PY", "DT", "LA", "DB"]
+
+
+def _value_counts(series: pd.Series, top: int = 30) -> list[dict]:
+    s = series.astype(str).str.strip()
+    s = s[(s != "") & (s.str.upper() != "NAN")]
+    counts = s.value_counts().head(top)
+    return [{"value": str(k), "count": int(v)} for k, v in counts.items()]
+
+
+def compute_facets(df: pd.DataFrame) -> dict[str, Any]:
+    facets: dict[str, Any] = {"total": int(len(df))}
+    if _has_col(df, "PY"):
+        years = pd.to_numeric(df["PY"], errors="coerce").dropna().astype(int)
+        if len(years):
+            histogram = years.value_counts().sort_index()
+            facets["year"] = {
+                "min": int(years.min()),
+                "max": int(years.max()),
+                "histogram": [{"year": int(y), "count": int(c)} for y, c in histogram.items()],
+            }
+    if _has_col(df, "TC"):
+        cit = pd.to_numeric(df["TC"], errors="coerce").dropna().astype(int)
+        if len(cit):
+            facets["citation_count"] = {"min": int(cit.min()), "max": int(cit.max()), "mean": float(cit.mean())}
+    for field, name in [("DT", "doc_type"), ("LA", "language"), ("DB", "db_source")]:
+        if _has_col(df, field):
+            facets[name] = _value_counts(df[field], top=20)
+    # Çoklu-değerli alanlar için top dergi/kategori (split-by-semicolon yapmadan)
+    if _has_col(df, "SO"):
+        facets["journal_top"] = _value_counts(df["SO"], top=20)
+    return facets
+
+
+# ---------- Sayfalama + projeksiyon ----------
+
+# Bunlar UI'da varsayılan olarak görünür kolonlar (öncelik sırası); diğerleri açılır menüden açılır.
+DISPLAY_COLS = ["TI", "AU", "SO", "PY", "TC", "DT", "LA", "DI", "DE", "DB"]
+
+# UI tarafından bilinmeyen / faydasız kolonlar (Excel index, vb.)
+SKIP_COLS = {"Unnamed: 0", "ER"}
+
+
+def paginate(df: pd.DataFrame, offset: int = 0, limit: int = 50, columns: Optional[list[str]] = None) -> dict:
+    """Tüm kolonları döndür (kullanıcı UI'dan filtreleyebilsin). columns verilirse onları kullan.
+
+    UID kolonu varsa her zaman dahil edilir (frontend row identification için).
+    """
+    if columns:
+        cols = [c for c in columns if c in df.columns]
+        # UID her zaman dahil — UI'da görünmese bile seçim için lazım
+        if "UID" in df.columns and "UID" not in cols:
+            cols = ["UID"] + cols
+    else:
+        # Tüm kolonlar; ama UI'da en sık görünenler önce gelsin
+        all_cols = [c for c in df.columns if c not in SKIP_COLS]
+        priority = [c for c in DISPLAY_COLS if c in all_cols]
+        rest = [c for c in all_cols if c not in priority]
+        cols = priority + sorted(rest)
+        # UID en başa
+        if "UID" in df.columns and "UID" in cols:
+            cols = ["UID"] + [c for c in cols if c != "UID"]
+
+    total = int(len(df))
+    page = df.iloc[offset: offset + limit][cols]
+    records: list[dict[str, Any]] = []
+    for _, row in page.iterrows():
+        rec: dict[str, Any] = {}
+        for c in cols:
+            v = row[c]
+            if pd.isna(v):
+                rec[c] = None
+            elif isinstance(v, (int, float)) and not isinstance(v, bool):
+                # Sayısal alanları string yap (NaN korunsun)
+                rec[c] = str(int(v)) if float(v).is_integer() else str(v)
+            else:
+                rec[c] = str(v) if v is not None else None
+        records.append(rec)
+    return {
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+        "columns": cols,
+        "records": records,
+    }

bibexpy/_server/services/merger.py

@@ -0,0 +1,202 @@
+"""Birleştirme operasyonları sarmalı.
+
+v2'de her birleştirme bağımsız bir analiz klasörü olarak saklanır
+(`storage/<id>/analyses/analysis_<ts>_<method>/`). Bu modül kaynakları yükler ve
+smart_merger pipeline'ına yönlendirir; pipeline kendi analiz klasörünü açıp
+finalize eder.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+from fastapi import HTTPException
+
+from jobs.runner import JobContext
+from services import analyses, converter, storage
+
+
+def _project_paths(project_id: str) -> tuple[Path, Path, Path]:
+    """(root, raw, processed) — proje veri klasörleri."""
+    meta = storage.get_project(project_id)
+    if meta is None:
+        raise HTTPException(404, "Proje bulunamadı")
+    root = storage.project_dir(project_id)
+    return root, root / "raw", root / "processed"
+
+
+def _find_xlsx(processed: Path, raw: Path, hint: str) -> Path | None:
+    """Önce processed, sonra raw'da ara."""
+    for d in (processed, raw):
+        if not d.exists():
+            continue
+        for f in d.iterdir():
+            if not f.is_file():
+                continue
+            if f.suffix.lower() == ".xlsx" and hint in f.name.lower():
+                return f
+    return None
+
+
+def check_ready_to_merge(project_id: str) -> None:
+    """Merge başlamadan ÖNCE çağrılır (job submit etmeden). Hazırlık artık merge
+    job'unun ilk fazında ÖRTÜK yapıldığından ham veri yeterlidir; yalnızca hiç
+    kaynak veri yoksa 409 'no_source_data' fırlatır (UI kullanıcıyı yüklemeye yönlendirir).
+    """
+    _, raw, processed = _project_paths(project_id)
+    has_xlsx = bool(
+        _find_xlsx(processed, raw, "scopus") or _find_xlsx(processed, raw, "scp")
+        or _find_xlsx(processed, raw, "wos")
+    )
+    has_raw = raw.exists() and any(
+        f.is_file() and f.suffix.lower() in (".csv", ".txt", ".isi", ".xlsx")
+        for f in raw.iterdir()
+    )
+    if has_xlsx or has_raw:
+        return
+    raise HTTPException(409, "no_source_data")
+
+
+def _load_inputs(
+    project_id: str, ctx: JobContext | None = None
+) -> tuple[pd.DataFrame | None, pd.DataFrame | None]:
+    """Scopus + WoS XLSX'leri yükle. Eksik biri varsa CSV/TXT'den otomatik dönüştür.
+
+    Tek kaynak varsa onu döndürür, diğeri None olur (birleştirme adımı bunu
+    passthrough yapar). YALNIZCA ikisi de yoksa hata verir — kullanıcı sadece
+    Scopus ya da sadece WoS verisini hazırlamak isteyebilir.
+    """
+    _, raw, processed = _project_paths(project_id)
+
+    scp_xlsx = _find_xlsx(processed, raw, "scopus") or _find_xlsx(processed, raw, "scp")
+    wos_xlsx = _find_xlsx(processed, raw, "wos")
+
+    # Hazırlanmış (processed) XLSX yoksa merge ham CSV/TXT'den OTOMATİK üretmez —
+    # bu 1. adımı (Preparing) baypas ederdi. Bunun yerine, ham veri var ama hazırlık
+    # yapılmamışsa kullanıcıyı 1. adıma yönlendiren net bir hata döndürürüz.
+    if scp_xlsx is None and wos_xlsx is None:
+        has_raw = raw.exists() and any(
+            f.suffix.lower() in (".csv", ".txt", ".isi", ".xlsx")
+            for f in raw.iterdir() if f.is_file()
+        )
+        # Ham veri VAR ama hazırlanmamış → "önce hazırla"; hiç veri yoksa → "önce yükle".
+        raise HTTPException(409, "not_prepared" if has_raw else "no_source_data")
+
+    scp_df = pd.read_excel(scp_xlsx) if scp_xlsx is not None else None
+    wos_df = pd.read_excel(wos_xlsx) if wos_xlsx is not None else None
+    if ctx:
+        ctx.log(
+            f"Sources — Scopus: {len(scp_df) if scp_df is not None else 'none'}, "
+            f"WoS: {len(wos_df) if wos_df is not None else 'none'}"
+        )
+    return scp_df, wos_df
+
+
+async def _run_single_source(
+    ctx: JobContext, project_id: str,
+    scp_df: pd.DataFrame | None, wos_df: pd.DataFrame | None,
+) -> dict[str, Any]:
+    """Tek kaynak (yalnız Scopus veya yalnız WoS) — birleştirilecek ikinci veri yok.
+    Tek kaynağı doğrudan analiz veri seti yapar (dedup yok), filtreye hazır.
+    """
+    import asyncio
+    df = scp_df if scp_df is not None else wos_df
+    src = "Scopus" if scp_df is not None else "WoS"
+    ctx.log(f"Single source ({src}) — no second dataset to merge, used directly (no dedup).")
+    ctx.progress(0.3)
+
+    analysis_id, adir = analyses.create_analysis(project_id, "single")
+    ctx.log(f"Analysis folder: {analysis_id}")
+    output_xlsx = adir / "merged.xlsx"
+    await asyncio.to_thread(lambda: df.to_excel(output_xlsx, index=False))
+    ctx.progress(0.7)
+
+    scp_count = int(len(scp_df)) if scp_df is not None else 0
+    wos_count = int(len(wos_df)) if wos_df is not None else 0
+    statistic_xlsx = adir / "Statistic.xlsx"
+    try:
+        from services.smart_merger import _write_statistic_smart
+        await asyncio.to_thread(
+            _write_statistic_smart, int(len(df)), wos_count, scp_count, df, statistic_xlsx,
+        )
+    except Exception as e:
+        ctx.log(f"Statistic.xlsx could not be generated: {e}")
+
+    try:
+        from services import filter_engine
+        filter_engine._DF_CACHE.clear()
+    except Exception:
+        pass
+
+    analyses.finalize_analysis(project_id, analysis_id)
+    storage.touch_project(project_id)
+    ctx.progress(1.0)
+    ctx.log(f"Single source ready — {len(df)} records. You can proceed to the filtering step.")
+    return {
+        "method": "single",
+        "analysis_id": analysis_id,
+        "scopus_input": scp_count,
+        "wos_input": wos_count,
+        "merged_count": int(len(df)),
+        "duplicates_removed": 0,
+        "output_xlsx": str(output_xlsx.relative_to(storage.settings.storage_path)),
+        "stats": {},
+    }
+
+
+async def run_merge(ctx: JobContext, project_id: str) -> dict[str, Any]:
+    """Birleştirme jobu — tek algoritma: Smart Merge.
+
+    Tek kaynak (yalnız Scopus veya yalnız WoS) varsa passthrough (dedup yok);
+    iki kaynak varsa bağımsız smart_merger pipeline'ı çalışır — kendi analiz
+    klasörünü açar, finalize eder ve özetini döndürür.
+    """
+    import asyncio
+
+    ctx.log("Starting merge (Smart Merge)")
+    ctx.progress(0.05)
+
+    # Örtük hazırlık — ham CSV/TXT'leri konsolide XLSX'e çevir (ayrı Prepare adımı yok).
+    # Skip-if-fresh: yalnız ham dosya processed'tan yeniyse yeniden çevirir.
+    ctx.log("Preparing sources (CSV/TXT → XLSX)")
+    await asyncio.to_thread(converter.auto_prepare, project_id, ctx)
+
+    # Kaynakları yükle — tek-kaynak tespiti dispatch'ten önce yapılmalı.
+    scp_df, wos_df = await asyncio.to_thread(_load_inputs, project_id, ctx)
+
+    # Tek kaynak: birleştirilecek ikinci veri yok → passthrough (dedup yok),
+    # doğrudan filtreye hazır analiz veri seti.
+    if scp_df is None or wos_df is None:
+        return await _run_single_source(ctx, project_id, scp_df, wos_df)
+
+    # İki kaynak da var → Smart Merge (bağımsız pipeline, kendi klasörünü açar).
+    from services import smart_merger
+    return await smart_merger.run_smart_merge(ctx, project_id)
+
+
+def list_merged(project_id: str) -> list[dict]:
+    """Aktif analiz klasöründeki dosyaları listele."""
+    adir = analyses.get_active_analysis_dir(project_id)
+    if adir is None:
+        return []
+    out = []
+    for f in sorted(adir.iterdir()):
+        if not f.is_file() or f.name == "meta.json":
+            continue
+        out.append({
+            "name": f.name,
+            "size": f.stat().st_size,
+            "relative_path": str(f.relative_to(storage.settings.storage_path)),
+        })
+    return out
+
+
+def merged_dataset_path(project_id: str) -> Path | None:
+    """Filter/export için ana birleştirilmiş XLSX'i bul.
+
+    Aktif analiz klasöründen okur. Records / Filter / Quality / Disambiguation
+    otomatik olarak aktif analizin dataset'ini görür.
+    """
+    return analyses.active_dataset_path(project_id)

bibexpy/_server/services/methodology.py

@@ -0,0 +1,102 @@
+"""LLM ile metodoloji raporu üretimi.
+
+Operasyon günlüğü (audit log) bir LLM'e gönderilir; LLM, bibliometrik bir
+makalenin "Veri Hazırlama / Metodoloji" alt bölümüne yazılabilecek İngilizce
+bir anlatı döndürür. Sonuç projede saklanır ve MD/TXT/PDF olarak indirilebilir.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+from fastapi import HTTPException
+
+from config import settings
+from services import report_export, storage
+from services.disambiguation.deepseek_client import (
+    DeepSeekClient, DeepSeekError, METHODOLOGY_SYSTEM_PROMPT,
+)
+
+
+# Üretilen metinde her zaman bulunması gereken BibexPy künyesi (APA7, kullanıcı zorunlu kıldı).
+BIBEXPY_CITATION = (
+    "Kara, B. C., Şahin, A., & Dirsehan, T. (2025). BibexPy: Harmonizing the "
+    "bibliometric symphony of Scopus and Web of Science. SoftwareX, 30, 102098. "
+    "https://doi.org/10.1016/j.softx.2025.102098"
+)
+
+
+def _ensure_citation(text: str) -> str:
+    """LLM atfı eklemediyse deterministik olarak ekle (çift eklemeyi önle)."""
+    low = text.lower()
+    if "softx" in low or "dirsehan" in low or "102098" in low:
+        return text
+    return text.rstrip() + "\n\n## Reference\n\n" + BIBEXPY_CITATION
+
+
+def _report_path(project_id: str) -> Path:
+    return storage.project_dir(project_id) / "methodology_report.json"
+
+
+def _client() -> DeepSeekClient:
+    api_key = settings.effective_llm_api_key
+    if not api_key:
+        raise HTTPException(400, "llm_key_missing")
+    return DeepSeekClient(
+        api_key=api_key,
+        base_url=settings.effective_llm_base_url,
+        model=settings.effective_llm_model,
+    )
+
+
+def get_methodology(project_id: str) -> Optional[dict[str, Any]]:
+    """Saklanan metodoloji raporunu döndür (yoksa None)."""
+    p = _report_path(project_id)
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def generate_methodology(project_id: str) -> dict[str, Any]:
+    """Günlükten LLM ile İngilizce metodoloji raporu üret, sakla ve döndür."""
+    digest = report_export.build_log_digest(project_id)
+    if not digest.get("steps"):
+        raise HTTPException(400, "no_operations")
+
+    client = _client()  # anahtar yoksa burada llm_key_missing fırlatır
+    try:
+        text = client.chat_text(
+            METHODOLOGY_SYSTEM_PROMPT,
+            json.dumps(digest, ensure_ascii=False),
+            temperature=0.3,
+        )
+    except DeepSeekError as e:
+        raise HTTPException(502, f"llm_request_failed: {e}")
+
+    report = {
+        "text": _ensure_citation((text or "").strip()),
+        "generated_at": time.time(),
+        "model": settings.effective_llm_model,
+        "provider": settings.llm_provider or "deepseek",
+        "lang": "en",
+        "step_count": len(digest["steps"]),
+    }
+    try:
+        _report_path(project_id).write_text(
+            json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    except Exception:
+        pass
+    return report
+
+
+def methodology_title(project_id: str) -> str:
+    meta = storage.get_project(project_id)
+    name = meta.name if meta else project_id
+    return f"Data Preparation Methodology — {name}"