@codesoul-co/hypha-memory / provider-observability
模块用法
用于把外部或本地 Provider 绑定到 Hypha Port。Provider observability 模块公开 2 类、6 接口、3 类型。
从包入口导入
ts
import {
MemoryProviderTelemetry,
ObservedMemoryManagementProvider,
} from '@codesoul-co/hypha-memory';
import type {
MemoryProviderMetricSample,
MemoryProviderOperationalReport,
MemoryProviderOperationEstimate,
MemoryProviderTelemetryOptions,
MemoryProviderTelemetryPolicy,
ObservedMemoryManagementProviderOptions,
MemoryProviderCostEstimator,
MemoryProviderOperation,
} from '@codesoul-co/hypha-memory';
// 完整导出列表见下方。使用要点
- 9 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用
import type，运行时不应依赖它们。 - 2 个类提供可实例化的运行时实现；构造参数与公开方法在各自条目中完整列出。
公共导出
| Symbol | 种类 | 签名 | 说明 |
|---|---|---|---|
MemoryProviderTelemetry | 类 | new MemoryProviderTelemetry(options: MemoryProviderTelemetryOptions): MemoryProviderTelemetry | Bounded, content-free Provider telemetry with quota admission and SLO evaluation. Samples retain only operation metadata; requests, responses, scopes and content are never stored. |
ObservedMemoryManagementProvider | 类 | new ObservedMemoryManagementProvider(options: ObservedMemoryManagementProviderOptions): ObservedMemoryManagementProvider | Provider decorator that instruments every canonical operation without changing Provider APIs. |
MemoryProviderMetricSample | 接口 | interface MemoryProviderMetricSample | Memory Provider Metric Sample 接口，共包含 8 个公开字段或方法。 |
MemoryProviderOperationalReport | 接口 | interface MemoryProviderOperationalReport | Memory Provider Operational Report 接口，共包含 9 个公开字段或方法。 |
MemoryProviderOperationEstimate | 接口 | interface MemoryProviderOperationEstimate | Memory Provider Operation Estimate 接口，共包含 2 个公开字段或方法。 |
MemoryProviderTelemetryOptions | 接口 | interface MemoryProviderTelemetryOptions | Memory Provider Telemetry Options 接口，共包含 3 个公开字段或方法。 |
MemoryProviderTelemetryPolicy | 接口 | interface MemoryProviderTelemetryPolicy | Memory Provider Telemetry Policy 接口，共包含 4 个公开字段或方法。 |
ObservedMemoryManagementProviderOptions | 接口 | interface ObservedMemoryManagementProviderOptions | Observed Memory Management Provider Options 接口，共包含 3 个公开字段或方法。 |
MemoryProviderCostEstimator | 类型 | type MemoryProviderCostEstimator = (operation: MemoryProviderOperation, request: unknown) => MemoryProviderOperationEstimate | Memory Provider Cost Estimator 公共类型别名；完整类型表达式见声明。 |
MemoryProviderOperation | 类型 | type MemoryProviderOperation = 'add' | 'search' | 'get' | 'list' | 'update' | 'delete' | 'history' | 'health' | Memory Provider Operation 公共类型别名；完整类型表达式见声明。 |
MemoryProviderOperationOutcome | 类型 | type MemoryProviderOperationOutcome = 'succeeded' | 'failed' | 'quota_rejected' | Memory Provider Operation Outcome 公共类型别名；完整类型表达式见声明。 |
MemoryProviderTelemetry
Bounded, content-free Provider telemetry with quota admission and SLO evaluation. Samples retain only operation metadata; requests, responses, scopes and content are never stored.
- 种类: 类
- 导入:
import { MemoryProviderTelemetry } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export declare class MemoryProviderTelemetry {
constructor(options: MemoryProviderTelemetryOptions);
begin(providerId: string, operation: MemoryProviderOperation, estimate?: MemoryProviderOperationEstimate): Reservation;
snapshot(providerId: string): MemoryProviderOperationalReport;
}公开成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
begin | 方法 | begin(providerId: string, operation: MemoryProviderOperation, estimate?: MemoryProviderOperationEstimate): Reservation | 公开方法；参数与返回类型以签名列为准。 |
constructor | 构造函数 | (options: MemoryProviderTelemetryOptions): MemoryProviderTelemetry | 创建该类的实例。 |
snapshot | 方法 | snapshot(providerId: string): MemoryProviderOperationalReport | 公开方法；参数与返回类型以签名列为准。 |
ObservedMemoryManagementProvider
Provider decorator that instruments every canonical operation without changing Provider APIs.
- 种类: 类
- 导入:
import { ObservedMemoryManagementProvider } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export declare class ObservedMemoryManagementProvider implements MemoryManagementProvider {
readonly id: string;
constructor(options: ObservedMemoryManagementProviderOptions);
capabilities(): Promise<import("./contracts").MemoryManagementCapabilities>;
add(request: MemoryAddRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult>;
search(request: ManagedMemorySearchRequest, signal?: AbortSignal): Promise<ManagedMemorySearchResult[]>;
get(request: MemoryGetRequest, signal?: AbortSignal): Promise<import("./contracts").ManagedMemoryRecord<unknown> | null>;
list(request: MemoryListRequest, signal?: AbortSignal): Promise<MemoryListResult>;
update(request: ManagedMemoryUpdateRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult>;
delete(request: ManagedMemoryDeleteRequest, signal?: AbortSignal): Promise<ManagedMemoryDeleteResult>;
history(request: MemoryHistoryRequest, signal?: AbortSignal): Promise<MemoryVersion[]>;
health(): Promise<ProviderHealth>;
close(): Promise<void>;
}公开成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
add | 方法 | add(request: MemoryAddRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult> | 公开方法；参数与返回类型以签名列为准。 |
capabilities | 方法 | capabilities(): Promise<import("./contracts").MemoryManagementCapabilities> | 公开方法；参数与返回类型以签名列为准。 |
close | 方法 | close(): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
constructor | 构造函数 | (options: ObservedMemoryManagementProviderOptions): ObservedMemoryManagementProvider | 创建该类的实例。 |
delete | 方法 | delete(request: ManagedMemoryDeleteRequest, signal?: AbortSignal): Promise<ManagedMemoryDeleteResult> | 公开方法；参数与返回类型以签名列为准。 |
get | 方法 | get(request: MemoryGetRequest, signal?: AbortSignal): Promise<import("./contracts").ManagedMemoryRecord<unknown> | null> | 公开方法；参数与返回类型以签名列为准。 |
health | 方法 | health(): Promise<ProviderHealth> | 公开方法；参数与返回类型以签名列为准。 |
history | 方法 | history(request: MemoryHistoryRequest, signal?: AbortSignal): Promise<MemoryVersion[]> | 公开方法；参数与返回类型以签名列为准。 |
id | 属性 | readonly id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
list | 方法 | list(request: MemoryListRequest, signal?: AbortSignal): Promise<MemoryListResult> | 公开方法；参数与返回类型以签名列为准。 |
search | 方法 | search(request: ManagedMemorySearchRequest, signal?: AbortSignal): Promise<ManagedMemorySearchResult[]> | 公开方法；参数与返回类型以签名列为准。 |
update | 方法 | update(request: ManagedMemoryUpdateRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult> | 公开方法；参数与返回类型以签名列为准。 |
MemoryProviderMetricSample
Memory Provider Metric Sample 接口，共包含 8 个公开字段或方法。
- 种类: 接口
- 导入:
import type { MemoryProviderMetricSample } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export interface MemoryProviderMetricSample {
providerId: string;
operation: MemoryProviderOperation;
outcome: MemoryProviderOperationOutcome;
latencyMs: number;
occurredAt: string;
costUnits?: number;
storedBytesDelta?: number;
errorCode?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
costUnits | 属性 | costUnits?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
errorCode | 属性 | errorCode?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
latencyMs | 属性 | latencyMs: number | 公开属性；类型、只读和可选状态以签名列为准。 |
occurredAt | 属性 | occurredAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
operation | 属性 | operation: MemoryProviderOperation | 公开属性；类型、只读和可选状态以签名列为准。 |
outcome | 属性 | outcome: MemoryProviderOperationOutcome | 公开属性；类型、只读和可选状态以签名列为准。 |
providerId | 属性 | providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
storedBytesDelta | 属性 | storedBytesDelta?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
MemoryProviderOperationalReport
Memory Provider Operational Report 接口，共包含 9 个公开字段或方法。
- 种类: 接口
- 导入:
import type { MemoryProviderOperationalReport } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export interface MemoryProviderOperationalReport {
providerId: string;
window: {
startedAt: string;
endedAt: string;
durationMs: number;
};
operations: {
total: number;
succeeded: number;
failed: number;
quotaRejected: number;
inFlight: number;
byOperation: Partial<Record<MemoryProviderOperation, number>>;
};
availability: number | null;
latencyMs: {
p50: number | null;
p95: number | null;
p99: number | null;
max: number | null;
};
cost: {
measuredUnits: number;
unpricedOperations: number;
complete: boolean;
};
storage: {
measuredBytes: number;
};
quota: {
maxOperations?: number;
remainingOperations?: number;
maxCostUnits?: number;
remainingCostUnits?: number;
maxStoredBytes?: number;
remainingStoredBytes?: number;
};
slo: {
status: 'met' | 'breached' | 'insufficient_data';
reasons: string[];
minimumOperations: number;
availabilityTarget?: number;
latencyP95Ms?: number;
};
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
availability | 属性 | availability: number | 公开属性；类型、只读和可选状态以签名列为准。 |
cost | 属性 | cost: { measuredUnits: number; unpricedOperations: number; complete: boolean; } | 公开属性；类型、只读和可选状态以签名列为准。 |
latencyMs | 属性 | latencyMs: { p50: number | null; p95: number | null; p99: number | null; max: number | null; } | 公开属性；类型、只读和可选状态以签名列为准。 |
operations | 属性 | operations: { total: number; succeeded: number; failed: number; quotaRejected: number; inFlight: number; byOperation: Partial<Record<MemoryProviderOperation, number>>; } | 公开属性；类型、只读和可选状态以签名列为准。 |
providerId | 属性 | providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
quota | 属性 | quota: { maxOperations?: number; remainingOperations?: number; maxCostUnits?: number; remainingCostUnits?: number; maxStoredBytes?: number; remainingStoredBytes?: number; } | 公开属性；类型、只读和可选状态以签名列为准。 |
slo | 属性 | slo: { status: "met" | "breached" | "insufficient_data"; reasons: string[]; minimumOperations: number; availabilityTarget?: number; latencyP95Ms?: number; } | 公开属性；类型、只读和可选状态以签名列为准。 |
storage | 属性 | storage: { measuredBytes: number; } | 公开属性；类型、只读和可选状态以签名列为准。 |
window | 属性 | window: { startedAt: string; endedAt: string; durationMs: number; } | 公开属性；类型、只读和可选状态以签名列为准。 |
MemoryProviderOperationEstimate
Memory Provider Operation Estimate 接口，共包含 2 个公开字段或方法。
- 种类: 接口
- 导入:
import type { MemoryProviderOperationEstimate } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export interface MemoryProviderOperationEstimate {
costUnits?: number;
storedBytesDelta?: number;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
costUnits | 属性 | costUnits?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
storedBytesDelta | 属性 | storedBytesDelta?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
MemoryProviderTelemetryOptions
Memory Provider Telemetry Options 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { MemoryProviderTelemetryOptions } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export interface MemoryProviderTelemetryOptions {
defaultPolicy: MemoryProviderTelemetryPolicy;
providerPolicies?: Record<string, MemoryProviderTelemetryPolicy>;
now?: () => Date;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
defaultPolicy | 属性 | defaultPolicy: MemoryProviderTelemetryPolicy | 公开属性；类型、只读和可选状态以签名列为准。 |
now | 方法 | now?(): Date | 公开方法；参数与返回类型以签名列为准。 |
providerPolicies | 属性 | providerPolicies?: Record<string, MemoryProviderTelemetryPolicy> | 公开属性；类型、只读和可选状态以签名列为准。 |
MemoryProviderTelemetryPolicy
Memory Provider Telemetry Policy 接口，共包含 4 个公开字段或方法。
- 种类: 接口
- 导入:
import type { MemoryProviderTelemetryPolicy } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export interface MemoryProviderTelemetryPolicy {
windowMs: number;
maxSamples?: number;
quota?: {
maxOperations?: number;
maxCostUnits?: number;
maxStoredBytes?: number;
};
slo?: {
minimumOperations?: number;
availabilityTarget?: number;
latencyP95Ms?: number;
};
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
maxSamples | 属性 | maxSamples?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
quota | 属性 | quota?: { maxOperations?: number; maxCostUnits?: number; maxStoredBytes?: number; } | 公开属性；类型、只读和可选状态以签名列为准。 |
slo | 属性 | slo?: { minimumOperations?: number; availabilityTarget?: number; latencyP95Ms?: number; } | 公开属性；类型、只读和可选状态以签名列为准。 |
windowMs | 属性 | windowMs: number | 公开属性；类型、只读和可选状态以签名列为准。 |
ObservedMemoryManagementProviderOptions
Observed Memory Management Provider Options 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { ObservedMemoryManagementProviderOptions } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export interface ObservedMemoryManagementProviderOptions {
provider: MemoryManagementProvider;
telemetry: MemoryProviderTelemetry;
estimate?: MemoryProviderCostEstimator;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
estimate | 方法 | estimate?(operation: MemoryProviderOperation, request: unknown): MemoryProviderOperationEstimate | 公开方法；参数与返回类型以签名列为准。 |
provider | 属性 | provider: MemoryManagementProvider | 公开属性；类型、只读和可选状态以签名列为准。 |
telemetry | 属性 | telemetry: MemoryProviderTelemetry | 公开属性；类型、只读和可选状态以签名列为准。 |
MemoryProviderCostEstimator
Memory Provider Cost Estimator 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { MemoryProviderCostEstimator } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export type MemoryProviderCostEstimator = (operation: MemoryProviderOperation, request: unknown) => MemoryProviderOperationEstimate;MemoryProviderOperation
Memory Provider Operation 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { MemoryProviderOperation } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export type MemoryProviderOperation = 'add' | 'search' | 'get' | 'list' | 'update' | 'delete' | 'history' | 'health';MemoryProviderOperationOutcome
Memory Provider Operation Outcome 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { MemoryProviderOperationOutcome } from '@codesoul-co/hypha-memory'; - 源码模块:
provider-observability
声明
text
export type MemoryProviderOperationOutcome = 'succeeded' | 'failed' | 'quota_rejected';