TopStepAIKit

TopStepAIKit is an AI business SDK independent of TopStepComKit. Its provider-neutral contracts and Context runtime hide concrete AI providers, while platform DeviceBridges connect wearable microphones and device-side AI features.

Architecture

App
 └─ TSAIKit
     └─ activeContext (one at a time)
         ├─ assistant        text summary and voice chat
         ├─ questionAnswer   single-turn question answering
         ├─ translate        text translation
         ├─ speech           TTS and PCM/file/device-mic ASR
         ├─ interpreter      simultaneous interpretation
         ├─ audioRecord      normal and AI recording
         ├─ imageGeneration  image generation
         └─ audioRouting     audio-route discovery and observation

Application code obtains capabilities from TSAIKit.sharedInstance.activeContext. Do not instantiate providers, adapters, or DeviceBridges directly.

Requirements

• iOS 13.0 or later
• CocoaPods
• One AI provider product package; AIBuds is the current production provider
• At least one platform AI Bridge: Fit, NewPlatform, or Persimwear
• The corresponding device SDK must already be initialized and connected

Installation

target 'YourApp' do
  pod 'TopStepAIKit/Providers/AIBuds'

  # Select the platforms used by the app. Multiple platforms may coexist.
  pod 'TopStepFitKit/AI'
  # pod 'TopStepNewPlatformKit/AI'
  # pod 'TopStepPersimwearKit/AI'

  # Optional; includes FFmpeg.
  # pod 'TopStepAIKit/Providers/AIBudsLiveStream'
end

TopStepAIKit/AIBuds and TopStepAIKit/AIBudsLiveStream remain legacy aliases. New integrations should use Providers/*.

Static-framework projects

When using use_frameworks! :linkage => :static, keep AFNetworking and SocketRocket as dynamic frameworks because the AIBuds runtime loads them dynamically. Do not install AIBudsLiveStream together with another video SDK that already ships libav*.xcframework.

Activate a Context

Initialize and connect the device platform first so its AI Bridge is registered, then activate the AI Context:

#import <TopStepAIKit/TopStepAIKit.h>

TSAIBudsConfiguration *providerConfig =
    [TSAIBudsConfiguration configurationWithPreferredVendor:TSAIBudsVendorTypeStarBurst];

TSAIContextConfiguration *contextConfig =
    [TSAIContextConfiguration configurationWithPlatformIdentifier:TSAIPlatformIdentifierFit
                                                      providerType:TSAIProviderTypeAIBuds
                                             providerConfiguration:providerConfig];

[[TSAIKit sharedInstance] activateContextWithConfiguration:contextConfig
                                                completion:^(BOOL success, NSError *error) {
    if (!success) {
        TSLog(@"AI Context activation failed: %@", error.localizedDescription);
        return;
    }

    TSAIContext *context = [TSAIKit sharedInstance].activeContext;
    TSLog(@"AI Context active: %@", context.contextIdentifier);
}];

TSAIContextConfiguration

Property	Type	Description
platformIdentifier	NSString *	DeviceBridge platform identifier
providerType	TSAIProviderType	Selected AI provider product
providerConfiguration	id	Provider-specific configuration; AIBuds uses TSAIBudsConfiguration

TSAIContext also exposes read-only contextIdentifier, platformIdentifier, state, authorizationState, seven business capability objects, and the read-only audioRouting discovery interface. It also implements exact start eligibility and device-session coordination. TSAIBudsConfiguration contains preferredVendor, appId, appKey, and vendorOptions; the host app should inject sensitive values at runtime.

Providers and AIBuds vendors

Enum	Values and raw values
TSAIProviderType	Unknown = 0, AIBuds = 1, AliAI = 2
TSAIBudsVendorType	None = 0, StarBurst = 1 << 0, MltCloud = 1 << 1, All = StarBurst | MltCloud

Select exactly one concrete preferredVendor for a Context. All is reserved for SDK Runtime registration.

Platform identifiers

Constant	Platform
TSAIPlatformIdentifierFit	TopStepFitKit
TSAIPlatformIdentifierNewPlatform	TopStepNewPlatformKit
TSAIPlatformIdentifierPersimwear	TopStepPersimwearKit

Context states

Value	Description
TSAIContextStateInactive	Inactive
TSAIContextStateActivating	Activation in progress
TSAIContextStateActive	Active and ready for capability calls
TSAIContextStateDeactivating	Deactivation in progress
TSAIContextStateFailed	Activation failed

Use registerStateDidChange: and registerAuthorizationStateDidChange: to observe Context and provider-authorization states.

TSAIAuthorizationState	Raw value	Meaning
TSAIAuthorizationStateUnknown	0	No known authorization state
TSAIAuthorizationStateDisconnected	1	Provider is disconnected
TSAIAuthorizationStateAuthenticating	2	Authentication in progress
TSAIAuthorizationStateAuthenticated	3	Authentication succeeded
TSAIAuthorizationStateFailed	4	Authentication failed

Deactivate or switch

[[TSAIKit sharedInstance] deactivateActiveContextWithCompletion:^(BOOL success, NSError *error) {
    if (!success) {
        TSLog(@"AI Context deactivation failed: %@", error.localizedDescription);
    }
}];

Before switching platforms, switch the device SDK first, then activate a new Context. The old Context and previously retained capability objects become invalid and return TSAIErrorCodeContextInactive.

Next steps

• Capability and Start Eligibility
• Audio Routing
• AI Assistant
• AI Speech
• Common Types and Errors

Important notes

1. Only one activeContext is supported in the process.
2. Obtain capability objects after successful activation and do not retain them across platform switches.
3. Never log App keys, tokens, or other provider secrets.
4. Do not call AIBuds global initialization, vendor switching, or authentication APIs directly; TopStepAIKit serializes those operations.