fix(comses): surface PDF/DOCX ODD docs as odd_doc_binary

Smoke test B (FNNR-ABM Python/Mesa model) showed the ODD protocol was
a PDF (docs/FNNR ABM - ODD Protocol with References.pdf). Our old
find_odd_doc only scanned .md/.txt, so open_comses_model returned
odd_doc=null even though a real ODD existed. The AI ended up
summarizing from metadata + DEM header bytes.

- New find_odd_doc_binary: same name patterns as find_odd_doc, but
  for .pdf / .docx / .doc / .odt. Two-pass matching (name prefix,
  then substring) so "FNNR ABM - ODD ..." is caught.
- DownloadOutcome gains odd_doc_binary; wired through _inspect_extracted
  and _outcome_to_payload so both open_comses_model and
  download_comses_model return the path.
- read_comses_files still doesn't try to read PDFs (v1 scope limit) —
  the AI should surface the path from odd_doc_binary so the user can
  open it in a viewer.
- 2 new unit tests + 1 assertion update on the non-NetLogo integration
  test (FNNR-style PDF-only docs).

89 tests pass, lint + mypy clean.

Author: Razee4315

src/netlogo_mcp/comses.py

@@ -585,27 +585,55 @@ def rel_parts(p: Path) -> tuple[str, ...]:
     return candidates[-1]
 
 
-def find_odd_doc(extracted_dir: Path) -> Path | None:
-    """First matching ODD / documentation file, None if none found."""
+_ODD_NAME_PATTERNS = ("ODD", "odd", "documentation", "README", "readme")
+_ODD_TEXT_EXTS = (".md", ".txt")
+_ODD_BINARY_EXTS = (".pdf", ".docx", ".odt", ".doc")
+
+
+def _find_odd_by_exts(extracted_dir: Path, exts: tuple[str, ...]) -> Path | None:
+    """Shared scanner for `find_odd_doc` / `find_odd_doc_binary`."""
     docs_dir = extracted_dir / "docs"
     search_roots = [docs_dir, extracted_dir] if docs_dir.is_dir() else [extracted_dir]
-    # Priority patterns (case-insensitive).
-    patterns = ("ODD", "odd", "documentation", "README", "readme")
     for root in search_roots:
         if not root.is_dir():
             continue
         for p in sorted(root.iterdir(), key=lambda x: x.name):
             if not p.is_file():
                 continue
-            if p.suffix.lower() not in (".md", ".txt"):
+            if p.suffix.lower() not in exts:
                 continue
             name = p.name
-            for pat in patterns:
+            for pat in _ODD_NAME_PATTERNS:
                 if name.startswith(pat):
                     return p
+    # Second pass: match anywhere in the filename (e.g. "FNNR ABM - ODD.pdf").
+    for root in search_roots:
+        if not root.is_dir():
+            continue
+        for p in sorted(root.iterdir(), key=lambda x: x.name):
+            if not p.is_file() or p.suffix.lower() not in exts:
+                continue
+            lower = p.name.lower()
+            if any(pat.lower() in lower for pat in _ODD_NAME_PATTERNS):
+                return p
     return None
 
 
+def find_odd_doc(extracted_dir: Path) -> Path | None:
+    """First matching text ODD / documentation file, None if none found."""
+    return _find_odd_by_exts(extracted_dir, _ODD_TEXT_EXTS)
+
+
+def find_odd_doc_binary(extracted_dir: Path) -> Path | None:
+    """First matching ODD / documentation file in a binary format (PDF/DOCX/etc.).
+
+    Useful so the tool can tell the AI "an ODD exists but is a PDF — the
+    user will need to open it in a viewer." The file itself is NOT read
+    by read_comses_files (v1 scope limit).
+    """
+    return _find_odd_by_exts(extracted_dir, _ODD_BINARY_EXTS)
+
+
 @dataclass
 class DownloadOutcome:
     """Result of a high-level download_release call.
@@ -622,6 +650,7 @@ class DownloadOutcome:
     selected_netlogo_file: Path | None
     code_files: list[Path]
     odd_doc: Path | None
+    odd_doc_binary: Path | None
     license_name: str | None
     title: str | None
 
@@ -737,6 +766,7 @@ def _inspect_extracted(
     selected = select_netlogo_file(netlogo, extracted_path)
     code = find_code_files(extracted_path)
     odd = find_odd_doc(extracted_path)
+    odd_bin = find_odd_doc_binary(extracted_path)
     return DownloadOutcome(
         identifier=identifier,
         resolved_version=resolved_version,
@@ -747,6 +777,7 @@ def _inspect_extracted(
         selected_netlogo_file=selected,
         code_files=code,
         odd_doc=odd,
+        odd_doc_binary=odd_bin,
         license_name=license_name,
         title=title,
     )

src/netlogo_mcp/tools.py

@@ -720,6 +720,9 @@ def _outcome_to_payload(outcome: _comses.DownloadOutcome) -> dict:
         "loaded_netlogo_file": rel(outcome.selected_netlogo_file),
         "code_files": [rel(p) for p in outcome.code_files],
         "odd_doc": rel(outcome.odd_doc),
+        # Non-text ODD (PDF/DOCX) — read_comses_files cannot read it, but
+        # the AI should surface the path so the user can open it manually.
+        "odd_doc_binary": rel(outcome.odd_doc_binary),
     }
 
 

tests/test_comses.py

@@ -473,6 +473,26 @@ def test_find_odd_doc_prefers_odd_then_readme(tmp_path):
     assert found is not None and found.name == "ODD.md"
 
 
+def test_find_odd_doc_binary_picks_up_pdf_with_odd_in_name(tmp_path):
+    """Real-world case from FNNR-ABM smoke test — PDF ODD is the only doc."""
+    (tmp_path / "docs").mkdir()
+    (tmp_path / "docs" / "FNNR ABM - ODD Protocol with References.pdf").write_bytes(
+        b"%PDF-1.4\n"
+    )
+    # Text scanner finds nothing.
+    assert comses.find_odd_doc(tmp_path) is None
+    # Binary scanner finds the PDF.
+    found = comses.find_odd_doc_binary(tmp_path)
+    assert found is not None and found.suffix == ".pdf"
+    assert "ODD" in found.name
+
+
+def test_find_odd_doc_binary_none_when_only_text_docs(tmp_path):
+    (tmp_path / "docs").mkdir()
+    (tmp_path / "docs" / "ODD.md").write_text("odd")
+    assert comses.find_odd_doc_binary(tmp_path) is None
+
+
 # ── High-level download_release + MCP tool ───────────────────────────────────
 
 
@@ -788,7 +808,8 @@ async def test_open_comses_model_non_netlogo_returns_structured_json(
         {
             "code/model.py": b"# python\n",
             "codemeta.json": b'{"programmingLanguage": {"name": "Python"}}',
-            "docs/ODD.md": b"# ODD",
+            # Simulate the FNNR-ABM real case: ODD is a PDF only.
+            "docs/FNNR ABM - ODD Protocol.pdf": b"%PDF-1.4\n",
         },
     )
 
@@ -801,6 +822,11 @@ async def test_open_comses_model_non_netlogo_returns_structured_json(
         mock_context, identifier=identifier, version=version
     )
     data = json.loads(raw)
+    # Binary ODD is surfaced so the AI can tell the user where to read it.
+    assert data["odd_doc"] is None
+    assert data["odd_doc_binary"] is not None
+    assert "ODD" in data["odd_doc_binary"]
+    assert data["odd_doc_binary"].endswith(".pdf")
 
     assert data["status"] == "not_runnable_in_netlogo"
     assert data["language"] == "Python"