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,30 @@ 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.
+
+> **Note:** Seed behavior depends on the underlying model. Some models (e.g., certain Ollama models) may not fully support deterministic output even with `--seed` set. For guaranteed reproducibility, test with your specific model and endpoint.
+
 ## Usage examples
 
 ### Idea discovery

src/scribae/brief.py

@@ -16,7 +16,7 @@
 from .idea import Idea, IdeaList
 from .io_utils import NoteDetails, load_note
 from .language import LanguageMismatchError, LanguageResolutionError, ensure_language_output, resolve_output_language
-from .llm import LLM_OUTPUT_RETRIES, LLM_TIMEOUT_SECONDS, OpenAISettings, make_model
+from .llm import LLM_OUTPUT_RETRIES, LLM_TIMEOUT_SECONDS, OpenAISettings, apply_optional_settings, make_model
 from .project import ProjectConfig
 from .prompts.brief import SYSTEM_PROMPT, PromptBundle, build_prompt_bundle
 
@@ -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,18 @@ 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)
+    apply_optional_settings(model_settings, top_p=top_p, 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

@@ -19,6 +19,7 @@
     LLM_OUTPUT_RETRIES,
     LLM_TIMEOUT_SECONDS,
     OpenAISettings,
+    apply_optional_settings,
     make_model,
 )
 from .project import ProjectConfig
@@ -88,8 +89,8 @@ class IdeaContext:
 
 
 def prepare_context(
-    note_path: Path,
     *,
+    note_path: Path,
     project: ProjectConfig,
     max_chars: int,
     language: str | None = None,
@@ -146,6 +147,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 +159,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 +228,19 @@ 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)
+    apply_optional_settings(model_settings, top_p=top_p, 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/llm.py

@@ -43,12 +43,30 @@ def make_model(model_name: str, *, model_settings: ModelSettings,
     return OpenAIChatModel(model_name, provider=provider, settings=model_settings)
 
 
+def apply_optional_settings(
+    model_settings: ModelSettings,
+    *,
+    top_p: float | None = None,
+    seed: int | None = None,
+) -> None:
+    """Apply optional sampling parameters to model settings in-place.
+
+    This helper reduces repetitive conditional assignment when configuring
+    `top_p` and `seed` parameters across the codebase.
+    """
+    if top_p is not None:
+        model_settings["top_p"] = top_p
+    if seed is not None:
+        model_settings["seed"] = seed
+
+
 __all__ = [
     "OpenAISettings",
     "DEFAULT_MODEL_NAME",
     "DEFAULT_BASE_URL",
     "DEFAULT_API_KEY",
     "LLM_OUTPUT_RETRIES",
     "LLM_TIMEOUT_SECONDS",
+    "apply_optional_settings",
     "make_model",
 ]

src/scribae/meta.py

@@ -16,7 +16,7 @@
 
 from .brief import SeoBrief
 from .language import LanguageMismatchError, LanguageResolutionError, ensure_language_output, resolve_output_language
-from .llm import LLM_OUTPUT_RETRIES, LLM_TIMEOUT_SECONDS, OpenAISettings, make_model
+from .llm import LLM_OUTPUT_RETRIES, LLM_TIMEOUT_SECONDS, OpenAISettings, apply_optional_settings, make_model
 from .project import ProjectConfig
 from .prompts.meta import (
     META_SYSTEM_PROMPT,
@@ -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,15 @@ 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)
+    apply_optional_settings(model_settings, top_p=top_p, 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,