@kangthink/q-engine/README.md

A question-answer generation engine that stimulates thinking

# 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 퍼블릭 패키지
```bash
npm install @kangthink/q-engine
npx q-engine transform "테스트" --mode socratic
```

### Git 저장소에서 직접 설치
```bash
# GitHub에서 설치
npm install git+https://github.com/your-username/q-engine.git

# 설치 후 사용
npx q-engine transform "테스트 질문" --mode socratic
```

### 로컬 개발/테스트
```bash
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
```

## 사용법

### 프로그래밍 방식

```typescript
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 사용

```bash
# 환경변수 설정 (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)**:
1. 사실 확인: 표면적 정보
2. 이해·설명: 개념과 원리
3. 원인·맥락: 배경과 관계
4. 적용·비교: 다른 상황에 적용
5. 평가·창의·비판: 한계와 대안

**방향 (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

```typescript
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 (자동 타입 감지)

```typescript
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;
  }
}
```

### 환경변수 설정

```bash
# 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

```typescript
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뿐만 아니라 브라우저에서도 사용할 수 있습니다.

### 브라우저 설치

```bash
npm install @kangthink/q-engine
```

### 브라우저에서 사용법

```javascript
// 브라우저 전용 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 예제

```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 | ✅ 지원 | ✅ 지원 |

## 개발

```bash
# 의존성 설치
npm install

# 빌드
npm run build

# 테스트
npm test

# 개발 모드
npm run dev
```

## 라이선스

MIT