llama-github 0.4.0__tar.gz → 0.4.2__tar.gz

{llama_github-0.4.0 → llama_github-0.4.2}/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2026-07-15
+
+### Added
+- Added a typed, fixed-cap repository text-read API with distinct success, policy, missing, oversize, binary, directory, and transport outcomes
+- Added explicit `dependency_lock` and `ci_config` opt-ins without changing the legacy `get_file_content()` exclusion or cache contract
+
+### Security
+- Enforced the 2 MiB product cap both from GitHub size metadata and while streaming raw bytes
+- Kept binary, generated, minified, and sensitive paths outside the new opt-in surface
+- Raised the tested `setuptools` and `transformers` lower bounds to versions that clear the current dependency-audit security gate
+
+## [0.4.1] - 2026-07-12
+
+### Added
+- Added status-aware code/issue search APIs that distinguish `ok`, `no_hit`, `partial`, and `error`
+- Added bounded pagination metadata for PR files and comments, plus the captured PR `head_sha`
+- Added exact-head, bounded CI refresh with independently typed status/check-run evidence
+- Added explicit repository-pool shutdown and an option to disable its cleanup worker
+
+### Changed
+- Made the public `GithubRAG` import lazy so retrieval-only consumers do not import the ML/RAG stack
+- Added connect/read timeouts, bounded REST pagination, privacy-safe logging, and immutable revisions for built-in Jina models
+- Bounded related-issue extraction and expansion with configurable limits and truncation metadata
+- Limited related-issue discovery to PR title/body and top-level PR comments, while retaining bare `#123` references in long descriptions
+- Preserved review summaries and every inline review comment as separate chronological interactions
+- Reduced commit-status history to the newest result per logical context while preserving fetched/current counts
+- Raised dependency security floors while keeping the full install and public high-level RAG API compatible
+- Hardened release and secret-scanning workflows with pinned actions, full-history scanning, checksum verification, and job-scoped PyPI OIDC
+- Added a release artifact allowlist that rejects stale or unexplained files in the built wheel
+
+### Fixed
+- Prevented Python AST parsing from being selected for non-Python paths based only on repository language metadata
+- Fixed repository-pool cleanup so expired entries are actually evicted instead of retaining empty objects
+- Fixed `get_pr_content()` so already-fetched PR comments participate in related-issue discovery instead of being processed too late
+
 ## [0.4.0] - 2026-03-25
 
 ### Changed
@@ -157,6 +192,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Integration with LLM for processing and generating responses
 
 [0.1.4]: https://github.com/JetXu-LLM/llama-github/compare/v0.1.3...v0.1.4
+[0.4.2]: https://github.com/JetXu-LLM/llama-github/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/JetXu-LLM/llama-github/compare/v0.4.0...v0.4.1
 [0.1.3]: https://github.com/JetXu-LLM/llama-github/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/JetXu-LLM/llama-github/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/JetXu-LLM/llama-github/compare/v0.1.0...v0.1.1

llama_github-0.4.2/MANIFEST.in

@@ -0,0 +1,6 @@
+include llama_github/config/config.json
+include CHANGELOG.md
+include pytest.ini
+include tests/*.py
+include scripts/*.py
+prune tests/self

{llama_github-0.4.0/llama_github.egg-info → llama_github-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llama-github
-Version: 0.4.0
+Version: 0.4.2
 Summary: GitHub retrieval and context generation utilities for coding assistants and AI developer workflows.
 Author-email: Jet Xu <Voldemort.xu@foxmail.com>
 License-Expression: Apache-2.0
@@ -11,66 +11,38 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyGithub<3,>=2.4
-Requires-Dist: aiohttp<4,>=3.9
-Requires-Dist: ipython<9,>=8
-Requires-Dist: langchain-core<0.4,>=0.3.30
-Requires-Dist: langchain-mistralai<0.3,>=0.2
-Requires-Dist: langchain-openai<0.4,>=0.3.0
-Requires-Dist: langchain-text-splitters<0.4,>=0.3.0
+Requires-Dist: PyJWT[crypto]<3,>=2.13
+Requires-Dist: aiohttp<4,>=3.14.1
+Requires-Dist: ipython<9,>=8.10
+Requires-Dist: langchain-core<2,>=1.3.3
+Requires-Dist: langchain-mistralai<2,>=1.0
+Requires-Dist: langchain-openai<2,>=1.1.14
+Requires-Dist: langchain-text-splitters<2,>=1.1.2
 Requires-Dist: nest-asyncio<2,>=1.6
-Requires-Dist: numpy<3,>=1.24
+Requires-Dist: numpy<3,>=1.26.4
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: python-dateutil<3,>=2.9
-Requires-Dist: requests<3,>=2.31
-Requires-Dist: tokenizers<1,>=0.20
-Requires-Dist: transformers<6,>=4.47
-Requires-Dist: urllib3<3,>=2
+Requires-Dist: requests<3,>=2.33
+Requires-Dist: tokenizers<1,>=0.22.1
+Requires-Dist: transformers<6,>=5.5
+Requires-Dist: urllib3<3,>=2.7
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == "dev"
-Requires-Dist: pytest<9,>=8.3; extra == "dev"
-Requires-Dist: pytest-asyncio<1,>=0.25; extra == "dev"
+Requires-Dist: pip-audit<3,>=2.10; extra == "dev"
+Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=1.3; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
 Dynamic: license-file
 
-
-<div align="right">
-  <details>
-    <summary >🌐 Language</summary>
-    <div>
-      <div align="center">
-        <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=en">English</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=zh-CN">简体中文</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=zh-TW">繁體中文</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ja">日本語</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ko">한국어</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=hi">हिन्दी</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=th">ไทย</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=fr">Français</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=de">Deutsch</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=es">Español</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=it">Italiano</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ru">Русский</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=pt">Português</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=nl">Nederlands</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=pl">Polski</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ar">العربية</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=fa">فارسی</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=tr">Türkçe</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=vi">Tiếng Việt</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=id">Bahasa Indonesia</a>
-      </div>
-    </div>
-  </details>
-</div>
-
 # llama-github
 
-[Detail Document] https://deepwiki.com/JetXu-LLM/llama-github
-
 [![PyPI version](https://badge.fury.io/py/llama-github.svg)](https://badge.fury.io/py/llama-github)
 [![Downloads](https://static.pepy.tech/badge/Llama-github)](https://pepy.tech/project/Llama-github)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -87,7 +59,16 @@ If you like this project or believe it has potential, please give it a ⭐️. Y
 pip install llama-github
 ```
 
-Current maintained runtime target: Python `3.10+`.
+Current maintained runtime target: Python `3.10` through `3.14`.
+
+Version `0.4.2` keeps the existing high-level API while allowing retrieval-only
+integrations to import GitHub and diff helpers without loading the ML/RAG dependency
+stack. Built-in Jina models are pinned to immutable revisions; custom remote-code
+models should provide their own immutable revision. Pull-request retrieval now keeps
+bounded fetch-health metadata, expands related issues only from PR conversation
+evidence, and preserves review summaries plus each inline comment without collapsing
+them together. Deterministic planners can explicitly opt into typed, 2 MiB-capped
+lockfile or CI-config reads without weakening the generic file policy.
 
 ## Usage
 
@@ -112,6 +93,9 @@ contexts = github_rag.retrieve_context(
 
 print(contexts[0]["url"])
 print(contexts[0]["context"])
+
+# Stop the optional repository-cache cleanup worker in long-lived applications.
+github_rag.close()
 ```
 
 `retrieve_context()` returns a list of context dictionaries. Each item contains at least `context` and `url`.

{llama_github-0.4.0 → llama_github-0.4.2}/README.md

@@ -1,38 +1,5 @@
-
-<div align="right">
-  <details>
-    <summary >🌐 Language</summary>
-    <div>
-      <div align="center">
-        <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=en">English</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=zh-CN">简体中文</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=zh-TW">繁體中文</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ja">日本語</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ko">한국어</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=hi">हिन्दी</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=th">ไทย</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=fr">Français</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=de">Deutsch</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=es">Español</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=it">Italiano</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ru">Русский</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=pt">Português</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=nl">Nederlands</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=pl">Polski</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=ar">العربية</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=fa">فارسی</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=tr">Türkçe</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=vi">Tiếng Việt</a>
-        | <a href="https://openaitx.github.io/view.html?user=JetXu-LLM&project=llama-github&lang=id">Bahasa Indonesia</a>
-      </div>
-    </div>
-  </details>
-</div>
-
 # llama-github
 
-[Detail Document] https://deepwiki.com/JetXu-LLM/llama-github
-
 [![PyPI version](https://badge.fury.io/py/llama-github.svg)](https://badge.fury.io/py/llama-github)
 [![Downloads](https://static.pepy.tech/badge/Llama-github)](https://pepy.tech/project/Llama-github)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -49,7 +16,16 @@ If you like this project or believe it has potential, please give it a ⭐️. Y
 pip install llama-github
 ```
 
-Current maintained runtime target: Python `3.10+`.
+Current maintained runtime target: Python `3.10` through `3.14`.
+
+Version `0.4.2` keeps the existing high-level API while allowing retrieval-only
+integrations to import GitHub and diff helpers without loading the ML/RAG dependency
+stack. Built-in Jina models are pinned to immutable revisions; custom remote-code
+models should provide their own immutable revision. Pull-request retrieval now keeps
+bounded fetch-health metadata, expands related issues only from PR conversation
+evidence, and preserves review summaries plus each inline comment without collapsing
+them together. Deterministic planners can explicitly opt into typed, 2 MiB-capped
+lockfile or CI-config reads without weakening the generic file policy.
 
 ## Usage
 
@@ -74,6 +50,9 @@ contexts = github_rag.retrieve_context(
 
 print(contexts[0]["url"])
 print(contexts[0]["context"])
+
+# Stop the optional repository-cache cleanup worker in long-lived applications.
+github_rag.close()
 ```
 
 `retrieve_context()` returns a list of context dictionaries. Each item contains at least `context` and `url`.

llama_github-0.4.2/llama_github/__init__.py

@@ -0,0 +1,20 @@
+"""Public package surface with heavyweight RAG imports loaded on demand."""
+
+from .logger import configure_logging
+from .version import __version__
+
+__all__ = ["GithubRAG", "__version__", "configure_logging"]
+
+
+def __getattr__(name: str):
+    """Preserve ``from llama_github import GithubRAG`` without eager ML imports."""
+    if name == "GithubRAG":
+        from .github_rag import GithubRAG
+
+        return GithubRAG
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    """Expose lazy public attributes to introspection tools."""
+    return sorted(set(globals()) | set(__all__))

{llama_github-0.4.0 → llama_github-0.4.2}/llama_github/config/config.json

@@ -10,12 +10,15 @@
     "default_mistral_model": "mistral-small-latest",
     "default_mistral_simple_model": "mistral-small-latest",
     "default_embedding": "jinaai/jina-embeddings-v2-base-code",
+    "default_embedding_revision": "516f4baf13dec4ddddda8631e019b5737c8bc250",
     "default_reranker": "jinaai/jina-reranker-v2-base-multilingual",
+    "default_reranker_revision": "9cfeff2df7d40d1b78e75e5e9cebec92a99813c9",
     "min_stars_to_keep_result": 20,
     "max_workers": 8,
     "code_search_max_hits": 30,
     "issue_search_max_hits": 30,
     "repo_search_max_hits": 10,
+    "related_issue_max_hits": 20,
     "chunk_size": 2000,
     "issue_chunk_size": 7000,
     "repo_chunk_size": 7000,

llama_github-0.4.2/llama_github/data_retrieval/__init__.py

@@ -0,0 +1,19 @@
+"""Typed retrieval primitives exposed by llama-github."""
+
+from .github_entities import (
+    BoundedTextReadOptIn,
+    BoundedTextReadOutcome,
+    BoundedTextReadResult,
+    CIStatusSnapshot,
+    Repository,
+    RepositoryPool,
+)
+
+__all__ = [
+    "BoundedTextReadOptIn",
+    "BoundedTextReadOutcome",
+    "BoundedTextReadResult",
+    "CIStatusSnapshot",
+    "Repository",
+    "RepositoryPool",
+]

{llama_github-0.4.0 → llama_github-0.4.2}/llama_github/data_retrieval/github_api.py

@@ -2,15 +2,19 @@ from __future__ import annotations
 
 import re
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from typing import Dict, List, Optional
+from typing import Optional
 
 from github import GithubException
 
 from llama_github.config.config import config
-from llama_github.github_integration.github_auth_manager import ExtendedGithub
+from llama_github.github_integration.github_auth_manager import (
+    ExtendedGithub,
+    RetrievalOutcome,
+    RetrievalResult,
+)
 from llama_github.logger import logger
 
-from .github_entities import Repository, RepositoryPool
+from .github_entities import RepositoryPool
 
 
 class GitHubAPIHandler:
@@ -23,8 +27,21 @@ class GitHubAPIHandler:
     ):
         """Create a retrieval helper bound to one GitHub client and one repository pool."""
         self._github = github_instance
+        self._owns_pool = pool is None
         self.pool = pool if pool is not None else RepositoryPool(github_instance)
 
+    def close(self) -> None:
+        """Close the internally-created pool; injected pools remain caller-owned."""
+        if self._owns_pool:
+            self.pool.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+        return False
+
     def _require_github(self) -> ExtendedGithub:
         """Return the configured GitHub client or raise a clear runtime error."""
         if self._github is None:
@@ -59,8 +76,12 @@ class GitHubAPIHandler:
                     )
                 )
             return result
-        except (GithubException, RuntimeError) as exc:
-            logger.exception("Error searching repositories with query '%s': %s", query, exc)
+        except Exception as exc:
+            logger.error(
+                "Repository search failed query_length=%s error_type=%s",
+                len(query or ""),
+                type(exc).__name__,
+            )
             return []
 
     def get_repository(self, full_repo_name, github_instance=None):
@@ -76,20 +97,41 @@ class GitHubAPIHandler:
         file_content = repository_obj.get_file_content(code_search_result["path"])
         return repository_obj, file_content
 
-    def search_code(self, query, repo_full_name=None):
-        """Search GitHub code and expand search hits into ranked file-content records."""
+    def search_code_with_status(self, query, repo_full_name=None) -> RetrievalResult:
+        """Search code and retain fetch status through content expansion."""
         try:
             github = self._require_github()
-            logger.debug("Searching code with query '%s'...", query)
+            logger.debug("Searching code query_length=%s", len(query or ""))
             if repo_full_name:
                 query = f"{query} repo:{repo_full_name}"
 
-            code_results = github.search_code(
-                query=query,
-                per_page=config.get("code_search_max_hits"),
+            status_search = getattr(github, "search_code_with_status", None)
+            raw_result = (
+                status_search(
+                    query=query,
+                    per_page=config.get("code_search_max_hits"),
+                )
+                if callable(status_search)
+                else None
             )
+            if not isinstance(raw_result, RetrievalResult):
+                legacy_items = github.search_code(
+                    query=query,
+                    per_page=config.get("code_search_max_hits"),
+                )
+                raw_result = RetrievalResult(
+                    items=list(legacy_items or []),
+                    outcome=(
+                        RetrievalOutcome.OK
+                        if legacy_items
+                        else RetrievalOutcome.NO_HIT
+                    ),
+                    pages_fetched=1,
+                )
+            code_results = raw_result.items
 
             results_with_index = []
+            content_failures = 0
             with ThreadPoolExecutor(max_workers=config.get("max_workers")) as executor:
                 future_to_index = {
                     executor.submit(self._get_file_content_through_repository, code_result): index
@@ -117,12 +159,54 @@ class GitHubAPIHandler:
                                 }
                             )
                     except Exception:
-                        logger.exception("%s generated an exception:", code_result["name"])
+                        content_failures += 1
+                        logger.error(
+                            "Code-search content expansion failed result_index=%s",
+                            index,
+                        )
 
-            return sorted(results_with_index, key=lambda item: item["index"])
-        except (GithubException, RuntimeError) as exc:
-            logger.exception("Error searching code with query '%s': %s", query, exc)
-            return []
+            items = sorted(results_with_index, key=lambda item: item["index"])
+            missing_content = len(code_results) - len(items)
+            incomplete = raw_result.outcome in {
+                RetrievalOutcome.PARTIAL,
+                RetrievalOutcome.ERROR,
+            } or missing_content > 0
+            if incomplete:
+                outcome = (
+                    RetrievalOutcome.ERROR
+                    if raw_result.outcome is RetrievalOutcome.ERROR and not items
+                    else RetrievalOutcome.PARTIAL
+                )
+            elif items:
+                outcome = RetrievalOutcome.OK
+            else:
+                outcome = RetrievalOutcome.NO_HIT
+            return RetrievalResult(
+                items=items,
+                outcome=outcome,
+                pages_fetched=raw_result.pages_fetched,
+                truncated=raw_result.truncated,
+                status_code=raw_result.status_code,
+                error_type=(
+                    "content_fetch_incomplete"
+                    if missing_content or content_failures
+                    else raw_result.error_type
+                ),
+            )
+        except Exception as exc:
+            logger.error(
+                "Code search failed query_length=%s error_type=%s",
+                len(query or ""),
+                type(exc).__name__,
+            )
+            return RetrievalResult(
+                outcome=RetrievalOutcome.ERROR,
+                error_type=type(exc).__name__,
+            )
+
+    def search_code(self, query, repo_full_name=None):
+        """Compatibility API returning expanded code-search items only."""
+        return self.search_code_with_status(query, repo_full_name).items
 
     def _get_issue_content_through_repository(self, issue):
         """Resolve an issue search hit into the rendered issue-content text block."""
@@ -130,8 +214,7 @@ class GitHubAPIHandler:
         match = re.search(r"https://api.github.com/repos/([^/]+/[^/]+)/issues/(\d+)", issue_url)
         if not match:
             logger.warning(
-                "Failed to extract repo_full_name and issue_number from issue url: %s",
-                issue_url,
+                "Failed to extract repository and issue number from issue URL",
             )
             return None
 
@@ -140,18 +223,39 @@ class GitHubAPIHandler:
         repository_obj = self.get_repository(repo_full_name, github_instance=self._github)
         return repository_obj.get_issue_content(number=issue_number, issue=issue)
 
-    def search_issues(self, query, repo_full_name=None):
-        """Search GitHub issues and expand each result into a normalized issue-content record."""
+    def search_issues_with_status(self, query, repo_full_name=None) -> RetrievalResult:
+        """Search issues and retain fetch status through content expansion."""
         try:
             github = self._require_github()
-            logger.debug("Searching issues with query '%s'...", query)
+            logger.debug("Searching issues query_length=%s", len(query or ""))
             if repo_full_name:
                 query = f"{query} repo:{repo_full_name}"
 
-            issue_results = github.search_issues(
-                query=query,
-                per_page=config.get("issue_search_max_hits"),
+            status_search = getattr(github, "search_issues_with_status", None)
+            raw_result = (
+                status_search(
+                    query=query,
+                    per_page=config.get("issue_search_max_hits"),
+                )
+                if callable(status_search)
+                else None
             )
+            if not isinstance(raw_result, RetrievalResult):
+                legacy_items = github.search_issues(
+                    query=query,
+                    per_page=config.get("issue_search_max_hits"),
+                )
+                raw_result = RetrievalResult(
+                    items=list(legacy_items or []),
+                    outcome=(
+                        RetrievalOutcome.OK
+                        if legacy_items
+                        else RetrievalOutcome.NO_HIT
+                    ),
+                    pages_fetched=1,
+                )
+            raw_issue_count = len(raw_result.items)
+            issue_results = raw_result.items
             issue_results = [
                 issue
                 for issue in issue_results
@@ -159,6 +263,7 @@ class GitHubAPIHandler:
             ]
 
             results_with_index = []
+            content_failures = 0
             with ThreadPoolExecutor(max_workers=config.get("max_workers")) as executor:
                 future_to_index = {
                     executor.submit(self._get_issue_content_through_repository, issue): index
@@ -180,12 +285,54 @@ class GitHubAPIHandler:
                                 }
                             )
                     except Exception:
-                        logger.exception("%s generated an exception:", issue_result["url"])
+                        content_failures += 1
+                        logger.error(
+                            "Issue-search content expansion failed result_index=%s",
+                            index,
+                        )
 
-            return sorted(results_with_index, key=lambda item: item["index"])
-        except (GithubException, RuntimeError) as exc:
-            logger.exception("Error searching issue with query '%s': %s", query, exc)
-            return []
+            items = sorted(results_with_index, key=lambda item: item["index"])
+            missing_content = raw_issue_count - len(items)
+            incomplete = raw_result.outcome in {
+                RetrievalOutcome.PARTIAL,
+                RetrievalOutcome.ERROR,
+            } or missing_content > 0
+            if incomplete:
+                outcome = (
+                    RetrievalOutcome.ERROR
+                    if raw_result.outcome is RetrievalOutcome.ERROR and not items
+                    else RetrievalOutcome.PARTIAL
+                )
+            elif items:
+                outcome = RetrievalOutcome.OK
+            else:
+                outcome = RetrievalOutcome.NO_HIT
+            return RetrievalResult(
+                items=items,
+                outcome=outcome,
+                pages_fetched=raw_result.pages_fetched,
+                truncated=raw_result.truncated,
+                status_code=raw_result.status_code,
+                error_type=(
+                    "content_fetch_incomplete"
+                    if missing_content or content_failures
+                    else raw_result.error_type
+                ),
+            )
+        except Exception as exc:
+            logger.error(
+                "Issue search failed query_length=%s error_type=%s",
+                len(query or ""),
+                type(exc).__name__,
+            )
+            return RetrievalResult(
+                outcome=RetrievalOutcome.ERROR,
+                error_type=type(exc).__name__,
+            )
+
+    def search_issues(self, query, repo_full_name=None):
+        """Compatibility API returning expanded issue-search items only."""
+        return self.search_issues_with_status(query, repo_full_name).items
 
     @staticmethod
     def _categorize_github_url(url):
@@ -209,7 +356,7 @@ class GitHubAPIHandler:
         """Expand a GitHub repository / issue / file URL into text content for retrieval."""
         try:
             self._require_github()
-            logger.debug("Retrieving content from GitHub URL '%s'...", url)
+            logger.debug("Retrieving content from categorized GitHub URL")
             content = None
             category = GitHubAPIHandler._categorize_github_url(url)
             if category == "repo":
@@ -239,5 +386,8 @@ class GitHubAPIHandler:
                 logger.warning("Unsupported GitHub URL category: %s", category)
             return content
         except (GithubException, RuntimeError) as exc:
-            logger.exception("Error retrieving content from GitHub URL '%s': %s", url, exc)
+            logger.error(
+                "GitHub URL retrieval failed error_type=%s",
+                type(exc).__name__,
+            )
             return None