AI Capability and Start Eligibility

TopStepAIKit has two query layers. supportsAIFeatures: is a legacy discovery API. Before actually starting an AI operation, call startEligibilityForRequest: to evaluate the complete request against current state without side effects.

Recommended flow

Show entry: supportsAIFeatures: (optional, coarse)
    ↓
Build TSAIStartRequest (use case + parameters + optional device coordination)
    ↓
startEligibilityForRequest: (required, exact)
    ↓ Supported
Call the capability API

TSAIStartEligibility.support is either TSAICapabilitySupported or TSAICapabilityUnsupported. An unsupported result always carries an error; a supported result never does.

Build a start request

TSAIUseCaseParameters *parameters =
    [TSAIUseCaseParameters voiceTranslationParametersWithMode:
        TSAIVoiceTranslationModeStandard];

TSAIAudioRouteConfiguration *route =
    [TSAIAudioRouteConfiguration defaultConfiguration];
TSAIDeviceCoordination *coordination =
    [TSAIDeviceCoordination coordinationWithScene:TSAIDeviceAISceneTranslation
                                         initiator:TSAISessionInitiatorApp
                           audioRouteConfiguration:route];

TSAIStartRequest *request =
    [TSAIStartRequest requestWithIdentifier:NSUUID.UUID.UUIDString
                                    useCase:TSAIUseCaseVoiceTranslation
                                 parameters:parameters
                         deviceCoordination:coordination];

TSAIStartEligibility *eligibility =
    [context startEligibilityForRequest:request];
if (eligibility.support == TSAICapabilityUnsupported) {
    TSLog(@"Cannot start: %@", eligibility.error.localizedDescription);
    return;
}

Pass nil for deviceCoordination in app-only operations. A device-coordinated operation must specify the exact scene, initiator, and complete audio route; a feature bit is not sufficient.

Request models

Type	Read-only properties	Constructor
TSAIStartRequest	requestIdentifier, useCase, parameters, deviceCoordination	requestWithIdentifier:useCase:parameters:deviceCoordination:
TSAIUseCaseParameters	kind, recordingScene, voiceTranslationMode	audioRecordingParametersWithScene:, voiceTranslationParametersWithMode:
TSAIDeviceCoordination	scene, initiator, audioRouteConfiguration	coordinationWithScene:initiator:audioRouteConfiguration:
TSAIStartEligibility	support, error	supportedEligibility, unsupportedEligibilityWithError:

requestIdentifier must be unique within the current connection generation. These models are immutable and copyable.

Use cases

TSAIUseCase	Purpose
TSAIUseCaseInvalid	Invalid use case
TSAIUseCaseTextSummary / TSAIUseCaseChat	Text summary / AI chat
TSAIUseCaseTextTranslation	Text translation
TSAIUseCaseSpeechSynthesis	Speech synthesis
TSAIUseCasePCMRecognition / TSAIUseCaseFileRecognition / TSAIUseCaseOfflineRecognition	PCM / file / offline recognition
TSAIUseCasePhoneInterpretation	Phone interpretation
TSAIUseCaseAIRecording / TSAIUseCaseCallRecording / TSAIUseCaseNormalRecording	AI / call / normal recording
TSAIUseCaseTextQuestionAnswer	Text question answering
TSAIUseCaseImageGeneration	Image generation
TSAIUseCaseVoiceTranslation / TSAIUseCaseVoiceQuestionAnswer	Device-coordinated voice translation / question answering
TSAIUseCaseWatchFace / TSAIUseCaseRideHailing	Voice watch-face creation / ride hailing

Device-coordination enums

Enum	Values
TSAIDeviceAIScene	TSAIDeviceAISceneInvalid, TSAIDeviceAISceneChat, TSAIDeviceAISceneRecording, TSAIDeviceAISceneCallRecording, TSAIDeviceAISceneTranslation, TSAIDeviceAISceneRideHailing, TSAIDeviceAISceneWatchFace, TSAIDeviceAISceneQuestionAnswer, TSAIDeviceAISceneTranslationSelf, TSAIDeviceAISceneTranslationPeer
TSAISessionInitiator	TSAISessionInitiatorInvalid, TSAISessionInitiatorApp, TSAISessionInitiatorDevice
TSAIUseCaseParameterKind	TSAIUseCaseParameterKindNone, TSAIUseCaseParameterKindAudioRecording, TSAIUseCaseParameterKindVoiceTranslation
TSAIVoiceTranslationMode	TSAIVoiceTranslationModeInvalid, TSAIVoiceTranslationModeStandard, TSAIVoiceTranslationModeConversationSelf, TSAIVoiceTranslationModeConversationPeer
TSAIConversationTranslationMode	TSAIConversationTranslationModeInvalid, TSAIConversationTranslationModeFaceToFace, TSAIConversationTranslationModePrivate, TSAIConversationTranslationModePortable

Atomic service capabilities

TSAIServiceCapabilityOptions defines TSAIServiceCapabilityNone, TSAIServiceCapabilityTextSummarization, TSAIServiceCapabilityConversation, TSAIServiceCapabilityTextTranslation, TSAIServiceCapabilitySpeechSynthesis, TSAIServiceCapabilityPCMRecognition, TSAIServiceCapabilityFileRecognition, TSAIServiceCapabilityOfflineRecognition, TSAIServiceCapabilityInterpretation, TSAIServiceCapabilityAudioRecordingProcessing, TSAIServiceCapabilityQuestionAnswering, and TSAIServiceCapabilityImageGeneration.

A provider exposes supportedAIServiceCapabilities and supportForAIServiceCapabilities:. A device bridge exposes supportForDeviceAIScene:initiator:audioInputChannel:. Each reports only its own facts; the Context combines them with live state.

Legacy feature discovery

- (BOOL)supportsAIFeatures:(TSAIFeatureOptions)features;

The legacy bit values are frozen: TSAIFeatureNone, TSAIFeatureAISummary, TSAIFeatureAIChat, TSAIFeatureTextTranslation, TSAIFeatureSpeechSynthesis, TSAIFeaturePCMRecognition, TSAIFeatureFileRecognition, TSAIFeatureDeviceMicRecognition, TSAIFeatureOfflineRecognition, TSAIFeatureInterpretation, TSAIFeatureAIAudioRecording, TSAIFeatureCallAudioRecording, TSAIFeatureNormalAudioRecording, TSAIFeatureQuestionAnswering, TSAIFeatureImageGeneration, TSAIFeatureDeviceVoiceTranslation, and TSAIFeatureDeviceQuestionAnswering. TSAIFeatureAll is fixed at 0xFFFF.

This API omits Context state, authorization, permissions, network state, task contention, and exact routing. A YES result must never authorize a start.

Important notes

1. Evaluate eligibility immediately before the real start call and re-evaluate after external state changes.
2. Use the unsupported result's error as the exact reason; do not infer it from feature bits.
3. Unknown and Automatic inputs are not device capability facts; device evaluation requires a resolved channel.
4. Use TSAIFeatureAll only for compatibility diagnostics, not UI enablement.