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 usinggenerative.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):
Command line arguments where supported (e.g.
--dev
)You can use environment variables, (e.g.
GENERATIVE_DEV_MODE=true server examples
)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.
- 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 tonone
. 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.