providerplaneai
    Preparing search index...

    Class AIClient

    Main orchestrator for ProviderPlaneAI consumers.

    • Load and manage application configuration
    • Register, initialize, and route to AI providers
    • Enforce capability availability and fail-fast error handling
    • Manage session lifecycle and event timelines
    • Provide job-first, provider-agnostic orchestration for all capabilities
    • No provider-specific logic or AI implementation details
    • Providers are opaque containers of capabilities
    • Focuses on orchestration, error handling, and capability-based routing

    Instantiate once, register providers, and use for all AI requests and session management.

    This class is the central hub for all AI operations, ensuring that consumers interact with a unified interface regardless of provider or capability.

    Index

    Constructors

    constructor

    Accessors

    jobManager

    Methods

    analyzeImage analyzeImageStream analyzeVideo chat chatStream createCapabilityJob downloadVideo editImage editImageStream embeddings extendVideo findProvidersByCapability generateImage generateImageStream generateVideo getConfig getProvider moderation registerCapabilityExecutor registerProvider remixVideo setLifecycleHooks transcribeAudio transcribeAudioStream translateAudio tts ttsStream

    Constructors

    Accessors

    Methods

    • Creates a new job for executing a capability with full lifecycle management.

      This is the primary entry point for consumers to submit AI requests. The returned job can be queued, observed, persisted, rerun, and supports streaming or non-streaming execution.

      Features:

      • Supports custom per-job overrides for chunk retention, raw payload retention, and byte budget.
      • Allows specifying a custom provider chain for fallback/routing.
      • Optionally attaches custom lifecycle hooks for job-level observability.
      • By default, adds the job to the JobManager for execution and tracking.

      Type Parameters

      • C extends CapabilityKeyType

        Capability key type (e.g., chat, image, embedding)

      • TInput

        Input type for the capability

      • TOutput

        Output type for the capability

      Parameters

      • capability: C

        The capability key to execute (must be registered).

      • request: AIRequest<TInput>

        The AIRequest payload (input, options, context, etc.).

      • Optionaloptions: {
            addToManager?: boolean;
            lifecycleHooks?: JobLifecycleHooks<TOutput>;
            maxRawBytesPerJob?: number;
            maxStoredResponseChunks?: number;
            providerChain?: ProviderRef[];
            storeRawResponses?: boolean;
        }

        Optional per-job overrides:

        • maxStoredResponseChunks: Max number of response chunks to retain
        • storeRawResponses: Whether to retain raw provider payloads
        • maxRawBytesPerJob: Max bytes of raw payloads to retain
        • providerChain: Custom provider fallback chain for this job
        • addToManager: If false, does not add job to JobManager (manual control)
        • lifecycleHooks: Custom hooks for this job's lifecycle events

      Returns GenericJob<AIRequest<TInput>, TOutput>

      A GenericJob instance representing the full execution lifecycle.

    • Returns all registered providers that support a given capability.

      This method exists primarily for:

      • Capability discovery
      • Diagnostics and introspection
      • Future agent planners and routers

      It does NOT perform routing or ranking.

      Type Parameters

      Parameters

      • capability: C

        The capability key to search for.

      Returns BaseProvider[]

      Array of providers that implement the requested capability.

    • Returns the resolved ProviderPlane application configuration.

      Returns AppConfig

      The loaded application configuration after node-config and environment resolution.

    • Resolves a provider by type and connection name.

      This method intentionally throws hard errors:

      • Missing providers are a configuration error, not a recoverable state

      Type Parameters

      • T extends BaseProvider

        The type of the provider, typically a BaseProvider combined with a capability interface

      Parameters

      • type: AIProviderType

        Provider type to resolve.

      • connectionName: string = "default"

        Optional connection name; defaults to "default".

      Returns T

      The requested provider instance.

      Error if the provider type or connection name is not registered.

    • Registers and initializes a provider instance.

      Invariants:

      • A provider + connectionName pair may only be registered once.
      • Providers are initialized lazily at registration time with config from appConfig.
      • Capability registration is the provider’s responsibility, not the client’s.
      • Executors are set on the provider after registration.

      Parameters

      • provider: BaseProvider

        The provider instance to register.

      • providerType: AIProviderType

        The type of the provider (e.g. OpenAI, Anthropic).

      • connectionName: string = "default"

        Optional connection name; defaults to "default".

      Returns void

      DuplicateProviderRegistrationError if the provider + connectionName is already registered.

      ExecutionPolicyError if the provider configuration is missing.

    • Set lifecycle hooks for metrics, observability, and instrumentation. Can only be set once per client instance.

      Parameters

      Returns void

      Error if hooks are already set.

    Settings

    Member Visibility

    On This Page

    ResponsibilitiesDesignUsage
    Constructors
    Accessors
    Methods