docs: document --use-cog-base-image and prebuilt base images

[anish-sahoo]

Closes #1820

Summary

• Add new docs/base-images.md page explaining what Cog prebuilt base images are, what's on them, and how to use/disable --use-cog-base-image
• Clarify the relationship between --use-cog-base-image and --use-cuda-base-image (mutually exclusive; cuda flag only takes effect when cog base image is disabled)
• Update docs/getting-started.md and docs/getting-started-own-model.md with notes about default base-image behavior and links to the new page
• Regenerate docs/llms.txt

Validation

• prettier --check passes on all changed files
• mise run docs:llm succeeds
• docs/cli.md unchanged (already in sync)

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. Overall the content is accurate and well-placed.

One issue found:

1. docs/llms.txt is missing the new base-images.md content — The generation script (mise run docs:llm) uses git ls-files to discover docs, so if it was run before base-images.md was tracked by git, the new page won't be included. The current llms.txt only shows the +7 lines from the getting-started guides, but is missing the ~70 lines of new base-images content. Please regenerate it after ensuring base-images.md is staged/committed.

[ask-bonk]

Done — posted a review on PR #3088 noting that docs/llms.txt is missing the new base-images.md content and needs to be regenerated.

github run

[ask-bonk]

LGTM

github run

[ask-bonk]

LGTM

github run

[ask-bonk]

LGTM

github run

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

One issue found:

1. Incorrect example base image tag format — The example tag r8.im/cog-base:cuda12-python3.13-torch2.6 doesn't match the actual format produced by Cog. The BaseImageName function uses version.StripPatch() for CUDA and Python (preserving minor versions like 12.4), and the full torch version from the compatibility matrix (e.g., 2.6.0). Actual tags look like cuda12.4-python3.13-torch2.6.0.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

One issue found:

1. Incorrect example base image tag format — The example tag r8.im/cog-base:cuda12-python3.13-torch2.6 doesn't match the actual format produced by Cog. The BaseImageName function uses version.StripPatch() for CUDA and Python (preserving minor versions like 12.4), and the full torch version from the compatibility matrix (e.g., 2.6.0). Actual tags look like cuda12.4-python3.13-torch2.6.0.

Posted review: #3088 (review)

github run

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

One issue found:

1. Stale content in docs/llms.txt — The llms.txt file contains the old incorrect base image tag format (cuda12-python3.13-torch2.6) in the base-images.md section, but docs/base-images.md itself was already fixed to show the correct format (cuda12.4-python3.13-torch2.6.0). Please regenerate docs/llms.txt so it picks up the latest base-images.md content.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

One issue found:

1. Stale content in docs/llms.txt — The llms.txt file contains the old incorrect base image tag format (cuda12-python3.13-torch2.6) in the base-images.md section, but docs/base-images.md itself was already fixed to show the correct format (cuda12.4-python3.13-torch2.6.0). Please regenerate docs/llms.txt so it picks up the latest base-images.md content.

Posted review: #3088 (review)

github run

[ask-bonk]

LGTM

github run

[ask-bonk]

LGTM

github run

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

One issue found:

1. Inaccurate claim about Cog runtime in base images — The documentation states that Cog base images include "the Cog SDK and coglet prediction server." However, the base image generator (BaseImageGenerator.GenerateDockerfile) creates a StandardGenerator with requiresCog = false, which causes installCog() to skip installing the Cog SDK and coglet. These are installed as separate layers during the model build, not baked into the base image itself. The same inaccurate phrasing appears in the two getting-started guides.

Please also regenerate docs/llms.txt after applying these fixes.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

One issue found:

1. Inaccurate claim about Cog runtime in base images — The documentation states that Cog base images include "the Cog SDK and coglet prediction server." However, the base image generator (BaseImageGenerator.GenerateDockerfile) creates a StandardGenerator with requiresCog = false, which causes installCog() to skip installing the Cog SDK and coglet. These are installed as separate layers during the model build, not baked into the base image itself. The same inaccurate phrasing appears in the two getting-started guides.

Please also regenerate docs/llms.txt after applying these fixes.

github run

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

Two issues remain from previous review rounds:

1. Inaccurate claim about Cog runtime in base images — docs/base-images.md still states that base images include "the Cog SDK and coglet prediction server." This was previously flagged but not fixed. The base image generator creates a StandardGenerator with requiresCog = false, so the Cog SDK and coglet are installed as separate layers during the model build, not baked into the base image.

2. Stale content in docs/llms.txt — The llms.txt file still contains the old inaccurate phrasing from both base-images.md (the Cog runtime claim) and the getting-started guides (which were fixed in the source files but not regenerated into llms.txt).

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

Two issues remain from previous review rounds:

1. Inaccurate claim about Cog runtime in base images — docs/base-images.md still states that base images include "the Cog SDK and coglet prediction server." This was previously flagged but not fixed. The base image generator creates a StandardGenerator with requiresCog = false, so the Cog SDK and coglet are installed as separate layers during the model build, not baked into the base image.

2. Stale content in docs/llms.txt — The llms.txt file still contains the old inaccurate phrasing from both base-images.md (the Cog runtime claim) and the getting-started guides (which were fixed in the source files but not regenerated into llms.txt).

Posted review: #3088 (review)

github run

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

Two issues remain from previous review rounds:

1. Inaccurate claim about Cog runtime in base images — docs/base-images.md still states that base images include "the Cog SDK and coglet prediction server." This was previously flagged but not fixed. The base image generator creates a StandardGenerator with requiresCog = false, so the Cog SDK and coglet are installed as separate layers during the model build, not baked into the base image.

2. Stale content in docs/llms.txt — The llms.txt file still contains the old inaccurate phrasing from both base-images.md (the Cog runtime claim) and the getting-started guides (which were fixed in the source files but not regenerated into llms.txt). Please run mise run docs:llm after fixing base-images.md.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

Two issues remain from previous review rounds:

1. Inaccurate claim about Cog runtime in base images — docs/base-images.md still states that base images include "the Cog SDK and coglet prediction server." This was previously flagged but not fixed. The base image generator creates a StandardGenerator with requiresCog = false, so the Cog SDK and coglet are installed as separate layers during the model build, not baked into the base image.

2. Stale content in docs/llms.txt — The llms.txt file still contains the old inaccurate phrasing from both base-images.md (the Cog runtime claim) and the getting-started guides (which were fixed in the source files but not regenerated into llms.txt). Please run mise run docs:llm after fixing base-images.md.

Posted review: #3088 (review)

github run

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

Two issues remain from previous review rounds:

1. Inaccurate claim about Cog runtime in base images — docs/base-images.md still states that base images include "the Cog SDK and coglet prediction server." This was previously flagged but not fixed. The base image generator creates a StandardGenerator with requiresCog = false, so the Cog SDK and coglet are installed as separate layers during the model build, not baked into the base image.

2. Stale content in docs/llms.txt — The llms.txt file still contains the old inaccurate phrasing from base-images.md (the Cog runtime claim). Please run mise run docs:llm after fixing base-images.md.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds clear documentation for Cog's prebuilt base images and how the --use-cog-base-image / --use-cuda-base-image flags interact. The content is accurate and well-placed.

Two issues remain from previous review rounds:

1. Inaccurate claim about Cog runtime in base images — docs/base-images.md still states that base images include "the Cog SDK and coglet prediction server." This was previously flagged but not fixed. The base image generator creates a StandardGenerator with requiresCog = false, so the Cog SDK and coglet are installed as separate layers during the model build, not baked into the base image.

2. Stale content in docs/llms.txt — The llms.txt file still contains the old inaccurate phrasing from base-images.md (the Cog runtime claim). Please run mise run docs:llm after fixing base-images.md.

Posted review: #3088 (review)

github run

[ask-bonk]

LGTM

github run