👷♀️ This is a prerelease version of Cog. Please give it a try and file issues if you encounter any problems.
What's changed?
It's all about the schema!
Cog's [Python API](https://github.com/replicate/cog/blob/future/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.
Installation
First, [install Docker if you haven't already](https://docs.docker.com/get-docker/). Then run this in a terminal:
sudo curl -o /usr/local/bin/cog -L https://github.com/replicate/cog/releases/download/v0.1.0-alpha/cog_`uname -s`_`uname -m`
sudo chmod +x /usr/local/bin/cog
Upgrading from Cog 0.0.x to 0.1.x
In Cog versions up to 0.0.20 you described inputs using annotations 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 annotations, you now describe them with 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 by two options:
- `ge`: greater than or equal to (direct replacement)
- `gt`: greater than (a new alternative)
- The `max` option has been replaced by two options:
- `le`: less than or equal to (direct replacement)
- `lt`: less than (a new alternative)
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](…). If you only have a single output, but it can be of different types depending on the run, you can use `typing.Any`:
py
from typing import Any
def predict(self) -> Any:
...
Reference docs for Cog's new Python API can be found [here](https://github.com/replicate/cog/blob/79f440d588e9315d362c12540f189ba145367eb0/docs/python.md).
🆕 This is a prerelease version, so there are likely to be some rough edges. If you have any trouble please [open an issue](https://github.com/replicate/cog/issues). :octocat:
Changelog
* ad918f9 Add cog.BaseModel
* add4304 Add some more vscode settings from my local config
* c9b0a84 Add support for redis queue worker
* dacc30b Better error message when providing invalid inputs
* f999872 Bump github.com/anaskhan96/soup from 1.2.4 to 1.2.5
* 572c921 Bump github.com/docker/cli
* 1ef44fa Bump github.com/docker/docker
* 9c9659a Bump github.com/golangci/golangci-lint from 1.42.1 to 1.43.0
* a29457d Bump github.com/golangci/golangci-lint from 1.43.0 to 1.44.0
* a9e31c6 Bump github.com/golangci/golangci-lint from 1.44.0 to 1.44.1
* 1333cbc Bump github.com/spf13/cobra from 1.2.1 to 1.3.0
* 7c5d4b8 Bump pillow from 8.3.2 to 9.0.0
* e01e07e Clean up build integration tests
* c172527 Correctly pass environment variables to docker run
* 944b5fc Display better error when output type is undefined
* 7e91261 Don't require defining setup()
* 6e71e31 Fix lint errors
* 2b4f059 Implement choices option on input
* 27c63bf Install wheel with pyenv Python
* 79f440d Merge branch 'main' into future
* ea3dac8 Merge pull request 420 from replicate/better-input-validation-messages
* 44df62b Merge pull request 421 from replicate/throw-error-for-missing-output-type
* c83030f Move integration test project to fixtures
* 3158cb1 Move predict integration tests to fixtures
* 94f466f Remove AI Platform server
* cae046b Remove non-essential arguments to `cog.Input()`
* 7e7e2b5 Remove old test fixtures
* 12d5fbb Rename Predictor to BasePredictor
* a62c4bc Rename annotation to InputType for clarity
* 758a4bf Rename global.Verbose to global.Debug
* 24112a3 Reorganize tests
* 999756c Run Python tests on multiple Python versions
* cda6c97 Run redis integration tests in Docker network
* a73c1a7 Simplify tests by only testing setup() in one place
* 6977af8 Skip predict with remote image test
* 81bb5af Test complex output
* 393ab98 Update documentation to use Pydantic annotations
* 84d0bd5 Upgrade numpy to 1.21.5
* d15a16d Upgrade to redis-py 4
* e2e8f91 Use Pydantic for predictor type annotations
* 9a1a828 add TOC to README
* 42de67f add docstrings to new python functions
* 43f9996 add pip install to CONTRIBUTING
* 23be217 add prereqs to README
* 06fb9c7 allow server log level to be configured with COG_LOG_LEVEL
* 22b8fef always define components.schemas.Output
* 33d74ba chore: support and document prereleases (431)
* d826854 clarify supported Python versions
* 9467d76 document how to run tests
* 631fe08 document new Python API
* 76a8df2 nestle the story and shorten the TOC
* 5a85615 recognize all contributors
* c96c993 remove leftover prereq
* e01b41a update VS Code settings to format on save
* 68e04a7 update `cog init` predictor template
* a4bc493 update prereqs to mention Python versions