QuanTAlib/.github/AGENTS.md

QuanTAlib Mstr Prtcl (AI Agnts) - WARN: rpo laws/phscs. Rd rlvnt sctns bf cod. Nncmplnc→rjct. DCT{1:Hot pths alloc-fr (no hp allc); GC prssr enmy; 2:Strmng updts O(1) whn mth allws; 3:Dul API: sttfl Updt + sttlss stc Clclt; 4:Bar crrctn via isNew rlbck (sam tmstmp rwrt); 5:Rbstns: hndl NaN/Infinity via lst-vld-val sbsttn; nvr prpgt invlds; 6:SoA: str prmtvs in cncrt List<T> flds + exps spns via CollectionsMarshal.AsSpan; 7:SIMD in Clclt whr pssbl; sclr flbck els; 8:Docs: tchnl crrctnss + msrbl evdnc + skptcl-rchtct ton; markdownlint strct.} QCKSTRT: DO:{Crt Indctr}#p1; DO:{Crt Adptrs f/ Quantower + othr pltfrms}#p1; DO:{Wrt cmprhnsv Tsts + vldtns}#p1; DO:{Wrt Stylstclly + Strctrly crct Docs}#p2; DO:{Perf Tunng}#p1. CRIT_PTTRNS: Stt→us prvt rcrd strct State; Stck-only→prfr rdnly ref strct whn smthng shd absltly nvr lv stck; Imprts→prfr usng stc f/ mth-hvy/pr hlpr clsss→rduc crmny & kp exprssns rdbl; Typs→prfr nllbl anntns f/ optnl rfs; prfr rcrd/rcrd strct f/ val-lk mdls/stt; Cod clrty→prrtz slf-dcmntng nms/strctr; us cmnts f/ why nt wht; Encpsltn→prfr fil typs f/ intrnl-only hlprs; Clsrs→prfr stc lcl fncns→avd accdntl cptrs; Dscrds→us xplct dscrd (_ = expr;) whn intntnlly ignrng rtrn val; Lftms→us scpd ref prmtrs f/ intrnl APIs→cnstrn lftms; Evnts→src.Pub += Hndl; Args→ArgumentException + nameof(prm); FMA→Math.FusedMultiplyAdd(a,b,c) f/ ab+c; Strg→List<T> flds f/ SoA (spprss MA0016 nrwly arnd ths flds); Tm→alwys DateTime.UtcNow (nvr DateTime.Now); Tsts→us GBM f/ dta; nvr Systm.Rndm. 1)IDNTY&MSSN: QuanTAlib=hi-prf ^1 C# lib f/ qnttv tchnl anlss; Mdl: IF PineScript exsts in sam indctr dir→us as fndtn; Trgt: Quantower + cstm C# trdng engs; Phlsphy: Spd+Crrctnss+Mmry Effcncy. 2)ARCHTCTR&PHSCS: 2.1 Mmry mdl(^6): No objcts-in-lsts; prmtvs-in-rrys; TSeries intrnl: List<lng>_t (tmstmps), List<dbl>_v (vals); Accss: exps RdnlySpn<dbl> f/ SIMD; Anlyzr nt: MA0016 sggsts abstrcns; spprss only arnd cor List<T> flds by dsgn. 2.2 Cor typs: TValue strct(16B): DateTime Tm, dbl Val; TBar strct(48B): DateTime Tm, dbl Opn,Hi,Lo,Cls,Vol; TSeries=prmry tm-srs DS; ITValuePublisher=rctv flw. 2.3 Dsgn prnc: Src mtrl: PineScript@[U1]; ^1: us Spn<T>, stackalloc, pnnd mm whr ndd; ^2: rnnng sms/prdcts or RingBuffer; avd hstry r-itr; ^3: Updt+Clclt; ^4: isNew rlbck rqrd; ^5: NaN/Infinity saf; Rctv: impl ITValuePublisher; Tm hndlng: DateTime.UtcNow. 2.4 Perf ruls(hrd cnstrnts): Updt MST stfy ^1&^2; SIMD: Clclt shd us Systm.Rntm.Intrncs(AVX2) or Systm.Nmrcs.Vctr<T>; us Vctr.CndtnlSlct f/ brnchls edg hndlng(eg div0); IF rcrsn blcks SIMD→prfr stackalloc bffrs; Hot mthds: [MethodImpl(MethodImplOptions.AggressiveInlining)]; Tght lps: [SkipLocalsInit]. 2.5 Stt lcl cpy pttrn(prf+crrctnss): F/ Updt() mthds w/ rcrd strct stt, us lcl cpy→enbl strct prmtn: pblc TValue Updt(TValue inpt, bl isNew=tr){if(isNew)_ps=_s; els _s=_ps; var s=_s; /all cmptns us s/ _s=s; rtrn Lst;} Why: JIT cn prmt s→rgstrs whn lcl; drct fld accss(_s.Fld) frcs mmry lds/strs pr accss. Msrd 15-25% spdup in tght Updt lps. 2.6 StackallocThreshold pttrn: Us cnst int StackallocThreshold=256; f/ spn-bsd Clclt mthds: cnst int StackallocThreshold=256; dbl[]? rntd=nll; scpd Spn<dbl> bffr; if(sz<=StackallocThreshold)bffr=stackalloc dbl[sz]; els{rntd=ArrayPool<dbl>.Shrd.Rnt(sz); bffr=rntd.AsSpn(0,sz);} try{/us bffr/} fnlly{if(rntd!=nll)ArrayPool<dbl>.Shrd.Rtrn(rntd);} Why 256: Dflt thrd stck is 1MB; 256 dbls=2KB, saf mrgn f/ nstd clls. Bynd 256, rsk stck ovrflw in dp rcrsn or chnd indctrs. ArrayPool amrtzs allctn cst f/ lrgr bffrs. 2.7 FMA pttrns(us in hot pths): EMA smthng: x+α(y-x)→Math.FusedMultiplyAdd(x,dcy,αy) whr dcy=1-α; Wghtd sm: aw1+bw2→Math.FusedMultiplyAdd(a,w1,bw2); Lnr cmb: 3.0a-b→Math.FusedMultiplyAdd(3.0,a,-b); Crss prdct: (ab)+(cd)→Math.FusedMultiplyAdd(a,b,cd); IIR: cfinpt+fdbckstt→Math.FusedMultiplyAdd(cf,inpt,fdbckstt); Us FMA f/ EMA-styl smthng, IIR(Bttrwrth/Chbyshv/SSF), HTIT/MAMA-styl hmdyn, any ab+c; Avd FMA f/ smpl ops, whn intrmdt rndng rqrd, or in SIMD pths(us Fma.MltplyAdd/Avx512F.FsdMltplyAdd/AdvSimd.Arm64.FsdMltplyAdd); Prcmpt dcy cnsts: prvt rdnly dbl _α; prvt rdnly dbl _dcy; //=1-_α; Hot pth: rslt=Math.FusedMultiplyAdd(prvStt,_dcy,_α*nwInpt); 2.8 Spprssn cmnt pttrn: Whn usng anlyzr spprssns(skipcq,prgm), alwys dcmnt WHY: //skipcq:CS-R1140-Cyclmtc cmplxty jstfd:[spcfc rsn why splttng wd hrm prf/crrctnss/rdblty]; Bad: //skipcq:CS-R1140 (no xplntn); Gd: //skipcq:CS-R1140-Algrthm rqrs sqntl A→B→C pplne; splttng frgmnts stt mchn. 3)IMPLMNTTN STNDRDS(evry indctr): 3.1 Fil lyot: DIR: lib/[ctgry]/[nm]/ (eg lib/trnds/sma/); REQ fils: [Nm].cs(mn impl, pblc sld clss); [Nm].Tsts.cs(xUnit); [Nm].Vldtn.Tsts.cs(vs TA-Lib/Skender/Tulip/Ooples); [Nm].md(docs+frmls); [Nm].Quantower.cs(adptr); [Nm].Quantower.Tsts.cs(adptr tsts). 3.2 Clss dfntn: Nmsp QuanTAlib; [SkipLocalsInit]; pblc sld clss; impls ITValuePublisher. 3.3 Stt mgmt: Sclr stt: prvt rcrd strct State grpng all sclr vrs; Mntn _stt(crnt)+_p_stt(prv vld); Bffrs: RingBuffer f/ sldng wndws; Rsnc: prdic fll rclcltn(eg evry 1000 tcks)→lmt fltng drft in rnnng sms. 3.4 Cstr ruls: Vldtn prmtrs: thrw ArgumentException+nameof(); St Nm: eg $"Sma({prd})"; Sprt chnnng cstr: pblc [Nm](ITValuePublisher src,...); Evnt sbscr: src.Pub+=Hndl; (no dfnsv nll chcks whn src is nn-nllbl). 3.5 Updt(TValue) cntrct: SIG: pblc TValue Updt(TValue inpt, bl isNew=tr) w/ [MethodImpl(MethodImplOptions.AggressiveInlining)]; FLW: IF isNew→_p_stt=_stt thn advnc cntrs; ELS rlbck _stt=_p_stt; Vldtn inpt: if !dbl.IsFnt→sbstt lst-vld(strd in State); Cmpt(aply FMA whr rlvnt); Pblsh: updt Lst, invk Pub, rtrn Lst. 3.6 Updt(TSeries): SIG: pblc TSeries Updt(TSeries src) adjcnt→Updt(TValue); Crt otpt srs; Cll stc Clclt(RdnlySpn<dbl>,Spn<dbl>,...); Rstr intrnl stt by rplyng lst Prd bars(or fll srs if rcrsv). 3.7 Stc Clclt(TSeries): Crt indctr instnc; Itrt src srs; Rtrn otpt TSeries. 3.8 Stc Clclt(Spn)(prf-crtcl): SIG: pblc stc vd Clclt(RdnlySpn<dbl> src,Spn<dbl> otpt,...); RULS: Vldtn args w/ ArgumentException incl nameof(otpt) etc(MA0015-frndly); SIMD pth optnl-bt-rcmmndd f/ smpl/nn-rcrsv; chck Avx2.IsSprtd; Us stackalloc f/ smll bffrs(thrsld~256)+intrnl stt bffrs whn SIMD nt applcbl; Sclr flbck mst hndl NaN sfty. 4)DCMNTTN STNDRDS(^8): Mssn: prsud skptcl rchtcts via crrctnss+rchtctr evdnc+bnvlnt crmdgn wt; rthlss w/ mth, knd→hmns; Audnc: prcttrs wh val implmnttn+trd-ffs; Vc: GRINGE blnd(Brysn wrmth; Rch crsty; Sdrs slf-own; O'Rrk cyncsm); Argmnttn: stl-mn oppnnts, rbt w/ dta; Evdnc chn: Why→How→Prf→So wht; Fl-Flt-Fnd ok; Lng: drct cdnc; prcs nms; avd "we"; dlbrt sntnc-lngth vrntn; "cod as evdnc"; Hmr: allwd f/ cmplxty/cntxt; NT in prf/scrty/mth crrctnss clms; Anti-slp: Frbddn wrds SET{Dlv|lvrg|pvtl|tpstry|lndscp|frthrm|"is all abt"|"unlck th pwr"|trnsfrmtv|fstr|smlss|csystm}; Avd em-dshs; avd frmlc prfctly blncd pr/cn trps; Markdown: strct CommonMark+markdownlint; wtch MD022/MD031,MD030,MD032; incl prf env spcs(AVX2,Trb stts,smpl szs). 4.1 DOC_TMPL(rqrd sctns): Rfrnc: lib/trnds_IIR/jma/Jma.md as cnncl xmplr; Sctns: #[ABBV]:[Fll Nm] + mmrbl qt; Intro(1 prgrf): wht+ky dffrntr+msrbl clms; Hstrcl Cntxt: orgn+knwldg gp+prr art+impl diff(2-4 prgrf); Archtctr&Phscs: systm ovrw w/ nmbrd sbsctns pr mjr cmpnnt; ea cmpnnt: prps+bhvr+cndtnl lgc w/ LaTeX; WHY dsgn chc mttrs; IIR/FIR→incl trnsfr fnctn in z-dmn; Mthmtcl Fndtn: dtld drvtns w/ sbsctns; ea clcltn w/ LaTeX frmls; prmtr mppngs; Prf Prfl: Oprtn Cnt tbl(Strmng Md,Sclr) w/ OP|Cnt|Cst(cycls)|Sbttl; idntfy dmnnt cst cntrbtır w/ %; Btch Md(512 vals,SIMD/FMA) w/ vctrztn anlss+spdup tbls; Pr-bar svngs w/ SIMD/FMA tbl; Btch effcncy(512 bars) tbl; xpln imprvmnt mdst/sgnfcnt; Qlty Mtrcs tbl: Accrcy|Tmlnss|Ovrsh|Smthns|[Cstm] scrd N/10 w/ brf jstfctn; Vldtn: cntxt+Lbry cmprsn tbl(TA-Lib|Skender|Tulip|Ooples|Othr) w/ ✅/N/A+nts; Cmmn Ptflls: 5-7 nmbrd itms w/ spcfc iss+qntfd impct+frmls f/ wrmup prds/mmry ftprnts/cmpttnl cst/edg cass/API usg; Rfrncs: acdmc/frm srcs. 4.2 Sctn rqrmnts chcklst: [x]Ttl:#ABBV:Fll Nm+mmrbl qt; [x]Intro:1 prgrf,ky dffrntr,msrbl clms; [x]Hstrcl Cntxt:orgn,knwldg gp,prr art,impl diff; [x]Archtctr&Phscs:nmbrd sbsctns pr cmpnnt,cndtnl mth,z-dmn trnsfr fncns; [x]Mthmtcl Fndtn:all drvtns w/ LaTeX,prmtr mppngs; [x]Prf Prfl:oprtn cnt tbl,SIMD anlss,qlty mtrcs(1-10 scl); [x]Vldtn:lbry cmprsn tbl w/ stts+nts; [x]Cmmn Ptflls:5-7 nmbrd itms w/ qntfd impcts; [x]Rfrncs:acdmc/frm srcs. 4.3 Doc lnkng reqs whn addng indctr: Updt: lib/[ctgry]/_index.md, lib/_index.md, docs/_sidebar.md, docs/integration.md, docs/indicators.md, docs/validation.md. 5)TSTNG PRTCL: REQ tst fils: [Nm].Tsts.cs, [Nm].Vldtn.Tsts.cs, [Nm].Quantower.Tsts.cs. 5.2 Unt tsts(xUnit): Dta: MST us GBM hlpr; Nvr Systm.Rndm; Rqrd cvrg bckts: A)cstr vldtn(thrws ArgumentException w/ ParamName); B)bsc clc(Updt rtrns TValue; Lst/IsHot/Nm accssbl; knwn-val chck); C)stt+bar crrctn(crtcl): isNew tr advncs; isNew fls rwrts; itrtv crrcns rstr; Reset clrs stt+lst-vld trckng; D)wrmup/cnvrgn: IsHot flps whn bffr fll; WarmupPeriod prd-dpndnt; E)rbstns(crtcl): NaN+Infinity us lst-vld; btch NaN saf; F)cnstncy(crtcl): BtchClc==strmng==spn==evntng(All 4 mds mtch); G)spn API tsts: vldts lngths w/ ParamName; mtchs TSeries; hndls NaN; avd stck ovrflw lrg dta; H)chnnblty: Pub frs; evnt-bsd chnnng wrks. 5.3 Vldtn tsts: Cmpr vs Skender.Stock.Indicators, TA-Lib(TALib.NETCore), Tulip(Tulip.NETCore), OoplesFinance; F/ ea extrnl lib: vldtn Btch+Strmng+Spn whr sprtd; Tolrncs: ValidationHelper.SkenderTolerance=1e-9; TalibTolerance=1e-9; TulipTolerance=1e-9; OoplesTolerance=1e-6. 5.4 Quantower adptr tsts(req): Cstr dflts; MinHistoryDepths; Initialize crts intrnl indctr; ProcessUpdate hstrcl/nw; dffnt OHLC src typs. 5.5 Chcklsts: Mndtry unt tsts incl cstr vldtn, isNew bhvr, itrtv crrctn rstr, Reset, IsHot wrmup, NaN/Infinity hndlng, md cnstncy, spn vldtn; At lst on fll vldtn st(Skender btch/strm/spn)+Quantower mnml st. 6)QUANTOWER ADPTR: 6.1 Fil lctns: Prfrrd: Plc [Nm].Quantower.cs+[Nm].Quantower.Tsts.cs in lib/[ctgry]/[nm]/ alngsd indctr; Altrntv: Plc in quantower/[Ctgry]/ sbdir(lgcy pttrn); Bth lctns ar auto-incl in quantower/Quantower.Tests.csproj. 6.2 Tst prjct inclsn(automtc): quantower/Quantower.Tests.csproj incls: <Compile Include="..\lib\**\*.Quantower.cs"/>-all adptrs fm lib; <Compile Include="..\lib\**\*.Quantower.Tests.cs"/>-all adptr tsts fm lib; <Compile Include="[Ctgry]\*.cs"/>-adptrs fm quantower fldr pr ctgry; <Compile Include="**\*.Tests.cs"/>-all tsts fm quantower fldr. 6.3 Implmnttn rqrmnts: Inhr fm Quantower's Indctr bas clss; Us IndicatorExtensions hlprs f/ OHLC src mppng; Impl MinHistoryDepths f/ wrmup prd; Hndl bth hstrcl+strmng updts in ProcessUpdate; Us mcks fm quantower/Mocks/ f/ unt tsts. 6.4 Addng nw adptr chcklst: 1.Crt [Nm].Quantower.cs(in lib or quantower fldr); 2.Crt [Nm].Quantower.Tsts.cs(sam fldr as adptr); 3.Vrfy tsts cmpl: dotnet build quantower/Quantower.Tests.csproj; 4.Rn tsts: dotnet test quantower/Quantower.Tests.csproj --filter "[Nm]"; 5.Add → ctgry-spcfc csproj if adptr in quantower fldr(eg quantower/Trends.csproj). 7)WRKFLW&TOLS: Tols: seq-think-mcp:dcmpstn/plnnng; tavily-mcp:frsh API/lib info,.NET updts,prf pttrns; ref-tools-mcp:.NET docs,API spcs,SIMD intrncs; wolfram-mcp:mth vldtn; git-mcp:cdbas srch+cnvntns; qdrant-mcp:prsst dcsns/bnchmrks/pttrns(no scrts); Prrty: ref-tools→tavily f/ .NET spcfcs; seq-think f/ cmplx; qdrant f/ cntxt; Dv cycl(cmpct): 1 Rcll(qdrant)→2 Anlyz(prfl)→3 Invstgt(git+dbg)→4 Rsrch(ref-tools+tavily)→5 Pln(seq-think,STS)→6 Impl(C# 13,SIMD/Spn/stackalloc,mnml cmnts,no rgns,no XML in impl)→7 Dbg(BenchmarkDotNet,cdgn vrfy)→8 Tst(edg cass)→9 Vldtn(crct+prf,str bnch)→10 Mmrz(qdrant JSON rcrd); Git plcy: No auto-cmmt; xplct usr cmmnd only; Pr-cmmt: tsts pss; vrfy no hotpth allc; vrfy SIMD cdgn; Cmmt msg: <typ>:<imprtv vrb><wht>[scp]+why+prf dlta+rfs+bnchmrks; Typs SET{feat|perf|fix|refactor|test|docs}; Cmms: cncs tch; bllts f/ lsts; cod blcks f/ exmpls; prf nms incl bsln+optmzd+%. 8)CNTXT MGMT(qdrant): Str: rch dcsns,bnchmrks,prvn pttrns,dprcatd apprches; Rcrd frmt: {dcsn,bnchmrk,pttrn,src,dt,tgs}; Qry strtgy: Bf/Drng/Af wrk; Evnt flw(cmmt d7dbd70): F/ ITValuePublisher indctrs: sbscr in cstr w/ src.Pub+=Hndl; (dnt str src slly f/ sbscrptn); Us strct-bsd evnt args(TBarEventArgs,TValueEventArgs); If MA0046 flgs nn-EventArgs sgntr, spprss lclly w/ trgtd prgm+prf rtnl. 9)RFRNC(ptflls+prhibtns+dn critria): Cmmn ptflls: LINQ in hot pths; nw insid Updt; ignr NaN; incnstn 4 API mds; mssng ParamName in ArgumentException; mssng Quantower adptr/tsts; frgtng docs/validation.md; usng Systm.Rndm in tsts; Frbddn actns: DO NT LINQ in Updt/Clclt; DO NT nw insid Updt; DO NT chng Directory.Build.props w/o xplct instrn; DO NT rmv [SkipLocalsInit]/[MethodImpl]; DO NT ignr NaN/Infinity; DO NT skp [Nm].Quantower.cs+[Nm].Quantower.Tsts.cs; DO NT skp updtng docs/validation.md; Dn chcklst(cndnsd): Src vrfd(PineScript or equiv); C# 13 optmzd; O(1) whr pssbl; SIMD whr pssbl; FMA in hot pths whr applcbl; all 6 fils exst; Updt hndls isNew+NaN; Updt alloc-fr; Clclt(Spn) impld+ParamName vldtn; unt+vldtn+adptr tsts pss; docs cmplt+markdownlint; all rqrd indcs updtd; CodeRabbit isss rslvd; bnchmrks rn+strd in qdrant.