KIOSTextAligner.h

//
//  KIOSTextAligner.h
//  KeenASR
//
//  Copyright © 2026 Keen Research LLC. All rights reserved.
//
 
#import <Foundation/Foundation.h>
 
@class KIOSRecognizer;
 
NS_ASSUME_NONNULL_BEGIN

typedef NS_ENUM(NSInteger, KIOSAlignOp) {
    KIOSAlignOpMatch        = 0,
    KIOSAlignOpSubstitution = 1,
    KIOSAlignOpInsertion    = 2,
    KIOSAlignOpDeletion     = 3,
};
 
#pragma mark - KIOSAlignmentConfig

@interface KIOSAlignmentConfig : NSObject

@property (nonatomic, assign) float insertCost;

@property (nonatomic, assign) float deleteCost;

@property (nonatomic, assign) float substituteCost;

@property (nonatomic, assign) BOOL detectRepetitions;

@property (nonatomic, assign) BOOL filterNoiseTokens;
 
@end
 
#pragma mark - KIOSAlignmentItem

@interface KIOSAlignmentItem : NSObject

@property (nonatomic, readonly) KIOSAlignOp op;

@property (nonatomic, readonly) NSInteger refIndex;

@property (nonatomic, readonly) NSInteger recIndex;

@property (nonatomic, readonly, copy) NSString *refToken;

@property (nonatomic, readonly, copy) NSString *recToken;
 
@end
 
#pragma mark - KIOSAlignmentResult

@interface KIOSAlignmentResult : NSObject

@property (nonatomic, readonly) NSArray<KIOSAlignmentItem *> *trace;
 
#pragma mark Edit-distance counts

@property (nonatomic, readonly) NSInteger matches;

@property (nonatomic, readonly) NSInteger substitutions;

@property (nonatomic, readonly) NSInteger insertions;

@property (nonatomic, readonly) NSInteger deletions;

@property (nonatomic, readonly) NSInteger refLength;

@property (nonatomic, readonly) NSInteger recLength;

@property (nonatomic, readonly) float wordErrorRate;
 
#pragma mark Oral-reading views

@property (nonatomic, readonly) NSArray<NSNumber *> *matchedRefIndices;

@property (nonatomic, readonly) NSArray<NSNumber *> *skippedRefIndices;

@property (nonatomic, readonly) NSInteger furthestMatchedIndex;

@property (nonatomic, readonly) NSArray<NSNumber *> *repetitionRefIndices;
 
@end
 
#pragma mark - KIOSTextAligner

@interface KIOSTextAligner : NSObject

- (nullable instancetype)initWithReference:(NSString *)reference
                                  langCode:(NSString *)langCode
    NS_DESIGNATED_INITIALIZER;

- (nullable instancetype)initWithReference:(NSString *)reference
                                recognizer:(KIOSRecognizer *)recognizer;
 
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
 
#pragma mark Alignment

- (KIOSAlignmentResult *)align:(NSString *)recognized;

- (KIOSAlignmentResult *)align:(NSString *)recognized
                        config:(nullable KIOSAlignmentConfig *)config;
 
#pragma mark Incremental alignment

- (KIOSAlignmentResult *)incrementalAlign:(NSString *)recognized;

- (KIOSAlignmentResult *)incrementalAlign:(NSString *)recognized
                                   config:(nullable KIOSAlignmentConfig *)config;

- (void)reset;
 
#pragma mark Accessors

@property (nonatomic, readonly) NSArray<NSString *> *referenceTokens;

@property (nonatomic, readonly, copy) NSString *langCode;
 
@end
 
NS_ASSUME_NONNULL_END