ExuluPython - IMP Docs

ExuluPython provides functions for setting up, checking, and validating the Python virtual environment that IMP’s document processing and ML features depend on. The environment is created inside the installed @exulu/backend package at ee/python/.venv. You do not need to call these functions in normal production use — the document processor calls setup and validate automatically. Use ExuluPython directly when you want to pre-warm the environment at deploy time, build a health check, or display setup instructions to end-users.

API surface

ExuluPython.setup

ExuluPython.setup(options?: {
  packageRoot?: string;
  force?: boolean;
  verbose?: boolean;
  timeout?: number;
}): Promise<{
  success: boolean;
  message: string;
  alreadyExists: boolean;
  pythonVersion?: string;
  output?: string;
}>

Runs the bundled ee/python/setup.sh script to create and populate the virtual environment. Skips when the environment already exists, unless force: true.

packageRoot

string

Path to the installed @exulu/backend package. Auto-detected by walking the directory tree when omitted.

force

boolean

default:"false"

Re-run setup even when the virtual environment already exists (useful when packages are missing or corrupted).

verbose

boolean

default:"false"

Print setup script output to the console during execution.

timeout

number

default:"600000"

Setup timeout in milliseconds. The default (10 minutes) accommodates slow network downloads on first install.

ExuluPython.check

ExuluPython.check(packageRoot?: string): boolean

Synchronous check. Returns true when ee/python/.venv/bin/python exists. Does not verify that packages are installed — use validate for a thorough check.

ExuluPython.validate

ExuluPython.validate(
  packageRoot?: string,
  checkPackages?: boolean,
): Promise<{ valid: boolean; message: string }>

Verifies that the virtual environment exists, that the Python executable works, and (when checkPackages is true) that the critical packages docling and transformers can be imported.

checkPackages

boolean

default:"true"

Whether to import-check docling and transformers in addition to checking the executable.

ExuluPython.instructions

ExuluPython.instructions(): string

Returns a multi-line string with step-by-step setup instructions for the user, covering automatic (setupPythonEnvironment()), CLI (npx @exulu/backend setup-python), and manual paths. Includes platform-specific package manager commands.

Example

import { ExuluPython } from "@exulu/backend";

// At container startup: set up if not already done
if (!ExuluPython.check()) {
  console.log("Setting up Python environment…");
  const result = await ExuluPython.setup({ verbose: true });
  if (!result.success) {
    console.error("Python setup failed:", result.message);
    process.exit(1);
  }
  console.log("Python ready:", result.pythonVersion);
}

// Validate before processing documents
const { valid, message } = await ExuluPython.validate();
if (!valid) {
  console.error(ExuluPython.instructions());
  throw new Error("Python environment not valid: " + message);
}

System requirements

Requirement	Details
Python version	3.10 or higher
pip	Must be available
venv	`python3-venv` or equivalent
Disk	~2 GB for `docling` + `transformers` models on first run

Install Python on common platforms:

# macOS
brew install python@3.12

# Ubuntu / Debian
sudo apt-get install python3.12 python3-pip python3-venv

# Alpine (Docker)
apk add python3 py3-pip python3-dev

ExuluDocumentProcessor: the main consumer of the Python environment.

​API surface

​ExuluPython.setup

​ExuluPython.check

​ExuluPython.validate

​ExuluPython.instructions

​Example

​System requirements

​Related

API surface

ExuluPython.setup

ExuluPython.check

ExuluPython.validate

ExuluPython.instructions

Example

System requirements

Related