Skip to main content
The CRM Data Pipeline Environment can be installed in three ways: locally using the 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-slim as its base image. The pyproject.toml does not declare a hard upper bound, so Python 3.12 works equally well.
  • uv package manager — Strongly recommended. uv resolves the pinned uv.lock file for fully reproducible installs and is 10–100× faster than pip. Install it with curl -LsSf https://astral.sh/uv/install.sh | sh.
  • pip — An alternative to uv, 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 provides EnvClient, Environment, and associated base types. This is installed automatically by either uv sync or pip 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.
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.
After 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 prefer pip, 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.
Complete 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.
To start the server with a plain pip install:

Docker Installation

The repository ships a production-ready Dockerfile 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:
Run the container:
Run with all configuration options:
Dockerfile explained, line by line:
Do not change the exposed port from 8080. HuggingFace Spaces enforces this port in its reverse proxy configuration, and the OpenEnv client defaults to http://localhost:8080 as well. If you need a different host port, use Docker’s port mapping (-p 9000:8080) rather than changing the EXPOSE or CMD directives inside the Dockerfile.

Verify the Installation

Regardless of which installation method you used, confirm the server is responding correctly:
Expected output:
You can also hit the health check from a browser at http://localhost:8080/ or view the auto-generated OpenAPI documentation at http://localhost:8080/docs.
The FastAPI server exposes interactive Swagger UI at /docs and a ReDoc interface at /redoc. Both are generated automatically from the Pydantic models in models.py and are extremely useful for exploring the full action and observation schemas without writing any code.

Project Structure

Once cloned, the repository has the following layout. Understanding each file’s role will help you navigate the codebase, extend the environment, or build custom evaluation harnesses.