Overview

A Python package for serving Generative Functions. It includes the following sub-packages:

  • generative.server - a RESTful HTTP server with endpoints for evaluating functions defined using generative.core.

  • generative.messaging - common datatypes for interaction with other services

Setup

Installation guides can be found here.

Usage

The server can be run using any of the following commands.

with plain uv:

uv run server examples

or with Nix (which will have built a server executable):

server examples

or just with Python - if generative-server is available in the current installation:

python -m generative.server examples

This runs a customised FastAPI server with endpoints for each of the functions defined in examples. Use --help for more details, and to see the available command-line parameters.

ℹ️ Note the server will automatically set up and import Python packages based on this directory, so it’s very important to consistently specify the root to your generative functions.

Configuration

Methods

There are configuration options you can set to customise operation of the server (in descending order of precedence):

  1. Command line arguments where supported (e.g. --dev)

  2. You can use environment variables, (e.g. GENERATIVE_DEV_MODE=true server examples)

  3. You can use dotenv to keep these neatly in a .env file.

Parameters

All fields of the Settings class are exposed as environment variables. These are prefixed with GENERATIVE_. E.g. function_dirs would be set using the GENERATIVE_FUNCTION_DIRS environment variable.

The code to handle these Settings instances lives in config.py.

class Settings
classmethod ensure_trailing_slashes(value, info)

Wrap a classmethod, staticmethod, property or unbound function and act as a descriptor that allows us to detect decorated items from the class’ attributes.

This class’ __get__ returns the wrapped item’s __get__ result, which makes it transparent for classmethods and staticmethods.

Attributes:

wrapped: The decorator that has to be wrapped. decorator_info: The decorator info. shim: A wrapper function to wrap V1 style function.

allowed_groups

Groups which are allowed to evaluate. An empty set means any group is allowed.

assets_public_base_url

URL to use for publicly referencing assets in the assets endpoints. If not configured, it will be set to the server itself.

auth_mode

The mode for authentication of incoming requests.

cors_allowed_origins

Comma-separated list of allowed origin URLs for CORS requests.

data_dir

Path for storing results and assets as store and / or cache. Default: data in the current directory.

default_group_id

The default Group ID to use if not supplied.

dev_mode

Whether to run with extra dev / debugging settings. Not suitable for hosted systems.

enable_local_results_cache

Enable a local disk cache of evaluation results (even if local results are disabled).

enable_reload

Whether to watch for changes in Generative Functions files, and reload the server when they happen.

enable_results_service

Start and use a local results service API.

function_dirs

The directories to search for Generative Functions. Defaults to the current directory.

Separate multiple values using commas e.g. foo,parent/bar. If the directories include commas, you can quote them with double quotes (“), as per CSV files: "example, foo",parent/bar.

functions_version

Multihash-multibase-encoded version of the generative functions to expose. If not specified, Git will be used to get the raw version, which will the be encoded.

git_commit

SHA1 hash of the commit to use when the Git version mode is selected. This can be entered manually, or the server will detect it by running: git rev-parse HEAD

log_level

Base logging threshold for Generative and related logs to be output. Note there is some logic here to tweak exact log levels.

oauth2_scopes

The space-or-comma-separated scopes to enrich JWTs when authorising through Swagger UI.

oidc_audience

The JWT audience field to mandate tokens contain during OIDC flows. Ignored if this field is “null” or not set. Default: Do not verify

oidc_client_id

Optional OIDC Client ID, for authenticating requests.

oidc_url

OIDC Authority URL for OpenID Connect authentication operations. This is required unless AuthMode is set to none. The discovery URL is assumed to be at ./.well-known/openid-configuration relative to this

results_client_base_url

Optional URL to use for saving results, when not using local enable_results_service.

results_public_base_url

Optional URL to use for referring to saved results. If not set, results_client_base_url will be used.

server_host

The hostname to bind the server to

Set this to 0.0.0.0 to accept connections from any interface.

server_port

The port to run the server on.

server_public_base_url

The publicly routable base URL for the server (e.g. for load balancers / HTTPS termination). If none, each request’s URL will be used.

version_mode

The mode used to determine the version of functions. Default: runtime

The following options are available: - runtime: A version is automatically generated based on the Python version, the code in any function source files, and the version of any modules they depend on. - git: The version is determined by the current commit in the Git repository. - manual: The version is supplied through the GENERATIVE_FUNCTIONS_VERSION parameter.