Connectors

Connectors help import reported data from other data sources, such as ATLAS Case studies, NIST CVEs, AIID incidents.

The modules below document all currently supported connectors and connector utilities.

avidtools.connectors.aiid

AIID connector placeholder module.

avidtools.connectors.atlas

Connector utilities for importing and converting MITRE ATLAS data.

import_case_study(case_study_id)[source]

Import a case study from MITRE ATLAS website and return a yaml object.

Parameters:

case_study_id (str) – Identifier of the case studies to be imported. Has the format AML.CSXXXX

Returns:

case_study – Dictionary containing the imported case study.

Return type:

dict

convert_case_study(case_study)[source]

Convert a case study in the ATLAS schema into an AVID report object.

Parameters:

case_study (dict) – Dictionary containing the imported case study.

Returns:

report – an AVID report object containing information in the case study.

Return type:

Report

avidtools.connectors.base

Generic normalize helpers for AVID report JSON and JSONL files.

process_json_file(input_path: Path, dry_run: bool) → int[source]

Normalize a JSON file containing one report object or a list of reports.

process_jsonl_file(input_path: Path, dry_run: bool) → int[source]

Normalize each report object in a JSONL file.

normalize_file(input_path: Path, dry_run: bool = False) → int[source]

Dispatch normalize processing based on input file extension.

avidtools.connectors.cve

Connector utilities for importing and converting CVEs.

import_cve(cve_id)[source]

Import a CVE from the NVD API and return a JSON dump object.

Parameters:

cve_id (str) – Identifier of the CVE to be imported. Has the format CVE-2XXX-XXXXX

Returns:

cve – JSON dump object containing the imported CVE information.

Return type:

nvdlib.classes.CVE

convert_cve(cve)[source]

Convert a CVE into an AVID report object.

Parameters:

cve (nvdlib.classes.CVE) – JSON dump object containing the imported CVE information.

Returns:

vuln – an AVID vulnerability object containing information in the CVE.

Return type:

Vulnerability

avidtools.connectors.garak

Garak-specific normalize helpers for AVID report JSON and JSONL files.

normalize_file(input_path: Path, dry_run: bool = False, cache_path: Path = PosixPath('/home/smajumdar/avidml/avidtools/avidtools/connectors/.garak_probe_summary_cache.json')) → int[source]

Normalize a Garak JSON/JSONL input file and optionally rewrite in place.

avidtools.connectors.inspect

Connector helpers for converting and normalizing Inspect evaluation reports.

exception UnsupportedInspectBenchmarkError[source]

Bases: RuntimeError

Raised when an Inspect benchmark cannot be resolved to a supported page.

import_eval_log(file_path: str) → Any[source]

Import an Inspect evaluation log from a file.

Parameters:

file_path (str) – Path to the evaluation log file (.eval or .json).

Returns:

eval_log – The loaded evaluation log.

Return type:

EvalLog

convert_eval_log(file_path: str, normalize: bool = False) → List[Report][source]

Convert an Inspect evaluation log into a list of AVID Report objects.

Parameters:

  • file_path (str) – Path to the evaluation log file (.eval or .json).

  • normalize (bool) – If True, run normalize steps that fetch benchmark overview/scoring and apply report normalizations.

Returns:

A list of AVID Report objects created from the evaluation log.

Return type:

List[Report]

normalize_report_data(report: dict)[source]

Apply Inspect normalize transformations to a report dictionary.

process_report(file_path: Path)[source]

Load, normalize, and rewrite a single Inspect report file.

avidtools.connectors.url

URL connector for AVID that scrapes web content and uses an AI agent to create AVID reports.

class URLConnector(api_key: str | None = None, model: str = 'gpt-4o-mini')[source]

Bases: object

Connector to scrape URLs and create AVID reports using AI.

scrape_url(url: str) → dict[source]

Scrape content from a URL.

Parameters:

url (str) – The URL to scrape.

Returns:

Dictionary containing scraped content with keys: url, title, text, html.

Return type:

dict

create_report_from_url(url: str, max_retries: int = 2) → Report[source]

Scrape a URL and create an AVID report using AI.

Parameters:

  • url (str) – The URL to scrape and analyze.

  • max_retries (int, default=2) – Maximum number of retries if AI response parsing fails.

Returns:

The generated AVID Report object.

Return type:

Report

fetch_and_convert(url: str, api_key: str | None = None, model: str = 'gpt-4o-mini') → Report[source]

Convenience function to scrape a URL and create an AVID report.

Parameters:

  • url (str) – The URL to scrape and analyze.

  • api_key (str, optional) – OpenAI API key. If not provided, will use OPENAI_API_KEY environment variable.

  • model (str, default="gpt-4o-mini") – The OpenAI model to use for report generation.

Returns:

The generated AVID Report object.

Return type:

Report

avidtools.connectors.utils

Reusable normalization helpers for review workflows.

to_list(value)[source]

Coerce a scalar or list-like input into a list of strings.

extract_model_names(report: dict, preferred_model_name: str | None = None) → List[str][source]

Extract and deduplicate model names from report fields.

apply_model_developer_mapping(report: dict, model_names: List[str] | None = None) → bool[source]

Normalize developer/deployer fields for a report when inference matches.

apply_openai_system_artifact_type(report: dict, model_names: List[str] | None = None) → bool[source]

Set artifact type to System for GPT/OpenAI-context report artifacts.

apply_normalizations(report: dict, preferred_model_name: str | None = None) → bool[source]

Apply the default normalization suite to a report.

apply_review_normalizations(report: dict, preferred_model_name: str | None = None) → bool[source]

Backward-compatible alias for default normalizations.

choose_model_subject_label(report: dict) → str[source]

Choose whether descriptions should refer to an LLM or AI system.