prompter

prompter는 XML 프롬프트 계약을 기준으로 LLM 요청을 실행하는 모듈입니다. OpenAI, Claude, Gemini, Ollama, LM Studio 같은 제공자를 LLMSource로 등록하고, transact에서는 CommandType=P로 라우팅합니다.

책임 범위

• 프롬프트 계약을 읽어 provider, model, 메시지, body, tool 사용 범위를 구성합니다.
• 요청 파라미터를 프롬프트 본문과 헤더, 인증 정보, body 속성에 바인딩합니다.
• KernelPlugin, MCP 서버, CLI 도구, body 파일 경로 사용을 allowlist로 제한합니다.
• LLM 응답을 HandStack 거래 응답 형식으로 변환합니다.
• 요청/응답 로그와 채팅 이력 출력 여부를 설정으로 제어합니다.

주요 API

메서드	경로	용도
GET	/prompter/api/query/has	프롬프트 계약 존재 여부를 확인합니다.
GET	/prompter/api/query/refresh	프롬프트 계약 캐시를 갱신합니다.
GET	/prompter/api/query/retrieve	계약 원문 또는 상세 정보를 조회합니다.
GET	/prompter/api/query/meta	입력/출력 메타 정보를 반환합니다.
GET	/prompter/api/query/reports	계약 기반 보고용 정보를 조회합니다.
POST	/prompter/api/query/execute	프롬프트 계약을 실행합니다.

핵심 구현

• Areas/prompter/Controllers/QueryController.cs: query API 진입점입니다.
• DataClient/PromptClient.cs: 프롬프트 계약 실행과 LLM provider 호출을 담당합니다.
• Extensions/PromptMapper.cs: XML 계약 로드와 refresh를 담당합니다.
• Entity/ModuleConfigJson.cs: LLMSource와 도구 allowlist 설정 스키마입니다.
• Events/ManagedRequestHandler.cs: 관리 기능에서 전달되는 설정 변경 요청을 처리합니다.

계약과 식별자

계약은 기본적으로 다음 위치에 둡니다.

contracts/prompter/{ApplicationID}/{ProjectID}/{TransactionID}.xml

프롬프트 ID는 다음 형식으로 조회됩니다.

ApplicationID|ProjectID|TransactionID|PromptID

프롬프트 본문은 ${ParameterName} 형태로 요청 값을 치환합니다. authorization, headers, body 속성처럼 값 전체를 파라미터로 받을 때는 @ParameterName 형식을 사용합니다.

주요 설정

설정	설명
LLMSource	provider, model, endpoint, API Key, stream/think 옵션을 정의합니다.
AllowedKernelPlugins	계약에서 호출 가능한 커널 플러그인과 함수 allowlist입니다.
AllowedMcpServers	계약에서 사용할 수 있는 MCP 서버 allowlist입니다.
AllowedCliTools	프롬프트 실행 중 사용할 수 있는 CLI 도구 allowlist입니다.
AllowedBodyFileBasePaths	body 파일을 읽을 수 있는 기준 경로입니다.
IsChatHistoryConsoleShow	채팅 이력을 콘솔에 출력할지 결정합니다.
EventAction	기본값은 prompter.Events.ManagedRequest입니다.

LLMSource 예시는 다음과 같습니다.

{
  "ApplicationID": "HDS",
  "ProjectID": "*",
  "DataSourceID": "LLM1",
  "LLMProvider": "OpenAI",
  "ApiKey": "<api-key>",
  "ModelID": "gpt-5.4-mini",
  "Endpoint": "",
  "Think": false,
  "Stream": false
}

transact 연동

transact 거래 계약에서는 CommandType을 P로 둡니다.

{
  "ServiceID": "GPT010",
  "CommandType": "P",
  "ReturnType": "Json"
}

라우팅 예시는 다음과 같습니다.

{
  "HDS|*|P|D": "http://localhost:8421/prompter/api/query",
  "HDS|*|P|P": "http://localhost:8421/prompter/api/query",
  "HDS|*|P|T": "http://localhost:8421/prompter/api/query"
}

운영 주의사항

• API Key, endpoint, 로컬 모델 경로는 실제 값으로 계약이나 공개 문서에 남기지 않습니다.
• 도구 호출은 계약 선언과 module.json allowlist가 모두 일치할 때만 허용되도록 관리합니다.
• MCP, CLI, 파일 body 기능은 외부 시스템이나 파일 시스템에 접근할 수 있으므로 운영 환경에서는 최소 권한 원칙을 적용합니다.
• LLM 응답은 비결정적일 수 있으므로 업무 거래에서는 후속 검증, 스키마 검사, 실패 시 fallback 전략을 함께 설계합니다.