Aifw 19570 aibom high level client

.github/workflows/python-tests.yml

@@ -33,10 +33,10 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install dependencies
-      run: poetry install
+      run: poetry install --extras aibom
 
     - name: Install extra test dependencies
       run: poetry run pip install boto3 google-auth
 
     - name: Run tests
-      run: poetry run pytest
+      run: poetry run pytest

README.md

@@ -14,6 +14,7 @@ Integrate AI-powered security, privacy, and safety inspections into your Python
   - [Agent Runtime SDK (Recommended)](#agent-runtime-sdk-recommended)
   - [Inspection API](#inspection-api)
   - [Model Scanning API](#model-scanning-api)
+    - [AIBOM API](#aibom-api)
   - [Management API](#management-api)
 - [SDK Structure](#sdk-structure)
 - [Usage Examples](#usage-examples)
@@ -23,6 +24,7 @@ Integrate AI-powered security, privacy, and safety inspections into your Python
   - [MCP Inspection](#mcp-inspection)
   - [MCP Server Scanning](#mcp-server-scanning)
   - [Model Scanning](#model-scanning)
+    - [AIBOM](#aibom)
   - [Management API Examples](#management-api-examples)
   - [Validation API](#validation-api)
 - [Configuration](#configuration)
@@ -186,6 +188,26 @@ if result.status == ScanStatus.COMPLETED:
             print(f"✅ {file_info.name} is clean")
 ```
 
+### AIBOM API
+
+```python
+from aidefense import Config
+from aidefense.aibom.aibom_client import AiBomClient
+
+# Initialize client
+client = AiBomClient(
+    api_key="YOUR_MANAGEMENT_API_KEY",
+    config=Config(management_base_url="https://api.security.cisco.com"),
+)
+
+# Analyze and submit
+report = client.analyze(sources=["/path/to/project"])
+response = client.submit_report_file(raw_data=report)
+print(response.analysis_id, response.status)
+```
+
+See [AIBOM module docs](aidefense/aibom/README.md) for full API reference and additional examples.
+
 ### Management API
 
 ```python
@@ -268,6 +290,13 @@ print(resp.task_id)
 - `modelscan/model_scan_base.py` — ModelScan base class for granular scan operations
 - `modelscan/models.py` — Data models for scan requests, responses, and status information
 
+### AIBOM API
+
+- `aibom/aibom_client.py` — AiBomClient for analyze-and-submit workflows
+- `aibom/aibom_base.py` — AiBom base client for direct AIBOM API operations
+- `aibom/models.py` — Data models for AIBOM requests, responses, and filters
+- `aibom/README.md` — AIBOM usage guide and method examples
+
 ### Management API
 
 - `management/__init__.py` — ManagementClient for accessing all management APIs
@@ -657,6 +686,25 @@ print(f"Scan status: {scan_info.status}")
 print(f"Files analyzed: {len(scan_info.analysis_results.items)}")
 ```
 
+### AIBOM
+
+```python
+from aidefense import Config
+from aidefense.aibom.aibom_client import AiBomClient
+
+client = AiBomClient(
+    api_key="YOUR_MANAGEMENT_API_KEY",
+    config=Config(management_base_url="https://api.security.cisco.com"),
+)
+
+# Run local AIBOM analysis, then submit it
+report = client.analyze(sources=["/path/to/project"])
+submission = client.submit_report_file(raw_data=report)
+print(f"Created analysis: {submission.analysis_id}")
+```
+
+For direct endpoint-style operations (create/list/get/components/summary/delete), use the base client and examples in [aidefense/aibom/README.md](aidefense/aibom/README.md).
+
 ### Management API
 
 #### Managing Applications

aidefense/aibom/README.md

@@ -0,0 +1,159 @@
+# AI Defense AIBOM Module
+
+The AI Defense AIBOM module provides APIs for creating, storing, and querying AI Bill of Materials (AIBOM) analyses. It supports both:
+
+- High-level workflows through `AiBomClient` (analyze sources and submit reports)
+- Low-level API access through `AiBom` (direct CRUD/query operations)
+
+## Features
+
+- **Analyze and Submit**: Run local AIBOM analysis and submit results to AI Defense
+- **Report Submission**: Submit already-generated AIBOM JSON reports
+- **BOM Query APIs**: List BOMs, fetch BOM details, and list BOM components
+- **Summary Statistics**: Retrieve aggregate AIBOM summary metrics
+- **Delete Support**: Remove BOMs by `analysis_id`
+
+## Installation
+
+```bash
+pip install cisco-aidefense-sdk
+```
+
+If you want to use `AiBomClient.analyze(...)`, install the optional AIBOM extra:
+
+```bash
+pip install "cisco-aidefense-sdk[aibom]"
+```
+
+## Quick Start
+
+### High-Level Client: Analyze and Submit
+
+```python
+from aidefense import Config
+from aidefense.aibom.aibom_client import AiBomClient
+
+client = AiBomClient(
+    api_key="YOUR_MANAGEMENT_API_KEY",
+    config=Config(management_base_url="https://api.security.cisco.com"),
+)
+
+# Analyze one or more local sources
+report = client.analyze(sources=["/path/to/project"])
+
+# Submit the generated report
+response = client.submit_report_file(raw_data=report)
+print(response.analysis_id, response.status)
+```
+
+### Submit an Existing Report File
+
+```python
+from pathlib import Path
+from aidefense import Config
+from aidefense.aibom.aibom_client import AiBomClient
+
+client = AiBomClient(
+    api_key="YOUR_MANAGEMENT_API_KEY",
+    config=Config(management_base_url="https://api.security.cisco.com"),
+)
+
+response = client.submit_report_file(file_path=Path("./aibom-report.json"))
+print(response.model_dump_json(indent=2))
+```
+
+### Low-Level Client: Direct AIBOM API Methods
+
+```python
+from aidefense import Config
+from aidefense.aibom.aibom_base import AiBom
+from aidefense.aibom.models import (
+    BomsSummaryRequest,
+    ListBomComponentsRequest,
+    ListBomsRequest,
+)
+
+client = AiBom(
+    api_key="YOUR_MANAGEMENT_API_KEY",
+    config=Config(management_base_url="https://api.security.cisco.com"),
+)
+
+# List BOMs
+boms = client.list_boms(ListBomsRequest(limit=10, offset=0))
+print(f"Found {len(boms.items)} BOMs")
+
+if boms.items:
+    analysis_id = boms.items[0].analysis_id
+
+    # Get one BOM
+    bom = client.get_bom(analysis_id)
+    print(bom.model_dump_json(indent=2))
+
+    # List components
+    components = client.list_bom_components(
+        analysis_id,
+        ListBomComponentsRequest(limit=20, offset=0),
+    )
+    print(f"Components: {len(components.items)}")
+
+# Get summary
+summary = client.get_bom_summary(BomsSummaryRequest())
+print(summary.model_dump_json(indent=2))
+```
+
+## API Surface
+
+### `AiBomClient` Methods
+
+- `analyze(sources, output_file=None, **kwargs) -> dict`
+- `submit_report_file(raw_data=None, file_path=None) -> CreateAnalysisResponse`
+- `analyze_and_submit(sources, output_file=None, **kwargs) -> CreateAnalysisResponse`
+
+### `AiBom` Methods
+
+- `create_analysis(req: CreateAnalysisRequest) -> CreateAnalysisResponse`
+- `list_boms(req: ListBomsRequest) -> ListBomsResponse`
+- `get_bom(analysis_id: str) -> BomDetail`
+- `delete_bom(analysis_id: str) -> None`
+- `list_bom_components(analysis_id: str, req: ListBomComponentsRequest) -> ListBomComponentsResponse`
+- `get_bom_summary(req: BomsSummaryRequest) -> GetBomSummaryResponse`
+
+## BOM Status Reference
+
+| Status                               | Description                    |
+| ------------------------------------ | ------------------------------ |
+| `BOM_STATUS_UNSPECIFIED`             | Status unknown or unspecified  |
+| `BOM_STATUS_COMPLETED`               | Analysis completed successfully |
+| `BOM_STATUS_COMPLETED_WITH_ERRORS`   | Completed, with non-fatal errors |
+| `BOM_STATUS_FAILED`                  | Analysis failed                |
+| `BOM_STATUS_SKIPPED`                 | Analysis was skipped           |
+
+## Source Kind Reference
+
+| Source Kind                  | Description                          |
+| ---------------------------- | ------------------------------------ |
+| `SOURCE_KIND_LOCAL_PATH`     | Local file system source             |
+| `SOURCE_KIND_CONTAINER`      | Container image/source               |
+| `SOURCE_KIND_OTHER`          | Mixed or unknown source type         |
+| `SOURCE_KIND_UNSPECIFIED`    | Unspecified source type              |
+
+## Error Handling
+
+```python
+from aidefense.exceptions import ApiError, ValidationError, SDKError
+
+try:
+    report = client.analyze(sources=["/path/to/project"])
+    response = client.submit_report_file(raw_data=report)
+except ValidationError as e:
+    print(f"Invalid request: {e}")
+except ApiError as e:
+    print(f"API error: {e}")
+except SDKError as e:
+    print(f"SDK error: {e}")
+```
+
+## Related Examples
+
+- `examples/aibom/aibom_client.py`
+- `examples/aibom/aibom_base.py`

aidefense/aibom/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Cisco Systems, Inc. and its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .aibom_client import AiBomClient
+from .aibom_base import AiBom
+from .models import (
+    CreateAnalysisRequest,
+    CreateAnalysisResponse,
+    GetBomSummaryResponse,
+    ListBomComponentsRequest,
+    ListBomComponentsResponse,
+    ListBomsRequest,
+    ListBomsResponse,
+    BomDetail,
+)
+
+__all__ = [
+    "AiBomClient",
+    "AiBom",
+]