Provider Context and Dependency Injection

Vue 3 SDK uses Vue 3's provide/inject mechanism to manage AaaS Pilot Kit instance lifecycle and state sharing.

Dependency Injection System

Recommended Usage

• Regular scenarios: Use provideAaaSPilotKit - This is the recommended standard method, suitable for most applications
• Multi-instance scenarios: Use useAaaSPilotKitProvider + provide - Used when you need to manage multiple independent AaaS Pilot Kit instances in the same application

provideAaaSPilotKit

Recommended - Vue 3 dependency injection provider, responsible for creating/destroying underlying createAaaSPilotKit controller, and injecting state to child components.

function provideAaaSPilotKit<AS extends BaseAgentService = BaseAgentService>(
    options: IOptions<AS>
): IAaaSPilotKitProvider<AS>

Core Responsibilities

• Automatically creates controller on first call and when options change
• Automatically executes controller.dispose() on component unmount
• Synchronously monitors events like ready, mute, is_rendering_change, generating reactive state
• Provides unified state and controller access interface for child components

Basic Usage

<template>
    <div class="app">
        <ChatComponent />
        <VoiceControls />
        <ConversationHistory />
    </div>
</template>

<script setup lang="ts">
import {provideAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';
import type {IOptions} from '@bdky/aaas-pilot-kit';

const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: If custom agentService is not provided, this config is required
    agentConfig: {
        token: 'your-token',
        robotId: 'your-robot-id'
    }
};

// Provide AaaSPilotKit instance to all child components
const provider = provideAaaSPilotKit(options);
</script>

Language Configuration

Through lang parameter you can configure ASR recognition and TTS synthesis language:

<script setup lang="ts">
import {provideAaaSPilotKit, Language} from '@bdky/aaas-pilot-kit-vue3';
import type {IOptions} from '@bdky/aaas-pilot-kit';

const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    lang: Language.ENGLISH,  // Use Language constant
    // or lang: 'en'           // Or use string directly
    agentConfig: {
        token: 'your-token',
        robotId: 'your-robot-id'
    }
};

const provider = provideAaaSPilotKit(options);
</script>

Supported languages include: Chinese(zh), English(en), Japanese(ja), Spanish(es), Russian(ru), Korean(ko), Vietnamese(vi), German(de), Indonesian(id), Thai(th).

For detailed language configuration instructions, please refer to Configuration Options Documentation.

Dynamic Configuration Updates

Provider supports reactive configuration updates:

<script setup lang="ts">
    import {ref, computed} from 'vue';
    import {provideAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    const userId = ref('user123');
    const selectedRobot = ref('robot456');

    // Reactive configuration
    const options = computed(() => ({
        token: 'your-auth-token-here',
        figureId: '209337',
        ttsPer: 'LITE_audiobook_female_1',
        // agentConfig: If custom agentService is not provided, this config is required
        agentConfig: {
            token: `token-${userId.value}`,
            robotId: selectedRobot.value
        }
    }));

    // Re-create controller when configuration changes
    provideAaaSPilotKit(options.value);
</script>

useAaaSPilotKitProvider

Advanced Usage - Underlying provider implementation, returns reactive controller and state.

Usage Scenarios

• Regular scenarios: No need to call directly, just use provideAaaSPilotKit
• Multi-instance scenarios: Used when managing multiple independent instances in the same application (see Multi-instance Support)
• Custom injection: Used when you need to use custom injection key

function useAaaSPilotKitProvider<AS extends BaseAgentService = BaseAgentService>(
    options: IOptions<AS>
): IAaaSPilotKitProvider<AS>

Return Value Interface

interface IAaaSPilotKitProvider<AS extends BaseAgentService = BaseAgentService> {
    controller: ShallowRef<ReturnType<typeof createAaaSPilotKit<AS>> | null>;
    isReady: Ref<boolean>;
    isMuted: Ref<boolean>;
    isRendering: Ref<boolean>;
    create: () => void;
    dispose: () => void;
}

injectAaaSPilotKit

Underlying dependency injection function, used to access Provider instance in child components.

function injectAaaSPilotKit<AS extends BaseAgentService = BaseAgentService>():
    IAaaSPilotKitProvider<AS> | undefined

Usage Example

<script setup lang="ts">
    import {injectAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    const provider = injectAaaSPilotKit();

    if (!provider) {
        throw new Error('AaaSPilotKit provider not injected, please ensure it is used within provideAaaSPilotKit scope');
    }

    // Directly access provider properties
    console.log('Controller instance:', provider.controller.value);
    console.log('Ready status:', provider.isReady.value);
</script>

Lifecycle Management

Automatic Lifecycle

Provider automatically manages controller lifecycle:

<script setup lang="ts">
import {onMounted, onUnmounted} from 'vue';
import {provideAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

const provider = provideAaaSPilotKit(options);

// Provider automatically handles:
// - onMounted: Call provider.controller.mount(element)
// - onUnmounted: Call provider.controller.dispose()
// - Configuration change: Re-create controller
</script>

Manual Lifecycle Control

In certain scenarios, you may need to manually control lifecycle:

<script setup lang="ts">
    import {nextTick} from 'vue';
    import {useAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    const {controller, create, dispose} = useAaaSPilotKit();

    // Manual creation (e.g., delayed initialization)
    const initializeAvatar = async () => {
        if (!controller.value) {
            create();
        }
    };

    // Manual destruction (e.g., user logout)
    const cleanup = () => {
        dispose();
    };

    // Reset session
    const restartSession = async () => {
        dispose();
        // Wait for one tick to ensure destruction completes
        await nextTick();
        create();
    };
</script>

State Management

Reactive State

All states maintained by Provider are reactive:

<template>
    <div class="status-indicator">
        <div :class="['status', {ready: isReady}]">
            {{isReady ? 'Ready' : 'Initializing'}}
        </div>
        <div v-if="isMuted" class="muted">🔇 Muted</div>
        <div v-if="isRendering" class="rendering">⏳ Processing</div>
    </div>
</template>

<script setup lang="ts">
    import {useAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    const {isReady, isMuted, isRendering} = useAaaSPilotKit();
</script>

<style scoped>
    .status.ready {
        color: #4caf50;
    }

    .muted, .rendering {
        color: #ff9800;
    }
</style>

Cross-Component State Sharing

All child components can access the same state instance:

<!-- ParentComponent.vue -->
<template>
    <div class="chat-app">
        <StatusBar />
        <MessageInput />
        <ConversationList />
    </div>
</template>

<script setup lang="ts">
    import {provideAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    provideAaaSPilotKit(options);
</script>

<!-- StatusBar.vue -->
<script setup lang="ts">
    import {useAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    // Access shared state
    const {isReady, isRendering} = useAaaSPilotKit();
</script>

<!-- MessageInput.vue -->
<script setup lang="ts">
    import {useAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    // Access shared controller
    const {controller} = useAaaSPilotKit();

    const sendMessage = (text: string) => {
        controller.value?.input(text);
    };
</script>

Error Handling

Provider Injection Check

<script setup lang="ts">
    import {useAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';

    try {
        const {controller} = useAaaSPilotKit();
    }
    catch (error) {
        console.error('AaaSPilotKit Provider not found, please check:');
        console.error('1. Whether provideAaaSPilotKit was called in parent component');
        console.error('2. Whether current component is within Provider scope');
        throw error;
    }
</script>

Controller Availability Check

<script setup lang="ts">
    import {computed} from 'vue';
    import { useAaaSPilotKit } from '@bdky/aaas-pilot-kit-vue3';

    const {controller, isReady} = useAaaSPilotKit();

    const isControllerAvailable = computed(() => {
        return controller.value !== null && isReady.value;
    });

    const safelyCallController = (callback: (ctrl: any) => void) => {
        if (isControllerAvailable.value) {
            callback(controller.value);
        }
        else {
            console.warn('Controller not ready or unavailable');
        }
    };
</script>

Advanced Usage

Multi-instance Support

In complex applications, you may need to manage multiple AaaS Pilot Kit instances:

<template>
    <div class="multi-avatar-app">
        <div class="avatar-section">
            <h3>Customer Service Assistant</h3>
            <AvatarContainer :provide-key="customerServiceKey" />
        </div>
        <div class="avatar-section">
            <h3>Sales Assistant</h3>
            <AvatarContainer :provide-key="salesAssistantKey" />
        </div>
    </div>
</template>

<script setup lang="ts">
    import {provide} from 'vue';
    import {useAaaSPilotKitProvider} from '@bdky/aaas-pilot-kit-vue3';

    // Create different instances for different uses
    const customerServiceKey = Symbol('customer-service');
    const salesAssistantKey = Symbol('sales-assistant');

    const customerServiceProvider = useAaaSPilotKitProvider({
        token: 'your-auth-token-here',
        figureId: '209337',
        // agentConfig: If custom agentService is not provided, this config is required
        agentConfig: {
            robotId: 'customer-service-bot'
        }
    });

    const salesAssistantProvider = useAaaSPilotKitProvider({
        token: 'your-auth-token-here',
        figureId: '209338',
        // agentConfig: If custom agentService is not provided, this config is required
        agentConfig: {
            robotId: 'sales-assistant-bot'
        }
    });

    provide(customerServiceKey, customerServiceProvider);
    provide(salesAssistantKey, salesAssistantProvider);
</script>

Integration with Global State Management

<script setup lang="ts">
    import {watch} from 'vue';
    import {useStore} from 'vuex'; // Or other state management library
    import {provideAaaSPilotKit, useAaaSPilotKitEvents} from '@bdky/aaas-pilot-kit-vue3';

    const store = useStore();

    // Get configuration from global state
    const options = computed(() => ({
        token: store.state.auth.token,
        figureId: store.state.avatar.figureId,
        // agentConfig: If custom agentService is not provided, this config is required
        agentConfig: {
            token: store.state.user.token,
            robotId: store.state.avatar.selectedRobot
        }
    }));

    const provider = provideAaaSPilotKit(options.value);

    // Sync state to global store
    useAaaSPilotKitEvents({
        onReady: () => store.dispatch('avatar/setReady', true),
        onConversationAdd: (conversation) =>
            store.dispatch('chat/addConversation', conversation)
    });
</script>

Type Safety

Provider system provides complete TypeScript support:

import type {
    IAaaSPilotKitProvider,
    AaaSPilotKitProviderKey
} from '@bdky/aaas-pilot-kit-vue3';

// Custom Agent Service type
class CustomAgentService extends BaseAgentService {
    customMethod() {
        return 'custom';
    }
}

// Typed Provider
const provider = provideAaaSPilotKit<CustomAgentService>(options);

// Type-safe controller access
const { controller } = useAaaSPilotKit<CustomAgentService>();
if (controller.value) {
    // Type-safe
    controller.value.agentService.customMethod();
}