Package Exports
- @kangthink/q-engine
- @kangthink/q-engine/browser
Readme
Q-Engine
생각을 자극하는 질문답변을 생성하는 엔진 (A question-answer generation engine that stimulates thinking)
개요
Q-Engine은 질문과 답변을 다양한 사고 방식을 통해 변환하고 확장하는 TypeScript 라이브러리입니다. 육하원칙, 소크라테스식 문답법, Matrix 모드 등 여러 변환 모드를 지원하여 깊이 있는 사고를 유도합니다.
주요 기능
- 🤖 자동 타입 감지: 입력 내용을 분석하여 질문/답변 자동 분류 (신뢰도 표시)
- 🔄 다양한 변환 모드: 육하원칙(5W1H), 소크라테스식, Matrix 모드, 답변 생성
- 💬 답변 생성: 질문에 대한 답변을 다양한 길이와 톤으로 생성
- 📊 그래프 구조: Node(Question/Answer)와 Edge(Transform)를 기반으로 한 관계형 데이터
- 🎯 정확한 타입 매핑: 모든 변환 모드에서 의미론적으로 올바른 결과 생성
- ⚡ 단일/다중 변환: 하나 또는 여러 개의 결과를 유연하게 생성
- 📏 답변 길이 제어: SHORT(1-2문장), MEDIUM(3-5문장), LONG(6-10문장), DETAILED(10+문장)
- 🔧 확장 가능: 커스텀 LLM Provider와 프롬프트 템플릿 지원
- 💻 CLI 지원: 명령줄에서 바로 사용 가능
- 🏷️ TypeScript: 완전한 타입 지원
설치
npm 퍼블릭 패키지
npm install @kangthink/q-engine
npx q-engine transform "테스트" --mode socratic
Git 저장소에서 직접 설치
# GitHub에서 설치
npm install git+https://github.com/your-username/q-engine.git
# 설치 후 사용
npx q-engine transform "테스트 질문" --mode socratic
로컬 개발/테스트
git clone https://github.com/your-username/q-engine.git
cd q-engine
npm install
npm run build
# 글로벌 링크 (선택사항)
npm link
# 사용
npm run cli -- transform "테스트" --mode 5w1h
# 또는 링크 후: q-engine transform "테스트" --mode 5w1h
사용법
프로그래밍 방식
import {
QEngine,
NodeModel,
OpenAIProvider,
MockLLMProvider,
TransformMode,
TypeDetector,
AnswerLength
} from 'q-engine';
// OpenAI Provider 사용 (실제 AI 응답)
const openaiProvider = new OpenAIProvider({
apiKey: 'your-openai-api-key',
model: 'gpt-3.5-turbo',
temperature: 0.7
});
// 또는 Mock Provider 사용 (테스트용)
const mockProvider = new MockLLMProvider();
// 엔진 초기화
const engine = new QEngine({ llmProvider: openaiProvider });
await engine.initialize();
// 🤖 자동 타입 감지 사용
const content = "선글라스는 비싸다";
const analysis = TypeDetector.analyzeType(content);
console.log(`감지 결과: ${analysis.type} (${analysis.reason}, 신뢰도: ${Math.round(analysis.confidence * 100)}%)`);
// 감지된 타입으로 Node 생성
const sourceNode = analysis.type === 'QUESTION'
? NodeModel.createQuestion(content)
: NodeModel.createAnswer(content);
// 단일 변환
const result = await engine.transform(sourceNode, TransformMode.FIVE_W_ONE_H);
console.log('생성된 질문:', result.targetNode.content);
// 다중 변환 (여러 질문 생성)
const multiResult = await engine.transformMultiple(sourceNode, TransformMode.MATRIX, { count: 3 });
multiResult.targetNodes.forEach((node, index) => {
console.log(`질문 ${index + 1}:`, node.content);
});
// 💬 답변 생성 (질문 → 답변)
const questionNode = NodeModel.createQuestion("인공지능이란 무엇인가?");
const answerResult = await engine.transform(questionNode, TransformMode.ANSWER, {
answerOptions: {
length: AnswerLength.MEDIUM,
tone: 'academic',
includeExamples: true
}
});
console.log('답변:', answerResult.targetNode.content);
// 연쇄 변환 (여러 모드 순차 적용)
const chainResult = await engine.transformChain(
sourceNode,
[TransformMode.FIVE_W_ONE_H, TransformMode.SOCRATIC, TransformMode.ANSWER]
);
CLI 사용
# 환경변수 설정 (OpenAI API 사용)
export OPENAI_API_KEY="your-api-key"
# 🤖 자동 타입 감지 (기본값)
q-engine transform "선글라스는 비싸다" --mode 5w1h -n 3
# 🤖 자동 감지: "선글라스는 비싸다" → 답변/진술 (단정적 어미 사용, 신뢰도: 80%)
# 명시적 타입 지정
q-engine transform "인공지능이란 무엇인가?" --type question --mode socratic
# Matrix 모드 (레벨과 방향 지정)
q-engine transform "머신러닝은 어떻게 작동하나요?" --mode matrix --matrix-level 3 --matrix-direction context -n 5
# 💬 답변 생성 (짧게)
q-engine transform "인공지능이란 무엇인가?" --mode answer --answer-length short
# 💬 답변 생성 (상세히, 예시 포함)
q-engine transform "머신러닝의 원리는?" --mode answer --answer-length detailed --answer-tone academic --include-examples
# 💬 답변 생성 (여러 개, 다양한 관점)
q-engine transform "블록체인 기술이란?" --mode answer --answer-length medium -n 3
# 다중 생성 (여러 질문 한번에)
q-engine transform "몰입하는 방법은?" --mode 5w1h -n 6
# 연쇄 변환 (질문 → 소크라테스식 질문 → 답변)
q-engine chain "의식이란 무엇인가?" --modes "5w1h,socratic,answer"
# 그래프 데이터 내보내기/가져오기
q-engine export graph.json
q-engine import graph.json
# 환경변수 설정 가이드
q-engine config
# 예제 보기
q-engine examples
변환 모드
1. 육하원칙 (5W1H) 모드
- Who (누가): 주체나 행위자 식별
- What (무엇을): 주요 주제나 행동 정의
- When (언제): 시간적 측면 고려
- Where (어디서): 위치나 맥락 고려
- Why (왜): 동기나 이유 탐구
- How (어떻게): 방법이나 과정 검토
2. 소크라테스 모드
- 호기심을 자극하는 방향으로 질문 생성
- 정의나 표현이 명확하지 않은 부분을 명확하게
- 가정에 대한 비판적 검토 유도
- 지적 탐구를 통한 깊은 이해 추구
3. Matrix 모드
레벨 (Level):
- 사실 확인: 표면적 정보
- 이해·설명: 개념과 원리
- 원인·맥락: 배경과 관계
- 적용·비교: 다른 상황에 적용
- 평가·창의·비판: 한계와 대안
방향 (Direction):
- Focused: 주제 내부로 깊이 파고들기
- Context: 관련 주제로 시야 확장
- Applied: 새로운 상황에 적용
- Critical: 비판적 관점에서 접근
4. 답변 (Answer) 모드
질문에 대한 답변을 생성합니다. 답변의 길이와 톤을 제어할 수 있어 용도에 맞게 활용할 수 있습니다.
길이 옵션 (Length):
- SHORT: 짧게 (1-2문장) - 핵심만 간단히
- MEDIUM: 보통 (3-5문장) - 적절한 설명과 함께
- LONG: 길게 (6-10문장) - 충분한 설명과 배경 정보
- DETAILED: 상세히 (10+문장) - 매우 상세하고 포괄적으로
톤 옵션 (Tone):
- formal: 정중하고 격식 있는 어조
- casual: 친근하고 편안한 어조
- academic: 학술적이고 전문적인 어조
- simple: 쉽고 이해하기 쉬운 어조
추가 옵션:
- includeExamples: 구체적인 예시 포함
API 레퍼런스
QEngine
class QEngine {
constructor(config: QEngineConfig)
// 단일 변환
async transform(
sourceNode: Node,
mode: TransformMode,
options?: Record<string, any>
): Promise<TransformResult>
// 다중 변환
async transformMultiple(
sourceNode: Node,
mode: TransformMode,
options?: Record<string, any>
): Promise<MultiTransformResult>
// 연쇄 변환
async transformChain(
sourceNode: Node,
modes: TransformMode[],
options?: Record<string, any>[]
): Promise<TransformResult[]>
// 그래프 관리
exportGraph(): { nodes: Node[], edges: Edge[] }
importGraph(data: { nodes: Node[], edges: Edge[] }): void
}
TypeDetector (자동 타입 감지)
class TypeDetector {
// 타입 감지 (QUESTION 또는 ANSWER)
static detectType(content: string): NodeType
// 감지 신뢰도 (0-1)
static getConfidence(content: string): number
// 타입, 신뢰도, 이유를 모두 포함한 분석
static analyzeType(content: string): {
type: NodeType;
confidence: number;
reason: string;
}
}
환경변수 설정
# OpenAI API 설정
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="gpt-3.5-turbo" # 선택사항
export OPENAI_TEMPERATURE="0.7" # 선택사항
export OPENAI_MAX_TOKENS="1000" # 선택사항
커스텀 LLM Provider
import { LLMProvider } from 'q-engine';
class MyLLMProvider implements LLMProvider {
async generateResponse(prompt: string): Promise<string> {
// 커스텀 LLM API 호출 구현
return generatedResponse;
}
}
// 사용
const engine = new QEngine({ llmProvider: new MyLLMProvider() });
브라우저에서 사용
Q-Engine은 Node.js뿐만 아니라 브라우저에서도 사용할 수 있습니다.
브라우저 설치
npm install @kangthink/q-engine
브라우저에서 사용법
// 브라우저 전용 import
import {
QEngine,
MockLLMProvider,
NodeModel,
OpenAIProvider,
TransformMode,
NodeType
} from '@kangthink/q-engine/browser';
// 또는 번들러가 자동 감지
import { QEngine, MockLLMProvider, NodeModel } from '@kangthink/q-engine';
// Mock Provider 사용 (테스트용)
const provider = new MockLLMProvider();
const engine = new QEngine({ llmProvider: provider });
// Node 객체 생성
const sourceNode = new NodeModel(NodeType.QUESTION, "학습 효과를 높이는 방법은?");
const result = await engine.transform(sourceNode, TransformMode.SOCRATIC);
console.log('입력:', result.targetNode.content);
console.log('출력:', result.targetNode.content);
// OpenAI Provider 사용 (실제 AI)
const openAIProvider = new OpenAIProvider('your-api-key');
const engineWithAI = new QEngine({ llmProvider: openAIProvider });
HTML 예제
<!DOCTYPE html>
<html>
<head>
<title>Q-Engine Browser Example</title>
</head>
<body>
<script type="module">
import { QEngine, MockLLMProvider, NodeModel, TransformMode, NodeType }
from './node_modules/@kangthink/q-engine/dist/index.browser.js';
async function transform() {
const provider = new MockLLMProvider();
const engine = new QEngine({ llmProvider: provider });
// Node 객체 생성
const sourceNode = new NodeModel(NodeType.QUESTION, "학습 효과를 높이는 방법은?");
const result = await engine.transform(sourceNode, TransformMode.SOCRATIC);
console.log('입력:', sourceNode.content);
console.log('출력:', result.targetNode.content);
}
transform();
</script>
</body>
</html>
브라우저 vs Node.js 차이점
기능 | Node.js | 브라우저 |
---|---|---|
CLI 도구 | ✅ 지원 | ❌ 미지원 |
파일 시스템 접근 | ✅ 지원 | ❌ 미지원 |
프롬프트 파일 로딩 | ✅ 지원 | ❌ 미지원 |
기본 프롬프트 | ✅ 지원 | ✅ 지원 |
동적 프롬프트 추가 | ✅ 지원 | ✅ 지원 |
OpenAI Provider | ✅ 지원 | ✅ 지원 |
Mock Provider | ✅ 지원 | ✅ 지원 |
개발
# 의존성 설치
npm install
# 빌드
npm run build
# 테스트
npm test
# 개발 모드
npm run dev
라이선스
MIT