본문으로 건너뛰기

RecognitionBridge

디지털 잉크 인식 provider 어댑터 + 후보 정규화

상태​

항목값
Layercore
TierL1
Statuswip
Version0.9.0
가격Free (free)
**카�
�고리**Input & UX

개요​

개요​

RecognitionBridge 는 multi-saas-kit 의 Layer 1 Core Plugin � 니다. DigitalInk stroke 데이터를 외부 인식 provider 로 전송하고 후보 � �스트를 표준 결과로 정규화하는 어댑터 계층� 니다.

provider 의 서비스 운영, 가격 정� , 사용량 과금은 이 plugin 의 � 임이 아닙니다. 예를 들어 apis.how Hand Writer 는 RecognitionBridge 가 호출할 수 있는 provider 중 하나이며, apis.how 의 상품/과금 정� 은 apis.how 프로젝트가 담당합니다.

DigitalInk(stroke 표준) + BrushConfiguration(렌더 설정) 와 함께 HandwritingInput Composite 의 3대 base 중 하나.

핵심 컴포넌트​

RecognizerInterface​

모든 인식 어댑터의 공통 계약:

interface RecognizerInterface {
    public function recognize(
        array $ink, int $width, int $height,
        ?string $language = null, ?string $mode = null, ?int $returnCount = null,
    ): RecognitionResult;
}

RecognitionResult (DTO)​

표준 결과 shape — ok, provider, elapsed_ms, candidates, message. success() / failure() named constructors.

CandidateNormalizer (Pure)​

인식 응답에서 candidates 추출. 3가지 shape 자동 인식:

응답 shape출처
['candidates' => [...]]Hand Writer API
['data' => ['candidates' => [...]]]wrapping 변형
[_, [[_, [...]]]]Google Input Tools native

추가 처리: trim, mode='numeric' 시 numeric_regex (/^[0-9]{1,6}$/) 매칭, 빈 문자열 / 중복 제거, return_count clamp (1~10).

HandWriterRecognizer (어댑터)​

apis.how /api/v1/handwriting/recognize Bearer 토큰 호출 어댑터. API 키 누락 / 5xx / 네트워크 예외 모두 RecognitionResult::failure() 로 안전 fallback. X-Client-Origin / X-Client-Domain 헤더 첨부.

GoogleInputToolsRecognizer (어댑터)​

Google Input Tools request endpoint 무인증 fallback 어댑터.

RecognizerChain​

여러 recognizer 를 순차 시도. 첫 번째 ok=true 결과 즉시 반환. 모두 실패 시 마지막 결과 반환. 빈 chain → failure(null, 0, 'No recognizers configured.').

사용 예시​

use App\Plugins\DigitalInk\Data\StrokeData;
use App\Plugins\RecognitionBridge\Services\CandidateNormalizer;
use App\Plugins\RecognitionBridge\Services\RecognizerChain;
use App\Plugins\RecognitionBridge\Recognizers\HandWriterRecognizer;
use App\Plugins\RecognitionBridge\Recognizers\GoogleInputToolsRecognizer;

$normalizer = CandidateNormalizer::fromConfig(config('recognition-bridge.candidates'));

$primary  = new HandWriterRecognizer(config('recognition-bridge.hand_writer'), $normalizer, [
    'X-Client-Origin' => config('app.url'),
]);
$fallback = new GoogleInputToolsRecognizer(config('recognition-bridge.google_input_tools'), $normalizer);

$chain = new RecognizerChain([$primary, $fallback]);

$stroke = StrokeData::fromArray($payload);
$result = $chain->recognize(
    ink: $stroke->toArray(),
    width: $stroke->canvasWidth,
    height: $stroke->canvasHeight,
    language: 'en',
    mode: 'numeric',
    returnCount: 5,
);

if ($result->ok) {
    return response()->json($result->toArray());
}

설정 (config/recognition-bridge.php)​

return [
    'enabled' => env('PLG_RECOGNITION_BRIDGE_ENABLED', true),
    'hand_writer' => [
        'base_url'        => env('HAND_WRITER_API_URL', 'https://apis.how'),
        'recognize_path'  => env('HAND_WRITER_RECOGNIZE_PATH', '/api/v1/handwriting/recognize'),
        'api_key'         => env('HAND_WRITER_API_KEY'),
        'timeout_seconds' => 12,
        'language'        => 'en',
        'mode'            => 'numeric',
        'return_count'    => 5,
    ],
    'google_input_tools' => [
        'enabled'         => true,
        'endpoint'        => 'https://www.google.com.tw/inputtools/request?ime=handwriting&app=mobilesearch&cs=1&oe=UTF-8',
        'timeout_seconds' => 12,
    ],
    'candidates' => [
        'min_count'     => 1,
        'max_count'     => 10,
        'numeric_regex' => '/^[0-9]{1,6}$/',
    ],
];

범위​

이 plugin 은 provider 호출 어댑터와 후보 정규화만 제공합니다. API gateway, 가격표, quota, metering, spend log 는 ApiUsageAnalytics 또는 각 provider SaaS 프로젝트의 � 임� 니다.

다음 단계 (Phase 3+)​

  • Filament Settings Page (provider/credential 관리)
  • Custom Recognizer 등록 (DI 컨� �이너 binding)
  • 실패 통계 + Audit log 통합

라이선스​

MIT

의존성​

데모​

🛒 Plugin Store에서 보기: store.codebase.how/plugins/recognition-bridge