citegraph 0.2.0__py3-none-any.whl

citegraph/cocitation_stats.py

@@ -0,0 +1,370 @@
+"""Does a documented tie between two authors show up in how the literature cites them?
+
+A supervision record says that two people are connected socially. An author
+co-citation network says which people the field reads together. This module
+asks whether the first shows up in the second: for each tie, is the pair
+co-cited more often than a *comparable* pair of strangers?
+
+"Comparable" is the whole problem. Advisors and their students are prominent
+people, and prominent people are co-cited with everyone, so a tie that beats an
+average pair has proved nothing. The null here therefore holds prominence
+fixed: each end of a tie is replaced by an author cited by a similar number of
+bibliographies, and the tie is scored against the pairs that substitution
+produces. What survives is co-citation the two ends' individual visibility does
+not already explain.
+
+Two further controls matter on a corpus whose bibliographies were written by
+the people being studied:
+
+- ``exclude_self_citations`` drops, for each pair, the bibliographies either
+  member wrote. What remains is co-citation by third parties — other people
+  putting the two names in one conversation. **The exclusion defines a universe
+  rather than filtering one side of a comparison**: the tie's remaining
+  bibliographies become the eligible set, and the null pairs are then counted,
+  and prominence-matched, inside that same set. Filtering only the tie would
+  compare authors who lost most of their chances against authors who lost none
+  — on the corpus this was written for, 485 of 564 co-cited authors wrote none
+  of the bibliographies at all, while one end of a tie wrote every bibliography
+  that cited them. That comparison is not conservative, it is wrong.
+- Combined inference needs independent p-values. :func:`fisher_combined_p` is
+  retained as an assumption-bound diagnostic, but supervision ties that share
+  people are dependent, so it is not confirmatory evidence for overlapping ties.
+
+Nothing here is Gemini- or provider-specific: it reads the finished tables.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+import pandas as pd
+
+from citegraph.graph import CitationGraph, author_mentions
+
+__all__ = [
+    "TieCocitation",
+    "SkippedTie",
+    "TieCocitationTest",
+    "tie_cocitation_test",
+    "fisher_combined_p",
+]
+
+#: Columns of :meth:`TieCocitationTest.to_frame`, in order.
+TIE_COLUMNS = [
+    "source",
+    "target",
+    "source_name",
+    "target_name",
+    "observed",
+    "null_median",
+    "null_mean",
+    "p_value",
+    "pool_size",
+    "n_eligible",
+    "n_draws",
+]
+
+
+@dataclass(frozen=True)
+class TieCocitation:
+    """One tie scored against its degree-matched null.
+
+    ``observed`` is the number of eligible bibliographies citing both ends.
+    ``null_median`` / ``null_mean`` summarise the same count over pairs drawn
+    from the two ends' prominence strata, and ``p_value`` is the share of those
+    draws reaching ``observed`` — counting the observation itself, so it can
+    never be reported as zero. ``pool_size`` is the smaller of the two strata:
+    a tie scored against a handful of comparable authors carries a p-value with
+    very few distinct values, whatever the draw count says.
+
+    ``n_eligible`` is how many bibliographies the tie was scored over. It
+    equals the corpus total unless self-citations were excluded, and then it is
+    the number that remained — the honest denominator, and the thing to look at
+    before reading anything into a tie that came out at zero.
+    """
+
+    source: str
+    target: str
+    source_name: str
+    target_name: str
+    observed: int
+    null_median: float
+    null_mean: float
+    p_value: float
+    pool_size: int
+    n_eligible: int
+    n_draws: int
+
+
+@dataclass(frozen=True)
+class SkippedTie:
+    """A tie the data cannot carry, kept so a caller can report the shortfall."""
+
+    source: str
+    target: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class TieCocitationTest:
+    """Every tie that could be scored, every tie that could not, and the totals."""
+
+    ties: tuple[TieCocitation, ...]
+    skipped: tuple[SkippedTie, ...]
+    n_citing_works: int
+    n_network_authors: int
+    n_draws: int
+    alpha: float
+    exclude_self_citations: bool
+
+    @property
+    def n_ties(self) -> int:
+        return len(self.ties)
+
+    @property
+    def n_significant(self) -> int:
+        """Ties whose own permutation p-value falls below ``alpha``."""
+        return sum(1 for tie in self.ties if tie.p_value < self.alpha)
+
+    @property
+    def expected_significant(self) -> float:
+        """How many of that count chance alone would be expected to produce."""
+        return self.alpha * self.n_ties
+
+    @property
+    def fisher_p_value(self) -> float | None:
+        """Fisher's combination of the per-tie p-values.
+
+        This is only interpretable when the supplied ties are independent.
+        Overlapping supervision ties violate that assumption, so callers must
+        treat this as a diagnostic rather than confirmatory evidence.
+        """
+        return fisher_combined_p([tie.p_value for tie in self.ties])
+
+    def to_frame(self) -> pd.DataFrame:
+        """One row per scored tie, in the order the ties were supplied."""
+        if not self.ties:
+            return pd.DataFrame(columns=TIE_COLUMNS)
+        return pd.DataFrame(
+            [{column: getattr(tie, column) for column in TIE_COLUMNS} for tie in self.ties]
+        )
+
+
+def tie_cocitation_test(
+    graph: CitationGraph,
+    ties: Iterable[tuple[str, str]],
+    *,
+    min_papers: int = 3,
+    n_draws: int = 2000,
+    degree_tolerance: float = 0.2,
+    exclude_self_citations: bool = False,
+    alpha: float = 0.05,
+    seed: int = 0,
+) -> TieCocitationTest:
+    """Score each ``(source, target)`` author pair against a degree-matched null.
+
+    ``min_papers`` is the co-citation network's inclusion threshold and must
+    match the network a companion figure draws, or the test and the picture
+    describe different populations. ``degree_tolerance`` is the half-width of
+    the prominence stratum a substitute is drawn from, as a fraction of the
+    replaced author's citing-bibliography count, with a floor of one
+    bibliography — at a threshold of three, a 20% band would otherwise admit
+    only exact matches.
+
+    Each tie seeds its own generator from its own identity, so the numbers a
+    tie gets do not depend on where it sat in ``ties`` or on how many ties came
+    with it. A pair given twice, or given both ways round, is scored once.
+    """
+    graph._require_authors()
+    if n_draws < 1:
+        raise ValueError(f"n_draws must be at least 1, got {n_draws}")
+    if not 0 < alpha < 1:
+        raise ValueError(f"alpha must lie in (0, 1), got {alpha}")
+
+    mentions = author_mentions(graph.edges, graph.author_citations, min_papers=min_papers)
+    cited_by: dict[str, frozenset[str]] = {
+        author: frozenset(group)
+        for author, group in mentions.groupby("author_id")["citing_id"]
+    }
+    universe = sorted(cited_by)
+
+    citing_works = set(graph.edges["citing_id"].unique())
+    wrote = graph.author_citations[graph.author_citations["record_id"].isin(citing_works)]
+    authored_by: dict[str, frozenset[str]] = {
+        author: frozenset(group) for author, group in wrote.groupby("author_id")["record_id"]
+    }
+    names = graph.authors["display_name"] if "display_name" in graph.authors.columns else None
+
+    def display(author: str) -> str:
+        if names is None:
+            return author
+        return str(names.get(author, author))
+
+    def stratum(
+        author: str, exclude: Sequence[str], local_counts: dict[str, int]
+    ) -> list[str]:
+        width = max(1.0, degree_tolerance * local_counts[author])
+        blocked = set(exclude)
+        return [
+            other
+            for other in universe
+            if other not in blocked
+            and abs(local_counts[other] - local_counts[author]) <= width
+        ]
+
+    scored: list[TieCocitation] = []
+    skipped: list[SkippedTie] = []
+    seen: set[frozenset[str]] = set()
+
+    for source, target in ties:
+        if source == target:
+            skipped.append(SkippedTie(source, target, "both ends are the same author"))
+            continue
+        key = frozenset((source, target))
+        if key in seen:
+            continue
+        missing = [end for end in (source, target) if end not in cited_by]
+        if missing:
+            skipped.append(
+                SkippedTie(
+                    source,
+                    target,
+                    f"not in the co-citation network at min_papers={min_papers}: "
+                    + ", ".join(missing),
+                )
+            )
+            continue
+        seen.add(key)
+
+        # The eligible bibliographies are this tie's universe. Every count
+        # below — the tie's, the strata's, the null draws' — is taken inside
+        # it, so the tie and its comparison pairs had the same chances.
+        if exclude_self_citations:
+            eligible = (
+                citing_works
+                - authored_by.get(source, frozenset())
+                - authored_by.get(target, frozenset())
+            )
+            local_cited = {author: works & eligible for author, works in cited_by.items()}
+        else:
+            eligible = citing_works
+            local_cited = cited_by
+        local_counts = {author: len(works) for author, works in local_cited.items()}
+
+        def shared(first: str, second: str, _cited: dict[str, frozenset[str]] = local_cited) -> int:
+            return len(_cited[first] & _cited[second])
+
+        source_pool = stratum(source, (source, target), local_counts)
+        target_pool = stratum(target, (source, target), local_counts)
+        empty_ends = [
+            author
+            for author, pool in ((source, source_pool), (target, target_pool))
+            if not pool
+        ]
+        if empty_ends:
+            skipped.append(
+                SkippedTie(
+                    source,
+                    target,
+                    "no degree-matched substitute for: " + ", ".join(empty_ends),
+                )
+            )
+            continue
+        if len(set(source_pool) | set(target_pool)) < 2:
+            skipped.append(
+                SkippedTie(source, target, "no comparable pair of authors to draw a null from")
+            )
+            continue
+
+        observed = shared(source, target)
+        low, high = sorted((source, target))
+        rng = random.Random(f"{seed}|{low}|{high}")
+        draws: list[int] = []
+        # Two draws can collide on one author; redraw rather than score a
+        # self-pair, and cap the attempts so a degenerate stratum cannot spin.
+        attempts = 0
+        while len(draws) < n_draws and attempts < n_draws * 20:
+            attempts += 1
+            first = rng.choice(source_pool)
+            second = rng.choice(target_pool)
+            if first == second:
+                continue
+            draws.append(shared(first, second))
+        if not draws:  # pragma: no cover - guarded by the stratum size check
+            skipped.append(SkippedTie(source, target, "null sampling produced no valid pair"))
+            continue
+
+        at_least = sum(1 for value in draws if value >= observed)
+        scored.append(
+            TieCocitation(
+                source=source,
+                target=target,
+                source_name=display(source),
+                target_name=display(target),
+                observed=observed,
+                null_median=float(_median(draws)),
+                null_mean=float(sum(draws) / len(draws)),
+                p_value=(1 + at_least) / (1 + len(draws)),
+                pool_size=min(len(source_pool), len(target_pool)),
+                n_eligible=len(eligible),
+                n_draws=len(draws),
+            )
+        )
+
+    return TieCocitationTest(
+        ties=tuple(scored),
+        skipped=tuple(skipped),
+        n_citing_works=len(citing_works),
+        n_network_authors=len(universe),
+        n_draws=n_draws,
+        alpha=alpha,
+        exclude_self_citations=exclude_self_citations,
+    )
+
+
+def _median(values: Sequence[float]) -> float:
+    ordered = sorted(values)
+    middle = len(ordered) // 2
+    if len(ordered) % 2:
+        return float(ordered[middle])
+    return (ordered[middle - 1] + ordered[middle]) / 2
+
+
+# ----------------------------------------------------------------------
+# Combination statistic
+# ----------------------------------------------------------------------
+def fisher_combined_p(pvalues: Iterable[float]) -> float | None:
+    """Combine independent p-values by Fisher's method.
+
+    ``-2 * sum(log p)`` is chi-squared on twice as many degrees of freedom.
+    The degrees of freedom are always even, so the survival function has the
+    closed form used here and no SciPy dependency is needed for it.
+
+    Returns ``None`` for an empty input. **The independence assumption is
+    real**: supervision ties that share an advisor are not independent, and
+    this will overstate the evidence for them.
+    """
+    values = [float(p) for p in pvalues]
+    if not values:
+        return None
+    for value in values:
+        if not 0.0 <= value <= 1.0:
+            raise ValueError(f"p-values must be between 0 and 1, got {value}")
+    if any(value == 0.0 for value in values):
+        return 0.0
+    statistic = -2.0 * sum(math.log(value) for value in values)
+    return _chi2_sf_even(statistic, 2 * len(values))
+
+
+def _chi2_sf_even(statistic: float, df: int) -> float:
+    """``P(X > statistic)`` for chi-squared with an even number of df, exactly."""
+    half = statistic / 2.0
+    term = 1.0
+    total = 1.0
+    for i in range(1, df // 2):
+        term *= half / i
+        total += term
+    return math.exp(-half) * total

citegraph/config.py

@@ -0,0 +1,73 @@
+"""Runtime configuration for citegraph.
+
+Reads from environment variables and an optional ``.env`` file via
+``pydantic-settings``. No file paths or secrets should be hardcoded
+elsewhere in the package.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Global, environment-driven settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_prefix="",
+        extra="ignore",
+    )
+
+    google_api_key: str | None = Field(
+        default=None,
+        validation_alias="GOOGLE_API_KEY",
+        description="API key for the Google Gemini API.",
+    )
+    openalex_api_key: str | None = Field(
+        default=None,
+        validation_alias="OPENALEX_API_KEY",
+        description="API key for the OpenAlex API (raises the daily credit budget).",
+    )
+    citegraph_model: str = Field(
+        default="gemini-3.1-flash-lite",
+        validation_alias="CITEGRAPH_MODEL",
+        description="Default Gemini model identifier.",
+    )
+    citegraph_max_output_tokens: int = Field(
+        default=40_000,
+        validation_alias="CITEGRAPH_MAX_OUTPUT_TOKENS",
+    )
+    citegraph_request_timeout_s: float = Field(
+        default=120.0,
+        validation_alias="CITEGRAPH_REQUEST_TIMEOUT_S",
+    )
+    citegraph_llm_concurrency: int = Field(
+        default=4,
+        ge=1,
+        validation_alias="CITEGRAPH_LLM_CONCURRENCY",
+        description="Maximum concurrent LLM extraction calls.",
+    )
+
+    def require_api_key(self) -> str:
+        """Return the Gemini API key or raise a helpful error."""
+        if not self.google_api_key:
+            raise RuntimeError(
+                "GOOGLE_API_KEY is not set. Export it in your environment or "
+                "place it in a .env file in your working directory."
+            )
+        return self.google_api_key
+
+
+def get_settings() -> Settings:
+    """Load settings (cheap; safe to call repeatedly)."""
+    return Settings()
+
+
+def default_out_dir() -> Path:
+    """Default output directory used when the caller doesn't specify one."""
+    return Path.cwd() / "out"

citegraph/cost_estimation.py

@@ -0,0 +1,259 @@
+"""Pre-flight cost estimation for the LLM extraction stages.
+
+Reads the on-disk markdown files (stage-1 output) and estimates Gemini token
+usage for stages 2 (metadata) and 3 (references) before making any API calls.
+Already-cached files are excluded from the estimate.
+
+Library usage::
+
+    pipeline = Pipeline(pdf_dir=..., out_dir=...)
+    estimate = pipeline.estimate_extraction_cost()
+    print(estimate.format_summary())
+
+CLI usage::
+
+    citegraph estimate --out ./out
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+from citegraph.extract_metadata import DEFAULT_METADATA_INPUT_CHARS
+from citegraph.extract_references import slice_to_references_section
+from citegraph.io import OutLayout, read_pydantic_cache
+from citegraph.schemas import PaperMetadata, Reference
+
+# Rough heuristic: English/academic prose averages ~4 characters per token.
+_CHARS_PER_TOKEN: int = 4
+
+# Static prompt overhead per call (template chars + system instruction chars).
+# Measured from the actual prompt strings in extract_metadata.py / extract_references.py.
+_METADATA_OVERHEAD_CHARS: int = 560
+_REFERENCES_OVERHEAD_CHARS: int = 1_060
+
+# Output-token constants for cost projection.
+_METADATA_OUTPUT_TOKENS: int = 300   # PaperMetadata JSON is small and bounded
+_TOKENS_PER_REFERENCE: int = 75      # one Reference JSON object
+_CHARS_PER_REFERENCE_APPROX: int = 175  # typical reference length in source text
+
+# Pricing table: (input USD / 1M tokens, output USD / 1M tokens).
+# Approximate standard paid-tier rates as of 2026-09-04 — check
+# https://ai.google.dev/gemini-api/docs/pricing for
+# current numbers before trusting these for budget planning.
+_PRICING: dict[str, tuple[float, float]] = {
+    "gemini-2.5-pro-preview":   (1.25, 10.00),
+    "gemini-2.5-flash-preview": (0.15,  0.60),
+    "gemini-2.5-flash":         (0.15,  0.60),
+    "gemini-2.0-flash":         (0.10,  0.40),
+    "gemini-2.0-flash-lite":    (0.075, 0.30),
+    "gemini-1.5-pro":           (1.25,  5.00),
+    "gemini-1.5-flash":         (0.075, 0.30),
+    "gemini-1.5-flash-lite":    (0.075, 0.30),
+    "gemini-3.1-flash-lite":    (0.25,  1.50),
+}
+
+
+def _chars_to_tokens(n: int) -> int:
+    return math.ceil(n / _CHARS_PER_TOKEN)
+
+
+@dataclass
+class FileEstimate:
+    """Per-file breakdown of estimated token usage."""
+
+    name: str
+    metadata_cached: bool
+    references_cached: bool
+    metadata_input_tokens: int    # 0 when cached
+    references_input_tokens: int  # 0 when cached
+    estimated_n_references: int   # 0 when cached
+
+
+@dataclass
+class ExtractionEstimate:
+    """Aggregate token and cost estimate for LLM extraction stages 2 and 3."""
+
+    model: str
+    files: list[FileEstimate] = field(default_factory=list)
+
+    @property
+    def n_files(self) -> int:
+        return len(self.files)
+
+    @property
+    def n_metadata_to_process(self) -> int:
+        return sum(1 for f in self.files if not f.metadata_cached)
+
+    @property
+    def n_references_to_process(self) -> int:
+        return sum(1 for f in self.files if not f.references_cached)
+
+    @property
+    def total_input_tokens(self) -> int:
+        return sum(f.metadata_input_tokens + f.references_input_tokens for f in self.files)
+
+    @property
+    def estimated_output_tokens(self) -> int:
+        meta_out = self.n_metadata_to_process * _METADATA_OUTPUT_TOKENS
+        refs_out = sum(
+            f.estimated_n_references * _TOKENS_PER_REFERENCE
+            for f in self.files
+            if not f.references_cached
+        )
+        return meta_out + refs_out
+
+    def cost_usd(self) -> tuple[float, float] | None:
+        """Return ``(input_cost_usd, output_cost_usd)``, or ``None`` for unknown models."""
+        pricing = _PRICING.get(self.model)
+        if pricing is None:
+            return None
+        in_price, out_price = pricing
+        return (
+            self.total_input_tokens * in_price / 1_000_000,
+            self.estimated_output_tokens * out_price / 1_000_000,
+        )
+
+    def format_references_summary(self) -> str:
+        """Return a concise cost summary covering only stage 3 (references extraction)."""
+        n_cached = self.n_files - self.n_references_to_process
+        cached_str = f"  ({n_cached} cached)" if n_cached else ""
+
+        refs_input = sum(f.references_input_tokens for f in self.files)
+        refs_output = sum(
+            f.estimated_n_references * _TOKENS_PER_REFERENCE
+            for f in self.files
+            if not f.references_cached
+        )
+
+        lines = [
+            f"Model:                 {self.model}",
+            f"Files to process:      {self.n_references_to_process}{cached_str}",
+            f"Est. input tokens:     ~{refs_input:,}",
+            f"Est. output tokens:    ~{refs_output:,}",
+        ]
+
+        pricing = _PRICING.get(self.model)
+        if pricing is not None:
+            in_price, out_price = pricing
+            in_cost = refs_input * in_price / 1_000_000
+            out_cost = refs_output * out_price / 1_000_000
+            lines.append(
+                f"Est. cost:             ~${in_cost:.4f} input"
+                f" + ~${out_cost:.4f} output"
+                f" = ~${in_cost + out_cost:.4f} total"
+            )
+        else:
+            lines.append(
+                f"Est. cost:             unknown (no pricing data for '{self.model}')"
+            )
+        lines.append("(Estimates are approximate; actual cost depends on response length.)")
+        return "\n".join(lines)
+
+    def format_summary(self) -> str:
+        """Return a multi-line human-readable cost summary."""
+        n_meta_cached = self.n_files - self.n_metadata_to_process
+        n_refs_cached = self.n_files - self.n_references_to_process
+
+        def _cached(n: int) -> str:
+            return f"  ({n} cached)" if n else ""
+
+        lines = [
+            f"Model:                 {self.model}",
+            f"Files found:           {self.n_files}",
+            f"Metadata to process:   {self.n_metadata_to_process}{_cached(n_meta_cached)}",
+            f"References to process: {self.n_references_to_process}{_cached(n_refs_cached)}",
+            f"Est. input tokens:     ~{self.total_input_tokens:,}",
+            f"Est. output tokens:    ~{self.estimated_output_tokens:,}",
+        ]
+
+        cost = self.cost_usd()
+        if cost is not None:
+            in_c, out_c = cost
+            lines.append(
+                f"Est. cost:             ~${in_c:.4f} input"
+                f" + ~${out_c:.4f} output"
+                f" = ~${in_c + out_c:.4f} total"
+            )
+        else:
+            lines.append(
+                f"Est. cost:             unknown (no pricing data for '{self.model}')"
+            )
+        lines.append("(Estimates are approximate; actual cost depends on response length.)")
+        return "\n".join(lines)
+
+
+def estimate_extraction_cost(
+    layout: OutLayout,
+    model: str,
+    max_input_chars_metadata: int = DEFAULT_METADATA_INPUT_CHARS,
+) -> ExtractionEstimate:
+    """Estimate LLM token usage for stages 2 and 3 without making any API calls.
+
+    Reads markdown files from ``layout.markdown_dir`` and skips files whose
+    metadata / references caches already exist.
+
+    Raises :class:`~citegraph.pipeline.StageNotReadyError` when no markdown
+    files are found (stage 1 must run first).
+    """
+    from citegraph.pipeline import StageNotReadyError, extraction_recipe
+
+    md_paths = layout.markdown_inputs()
+    if not md_paths:
+        raise StageNotReadyError(
+            f"No markdown files found in {layout.markdown_dir}. "
+            "Run `citegraph convert <pdf_dir>` first."
+        )
+
+    file_estimates: list[FileEstimate] = []
+    metadata_recipe = extraction_recipe(model)
+    metadata_recipe['max_input_chars'] = max_input_chars_metadata
+    references_recipe = extraction_recipe(model, references=True)
+    for md in md_paths:
+        metadata_cache = layout.metadata_dir / f"{md.stem}.json"
+        references_cache = layout.references_dir / f"{md.stem}.json"
+        meta_cached = read_pydantic_cache(metadata_cache, md, PaperMetadata, recipe=metadata_recipe) is not None
+        refs_cached = read_pydantic_cache(references_cache, md, Reference, many=True, recipe=references_recipe) is not None
+
+        if meta_cached and refs_cached:
+            file_estimates.append(
+                FileEstimate(
+                    name=md.name,
+                    metadata_cached=True,
+                    references_cached=True,
+                    metadata_input_tokens=0,
+                    references_input_tokens=0,
+                    estimated_n_references=0,
+                )
+            )
+            continue
+
+        content = md.read_text(encoding="utf-8")
+
+        if meta_cached:
+            meta_tokens = 0
+        else:
+            capped = min(len(content), max_input_chars_metadata) if max_input_chars_metadata else len(content)
+            meta_tokens = _chars_to_tokens(capped + _METADATA_OVERHEAD_CHARS)
+
+        if refs_cached:
+            refs_tokens = 0
+            est_n_refs = 0
+        else:
+            sliced, _ = slice_to_references_section(content)
+            refs_tokens = _chars_to_tokens(len(sliced) + _REFERENCES_OVERHEAD_CHARS)
+            est_n_refs = max(1, len(sliced) // _CHARS_PER_REFERENCE_APPROX)
+
+        file_estimates.append(
+            FileEstimate(
+                name=md.name,
+                metadata_cached=meta_cached,
+                references_cached=refs_cached,
+                metadata_input_tokens=meta_tokens,
+                references_input_tokens=refs_tokens,
+                estimated_n_references=est_n_refs,
+            )
+        )
+
+    return ExtractionEstimate(model=model, files=file_estimates)