👷♀️ This new version of Cog includes significant changes from previous versions. If you encounter any problems using it, please [open an issue](https://github.com/replicate/cog/issues) and we'll help you out! :octocat:
What's changed?
It's all about the schema! `{...}`
Cog's [Python API](https://github.com/replicate/cog/blob/main/docs/python.md) has been updated to use the popular [Pydantic](https://pydantic-docs.helpmanual.io/) library under the hood. Pydantic makes use of Python's [type annotations](https://dev.to/dan_starner/using-pythons-type-annotations-4cfe) (a native feature of the Python language) to help validate your code and prevent runtime errors. But perhaps most importantly, Pydantic can convert a Python file into a JSON schema.
Cog now generates a JSON schema from the Predictor you've defined in your `predict.py` file, and uses another popular Python package called [FastAPI](https://fastapi.tiangolo.com/) to dynamically build an OpenAPI schema and HTTP web server that can be used as a JSON API to generate predictions from your model. And because it's using OpenAPI, this server also dynamically generates documentation specific to your model, and a Swagger UI interface for trying out the API.
With this new schema-focused design, the inputs and outputs you define for your model are converted into a portable, language-agnostic structured data format. This helps guide us toward a more **standardized way of defining model interfaces** and paves the way to better documentation, more automated tests, easier integrations across systems, and less reinventing the wheel.
Upgrading
First, [install Docker if you haven't already](https://docs.docker.com/get-docker/). Then run this in a terminal:
sh
sudo rm $(which cog) (if you have a previous version of cog installed)
sudo curl -o /usr/local/bin/cog -L https://github.com/replicate/cog/releases/latest/download/cog_`uname -s`_`uname -m`
sudo chmod +x /usr/local/bin/cog
Examples
To get a feel for the changes, check out the [replicate/cog-examples](https://github.com/replicate/cog-examples) repository which has been updated with examples supporting this new version:
- https://github.com/replicate/cog-examples/blob/main/blur/predict.py
- https://github.com/replicate/cog-examples/blob/main/hello-world/predict.py
- https://github.com/replicate/cog-examples/blob/main/resnet/predict.py
Upgrading from Cog 0.0.x to 0.1.x
Reference docs for Cog's new Python API can be found [here](https://github.com/replicate/cog/blob/cf94f63abd5d010bb14ec51c50c41c70d0f84055/docs/python.md).
In Cog versions up to 0.0.20, you described inputs using `cog.input` decorators on your `predict` method. For example:
py
cog.input("image", type=Path, help="Image to enlarge")
cog.input("scale", type=float, default=1.5, help="Factor to scale image by")
def predict(self, image, scale):
...
From Cog 0.1.0 onwards, we've started using [Pydantic](https://pydantic-docs.helpmanual.io/) to define input and output types. Rather than describing inputs using decorator annotations, you now describe them with Python's built-in type hinting. Here's how you'd define the same inputs now:
py
def predict(self,
image: Path = Input(description="Image to enlarge"),
scale: float = Input(description="Factor to scale image by", default=1.5)
) -> Path:
...
The parameters that `Input()` takes are pretty similar to those `cog.input()` used to take. Here are the differences:
- It no longer takes a `type` parameter; use a type hint instead.
- The `help` parameter has been renamed to `description`.
- The `options` parameter has been renamed to `choices`.
- The `min` option has been replaced with `ge` (greater than or equal to)
- The `max` option has been replaced with `le` (less than or equal to)
The other major difference is that you now need to define the output type of your model. That's the `-> Path` bit in the example above. That might be a simple type like `str`, `float` or `bool`. If you need to handle multiple outputs, check out the [new documentation for complex output objects](https://github.com/replicate/cog/blob/cf94f63abd5d010bb14ec51c50c41c70d0f84055/docs/python.md#outputbasemodel).
If you have any trouble using this new version of Cog, please [open an issue](https://github.com/replicate/cog/issues). :octocat:
Feedback
This new version of Cog includes a number of internal and user-facing changes from previous versions, so there could be some rough edges.
If you encounter any problems using it, please [open an issue](https://github.com/replicate/cog/issues) and we'll help you out! :octocat:
You can also chat with us on Discord at [discord.gg/replicate](https://discord.gg/replicate). 💬