fix(recovery): restore source removed by production documentation merge
This commit is contained in:
@@ -0,0 +1,207 @@
|
||||
/**
|
||||
* src/features/feast-adapter.ts
|
||||
* ==============================
|
||||
* Feature capability contract + Feast adapter (Master-DoD §10 Feature
|
||||
* capability: Feature definitions, Feast adapter, offline/online,
|
||||
* point-in-time correctness, materialization, versioning, feature lineage).
|
||||
*
|
||||
* What is REAL here vs. contract-only — stated plainly (§56):
|
||||
* - Feature-view registry with versioning: REAL (in-process registry,
|
||||
* versioned like QualityService rules).
|
||||
* - get-online-features: REAL HTTP adapter against Feast's feature server
|
||||
* (`POST /get-online-features`, Feast's documented REST contract).
|
||||
* Contract-tested against a recording double; needs a live Feast for
|
||||
* INTEGRATION_TESTED.
|
||||
* - materialize / get-historical (offline, point-in-time): DELEGATION
|
||||
* CONTRACTS ONLY — Feast materialization and offline retrieval are
|
||||
* Python-side operations; 0pt submits N0D jobs ("0pt.features.materialize",
|
||||
* "0pt.features.get_historical") for 0pt-motor to execute. This adapter
|
||||
* never fakes a result for them.
|
||||
*/
|
||||
import { SiaxError, siaxErrorCodeForUpstreamStatus } from "../platform/errors";
|
||||
import type { N0dClient, N0dJob } from "../clients/n0d-client";
|
||||
|
||||
/** A versioned 0pt feature-view definition (maps to a Feast FeatureView). */
|
||||
export interface FeatureViewDefinition {
|
||||
feature_view: string;
|
||||
tenant_id: string;
|
||||
project_id: string;
|
||||
/** Entity join keys, e.g. ["org_nr"]. */
|
||||
entities: string[];
|
||||
features: { name: string; dtype: "int64" | "float64" | "string" | "bool" | "timestamp" }[];
|
||||
/** Source dataset ref this view materializes from (canonical 0pt ref). */
|
||||
source_dataset_ref: string;
|
||||
ttl_hours?: number;
|
||||
version: number;
|
||||
created_at: string;
|
||||
}
|
||||
|
||||
export type RegisterFeatureViewInput = Omit<FeatureViewDefinition, "version" | "created_at">;
|
||||
|
||||
export interface OnlineFeaturesRequest {
|
||||
tenant_id: string;
|
||||
feature_view: string;
|
||||
features: string[];
|
||||
/** Entity rows, e.g. [{ org_nr: "5560360793" }]. */
|
||||
entities: Record<string, (string | number)[]>;
|
||||
}
|
||||
|
||||
export interface OnlineFeaturesResult {
|
||||
feature_names: string[];
|
||||
results: { values: unknown[]; statuses: string[] }[];
|
||||
}
|
||||
|
||||
export class FeatureService {
|
||||
private readonly views = new Map<string, FeatureViewDefinition>();
|
||||
private readonly history = new Map<string, FeatureViewDefinition[]>();
|
||||
|
||||
constructor(
|
||||
private readonly opts: {
|
||||
/** Feast feature-server base URL (online path). */
|
||||
feastServerUrl?: string;
|
||||
n0dClient?: N0dClient;
|
||||
timeoutMs?: number;
|
||||
} = {}
|
||||
) {}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Registry (versioned)
|
||||
// -----------------------------------------------------------------------
|
||||
registerFeatureView(input: RegisterFeatureViewInput): FeatureViewDefinition {
|
||||
const key = `${input.tenant_id}:${input.feature_view}`;
|
||||
const current = this.views.get(key);
|
||||
if (current) {
|
||||
const hist = this.history.get(key) ?? [];
|
||||
hist.push(current);
|
||||
this.history.set(key, hist);
|
||||
}
|
||||
const def: FeatureViewDefinition = {
|
||||
...input,
|
||||
version: (current?.version ?? 0) + 1,
|
||||
created_at: new Date().toISOString(),
|
||||
};
|
||||
this.views.set(key, def);
|
||||
return def;
|
||||
}
|
||||
|
||||
getFeatureView(tenantId: string, featureView: string): FeatureViewDefinition {
|
||||
const def = this.views.get(`${tenantId}:${featureView}`);
|
||||
if (!def) throw new SiaxError("NOT_FOUND", "0pt.features", `feature view ${featureView} not found`);
|
||||
return def;
|
||||
}
|
||||
|
||||
getFeatureViewVersions(tenantId: string, featureView: string): FeatureViewDefinition[] {
|
||||
const current = this.getFeatureView(tenantId, featureView);
|
||||
return [...(this.history.get(`${tenantId}:${featureView}`) ?? []), current];
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Online path — REAL Feast feature-server adapter
|
||||
// -----------------------------------------------------------------------
|
||||
async getOnlineFeatures(req: OnlineFeaturesRequest): Promise<OnlineFeaturesResult> {
|
||||
this.getFeatureView(req.tenant_id, req.feature_view); // tenant + existence gate
|
||||
if (!this.opts.feastServerUrl) {
|
||||
throw new SiaxError(
|
||||
"DEPENDENCY_UNAVAILABLE",
|
||||
"feast",
|
||||
"no Feast feature server configured (FEAST_SERVER_URL)"
|
||||
);
|
||||
}
|
||||
let res: Response;
|
||||
try {
|
||||
res = await fetch(`${this.opts.feastServerUrl.replace(/\/+$/, "")}/get-online-features`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
// Feast REST contract: features as "view:feature" refs.
|
||||
features: req.features.map((f) => `${req.feature_view}:${f}`),
|
||||
entities: req.entities,
|
||||
}),
|
||||
signal: AbortSignal.timeout(this.opts.timeoutMs ?? 10_000),
|
||||
});
|
||||
} catch (cause) {
|
||||
throw new SiaxError("DEPENDENCY_UNAVAILABLE", "feast", "feast feature server unreachable", { cause });
|
||||
}
|
||||
if (!res.ok) {
|
||||
throw new SiaxError(
|
||||
siaxErrorCodeForUpstreamStatus(res.status),
|
||||
"feast",
|
||||
`get-online-features → HTTP ${res.status}`
|
||||
);
|
||||
}
|
||||
const body = (await res.json()) as {
|
||||
metadata?: { feature_names?: string[] };
|
||||
results?: { values: unknown[]; statuses: string[] }[];
|
||||
};
|
||||
return {
|
||||
feature_names: body.metadata?.feature_names ?? [],
|
||||
results: body.results ?? [],
|
||||
};
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Offline paths — N0D delegation contracts (never faked locally)
|
||||
// -----------------------------------------------------------------------
|
||||
async materialize(input: {
|
||||
tenant_id: string;
|
||||
project_id: string;
|
||||
feature_view: string;
|
||||
start_time: string;
|
||||
end_time: string;
|
||||
correlation_id?: string;
|
||||
}): Promise<N0dJob> {
|
||||
const def = this.getFeatureView(input.tenant_id, input.feature_view);
|
||||
return this.requireN0d().createJob({
|
||||
tenant_id: input.tenant_id,
|
||||
project_id: input.project_id,
|
||||
job_type: "0pt.features.materialize",
|
||||
capability_id: "0pt.features.materialize.v1",
|
||||
requested_by_app_id: "0pt",
|
||||
requested_by_actor_id: "svc_0pt",
|
||||
output_artifact_type: "feature_materialization",
|
||||
requires_backbone: false,
|
||||
requires_gpu: false,
|
||||
required_node_roles: ["compute_general"],
|
||||
resource_profile: "standard",
|
||||
risk_level: "L2",
|
||||
correlation_id: input.correlation_id,
|
||||
idempotency_key: `feat-mat:${input.feature_view}@${def.version}:${input.start_time}:${input.end_time}`,
|
||||
});
|
||||
}
|
||||
|
||||
/** Point-in-time correct historical retrieval — Feast offline via 0pt-motor. */
|
||||
async getHistorical(input: {
|
||||
tenant_id: string;
|
||||
project_id: string;
|
||||
feature_view: string;
|
||||
features: string[];
|
||||
/** ST0RE artifact ref of the entity dataframe (with event timestamps). */
|
||||
entity_df_artifact_ref: string;
|
||||
correlation_id?: string;
|
||||
}): Promise<N0dJob> {
|
||||
this.getFeatureView(input.tenant_id, input.feature_view);
|
||||
return this.requireN0d().createJob({
|
||||
tenant_id: input.tenant_id,
|
||||
project_id: input.project_id,
|
||||
job_type: "0pt.features.get_historical",
|
||||
capability_id: "0pt.features.get_historical.v1",
|
||||
requested_by_app_id: "0pt",
|
||||
requested_by_actor_id: "svc_0pt",
|
||||
input_artifact_ids: [input.entity_df_artifact_ref],
|
||||
output_artifact_type: "feature_historical_result",
|
||||
requires_backbone: false,
|
||||
requires_gpu: false,
|
||||
required_node_roles: ["compute_general"],
|
||||
resource_profile: "standard",
|
||||
risk_level: "L2",
|
||||
correlation_id: input.correlation_id,
|
||||
});
|
||||
}
|
||||
|
||||
private requireN0d(): N0dClient {
|
||||
if (!this.opts.n0dClient) {
|
||||
throw new SiaxError("DEPENDENCY_UNAVAILABLE", "n0d", "no N0D client configured for feature jobs");
|
||||
}
|
||||
return this.opts.n0dClient;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user