Vertiq architecture

Architecture

Vertiq has three components: Vertiq LM, the decision engine and the recursive self-improvement loop. The decision engine runs inside the host application rather than as a separate service: the host loads its records into a common data contract, calls Vertiq and stores the resulting models, which are plain dictionaries. The engine does not import web frameworks, ORMs or HTTP clients; tests/test_boundary.py enforces this.

Records are mapped once to a common data contract. Analysis tasks train candidate models, plugins add domain features, and the evaluation gate promotes a candidate only if it outperforms both the rule-based baseline and the production model on held-out entities.

Design principles

Structural intelligence

Language-model output is constrained by verification against the data.

Local schema resolution. Vertiq LM, a 4-billion-parameter model fine-tuned with LoRA, proposes a mapping from the column headers and sample rows. It runs on the user's machine; source data is not sent to an external service.
Deterministic validation. vertiq.mapping.repair checks the proposal against the rows: names are matched to existing columns, roles are checked against value types and the date format is inferred. It never introduces a column that does not exist.
Bounded data contract. Every record is expressed as an entity, a timestamp, an event type, a value and attributes. Rows that fail validation are reported to the caller, so models train only on records that loaded.

Causal measurement

Intervention effects are estimated against control groups rather than inferred from correlation.

Control-group uplift. vertiq.uplift compares treated entities with a randomly held-out group over the same window and ranks entities by estimated incremental effect. In the benchmark it estimated a planted −20% offer effect at -20.2%.
Configurable horizons. window_days sets the prediction horizon, cutoffs the number of historical training points and history the event types used as inputs, so each task matches the operating cycle of the industry.
Small footprint. The decision engine has no third-party dependencies and no network layer. It runs wherever Python 3.10 runs; the full benchmark suite completes in 196 seconds on a laptop using 4 cores.

Defensive deployment

A candidate model is treated as unproven until it has been evaluated.

Held-out evaluation. Candidates are scored on entities excluded from training, using features built only from events recorded before each cutoff.
Champion–challenger gate. A candidate must outperform the rule-based baseline and the production model, and its gain over the baseline must be clear at 90% confidence by default. min_gain sets a required margin: an AUC margin for event tasks and a relative error reduction for value tasks.
Explicit rejection. A rejected candidate returns status "kept" with the reason, such as the AUC it reached against the required threshold. The production model remains in service.

Principle	Mechanism	Configuration	Operational value
Structural intelligence	Local mapping proposal, validated against the rows	Fine-tune Vertiq LM on your naming conventions (lm/); vertiq.mapping.repair	Source data stays on premises; new sources are onboarded without hand-written mappings
Causal measurement	Control-group uplift and point-in-time tasks	window_days, cutoffs and history in vertiq.tasks; a hold-out share on every campaign	Intervention effects are measured rather than assumed; horizons match each industry's cycle
Defensive deployment	Entity-level holdout with champion–challenger comparison	min_gain in vertiq.tasks and vertiq.harness	Weaker or unstable candidates are not promoted; the production model stays in service

Methods. The methods are established and deliberately transparent: regularised logistic and linear regression with per-group offsets, gradient-boosted trees, two-model and boosted uplift estimators, matching and augmented inverse-probability weighting for observational effects, sequential tests, Benjamini–Hochberg false-discovery control and rule-based checks. Vertiq's contribution is the structure around them: point-in-time features, entity-level holdout, control-group measurement, the promotion gate and local mapping. Stronger estimators can be registered through register_learner and are evaluated by the same gate.

Modules

Module	Responsibility
`mapping`	Maps a source table to the data contract; repair() validates column names, value types and the date format
`contract`	Entity, Event, Action and Dataset: the common structure that every task reads
`tasks`	predict_event and predict_value for any event type, with contributing factors for each score
`harness`	Evaluation gate: entity-level holdout, baseline comparison and production-model comparison
`plugins`	Registration of domain features, rules and custom learners
`rules`	Declarative checks: repeat, overdue, exceeds and too_short
`churn · uplift · value`	Customer retention, intervention uplift, transaction value and campaign revenue
`affinity · offers`	Product affinity, next likely product, replenishment intervals and threshold offers
`insights`	Segment patterns filtered with false-discovery-rate control
`inventory`	Reorder points, slow-moving stock, new items and margins
`learn`	Regularised logistic and linear models, AUC, Brier score, calibration and Benjamini–Hochberg
`verticals`	Industry profiles: time windows, terminology and currency
`boost`	Gradient-boosted trees for non-linear effects, with path-based contributing factors
`survival`	Kaplan–Meier time-to-event estimates with censoring and per-entity rhythm
`causal`	Matched-cohort ATT and cross-fitted doubly robust (AIPW) ATE, with balance, overlap and intervals
`design`	Experiment sizing, minimum detectable effects and next-step recommendations
`sequential`	Wald's SPRT for one rate and a mixture SPRT for two live arms; a result can block a promotion
`autotune`	Gated search over task settings and candidate features, scored by cross-validation on training entities
`patterns`	Automatic search for tested patterns across all features of a dataset, with false-discovery control
`report`	python -m vertiq.report config.json: exported tables to a written report
`tables`	Mapping and join proposals from the values alone, checked by mapping.repair
`menu`	Candidate features as reviewable specs (count, since, share, sum, group rate, attribute); no generated code
`category`	Which of several outcomes comes next, one model per outcome, gated on macro AUC against the past mix
`plan`	Choice of action per entity under a budget from measured effects, costs and outcome values
`guard`	Allow, hold or block for proposed actions, from measured effects, intervals and rule flags
`diagnose`	Rate and mix effects of a change between two periods, by group, with false-discovery control
`summary`	The last period against the previous one, with chance-adjusted changes
`drift`	Population Stability Index for inputs and scores, and accuracy on new outcomes
`sequences`	Lagged A-then-B patterns between consecutive events, filtered for false discoveries
`profiles`	Precomputed scores and factors for serving, with staleness checks
`narrate`	Plain-language descriptions of results, and a check that rejects rewrites with numbers not in the result
`dataset · research · trends`	Training data export for language models, cited external tactics and trend matching

Extensibility

Features and rules are registered under a pack name and selected with pack=. Custom learners require fit, predict, to_dict and from_dict; per-group offsets and contributing factors are optional.

Deployment footprint

Python 3.10 or later with no third-party dependencies. The complete benchmark suite runs in 196 seconds on a laptop using 4 cores.

Integration

The host application owns data access, storage and serving. The decision engine has no knowledge of the product that embeds it.