FAQ / Troubleshooting
Q: Why did my strategy="simple" get overridden?
PromptBuilder._resolve_strategy only treats a non-default explicit strategy as an override. Because SIMPLE is itself the dataclass default, passing it explicitly is indistinguishable from omitting it, and the type-based default table still applies. See api/builder.
Q: Why does my prompt still contain "Think step by step" guardrail text even though I set enable_guardrails=False?
SHOW_REASONING and SELF_CHECK are added by strategy/complexity, independent of enable_guardrails. SAFE_OUTPUT and CONCISE are always-on regardless of the flag. See api/guardrails.
Q: Why is my conversation history missing from user_prompt under strategy="self_consistent" (or step_back/least_to_most)?
Those three strategies' _build_user implementations never read the memory_block argument. History is only surfaced via the raw Message objects appended in messages (last 10), not in the flattened text. See api/strategies.
Q: Does max_answer_tokens actually limit the model's response length?
No — it's stored on the request but never read elsewhere in the provided source. See Configuration.
Q: Does ContextManager(summarize_overflow=True) summarize overflowing documents?
No — the flag is declared but unused; overflow always results in truncation, never summarization. See api/context_manager.
Q: Is the token counting accurate?
No — every token count in the library (context_manager._count_tokens, optimizer._tok, strategies._estimate_tokens) uses the same rough heuristic, int(len(text.split()) * 1.3), independently reimplemented in each module rather than shared. This is explicitly noted as a placeholder in the source comments ("swap for tiktoken in production"). Treat estimated_tokens and related fields as approximations, not exact counts.
Q: Is PromptEngine safe to share across threads?
No explicit thread-safety guarantee exists anywhere in the source, and mutable state (_cache, _metrics, _trace_log, _feedback) is updated without locks. See api/prompt_engine.md#thread-safety.
Q: Can I get a French/Spanish/German native prompt like Arabic?
Not natively. Only English and Arabic have authored templates; any other language value falls back to English plus a "Respond in <language>." line. See api/templates.
Q: What happens if I pass an invalid strategy/type/format string?
PromptEngine.build() raises a standard ValueError from Python's Enum(value) constructor (e.g. 'not_real' is not a valid PromptStrategy). See api/prompt_engine.
Q: Does the library make any network or file-system calls?
No — everything in prompt/* is pure in-memory string/data processing except for calls the caller makes to their own injected llm/judge_llm/rag_system objects inside ab_testing. PromptEngine itself never calls an LLM.