Skip to main content
The official Python client for the Archetype platform provides a simple interface to interact with the Archetype API.

GitHub Repository

View source code, examples, and documentation

Requirements

  • Python 3.11 or later. Python 3.10 is the minimum the client installs on, but it reached end of life in October 2026.
  • An Archetype API key (see Libraries for setup instructions)

Install

Create a virtual environment, install the client, and set your credentials for your operating system:
macOS ships with python3. Recent Homebrew and system Pythons block system-wide installs (PEP 668), so create a virtual environment first — a bare pip install fails with externally-managed-environment:
Set your credentials in the activated shell (or persist them in ~/.zshrc):
If you’re using the Archetype AI free trial, use the following instead:
On other Linux distributions, the same pattern applies: ensure Python 3.11+ is installed, create and activate a virtual environment, then pip install archetypeai. For more on credentials, see Environment Variables.
If you prefer Anaconda or Miniconda to manage Python environments, create and activate an environment and install the client inside it:

Verify Installation

Test that the client is correctly installed by running (inside your activated environment):
If successful, you should see a version number printed:

What’s Included

The Python client includes:
  • API Client: Core client for interacting with the Archetype platform
  • Examples: Sample scripts demonstrating common use cases

Build and Run a Package

Requires version 2.0.1 or later of the Archetype platform.
A package is an immutable build of a blueprint: every model slot is resolved when the package is built, so it always runs the same models. To run a package, deploy it, then open a session on the deployment. A batch session is one run over its input files. With client version 26.10.30.0 or later, build a package with client.agents.packages, deploy it with client.agents.deployments, and run it with client.agents.sessions. Only a package in a project can be deployed, so start by copying a blueprint into a project:
  • Client version 26.10.30.0 removes client.agents.bundles and client.agents.instances. Code that uses them must move to deployments and sessions.
  • client.agents.deployments also provides list, get, stop, and delete. wait_until_ready returns once the deployment is ready, stopped, or failed.
  • client.agents.sessions also provides list, get, get_events, cancel, and delete.
  • A package that has deployments cannot be deleted. Stop and delete its deployments first.
For the underlying endpoints, see Create Package, Create Deployment, and Create Session.

Upgrade Python Client

  • To show the currently installed version of the python client, please use
  • To upgrade to the latest version of the python client, please use
Please note the minimum requirements here.