Skip to content

Rename predict to run#2781

Draft
bfirsh wants to merge 11 commits intomainfrom
rename-predict-to-run-clean2
Draft

Rename predict to run#2781
bfirsh wants to merge 11 commits intomainfrom
rename-predict-to-run-clean2

Conversation

@bfirsh
Copy link
Member

@bfirsh bfirsh commented Feb 27, 2026 •
edited
Loading

Summary

Renames the core "predict" concept to "run" across the entire codebase — CLI, Python SDK, Rust coglet, HTTP API, Go internals, docs, and integration tests. Backwards compatibility is maintained, except for the previous behavior of cog run being renamed to cog exec.

Key changes

  • CLI: cog run is now the prediction command (old cog run for arbitrary commands → cog exec); cog predict kept as hidden alias
  • cog.yaml: accepts both run: and predict: keys (errors if both set; run preferred)
  • Python SDK: BaseRunner class with def run() method; BasePredictor/def predict() are aliases
  • Rust coglet: detects run() vs predict() method at load time, dispatches accordingly
  • HTTP API: /runs, /runs/{id}, /runs/{id}/cancel added as aliases for /predictions endpoints
  • Metrics: emits both run_time and predict_time (same value)
  • Go internals: pkg/predict/ renamed to pkg/run/ via git mv; Predictor → Runner
  • cog init: generates run.py with BaseRunner/Runner class

Backwards compatibility

  • cog predict still works (hidden alias)
  • predict: key in cog.yaml still works
  • BasePredictor class still works
  • def predict() method still works
  • /predictions HTTP endpoints unchanged
  • predict_time metric still emitted
  • 4 dedicated backwards-compat integration tests added

Commits

Each commit is a logical unit:

  1. Add implementation plan
  2. Rename CLI commands: cog run → cog exec, cog predict → cog run
  3. Add run key to cog.yaml alongside legacy predict key
  4. Add BaseRunner class and run() method to Python SDK
  5. Add /runs HTTP endpoints and run_time metric; Rust coglet detects run() vs predict()
  6. Rename pkg/predict to pkg/run (via git mv)
  7. Update Go test files
  8. Update all documentation
  9. Update all integration tests
  10. Add backwards compatibility integration tests
  11. Regenerate docs/cli.md and docs/llms.txt

Testing

  • Go build + unit tests: pass
  • Rust tests (132): pass
  • Python unit tests (124): pass
  • Integration tests (227 run, 25 skipped): pass (1 pre-existing version mismatch failure unrelated to this PR)

@bfirsh
Add implementation plan for renaming predict to run
2519c08
@bfirsh
Rename CLI commands: cog run → cog exec, cog predict → cog run
e561ebf 
- New 'cog exec' command replaces old 'cog run' for running arbitrary
  commands in the Docker environment
- New 'cog run' command runs predictions (replaces 'cog predict')
- 'cog predict' kept as hidden alias for backwards compatibility
- Heuristic detection warns users who try old 'cog run <cmd>' usage
  and suggests 'cog exec' instead
@bfirsh
Add 'run' key to cog.yaml alongside legacy 'predict' key
374bb7e 
- Accept both 'run:' and 'predict:' in cog.yaml (cannot set both)
- 'run' takes precedence; 'predict' is the legacy name
- Update JSON schema to include 'run' property
- Update cog init template: generate run.py with BaseRunner class
- Update cog.yaml template to use run: 'run.py:Runner'
- Add validation tests for run/predict conflict
@bfirsh
Add BaseRunner class and run() method to Python SDK
d95da02 
- Add BaseRunner as the new base class with run() method
- BasePredictor is now an alias for BaseRunner (backwards compat)
- get_predict() prefers run() over predict(); errors if both defined
- Inspector (schema generation) detects run() or predict() on classes
- Export BaseRunner from cog package
- Add tests for BaseRunner, run(), and dispatch logic
@bfirsh
Add /runs HTTP endpoints and run_time metric
a4fec20 
- Add /runs, /runs/{id}, /runs/{id}/cancel as aliases for /predictions
- Emit run_time metric alongside predict_time in all responses
- Both metrics contain the same value for backwards compatibility
- Add test for /runs route and run_time metric presence
@bfirsh
Rename pkg/predict to pkg/run and update CLI references
d63bb35 
Rename the Go prediction package from pkg/predict/ to pkg/run/:
- predictor.go → runner.go: Predictor → Runner, NewPredictor → NewRunner,
  Predict() → Run(), endpoint returns 'runs'
- api.go, input.go: package name updated to 'run'

Update CLI files that reference the package:
- train.go: predict.NewPredictor → run.NewRunner
- predict.go: already updated in Phase 1, import verified
- build.go: help text 'cog predict' → 'cog run'
- init_test.go: expect run.py instead of predict.py from cog init
@bfirsh
Update Go test files to use run/Runner terminology
10dd489 
Update test config strings and assertions across Go test packages:
- pkg/config/: config_test, load_test, validate_test use run: key
- pkg/dockerfile/: standard_generator_test uses run: 'run.py:Runner'
- pkg/util/: overwrite_yaml_test uses run: key
- pkg/web/: client_test creates run.py temp files

Note: Docker image label JSON continues to use 'predict' key (part of
Config struct's json tag), so model/image tests and mock configs that
test label parsing are intentionally unchanged.
@bfirsh
Update all documentation to use run/Runner terminology
f924412 
Rename predict concepts to run across all user-facing and internal docs:
- README.md, docs/README.md: run.py:Runner, cog run, BaseRunner
- docs/python.md: ~40 substitutions (BaseRunner, def run(), Runner class)
- docs/getting-started.md, docs/getting-started-own-model.md
- docs/yaml.md: renamed 'predict' config section to 'run'
- docs/http.md: predict function → run function
- docs/training.md: BaseRunner, cog run
- docs/notebooks.md: run.py, BaseRunner
- docs/wsl2/wsl2.md: cog run
- CONTRIBUTING.md: run.py:Runner, pkg/run/
- AGENTS.md: updated project structure descriptions
- crates/README.md: PythonRunner, run() method
- architecture/*.md (11 files): updated diagrams and descriptions

Preserved as-is: 'prediction' as a noun, /predictions HTTP endpoints,
predict_time metric, predictor_ref protocol field, Config.Predict Go field.
@bfirsh
Update all integration tests to use run/Runner terminology
70389a6 
Mechanical rename across 106 .txtar test files plus supporting Go files:
- cog predict → cog run (prediction commands)
- cog run → cog exec (arbitrary command execution in 6 files)
- predict: 'predict.py:Predictor' → run: 'run.py:Runner' (cog.yaml)
- -- predict.py -- → -- run.py -- (txtar file sections)
- from cog import BasePredictor → from cog import BaseRunner
- class Predictor(BasePredictor) → class Runner(BaseRunner)
- def predict(self → def run(self
- Updated comments and docstrings to use runner terminology
- integration-tests/README.md: updated examples and descriptions
- integration-tests/concurrent/concurrent_test.go: updated config and code
github-code-quality[bot]
github-code-quality bot found potential problems Feb 27, 2026
View reviewed changes
@bfirsh bfirsh force-pushed the rename-predict-to-run-clean2 branch from cc3866e to 72c56cf Compare February 27, 2026 18:13
@bfirsh bfirsh force-pushed the rename-predict-to-run-clean2 branch from 72c56cf to b27ea69 Compare February 27, 2026 18:19
@markphelps markphelps added this to the 0.18.0 milestone Mar 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@github-code-quality github-code-quality[bot] github-code-quality[bot] left review comments

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

0.18.0

Development

Successfully merging this pull request may close these issues.

2 participants

@bfirsh @markphelps