Skip to content

Latest commit

 

History

History
214 lines (181 loc) · 7.66 KB

analyses-contract.md

File metadata and controls

214 lines (181 loc) · 7.66 KB

Analyses Runtime 계약 (AI 소유)

Server PR #138의 AiRuntimeHttpRequest와 맞춘 계약이다. 계약 버전은 1.1.0이며, MVP에서는 발화 하나당 대표 Intent와 canonical Workflow 한 쌍만 처리한다.

Endpoint와 흐름

POST /internal/v1/analyses

PLAN    → Intent 모델 1회 → CONTEXT_REQUIRED | OUT_OF_SCOPE
        → CONTEXT_REQUIRED: Server가 대표 Intent/Workflow 저장 + DB 조회
        → OUT_OF_SCOPE: Workflow/DB/ANALYZE 없이 종료
ANALYZE → PLAN 결정 재사용(모델 0회) → NEEDS_INFO | REVIEW_REQUIRED

PLAN 요청

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "phase": "PLAN",
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘"
  }
}

PLAN에는 plannedIntent, plannedWorkflowId, Worker context를 보내지 않는다.

CONTEXT_REQUIRED 응답

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "outcome": "CONTEXT_REQUIRED",
  "contextRequirement": {
    "detectedIntent": "EXPIRY_RENEWAL",
    "workflowId": "WF-STY-001",
    "evidence": "체류연장 준비해줘",
    "confidence": null,
    "confidenceSource": "UNAVAILABLE",
    "bertRoutingScore": 0.3088,
    "targetDisplayName": "응웬반안",
    "extractedSlots": {},
    "requiredFieldKeys": [
      "worker_id",
      "due_at",
      "stay_expiry_date",
      "passport_status",
      "arc_status"
    ]
  },
  "questions": [],
  "candidates": [],
  "validationErrors": [],
  "versions": {
    "agentVersion": "0.1.0",
    "modelProvider": "huggingface",
    "modelName": "skt/A.X-4.0-Light",
    "modelVersion": "AX",
    "promptVersion": "knowledge-25e778ad",
    "contextPackVersion": "0.3.1",
    "workflowCatalogVersion": "0.3.1",
    "contractVersion": "1.1.0"
  },
  "providerAttemptCount": 1,
  "latencyMs": 120
}

규칙:

  • workflowId는 WF-STY-001 같은 Knowledge canonical ID다.
  • A.X는 확률을 제공하지 않으므로 confidence=null, confidenceSource=UNAVAILABLE이다.
  • BERT가 최종 분류기이면 confidenceSource=BERT이고 confidence를 반환한다.
  • 고정 규칙 fallback은 confidenceSource=MODEL을 사용한다.
  • bertRoutingScore는 A.X 선택 전 참고값이며 A.X confidence가 아니다.
  • evidence는 A.X의 원문 substring이다. BERT와 OUT_OF_SCOPE에서는 null일 수 있다.
  • evidence는 Slot이 아니므로 extractedSlots에 evidence:* key를 만들지 않는다.
  • A.X가 여러 Intent를 반환해도 MVP 응답은 원문 등장 순서의 첫 Intent만 사용한다.
  • 같은 Intent에 여러 Knowledge Workflow가 있으면 발화/evidence의 업무 신호로 선택한다.
  • EXPIRY_RENEWAL의 체류 신호는 WF-STY-001, 계약·재계약·취업활동기간 연장·고용허가기간 연장 신호는 WF-CON-001이다.
  • requiredFieldKeys는 Server에 조회를 요청할 Context key다. 이 중 Workflow의 필수 Slot만 누락 질문을 만들며 선택 Slot 누락은 실행을 막지 않는다.
  • WF-STY-001에서 worker_id, due_at은 필수이고 stay_expiry_date, passport_status, arc_status는 선택 Context다.

OUT_OF_SCOPE 응답

실행할 Workflow가 없는 발화는 DB context를 요청하지 않고 PLAN에서 즉시 종료한다.

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "outcome": "OUT_OF_SCOPE",
  "contextRequirement": null,
  "questions": [],
  "candidates": [],
  "validationErrors": [],
  "providerAttemptCount": 1
}

Server는 OUT_OF_SCOPE에서 Workflow 검증·DB 조회·ANALYZE 호출을 수행하지 않는다.

ANALYZE 요청

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "phase": "ANALYZE",
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘",
    "plannedIntent": "EXPIRY_RENEWAL",
    "plannedWorkflowId": "WF-STY-001",
    "requestedFieldKeys": [
      "worker_id",
      "due_at",
      "stay_expiry_date",
      "passport_status",
      "arc_status"
    ],
    "workers": [
      {
        "workerRef": "30000000-0000-0000-0000-000000000001",
        "requestedFields": {
          "worker_id": "30000000-0000-0000-0000-000000000001",
          "due_at": "2026-10-01T09:00:00+09:00",
          "stay_expiry_date": "2026-12-31",
          "passport_status": "VERIFIED",
          "arc_status": "SUBMITTED"
        }
      }
    ]
  }
}

규칙:

  • plannedIntent, plannedWorkflowId는 모두 필수다. 하나라도 없으면 422로 거부한다.
  • AI는 이 값을 신뢰하여 Intent 모델을 다시 호출하지 않고 Slot/Context만 검사한다.
  • providerAttemptCount=0은 ANALYZE에서 모델 호출이 없었음을 뜻한다.
  • requestedFieldKeys는 PLAN에서 요청한 전체 key다.
  • workers[].requestedFields에는 Server DB에서 실제로 찾은 값만 담는다.
  • 필수 due_at이 없으면 NEEDS_INFO로 HR 입력을 요청한다.
  • 선택 Context나 문서 상태가 없다는 이유만으로 NEEDS_INFO를 만들지 않는다.
  • MVP는 Worker 한 명과 대표 Intent/Workflow 한 쌍만 처리한다.

ANALYZE 응답

NEEDS_INFO

  • contextRequirement: null
  • candidates: []
  • questions: 한 개 이상

REVIEW_REQUIRED

{
  "candidateRef": "candidate-1",
  "workerRef": "30000000-0000-0000-0000-000000000001",
  "workflowId": "WF-STY-001",
  "extractedSlots": {
    "worker_id": "30000000-0000-0000-0000-000000000001",
    "due_at": "2026-10-01T09:00:00+09:00",
    "stay_expiry_date": "2026-12-31"
  },
  "missingSlots": [],
  "confidence": null
}

Candidate의 workflowId는 plannedWorkflowId와 반드시 같아야 한다. ANALYZE는 모델을 재호출하지 않고 Server가 confidence를 다시 보내지 않으므로 AI는 새 점수를 만들지 않는다.

Server #138 확정 정책

  • PLAN의 confidence는 Intent 분류 결과다.
  • Server는 PLAN의 BERT confidence, confidenceSource, bertRoutingScore를 실행 이력에 보존한다.
  • ANALYZE 요청에는 plannedIntent, plannedWorkflowId만 전달한다.
  • AI는 Intent 모델을 재호출하지 않고 Candidate confidence를 null로 반환한다.
  • Server는 Candidate confidence와 PLAN confidence를 비교하지 않으며 nullable을 허용한다.
  • Candidate의 workflowId는 plannedWorkflowId와 반드시 같아야 한다.
  • PLAN 결정을 재사용한 ANALYZE의 providerAttemptCount는 0이다.

Intent 운영 설정

설정 동작
FOWOCO_INTENT_MODEL_ENABLED=false EXPIRY_RENEWAL 고정 규칙
FOWOCO_INTENT_MODEL_ENABLED=true HF BERT와 선택적 A.X 하이브리드
FOWOCO_INTENT_WARMUP_ON_START=true startup에서 BERT/A.X 로딩·첫 추론
FOWOCO_INTENT_WARMUP_REQUIRED=true warmup 실패 시 애플리케이션 startup 실패

A.X 사용 이미지는 intent-ax extra를 설치한다. 운영 장치에 맞춰 FOWOCO_INTENT_DEVICE를 설정하고 private HF Token은 Kubernetes Secret으로 주입한다. BERT/Base/Adapter의 *_REVISION은 immutable Hugging Face commit SHA로 고정한다.

GET /internal/v1/intent/status에서 모델 설정, lazy-load 상태, BERT/A.X 가용성과 promptVersion을 확인한다. Kubernetes readiness는 GET /internal/v1/intent/readiness의 200 응답을 사용한다. 운영에서는 warmup 후 ready=true, axAvailable=true, promptVersion=knowledge-25e778ad를 확인한다.

Fixtures

파일 용도
examples/analyses/request_plan.json PLAN 요청
examples/analyses/response_context_required.json CONTEXT_REQUIRED
examples/analyses/request_analyze.json ANALYZE 요청
examples/analyses/response_needs_info.json NEEDS_INFO
examples/analyses/response_review_required.json REVIEW_REQUIRED
examples/analyses/response_out_of_scope.json OUT_OF_SCOPE