Models and Errors

Structured SDK responses use Pydantic models. Resource models such as Evaluation inherit from VijilModel, while generated API models such as RedteamStatusResponse inherit directly from BaseModel. SDK exceptions inherit from VijilError. Hand-curated models inherit from VijilModel, which ignores unknown response fields. Models generated from the Console schemas inherit directly from Pydantic’s BaseModel. When vijil.models exports a model, import it there. Treat vijil._generated as internal implementation detail.

Pagination

`Page[T]`

Generic paginated response returned by resource collection methods such as list() and client.evaluations.responses().

page = client.agents.list()

for agent in page:
    print(agent.id, agent.agent_name)

print(page.items)      # list[Agent]
print(page.total)      # total matching records
print(page.has_more)   # whether len(page.items) is less than page.total

Page[T] normalizes the Console’s items or results collections and its total or count fields. Some methods intentionally return a plain list, such as client.rca_runs.list().

Core Models

`Evaluation`

Returned by client.evaluate() for behavioral evaluations. Trust Scores and Harness fields do not apply to Red Team evaluations.

evaluation.id             # str
evaluation.agent_id       # str | None
evaluation.status         # str
evaluation.harness_names  # list[str]
evaluation.trust_score    # float | None
evaluation.scores         # dict[str, float] | None
evaluation.dimensions     # Dimensions | None
evaluation.created_at     # int | str | None
evaluation.completed_at   # int | str | None
evaluation.error_message  # str | None

The behavioral poller treats completed, succeeded, saved, failed, and cancelled as terminal statuses.

`EvaluationResponse`

Returned in the page.items list from client.evaluations.responses(). Each model represents one prompt and Agent response from a completed behavioral evaluation.

response.harness_id       # str
response.scenario_id      # str
response.probe_id         # str
response.probe_score      # float
response.prompt_id        # str
response.prompt_text      # str | None
response.response_text    # str
response.status           # "passed" | "failed"
response.detector_results # dict[str, Any]

probe_score and status describe the parent Probe and repeat on each of its prompt rows. detector_results contains the raw per-Detector results for that prompt. This model does not apply to Red Team evaluations.

`RedteamStatusResponse`

Returned by client.evaluate(..., type="redteam") and client.evaluations.redteam_status(evaluation_id). This is a Red Team progress snapshot, not a Trust Score.

status.evaluation_id       # str
status.status              # str
status.phase               # str | None
status.current_wave        # int | None
status.attackers_completed # int | None
status.degraded            # bool | None

Fields	What They Show
`phase`, `current_wave`, `max_waves`, `seeds_in_wave`	Current stage and wave progress
`attackers_completed`, `attackers_errored`, `attackers_timed_out`, `attackers_cancelled`, `attackers_total`	Attacker outcomes and total count
`wave_breakdown`	Per-wave attacker counts, judgments, errors, and degradation indicators
`created_at`, `started_at`, `completed_at`	Run timestamps, when available
`error_message`, `degraded`, `degradation_reason`, `attack_error_types`	Failure and degradation details

A Red Team run can report created, starting, or running before it reaches a terminal status: succeeded, failed, cancelled, or degraded. A degraded run has finished with some attackers lost, so inspect its error and wave details before relying on the report. Red Team does not use the behavioral completed or saved statuses.

`Dimensions`

dimensions.reliability  # float | None
dimensions.security     # float | None
dimensions.safety       # float | None

The SDK builds dimensions from the Console’s pillar score fields or its scores dictionary.

`EvaluationResponse`

client.evaluations.responses() returns a Page[EvaluationResponse] containing individual behavioral Evaluation records.

response.harness_id       # str
response.scenario_id      # str
response.probe_id         # str
response.probe_score      # float
response.prompt_id        # str
response.prompt_text      # str | None
response.response_text    # str
response.status           # "passed" | "failed"
response.detector_results # dict[str, Any]

`Agent`

The Console schema uses agent_name and agent_url as the public field names.

agent.id                 # str
agent.agent_name         # str
agent.model_name         # str
agent.agent_url          # str | None
agent.team_id            # str
agent.status             # str | None
agent.access_level       # str | None
agent.protocol           # str | None
agent.deployment         # str | None
agent.latest_evaluation  # AgentLatestEvaluation | None

The client.agents resource removes API key values from Console responses before returning an Agent.

`Job`

job.id          # str
job.agent_id    # str | None
job.status      # str
job.mode        # str | None
job.created_at  # int | str | None
job.error       # str | None

Lifecycle methods return the terminal Job record even when its status is failed or cancelled. Inspect job.status and job.error after polling.

`TrustScore`

score.evaluation_id  # str | None
score.agent_id       # str | None
score.trust_score    # float | None
score.reliability    # float | None
score.security       # float | None
score.safety         # float | None
score.pillar_details # dict[str, PillarDetail]
score.harness_names  # list[str]
score.status         # str | None
score.evaluated_at   # int | str | None

Use score.summarize(results=results, scale=100) to flatten full Evaluation results into summary, Harness, Scenario, and Probe rows. Get results with client.scores.results().

`DomeConfig`

dome.id             # str | None
dome.agent_id       # str | None
dome.guards         # list[str]
dome.mode           # str
dome.input_guards   # list[str]
dome.output_guards  # list[str]

`Harness` and `Report`

Model	Key Fields	Produced By
`Harness`	`id`, `name`, `type`, `agent_id`, `persona_ids`, `policy_ids`, `status`, `prompt_count`, `workflow`	`client.harnesses.*`
`Report`	`id`, `agent_id`, `status`, `format`, `created_at`	`client.reports.*`

For a custom Harness, show() and create(wait=True) populate workflow with the generation status when available. Report.created_at can be a Unix timestamp or an ISO-formatted string.

Other Models

Model	Key Fields	Produced By
`Genome`	`id`, `agent_id`, `version`, `genes`, `created_at`	`client.genomes.*`
`GenomeDiff`	`genome_id`, `v1`, `v2`, `changes`	`client.genomes.diff()`
`Proposal`	`id`, `agent_id`, `genome_id`, `genome_version`, `status`, `mutations`, `fitness_delta`	`client.proposals.*`
`Deployment`	`id`, `agent_id`, `runtime`, `status`, `url`, `version`	`client.deploy()`
`DiscoveredAgent`	`id`, `name`, `source`, `framework`, `status`, `description`	`client.discover()`
`Trace`	`trace_id`, `agent_id`, `duration_ms`, `spans`, `timestamp`	`client.monitor.traces()`
`LogEntry`	`agent_id`, `level`, `message`, `timestamp`	`client.monitor.logs()`
`Persona`	`id`, `team_id`, `name`, `role`, `intent`, `knowledge_level`, `skill_level`	`client.personas.*`
`Policy`	`id`, `team_id`, `name`, `category`, `status`, `source_text`, `tags`, `rules_count`, `workflow_id`, `rule_extraction`	`client.policies.*`
`TunnelCredential`	`provider`, `token`, `binding_url`	`client.agent_tunnel.get()`
`AnalyzerRunSummary`	`run_id`, `agent_id`, `eval_id`, `status`, `ticket_count`	`client.rca_runs.list()`
`AnalyzerRunDetail`	Summary fields plus `failure_class`, `evidence`, and `error`	`client.rca_runs.show()`
`Ticket`	`ticket_id`, `title`, `priority`, `description`, `actions`, `status`	`client.rca_runs.tickets()`

MonitorSummary and Detection models exist for forward compatibility, but their corresponding resource read methods currently raise NotImplementedError. See SDK Resources for supported telemetry operations.

Errors

Import SDK exceptions from vijil.exceptions:

from vijil.exceptions import (
    ConsoleRejected,
    ContractDrift,
    NetworkError,
    SDKValidationFailed,
    VijilAuthError,
    VijilConfigError,
    VijilError,
    VijilJobFailedError,
    VijilNotFoundError,
    VijilRateLimitError,
    VijilServerError,
    VijilValidationError,
)

All concrete SDK exceptions inherit from VijilError. The hierarchy supports two ways to classify a failure:

VijilError
├── ConsoleRejected
│   ├── VijilAuthError
│   ├── VijilNotFoundError
│   ├── VijilValidationError
│   ├── VijilRateLimitError
│   └── VijilServerError
├── SDKValidationFailed
├── NetworkError
├── ContractDrift
├── VijilJobFailedError
└── VijilConfigError

Source-Attributed Errors

Each concrete exception exposes a source and a remediation hint.

Exception	Source	Meaning	Specific Attributes
`ConsoleRejected`	`"console"`	Console returned a non-success HTTP response	`reason`, `status_code`
`SDKValidationFailed`	`"sdk"`	The SDK rejected invalid arguments before sending a request	`field`, `expected`, `actual`
`NetworkError`	`"network"`	No HTTP response arrived because of a transport failure	`transport_error`
`ContractDrift`	`"drift"`	A successful response did not match the model expected by the SDK	`expected_shape`, `actual_shape`

Catch ConsoleRejected to handle every Console rejection together, or catch one of its status-specific subclasses.

HTTP Status Errors

Exception	HTTP Status	Specific Attributes
`VijilAuthError`	`401`, `403`	`status_code`
`VijilNotFoundError`	`404`	`resource_type`, `resource_id` when available
`VijilValidationError`	`400`, `422`	`details`
`VijilRateLimitError`	`429`	`retry_after`
`VijilServerError`	`5xx`	`status_code`

Other non-success statuses, such as 409, raise ConsoleRejected directly.

SDKValidationFailed and VijilValidationError represent different failure locations. The first means local SDK validation stopped the request. The second means the Console rejected a request with HTTP 400 or 422.

Configuration and Job Errors

Exception	When
`VijilConfigError`	The SDK cannot load or decode required local configuration or state
`VijilJobFailedError`	Exception type defined for asynchronous job failures; current lifecycle methods return failed terminal models instead of raising it

Error-Handling Pattern

Catch the narrowest actionable exception before its parent class.

from vijil.exceptions import (
    ConsoleRejected,
    ContractDrift,
    NetworkError,
    SDKValidationFailed,
    VijilError,
    VijilNotFoundError,
)

try:
    evaluation = client.evaluate("agent-id", baseline=True)
except SDKValidationFailed as error:
    print(f"Invalid {error.field}: expected {error.expected}")
except VijilNotFoundError as error:
    print(f"Resource not found: {error.resource_id or error}")
except ConsoleRejected as error:
    print(f"Console rejected the request ({error.status_code}): {error.reason}")
except NetworkError as error:
    print(f"Network failure: {error.transport_error}")
except ContractDrift as error:
    print(f"Unexpected response shape: {error.actual_shape}")
except VijilError as error:
    print(f"Vijil SDK failure: {error}")
else:
    print(evaluation.trust_score)

Automatic Retries

The HTTP client makes at most three total attempts for a request:

For transport failures and 5xx responses, it waits one second before the second attempt and two seconds before the third.
For 429 responses, it uses a numeric Retry-After value. If the header is missing or invalid, it waits one second.
For a 401 response, it performs one refresh-and-retry when the credentials support token refresh.

After the final attempt, the SDK raises NetworkError, VijilRateLimitError, or VijilServerError, depending on the last failure. Individual operations can disable retries when repeating the request would be unsafe. Multipart uploads do not retry automatically.

Next Steps

SDK Resources

See which methods produce each model.

Lifecycle Methods

Use high-level workflows and inspect their return values.

SDK Setup

Configure authentication, gateways, and team defaults.

Run Evaluations

Start Evaluations and retrieve their results.

Get Started

Evaluate Agents

Red Team

Protect Agents

Reference

Models and Errors

`Page[T]`

Core Models

`Evaluation`

`EvaluationResponse`

`RedteamStatusResponse`

`Dimensions`

`EvaluationResponse`

`Agent`

`Job`

`TrustScore`

`DomeConfig`

`Harness` and `Report`

Other Models

Errors

Source-Attributed Errors

HTTP Status Errors

Configuration and Job Errors

Error-Handling Pattern

Automatic Retries

Next Steps

SDK Resources

Lifecycle Methods

SDK Setup

Run Evaluations

​Pagination

​Page[T]

​Core Models

​Evaluation

​EvaluationResponse

​RedteamStatusResponse

​Dimensions

​EvaluationResponse

​Agent

​Job

​TrustScore

​DomeConfig

​Harness and Report

​Other Models

​Errors

​Source-Attributed Errors

​HTTP Status Errors

​Configuration and Job Errors

​Error-Handling Pattern

​Automatic Retries

​Next Steps

SDK Resources

Lifecycle Methods

SDK Setup

Run Evaluations

Pagination

`Page[T]`

Core Models

`Evaluation`

`EvaluationResponse`

`RedteamStatusResponse`

`Dimensions`

`EvaluationResponse`

`Agent`

`Job`

`TrustScore`

`DomeConfig`

`Harness` and `Report`

Other Models

Errors

Source-Attributed Errors

HTTP Status Errors

Configuration and Job Errors

Error-Handling Pattern

Automatic Retries

Next Steps