AI Assistant

외부 AI와 연동하기 위한 패널·도구·실행 API 설정과 사용법을 안내한다.

RealPivot2는 AI 모델이나 AI 서비스를 제공하지 않는다. 외부 LLM·에이전트와 연동할 수 있는 패널(UI), 피벗 조작 도구(tool), 실행 API, 그리고 RAG 연동 지점을 제공한다. 추론, 응답 생성, 지식 코퍼스(Corpus) 관리 등은 연동한 외부 모델이나 서버에서 담당한다.

Book 개요는 피벗 북(Book)을 참고한다.

RealPivot2가 제공하는 것

구분	내용
AI 패널	질의 입력·대화·제안 문구를 표시하는 UI (`ai.panel`)
모델 연결	외부 OpenAI/Gemini API 또는 자체 원격 서버 연동 (`ai.models`)
도구(tool)	필드 이동·필터·분석 등 피벗을 조작하는 명령 스키마
실행 API	`book.aiApi`로 도구를 실행하는 관문
RAG 연동	설정 지식 검색(`search_features`)·로컬 임베딩 검색(`useRag`)·컨텍스트 파일 로드

AI 라이선스·API 키·원격 서버·지식베이스 구축·응답 품질은 RealPivot2 범위가 아니다. 연동 목적과 사용 환경에 맞춰 직접 구축해야 한다.

지정 위치

피벗 북(Book) 설정의 ai 옵션(PivotAIOptions)에서 활성화한다. 기본값은 enabled: false이다.

속성	역할
`enabled`	AI 연동 UI·기능 사용 여부
`models`	연결할 외부 모델(로컬 API 또는 원격 서버)
`panel`	패널 위치·크기·프롬프터 UI
`resources`	컨텍스트 파일·RAG 기능 검색(`featureSearch`) 등
`autoSubmit`	제안 문구 클릭 시 바로 전송할지 여부
`addMode`	테이블 추가 UI (`'dialog'` \| `'page'`)
`devMode`	개발자 모드(모델이 넘긴 설정 내용 표시)

const config = {
  ai: {
    enabled: true,
    models: {
      type: 'remote',
      name: 'my-server',
      modelName: 'gpt-4.1',
      url: 'https://my-ai.example.com/v1',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN>',
      },
    },
    panel: {
      position: 'right',
      width: 320,
      prompter: {
        suggestions: [
          '판매수량 이상치를 탐지해줘.',
          '판매수량에 데이터바를 적용해.',
        ],
      },
    },
  },
  tables: {
    name: 'sales',
    cube: 'sales',
    // fields ...
  },
};

AI 패널

AI 패널은 외부 LLM과 대화하는 UI 영역이다. ai.panel.position 옵션으로 위치를 지정할 수 있다.

`position`	표시 위치
`'right'`(기본)	북 오른쪽
`'left'`	북 왼쪽
`'float'`	떠 있는 패널(`floatBounds`로 초기 위치·크기)
`'inspector'`	인스펙터 탭
`'explorer'`	탐색기 탭 (탐색기)

ai: {
  enabled: true,
  panel: {
    position: 'explorer',
    width: 320,
    autoDock: true,
    prompter: {
      greetings: '피벗 구성을 자연어로 요청해 보세요.',
      placeholder: '예: 차종을 행으로 옮겨줘',
      waitingMessage: '분석 중...',
      suggestions: ['국가를 필터에 넣어줘.'],
    },
  },
}

ai.panel.prompter 항목은 인사말, 제안어, placeholder 등 패널 UI에 표시될 문구만 설정하며, 실제 답변은 연동된 AI 모델이 생성한다.

헤더·탭바의 AI 관련 버튼은 ai.enabled가 true일 때 표시된다.

외부 모델 연결

ai.models에 개발자가 사용할 모델을 등록한다. 객체 하나 또는 배열로 지정할 수 있다.

원격 서버 (`type: 'remote'`)

자체 백엔드(또는 프록시)를 경유해 LLM을 호출하는 방식이다.

속성	설명
`name`	모델 식별 이름
`modelName`	서버에서 쓰는 모델 이름
`url`	서버 베이스 URL
`headers`	`Authorization` 등 요청 헤더
`commandsPath` / `contextPath` / `queryPath`	하위 경로(기본 `commands` · `context` · `query`)

models: {
  type: 'remote',
  name: 'my-server',
  modelName: 'gpt-4.1',
  url: 'https://my-ai.example.com/v1',
  headers: { Authorization: 'Bearer <YOUR_TOKEN>' },
}

원격 모델의 전체 설정 항목은 Config · ai · models를 참고한다.

브라우저에서 provider API 호출 (`type: 'local'`)

OpenAI·Gemini API를 브라우저에서 직접 호출한다. provider는 'openai' 또는 'gemini'이다.

속성	설명
`provider`	`'openai'` \| `'gemini'`
`apiKey`	provider API 키
`modelName`	호출할 모델 이름
`endpoint`	커스텀 base URL(선택)

models: {
  type: 'local',
  name: 'gpt',
  provider: 'openai',
  modelName: 'gpt-4.1',
  apiKey: '<YOUR_OPENAI_API_KEY>',
}

로컬 모델의 전체 설정 항목은 Config · ai · models를 참고한다.

피벗 도구(tool)

RealPivot2는 LLM이 피벗을 제어할 수 있도록 조작 도구(Tool) 항목들을 제공한다. 도구 자체는 AI가 아니며, 연동된 AI가 피벗을 변경할 때 호출하는 명령 스키마 목록이다.

대표 예시는 다음과 같다.

도구	역할
`move_field` / `remove_field` / `add_value_field`	필드 배치
`filter_by_member` / `set_slicer_filter`	필터
`config`	테이블 옵션 변경
`detect_outliers` / `analyze_growth` 등	분석
`search_features`	설정 방법 RAG 검색(`resources.featureSearch.url`이 있을 때)
`focus_cell`	셀 포커스

옵션 구조가 확실하지 않을 경우, AI가 임의로 추측하기보다는 search_features 도구로 지식베이스를 먼저 검색한 후 반환된 config를 적용하도록 구성하는 것을 권장한다.

스키마 목록은 getAITools() · exportAITools() · book.aiApi.getToolSchemas()로 확인할 수 있다.

import { getAITools, exportAITools } from 'realpivot2';
 
const tools = getAITools();
const schemaJson = exportAITools();

외부 에이전트에서 실행하기

자체 채팅 UI·에이전트를 쓰는 경우에도 book.aiApi(PivotAIApi)로 동일 도구를 실행할 수 있다. 내장 AI 패널을 쓰지 않아도 된다.

const api = control.book.aiApi;
 
const schemas = api.getToolSchemas();
const state = api.serializeState({ include: ['config'] });
 
const result = await api.execute({
  tool: 'move_field',
  arguments: {
    // 도구별 인자
  },
  reason: '차종을 행 영역으로 이동합니다.',
});

컨텍스트·도구·상태 조회와 실행 진입점이 API에 모여 있다. 상세는 API 문서를 참고한다.

RAG · 리소스

RealPivot2는 지식베이스(코퍼스)를 내장·호스팅하지 않는다. 대신 AI가 피벗 설정 방법을 스스로 찾도록 RAG 연동을 지원한다. 컨텍스트 파일·검색 엔드포인트·임베딩 코퍼스는 앱에서 제공한다.

컨텍스트 파일

ai.resources로 모델에 넘길 설명 문서 경로를 지정한다.

속성	기본	설명
`systemContextPath`	`'rag/system_context.md'`	시스템 컨텍스트(사용 설명)
`developerContextPath`	`'rag/developer_context.md'`	개발자 컨텍스트

해당 경로의 마크다운(.md) 파일을 웹 애플리케이션에서 접근(서빙)할 수 있도록 설정해야 정상 로드된다.

설정 방법 검색 (`featureSearch`)

search_features 도구가 호출하는 원격 RAG 엔드포인트이다. 히트맵이나 데이터바 등 복잡한 config 구조를 모를 때, AI가 지식베이스를 검색하여 가져온 설정을 config 도구에 적용할 수 있도록 지원한다.

속성	설명
`featureSearch.url`	POST 대상 URL(필수, 없으면 도구 미노출)
`featureSearch.headers`	`Authorization` 등
`featureSearch.enabled`	사용 여부(기본 `true`)

요청·응답 계약은 다음과 같다.

요청: POST body { query }
응답: { count, grounding }

ai: {
  enabled: true,
  resources: {
    systemContextPath: 'rag/system_context.md',
    developerContextPath: 'rag/developer_context.md',
    featureSearch: {
      url: '/api/feature-search',
      headers: { Authorization: 'Bearer <YOUR_TOKEN>' },
    },
  },
  // models, panel ...
}

전체 항목은 Config · ai · resources · featureSearch를 참고한다.

로컬 모델 RAG (`useRag`)

type: 'local' 모델에서는 질의마다 임베딩 코퍼스를 검색해 프롬프트에 주입할 수 있다. 코퍼스 파일도 앱이 서빙하며, RealPivot2는 검색·주입 경로만 제공한다.

속성	설명	기본
`useRag`	검색 결과를 프롬프트에 자동 주입	`false`
`embeddingModel`	질의 임베딩 모델(코퍼스와 동일해야 함)	provider별 기본
`ragTopK`	상위 chunk 수	`5`
`ragEmbeddingsPath`	임베딩 바이너리(Float32)	provider별 (`rag/openai/...` 등)
`ragChunksPath`	원문 chunk JSON	provider별
`ragMetaPath`	메타(count/dim/model)	provider별

models: {
  type: 'local',
  name: 'gpt',
  provider: 'openai',
  modelName: 'gpt-4.1',
  apiKey: '<YOUR_OPENAI_API_KEY>',
  useRag: true,
  ragTopK: 5,
}

패널 UI 메뉴에서도 로컬 모델의 RAG 활성화 여부를 전환할 수 있다. featureSearch(원격 도구 검색) 방식과 useRag(로컬 프롬프트 주입) 방식은 독립적으로 동작하므로, 상황에 맞춰 개별 또는 조합하여 사용할 수 있다.

API로 패널·질의 다루기

const ai = control.book.ai;
const panel = ai.panel;
const prompter = panel.prompter;
 
ai.enabled; // true / false
ai.setActiveModel('my-server');
 
prompter.send('판매수량에 히트맵을 적용해줘.');
prompter.reset();

옵션 변경 규칙은 개발 가이드를 참고한다.