Update docs/AI_SBOM_API_doc.md

docs/AI_SBOM_API_doc.md

@@ -6,12 +6,17 @@ The AI SBOM Generator API provides a comprehensive solution for generating Cyclo
 
 ## Base URL
 
-When deployed on Hugging Face Spaces, the base URL will be:
+When deployed on Hugging Face Spaces, the base URL for API access will be:
 ```
 https://aetheris-ai-aibom-generator.hf.space
 ```
 
-Replace this with your actual deployment URL.
+You can also access the web interface through:
+```
+https://huggingface.co/spaces/aetheris-ai/aibom-generator
+```
+
+Both URLs point to the same application, but the first format (hf.space) is preferred for API calls.
 
 ## API Endpoints
 
@@ -211,7 +216,7 @@ curl -X POST "https://aetheris-ai-aibom-generator.hf.space/generate" \
 
 The API also provides a web user interface for generating AI SBOMs without writing code:
 
-**URL**: `https://aetheris-ai-aibom-generator.hf.space/`
+**URL**: `https://huggingface.co/spaces/aetheris-ai/aibom-generator`
 
 The web UI allows you to:
 1. Enter a Hugging Face model ID
@@ -235,7 +240,7 @@ In the Field Checklist tab of the results page, you'll see a list of fields with
 
 ## Security Features
 
-The API includes several security features to protect against Denial of Service (DoS) attacks:
+The API includes several security features to protect against Denial of Service (DoS) attacks and contain resources:
 
 1. **Rate Limiting**: Limits the number of requests a single IP address can make within a specific time window.
 
@@ -243,9 +248,6 @@ The API includes several security features to protect against Denial of Service
 
 3. **Request Size Limiting**: Prevents attackers from sending extremely large payloads that could consume memory or processing resources.
 
-4. **API Key Authentication** (optional): When configured, requires an API key for accessing API endpoints, enabling tracking and control of API usage.
-
-5. **CAPTCHA Verification** (optional): When configured for the web interface, helps ensure requests come from humans rather than bots.
 
 ## Notes on Using the API
 
@@ -274,15 +276,66 @@ Error responses include a detail message explaining the error:
 
 ## Completeness Score
 
-The completeness score is calculated based on the presence and quality of various fields in the AI SBOM. The score is broken down into sections:
+The completeness score evaluates the quality and completeness of the generated AI SBOM. Understanding how this score is calculated is important for interpreting API responses.
+
+### Scoring Formula
+
+The total score is calculated using a **weighted normalization** approach:
+
+```
+Total Score = Sum of (Section Score × Section Weight)
+```
+
+Where:
+- Section Score = Points earned in that section
+- Section Weight = Section's maximum points ÷ Total possible points (100)
+
+### Scoring Categories
+
+The score is divided into five weighted sections:
+
+1. **Required Fields** (20% weight): Basic required fields for a valid AI SBOM
+2. **Metadata** (20% weight): Information about the AI SBOM itself
+3. **Component Basic Info** (20% weight): Basic information about the AI model component
+4. **Model Card** (30% weight): Detailed model card information (higher weight as it contains critical AI information)
+5. **External References** (10% weight): Links to external resources
+
+### Example Calculation
+
+For an SBOM with these section scores:
+- Required Fields: 20 points × 0.20 weight = 4.0 points
+- Metadata: 15 points × 0.20 weight = 3.0 points
+- Component Basic: 10 points × 0.20 weight = 2.0 points
+- Model Card: 10 points × 0.30 weight = 3.0 points
+- External References: 5 points × 0.10 weight = 0.5 points
+
+The total score would be 12.5 points, even though the raw section scores sum to 60 points.
+
+**Note:** The total score is not the sum of section scores. Each section contributes proportionally to its weight in the final score.
 
-1. **Required Fields** (20 points): Basic required fields for a valid AI SBOM
-2. **Metadata** (20 points): Information about the AI SBOM 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
+### Sample API Response
 
-The total score is a weighted sum of these section scores, with a maximum of 100 points.
+When using the score endpoint, you'll receive a response like this:
+
+```json
+{
+  "total_score": 11.3,
+  "section_scores": {
+    "required_fields": 20,
+    "metadata": 11.7,
+    "component_basic": 15.6,
+    "component_model_card": 2.7,
+    "external_references": 10
+  },
+  "max_scores": {
+    "required_fields": 20,
+    "metadata": 20,
+    "component_basic": 20,
+    "component_model_card": 30,
+    "external_references": 10
+  }
+}
+```
 
 ## Enhancement Report