Add reasoning mode configuration (#175)

Author: Eridanus117

.env.example

@@ -72,6 +72,12 @@ REPOWISE_DEFAULT_MODEL=claude-sonnet-4-6
 # Max concurrent LLM calls during generation
 REPOWISE_MAX_CONCURRENT=5
 
+# Reasoning mode for supported docs-generation providers: auto | off | minimal
+# auto = provider default; off = disable Qwen3/OpenRouter effort reasoning when supported;
+# minimal = request the lowest supported OpenAI/OpenRouter reasoning effort.
+# Unsupported explicit modes fail before an API call.
+REPOWISE_REASONING=auto
+
 # Max pages to regenerate per maintenance run
 REPOWISE_CASCADE_BUDGET=30
 

README.md

@@ -577,9 +577,10 @@ repowise reindex                  # rebuild vector store (no LLM calls)
 `repowise init` generates `.repowise/config.yaml`. Key options:
 
 ```yaml
-provider: anthropic               # anthropic | openai | ollama | litellm
+provider: anthropic               # anthropic | openai | openrouter | gemini | deepseek | ollama | litellm | mock
 model: claude-sonnet-4-5
 embedding_model: voyage-3
+reasoning: auto                   # auto | off | minimal
 
 git:
   co_change_commit_limit: 500
@@ -594,6 +595,10 @@ maintenance:
   background_regen_schedule: "0 2 * * *"
 ```
 
+`reasoning` applies to documentation generation. `auto` preserves provider
+defaults; explicit `off` / `minimal` modes are translated only by providers and
+models that support them, otherwise repowise fails before making an API call.
+
 Full configuration reference: [docs/CONFIG.md](docs/CONFIG.md)
 
 ---

docs/CLI_REFERENCE.md

@@ -50,7 +50,7 @@ In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (
 
 | Flag | Description |
 |------|-------------|
-| `--provider` | LLM provider: `anthropic`, `openai`, `gemini`, `ollama`, `mock` |
+| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `ollama`, `litellm`, `mock` |
 | `--model` | Model name override (e.g., `claude-sonnet-4-6`) |
 | `--embedder` | Embedder for semantic search: `gemini`, `openai`, `mock` |
 | `--index-only` | Skip LLM generation. Only parse, build graph, and index git. Free. |
@@ -61,6 +61,7 @@ In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (
 | `--exclude / -x` | Gitignore-style exclusion patterns. Repeatable. |
 | `--include-submodules` | Include git submodule directories. |
 | `--concurrency` | Max concurrent LLM calls (default: 5). |
+| `--reasoning` | Reasoning mode for supported providers: `auto`, `off`, or `minimal` (default: `auto`). |
 | `--resume` | Resume from the last checkpoint if interrupted. |
 | `--force` | Regenerate all pages even if they exist. |
 | `--commit-limit` | Max commits to analyze per file (default: 500). |
@@ -76,6 +77,8 @@ repowise init --provider anthropic --yes              # automated
 repowise init --index-only                            # free, no LLM
 repowise init --dry-run                               # preview cost
 repowise init --test-run                              # quick test (10 files)
+repowise init --provider openai --model qwen3 --reasoning off
+repowise init --provider openrouter --model openai/gpt-5 --reasoning minimal
 repowise init -x vendor/ -x "*.gen.go"               # exclude patterns
 repowise init --include-submodules                    # include submodules
 repowise init .                                       # workspace mode
@@ -95,6 +98,7 @@ Incrementally update wiki pages for files changed since the last sync.
 | `--provider` | Override LLM provider for this run |
 | `--model` | Override model |
 | `--since` | Git ref to diff from (overrides `state.json`) |
+| `--reasoning` | Reasoning mode for supported providers: `auto`, `off`, or `minimal` |
 | `--cascade-budget` | Max pages to regenerate (default: auto) |
 | `--dry-run` | Show what would be updated without regenerating |
 | `--workspace` | Update all stale repos in the workspace + cross-repo analysis |
@@ -109,6 +113,7 @@ Incrementally update wiki pages for files changed since the last sync.
 repowise update                        # diff since last sync
 repowise update --dry-run              # preview
 repowise update --since v1.0.0         # diff from a tag
+repowise update --reasoning off        # one-off supported-provider thinking-off run
 repowise update --workspace            # all workspace repos (incl. first-time indexing)
 repowise update --repo backend         # specific workspace repo
 repowise update --no-workspace         # force single-repo mode in a workspace root

docs/USER_GUIDE.md

@@ -162,7 +162,7 @@ repowise init [PATH]
 
 | Flag | Description |
 |------|-------------|
-| `--provider` | LLM provider: `anthropic`, `openai`, `gemini`, `ollama`, `mock`. Auto-detected from env vars if not set. |
+| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `ollama`, `litellm`, `mock`. Auto-detected from env vars if not set. |
 | `--model` | Model name override (e.g., `claude-sonnet-4-6`, `gpt-5.4-nano`) |
 | `--embedder` | Embedder for semantic search: `gemini`, `openai`, `mock`. Auto-detected from env vars. |
 | `--index-only` | Skip LLM generation entirely. Only parse, build graph, and index git. Free. |
@@ -172,6 +172,7 @@ repowise init [PATH]
 | `--skip-infra` | Exclude infrastructure files (Dockerfiles, Makefiles, Terraform, shell scripts). |
 | `--exclude / -x` | Gitignore-style exclusion patterns. Repeatable: `-x vendor/ -x "*.generated.*"` |
 | `--concurrency` | Max concurrent LLM calls (default: 5). Higher = faster but more API pressure. |
+| `--reasoning` | Reasoning mode for supported providers: `auto`, `off`, or `minimal` (default: `auto`). |
 | `--resume` | Resume from the last checkpoint if a previous run was interrupted. |
 | `--force` | Regenerate all pages even if they already exist. |
 | `--commit-limit` | Max commits to analyze per file (default: 500, max: 5000). Saved to config. |
@@ -197,6 +198,9 @@ repowise init --provider openai --dry-run
 # Quick test with 10 files
 repowise init --provider gemini --test-run
 
+# OpenRouter with minimal reasoning effort
+repowise init --provider openrouter --model openai/gpt-5 --reasoning minimal
+
 # Exclude vendor and generated code
 repowise init -x vendor/ -x "*.gen.go" -x "**/__generated__/**"
 ```
@@ -228,6 +232,7 @@ Much faster and cheaper than a full `init` — only regenerates pages for change
 | `--provider` | Override LLM provider for this run |
 | `--model` | Override model |
 | `--since` | Git ref to diff from (overrides `state.json`). Example: `--since v1.0.0` |
+| `--reasoning` | Reasoning mode for supported providers: `auto`, `off`, or `minimal`. |
 | `--cascade-budget` | Max pages to regenerate per run (default: 30). Prevents runaway regeneration. |
 | `--dry-run` | Show what would be updated without regenerating. |
 
@@ -246,6 +251,9 @@ repowise update --since v2.0.0
 
 # Limit regeneration scope
 repowise update --cascade-budget 10
+
+# Disable reasoning for a supported provider/model for this run
+repowise update --reasoning off
 ```
 
 ---

docs/architecture/ARCHITECTURE.md

@@ -1617,7 +1617,7 @@ Key files:
 Full configuration with defaults (`.repowise/config.yaml`):
 
 ```yaml
-provider: anthropic          # anthropic | openai | ollama | litellm
+provider: anthropic          # anthropic | openai | openrouter | gemini | deepseek | ollama | litellm | mock
 model: claude-sonnet-4-5    # passed through to the provider
 embedding_provider: anthropic
 embedding_model: voyage-3
@@ -1694,4 +1694,4 @@ rate_limits:
   ollama:
     rpm: 999999
     tpm: 999999
-```
+```

packages/cli/src/repowise/cli/commands/init_cmd.py

@@ -21,6 +21,7 @@
     load_config,
     load_state,
     resolve_provider,
+    resolve_reasoning,
     resolve_repo_path,
     run_async,
     save_config,
@@ -277,7 +278,9 @@ async def _persist_result(
 
         # Record a completed GenerationJob so the web UI can show
         # "last synced" / "last re-indexed" timestamps.
-        from datetime import datetime, UTC as _UTC
+        from datetime import UTC as _UTC
+        from datetime import datetime
+
         from repowise.core.persistence.crud import upsert_generation_job
 
         now = datetime.now(_UTC)
@@ -318,6 +321,7 @@ def _run_workspace_generation(
     skip_tests: bool,
     skip_infra: bool,
     test_run: bool,
+    reasoning: str = "auto",
 ) -> list[Any]:
     """Run LLM generation for a single repo in the workspace init flow.
 
@@ -326,20 +330,28 @@ def _run_workspace_generation(
     workspace run.
     """
     from repowise.cli.cost_estimator import build_generation_plan, estimate_cost
+    from repowise.cli.helpers import get_db_url_for_repo
     from repowise.cli.ui import BRAND, RichProgressCallback
     from repowise.core.generation import GenerationConfig
     from repowise.core.generation.cost_tracker import CostTracker
-    from repowise.core.persistence.vector_store import InMemoryVectorStore
-    from repowise.core.providers.embedding.base import MockEmbedder
-    from repowise.core.pipeline import run_generation
-    from repowise.cli.helpers import get_db_url_for_repo
     from repowise.core.persistence import (
         create_engine as _ce,
+    )
+    from repowise.core.persistence import (
         create_session_factory as _csf,
+    )
+    from repowise.core.persistence import (
         get_session as _gs,
+    )
+    from repowise.core.persistence import (
         init_db as _idb,
+    )
+    from repowise.core.persistence import (
         upsert_repository as _ur,
     )
+    from repowise.core.persistence.vector_store import InMemoryVectorStore
+    from repowise.core.pipeline import run_generation
+    from repowise.core.providers.embedding.base import MockEmbedder
 
     # Build embedder
     embedder_impl: Any
@@ -371,7 +383,10 @@ def _run_workspace_generation(
         vector_store = InMemoryVectorStore(embedder_impl)
 
     # Cost estimate
-    gen_config = GenerationConfig(max_concurrency=concurrency)
+    gen_config = GenerationConfig(
+        max_concurrency=concurrency,
+        reasoning=resolve_reasoning(reasoning),
+    )
     plans = build_generation_plan(
         result.parsed_files, result.graph_builder, gen_config, skip_tests, skip_infra
     )
@@ -475,6 +490,7 @@ def _workspace_init(
     skip_infra: bool = False,
     concurrency: int = 5,
     test_run: bool = False,
+    reasoning: str | None = None,
     yes: bool = False,
     dry_run: bool = False,
     resume: bool = False,
@@ -574,6 +590,7 @@ def _workspace_init(
             if adv.get("exclude"):
                 exclude_patterns = list(exclude_patterns) + list(adv["exclude"])
             test_run = adv.get("test_run", test_run)
+            reasoning = adv.get("reasoning") or reasoning
             embedder_name_resolved = _resolve_embedder(adv.get("embedder") or embedder_name)
         elif not index_only:
             # "full" mode
@@ -582,6 +599,8 @@ def _workspace_init(
             )
 
     # Resolve provider once (shared across all repos for generation)
+    primary_cfg = load_config(primary_repo.path)
+    resolved_reasoning = resolve_reasoning(reasoning, primary_cfg)
     provider = None
     if not index_only:
         try:
@@ -591,6 +610,8 @@ def _workspace_init(
                 f"Model: [cyan]{provider.model_name}[/cyan]"
             )
             console.print(f"  Embedder: [cyan]{embedder_name_resolved}[/cyan]\n")
+            if resolved_reasoning != "auto":
+                console.print(f"  Reasoning: [cyan]{resolved_reasoning}[/cyan]\n")
         except Exception as exc:
             console.print(f"  [yellow]Provider setup failed ({exc}); falling back to index-only.[/yellow]")
             index_only = True
@@ -693,6 +714,7 @@ def _workspace_init(
                         skip_tests=skip_tests,
                         skip_infra=skip_infra,
                         test_run=test_run,
+                        reasoning=resolved_reasoning,
                     )
                     result.generated_pages = generated_pages
                     total_pages += len(generated_pages)
@@ -753,6 +775,7 @@ def _workspace_init(
                 embedder_name_resolved,
                 exclude_patterns=exclude_patterns if exclude_patterns else None,
                 commit_limit=resolved_commit_limit,
+                reasoning=resolved_reasoning,
             )
 
     # Save workspace config with updated timestamps
@@ -867,7 +890,10 @@ def _workspace_init(
     "--provider",
     "provider_name",
     default=None,
-    help="LLM provider name (anthropic, openai, gemini, deepseek, ollama, litellm, mock).",
+    help=(
+        "LLM provider name (anthropic, openai, openrouter, gemini, "
+        "deepseek, ollama, litellm, mock)."
+    ),
 )
 @click.option("--model", default=None, help="Model identifier override.")
 @click.option(
@@ -888,6 +914,12 @@ def _workspace_init(
     "--force", is_flag=True, default=False, help="Regenerate all pages, ignoring existing."
 )
 @click.option("--concurrency", type=int, default=5, help="Max concurrent LLM calls.")
+@click.option(
+    "--reasoning",
+    type=click.Choice(["auto", "off", "minimal"]),
+    default=None,
+    help="Reasoning mode for supported providers: auto, off, or minimal. Default: auto.",
+)
 @click.option(
     "--test-run",
     is_flag=True,
@@ -951,6 +983,7 @@ def init_command(
     resume: bool,
     force: bool,
     concurrency: int,
+    reasoning: str | None,
     test_run: bool,
     index_only: bool,
     exclude: tuple[str, ...],
@@ -1012,6 +1045,7 @@ def init_command(
             skip_tests=skip_tests,
             skip_infra=skip_infra,
             concurrency=concurrency,
+            reasoning=reasoning,
             test_run=test_run,
             yes=yes,
             dry_run=dry_run,
@@ -1073,6 +1107,7 @@ def init_command(
             skip_tests = adv["skip_tests"]
             skip_infra = adv["skip_infra"]
             concurrency = adv["concurrency"]
+            reasoning = adv.get("reasoning") or reasoning
             exclude = adv["exclude"]
             test_run = adv["test_run"]
             embedder_name = adv.get("embedder") or embedder_name
@@ -1090,6 +1125,7 @@ def init_command(
     # Merge exclude_patterns from config.yaml and --exclude/-x flags
     config = load_config(repo_path)
     language = config.get("language", "en")
+    resolved_reasoning = resolve_reasoning(reasoning, config)
     exclude_patterns: list[str] = list(config.get("exclude_patterns") or []) + list(exclude)
 
     # Resolve commit limit: CLI flag → config.yaml → default (500)
@@ -1153,13 +1189,22 @@ def init_command(
         console.print(f"  Embedder: [cyan]{embedder_name_resolved}[/cyan]")
         if language != "en":
             console.print(f"  Language: [cyan]{language}[/cyan]")
+        if resolved_reasoning != "auto":
+            console.print(f"  Reasoning: [cyan]{resolved_reasoning}[/cyan]")
 
         # Validate provider connection
         from repowise.core.providers.llm.base import ProviderError
 
         with console.status("  Verifying provider connection…", spinner="dots"):
             try:
-                run_async(provider.generate("You are a test.", "Reply with OK.", max_tokens=50))
+                run_async(
+                    provider.generate(
+                        "You are a test.",
+                        "Reply with OK.",
+                        max_tokens=50,
+                        reasoning=resolved_reasoning,
+                    )
+                )
             except ProviderError as exc:
                 raise click.ClickException(f"Provider validation failed: {exc}") from exc
         console.print("  [green]✓[/green] Provider connection verified")
@@ -1269,7 +1314,11 @@ def init_command(
 
         # Cost estimation
         from repowise.core.generation import GenerationConfig
-        gen_config = GenerationConfig(max_concurrency=concurrency, language=language)
+        gen_config = GenerationConfig(
+            max_concurrency=concurrency,
+            language=language,
+            reasoning=resolved_reasoning,
+        )
         plans = build_generation_plan(
             result.parsed_files, result.graph_builder, gen_config, skip_tests, skip_infra
         )
@@ -1365,13 +1414,21 @@ def init_command(
                 # is persisted to the llm_costs table.  We need the repo_id from the
                 # database row that was created/upserted during _persist_result
                 # (which has not run yet), so we look it up or fall back to in-memory.
-                from repowise.core.generation.cost_tracker import CostTracker
                 from repowise.cli.helpers import get_db_url_for_repo
+                from repowise.core.generation.cost_tracker import CostTracker
                 from repowise.core.persistence import (
                     create_engine as _create_engine,
+                )
+                from repowise.core.persistence import (
                     create_session_factory as _create_sf,
+                )
+                from repowise.core.persistence import (
                     get_session as _get_session,
+                )
+                from repowise.core.persistence import (
                     init_db as _init_db,
+                )
+                from repowise.core.persistence import (
                     upsert_repository as _upsert_repo,
                 )
 
@@ -1522,6 +1579,7 @@ async def _count_db_pages() -> int:
             embedder_name_resolved,
             exclude_patterns=exclude_patterns if exclude_patterns else None,
             commit_limit=resolved_commit_limit if commit_limit is not None else None,
+            reasoning=resolved_reasoning,
         )
 
     # ---- Completion panel ----