Installation

Requirements

Kellogg LLM Batch supports Python 3.10 through 3.12. A dedicated environment keeps its dependencies separate from other research projects. For example, with mamba:

$ mamba create -n kllm-batch python=3.12 -y
$ mamba activate kllm-batch

Clone and install

Clone the public repository and install the local checkout in editable mode:

$ git clone https://github.com/rs-kellogg/llm-batch_pipeline.git
$ cd llm-batch_pipeline
$ python -m pip install -e .
$ kllm-batch --help

To update the package later, pull the latest code from the same checkout. The editable installation uses the updated local source without requiring another package installation:

$ git pull

The standard installation includes the local project builder. After creating a project, you can open it in your browser:

$ kllm-batch init my-project
$ kllm-batch gui my-project

Using the GUI is optional. It binds only to 127.0.0.1 and does not call a provider. Preparation and provider operations remain CLI-only.

Contributor tools

To add tests and documentation tools to the same editable checkout:

$ python -m pip install -e '.[dev,docs]'
$ python -m pytest

Provider credentials

Set only the credential for the provider you intend to use:

$ export OPENAI_API_KEY="your-key"
$ export ANTHROPIC_API_KEY="your-key"

Credentials are not needed for init, gui, validate, or prepare. They are required when a command contacts the corresponding provider.

For a self-hosted Ollama or vLLM server (the openai_compatible provider, see Project settings), most local deployments need no credential at all — only providers.openai_compatible.base_url in project.yaml. If your server sits behind authentication, set api_key_env_var to the name of an environment variable and export it the same way:

$ export MY_LOCAL_SERVER_API_KEY="your-key"

Warning

Never put credentials in project.yaml, prompt files, shared shell history, or Git. Keep local secret files outside the repository or add them to an appropriate ignore rule before use.

Next step

Continue to the Basic workflow guide to create a project and run a small pilot before submitting a complete batch.