Files
0pt/src/features/feast-adapter.ts
T
Simon AxelssonandClaude Fable 5 c47e3b468e
CI (SIAX Cloud) / integration (push) Failing after 22s
CI (SIAX Cloud) / security (push) Successful in 22s
Security Scan (SIAX Cloud) / security (push) Successful in 21s
CI (SIAX Cloud) / quality (push) Successful in 43s
CI (SIAX Cloud) / integration (pull_request) Failing after 3s
CI (SIAX Cloud) / security (pull_request) Successful in 17s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 16s
CI (SIAX Cloud) / quality (pull_request) Successful in 43s
test(integration)+ci+docs: live OpenSearch/ClickHouse suites, CI service containers, STATUS.md (§56)
- tests/integration/: 10 tests against REAL OpenSearch 2.11 (tenant
  isolation, purpose/rights filters, generation rebuild/rollback,
  projection-disaster rebuild §68) + REAL ClickHouse 24.8 (tenant-isolated
  metric DSL, TTL schema, injection-surface refusals). Honest skip without
  env - and CI fails hard if the suites skip instead of running.
- .gitea/workflows/ci.yml: new blocking 'integration' job with
  self-identifying service containers (st0re ci.yml's measured
  alias-collision discipline: run-unique cluster.name / credentials,
  getent-enumerated IP selection, no-match = hard fail).
- STATUS.md: full 8-level Master-DoD classification per capability incl.
  the honest gaps blocking PRODUCTION_READY.
- dependency-mode: NEXT_PHASE=phase-production-build is not a serving
  runtime (next build page-data collection must compile; guard re-arms at
  boot) - pinned by contract test.
- docs/02-architecture.md: superseded the accurate-but-now-fixed 'every
  client runs against its mock' paragraph; .env.example: client URLs now
  actually read from env + new P0 backend vars.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-31 16:56:33 +02:00

208 lines
7.7 KiB
TypeScript

/**
* 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;
}
}