@typegraph-ai/adapter-redis-upstash 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,168 @@
+# @typegraph-ai/adapter-redis-upstash
+
+Upstash Redis coreference-cache adapter for self-hosted TypeGraph deployments.
+
+This package is a small Upstash-friendly wrapper around
+`@typegraph-ai/adapter-redis`. It provides the same extraction coreference cache
+behavior, but its option names and examples are written for `@upstash/redis`.
+
+Cloud users do not configure this adapter. TypeGraph Cloud manages extraction
+cache infrastructure for hosted API-key clients.
+
+## What It Does
+
+TypeGraph graph extraction often runs over many chunks, documents, event
+payloads, attached transcripts, and thread turns. The extractor needs continuity:
+if one chunk resolves `Acme Inc.` to an organization entity, later chunks should
+reuse that context instead of treating every mention as a fresh candidate.
+
+This adapter stores a temporary, compact list of recently extracted entities in
+Upstash Redis. TypeGraph passes those entities back into subsequent extraction
+calls as coreference context.
+
+It helps with:
+
+- consistent entity resolution across chunked documents;
+- event extraction with attached documents;
+- thread-turn extraction;
+- multi-worker and serverless ingestion jobs;
+- retries where the extractor benefits from prior context.
+
+It does not store TypeGraph documents, memories, facts, graph edges, embeddings,
+jobs, or buckets. Use `@typegraph-ai/adapter-pgvector` for TypeGraph storage.
+
+## Install
+
+```bash
+pnpm add @typegraph-ai/adapter-redis-upstash @upstash/redis
+```
+
+`@typegraph-ai/adapter-redis-upstash` depends on
+`@typegraph-ai/adapter-redis`, so you do not need to import the base Redis
+adapter directly unless you are using a different Redis client.
+
+## Usage
+
+```ts
+import { Redis } from '@upstash/redis'
+import { typegraphInit } from '@typegraph-ai/sdk'
+import { createUpstashCoreferenceCache } from '@typegraph-ai/adapter-redis-upstash'
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+})
+
+const typegraph = await typegraphInit({
+  vectorStore,
+  embedding,
+  searchEmbedding,
+  llm,
+  extractionCoreferenceCache: createUpstashCoreferenceCache({
+    redis,
+    namespace: 'tenant_public',
+    ttlSeconds: 4 * 60 * 60,
+  }),
+})
+```
+
+`tenantId` defaults to `public` when omitted. For multi-tenant self-hosted apps,
+include your schema, environment, or tenant in `namespace`:
+
+```ts
+extractionCoreferenceCache: createUpstashCoreferenceCache({
+  redis,
+  namespace: `prod:${schemaName}:${tenantId}`,
+})
+```
+
+## TypeGraph App Usage
+
+The TypeGraph Cloud app uses this package only for its own self-hosted backend
+runtime. End users of TypeGraph Cloud should not configure Redis.
+
+Example app wrapper:
+
+```ts
+import { Redis } from '@upstash/redis'
+import { createUpstashCoreferenceCache } from '@typegraph-ai/adapter-redis-upstash'
+
+export function createCoreferenceCache(schema: string, tenantId = 'public') {
+  const url = process.env.UPSTASH_REDIS_REST_URL
+  const token = process.env.UPSTASH_REDIS_REST_TOKEN
+  if (!url || !token) return undefined
+
+  return createUpstashCoreferenceCache({
+    redis: new Redis({ url, token }),
+    namespace: `${schema}:${tenantId}`,
+    onError(error) {
+      console.warn('TypeGraph coreference cache unavailable', error)
+    },
+  })
+}
+```
+
+## Options
+
+```ts
+type UpstashCoreferenceCacheOptions = {
+  redis: Redis
+  namespace?: string
+  ttlSeconds?: number
+  maxEntities?: number
+  maxAliases?: number
+  maxTypeCandidates?: number
+  onError?: (error: unknown) => void
+}
+```
+
+### `redis`
+
+Required `@upstash/redis` client or compatible object with `get` and `set`
+methods.
+
+### `namespace`
+
+Optional logical prefix for cache keys. Use this to isolate deployments,
+schemas, tenants, or test runs.
+
+### `ttlSeconds`
+
+How long cache entries live. Defaults to 4 hours.
+
+The cache is intentionally temporary. TypeGraph’s durable state still lives in
+the configured TypeGraph storage adapter.
+
+### `maxEntities`, `maxAliases`, `maxTypeCandidates`
+
+Compaction limits applied before saving:
+
+- `maxEntities`: default `120`
+- `maxAliases`: default `12`
+- `maxTypeCandidates`: default `4`
+
+### `onError`
+
+Optional error callback. Cache failures are swallowed after this hook runs, so
+Redis downtime does not fail an otherwise valid ingest request.
+
+## When To Use This
+
+Use this package when:
+
+- you self-host TypeGraph or TypeGraph Cloud backend code;
+- extraction runs across multiple workers or serverless invocations;
+- you want better entity continuity during graph extraction;
+- Upstash Redis is already part of your infrastructure.
+
+Do not use it when:
+
+- you are a TypeGraph Cloud customer using only an API key;
+- you need a vector database, graph database, or job queue;
+- you want permanent memory storage.
+
+## Related Packages
+
+- `@typegraph-ai/adapter-redis`: generic Redis-compatible cache adapter.
+- `@typegraph-ai/adapter-pgvector`: Postgres/pgvector TypeGraph storage adapter.
+- `@typegraph-ai/sdk`: TypeGraph SDK.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { type RedisCoreferenceCacheOptions, type RedisCoreferenceClient } from '@typegraph-ai/adapter-redis';
+export interface UpstashCoreferenceClient extends RedisCoreferenceClient {
+}
+export interface UpstashCoreferenceCacheOptions extends Omit<RedisCoreferenceCacheOptions, 'redis'> {
+    redis: UpstashCoreferenceClient;
+}
+export declare function createUpstashCoreferenceCache(options: UpstashCoreferenceCacheOptions): import("@typegraph-ai/sdk").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,EAEL,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC5B,MAAM,6BAA6B,CAAA;AAEpC,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;CAAG;AAE3E,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAAC,4BAA4B,EAAE,OAAO,CAAC;IACjG,KAAK,EAAE,wBAAwB,CAAA;CAChC;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,0DAEpF"}

package/dist/index.js

@@ -0,0 +1,5 @@
+import { createRedisCoreferenceCache, } from '@typegraph-ai/adapter-redis';
+export function createUpstashCoreferenceCache(options) {
+    return createRedisCoreferenceCache(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,GAG5B,MAAM,6BAA6B,CAAA;AAQpC,MAAM,UAAU,6BAA6B,CAAC,OAAuC;IACnF,OAAO,2BAA2B,CAAC,OAAO,CAAC,CAAA;AAC7C,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@typegraph-ai/adapter-redis-upstash",
+  "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/adapter-redis": "0.1.0",
+    "@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"
+  }
+}