VocaEngine

A vocabulary enhancement assistant that helps users collect, manage, and reuse vocabulary suggestions through AI-powered generation and organized collections.

Features

• Multiple Input Types: Support for expressions, explanations, and images
• AI-Powered Suggestions: Generate vocabulary alternatives using OpenAI or mock providers
• Collection Management: Organize vocabulary entries into named collections
• Tagging System: Add tags to entries for better organization and searchability
• Search Functionality: Find entries by content, suggestions, or tags
• CLI Interface: Complete command-line interface for all operations
• TypeScript Support: Full TypeScript support with type definitions
• Cross-Platform: Works in Node.js and browser environments

Installation

npm install @kangthink/voca-engine

Quick Start

Using the CLI

# Install globally for CLI access
npm install -g @kangthink/voca-engine

# Quick workflow: add input and generate suggestions
voca-engine quick -t expression -c "노래 소리가 잔잔하게 들린다"

# Create a collection
voca-engine create-collection -n "일상 표현 모음"

# Use mock provider for testing
voca-engine quick -t expression -c "테스트 표현" --mock

Using as a Library

import { VocaEngine, OpenAIProvider, InputType } from '@kangthink/voca-engine';

// Initialize with OpenAI provider
const provider = new OpenAIProvider(process.env.OPENAI_API_KEY);
const engine = new VocaEngine({
  llmProvider: provider,
  defaultSuggestionCount: 5
});

// Add input and generate suggestions
const input = await engine.addInput(InputType.Expression, "노래 소리가 잔잔하게 들린다");
const suggestions = await engine.generateSuggestions(input.id);

// Create collection and save entry
const collection = await engine.createCollection("일상 표현 모음");
const entry = await engine.saveEntry(
  input.id, 
  suggestions.id, 
  collection.id, 
  ["카페", "감성"]
);

API Reference

Core Operations

addInput(type, content)

Add a new input for vocabulary generation.

const input = await engine.addInput(InputType.Expression, "잔잔하게 들린다");

generateSuggestions(inputId)

Generate vocabulary suggestions for an input.

const suggestions = await engine.generateSuggestions(input.id);

createCollection(name)

Create a new collection for organizing entries.

const collection = await engine.createCollection("감성 표현");

saveEntry(inputId, suggestionId, collectionId, tags?)

Save an entry (input + suggestion) to a collection.

const entry = await engine.saveEntry(input.id, suggestion.id, collection.id, ["태그1", "태그2"]);

searchEntries(collectionId, query)

Search entries within a collection.

const results = await engine.searchEntries(collection.id, "노래");

Data Types

InputType

enum InputType {
  Expression = 'expression',    // 표현
  Explanation = 'explanation',  // 설명
  Image = 'image'              // 이미지
}

ExpressionInput

interface ExpressionInput {
  id: string;
  type: InputType;
  content: string;
  createdAt: Date;
}

Suggestion

interface Suggestion {
  id: string;
  inputId: string;
  candidates: string[];
  generatedAt: Date;
}

Collection

interface Collection {
  id: string;
  name: string;
  createdAt: Date;
}

Entry

interface Entry {
  id: string;
  input: ExpressionInput;
  suggestion: Suggestion;
  collectionId: string;
  tags: string[];
  savedAt: Date;
}

CLI Commands

Basic Operations

# Add input
voca-engine add-input -t expression -c "노래 소리가 잔잔하게 들린다"

# Generate suggestions
voca-engine generate -i <input-id>

# Quick workflow (add input + generate suggestions)
voca-engine quick -t expression -c "잔잔한 소리"

Collection Management

# Create collection
voca-engine create-collection -n "일상 표현 모음"

# List collections
voca-engine list-collections

# Rename collection
voca-engine rename-collection -c <collection-id> -n "새로운 이름"

Entry Management

# Save entry to collection
voca-engine save-entry -i <input-id> -s <suggestion-id> -c <collection-id> -t "tag1,tag2"

# List entries in collection
voca-engine list-entries -c <collection-id>

# Search entries
voca-engine search -c <collection-id> -q "검색어"

# Delete entry
voca-engine delete-entry -e <entry-id>

Utility Commands

# Show statistics
voca-engine stats

# Show examples
voca-engine examples

# Configure API key
voca-engine config

# Use mock provider for testing
voca-engine quick -t expression -c "테스트" --mock

Configuration

OpenAI API Key

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY=your-api-key-here

Mock Provider

For testing without an API key, use the --mock flag:

voca-engine quick -t expression -c "테스트 표현" --mock

Examples

Example Workflow

# 1. Add an expression input
voca-engine add-input -t expression -c "노래 소리가 잔잔하게 들린다"
# Output: {"success": true, "data": {"id": "abc123", ...}}

# 2. Generate suggestions
voca-engine generate -i abc123
# Output: {"success": true, "data": {"id": "def456", "candidates": ["부드럽게", "조용히", ...]}}

# 3. Create a collection
voca-engine create-collection -n "일상 표현 모음"
# Output: {"success": true, "data": {"id": "ghi789", ...}}

# 4. Save entry to collection
voca-engine save-entry -i abc123 -s def456 -c ghi789 -t "카페,감성"
# Output: {"success": true, "data": {"id": "jkl012", ...}}

# 5. Search entries
voca-engine search -c ghi789 -q "노래"
# Output: {"success": true, "data": [{"id": "jkl012", ...}]}

Programmatic Usage

import { VocaEngine, MockLLMProvider, InputType } from '@kangthink/voca-engine';

// Use mock provider for testing
const engine = new VocaEngine({
  llmProvider: new MockLLMProvider(),
  defaultSuggestionCount: 5
});

async function example() {
  // Add different types of inputs
  const expression = await engine.addInput(
    InputType.Expression, 
    "노래 소리가 잔잔하게 들린다"
  );
  
  const explanation = await engine.addInput(
    InputType.Explanation,
    "카페에서 노래를 들으며 창을 바라보는 상황"
  );
  
  // Generate suggestions
  const suggestions1 = await engine.generateSuggestions(expression.id);
  const suggestions2 = await engine.generateSuggestions(explanation.id);
  
  // Create collections
  const dailyExpressions = await engine.createCollection("일상 표현");
  const situationalExpressions = await engine.createCollection("상황별 표현");
  
  // Save entries with tags
  await engine.saveEntry(
    expression.id, 
    suggestions1.id, 
    dailyExpressions.id, 
    ["음악", "감성"]
  );
  
  await engine.saveEntry(
    explanation.id, 
    suggestions2.id, 
    situationalExpressions.id, 
    ["카페", "분위기"]
  );
  
  // Search across all entries
  const musicEntries = await engine.searchAllEntries("음악");
  const cafeEntries = await engine.searchEntries(situationalExpressions.id, "카페");
  
  // Get statistics
  const stats = await engine.getStats();
  console.log(`Total collections: ${stats.collections}`);
  console.log(`Total entries: ${stats.entries}`);
  console.log(`Total suggestions: ${stats.totalSuggestions}`);
}

Browser Usage

import { VocaEngine, MockLLMProvider } from '@kangthink/voca-engine/browser';

// Browser environment only supports MockLLMProvider
const engine = new VocaEngine({
  llmProvider: new MockLLMProvider()
});

// Same API as Node.js version
const input = await engine.addInput(InputType.Expression, "테스트");
const suggestions = await engine.generateSuggestions(input.id);

Development

Setup

git clone <repository>
cd voca-engine
npm install

Build

npm run build

Test

npm test

CLI Development

npm run dev  # Watch mode for development
npm run cli  # Run CLI in development mode

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.