The manual · v1.9.1

RegimeLens Documentation

Everything from installing the engine to writing your own overlay recipes. This manual describes the planned release; RegimeLens is not on sale yet and downloads open with early access.

1.1Install & first run

1. Download: downloads open with early access. See the download page.
2. Start RegimeLens. The first launch starts the RegimeLens core engine as a background service on localhost:8787 and opens the app in guest mode.
3. Activate (optional now, required for saving): Settings → Licence → paste the licence you receive with early access. The planned licence covers 3 devices.
4. Add a FRED key (free, see below) and a price connector. You can plot the shipped recipes immediately.

1.2Your first overlay chart

Open XAUUSD (or any symbol your connector supports), press O and tick cpi_yoy. The overlay pulls CPIAUCSL from FRED, computes the 12-month change, shifts each point to its BLS release date and draws it normalised onto the visible window. Press E to toggle event markers. The correlation panel below the chart fills in as soon as one overlay is active.

# the same thing from the terminal
regimelens chart XAUUSD --tf 1D --range 1Y --overlay cpi_yoy --events fomc,cpi

1.3Concepts: recipes, series, events

2.1Architecture & ports

Two processes. The core engine (Python) owns data connectors, the recipe runner, the cache (SQLite metadata + Parquet columns), the event-study engine and the licence module; it listens on 127.0.0.1:8787 (HTTP + websocket). The RegimeLens UI is a desktop shell talking to that port.

Outbound connections: your configured data sources, directly; and one planned licence check per day containing licence ID and version. No market data, no keys, no symbols leave your machine.

2.2Docker & headless

The Docker image opens with early access, together with the other downloads. It will run the engine headless on a home server or VPS, with your keys mounted read-only.

Keep the engine on a private network or behind Tailscale / WireGuard. It has no authentication of its own because it is designed to be reachable only by you.

2.3CLI reference

3.1Overlay recipes

Recipes live in ~/.regimelens/recipes/ (Windows: %APPDATA%\RegimeLens\recipes). RegimeLens ships 24; yours sit next to them. Minimal example and the full schema:

id: real_yield_10y
source: fred                 # fred | gdelt | acled | cot | onchain | calendar | csv
series: DFII10               # source-specific identifier
transform:                   # applied in order, all optional
  - pct_change: 12           # n-period change in %
  - diff: 1                  # n-period difference
  - zscore: 756              # rolling z-score, window in observations
  - ema: 5                   # smoothing
  - align: release_date      # release_date | reference_date (default)
  - surprise: consensus      # value minus consensus (calendar sources only)
  - clip: [-3, 3]
display:
  label: "10Y real yield"
  color: "#5aa9e6"
  scale: normalize           # normalize | zscore | axis:right
  step: false
  invert: true               # plot −x (useful for yields vs gold)

Recipe cookbook

3.2Events & calendar

Scheduled events come from the built-in calendar (Fed, ECB, BoE, BoJ, SNB, RBA decisions; BLS CPI, NFP; Eurostat HICP), refreshed weekly. Derived events are rules on series: acled:escalation region=MENA cross_above 70, gdelt:tone theme=INFLATION zscore < -2. Toggle families with E or --events fomc,cpi,acled. Each marker's tooltip shows the base-rate table for the current asset (5/20/60 sessions).

3.3Correlation panel

Computed on log returns of the asset versus shocks (standardised daily changes) of each active overlay, over 30, 90 and 250 sessions. Lead/lag scans −10…+10 sessions on the 250-session window and reports the strongest. Positive lag means the overlay leads price. Monthly series (CPI) produce shocks only on release days; the panel handles this by correlating on release days only and reports the effective n.

3.4Event studies

regimelens study --event "acled:escalation cross_above 70 cooldown 60" \
  --asset BRENT --window -20..60 --csv ~/studies/brent_escalation.csv
# → n=31 · median t+20 +3.4% · P25 −2.9% · P75 +9.6% · hit 65% · worst −14.0%

Studies use log returns relative to the close at t−1, exclude overlapping events via cooldown, and can be filtered by --filter region=MENA or any series attribute. Save a study to attach its table to future markers of that event type.

3.5Model portfolios

The framework lives in ~/.regimelens/portfolio/: four regime-flag recipes, a regimes.yaml mapping flag combinations to one of three allocations, and rules.yaml with the edge adjustments (for example gold: +5 if acled_watch). P opens the portfolio panel: current regime, target vs current weight, drift since the last rebalance and the rule that would change each weight. Rebalancing is banded (±3 pts) and evaluated on the first business day of the month. Editing any file changes the framework; the drift table recomputes against your version. Export of weights (CSV / JSON) and rebalance alerts require the feed. The framework is educational — see the disclaimer.

3.6Alerts

Alert rules (acled:escalation region=SAHEL > 70, cot:net_spec market=GC zscore > 2, portfolio:regime changed) are evaluated by the engine on each refresh. Building, arming and watching a condition is included in the licence — ALERTS <GO> in the terminal, or regimelens alerts check from the CLI — and every armed rule is backtested over the ten-year cache the moment you arm it, so you see how often it crossed before you rely on it. Delivery off the tab — Telegram, e-mail or a webhook — requires the Macro & Sentiment Feed, because it depends on the feed's 15-minute refresh running when your tab is not open.

3.7Export (PNG / CSV / Parquet)

SNAP (terminal) or Ctrl+S (app) copies the current chart as a PNG with the active recipe list embedded in its metadata, so a screenshot can always be rebuilt. Every recipe is also an engine series: regimelens series export cpi_yoy --csv or --parquet writes it to disk, release-aligned and already transformed, for spreadsheets, notebooks or any strategy tester that reads CSV.

3.8Bring your own data

Any dated series can become an overlay. In the terminal, DATA <GO> (or Add own data → in the F1 asset menu) opens the data connection page: drop a CSV or Parquet file and map its date and value columns, paste a REST or WebSocket feed URL, or add exchange / FRED / ACLED keys of your own. Imported series are cached like any other recipe and appear in the overlay editor under Custom. From the CLI: regimelens data import ./my_series.csv --date date --value close --name my_series.

3.9What the analyst does

Every view carries the analyst in the same place: a spark in the panel header, which opens it already scoped to that surface — it knows which view you are on, which object is selected and what the controls are set to. It offers three to five actions written for that surface, not a generic chip row:

The generic assistant stays on C and in the palette; the spark is the same assistant entered with context, never a second one. Every reply ends with a line stating what it just did — for example "Read the 252 sessions in view off the same arrays the canvas draws. Nothing on the chart moved." If it could not do something, it says so instead of pretending.

There is also a path where you configure nothing. START <GO> asks "What are you here to do?" and offers five concrete answers. Picking one sets the instrument, the range, the overlays, the correlation window, the regime axis and the standing instruction — then explains what it chose, why, and what the choice costs. Every answer is reversible: LAYOUT RESET restores the workspace, the standing desk stands down in one click, and anything it armed is disarmed with a switch on its row.

3.10What it refuses

RegimeLens is a research terminal. The analyst will not size a position, name a return or tell you what to buy, and it says so rather than deflecting:

• Sizing and returns. "RegimeLens is a research terminal, not an execution or advice tool — I will not propose a trade size or a return. What I can do is show you the macro context: which series moves XAUUSD, whether it leads or lags, and what price did around the last policy or escalation event."
• Samples too small to describe. Below four complete instances of an event class it draws no median and states why: "Any median I put on that would be a coincidence with a decimal point, so I will not put one on it."
• Correlations inside the noise floor. Below |r| = 0.15 the sample cannot tell the relationship from nothing, so the analyst removes the series from the axis and names the number rather than plotting it.
• Conditions it cannot build. A scheduled event is a date, not a reading: it will not arm one, and it points you at the calendar panel instead.
• Firing rate is not profit. When it grades your armed conditions it adds: "that is a count of crossings, not of profitable ones — no condition here has ever been tested for whether acting on it made money, and I am not going to imply it has."

3.11Where its numbers come from

The analyst never computes anything of its own. Every figure it quotes is read from the same functions the panels call, so the analyst and the screen cannot disagree; where it cannot compute something it names the panel that can. Concretely:

• Correlations — Pearson r on log returns against the overlay's shock series, on a 30 / 90 / 250-session window ending at the right edge of the view, with lead/lag scanned from −10 to +10 sessions.
• Event studies — an event class is a rule over the series (a CPI print 0.2 points or more away from the one before it; a meeting that actually changed the funds rate; an escalation crossing your alert level from below; positioning crossing ±1.5σ from inside; the quarterly roll). Every instance whose whole t−10 … +20 path exists is counted; none is hand-picked.
• "Is it real" — the median move plus the scatter of every instance, with the interval taken as median ± 1.96 standard errors of the median. When that interval contains zero, the analyst leads with that fact.
• Armed conditions — backtested across all 2,520 sessions in the cache; the analyst reports the number of false→true crossings, the date of the last one, and the rate per year.
• Regime splits — the correlation recomputed inside each regime, with any bucket under 60 sessions dimmed and flagged as thin.

3.12The standing desk

STANDING <GO> (or 8 for the standing-desk view) asks "What should the desk watch for you?". Pick one of four instructions, in words:

After that it works on the terminal's clock — every 6 seconds in the browser terminal, on each engine refresh in the desktop app. Each check runs the same set of tests and writes to a visible, scrollable log. Every entry carries three things: what it did, why, and the number that caused it. A reading that has just been raised is held quiet for five checks, so one swinging series cannot fill the log on its own.

On the checks where nothing crossed anything, it writes that down too — "Nothing worth telling you about. Checked 6 things: … Nothing crossed a threshold I hold, so there is nothing to say. On a macro desk that is the honest answer most days." An agent that always finds something is a salesman.

A standing instruction does not survive a reload. Nothing was running while the tab was shut, and a log you are meant to trust cannot pretend otherwise.

3.13Pause, undo and stop

Five controls sit in the standing desk's header strip, one click each:

• Pause — the instruction and everything it armed are kept, but nothing reaches you, including the things you asked to be told about. On resume it says so: the readings moved while it was paused and it did not watch them, so the first check may have several things to say at once.
• Check now — runs a cycle immediately and reports either how many things were worth reporting or "nothing crossed anything · 6 tests run".
• Undo the last action — reverses the most recent thing the desk changed on your screen. The entry stays in the log so the record is complete. Reporting is not undoable: it already happened, and the desk says that rather than pretending.
• Change the instruction — reopens the four options with the current one preselected.
• Stand down — stops all checking. The log stays, and anything it armed stays armed until you disarm it yourself; the confirmation says exactly that.

Clearing the log is a separate control and touches nothing else — it confirms with "… log entries cleared · what it armed is untouched". Everything on this page is educational model output — see the disclaimer.

4.1FRED API key

1. Create a free account at the St. Louis Fed FRED website and request an API key (My Account → API Keys). It is instant and free; there is no paid tier.
2. regimelens keys set fred and paste the key, or Settings → Data & keys → FRED in the UI.
3. regimelens keys test fred should report 200 OK. FRED's limit is 120 requests/minute; the cache means you rarely make more than a handful per day.

Keys are encrypted with AES-256-GCM using a key derived from your OS keychain / DPAPI and stored in ~/.regimelens/keys/ with owner-only permissions. They are never included in exports, logs or the licence heartbeat.

4.2GDELT access

GDELT is open and needs no key. The engine reads the 15-minute GKG update files (about 2 GB/day uncompressed), filters to the themes you have recipes for and stores the aggregated tone per theme as Parquet. Expect the first backfill of one year to take 1–3 hours and ~6 GB of disk; after that, incremental updates are a few MB every 15 minutes. If you would rather not run this locally, the feed serves the same indices pre-computed.

regimelens recipes pull gdelt_tone_inflation --since 2025-01-01
# ▸ downloading 35,040 GKG slices … ✓ · tone(INFLATION) 2025-01-01 → today cached

4.3ACLED access

ACLED provides free access for non-commercial and academic use after registration (you receive an access key and e-mail pair) and paid licences for commercial use. Store the pair with regimelens keys set acled. The engine pulls weekly aggregates per region and computes the escalation index locally. You are responsible for complying with ACLED's terms for your own use; the feed's escalation index is a RegimeLens-derived product licensed separately.

4.4Feed licence key

The planned Macro & Sentiment Feed issues a feed key tied to your RegimeLens licence. Enter it with regimelens keys set feed. The engine then pulls pre-computed indices every 15 minutes (tone by theme), daily (escalation by region) and weekly (COT z-scores), and enables alert delivery. Cancel the subscription and the engine falls back to your own keys automatically; nothing else changes.

4.5Caching & offline mode

regimelens cache offline on forces the engine to serve only from cache — useful on flights or when you want every chart served from the same cache. The licence tolerates 30 days without a heartbeat; past that the engine needs one successful check-in before it will activate again on that device. Charts, recipes and cache are untouched either way — this gates activation, not your files. If you need a permanently air-gapped machine, ask us before you buy.

5.1Licence & devices

One licence key, three concurrent device activations. Deactivate a device from the account portal or with regimelens licence deactivate on that device. A lost machine can be released from the portal. Licences are personal and non-transferable except by written request.

5.2Update contract & fallback version

The licence includes twelve months of updates. With an active contract afterwards (€99 / yr, or included with the feed), the engine installs new releases automatically (you can pin: regimelens update pin 1.9). When the contract lapses, the latest release published while it was active becomes your fallback version, shown in the account portal and in regimelens licence status. The software keeps working on that version indefinitely; renewing jumps you to the current release. See the changelog for what each release adds.

6.1Common problems