feat: doc type in index.md, remove list_files from query agent, source backlink for short docs

- index.md entries now show (short) or (pageindex) type marker
- Query agent prompt updated: guides agent to read sources for detail
- Removed list_files tool from query agent (index.md is sufficient)
- Short doc summaries now have source_doc frontmatter linking to sources/
- Reverted list_wiki_files to only list .md files
- Fixed tests for model name change and agent tool count

Author: KylinMountain

openkb/agent/compiler.py

@@ -289,13 +289,20 @@ def _find_source_filename(doc_name: str, kb_dir: Path) -> str:
     return f"{doc_name}.pdf"
 
 
-def _write_summary(wiki_dir: Path, doc_name: str, source_file: str, summary: str, brief: str = "") -> None:
-    """Write summary page with frontmatter."""
+def _write_summary(wiki_dir: Path, doc_name: str, source_file: str, summary: str,
+                    brief: str = "", doc_type: str = "short") -> None:
+    """Write summary page with frontmatter.
+
+    For short docs, includes a ``source_doc`` field linking to the full
+    source text in ``sources/{doc_name}.md``.
+    """
     summaries_dir = wiki_dir / "summaries"
     summaries_dir.mkdir(parents=True, exist_ok=True)
     fm_lines = [f"sources: [{source_file}]"]
     if brief:
         fm_lines.append(f"brief: {brief}")
+    if doc_type == "short":
+        fm_lines.append(f"source_doc: sources/{doc_name}.md")
     frontmatter = "---\n" + "\n".join(fm_lines) + "\n---\n\n"
     (summaries_dir / f"{doc_name}.md").write_text(frontmatter + summary, encoding="utf-8")
 
@@ -442,12 +449,15 @@ def _backlink_concepts(wiki_dir: Path, doc_name: str, concept_slugs: list[str])
 def _update_index(
     wiki_dir: Path, doc_name: str, concept_names: list[str],
     doc_brief: str = "", concept_briefs: dict[str, str] | None = None,
+    doc_type: str = "short",
 ) -> None:
     """Append document and concept entries to index.md.
 
     When ``doc_brief`` or entries in ``concept_briefs`` are provided, entries
-    are written as ``- [[link]] — brief text``.  Existing entries are detected
-    by the link part only, so updating a brief on a re-compile works correctly.
+    are written as ``- [[link]] (type) — brief text``.  Existing entries are
+    detected by the link part only, so updating a brief on a re-compile works.
+    ``doc_type`` is ``"short"`` or ``"pageindex"`` — shown in the entry so the
+    query agent knows how to access detailed content.
     """
     if concept_briefs is None:
         concept_briefs = {}
@@ -463,7 +473,7 @@ def _update_index(
 
     doc_link = f"[[summaries/{doc_name}]]"
     if doc_link not in text:
-        doc_entry = f"- {doc_link}"
+        doc_entry = f"- {doc_link} ({doc_type})"
         if doc_brief:
             doc_entry += f" — {doc_brief}"
         if "## Documents" in text:
@@ -498,6 +508,7 @@ async def _compile_concepts(
     doc_name: str,
     max_concurrency: int,
     doc_brief: str = "",
+    doc_type: str = "short",
 ) -> None:
     """Shared Steps 2-4: concepts plan → generate/update → index.
 
@@ -635,7 +646,8 @@ async def _gen_update(concept: dict) -> tuple[str, str, bool, str]:
 
     # --- Step 4: Update index (code only) ---
     _update_index(wiki_dir, doc_name, concept_names,
-                  doc_brief=doc_brief, concept_briefs=concept_briefs_map)
+                  doc_brief=doc_brief, concept_briefs=concept_briefs_map,
+                  doc_type=doc_type)
 
 
 async def compile_short_doc(
@@ -684,6 +696,7 @@ async def compile_short_doc(
     await _compile_concepts(
         wiki_dir, kb_dir, model, system_msg, doc_msg,
         summary, doc_name, max_concurrency, doc_brief=doc_brief,
+        doc_type="short",
     )
 
 
@@ -726,4 +739,5 @@ async def compile_long_doc(
     await _compile_concepts(
         wiki_dir, kb_dir, model, system_msg, doc_msg,
         overview, doc_name, max_concurrency, doc_brief=doc_description,
+        doc_type="pageindex",
     )

openkb/agent/query.py

@@ -5,27 +5,27 @@
 
 from agents import Agent, Runner, function_tool
 
-from openkb.agent.tools import list_wiki_files, read_wiki_file
-from openkb.schema import SCHEMA_MD, get_agents_md
+from openkb.agent.tools import read_wiki_file
+from openkb.schema import get_agents_md
 
 _QUERY_INSTRUCTIONS_TEMPLATE = """\
 You are a knowledge-base Q&A agent. You answer questions by searching the wiki.
 
 {schema_md}
 
 ## Search strategy
-1. Read index.md to understand what documents and concepts are available.
-   Each entry has a brief summary to help you judge relevance.
+1. Read index.md to see all documents and concepts with brief summaries.
+   Each document is marked (short) or (pageindex) to indicate its type.
 2. Read relevant summary pages (summaries/) for document overviews.
 3. Read concept pages (concepts/) for cross-document synthesis.
-4. For long documents, use get_page_content(doc_name, pages) to read
-   specific pages when you need detailed content. The summary page
-   shows chapter structure with page ranges to help you decide which
-   pages to read.
-5. Synthesise a clear, well-cited answer.
-
-Always ground your answer in the wiki content. If you cannot find relevant
-information, say so clearly.
+4. When you need detailed source content:
+   - Short documents: read_file("sources/{{doc_name}}.md") for the full text.
+   - PageIndex documents: use get_page_content(doc_name, pages) to read
+     specific pages. The summary page shows chapter structure with page
+     ranges to help you decide which pages to read.
+5. Synthesise a clear, well-cited answer grounded in wiki content.
+
+If you cannot find relevant information, say so clearly.
 """
 
 
@@ -35,14 +35,6 @@ def build_query_agent(wiki_root: str, model: str, language: str = "en") -> Agent
     instructions = _QUERY_INSTRUCTIONS_TEMPLATE.format(schema_md=schema_md)
     instructions += f"\n\nIMPORTANT: Write all wiki content in {language} language."
 
-    @function_tool
-    def list_files(directory: str) -> str:
-        """List all Markdown files in a wiki subdirectory.
-        Args:
-            directory: Subdirectory path relative to wiki root (e.g. 'sources').
-        """
-        return list_wiki_files(directory, wiki_root)
-
     @function_tool
     def read_file(path: str) -> str:
         """Read a Markdown file from the wiki.
@@ -68,7 +60,7 @@ def get_page_content_tool(doc_name: str, pages: str) -> str:
     return Agent(
         name="wiki-query",
         instructions=instructions,
-        tools=[list_files, read_file, get_page_content_tool],
+        tools=[read_file, get_page_content_tool],
         model=f"litellm/{model}",
         model_settings=ModelSettings(parallel_tool_calls=False),
     )

tests/test_compiler.py

@@ -160,7 +160,7 @@ def test_appends_entries_with_briefs(self, tmp_path):
                        doc_brief="Introduces transformers",
                        concept_briefs={"attention": "Focus mechanism", "transformer": "NN architecture"})
         text = (wiki / "index.md").read_text()
-        assert "[[summaries/my-doc]] — Introduces transformers" in text
+        assert "[[summaries/my-doc]] (short) — Introduces transformers" in text
         assert "[[concepts/attention]] — Focus mechanism" in text
         assert "[[concepts/transformer]] — NN architecture" in text
 

tests/test_config.py

@@ -10,7 +10,7 @@ def test_default_config_keys():
 
 
 def test_default_config_values():
-    assert DEFAULT_CONFIG["model"] == "gpt-5.4"
+    assert DEFAULT_CONFIG["model"] == "gpt-5.4-mini"
     assert DEFAULT_CONFIG["language"] == "en"
     assert DEFAULT_CONFIG["pageindex_threshold"] == 20
 

tests/test_query.py

@@ -15,16 +15,16 @@ def test_agent_name(self, tmp_path):
         agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
         assert agent.name == "wiki-query"
 
-    def test_agent_has_three_tools(self, tmp_path):
+    def test_agent_has_two_tools(self, tmp_path):
         agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
-        assert len(agent.tools) == 3
+        assert len(agent.tools) == 2
 
     def test_agent_tool_names(self, tmp_path):
         agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
         names = {t.name for t in agent.tools}
-        assert "list_files" in names
         assert "read_file" in names
         assert "get_page_content_tool" in names
+        assert "list_files" not in names
         assert "pageindex_retrieve" not in names
 
     def test_instructions_mention_get_page_content(self, tmp_path):