CalypsoAI
Search K

Appearance

Working with scanner versions ​

INFERENCE DEFEND

This article is meant for Inference Defend users.

ROLES AND PERMISSIONS

To complete the tasks described in this section, make sure you have the required permissions.

Custom scanners can have multiple versions, with different configurations. CalypsoAI provides several options for working with custom scanner versions.

You can do the following:

Get a list of scanner versions ​

When working with scanners, you may find it useful to see all the versions created for a particular scanner.

To get the list of scanner versions:

  1. Add your token and scanner ID values to the following sample:

    python
    from calypsoai import CalypsoAI
from calypsoai.datatypes import ProjectConfigScanner, UUID

# Define the URL and token for CalypsoAI
CALYPSOAI_URL="https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN="ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Get the list of all scanner versions
versions = GetScannerVersionsResponse(versions=[version for version in cai.scanners.versions.iterate(scanner="ADD-YOUR-SCANNER-ID-HERE", onlyPublished=False)])

# Print the response
print(versions.model_dump_json(indent=2))

    PUBLISHED SCANNERS

    In the sample Python request, the GetScannerVersionsResponse > onlyPublished attribute is set to False. To get a list containing only the published versions of the scanner, set onlyPublished to True.

  2. Run the script.

  3. Analyze the response.
    The following response sample is a simplified version of a successful request, focusing only on the main details relevant to this specific request.

    json
    [{
  "id": "01982c91-c665-7082-a8b8-b400bac9ec4d",
  "name": "v_2",
  "published": true
},{
  "id": "01982c91-46f0-7009-b409-286411c65035",
  "name": "v_1",
  "published": true
  }
]
    To view the full response, click here.
    json
    [{
    "createdAt": "2025-07-21T10:40:07.781554Z",
    "createdBy": "xxxxxxx",
    "description": "",
    "id": "01982c91-c665-7082-a8b8-b400bac9ec4d",
    "name": "v_2",
    "published": true
 }, {
    "createdAt": "2025-07-21T10:39:35.152053Z",
    "createdBy": "xxxxxxxx",
    "description": "",
    "id": "01982c91-46f0-7009-b409-286411c65035",
    "name": "v_1",
    "published": true
 }
]

Create a scanner version ​

A new scanner version is created each time you update a scanner.

In this scenario, we are going to create the second version of a custom keyword scanner, adding an additional keyword we want to include in the scan.

To create a scanner version:

  1. Edit the following sample.

    python
    from calypsoai import CalypsoAI
from calypsoai.datatypes import KeywordScannerConfig, ScannerDirection,
ScannerVersionInputModel

# Define the URL and token for CalypsoAI
CALYPSOAI_URL="https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN="ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Update the scanner configuration
config = KeywordScannerConfig(words=["hello", "world", "newWord"], type="keyword")

# Update the scanner version
version = ScannerVersionInputModel(name="ADD-YOUR-VERSION-NAME-HERE", description="ADD-YOUR-VERSION-DESCRIPTION-HERE",
published=False, push=False)

# Create the new scanner version
response = cai.scanners.update(scanner = "ADD-YOUR-SCANNER-ID-HERE", name='ADD-YOUR-SCANNER-NAME-HERE',
config=config, direction=ScannerDirection.BOTH, published=False)

# Print the response
print(response.model_dump_json(indent=2))
    • Add your token value.
    • In KeywordScannerConfig, update your scanner's scan parameters, if required.
      In this scenario, we added the keyword newWord to the words list.
    • In ScannerVersionInputModel, do the following:

      SCANNER VERSIONS

      If you don't set a version when updating a custom scanner, the system creates a version for you and automatically assigns a version name, with the following additional configuration:

      • description left empty.
      • published and push set to False.
      • In name, provide a name for your new scanner version.
      • In description, provide a description for your new scanner version.
        This is an optional parameter. You can include it to add context and describe the changes made in each new scanner version.
      • In published, enter either True or False.
        If set to True, the scanner version is published and made available for use.
        The default value for this property is False.
      • In push, enter either True or False.
        If set to True, the scanner version is pushed to all projects in which the scanner is included, and automatically set as the active version. As a prerequisite, the scanner version can only be pushed if published is set to True.
        The default value for this property is False.
    • In cai.scanners.update, do the following:
      • In scanner, provide the ID of the scanner you want to update.
      • In name, provide the name of the scanner you want to update.
      • In direction, define the direction of the scan.
        The direction property defines if the scan analyzes the request, the response, or both. You can choose one of the following three options:
        • REQUEST: Only the request (prompt) is scanned. This is the default selection.
        • RESPONSE: Only the LLM response is scanned.
        • BOTH: Both the request and response are scanned.
      • In published, enter either True or False.

        PUBLISHING SCANNER VERSIONS

        The Python request sample includes two instances of the published property.

        • ScannerVersionInputModel > published
        • cai.scanners.update > published

        Both instances of the published property have the same function - they define if the scanner version is published. The published property in cai.scanners.update is a legacy feature to allow for backwards compatibility.

        • If you don't set a version, or ScannerVersionInputModel is invalid, the value in cai.scanners.update > published is used.
        • If ScannerVersionInputModel includes the published property, this value is used.
        • If the published property is included in both ScannerVersionInputModel and cai.scanners.update, the value in ScannerVersionInputModel > published is used.

  2. Run the script.

  3. Analyze the response.
    The following response sample is a simplified version of a successful request, focusing only on the main details relevant to this specific request.

    json
    {
  "description": "ADD-YOUR-VERSION-DESCRIPTION-HERE",
  "id": "01985693-0471-70ed-9359-527a103f4793",
  "name": "ADD-YOUR-VERSION-NAME-HERE",
  "published": false
}
    To view the full response, click here.
    json
    {
    "createdAt": "2025-07-29T14:25:32.273974Z",
    "createdBy": null,
    "description": "ADD-YOUR-VERSION-DESCRIPTION-HERE",
    "id": "01985693-0471-70ed-9359-527a103f4793",
    "name": "ADD-YOUR-VERSION-NAME-HERE",
    "published": false
}

Publish a scanner version ​

Publishing a scanner version makes it available for scanning prompts and scan requests, and for use in your projects and scanner packages.

To publish a scanner version:

  1. Add your token, scanner ID, and version ID values to the following sample:

    python
    from calypsoai import CalypsoAI

# Define the URL and token for CalypsoAI
CALYPSOAI_URL="https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN="ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Publish the scanner version
cai.scanners.versions.publish(scanner="ADD-YOUR-SCANNER-ID-HERE", version="ADD-YOUR-VERSION-ID-HERE", push=False)

    PUSH TO PROJECTS

    In the sample Python request, the cai.scanners.versions.publish > push attribute is set to False. To push the scanner version to all projects in which the scanner is included, and automatically set the version as the active version, set push to True.

  2. Run the script.
    If the request is successful, you receive the None response.

    THE NONE RESPONSE

    Confirm the scanner version is published by getting the list of scanner versions and checking the published attribute.

Updated at:

CalypsoAI © 2025-present