llama-github 0.4.1__tar.gz → 0.4.3__tar.gz

{llama_github-0.4.1 → llama_github-0.4.3}/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.3] - 2026-07-15
+
+### Fixed
+- Aligned the `dependency_lock` opt-in with the complete standard lockfile family used by bounded review planning, including `go.sum`, `gradle.lockfile`, `packages.lock.json`, and ecosystem peers
+- Aligned the `ci_config` opt-in with the existing bounded CI path family, including AppVeyor configuration
+
+## [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
@@ -181,6 +198,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.3]: https://github.com/JetXu-LLM/llama-github/compare/v0.4.2...v0.4.3
+[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

{llama_github-0.4.1/llama_github.egg-info → llama_github-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llama-github
-Version: 0.4.1
+Version: 0.4.3
 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
@@ -31,7 +31,7 @@ Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: python-dateutil<3,>=2.9
 Requires-Dist: requests<3,>=2.33
 Requires-Dist: tokenizers<1,>=0.22.1
-Requires-Dist: transformers<6,>=5.3
+Requires-Dist: transformers<6,>=5.5
 Requires-Dist: urllib3<3,>=2.7
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == "dev"
@@ -61,13 +61,14 @@ pip install llama-github
 
 Current maintained runtime target: Python `3.10` through `3.14`.
 
-Version `0.4.1` keeps the existing high-level API while allowing retrieval-only
+Version `0.4.3` 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.
+them together. Deterministic planners can explicitly opt into typed, 2 MiB-capped
+lockfile or CI-config reads without weakening the generic file policy.
 
 ## Usage
 

{llama_github-0.4.1 → llama_github-0.4.3}/README.md

@@ -18,13 +18,14 @@ pip install llama-github
 
 Current maintained runtime target: Python `3.10` through `3.14`.
 
-Version `0.4.1` keeps the existing high-level API while allowing retrieval-only
+Version `0.4.3` 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.
+them together. Deterministic planners can explicitly opt into typed, 2 MiB-capped
+lockfile or CI-config reads without weakening the generic file policy.
 
 ## Usage
 

llama_github-0.4.3/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.1 → llama_github-0.4.3}/llama_github/data_retrieval/github_entities.py

@@ -2,6 +2,7 @@ from github import GithubException
 from threading import Lock, Event, Thread
 from datetime import datetime, timezone
 from dataclasses import dataclass, field
+from enum import Enum
 
 from typing import Optional, Dict, Any, List, Callable
 from llama_github.logger import logger
@@ -18,10 +19,167 @@ import requests
 from llama_github.config.config import config
 from llama_github.utils import DiffGenerator, CodeAnalyzer
 
-__all__ = ["CIStatusSnapshot", "Repository", "RepositoryPool"]
+__all__ = [
+    "BoundedTextReadOptIn",
+    "BoundedTextReadOutcome",
+    "BoundedTextReadResult",
+    "CIStatusSnapshot",
+    "Repository",
+    "RepositoryPool",
+]
 
 
 DEFAULT_RELATED_ISSUE_MAX_HITS = 20
+BOUNDED_TEXT_SOURCE_MAX_BYTES = 2 * 1024 * 1024
+
+_DEPENDENCY_LOCK_BASENAMES = frozenset(
+    {
+        "package-lock.json",
+        "npm-shrinkwrap.json",
+        "pnpm-lock.yaml",
+        "pnpm-lock.yml",
+        "yarn.lock",
+        "bun.lock",
+        "bun.lockb",
+        "uv.lock",
+        "poetry.lock",
+        "pipfile.lock",
+        "go.sum",
+        "cargo.lock",
+        "gradle.lockfile",
+        "gemfile.lock",
+        "composer.lock",
+        "pubspec.lock",
+        "mix.lock",
+        "flake.lock",
+        "renv.lock",
+        "package.resolved",
+        "packages.lock.json",
+    }
+)
+
+
+class BoundedTextReadOutcome(str, Enum):
+    """Truthful terminal outcome for one bounded repository text read."""
+
+    SUCCESS = "success"
+    EXCLUDED_BY_POLICY = "excluded_by_policy"
+    NOT_FOUND = "not_found"
+    OVERSIZE = "oversize"
+    BINARY_OR_NON_UTF8 = "binary_or_non_utf8"
+    DIRECTORY = "directory"
+    ERROR = "error"
+
+
+class BoundedTextReadOptIn(str, Enum):
+    """Narrow high-intent exceptions to the default repository-read policy."""
+
+    DEPENDENCY_LOCK = "dependency_lock"
+    CI_CONFIG = "ci_config"
+
+
+@dataclass(frozen=True)
+class BoundedTextReadResult:
+    """Text plus bounded, JSON-safe retrieval metadata."""
+
+    outcome: BoundedTextReadOutcome
+    content: Optional[str] = None
+    source_size_bytes: Optional[int] = None
+    bytes_read: int = 0
+    max_bytes: int = BOUNDED_TEXT_SOURCE_MAX_BYTES
+    policy_class: Optional[str] = None
+    status_code: Optional[int] = None
+    error_type: Optional[str] = None
+
+    def to_meta(self) -> dict:
+        """Return metadata only; never include repository text."""
+        return {
+            "outcome": self.outcome.value,
+            "source_size_bytes": self.source_size_bytes,
+            "bytes_read": self.bytes_read,
+            "max_bytes": self.max_bytes,
+            "policy_class": self.policy_class,
+            "status_code": self.status_code,
+            "error_type": self.error_type,
+        }
+
+
+def _normalized_repo_path(file_path: str) -> str:
+    return "/" + str(file_path or "").replace("\\", "/").lstrip("/")
+
+
+def _bounded_text_policy_class(file_path: str) -> Optional[str]:
+    """Classify paths that the bounded API may not read by default."""
+    normalized = _normalized_repo_path(file_path)
+    lowered = normalized.casefold()
+    basename = lowered.rsplit("/", 1)[-1]
+
+    if (
+        basename == ".env"
+        or (basename.startswith(".env.") and basename not in {".env.example", ".env.sample"})
+        or basename in {"id_rsa", "id_ed25519", "credentials", "secrets.yml", "secrets.yaml"}
+        or any(part in lowered for part in ("/.git/", "/.aws/", "/.ssh/"))
+    ):
+        return "sensitive"
+
+    if (
+        basename.endswith(".lock")
+        or basename.endswith(".lockfile")
+        or basename.endswith(".lock.json")
+        or basename.endswith("-lock.json")
+        or basename.endswith("_lock.json")
+        or basename in _DEPENDENCY_LOCK_BASENAMES
+    ):
+        return BoundedTextReadOptIn.DEPENDENCY_LOCK.value
+
+    if (
+        lowered.startswith("/.github/workflows/")
+        or lowered.startswith("/.gitlab/ci/")
+        or lowered.startswith("/.circleci/")
+        or lowered.startswith("/.buildkite/")
+        or basename
+        in {
+            ".gitlab-ci.yml",
+            ".gitlab-ci.yaml",
+            ".travis.yml",
+            ".travis.yaml",
+            "azure-pipelines.yml",
+            "azure-pipelines.yaml",
+            "bitbucket-pipelines.yml",
+            "bitbucket-pipelines.yaml",
+            "jenkinsfile",
+            "appveyor.yml",
+            "appveyor.yaml",
+        }
+    ):
+        return BoundedTextReadOptIn.CI_CONFIG.value
+
+    if any(
+        basename.endswith(suffix)
+        for suffix in (
+            ".exe", ".dll", ".so", ".dylib", ".bin", ".obj", ".o", ".a",
+            ".lib", ".jar", ".war", ".ear", ".class", ".apk", ".wasm",
+            ".png", ".jpg", ".jpeg", ".gif", ".ico", ".bmp", ".webp",
+            ".mp3", ".mp4", ".wav", ".avi", ".mov", ".mkv", ".webm",
+            ".ttf", ".otf", ".woff", ".woff2", ".zip", ".rar", ".7z",
+            ".tar", ".gz", ".bz2", ".xz", ".pkl", ".pickle", ".npy",
+            ".npz", ".h5", ".hdf5", ".pyc", ".pyo", ".min.js", ".min.css",
+            ".bundle.js", ".bundle.css", ".map", ".pbix", ".pbit", ".abf",
+        )
+    ):
+        return "binary_generated_or_minified"
+
+    if any(
+        segment in lowered
+        for segment in (
+            "/node_modules/", "/bower_components/", "/__pycache__/", "/.git/",
+            "/coverage/", "/.pytest_cache/", "/.tox/", "/venv/",
+            "/.virtualenv/", "/.cache/", "/.dart_tool/", "/.next/",
+            "/.nuxt/", "/.ipynb_checkpoints/",
+        )
+    ):
+        return "binary_generated_or_minified"
+    return None
 
 
 @dataclass(frozen=True)
@@ -114,6 +272,7 @@ class Repository:
 
         self._structure = None  # Singleton pattern for repository structure
         self._file_contents = {}  # Singleton pattern for file contents
+        self._bounded_text_reads = {}
         self._issues = {}  # Singleton pattern for file contents
         self._readme = None  # Singleton pattern for README content
         self._prs = {}  # Singleton pattern for PR content
@@ -604,6 +763,201 @@ class Repository:
         self.update_last_read_time()
         return self._file_contents.get(file_key)
 
+    def read_text_file_bounded(
+        self,
+        file_path: str,
+        sha: Optional[str] = None,
+        *,
+        opt_in: Optional[BoundedTextReadOptIn] = None,
+    ) -> BoundedTextReadResult:
+        """Read one UTF-8 file under a fixed 2 MiB source cap.
+
+        Dependency lockfiles and CI configuration require an exact, typed
+        ``opt_in``. Other binary, generated, minified, or sensitive paths stay
+        excluded even when an opt-in is supplied. The legacy
+        :meth:`get_file_content` contract and cache are intentionally separate.
+        """
+        requested_opt_in = None
+        if opt_in is not None:
+            requested_opt_in = BoundedTextReadOptIn(opt_in).value
+
+        policy_class = _bounded_text_policy_class(file_path)
+        allowed_exception = policy_class in {
+            BoundedTextReadOptIn.DEPENDENCY_LOCK.value,
+            BoundedTextReadOptIn.CI_CONFIG.value,
+        }
+        if (
+            (allowed_exception and requested_opt_in != policy_class)
+            or (policy_class is not None and not allowed_exception)
+            or (policy_class is None and requested_opt_in is not None)
+        ):
+            return BoundedTextReadResult(
+                outcome=BoundedTextReadOutcome.EXCLUDED_BY_POLICY,
+                policy_class=policy_class or "opt_in_path_mismatch",
+            )
+
+        cache_key = (str(file_path), sha, requested_opt_in)
+        cached = self._bounded_text_reads.get(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            repo = self.repo
+            if repo is None:
+                return BoundedTextReadResult(
+                    outcome=BoundedTextReadOutcome.ERROR,
+                    policy_class=policy_class,
+                    error_type="repository_unavailable",
+                )
+            file_content = (
+                repo.get_contents(file_path, ref=sha)
+                if sha is not None
+                else repo.get_contents(file_path)
+            )
+        except GithubException as exc:
+            status_code = getattr(exc, "status", None)
+            return BoundedTextReadResult(
+                outcome=(
+                    BoundedTextReadOutcome.NOT_FOUND
+                    if status_code == 404
+                    else BoundedTextReadOutcome.ERROR
+                ),
+                policy_class=policy_class,
+                status_code=status_code,
+                error_type=(
+                    "http_404"
+                    if status_code == 404
+                    else type(exc).__name__
+                ),
+            )
+        except Exception as exc:
+            logger.warning(
+                "Bounded text read failed operation=get_contents error_type=%s",
+                type(exc).__name__,
+            )
+            return BoundedTextReadResult(
+                outcome=BoundedTextReadOutcome.ERROR,
+                policy_class=policy_class,
+                error_type=type(exc).__name__,
+            )
+
+        try:
+            is_directory = (
+                isinstance(file_content, list)
+                or getattr(file_content, "type", None) == "dir"
+            )
+            raw_size = getattr(file_content, "size", None)
+        except Exception as exc:
+            return BoundedTextReadResult(
+                outcome=BoundedTextReadOutcome.ERROR,
+                policy_class=policy_class,
+                error_type=type(exc).__name__,
+            )
+        if is_directory:
+            return BoundedTextReadResult(
+                outcome=BoundedTextReadOutcome.DIRECTORY,
+                policy_class=policy_class,
+            )
+
+        source_size = (
+            raw_size
+            if isinstance(raw_size, int) and not isinstance(raw_size, bool) and raw_size >= 0
+            else None
+        )
+        if source_size is not None and source_size > BOUNDED_TEXT_SOURCE_MAX_BYTES:
+            return BoundedTextReadResult(
+                outcome=BoundedTextReadOutcome.OVERSIZE,
+                source_size_bytes=source_size,
+                max_bytes=BOUNDED_TEXT_SOURCE_MAX_BYTES,
+                policy_class=policy_class,
+            )
+
+        try:
+            encoding = getattr(file_content, "encoding", None)
+            if encoding == "base64":
+                encoded = file_content.content
+                if not isinstance(encoded, str):
+                    raise ValueError("base64 content is not text")
+                raw_bytes = base64.b64decode(encoded)
+                bytes_read = len(raw_bytes)
+                status_code = 200
+            else:
+                raw_url = getattr(file_content, "url", None)
+                if not isinstance(raw_url, str) or not raw_url:
+                    raw_url = getattr(file_content, "download_url", None)
+                bounded_request = getattr(self._github, "_request_bounded_bytes", None)
+                if not isinstance(raw_url, str) or not raw_url or not callable(bounded_request):
+                    return BoundedTextReadResult(
+                        outcome=BoundedTextReadOutcome.ERROR,
+                        source_size_bytes=source_size,
+                        policy_class=policy_class,
+                        error_type="raw_transport_unavailable",
+                    )
+                response = bounded_request(
+                    raw_url,
+                    max_bytes=BOUNDED_TEXT_SOURCE_MAX_BYTES,
+                    operation="bounded_text_read",
+                )
+                if response.oversize:
+                    declared_size = response.declared_size_bytes
+                    return BoundedTextReadResult(
+                        outcome=BoundedTextReadOutcome.OVERSIZE,
+                        source_size_bytes=source_size or declared_size,
+                        bytes_read=response.bytes_read,
+                        policy_class=policy_class,
+                        status_code=response.status_code,
+                    )
+                if response.error_type is not None or response.data is None:
+                    return BoundedTextReadResult(
+                        outcome=(
+                            BoundedTextReadOutcome.NOT_FOUND
+                            if response.status_code == 404
+                            else BoundedTextReadOutcome.ERROR
+                        ),
+                        source_size_bytes=source_size,
+                        bytes_read=response.bytes_read,
+                        policy_class=policy_class,
+                        status_code=response.status_code,
+                        error_type=response.error_type or "empty_raw_response",
+                    )
+                raw_bytes = response.data
+                bytes_read = response.bytes_read
+                status_code = response.status_code
+                if source_size is None:
+                    source_size = response.declared_size_bytes
+
+            if len(raw_bytes) > BOUNDED_TEXT_SOURCE_MAX_BYTES:
+                return BoundedTextReadResult(
+                    outcome=BoundedTextReadOutcome.OVERSIZE,
+                    source_size_bytes=source_size or len(raw_bytes),
+                    bytes_read=len(raw_bytes),
+                    policy_class=policy_class,
+                    status_code=status_code,
+                )
+            if b"\x00" in raw_bytes:
+                raise UnicodeDecodeError("utf-8", raw_bytes, 0, 1, "NUL byte")
+            decoded = raw_bytes.decode("utf-8")
+        except (UnicodeDecodeError, ValueError, TypeError):
+            return BoundedTextReadResult(
+                outcome=BoundedTextReadOutcome.BINARY_OR_NON_UTF8,
+                source_size_bytes=source_size,
+                policy_class=policy_class,
+            )
+
+        result = BoundedTextReadResult(
+            outcome=BoundedTextReadOutcome.SUCCESS,
+            content=decoded,
+            source_size_bytes=source_size or len(raw_bytes),
+            bytes_read=bytes_read,
+            policy_class=policy_class,
+            status_code=status_code,
+        )
+        with self._file_contents_lock:
+            self._bounded_text_reads.setdefault(cache_key, result)
+            result = self._bounded_text_reads[cache_key]
+        self.update_last_read_time()
+        return result
+
 
     def get_issue_content(self, number, issue=None) -> str:
         """
@@ -1338,6 +1692,7 @@ class Repository:
             self._structure = None  # Reset the repository structure cache
         with self._file_contents_lock:
             self._file_contents = {}  # Reset the file contents cache
+            self._bounded_text_reads = {}
         with self._issue_lock:
             self._issues = {}  # Reset the issue contents cache
         with self._readme_lock:

{llama_github-0.4.1 → llama_github-0.4.3}/llama_github/github_integration/github_auth_manager.py

@@ -54,6 +54,18 @@ class _JSONResponse:
     error_type: Optional[str] = None
 
 
+@dataclass(frozen=True)
+class _BoundedBytesResponse:
+    """Private transport result for a size-capped raw GitHub response."""
+
+    data: Optional[bytes] = None
+    bytes_read: int = 0
+    declared_size_bytes: Optional[int] = None
+    status_code: Optional[int] = None
+    error_type: Optional[str] = None
+    oversize: bool = False
+
+
 class GitHubAuthManager:
     """Manage personal-token and GitHub-App authentication for `ExtendedGithub` clients."""
 
@@ -243,6 +255,92 @@ class ExtendedGithub(Github):
         """Compatibility helper returning decoded JSON or ``None`` on failure."""
         return self._request_json_response(url, params).data
 
+    def _request_bounded_bytes(
+        self,
+        url: str,
+        *,
+        max_bytes: int,
+        operation: str = "github_raw_get",
+    ) -> _BoundedBytesResponse:
+        """Download at most ``max_bytes`` while retaining typed failure metadata."""
+        if max_bytes <= 0:
+            raise ValueError("max_bytes must be positive")
+
+        self._ensure_fresh_token()
+        session = self._build_session()
+        headers = {
+            "Accept": "application/vnd.github.raw+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self._access_token:
+            headers["Authorization"] = f"Bearer {self._access_token}"
+
+        try:
+            response = session.get(
+                url,
+                headers=headers,
+                timeout=(self._connect_timeout, self._read_timeout),
+                stream=True,
+            )
+            response.raise_for_status()
+
+            declared_size = None
+            content_length = response.headers.get("Content-Length")
+            if content_length is not None:
+                try:
+                    parsed_length = int(content_length)
+                    if parsed_length >= 0:
+                        declared_size = parsed_length
+                except (TypeError, ValueError):
+                    declared_size = None
+            if declared_size is not None and declared_size > max_bytes:
+                return _BoundedBytesResponse(
+                    declared_size_bytes=declared_size,
+                    status_code=response.status_code,
+                    oversize=True,
+                )
+
+            chunks = []
+            bytes_read = 0
+            for chunk in response.iter_content(chunk_size=64 * 1024):
+                if not chunk:
+                    continue
+                bytes_read += len(chunk)
+                if bytes_read > max_bytes:
+                    return _BoundedBytesResponse(
+                        bytes_read=bytes_read,
+                        declared_size_bytes=declared_size,
+                        status_code=response.status_code,
+                        oversize=True,
+                    )
+                chunks.append(chunk)
+            return _BoundedBytesResponse(
+                data=b"".join(chunks),
+                bytes_read=bytes_read,
+                declared_size_bytes=declared_size,
+                status_code=response.status_code,
+            )
+        except HTTPError as exc:
+            status_code = getattr(exc.response, "status_code", None)
+            logger.warning(
+                "GitHub request failed operation=%s error_type=http_error status_code=%s",
+                operation,
+                status_code,
+            )
+            return _BoundedBytesResponse(
+                status_code=status_code,
+                error_type=f"http_{status_code}" if status_code else "http_error",
+            )
+        except RequestException as exc:
+            logger.warning(
+                "GitHub request failed operation=%s error_type=%s",
+                operation,
+                type(exc).__name__,
+            )
+            return _BoundedBytesResponse(error_type=type(exc).__name__)
+        finally:
+            session.close()
+
     def _request_paginated_list(
         self,
         url: str,

llama_github-0.4.3/llama_github/version.py

@@ -0,0 +1 @@
+__version__ = "0.4.3"

{llama_github-0.4.1 → llama_github-0.4.3/llama_github.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llama-github
-Version: 0.4.1
+Version: 0.4.3
 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
@@ -31,7 +31,7 @@ Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: python-dateutil<3,>=2.9
 Requires-Dist: requests<3,>=2.33
 Requires-Dist: tokenizers<1,>=0.22.1
-Requires-Dist: transformers<6,>=5.3
+Requires-Dist: transformers<6,>=5.5
 Requires-Dist: urllib3<3,>=2.7
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == "dev"
@@ -61,13 +61,14 @@ pip install llama-github
 
 Current maintained runtime target: Python `3.10` through `3.14`.
 
-Version `0.4.1` keeps the existing high-level API while allowing retrieval-only
+Version `0.4.3` 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.
+them together. Deterministic planners can explicitly opt into typed, 2 MiB-capped
+lockfile or CI-config reads without weakening the generic file policy.
 
 ## Usage
 

{llama_github-0.4.1 → llama_github-0.4.3}/llama_github.egg-info/requires.txt

@@ -12,7 +12,7 @@ pydantic<3,>=2.10
 python-dateutil<3,>=2.9
 requests<3,>=2.33
 tokenizers<1,>=0.22.1
-transformers<6,>=5.3
+transformers<6,>=5.5
 urllib3<3,>=2.7
 
 [dev]

{llama_github-0.4.1 → llama_github-0.4.3}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=77.0.3", "wheel"]
+requires = ["setuptools>=83.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -36,7 +36,7 @@ dependencies = [
   "python-dateutil>=2.9,<3",
   "requests>=2.33,<3",
   "tokenizers>=0.22.1,<1",
-  "transformers>=5.3,<6",
+  "transformers>=5.5,<6",
   "urllib3>=2.7,<3",
 ]
 

{llama_github-0.4.1 → llama_github-0.4.3}/tests/test_data_retrieval.py

@@ -1,11 +1,19 @@
+import base64
 from datetime import datetime, timezone
+from types import SimpleNamespace
 from unittest.mock import MagicMock, call, patch
 
 import pytest
 from github import GithubException
 
 from llama_github.data_retrieval.github_api import GitHubAPIHandler
-from llama_github.data_retrieval.github_entities import Repository, RepositoryPool
+from llama_github.data_retrieval.github_entities import (
+    BOUNDED_TEXT_SOURCE_MAX_BYTES,
+    BoundedTextReadOptIn,
+    BoundedTextReadOutcome,
+    Repository,
+    RepositoryPool,
+)
 from llama_github.github_integration.github_auth_manager import (
     RetrievalOutcome,
     RetrievalResult,
@@ -48,6 +56,195 @@ class TestRepository:
 
         assert content == 'print("hello")'
 
+    def test_bounded_text_read_preserves_legacy_lockfile_exclusion(
+        self, mock_github_instance, mock_repo_object
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        assert repo.get_file_content("package-lock.json") is None
+        result = repo.read_text_file_bounded("package-lock.json")
+
+        assert result.outcome is BoundedTextReadOutcome.EXCLUDED_BY_POLICY
+        assert result.policy_class == "dependency_lock"
+        mock_repo_object.get_contents.assert_not_called()
+
+    @pytest.mark.parametrize(
+        ("path", "opt_in", "expected_policy"),
+        [
+            ("uv.lock", BoundedTextReadOptIn.DEPENDENCY_LOCK, "dependency_lock"),
+            ("go.sum", BoundedTextReadOptIn.DEPENDENCY_LOCK, "dependency_lock"),
+            ("gradle.lockfile", BoundedTextReadOptIn.DEPENDENCY_LOCK, "dependency_lock"),
+            ("packages.lock.json", BoundedTextReadOptIn.DEPENDENCY_LOCK, "dependency_lock"),
+            (
+                ".github/workflows/test.yml",
+                BoundedTextReadOptIn.CI_CONFIG,
+                "ci_config",
+            ),
+            ("appveyor.yml", BoundedTextReadOptIn.CI_CONFIG, "ci_config"),
+        ],
+    )
+    def test_bounded_text_read_allows_only_exact_high_intent_opt_in(
+        self,
+        mock_github_instance,
+        mock_repo_object,
+        path,
+        opt_in,
+        expected_policy,
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        content = b"version = 1\n"
+        file_obj = SimpleNamespace(
+            type="file",
+            size=len(content),
+            encoding="base64",
+            content=base64.b64encode(content).decode("ascii"),
+        )
+        mock_repo_object.get_contents.return_value = file_obj
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        result = repo.read_text_file_bounded(path, sha="head", opt_in=opt_in)
+
+        assert result.outcome is BoundedTextReadOutcome.SUCCESS
+        assert result.content == content.decode("utf-8")
+        assert result.policy_class == expected_policy
+        assert result.source_size_bytes == len(content)
+        assert result.bytes_read == len(content)
+        assert "content" not in result.to_meta()
+        mock_repo_object.get_contents.assert_called_once_with(path, ref="head")
+
+    @pytest.mark.parametrize(
+        ("path", "opt_in"),
+        [
+            ("uv.lock", BoundedTextReadOptIn.CI_CONFIG),
+            ("src/main.py", BoundedTextReadOptIn.CI_CONFIG),
+            (".env", None),
+            ("dist/app.min.js", None),
+        ],
+    )
+    def test_bounded_text_read_rejects_mismatched_or_non_text_policy(
+        self, mock_github_instance, mock_repo_object, path, opt_in
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        result = repo.read_text_file_bounded(path, opt_in=opt_in)
+
+        assert result.outcome is BoundedTextReadOutcome.EXCLUDED_BY_POLICY
+        mock_repo_object.get_contents.assert_not_called()
+
+    def test_bounded_text_read_rejects_oversize_before_content_access(
+        self, mock_github_instance, mock_repo_object
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        file_obj = MagicMock()
+        file_obj.type = "file"
+        file_obj.size = BOUNDED_TEXT_SOURCE_MAX_BYTES + 1
+        mock_repo_object.get_contents.return_value = file_obj
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        result = repo.read_text_file_bounded("src/large.txt")
+
+        assert result.outcome is BoundedTextReadOutcome.OVERSIZE
+        assert result.source_size_bytes == BOUNDED_TEXT_SOURCE_MAX_BYTES + 1
+        assert file_obj.content.call_count == 0
+
+    @pytest.mark.parametrize(
+        ("payload_size", "expected"),
+        [
+            (BOUNDED_TEXT_SOURCE_MAX_BYTES, BoundedTextReadOutcome.SUCCESS),
+            (BOUNDED_TEXT_SOURCE_MAX_BYTES + 1, BoundedTextReadOutcome.OVERSIZE),
+        ],
+    )
+    def test_bounded_text_read_enforces_local_cap_after_decode(
+        self, mock_github_instance, mock_repo_object, payload_size, expected
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        payload = b"a" * payload_size
+        mock_repo_object.get_contents.return_value = SimpleNamespace(
+            type="file",
+            size=BOUNDED_TEXT_SOURCE_MAX_BYTES,
+            encoding="base64",
+            content=base64.b64encode(payload).decode("ascii"),
+        )
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        result = repo.read_text_file_bounded("src/large.txt")
+
+        assert result.outcome is expected
+
+    @pytest.mark.parametrize("payload", [b"\xff\xfe", b"text\x00tail"])
+    def test_bounded_text_read_rejects_binary_or_non_utf8(
+        self, mock_github_instance, mock_repo_object, payload
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        mock_repo_object.get_contents.return_value = SimpleNamespace(
+            type="file",
+            size=len(payload),
+            encoding="base64",
+            content=base64.b64encode(payload).decode("ascii"),
+        )
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        result = repo.read_text_file_bounded("src/data.txt")
+
+        assert result.outcome is BoundedTextReadOutcome.BINARY_OR_NON_UTF8
+
+    def test_bounded_text_read_distinguishes_directory_not_found_and_error(
+        self, mock_github_instance, mock_repo_object
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        mock_repo_object.get_contents.return_value = []
+        assert (
+            repo.read_text_file_bounded("src").outcome
+            is BoundedTextReadOutcome.DIRECTORY
+        )
+
+        mock_repo_object.get_contents.side_effect = GithubException(404, {"message": "missing"})
+        assert (
+            repo.read_text_file_bounded("missing.txt").outcome
+            is BoundedTextReadOutcome.NOT_FOUND
+        )
+
+        mock_repo_object.get_contents.side_effect = GithubException(503, {"message": "down"})
+        assert (
+            repo.read_text_file_bounded("unavailable.txt").outcome
+            is BoundedTextReadOutcome.ERROR
+        )
+
+    def test_bounded_text_read_maps_raw_transport_outcomes(
+        self, mock_github_instance, mock_repo_object
+    ):
+        mock_github_instance.get_repo.return_value = mock_repo_object
+        mock_repo_object.get_contents.return_value = SimpleNamespace(
+            type="file",
+            size=None,
+            encoding="none",
+            url="https://api.github.test/contents/src/config.txt",
+            download_url=None,
+        )
+        mock_github_instance._request_bounded_bytes.return_value = SimpleNamespace(
+            data=b"tail = true\n",
+            bytes_read=12,
+            declared_size_bytes=12,
+            status_code=200,
+            error_type=None,
+            oversize=False,
+        )
+        repo = Repository("owner/test-repo", mock_github_instance)
+
+        result = repo.read_text_file_bounded("src/config.txt")
+
+        assert result.outcome is BoundedTextReadOutcome.SUCCESS
+        assert result.content == "tail = true\n"
+        mock_github_instance._request_bounded_bytes.assert_called_once_with(
+            "https://api.github.test/contents/src/config.txt",
+            max_bytes=BOUNDED_TEXT_SOURCE_MAX_BYTES,
+            operation="bounded_text_read",
+        )
+
     def test_get_pr_content_includes_current_head_sha(
         self, mock_github_instance, mock_repo_object
     ):

{llama_github-0.4.1 → llama_github-0.4.3}/tests/test_distribution_contents.py

@@ -16,20 +16,20 @@ def _write_wheel(path: Path, *, extra_files=()) -> None:
     with zipfile.ZipFile(path, "w") as archive:
         for name in sorted(expected_package_files(ROOT)):
             archive.writestr(name, b"")
-        archive.writestr("llama_github-0.4.1.dist-info/METADATA", b"")
+        archive.writestr("llama_github-0.4.3.dist-info/METADATA", b"")
         for name in extra_files:
             archive.writestr(name, b"")
 
 
 def test_wheel_content_verifier_accepts_exact_source_package(tmp_path):
-    wheel = tmp_path / "llama_github-0.4.1-py3-none-any.whl"
+    wheel = tmp_path / "llama_github-0.4.3-py3-none-any.whl"
     _write_wheel(wheel)
 
     verify_wheel(wheel, source_root=ROOT)
 
 
 def test_wheel_content_verifier_rejects_stale_duplicate_module(tmp_path):
-    wheel = tmp_path / "llama_github-0.4.1-py3-none-any.whl"
+    wheel = tmp_path / "llama_github-0.4.3-py3-none-any.whl"
     _write_wheel(
         wheel,
         extra_files=("llama_github/data_retrieval/github_entities 2.py",),

{llama_github-0.4.1 → llama_github-0.4.3}/tests/test_github_auth_manager.py

@@ -148,6 +148,67 @@ class TestExtendedGithub:
         assert session.get.call_args.kwargs["timeout"] == (2.5, 9.0)
         session.close.assert_called_once()
 
+    def test_bounded_raw_request_rejects_declared_oversize_before_stream(self):
+        gh = ExtendedGithub("token")
+        response = MagicMock()
+        response.status_code = 200
+        response.headers = {"Content-Length": "11"}
+        session = MagicMock()
+        session.get.return_value = response
+        gh._build_session = MagicMock(return_value=session)
+
+        result = gh._request_bounded_bytes(
+            "https://api.github.com/example",
+            max_bytes=10,
+        )
+
+        assert result.oversize is True
+        assert result.declared_size_bytes == 11
+        response.iter_content.assert_not_called()
+        assert session.get.call_args.kwargs["stream"] is True
+        session.close.assert_called_once()
+
+    def test_bounded_raw_request_rejects_stream_that_crosses_cap(self):
+        gh = ExtendedGithub("token")
+        response = MagicMock()
+        response.status_code = 200
+        response.headers = {}
+        response.iter_content.return_value = [b"123456", b"78901"]
+        session = MagicMock()
+        session.get.return_value = response
+        gh._build_session = MagicMock(return_value=session)
+
+        result = gh._request_bounded_bytes(
+            "https://api.github.com/example",
+            max_bytes=10,
+        )
+
+        assert result.oversize is True
+        assert result.bytes_read == 11
+        assert result.data is None
+        session.close.assert_called_once()
+
+    def test_bounded_raw_request_returns_exact_cap(self):
+        gh = ExtendedGithub("token")
+        response = MagicMock()
+        response.status_code = 200
+        response.headers = {"Content-Length": "10"}
+        response.iter_content.return_value = [b"12345", b"67890"]
+        session = MagicMock()
+        session.get.return_value = response
+        gh._build_session = MagicMock(return_value=session)
+
+        result = gh._request_bounded_bytes(
+            "https://api.github.com/example",
+            max_bytes=10,
+        )
+
+        assert result.oversize is False
+        assert result.data == b"1234567890"
+        assert result.bytes_read == 10
+        assert result.declared_size_bytes == 10
+        session.close.assert_called_once()
+
     def test_refresh_token_updates_requester(self):
         gh = ExtendedGithub("token-1")
         gh.refresh_token("token-2")

{llama_github-0.4.1 → llama_github-0.4.3}/tests/test_minimal_imports.py

@@ -12,7 +12,7 @@ def test_retrieval_imports_do_not_load_heavy_rag_dependencies():
         assert "llama_github.github_rag" not in sys.modules
 
         from llama_github.data_retrieval.github_api import GitHubAPIHandler
-        from llama_github.data_retrieval.github_entities import CIStatusSnapshot, Repository, RepositoryPool
+        from llama_github.data_retrieval.github_entities import BoundedTextReadResult, CIStatusSnapshot, Repository, RepositoryPool
         from llama_github.github_integration.github_auth_manager import GitHubAuthManager
         from llama_github.utils import AsyncHTTPClient, DiffGenerator
 
@@ -20,7 +20,9 @@ def test_retrieval_imports_do_not_load_heavy_rag_dependencies():
         loaded = forbidden.intersection(sys.modules)
         assert not loaded, sorted(loaded)
         assert callable(Repository.get_ci_status_with_status)
-        assert llama_github.__version__ == "0.4.1"
+        assert callable(Repository.read_text_file_bounded)
+        assert BoundedTextReadResult.__name__ == "BoundedTextReadResult"
+        assert llama_github.__version__ == "0.4.3"
         """
     )
 

llama_github-0.4.1/llama_github/version.py

@@ -1 +0,0 @@
-__version__ = "0.4.1"