Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(generation): enforce documentation completion (#1011)
Austin Traveree54e1737c8e
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex 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 LLMrepowise 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.mdindex 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 passflags 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.```yamlprovider: anthropic # LLM provider (auto-detected if omitted)@@ -43,6 +44,7 @@ model: claude-sonnet-4-6 # Model identifier (provider default if omiembedder: 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 pagecommit_limit: 500 # Max commits per file for git analysis (clamped 1-10000)follow_renames: false # Track file renames in git historywiki_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 makingan 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 alsoregenerates the wiki). Power users can define their own style underdiff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/command.py b/packages/cli/src/repowise/cli/commands/generate_cmd/command.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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_configrepo_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.pyindex 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 annotationsimport hashlib-from collections.abc import Iterable+from collections.abc import Iterable, Mappingfrom dataclasses import dataclass, fieldfrom datetime import UTC, datetime-from typing import Literal+from typing import Any, Literalfrom 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_TOKENStemperature: float = 0.3token_budget: int = 48000max_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.pyindex 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_responseif 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.pyindex 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 annotationsimport re+from collections import Counterfrom 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.pyindex 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.pyindex 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 exccached = 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.pyindex 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 dictcarrying at least ``title`` + ``source_quote``; thegenerator 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 = 0usage: dict[str, Any] = field(default_factory=dict)decisions: list[dict] | None = None+ stop_reason: str | None = None+ provider_stop_reason: str | None = None@propertydef 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.pyindex 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 excusage = 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.pyindex 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 excusage = 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.pyindex 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 excusage = 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.pyindex 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 excusage = 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.pyindex 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 excusage = 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.pyindex 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.pyindex 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 excusage = 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.pyindex 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).namerepo_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 defaultdiff --git a/tests/unit/generation/test_models.py b/tests/unit/generation/test_models.pyindex 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 == 3diff --git a/tests/unit/generation/test_output_validation.py b/tests/unit/generation/test_output_validation.pynew file mode 100644index 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.pyindex 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 datetimeimport pytestfrom 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 InvalidGeneratedContentErrorfrom repowise.core.ingestion.models import ParsedFile, RepoStructure+from repowise.core.providers.llm.base import GeneratedResponsefrom repowise.core.providers.llm.mock import MockProviderfrom .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.pyindex 76e24b8c8..361e77d42 100644--- a/tests/unit/server/test_job_executor.py+++ b/tests/unit/server/test_job_executor.py@@ -16,6 +16,7 @@ import pytestfrom repowise.core.persistence.crud import upsert_generation_job, upsert_repositoryfrom 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.asyncioasync 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 OrchestratorModediff --git a/tests/unit/test_providers/test_anthropic_provider.py b/tests/unit/test_providers/test_anthropic_provider.pyindex 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 = 200usage.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_reasonreturn 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.pyindex 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 = 120usage.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_reasonresponse = 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 == 120assert 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.pyindex 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, patchimport pytestpytest.importorskip("google.genai", reason="google-genai SDK not installed")+from google.genai import types as genai_typesfrom repowise.core.providers.llm import gemini as gemini_modulefrom 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 = 100usage.candidates_token_count = 50@@ -130,6 +135,9 @@ def _make_mock_response(text: str = "# Doc\nContent here.") -> MagicMock:response = MagicMock()response.text = textresponse.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_contentawait 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 == 1234async 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.pyindex 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 = 120usage.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_reasonresponse = 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 == 120assert result.output_tokens == 60diff --git a/tests/unit/test_providers/test_litellm_provider.py b/tests/unit/test_providers/test_litellm_provider.pyindex 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.pyindex 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 == 10assert result.output_tokens == 20+ assert result.stop_reason == "end_turn"+ assert result.provider_stop_reason == "stop"@pytest.mark.asynciodiff --git a/tests/unit/test_providers/test_openai_provider.py b/tests/unit/test_providers/test_openai_provider.pyindex 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 = 120usage.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_reasonresponse = 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.pyindex 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 = 120usage.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_reasonresponse = 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.mdindex 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 edprovider: anthropicmodel: claude-sonnet-4-6embedder: gemini+max_tokens: 16384exclude_patterns:- vendor/- "*.generated.*"@@ -451,4 +452,7 @@ commit_limit: 500follow_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.mdindex 473cdb07b..22b53c678 100644--- a/website/configuration.md+++ b/website/configuration.md@@ -47,6 +47,7 @@ provider: anthropic # LLM providermodel: claude-sonnet-4-6 # Model identifierembedder: gemini # Embedding providerreasoning: auto # auto | off/none | minimal | low | medium | high | xhigh | max+max_tokens: 16384 # Max output tokens per generated documentation pageexclude_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 thissetting.+`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