Skip to content

v0.1.0-alpha

Pre-release
Pre-release
Compare
Choose a tag to compare
@github-actions github-actions released this 17 Feb 22:29
· 863 commits to main since this release
v0.1.0-alpha
79f440d

👷‍♀️ 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 has been updated to use the popular Pydantic library under the hood. Pydantic makes use of Python's type annotations (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 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. 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:

@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 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:

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:

from typing import Any

def predict(self) -> Any:
    ...

Reference docs for Cog's new Python API can be found here.

🆕 This is a prerelease version, so there are likely to be some rough edges. If you have any trouble please open an issue. :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
Assets 7