Overview

PIE V2 separates the model registry from the tenant context used to run models. Most consumers work with tenant-scoped resources: a client owns domains, domains contain services, and domains or services expose stable assignment keys that run a model version.

Core objects

• Client: A registry tenant. The client_id appears in paths under /v2/clients/{client_id} and is also used for tenant authorization.
• Domain: A business scope under a client. Domains define the features needed to initialize services and can hold domain-scoped assignments.
• Service: A concrete service within a domain. A service stores provided features, resolved defaults, status, and service-scoped assignments.
• Model: A reusable definition in the global model registry. Models have one or more versions.
• Model version: A runnable version with handlers, status, and metadata.
• Assignment: A stable key such as default or forecast that points to one active model version in a domain or service scope.
• Job: A durable async training or inference record. Jobs store input, output, error details, status, timestamps, and optional assignment context.

Relationship map

flowchart TB
    subgraph tenancy [Tenant context]
        Client[Client]
        Domain[Domain]
        DomainFeatures[Domain features]
        Service[Service]
    end

    subgraph engine [Model registry]
        Model[Model]
        Version[Model version]
        Assignment[Model assignment]
        Job[Model job]
        Subscription[Event subscription]
    end

    Client --> Domain
    Domain --> DomainFeatures
    Domain --> Service
    Domain --> Assignment
    Service --> Assignment
    Model --> Version
    Assignment --> Version
    Version --> Job
    Assignment --> Job
    Model --> Subscription

The normal consumer path

1. Obtain a JWT from Cognito.
2. Use the correct client_id for your tenant.
3. Create or read a domain.
4. Initialize a service or use an existing one.
5. Run inference through an assignment key.
6. Poll the returned job until it reaches success or failure.

Use direct model routes when you are managing the model registry itself. Use domain and service assignment routes when you are integrating a business workflow.