Update src/aibom_generator/utils.py

src/aibom_generator/utils.py

@@ -371,7 +371,7 @@ def apply_completeness_penalties(original_score: float, missing_fields: Dict[str
     adjusted_score = original_score * penalty_factor
     
     return {
-        "adjusted_score": round(adjusted_score, 2),
+        "adjusted_score": round(adjusted_score, 1),  # Round to 1 decimal place
         "penalty_applied": penalty_reason is not None,
         "penalty_reason": penalty_reason,
         "penalty_factor": penalty_factor
@@ -404,15 +404,11 @@ def generate_field_recommendations(missing_fields: Dict[str, List[str]]) -> List
                 "priority": "high",
                 "field": field,
                 "message": f"Missing critical field: {field}",
-                "recommendation": f"Add {field} information to improve documentation completeness"
+                "recommendation": f"Add {field} to improve documentation completeness"
             })
     
-    # Then suggest important fields (limit to top 3)
-    important_count = 0
+    # Then important fields
     for field in missing_fields["important"]:
-        if important_count >= 3:
-            break
-            
         if field in VALIDATION_MESSAGES:
             recommendations.append({
                 "priority": "medium",
@@ -420,15 +416,27 @@ def generate_field_recommendations(missing_fields: Dict[str, List[str]]) -> List
                 "message": VALIDATION_MESSAGES[field]["missing"],
                 "recommendation": VALIDATION_MESSAGES[field]["recommendation"]
             })
-            important_count += 1
         else:
             recommendations.append({
                 "priority": "medium",
                 "field": field,
                 "message": f"Missing important field: {field}",
-                "recommendation": f"Consider adding {field} information to enhance documentation"
+                "recommendation": f"Consider adding {field} for better documentation"
             })
-            important_count += 1
+    
+    # Finally supplementary fields (limit to top 5)
+    supplementary_count = 0
+    for field in missing_fields["supplementary"]:
+        if supplementary_count >= 5:
+            break
+            
+        recommendations.append({
+            "priority": "low",
+            "field": field,
+            "message": f"Missing supplementary field: {field}",
+            "recommendation": f"Consider adding {field} for comprehensive documentation"
+        })
+        supplementary_count += 1
     
     return recommendations
 
@@ -444,142 +452,260 @@ def _validate_ai_requirements(aibom: Dict[str, Any]) -> List[Dict[str, Any]]:
         List of validation issues
     """
     issues = []
+    issue_codes = set()
+    
+    # Check required fields
+    for field in ["bomFormat", "specVersion", "serialNumber", "version"]:
+        if field not in aibom:
+            issues.append({
+                "severity": ValidationSeverity.ERROR.value,
+                "code": f"MISSING_{field.upper()}",
+                "message": f"Missing required field: {field}",
+                "path": f"$.{field}"
+            })
+            issue_codes.add(f"MISSING_{field.upper()}")
+    
+    # Check bomFormat
+    if "bomFormat" in aibom and aibom["bomFormat"] != "CycloneDX":
+        issues.append({
+            "severity": ValidationSeverity.ERROR.value,
+            "code": "INVALID_BOM_FORMAT",
+            "message": f"Invalid bomFormat: {aibom['bomFormat']}. Must be 'CycloneDX'",
+            "path": "$.bomFormat"
+        })
+        issue_codes.add("INVALID_BOM_FORMAT")
+    
+    # Check specVersion
+    if "specVersion" in aibom and aibom["specVersion"] != "1.6":
+        issues.append({
+            "severity": ValidationSeverity.ERROR.value,
+            "code": "INVALID_SPEC_VERSION",
+            "message": f"Invalid specVersion: {aibom['specVersion']}. Must be '1.6'",
+            "path": "$.specVersion"
+        })
+        issue_codes.add("INVALID_SPEC_VERSION")
+    
+    # Check serialNumber
+    if "serialNumber" in aibom and not aibom["serialNumber"].startswith("urn:uuid:"):
+        issues.append({
+            "severity": ValidationSeverity.ERROR.value,
+            "code": "INVALID_SERIAL_NUMBER",
+            "message": f"Invalid serialNumber format: {aibom['serialNumber']}. Must start with 'urn:uuid:'",
+            "path": "$.serialNumber"
+        })
+        issue_codes.add("INVALID_SERIAL_NUMBER")
+    
+    # Check version
+    if "version" in aibom:
+        if not isinstance(aibom["version"], int):
+            issues.append({
+                "severity": ValidationSeverity.ERROR.value,
+                "code": "INVALID_VERSION_TYPE",
+                "message": f"Invalid version type: {type(aibom['version'])}. Must be an integer",
+                "path": "$.version"
+            })
+            issue_codes.add("INVALID_VERSION_TYPE")
+        elif aibom["version"] <= 0:
+            issues.append({
+                "severity": ValidationSeverity.ERROR.value,
+                "code": "INVALID_VERSION_VALUE",
+                "message": f"Invalid version value: {aibom['version']}. Must be positive",
+                "path": "$.version"
+            })
+            issue_codes.add("INVALID_VERSION_VALUE")
+    
+    # Check metadata
+    if "metadata" not in aibom:
+        issues.append({
+            "severity": ValidationSeverity.ERROR.value,
+            "code": "MISSING_METADATA",
+            "message": "Missing metadata section",
+            "path": "$.metadata"
+        })
+        issue_codes.add("MISSING_METADATA")
+    else:
+        metadata = aibom["metadata"]
+        
+        # Check timestamp
+        if "timestamp" not in metadata:
+            issues.append({
+                "severity": ValidationSeverity.WARNING.value,
+                "code": "MISSING_TIMESTAMP",
+                "message": "Missing timestamp in metadata",
+                "path": "$.metadata.timestamp"
+            })
+            issue_codes.add("MISSING_TIMESTAMP")
+        
+        # Check tools
+        if "tools" not in metadata or not metadata["tools"] or len(metadata["tools"]) == 0:
+            issues.append({
+                "severity": ValidationSeverity.WARNING.value,
+                "code": "MISSING_TOOLS",
+                "message": "Missing tools in metadata",
+                "path": "$.metadata.tools"
+            })
+            issue_codes.add("MISSING_TOOLS")
+        
+        # Check authors
+        if "authors" not in metadata or not metadata["authors"] or len(metadata["authors"]) == 0:
+            issues.append({
+                "severity": ValidationSeverity.WARNING.value,
+                "code": "MISSING_AUTHORS",
+                "message": "Missing authors in metadata",
+                "path": "$.metadata.authors"
+            })
+            issue_codes.add("MISSING_AUTHORS")
+        else:
+            # Check author properties
+            for i, author in enumerate(metadata["authors"]):
+                if "url" in author:
+                    issues.append({
+                        "severity": ValidationSeverity.ERROR.value,
+                        "code": "INVALID_AUTHOR_PROPERTY",
+                        "message": "Author objects should not contain 'url' property, use 'email' instead",
+                        "path": f"$.metadata.authors[{i}].url"
+                    })
+                    issue_codes.add("INVALID_AUTHOR_PROPERTY")
+        
+        # Check properties
+        if "properties" not in metadata or not metadata["properties"] or len(metadata["properties"]) == 0:
+            issues.append({
+                "severity": ValidationSeverity.INFO.value,
+                "code": "MISSING_PROPERTIES",
+                "message": "Missing properties in metadata",
+                "path": "$.metadata.properties"
+            })
+            issue_codes.add("MISSING_PROPERTIES")
     
-    # Check basic structure
-    if "components" not in aibom or not aibom["components"]:
+    # Check components
+    if "components" not in aibom or not aibom["components"] or len(aibom["components"]) == 0:
         issues.append({
             "severity": ValidationSeverity.ERROR.value,
             "code": "MISSING_COMPONENTS",
-            "message": "AIBOM must contain at least one component",
+            "message": "Missing components section or empty components array",
             "path": "$.components"
         })
-        return issues  # Can't continue validation without components
-        
-    # Check for schema compliance issues with authors
-    if "metadata" in aibom and "authors" in aibom["metadata"]:
-        for i, author in enumerate(aibom["metadata"]["authors"]):
-            if "url" in author:
-                issues.append({
-                    "severity": ValidationSeverity.ERROR.value,
-                    "code": "INVALID_AUTHOR_PROPERTY",
-                    "message": "Author object contains 'url' property which is not allowed in CycloneDX schema. Use 'email' instead.",
-                    "path": f"$.metadata.authors[{i}].url"
-                })
+        issue_codes.add("MISSING_COMPONENTS")
+    else:
+        components = aibom["components"]
         
-    # Validate each component
-    for i, component in enumerate(aibom["components"]):
-        component_path = f"$.components[{i}]"
+        # Check first component (AI model)
+        component = components[0]
         
-        # Check component type
+        # Check type
         if "type" not in component:
             issues.append({
                 "severity": ValidationSeverity.ERROR.value,
                 "code": "MISSING_COMPONENT_TYPE",
-                "message": "Component must have a type",
-                "path": f"{component_path}.type"
+                "message": "Missing type in first component",
+                "path": "$.components[0].type"
             })
-        elif component.get("type") != "machine-learning-model":
+            issue_codes.add("MISSING_COMPONENT_TYPE")
+        elif component["type"] != "machine-learning-model":
             issues.append({
-                "severity": ValidationSeverity.WARNING.value,
+                "severity": ValidationSeverity.ERROR.value,
                 "code": "INVALID_COMPONENT_TYPE",
-                "message": "Component type should be 'machine-learning-model' for AI components",
-                "path": f"{component_path}.type"
+                "message": f"Invalid type in first component: {component['type']}. Must be 'machine-learning-model'",
+                "path": "$.components[0].type"
             })
-            
-        # Check PURL format
-        if "purl" not in component:
+            issue_codes.add("INVALID_COMPONENT_TYPE")
+        
+        # Check name
+        if "name" not in component or not component["name"]:
             issues.append({
                 "severity": ValidationSeverity.ERROR.value,
+                "code": "MISSING_COMPONENT_NAME",
+                "message": "Missing name in first component",
+                "path": "$.components[0].name"
+            })
+            issue_codes.add("MISSING_COMPONENT_NAME")
+        
+        # Check bom-ref
+        if "bom-ref" not in component or not component["bom-ref"]:
+            issues.append({
+                "severity": ValidationSeverity.ERROR.value,
+                "code": "MISSING_BOM_REF",
+                "message": "Missing bom-ref in first component",
+                "path": "$.components[0].bom-ref"
+            })
+            issue_codes.add("MISSING_BOM_REF")
+        
+        # Check purl
+        if "purl" not in component or not component["purl"]:
+            issues.append({
+                "severity": ValidationSeverity.WARNING.value,
                 "code": "MISSING_PURL",
-                "message": "Component must have a PURL",
-                "path": f"{component_path}.purl"
+                "message": "Missing purl in first component",
+                "path": "$.components[0].purl"
             })
-        else:
-            purl = component["purl"]
-            if not purl.startswith("pkg:"):
-                issues.append({
-                    "severity": ValidationSeverity.ERROR.value,
-                    "code": "INVALID_PURL_FORMAT",
-                    "message": "PURL must start with 'pkg:'",
-                    "path": f"{component_path}.purl"
-                })
-            elif "huggingface" in purl and "@" not in purl and "version" in component:
-                issues.append({
-                    "severity": ValidationSeverity.WARNING.value,
-                    "code": "MISSING_VERSION_IN_PURL",
-                    "message": "PURL should include version information with '@' for versioned components",
-                    "path": f"{component_path}.purl"
-                })
-                
-        # Check model card
-        if "modelCard" not in component:
+            issue_codes.add("MISSING_PURL")
+        elif not component["purl"].startswith("pkg:"):
+            issues.append({
+                "severity": ValidationSeverity.ERROR.value,
+                "code": "INVALID_PURL_FORMAT",
+                "message": f"Invalid purl format: {component['purl']}. Must start with 'pkg:'",
+                "path": "$.components[0].purl"
+            })
+            issue_codes.add("INVALID_PURL_FORMAT")
+        elif "@" not in component["purl"]:
+            issues.append({
+                "severity": ValidationSeverity.WARNING.value,
+                "code": "MISSING_VERSION_IN_PURL",
+                "message": f"Missing version in purl: {component['purl']}. Should include version after '@'",
+                "path": "$.components[0].purl"
+            })
+            issue_codes.add("MISSING_VERSION_IN_PURL")
+        
+        # Check description
+        if "description" not in component or not component["description"]:
+            issues.append({
+                "severity": ValidationSeverity.WARNING.value,
+                "code": "MISSING_DESCRIPTION",
+                "message": "Missing description in first component",
+                "path": "$.components[0].description"
+            })
+            issue_codes.add("MISSING_DESCRIPTION")
+        elif len(component["description"]) < 20:
+            issues.append({
+                "severity": ValidationSeverity.INFO.value,
+                "code": "SHORT_DESCRIPTION",
+                "message": f"Description is too short: {len(component['description'])} characters. Recommended minimum is 20 characters",
+                "path": "$.components[0].description"
+            })
+            issue_codes.add("SHORT_DESCRIPTION")
+        
+        # Check modelCard
+        if "modelCard" not in component or not component["modelCard"]:
             issues.append({
                 "severity": ValidationSeverity.WARNING.value,
                 "code": "MISSING_MODEL_CARD",
-                "message": "AI component should include a model card",
-                "path": f"{component_path}.modelCard"
+                "message": "Missing modelCard in first component",
+                "path": "$.components[0].modelCard"
             })
+            issue_codes.add("MISSING_MODEL_CARD")
         else:
             model_card = component["modelCard"]
-            model_card_path = f"{component_path}.modelCard"
             
-            # Check model parameters
-            if "modelParameters" not in model_card:
+            # Check modelParameters
+            if "modelParameters" not in model_card or not model_card["modelParameters"]:
                 issues.append({
                     "severity": ValidationSeverity.WARNING.value,
                     "code": "MISSING_MODEL_PARAMETERS",
-                    "message": "Model card should include model parameters",
-                    "path": f"{model_card_path}.modelParameters"
+                    "message": "Missing modelParameters in modelCard",
+                    "path": "$.components[0].modelCard.modelParameters"
                 })
-                
+                issue_codes.add("MISSING_MODEL_PARAMETERS")
+            
             # Check considerations
-            if "considerations" not in model_card:
+            if "considerations" not in model_card or not model_card["considerations"]:
                 issues.append({
-                    "severity": ValidationSeverity.INFO.value,
+                    "severity": ValidationSeverity.WARNING.value,
                     "code": "MISSING_CONSIDERATIONS",
-                    "message": "Model card should include considerations section for ethical considerations, limitations, etc.",
-                    "path": f"{model_card_path}.considerations"
+                    "message": "Missing considerations in modelCard",
+                    "path": "$.components[0].modelCard.considerations"
                 })
-                
-    # Validate metadata
-    if "metadata" not in aibom:
-        issues.append({
-            "severity": ValidationSeverity.ERROR.value,
-            "code": "MISSING_METADATA",
-            "message": "AIBOM must contain metadata",
-            "path": "$.metadata"
-        })
-    else:
-        metadata = aibom["metadata"]
-        metadata_path = "$.metadata"
-        
-        # Check tools
-        if "tools" not in metadata or not metadata["tools"]:
-            issues.append({
-                "severity": ValidationSeverity.WARNING.value,
-                "code": "MISSING_TOOLS",
-                "message": "Metadata should include tools that generated the AIBOM",
-                "path": f"{metadata_path}.tools"
-            })
-            
-        # Check authors
-        if "authors" not in metadata or not metadata["authors"]:
-            issues.append({
-                "severity": ValidationSeverity.INFO.value,
-                "code": "MISSING_AUTHORS",
-                "message": "Metadata should include authors information",
-                "path": f"{metadata_path}.authors"
-            })
-            
-        # Check properties
-        if "properties" not in metadata or not metadata["properties"]:
-            issues.append({
-                "severity": ValidationSeverity.INFO.value,
-                "code": "MISSING_PROPERTIES",
-                "message": "Metadata should include properties for additional information",
-                "path": f"{metadata_path}.properties"
-            })
-            
+                issue_codes.add("MISSING_CONSIDERATIONS")
+    
     return issues
 
 
@@ -594,8 +720,6 @@ def _generate_validation_recommendations(issues: List[Dict[str, Any]]) -> List[s
         List of recommendations
     """
     recommendations = []
-    
-    # Group issues by code
     issue_codes = set(issue["code"] for issue in issues)
     
     # Generate recommendations based on issue codes
@@ -747,12 +871,16 @@ def calculate_industry_neutral_score(aibom: Dict[str, Any]) -> Dict[str, Any]:
     
     # Score each field based on classification
     scores_by_category = {category: 0 for category in max_scores.keys()}
+    max_possible_by_category = {category: 0 for category in max_scores.keys()}
     
     for field, classification in FIELD_CLASSIFICATION.items():
         tier = classification["tier"]
         weight = classification["weight"]
         category = classification["category"]
         
+        # Add to max possible score for this category
+        max_possible_by_category[category] += weight
+        
         # Check if field is present
         is_present = check_field_in_aibom(aibom, field)
         
@@ -766,16 +894,27 @@ def calculate_industry_neutral_score(aibom: Dict[str, Any]) -> Dict[str, Any]:
         field_checklist[field] = f"{'✔' if is_present else '✘'} {importance_indicator}"
     
     # Normalize category scores to max_scores
+    normalized_scores = {}
     for category in scores_by_category:
-        scores_by_category[category] = min(scores_by_category[category], max_scores[category])
+        if max_possible_by_category[category] > 0:
+            # Normalize to the max score for this category
+            normalized_score = (scores_by_category[category] / max_possible_by_category[category]) * max_scores[category]
+            normalized_scores[category] = min(normalized_score, max_scores[category])
+        else:
+            normalized_scores[category] = 0
     
-    # Calculate total score (sum of weighted category scores)
+    # Calculate total score (sum of weighted normalized scores)
     total_score = 0
-    for category in scores_by_category:
+    for category, score in normalized_scores.items():
+        # Each category contributes its percentage to the total
         category_weight = max_scores[category] / sum(max_scores.values())
-        total_score += scores_by_category[category] * category_weight
+        total_score += score * category_weight
+    
+    # Round to one decimal place
+    total_score = round(total_score, 1)
     
-    total_score = total_score * 100  # Convert to percentage
+    # Ensure score is between 0 and 100
+    total_score = max(0, min(total_score, 100))
     
     # Determine completeness profile
     profile = determine_completeness_profile(aibom, total_score)
@@ -788,9 +927,10 @@ def calculate_industry_neutral_score(aibom: Dict[str, Any]) -> Dict[str, Any]:
     
     return {
         "total_score": penalty_result["adjusted_score"],
-        "section_scores": scores_by_category,
+        "section_scores": normalized_scores,
         "max_scores": max_scores,
         "field_checklist": field_checklist,
+        "field_tiers": {field: info["tier"] for field, info in FIELD_CLASSIFICATION.items()},
         "missing_fields": missing_fields,
         "completeness_profile": profile,
         "penalty_applied": penalty_result["penalty_applied"],
@@ -831,12 +971,12 @@ def calculate_completeness_score(aibom: Dict[str, Any], validate: bool = True, u
                 if error_count > 0:
                     # Severe penalty for errors (up to 50% reduction)
                     error_penalty = min(0.5, error_count * 0.1)
-                    result["total_score"] = round(result["total_score"] * (1 - error_penalty), 2)
+                    result["total_score"] = round(result["total_score"] * (1 - error_penalty), 1)
                     result["validation_penalty"] = f"-{int(error_penalty * 100)}% due to {error_count} schema errors"
                 elif warning_count > 0:
                     # Minor penalty for warnings (up to 20% reduction)
                     warning_penalty = min(0.2, warning_count * 0.05)
-                    result["total_score"] = round(result["total_score"] * (1 - warning_penalty), 2)
+                    result["total_score"] = round(result["total_score"] * (1 - warning_penalty), 1)
                     result["validation_penalty"] = f"-{int(warning_penalty * 100)}% due to {warning_count} schema warnings"
         
         return result
@@ -900,15 +1040,17 @@ def calculate_completeness_score(aibom: Dict[str, Any], validate: bool = True, u
         model_card_score = sum([
             10 if card.get("modelParameters") else 0,
             10 if card.get("quantitativeAnalysis") else 0,
-            10 if card.get("considerations") and len(card["considerations"]) > 50 else 0
+            10 if card.get("considerations") and isinstance(card["considerations"], dict) and len(str(card["considerations"])) > 50 else 0
         ])
         for field in card_fields:
             field_checklist[f"modelCard.{field}"] = "✔" if field in card else "✘"
-            if field == "considerations" and field in card and len(card["considerations"]) <= 50:
+            if field == "considerations" and field in card and (not isinstance(card["considerations"], dict) or len(str(card["considerations"])) <= 50):
                 field_checklist[f"modelCard.{field}"] = "✘"
 
     # External References (10 points max)
-    ext_refs = aibom.get("externalReferences", [])
+    ext_refs = []
+    if components and components[0].get("externalReferences"):
+        ext_refs = components[0].get("externalReferences")
     ext_score = 0
     for ref in ext_refs:
         url = ref.get("url", "").lower()
@@ -922,23 +1064,32 @@ def calculate_completeness_score(aibom: Dict[str, Any], validate: bool = True, u
     field_checklist["externalReferences"] = "✔" if ext_refs else "✘"
 
     # Calculate total score
+    section_scores = {
+        "required_fields": required_score,
+        "metadata": metadata_score,
+        "component_basic": component_score,
+        "component_model_card": model_card_score,
+        "external_references": ext_score
+    }
+    
+    # Calculate weighted total score
     total_score = (
-        (required_score * 0.20) +
-        (metadata_score * 0.20) +
-        (component_score * 0.20) +
-        (model_card_score * 0.30) +
-        (ext_score * 0.10)
+        (section_scores["required_fields"] / max_scores["required_fields"]) * 20 +
+        (section_scores["metadata"] / max_scores["metadata"]) * 20 +
+        (section_scores["component_basic"] / max_scores["component_basic"]) * 20 +
+        (section_scores["component_model_card"] / max_scores["component_model_card"]) * 30 +
+        (section_scores["external_references"] / max_scores["external_references"]) * 10
     )
+    
+    # Round to one decimal place
+    total_score = round(total_score, 1)
+    
+    # Ensure score is between 0 and 100
+    total_score = max(0, min(total_score, 100))
 
     result = {
-        "total_score": round(total_score, 2),
-        "section_scores": {
-            "required_fields": required_score,
-            "metadata": metadata_score,
-            "component_basic": component_score,
-            "component_model_card": model_card_score,
-            "external_references": ext_score
-        },
+        "total_score": total_score,
+        "section_scores": section_scores,
         "max_scores": max_scores,
         "field_checklist": field_checklist
     }
@@ -958,12 +1109,12 @@ def calculate_completeness_score(aibom: Dict[str, Any], validate: bool = True, u
             if error_count > 0:
                 # Severe penalty for errors (up to 50% reduction)
                 error_penalty = min(0.5, error_count * 0.1)
-                result["total_score"] = round(result["total_score"] * (1 - error_penalty), 2)
+                result["total_score"] = round(result["total_score"] * (1 - error_penalty), 1)
                 result["validation_penalty"] = f"-{int(error_penalty * 100)}% due to {error_count} schema errors"
             elif warning_count > 0:
                 # Minor penalty for warnings (up to 20% reduction)
                 warning_penalty = min(0.2, warning_count * 0.05)
-                result["total_score"] = round(result["total_score"] * (1 - warning_penalty), 2)
+                result["total_score"] = round(result["total_score"] * (1 - warning_penalty), 1)
                 result["validation_penalty"] = f"-{int(warning_penalty * 100)}% due to {warning_count} schema warnings"
     
     return result