Create docs/AI_SBOM_API_doc.md

docs/AI_SBOM_API_doc.md

@@ -0,0 +1,359 @@
+# 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**:
+```bash
+curl -X GET "https://aetheris-ai-aibom-generator.hf.space/status"
+```
+
+**Expected Response**:
+```json
+{
+  "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**:
+```bash
+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.
+```json
+{
+  "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**:
+```bash
+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.
+```json
+{
+  "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**:
+```bash
+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.
+```json
+{
+  "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**:
+```bash
+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.
+```json
+{
+  "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**:
+```bash
+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.
+```json
+{
+  "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**:
+```bash
+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**:
+```bash
+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:
+1. Enter a Hugging Face model ID
+2. Configure generation options
+3. Generate an AIBOM
+4. View the results in a human-friendly format
+5. 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
+
+1. When deployed on Hugging Face Spaces, use the correct URL format as shown in the examples.
+2. Some endpoints may have rate limiting or require authentication.
+3. For large responses, consider adding appropriate timeout settings in your requests.
+4. If you encounter CORS issues, you may need to add appropriate headers.
+5. 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:
+```json
+{
+  "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:
+
+1. **Required Fields** (20 points): Basic required fields for a valid AIBOM
+2. **Metadata** (20 points): Information about the AIBOM itself
+3. **Component Basic Info** (20 points): Basic information about the AI model component
+4. **Model Card** (30 points): Detailed model card information
+5. **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:
+
+1. **Original Score**: The completeness score before enhancement
+2. **Enhanced Score**: The completeness score after enhancement
+3. **Improvement**: The point increase from enhancement
+4. **AI Model Used**: The model used for enhancement
+
+This helps you understand how much the AI enhancement improved the AIBOM's completeness.