Invoker

Invoker

Define and manage invoker scripts in the Sierra Dev. Invoker scripts are used to execute specific actions in a controlled environment.

Invoker Example

import sierra

# Define an InvokerScript with dependencies and an entry point
invoker = sierra.InvokerScript(
    name="example",
    description="An example invoker script."
)

@invoker.dependency
def helper_function(param: int) -> int:
    return param + 1

@invoker.entry_point
def run(param: sierra.Param[int, sierra.SierraOption(description="An integer parameter.")]) -> None:
    result = helper_function(param)
    print(f"Result: {result}")

# Register the invoker
sierra.register_invoker(invoker)

sierra.invoker

Sierra Invoker Script.

The core InvokerScript class that developers use to define, annotate, and register SIERRA invoker scripts. Supports V1 (batch) and V2 (streaming) protocols, STRING, FILE, and IMAGE parameter types, and PRIMARY + MANDATORY option flags.

Usage

import sierra

invoker = sierra.InvokerScript(
    name="subdomain_finder",
    description="Discover subdomains for a target domain",
    protocol="V2",
)

@invoker.entry_point
def run(domain: str, timeout: int = 30) -> None:
    '''
    Subdomain discovery tool.

    Parameters

    domain : str
        Target domain to enumerate.
    timeout : int
        Request timeout in seconds.
    '''
    ...

Classes

InvokerScript

Python

InvokerScript(name: str, description: str | None = None, protocol: typing.Literal['V1', 'V2'] = 'V1')

Typed invoker script wrapper for building SIERRA canvas integrations.

Generates config.yaml entries and standalone argparse-compatible Python scripts from annotated function signatures.

PARAMETER	DESCRIPTION
name	Unique identifier for the invoker. Must be a valid Python identifier (lowercase + underscores recommended). TYPE: str
description	Brief description shown in the SIERRA canvas context menu. TYPE: str or None DEFAULT: None
protocol	Execution protocol: - "V1" (default): Batch mode — script runs to completion, outputs a single JSON block. - "V2": Streaming mode — script emits incremental JSON events line-by-line to stdout in real-time. TYPE: Literal[V1, V2] DEFAULT: 'V1'

ATTRIBUTE	DESCRIPTION
name	The unique name of the script. TYPE: str
description	A short description of the script. TYPE: str or None
protocol	The execution protocol version. TYPE: Literal[V1, V2]
params	List of extracted parameter metadata. TYPE: list[SierraInvokerParam]
deps	List of registered dependency functions. TYPE: list[Callable]
requirements	List of pip package requirements. TYPE: list[str]
command	The generated CLI command template. TYPE: str or None
filename	Path to the source file containing the entry point. TYPE: pathlib.Path

Attributes

name instance-attribute

Python

name: str = name

description instance-attribute

Python

description: str | None = description

protocol instance-attribute

Python

protocol: typing.Literal['V1', 'V2'] = protocol

params instance-attribute

Python

params: list[sierra_abc_sierra.SierraInvokerParam] = []

deps instance-attribute

Python

deps: list[_TCallable] = []

requirements instance-attribute

Python

requirements: list[str] = []

command instance-attribute

Python

command: str | None = None

filename instance-attribute

Python

filename: pathlib.Path

Functions

verify_signature staticmethod

Python

verify_signature(func: _TCallable) -> None

Verify that function parameters are valid for invoker generation.

Rejects *args and **kwargs — all parameters must be named.

PARAMETER	DESCRIPTION
func	The function to verify. TYPE: Callable

RAISES	DESCRIPTION
TypeError	If variadic parameters are found.

entry_point

Python

entry_point(func: _TCallable) -> _TCallable

Register a Python function as the invoker's entry point.

Extracts parameter metadata from the function signature and docstring. Supports both Annotated[T, SierraOption] and plain type annotations.

PARAMETER	DESCRIPTION
func	The function to register. TYPE: Callable

RETURNS	DESCRIPTION
Callable	The original function (unmodified).

RAISES	DESCRIPTION
ValueError	If the function has no parameters.
TypeError	If variadic parameters are found.

dependancy

Python

dependancy(func: _TCallable) -> _TCallable

Register a dependency function that will be inlined into the compiled standalone script.

PARAMETER	DESCRIPTION
func	The dependency function. TYPE: Callable

RETURNS	DESCRIPTION
Callable	The original function (unmodified).

requirement

Python

requirement(requirement: list[str]) -> None

Add pip package requirements for this invoker.

PARAMETER	DESCRIPTION
requirement	List of pip package specifiers (e.g. ["requests", "dnspython>=2.0"]). TYPE: list[str]

set_command

Python

set_command(command: str) -> None

Set the generated CLI command template.

PARAMETER	DESCRIPTION
command	The command string with parameter placeholders. TYPE: str