@typegraph-ai/adapter-redis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TypeGraph
+
+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.

package/README.md

@@ -0,0 +1,164 @@
+# @typegraph-ai/adapter-redis
+
+Redis-backed cache utilities for self-hosted TypeGraph deployments.
+
+This package currently provides an extraction coreference cache. It is not a
+vector store, memory store, graph store, or queue adapter. Its job is narrower:
+it lets TypeGraph remember recently resolved entities during extraction so
+large document, event, and thread ingestion jobs keep entity names consistent
+across chunks and batches.
+
+Cloud users do not configure this adapter. TypeGraph Cloud manages extraction
+cache infrastructure for hosted API-key clients.
+
+## What It Does
+
+During graph extraction, TypeGraph may see the same real-world entity many times:
+
+- `Acme`
+- `Acme Inc.`
+- `ACME Corporation`
+- `the customer`
+
+The extractor resolves those mentions into normalized entities. Without a shared
+cache, each chunk or worker may have to rediscover the same mappings. With this
+adapter, TypeGraph stores a compact list of recently extracted entities in Redis
+and passes it back into later extraction calls.
+
+That improves:
+
+- entity consistency across chunks;
+- event/document/thread extraction continuity;
+- multi-worker self-hosted ingestion behavior;
+- retry behavior after transient extraction failures.
+
+It does not grant access, route graph writes, or change search results by itself.
+Access and graph boundaries still come from TypeGraph tenant, graph, bucket, and
+context configuration.
+
+## Install
+
+```bash
+pnpm add @typegraph-ai/adapter-redis
+```
+
+You also need a Redis client. This package intentionally does not depend on a
+specific Redis library. It accepts any client with compatible `get` and `set`
+methods.
+
+```ts
+interface RedisCoreferenceClient {
+  get<T = unknown>(key: string): Promise<T | null>
+  set(key: string, value: unknown, options?: { ex?: number }): Promise<unknown>
+}
+```
+
+For Upstash, use `@typegraph-ai/adapter-redis-upstash`.
+
+## Usage
+
+```ts
+import { typegraphInit } from '@typegraph-ai/sdk'
+import { createRedisCoreferenceCache } from '@typegraph-ai/adapter-redis'
+
+const extractionCoreferenceCache = createRedisCoreferenceCache({
+  redis,
+  namespace: 'tenant_public',
+  ttlSeconds: 4 * 60 * 60,
+})
+
+const typegraph = await typegraphInit({
+  vectorStore,
+  embedding,
+  searchEmbedding,
+  llm,
+  extractionCoreferenceCache,
+})
+```
+
+`tenantId` defaults to `public` when omitted. For multi-tenant self-hosted apps,
+use a namespace that includes your tenant or deployment boundary:
+
+```ts
+const extractionCoreferenceCache = createRedisCoreferenceCache({
+  redis,
+  namespace: `schema_${schemaName}:tenant_${tenantId}`,
+})
+```
+
+## Options
+
+```ts
+type RedisCoreferenceCacheOptions = {
+  redis: RedisCoreferenceClient
+  namespace?: string
+  ttlSeconds?: number
+  maxEntities?: number
+  maxAliases?: number
+  maxTypeCandidates?: number
+  onError?: (error: unknown) => void
+}
+```
+
+### `redis`
+
+Required Redis-compatible client.
+
+The adapter stores JSON-compatible arrays of extracted entity records. The Redis
+client may serialize values itself, or it may return strings. The adapter handles
+both parsed arrays and JSON strings on reads.
+
+### `namespace`
+
+Optional logical prefix for cache keys. Use this to isolate environments,
+schemas, tenants, or test runs.
+
+The final key also includes TypeGraph extraction context such as tenant, bucket,
+group, user, agent, and thread when those fields are available.
+
+### `ttlSeconds`
+
+How long cache entries live. Defaults to 4 hours.
+
+This cache is intentionally temporary. It should help active ingestion jobs
+maintain continuity, not become a permanent entity store.
+
+### `maxEntities`, `maxAliases`, `maxTypeCandidates`
+
+Compaction limits applied before saving. Defaults are conservative so the cache
+stays small:
+
+- `maxEntities`: `120`
+- `maxAliases`: `12`
+- `maxTypeCandidates`: `4`
+
+### `onError`
+
+Optional error hook. Cache failures are swallowed after calling this hook. This
+is deliberate: Redis should improve extraction quality and throughput, but it
+should not make document ingestion fail when the primary database and extractor
+are healthy.
+
+## Key Shape
+
+Keys are URL-encoded and prefixed:
+
+```text
+typegraph:coreference:<namespace>:<tenantId>:<bucketId>:group:<groupId>:user:<userId>:agent:<agentId>:thread:<threadId>
+```
+
+Only fields present in the extraction context are included.
+
+## Self-Hosted vs Cloud
+
+Use this adapter when you run TypeGraph yourself and want Redis-backed extraction
+continuity across workers.
+
+Do not use it when calling TypeGraph Cloud with an API key. Cloud manages this
+cache internally and may use different infrastructure.
+
+## Related Packages
+
+- `@typegraph-ai/adapter-redis-upstash`: Upstash Redis wrapper around this package.
+- `@typegraph-ai/adapter-pgvector`: Postgres/pgvector storage adapter for TypeGraph data.
+- `@typegraph-ai/sdk`: TypeGraph SDK.

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { ExtractionCoreferenceCache } from '@typegraph-ai/sdk';
+export interface RedisCoreferenceClient {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, options?: {
+        ex?: number | undefined;
+    }): Promise<unknown>;
+}
+export interface RedisCoreferenceCacheOptions {
+    redis: RedisCoreferenceClient;
+    namespace?: string | undefined;
+    ttlSeconds?: number | undefined;
+    maxEntities?: number | undefined;
+    maxAliases?: number | undefined;
+    maxTypeCandidates?: number | undefined;
+    onError?: ((error: unknown) => void) | undefined;
+}
+export declare function createRedisCoreferenceCache(options: RedisCoreferenceCacheOptions): ExtractionCoreferenceCache;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,0BAA0B,EAE3B,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC1F;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,sBAAsB,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CACjD;AAOD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,0BAA0B,CA2B7G"}

package/dist/index.js

@@ -0,0 +1,83 @@
+const DEFAULT_TTL_SECONDS = 60 * 60 * 4;
+const DEFAULT_MAX_ENTITIES = 120;
+const DEFAULT_MAX_ALIASES = 12;
+const DEFAULT_MAX_TYPE_CANDIDATES = 4;
+export function createRedisCoreferenceCache(options) {
+    const ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    const maxEntities = options.maxEntities ?? DEFAULT_MAX_ENTITIES;
+    const maxAliases = options.maxAliases ?? DEFAULT_MAX_ALIASES;
+    const maxTypeCandidates = options.maxTypeCandidates ?? DEFAULT_MAX_TYPE_CANDIDATES;
+    return {
+        async load(key) {
+            try {
+                return normalizeEntities(await options.redis.get(cacheKey(options.namespace, key)));
+            }
+            catch (error) {
+                options.onError?.(error);
+                return [];
+            }
+        },
+        async save(key, entities) {
+            try {
+                await options.redis.set(cacheKey(options.namespace, key), compactEntities(entities, maxEntities, maxAliases, maxTypeCandidates), { ex: ttlSeconds });
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+        },
+    };
+}
+function cacheKey(namespace, key) {
+    const parts = [
+        'typegraph',
+        'coreference',
+        namespace ?? 'default',
+        key.tenantId ?? 'public',
+        key.bucketId,
+        key.groupId ? `group:${key.groupId}` : undefined,
+        key.userId ? `user:${key.userId}` : undefined,
+        key.agentId ? `agent:${key.agentId}` : undefined,
+        key.threadId ? `thread:${key.threadId}` : undefined,
+    ].filter((part) => Boolean(part));
+    return parts.map(encodeURIComponent).join(':');
+}
+function normalizeEntities(value) {
+    if (typeof value === 'string') {
+        try {
+            return normalizeEntities(JSON.parse(value));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isExtractedEntity);
+}
+function isExtractedEntity(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entity = value;
+    return typeof entity.type === 'string' && typeof entity.name === 'string';
+}
+function compactEntities(entities, maxEntities, maxAliases, maxTypeCandidates) {
+    const byKey = new Map();
+    for (const entity of entities) {
+        const key = `${entity.type}:${entity.name.toLowerCase()}`;
+        if (byKey.has(key))
+            continue;
+        byKey.set(key, {
+            type: entity.type,
+            id: entity.id,
+            name: entity.name,
+            description: entity.description,
+            aliases: entity.aliases?.slice(0, maxAliases),
+            typeCandidates: entity.typeCandidates?.slice(0, maxTypeCandidates),
+            metadata: entity.metadata,
+        });
+        if (byKey.size >= maxEntities)
+            break;
+    }
+    return [...byKey.values()];
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@typegraph-ai/adapter-redis",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@typegraph-ai/sdk": "0.5.1"
+  },
+  "peerDependencies": {
+    "@typegraph-ai/sdk": "0.5.1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}