release: bound pull request source ingestion

Author: JetXu-LLM

.github/workflows/tests.yml

@@ -129,7 +129,7 @@ jobs:
           assert callable(Repository.get_ci_status_with_status)
           assert callable(Repository.read_text_file_bounded)
           assert BoundedTextReadResult.__name__ == "BoundedTextReadResult"
-          assert llama_github.__version__ == "0.4.4"
+          assert llama_github.__version__ == "0.4.5"
           PY
 
   dependency-audit:

CHANGELOG.md

@@ -5,6 +5,17 @@ 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.5] - 2026-07-20
+
+### Added
+- Added optional per-file and cumulative source limits to `get_pr_content()` for memory-bounded consumers while preserving the historical unbounded default and a separate cache identity
+- Added an optional caller-owned source limit to `get_file_content()`, including size-before-decode checks and locally capped raw-response streaming
+- Added content-free PR retrieval metadata for retained reads, budget exhaustion, API-patch fallback, and missing-patch fallback
+
+### Fixed
+- Prevented large changed-file base/head content from being materialized or accumulated before callers can apply their own memory boundary
+- Reused GitHub's changed-file patch when bounded source is unavailable instead of treating the file as analyzable full source
+
 ## [0.4.4] - 2026-07-19
 
 ### Fixed
@@ -204,6 +215,7 @@ 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.5]: https://github.com/JetXu-LLM/llama-github/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/JetXu-LLM/llama-github/compare/v0.4.3...v0.4.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

README.md

@@ -18,7 +18,7 @@ pip install llama-github
 
 Current maintained runtime target: Python `3.10` through `3.14`.
 
-Version `0.4.4` keeps the existing high-level API while allowing retrieval-only
+Version `0.4.5` 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
@@ -27,7 +27,9 @@ evidence, and preserves review summaries plus each inline comment without collap
 them together. Repository-qualified links are identity-aware, so upstream release-note
 links are not expanded as same-repository issues. Deterministic planners can explicitly
 opt into typed, 2 MiB-capped
-lockfile or CI-config reads without weakening the generic file policy.
+lockfile or CI-config reads without weakening the generic file policy. Memory-sensitive
+PR consumers can also opt into per-file and cumulative source limits; oversized source
+falls back to GitHub's changed-file patch without changing the default retrieval API.
 
 ## Usage
 

docs/api_reference.md

@@ -83,7 +83,7 @@ GitHubAppCredentials(
 
 Used with `GithubRAG(github_app_credentials=...)`.
 
-## `Repository.get_pr_content(number, pr=None, context_lines=10, force_update=False, *, related_issue_max_hits=None)`
+## `Repository.get_pr_content(number, pr=None, context_lines=10, force_update=False, *, related_issue_max_hits=None, source_file_max_bytes=None, source_total_max_bytes=None)`
 
 Available from:
 
@@ -128,8 +128,29 @@ comment as separate chronological records. `reviews` and `review_comments` have
 independent bounded-fetch metadata; `partial` or `error` means the interaction view is
 incomplete, not that no more comments exist.
 
+The two source-budget arguments are optional and leave the historical behavior
+unchanged when omitted. A bounded caller supplies a positive
+`source_file_max_bytes`; `source_total_max_bytes` is an optional positive cumulative
+limit and requires the per-file limit. Base/head reads are bounded before decode and
+while streaming raw responses. If the required source side is unavailable, oversized,
+or outside the remaining total budget, `file_changes[].diff` uses the patch already
+returned by GitHub. If GitHub omitted that patch, the diff is an explicit `[SKIPPED]`
+marker rather than a false full-source result. Content-free counts and the aggregate
+`complete|partial` outcome are available at
+`_retrieval_meta.file_content_budget`. Bounded and legacy results use distinct cache
+identities so one call mode cannot silently change the other.
+
 The method returns `None` if the PR cannot be retrieved.
 
+## `Repository.get_file_content(file_path, sha=None, *, max_source_bytes=None)`
+
+Returns the legacy generic text content or `None`. `max_source_bytes` is an optional
+positive caller-owned memory boundary. When supplied, GitHub's declared size is checked
+before decode; raw downloads are streamed and stopped locally at the same limit, and a
+cached value is rechecked before return. The default remains backward compatible and
+does not impose a new limit. This API retains the existing generic exclusion policy;
+use `read_text_file_bounded()` for the typed lockfile/CI-config opt-in contract.
+
 ## `Repository.read_text_file_bounded(file_path, sha=None, *, opt_in=None)`
 
 Reads one UTF-8 repository file under a fixed 2 MiB source cap and returns a

docs/usage.md

@@ -112,6 +112,24 @@ phrases. Explicit `#123` shorthand remains local.
 `_retrieval_meta` records bounded-fetch outcomes. A `partial` or `error` result is an
 unknown, not evidence that a file, comment, or match does not exist.
 
+Long-lived or memory-constrained consumers may opt into source limits without changing
+the default API:
+
+```python
+pr_content = repo.get_pr_content(
+    number=15,
+    source_file_max_bytes=128 * 1024,
+    source_total_max_bytes=16 * 1024 * 1024,
+)
+print(pr_content["_retrieval_meta"]["file_content_budget"])
+```
+
+Each base/head read is bounded before decode and during raw streaming. When bounded
+source cannot be retained, the method uses GitHub's changed-file patch; if GitHub did
+not provide one, it records an explicit skipped diff. The metadata contains only
+limits and counts, not source content. Bounded and legacy calls have separate cache
+identities.
+
 To refresh CI evidence later without refetching the whole pull request:
 
 ```python