@rheonic/sdk 0.1.0-beta.1

package/dist/providers/anthropicAdapter.js

@@ -0,0 +1,189 @@
+import { buildEvent } from "../eventBuilder.js";
+import { RHEONICBlockedError } from "../protectEngine.js";
+import { validateProviderModel } from "../providerModelValidation.js";
+import { estimateInputTokensFromRequest } from "../tokenEstimator.js";
+let estimatorOverrideForTests = null;
+export function __setInputTokenEstimatorForTests(estimator) {
+    estimatorOverrideForTests = estimator;
+}
+export function instrumentAnthropic(anthropicClient, options) {
+    const targetCreate = anthropicClient?.messages?.create;
+    if (typeof targetCreate !== "function") {
+        return anthropicClient;
+    }
+    const originalCreate = targetCreate.bind(anthropicClient.messages);
+    anthropicClient.messages.create = async (...args) => {
+        const startedAt = Date.now();
+        const requestPayload = extractRequestPayload(args);
+        const requestedModel = extractRequestedModel(args);
+        validateProviderModel("anthropic", requestedModel);
+        let estimatedInputTokens = null;
+        const tokenEstimateStartedAt = Date.now();
+        estimatedInputTokens = requestPayload
+            ? (estimatorOverrideForTests
+                ? estimatorOverrideForTests(requestPayload)
+                : estimateInputTokensFromRequest(requestPayload))
+            : null;
+        options.client.debugLog("Protect token estimation completed", {
+            provider: "anthropic",
+            model: requestedModel,
+            latency_ms: Date.now() - tokenEstimateStartedAt,
+            estimated_input_tokens: estimatedInputTokens ?? undefined,
+        });
+        const protectPayload = {
+            provider: "anthropic",
+            model: requestedModel,
+            environment: options.environment ?? options.client.environment,
+            feature: options.feature,
+            max_output_tokens: extractMaxOutputTokens(args),
+        };
+        if (typeof estimatedInputTokens === "number") {
+            protectPayload.input_tokens_estimate = estimatedInputTokens;
+        }
+        const protectDecision = await options.client.evaluateProtectDecision(protectPayload);
+        if (protectDecision.decision === "block") {
+            throw new RHEONICBlockedError(protectDecision.reason);
+        }
+        const callArgs = maybeApplyAnthropicClamp(args, protectDecision);
+        markClampAppliedIfChanged(protectDecision, extractMaxOutputTokens(args), extractMaxOutputTokens(callArgs));
+        try {
+            const response = await originalCreate(...callArgs);
+            void options.client.captureEvent(buildEvent({
+                provider: "anthropic",
+                model: extractResponseModel(response) ?? requestedModel,
+                environment: options.environment ?? options.client.environment,
+                request: {
+                    endpoint: options.endpoint,
+                    feature: options.feature,
+                    input_tokens_estimate: typeof estimatedInputTokens === "number" ? estimatedInputTokens : undefined,
+                    protect_decision: protectDecision.decision === "warn" ? "warn" : undefined,
+                    protect_reason: protectDecision.decision === "warn" ? protectDecision.reason : undefined,
+                },
+                response: {
+                    latency_ms: Date.now() - startedAt,
+                    total_tokens: extractTotalTokens(response),
+                    http_status: 200,
+                },
+            }));
+            return response;
+        }
+        catch (error) {
+            void options.client.captureEvent(buildEvent({
+                provider: "anthropic",
+                model: requestedModel,
+                environment: options.environment ?? options.client.environment,
+                request: {
+                    endpoint: options.endpoint,
+                    feature: options.feature,
+                    input_tokens_estimate: typeof estimatedInputTokens === "number" ? estimatedInputTokens : undefined,
+                    protect_decision: protectDecision.decision === "warn" ? "warn" : undefined,
+                    protect_reason: protectDecision.decision === "warn" ? protectDecision.reason : undefined,
+                },
+                response: {
+                    latency_ms: Date.now() - startedAt,
+                    error_type: extractErrorType(error),
+                    http_status: extractHttpStatus(error),
+                },
+            }));
+            throw error;
+        }
+    };
+    return anthropicClient;
+}
+function extractRequestPayload(args) {
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object") {
+        return null;
+    }
+    return firstArg;
+}
+function extractRequestedModel(args) {
+    const payload = extractRequestPayload(args);
+    const model = payload?.model;
+    return typeof model === "string" ? model : null;
+}
+function extractMaxOutputTokens(args) {
+    const payload = extractRequestPayload(args);
+    const maxTokens = payload?.max_tokens;
+    return typeof maxTokens === "number" ? maxTokens : undefined;
+}
+function extractResponseModel(response) {
+    if (response && typeof response === "object" && "model" in response) {
+        const model = response.model;
+        return typeof model === "string" ? model : null;
+    }
+    return null;
+}
+function extractTotalTokens(response) {
+    if (!response || typeof response !== "object") {
+        return undefined;
+    }
+    const usage = response.usage;
+    if (typeof usage?.total_tokens === "number") {
+        return usage.total_tokens;
+    }
+    const input = typeof usage?.input_tokens === "number" ? usage.input_tokens : 0;
+    const output = typeof usage?.output_tokens === "number" ? usage.output_tokens : 0;
+    const total = input + output;
+    return total > 0 ? total : undefined;
+}
+function extractErrorType(error) {
+    if (error && typeof error === "object" && "name" in error) {
+        const name = error.name;
+        if (typeof name === "string" && name.length > 0) {
+            return name;
+        }
+    }
+    return "unknown";
+}
+function extractHttpStatus(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const withStatus = error;
+    if (typeof withStatus.status === "number") {
+        return withStatus.status;
+    }
+    if (typeof withStatus.statusCode === "number") {
+        return withStatus.statusCode;
+    }
+    if (typeof withStatus.response?.status === "number") {
+        return withStatus.response.status;
+    }
+    return undefined;
+}
+function maybeApplyAnthropicClamp(args, decision) {
+    if (decision.decision !== "warn" || decision.reason !== "near_cap") {
+        return args;
+    }
+    if (!decision.applyClampEnabled) {
+        return args;
+    }
+    const recommended = decision.clamp?.recommended_max_output_tokens;
+    if (typeof recommended !== "number" || recommended < 1) {
+        return args;
+    }
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object") {
+        return args;
+    }
+    const payload = { ...firstArg };
+    const maxTokens = payload.max_tokens;
+    if (typeof maxTokens === "number") {
+        payload.max_tokens = Math.min(maxTokens, recommended);
+    }
+    else {
+        payload.max_tokens = recommended;
+    }
+    const nextArgs = [...args];
+    nextArgs[0] = payload;
+    return nextArgs;
+}
+function markClampAppliedIfChanged(decision, originalMaxTokens, appliedMaxTokens) {
+    if (!decision.clamp || typeof appliedMaxTokens !== "number") {
+        return;
+    }
+    if (typeof originalMaxTokens !== "number" || appliedMaxTokens < originalMaxTokens) {
+        decision.clamp.applied = true;
+    }
+}

package/dist/providers/googleAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "../client.js";
+export interface GoogleInstrumentationOptions {
+    client: Client;
+    environment?: string;
+    endpoint?: string;
+    feature?: string;
+}
+export declare function __setInputTokenEstimatorForTests(estimator: ((payload: unknown) => number | null) | null): void;
+export declare function instrumentGoogle<T extends Record<string, any>>(googleModel: T, options: GoogleInstrumentationOptions): T;

package/dist/providers/googleAdapter.js

@@ -0,0 +1,212 @@
+import { buildEvent } from "../eventBuilder.js";
+import { RHEONICBlockedError } from "../protectEngine.js";
+import { validateProviderModel } from "../providerModelValidation.js";
+import { estimateInputTokensFromRequest } from "../tokenEstimator.js";
+let estimatorOverrideForTests = null;
+export function __setInputTokenEstimatorForTests(estimator) {
+    estimatorOverrideForTests = estimator;
+}
+export function instrumentGoogle(googleModel, options) {
+    const targetGenerate = googleModel?.generateContent;
+    if (typeof targetGenerate !== "function") {
+        return googleModel;
+    }
+    const originalGenerate = targetGenerate.bind(googleModel);
+    googleModel.generateContent = async (...args) => {
+        const startedAt = Date.now();
+        const requestedModel = extractRequestedModel(googleModel);
+        validateProviderModel("google", requestedModel);
+        const requestPayload = extractRequestPayload(args, requestedModel);
+        let estimatedInputTokens = null;
+        const tokenEstimateStartedAt = Date.now();
+        estimatedInputTokens = requestPayload
+            ? (estimatorOverrideForTests
+                ? estimatorOverrideForTests(requestPayload)
+                : estimateInputTokensFromRequest(requestPayload))
+            : null;
+        options.client.debugLog("Protect token estimation completed", {
+            provider: "google",
+            model: requestedModel,
+            latency_ms: Date.now() - tokenEstimateStartedAt,
+            estimated_input_tokens: estimatedInputTokens ?? undefined,
+        });
+        const protectPayload = {
+            provider: "google",
+            model: requestedModel,
+            environment: options.environment ?? options.client.environment,
+            feature: options.feature,
+            max_output_tokens: extractMaxOutputTokens(args),
+        };
+        if (typeof estimatedInputTokens === "number") {
+            protectPayload.input_tokens_estimate = estimatedInputTokens;
+        }
+        const protectDecision = await options.client.evaluateProtectDecision(protectPayload);
+        if (protectDecision.decision === "block") {
+            throw new RHEONICBlockedError(protectDecision.reason);
+        }
+        const callArgs = maybeApplyGoogleClamp(args, protectDecision);
+        markClampAppliedIfChanged(protectDecision, extractMaxOutputTokens(args), extractMaxOutputTokens(callArgs));
+        try {
+            const response = await originalGenerate(...callArgs);
+            void options.client.captureEvent(buildEvent({
+                provider: "google",
+                model: requestedModel,
+                environment: options.environment ?? options.client.environment,
+                request: {
+                    endpoint: options.endpoint,
+                    feature: options.feature,
+                    input_tokens_estimate: typeof estimatedInputTokens === "number" ? estimatedInputTokens : undefined,
+                    protect_decision: protectDecision.decision === "warn" ? "warn" : undefined,
+                    protect_reason: protectDecision.decision === "warn" ? protectDecision.reason : undefined,
+                },
+                response: {
+                    latency_ms: Date.now() - startedAt,
+                    total_tokens: extractTotalTokens(response),
+                    http_status: 200,
+                },
+            }));
+            return response;
+        }
+        catch (error) {
+            void options.client.captureEvent(buildEvent({
+                provider: "google",
+                model: requestedModel,
+                environment: options.environment ?? options.client.environment,
+                request: {
+                    endpoint: options.endpoint,
+                    feature: options.feature,
+                    input_tokens_estimate: typeof estimatedInputTokens === "number" ? estimatedInputTokens : undefined,
+                    protect_decision: protectDecision.decision === "warn" ? "warn" : undefined,
+                    protect_reason: protectDecision.decision === "warn" ? protectDecision.reason : undefined,
+                },
+                response: {
+                    latency_ms: Date.now() - startedAt,
+                    error_type: extractErrorType(error),
+                    http_status: extractHttpStatus(error),
+                },
+            }));
+            throw error;
+        }
+    };
+    return googleModel;
+}
+function extractRequestPayload(args, model) {
+    const firstArg = args[0];
+    if (typeof firstArg === "string") {
+        return { model, prompt: firstArg };
+    }
+    if (firstArg && typeof firstArg === "object") {
+        return firstArg;
+    }
+    return null;
+}
+function extractRequestedModel(googleModel) {
+    if (!googleModel || typeof googleModel !== "object") {
+        return null;
+    }
+    const withModel = googleModel;
+    if (typeof withModel.model === "string") {
+        return withModel.model;
+    }
+    if (typeof withModel.modelName === "string") {
+        return withModel.modelName;
+    }
+    return null;
+}
+function extractMaxOutputTokens(args) {
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object") {
+        return undefined;
+    }
+    const payload = firstArg;
+    const maxOutput = payload.generationConfig?.maxOutputTokens;
+    return typeof maxOutput === "number" ? maxOutput : undefined;
+}
+function extractTotalTokens(response) {
+    if (!response || typeof response !== "object") {
+        return undefined;
+    }
+    const usageMetadata = response.response?.usageMetadata
+        ?? response.usageMetadata;
+    if (!usageMetadata || typeof usageMetadata !== "object") {
+        return undefined;
+    }
+    const usage = usageMetadata;
+    if (typeof usage.totalTokenCount === "number") {
+        return usage.totalTokenCount;
+    }
+    const prompt = typeof usage.promptTokenCount === "number" ? usage.promptTokenCount : 0;
+    const candidates = typeof usage.candidatesTokenCount === "number" ? usage.candidatesTokenCount : 0;
+    const total = prompt + candidates;
+    return total > 0 ? total : undefined;
+}
+function extractErrorType(error) {
+    if (error && typeof error === "object" && "name" in error) {
+        const name = error.name;
+        if (typeof name === "string" && name.length > 0) {
+            return name;
+        }
+    }
+    return "unknown";
+}
+function extractHttpStatus(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const withStatus = error;
+    if (typeof withStatus.status === "number") {
+        return withStatus.status;
+    }
+    if (typeof withStatus.statusCode === "number") {
+        return withStatus.statusCode;
+    }
+    if (typeof withStatus.response?.status === "number") {
+        return withStatus.response.status;
+    }
+    return undefined;
+}
+function maybeApplyGoogleClamp(args, decision) {
+    if (decision.decision !== "warn" || decision.reason !== "near_cap") {
+        return args;
+    }
+    if (!decision.applyClampEnabled) {
+        return args;
+    }
+    const recommended = decision.clamp?.recommended_max_output_tokens;
+    if (typeof recommended !== "number" || recommended < 1) {
+        return args;
+    }
+    const nextArgs = [...args];
+    const firstArg = nextArgs[0];
+    if (firstArg && typeof firstArg === "object") {
+        const payload = { ...firstArg };
+        const existingConfig = payload.generationConfig && typeof payload.generationConfig === "object"
+            ? payload.generationConfig
+            : {};
+        const existingMax = existingConfig.maxOutputTokens;
+        payload.generationConfig = {
+            ...existingConfig,
+            maxOutputTokens: typeof existingMax === "number" ? Math.min(existingMax, recommended) : recommended,
+        };
+        nextArgs[0] = payload;
+        return nextArgs;
+    }
+    const secondArg = nextArgs[1];
+    const existingConfig = secondArg && typeof secondArg === "object" ? { ...secondArg } : {};
+    const generationConfig = existingConfig.generationConfig && typeof existingConfig.generationConfig === "object"
+        ? { ...existingConfig.generationConfig }
+        : {};
+    const existingMax = generationConfig.maxOutputTokens;
+    generationConfig.maxOutputTokens = typeof existingMax === "number" ? Math.min(existingMax, recommended) : recommended;
+    existingConfig.generationConfig = generationConfig;
+    nextArgs[1] = existingConfig;
+    return nextArgs;
+}
+function markClampAppliedIfChanged(decision, originalMaxTokens, appliedMaxTokens) {
+    if (!decision.clamp || typeof appliedMaxTokens !== "number") {
+        return;
+    }
+    if (typeof originalMaxTokens !== "number" || appliedMaxTokens < originalMaxTokens) {
+        decision.clamp.applied = true;
+    }
+}

package/dist/providers/openaiAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "../client.js";
+export interface OpenAIInstrumentationOptions {
+    client: Client;
+    environment?: string;
+    endpoint?: string;
+    feature?: string;
+}
+export declare function __setInputTokenEstimatorForTests(estimator: ((payload: unknown) => number | null) | null): void;
+export declare function instrumentOpenAI<T extends Record<string, any>>(openaiClient: T, options: OpenAIInstrumentationOptions): T;

package/dist/providers/openaiAdapter.js

@@ -0,0 +1,203 @@
+import { buildEvent } from "../eventBuilder.js";
+import { RHEONICBlockedError } from "../protectEngine.js";
+import { validateProviderModel } from "../providerModelValidation.js";
+import { estimateInputTokensFromRequest } from "../tokenEstimator.js";
+let estimatorOverrideForTests = null;
+export function __setInputTokenEstimatorForTests(estimator) {
+    estimatorOverrideForTests = estimator;
+}
+export function instrumentOpenAI(openaiClient, options) {
+    const targetCreate = openaiClient?.chat?.completions?.create;
+    if (typeof targetCreate !== "function") {
+        return openaiClient;
+    }
+    const originalCreate = targetCreate.bind(openaiClient.chat.completions);
+    openaiClient.chat.completions.create = async (...args) => {
+        const startedAt = Date.now();
+        const model = extractRequestedModel(args);
+        validateProviderModel("openai", model);
+        const requestPayload = extractRequestPayload(args);
+        const tokenEstimateStartedAt = Date.now();
+        const estimatedInputTokens = requestPayload
+            ? (estimatorOverrideForTests
+                ? estimatorOverrideForTests(requestPayload)
+                : estimateInputTokensFromRequest(requestPayload))
+            : null;
+        options.client.debugLog("Protect token estimation completed", {
+            provider: "openai",
+            model,
+            latency_ms: Date.now() - tokenEstimateStartedAt,
+            estimated_input_tokens: estimatedInputTokens ?? undefined,
+        });
+        const protectPayload = {
+            provider: "openai",
+            model,
+            environment: options.environment ?? options.client.environment,
+            feature: options.feature,
+            max_output_tokens: extractMaxOutputTokens(args),
+        };
+        if (typeof estimatedInputTokens === "number") {
+            protectPayload.input_tokens_estimate = estimatedInputTokens;
+        }
+        const protectDecision = await options.client.evaluateProtectDecision({
+            ...protectPayload,
+        });
+        if (protectDecision.decision === "block") {
+            throw new RHEONICBlockedError(protectDecision.reason);
+        }
+        const callArgs = maybeApplyOpenAIClamp(args, protectDecision);
+        markClampAppliedIfChanged(protectDecision, extractMaxOutputTokens(args), extractMaxOutputTokens(callArgs));
+        try {
+            const response = await originalCreate(...callArgs);
+            void options.client.captureEvent(buildEvent({
+                provider: "openai",
+                model: extractResponseModel(response) ?? model,
+                environment: options.environment ?? options.client.environment,
+                request: {
+                    endpoint: options.endpoint,
+                    feature: options.feature,
+                    protect_decision: protectDecision.decision === "warn" ? "warn" : undefined,
+                    protect_reason: protectDecision.decision === "warn" ? protectDecision.reason : undefined,
+                },
+                response: {
+                    latency_ms: Date.now() - startedAt,
+                    total_tokens: extractTotalTokens(response),
+                    http_status: 200,
+                },
+            }));
+            return response;
+        }
+        catch (error) {
+            void options.client.captureEvent(buildEvent({
+                provider: "openai",
+                model,
+                environment: options.environment ?? options.client.environment,
+                request: {
+                    endpoint: options.endpoint,
+                    feature: options.feature,
+                    protect_decision: protectDecision.decision === "warn" ? "warn" : undefined,
+                    protect_reason: protectDecision.decision === "warn" ? protectDecision.reason : undefined,
+                },
+                response: {
+                    latency_ms: Date.now() - startedAt,
+                    error_type: extractErrorType(error),
+                    http_status: extractHttpStatus(error),
+                },
+            }));
+            throw error;
+        }
+    };
+    return openaiClient;
+}
+function extractRequestedModel(args) {
+    const firstArg = args[0];
+    if (firstArg && typeof firstArg === "object" && "model" in firstArg) {
+        const maybeModel = firstArg.model;
+        return typeof maybeModel === "string" ? maybeModel : null;
+    }
+    return null;
+}
+function extractRequestPayload(args) {
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object") {
+        return null;
+    }
+    return firstArg;
+}
+function extractMaxOutputTokens(args) {
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object") {
+        return undefined;
+    }
+    if ("max_tokens" in firstArg && typeof firstArg.max_tokens === "number") {
+        return firstArg.max_tokens;
+    }
+    if ("max_output_tokens" in firstArg && typeof firstArg.max_output_tokens === "number") {
+        return firstArg.max_output_tokens;
+    }
+    return undefined;
+}
+function maybeApplyOpenAIClamp(args, decision) {
+    if (decision.decision !== "warn" || decision.reason !== "near_cap") {
+        return args;
+    }
+    if (!decision.applyClampEnabled) {
+        return args;
+    }
+    const recommended = decision.clamp?.recommended_max_output_tokens;
+    if (typeof recommended !== "number" || recommended < 1) {
+        return args;
+    }
+    const firstArg = args[0];
+    if (!firstArg || typeof firstArg !== "object") {
+        return args;
+    }
+    const payload = { ...firstArg };
+    let updated = false;
+    const maxTokens = payload.max_tokens;
+    if (typeof maxTokens === "number") {
+        payload.max_tokens = Math.min(maxTokens, recommended);
+        updated = true;
+    }
+    const maxOutputTokens = payload.max_output_tokens;
+    if (typeof maxOutputTokens === "number") {
+        payload.max_output_tokens = Math.min(maxOutputTokens, recommended);
+        updated = true;
+    }
+    if (!updated) {
+        payload.max_tokens = recommended;
+    }
+    const nextArgs = [...args];
+    nextArgs[0] = payload;
+    return nextArgs;
+}
+function markClampAppliedIfChanged(decision, originalMaxTokens, appliedMaxTokens) {
+    if (!decision.clamp || typeof appliedMaxTokens !== "number") {
+        return;
+    }
+    if (typeof originalMaxTokens !== "number" || appliedMaxTokens < originalMaxTokens) {
+        decision.clamp.applied = true;
+    }
+}
+function extractResponseModel(response) {
+    if (response && typeof response === "object" && "model" in response) {
+        const maybeModel = response.model;
+        return typeof maybeModel === "string" ? maybeModel : null;
+    }
+    return null;
+}
+function extractTotalTokens(response) {
+    if (response && typeof response === "object" && "usage" in response) {
+        const usage = response.usage;
+        const totalTokens = usage?.total_tokens;
+        if (typeof totalTokens === "number") {
+            return totalTokens;
+        }
+    }
+    return undefined;
+}
+function extractErrorType(error) {
+    if (error && typeof error === "object" && "name" in error) {
+        const name = error.name;
+        if (typeof name === "string" && name.length > 0) {
+            return name;
+        }
+    }
+    return "unknown";
+}
+function extractHttpStatus(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const withStatus = error;
+    if (typeof withStatus.status === "number") {
+        return withStatus.status;
+    }
+    if (typeof withStatus.statusCode === "number") {
+        return withStatus.statusCode;
+    }
+    if (typeof withStatus.response?.status === "number") {
+        return withStatus.response.status;
+    }
+    return undefined;
+}

package/dist/rateLimiter.d.ts

@@ -0,0 +1,3 @@
+export declare class RateLimiter {
+    allow(_key: string): boolean;
+}

package/dist/rateLimiter.js

@@ -0,0 +1,6 @@
+export class RateLimiter {
+    allow(_key) {
+        // TODO: Implement local sliding-window rate limiting.
+        return true;
+    }
+}

package/dist/tokenEstimator.d.ts

@@ -0,0 +1,2 @@
+export declare function prewarmTokenEstimator(model?: string | null): void;
+export declare function estimateInputTokensFromRequest(payload: unknown): number | null;