@eottabom/tokenizer-core 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# @eottabom/tokenizer-core
+
+오프라인 환경에서 LLM 3사(OpenAI, Anthropic, Google)의 토큰 수를 계산하는 순수 JavaScript 토크나이저입니다.
+
+API 키 없이, 외부 의존성 없이, 로컬에서 바로 동작합니다.
+
+## 특징
+
+- **의존성 제로**: tiktoken WASM, HuggingFace transformers 등 무거운 라이브러리 없이 순수 JS로 BPE 알고리즘을 직접 구현
+- **오프라인 동작**: 토크나이저 데이터(vocab, merges)를 프로젝트에 내장
+- **3사 통합**: OpenAI(tiktoken), Anthropic(Claude), Google(Gemma3) 토크나이저를 하나의 인터페이스로 제공
+
+## 정확도
+
+| Provider | 토크나이저 출처 | 정확도 |
+|---|---|---|
+| OpenAI | tiktoken 공식 인코딩 데이터 포팅 | 공식 tiktoken과 동일 |
+| Anthropic | Xenova/claude-tokenizer 데이터 | 근사치 (~10% 오차 가능) |
+| Google | unsloth/gemma-3-1b-it 데이터 | Gemma3 토크나이저와 동일 |
+
+> Anthropic은 공식 오프라인 토크나이저를 공개하지 않아, 공개된 토크나이저 데이터 기반의 근사치입니다.
+
+## CLI 사용법
+
+```bash
+# 워크스페이스 루트에서 설치
+npm install
+
+# 텍스트 직접 입력
+npx tokenizer-core -t "Hello, world! 안녕하세요."
+
+# 파일에서 읽기
+npx tokenizer-core -f ./document.txt
+
+# 특정 프로바이더만 출력
+npx tokenizer-core -t "텍스트" -p openai
+npx tokenizer-core -t "텍스트" -p anthropic
+npx tokenizer-core -t "텍스트" -p google
+```
+
+### 옵션
+
+| 옵션 | 설명 | 기본값 |
+|---|---|---|
+| `-t, --text <string>` | 토큰을 계산할 텍스트 (`-t` 또는 `-f` 중 하나 필수) | - |
+| `-f, --file <path>` | 토큰을 계산할 파일 경로 (UTF-8) (`-t` 또는 `-f` 중 하나 필수) | - |
+| `-p, --provider <type>` | (선택) 필터링 (`all`, `openai`, `anthropic`, `google`) | `all` |
+
+### 출력 예시
+
+```
+==================================================
+입력된 텍스트 길이: 1,882 글자
+==================================================
+
+[ OpenAI ]
+▶ GPT-4.1, o3, o4-mini, GPT-4o (o200k_base)  : 812 Tokens
+▶ GPT-4-turbo, GPT-4, GPT-3.5 (cl100k_base) : 995 Tokens
+▶ Codex, text-davinci (p50k_base)            : 1,857 Tokens
+
+[ Anthropic ]
+▶ Claude 4.6 ~ 3 Family                      : ~1,095 Tokens (근사치)
+
+[ Google ]
+▶ Gemini 2.5 ~ 1.5, Gemma (Gemma3)           : 842 Tokens
+
+※ Anthropic은 공식 오프라인 토크나이저가 없어 근사치입니다 (~10% 오차 가능)
+==================================================
+```
+
+## 라이브러리로 사용
+
+```javascript
+import { countTokens, providers } from '@eottabom/tokenizer-core';
+
+// 개별 프로바이더 토큰 수 계산
+const count = countTokens("Hello, world!", "openai_o200k");
+
+// 사용 가능한 프로바이더 목록
+// ["openai_o200k", "openai_cl100k", "openai_p50k", "anthropic", "google"]
+console.log(providers);
+```
+
+### 프로바이더 ID
+
+| ID | 대상 모델 |
+|---|---|
+| `openai_o200k` | GPT-4.1, o3, o4-mini, GPT-4o |
+| `openai_cl100k` | GPT-4-turbo, GPT-4, GPT-3.5 |
+| `openai_p50k` | Codex, text-davinci |
+| `anthropic` | Claude 4.6 ~ 3 전 계열 |
+| `google` | Gemini 2.5 ~ 1.5, Gemma |
+
+## 구조
+
+```
+packages/tokenizer-core/
+├── cli.js          ← CLI 진입점
+├── index.js        ← 통합 API (countTokens)
+├── bpe.js          ← BPE 알고리즘 (rank 기반 + merge 목록 기반)
+├── tiktoken.js     ← OpenAI tiktoken 포맷 처리
+├── hf-bpe.js       ← HuggingFace tokenizer.json 포맷 처리
+└── data/
+    ├── o200k_base.json   (2.2MB)
+    ├── cl100k_base.json  (1.0MB)
+    ├── p50k_base.json    (0.5MB)
+    ├── claude.json       (1.7MB)
+    └── gemma3.json       (14MB)
+```
+
+## 토크나이저 데이터 출처
+
+- **OpenAI**: [tiktoken](https://github.com/openai/tiktoken) 인코딩 데이터
+- **Anthropic**: [Xenova/claude-tokenizer](https://huggingface.co/Xenova/claude-tokenizer) (HuggingFace)
+- **Google**: [unsloth/gemma-3-1b-it](https://huggingface.co/unsloth/gemma-3-1b-it) (HuggingFace)

package/bpe.js

@@ -0,0 +1,147 @@
+/**
+ * bpe.js - BPE (Byte Pair Encoding) 핵심 알고리즘
+ *
+ * BPE는 텍스트를 토큰으로 분할하는 알고리즘으로,
+ * "가장 우선순위가 높은 인접 쌍을 반복적으로 병합"하는 원리입니다.
+ *
+ * 두 가지 변형을 제공합니다:
+ * 1. bytePairEncode - rank 기반 (tiktoken/OpenAI용)
+ * 2. mergeBPE       - merge 목록 기반 (HuggingFace/Claude,Gemma용)
+ */
+
+// ============================================================
+// 1. Rank-based BPE (tiktoken 방식 - OpenAI에서 사용)
+// ============================================================
+
+/**
+ * rank 기반 BPE 인코딩
+ *
+ * tiktoken은 모든 가능한 바이트 조합에 "rank(순위)"를 부여합니다.
+ * rank가 낮을수록 우선순위가 높아 먼저 병합됩니다.
+ *
+ * @param {number[]} piece  - 입력 바이트 배열 (UTF-8 인코딩된 텍스트 조각)
+ * @param {Map<string, number>} ranks - 바이트 시퀀스 → rank 매핑
+ *   key: 쉼표로 연결된 바이트열 (예: "72,101,108" = "Hel")
+ *   value: rank 번호 (낮을수록 병합 우선)
+ * @returns {number[]} 토큰 ID 배열
+ */
+export function bytePairEncode(piece, ranks) {
+  // 1바이트는 그 자체가 토큰이므로 바로 반환
+  if (piece.length === 1) {
+    return [ranks.get(String(piece[0]))];
+  }
+
+  // 병합 수행 후, 각 구간을 rank에서 찾아 토큰 ID로 변환
+  const parts = bytePairMerge(piece, ranks);
+  return parts
+    .map(p => ranks.get(piece.slice(p.start, p.end).join(',')))
+    .filter(x => x != null);
+}
+
+/**
+ * rank 기반 BPE의 핵심 병합 루프
+ *
+ * 동작 원리:
+ * 1. 각 바이트를 개별 구간(part)으로 시작
+ * 2. 인접한 두 구간을 합쳤을 때의 rank를 확인
+ * 3. rank가 가장 낮은(우선순위 높은) 쌍을 병합
+ * 4. 더 이상 병합할 수 없을 때까지 반복
+ *
+ * @param {number[]} piece  - 바이트 배열
+ * @param {Map<string, number>} ranks - rank 맵
+ * @returns {{start: number, end: number}[]} 병합된 구간 배열
+ */
+function bytePairMerge(piece, ranks) {
+  // 초기 상태: 각 바이트가 하나의 구간
+  // 예: [72, 101, 108] → [{0,1}, {1,2}, {2,3}]
+  let parts = Array.from({ length: piece.length }, (_, i) => ({
+    start: i,
+    end: i + 1,
+  }));
+
+  while (parts.length > 1) {
+    let minRank = null;
+
+    // 인접 구간 쌍 중 rank가 가장 낮은 것을 찾기
+    for (let i = 0; i < parts.length - 1; i++) {
+      // 두 구간을 합친 바이트열의 rank를 조회
+      const key = piece.slice(parts[i].start, parts[i + 1].end).join(',');
+      const rank = ranks.get(key);
+      if (rank != null && (minRank == null || rank < minRank[0])) {
+        minRank = [rank, i];
+      }
+    }
+
+    // 병합 가능한 쌍이 없으면 종료
+    if (minRank == null) break;
+
+    // 가장 우선순위 높은 쌍을 하나의 구간으로 병합
+    const i = minRank[1];
+    parts[i] = { start: parts[i].start, end: parts[i + 1].end };
+    parts.splice(i + 1, 1);
+  }
+
+  return parts;
+}
+
+// ============================================================
+// 2. Merge-list BPE (HuggingFace 방식 - Claude, Gemma에서 사용)
+// ============================================================
+
+/**
+ * merge 목록 기반 BPE 인코딩
+ *
+ * HuggingFace tokenizer.json에는 merge 규칙이 순서대로 나열되어 있습니다.
+ * 목록의 앞에 있을수록 우선순위가 높아 먼저 병합됩니다.
+ *
+ * 예) merges: ["▁ t", "e r", "▁t h", ...]
+ *   → "▁"와 "t"를 먼저 병합, 그 다음 "e"와 "r" 병합, ...
+ *
+ * @param {string[]} symbols    - 초기 심볼 배열 (개별 문자 또는 바이트 문자)
+ * @param {Map<string, number>} mergeRanks - "심볼A 심볼B" → 우선순위(인덱스) 매핑
+ * @returns {string[]} 병합이 완료된 심볼 배열 (각 심볼 = 하나의 토큰)
+ */
+export function mergeBPE(symbols, mergeRanks) {
+  if (symbols.length <= 1) return symbols;
+
+  let word = [...symbols];
+
+  while (word.length > 1) {
+    // 현재 인접 쌍 중 우선순위가 가장 높은(인덱스가 가장 낮은) 것 찾기
+    let bestPair = null;
+    let bestRank = Infinity;
+
+    for (let i = 0; i < word.length - 1; i++) {
+      const pair = word[i] + ' ' + word[i + 1];
+      const rank = mergeRanks.get(pair);
+      if (rank !== undefined && rank < bestRank) {
+        bestRank = rank;
+        bestPair = [word[i], word[i + 1]];
+      }
+    }
+
+    // merge 목록에 해당하는 쌍이 없으면 종료
+    if (bestPair == null) break;
+
+    // 해당 쌍의 모든 출현을 병합
+    // 예: ["a", "b", "a", "b"] + merge("a","b") → ["ab", "ab"]
+    const [first, second] = bestPair;
+    const merged = first + second;
+    const newWord = [];
+    let i = 0;
+
+    while (i < word.length) {
+      if (i < word.length - 1 && word[i] === first && word[i + 1] === second) {
+        newWord.push(merged);
+        i += 2; // 두 심볼을 건너뜀
+      } else {
+        newWord.push(word[i]);
+        i++;
+      }
+    }
+
+    word = newWord;
+  }
+
+  return word;
+}

package/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * cli.js - 오프라인 LLM 3사 모델별 토큰 계산 CLI
+ *
+ * 사용법:
+ *   node cli.js -t "텍스트"          # 직접 텍스트 입력
+ *   node cli.js -f ./file.txt        # 파일에서 읽기
+ *   node cli.js -t "텍스트" -p openai # 특정 프로바이더만 출력
+ *
+ * 옵션:
+ *   -t, --text <string>   토큰을 계산할 텍스트
+ *   -f, --file <path>     토큰을 계산할 파일 경로 (UTF-8)
+ *   -p, --provider <type> 필터링 (all | openai | anthropic | google)
+ */
+
+import { program } from 'commander';
+import fs from 'fs';
+import { countTokens } from './index.js';
+
+// CLI 옵션 정의
+program
+  .name('tokenizer-core')
+  .description('오프라인 LLM 3사 모델별 토큰 계산 CLI (의존성 제로)')
+  .option('-t, --text <string>', '토큰을 계산할 직접 텍스트 입력')
+  .option('-f, --file <path>', '토큰을 계산할 텍스트 파일 경로 (UTF-8)')
+  .option('-p, --provider <type>', '특정 제공자 필터링 (all, openai, anthropic, google)', 'all')
+  .parse();
+
+const opts = program.opts();
+
+// ── 입력 검증 ──────────────────────────────────────────────
+
+if (!opts.text && !opts.file) {
+  console.error('오류: -t (텍스트) 또는 -f (파일) 옵션 중 하나를 반드시 제공해야 합니다.');
+  process.exit(1);
+}
+
+const validProviders = ['all', 'openai', 'anthropic', 'google'];
+if (!validProviders.includes(opts.provider)) {
+  console.error(`오류: --provider 값은 ${validProviders.join(', ')} 중 하나여야 합니다.`);
+  process.exit(1);
+}
+
+// ── 텍스트 로드 ────────────────────────────────────────────
+
+let text;
+if (opts.file) {
+  if (!fs.existsSync(opts.file)) {
+    console.error(`오류: 파일을 찾을 수 없습니다: ${opts.file}`);
+    process.exit(1);
+  }
+  text = fs.readFileSync(opts.file, 'utf-8');
+} else {
+  text = opts.text;
+}
+
+// ── 숫자 포맷팅 (천단위 콤마) ──────────────────────────────
+
+function fmt(n) {
+  return n.toLocaleString('ko-KR');
+}
+
+// ── 결과 출력 ──────────────────────────────────────────────
+
+const separator = '='.repeat(50);
+const provider = opts.provider;
+
+console.log(separator);
+console.log(`입력된 텍스트 길이: ${fmt(text.length)} 글자`);
+console.log(separator);
+
+// [ OpenAI ] - 인코딩별로 대응하는 모델 그룹이 다름
+if (provider === 'all' || provider === 'openai') {
+  console.log('');
+  console.log('[ OpenAI ]');
+  console.log(`▶ GPT-4.1, o3, o4-mini, GPT-4o (o200k_base)  : ${fmt(countTokens(text, 'openai_o200k'))} Tokens`);
+  console.log(`▶ GPT-4-turbo, GPT-4, GPT-3.5 (cl100k_base) : ${fmt(countTokens(text, 'openai_cl100k'))} Tokens`);
+  console.log(`▶ Codex, text-davinci (p50k_base)            : ${fmt(countTokens(text, 'openai_p50k'))} Tokens`);
+}
+
+// [ Anthropic ] - Claude 3 이후 전 계열 공통 토크나이저
+// 공식 오프라인 토크나이저가 없어 근사치 (실제 API 대비 ~10% 오차 가능)
+if (provider === 'all' || provider === 'anthropic') {
+  console.log('');
+  console.log('[ Anthropic ]');
+  console.log(`▶ Claude 4.6 ~ 3 Family                      : ~${fmt(countTokens(text, 'anthropic'))} Tokens (근사치)`);
+}
+
+// [ Google ] - Gemini/Gemma 전 계열 공통 (Gemma3 토크나이저 기반)
+if (provider === 'all' || provider === 'google') {
+  console.log('');
+  console.log('[ Google ]');
+  console.log(`▶ Gemini 2.5 ~ 1.5, Gemma (Gemma3)           : ${fmt(countTokens(text, 'google'))} Tokens`);
+}
+
+console.log('');
+console.log('※ Anthropic은 공식 오프라인 토크나이저가 없어 근사치입니다 (~10% 오차 가능)');
+console.log(separator);