docs: Document Flash local (non-pip) module bundling for endpoints - #775
docs: Document Flash local (non-pip) module bundling for endpoints#775promptless[bot] wants to merge 7 commits into
Conversation
Documents runpod/flash PR #352: automatic bundling of local Python modules that endpoints import. Adds an 'Import local modules' section to create-endpoints (supported import forms, transitive resolution, 8 MiB live cap, parent-directory constraint), a force-include note to the build CLI reference, and troubleshooting entries for the new resolution and payload-size errors.
…l-module-bundling
Rewrite the build page's local-module section to match merged behavior (the build validates against the ignore filter and fails loudly on ignore-excluded or unresolvable endpoint imports; it does not force-include ignored files), clarify transitive pip dependencies, add the ignore-excluded LocalModuleResolutionError variant to troubleshooting, and tighten cross-links. Ref: runpod/flash#352 (SLS-360)
…l-module-bundling # Conflicts: # release-notes.mdx
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
| return {"processed": True} | ||
| ``` | ||
|
|
||
| ## Import local modules |
There was a problem hiding this comment.
Documents the local-module bundling feature added in PR #352. stubs/local_modules.py::resolve_local_modules walks the transitive local-import closure (absolute, relative, and literal importlib.import_module imports, at module level and in function bodies), pulls in package __init__.py files, classifies stdlib/installed names as external, and warns on non-literal dynamic imports; stubs/live_serverless.py::build_modules_map ships the resolved source inline via the new FunctionRequest.modules field and enforces MAX_INLINE_MODULE_BYTES = 8 MiB.
Source: runpod/flash#352
|
|
||
| When you run an endpoint live (calling an `@Endpoint` function directly, or during `flash dev`), Flash ships the resolved module source inline with the request. The combined source is capped at 8 MiB. If your local dependencies exceed this limit, deploy the app with `flash deploy` instead, which bundles local modules into the build artifact rather than the request payload. See [Local module payload too large](/flash/troubleshooting#local-module-payload-too-large) for the corresponding error. | ||
|
|
||
| ### Local modules in a parent directory |
There was a problem hiding this comment.
Documents the parent-directory constraint. The docstring note in stubs/local_modules.py::resolve_local_modules states that on the live path a module imported by absolute name from a parent directory is classified as external and silently omitted (raising ModuleNotFoundError on the worker); only relative imports fail loudly, and the workaround is to keep the endpoint at/above its local deps or use flash deploy.
Source: runpod/flash#352
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
| If you use other environment file variants like `.env.dev` or `.env.staging`, add them to your `.gitignore` to exclude them from deployment artifacts. | ||
| </Tip> | ||
|
|
||
| ### Local modules and the ignore filter |
There was a problem hiding this comment.
Documents the build-path validation behavior (merged PR #352, not force-include). validate_local_module_imports in cli/commands/build.py is called from run_build AFTER files = get_file_tree(project_dir, spec) (the ignore-filtered shipped set) is computed; it never expands that set. For every shipped .py file it walks the local-import closure via stubs/local_modules.py::resolve_local_modules and checks each resolved file against the already-ignore-filtered files. If a shipped file imports a local module the ignore rules excluded, the build is refused (LocalModuleResolutionError -> typer.Exit(1)) with an actionable message naming the excluded file and its importer — it does NOT force-include the file. Strictness for unresolvable imports is scoped to endpoint files via build_utils/scanner.py::defines_endpoint (recognizing @remote/@Endpoint): an endpoint file with an unresolvable local import fails the build loudly, while a non-endpoint file that fails resolution is skipped with a warning and the build continues.
Source: runpod/flash#352
There was a problem hiding this comment.
(Line 488)
Documents the LocalModulePayloadTooLargeError raised in stubs/live_serverless.py::build_modules_map when the inline module payload exceeds MAX_INLINE_MODULE_BYTES (8 * 1024 * 1024 = 8388608 bytes = 8 MiB), defined in stubs/local_modules.py. The raised message is a single continuous string: "Inline module payload is {total} bytes, over the {MAX_INLINE_MODULE_BYTES}-byte live-serverless cap. Use flash deploy for endpoints with large local dependencies." — no embedded newline; the docs code block wraps it onto two lines for readability. The error points users to flash deploy, which is the documented solution. Anchor moved from line 484 (inside the unrelated pre-existing "Payload too large" section) to line 488, the heading of the new "Local module payload too large" section this citation actually supports.
Source: runpod/flash#352
|
|
||
| **July 28, 2026** | ||
|
|
||
| <h4><Badge color="green">New Release</Badge> [Automatic local module bundling for Flash endpoints](/flash/create-endpoints#import-local-modules) </h4> Flash now automatically bundles the local Python modules your endpoints import — sibling files and packages that aren't installed via pip — and ships their source to the worker. Imports like `import utils` or `from helpers import x` now work remotely with no extra configuration. |
There was a problem hiding this comment.
Announces the local (non-pip) module bundling feature implemented in PR #352 (merged 2026-07-20): stubs/local_modules.py::resolve_local_modules resolves the transitive local-import closure and stubs/live_serverless.py::build_modules_map ships the resolved source inline to the worker via the new FunctionRequest.modules field, so imports like import utils or from helpers import x work remotely with no extra configuration. The July 28, 2026 entry date matches the merge date of release PR #356 ("chore: release 1.19.0"), the release that shipped PR #352. Full technical detail (parent-directory constraint, 8 MiB inline cap, build-time validation) is already covered by the existing citations on flash/create-endpoints.mdx, flash/cli/build.mdx, and flash/troubleshooting.mdx; this citation anchors the release-announcement entry itself.
Source: runpod/flash#352
|
@Promptless: can you remove the hyphens added in between the texts from the draft? |
|
Thanks — on it. I'll remove the stray hyphens inserted between words in the draft and push an update to this PR shortly. |
|
Update: I found two stray dash connectors in the prose (one in the release notes entry and one in a link label on the create-endpoints page) and I'm removing those. Legitimate compound terms like "non-pip" and "built-in", along with error messages and code, are left untouched. Pushing the change shortly. |
Address PR review feedback (#775): replace the em-dash parenthetical connector in the July 28 release-notes entry with parentheses, and drop the 'flash build - ' connector prefix from the create-endpoints link text. Preserves compound modifiers, error-message strings, and code identifiers.
|
Done — I removed the two dash connectors that had been inserted between words in the draft:
I left legitimate hyphenation in place — compound terms like |
1 participant
Open in Promptless
Documents Flash's new first-class support for bundling local (non-pip) Python modules that endpoints import (runpod/flash PR #352, SLS-360), shipped in Flash v1.19.0 (release PR #356, merged 2026-07-28). Adds an "Import local modules" section to create-endpoints (supported import forms, transitive resolution, transitive pip-dependency note, the 8 MiB live-path cap, and the parent-directory absolute-import constraint), documents the build behavior on the build CLI reference (local modules are bundled when they pass the ignore filter; the build fails with a LocalModuleResolutionError on ignore-excluded or unresolvable endpoint imports rather than force-including files), and adds two troubleshooting entries for the resolution error (both variants) and the payload-too-large error. Also adds a "Product updates" (release-notes) entry dated July 28, 2026 announcing the feature and linking to the new create-endpoints section. Note: the build path validates against the ignore filter and refuses — it does not force-include ignore-excluded files, correcting the PR body's stale "force-include" wording against the merged code.
Trigger Events
Review feedback addressed
Applied @lavanya-gunreddi's request to remove hyphens inserted between words in the draft prose. Two draft-introduced dash connectors were removed:
release-notes.mdx(July 28, 2026 entry): applied — replaced the em-dash parenthetical connector pair around "sibling files and packages that aren't installed via pip" with parentheses.flash/create-endpoints.mdx("Import local modules" section): applied — removed the "flash build- " connector prefix from the link text so it reads "Local modules and the ignore filter"; link target unchanged.Legitimate hyphenation was preserved (compound modifiers like
non-pip,built-in,ignore-excluded; verbatim error-message strings such as the8388608-bytelive-serverless cap; and code identifiers), so no other dashes were altered.Tip: Worried about broken links? Ask Promptless to find and fix them automatically 🔗