FeatLock 1.0 API Documentation

Overview

FEATSRV delivers a five-layer feature store: temporal Parquet / SCD Type 2 sources, Feast registry with Redis online materialisation, FastAPI serving, dual Dask/PySpark PIT engines, and the FeatLock operator console. Every online and offline value is requested against an event_timestamp so future information cannot leak into training or scoring rows.

Online Redis — sub-10 ms policy and claim feature fetch
PIT training — as-of joins on uploaded target CSVs
Leakage audit — scan datasets for temporal traps
Feature importance — attribution across actuarial models

Authentication

Requests accept an x-api-key header. The public demo console uses a research prototype key suitable for evaluation traffic. Production deployments should rotate keys via environment configuration (FEATSRV_DEMO_API_KEY / upstream backend policy).

x-api-key: <your-api-key>
Accept: application/json

Same-origin proxy

Browser clients should call the Zi Humana proxy at /api/featsrv/*. The route forwards to the FEATSRV backend and injects the demo key when none is supplied. Multipart uploads (PIT training, leakage audit) preserve the original Content-Type boundary.

GET  /api/featsrv/health
GET  /api/featsrv/online/policy/{policy_id}
GET  /api/featsrv/online/claim/{claim_id}
POST /api/featsrv/offline
POST /api/featsrv/pit-training
POST /api/featsrv/leakage-audit
GET  /api/featsrv/feature-importance

Endpoints

Method	Path	Purpose
`GET`	`/health`	Uptime and Redis / Feast dependency checks
`GET`	`/online/policy/{id}`	Real-time policy features from Redis
`GET`	`/online/claim/{id}`	Real-time claim features from Redis
`POST`	`/offline`	Batch offline feature retrieval
`POST`	`/pit-training`	Point-in-time join on uploaded target CSV
`POST`	`/leakage-audit`	Scan datasets for temporal leakage traps
`GET`	`/feature-importance`	Model attribution scores

Online lookups

Online endpoints return the latest materialised feature payload for a policy or claim entity ID. Typical latency is under 10 ms when Redis is healthy.

Example

GET /api/featsrv/online/policy/POL-4471
x-api-key: <your-api-key>

{
  "entity_type": "policy",
  "entity_id": "POL-4471",
  "features": {
    "initial_premium": 1240.5,
    "region": "NE",
    "address": "…",
    "inception_date": "2024-03-12"
  }
}

POST /pit-training

Upload a target CSV of entity IDs and event timestamps. The server performs a point-in-time as-of join against SCD Type 2 feature sources (Feast/Dask or PySpark) and returns a leakage-free training frame preview.

POST /api/featsrv/pit-training
Content-Type: multipart/form-data
x-api-key: <your-api-key>

file=@targets.csv

POST /leakage-audit

Upload a dataset to scan for temporal leakage traps — feature timestamps later than the event timestamp they would be joined against. Findings power the Risk & Leakage Audit panel in FeatLock 1.0.

POST /api/featsrv/leakage-audit
Content-Type: multipart/form-data
x-api-key: <your-api-key>

file=@candidate_features.csv

GET /feature-importance

Returns attribution scores across underwriting, pricing, and fraud model tasks — the same series rendered in the FeatLock Feature Importance tab.

Console panels

The FeatLock 1.0 console mirrors the FEATSRV CLI services:

00 Overview — adoption volume, activity log, service mix
01 Data lineage — source → PIT store → model consumers
05 Risk & leakage — portfolio risk and audit findings
06 Feature importance — model attribution
01/04 Training & batch — PIT and offline previews
02/03 Online lookups — live Redis policy/claim fetch

Point-in-time feature serving fundamentals