Technical trading desk engineering documentation

Engineering notes on metals trading platform components including physical engine, signal processing, and trader workflow automation.

#!/usr/bin/env python3
"""
L3 Physical Engine — technical note for Rashid Sahab.
Editorial style: Georgia serif, navy accent, off-white ground.
Full technical depth. Researcher-to-principal voice.
Every figure sourced from the actual code (l3_physical.py / titan_signals.py).
"""

from reportlab.lib.pagesizes import A4
from reportlab.lib.units import mm
from reportlab.lib import colors
from reportlab.platypus import (
BaseDocTemplate, PageTemplate, Frame, Paragraph, Spacer,
Table, TableStyle, HRFlowable, KeepTogether
)
from reportlab.lib.styles import ParagraphStyle
from reportlab.lib.enums import TA_LEFT, TA_JUSTIFY

---- palette ----------------------------------------------------------------

SERIF = "Times-Roman"
SERIFB = "Times-Bold"
SERIFI = "Times-Italic"

---- styles -----------------------------------------------------------------

S = styles()

---- page furniture ---------------------------------------------------------

def rule(color=RULE, w=0.6, sb=2, sa=8):
return HRFlowable(width="100%", thickness=w, color=color,
spaceBefore=sb, spaceAfter=sa, lineCap="round")

def callout(title, body_html, accent=NAVY):
"""Boxed aside."""
inner = [Paragraph(title, S["boxh"]), Paragraph(body_html, S["box"])]
t = Table([[inner]], colWidths=[None])
t.setStyle(TableStyle([
("BACKGROUND", (0,0), (-1,-1), BOXBG),
("LEFTPADDING", (0,0), (-1,-1), 10),
("RIGHTPADDING", (0,0), (-1,-1), 10),
("TOPPADDING", (0,0), (-1,-1), 8),
("BOTTOMPADDING", (0,0), (-1,-1), 8),
("LINEBEFORE", (0,0), (0,-1), 2.5, accent),
]))
return t

def datatable(rows, colw, header=True):
t = Table(rows, colWidths=colw, hAlign="LEFT")
cmds = [
("VALIGN", (0,0), (-1,-1), "MIDDLE"),
("LEFTPADDING", (0,0), (-1,-1), 7),
("RIGHTPADDING", (0,0), (-1,-1), 7),
("TOPPADDING", (0,0), (-1,-1), 5),
("BOTTOMPADDING", (0,0), (-1,-1), 5),
("LINEBELOW", (0,0), (-1,-2), 0.4, RULE),
]
if header:
cmds += [
("BACKGROUND", (0,0), (-1,0), NAVY),
("LINEBELOW", (0,0), (-1,0), 0, NAVY),
("TOPPADDING", (0,0), (-1,0), 6),
("BOTTOMPADDING", (0,0), (-1,0), 6),
]
t.setStyle(TableStyle(cmds))
return t

def P(t, st="body"): return Paragraph(t, S[st])
def C(t): return Paragraph(t, S["cell"])
def CB(t): return Paragraph(t, S["cellb"])
def CH(t): return Paragraph(t, S["cellh"])

---- build -------------------------------------------------------------------

f = [] # flowables

---- masthead ----

---- opening ----

---- 1. what L3 is ----

f.append(callout(
"The honest scope of the engine",
"L3 is built from five free data series via Yahoo Finance \u2014 GDX (gold-miner ETF), "
"GLD (gold ETF), SLV (silver ETF), GC=F (COMEX gold) and SI=F (COMEX silver) \u2014 plus a "
"Shanghai premium feed discussed in \u00a73. It does not have institutional data: no live "
"SGE physical premium, no real-time COMEX options, no paid order-flow. It is a disciplined "
"reading of publicly available proxies, not a Bloomberg terminal. Its value is that it "
"reads them the same way every day and refuses to invent conviction it has not earned."))

---- 2. the three live components ----

rows = [
[CH("Component"), CH("What it reads"), CH("Nominal"), CH("Effective"), CH("Direction logic")],
[CB("GDX vs Gold divergence"),
C("5-day return of the miner ETF minus 5-day return of COMEX gold"),
C("25"), CB("~38%"),
C("Miners leading gold \u2192 bullish; lagging \u2192 bearish. Spread >\u00b12% scaled \u00d715, capped \u00b170")],
[CB("GLD volume flow"),
C("Latest GLD volume vs prior-day average, signed by price direction"),
C("20"), CB("~31%"),
C("Vol >1.5\u00d7 avg + price up \u2192 accumulation (bullish); + price down \u2192 distribution (bearish); else 0")],
[CB("Silver / Gold ratio"),
C("GC=F price divided by SI=F price"),
C("20"), CB("~31%"),
C("Banded: >90 \u2192 +30; 80\u201390 \u2192 \u221210; 65\u201380 \u2192 0; <65 \u2192 \u221220")],
]
f.append(datatable(rows, [27*mm, 42*mm, 16*mm, 18*mm, 67*mm]))
f.append(Spacer(1, 8))
f.append(P("So the single heaviest input to your signal is the miner-versus-metal divergence "
"\u2014 the read that when GDX moves ahead of gold, real money is positioning before the "
"move shows in the front month. That is a defensible lead indicator and it is, today, "
"the backbone of the engine."))

f.append(P("To make this concrete, the engine\u2019s reading as of the COMEX close on 30 May 2026:", "bodyt"))
rows2 = [
[CH("Component"), CH("Input"), CH("Score"), CH("Read")],
[CB("GDX divergence"), C("GDX +4.07% vs Gold +0.46% (5d) \u2014 spread +3.61"),
CB("+54"), C("Miners leading \u2014 bullish")],
[CB("GLD flow"), C("Volume near average, no spike"), CB("0"), C("Neutral")],
[CB("Silver/Gold ratio"), C("\u2248 60 (GC=F 4,560.50 / SI=F 75.62)"),
CB("\u221220"), C("Below 65 band")],
[CB("Composite"), C("Weight-normalised average"),
CB("+15"), C("Mild long \u2014 a BUY at the lower threshold")],
]
f.append(datatable(rows2, [30*mm, 78*mm, 18*mm, 44*mm]))
f.append(Spacer(1, 6))
f.append(Paragraph("Both your daily brief and the website now return this same +15, computed from "
"identical data \u2014 verified component by component. Before this week they did not, "
"which is the subject of the next section.", S["note"]))

---- 3. the correction ----

f.append(Paragraph("3.1 The brief and the website were running different engines", S["h2"]))
f.append(P("The website signal excluded Shanghai entirely \u2014 it passed the Shanghai "
"input as empty, scoring on the three components in \u00a72. The daily brief, "
"generated by a separate code path, included Shanghai live at 15\u201340% weight. "
"On the same day, with the same prices, the two surfaces could therefore return "
"different convictions \u2014 and at present, with Shanghai premium around \u22125%, "
"they did: the brief carried a large bearish Shanghai contribution that the website "
"did not. Two numbers, one signal, no indication of which to trust."))

f.append(Paragraph("3.2 Why Shanghai cannot ride on the 18-year validation", S["h2"]))
f.append(P("The engine\u2019s headline credential is a 54.6% directional hit-rate over 18 years "
"(confidence interval 52.6\u201356.5%, Sharpe 1.40, surviving the standard "
"over-fitting tests). That number was produced without Shanghai \u2014 the "
"backtest never contained it. The reason is concrete: the live Shanghai proxy is the "
"Huaan Gold ETF (Shanghai 518880), which only began trading on 18 July 2013. There "
"are not 18 years of it to test. Including it in the live brief therefore meant the "
"brief was carrying an 18-year credential over a signal whose largest current input "
"had never been part of those 18 years."))

f.append(callout(
"The change I made",
"I converged the brief to the validated engine: Shanghai is now excluded from live "
"conviction in both paths, exactly as the validated backtest was run. The Shanghai "
"premium still appears in the brief narrative as context \u2014 you continue to see the "
"Asian read \u2014 it simply no longer moves the conviction number until it has been "
"validated on its own terms. I also aligned the brief\u2019s data preparation to the website\u2019s "
"(completed bars only, dates aligned across all five instruments, fixed 5-day lookback), so "
"the two now compute identically. Verified: composite +15 on both, every component matching.",
accent=GREEN))

f.append(P("I want to be plain that this makes your current signal less bearish than the "
"brief previously showed, because a roughly \u221279 Shanghai contribution came out of "
"it. That is the correct direction: the engine should show only what it can stand "
"behind. A weaker but honest number is worth more than a stronger one the backtest "
"does not support.", "bodyt"))

---- 4. honest weak spots ----

f.append(Paragraph("4.1 The silver/gold ratio component", S["h2"]))
f.append(P("This is the weakest of the three. It scores in hard steps rather than on a gradient "
"\u2014 a ratio of 89.9 scores zero, 90.1 scores +30 \u2014 so it can jump on a "
"trivial move across a band edge. Its internal rationale is also muddled: the code "
"comment reasons about silver being cheap or dear, but the score it returns is for "
"gold, and the mapping does not cleanly follow from the comment. At today\u2019s "
"ratio near 60 it is contributing \u221220 to your signal on logic I would not yet "
"defend in front of you. I am treating this component as under review and will bring "
"you a revised version rather than leave the cliffs in place."))

f.append(Paragraph("4.2 Free, ~15-minute-delayed data", S["h2"]))
f.append(P("Every input is a free Yahoo Finance series, delayed by roughly fifteen minutes on "
"the futures. For a daily-horizon swing signal computed after the close this is "
"acceptable \u2014 the close is the close. It would not be acceptable for an intraday "
"tool, and the engine does not claim to be one."))

---- 5. forward ----

f.append(rule(RULE, 0.6, 8, 10))
f.append(P("The engine is sound at its core \u2014 a daily, miner-led physical read with a real "
"18-year edge, now computed identically wherever you look at it. Where it is thin I "
"have said so. I will report on the Shanghai validation in the next update.", "bodyt"))
f.append(Spacer(1, 10))
f.append(Paragraph("Respectfully,", S["sign"]))
f.append(Paragraph("Khurram", S["sign"]))

doc.build(f)
print("built /home/claude/L3_Engine_Note.pdf")

build()