fix: close #5

.changeset/repobot-tighten-type-usage-replace-lazy-any-unknown-with-true-types-issue5.md

@@ -0,0 +1,10 @@
+---
+"@reaatech/llm-cache-adapters-dynamodb": patch
+"@reaatech/llm-cache-adapters-qdrant": patch
+"@reaatech/llm-cache": patch
+"@reaatech/llm-cache-server": patch
+---
+
+Fix: Tighten type usage: replace lazy any/unknown with true types
+
+Closes #5

packages/adapters/dynamodb/src/DynamoDBAdapter.ts

@@ -13,6 +13,7 @@ import type {
   CacheEntry,
   HealthStatus,
   InvalidationCriteria,
+  JsonValue,
   StorageAdapter,
   StorageStats,
 } from '@reaatech/llm-cache';
@@ -341,7 +342,7 @@ export class DynamoDBAdapter implements StorageAdapter {
   private deserialize(item: Record<string, unknown>): CacheEntry {
     const metadata = item.metadata as Record<string, unknown>;
 
-    let response: unknown = null;
+    let response: JsonValue = null;
     try {
       response = JSON.parse(String(item.response ?? 'null'));
     } catch {

packages/adapters/qdrant/src/QdrantAdapter.ts

@@ -3,6 +3,7 @@ import type {
   CacheEntry,
   HealthStatus,
   InvalidationCriteria,
+  JsonValue,
   SimilarityResult,
   StorageStats,
   VectorSearchFilters,
@@ -375,7 +376,7 @@ export class QdrantAdapter implements VectorStorageAdapter {
   private deserializeEntry(payload: Record<string, unknown>, vector: number[]): CacheEntry {
     const metadata = payload.metadata as Record<string, unknown>;
 
-    let response: unknown = null;
+    let response: JsonValue = null;
     try {
       response = JSON.parse(String(payload.response));
     } catch {

packages/core/src/cache/CacheEngine.ts

@@ -9,6 +9,7 @@ import type {
   CacheResult,
   CostCalculatorLike,
   InvalidateResult,
+  JsonValue,
   VectorSearchFilters,
 } from '../types/index.js';
 import type { EncryptedPayload, EncryptionService } from '../utils/encryption.js';
@@ -142,7 +143,7 @@ export class CacheEngine {
 
   async set(
     prompt: string,
-    response: unknown,
+    response: JsonValue,
     options?: CacheOptions,
     metadata?: CacheMetadata,
   ): Promise<CacheEntry> {
@@ -218,7 +219,7 @@ export class CacheEngine {
   async setBatch(
     items: Array<{
       prompt: string;
-      response: unknown;
+      response: JsonValue;
       options?: CacheOptions;
       metadata?: CacheMetadata;
     }>,

packages/core/src/types/index.ts

@@ -1,8 +1,25 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export interface ToolDefinition {
+  type?: string;
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
 export interface CacheEntry {
   id: string;
   prompt: string;
   promptHash: string;
-  response: unknown;
+  response: JsonValue;
   embedding: number[];
   model: string;
   modelVersion: string;
@@ -56,7 +73,7 @@ export interface CacheOptions {
   topP?: number;
   maxTokens?: number;
   systemPrompt?: string;
-  tools?: unknown[];
+  tools?: ToolDefinition[];
   responseFormat?: 'text' | 'json_object' | 'json_schema';
 }
 

packages/core/src/utils/hash.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import type { ToolDefinition } from '../types/index.js';
 
 export function sha256(input: string): string {
   return createHash('sha256').update(input).digest('hex');
@@ -31,7 +32,7 @@ export function buildCacheFingerprint(options: {
   topP?: number;
   maxTokens?: number;
   systemPrompt?: string;
-  tools?: unknown[];
+  tools?: ToolDefinition[];
   responseFormat?: string;
 }): string {
   const canonical = JSON.stringify({

packages/server/src/app.ts

@@ -6,6 +6,7 @@ import {
   type CacheOptions,
   type EmbeddingProvider,
   InMemoryAdapter,
+  type JsonValue,
   OpenAIEmbedder,
 } from '@reaatech/llm-cache';
 import { DynamoDBAdapter } from '@reaatech/llm-cache-adapters-dynamodb';
@@ -255,7 +256,7 @@ export async function createApp(): Promise<App> {
         if (url.pathname === '/cache/set' && req.method === 'POST') {
           const body = (await readBody(req)) as {
             prompt: string;
-            response: unknown;
+            response: JsonValue;
             options?: CacheOptions;
             metadata?: {
               queryType?: 'factual' | 'creative' | 'analytical';