@codesoul-co/hypha-serving-cache / types

• Package index: @codesoul-co/hypha-serving-cache
• Source: packages/serving-cache/src/types.ts
• Exports: 29

Using this module

Use the Types module for declaring and runtime-validating contracts. It exports 18 interfaces, 11 types.

Import from the package entrypoint

import type {
  CachedLLMProviderOptions,
  CachedModelResponseProjection,
  CacheEntry,
  CacheLookupHit,
  CacheLookupMiss,
  CacheMetadata,
  CachePolicy,
  CacheScope,
} from '@codesoul-co/hypha-serving-cache';

// The complete export list is documented below.

Usage patterns

• Use the 29 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.

Public exports

Symbol	Kind	Signature	Description
CachedLLMProviderOptions	interface	interface CachedLLMProviderOptions	Cached LLM Provider Options interface with 8 public fields or methods.
CachedModelResponseProjection	interface	interface CachedModelResponseProjection	Cached Model Response Projection interface with 6 public fields or methods.
CacheEntry	interface	interface CacheEntry	Cache Entry interface with 8 public fields or methods.
CacheLookupHit	interface	interface CacheLookupHit	Cache Lookup Hit interface with 4 public fields or methods.
CacheLookupMiss	interface	interface CacheLookupMiss	Cache Lookup Miss interface with 3 public fields or methods.
CacheMetadata	interface	interface CacheMetadata	Cache Metadata interface with 12 public fields or methods.
CachePolicy	interface	interface CachePolicy	Cache Policy interface with 10 public fields or methods.
CacheScope	interface	interface CacheScope	Cache Scope interface with 5 public fields or methods.
CacheStore	interface	interface CacheStore	Cache Store interface with 8 public fields or methods.
CacheStoreHealth	interface	interface CacheStoreHealth	Cache Store Health interface with 3 public fields or methods.
CacheStoreStats	interface	interface CacheStoreStats	Cache Store Stats interface with 3 public fields or methods.
LLMCacheKeyInput	interface	interface LLMCacheKeyInput	LLM Cache Key Input interface with 8 public fields or methods.
ModelRequestCacheControl	interface	interface ModelRequestCacheControl	Model Request Cache Control interface with 2 public fields or methods.
PrefixCacheShapeObservation	interface	interface PrefixCacheShapeObservation	Prefix Cache Shape Observation interface with 17 public fields or methods.
PromptPrefixBlock	interface	interface PromptPrefixBlock extends Required<Pick<PromptPrefixBlockInput, 'id' | 'type' | 'hash'>>	Prompt Prefix Block interface with 11 public fields or methods.
PromptPrefixBlockInput	interface	interface PromptPrefixBlockInput	Prompt Prefix Block Input interface with 11 public fields or methods.
PromptPrefixMetadata	interface	interface PromptPrefixMetadata	Prompt Prefix Metadata interface with 7 public fields or methods.
ProviderPrefixCacheUsage	interface	interface ProviderPrefixCacheUsage	Provider Prefix Cache Usage interface with 5 public fields or methods.
CacheFailureMode	type	type CacheFailureMode = 'bypass' | 'strict'	Public type alias for Cache Failure Mode; the declaration contains its complete type expression.
CacheLookupResult	type	type CacheLookupResult = CacheLookupHit<T> | CacheLookupMiss	Public type alias for Cache Lookup Result; the declaration contains its complete type expression.
CacheMode	type	type CacheMode = 'off' | 'read' | 'write' | 'readwrite'	Public type alias for Cache Mode; the declaration contains its complete type expression.
CacheScopeRequirement	type	type CacheScopeRequirement = 'none' | 'user' | 'session'	Public type alias for Cache Scope Requirement; the declaration contains its complete type expression.
CacheType	type	type CacheType = 'exact' | 'prefix-metadata' | 'semantic'	Public type alias for Cache Type; the declaration contains its complete type expression.
PrefixCacheChangeReason	type	type PrefixCacheChangeReason = 'first_request' | 'prefix_changed' | 'tool_schema_changed' | 'domain_pack_changed' | 'dynamic_suffix_changed' | 'unchanged'	Public type alias for Prefix Cache Change Reason; the declaration contains its complete type expression.
PromptPrefixBlockType	type	type PromptPrefixBlockType = 'system' | 'tool-schema' | 'project-context' | 'domain-pack' | 'memory' | 'prompt-template'	Public type alias for Prompt Prefix Block Type; the declaration contains its complete type expression.
ServingCacheEvent	type	type ServingCacheEvent = { type: 'llm.cache.lookup'; key: string; provider: string; model: string; scope?: CacheScope; prefixCache?: PrefixCacheShapeObservation; runId?: string; stepId?: string; } | { type: 'llm.cache.hit'; key: string; ageMs: number; provider: string; model: string; scope?: CacheScope; prefixCache?: PrefixCacheShapeObservation; runId?: string; stepId?: string; } | { type: 'llm.cache.miss'; key: s...	Public type alias for Serving Cache Event; the declaration contains its complete type expression.
ServingCacheMissReason	type	type ServingCacheMissReason = 'not_found' | 'expired' | 'disabled' | 'streaming' | 'no_cache' | 'mode_off' | 'read_disabled' | 'scope_missing' | 'store_unavailable' | 'entry_oversized' | 'corrupt'	Public type alias for Serving Cache Miss Reason; the declaration contains its complete type expression.
ServingCacheStoreKind	type	type ServingCacheStoreKind = 'off' | 'noop' | 'memory' | 'sqlite' | 'redis'	Public type alias for Serving Cache Store Kind; the declaration contains its complete type expression.
ServingCacheTraceSink	type	type ServingCacheTraceSink = (event: ServingCacheEvent) => void | Promise<void>	Public type alias for Serving Cache Trace Sink; the declaration contains its complete type expression.

CachedLLMProviderOptions

Cached LLM Provider Options interface with 8 public fields or methods.

• Kind: interface
• Import: import type { CachedLLMProviderOptions } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CachedLLMProviderOptions {
    policy?: Partial<CachePolicy>;
    trace?: ServingCacheTraceSink;
    providerResolver?: (request: ModelRequest, inner: ModelProvider<ModelRequest, ModelResponse>) => string;
    modelResolver?: (request: ModelRequest, inner: ModelProvider<ModelRequest, ModelResponse>) => string;
    scopeResolver?: (request: ModelRequest) => CacheScope | undefined;
    paramsResolver?: (request: ModelRequest) => Record<string, unknown> | undefined;
    promptBlocksResolver?: (request: ModelRequest) => PromptPrefixBlockInput[] | undefined;
    responseIdFactory?: (request: ModelRequest, key: string) => string;
}

Contract members

Member	Kind	Signature	Description
modelResolver	method	modelResolver?(request: ModelRequest, inner: ModelProvider<ModelRequest, ModelResponse>): string	Public method; parameters and return type are shown in the signature.
paramsResolver	method	paramsResolver?(request: ModelRequest): Record<string, unknown> | undefined	Public method; parameters and return type are shown in the signature.
policy	property	policy?: Partial<CachePolicy>	Public property; its type, readonly modifier and optionality are shown in the signature.
promptBlocksResolver	method	promptBlocksResolver?(request: ModelRequest): PromptPrefixBlockInput[] | undefined	Public method; parameters and return type are shown in the signature.
providerResolver	method	providerResolver?(request: ModelRequest, inner: ModelProvider<ModelRequest, ModelResponse>): string	Public method; parameters and return type are shown in the signature.
responseIdFactory	method	responseIdFactory?(request: ModelRequest, key: string): string	Public method; parameters and return type are shown in the signature.
scopeResolver	method	scopeResolver?(request: ModelRequest): CacheScope | undefined	Public method; parameters and return type are shown in the signature.
trace	method	trace?(event: ServingCacheEvent): void | Promise<void>	Public method; parameters and return type are shown in the signature.

CachedModelResponseProjection

Cached Model Response Projection interface with 6 public fields or methods.

• Kind: interface
• Import: import type { CachedModelResponseProjection } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CachedModelResponseProjection {
    schemaVersion: '1.0';
    providerId?: string;
    model?: string;
    content: ModelResponse['content'];
    toolCalls?: ModelResponse['toolCalls'];
    usage?: ModelResponse['usage'];
}

Contract members

Member	Kind	Signature	Description
content	property	content: string	Public property; its type, readonly modifier and optionality are shown in the signature.
model	property	model?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
schemaVersion	property	schemaVersion: "1.0"	Public property; its type, readonly modifier and optionality are shown in the signature.
toolCalls	property	toolCalls?: import("/Users/erwin/Downloads/codespace/Hypha/packages/models/dist/index").NormalizedToolCall[]	Public property; its type, readonly modifier and optionality are shown in the signature.
usage	property	usage?: import("/Users/erwin/Downloads/codespace/Hypha/packages/models/dist/index").ModelUsage	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheEntry

Cache Entry interface with 8 public fields or methods.

• Kind: interface
• Import: import type { CacheEntry } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheEntry<T = unknown> {
    schemaVersion?: '1.0';
    keyVersion?: '1';
    key: string;
    value: T;
    createdAt: number;
    expiresAt?: number;
    sizeBytes?: number;
    metadata?: CacheMetadata;
}

Contract members

Member	Kind	Signature	Description
createdAt	property	createdAt: number	Public property; its type, readonly modifier and optionality are shown in the signature.
expiresAt	property	expiresAt?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
key	property	key: string	Public property; its type, readonly modifier and optionality are shown in the signature.
keyVersion	property	keyVersion?: "1"	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: CacheMetadata	Public property; its type, readonly modifier and optionality are shown in the signature.
schemaVersion	property	schemaVersion?: "1.0"	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
value	property	value: T	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheLookupHit

Cache Lookup Hit interface with 4 public fields or methods.

• Kind: interface
• Import: import type { CacheLookupHit } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheLookupHit<T = unknown> {
    hit: true;
    key: string;
    entry: CacheEntry<T>;
    ageMs: number;
}

Contract members

Member	Kind	Signature	Description
ageMs	property	ageMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.
entry	property	entry: CacheEntry<T>	Public property; its type, readonly modifier and optionality are shown in the signature.
hit	property	hit: true	Public property; its type, readonly modifier and optionality are shown in the signature.
key	property	key: string	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheLookupMiss

Cache Lookup Miss interface with 3 public fields or methods.

• Kind: interface
• Import: import type { CacheLookupMiss } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheLookupMiss {
    hit: false;
    key: string;
    reason: 'not_found' | 'expired';
}

Contract members

Member	Kind	Signature	Description
hit	property	hit: false	Public property; its type, readonly modifier and optionality are shown in the signature.
key	property	key: string	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason: "not_found" | "expired"	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheMetadata

Cache Metadata interface with 12 public fields or methods.

• Kind: interface
• Import: import type { CacheMetadata } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheMetadata {
    provider: string;
    model: string;
    cacheType: CacheType;
    promptHash?: string;
    toolSchemaHash?: string;
    requestHash?: string;
    hitCount?: number;
    tags?: string[];
    scope?: CacheScope;
    projectionType?: string;
    classification?: 'public' | 'internal' | 'confidential' | 'restricted';
    prefixMetadata?: PromptPrefixMetadata;
}

Contract members

Member	Kind	Signature	Description
cacheType	property	cacheType: CacheType	Public property; its type, readonly modifier and optionality are shown in the signature.
classification	property	classification?: "restricted" | "public" | "internal" | "confidential"	Public property; its type, readonly modifier and optionality are shown in the signature.
hitCount	property	hitCount?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
model	property	model: string	Public property; its type, readonly modifier and optionality are shown in the signature.
prefixMetadata	property	prefixMetadata?: PromptPrefixMetadata	Public property; its type, readonly modifier and optionality are shown in the signature.
projectionType	property	projectionType?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
promptHash	property	promptHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
provider	property	provider: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requestHash	property	requestHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
scope	property	scope?: CacheScope	Public property; its type, readonly modifier and optionality are shown in the signature.
tags	property	tags?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
toolSchemaHash	property	toolSchemaHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

CachePolicy

Cache Policy interface with 10 public fields or methods.

• Kind: interface
• Import: import type { CachePolicy } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CachePolicy {
    enabled: boolean;
    mode: CacheMode;
    ttlMs?: number;
    respectNoCache?: boolean;
    failureMode?: CacheFailureMode;
    scopeRequirement?: CacheScopeRequirement;
    operationTimeoutMs?: number;
    singleflight?: boolean;
    maxEntryBytes?: number;
    circuitBreaker?: {
        failureThreshold: number;
        resetTimeoutMs: number;
    };
}

Contract members

Member	Kind	Signature	Description
circuitBreaker	property	circuitBreaker?: { failureThreshold: number; resetTimeoutMs: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
enabled	property	enabled: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
failureMode	property	failureMode?: CacheFailureMode	Public property; its type, readonly modifier and optionality are shown in the signature.
maxEntryBytes	property	maxEntryBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
mode	property	mode: CacheMode	Public property; its type, readonly modifier and optionality are shown in the signature.
operationTimeoutMs	property	operationTimeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
respectNoCache	property	respectNoCache?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
scopeRequirement	property	scopeRequirement?: CacheScopeRequirement	Public property; its type, readonly modifier and optionality are shown in the signature.
singleflight	property	singleflight?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
ttlMs	property	ttlMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheScope

Cache Scope interface with 5 public fields or methods.

• Kind: interface
• Import: import type { CacheScope } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheScope {
    tenantId?: string;
    userId?: string;
    projectId?: string;
    sessionId?: string;
    domainPackId?: string;
}

Contract members

Member	Kind	Signature	Description
domainPackId	property	domainPackId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
projectId	property	projectId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sessionId	property	sessionId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheStore

Cache Store interface with 8 public fields or methods.

• Kind: interface
• Import: import type { CacheStore } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheStore<T = unknown> {
    get<TValue = T>(key: string): Promise<CacheEntry<TValue> | null>;
    set<TValue = T>(key: string, entry: CacheEntry<TValue>): Promise<void>;
    delete(key: string): Promise<void>;
    clear?(): Promise<void>;
    touch?(key: string, timestamp: number): Promise<void>;
    stats?(): Promise<CacheStoreStats>;
    health?(): Promise<CacheStoreHealth>;
    close?(): Promise<void>;
}

Contract members

Member	Kind	Signature	Description
clear	method	clear?(): Promise<void>	Public method; parameters and return type are shown in the signature.
close	method	close?(): Promise<void>	Public method; parameters and return type are shown in the signature.
delete	method	delete(key: string): Promise<void>	Public method; parameters and return type are shown in the signature.
get	method	get<TValue = T>(key: string): Promise<CacheEntry<TValue> | null>	Public method; parameters and return type are shown in the signature.
health	method	health?(): Promise<CacheStoreHealth>	Public method; parameters and return type are shown in the signature.
set	method	set<TValue = T>(key: string, entry: CacheEntry<TValue>): Promise<void>	Public method; parameters and return type are shown in the signature.
stats	method	stats?(): Promise<CacheStoreStats>	Public method; parameters and return type are shown in the signature.
touch	method	touch?(key: string, timestamp: number): Promise<void>	Public method; parameters and return type are shown in the signature.

CacheStoreHealth

Cache Store Health interface with 3 public fields or methods.

• Kind: interface
• Import: import type { CacheStoreHealth } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheStoreHealth {
    status: 'healthy' | 'degraded' | 'unavailable';
    checkedAt: string;
    details?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
checkedAt	property	checkedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
details	property	details?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "healthy" | "degraded" | "unavailable"	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheStoreStats

Cache Store Stats interface with 3 public fields or methods.

• Kind: interface
• Import: import type { CacheStoreStats } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface CacheStoreStats {
    entries: number;
    sizeBytes?: number;
    evictions?: number;
}

Contract members

Member	Kind	Signature	Description
entries	property	entries: number	Public property; its type, readonly modifier and optionality are shown in the signature.
evictions	property	evictions?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

LLMCacheKeyInput

LLM Cache Key Input interface with 8 public fields or methods.

• Kind: interface
• Import: import type { LLMCacheKeyInput } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface LLMCacheKeyInput {
    provider: string;
    model: string;
    messages: unknown[];
    system?: string;
    tools?: unknown[];
    params?: Record<string, unknown>;
    cacheScope?: CacheScope;
    promptBlocks?: PromptPrefixBlockInput[];
}

Contract members

Member	Kind	Signature	Description
cacheScope	property	cacheScope?: CacheScope	Public property; its type, readonly modifier and optionality are shown in the signature.
messages	property	messages: unknown[]	Public property; its type, readonly modifier and optionality are shown in the signature.
model	property	model: string	Public property; its type, readonly modifier and optionality are shown in the signature.
params	property	params?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
promptBlocks	property	promptBlocks?: PromptPrefixBlockInput[]	Public property; its type, readonly modifier and optionality are shown in the signature.
provider	property	provider: string	Public property; its type, readonly modifier and optionality are shown in the signature.
system	property	system?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tools	property	tools?: unknown[]	Public property; its type, readonly modifier and optionality are shown in the signature.

ModelRequestCacheControl

Model Request Cache Control interface with 2 public fields or methods.

• Kind: interface
• Import: import type { ModelRequestCacheControl } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface ModelRequestCacheControl {
    mode?: CacheMode;
    noCache?: boolean;
}

Contract members

Member	Kind	Signature	Description
mode	property	mode?: CacheMode	Public property; its type, readonly modifier and optionality are shown in the signature.
noCache	property	noCache?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

PrefixCacheShapeObservation

Prefix Cache Shape Observation interface with 17 public fields or methods.

• Kind: interface
• Import: import type { PrefixCacheShapeObservation } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface PrefixCacheShapeObservation {
    provider: string;
    model: string;
    prefixHash: string;
    previousPrefixHash?: string;
    toolSchemaHash?: string;
    previousToolSchemaHash?: string;
    domainPackHash?: string;
    previousDomainPackHash?: string;
    dynamicSuffixHash?: string;
    previousDynamicSuffixHash?: string;
    requestHash?: string;
    prefixTokenEstimate?: number;
    blockCount: number;
    stablePrefixChanged: boolean;
    dynamicSuffixChanged: boolean;
    changedReasons: PrefixCacheChangeReason[];
    scope?: CacheScope;
}

Contract members

Member	Kind	Signature	Description
blockCount	property	blockCount: number	Public property; its type, readonly modifier and optionality are shown in the signature.
changedReasons	property	changedReasons: PrefixCacheChangeReason[]	Public property; its type, readonly modifier and optionality are shown in the signature.
domainPackHash	property	domainPackHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
dynamicSuffixChanged	property	dynamicSuffixChanged: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
dynamicSuffixHash	property	dynamicSuffixHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
model	property	model: string	Public property; its type, readonly modifier and optionality are shown in the signature.
prefixHash	property	prefixHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
prefixTokenEstimate	property	prefixTokenEstimate?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
previousDomainPackHash	property	previousDomainPackHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
previousDynamicSuffixHash	property	previousDynamicSuffixHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
previousPrefixHash	property	previousPrefixHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
previousToolSchemaHash	property	previousToolSchemaHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
provider	property	provider: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requestHash	property	requestHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
scope	property	scope?: CacheScope	Public property; its type, readonly modifier and optionality are shown in the signature.
stablePrefixChanged	property	stablePrefixChanged: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
toolSchemaHash	property	toolSchemaHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

PromptPrefixBlock

Prompt Prefix Block interface with 11 public fields or methods.

• Kind: interface
• Import: import type { PromptPrefixBlock } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface PromptPrefixBlock extends Required<Pick<PromptPrefixBlockInput, 'id' | 'type' | 'hash'>> {
    stable: boolean;
    content?: string;
    tokenEstimate?: number;
    order?: number;
    source?: string;
    templateId?: string;
    templateVersion?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
content	property	content?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
hash	property	hash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
order	property	order?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	source?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stable	property	stable: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
templateId	property	templateId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
templateVersion	property	templateVersion?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tokenEstimate	property	tokenEstimate?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
type	property	type: PromptPrefixBlockType	Public property; its type, readonly modifier and optionality are shown in the signature.

PromptPrefixBlockInput

Prompt Prefix Block Input interface with 11 public fields or methods.

• Kind: interface
• Import: import type { PromptPrefixBlockInput } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface PromptPrefixBlockInput {
    id: string;
    type: PromptPrefixBlockType;
    stable?: boolean;
    hash?: string;
    content?: string;
    tokenEstimate?: number;
    order?: number;
    source?: string;
    templateId?: string;
    templateVersion?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
content	property	content?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
hash	property	hash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
order	property	order?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	source?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stable	property	stable?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
templateId	property	templateId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
templateVersion	property	templateVersion?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tokenEstimate	property	tokenEstimate?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
type	property	type: PromptPrefixBlockType	Public property; its type, readonly modifier and optionality are shown in the signature.

PromptPrefixMetadata

Prompt Prefix Metadata interface with 7 public fields or methods.

• Kind: interface
• Import: import type { PromptPrefixMetadata } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface PromptPrefixMetadata {
    prefixHash: string;
    prefixTokenEstimate?: number;
    dynamicSuffixHash?: string;
    requestHash?: string;
    toolSchemaHash?: string;
    domainPackHash?: string;
    blocks: PromptPrefixBlock[];
}

Contract members

Member	Kind	Signature	Description
blocks	property	blocks: PromptPrefixBlock[]	Public property; its type, readonly modifier and optionality are shown in the signature.
domainPackHash	property	domainPackHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
dynamicSuffixHash	property	dynamicSuffixHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
prefixHash	property	prefixHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
prefixTokenEstimate	property	prefixTokenEstimate?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
requestHash	property	requestHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolSchemaHash	property	toolSchemaHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ProviderPrefixCacheUsage

Provider Prefix Cache Usage interface with 5 public fields or methods.

• Kind: interface
• Import: import type { ProviderPrefixCacheUsage } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export interface ProviderPrefixCacheUsage {
    source: 'provider-usage' | 'hypha-serving-cache' | 'unknown';
    inputTokens?: number;
    hitTokens?: number;
    missTokens?: number;
    hitRate?: number;
}

Contract members

Member	Kind	Signature	Description
hitRate	property	hitRate?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
hitTokens	property	hitTokens?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
inputTokens	property	inputTokens?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
missTokens	property	missTokens?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	source: "unknown" | "provider-usage" | "hypha-serving-cache"	Public property; its type, readonly modifier and optionality are shown in the signature.

CacheFailureMode

Public type alias for Cache Failure Mode; the declaration contains its complete type expression.

• Kind: type
• Import: import type { CacheFailureMode } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type CacheFailureMode = 'bypass' | 'strict';

CacheLookupResult

Public type alias for Cache Lookup Result; the declaration contains its complete type expression.

• Kind: type
• Import: import type { CacheLookupResult } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type CacheLookupResult<T = unknown> = CacheLookupHit<T> | CacheLookupMiss;

CacheMode

Public type alias for Cache Mode; the declaration contains its complete type expression.

• Kind: type
• Import: import type { CacheMode } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type CacheMode = 'off' | 'read' | 'write' | 'readwrite';

CacheScopeRequirement

Public type alias for Cache Scope Requirement; the declaration contains its complete type expression.

• Kind: type
• Import: import type { CacheScopeRequirement } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type CacheScopeRequirement = 'none' | 'user' | 'session';

CacheType

Public type alias for Cache Type; the declaration contains its complete type expression.

• Kind: type
• Import: import type { CacheType } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type CacheType = 'exact' | 'prefix-metadata' | 'semantic';

PrefixCacheChangeReason

Public type alias for Prefix Cache Change Reason; the declaration contains its complete type expression.

• Kind: type
• Import: import type { PrefixCacheChangeReason } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type PrefixCacheChangeReason = 'first_request' | 'prefix_changed' | 'tool_schema_changed' | 'domain_pack_changed' | 'dynamic_suffix_changed' | 'unchanged';

PromptPrefixBlockType

Public type alias for Prompt Prefix Block Type; the declaration contains its complete type expression.

• Kind: type
• Import: import type { PromptPrefixBlockType } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type PromptPrefixBlockType = 'system' | 'tool-schema' | 'project-context' | 'domain-pack' | 'memory' | 'prompt-template';

ServingCacheEvent

Public type alias for Serving Cache Event; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ServingCacheEvent } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type ServingCacheEvent = {
    type: 'llm.cache.lookup';
    key: string;
    provider: string;
    model: string;
    scope?: CacheScope;
    prefixCache?: PrefixCacheShapeObservation;
    runId?: string;
    stepId?: string;
} | {
    type: 'llm.cache.hit';
    key: string;
    ageMs: number;
    provider: string;
    model: string;
    scope?: CacheScope;
    prefixCache?: PrefixCacheShapeObservation;
    runId?: string;
    stepId?: string;
} | {
    type: 'llm.cache.miss';
    key: string;
    reason: ServingCacheMissReason;
    provider: string;
    model: string;
    scope?: CacheScope;
    prefixCache?: PrefixCacheShapeObservation;
    runId?: string;
    stepId?: string;
} | {
    type: 'llm.cache.write';
    key: string;
    ttlMs?: number;
    provider: string;
    model: string;
    scope?: CacheScope;
    prefixMetadata?: PromptPrefixMetadata;
    prefixCache?: PrefixCacheShapeObservation;
    providerPrefixCache?: ProviderPrefixCacheUsage;
    runId?: string;
    stepId?: string;
} | {
    type: 'llm.cache.bypass';
    reason: ServingCacheMissReason;
    operation?: 'lookup' | 'write' | 'delete' | 'trace';
    code?: string;
    key?: string;
    provider?: string;
    model?: string;
    scope?: CacheScope;
    runId?: string;
    stepId?: string;
};

ServingCacheMissReason

Public type alias for Serving Cache Miss Reason; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ServingCacheMissReason } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type ServingCacheMissReason = 'not_found' | 'expired' | 'disabled' | 'streaming' | 'no_cache' | 'mode_off' | 'read_disabled' | 'scope_missing' | 'store_unavailable' | 'entry_oversized' | 'corrupt';

ServingCacheStoreKind

Public type alias for Serving Cache Store Kind; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ServingCacheStoreKind } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type ServingCacheStoreKind = 'off' | 'noop' | 'memory' | 'sqlite' | 'redis';

ServingCacheTraceSink

Public type alias for Serving Cache Trace Sink; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ServingCacheTraceSink } from '@codesoul-co/hypha-serving-cache';
• Source module: types

Declaration

export type ServingCacheTraceSink = (event: ServingCacheEvent) => void | Promise<void>;