Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(generation): enforce documentation completion (#1011)

Austin Traveree54e1737c8e
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 691501214..42d81b889 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -124,6 +124,12 @@ repowise init . --no-prose -x "node_modules/" # workspace, no LLM
repowise init . --no-workspace # force single-repo, even in a workspace root
```
+**Documentation output limit.** Set `max_tokens` in
+`.repowise/config.yaml` to bound each model-written page. It is persistent, not
+a per-run flag, and is honored by `init`, `update`, `generate`, `restyle`,
+workspace generation, and server-triggered generation. See
+[Configuration](CONFIG.md#configyaml).
+
---
### `repowise update [PATH]`
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 5f654556c..1d7bcc614 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -31,11 +31,12 @@ should not be committed; it's a local cache, not a source of truth.
The main configuration file. Created after first `init`, updated when you pass
flags like `--commit-limit`, `--follow-renames`, or `--wiki-style`.
-> **No schema validation.** `config.yaml` is loaded as a plain YAML dict.
+> **Limited schema validation.** `config.yaml` is loaded as a plain YAML dict.
> Unknown or misspelled keys are silently ignored, they won't error and won't
-> take effect. The only part that's validated is the `distill:` block, and
-> only when you run `repowise doctor`. If a setting doesn't seem to be taking
-> effect, check spelling and indentation first.
+> take effect. `max_tokens` must be a positive integer when documentation is
+> generated. The `distill:` block is validated only when you run
+> `repowise doctor`. If a setting doesn't seem to be taking effect, check
+> spelling and indentation first.
```yaml
provider: anthropic # LLM provider (auto-detected if omitted)
@@ -43,6 +44,7 @@ model: claude-sonnet-4-6 # Model identifier (provider default if omi
embedder: mock # Embedding provider (mock if no key detected)
embedding_model: text-embedding-3-small # Embedding model (provider default if omitted)
reasoning: auto # auto | off | none | minimal | low | medium | high | xhigh | max
+max_tokens: 16384 # Max output tokens for each generated documentation page
commit_limit: 500 # Max commits per file for git analysis (clamped 1-10000)
follow_renames: false # Track file renames in git history
wiki_style: comprehensive # comprehensive | caveman | reference | tutorial | custom
@@ -74,6 +76,7 @@ You can edit this file directly. Changes take effect on the next `init`,
| `embedder` | `mock` | `openai`, `gemini`, `ollama`, `openrouter`, `mock` |
| `embedding_model` | provider default | Embedding model identifier |
| `reasoning` | `auto` | `auto`, `off`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `max_tokens` | `16384` | Maximum output tokens requested for each model-written documentation page |
| `commit_limit` | `500` | Max commits per file walked for git analysis, clamped to 1-10000 |
| `follow_renames` | `false` | Track file renames through git history |
| `exclude_patterns` | `[]` | Extra gitignore-style patterns, on top of `.gitignore` |
@@ -96,6 +99,13 @@ example OpenAI reasoning models and OpenRouter's `reasoning.effort`).
Providers or models that cannot translate an explicit mode fail before making
an API call.
+`max_tokens` bounds each model-written documentation response. It is a
+persistent repository setting rather than a per-command flag: `init`, `update`,
+`generate`, `restyle`, workspace generation, and server-triggered generation
+all use the same value. Providers may enforce a lower model limit. If
+generation reaches a token limit before the page is complete, repowise rejects
+the partial page instead of saving it.
+
`wiki_style` controls the voice and density of generated wiki pages. Set it with
`init --wiki-style` or switch later with `repowise restyle <style>` (which also
regenerates the wiki). Power users can define their own style under
diff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/command.py b/packages/cli/src/repowise/cli/commands/generate_cmd/command.py
index f6019cec9..e0e7fbb5b 100644
--- a/packages/cli/src/repowise/cli/commands/generate_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/command.py
@@ -256,7 +256,8 @@ def generate_command(
from repowise.core.generation import GenerationConfig
- config = GenerationConfig(
+ config = GenerationConfig.from_repo_config(
+ cfg,
max_concurrency=concurrency,
language=cfg.get("language", "en"),
reasoning=resolve_reasoning(reasoning, cfg),
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index ca6767a07..0e5b392d5 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -274,7 +274,8 @@ def _run_generation_phase(
f"Generating wiki pages with {provider.provider_name} / {provider.model_name}",
)
- gen_config = GenerationConfig(
+ gen_config = GenerationConfig.from_repo_config(
+ load_config(repo_path),
max_concurrency=concurrency,
language=language,
reasoning=resolved_reasoning,
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
index 7ca917101..b80cf2eca 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
@@ -103,7 +103,8 @@ def _run_workspace_generation(
"""
from repowise.core.generation import GenerationConfig
- gen_config = GenerationConfig(
+ gen_config = GenerationConfig.from_repo_config(
+ load_config(repo_path),
max_concurrency=concurrency,
reasoning=resolve_reasoning(reasoning),
enable_onboarding=onboarding,
diff --git a/packages/cli/src/repowise/cli/commands/restyle_cmd.py b/packages/cli/src/repowise/cli/commands/restyle_cmd.py
index d8f9225ed..ee70a4912 100644
--- a/packages/cli/src/repowise/cli/commands/restyle_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/restyle_cmd.py
@@ -234,7 +234,8 @@ def restyle_command(
from repowise.core.generation import GenerationConfig
- config = GenerationConfig(
+ config = GenerationConfig.from_repo_config(
+ cfg,
max_concurrency=concurrency,
language=cfg.get("language", "en"),
reasoning=resolve_reasoning(reasoning, cfg),
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 8f5620c5c..31e05528c 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -1183,7 +1183,8 @@ def run_update(
# on update yet — defaults to on to keep the onboarding collection
# fresh as the codebase evolves.
enable_onboarding_cfg = bool(cfg.get("enable_onboarding", True))
- config = GenerationConfig(
+ config = GenerationConfig.from_repo_config(
+ cfg,
max_concurrency=concurrency,
language=language,
reasoning=resolve_reasoning(reasoning, cfg),
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
index 3758d55e7..14677eab8 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -148,7 +148,8 @@ def _render_pages(
return []
try:
- config = GenerationConfig(
+ config = GenerationConfig.from_repo_config(
+ cfg,
deterministic=True,
file_pages_only=True,
max_concurrency=concurrency,
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index 46b4d7146..2adeab16c 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -430,7 +430,8 @@ def upgrade_to_full(
# not have one configured yet. resolve_provider surfaces a clear error.
provider = resolve_provider(provider_name, model, repo_path=repo_path)
- config = GenerationConfig(
+ config = GenerationConfig.from_repo_config(
+ cfg,
max_concurrency=concurrency,
language=cfg.get("language", "en"),
reasoning=resolve_reasoning(reasoning, cfg),
diff --git a/packages/cli/src/repowise/cli/commands/workspace_cmd.py b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
index fb11d6819..caab728a7 100644
--- a/packages/cli/src/repowise/cli/commands/workspace_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
@@ -688,7 +688,8 @@ def _generate_docs_for_added_repo(
from repowise.core.repo_config import load_repo_config
repo_cfg = load_repo_config(repo_path)
- config = GenerationConfig(
+ config = GenerationConfig.from_repo_config(
+ repo_cfg,
max_concurrency=concurrency,
reasoning=reasoning,
wiki_style=repo_cfg.get("wiki_style", "comprehensive"),
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index 720601894..a22a486d8 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -10,10 +10,10 @@ import graph stays one-directional:
from __future__ import annotations
import hashlib
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping
from dataclasses import dataclass, field
from datetime import UTC, datetime
-from typing import Literal
+from typing import Any, Literal
from repowise.core.reasoning import ReasoningMode, normalize_reasoning
@@ -52,6 +52,7 @@ GENERATION_LEVELS: dict[str, int] = {
}
FreshnessStatus = Literal["fresh", "stale", "expired", "unknown"]
+DEFAULT_MAX_TOKENS = 16384
# ---------------------------------------------------------------------------
@@ -78,7 +79,7 @@ class GenerationConfig:
jobs_dir: Directory for job checkpoint JSON files.
"""
- max_tokens: int = 16384
+ max_tokens: int = DEFAULT_MAX_TOKENS
temperature: float = 0.3
token_budget: int = 48000
max_concurrency: int = 12
@@ -205,7 +206,40 @@ class GenerationConfig:
# ``repowise generate`` uses to refresh those repo-wide pages on demand.
file_pages_only: bool = False
+ @classmethod
+ def from_repo_config(
+ cls,
+ config: Mapping[str, Any],
+ **overrides: Any,
+ ) -> GenerationConfig:
+ """Build a generation config with the repo's documentation output limit.
+
+ ``max_tokens`` is the persisted user-facing setting. Keeping its parsing
+ here gives CLI, server, and core entry points one owner for translating
+ repo configuration into the provider request budget.
+ """
+ raw_max_tokens = config.get("max_tokens", DEFAULT_MAX_TOKENS)
+ if isinstance(raw_max_tokens, bool):
+ raise ValueError("max_tokens must be a positive integer")
+ if isinstance(raw_max_tokens, int):
+ max_tokens = raw_max_tokens
+ elif isinstance(raw_max_tokens, str) and raw_max_tokens.strip().isdigit():
+ max_tokens = int(raw_max_tokens)
+ else:
+ raise ValueError("max_tokens must be a positive integer")
+ if max_tokens <= 0:
+ raise ValueError("max_tokens must be a positive integer")
+
+ values = {"max_tokens": max_tokens, **overrides}
+ return cls(**values)
+
def __post_init__(self) -> None:
+ if (
+ isinstance(self.max_tokens, bool)
+ or not isinstance(self.max_tokens, int)
+ or self.max_tokens <= 0
+ ):
+ raise ValueError("max_tokens must be a positive integer")
if self.embed_concurrency is None:
object.__setattr__(self, "embed_concurrency", self.max_concurrency)
object.__setattr__(self, "reasoning", normalize_reasoning(self.reasoning))
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index f063a98a5..20caa6fde 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -42,6 +42,7 @@ from .structural import (
oneline,
signature,
)
+from .validation import validate_generated_response
if TYPE_CHECKING:
from pathlib import Path as _Path # noqa: F401
@@ -362,6 +363,7 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
reasoning=self._config.reasoning,
cache_hints=cache_hints,
)
+ validate_generated_response(response)
if self._config.cache_enabled:
self._cache[key] = response
@@ -445,6 +447,14 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
# styles, so default ("comprehensive") pages keep byte-identical metadata.
if self._style.is_active:
page.metadata["style"] = self._style.name
+ # Keep the completion boundary visible after persistence. A successful
+ # page normally ends with ``end_turn``; retaining both forms makes an
+ # adapter-specific termination diagnosable without changing the shared
+ # page schema.
+ if response.stop_reason is not None:
+ page.metadata["stop_reason"] = response.stop_reason
+ if response.provider_stop_reason is not None:
+ page.metadata["provider_stop_reason"] = response.provider_stop_reason
# Content came back verbatim from the prior run's persisted page:
# downstream (embedding) uses this to skip work whose output already
# exists byte-identically.
diff --git a/packages/core/src/repowise/core/generation/page_generator/validation.py b/packages/core/src/repowise/core/generation/page_generator/validation.py
index defa9727c..93c7e0445 100644
--- a/packages/core/src/repowise/core/generation/page_generator/validation.py
+++ b/packages/core/src/repowise/core/generation/page_generator/validation.py
@@ -1,15 +1,80 @@
-"""LLM-output validation — hallucination detection for generated pages.
+"""LLM-output validation for generated documentation pages.
-Cross-checks backtick-quoted names in LLM output against the symbols,
-exports, and imports of the source ``ParsedFile`` so that references the
-model invented (but that do not exist in the AST) can be surfaced.
+Rejects unusable provider responses before persistence and cross-checks
+backtick-quoted names against the source ``ParsedFile`` so invented symbols
+can be surfaced.
"""
from __future__ import annotations
import re
+from collections import Counter
from repowise.core.ingestion.models import ParsedFile
+from repowise.core.providers.llm.base import GeneratedResponse
+
+_REPETITION_SHINGLE_WORDS = 12
+_REPETITION_MIN_WORDS = 240
+_REPETITION_MIN_OCCURRENCES = 20
+_REPETITION_MAX_UNIQUE_RATIO = 0.25
+_WORD_RE = re.compile(r"\w+", re.UNICODE)
+
+
+class InvalidGeneratedContentError(ValueError):
+ """Raised when a fresh LLM response cannot be persisted as documentation."""
+
+
+def _pathological_repetition_detail(content: str) -> str | None:
+ """Describe gross repetition, using deliberately conservative thresholds.
+
+ Twelve-word shingles tolerate ordinary repeated headings, table columns,
+ API-list phrasing, and identifiers because the output must also be long,
+ repeat one exact shingle at least twenty times, and have fewer than one
+ unique shingle per four windows.
+ """
+ words = [match.group(0).casefold() for match in _WORD_RE.finditer(content)]
+ if len(words) < _REPETITION_MIN_WORDS:
+ return None
+
+ shingle_count = len(words) - _REPETITION_SHINGLE_WORDS + 1
+ if shingle_count <= 0:
+ return None
+ shingles = Counter(
+ tuple(words[index : index + _REPETITION_SHINGLE_WORDS]) for index in range(shingle_count)
+ )
+ maximum_occurrences = max(shingles.values(), default=0)
+ unique_ratio = len(shingles) / shingle_count
+ if (
+ maximum_occurrences >= _REPETITION_MIN_OCCURRENCES
+ and unique_ratio <= _REPETITION_MAX_UNIQUE_RATIO
+ ):
+ return (
+ f"12-word shingle repeated {maximum_occurrences} times "
+ f"(unique ratio {unique_ratio:.3f})"
+ )
+ return None
+
+
+def validate_generated_response(response: GeneratedResponse) -> None:
+ """Reject fresh provider output that is unsafe to persist as a wiki page."""
+ if response.stop_reason == "max_tokens":
+ detail = (
+ f" (provider reason: {response.provider_stop_reason})"
+ if response.provider_stop_reason
+ else ""
+ )
+ raise InvalidGeneratedContentError(
+ f"generation reached a token limit before the documentation was complete{detail}"
+ )
+ if not response.content.strip():
+ raise InvalidGeneratedContentError("provider returned empty documentation")
+
+ repetition_detail = _pathological_repetition_detail(response.content)
+ if repetition_detail is not None:
+ raise InvalidGeneratedContentError(
+ f"provider returned pathologically repetitive documentation: {repetition_detail}"
+ )
+
# Common words that appear in backticks but are not code symbols.
_BACKTICK_SKIP = frozenset(
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 20868ea1d..5359550a5 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -644,7 +644,8 @@ async def run_pipeline(
# Wiki style precedence: explicit param (server passes the DB-settings
# value) > repo-local config.yaml (CLI/init) > default.
_style = wiki_style or _cfg.get("wiki_style", "comprehensive")
- resolved_generation_config = GenerationConfig(
+ resolved_generation_config = GenerationConfig.from_repo_config(
+ _cfg,
max_concurrency=concurrency,
reasoning=resolve_reasoning(config=_cfg),
wiki_style=_style,
diff --git a/packages/core/src/repowise/core/providers/llm/anthropic.py b/packages/core/src/repowise/core/providers/llm/anthropic.py
index b07ced2a0..8a7593298 100644
--- a/packages/core/src/repowise/core/providers/llm/anthropic.py
+++ b/packages/core/src/repowise/core/providers/llm/anthropic.py
@@ -34,6 +34,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -219,6 +220,7 @@ class AnthropicProvider(BaseProvider):
raise ProviderError("anthropic", str(exc), status_code=exc.status_code) from exc
cached = getattr(response.usage, "cache_read_input_tokens", 0) or 0
+ stop_reason, provider_stop_reason = normalize_stop_reason(response.stop_reason)
text_content = ""
for block in response.content:
@@ -231,6 +233,8 @@ class AnthropicProvider(BaseProvider):
input_tokens=response.usage.input_tokens,
output_tokens=response.usage.output_tokens,
cached_tokens=cached,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"input_tokens": response.usage.input_tokens,
"output_tokens": response.usage.output_tokens,
diff --git a/packages/core/src/repowise/core/providers/llm/base.py b/packages/core/src/repowise/core/providers/llm/base.py
index 74fece5db..33ff61618 100644
--- a/packages/core/src/repowise/core/providers/llm/base.py
+++ b/packages/core/src/repowise/core/providers/llm/base.py
@@ -24,6 +24,35 @@ CacheSegment = Literal["system", "user_prefix"]
ModelOptionSource = Literal["api", "local", "fallback"]
+def normalize_stop_reason(reason: object) -> tuple[str | None, str | None]:
+ """Return ``(normalized, provider-native)`` completion stop reasons.
+
+ Non-streaming adapters use the same neutral values as ``ChatStreamEvent``.
+ Unknown provider values are retained verbatim so failures remain
+ diagnosable without teaching the provider-neutral layer every vendor enum.
+ """
+ if reason is None:
+ return None, None
+
+ raw_reason = reason if isinstance(reason, str) else getattr(reason, "value", None)
+ if not isinstance(raw_reason, str) or not raw_reason.strip():
+ return None, None
+
+ provider_stop_reason = raw_reason.strip()
+ normalized_key = provider_stop_reason.lower()
+ aliases = {
+ "stop": "end_turn",
+ "end_turn": "end_turn",
+ "stop_sequence": "end_turn",
+ "length": "max_tokens",
+ "max_tokens": "max_tokens",
+ "tool_calls": "tool_use",
+ "function_call": "tool_use",
+ "tool_use": "tool_use",
+ }
+ return aliases.get(normalized_key), provider_stop_reason
+
+
@dataclass(frozen=True)
class ProviderModelOption:
"""A model choice exposed by a provider for interactive configuration."""
@@ -100,6 +129,11 @@ class GeneratedResponse:
when nothing was harvested. Each item is a raw dict
carrying at least ``title`` + ``source_quote``; the
generator gates them against the file source before use.
+ stop_reason: Provider-neutral completion reason. Uses the same values
+ as streaming chat (notably ``end_turn``, ``max_tokens``,
+ and ``tool_use``).
+ provider_stop_reason:
+ Provider-native completion reason retained for diagnosis.
"""
content: str
@@ -108,6 +142,8 @@ class GeneratedResponse:
cached_tokens: int = 0
usage: dict[str, Any] = field(default_factory=dict)
decisions: list[dict] | None = None
+ stop_reason: str | None = None
+ provider_stop_reason: str | None = None
@property
def total_tokens(self) -> int:
diff --git a/packages/core/src/repowise/core/providers/llm/deepseek.py b/packages/core/src/repowise/core/providers/llm/deepseek.py
index 96addee94..11ed96d52 100644
--- a/packages/core/src/repowise/core/providers/llm/deepseek.py
+++ b/packages/core/src/repowise/core/providers/llm/deepseek.py
@@ -34,6 +34,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -274,11 +275,15 @@ class DeepSeekProvider(BaseProvider):
) from exc
usage = response.usage
+ choice = response.choices[0]
+ stop_reason, provider_stop_reason = normalize_stop_reason(choice.finish_reason)
result = GeneratedResponse(
- content=response.choices[0].message.content or "",
+ content=choice.message.content or "",
input_tokens=usage.prompt_tokens if usage else 0,
output_tokens=usage.completion_tokens if usage else 0,
cached_tokens=0,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"prompt_tokens": usage.prompt_tokens if usage else 0,
"completion_tokens": usage.completion_tokens if usage else 0,
diff --git a/packages/core/src/repowise/core/providers/llm/gemini.py b/packages/core/src/repowise/core/providers/llm/gemini.py
index 72412e982..5d093fff7 100644
--- a/packages/core/src/repowise/core/providers/llm/gemini.py
+++ b/packages/core/src/repowise/core/providers/llm/gemini.py
@@ -30,6 +30,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
provider_retry_stop,
provider_retry_wait,
provider_should_retry,
@@ -350,9 +351,7 @@ class GeminiProvider(BaseProvider):
config_kwargs: dict[str, Any] = {
"system_instruction": system_prompt,
"temperature": temperature,
- # max_output_tokens intentionally omitted — Gemini flash
- # models default to 65k tokens, which is far better for
- # documentation generation than any low cap we'd impose.
+ "max_output_tokens": max_tokens,
}
if thinking_config is not None:
config_kwargs["thinking_config"] = thinking_config
@@ -375,11 +374,17 @@ class GeminiProvider(BaseProvider):
raise ProviderError("gemini", f"{type(exc).__name__}: {exc_str}") from exc
usage = response.usage_metadata
+ candidate = response.candidates[0] if response.candidates else None
+ stop_reason, provider_stop_reason = normalize_stop_reason(
+ getattr(candidate, "finish_reason", None)
+ )
return GeneratedResponse(
content=response.text or "",
input_tokens=getattr(usage, "prompt_token_count", 0) or 0,
output_tokens=getattr(usage, "candidates_token_count", 0) or 0,
cached_tokens=getattr(usage, "cached_content_token_count", 0) or 0,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"prompt_token_count": getattr(usage, "prompt_token_count", 0) or 0,
"candidates_token_count": getattr(usage, "candidates_token_count", 0) or 0,
diff --git a/packages/core/src/repowise/core/providers/llm/kimi.py b/packages/core/src/repowise/core/providers/llm/kimi.py
index 478d7d4e3..75c97c8b5 100644
--- a/packages/core/src/repowise/core/providers/llm/kimi.py
+++ b/packages/core/src/repowise/core/providers/llm/kimi.py
@@ -35,6 +35,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -280,11 +281,15 @@ class KimiProvider(BaseProvider):
raise ProviderError("kimi", str(exc), status_code=exc.status_code) from exc
usage = response.usage
+ choice = response.choices[0]
+ stop_reason, provider_stop_reason = normalize_stop_reason(choice.finish_reason)
result = GeneratedResponse(
- content=response.choices[0].message.content or "",
+ content=choice.message.content or "",
input_tokens=usage.prompt_tokens if usage else 0,
output_tokens=usage.completion_tokens if usage else 0,
cached_tokens=0,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"prompt_tokens": usage.prompt_tokens if usage else 0,
"completion_tokens": usage.completion_tokens if usage else 0,
diff --git a/packages/core/src/repowise/core/providers/llm/litellm.py b/packages/core/src/repowise/core/providers/llm/litellm.py
index aafad4e47..9909ce191 100644
--- a/packages/core/src/repowise/core/providers/llm/litellm.py
+++ b/packages/core/src/repowise/core/providers/llm/litellm.py
@@ -37,6 +37,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -263,11 +264,15 @@ class LiteLLMProvider(BaseProvider):
raise ProviderError("litellm", f"{type(exc).__name__}: {exc}") from exc
usage = response.usage
+ choice = response.choices[0]
+ stop_reason, provider_stop_reason = normalize_stop_reason(choice.finish_reason)
result = GeneratedResponse(
- content=response.choices[0].message.content or "",
+ content=choice.message.content or "",
input_tokens=getattr(usage, "prompt_tokens", 0) if usage else 0,
output_tokens=getattr(usage, "completion_tokens", 0) if usage else 0,
cached_tokens=0,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage=dict(usage) if usage else {},
)
log.debug(
diff --git a/packages/core/src/repowise/core/providers/llm/ollama.py b/packages/core/src/repowise/core/providers/llm/ollama.py
index 3062af3aa..df91e316b 100644
--- a/packages/core/src/repowise/core/providers/llm/ollama.py
+++ b/packages/core/src/repowise/core/providers/llm/ollama.py
@@ -42,6 +42,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -276,11 +277,15 @@ class OllamaProvider(BaseProvider):
) from exc
usage = response.usage
+ choice = response.choices[0]
+ stop_reason, provider_stop_reason = normalize_stop_reason(choice.finish_reason)
result = GeneratedResponse(
- content=response.choices[0].message.content or "",
+ content=choice.message.content or "",
input_tokens=usage.prompt_tokens if usage else 0,
output_tokens=usage.completion_tokens if usage else 0,
cached_tokens=0,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"prompt_tokens": usage.prompt_tokens if usage else 0,
"completion_tokens": usage.completion_tokens if usage else 0,
diff --git a/packages/core/src/repowise/core/providers/llm/openai.py b/packages/core/src/repowise/core/providers/llm/openai.py
index 353270b17..a54742120 100644
--- a/packages/core/src/repowise/core/providers/llm/openai.py
+++ b/packages/core/src/repowise/core/providers/llm/openai.py
@@ -35,6 +35,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -349,11 +350,15 @@ class OpenAIProvider(BaseProvider):
details = getattr(usage, "prompt_tokens_details", None)
if details is not None:
cached = getattr(details, "cached_tokens", 0) or 0
+ choice = response.choices[0]
+ stop_reason, provider_stop_reason = normalize_stop_reason(choice.finish_reason)
result = GeneratedResponse(
- content=response.choices[0].message.content or "",
+ content=choice.message.content or "",
input_tokens=usage.prompt_tokens if usage else 0,
output_tokens=usage.completion_tokens if usage else 0,
cached_tokens=cached,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"prompt_tokens": usage.prompt_tokens if usage else 0,
"completion_tokens": usage.completion_tokens if usage else 0,
diff --git a/packages/core/src/repowise/core/providers/llm/openrouter.py b/packages/core/src/repowise/core/providers/llm/openrouter.py
index a2538880a..ef40b64fc 100644
--- a/packages/core/src/repowise/core/providers/llm/openrouter.py
+++ b/packages/core/src/repowise/core/providers/llm/openrouter.py
@@ -35,6 +35,7 @@ from repowise.core.providers.llm.base import (
RateLimitError,
ensure_reasoning_supported,
fallback_model_option,
+ normalize_stop_reason,
parse_retry_after,
provider_retry_stop,
provider_retry_wait,
@@ -355,11 +356,15 @@ class OpenRouterProvider(BaseProvider):
) from exc
usage = response.usage
+ choice = response.choices[0]
+ stop_reason, provider_stop_reason = normalize_stop_reason(choice.finish_reason)
result = GeneratedResponse(
- content=response.choices[0].message.content or "",
+ content=choice.message.content or "",
input_tokens=usage.prompt_tokens if usage else 0,
output_tokens=usage.completion_tokens if usage else 0,
cached_tokens=0,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
usage={
"prompt_tokens": usage.prompt_tokens if usage else 0,
"completion_tokens": usage.completion_tokens if usage else 0,
diff --git a/packages/server/src/repowise/server/job_executor.py b/packages/server/src/repowise/server/job_executor.py
index f150e8bf9..088088c09 100644
--- a/packages/server/src/repowise/server/job_executor.py
+++ b/packages/server/src/repowise/server/job_executor.py
@@ -923,7 +923,8 @@ def _build_generation_config(repo_path: Path, config: dict, wiki_style: str) ->
repo_cfg = load_repo_config(repo_path)
effective_style = resolve_style(config.get("style") or wiki_style, repo_path=repo_path).name
- return GenerationConfig(
+ return GenerationConfig.from_repo_config(
+ repo_cfg,
reasoning=resolve_reasoning(config=repo_cfg),
wiki_style=effective_style,
language=repo_cfg.get("language", "en"),
@@ -1201,7 +1202,8 @@ async def _incremental_page_regen(
job_config.get("style") or repo_wiki_style, repo_path=repo_path
).name
repo_cfg = load_repo_config(repo_path)
- generation_config = GenerationConfig(
+ generation_config = GenerationConfig.from_repo_config(
+ repo_cfg,
reasoning=resolve_reasoning(config=repo_cfg),
wiki_style=effective_style,
# Regenerate in the repo's configured output language, not default
diff --git a/tests/unit/generation/test_models.py b/tests/unit/generation/test_models.py
index a7c533f3d..cd8a8ffd0 100644
--- a/tests/unit/generation/test_models.py
+++ b/tests/unit/generation/test_models.py
@@ -157,6 +157,17 @@ def test_generation_config_defaults():
assert config.reasoning == "auto"
+def test_generation_config_reads_repo_max_tokens():
+ config = GenerationConfig.from_repo_config({"max_tokens": "2345"})
+ assert config.max_tokens == 2345
+
+
[email protected]("value", [0, -1, True, 1.5, "not-a-number"])
+def test_generation_config_rejects_invalid_repo_max_tokens(value):
+ with pytest.raises(ValueError, match="positive integer"):
+ GenerationConfig.from_repo_config({"max_tokens": value})
+
+
def test_generation_config_embed_concurrency_defaults_to_max_concurrency():
config = GenerationConfig(max_concurrency=3)
assert config.embed_concurrency == 3
diff --git a/tests/unit/generation/test_output_validation.py b/tests/unit/generation/test_output_validation.py
new file mode 100644
index 000000000..b6a581d49
--- /dev/null
+++ b/tests/unit/generation/test_output_validation.py
@@ -0,0 +1,88 @@
+"""Tests for the generated documentation completion contract."""
+
+import pytest
+
+from repowise.core.generation.page_generator.validation import (
+ InvalidGeneratedContentError,
+ validate_generated_response,
+)
+from repowise.core.providers.llm.base import GeneratedResponse
+
+
+def _response(
+ content: str,
+ *,
+ stop_reason: str | None = "end_turn",
+ provider_stop_reason: str | None = "stop",
+) -> GeneratedResponse:
+ return GeneratedResponse(
+ content=content,
+ input_tokens=10,
+ output_tokens=20,
+ stop_reason=stop_reason,
+ provider_stop_reason=provider_stop_reason,
+ )
+
+
+def test_accepts_valid_documentation() -> None:
+ validate_generated_response(
+ _response(
+ """# Queue status
+
+`QueueStatus` reports the active queue and its pending work.
+
+## Usage
+
+Call `snapshot()` after workers have registered.
+"""
+ )
+ )
+
+
+def test_rejects_whitespace_documentation() -> None:
+ with pytest.raises(InvalidGeneratedContentError, match="empty documentation"):
+ validate_generated_response(_response(" \n\t "))
+
+
+def test_rejects_provider_declared_token_limit() -> None:
+ with pytest.raises(
+ InvalidGeneratedContentError,
+ match="token limit before the documentation was complete",
+ ):
+ validate_generated_response(
+ _response(
+ "# Queue status\n\nThis sentence stops midway",
+ stop_reason="max_tokens",
+ provider_stop_reason="length",
+ )
+ )
+
+
+def test_rejects_pathological_repetition() -> None:
+ repeated_dependency = (
+ "The queue status reader depends on the repository cache and worker registry "
+ "before it can report pending jobs accurately."
+ )
+ content = "# Queue status\n\n" + "\n".join(repeated_dependency for _ in range(40))
+
+ with pytest.raises(InvalidGeneratedContentError, match="pathologically repetitive"):
+ validate_generated_response(_response(content))
+
+
+def test_accepts_repetitive_but_valid_api_documentation() -> None:
+ sections = []
+ for index in range(40):
+ sections.append(
+ f"""## `endpoint_{index}`
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `request_{index}` | `Request{index}` | yes |
+| `timeout_{index}` | integer | no |
+
+`endpoint_{index}` validates `Request{index}` and returns `Response{index}`.
+The response includes the distinct operation code `operation_{index}`.
+"""
+ )
+
+ validate_generated_response(_response("\n".join(sections)))
diff --git a/tests/unit/generation/test_page_generator.py b/tests/unit/generation/test_page_generator.py
index 02eb88817..570ce0767 100644
--- a/tests/unit/generation/test_page_generator.py
+++ b/tests/unit/generation/test_page_generator.py
@@ -7,9 +7,17 @@ from datetime import datetime
import pytest
from repowise.core.generation.context_assembler import ContextAssembler
-from repowise.core.generation.models import GeneratedPage, GenerationConfig
+from repowise.core.generation.models import (
+ GeneratedPage,
+ GenerationConfig,
+ compute_page_id,
+ compute_source_hash,
+)
from repowise.core.generation.page_generator import SYSTEM_PROMPTS, PageGenerator
+from repowise.core.generation.page_generator.core import PriorPage
+from repowise.core.generation.page_generator.validation import InvalidGeneratedContentError
from repowise.core.ingestion.models import ParsedFile, RepoStructure
+from repowise.core.providers.llm.base import GeneratedResponse
from repowise.core.providers.llm.mock import MockProvider
from .conftest import _make_file_info, _make_symbol
@@ -160,6 +168,138 @@ async def test_file_page_is_byte_identical_with_and_without_a_key(
assert pages[0].page_id == pages[1].page_id
+async def test_provider_request_forwards_reasoning_config():
+ provider = MockProvider()
+ config = GenerationConfig(reasoning="off")
+ assembler = ContextAssembler(config)
+ gen = PageGenerator(provider, assembler, config)
+
+ await gen._call_provider("module_page", "Document this module.", "request-id")
+
+ assert provider.calls[0]["reasoning"] == "off"
+
+
+async def test_repo_output_limit_reaches_provider_request(sample_config):
+ """Exercise the public config-to-provider path without a network call."""
+ provider = MockProvider()
+ config = GenerationConfig.from_repo_config(
+ {"max_tokens": 2345},
+ token_budget=sample_config.token_budget,
+ cache_enabled=False,
+ )
+ generator = PageGenerator(provider, ContextAssembler(config), config)
+
+ await generator._call_provider("module_page", "Document this module.", "request-id")
+
+ assert provider.calls[0]["max_tokens"] == 2345
+
+
+async def test_invalid_provider_output_raises_and_is_not_cached(sample_config):
+ provider = MockProvider(
+ responses=[
+ GeneratedResponse(
+ content="# Queue status\n\nIncomplete",
+ input_tokens=10,
+ output_tokens=20,
+ stop_reason="max_tokens",
+ provider_stop_reason="length",
+ )
+ ]
+ )
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ for _ in range(2):
+ with pytest.raises(
+ InvalidGeneratedContentError,
+ match="token limit before the documentation was complete",
+ ):
+ await generator._call_provider("module_page", "Document this module.", "request-id")
+
+ assert provider.call_count == 2
+
+
+def test_generated_page_retains_completion_stop_metadata(sample_config):
+ generator = PageGenerator(MockProvider(), ContextAssembler(sample_config), sample_config)
+ page = generator._build_generated_page(
+ "module_page",
+ "pkg",
+ "Package",
+ GeneratedResponse(
+ content="## Overview\n\nA package.",
+ input_tokens=10,
+ output_tokens=20,
+ stop_reason="end_turn",
+ provider_stop_reason="stop",
+ ),
+ "source-hash",
+ 4,
+ )
+
+ assert page.metadata["stop_reason"] == "end_turn"
+ assert page.metadata["provider_stop_reason"] == "stop"
+
+
+async def test_prior_page_reuse_bypasses_fresh_output_validation(sample_config):
+ provider = MockProvider()
+ prompt = "Document this module."
+ target_path = "pkg"
+ prior_pages = {
+ compute_page_id("module_page", target_path): PriorPage(
+ source_hash=compute_source_hash(prompt),
+ model_name=provider.model_name,
+ content=" \n ",
+ )
+ }
+ generator = PageGenerator(
+ provider,
+ ContextAssembler(sample_config),
+ sample_config,
+ prior_pages=prior_pages,
+ )
+
+ response = await generator._call_provider(
+ "module_page",
+ prompt,
+ "request-id",
+ target_path=target_path,
+ )
+
+ assert response.content == " \n "
+ assert provider.call_count == 0
+
+
+# ---------------------------------------------------------------------------
+# Prompt cache
+# ---------------------------------------------------------------------------
+
+
+async def test_cache_hit_does_not_increment_call_count(sample_config):
+ provider = MockProvider()
+ config = GenerationConfig(
+ max_tokens=1024, token_budget=2000, max_concurrency=2, cache_enabled=True
+ )
+ assembler = ContextAssembler(config)
+ gen = PageGenerator(provider, assembler, config)
+
+ await gen._call_provider("module_page", "Document this module.", "request-id")
+ # Second call — identical inputs → cache hit
+ await gen._call_provider("module_page", "Document this module.", "request-id")
+ assert provider.call_count == 1
+
+
+async def test_cache_disabled_increments_every_call(sample_config):
+ provider = MockProvider()
+ config = GenerationConfig(
+ max_tokens=1024, token_budget=2000, max_concurrency=2, cache_enabled=False
+ )
+ assembler = ContextAssembler(config)
+ gen = PageGenerator(provider, assembler, config)
+
+ await gen._call_provider("module_page", "Document this module.", "request-id-one")
+ await gen._call_provider("module_page", "Document this module.", "request-id-two")
+ assert provider.call_count == 2
+
+
# ---------------------------------------------------------------------------
# Cache key uniqueness
# ---------------------------------------------------------------------------
diff --git a/tests/unit/server/test_job_executor.py b/tests/unit/server/test_job_executor.py
index 76e24b8c8..361e77d42 100644
--- a/tests/unit/server/test_job_executor.py
+++ b/tests/unit/server/test_job_executor.py
@@ -16,6 +16,7 @@ import pytest
from repowise.core.persistence.crud import upsert_generation_job, upsert_repository
from repowise.server.job_executor import (
+ _build_generation_config,
_incremental_page_regen,
_repo_exclude_patterns,
execute_job,
@@ -198,6 +199,16 @@ def test_repo_wiki_style_defaults_and_tolerates_bad_input(tmp_path):
)
+def test_server_generation_config_reads_repo_output_limit(tmp_path):
+ config_dir = tmp_path / ".repowise"
+ config_dir.mkdir()
+ (config_dir / "config.yaml").write_text("max_tokens: 2468\n", encoding="utf-8")
+
+ config = _build_generation_config(tmp_path, {}, "comprehensive")
+
+ assert config.max_tokens == 2468
+
+
@pytest.mark.asyncio
async def test_execute_job_merges_config_yaml_excludes(session_factory, tmp_path):
"""End-to-end regression: the real user case (tools/ excluded).
@@ -413,9 +424,7 @@ def _no_provider():
@pytest.mark.asyncio
-async def test_initial_index_without_provider_renders_deterministic_wiki(
- session_factory, tmp_path
-):
+async def test_initial_index_without_provider_renders_deterministic_wiki(session_factory, tmp_path):
"""A keyless first index renders a template wiki instead of nothing.
Without a provider, the pipeline runs in DETERMINISTIC mode (it supplies its
@@ -492,9 +501,7 @@ async def test_initial_index_with_provider_uses_llm_mode(session_factory, tmp_pa
@pytest.mark.asyncio
-async def test_initial_index_no_provider_generate_docs_false_writes_none(
- session_factory, tmp_path
-):
+async def test_initial_index_no_provider_generate_docs_false_writes_none(session_factory, tmp_path):
"""An explicit generate_docs=False keyless index generates nothing ('none')."""
from repowise.core.pipeline.modes import OrchestratorMode
diff --git a/tests/unit/test_providers/test_anthropic_provider.py b/tests/unit/test_providers/test_anthropic_provider.py
index 776141e05..49ce34259 100644
--- a/tests/unit/test_providers/test_anthropic_provider.py
+++ b/tests/unit/test_providers/test_anthropic_provider.py
@@ -95,7 +95,11 @@ def test_available_model_options_uses_models_endpoint(monkeypatch):
# ---------------------------------------------------------------------------
-def _make_mock_response(text: str = "# Doc\nContent.") -> MagicMock:
+def _make_mock_response(
+ text: str = "# Doc\nContent.",
+ *,
+ stop_reason: str = "end_turn",
+) -> MagicMock:
usage = MagicMock()
usage.input_tokens = 200
usage.output_tokens = 80
@@ -108,6 +112,7 @@ def _make_mock_response(text: str = "# Doc\nContent.") -> MagicMock:
response = MagicMock()
response.content = [content_block]
response.usage = usage
+ response.stop_reason = stop_reason
return response
@@ -122,6 +127,21 @@ async def test_generate_returns_generated_response():
assert isinstance(result, GeneratedResponse)
assert result.content == "Hello from Claude"
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "end_turn"
+
+
+async def test_generate_preserves_max_tokens_stop_reason():
+ provider = AnthropicProvider(api_key="sk-ant-test")
+ mock_response = _make_mock_response(stop_reason="max_tokens")
+
+ with patch("anthropic.AsyncAnthropic") as mock_client:
+ mock_client.return_value.messages.create = AsyncMock(return_value=mock_response)
+ provider._client = mock_client.return_value
+ result = await provider.generate("sys", "user")
+
+ assert result.stop_reason == "max_tokens"
+ assert result.provider_stop_reason == "max_tokens"
async def test_generate_token_counts_with_cache():
diff --git a/tests/unit/test_providers/test_deepseek_provider.py b/tests/unit/test_providers/test_deepseek_provider.py
index a3eabffe4..e7e6003f9 100644
--- a/tests/unit/test_providers/test_deepseek_provider.py
+++ b/tests/unit/test_providers/test_deepseek_provider.py
@@ -92,7 +92,11 @@ def test_available_model_options_uses_models_endpoint(monkeypatch):
assert flash.recommended is True
-def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
+def _make_mock_chat_response(
+ text: str = "# Doc\nContent.",
+ *,
+ finish_reason: str = "stop",
+) -> MagicMock:
usage = MagicMock()
usage.prompt_tokens = 120
usage.completion_tokens = 60
@@ -100,6 +104,7 @@ def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
choice = MagicMock()
choice.message.content = text
+ choice.finish_reason = finish_reason
response = MagicMock()
response.choices = [choice]
@@ -152,6 +157,8 @@ async def test_generate_returns_generated_response():
assert result.content == "Hello from DeepSeek"
assert result.input_tokens == 120
assert result.output_tokens == 60
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "stop"
async def test_generate_uses_correct_model_name():
diff --git a/tests/unit/test_providers/test_gemini_provider.py b/tests/unit/test_providers/test_gemini_provider.py
index 6d9371857..8cf4b59d0 100644
--- a/tests/unit/test_providers/test_gemini_provider.py
+++ b/tests/unit/test_providers/test_gemini_provider.py
@@ -10,6 +10,7 @@ from unittest.mock import MagicMock, patch
import pytest
pytest.importorskip("google.genai", reason="google-genai SDK not installed")
+from google.genai import types as genai_types
from repowise.core.providers.llm import gemini as gemini_module
from repowise.core.providers.llm.base import GeneratedResponse, ProviderError, RateLimitError
@@ -120,7 +121,11 @@ def test_available_model_options_lists_generate_content_models(monkeypatch):
# ---------------------------------------------------------------------------
-def _make_mock_response(text: str = "# Doc\nContent here.") -> MagicMock:
+def _make_mock_response(
+ text: str = "# Doc\nContent here.",
+ *,
+ finish_reason=None,
+) -> MagicMock:
usage = MagicMock()
usage.prompt_token_count = 100
usage.candidates_token_count = 50
@@ -130,6 +135,9 @@ def _make_mock_response(text: str = "# Doc\nContent here.") -> MagicMock:
response = MagicMock()
response.text = text
response.usage_metadata = usage
+ candidate = MagicMock()
+ candidate.finish_reason = finish_reason or genai_types.FinishReason.STOP
+ response.candidates = [candidate]
return response
@@ -143,6 +151,20 @@ async def test_generate_returns_generated_response():
assert isinstance(result, GeneratedResponse)
assert result.content == "Hello world"
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "STOP"
+
+
+async def test_generate_maps_max_tokens_finish_reason():
+ provider = GeminiProvider(api_key="fake-key")
+ mock_response = _make_mock_response(finish_reason=genai_types.FinishReason.MAX_TOKENS)
+
+ with patch("google.genai.Client") as mock_client:
+ mock_client.return_value.models.generate_content.return_value = mock_response
+ result = await provider.generate("sys", "user")
+
+ assert result.stop_reason == "max_tokens"
+ assert result.provider_stop_reason == "MAX_TOKENS"
async def test_generate_token_counts():
@@ -159,9 +181,7 @@ async def test_generate_token_counts():
async def test_generate_passes_max_tokens():
- """max_output_tokens is intentionally omitted in the Gemini config
- (flash models default to 65k which is better for doc generation).
- Verify the config is created but max_output_tokens is not set."""
+ """The shared documentation output limit reaches Gemini's request config."""
provider = GeminiProvider(api_key="fake-key")
mock_response = _make_mock_response()
captured: list = []
@@ -174,8 +194,7 @@ async def test_generate_passes_max_tokens():
mock_client.return_value.models.generate_content.side_effect = fake_generate_content
await provider.generate("sys", "user", max_tokens=1234)
- # max_output_tokens intentionally omitted — Gemini flash models default to 65k
- assert captured[0].max_output_tokens is None
+ assert captured[0].max_output_tokens == 1234
async def test_generate_forwards_thinking_level():
diff --git a/tests/unit/test_providers/test_kimi_provider.py b/tests/unit/test_providers/test_kimi_provider.py
index b52e0fb55..7e17a6a41 100644
--- a/tests/unit/test_providers/test_kimi_provider.py
+++ b/tests/unit/test_providers/test_kimi_provider.py
@@ -98,7 +98,11 @@ def test_available_model_options_uses_models_endpoint(monkeypatch):
)
-def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
+def _make_mock_chat_response(
+ text: str = "# Doc\nContent.",
+ *,
+ finish_reason: str = "stop",
+) -> MagicMock:
usage = MagicMock()
usage.prompt_tokens = 120
usage.completion_tokens = 60
@@ -106,6 +110,7 @@ def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
choice = MagicMock()
choice.message.content = text
+ choice.finish_reason = finish_reason
response = MagicMock()
response.choices = [choice]
@@ -156,6 +161,8 @@ async def test_generate_returns_generated_response():
assert isinstance(result, GeneratedResponse)
assert result.content == "Hello from Kimi"
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "stop"
assert result.input_tokens == 120
assert result.output_tokens == 60
diff --git a/tests/unit/test_providers/test_litellm_provider.py b/tests/unit/test_providers/test_litellm_provider.py
index 12693a33c..fc5ef0ea4 100644
--- a/tests/unit/test_providers/test_litellm_provider.py
+++ b/tests/unit/test_providers/test_litellm_provider.py
@@ -57,7 +57,10 @@ async def test_generate_forwards_reasoning_effort(monkeypatch):
type(
"Choice",
(),
- {"message": type("Message", (), {"content": "ok"})()},
+ {
+ "message": type("Message", (), {"content": "ok"})(),
+ "finish_reason": "length",
+ },
)()
],
"usage": None,
@@ -73,6 +76,8 @@ async def test_generate_forwards_reasoning_effort(monkeypatch):
)
provider = LiteLLMProvider(model="vendor/reasoner")
- await provider.generate("sys", "user", reasoning="high")
+ result = await provider.generate("sys", "user", reasoning="high")
assert completion.call_args.kwargs["reasoning_effort"] == "high"
+ assert result.stop_reason == "max_tokens"
+ assert result.provider_stop_reason == "length"
diff --git a/tests/unit/test_providers/test_ollama_provider_timeout_integration.py b/tests/unit/test_providers/test_ollama_provider_timeout_integration.py
index 87e634338..ae5b5380d 100644
--- a/tests/unit/test_providers/test_ollama_provider_timeout_integration.py
+++ b/tests/unit/test_providers/test_ollama_provider_timeout_integration.py
@@ -135,6 +135,8 @@ async def test_ollama_succeeds_on_retry():
assert result.content == "Generated wiki content"
assert result.input_tokens == 10
assert result.output_tokens == 20
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "stop"
@pytest.mark.asyncio
diff --git a/tests/unit/test_providers/test_openai_provider.py b/tests/unit/test_providers/test_openai_provider.py
index 2cb7c8194..dd54867ff 100644
--- a/tests/unit/test_providers/test_openai_provider.py
+++ b/tests/unit/test_providers/test_openai_provider.py
@@ -123,7 +123,11 @@ def test_available_model_options_falls_back_to_configured_model(monkeypatch):
# ---------------------------------------------------------------------------
-def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
+def _make_mock_chat_response(
+ text: str = "# Doc\nContent.",
+ *,
+ finish_reason: str = "stop",
+) -> MagicMock:
usage = MagicMock()
usage.prompt_tokens = 120
usage.completion_tokens = 60
@@ -132,6 +136,7 @@ def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
choice = MagicMock()
choice.message.content = text
+ choice.finish_reason = finish_reason
response = MagicMock()
response.choices = [choice]
@@ -150,6 +155,21 @@ async def test_generate_returns_generated_response():
assert isinstance(result, GeneratedResponse)
assert result.content == "Hello from OpenAI"
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "stop"
+
+
+async def test_generate_maps_length_to_token_limit():
+ provider = OpenAIProvider(api_key="sk-test")
+ mock_response = _make_mock_chat_response(finish_reason="length")
+
+ with patch("openai.AsyncOpenAI") as mock_client:
+ mock_client.return_value.chat.completions.create = AsyncMock(return_value=mock_response)
+ provider._client = mock_client.return_value
+ result = await provider.generate("sys", "user")
+
+ assert result.stop_reason == "max_tokens"
+ assert result.provider_stop_reason == "length"
async def test_generate_token_counts():
diff --git a/tests/unit/test_providers/test_openrouter_provider.py b/tests/unit/test_providers/test_openrouter_provider.py
index 3b6383452..23f443f9f 100644
--- a/tests/unit/test_providers/test_openrouter_provider.py
+++ b/tests/unit/test_providers/test_openrouter_provider.py
@@ -157,7 +157,11 @@ def test_available_model_options_uses_models_endpoint(monkeypatch):
# ---------------------------------------------------------------------------
-def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
+def _make_mock_chat_response(
+ text: str = "# Doc\nContent.",
+ *,
+ finish_reason: str = "stop",
+) -> MagicMock:
usage = MagicMock()
usage.prompt_tokens = 120
usage.completion_tokens = 60
@@ -165,6 +169,7 @@ def _make_mock_chat_response(text: str = "# Doc\nContent.") -> MagicMock:
choice = MagicMock()
choice.message.content = text
+ choice.finish_reason = finish_reason
response = MagicMock()
response.choices = [choice]
@@ -183,6 +188,8 @@ async def test_generate_returns_generated_response():
assert isinstance(result, GeneratedResponse)
assert result.content == "Hello from OpenRouter"
+ assert result.stop_reason == "end_turn"
+ assert result.provider_stop_reason == "stop"
async def test_generate_token_counts():
diff --git a/website/cli-reference.md b/website/cli-reference.md
index 8586c92f9..50ce7e5fc 100644
--- a/website/cli-reference.md
+++ b/website/cli-reference.md
@@ -444,6 +444,7 @@ Settings are saved to `.repowise/config.yaml` after the first `init`. You can ed
provider: anthropic
model: claude-sonnet-4-6
embedder: gemini
+max_tokens: 16384
exclude_patterns:
- vendor/
- "*.generated.*"
@@ -451,4 +452,7 @@ commit_limit: 500
follow_renames: false
```
+`max_tokens` is the persistent per-page documentation output limit used by all
+CLI and server generation paths.
+
See [Configuration →](configuration) for the full reference.
diff --git a/website/configuration.md b/website/configuration.md
index 473cdb07b..22b53c678 100644
--- a/website/configuration.md
+++ b/website/configuration.md
@@ -47,6 +47,7 @@ provider: anthropic # LLM provider
model: claude-sonnet-4-6 # Model identifier
embedder: gemini # Embedding provider
reasoning: auto # auto | off/none | minimal | low | medium | high | xhigh | max
+max_tokens: 16384 # Max output tokens per generated documentation page
exclude_patterns: # Gitignore-style patterns
- vendor/
- "*.generated.*"
@@ -74,6 +75,12 @@ translate an explicit mode fail before making an API call. The interactive
`serve` chat streaming path is separate and does not currently consume this
setting.
+`max_tokens` bounds each model-written documentation response. It is a
+persistent repository setting used by `init`, `update`, `generate`, `restyle`,
+workspace generation, and server-triggered generation. If generation reaches a
+token limit before the page is complete, repowise rejects the partial page
+instead of saving it.
+
---
## LLM providers