Murph Documentation

Overview

Functional architecture

Murph is organized around eight numbered tabs (shortcuts 1–8) and a Portfolio Construction group that chains Optimizer, Walk-Forward, and Portfolio.

Module 1

Nowcast

USA / EU macro regimes, growth & inflation scores.

Module 2

Strategies

Performance reports, regime & COT attribution.

Module 3

COT

CFTC positioning, percentiles, crowding.

Module 4

Optimizer

Calibrate rotation conditions.

Module 5

Walk-Forward

Chronological out-of-sample validation.

Module 6

Portfolio

Live combination search.

Module 7

Code Builder

Python hooks: conditions, sizing, score…

Module 8

Public API

Nowcast, COT, PIT enrichment.

Strategies (research) → Optimizer (calibration) → Walk-Forward (validation OOS) → Portfolio (live deployment)

Preview: navigation sidebar

Nowcast

live

Macro regime dashboard

Macro regime dashboard for USA and Eurozone.

Goldilocks

Recommended workflow: load strategy performance reports (trade logs, CSV/XML exports) into Strategies, calibrate a rotation condition in Optimizer, validate OOS in Walk-Forward, then deploy in Portfolio.

Getting started

Installation & license

On this page

Requirements
Installation
Sign-in & license
File locations
Troubleshooting

Requirements

Windows 10/11 (64 bits)
Internet connection (macro data, COT, license validation)
Murph opens automatically at http://127.0.0.1:8080 (or fallback ports 8081–8082)

Installation

Download Murph-Setup-2.0.5.exe from murph.tirmann.com/downloads.
Run the Inno Setup installer: desktop shortcut and Add/Remove Programs entry.
On first launch: email + license key (not your website password).

Sign-in & license

Remote validation via https://murph.tirmann.com/api/license/validate. Session is stored locally. Sign out in the top bar to sign out.

Updates: Download update banner if a newer version exists. Your cache/ and config/ folders are preserved during an Inno upgrade.

File locations

Path	Contents
`%LOCALAPPDATA%\Programs\Murph\`	Application (`Murph.exe`, `_internal/`)
`…\Murph\config\settings.json`	API keys, auth, preferences (survives upgrades)
`…\Murph\cache\`	Strategies, macro, COT, hooks, presets (survives upgrades)

Quick access: Win + R → paste %LOCALAPPDATA%\Programs\Murph → Enter.

Installation troubleshooting

Symptom	Action
Login OK but no macro data	Install the latest version (≥ 2.0.5). Wait 1–2 minutes on first launch.
Errors `add_docstring` in the logs	Version 2.0.4 or older: reinstall 2.0.5.
Empty hooks library	Same cause: hook seeding crashed before 2.0.5.
Corrupted config after testing	Delete `config\settings.json` then restart (recreated from defaults).

Getting started

Global interface

Sidebar

Element	Description
Logo Murph	Application identity. Click the hamburger button to collapse/expand the bar (icons-only mode).
Tabs 1–8	Main navigation. Each tab shows a colored dot when data is loading or an alert is active.
Portfolio Construction	Visual group for Optimizer (4), Walk-Forward (5), and Portfolio (6).
Theme	Dark / light toggle. Choice is stored in `localStorage` (`murph_theme`).
Account	Visible when signed in: email, license status, expiration.
Status	System state, CPU performance, data source health.
Logs	Filterable event log by category.

Top bar

Preview: top strip

Portfolio · Standard

live

Button	Function
Title + context	Shows the active tab and sub-context (e.g. Portfolio · Sub-accounts, Nowcast region).
New window	Opens the current tab in a new browser window (useful for a second monitor).
Refresh	Reloads all data: macro regimes, COT, strategy list, API status. Shows a loading animation.
Sign out	Sign out (visible when authenticated).
Alerts	Opens the alert strip (regime changes, load errors, etc.).
Pill « live »	Green = server connected and data up to date. Red or gray = connection or load issue.

Alert strip

Appears below the top strip when important events occur (macro regime change, download failure, etc.). Click Dismiss to dismiss until the next alert.

Status bar

Shows UTC time, the Ctrl+K shortcut for the command palette, and the application version (v2.0.5).

Command palette

Open with Ctrl+K (ou Cmd+K on Mac). Type to filter, up/down arrows to navigate, Enter to run, Esc to close.

Go to any tab (Nowcast → API)
View System Status / Event Log
Refresh all data
Switch region → USA / Eurozone
Toggle light / dark theme

Toasts

Ephemeral notifications bottom-right confirming actions (successful import, saved preset, clipboard copy, etc.).

Getting started

Portfolio workflow

The three modules Optimizer, Walk-Forward et Portfolio share common logic: rotation conditions, transaction costs, presets, force/skip, and a step wizard.

Step wizard

1 · Strategies 2 · Validation 3 · Results

Module	Steps	Description
Portfolio (Standard / Sub-accounts)	1 → 2 → 3	Strategies → Individual validation → Results (ranked combinations).
Walk-Forward	1 → 3	No single Validation step: each rotation cycle re-validates strategies (see Rotation Log).
Parameter Optimizer	1 → 3	Strategies to optimize → Results (parameter grid).

Standard vs Sub-accounts

STANDARD SUB-ACCOUNTS

Standard: Single portfolio; at most one strategy per market (symbol) at each rotation.
Sub-accounts: Capital split into parallel buckets; multiple strategies on the same market can coexist in separate sleeves.

Core module · 1

Nowcast

Macro dashboard. Tracks growth and inflation composites for the USA and euro area from public sources, and shows the active regime used in Strategies and portfolio construction.

Interactive globe

USA: Click the US point or use the palette (Switch region → USA).
Eurozone (EU): Same for Europe.
Hover: preview regime without changing selection.
Click: sets the active region for all of Murph (Strategies, API enrichment, etc.).

Displayed fields

Field	Meaning
Regime	Current macro regime (e.g. Goldilocks, Reflation, Stagflation, Deflation): color-coded.
Growth	Growth composite score (positive = expansion).
Inflation	Inflation composite score.
As of	Date of the latest available observation.

Regime key

Four macro regimes, color-coded:

● Goldilocks: solid growth, moderate inflation
● Reflation: recovery with inflation pressure
● Stagflation: weak growth, high inflation
● Recession: economic contraction

Current Regime card

Block	Contents
Regime badge	Active regime name with color.
Growth / Inflation	Nowcast scores + mini sparkline (recent trend).
Period	Nowcast reference month.
VAR(3) Projection \| 3 months	3-month VAR model projection: likely regimes M+1, M+2, M+3.

Data Health & Streak

Macro series quality indicators: missing series, publication delays, current regime streak (consecutive months in the same regime).

Summary metrics (banner)

Nowcast Regime: Active region regime
Strategies loaded: Number of strategies in memory
Last update: Last macro data sync

Regime history

ACTUAL: Timeline of observed regimes (past)
M+1 PREDICTED: Next-month projection from VAR(3)

Macro indicators & Regime distribution

Two columns: component indicator z-scores (GDP, employment, inflation, etc.) and historical time spent in each regime (%).

VAR(3) Projection Accuracy

Backtest of VAR predictive quality: correct regime classification rate at 1–3 month horizon.

Loading

On first launch or after Refresh, a Loading macro data banner appears with per-region progress bars and ETA. Data is cached locally for subsequent launches.

Core module · 2

Strategies

Single-strategy research workspace. Import performance reports and trade histories, measure behavior by Nowcast regime, and build manual combinations before entering the Portfolio Construction pipeline.

Import a strategy

Drop CSV / XML files here

Analyze from

Control	Description
Dropzone	Drag-and-drop or click to select `.csv` or `.xml` (TradeStation exports and compatible performance report formats).
Analyze from	Analysis start date: earlier trades are ignored.
Ready to import	Parsed files awaiting import; column mapping if CSV is ambiguous.
After import	Automatic destination after import: stay here, Portfolio, Walk-Forward, or Optimizer.
Analyze	Runs import and analysis (progress bar). Disabled until a valid file is ready.

Analyzed strategies: action bar

Button	Action
Select all / Deselect all	Selects or deselects all listed strategies.
Transfer to…	Sends selected strategies to Portfolio, Walk-Forward, or Optimizer (replaces target pool).
Create combination	Merges selected strategies into a temporary combination (minimum 2).
Delete selected	Deletes checked strategies (irreversible).
Custom hooks	Opens Code Builder tab size (position sizing).
Delete all	Deletes all imported strategies.

Strategy card (detail)

Each analyzed strategy appears as an expandable card with:

Header: Name, market, ID, selection checkbox, delete button.
Settings: Region (USA/EU), start date, OOS (out-of-sample) date, sizing hook, contract rounding.
Performance: Key metrics: Net profit, CAGR, Sharpe, Max DD, Win rate, Profit factor, etc.
Equity / Drawdown: Interactive SVG charts (resized on window resize).
Nowcast attribution: Performance split by macro regime.
COT performance: Performance vs positioning percentiles.
Tag performance: When a tag_trades hook is attached.
Monte Carlo: Bootstrap simulation with configurable capital, % trades skipped.
Monthly returns: Heatmap or table of monthly returns.
Trade list: Paginated trade list with CSV export.
Correlation: Correlation matrix with other strategies (dedicated button at top of list).

Strategy card: report tabs

Tab	Contents
STRATEGY	Global metrics, equity/drawdown, settings (region, OOS date, sizing hook).
NOWCAST	Performance by macro regime: bars or P&L / Sharpe table by regime.
COT	Performance conditioned on CFTC positioning percentiles.
TAGS	Visible when `tag_trades` hook is attached: performance by custom tag.
MONTE CARLO	Simulation bootstrap: initial capital, % trades skipped, outcome distribution.
MONTHLY	Table or heatmap of monthly returns.
TRADES	Paginated list; CSV export available.

Per-strategy settings

Field	Description
Region	USA or EU: Nowcast regime used for attribution.
Analyze from	Truncation date (editable via update settings).
OOS date	Date out-of-sample: separates IS/OOS in metrics.
Sizing hook	Hook `size()` attached: dropdown of saved hooks.
Round contracts	Round position sizes to whole contracts.
Delete	Deletes the strategy (trash icon in header).

Correlation matrix

Correlation heatmap across all loaded strategies: useful before combining redundant strategies.

Combinations

Manually created combinations appear as special entries. The report is computed on the fly (combine_preview) with no persistence.

Import CSV: column mapping

If the CSV is not recognized automatically, a preview screen lets you map entry/exit dates, P&L, direction, etc. Defaults configurable in System Status.

Core module · 3

COT

Weekly CFTC positioning for 23 futures markets. Percentiles use a 26-week window; the crowding score combines commercials, speculators, and open interest.

Main table

One row per asset (ES, NQ, CL, GC, etc.) with:

Commercial / Non-commercial / Non-reportable: Net positions in contracts
26-week percentiles: Where current positioning sits in recent history
Crowding: Integrated score and label (e.g. crowded long, neutral)
Mini chart: Sparkline of recent trend; date axis under the SVG

Interactions

Action	Effect
Click a row	Opens detail with full history chart, percentiles, and crowding breakdown.
Refresh (top strip)	Re-downloads CFTC reports when a new week is available.
Last report date	Shown under the intro: date of the latest integrated COT report.

Initial COT load can take a few minutes (first download). Data is then served from local cache.

Portfolio construction · 4

Parameter Optimizer

Search module for rotation conditions. Systematically sweeps parameter sets to find regime filters that preserve edge over time.

Step 1: Strategies to optimize

Strategy pool (CSV/XML import, transfer from Strategies, or list selection)
Sidebar: presets, rotation condition, costs, OOS date, rotation schedule, composite score weights

Sidebar: collapsible sections

Section	Parameters
Presets	Save / Load / Export / Import / star (default preset on startup).
Rotation condition	Hook condition whose numeric parameters will be swept (min/max/step per parameter).
Transaction costs	Commission and slippage per contract, applied at each simulated rebalance.
OOS start	First out-of-sample month to score each parameter combination.
Rotation schedule	Rebalance frequency and day during evaluation.
Score weights	Metric weights (Sharpe, CAGR, DD, etc.) or `score` custom hook.

Run & results

The Run optimization button shows a progress bar with per-substep ETA. Step 3 shows a ranked table of parameter combinations, with export and apply-to-Walk-Forward or Portfolio.

Use Optimizer before Walk-Forward to calibrate the condition, then validate temporal robustness in Walk-Forward before live deployment in Portfolio.

Portfolio construction · 5

Walk-Forward

Out-of-sample validation engine. Applies the rotation condition calibrated in Optimizer on a fixed calendar with exact rebalance dates, without lookahead.

Key parameters (sidebar)

Section	Description
Presets	Walk-Forward sidebar configurations (dates, rotation, costs).
Date range	`wf-start-month` / `wf-end-month`: calendar span of simulated monthly cycles.
Rotation day	Day of month and rebalance frequency (e.g. last Friday).
Transaction costs	Commission + slippage per contract at each simulated rebalance.
Rotation condition	Condition applied at each rotation step.
Sub-account structure	(Sub-accounts mode) Number of buckets, strategies per bucket, search limits.
Force / Skip	IDs or markets forced/excluded during bucket search.

Results

Equity curve OOS: Cumulative out-of-sample equity over the full period
Rotation Log: Cycle-by-cycle detail: active strategies, condition pass/fail, monthly P&L
Aggregated metrics: OOS Sharpe, max drawdown, rotation rate, etc.
Monte Carlo OOS: Robustness test on the OOS series (/api/walkforward/oos_monte_carlo)
Export: Rotation CSV, PDF/HTML report depending on options

Portfolio construction · 6

Portfolio

Live allocation module. With a rotation condition defined, ranks current strategy combinations and selects the portfolio to deploy now.

STANDARD SUB-ACCOUNTS

Step 1: Portfolio strategies (builder)

Portfolio strategies

Drop CSV / XML files here

STRATEGY · MARKET · ID · WEIGHT

Weights hook:

Reference date

Month · Year · Week · Day

Search params

Min/max strategies · Top N · Correlation…

Builder: controls

Element	Description
+ Add	Adds an empty row: select an imported strategy from the dropdown.
Dropzone	Direct import into the Portfolio pool (CSV/XML).
STRATEGY / MARKET / ID / WEIGHT columns	Strategy, market symbol, numeric ID, relative weight (allocation hint).
Weights hook + Suggest weights	Applies an `allocate()` hook to suggest weights (sum = 1).
Round to whole contracts	Rounds suggested weights to whole contracts.
Regime attribution	P&L attribution chart by Nowcast regime (if data available).

Sidebar Standard: Reference date

Portfolio evaluation date. Only trades closed on or before this date are included. Set month + year + week of month (1st–4th or Last) + weekday (Mon–Fri).

Sidebar: Search parameters

Field	Description
Min / Max strategies	Size of combinations searched.
Top N	Number of top combinations kept.
Max per market	Cap on strategies sharing the same market (0 = unlimited).
Max correlation	Rejects pairs above this threshold. Empty = disabled.
Synergy threshold	Minimum synergy ratio for a pair to score well.
Sort by	Ranking metric and direction (asc/desc).
Custom score hook	Replaces the built-in weighted score.
Force / Skip IDs & markets	Explicit inclusions/exclusions (comma-separated IDs or symbols).

Rotation condition & costs

Rotation condition: Main condition; None keeps all strategies active. Button Add condition for additional conditions (AND logic).

Transaction costs: Commission and slippage per contract deducted at each rebalance when enabled.

Step 2: Validation

Validates each strategy individually over the configured OOS period. Shows pass/fail, metrics, and exclusion reasons before the full portfolio run.

Step 3: Results

Ranked combination table. For each combination: included strategies, score, metrics, report tabs (Performance, Monthly, Monte Carlo, etc.). CSV export and transfer to other modules.

Sub-accounts: specifics

Structure: min/max buckets, min/max strategies per bucket, top N configs, max candidates
Max market exposure (%): combined market exposure within a bucket
Correlation scope: correlation limited intra-bucket or inter-buckets
Presets separate from Standard presets (acc-bkt-presets)

Run

Run portfolio search (Standard) or Sub-accounts equivalent: uses all CPU cores if Use max cores is enabled in Status, otherwise the worker count slider.

Developer · 7

Code Builder

Extend Murph with Python hooks: rotation conditions, position sizing, composite score, custom metrics, trade tagging, portfolio allocation. Save in the editor and attach from Strategies or Portfolio.

Code Builder tabs

Tab	Hook type	Role
Conditions	`condition(...)`	Evaluated monthly at rebalance. Returns `True` to keep a strategy active.
Position sizing	`size(...)`	Monthly position multiplier based on equity and history.
Composite score	`score(...)`	Single number to rank combinations (Portfolio, Optimizer).
Custom metrics	`custom_metric(...)`	User-defined metric over full history.
Trade tags	`tag_trades(...)`	Tags each trade; Murph splits performance by tag.
Allocation	`allocate(...)`	Returns weights summing to 1 across selected strategies.
Reference		Available columns and metrics, safe point-in-time examples.

Code Builder sub-tabs

CUSTOMIZE REFERENCE EDITOR

CUSTOMIZE: Visual catalog of all hook types with signatures.
REFERENCE: Trade columns, built-in metrics, point-in-time examples.
EDITOR: Create, test, and save Python hooks.

Condition Creator

From Portfolio / Optimizer / Walk-Forward, the condition creator button opens a wizard that saves to Code Builder without leaving the module.

Editor

Saved hooks list on the left: click to load
Monospace code area with basic highlighting
Save: Persists the hook (name required)
Delete: Deletes the selected hook
Test / Validate: Checks syntax and signature
New: New empty hook with signature template

Default rounding (sizing)

Global option to round attached position sizing hooks to whole contracts by default.

Developer · 8

Public API

Read-only HTTP API (plus POST enrichment) for Nowcast regimes, COT, and point-in-time joins. Serves on localhost by default; a public base URL can be configured for remote HTTP clients. Application licensing remains at murph.tirmann.com.

API panel (UI)

Block	Contents
Status	API v1 server state.
Base URL (local)	`http://127.0.0.1:8080/api/v1`
Base URL (public)	Externally reachable URL, as configured in the API tab.
API Key	Secret key: Show / Copy. Passed in header `X-API-Key`.
Refresh	Reloads status and capabilities.
Open Swagger docs	Opens `/api/v1/docs` (interactive OpenAPI documentation).
Live capabilities	Snapshot of regions, COT assets, keywords available on this install.

Main endpoints

Method	Path	Description
GET	`/api/v1/capabilities`	Lists endpoints, regions, COT assets.
GET	`/api/v1/keywords`	Macro series dictionary for `/series`.
GET	`/api/v1/series`	History for a keyword (`keyword`, `region`, `from`/`to`).
GET	`/api/v1/nowcast/{region}`	Current regime, scores, history (USA or EU).
GET	`/api/v1/cot/{asset}`	Latest COT and 26-week percentiles for an asset.
GET	`/api/v1/crowding/{asset}`	Integrated crowding score and label.
POST	`/api/v1/enrich`	Body `{dates, region, cot_asset}` → PIT join without lookahead.

API authentication

Include the header X-API-Key: <your_key> on every request. The key is generated locally and visible in the API tab.

Administration

Account & authentication

Element	Description
Signed in as	Active license email.
License expires	License expiration date.
Sign out	Sign out: returns to the login screen.
Open web account	Link to murph.tirmann.com/account to manage your key.

The license key is not shown in Murph desktop. Endpoints: POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me.

Administration

System Status

Performance settings, data source health, installation diagnostics.

Performance

Option	Description
Use max cores	Uses all CPU cores for Portfolio, Sub-accounts, Walk-Forward, and Optimizer.
Worker pool slider	Number of workers when max cores is disabled.

CSV import settings

Default column mapping, separator, date format: configurable to standardize recurring CSV imports.

MacroMurph API Status

Grid per macro series: latest value, date, status (OK / stale / error). Last check timestamp in header.

COT Data Status

State per futures market: latest CFTC week, local cache, errors. App version via GET /api/status.

Administration

Event Log

Button	Action
Clear	Clears the displayed log (current session).
Copy all	Copies the full log to the clipboard.

Filterable log (GET /api/audit_log): UTC timestamp, category, detailed message. Limit 200 recent entries.

Reference

Keyboard shortcuts

Shortcut	Action
1 – 8	Go to the matching tab (outside input fields)
Ctrl + K	Open / close command palette
Esc	Close palette, modals, overlays
↑ / ↓ (palette)	Navigate the command list
Enter (palette)	Run the selected command

Administration

Presets

Each pipeline module has its own sidebar preset system (Portfolio Standard, Sub-accounts, Walk-Forward, Optimizer).

Action	Description
Select preset	Loads a saved configuration (strategies, parameters, conditions).
★ (star)	Marks the default preset loaded on Murph startup for this module.
Preset name + Save	Saves current state under a name.
Del	Deletes the selected preset.
Export	Downloads a `.json` shareable file.
Import	Loads a preset from exported JSON.

Portfolio Standard and Sub-accounts presets are stored separately: a Standard preset does not affect Sub-accounts and vice versa.

Developer

Hooks library

On this page

Library vs Saved hooks
Hook types
Built-in library
Point-in-time

Library vs Saved hooks

Code Builder exposes two levels of hooks, like rotation conditions:

LIBRARY: built-in Murph hooks (BUILTIN_HOOKS) : usable immediately, not editable in place. Duplicate under another name to customize.
SAVED HOOKS: your hooks + examples seeded on first launch (cache/custom_hooks.json).

For rotation conditions (Portfolio / Optimizer / Walk-Forward), the LIBRARY contains 41 ready-to-use conditions (BUILTIN_CONDITIONS).

UI area	Contents	Editable
LIBRARY (Conditions)	41 rotation conditions (profitability, DD, COT, regime…)	No: duplicate for variants
LIBRARY (Hooks)	25 built-in hooks (5 × size, score, metric, tag, allocate)	No
SAVED HOOKS	Examples + saved client hooks	Yes

Hook types

Hook	Signature	Usage
condition	`condition(trades_df, date_ref)`	Monthly rotation: active/suspended boolean
size	`size(trades_df, date_ref, current_equity)`	Position multiplier (1.0 = nominal)
score	`score(strategies_metrics)`	Rank combinations in Portfolio / Optimizer
custom_metric	`custom_metric(trades_df)`	Metric shown in reports
tag_trades	`tag_trades(trades_df)`	Tag per trade → Tag performance tab
allocate	`allocate(strategies_metrics)`	Weights summing to 1: Suggest weights

Built-in library (examples)

Built-in hooks shipped with Murph (not exhaustive):

Size: Vol Targeting, Drawdown Throttle, Kelly Fraction, Ramp-Up New Strategy…
Score: Sharpe Only, Drawdown-Averse, Consistency First, Balanced Composite…
Metric: Ulcer Performance Index, Tail Ratio, Monthly Consistency %…
Tag: Trade Size Terciles, After Win vs After Loss, Seasonality…
Allocate: Equal Weight, Inverse Drawdown Risk, Top-3 Concentration…

Point-in-time

Point-in-time: hooks only receive data available at the evaluation date: no lookahead. Safe columns: Reference tab in Code Builder.

Administration

Data, cache & updates

Local storage

Imported strategies and precomputed metrics
Nowcast macro cache and underlying series
Downloaded COT history
Presets, hooks, UI preferences (/api/ui_prefs)
Audit log

Application updates

GET /api/app/update compares APP_VERSION local version with the manifest on murph.tirmann.com. Banner offers download if remote version is newer.

Refresh vs restart

Refresh re-downloads external data without restarting the server. A full restart (Murph.exe) reloads configuration and reapplies the starred default preset.

Export

Available exports: trade CSV, portfolio reports, JSON presets, walk-forward results. Endpoints: /api/export/csv, /api/export/file, export_reveal (opens the folder in Windows Explorer).

Reference

Frequently asked questions

Murph does not open

Check that Murph.exe is running (taskbar). Open manually at http://127.0.0.1:8080. Ensure no other service is using port 8080.

License error

Check email and key. Internet required. If the problem persists, the validation server (validate.php) may be unavailable: try again later.

Import CSV

Use the preview/mapping screen on import. Configure defaults in System Status → CSV import settings.

Slow portfolio run

Reduce Top N, max combinations, or enable Use max cores. Reduce strategies in the pool.

Optimizer vs Walk-Forward

Optimizer searches for the best parameters of a condition over history. Walk-Forward simulates the chronological application of fixed rules month by month to measure real OOS degradation.

Remote API access

Local default: http://127.0.0.1:8080/api/v1. Remote clients use the Base URL (public) from the API tab and authenticate with the X-API-Key header. OpenAPI documentation: /api/v1/docs.