# Build and get test cases

# Creating a Definition (wrapper)

hypervector-wrapper allows you to build a Definition using JSON and deploy it ready for use via the API. For example:

# definition.json
  "definition_name": "Example definition",
  "features": [
      "feature_name": "feature_A",
      "type": "INTEGER",
      "distribution": {
        "type": "UNIFORM",
        "min": 10,
        "max": 50
      "feature_name": "feature_B",
      "type": "FLOAT",
      "distribution": {
        "type": "GAUSSIAN",
        "mu": 15.0,
        "sigma": 2.5

The above JSON will create a 2-dimensional feature vector consisting of an integer and float value, with the distribution of these values across multiple cases following uniform and Gaussian distributions respectively.

You can create a new Project, and add the new Definition ready for use as follows:

import hypervector
hypervector.API_KEY = "YOUR_API_KEY"

project = hypervector.Project.new()
definition = hypervector.Definition.new(

The Definition will now be available (and editable) on the Hypervector Dashboard.

# Creating a Definition (dashboard)

Hypervector's Dashboard (opens new window) also provides an interface to easily build and edit Definitions. This allows for quicker prototyping of test cases.


# Adding an Ensemble

In order to generate test data from a Definition, we need to add an Ensemble instance. Ensembles are collections of test cases that use their parent Definition to generate distributions of data.

ensemble = hypervector.Ensemble.new(

Creating an Ensemble initialises a dedicated endpoint for the test data to be retrieved from. This can be then used as a canonical resource across as many environments and scenarios as is required.

The size attribute denotes how many cases should be generated for this Ensemble (in this example, the Ensemble will have 1000 examples derived from the Definition).

Ensembles are consistent

Data in an Ensemble is deterministic: the same examples will always be returned for a particular Ensemble. The canonical identifier for any given Ensemble is its ensemble_uuid value

Definition edits auto-create new Ensembles

If you edit a Definition, new Ensembles (with a new ensemble_uuid) will be generated for each existing Ensemble

# Get data from an Ensemble

Now we have a Definition with an Ensemble, we can query Hypervector in order to quickly retrieve the generated test data.

ensemble = definition.ensembles[0]
data = ensemble.hypervectors()

We can also directly retrieve the Ensemble by its ensemble_uuid. This can be useful when prototyping:

ensemble = hypervector.Ensemble.get('ENSEMBLE_UUID')
data = ensemble.hypervectors()

Direct retrieval of Ensembles

As a Definition is edited, new Ensembles will be auto-generated with new ensemble_uuid values. This can mean directly retrieved Ensembles might be from an earlier version of the Definition. To ensure the most up-to-date Ensemble is used in production environments, we recommend using the .ensembles attribute for a given Definition