fix(comses): language heuristic + tighter read default

Two bugs caught by live end-to-end smoke test in Claude Code:

1. search_comses returned language=null for every result. Real COMSES
   search responses don't include releaseLanguages on nested releases —
   that field only lives on /releases/{v}/?format=json. Added a cheap
   text-heuristic (scan title + description + tags for "netlogo",
   "python", "mesa", etc.) as a fallback. Honest: returns None when no
   hint is present; the authoritative language is on get_comses_model.

2. read_comses_files default max_total_bytes=200_000 blew past the MCP
   harness's per-response token budget on a single 57KB .nlogo file
   (JSON-escaped strings balloon ~25%). Dropped default to 50_000 with
   a docstring note that larger pulls should pass the value explicitly.

2 new tests: direct unit test of _language_hint_from_text, and an
integration test proving search_comses still populates language when
releaseLanguages is absent (real-API shape).

87 tests pass, lint + mypy clean.

Author: Razee4315

src/netlogo_mcp/tools.py

@@ -478,8 +478,12 @@ def _compact_search_result(entry: dict) -> dict:
         if name:
             authors.append(name)
 
-    # Language comes from the latest release's releaseLanguages, if present.
+    # Language: search results don't include releaseLanguages, so we fall back
+    # to a text heuristic over title + description + tags. This is surfaced as
+    # a hint only — the authoritative language lives on get_comses_model.
     language = _language_from_releases(entry.get("releases") or [])
+    if not language:
+        language = _language_hint_from_text(entry)
 
     return {
         "identifier": entry.get("identifier"),
@@ -501,10 +505,16 @@ def _compact_search_result(entry: dict) -> dict:
 
 
 def _language_from_releases(releases: list) -> str | None:
-    """Pick a language name from the release with the latest version, if any."""
+    """Pick a language name from a release detail, if the field is populated.
+
+    Real COMSES search results do NOT include `releaseLanguages` on nested
+    releases — that data is only on `/releases/{version}/?format=json`.
+    This helper still handles the full shape for detail responses and
+    mocked tests; callers that only have search results should also try
+    `_language_hint_from_text`.
+    """
     if not releases:
         return None
-    # Prefer the release flagged as latest, else the last one.
     target = None
     for rel in releases:
         if (rel or {}).get("latestVersion"):
@@ -518,14 +528,44 @@ def _language_from_releases(releases: list) -> str | None:
         name = pl.get("name") or (lang or {}).get("name")
         if name:
             return str(name)
-    # Fallback: programmingLanguageTags[] or platforms[]
     tags = (target or {}).get("programmingLanguageTags") or []
     if tags:
         first = tags[0]
         return first.get("name") if isinstance(first, dict) else str(first)
     return None
 
 
+# Keyword → display name, scanned case-insensitively against title /
+# description / tags. Keep multi-word and ambiguous keywords out of this
+# list so we don't mis-tag ecology models as "R".
+_LANGUAGE_TEXT_HINTS: tuple[tuple[str, str], ...] = (
+    ("netlogo", "NetLogo"),
+    ("mesa", "Python"),
+    ("repast", "Repast"),
+    ("python", "Python"),
+    ("julia", "Julia"),
+    ("matlab", "MATLAB"),
+    ("gama platform", "GAMA"),
+    ("gama-platform", "GAMA"),
+)
+
+
+def _language_hint_from_text(entry: dict) -> str | None:
+    """Cheap heuristic: scan title + description + tags for a known language."""
+    parts: list[str] = [
+        str(entry.get("title") or ""),
+        str(entry.get("summarizedDescription") or ""),
+        str(entry.get("description") or ""),
+    ]
+    for t in entry.get("tags") or []:
+        parts.append(str(t.get("name") if isinstance(t, dict) else t))
+    haystack = " ".join(parts).lower()
+    for needle, label in _LANGUAGE_TEXT_HINTS:
+        if needle in haystack:
+            return label
+    return None
+
+
 @mcp.tool()
 async def search_comses(
     ctx: Context,
@@ -890,7 +930,7 @@ async def read_comses_files(
     identifier: str,
     version: str = "latest",
     extensions: list[str] | None = None,
-    max_total_bytes: int = 200_000,
+    max_total_bytes: int = 50_000,
 ) -> str:
     """Return text contents of source and documentation files from a
     downloaded COMSES model.
@@ -912,10 +952,11 @@ async def read_comses_files(
       a string (may contain replacement characters for non-text bytes).
     - Files are included in priority order: ODD docs → NetLogo source →
       other code → other .md/.txt → everything else matching extensions.
-    - Total body is capped at `max_total_bytes` (default 200 KB). When the
-      cap is hit mid-file, that file is truncated at a line boundary;
-      subsequent files are listed in `omitted_files` with reason
-      `byte_cap_reached`.
+    - Total body is capped at `max_total_bytes` (default 50 KB — sized to
+      fit in a single conversational-LLM tool response). When the cap is
+      hit mid-file, that file is truncated at a line boundary; subsequent
+      files are listed in `omitted_files` with reason `byte_cap_reached`.
+      For larger pulls, pass a higher value explicitly.
     - Files matching no `extensions` filter are listed in `omitted_files`
       with reason `extension_not_in_filter`.
 

tests/test_comses.py

@@ -1004,3 +1004,48 @@ def test_explore_comses_prompt_has_required_rules():
     # Stop-and-ask fallback and no auto-translation.
     assert "Stop-and-ask" in body or "stop-and-ask" in body.lower()
     assert "Do NOT auto-translate" in body or "not auto-translate" in body.lower()
+
+
+# ── Language hint heuristic (real COMSES search results omit releaseLanguages)
+
+
+def test_language_hint_from_title_and_description():
+    from netlogo_mcp.tools import _language_hint_from_text
+
+    assert _language_hint_from_text({"title": "Wolf Sheep Netlogo Model"}) == "NetLogo"
+    assert (
+        _language_hint_from_text({"description": "Implemented in Python using Mesa."})
+        == "Python"
+    )
+    assert _language_hint_from_text({"tags": [{"name": "Repast"}]}) == "Repast"
+    assert _language_hint_from_text({"title": "ecology of wolves"}) is None
+
+
+@pytest.mark.asyncio
+async def test_search_comses_falls_back_to_heuristic_when_release_langs_absent(
+    monkeypatch,
+):
+    """Real COMSES search results don't include releaseLanguages.
+
+    The compact response must still get a language when the text mentions one.
+    """
+    from netlogo_mcp import tools
+
+    stripped = json.loads(json.dumps(_fx("search_result.json")))
+    # Strip releaseLanguages to simulate real API.
+    for r in stripped["results"]:
+        for rel in r.get("releases") or []:
+            rel["releaseLanguages"] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=stripped)
+
+    _patch_client_factory(monkeypatch, handler)
+
+    ctx = MagicMock()
+    raw = await tools.search_comses(ctx, query="x", page=1)
+    data = json.loads(raw)
+    # "Wolf Sheep Predation" + "NetLogo" tag → picked up via heuristic.
+    assert data["results"][0]["language"] == "NetLogo"
+    # Second result has "Python" in tags + description.
+    assert data["results"][1]["language"] == "Python"