veil-quant

English documentation | 简体中文

Veil is a quant research harness for Pi. It leaves ordinary coding alone, then adds a contract, evidence, gates, memory, and reproduction when a result is promoted.

The aim is simple: a researcher should be able to inspect and continue the work without reverse engineering the original chat and working tree.

Registry install after publication: pi install npm:veil-quant. During source development, run npm install at the repository root and use pi install ./packages/veil-agent instead.

Veil libraries support Node 20.10 through 29. The repository-pinned Pi 0.84.1 model runner requires Node 22.19 or newer.

What it adds

| Surface | Behavior | | --- | --- | | veil-data | Requires as_of, reads registered CSV/Parquet through the mandatory temporal guard, and optionally exports guarded Arrow | | veil-backtest | Runs structural promotion and, when requested, pricing, the eight gates, and Experiment archival | | veil-memory | Registers hypotheses and retrieves runs, Experiments, families, and trial evidence | | tool_call | Fails safe for malformed calls entering Veil's data or promotion surfaces | | tool_result | Appends non-blocking full-sample, future-function, and survivorship advisories | | Commands | /veil-brief, /veil-hypothesis, /veil-promote, /veil-reproduce, /veil-family | | Resources | veil-research-loop skill, factor/promotion templates, and research-plan/log prompts |

The extension auto-captures the first brief and hypothesis with Pi's durable session entry id and timestamp. It restores only entries on the active branch, so Pi forks naturally become research lineage.

Project profile

The default v0.1 file profile reads .veil/project.yaml from Pi's working directory:

format: veil.project.v0
datasets:
  - dataset: my-prices
    adapter: adapters/prices.yaml
    root: null
    root_env: VEIL_PRICES_ROOT
runtimes:
  - id: veil-node
    constraints:
      - ">=20.10.0,<30"
promotion_concurrency: 2
stage4:
  cost_models:
    - kind: linear-bps
      reference: equities-10bps
      basis_points: 10
  null_generators:
    - kind: centered-block-bootstrap
      reference: daily-centered-blocks
      replications: 1024
      block_length: 5
      seed: 20260813

Physical roots remain local capabilities. Tool results, Pi entries, run evidence, and Markdown logs contain only project-relative references and content identities. The default loader supports CSV and Parquet; use root: . with root_env: null when the locator is relative to the project itself. Custom backends can supply a VeilProjectLoader without changing tool contracts.

Claim boundary

A request without stage4 writes a researchRunId, complete structural evidence, and an explicitly unverified promotion candidate. A complete request additionally replays retained evidence, prices the locked method and cost model, audits trials, runs the standard policy, archives exact code and read sets, and appends accepted, degraded, or rejected Experiment memory.

The Stage 4 request locks a long-only or long/short quantile portfolio. Equal sizing uses no weight column; trailing-information sizing names a strictly positive artifact-output column, so portfolio construction cannot be substituted after OOS results are visible.

Known PIT_UNSAFE, unverified point-in-time, assumed-availability, and survivorship-biased or unknown declarations remain available for exploration but are rejected at promotion with C1. Do not change an adapter guarantee merely to pass that boundary.

The engine freezes this chain before a metric can become a claim:

guarded read → artifact → per-decision contract → registration chronology
             → unverified candidate → pricing/gates → Experiment → exact reproduction

See the repository quickstart and cold single-agent example, and Stage 4 agent example.

Extension boundary

Veil does not fork Pi. If an invariant cannot be enforced from an extension, the enforcement belongs in @veilquant/engine. Exploration heuristics never become blockers, and the extension does not claim to sandbox a user's shell or defend against a deliberately malicious agent.