openai-gabriel 1.0.1__py3-none-any.whl

gabriel/prompts/snippets.jinja2

@@ -0,0 +1,117 @@
+{% macro single_entry(modality, text) %}
+{% if modality == "text" %}
+BEGIN TEXT ENTRY
+{{ text }}
+END TEXT ENTRY
+Read entire text content carefully—start, middle, end. Do not skim; comprehend whole text deeply, including subtleties buried deep in the content.
+{% elif modality == "image" %}
+Carefully consider and analyze the provided image content. Comprehend it fully, both big picture and relevant subtleties.
+{% elif modality == "audio" %}
+Carefully consider and analyze the provided audio content. Comprehend it fully, both big picture and relevant subtleties. Pay close attention to both the content as well as the tone/style of the audio, and the sonic qualities of the content's presentation.
+{% elif modality == "pdf" %}
+Carefully consider and analyze the provided PDF content. Comprehend it fully, both big picture and relevant subtleties across the entire document.
+{% elif modality == "entity" %}
+Entity: {{ text }}
+Use your prodigious internal knowledge on the item/entity "{{ text }}".
+Comprehensively consider every relevant detail, both big picture and subtleties.
+Consider "{{ text }}" as the content to be analyzed.
+{% elif modality == "web" %}
+Entity: {{ text }}
+Comprehensively explore the web for all relevant information on the item/entity "{{ text }}".
+Ensure you collect a highly truthful, accurate, comprehensive, and representative picture of "{{ text }}" from the web.
+Consider "{{ text }}" as the content to be analyzed, fully grounded in the info you find on the web.
+Thoroughly research "{{ text }}" on the web; creatively use different search approaches; gather as much info as possible to deeply characterize the relevant aspects of "{{ text }}".
+Crucial: ONLY use the direct info you find on the web to perform your analysis. Collect the info then dispassionately analyze it with no preconceived notions.
+{% endif %}
+{% endmacro %}
+
+{% macro pair_entries(modality, entry_square, entry_circle, circle_first=False) %}
+{% if modality == "text" %}
+Consider the following two distinct text entries:
+{% if circle_first %}
+BEGIN ENTRY CIRCLE
+{{ entry_circle }}
+END ENTRY CIRCLE
+Above entry ("circle") is distinct from below entry ("square").
+BEGIN ENTRY SQUARE
+{{ entry_square }}
+END ENTRY SQUARE
+{% else %}
+BEGIN ENTRY SQUARE
+{{ entry_square }}
+END ENTRY SQUARE
+Above entry ("square") is distinct from below entry ("circle").
+BEGIN ENTRY CIRCLE
+{{ entry_circle }}
+END ENTRY CIRCLE
+{% endif %}
+
+Read both text entries separately from one another. Process each by itself and fully-start, middle, end.
+Do not skim; comprehend each whole text deeply, including subtleties buried deep in each text entry.
+Understand every nuance before comparing.
+{% elif modality == "image" %}
+{% if circle_first %}
+Two images are provided. **CIRCLE = first image. SQUARE = second image.** Comprehend both fully (overall + fine detail).
+Again, "square" references the second, later image entry; "circle" references the first, earlier image entry.
+Be very clear in your mind that "circle" is the first image and "square" is the second image.
+{% else %}
+Two images are provided. **SQUARE = first image. CIRCLE = second image.** Comprehend both fully (overall + fine detail).
+Again, "circle" references the second, later image entry; "square" references the first, earlier image entry.
+Be very clear in your mind that "square" is the first image and "circle" is the second image.
+{% endif %}
+{% elif modality == "audio" %}
+{% if circle_first %}
+Two audio files are provided. **CIRCLE = first audio recording. SQUARE = second audio recording.** Comprehend both fully (content, style, tone, sonic qualities).
+Again, "square" references the second, later audio entry; "circle" references the first, earlier audio entry.
+Be very clear in your mind that "circle" is the first audio recording and "square" is the second audio recording.
+{% else %}
+Two audio files are provided. **SQUARE = first audio recording. CIRCLE = second audio recording.** Comprehend both fully (content, style, tone, sonic qualities).
+Again, "circle" references the second, later audio entry; "square" references the first, earlier audio entry.
+Be very clear in your mind that "square" is the first audio recording and "circle" is the second audio recording.
+{% endif %}
+{% elif modality == "pdf" %}
+{% if circle_first %}
+Two PDFs are provided. **CIRCLE = first PDF. SQUARE = second PDF.** Comprehend both fully (overall content + fine detail).
+Again, "square" references the second, later PDF entry; "circle" references the first, earlier PDF entry.
+Be very clear in your mind that "circle" is the first PDF and "square" is the second PDF.
+{% else %}
+Two PDFs are provided. **SQUARE = first PDF. CIRCLE = second PDF.** Comprehend both fully (overall content + fine detail).
+Again, "circle" references the second, later PDF entry; "square" references the first, earlier PDF entry.
+Be very clear in your mind that "square" is the first PDF and "circle" is the second PDF.
+{% endif %}
+{% elif modality == "entity" %}
+{% if circle_first %}
+Entity circle: {{ entry_circle }}
+Entity square: {{ entry_square }}
+Use your prodigious internal knowledge on both item/entity square ("{{ entry_square }}") and item/entity circle ("{{ entry_circle }}").
+Comprehensively consider every relevant detail you know about each, both big picture and subtleties.
+Consider "{{ entry_square }}" ("square") and "{{ entry_circle }}" ("circle") as the entries/content to be compared, using your internal knowledge.
+{% else %}
+Entity square: {{ entry_square }}
+Entity circle: {{ entry_circle }}
+Use your prodigious internal knowledge on both item/entity circle ("{{ entry_circle }}") and item/entity square ("{{ entry_square }}").
+Comprehensively consider every relevant detail you know about each, both big picture and subtleties.
+Consider "{{ entry_circle }}" ("circle") and "{{ entry_square }}" ("square") as the entries/content to be compared, using your internal knowledge.
+{% endif %}
+{% elif modality == "web" %}
+{% if circle_first %}
+Entity circle: {{ entry_circle }}
+Entity square: {{ entry_square }}
+Comprehensively explore the web for all relevant information on both item/entity square ("{{ entry_square }}") and item/entity circle ("{{ entry_circle }}").
+Ensure you collect a highly truthful, accurate, comprehensive, and representative picture of each from the web.
+Critical that you search on each entity separately and with equal thoroughness.
+Consider "{{ entry_square }}" ("square") and "{{ entry_circle }}" ("circle") as the entries/content to be compared, fully grounded in the info you find on the web.
+Thoroughly research each entity on the web; creatively use different search approaches; gather as much info as possible to deeply characterize the relevant aspects of both square and circle.
+Crucial: ONLY use the direct info you find on the web to perform your analysis. Collect the info then dispassionately analyze it with no preconceived notions.
+{% else %}
+Entity square: {{ entry_square }}
+Entity circle: {{ entry_circle }}
+Comprehensively explore the web for all relevant information on both item/entity circle ("{{ entry_circle }}") and item/entity square ("{{ entry_square }}").
+Ensure you collect a highly truthful, accurate, comprehensive, and representative picture of each from the web.
+Critical that you search on each entity separately and with equal thoroughness.
+Consider "{{ entry_circle }}" ("circle") and "{{ entry_square }}" ("square") as the entries/content to be compared, fully grounded in the info you find on the web.
+Thoroughly research each entity on the web; creatively use different search approaches; gather as much info as possible to deeply characterize the relevant aspects of both circle and square.
+Crucial: ONLY use the direct info you find on the web to perform your analysis. Collect the info then dispassionately analyze it with no preconceived notions.
+{% endif %}
+{% endif %}
+{% endmacro %}

gabriel/tasks/__init__.py

@@ -0,0 +1,63 @@
+"""Task implementations for GABRIEL."""
+
+from importlib import import_module
+from typing import List
+
+_lazy_imports = {
+    "Rate": ".rate",
+    "RateConfig": ".rate",
+    "Deidentifier": ".deidentify",
+    "DeidentifyConfig": ".deidentify",
+    "EloRater": ".elo",
+    "EloConfig": ".elo",
+    "Classify": ".classify",
+    "ClassifyConfig": ".classify",
+    "Rank": ".rank",
+    "RankConfig": ".rank",
+    "Codify": ".codify",
+    "CodifyConfig": ".codify",
+    "Paraphrase": ".paraphrase",
+    "ParaphraseConfig": ".paraphrase",
+    "Extract": ".extract",
+    "ExtractConfig": ".extract",
+    "Regional": ".regional",
+    "RegionalConfig": ".regional",
+    "CountyCounter": ".county_counter",
+    "Compare": ".compare",
+    "CompareConfig": ".compare",
+    "Merge": ".merge",
+    "MergeConfig": ".merge",
+    "Deduplicate": ".deduplicate",
+    "DeduplicateConfig": ".deduplicate",
+    "Bucket": ".bucket",
+    "BucketConfig": ".bucket",
+    "Discover": ".discover",
+    "DiscoverConfig": ".discover",
+    "Seed": ".seed",
+    "SeedConfig": ".seed",
+    "Filter": ".filter",
+    "FilterConfig": ".filter",
+    "Whatever": ".whatever",
+    "WhateverConfig": ".whatever",
+    "Ideate": ".ideate",
+    "IdeateConfig": ".ideate",
+    "DebiasPipeline": ".debias",
+    "DebiasConfig": ".debias",
+    "DebiasResult": ".debias",
+    "DebiasRegressionResult": ".debias",
+    "MeasurementMode": ".debias",
+    "RemovalMethod": ".debias",
+}
+
+__all__ = list(_lazy_imports.keys())
+
+
+def __getattr__(name: str):
+    if name in _lazy_imports:
+        module = import_module(_lazy_imports[name], __name__)
+        return getattr(module, name)
+    raise AttributeError(name)
+
+
+def __dir__() -> List[str]:
+    return __all__

gabriel/tasks/_attribute_utils.py

@@ -0,0 +1,69 @@
+import json
+import os
+from typing import Any, Dict, Optional
+
+
+def load_persisted_attributes(
+    *,
+    save_dir: str,
+    incoming: Dict[str, Any],
+    reset_files: bool,
+    task_name: str,
+    item_name: str = "attributes",
+    legacy_filename: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Load attributes/labels from disk for reproducibility.
+
+    Preference order:
+    1) ``attributes.json`` in ``save_dir``
+    2) ``legacy_filename`` (e.g., ``ratings_attrs.json``) in ``save_dir``
+    When neither exists, ``incoming`` is written to both paths (when
+    applicable) for future runs.
+    """
+
+    primary_path = os.path.join(save_dir, "attributes.json")
+    legacy_path = os.path.join(save_dir, legacy_filename) if legacy_filename else None
+    candidate_paths = [primary_path] + ([legacy_path] if legacy_path else [])
+
+    if reset_files:
+        for path in candidate_paths:
+            if path and os.path.exists(path):
+                try:
+                    os.remove(path)
+                except Exception:
+                    pass
+
+    loaded: Optional[Dict[str, Any]] = None
+    source_path: Optional[str] = None
+    for path in candidate_paths:
+        if not path or not os.path.exists(path):
+            continue
+        try:
+            with open(path) as f:
+                loaded = json.load(f)
+            source_path = path
+            break
+        except Exception:
+            continue
+
+    if loaded is not None:
+        message = (
+            f"[{task_name}] Found saved {item_name} in {source_path}. Using them for consistency."
+        )
+        if loaded != incoming:
+            message += (
+                f" The provided {item_name} differ; set reset_files=True or use a new save_dir to update them."
+            )
+        print(message)
+        return loaded
+
+    for path in candidate_paths:
+        if not path:
+            continue
+        try:
+            with open(path, "w") as f:
+                json.dump(incoming, f, indent=2)
+        except Exception:
+            pass
+
+    return incoming

gabriel/tasks/bucket.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import random
+import math
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+import pandas as pd
+
+from ..core.prompt_template import PromptTemplate, resolve_template
+from ..utils.openai_utils import get_all_responses
+from ..utils import safest_json
+from ..utils.logging import announce_prompt_rendering
+
+
+@dataclass
+class BucketConfig:
+    """Configuration for :class:`Bucket`."""
+
+    bucket_count: int = 10
+    save_dir: str = "buckets"
+    file_name: str = "bucket_definitions.csv"
+    model: str = "gpt-5-mini"
+    n_parallels: int = 650
+    use_dummy: bool = False
+    max_timeout: Optional[float] = None
+    additional_instructions: Optional[str] = None
+    differentiate: bool = False
+    n_terms_per_prompt: int = 250
+    repeat_bucketing: int = 5
+    repeat_voting: int = 25
+    next_round_frac: float = 0.25
+    top_k_per_round: int = 1
+    raw_term_definitions: bool = True
+    reasoning_effort: Optional[str] = None
+    reasoning_summary: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.additional_instructions is not None:
+            cleaned = str(self.additional_instructions).strip()
+            self.additional_instructions = cleaned or None
+
+
+class Bucket:
+    """Group raw terms into a smaller set of mutually exclusive buckets."""
+
+    def __init__(
+        self,
+        cfg: BucketConfig,
+        template: Optional[PromptTemplate] = None,
+        template_path: Optional[str] = None,
+    ) -> None:
+        expanded = Path(os.path.expandvars(os.path.expanduser(cfg.save_dir)))
+        expanded.mkdir(parents=True, exist_ok=True)
+        cfg.save_dir = str(expanded)
+        self.cfg = cfg
+        self.template = resolve_template(
+            template=template,
+            template_path=template_path,
+            reference_filename="bucket_prompt.jinja2",
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers for persisting intermediate progress
+    # ------------------------------------------------------------------
+    def _state_path(self) -> str:
+        return os.path.join(self.cfg.save_dir, "bucket_state.json")
+
+    def _read_state(self) -> Dict[str, Any]:
+        path = self._state_path()
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            if isinstance(data, dict):
+                return data
+        except FileNotFoundError:
+            return {}
+        except Exception:
+            return {}
+        return {}
+
+    def _write_state(self, state: Dict[str, Any]) -> None:
+        path = self._state_path()
+        payload = dict(state)
+        payload["updated_at"] = datetime.utcnow().isoformat() + "Z"
+        try:
+            with open(path, "w", encoding="utf-8") as fh:
+                json.dump(payload, fh, ensure_ascii=False, indent=2)
+        except Exception:
+            pass
+
+    def _terms_signature(self, terms: List[str], term_map: Dict[str, str]) -> str:
+        if self.cfg.raw_term_definitions:
+            entries = [f"{t}::{term_map.get(t, '')}" for t in sorted(terms)]
+        else:
+            entries = sorted(terms)
+        joined = "||".join(entries)
+        return hashlib.sha1(joined.encode("utf-8")).hexdigest()
+
+    async def _parse(self, raw: Any) -> Dict[str, str]:
+        obj = await safest_json(raw)
+        if isinstance(obj, list) and obj:
+            obj = obj[0]
+        if isinstance(obj, dict):
+            return {str(k): str(v) if v is not None else "" for k, v in obj.items()}
+        return {}
+
+    async def run(
+        self,
+        df: pd.DataFrame,
+        column_name: str,
+        *,
+        reset_files: bool = False,
+        **kwargs: Any,
+    ) -> pd.DataFrame:
+        cache_path = os.path.join(self.cfg.save_dir, self.cfg.file_name)
+        state_path = self._state_path()
+        if reset_files and os.path.exists(state_path):
+            try:
+                os.remove(state_path)
+            except Exception:
+                pass
+        if not reset_files and os.path.exists(cache_path):
+            try:
+                cached = pd.read_csv(cache_path)
+                if {"bucket", "definition"}.issubset(cached.columns):
+                    cols = ["bucket", "definition"]
+                    return cached[cols]
+            except Exception:
+                pass
+
+        state: Dict[str, Any] = {} if reset_files else self._read_state()
+
+        df_proc = df.reset_index(drop=True).copy()
+        raw_entries = df_proc[column_name].dropna().tolist()
+
+        seen: Set[str] = set()
+        terms: List[str] = []
+        term_map: Dict[str, str] = {}
+        for entry in raw_entries:
+            if isinstance(entry, dict):
+                for k, v in entry.items():
+                    key = str(k)
+                    if key not in seen:
+                        seen.add(key)
+                        terms.append(key)
+                    term_map.setdefault(key, str(v) if v is not None else "")
+            elif isinstance(entry, list):
+                for item in entry:
+                    key = str(item)
+                    if key not in seen:
+                        seen.add(key)
+                        terms.append(key)
+                    term_map.setdefault(key, "")
+            else:
+                key = str(entry)
+                if key not in seen:
+                    seen.add(key)
+                    terms.append(key)
+                term_map.setdefault(key, "")
+
+        if not terms:
+            return pd.DataFrame(columns=["bucket", "definition"])
+
+        signature = self._terms_signature(terms, term_map)
+        if state.get("terms_signature") != signature:
+            state = {"terms_signature": signature}
+        else:
+            state["terms_signature"] = signature
+
+        def persist_state() -> None:
+            self._write_state(state)
+
+        if state.get("finalized") and state.get("final_buckets") is not None:
+            records = state.get("final_buckets") or []
+            final_df = pd.DataFrame(records)
+            if not final_df.empty and not {"bucket", "definition"}.issubset(final_df.columns):
+                final_df = final_df.rename(columns={0: "bucket", 1: "definition"})
+            if not final_df.empty and not os.path.exists(cache_path):
+                try:
+                    final_df.to_csv(cache_path, index=False)
+                except Exception:
+                    pass
+            if not final_df.empty:
+                cols = ["bucket", "definition"]
+                return final_df[cols]
+            return pd.DataFrame(columns=["bucket", "definition"])
+
+        # ── 1: generate bucket candidates ───────────────────────────────
+        candidate_defs: Dict[str, str] = {}
+        candidates: List[str] = []
+        if state.get("candidate_defs") and isinstance(state["candidate_defs"], dict):
+            cached_defs = {
+                str(k): str(v) if v is not None else ""
+                for k, v in state["candidate_defs"].items()
+            }
+            candidate_defs.update(cached_defs)
+            candidates = [
+                c
+                for c in state.get("candidates", list(candidate_defs.keys()))
+                if c in candidate_defs
+            ]
+        if not candidate_defs:
+            prompts: List[str] = []
+            ids: List[str] = []
+            chunks_per_rep = max(
+                1, math.ceil(len(terms) / self.cfg.n_terms_per_prompt)
+            )
+            announce_prompt_rendering(
+                "Bucket:generate",
+                chunks_per_rep * self.cfg.repeat_bucketing,
+            )
+            for rep in range(self.cfg.repeat_bucketing):
+                random.shuffle(terms)
+                chunks = [
+                    terms[i : i + self.cfg.n_terms_per_prompt]
+                    for i in range(0, len(terms), self.cfg.n_terms_per_prompt)
+                ]
+                for ci, chunk in enumerate(chunks):
+                    chunk_data = (
+                        {t: term_map.get(t, "") for t in chunk}
+                        if self.cfg.raw_term_definitions
+                        else chunk
+                    )
+                    prompts.append(
+                        self.template.render(
+                            terms=chunk_data,
+                            bucket_count=self.cfg.bucket_count,
+                            differentiate=self.cfg.differentiate,
+                            additional_instructions=self.cfg.additional_instructions or "",
+                            voting=False,
+                        )
+                    )
+                    ids.append(f"gen|{rep}|{ci}")
+
+            gen_df = await get_all_responses(
+                prompts=prompts,
+                identifiers=ids,
+                n_parallels=self.cfg.n_parallels,
+                model=self.cfg.model,
+                save_path=os.path.join(self.cfg.save_dir, "bucket_generation.csv"),
+                use_dummy=self.cfg.use_dummy,
+                max_timeout=self.cfg.max_timeout,
+                json_mode=True,
+                reset_files=reset_files,
+                reasoning_effort=self.cfg.reasoning_effort,
+                reasoning_summary=self.cfg.reasoning_summary,
+                **kwargs,
+            )
+            if not isinstance(gen_df, pd.DataFrame):
+                raise RuntimeError("get_all_responses returned no DataFrame")
+
+            resp_map = dict(zip(gen_df.Identifier, gen_df.Response))
+            parsed = await asyncio.gather(*[self._parse(resp_map.get(i, "")) for i in ids])
+            for res in parsed:
+                for b, j in res.items():
+                    candidate_defs.setdefault(b, j)
+
+            candidates = list(candidate_defs.keys())
+            state["candidate_defs"] = candidate_defs
+            state["candidates"] = candidates
+            state["stage"] = "candidates"
+            persist_state()
+        elif not candidates:
+            candidates = list(candidate_defs.keys())
+
+        # helper to build voting prompts
+        def _vote_prompts(opts: List[str], selected: List[str], tag: str):
+            pr: List[str] = []
+            idn: List[str] = []
+            chunks_per_rep = max(
+                1, math.ceil(len(opts) / self.cfg.n_terms_per_prompt)
+            )
+            announce_prompt_rendering(
+                f"Bucket:{tag}",
+                chunks_per_rep * self.cfg.repeat_voting,
+            )
+            for rep in range(self.cfg.repeat_voting):
+                random.shuffle(opts)
+                chunks = [
+                    opts[i : i + self.cfg.n_terms_per_prompt]
+                    for i in range(0, len(opts), self.cfg.n_terms_per_prompt)
+                ]
+                for ci, ch in enumerate(chunks):
+                    sample_list = random.sample(
+                        terms, min(len(terms), self.cfg.n_terms_per_prompt)
+                    )
+                    sample_terms = (
+                        {t: term_map.get(t, "") for t in sample_list}
+                        if self.cfg.raw_term_definitions
+                        else sample_list
+                    )
+                    selected_map = {
+                        b: candidate_defs.get(b, "") for b in selected
+                    }
+                    pr.append(
+                        self.template.render(
+                            terms=sample_terms,
+                            bucket_count=self.cfg.bucket_count,
+                            differentiate=self.cfg.differentiate,
+                            additional_instructions=self.cfg.additional_instructions
+                            or "",
+                            voting=True,
+                            bucket_candidates=ch,
+                            selected_buckets=selected_map if selected_map else None,
+                        )
+                    )
+                    idn.append(f"vote|{tag}|{rep}|{ci}")
+            return pr, idn
+
+        # ── 2: iterative reduction ─────────────────────────────────────
+        current = candidates[:]
+        if state.get("current_candidates"):
+            saved_current = [
+                c for c in state["current_candidates"] if c in candidate_defs
+            ]
+            if saved_current:
+                current = saved_current
+        round_idx = int(state.get("reduce_round", 0))
+        while len(current) >= 3 * self.cfg.bucket_count:
+            round_idx += 1
+            pr, idn = _vote_prompts(current, [], f"reduce{round_idx}")
+            vote_df = await get_all_responses(
+                prompts=pr,
+                identifiers=idn,
+                n_parallels=self.cfg.n_parallels,
+                model=self.cfg.model,
+                save_path=os.path.join(
+                    self.cfg.save_dir, f"vote_reduce{round_idx}.csv"
+                ),
+                use_dummy=self.cfg.use_dummy,
+                max_timeout=self.cfg.max_timeout,
+                json_mode=True,
+                reset_files=reset_files,
+                reasoning_effort=self.cfg.reasoning_effort,
+                reasoning_summary=self.cfg.reasoning_summary,
+                **kwargs,
+            )
+            vote_map = dict(zip(vote_df.Identifier, vote_df.Response))
+            parsed_votes = await asyncio.gather(
+                *[self._parse(vote_map.get(i, "")) for i in idn]
+            )
+            tallies: Dict[str, int] = defaultdict(int)
+            for res in parsed_votes:
+                for b in res.keys():
+                    tallies[b] += 1
+            current.sort(
+                key=lambda x: (tallies.get(x, 0), random.random()), reverse=True
+            )
+            keep = max(
+                self.cfg.bucket_count, int(len(current) * self.cfg.next_round_frac)
+            )
+            current = current[:keep]
+            state["current_candidates"] = current
+            state["reduce_round"] = round_idx
+            state["stage"] = "reduce"
+            persist_state()
+
+        # ── 3: final selection ─────────────────────────────────────────
+        selected: List[str] = [
+            c for c in state.get("selected", []) if c in candidate_defs
+        ]
+        remaining = [o for o in current if o not in selected]
+        loop_idx = int(state.get("final_loop", 0))
+        while len(selected) < self.cfg.bucket_count and remaining:
+            loop_idx += 1
+            pr, idn = _vote_prompts(
+                [o for o in remaining if o not in selected],
+                selected,
+                f"final{loop_idx}",
+            )
+            vote_df = await get_all_responses(
+                prompts=pr,
+                identifiers=idn,
+                n_parallels=self.cfg.n_parallels,
+                model=self.cfg.model,
+                save_path=os.path.join(
+                    self.cfg.save_dir, f"vote_final{loop_idx}.csv"
+                ),
+                use_dummy=self.cfg.use_dummy,
+                max_timeout=self.cfg.max_timeout,
+                json_mode=True,
+                reset_files=reset_files,
+                reasoning_effort=self.cfg.reasoning_effort,
+                reasoning_summary=self.cfg.reasoning_summary,
+                **kwargs,
+            )
+            vote_map = dict(zip(vote_df.Identifier, vote_df.Response))
+            parsed_votes = await asyncio.gather(
+                *[self._parse(vote_map.get(i, "")) for i in idn]
+            )
+            tallies: Dict[str, int] = defaultdict(int)
+            for res in parsed_votes:
+                for b in res.keys():
+                    if b not in selected:
+                        tallies[b] += 1
+            remaining = [o for o in remaining if o not in selected]
+            remaining.sort(
+                key=lambda x: (tallies.get(x, 0), random.random()), reverse=True
+            )
+            n_pick = min(
+                self.cfg.top_k_per_round,
+                self.cfg.bucket_count - len(selected),
+                len(remaining),
+            )
+            winners = remaining[:n_pick]
+            selected.extend(winners)
+            state["selected"] = selected
+            state["remaining_candidates"] = remaining
+            state["final_loop"] = loop_idx
+            state["stage"] = "finalizing"
+            persist_state()
+
+        bucket_defs = {b: candidate_defs.get(b, "") for b in selected}
+        out_df = pd.DataFrame(
+            {"bucket": list(bucket_defs.keys()), "definition": list(bucket_defs.values())}
+        )
+        out_df.to_csv(
+            os.path.join(self.cfg.save_dir, self.cfg.file_name), index=False
+        )
+        state["final_buckets"] = out_df.to_dict(orient="records")
+        state["finalized"] = True
+        state["stage"] = "complete"
+        persist_state()
+        return out_df