types

README

pkg/types

Canonical interface definitions for Augustus components.

Interfaces

Prober (core execution)

type Prober interface {
    Probe(ctx context.Context, gen Generator) ([]*attempt.Attempt, error)
    Name() string
}

When to implement: Every probe must implement Prober. This is the minimal interface required for probe execution by the scanner.

ProbeMetadata (optional metadata)

type ProbeMetadata interface {
    Description() string
    Goal() string
    GetPrimaryDetector() string
    GetPrompts() []string
}

When to implement: Implement ProbeMetadata when your probe needs to expose metadata for reporting, filtering, or UI display. This is optional -- probes that only need execution can implement just Prober.

Why Two Interfaces?

This follows the Interface Segregation Principle (ISP). Clients that only execute probes (like Scanner) don't pay for metadata methods they don't use. Clients that need metadata (like report generators) can check for it.

Type Assertion Pattern

Use type assertion to check if a Prober also provides metadata:

prober := getProber() // returns types.Prober

// Check for metadata support
if pm, ok := prober.(types.ProbeMetadata); ok {
    fmt.Println(pm.Description())
    fmt.Println(pm.Goal())
    fmt.Println(pm.GetPrimaryDetector())
} else {
    // Probe does not provide metadata -- that's fine
}

Generator

type Generator interface {
    Generate(ctx context.Context, conv *attempt.Conversation, n int) ([]attempt.Message, error)
    ClearHistory()
    Name() string
    Description() string
}

All LLM backends implement Generator. Generators wrap API clients with authentication, rate limiting, and conversation management.

Detector

type Detector interface {
    Detect(ctx context.Context, a *attempt.Attempt) ([]float64, error)
    Name() string
    Description() string
}

Detectors analyze LLM outputs and assign vulnerability scores (0.0 = safe, 1.0 = vulnerable).

Backward Compatibility

Other packages (e.g., pkg/probes, pkg/scanner) re-export these interfaces as type aliases:

// In pkg/probes/probe.go:
type Prober = types.Prober
type ProbeMetadata = types.ProbeMetadata

This ensures existing imports continue to work while the canonical definitions live here.

Documentation

Overview

Package types provides shared interfaces used across Augustus packages.

This package eliminates interface duplication by providing canonical definitions that other packages import via type aliases for backward compatibility.

Index

• type Detector
• type Generator
• type ProbeMetadata
• type Prober

Types

type Detector

type Detector interface {
	// Detect analyzes an attempt's outputs and returns scores.
	// Returns one score per output, each in range [0.0, 1.0].
	// 0.0 = safe/passed, 1.0 = vulnerable/failed.
	Detect(ctx context.Context, a *attempt.Attempt) ([]float64, error)
	// Name returns the fully qualified detector name (e.g., "always.Pass").
	Name() string
	// Description returns a human-readable description.
	Description() string
}

Detector is the interface that all detector implementations must satisfy. Detectors analyze LLM outputs from attempts and assign vulnerability scores. Scores range from 0.0 (safe/passed) to 1.0 (vulnerable/failed).

type Generator

type Generator interface {
	// Generate sends a conversation to the model and returns responses.
	// n specifies the number of completions to generate.
	Generate(ctx context.Context, conv *attempt.Conversation, n int) ([]attempt.Message, error)
	// ClearHistory resets any conversation state in the generator.
	ClearHistory()
	// Name returns the fully qualified generator name (e.g., "openai.GPT4").
	Name() string
	// Description returns a human-readable description.
	Description() string
}

Generator is the interface that all generator implementations must satisfy. Generators wrap LLM APIs with a common interface for authentication, rate limiting, and conversation management.

type ProbeMetadata

type ProbeMetadata interface {
	// Description returns a human-readable description.
	Description() string
	// Goal returns the probe's objective (matches Python garak).
	Goal() string
	// GetPrimaryDetector returns the recommended detector for this probe.
	GetPrimaryDetector() string
	// GetPrompts returns the attack prompts used by this probe.
	GetPrompts() []string
}

ProbeMetadata is an optional interface for probes that expose metadata. Implement this interface when your probe needs to expose information for reporting, filtering, or UI display. Clients can check for metadata support via type assertion: if pm, ok := prober.(ProbeMetadata); ok { ... }

type Prober

type Prober interface {
	// Probe executes the attack against the generator.
	Probe(ctx context.Context, gen Generator) ([]*attempt.Attempt, error)
	// Name returns the fully qualified probe name (e.g., "test.Blank").
	Name() string
}

Prober is the minimal interface that all probes must implement. This follows the Interface Segregation Principle (ISP) - clients that only execute probes (like Scanner) don't pay for metadata methods they don't use.