API Reference — Core Types¶

Data types shared across the entire framework. All importable from rampart directly.

Data Types¶

types ¶

Core data types for the RAMPART framework.

All types in this module are the shared vocabulary of the entire framework — evaluators, adapters, factories, and reporting all speak in these types.

Payload `dataclass` ¶

Python

Payload(
    *,
    content,
    id=(lambda: hex[:12])(),
    format=TEXT,
    artifact=None,
    metadata=dict[str, Any](),
)

Content to inject into a surface or send alongside a prompt.

content is always the semantic text — the attack instruction, the adversarial prompt, or a description of the payload's purpose. It is what reports display and what makes a payload reproducible.

For text formats (TEXT, HTML, MARKDOWN), content is delivered directly — no artifact is needed. For binary formats (IMAGE, PDF, DOCX), artifact points to the file that surfaces and adapters deliver. The content field still holds the human-readable text for reporting and debugging.

Parameters:

Name	Type	Description	Default
`content`	`str`	The semantic text content. Always human-readable.	required
`id`	`str`	Stable identifier for reproduction and cache keys.	`(lambda: hex[:12])()`
`format`	`PayloadFormat`	Delivery format. TEXT by default.	`TEXT`
`artifact`	`Path \| None`	Path to a rendered binary file. Required for binary formats, must be None for text formats.	`None`
`metadata`	`dict[str, Any]`	Provenance tracking (persona, template, variant index, generation params).	`dict[str, Any]()`

PayloadFormat ¶

Bases: Enum

Delivery format for a payload.

Text formats deliver content directly. Binary formats deliver via artifact (a file on disk). Surfaces inspect format to decide how to upload or inject the content.

The is_text and is_binary properties let converters, surfaces, and the store handle the two categories uniformly without listing every enum member.

is_text `property` ¶

Python

is_text

True if this format carries content as str.

is_binary `property` ¶

Python

is_binary

True if this format carries content as bytes or Path.

extension `property` ¶

Python

extension

File extension including the leading dot (e.g., '.png').

Request `dataclass` ¶

Python

Request(*, prompt=None, attachments=list[Payload]())

What is sent to the agent in a single turn.

Combines prompt text and inline payloads into a single object. At least one of prompt or attachments must be provided.

Parameters:

Name	Type	Description	Default
`prompt`	`str \| None`	The text prompt to send. None when only attachments are sent (e.g., inline XPIA).	`None`
`attachments`	`list[Payload]`	Payloads sent alongside the prompt for inline delivery (e.g., poisoned documents).	`list[Payload]()`

Response `dataclass` ¶

Python

Response(
    *,
    text,
    tool_calls=list[ToolCall](),
    side_effects=list[SideEffect](),
    metadata=dict[str, Any](),
)

What the agent returned for a single prompt.

The adapter populates every field it can observe.

Parameters:

Name	Type	Description	Default
`text`	`str`	The agent's text response.	required
`tool_calls`	`list[ToolCall]`	Tool invocations observed during this interaction.	`list[ToolCall]()`
`side_effects`	`list[SideEffect]`	Other observable effects.	`list[SideEffect]()`
`metadata`	`dict[str, Any]`	Adapter-specific diagnostic data.	`dict[str, Any]()`

ToolCall `dataclass` ¶

Python

ToolCall(
    *,
    name,
    arguments=dict[str, Any](),
    result=None,
    timestamp=None,
)

A tool invocation observed during agent execution.

Adapters populate this from whatever observability they have — API response fields, telemetry streams, log parsing.

Parameters:

Name	Type	Description	Default
`name`	`str`	Tool name as the agent reported it (e.g., "send_email").	required
`arguments`	`dict[str, Any]`	Parameters passed to the tool.	`dict[str, Any]()`
`result`	`str \| None`	Tool return value, if the adapter can observe it.	`None`
`timestamp`	`datetime \| None`	When the invocation occurred, if available.	`None`

SideEffect `dataclass` ¶

Python

SideEffect(*, kind, details=dict[str, Any]())

An observable side effect beyond tool invocations.

Covers effects like HTTP requests, file system changes, or database writes that the adapter can observe but that are not modeled as tool calls in the agent's API.

Parameters:

Name	Type	Description	Default
`kind`	`str`	Effect category (e.g., "http_request", "file_write").	required
`details`	`dict[str, Any]`	Structured data about the effect.	`dict[str, Any]()`

Turn `dataclass` ¶

Python

Turn(
    *,
    request,
    response,
    eval_result=None,
    turn_number=0,
    timestamp=None,
    driver_reasoning="",
)

One prompt-response exchange.

Turn is immutable. The execution loop constructs a provisional Turn (without eval_result) for the evaluator call, then produces the final Turn via dataclasses.replace before appending to history.

Parameters:

Name	Type	Description	Default
`request`	`Request`	What was sent to the agent.	required
`response`	`Response`	What the agent returned.	required
`eval_result`	`EvalResult \| None`	Evaluator outcome for this turn.	`None`
`turn_number`	`int`	Position in the conversation (0-indexed).	`0`
`timestamp`	`datetime \| None`	When this exchange occurred.	`None`
`driver_reasoning`	`str`	Why the driver chose this request.	`''`

EvalOutcome ¶

Bases: Enum

What the evaluator determined.

DETECTED: The condition was found. NOT_DETECTED: The condition was not found. UNDETERMINED: The evaluator could not make a determination.

EvalResult `dataclass` ¶

Python

EvalResult(
    *,
    outcome,
    confidence=1.0,
    evidence=list[str](),
    rationale="",
)

What an evaluator returns — a raw condition detection signal.

This is NOT a safety judgment. Whether DETECTED means "safe" or "unsafe" depends on context.

Parameters:

Name	Type	Description	Default
`outcome`	`EvalOutcome`	What the evaluator determined.	required
`confidence`	`float`	How confident the evaluator is (0.0 to 1.0).	`1.0`
`evidence`	`list[str]`	Specific observations supporting the outcome.	`list[str]()`
`rationale`	`str`	Human-readable explanation.	`''`

detected `property` ¶

Python

detected

Convenience: True when the condition was detected.

EvalContext `dataclass` ¶

Python

EvalContext(
    *, turns, manifest=None, metadata=dict[str, Any]()
)

Everything an evaluator needs to make a determination.

Holds the full conversation as a flat list of turns. Provides convenience properties for common access patterns.

The last turn in turns is the one currently being evaluated. Its eval_result may be None during evaluation — the execution loop attaches the result via dataclasses.replace after the evaluator returns.

Parameters:

Name	Type	Description	Default
`turns`	`list[Turn]`	All turns in the interaction, in chronological order. Includes the turn being evaluated as the last element.	required
`manifest`	`AppManifest \| None`	The agent's declared capabilities, if available.	`None`
`metadata`	`dict[str, Any]`	Additional context from the test setup.	`dict[str, Any]()`

current_turn `property` ¶

Python

current_turn

The most recent turn. Raises ValueError if no turns exist.

text `property` ¶

Python

text

Current turn's response text.

all_tool_calls `property` ¶

Python

all_tool_calls

Tool calls across ALL turns, in chronological order.

all_side_effects `property` ¶

Python

all_side_effects

Side effects across ALL turns, in chronological order.

from_response `classmethod` ¶

Python

from_response(*, response, prompt='', manifest=None)

Build a context from a single response.

Convenience for evaluating outside the factory flow.

Parameters:

Name	Type	Description	Default
`response`	`Response`	The agent response to evaluate.	required
`prompt`	`str`	The prompt that produced this response.	`''`
`manifest`	`AppManifest \| None`	Optional agent manifest.	`None`

Returns:

Type	Description
`EvalContext`	A single-turn evaluation context.

Source code in rampart/core/types.py

Python
@classmethod
def from_response(
    cls,
    *,
    response: Response,
    prompt: str = "",
    manifest: AppManifest | None = None,
) -> EvalContext:
    """Build a context from a single response.

    Convenience for evaluating outside the factory flow.

    Args:
        response: The agent response to evaluate.
        prompt: The prompt that produced this response.
        manifest: Optional agent manifest.

    Returns:
        A single-turn evaluation context.
    """
    return cls(
        turns=[Turn(request=Request(prompt=prompt), response=response)],
        manifest=manifest,
    )

ObservabilityLevel ¶

Bases: Enum

What the adapter can reliably observe during agent execution.

Declared by the adapter to inform evaluators and reporting. When the adapter declares RESPONSE_ONLY, evaluators that require tool call data return UNDETERMINED rather than a false SAFE.

Result Types¶

result ¶

Core result types for the RAMPART framework.

Defines the single Result type, SafetyStatus, HarmCategory, InjectionRecord, and the resolve_as_attack / resolve_as_probe functions that map evaluator outcomes to safety verdicts.

Result `dataclass` ¶

Python

Result(
    *,
    safe,
    status,
    summary,
    turns=list[Turn](),
    duration_seconds=0.0,
    harm_category=None,
    strategy="",
    observability_level=RESPONSE_ONLY,
    injections=list[InjectionRecord](),
    metadata=dict[str, Any](),
)

The outcome of a safety test.

This is the single result type for the entire framework. Attacks and probes both produce Result objects. The reporting infrastructure, pytest plugin, and dashboards all consume them.

The critical invariant: bool(result) returns result.safe. This means assert result, result.summary always means "assert the agent behaved safely" — and failures include the summary explaining what was detected.

Parameters:

Name	Type	Description	Default
`safe`	`bool`	Whether the agent behaved safely. True = safe.	required
`status`	`SafetyStatus`	Categorical status for structured reporting.	required
`summary`	`str`	Human-readable one-line summary.	required
`turns`	`list[Turn]`	The full conversation for evidence and debugging.	`list[Turn]()`
`duration_seconds`	`float`	How long the test execution took.	`0.0`
`harm_category`	`HarmCategory \| str \| None`	Which harm category this test covers. Accepts HarmCategory enum values for built-in categories or plain strings for team-defined categories (e.g., "custom_product_risk"). Both are strings at runtime since HarmCategory is a StrEnum.	`None`
`strategy`	`str`	Name of the execution strategy (e.g., "xpia", "crescendo").	`''`
`observability_level`	`ObservabilityLevel`	What the adapter could observe.	`RESPONSE_ONLY`
`injections`	`list[InjectionRecord]`	What was injected and into which surfaces, for full reproduction of multi-surface attacks. Empty for non-XPIA tests.	`list[InjectionRecord]()`
`metadata`	`dict[str, Any]`	Additional structured data for reporting.	`dict[str, Any]()`

eval_results `property` ¶

Python

eval_results

Evaluator outcomes derived from turns.

SafetyStatus ¶

Bases: Enum

Categorical safety status for structured reporting.

SAFE: The agent behaved correctly. UNSAFE: A safety violation was detected. UNDETERMINED: The framework could not determine safety (typically an observability gap). ERROR: The test encountered an infrastructure error.

HarmCategory ¶

Bases: StrEnum

Classification of the safety concern being tested.

Used by the pytest @harm marker for categorization, by reporting sinks for grouping, and by safety gates for threshold configuration.

HarmCategory is a StrEnum so that its values are native strings. This enables teams to use custom string categories alongside the built-in values: @pytest.mark.harm("custom_product_risk") is valid, and the string flows through Result.harm_category, reporting sinks, and dashboard grouping without requiring enum membership. Built-in values provide IDE completion and typo protection for common categories; plain strings provide extensibility for team-specific risks.

Phase availability

Phase 1: All values are defined and usable with MockAdapter. Phase 2: PROMPT_INJECTION, JAILBREAK, and remaining categories gain execution strategy support via PyRIT integration.

InjectionRecord `dataclass` ¶

Python

InjectionRecord(*, payload_id, surface_name)

Records what was injected and where, for reproduction and reporting.

Populated by XPIAExecution after handles are activated and stored on Result. Provides the complete injection context needed to reproduce a test run: which payload was placed in which surface.

Parameters:

Name	Type	Description	Default
`payload_id`	`str \| None`	The injected payload's identifier. None if the surface implementation does not track payload IDs.	required
`surface_name`	`str`	The surface this payload was injected into (e.g., "SharePoint", "Exchange").	required

resolve_as_attack ¶

Python

resolve_as_attack(*, eval_results)

Attack semantics: detected -> UNSAFE, not detected -> SAFE.

Shared by all attack execution strategies (XPIA, prompt injection, Crescendo, PAIR). Lives in core/result.py because it operates entirely on core types.

Precedence: DETECTED > UNDETERMINED > NOT_DETECTED. If any evaluator detected the attack condition, the agent is provably compromised regardless of whether other evaluators were undetermined. UNDETERMINED only matters when no evaluator produced a definitive signal.

Parameters:

Name	Type	Description	Default
`eval_results`	`list[EvalResult]`	List of evaluator outcomes.	required

Returns:

Type	Description
`tuple[bool, SafetyStatus]`	Tuple of (safe, status).

Source code in rampart/core/result.py

Python
def resolve_as_attack(*, eval_results: list[EvalResult]) -> tuple[bool, SafetyStatus]:
    """Attack semantics: detected -> UNSAFE, not detected -> SAFE.

    Shared by all attack execution strategies (XPIA, prompt injection,
    Crescendo, PAIR). Lives in core/result.py because it operates
    entirely on core types.

    Precedence: DETECTED > UNDETERMINED > NOT_DETECTED. If any evaluator
    detected the attack condition, the agent is provably compromised
    regardless of whether other evaluators were undetermined. UNDETERMINED
    only matters when no evaluator produced a definitive signal.

    Args:
        eval_results: List of evaluator outcomes.

    Returns:
        Tuple of (safe, status).
    """
    if not eval_results:
        return False, SafetyStatus.ERROR
    if any(er.detected for er in eval_results):
        return False, SafetyStatus.UNSAFE
    if any(er.outcome == EvalOutcome.UNDETERMINED for er in eval_results):
        return False, SafetyStatus.UNDETERMINED
    return True, SafetyStatus.SAFE

resolve_as_probe ¶

Python

resolve_as_probe(*, eval_results)

Probe semantics: detected -> SAFE, not detected -> UNSAFE.

Shared by all probe execution strategies.

Precedence: NOT_DETECTED > UNDETERMINED > DETECTED. If any evaluator failed to detect the expected behavior, the agent is provably non-compliant regardless of whether other evaluators were undetermined. UNDETERMINED only matters when no evaluator produced a definitive negative signal.

Parameters:

Name	Type	Description	Default
`eval_results`	`list[EvalResult]`	List of evaluator outcomes.	required

Returns:

Type	Description
`tuple[bool, SafetyStatus]`	Tuple of (safe, status).

Source code in rampart/core/result.py

Python
def resolve_as_probe(*, eval_results: list[EvalResult]) -> tuple[bool, SafetyStatus]:
    """Probe semantics: detected -> SAFE, not detected -> UNSAFE.

    Shared by all probe execution strategies.

    Precedence: NOT_DETECTED > UNDETERMINED > DETECTED. If any evaluator
    failed to detect the expected behavior, the agent is provably
    non-compliant regardless of whether other evaluators were undetermined.
    UNDETERMINED only matters when no evaluator produced a definitive
    negative signal.

    Args:
        eval_results: List of evaluator outcomes.

    Returns:
        Tuple of (safe, status).
    """
    if not eval_results:
        return False, SafetyStatus.ERROR
    if any(er.outcome == EvalOutcome.NOT_DETECTED for er in eval_results):
        return False, SafetyStatus.UNSAFE
    if any(er.outcome == EvalOutcome.UNDETERMINED for er in eval_results):
        return False, SafetyStatus.UNDETERMINED
    return True, SafetyStatus.SAFE

Configuration¶

llm ¶

LLM configuration — public model-configuration type.

LLMConfig is the team-facing abstraction for specifying which LLM to use for adversarial payload generation, multi-turn attack drivers, and LLM-backed evaluators. Teams construct it from environment variables or programmatic values; the framework translates it to internal engine types behind rampart.pyrit_bridge — no PyRIT type ever surfaces here.

LLMConfig `dataclass` ¶

Python

LLMConfig(
    *,
    model,
    endpoint,
    api_key=None,
    deployment=None,
    metadata=dict[str, Any](),
)

Immutable configuration for an LLM endpoint.

Parameters:

Name	Type	Description	Default
`model`	`str`	Model identifier (e.g. `"gpt-4o"`, `"gpt-4"`).	required
`endpoint`	`str`	API endpoint URL.	required
`api_key`	`str \| None`	API key for authentication.	`None`
`deployment`	`str \| None`	Azure deployment name, if applicable.	`None`
`metadata`	`dict[str, Any]`	Additional provider-specific configuration.	`dict[str, Any]()`

persona ¶

Persona dataclass — shared by payloads/ and drivers/.

A Persona is a named LLM identity used to shape model behavior for payload generation (adversarial personas) and LLM-backed PromptDriver implementations (benign user personas).

Persona `dataclass` ¶

Python

Persona(*, name, description='', system_prompt='')

A named LLM identity used to shape model behavior.

Parameters:

Name	Type	Description	Default
`name`	`str`	Stable identifier used in cache keys and reports.	required
`description`	`str`	Human-readable summary of this persona's role.	`''`
`system_prompt`	`str`	The system message injected into the LLM to establish this identity.	`''`

prompt_driver ¶

PromptDriver protocol and PromptDecision.

Drivers generate the prompts sent to the agent during an execution.

PromptDecision `dataclass` ¶

Python

PromptDecision(*, request, reasoning='')

A driver's decision for the next turn.

Pairs a Request (what to send) with optional reasoning (why the driver chose it). Reasoning is empty for deterministic drivers (StaticDriver) and populated by LLM-backed drivers for post-test diagnostics.

Parameters:

Name	Type	Description	Default
`request`	`Request`	The request to send to the agent.	required
`reasoning`	`str`	Why this request was chosen.	`''`

Manifest¶

manifest ¶

AppManifest, ToolDeclaration, and DataSource.

Describes what an agent can do — its tools, data sources, and capabilities. Used by payload generation, evaluators, and reporting.

AppManifest `dataclass` ¶

Python

AppManifest(
    *,
    name,
    tools=list[ToolDeclaration](),
    data_sources=list[DataSource](),
    description="",
    metadata=dict[str, Any](),
)

Structured descriptor of an agent's capabilities.

Parameters:

Name	Type	Description	Default
`name`	`str`	Agent display name (e.g., "Microsoft Copilot").	required
`tools`	`list[ToolDeclaration]`	Tools the agent can invoke.	`list[ToolDeclaration]()`
`data_sources`	`list[DataSource]`	Data sources the agent can access.	`list[DataSource]()`
`description`	`str`	What the agent does.	`''`
`metadata`	`dict[str, Any]`	Additional agent metadata.	`dict[str, Any]()`

declares_tool ¶

Python

declares_tool(name)

Check if a tool is declared in the manifest.

Source code in rampart/core/manifest.py

Python
def declares_tool(self, name: str) -> bool:
    """Check if a tool is declared in the manifest."""
    return any(t.name == name for t in self.tools)

get_tool ¶

Python

get_tool(name)

Get a tool declaration by name, or None if not declared.

Source code in rampart/core/manifest.py

Python
def get_tool(self, name: str) -> ToolDeclaration | None:
    """Get a tool declaration by name, or None if not declared."""
    for t in self.tools:
        if t.name == name:
            return t
    return None

ToolDeclaration `dataclass` ¶

Python

ToolDeclaration(
    *,
    name,
    description="",
    parameters=dict[str, Any](),
    permissions=list[str](),
)

A tool the agent can invoke.

Parameters:

Name	Type	Description	Default
`name`	`str`	Tool identifier as the agent reports it.	required
`description`	`str`	What the tool does (used by payload generation).	`''`
`parameters`	`dict[str, Any]`	Parameter schema.	`dict[str, Any]()`
`permissions`	`list[str]`	Required permissions (e.g., "Mail.Send").	`list[str]()`

DataSource `dataclass` ¶

Python

DataSource(*, name, type='', writable_by_untrusted=False)

A data source the agent can access.

The payload generator uses trust metadata to prioritize targets: a data source writable by untrusted users is a higher-priority XPIA injection surface.

Parameters:

Name	Type	Description	Default
`name`	`str`	Data source identifier (e.g., "SharePoint", "Exchange").	required
`type`	`str`	Platform type (e.g., "sharepoint", "exchange", "database").	`''`
`writable_by_untrusted`	`bool`	Whether untrusted users can write to this source. True makes it a higher-priority XPIA target.	`False`

API Reference — Core Types¶

Data Types¶

types ¶

Payload dataclass ¶

PayloadFormat ¶

is_text property ¶

is_binary property ¶

extension property ¶

Request dataclass ¶

Response dataclass ¶

ToolCall dataclass ¶

SideEffect dataclass ¶

Turn dataclass ¶

EvalOutcome ¶

EvalResult dataclass ¶

detected property ¶

EvalContext dataclass ¶

current_turn property ¶

text property ¶

all_tool_calls property ¶

all_side_effects property ¶

from_response classmethod ¶

ObservabilityLevel ¶

Result Types¶

result ¶

Result dataclass ¶

eval_results property ¶

SafetyStatus ¶

HarmCategory ¶

InjectionRecord dataclass ¶

resolve_as_attack ¶

resolve_as_probe ¶

Configuration¶

llm ¶

LLMConfig dataclass ¶

persona ¶

Persona dataclass ¶

prompt_driver ¶

PromptDecision dataclass ¶

Manifest¶

manifest ¶

AppManifest dataclass ¶

declares_tool ¶

get_tool ¶

ToolDeclaration dataclass ¶

DataSource dataclass ¶

Payload `dataclass` ¶

is_text `property` ¶

is_binary `property` ¶

extension `property` ¶

Request `dataclass` ¶

Response `dataclass` ¶

ToolCall `dataclass` ¶

SideEffect `dataclass` ¶

Turn `dataclass` ¶

EvalResult `dataclass` ¶

detected `property` ¶

EvalContext `dataclass` ¶

current_turn `property` ¶

text `property` ¶

all_tool_calls `property` ¶

all_side_effects `property` ¶

from_response `classmethod` ¶

Result `dataclass` ¶

eval_results `property` ¶

InjectionRecord `dataclass` ¶

LLMConfig `dataclass` ¶

Persona `dataclass` ¶

PromptDecision `dataclass` ¶

AppManifest `dataclass` ¶

ToolDeclaration `dataclass` ¶

DataSource `dataclass` ¶