AI SBOM Generator API Documentation

Overview

The AI SBOM Generator API provides a comprehensive solution for generating CycloneDX-compliant AI Bill of Materials (AIBOM) for Hugging Face models. This document outlines the available API endpoints, their functionality, and how to interact with them using cURL commands.

Base URL

When deployed on Hugging Face Spaces, the base URL will be:

https://aetheris-ai-aibom-generator.hf.space

Replace this with your actual deployment URL.

API Endpoints

Status Endpoint

Purpose: Check if the API is operational and get version information.

Endpoint: /status

Method: GET

cURL Example:

curl -X GET "https://aetheris-ai-aibom-generator.hf.space/status"

Expected Response:

{
  "status": "operational",
  "version": "1.0.0",
  "generator_version": "1.0.0"
}

Generate AIBOM Endpoint

Purpose: Generate an AI SBOM for a specified Hugging Face model.

Endpoint: /api/generate

Method: POST

Parameters:

model_id (required): The Hugging Face model ID (e.g., 'meta-llama/Llama-2-7b-chat-hf')
include_inference (optional): Whether to use AI inference to enhance the AI SBOM (default: true)
use_best_practices (optional): Whether to use industry best practices for scoring (default: true)
hf_token (optional): Hugging Face API token for accessing private models

cURL Example:

curl -X POST "https://aetheris-ai-aibom-generator.hf.space/api/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "meta-llama/Llama-2-7b-chat-hf",
    "include_inference": true,
    "use_best_practices": true
  }'

Expected Response: JSON containing the generated AIBOM, model ID, timestamp, and download URL.

{
  "aibom": {
    "bomFormat": "CycloneDX",
    "specVersion": "1.6",
    "serialNumber": "urn:uuid:...",
    "version": 1,
    "metadata": { ... },
    "components": [ ... ],
    "dependencies": [ ... ]
  },
  "model_id": "meta-llama/Llama-2-7b-chat-hf",
  "generated_at": "2025-04-24T20:30:00Z",
  "request_id": "...",
  "download_url": "/output/meta-llama_Llama-2-7b-chat-hf_....json"
}

Generate AIBOM with Enhancement Report

Purpose: Generate an AI SBOM with a detailed enhancement report.

Endpoint: /api/generate-with-report

Method: POST

Parameters: Same as /api/generate

cURL Example:

curl -X POST "https://aetheris-ai-aibom-generator.hf.space/api/generate-with-report" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "meta-llama/Llama-2-7b-chat-hf",
    "include_inference": true,
    "use_best_practices": true
  }'

Expected Response: JSON containing the generated AIBOM, model ID, timestamp, download URL, and enhancement report.

{
  "aibom": { ... },
  "model_id": "meta-llama/Llama-2-7b-chat-hf",
  "generated_at": "2025-04-24T20:30:00Z",
  "request_id": "...",
  "download_url": "/output/meta-llama_Llama-2-7b-chat-hf_....json",
  "enhancement_report": {
    "ai_enhanced": true,
    "ai_model": "BERT-base-uncased",
    "original_score": {
      "total_score": 65.5,
      "completeness_score": 65.5
    },
    "final_score": {
      "total_score": 85.2,
      "completeness_score": 85.2
    },
    "improvement": 19.7
  }
}

Get Model Score

Purpose: Get the completeness score for a model without generating a full AIBOM.

Endpoint: /api/models/{model_id}/score

Method: GET

Parameters:

model_id (path parameter): The Hugging Face model ID
hf_token (query parameter, optional): Hugging Face API token for accessing private models
use_best_practices (query parameter, optional): Whether to use industry best practices for scoring (default: true)

cURL Example:

curl -X GET "https://aetheris-ai-aibom-generator.hf.space/api/models/meta-llama/Llama-2-7b-chat-hf/score?use_best_practices=true"

Expected Response: JSON containing the completeness score information.

{
  "total_score": 85.2,
  "section_scores": {
    "required_fields": 20,
    "metadata": 18.5,
    "component_basic": 20,
    "component_model_card": 20.7,
    "external_references": 6
  },
  "max_scores": {
    "required_fields": 20,
    "metadata": 20,
    "component_basic": 20,
    "component_model_card": 30,
    "external_references": 10
  }
}

Batch Generate AIBOMs

Purpose: Start a batch job to generate AIBOMs for multiple models.

Endpoint: /api/batch

Method: POST

Parameters:

model_ids (required): List of Hugging Face model IDs to generate AIBOMs for
include_inference (optional): Whether to use AI inference to enhance the AI SBOM (default: true)
use_best_practices (optional): Whether to use industry best practices for scoring (default: true)
hf_token (optional): Hugging Face API token for accessing private models

cURL Example:

curl -X POST "https://aetheris-ai-aibom-generator.hf.space/api/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "model_ids": [
      "meta-llama/Llama-2-7b-chat-hf",
      "google/flan-t5-base"
    ],
    "include_inference": true,
    "use_best_practices": true
  }'

Expected Response: JSON containing the batch job ID and status information.

{
  "job_id": "...",
  "status": "queued",
  "model_ids": [
    "meta-llama/Llama-2-7b-chat-hf",
    "google/flan-t5-base"
  ],
  "created_at": "2025-04-24T20:30:00Z"
}

Check Batch Job Status

Purpose: Check the status of a batch job.

Endpoint: /api/batch/{job_id}

Method: GET

Parameters:

job_id (path parameter): The ID of the batch job to check

cURL Example:

curl -X GET "https://aetheris-ai-aibom-generator.hf.space/api/batch/{job_id}"

Expected Response: JSON containing the current status of the batch job and results for completed models.

{
  "job_id": "...",
  "status": "processing",
  "model_ids": [
    "meta-llama/Llama-2-7b-chat-hf",
    "google/flan-t5-base"
  ],
  "created_at": "2025-04-24T20:30:00Z",
  "completed": 1,
  "total": 2,
  "results": {
    "meta-llama/Llama-2-7b-chat-hf": {
      "status": "completed",
      "download_url": "/output/meta-llama_Llama-2-7b-chat-hf_....json",
      "enhancement_report": { ... }
    }
  }
}

Download Generated AIBOM

Purpose: Download a previously generated AIBOM file.

Endpoint: /download/{filename}

Method: GET

Parameters:

filename (path parameter): The filename of the AIBOM to download

cURL Example:

curl -X GET "https://aetheris-ai-aibom-generator.hf.space/download/{filename}" \
  -o "downloaded_aibom.json"

Expected Response: The AIBOM JSON file will be downloaded to your local machine.

Form-Based Generation (Web UI)

Purpose: Generate an AIBOM using form data (typically used by the web UI).

Endpoint: /generate

Method: POST

Parameters:

model_id (form field, required): The Hugging Face model ID
include_inference (form field, optional): Whether to use AI inference to enhance the AI SBOM
use_best_practices (form field, optional): Whether to use industry best practices for scoring

cURL Example:

curl -X POST "https://aetheris-ai-aibom-generator.hf.space/generate" \
  -F "model_id=meta-llama/Llama-2-7b-chat-hf" \
  -F "include_inference=true" \
  -F "use_best_practices=true"

Expected Response: HTML page with the generated AIBOM results.

Web UI

The API also provides a web user interface for generating AIBOMs without writing code:

URL: https://aetheris-ai-aibom-generator.hf.space/

The web UI allows you to:

Enter a Hugging Face model ID
Configure generation options
Generate an AIBOM
View the results in a human-friendly format
Download the generated AIBOM as a JSON file

Understanding the Field Checklist

In the Field Checklist tab of the results page, you'll see a list of fields with check marks (✔/✘) and stars (★). Here's what they mean:

Check marks:
- ✔: Field is present in the AIBOM
- ✘: Field is missing from the AIBOM
Stars (importance level):
- ★★★ (three stars): Critical fields - Essential for a valid and complete AIBOM
- ★★ (two stars): Important fields - Valuable information that enhances completeness
- ★ (one star): Supplementary fields - Additional context and details (optional)

Notes on Using the API

When deployed on Hugging Face Spaces, use the correct URL format as shown in the examples.
Some endpoints may have rate limiting or require authentication.
For large responses, consider adding appropriate timeout settings in your requests.
If you encounter CORS issues, you may need to add appropriate headers.
For downloading files, specify the output file name in your client code.

Error Handling

The API returns standard HTTP status codes:

200: Success
400: Bad Request (invalid parameters)
404: Not Found (resource not found)
500: Internal Server Error (server-side error)

Error responses include a detail message explaining the error:

{
  "detail": "Error generating AI SBOM: Model not found"
}

Completeness Score

The completeness score is calculated based on the presence and quality of various fields in the AIBOM. The score is broken down into sections:

Required Fields (20 points): Basic required fields for a valid AIBOM
Metadata (20 points): Information about the AIBOM itself
Component Basic Info (20 points): Basic information about the AI model component
Model Card (30 points): Detailed model card information
External References (10 points): Links to external resources

The total score is a weighted sum of these section scores, with a maximum of 100 points.

Enhancement Report

When AI enhancement is enabled, the API uses an inference model to extract additional information from the model card and other sources. The enhancement report shows:

Original Score: The completeness score before enhancement
Enhanced Score: The completeness score after enhancement
Improvement: The point increase from enhancement
AI Model Used: The model used for enhancement

This helps you understand how much the AI enhancement improved the AIBOM's completeness.