uv package manager (recommended for development and research), locally using pip with the provided requirements.txt, or as a fully self-contained Docker container suitable for CI pipelines, HuggingFace Spaces deployments, or any environment where you want strict process isolation. All three paths yield an identical runtime — a FastAPI server bound to port 8080 that speaks the OpenEnv REST protocol.
Prerequisites
Before installing, ensure the following are available on your machine:- Python 3.11+ — The Dockerfile uses
python:3.11-slimas its base image. Thepyproject.tomldoes not declare a hard upper bound, so Python 3.12 works equally well. uvpackage manager — Strongly recommended.uvresolves the pinneduv.lockfile for fully reproducible installs and is 10–100× faster thanpip. Install it withcurl -LsSf https://astral.sh/uv/install.sh | sh.pip— An alternative touv, available with any standard Python installation.- Docker — Optional. Required only if you want to run the containerized variant. Any version of Docker Engine that supports multi-stage builds is compatible.
openenv-core>=0.1.0— The OpenEnv protocol library that providesEnvClient,Environment, and associated base types. This is installed automatically by eitheruv syncorpip install -r requirements.txt.
The
openenv-core package provides graceful fallback stubs for all its types — if it is unavailable in your environment, the server and client will still import and run correctly using the inline stub classes defined in client.py and models.py. This makes the codebase portable even in sandboxes where the package registry is restricted.Local Installation with uv (Recommended)
uv sync reads the uv.lock file to install a fully pinned, reproducible dependency graph. This is the fastest and most reliable installation method for local development and baseline evaluation runs.
uv sync completes, all dependencies are installed into a project-local virtual environment (typically .venv/). You do not need to activate it manually — uv run handles activation transparently.
What uv sync installs (sourced from pyproject.toml):
To start the server with
uv:
Local Installation with pip
If you preferpip, the requirements.txt file lists the same packages with identical version constraints, plus python-dotenv (for .env file loading) and aiofiles (for async file I/O). This file is also what the Dockerfile uses to build the container image.
requirements.txt package list:
python-dotenv and aiofiles are listed in requirements.txt but not in pyproject.toml. The inference.py script calls load_dotenv() at startup to automatically source your .env file, and aiofiles is used for non-blocking I/O in certain async server paths. Both are needed for production-quality operation.pip install:
Docker Installation
The repository ships a production-readyDockerfile designed for compatibility with both local Docker runtimes and HuggingFace Spaces free tiers. The image is built from python:3.11-slim, installs GCC and build tools (required by pandas’ C extensions on slim images), and runs the server as a non-root user (UID 1000) — a hard requirement for HuggingFace Spaces.
Build the image: