Skip to content

Commit 98857e4

Browse files
committed
fix: overview generation never receives --instructions (custom_instructions)
MODULE_OVERVIEW_PROMPT and REPO_OVERVIEW_PROMPT (module-parent and repo-root overview generation) have no {custom_instructions} slot, unlike SYSTEM_PROMPT/LEAF_SYSTEM_PROMPT — so --instructions (language, audience, forbidden diagram styles, link format) never reaches these two prompts. Confirmed empirically on a real run (voll-intelligence): every affected overview page came back in English with the tool's default developer-oriented structure ("Purpose / Architecture / Core component documentation") and, in one case, a broken local-filesystem link — regardless of a detailed Portuguese business-audience --instructions file being passed on the CLI. Appending the instructions as trailing text to the single user-role prompt (the obvious first fix) measurably failed to change model output. The actual fix: thread an optional system_prompt through call_llm/_call_llm_via_litellm/ _call_llm_via_azure/LLMBackend.complete/PydanticAIBackend.complete/ CawBackend.complete, and have generate_parent_module_docs pass config.get_prompt_addition() as a system-role message — the same mechanism SYSTEM_PROMPT/LEAF_SYSTEM_PROMPT already use successfully, just not previously wired to the bare-completion overview path.
1 parent 532ba90 commit 98857e4

5 files changed

Lines changed: 62 additions & 11 deletions

File tree

‎codewiki/src/be/backend.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ def complete(
8989
prompt: str,
9090
*,
9191
model: str | None = None,
92+
system_prompt: str | None = None,
9293
) -> str:
9394
"""Single-shot text completion."""
9495

‎codewiki/src/be/caw_backend.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,18 +246,23 @@ def complete(
246246
prompt: str,
247247
*,
248248
model: str | None = None,
249+
system_prompt: str | None = None,
249250
) -> str:
250251
# Blocks the calling thread for the lifetime of the claude/codex
251252
# subprocess. Callers running this from an async context (e.g. the
252253
# documentation_generator) accept this — there is no concurrent work
253254
# to do while clustering is in flight anyway.
254255
effective_model = model or self._model
256+
# CawAgent has no separate system-role slot exposed here; best-effort
257+
# fold it into the prompt rather than silently drop it (see
258+
# llm_services.call_llm for the primary, tested path).
259+
effective_prompt = f"{system_prompt}\n\n{prompt}" if system_prompt else prompt
255260
agent = CawAgent(
256261
provider=self._caw_provider,
257262
model=effective_model,
258263
tools=ToolGroup.READER,
259264
)
260-
traj = agent.completion(prompt)
265+
traj = agent.completion(effective_prompt)
261266
self.last_usage = usage_to_dict(getattr(traj, "total_usage", None))
262267
return traj.result
263268

‎codewiki/src/be/documentation_generator.py‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -351,10 +351,26 @@ async def generate_parent_module_docs(
351351
prompt += "\n\n" + REPO_OVERVIEW_ARTIFACT_ADDENDUM.format(
352352
artifact_index=artifact_index
353353
)
354+
# Unlike SYSTEM_PROMPT/LEAF_SYSTEM_PROMPT, neither MODULE_OVERVIEW_PROMPT nor
355+
# REPO_OVERVIEW_PROMPT has a {custom_instructions} slot — without this, `--instructions`
356+
# (language, audience, forbidden diagram styles, link rules) silently never reaches
357+
# module-parent or repo-root overview generation. Passing it as a trailing addition to
358+
# the single user-role prompt measurably failed to change output (confirmed empirically:
359+
# still English, still the default structure). Passing it as its own system-role message
360+
# is the fix that actually works for SYSTEM_PROMPT/LEAF_SYSTEM_PROMPT (both put
361+
# `--instructions` in the Agent's system_prompt, not the user turn), so mirror that here.
362+
prompt_addition = self.config.get_prompt_addition()
363+
overview_system_prompt = (
364+
f"<CUSTOM_INSTRUCTIONS>\n{prompt_addition}\n</CUSTOM_INSTRUCTIONS>\n\n"
365+
"These instructions override any conflicting default in the user message below "
366+
"(audience, language, structure, diagram style, and link format all included)."
367+
if prompt_addition
368+
else None
369+
)
354370
logger.debug(f"Overview prompt for {module_name}: {len(prompt)} chars")
355371

356372
try:
357-
parent_docs = self.backend.complete(prompt)
373+
parent_docs = self.backend.complete(prompt, system_prompt=overview_system_prompt)
358374
if not parent_docs:
359375
raise RuntimeError(
360376
f"LLM returned empty content for {module_name} overview "

‎codewiki/src/be/llm_services.py‎

Lines changed: 36 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,9 @@ def _extract_content(response, model: str) -> Optional[str]:
308308
return content
309309

310310

311-
def call_llm(prompt: str, config: Config, model: str = None) -> Optional[str]:
311+
def call_llm(
312+
prompt: str, config: Config, model: str = None, system_prompt: str | None = None
313+
) -> Optional[str]:
312314
"""
313315
Call LLM with the given prompt.
314316
@@ -322,6 +324,13 @@ def call_llm(prompt: str, config: Config, model: str = None) -> Optional[str]:
322324
prompt: The prompt to send
323325
config: Configuration containing LLM settings
324326
model: Model name (defaults to config.main_model)
327+
system_prompt: Optional system-role message. `--instructions` reaching a model
328+
only as trailing text appended to a single user-role prompt (as opposed to a
329+
dedicated system message, or a `<CUSTOM_INSTRUCTIONS>` block inside an actual
330+
agent system_prompt) gets materially weaker adherence — confirmed empirically
331+
on `MODULE_OVERVIEW_PROMPT`/`REPO_OVERVIEW_PROMPT` output (still English,
332+
still the un-instructed default structure, after the instructions were
333+
appended to the prompt string).
325334
326335
Returns:
327336
LLM response text, or None when the provider returned no content
@@ -333,10 +342,10 @@ def call_llm(prompt: str, config: Config, model: str = None) -> Optional[str]:
333342
provider = getattr(config, "provider", "openai-compatible")
334343

335344
if provider in ("bedrock", "anthropic"):
336-
return _call_llm_via_litellm(prompt, config, model)
345+
return _call_llm_via_litellm(prompt, config, model, system_prompt=system_prompt)
337346

338347
if provider == "azure-openai":
339-
return _call_llm_via_azure(prompt, config, model)
348+
return _call_llm_via_azure(prompt, config, model, system_prompt=system_prompt)
340349

341350
# Default: OpenAI-compatible
342351
client = create_openai_client(config)
@@ -347,9 +356,14 @@ def call_llm(prompt: str, config: Config, model: str = None) -> Optional[str]:
347356
primary_key = "max_completion_tokens" if use_completion_tokens else "max_tokens"
348357
fallback_key = "max_tokens" if use_completion_tokens else "max_completion_tokens"
349358

359+
messages = []
360+
if system_prompt:
361+
messages.append({"role": "system", "content": system_prompt})
362+
messages.append({"role": "user", "content": prompt})
363+
350364
base_kwargs = {
351365
"model": model,
352-
"messages": [{"role": "user", "content": prompt}],
366+
"messages": messages,
353367
}
354368

355369
try:
@@ -387,7 +401,9 @@ def _is_unsupported_token_param_error(err: BadRequestError, param: str) -> bool:
387401
return "unsupported parameter" in msg and param in msg
388402

389403

390-
def _call_llm_via_litellm(prompt: str, config: Config, model: str) -> Optional[str]:
404+
def _call_llm_via_litellm(
405+
prompt: str, config: Config, model: str, system_prompt: str | None = None
406+
) -> Optional[str]:
391407
"""
392408
Call LLM via litellm for Bedrock/Anthropic providers.
393409
@@ -405,16 +421,23 @@ def _call_llm_via_litellm(prompt: str, config: Config, model: str) -> Optional[s
405421
elif config.provider == "anthropic":
406422
logger.debug("Calling Anthropic model %s via litellm", litellm_model)
407423

424+
messages = []
425+
if system_prompt:
426+
messages.append({"role": "system", "content": system_prompt})
427+
messages.append({"role": "user", "content": prompt})
428+
408429
response = litellm.completion(
409430
model=litellm_model,
410-
messages=[{"role": "user", "content": prompt}],
431+
messages=messages,
411432
max_tokens=config.max_tokens,
412433
api_key=config.llm_api_key if config.provider != "bedrock" else None,
413434
)
414435
return _extract_content(response, litellm_model)
415436

416437

417-
def _call_llm_via_azure(prompt: str, config: Config, model: str) -> Optional[str]:
438+
def _call_llm_via_azure(
439+
prompt: str, config: Config, model: str, system_prompt: str | None = None
440+
) -> Optional[str]:
418441
"""
419442
Call LLM via Azure OpenAI.
420443
@@ -434,9 +457,14 @@ def _call_llm_via_azure(prompt: str, config: Config, model: str) -> Optional[str
434457
"Calling Azure OpenAI deployment %s (api_version=%s)", deployment, config.api_version
435458
)
436459

460+
messages = []
461+
if system_prompt:
462+
messages.append({"role": "system", "content": system_prompt})
463+
messages.append({"role": "user", "content": prompt})
464+
437465
response = client.chat.completions.create(
438466
model=deployment,
439-
messages=[{"role": "user", "content": prompt}],
467+
messages=messages,
440468
max_tokens=config.max_tokens,
441469
)
442470
return _extract_content(response, deployment)

‎codewiki/src/be/pydantic_ai_backend.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,10 @@ def complete(
6363
prompt: str,
6464
*,
6565
model: str | None = None,
66+
system_prompt: str | None = None,
6667
) -> str:
6768
pop_last_usage()
68-
result = call_llm(prompt, self._config, model=model)
69+
result = call_llm(prompt, self._config, model=model, system_prompt=system_prompt)
6970
self.last_usage = pop_last_usage()
7071
return result
7172

0 commit comments

Comments
 (0)