LIANJie-Jason Claude Opus 4.6 commited on
Commit
9815e49
·
1 Parent(s): e5f51c4

fix: harden codebase against format injection, empty responses, and unsafe config access

Browse files

- Add _escape_braces() to all prompt builders to prevent str.format() crash
when user documents contain {placeholder} patterns
- Fix app_web.py display_query fallback to preserve clarification context
- Add empty-response guards to all 3 LLM providers (openai, anthropic, gemini)
- Replace all remaining direct dict access with .get() + defaults
- Add 2 regression tests for curly-brace format injection
- Expand query engine tests with display_query coverage
- 62 tests pass across 13 test files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app_cli.py CHANGED
@@ -99,7 +99,7 @@ def _format_sources(retrieval_result: dict) -> str:
99
  if db_results:
100
  lines.append("Local Sources:")
101
  for i, chunk in enumerate(db_results, 1):
102
- meta = chunk["metadata"]
103
  source = meta.get("source", "unknown")
104
  page = meta.get("page", "?")
105
  dataset = meta.get("dataset", "")
@@ -110,11 +110,11 @@ def _format_sources(retrieval_result: dict) -> str:
110
  lines.append("")
111
  lines.append("Web Sources:")
112
  for i, r in enumerate(web_results, 1):
113
- year_str = f" ({r['year']})" if r.get("year") else ""
114
  lines.append(f" [{i}] {r.get('authors', 'Unknown')}{year_str}. "
115
  f"\"{r.get('title', 'Untitled')}\"")
116
  if r.get("url"):
117
- lines.append(f" {r['url']}")
118
 
119
  return "\n".join(lines)
120
 
@@ -164,7 +164,7 @@ def _handle_model_switch(cfg: dict) -> None:
164
  try:
165
  idx = int(choice) - 1
166
  if 0 <= idx < len(models):
167
- cfg["llm"]["model"] = models[idx]
168
  console.print(f"[green]Model switched to: {models[idx]}[/green]")
169
  else:
170
  console.print("[red]Invalid selection.[/red]")
@@ -274,6 +274,7 @@ def main() -> None:
274
 
275
  original_query = user_input
276
  search_query = user_input
 
277
 
278
  if qu_enabled:
279
  with console.status("[bold blue]Understanding your question...[/bold blue]"):
@@ -284,12 +285,12 @@ def main() -> None:
284
  )
285
  except Exception as e:
286
  console.print(f"[yellow]Query understanding failed, using raw query: {e}[/yellow]")
287
- qu_result = {"action": "search", "search_query": user_input, "original_query": user_input}
288
 
289
  # Handle clarification
290
  clarification_rounds = 0
291
- while qu_result["action"] == "clarify" and clarification_rounds < max_clarifications:
292
- console.print(f"\n[bold yellow]Clarification needed:[/bold yellow] {qu_result['clarification_question']}")
293
  try:
294
  clarification = input("You> ").strip()
295
  except (EOFError, KeyboardInterrupt):
@@ -304,16 +305,15 @@ def main() -> None:
304
  state.get("conversation_history", []),
305
  )
306
  except Exception:
307
- qu_result = {"action": "search", "search_query": combined, "original_query": user_input}
308
  clarification_rounds += 1
309
 
310
  # After max clarification rounds, force search
311
- if qu_result["action"] == "clarify":
312
  qu_result["action"] = "search"
313
- # search_query fallback is already set in _parse_qu_result
314
 
315
  search_query = qu_result.get("search_query", user_input)
316
- original_query = qu_result.get("original_query", user_input)
317
 
318
  # Show reformulated query if different from original
319
  if search_query != user_input:
@@ -332,7 +332,7 @@ def main() -> None:
332
  # ── Generate + verify ───────────────────────────────────────────
333
  with console.status("[bold blue]Generating response...[/bold blue]"):
334
  try:
335
- result = verify_and_respond(original_query, retrieval_result, effective_cfg)
336
  except Exception as e:
337
  console.print(f"[red]Generation error: {e}[/red]")
338
  continue
@@ -341,11 +341,11 @@ def main() -> None:
341
  history = state.get("conversation_history", [])
342
  max_history = qu_cfg.get("max_history", 6)
343
  history.append({"role": "user", "content": user_input})
344
- history.append({"role": "assistant", "content": result["response"]})
345
  state["conversation_history"] = history[-max_history:]
346
 
347
  # ── Display response ─────────────────────────────────────────────
348
- response_text = result["response"]
349
 
350
  # Verification status line
351
  status_parts = []
 
99
  if db_results:
100
  lines.append("Local Sources:")
101
  for i, chunk in enumerate(db_results, 1):
102
+ meta = chunk.get("metadata", {})
103
  source = meta.get("source", "unknown")
104
  page = meta.get("page", "?")
105
  dataset = meta.get("dataset", "")
 
110
  lines.append("")
111
  lines.append("Web Sources:")
112
  for i, r in enumerate(web_results, 1):
113
+ year_str = f" ({r.get('year', '')})" if r.get("year") else ""
114
  lines.append(f" [{i}] {r.get('authors', 'Unknown')}{year_str}. "
115
  f"\"{r.get('title', 'Untitled')}\"")
116
  if r.get("url"):
117
+ lines.append(f" {r.get('url', '')}")
118
 
119
  return "\n".join(lines)
120
 
 
164
  try:
165
  idx = int(choice) - 1
166
  if 0 <= idx < len(models):
167
+ cfg.setdefault("llm", {})["model"] = models[idx]
168
  console.print(f"[green]Model switched to: {models[idx]}[/green]")
169
  else:
170
  console.print("[red]Invalid selection.[/red]")
 
274
 
275
  original_query = user_input
276
  search_query = user_input
277
+ display_query = user_input
278
 
279
  if qu_enabled:
280
  with console.status("[bold blue]Understanding your question...[/bold blue]"):
 
285
  )
286
  except Exception as e:
287
  console.print(f"[yellow]Query understanding failed, using raw query: {e}[/yellow]")
288
+ qu_result = {"action": "search", "search_query": user_input, "display_query": user_input, "original_query": user_input}
289
 
290
  # Handle clarification
291
  clarification_rounds = 0
292
+ while qu_result.get("action") == "clarify" and clarification_rounds < max_clarifications:
293
+ console.print(f"\n[bold yellow]Clarification needed:[/bold yellow] {qu_result.get('clarification_question', 'Could you be more specific?')}")
294
  try:
295
  clarification = input("You> ").strip()
296
  except (EOFError, KeyboardInterrupt):
 
305
  state.get("conversation_history", []),
306
  )
307
  except Exception:
308
+ qu_result = {"action": "search", "search_query": combined, "display_query": combined, "original_query": user_input}
309
  clarification_rounds += 1
310
 
311
  # After max clarification rounds, force search
312
+ if qu_result.get("action") == "clarify":
313
  qu_result["action"] = "search"
 
314
 
315
  search_query = qu_result.get("search_query", user_input)
316
+ display_query = qu_result.get("display_query", user_input)
317
 
318
  # Show reformulated query if different from original
319
  if search_query != user_input:
 
332
  # ── Generate + verify ───────────────────────────────────────────
333
  with console.status("[bold blue]Generating response...[/bold blue]"):
334
  try:
335
+ result = verify_and_respond(display_query, retrieval_result, effective_cfg)
336
  except Exception as e:
337
  console.print(f"[red]Generation error: {e}[/red]")
338
  continue
 
341
  history = state.get("conversation_history", [])
342
  max_history = qu_cfg.get("max_history", 6)
343
  history.append({"role": "user", "content": user_input})
344
+ history.append({"role": "assistant", "content": result.get("response", "")})
345
  state["conversation_history"] = history[-max_history:]
346
 
347
  # ── Display response ─────────────────────────────────────────────
348
+ response_text = result.get("response", "")
349
 
350
  # Verification status line
351
  status_parts = []
app_web.py CHANGED
@@ -153,7 +153,7 @@ def render_chat():
153
  max_history = qu_cfg.get("max_history", 6)
154
 
155
  search_query = combined
156
- response_query = combined # query passed to verify_and_respond
157
  max_clarifications = qu_cfg.get("max_clarifications", 1)
158
 
159
  if qu_enabled:
@@ -167,12 +167,12 @@ def render_chat():
167
  try:
168
  qu_result = understand_query(combined, cfg, history)
169
  except Exception:
170
- qu_result = {"action": "search", "search_query": combined, "original_query": combined}
171
 
172
- if qu_result["action"] == "clarify" and pending is None and max_clarifications > 0:
173
  # Ask clarification — store original query, show question
174
  st.session_state.pending_clarification = original_query
175
- clarification_msg = f"**Before I search, could you clarify?** {qu_result['clarification_question']}"
176
  st.session_state.messages.append(
177
  {"role": "assistant", "content": clarification_msg}
178
  )
@@ -181,16 +181,22 @@ def render_chat():
181
  return
182
 
183
  search_query = qu_result.get("search_query", combined)
 
184
 
185
  # Generate assistant response
186
  with st.chat_message("assistant"):
187
  with st.status("Searching knowledge base...", expanded=True) as status:
188
  # Show reformulated query if different
189
- if search_query != response_query:
190
  status.update(label=f'Searching for: "{search_query}"...')
191
 
192
  # Retrieval
193
- retrieval_result = retrieve(search_query, cfg)
 
 
 
 
 
194
  st.session_state.last_retrieval = retrieval_result
195
 
196
  n_local = len(retrieval_result.get("db_results", []))
@@ -199,16 +205,21 @@ def render_chat():
199
  label=f"Found {n_local} local + {n_web} web sources. Generating response..."
200
  )
201
 
202
- # Verification and response generation (uses combined query
203
- # so the LLM answers the clarified question, not just the original)
204
- result = verify_and_respond(response_query, retrieval_result, cfg)
 
 
 
 
 
205
 
206
  # Update status based on verification outcome
207
  if result.get("refused"):
208
  status.update(label="No sufficient sources found.", state="error")
209
  elif result.get("verification_passed") is True:
210
  status.update(
211
- label=f"Verified ({result['iterations']} iteration(s)). "
212
  f"{n_local} local + {n_web} web sources.",
213
  state="complete",
214
  )
@@ -224,11 +235,11 @@ def render_chat():
224
  )
225
 
226
  # Display the response
227
- st.markdown(result["response"])
228
 
229
  # Store assistant message
230
  st.session_state.messages.append(
231
- {"role": "assistant", "content": result["response"]}
232
  )
233
 
234
 
 
153
  max_history = qu_cfg.get("max_history", 6)
154
 
155
  search_query = combined
156
+ display_query = combined
157
  max_clarifications = qu_cfg.get("max_clarifications", 1)
158
 
159
  if qu_enabled:
 
167
  try:
168
  qu_result = understand_query(combined, cfg, history)
169
  except Exception:
170
+ qu_result = {"action": "search", "search_query": combined, "display_query": combined, "original_query": original_query}
171
 
172
+ if qu_result.get("action") == "clarify" and pending is None and max_clarifications > 0:
173
  # Ask clarification — store original query, show question
174
  st.session_state.pending_clarification = original_query
175
+ clarification_msg = f"**Before I search, could you clarify?** {qu_result.get('clarification_question', 'Could you be more specific?')}"
176
  st.session_state.messages.append(
177
  {"role": "assistant", "content": clarification_msg}
178
  )
 
181
  return
182
 
183
  search_query = qu_result.get("search_query", combined)
184
+ display_query = qu_result.get("display_query", original_query)
185
 
186
  # Generate assistant response
187
  with st.chat_message("assistant"):
188
  with st.status("Searching knowledge base...", expanded=True) as status:
189
  # Show reformulated query if different
190
+ if search_query != original_query:
191
  status.update(label=f'Searching for: "{search_query}"...')
192
 
193
  # Retrieval
194
+ try:
195
+ retrieval_result = retrieve(search_query, cfg)
196
+ except Exception as e:
197
+ status.update(label=f"Retrieval error: {e}", state="error")
198
+ st.error(f"Retrieval failed: {e}")
199
+ return
200
  st.session_state.last_retrieval = retrieval_result
201
 
202
  n_local = len(retrieval_result.get("db_results", []))
 
205
  label=f"Found {n_local} local + {n_web} web sources. Generating response..."
206
  )
207
 
208
+ # Response generation uses display_query — a clear,
209
+ # complete question that incorporates any clarification context
210
+ try:
211
+ result = verify_and_respond(display_query, retrieval_result, cfg)
212
+ except Exception as e:
213
+ status.update(label=f"Generation error: {e}", state="error")
214
+ st.error(f"Response generation failed: {e}")
215
+ return
216
 
217
  # Update status based on verification outcome
218
  if result.get("refused"):
219
  status.update(label="No sufficient sources found.", state="error")
220
  elif result.get("verification_passed") is True:
221
  status.update(
222
+ label=f"Verified ({result.get('iterations', 0)} iteration(s)). "
223
  f"{n_local} local + {n_web} web sources.",
224
  state="complete",
225
  )
 
235
  )
236
 
237
  # Display the response
238
+ st.markdown(result.get("response", ""))
239
 
240
  # Store assistant message
241
  st.session_state.messages.append(
242
+ {"role": "assistant", "content": result.get("response", "")}
243
  )
244
 
245
 
src/config_loader.py CHANGED
@@ -22,7 +22,7 @@ def load_config(config_path: str = None) -> dict:
22
  load_dotenv(str(env_path))
23
 
24
  with open(config_path, "r") as f:
25
- cfg = yaml.safe_load(f)
26
 
27
  for provider, env_var in _ENV_KEY_MAP.items():
28
  env_val = os.environ.get(env_var)
 
22
  load_dotenv(str(env_path))
23
 
24
  with open(config_path, "r") as f:
25
+ cfg = yaml.safe_load(f) or {}
26
 
27
  for provider, env_var in _ENV_KEY_MAP.items():
28
  env_val = os.environ.get(env_var)
src/ingest.py CHANGED
@@ -22,8 +22,9 @@ def split_text_recursive(text: str, chunk_size: int, chunk_overlap: int,
22
 
23
  if _sep_index >= len(separators):
24
  # Last resort: character split
 
25
  chunks = []
26
- for i in range(0, len(text), chunk_size - chunk_overlap):
27
  chunk = text[i:i + chunk_size]
28
  if chunk.strip():
29
  chunks.append(chunk.strip())
@@ -63,14 +64,17 @@ def chunk_documents(pages: list[dict], source_name: str, dataset_name: str,
63
  chunk_size: int = 1000, chunk_overlap: int = 100) -> list[dict]:
64
  """Split pages into smaller chunks with metadata."""
65
  chunks = []
 
66
  for page_info in pages:
67
- text = page_info["text"]
 
 
68
  if len(text) > MAX_CHUNK_CHARS:
69
  splits = split_text_recursive(text, MAX_CHUNK_CHARS, chunk_overlap)
70
  else:
71
  splits = split_text_recursive(text, chunk_size, chunk_overlap)
72
 
73
- for j, split in enumerate(splits):
74
  if len(split) > MAX_CHUNK_CHARS:
75
  split = split[:MAX_CHUNK_CHARS]
76
  chunks.append({
@@ -78,10 +82,11 @@ def chunk_documents(pages: list[dict], source_name: str, dataset_name: str,
78
  "metadata": {
79
  "source": source_name,
80
  "dataset": dataset_name,
81
- "page": str(page_info["page"]),
82
- "chunk_index": j,
83
  },
84
  })
 
85
  return chunks
86
 
87
 
@@ -114,7 +119,8 @@ def get_chroma_collection(cfg: dict):
114
  """Get or create the ChromaDB collection with embeddings."""
115
  db_path = cfg.get("paths", {}).get("vector_db", "chroma_db")
116
  if not os.path.isabs(db_path):
117
- db_path = os.path.join(os.path.dirname(os.path.abspath("config.yaml")), db_path)
 
118
 
119
  client = chromadb.PersistentClient(path=db_path)
120
 
@@ -147,9 +153,8 @@ def ingest_documents(cfg: dict = None, documents_dir: str = None) -> int:
147
  if documents_dir is None:
148
  documents_dir = cfg.get("paths", {}).get("knowledge_base", "knowledge_base")
149
  if not os.path.isabs(documents_dir):
150
- documents_dir = os.path.join(
151
- os.path.dirname(os.path.abspath("config.yaml")), documents_dir
152
- )
153
 
154
  files = discover_files(documents_dir)
155
  if not files:
@@ -176,7 +181,7 @@ def ingest_documents(cfg: dict = None, documents_dir: str = None) -> int:
176
  existing = collection.count()
177
  if existing > 0:
178
  print(f"Clearing {existing} existing chunks...\n")
179
- all_ids = collection.get()["ids"]
180
  if all_ids:
181
  for i in range(0, len(all_ids), 5000):
182
  collection.delete(ids=all_ids[i:i + 5000])
@@ -203,9 +208,9 @@ def ingest_documents(cfg: dict = None, documents_dir: str = None) -> int:
203
  batch_size = 100
204
  for i in range(0, len(chunks), batch_size):
205
  batch = chunks[i:i + batch_size]
206
- ids = [f"{dataset_name}_{file_path.stem}_{i + j}" for j in range(len(batch))]
207
- documents = [c["text"] for c in batch]
208
- metadatas = [c["metadata"] for c in batch]
209
  collection.add(ids=ids, documents=documents, metadatas=metadatas)
210
 
211
  total_chunks += len(chunks)
 
22
 
23
  if _sep_index >= len(separators):
24
  # Last resort: character split
25
+ step = max(1, chunk_size - chunk_overlap)
26
  chunks = []
27
+ for i in range(0, len(text), step):
28
  chunk = text[i:i + chunk_size]
29
  if chunk.strip():
30
  chunks.append(chunk.strip())
 
64
  chunk_size: int = 1000, chunk_overlap: int = 100) -> list[dict]:
65
  """Split pages into smaller chunks with metadata."""
66
  chunks = []
67
+ global_chunk_index = 0
68
  for page_info in pages:
69
+ text = page_info.get("text", "")
70
+ if not text.strip():
71
+ continue
72
  if len(text) > MAX_CHUNK_CHARS:
73
  splits = split_text_recursive(text, MAX_CHUNK_CHARS, chunk_overlap)
74
  else:
75
  splits = split_text_recursive(text, chunk_size, chunk_overlap)
76
 
77
+ for split in splits:
78
  if len(split) > MAX_CHUNK_CHARS:
79
  split = split[:MAX_CHUNK_CHARS]
80
  chunks.append({
 
82
  "metadata": {
83
  "source": source_name,
84
  "dataset": dataset_name,
85
+ "page": str(page_info.get("page", "?")),
86
+ "chunk_index": global_chunk_index,
87
  },
88
  })
89
+ global_chunk_index += 1
90
  return chunks
91
 
92
 
 
119
  """Get or create the ChromaDB collection with embeddings."""
120
  db_path = cfg.get("paths", {}).get("vector_db", "chroma_db")
121
  if not os.path.isabs(db_path):
122
+ project_root = Path(__file__).resolve().parent.parent
123
+ db_path = os.path.join(str(project_root), db_path)
124
 
125
  client = chromadb.PersistentClient(path=db_path)
126
 
 
153
  if documents_dir is None:
154
  documents_dir = cfg.get("paths", {}).get("knowledge_base", "knowledge_base")
155
  if not os.path.isabs(documents_dir):
156
+ project_root = Path(__file__).resolve().parent.parent
157
+ documents_dir = os.path.join(str(project_root), documents_dir)
 
158
 
159
  files = discover_files(documents_dir)
160
  if not files:
 
181
  existing = collection.count()
182
  if existing > 0:
183
  print(f"Clearing {existing} existing chunks...\n")
184
+ all_ids = collection.get().get("ids", [])
185
  if all_ids:
186
  for i in range(0, len(all_ids), 5000):
187
  collection.delete(ids=all_ids[i:i + 5000])
 
208
  batch_size = 100
209
  for i in range(0, len(chunks), batch_size):
210
  batch = chunks[i:i + batch_size]
211
+ ids = [f"{dataset_name}_{file_path.stem}{file_path.suffix}_{i + j}" for j in range(len(batch))]
212
+ documents = [c.get("text", "") for c in batch]
213
+ metadatas = [c.get("metadata", {}) for c in batch]
214
  collection.add(ids=ids, documents=documents, metadatas=metadatas)
215
 
216
  total_chunks += len(chunks)
src/llm/__init__.py CHANGED
@@ -19,7 +19,7 @@ def generate(system_prompt: str, user_message: str, cfg: dict,
19
  api_key = get_api_key(cfg, provider)
20
  if not api_key:
21
  raise ValueError(f"API key not set for {provider}. Set it in .env or config.yaml.")
22
- model = llm_cfg.get("model", "")
23
  temperature = llm_cfg.get("temperature", 0.0)
24
  if max_tokens is None:
25
  max_tokens = llm_cfg.get("max_tokens", 2048)
 
19
  api_key = get_api_key(cfg, provider)
20
  if not api_key:
21
  raise ValueError(f"API key not set for {provider}. Set it in .env or config.yaml.")
22
+ model = llm_cfg.get("model") or ""
23
  temperature = llm_cfg.get("temperature", 0.0)
24
  if max_tokens is None:
25
  max_tokens = llm_cfg.get("max_tokens", 2048)
src/llm/anthropic.py CHANGED
@@ -11,7 +11,9 @@ def generate(system_prompt: str, user_message: str, api_key: str,
11
  system=system_prompt,
12
  messages=[{"role": "user", "content": user_message}],
13
  )
14
- return response.content[0].text
 
 
15
 
16
  def list_models(api_key: str) -> list[str]:
17
  try:
 
11
  system=system_prompt,
12
  messages=[{"role": "user", "content": user_message}],
13
  )
14
+ if not response.content:
15
+ return ""
16
+ return response.content[0].text or ""
17
 
18
  def list_models(api_key: str) -> list[str]:
19
  try:
src/llm/gemini.py CHANGED
@@ -11,7 +11,10 @@ def generate(system_prompt: str, user_message: str, api_key: str,
11
  generation_config=genai.GenerationConfig(temperature=temperature, max_output_tokens=max_tokens),
12
  )
13
  response = gen_model.generate_content(user_message)
14
- return response.text
 
 
 
15
 
16
  def list_models(api_key: str) -> list[str]:
17
  try:
 
11
  generation_config=genai.GenerationConfig(temperature=temperature, max_output_tokens=max_tokens),
12
  )
13
  response = gen_model.generate_content(user_message)
14
+ try:
15
+ return response.text
16
+ except ValueError:
17
+ return ""
18
 
19
  def list_models(api_key: str) -> list[str]:
20
  try:
src/llm/openai.py CHANGED
@@ -13,7 +13,9 @@ def generate(system_prompt: str, user_message: str, api_key: str,
13
  {"role": "user", "content": user_message},
14
  ],
15
  )
16
- return response.choices[0].message.content
 
 
17
 
18
  def list_models(api_key: str) -> list[str]:
19
  try:
 
13
  {"role": "user", "content": user_message},
14
  ],
15
  )
16
+ if not response.choices:
17
+ return ""
18
+ return response.choices[0].message.content or ""
19
 
20
  def list_models(api_key: str) -> list[str]:
21
  try:
src/prompts.py CHANGED
@@ -132,9 +132,13 @@ RULES for SEARCH:
132
  - Expand abbreviations and acronyms (e.g., "HR" -> "human rights")
133
  - Resolve pronouns using conversation history (e.g., "they" -> the entity from prior turn)
134
  - Add relevant domain-specific keywords that would match document content
135
- - Keep the reformulated query concise (15-40 words)
136
  - Preserve the user's original intent -- do NOT change what they're asking about
137
  - If the query is already clear and specific, return it with minimal changes
 
 
 
 
138
 
139
  RULES for CLARIFY:
140
  - ONLY ask for clarification when the question is genuinely ambiguous
@@ -152,7 +156,8 @@ USER'S QUESTION: {query}
152
  Respond in JSON:
153
  {{
154
  "action": "search" or "clarify",
155
- "search_query": "reformulated search query (only if action is search)",
 
156
  "clarification_question": "question to ask (only if action is clarify)",
157
  "reasoning": "one sentence explaining your choice"
158
  }}
@@ -187,11 +192,16 @@ def build_query_understanding_prompt(
187
 
188
  return QUERY_UNDERSTANDING_PROMPT_TEMPLATE.format(
189
  domain=domain,
190
- history=history_str,
191
- query=query,
192
  )
193
 
194
 
 
 
 
 
 
195
  def build_prompt(context: str, bot_name: str, domain: str) -> str:
196
  """Build the system prompt with anti-hallucination guardrails.
197
 
@@ -206,7 +216,7 @@ def build_prompt(context: str, bot_name: str, domain: str) -> str:
206
  return SYSTEM_PROMPT_TEMPLATE.format(
207
  bot_name=bot_name,
208
  domain=domain,
209
- context=context,
210
  )
211
 
212
 
@@ -238,8 +248,8 @@ def build_verification_prompt(
238
  else "No similarity flags detected."
239
  )
240
  return VERIFICATION_PROMPT_TEMPLATE.format(
241
- response=response,
242
- context=context,
243
- phrase_flags=phrase_str,
244
- similarity_flags=similarity_str,
245
  )
 
132
  - Expand abbreviations and acronyms (e.g., "HR" -> "human rights")
133
  - Resolve pronouns using conversation history (e.g., "they" -> the entity from prior turn)
134
  - Add relevant domain-specific keywords that would match document content
135
+ - Keep the reformulated search_query concise (15-40 words)
136
  - Preserve the user's original intent -- do NOT change what they're asking about
137
  - If the query is already clear and specific, return it with minimal changes
138
+ - Also produce a display_query: a clear, complete natural-language question
139
+ that captures the user's full intent (including any clarification context).
140
+ This is the question the AI will actually answer, so it should read like
141
+ a well-formed question a person would ask.
142
 
143
  RULES for CLARIFY:
144
  - ONLY ask for clarification when the question is genuinely ambiguous
 
156
  Respond in JSON:
157
  {{
158
  "action": "search" or "clarify",
159
+ "search_query": "keyword-optimized query for vector search (only if action is search)",
160
+ "display_query": "clear natural-language question for the AI to answer (only if action is search)",
161
  "clarification_question": "question to ask (only if action is clarify)",
162
  "reasoning": "one sentence explaining your choice"
163
  }}
 
192
 
193
  return QUERY_UNDERSTANDING_PROMPT_TEMPLATE.format(
194
  domain=domain,
195
+ history=_escape_braces(history_str),
196
+ query=_escape_braces(query),
197
  )
198
 
199
 
200
+ def _escape_braces(text: str) -> str:
201
+ """Escape curly braces in user-supplied text for safe use with str.format()."""
202
+ return text.replace("{", "{{").replace("}", "}}")
203
+
204
+
205
  def build_prompt(context: str, bot_name: str, domain: str) -> str:
206
  """Build the system prompt with anti-hallucination guardrails.
207
 
 
216
  return SYSTEM_PROMPT_TEMPLATE.format(
217
  bot_name=bot_name,
218
  domain=domain,
219
+ context=_escape_braces(context),
220
  )
221
 
222
 
 
248
  else "No similarity flags detected."
249
  )
250
  return VERIFICATION_PROMPT_TEMPLATE.format(
251
+ response=_escape_braces(response),
252
+ context=_escape_braces(context),
253
+ phrase_flags=_escape_braces(phrase_str),
254
+ similarity_flags=_escape_braces(similarity_str),
255
  )
src/query_engine.py CHANGED
@@ -26,7 +26,8 @@ def understand_query(
26
  Returns:
27
  Dict with keys:
28
  - ``action``: ``"search"`` or ``"clarify"``
29
- - ``search_query``: Reformulated query (always present)
 
30
  - ``original_query``: The raw user input
31
  - ``clarification_question``: Question to ask (only if action is "clarify")
32
  """
@@ -37,6 +38,7 @@ def understand_query(
37
  return {
38
  "action": "search",
39
  "search_query": user_query,
 
40
  "original_query": user_query,
41
  }
42
 
@@ -63,6 +65,7 @@ def understand_query(
63
  result = {
64
  "action": "search",
65
  "search_query": user_query,
 
66
  "original_query": user_query,
67
  }
68
 
@@ -96,6 +99,7 @@ def _parse_qu_result(raw: str, original_query: str) -> dict:
96
  return {
97
  "action": "search",
98
  "search_query": original_query,
 
99
  "original_query": original_query,
100
  }
101
 
@@ -105,6 +109,7 @@ def _parse_qu_result(raw: str, original_query: str) -> dict:
105
  return {
106
  "action": "clarify",
107
  "search_query": original_query, # fallback if clarification is skipped
 
108
  "original_query": original_query,
109
  "clarification_question": parsed.get(
110
  "clarification_question", "Could you be more specific?"
@@ -112,8 +117,11 @@ def _parse_qu_result(raw: str, original_query: str) -> dict:
112
  }
113
 
114
  # action == "search"
 
 
115
  return {
116
  "action": "search",
117
- "search_query": parsed.get("search_query", original_query),
 
118
  "original_query": original_query,
119
  }
 
26
  Returns:
27
  Dict with keys:
28
  - ``action``: ``"search"`` or ``"clarify"``
29
+ - ``search_query``: Keyword-optimized query for retrieval (always present)
30
+ - ``display_query``: Clear natural-language question for response generation
31
  - ``original_query``: The raw user input
32
  - ``clarification_question``: Question to ask (only if action is "clarify")
33
  """
 
38
  return {
39
  "action": "search",
40
  "search_query": user_query,
41
+ "display_query": user_query,
42
  "original_query": user_query,
43
  }
44
 
 
65
  result = {
66
  "action": "search",
67
  "search_query": user_query,
68
+ "display_query": user_query,
69
  "original_query": user_query,
70
  }
71
 
 
99
  return {
100
  "action": "search",
101
  "search_query": original_query,
102
+ "display_query": original_query,
103
  "original_query": original_query,
104
  }
105
 
 
109
  return {
110
  "action": "clarify",
111
  "search_query": original_query, # fallback if clarification is skipped
112
+ "display_query": original_query, # fallback if clarification is skipped
113
  "original_query": original_query,
114
  "clarification_question": parsed.get(
115
  "clarification_question", "Could you be more specific?"
 
117
  }
118
 
119
  # action == "search"
120
+ search_query = parsed.get("search_query", original_query)
121
+ display_query = parsed.get("display_query", original_query)
122
  return {
123
  "action": "search",
124
+ "search_query": search_query,
125
+ "display_query": display_query,
126
  "original_query": original_query,
127
  }
src/readers/docx.py CHANGED
@@ -1,7 +1,8 @@
1
  """Reader for Word .docx files."""
2
- from docx import Document
3
 
4
  def read_docx(file_path: str) -> list[dict]:
 
5
  doc = Document(file_path)
6
  paragraphs = [p.text.strip() for p in doc.paragraphs if p.text.strip()]
7
  if not paragraphs:
 
1
  """Reader for Word .docx files."""
2
+
3
 
4
  def read_docx(file_path: str) -> list[dict]:
5
+ from docx import Document
6
  doc = Document(file_path)
7
  paragraphs = [p.text.strip() for p in doc.paragraphs if p.text.strip()]
8
  if not paragraphs:
src/readers/pdf.py CHANGED
@@ -1,9 +1,8 @@
1
  """Reader for PDF files."""
2
 
3
- from PyPDF2 import PdfReader
4
-
5
 
6
  def read_pdf(file_path: str) -> list[dict]:
 
7
  reader = PdfReader(file_path)
8
  pages = []
9
  for i, page in enumerate(reader.pages):
 
1
  """Reader for PDF files."""
2
 
 
 
3
 
4
  def read_pdf(file_path: str) -> list[dict]:
5
+ from PyPDF2 import PdfReader
6
  reader = PdfReader(file_path)
7
  pages = []
8
  for i, page in enumerate(reader.pages):
src/retriever.py CHANGED
@@ -35,13 +35,16 @@ def retrieve_from_vectordb(query: str, cfg: dict) -> list[dict]:
35
  )
36
 
37
  chunks = []
38
- for i in range(len(results["documents"][0])):
39
- distance = results["distances"][0][i]
 
 
 
40
  if distance > max_distance:
41
  continue
42
  chunks.append({
43
- "text": results["documents"][0][i],
44
- "metadata": results["metadatas"][0][i],
45
  "distance": distance,
46
  })
47
  return chunks
@@ -54,7 +57,7 @@ def format_db_results_as_context(chunks: list[dict]) -> str:
54
 
55
  parts = ["=== Local Document Results (PRIMARY — always trust these over web sources) ===\n"]
56
  for i, chunk in enumerate(chunks, 1):
57
- meta = chunk["metadata"]
58
  dataset = meta.get("dataset", "")
59
  dataset_label = f" [Dataset: {dataset}]" if dataset else ""
60
  source_path = f"knowledge_base/{meta.get('source', 'unknown')}"
@@ -62,7 +65,7 @@ def format_db_results_as_context(chunks: list[dict]) -> str:
62
  f"[CHUNK-LOCAL-{i:03d}] From: {meta.get('source', 'unknown')}, "
63
  f"Page/Section {meta.get('page', '?')}{dataset_label}\n"
64
  f" Path: {source_path}\n"
65
- f" {chunk['text']}\n"
66
  )
67
  return "\n".join(parts)
68
 
 
35
  )
36
 
37
  chunks = []
38
+ documents = results.get("documents", [[]])[0]
39
+ distances = results.get("distances", [[]])[0]
40
+ metadatas = results.get("metadatas", [[]])[0]
41
+ for i in range(len(documents)):
42
+ distance = distances[i]
43
  if distance > max_distance:
44
  continue
45
  chunks.append({
46
+ "text": documents[i],
47
+ "metadata": metadatas[i],
48
  "distance": distance,
49
  })
50
  return chunks
 
57
 
58
  parts = ["=== Local Document Results (PRIMARY — always trust these over web sources) ===\n"]
59
  for i, chunk in enumerate(chunks, 1):
60
+ meta = chunk.get("metadata", {})
61
  dataset = meta.get("dataset", "")
62
  dataset_label = f" [Dataset: {dataset}]" if dataset else ""
63
  source_path = f"knowledge_base/{meta.get('source', 'unknown')}"
 
65
  f"[CHUNK-LOCAL-{i:03d}] From: {meta.get('source', 'unknown')}, "
66
  f"Page/Section {meta.get('page', '?')}{dataset_label}\n"
67
  f" Path: {source_path}\n"
68
+ f" {chunk.get('text', '')}\n"
69
  )
70
  return "\n".join(parts)
71
 
src/search/__init__.py CHANGED
@@ -17,7 +17,7 @@ def format_web_results_as_context(results: list[dict]) -> str:
17
  return ""
18
  parts = ["=== Web Search Results (Academic Papers — SUPPLEMENTARY ONLY) ===\n"]
19
  for i, r in enumerate(results, 1):
20
- year_str = f" ({r['year']})" if r.get("year") else ""
21
  parts.append(
22
  f"[CHUNK-WEB-{i:03d}] From: {r.get('authors', 'Unknown')}{year_str}. \"{r.get('title', 'Untitled')}\"\n"
23
  f" URL: {r.get('url', 'N/A')}\n"
 
17
  return ""
18
  parts = ["=== Web Search Results (Academic Papers — SUPPLEMENTARY ONLY) ===\n"]
19
  for i, r in enumerate(results, 1):
20
+ year_str = f" ({r.get('year', '')})" if r.get("year") else ""
21
  parts.append(
22
  f"[CHUNK-WEB-{i:03d}] From: {r.get('authors', 'Unknown')}{year_str}. \"{r.get('title', 'Untitled')}\"\n"
23
  f" URL: {r.get('url', 'N/A')}\n"
src/search/semantic_scholar.py CHANGED
@@ -40,7 +40,7 @@ def search_papers(query: str, limit: int = 5) -> list[dict]:
40
  url = paper.get("url", "")
41
  external_ids = paper.get("externalIds") or {}
42
  if external_ids.get("DOI"):
43
- url = f"https://doi.org/{external_ids['DOI']}"
44
  results.append({
45
  "title": paper.get("title", "Untitled"), "authors": authors,
46
  "year": paper.get("year"), "abstract": abstract, "url": url,
 
40
  url = paper.get("url", "")
41
  external_ids = paper.get("externalIds") or {}
42
  if external_ids.get("DOI"):
43
+ url = f"https://doi.org/{external_ids.get('DOI', '')}"
44
  results.append({
45
  "title": paper.get("title", "Untitled"), "authors": authors,
46
  "year": paper.get("year"), "abstract": abstract, "url": url,
src/verifier.py CHANGED
@@ -218,7 +218,7 @@ def verify_and_respond(
218
  "iterations": 0,
219
  }
220
 
221
- context = retrieval_result["context"]
222
  bot_name = cfg.get("chatbot", {}).get("name", "ResearchBot")
223
  domain = cfg.get("chatbot", {}).get("domain", "research")
224
  llm_cfg = cfg.get("llm", {})
@@ -279,51 +279,9 @@ def verify_and_respond(
279
  # Verification failed — attempt correction
280
  error_count = vr.get("error_count", len(vr.get("errors", [])))
281
 
282
- if iteration == 1 and error_count <= 2:
283
- # Minor errors on first try: correct once, then re-verify
284
- correction_prompt = (
285
- f"Your previous response had {error_count} verification "
286
- f"error(s):\n"
287
- + json.dumps(vr.get("errors", []), indent=2)
288
- + "\n\nRewrite your response to fix these issues. "
289
- "Use ONLY the provided context. Keep all citation rules."
290
- )
291
- response = generate(
292
- system_prompt, correction_prompt, cfg, max_tokens=soft_max
293
- )
294
- # Re-verify the correction
295
- phrase_flags_2 = scan_warning_phrases(response)
296
- sim_flags_2 = compute_similarity_flags(response, context, cfg)
297
- vp2 = build_verification_prompt(
298
- response,
299
- context,
300
- [f["message"] for f in phrase_flags_2],
301
- [f["message"] for f in sim_flags_2],
302
- )
303
- raw2 = generate(
304
- "You are a strict verification agent. Return only JSON.",
305
- vp2,
306
- cfg,
307
- max_tokens=1024,
308
- )
309
- vr2 = parse_verification_result(raw2)
310
- if vr2.get("pass", False):
311
- return {
312
- "response": response,
313
- "refused": False,
314
- "verification_passed": True,
315
- "iterations": iteration,
316
- }
317
- # Correction did not pass — refuse
318
- return {
319
- "response": REFUSAL_AFTER_VERIFICATION,
320
- "refused": True,
321
- "verification_passed": False,
322
- "iterations": iteration,
323
- }
324
-
325
- # More than 2 errors or subsequent iterations: correct and loop
326
  correction_prompt = (
 
327
  f"Your previous response failed verification with "
328
  f"{error_count} error(s):\n"
329
  + json.dumps(vr.get("errors", []), indent=2)
 
218
  "iterations": 0,
219
  }
220
 
221
+ context = retrieval_result.get("context", "")
222
  bot_name = cfg.get("chatbot", {}).get("name", "ResearchBot")
223
  domain = cfg.get("chatbot", {}).get("domain", "research")
224
  llm_cfg = cfg.get("llm", {})
 
279
  # Verification failed — attempt correction
280
  error_count = vr.get("error_count", len(vr.get("errors", [])))
281
 
282
+ # Correct and loop for re-verification
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
283
  correction_prompt = (
284
+ f"The user's original question was: {query}\n\n"
285
  f"Your previous response failed verification with "
286
  f"{error_count} error(s):\n"
287
  + json.dumps(vr.get("errors", []), indent=2)
tests/test_prompts.py CHANGED
@@ -57,3 +57,26 @@ def test_build_query_understanding_prompt_no_history():
57
  prompt = build_query_understanding_prompt("test query", "research", [])
58
  assert "No prior conversation" in prompt
59
  assert "test query" in prompt
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
57
  prompt = build_query_understanding_prompt("test query", "research", [])
58
  assert "No prior conversation" in prompt
59
  assert "test query" in prompt
60
+
61
+
62
+ def test_build_prompt_with_curly_braces_in_context():
63
+ """Regression: context containing {placeholder} must not crash str.format()."""
64
+ from src.prompts import build_prompt
65
+ context = "The variable {unknown_var} was set to {value}."
66
+ prompt = build_prompt(context, "Bot", "testing")
67
+ assert "{unknown_var}" in prompt
68
+ assert "{value}" in prompt
69
+
70
+
71
+ def test_build_verification_prompt_with_curly_braces():
72
+ """Regression: braces in response/context must not crash str.format()."""
73
+ from src.prompts import build_verification_prompt
74
+ prompt = build_verification_prompt(
75
+ "The {result} showed improvement.",
76
+ "Data: {raw_value} was recorded.",
77
+ ["flag with {braces}"],
78
+ [],
79
+ )
80
+ assert "{result}" in prompt
81
+ assert "{raw_value}" in prompt
82
+ assert "{braces}" in prompt
tests/test_query_engine.py CHANGED
@@ -22,6 +22,7 @@ def _mock_generate_search(system_prompt, user_message, cfg, **kwargs):
22
  return json.dumps({
23
  "action": "search",
24
  "search_query": "reformulated test query about human rights",
 
25
  "reasoning": "expanded for better retrieval",
26
  })
27
 
@@ -46,6 +47,7 @@ def test_understand_query_reformulates():
46
  result = understand_query("test query", _make_cfg())
47
  assert result["action"] == "search"
48
  assert result["search_query"] == "reformulated test query about human rights"
 
49
  assert result["original_query"] == "test query"
50
 
51
 
@@ -56,8 +58,9 @@ def test_understand_query_clarifies():
56
  assert result["action"] == "clarify"
57
  assert "clarification_question" in result
58
  assert result["original_query"] == "AI"
59
- # search_query should still be present as fallback
60
  assert "search_query" in result
 
61
 
62
 
63
  def test_understand_query_preserves_original():
@@ -84,6 +87,7 @@ def test_understand_query_disabled():
84
  result = understand_query("test query", _make_cfg(enabled=False))
85
  assert result["action"] == "search"
86
  assert result["search_query"] == "test query"
 
87
  assert result["original_query"] == "test query"
88
 
89
 
@@ -93,6 +97,7 @@ def test_understand_query_fallback_on_error():
93
  result = understand_query("test query", _make_cfg())
94
  assert result["action"] == "search"
95
  assert result["search_query"] == "test query"
 
96
 
97
 
98
  def test_parse_qu_result_malformed_json():
@@ -100,6 +105,7 @@ def test_parse_qu_result_malformed_json():
100
  result = _parse_qu_result("not json at all", "original query")
101
  assert result["action"] == "search"
102
  assert result["search_query"] == "original query"
 
103
 
104
 
105
  def test_parse_qu_result_embedded_json():
@@ -108,3 +114,19 @@ def test_parse_qu_result_embedded_json():
108
  result = _parse_qu_result(raw, "original")
109
  assert result["action"] == "search"
110
  assert result["search_query"] == "better query"
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
22
  return json.dumps({
23
  "action": "search",
24
  "search_query": "reformulated test query about human rights",
25
+ "display_query": "What are the key human rights issues in this test query?",
26
  "reasoning": "expanded for better retrieval",
27
  })
28
 
 
47
  result = understand_query("test query", _make_cfg())
48
  assert result["action"] == "search"
49
  assert result["search_query"] == "reformulated test query about human rights"
50
+ assert result["display_query"] == "What are the key human rights issues in this test query?"
51
  assert result["original_query"] == "test query"
52
 
53
 
 
58
  assert result["action"] == "clarify"
59
  assert "clarification_question" in result
60
  assert result["original_query"] == "AI"
61
+ # search_query and display_query should still be present as fallback
62
  assert "search_query" in result
63
+ assert "display_query" in result
64
 
65
 
66
  def test_understand_query_preserves_original():
 
87
  result = understand_query("test query", _make_cfg(enabled=False))
88
  assert result["action"] == "search"
89
  assert result["search_query"] == "test query"
90
+ assert result["display_query"] == "test query"
91
  assert result["original_query"] == "test query"
92
 
93
 
 
97
  result = understand_query("test query", _make_cfg())
98
  assert result["action"] == "search"
99
  assert result["search_query"] == "test query"
100
+ assert result["display_query"] == "test query"
101
 
102
 
103
  def test_parse_qu_result_malformed_json():
 
105
  result = _parse_qu_result("not json at all", "original query")
106
  assert result["action"] == "search"
107
  assert result["search_query"] == "original query"
108
+ assert result["display_query"] == "original query"
109
 
110
 
111
  def test_parse_qu_result_embedded_json():
 
114
  result = _parse_qu_result(raw, "original")
115
  assert result["action"] == "search"
116
  assert result["search_query"] == "better query"
117
+ # display_query falls back to original when not in JSON
118
+ assert result["display_query"] == "original"
119
+
120
+
121
+ def test_parse_qu_result_with_display_query():
122
+ from src.query_engine import _parse_qu_result
123
+ raw = json.dumps({
124
+ "action": "search",
125
+ "search_query": "keyword optimized query",
126
+ "display_query": "What is the effect of AI on human rights?",
127
+ "reasoning": "clarified and expanded",
128
+ })
129
+ result = _parse_qu_result(raw, "AI human rights")
130
+ assert result["search_query"] == "keyword optimized query"
131
+ assert result["display_query"] == "What is the effect of AI on human rights?"
132
+ assert result["original_query"] == "AI human rights"
tests/test_readers_docx_excel_csv.py CHANGED
@@ -1,6 +1,7 @@
1
  import pytest
2
 
3
  def test_docx_reader(tmp_path):
 
4
  from docx import Document
5
  doc = Document()
6
  doc.add_paragraph("First paragraph of the document.")
@@ -13,6 +14,7 @@ def test_docx_reader(tmp_path):
13
  assert "First paragraph" in pages[0]["text"]
14
 
15
  def test_xlsx_reader(tmp_path):
 
16
  import openpyxl
17
  wb = openpyxl.Workbook()
18
  ws = wb.active
 
1
  import pytest
2
 
3
  def test_docx_reader(tmp_path):
4
+ pytest.importorskip("docx")
5
  from docx import Document
6
  doc = Document()
7
  doc.add_paragraph("First paragraph of the document.")
 
14
  assert "First paragraph" in pages[0]["text"]
15
 
16
  def test_xlsx_reader(tmp_path):
17
+ pytest.importorskip("openpyxl")
18
  import openpyxl
19
  wb = openpyxl.Workbook()
20
  ws = wb.active