cost_guard_ai 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# COST_GUARD_AI
+
+# Contributing to COST_GUARD_AI
+# COST_GUARD_AI 기여 가이드
+
+---
+
+### English
+Thank you for your interest in contributing to **cost_guard_ai**! We welcome all contributions that help developers optimize LLM costs and security.
+
+#### How to contribute
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Make sure to include bilingual comments (English first) in your code.
+4. Ensure all tests pass by running `npm test`.
+5. Submit a Pull Request.
+
+---
+
+### 한국어
+**cost_guard_ai**에 관심을 가져주셔서 감사합니다! 개발자들이 LLM 비용과 보안을 최적화하는 데 도움이 되는 모든 기여를 환영합니다.
+
+#### 기여 방법
+1. 저장소를 포크합니다.
+2. 새로운 기능이나 버그 수정을 위한 브랜치를 생성합니다.
+3. 코드에 한영 병기 주석(영어 먼저)을 포함해 주세요.
+4. `npm test`를 실행하여 모든 테스트가 통과하는지 확인합니다.
+5. 풀 리퀘스트를 제출합니다.

package/LICENSE

@@ -0,0 +1,27 @@
+COST_GUARD_AI
+
+MIT License
+
+Copyright (c) 2008-2026 Rheehose (Rhee Creative)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+English: This license covers the 'cost_guard_ai' package.
+한국어: 이 라이선스는 'cost_guard_ai' 패키지에 적용됩니다.

package/README.md

@@ -0,0 +1,59 @@
+# COST_GUARD_AI
+
+## Intelligent Prompt Compression & Security Middleware for LLMs
+## LLM을 위한 지능형 프롬프트 압축 및 보안 미들웨어
+
+---
+
+### English Description
+**cost_guard_ai** is a powerful guardian for developers and enterprises using LLM APIs (OpenAI, Anthropic, etc.). It sits between your application and the AI to optimize costs, ensure data privacy, and maintain high response quality.
+
+#### Key Features
+1. **Semantic Prompt Compression**: Reduces token consumption by 20-30% while maintaining context.
+2. **PII Masking**: Automatically detects and masks sensitive information (emails, phone numbers, credit cards, etc.).
+3. **Caching Layer**: Instantly returns responses for identical or similar queries from a local/DB cache.
+4. **Budget Management**: Monitors API usage and prevents overspending with budget alerts and hard limits.
+
+---
+
+### 한국어 설명
+**cost_guard_ai**는 LLM API(OpenAI, Anthropic 등)를 사용하는 개발자와 기업을 위한 강력한 가디언입니다. 애플리케이션과 AI 사이에서 비용을 최적화하고, 데이터 프라이버시를 보장하며, 높은 응답 품질을 유지합니다.
+
+#### 핵심 기능
+1. **지능형 프롬프트 압축 (Semantic Prompt Compression)**: 문맥을 유지하면서 토큰 사용량을 20~30% 절감합니다.
+2. **개인정보 마스킹 (PII Masking)**: 이메일, 전화번호, 신용카드 번호 등 민감 정보를 자동으로 탐지하여 마스킹 처리합니다.
+3. **캐싱 레이어 (Caching Layer)**: 동일하거나 유사한 질문에 대해 로컬/DB 캐시에서 즉시 응답을 반환합니다.
+4. **예산 관리 (Budget Management)**: API 사용량을 모니터링하고 설정된 예산을 초과하지 않도록 알림 및 차단 기능을 제공합니다.
+
+---
+
+### Installation / 설치
+```bash
+npm install cost_guard_ai
+```
+
+### Usage / 사용법
+```javascript
+import { AICostGuard } from 'cost_guard_ai';
+import OpenAI from 'openai';
+
+const guard = new AICostGuard({
+  maxTokenBudget: 10000, // Daily budget limit / 일일 예산 설정
+  maskPII: true,         // Enable PII masking / 개인정보 마스킹 활성화
+  compress: true         // Enable prompt compression / 프롬프트 압축 활성화
+});
+
+const openai = new OpenAI();
+
+// Wrap the existing call / 기존 호출 방식에 가드를 입힘
+const response = await guard.wrap(openai.chat.completions.create({
+  model: "gpt-4",
+  messages: [{ role: "user", content: "Check the balance for customer Hong Gil-dong (010-1234-5678)." }]
+}));
+```
+
+---
+
+### License / 라이선스
+MIT License
+Copyright (c) 2008-2026 Rheehose (Rhee Creative)

package/dist/budget.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Budget Management Module
+ * 예산 관리 모듈
+ */
+export interface BudgetOptions {
+    maxTokenBudget?: number;
+    onBudgetExceeded?: (current: number, limit: number) => void;
+}
+/**
+ * Budget Manager Class
+ * 예산 관리자 클래스
+ */
+export declare class BudgetManager {
+    private usedTokens;
+    private options;
+    private lastReset;
+    constructor(options: BudgetOptions);
+    /**
+     * Resets usage daily if necessary.
+     * 필요한 경우 일일 사용량을 초기화합니다.
+     */
+    private checkDailyReset;
+    /**
+     * Checks if the budget allows further requests.
+     * 예산이 추가 요청을 허용하는지 확인합니다.
+     *
+     * @returns True if within budget / 예산 내에 있으면 true
+     */
+    canSpend(): boolean;
+    /**
+     * Tracks token usage.
+     * 토큰 사용량을 추적합니다.
+     *
+     * @param tokens Number of tokens used / 사용된 토큰 수
+     */
+    track(tokens: number): void;
+    /**
+     * Gets current token usage.
+     * 현재 토큰 사용량을 가져옵니다.
+     *
+     * @returns Used tokens / 사용된 토큰 수
+     */
+    getUsage(): number;
+}

package/dist/budget.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Budget Management Module
+ * 예산 관리 모듈
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetManager = void 0;
+/**
+ * Budget Manager Class
+ * 예산 관리자 클래스
+ */
+class BudgetManager {
+    constructor(options) {
+        this.usedTokens = 0;
+        this.options = options;
+        this.lastReset = new Date();
+    }
+    /**
+     * Resets usage daily if necessary.
+     * 필요한 경우 일일 사용량을 초기화합니다.
+     */
+    checkDailyReset() {
+        const now = new Date();
+        if (now.getDate() !== this.lastReset.getDate()) {
+            this.usedTokens = 0;
+            this.lastReset = now;
+        }
+    }
+    /**
+     * Checks if the budget allows further requests.
+     * 예산이 추가 요청을 허용하는지 확인합니다.
+     *
+     * @returns True if within budget / 예산 내에 있으면 true
+     */
+    canSpend() {
+        this.checkDailyReset();
+        if (!this.options.maxTokenBudget)
+            return true;
+        return this.usedTokens < this.options.maxTokenBudget;
+    }
+    /**
+     * Tracks token usage.
+     * 토큰 사용량을 추적합니다.
+     *
+     * @param tokens Number of tokens used / 사용된 토큰 수
+     */
+    track(tokens) {
+        this.usedTokens += tokens;
+        if (this.options.maxTokenBudget && this.usedTokens >= this.options.maxTokenBudget) {
+            if (this.options.onBudgetExceeded) {
+                this.options.onBudgetExceeded(this.usedTokens, this.options.maxTokenBudget);
+            }
+        }
+    }
+    /**
+     * Gets current token usage.
+     * 현재 토큰 사용량을 가져옵니다.
+     *
+     * @returns Used tokens / 사용된 토큰 수
+     */
+    getUsage() {
+        return this.usedTokens;
+    }
+}
+exports.BudgetManager = BudgetManager;

package/dist/cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Caching Module
+ * 캐싱 모듈
+ */
+export interface CacheOptions {
+    enabled: boolean;
+    ttl?: number;
+}
+/**
+ * Response Cache Class
+ * 응답 캐시 클래스
+ */
+export declare class ResponseCache {
+    private cache;
+    private options;
+    constructor(options: CacheOptions);
+    /**
+     * Generates a key for the cache based on input messages.
+     * 입력 메시지를 기반으로 캐시 키를 생성합니다.
+     *
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @returns Cache key / 캐시 키
+     */
+    private generateKey;
+    /**
+     * Retrieves a cached response if available.
+     * 캐싱된 응답이 있는 경우 이를 반환합니다.
+     *
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @returns Cached data or null / 캐싱된 데이터 또는 null
+     */
+    get(messages: any[]): any | null;
+    /**
+     * Sets a value in the cache.
+     * 캐시에 값을 저장합니다.
+     *
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @param response The AI response / AI 응답
+     */
+    set(messages: any[], response: any): void;
+}

package/dist/cache.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseCache = void 0;
+const node_cache_1 = __importDefault(require("node-cache"));
+/**
+ * Response Cache Class
+ * 응답 캐시 클래스
+ */
+class ResponseCache {
+    constructor(options) {
+        this.options = {
+            enabled: options.enabled ?? true,
+            ttl: options.ttl ?? 3600,
+        };
+        this.cache = new node_cache_1.default({ stdTTL: this.options.ttl });
+    }
+    /**
+     * Generates a key for the cache based on input messages.
+     * 입력 메시지를 기반으로 캐시 키를 생성합니다.
+     *
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @returns Cache key / 캐시 키
+     */
+    generateKey(messages) {
+        return JSON.stringify(messages);
+    }
+    /**
+     * Retrieves a cached response if available.
+     * 캐싱된 응답이 있는 경우 이를 반환합니다.
+     *
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @returns Cached data or null / 캐싱된 데이터 또는 null
+     */
+    get(messages) {
+        if (!this.options.enabled)
+            return null;
+        const key = this.generateKey(messages);
+        return this.cache.get(key) || null;
+    }
+    /**
+     * Sets a value in the cache.
+     * 캐시에 값을 저장합니다.
+     *
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @param response The AI response / AI 응답
+     */
+    set(messages, response) {
+        if (!this.options.enabled)
+            return;
+        const key = this.generateKey(messages);
+        this.cache.set(key, response);
+    }
+}
+exports.ResponseCache = ResponseCache;

package/dist/compressor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prompt Compressor Module
+ * 프롬프트 압축 모듈
+ */
+export interface CompressorOptions {
+    enabled: boolean;
+    level?: 'light' | 'medium' | 'aggressive';
+}
+/**
+ * Prompt Compressor Class
+ * 프롬프트 압축 클래스
+ */
+export declare class PromptCompressor {
+    private options;
+    constructor(options: CompressorOptions);
+    /**
+     * Compresses the prompt text by removing redundancies.
+     * 중복을 제거하여 프롬프트 텍스트를 압축합니다.
+     *
+     * @param text The input text to compress / 압축할 입력 텍스트
+     * @returns Compressed text / 압축된 텍스트
+     */
+    compress(text: string): string;
+}

package/dist/compressor.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Prompt Compressor Module
+ * 프롬프트 압축 모듈
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptCompressor = void 0;
+/**
+ * Prompt Compressor Class
+ * 프롬프트 압축 클래스
+ */
+class PromptCompressor {
+    constructor(options) {
+        this.options = {
+            enabled: options.enabled ?? true,
+            level: options.level ?? 'light',
+        };
+    }
+    /**
+     * Compresses the prompt text by removing redundancies.
+     * 중복을 제거하여 프롬프트 텍스트를 압축합니다.
+     *
+     * @param text The input text to compress / 압축할 입력 텍스트
+     * @returns Compressed text / 압축된 텍스트
+     */
+    compress(text) {
+        if (!this.options.enabled)
+            return text;
+        let compressed = text;
+        // 1. Remove multiple spaces and newlines / 다중 공백 및 줄바꿈 제거
+        compressed = compressed.replace(/\s+/g, ' ').trim();
+        // 2. Medium level: Remove common filler words (English) / 중간 단계: 일반적인 채움말 제거 (영어)
+        if (this.options.level === 'medium' || this.options.level === 'aggressive') {
+            const fillerWords = ['actually', 'basically', 'honestly', 'literally', 'really', 'very'];
+            const fillerRegex = new RegExp(`\\b(${fillerWords.join('|')})\\b`, 'gi');
+            compressed = compressed.replace(fillerRegex, '');
+        }
+        // 3. Aggressive level: Remove common Korean filler words / 공격적 단계: 한국어 채움말 제거
+        if (this.options.level === 'aggressive') {
+            const koFillers = ['진짜', '정말', '사실', '기본적으로', '솔직히'];
+            const koFillerRegex = new RegExp(`(${koFillers.join('|')})`, 'g');
+            compressed = compressed.replace(koFillerRegex, '');
+        }
+        // Clean up extra spaces caused by replacement / 치환으로 발생한 추가 공백 정리
+        return compressed.replace(/\s+/g, ' ').trim();
+    }
+}
+exports.PromptCompressor = PromptCompressor;

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { MaskerOptions } from './masker';
+import { CompressorOptions } from './compressor';
+import { CacheOptions } from './cache';
+/**
+ * AICostGuard Options Interface
+ * AICostGuard 옵션 인터페이스
+ */
+export interface AICostGuardOptions {
+    maxTokenBudget?: number;
+    maskPII?: boolean | MaskerOptions;
+    compress?: boolean | CompressorOptions;
+    cache?: boolean | CacheOptions;
+    onBudgetExceeded?: (current: number, limit: number) => void;
+}
+/**
+ * Main AICostGuard Class
+ * 메인 AICostGuard 클래스
+ */
+export declare class AICostGuard {
+    private masker;
+    private compressor;
+    private cache;
+    private budget;
+    constructor(options?: AICostGuardOptions);
+    /**
+     * Proxies an OpenAI-like SDK instance to intercept calls.
+     * OpenAI 스타일의 SDK 인스턴스를 프록시하여 호출을 가로챕니다.
+     *
+     * @param sdk The SDK instance (e.g., OpenAI) / SDK 인스턴스 (예: OpenAI)
+     * @returns Proxied SDK / 프록시된 SDK
+     */
+    wrap<T extends any>(sdk: T): T;
+    /**
+     * Processes the completion request with optimization and security.
+     * 최적화 및 보안 처리를 거쳐 완성 요청을 수행합니다.
+     *
+     * @param originalFn The original create function / 기존 create 함수
+     * @param params Request parameters / 요청 파라미터
+     * @returns AI response / AI 응답
+     */
+    private processCompletion;
+}

package/dist/index.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AICostGuard = void 0;
+const masker_1 = require("./masker");
+const compressor_1 = require("./compressor");
+const cache_1 = require("./cache");
+const budget_1 = require("./budget");
+/**
+ * Main AICostGuard Class
+ * 메인 AICostGuard 클래스
+ */
+class AICostGuard {
+    constructor(options = {}) {
+        this.masker = new masker_1.PIIMasker(typeof options.maskPII === 'object' ? options.maskPII : { enabled: !!options.maskPII });
+        this.compressor = new compressor_1.PromptCompressor(typeof options.compress === 'object' ? options.compress : { enabled: !!options.compress });
+        this.cache = new cache_1.ResponseCache(typeof options.cache === 'object' ? options.cache : { enabled: options.cache !== false });
+        this.budget = new budget_1.BudgetManager({
+            maxTokenBudget: options.maxTokenBudget,
+            onBudgetExceeded: options.onBudgetExceeded,
+        });
+    }
+    /**
+     * Proxies an OpenAI-like SDK instance to intercept calls.
+     * OpenAI 스타일의 SDK 인스턴스를 프록시하여 호출을 가로챕니다.
+     *
+     * @param sdk The SDK instance (e.g., OpenAI) / SDK 인스턴스 (예: OpenAI)
+     * @returns Proxied SDK / 프록시된 SDK
+     */
+    wrap(sdk) {
+        const handler = {
+            get: (target, prop, receiver) => {
+                const value = Reflect.get(target, prop, receiver);
+                // Intercept chat.completions.create / chat.completions.create 호출 가로채기
+                if (prop === 'chat') {
+                    return new Proxy(value, {
+                        get: (chatTarget, chatProp) => {
+                            const chatValue = Reflect.get(chatTarget, chatProp);
+                            if (chatProp === 'completions') {
+                                return new Proxy(chatValue, {
+                                    get: (compTarget, compProp) => {
+                                        const compValue = Reflect.get(compTarget, compProp);
+                                        if (compProp === 'create') {
+                                            return async (params) => {
+                                                return this.processCompletion(compValue.bind(compTarget), params);
+                                            };
+                                        }
+                                        return compValue;
+                                    }
+                                });
+                            }
+                            return chatValue;
+                        }
+                    });
+                }
+                if (typeof value === 'function') {
+                    return value.bind(target);
+                }
+                return value;
+            }
+        };
+        return new Proxy(sdk, handler);
+    }
+    /**
+     * Processes the completion request with optimization and security.
+     * 최적화 및 보안 처리를 거쳐 완성 요청을 수행합니다.
+     *
+     * @param originalFn The original create function / 기존 create 함수
+     * @param params Request parameters / 요청 파라미터
+     * @returns AI response / AI 응답
+     */
+    async processCompletion(originalFn, params) {
+        // 1. Check budget / 예산 확인
+        if (!this.budget.canSpend()) {
+            throw new Error('COST_GUARD: Daily token budget exceeded. / 일일 토큰 예산을 초과했습니다.');
+        }
+        // 2. Pre-process messages (Masking & Compression) / 메시지 전처리 (마스킹 및 압축)
+        const originalMessages = params.messages;
+        const processedMessages = originalMessages.map((msg) => ({
+            ...msg,
+            content: typeof msg.content === 'string'
+                ? this.compressor.compress(this.masker.mask(msg.content))
+                : msg.content
+        }));
+        // 3. Check Cache / 캐시 확인
+        const cachedResponse = this.cache.get(processedMessages);
+        if (cachedResponse) {
+            return cachedResponse;
+        }
+        // 4. Execute API Call / API 호출 실행
+        const requestParams = { ...params, messages: processedMessages };
+        const response = await originalFn(requestParams);
+        // 5. Track Usage & Cache / 사용량 추적 및 캐싱
+        if (response.usage && response.usage.total_tokens) {
+            this.budget.track(response.usage.total_tokens);
+        }
+        this.cache.set(processedMessages, response);
+        return response;
+    }
+}
+exports.AICostGuard = AICostGuard;

package/dist/masker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PII Masking Module
+ * 개인정보 마스킹 모듈
+ */
+export interface MaskerOptions {
+    enabled: boolean;
+    maskString?: string;
+}
+/**
+ * PII Masker Class
+ * 개인정보 마스킹 클래스
+ */
+export declare class PIIMasker {
+    private patterns;
+    private options;
+    constructor(options: MaskerOptions);
+    /**
+     * Masks sensitive information in the given text.
+     * 주어진 텍스트 내의 민감 정보를 마스킹 처리합니다.
+     *
+     * @param text The input text to mask / 마스킹할 입력 텍스트
+     * @returns Masked text / 마스킹된 텍스트
+     */
+    mask(text: string): string;
+}

package/dist/masker.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * PII Masking Module
+ * 개인정보 마스킹 모듈
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIIMasker = void 0;
+/**
+ * PII Masker Class
+ * 개인정보 마스킹 클래스
+ */
+class PIIMasker {
+    constructor(options) {
+        this.patterns = {
+            // Email / 이메일
+            email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+            // Phone Number (Korean & International) / 전화번호 (한국식 및 국제 규격)
+            phone: /(\d{2,3}[-\s]?\d{3,4}[-\s]?\d{4})|(\+?\d{1,3}[-\s]?\d{1,4}[-\s]?\d{4,10})/g,
+            // Identification Numbers (e.g., SSN, RRN) / 주민등록번호 등 식별 번호
+            idNumber: /\d{6}-\d{7}/g,
+            // Credit Card Numbers / 신용카드 번호
+            creditCard: /\d{4}-\d{4}-\d{4}-\d{4}/g,
+        };
+        this.options = {
+            enabled: options.enabled ?? true,
+            maskString: options.maskString ?? '[MASKED]',
+        };
+    }
+    /**
+     * Masks sensitive information in the given text.
+     * 주어진 텍스트 내의 민감 정보를 마스킹 처리합니다.
+     *
+     * @param text The input text to mask / 마스킹할 입력 텍스트
+     * @returns Masked text / 마스킹된 텍스트
+     */
+    mask(text) {
+        if (!this.options.enabled)
+            return text;
+        let maskedText = text;
+        const maskStr = this.options.maskString || '[MASKED]';
+        for (const pattern of Object.values(this.patterns)) {
+            maskedText = maskedText.replace(pattern, maskStr);
+        }
+        return maskedText;
+    }
+}
+exports.PIIMasker = PIIMasker;

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/tests/**/*.test.ts'],
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cost_guard_ai",
+  "version": "1.0.0",
+  "description": "Intelligent Prompt Compression and Security Middleware for LLMs / LLM을 위한 지능형 프롬프트 압축 및 보안 미들웨어",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "cost-optimization",
+    "security",
+    "pii-masking",
+    "prompt-compression"
+  ],
+  "author": "Rheehose (Rhee Creative)",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.24",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3",
+    "openai": "^4.28.1"
+  },
+  "dependencies": {
+    "node-cache": "^5.1.2"
+  }
+}

package/src/budget.ts

@@ -0,0 +1,73 @@
+/**
+ * Budget Management Module
+ * 예산 관리 모듈
+ */
+
+export interface BudgetOptions {
+    maxTokenBudget?: number; // Daily token budget / 일일 토큰 예산
+    onBudgetExceeded?: (current: number, limit: number) => void; // Callback when budget exceeded / 예산 초과 시 콜백
+}
+
+/**
+ * Budget Manager Class
+ * 예산 관리자 클래스
+ */
+export class BudgetManager {
+    private usedTokens: number = 0;
+    private options: BudgetOptions;
+    private lastReset: Date;
+
+    constructor(options: BudgetOptions) {
+        this.options = options;
+        this.lastReset = new Date();
+    }
+
+    /**
+     * Resets usage daily if necessary.
+     * 필요한 경우 일일 사용량을 초기화합니다.
+     */
+    private checkDailyReset(): void {
+        const now = new Date();
+        if (now.getDate() !== this.lastReset.getDate()) {
+            this.usedTokens = 0;
+            this.lastReset = now;
+        }
+    }
+
+    /**
+     * Checks if the budget allows further requests.
+     * 예산이 추가 요청을 허용하는지 확인합니다.
+     * 
+     * @returns True if within budget / 예산 내에 있으면 true
+     */
+    public canSpend(): boolean {
+        this.checkDailyReset();
+        if (!this.options.maxTokenBudget) return true;
+        return this.usedTokens < this.options.maxTokenBudget;
+    }
+
+    /**
+     * Tracks token usage.
+     * 토큰 사용량을 추적합니다.
+     * 
+     * @param tokens Number of tokens used / 사용된 토큰 수
+     */
+    public track(tokens: number): void {
+        this.usedTokens += tokens;
+        if (this.options.maxTokenBudget && this.usedTokens >= this.options.maxTokenBudget) {
+            if (this.options.onBudgetExceeded) {
+                this.options.onBudgetExceeded(this.usedTokens, this.options.maxTokenBudget);
+            }
+        }
+    }
+
+    /**
+     * Gets current token usage.
+     * 현재 토큰 사용량을 가져옵니다.
+     * 
+     * @returns Used tokens / 사용된 토큰 수
+     */
+    public getUsage(): number {
+        return this.usedTokens;
+    }
+}

package/src/cache.ts

@@ -0,0 +1,65 @@
+import NodeCache from 'node-cache';
+
+/**
+ * Caching Module
+ * 캐싱 모듈
+ */
+
+export interface CacheOptions {
+    enabled: boolean;
+    ttl?: number; // Time to live in seconds / 유지 시간(초)
+}
+
+/**
+ * Response Cache Class
+ * 응답 캐시 클래스
+ */
+export class ResponseCache {
+    private cache: NodeCache;
+    private options: CacheOptions;
+
+    constructor(options: CacheOptions) {
+        this.options = {
+            enabled: options.enabled ?? true,
+            ttl: options.ttl ?? 3600,
+        };
+        this.cache = new NodeCache({ stdTTL: this.options.ttl });
+    }
+
+    /**
+     * Generates a key for the cache based on input messages.
+     * 입력 메시지를 기반으로 캐시 키를 생성합니다.
+     * 
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @returns Cache key / 캐시 키
+     */
+    private generateKey(messages: any[]): string {
+        return JSON.stringify(messages);
+    }
+
+    /**
+     * Retrieves a cached response if available.
+     * 캐싱된 응답이 있는 경우 이를 반환합니다.
+     * 
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @returns Cached data or null / 캐싱된 데이터 또는 null
+     */
+    public get(messages: any[]): any | null {
+        if (!this.options.enabled) return null;
+        const key = this.generateKey(messages);
+        return this.cache.get(key) || null;
+    }
+
+    /**
+     * Sets a value in the cache.
+     * 캐시에 값을 저장합니다.
+     * 
+     * @param messages The prompt messages / 프롬프트 메시지
+     * @param response The AI response / AI 응답
+     */
+    public set(messages: any[], response: any): void {
+        if (!this.options.enabled) return;
+        const key = this.generateKey(messages);
+        this.cache.set(key, response);
+    }
+}

package/src/compressor.ts

@@ -0,0 +1,57 @@
+/**
+ * Prompt Compressor Module
+ * 프롬프트 압축 모듈
+ */
+
+export interface CompressorOptions {
+    enabled: boolean;
+    level?: 'light' | 'medium' | 'aggressive';
+}
+
+/**
+ * Prompt Compressor Class
+ * 프롬프트 압축 클래스
+ */
+export class PromptCompressor {
+    private options: CompressorOptions;
+
+    constructor(options: CompressorOptions) {
+        this.options = {
+            enabled: options.enabled ?? true,
+            level: options.level ?? 'light',
+        };
+    }
+
+    /**
+     * Compresses the prompt text by removing redundancies.
+     * 중복을 제거하여 프롬프트 텍스트를 압축합니다.
+     * 
+     * @param text The input text to compress / 압축할 입력 텍스트
+     * @returns Compressed text / 압축된 텍스트
+     */
+    public compress(text: string): string {
+        if (!this.options.enabled) return text;
+
+        let compressed = text;
+
+        // 1. Remove multiple spaces and newlines / 다중 공백 및 줄바꿈 제거
+        compressed = compressed.replace(/\s+/g, ' ').trim();
+
+        // 2. Medium level: Remove common filler words (English) / 중간 단계: 일반적인 채움말 제거 (영어)
+        if (this.options.level === 'medium' || this.options.level === 'aggressive') {
+            const fillerWords = ['actually', 'basically', 'honestly', 'literally', 'really', 'very'];
+            const fillerRegex = new RegExp(`\\b(${fillerWords.join('|')})\\b`, 'gi');
+            compressed = compressed.replace(fillerRegex, '');
+        }
+
+        // 3. Aggressive level: Remove common Korean filler words / 공격적 단계: 한국어 채움말 제거
+        if (this.options.level === 'aggressive') {
+            const koFillers = ['진짜', '정말', '사실', '기본적으로', '솔직히'];
+            const koFillerRegex = new RegExp(`(${koFillers.join('|')})`, 'g');
+            compressed = compressed.replace(koFillerRegex, '');
+        }
+
+        // Clean up extra spaces caused by replacement / 치환으로 발생한 추가 공백 정리
+        return compressed.replace(/\s+/g, ' ').trim();
+    }
+}

package/src/index.ts

@@ -0,0 +1,130 @@
+import { PIIMasker, MaskerOptions } from './masker';
+import { PromptCompressor, CompressorOptions } from './compressor';
+import { ResponseCache, CacheOptions } from './cache';
+import { BudgetManager, BudgetOptions } from './budget';
+
+/**
+ * AICostGuard Options Interface
+ * AICostGuard 옵션 인터페이스
+ */
+export interface AICostGuardOptions {
+    maxTokenBudget?: number;
+    maskPII?: boolean | MaskerOptions;
+    compress?: boolean | CompressorOptions;
+    cache?: boolean | CacheOptions;
+    onBudgetExceeded?: (current: number, limit: number) => void;
+}
+
+/**
+ * Main AICostGuard Class
+ * 메인 AICostGuard 클래스
+ */
+export class AICostGuard {
+    private masker: PIIMasker;
+    private compressor: PromptCompressor;
+    private cache: ResponseCache;
+    private budget: BudgetManager;
+
+    constructor(options: AICostGuardOptions = {}) {
+        this.masker = new PIIMasker(
+            typeof options.maskPII === 'object' ? options.maskPII : { enabled: !!options.maskPII }
+        );
+        this.compressor = new PromptCompressor(
+            typeof options.compress === 'object' ? options.compress : { enabled: !!options.compress }
+        );
+        this.cache = new ResponseCache(
+            typeof options.cache === 'object' ? options.cache : { enabled: options.cache !== false }
+        );
+        this.budget = new BudgetManager({
+            maxTokenBudget: options.maxTokenBudget,
+            onBudgetExceeded: options.onBudgetExceeded,
+        });
+    }
+
+    /**
+     * Proxies an OpenAI-like SDK instance to intercept calls.
+     * OpenAI 스타일의 SDK 인스턴스를 프록시하여 호출을 가로챕니다.
+     * 
+     * @param sdk The SDK instance (e.g., OpenAI) / SDK 인스턴스 (예: OpenAI)
+     * @returns Proxied SDK / 프록시된 SDK
+     */
+    public wrap<T extends any>(sdk: T): T {
+        const handler: ProxyHandler<any> = {
+            get: (target, prop, receiver) => {
+                const value = Reflect.get(target, prop, receiver);
+
+                // Intercept chat.completions.create / chat.completions.create 호출 가로채기
+                if (prop === 'chat') {
+                    return new Proxy(value, {
+                        get: (chatTarget, chatProp) => {
+                            const chatValue = Reflect.get(chatTarget, chatProp);
+                            if (chatProp === 'completions') {
+                                return new Proxy(chatValue, {
+                                    get: (compTarget, compProp) => {
+                                        const compValue = Reflect.get(compTarget, compProp);
+                                        if (compProp === 'create') {
+                                            return async (params: any) => {
+                                                return this.processCompletion(compValue.bind(compTarget), params);
+                                            };
+                                        }
+                                        return compValue;
+                                    }
+                                });
+                            }
+                            return chatValue;
+                        }
+                    });
+                }
+
+                if (typeof value === 'function') {
+                    return value.bind(target);
+                }
+                return value;
+            }
+        };
+
+        return new Proxy(sdk, handler);
+    }
+
+    /**
+     * Processes the completion request with optimization and security.
+     * 최적화 및 보안 처리를 거쳐 완성 요청을 수행합니다.
+     * 
+     * @param originalFn The original create function / 기존 create 함수
+     * @param params Request parameters / 요청 파라미터
+     * @returns AI response / AI 응답
+     */
+    private async processCompletion(originalFn: Function, params: any): Promise<any> {
+        // 1. Check budget / 예산 확인
+        if (!this.budget.canSpend()) {
+            throw new Error('COST_GUARD: Daily token budget exceeded. / 일일 토큰 예산을 초과했습니다.');
+        }
+
+        // 2. Pre-process messages (Masking & Compression) / 메시지 전처리 (마스킹 및 압축)
+        const originalMessages = params.messages;
+        const processedMessages = originalMessages.map((msg: any) => ({
+            ...msg,
+            content: typeof msg.content === 'string'
+                ? this.compressor.compress(this.masker.mask(msg.content))
+                : msg.content
+        }));
+
+        // 3. Check Cache / 캐시 확인
+        const cachedResponse = this.cache.get(processedMessages);
+        if (cachedResponse) {
+            return cachedResponse;
+        }
+
+        // 4. Execute API Call / API 호출 실행
+        const requestParams = { ...params, messages: processedMessages };
+        const response = await originalFn(requestParams);
+
+        // 5. Track Usage & Cache / 사용량 추적 및 캐싱
+        if (response.usage && response.usage.total_tokens) {
+            this.budget.track(response.usage.total_tokens);
+        }
+        this.cache.set(processedMessages, response);
+
+        return response;
+    }
+}

package/src/masker.ts

@@ -0,0 +1,55 @@
+/**
+ * PII Masking Module
+ * 개인정보 마스킹 모듈
+ */
+
+export interface MaskerOptions {
+    enabled: boolean;
+    maskString?: string;
+}
+
+/**
+ * PII Masker Class
+ * 개인정보 마스킹 클래스
+ */
+export class PIIMasker {
+    private patterns: Record<string, RegExp> = {
+        // Email / 이메일
+        email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+        // Phone Number (Korean & International) / 전화번호 (한국식 및 국제 규격)
+        phone: /(\d{2,3}[-\s]?\d{3,4}[-\s]?\d{4})|(\+?\d{1,3}[-\s]?\d{1,4}[-\s]?\d{4,10})/g,
+        // Identification Numbers (e.g., SSN, RRN) / 주민등록번호 등 식별 번호
+        idNumber: /\d{6}-\d{7}/g,
+        // Credit Card Numbers / 신용카드 번호
+        creditCard: /\d{4}-\d{4}-\d{4}-\d{4}/g,
+    };
+
+    private options: MaskerOptions;
+
+    constructor(options: MaskerOptions) {
+        this.options = {
+            enabled: options.enabled ?? true,
+            maskString: options.maskString ?? '[MASKED]',
+        };
+    }
+
+    /**
+     * Masks sensitive information in the given text.
+     * 주어진 텍스트 내의 민감 정보를 마스킹 처리합니다.
+     * 
+     * @param text The input text to mask / 마스킹할 입력 텍스트
+     * @returns Masked text / 마스킹된 텍스트
+     */
+    public mask(text: string): string {
+        if (!this.options.enabled) return text;
+
+        let maskedText = text;
+        const maskStr = this.options.maskString || '[MASKED]';
+
+        for (const pattern of Object.values(this.patterns)) {
+            maskedText = maskedText.replace(pattern, maskStr);
+        }
+
+        return maskedText;
+    }
+}

package/tests/guard.test.ts

@@ -0,0 +1,95 @@
+import { AICostGuard } from '../src/index';
+
+/**
+ * Basic Test for AICostGuard
+ * AICostGuard 기본 테스트
+ */
+describe('AICostGuard', () => {
+    let guard: AICostGuard;
+
+    beforeEach(() => {
+        guard = new AICostGuard({
+            maskPII: true,
+            compress: true,
+            maxTokenBudget: 1000
+        });
+    });
+
+    test('should mask PII in messages', async () => {
+        const mockOpenAI = {
+            chat: {
+                completions: {
+                    create: jest.fn().mockResolvedValue({
+                        choices: [{ message: { content: 'Hello' } }],
+                        usage: { total_tokens: 10 }
+                    })
+                }
+            }
+        };
+
+        const wrapped = guard.wrap(mockOpenAI);
+        await wrapped.chat.completions.create({
+            model: 'gpt-4',
+            messages: [{ role: 'user', content: 'My email is test@example.com and phone is 010-1234-5678' }]
+        });
+
+        const callArgs = mockOpenAI.chat.completions.create.mock.calls[0][0];
+        const content = callArgs.messages[0].content;
+
+        // Check if email and phone are masked / 이메일과 전화번호가 마스킹되었는지 확인
+        expect(content).toContain('[MASKED]');
+        expect(content).not.toContain('test@example.com');
+        expect(content).not.toContain('010-1234-5678');
+    });
+
+    test('should compress whitespace in messages', async () => {
+        const mockOpenAI = {
+            chat: {
+                completions: {
+                    create: jest.fn().mockResolvedValue({
+                        choices: [{ message: { content: 'Hello' } }],
+                        usage: { total_tokens: 10 }
+                    })
+                }
+            }
+        };
+
+        const wrapped = guard.wrap(mockOpenAI);
+        await wrapped.chat.completions.create({
+            model: 'gpt-4',
+            messages: [{ role: 'user', content: 'Hello    world  \n  with   spaces' }]
+        });
+
+        const callArgs = mockOpenAI.chat.completions.create.mock.calls[0][0];
+        const content = callArgs.messages[0].content;
+
+        // Check if extra spaces are removed / 여분의 공백이 제거되었는지 확인
+        expect(content).toBe('Hello world with spaces');
+    });
+
+    test('should block requests when budget is exceeded', async () => {
+        const smallGuard = new AICostGuard({ maxTokenBudget: 5 });
+        const mockOpenAI = {
+            chat: {
+                completions: {
+                    create: jest.fn().mockResolvedValue({
+                        choices: [{ message: { content: 'Hello' } }],
+                        usage: { total_tokens: 10 }
+                    })
+                }
+            }
+        };
+
+        const wrapped = smallGuard.wrap(mockOpenAI);
+
+        // First call should succeed / 첫 번째 호출은 성공해야 함
+        await wrapped.chat.completions.create({
+            messages: [{ role: 'user', content: 'Hi' }]
+        });
+
+        // Second call should fail as usage (10) > budget (5) / 사용량(10)이 예산(5)을 초과하므로 두 번째 호출은 실패해야 함
+        await expect(wrapped.chat.completions.create({
+            messages: [{ role: 'user', content: 'Hi' }]
+        })).rejects.toThrow('COST_GUARD: Daily token budget exceeded.');
+    });
+});

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "CommonJS",
+        "lib": [
+            "ES2020",
+            "DOM"
+        ],
+        "declaration": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "**/*.test.ts"
+    ]
+}