feat: add --seed and --top-p options for output reproducibility

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `--seed` and `--top-p` CLI options for all LLM commands (`idea`, `brief`, `write`, `meta`) to control output reproducibility
+- `--postedit-seed` and `--postedit-top-p` CLI options for the `translate` command's LLM post-edit pass
+
 ## 0.1.0 - 2025-12-29
 
 ### Added

README.md

@@ -124,6 +124,28 @@ keywords:
   - programming
 ```
 
+### LLM settings
+
+All commands that use LLMs support `--temperature`, `--top-p`, and `--seed` for controlling output variability:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--temperature` | 0.2–0.4 | Sampling temperature. Lower values produce more deterministic output. |
+| `--top-p` | (none) | Nucleus sampling threshold. Set to `1.0` for full distribution. |
+| `--seed` | (none) | Random seed for reproducible outputs. |
+
+For fully deterministic output, set `--temperature 0`. For reproducible creative output, combine `--seed` with `--top-p 1.0`.
+
+```bash
+# Deterministic mode
+scribae brief --note notes.md --temperature 0 --out brief.json
+
+# Reproducible creative mode
+scribae write --note notes.md --brief brief.json --seed 42 --top-p 1.0 --out draft.md
+```
+
+The `translate` command uses `--postedit-temperature`, `--postedit-top-p`, and `--postedit-seed` for the LLM post-edit pass.
+
 ## Usage examples
 
 ### Idea discovery

src/scribae/brief.py

@@ -146,8 +146,8 @@ class BriefingContext:
 
 
 def prepare_context(
-    note_path: Path,
     *,
+    note_path: Path,
     project: ProjectConfig,
     max_chars: int,
     language: str | None = None,
@@ -227,6 +227,8 @@ def generate_brief(
     *,
     model_name: str,
     temperature: float,
+    top_p: float | None = None,
+    seed: int | None = None,
     reporter: Reporter = None,
     settings: OpenAISettings | None = None,
     agent: Agent[None, SeoBrief] | None = None,
@@ -236,7 +238,9 @@ def generate_brief(
     """Run the LLM call and return a validated SeoBrief."""
     resolved_settings = settings or OpenAISettings.from_env()
     llm_agent: Agent[None, SeoBrief] = (
-        _create_agent(model_name, resolved_settings, temperature=temperature) if agent is None else agent
+        _create_agent(model_name, resolved_settings, temperature=temperature, top_p=top_p, seed=seed)
+        if agent is None
+        else agent
     )
 
     _report(
@@ -322,10 +326,21 @@ def save_prompt_artifacts(
     return prompt_path, note_path
 
 
-def _create_agent(model_name: str, settings: OpenAISettings, *, temperature: float) -> Agent[None, SeoBrief]:
+def _create_agent(
+    model_name: str,
+    settings: OpenAISettings,
+    *,
+    temperature: float,
+    top_p: float | None = None,
+    seed: int | None = None,
+) -> Agent[None, SeoBrief]:
     """Instantiate the Pydantic AI agent for generating briefs."""
     settings.configure_environment()
     model_settings = ModelSettings(temperature=temperature)
+    if top_p is not None:
+        model_settings["top_p"] = top_p
+    if seed is not None:
+        model_settings["seed"] = seed
     model = make_model(model_name, model_settings=model_settings, settings=settings)
     return Agent[None, SeoBrief](
         model=model,

src/scribae/brief_cli.py

@@ -135,6 +135,18 @@ def brief_command(
         max=2.0,
         help="Temperature for the LLM request.",
     ),
+    top_p: float | None = typer.Option(  # noqa: B008
+        None,
+        "--top-p",
+        min=0.0,
+        max=1.0,
+        help="Nucleus sampling threshold (1.0 = full distribution). For reproducibility, set to 1.0.",
+    ),
+    seed: int | None = typer.Option(  # noqa: B008
+        None,
+        "--seed",
+        help="Random seed for reproducible outputs. For full determinism, combine with --temperature 0.",
+    ),
     dry_run: bool = typer.Option(  # noqa: B008
         False,
         "--dry-run",
@@ -223,6 +235,8 @@ def brief_command(
                     context,
                     model_name=model,
                     temperature=temperature,
+                    top_p=top_p,
+                    seed=seed,
                     reporter=reporter,
                 )
             except KeyboardInterrupt:
@@ -273,6 +287,8 @@ def brief_command(
             context,
             model_name=model,
             temperature=temperature,
+            top_p=top_p,
+            seed=seed,
             reporter=reporter,
         )
     except KeyboardInterrupt:

src/scribae/idea.py

@@ -88,8 +88,8 @@ class IdeaContext:
 
 
 def prepare_context(
-    note_path: Path,
     *,
+    note_path: Path,
     project: ProjectConfig,
     max_chars: int,
     language: str | None = None,
@@ -146,6 +146,8 @@ def generate_ideas(
     *,
     model_name: str,
     temperature: float,
+    top_p: float | None = None,
+    seed: int | None = None,
     reporter: Reporter = None,
     settings: OpenAISettings | None = None,
     agent: Agent[None, IdeaList] | None = None,
@@ -156,7 +158,9 @@ def generate_ideas(
 
     resolved_settings = settings or OpenAISettings.from_env()
     llm_agent: Agent[None, IdeaList] = (
-        _create_agent(model_name, resolved_settings, temperature=temperature) if agent is None else agent
+        _create_agent(model_name, resolved_settings, temperature=temperature, top_p=top_p, seed=seed)
+        if agent is None
+        else agent
     )
 
     _report(reporter, f"Calling model '{model_name}' via {resolved_settings.base_url}")
@@ -223,11 +227,22 @@ def save_prompt_artifacts(
     return prompt_path, note_path
 
 
-def _create_agent(model_name: str, settings: OpenAISettings, *, temperature: float) -> Agent[None, IdeaList]:
+def _create_agent(
+    model_name: str,
+    settings: OpenAISettings,
+    *,
+    temperature: float,
+    top_p: float | None = None,
+    seed: int | None = None,
+) -> Agent[None, IdeaList]:
     """Instantiate the Pydantic AI agent for generating ideas."""
 
     settings.configure_environment()
     model_settings = ModelSettings(temperature=temperature)
+    if top_p is not None:
+        model_settings["top_p"] = top_p
+    if seed is not None:
+        model_settings["seed"] = seed
     model = make_model(model_name, model_settings=model_settings, settings=settings)
     return Agent[None, IdeaList](
         model=model,

src/scribae/idea_cli.py

@@ -87,6 +87,18 @@ def idea_command(
         max=2.0,
         help="Temperature for the LLM request.",
     ),
+    top_p: float | None = typer.Option(  # noqa: B008
+        None,
+        "--top-p",
+        min=0.0,
+        max=1.0,
+        help="Nucleus sampling threshold (1.0 = full distribution). For reproducibility, set to 1.0.",
+    ),
+    seed: int | None = typer.Option(  # noqa: B008
+        None,
+        "--seed",
+        help="Random seed for reproducible outputs. For full determinism, combine with --temperature 0.",
+    ),
     dry_run: bool = typer.Option(  # noqa: B008
         False,
         "--dry-run",
@@ -165,6 +177,8 @@ def idea_command(
             context,
             model_name=model,
             temperature=temperature,
+            top_p=top_p,
+            seed=seed,
             reporter=reporter,
         )
     except KeyboardInterrupt:

src/scribae/language.py

@@ -93,14 +93,14 @@ def ensure_language_output(
 
     first_result = invoke(prompt)
     try:
-        _validate_language(extract_text(first_result), expected_language, language_detector)
+        _validate_language(extract_text(first_result), expected_language, language_detector=language_detector)
         return first_result
     except LanguageMismatchError as first_error:
         _report(reporter, str(first_error) + " Retrying with language correction.")
 
     corrective_prompt = _append_language_correction(prompt, expected_language)
     second_result = invoke(corrective_prompt)
-    _validate_language(extract_text(second_result), expected_language, language_detector)
+    _validate_language(extract_text(second_result), expected_language, language_detector=language_detector)
     return second_result
 
 
@@ -115,6 +115,7 @@ def _append_language_correction(prompt: str, expected_language: str) -> str:
 def _validate_language(
     text: str,
     expected_language: str,
+    *,
     language_detector: Callable[[str], str] | None = None,
 ) -> None:
     detected = _detect_language(text, language_detector)

src/scribae/meta.py

@@ -228,6 +228,8 @@ def generate_metadata(
     *,
     model_name: str,
     temperature: float,
+    top_p: float | None = None,
+    seed: int | None = None,
     reporter: Reporter = None,
     agent: Agent[None, ArticleMeta] | None = None,
     prompts: PromptBundle | None = None,
@@ -247,7 +249,7 @@ def generate_metadata(
 
     resolved_settings = OpenAISettings.from_env()
     llm_agent: Agent[None, ArticleMeta] = (
-        agent if agent is not None else _create_agent(model_name, temperature)
+        agent if agent is not None else _create_agent(model_name, temperature, top_p=top_p, seed=seed)
     )
 
     _report(
@@ -516,8 +518,18 @@ def _merge_frontmatter(meta: ArticleMeta, original: dict[str, Any], *, overwrite
     return merged
 
 
-def _create_agent(model_name: str, temperature: float) -> Agent[None, ArticleMeta]:
+def _create_agent(
+    model_name: str,
+    temperature: float,
+    *,
+    top_p: float | None = None,
+    seed: int | None = None,
+) -> Agent[None, ArticleMeta]:
     model_settings = ModelSettings(temperature=temperature)
+    if top_p is not None:
+        model_settings["top_p"] = top_p
+    if seed is not None:
+        model_settings["seed"] = seed
     model = make_model(model_name, model_settings=model_settings)
     return Agent[None, ArticleMeta](
         model=model,

src/scribae/meta_cli.py

@@ -83,6 +83,18 @@ def meta_command(
         max=2.0,
         help="Temperature for the LLM request.",
     ),
+    top_p: float | None = typer.Option(  # noqa: B008
+        None,
+        "--top-p",
+        min=0.0,
+        max=1.0,
+        help="Nucleus sampling threshold (1.0 = full distribution). For reproducibility, set to 1.0.",
+    ),
+    seed: int | None = typer.Option(  # noqa: B008
+        None,
+        "--seed",
+        help="Random seed for reproducible outputs. For full determinism, combine with --temperature 0.",
+    ),
     dry_run: bool = typer.Option(  # noqa: B008
         False,
         "--dry-run",
@@ -182,6 +194,8 @@ def meta_command(
             context,
             model_name=model,
             temperature=temperature,
+            top_p=top_p,
+            seed=seed,
             reporter=reporter,
             prompts=prompts,
             force_llm_on_missing=force_llm_on_missing,

src/scribae/translate/postedit.py

@@ -45,6 +45,8 @@ def __init__(
         *,
         model_name: str = DEFAULT_MODEL_NAME,
         temperature: float = 0.2,
+        top_p: float | None = None,
+        seed: int | None = None,
         create_agent: bool = True,
         max_chars: int | None = 4_000,
         timeout_seconds: float | None = 60.0,
@@ -57,7 +59,7 @@ def __init__(
         if agent is not None:
             self.agent = agent
         elif create_agent:
-            self.agent = self._create_agent(model_name, temperature=temperature)
+            self.agent = self._create_agent(model_name, temperature=temperature, top_p=top_p, seed=seed)
 
     def post_edit(
         self,
@@ -437,10 +439,21 @@ def _validate_output(self, text: str, placeholders: Iterable[str], glossary: dic
             elif target not in text:
                 raise PostEditValidationError(f"Glossary target not enforced: {target}")
 
-    def _create_agent(self, model_name: str, *, temperature: float) -> Agent[None, str] | None:
+    def _create_agent(
+        self,
+        model_name: str,
+        *,
+        temperature: float,
+        top_p: float | None = None,
+        seed: int | None = None,
+    ) -> Agent[None, str] | None:
         settings = OpenAISettings.from_env()
         settings.configure_environment()
         model_settings = ModelSettings(temperature=temperature)
+        if top_p is not None:
+            model_settings["top_p"] = top_p
+        if seed is not None:
+            model_settings["seed"] = seed
         model = make_model(model_name, model_settings=model_settings, settings=settings)
         return Agent[None, str](
             model=model,

src/scribae/translate_cli.py

@@ -197,6 +197,20 @@ def translate(
         "--pe-temp",
         help="Temperature for post-edit LLM pass.",
     ),
+    postedit_top_p: float | None = typer.Option(  # noqa: B008
+        None,
+        "--postedit-top-p",
+        "--pe-top-p",
+        min=0.0,
+        max=1.0,
+        help="Nucleus sampling threshold for post-edit (1.0 = full distribution).",
+    ),
+    postedit_seed: int | None = typer.Option(  # noqa: B008
+        None,
+        "--postedit-seed",
+        "--pe-seed",
+        help="Random seed for reproducible post-edit outputs.",
+    ),
     device: str = typer.Option(  # noqa: B008
         "auto",
         "--device",
@@ -276,6 +290,8 @@ def translate(
     posteditor = LLMPostEditor(
         model_name=postedit_model,
         temperature=postedit_temperature,
+        top_p=postedit_top_p,
+        seed=postedit_seed,
         create_agent=postedit,
         max_chars=postedit_max_chars,
     )