feat: API endpoint for fetching an SBOM's AI models

[jcrossley3]

Fixes #2254

Summary by Sourcery

Add a new SBOM API surface for listing AI models associated with an SBOM, including service and model scaffolding.

New Features:

• Expose a GET /v2/sbom/{id}/models endpoint to return paginated AI models linked to a given SBOM.
• Introduce an SbomModel type to represent AI models in the SBOM domain model.

Enhancements:

• Add a service-layer method to fetch paginated SBOM models, currently implemented as a stub returning an empty result set.

[sourcery-ai]

Reviewer's Guide

Adds a new HTTP GET endpoint to list AI models associated with an SBOM and wires it through the SBOM service layer with a placeholder implementation and corresponding SbomModel data type.

Sequence diagram for the new SBOM AI models listing endpoint

sequenceDiagram
    actor ApiClient
    participant ActixRouter
    participant SbomEndpoints as SbomEndpointsModule
    participant SbomService
    participant Database

    ApiClient->>ActixRouter: GET /v2/sbom/{id}/models
    ActixRouter->>SbomEndpoints: models(fetch, db, id, search, paginated)
    SbomEndpoints->>Database: begin_read()
    Database-->>SbomEndpoints: tx
    SbomEndpoints->>SbomService: fetch_sbom_models(sbom_id, search, paginated, tx)
    SbomService-->>SbomEndpoints: PaginatedResults<SbomPackage>
    SbomEndpoints-->>ApiClient: 200 OK JSON PaginatedResults<SbomModel>

Loading

Class diagram for SbomModel and updated SbomService method

classDiagram
    class SbomModel {
        <<struct>>
        +Default()
        +Serialize
        +Deserialize
        +ToSchema
        // TODO fields
    }

    class SbomPackage {
        <<struct>>
        // Existing fields not shown
    }

    class Paginated {
        <<struct>>
        // Existing pagination parameters
    }

    class Query {
        <<struct>>
        // Existing search parameters
    }

    class PaginatedResults~T~ {
        <<struct>>
        +Vec~T~ items
        +u64 total
    }

    class SbomService {
        +fetch_sbom_models(sbom_id Uuid, search Query, paginated Paginated, connection ConnectionTrait) Result~PaginatedResults~SbomPackage~~
    }

    class ConnectionTrait {
        <<trait>>
    }

    SbomService --> ConnectionTrait : uses
    SbomService --> PaginatedResults : returns
    PaginatedResults --> SbomPackage : T = SbomPackage
    SbomService --> Query : param
    SbomService --> Paginated : param

    class ModelsEndpoint {
        <<actix_handler>>
        +models(fetch SbomService, db Database, id Uuid, search Query, paginated Paginated, Require_ReadSbom) HttpResponse~PaginatedResults~SbomModel~~
    }

    class Database {
        +begin_read() Transaction
    }

    class Transaction {
        <<struct>>
    }

    ModelsEndpoint --> SbomService : calls fetch_sbom_models
    ModelsEndpoint --> Database : uses begin_read
    Database --> Transaction : returns
    ModelsEndpoint --> Transaction : passes_to_service
    ModelsEndpoint --> PaginatedResults : responds_with
    PaginatedResults --> SbomModel : T = SbomModel

    class Require_ReadSbom {
        <<guard>>
    }

Loading

File-Level Changes

Change	Details	Files
Expose a new /v2/sbom/{id}/models endpoint that returns paginated AI models for a given SBOM ID.	Extend SBOM model imports to include the new SbomModel type for use in endpoint responses. Define a models handler with utoipa documentation that accepts SBOM ID, query, and pagination parameters, authorizes with ReadSbom, invokes the service to fetch models, and returns the result as JSON.	modules/fundamental/src/sbom/endpoints/mod.rs
Introduce service-layer API for fetching SBOM models with a stubbed implementation.	Add fetch_sbom_models method on SbomService that accepts SBOM ID, search, pagination, and a database connection and returns PaginatedResults with SbomPackage as a placeholder item type. Instrument the new method with tracing and return an empty result set as a TODO placeholder.	modules/fundamental/src/sbom/service/sbom.rs
Add a new SbomModel domain type to represent AI models associated with an SBOM.	Define an SbomModel struct with standard serialization, schema, and equality derives, currently with a TODO body for future fields. Adjust module exports/usages to make SbomModel available to endpoint code.	modules/fundamental/src/sbom/model/mod.rs

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#2254	Add an HTTP API endpoint for fetching AI models associated with an SBOM (including routing, handler, and OpenAPI/utoipa documentation).	✅
#2254	Implement backend service logic to retrieve AI models for a given SBOM and return them via the new endpoint.	❌	The SbomService::fetch_sbom_models method is only a stub marked with TODO; it returns an empty list and total=0 instead of performing any real query or retrieval of models.
#2254	Define the data model representing an AI model (SbomModel) with appropriate fields used by the API response.	❌	The SbomModel struct is defined but contains no fields and a TODO comment, so the data model for AI models is not actually implemented.

Possibly linked issues

• Implement api endpoint for fetching the AI models associated with an SBOM #2254: PR adds /v2/sbom/{id}/models endpoint and SbomService::fetch_sbom_models, directly implementing the requested API.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.37%. Comparing base (bb24af9) to head (ffb4bca).

Files with missing lines	Patch %	Lines
modules/fundamental/src/sbom/endpoints/mod.rs	0.00%	14 Missing ⚠️
modules/fundamental/src/sbom/service/sbom.rs	0.00%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2255      +/-   ##
==========================================
- Coverage   70.41%   70.37%   -0.05%     
==========================================
  Files         413      413              
  Lines       23874    23896      +22     
  Branches    23874    23896      +22     
==========================================
+ Hits        16812    16816       +4     
- Misses       6152     6163      +11     
- Partials      910      917       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.