Upload 4 files

hrm_all_in_one_API_Reference.pdf

@@ -0,0 +1,225 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document http://www.reportlab.com
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R /F3 4 0 R /F4 5 0 R /F5 6 0 R /F6 7 0 R 
+  /F7 9 0 R /F8 11 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/BaseFont /Times-Roman /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
+>>
+endobj
+5 0 obj
+<<
+/BaseFont /ZapfDingbats /Name /F4 /Subtype /Type1 /Type /Font
+>>
+endobj
+6 0 obj
+<<
+/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F5 /Subtype /Type1 /Type /Font
+>>
+endobj
+7 0 obj
+<<
+/BaseFont /Times-Bold /Encoding /WinAnsiEncoding /Name /F6 /Subtype /Type1 /Type /Font
+>>
+endobj
+8 0 obj
+<<
+/Contents 20 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+9 0 obj
+<<
+/BaseFont /Times-Italic /Encoding /WinAnsiEncoding /Name /F7 /Subtype /Type1 /Type /Font
+>>
+endobj
+10 0 obj
+<<
+/Contents 21 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+11 0 obj
+<<
+/BaseFont /Symbol /Name /F8 /Subtype /Type1 /Type /Font
+>>
+endobj
+12 0 obj
+<<
+/Contents 22 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+13 0 obj
+<<
+/Contents 23 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+14 0 obj
+<<
+/Contents 24 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+15 0 obj
+<<
+/Contents 25 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+16 0 obj
+<<
+/Contents 26 0 R /MediaBox [ 0 0 612 792 ] /Parent 19 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+17 0 obj
+<<
+/PageMode /UseNone /Pages 19 0 R /Type /Catalog
+>>
+endobj
+18 0 obj
+<<
+/Author (Generated by ChatGPT) /CreationDate (D:20251016100229+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20251016100229+00'00') /Producer (ReportLab PDF Library - www.reportlab.com) 
+  /Subject (\(unspecified\)) /Title (hrm_all_in_one \204 API Reference) /Trapped /False
+>>
+endobj
+19 0 obj
+<<
+/Count 7 /Kids [ 8 0 R 10 0 R 12 0 R 13 0 R 14 0 R 15 0 R 16 0 R ] /Type /Pages
+>>
+endobj
+20 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1742
+>>
+stream
+Gau0C?#SIU'Re<2\-Oe<fj)R\*S^7Q!a1tn"k#<P[&:DFBSj%&:o#ShDR+EbI>=&'a%^A-`f^=Q6A_''glHLe4_j$/F+9sDkgt=pcTUiH$52p@XY'bnF;F4khXda#H_"2uqJ@=XU($@)[pDc%Yglr]_nHPFI.EgS^Lus+gT>XGJ@@g<NG4N/9SbBfTotp8^>GiPbBJ'I'4,VqnH0-tU>SOfH%-c<q&R6-\C9co\E!6d8#8]ro%NfjU9d$@:+0"Cc6C`5i9J0"H?e<Fp+':ZGd(JC42K#Q/=!l@T."<+O\dTPs$]j-h;g&NL2b'?Rp\*N"mHHBl/KB?I!bP#7DUh2'WYo5EI935D)@[F1'3GG-6n^(WJS`a,/LYKRdS[a^8.tX<FP:Nd7j-YQHYS83g%Y1$EfjX\R6:6]YJU4'/gL.:BedSM$IgZhm+dL>dkJ=DMWA3rLIZsH7nT%(Sd%4?Hc@IV8g#H);eDGO!!W@,9%l2hd81S1-Y3q)rK_%B4HM*Yo,^#5i$CIrlo7#L(mC'j+jL:j$dX6*pT7c.2.O%.@Y#u:8]mn_rIVpLX9(VjsEc4P;9"R_AnJcNOdEj"*=,")$@3%rq*u/[cgXM)3T>-<AI,n9mVjhFAbrC`2J7ed9NhCR`+A_ba@@aK,W,8k60Vu)>*1!UOaCrEH[hP_@0#B3=du?ct?7W6G)Dm\X]XdMpTn2^h_PJ.1atQj>.J?Cs:oV`bOLQoUPG2g,U4(RT-)5UCdPA\)t-Ug!$BKk4:D2g;L:\$0<_=6.gHXKQYMH-0#g1#ddjlO\7cdjol!fnmtPM,hHGqHKFZ-hK0"Y>q#@X;VLP)pLmA:JE8d3#Mr2A``A\33O)juro(0@AJ#b#?Xaj8l2f>h)(^qi7'EU1q"8N`)TtE<pgNA5)\49MoJ&"kXtMJ-YI,fCIA16J!5[&fgU!?tTdmo=/adJ`];eTK4ei+*q3k&Tk/"p4%FsW.dAc/q/c+P8i1N_;:^qT,5Q];NQbel.MI4LGPE)bM=ZB[sJ#TPHTX0]/5R:K^dBpTgl13o[Z!C$:b#5@X;,'qg=N'#N(^RXK.N,)I8l[hqN%k5!8?cR?WFWl)h1gO)$$;&%`9&P/d7VbFY)[9S88#nAO#:k_p[Gi)%)=(HcI&XI0U7q=Z,0JbV#/PTPf!(Z(9RQF7d#+<gZV1>/1G85hGS'a)pMC$`cY*=4%"9iYWr=Fhh1%X3D&GNZCiDW_/:;3Kd6\]XYC&g<?k)/ZC`R3c8CTT@dRe]CdYq8_rpEGn#B?bRkS[H]E_4,FTTTjZlZ0l>O.]`;AIg9mgT1SRR><81qSn+nb)l7?cPcgID+M`4E>$&po0#2Nq_pLqtGn`)isf$brtC_+gRu"[n"nON5P+E-3V2?BY&Q=\eH6s_$OEd*=UO$K6n2aTiJ+$LecqRBpKbNVD0Fs45?DER.D5Y"(@/93&dO#G)#4)ZTVu.[q>2K+ocUlnN3mnPiGkG5ZYGm@:g$O?m#4*EM,S>K&sNXYt97GV<'-A.KXgfcn.:gd?IN2T;meqrNi+g.rZ*9r?:""$?<hno[q,`,VW7h.(aub]f:&S_Ss$L<q*8H@Q].E/&a'g$gM!?mq1jlkpTIr+C!-s3q(caHabIZGCqZ?SI3NfaMHAD'>BfjWW\@mC0VbFm,80Q=gHF(UefY&>0P,<+r;d*_P#\;J1=Z+LFT3qV^X5tT(CS8:)%8ECBi1J(Vl*gXb5'&l*I9#4mi1Q;>UQ!~>endstream
+endobj
+21 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1621
+>>
+stream
+Gat=+;,cL5&:WeDm%i*%\E6,JKKqnG1Nsh_4j^fV8Y6:K;/A6n,?m?'-FCJcpTA$g`l>hO^jpEJ=5SJ\:TJVGLu46km6q!s(3"<]J2;dG!7#+/J]/('/WROc3P"6n4IF"=d!XnC7mDHf1_;Dd>#YGOOlU1hmH"*L6PVd%%V)'H,/WQAn?[BKllnC8o+fL.P,+!)b:no7e6hpVf[/8N>#H"+@E!r0E>AA?c:=e]jmb&Vre/60kU@,jS>*X!mY:H95JTK((+6))RBJY-\.S7W6";5%*BN'OTu5!0nqN5)/Ri1l^X]Z]St0NIIV[/F#idHlb]7M5S(bfj+MR.T9bc,q&6DnW[`7QNqL9AG4l8bDD<5>I`u*a$&ukNe%$4ekXqM!q:*U?,cH++nD-4TPn'ZI*R0m5lH('SWaM0e7C6XB-]aLP\@<'QO:%_jf*t\pVgn2EL`!5=Ik^IIKn\^gm<_1!0cW;j)C0!`;k&FQ\bhpufb;u'mM_uD6U[so\d9]p0W>WWgj<BNlQ)_&*eqaX]+Q2Iu&q]/a$^oGCKbmX*P6gf(Kg^[WF$`'K\E62,T4Kp`8uTc9=&7UhR*sQpE8LCCO5]If=JR@0]D&9?$R77I:\N`l<lb`9MLEKm2?EY$WVcRZj=m!\$9;'b0KIDCdBSJHan6L@@9/[_"[fIq>lff\N,<r#]+8$9i7VT?DLMan:b5o`i&4:B+glntl$A>-i0nm)o'09F^^+&L-eE"C"aaC3cb!<7K>F4M)jH/)G($Fs_KS[b-lAk!61q"ESKpUYc@u3Q\nGCPYu=E"IK1mbi]]#B%W4h;BLDPm+:W9m!/[M/`qfahN%bO/A(8.t#otol/*6@RR`Y9jE%meAPOUXa[a6g@4:b<:<Wa]FLfN&^LrqU"`49-m\J%0c:C"<O&o(t!P/M1n0/cSoqhjB>\fu*9.+37:^M!#mAUfffm%H,2Z/8rJLCf<m7BqJ4S'/)r0%^I9k:>P/5RS^]2$A->'0M7`_d">4fH7p+,f/sWY.i].MWudi1&/Ua-ajcp0;%!_;6q+Z<@pl`[#gOdmO#6'2mk-MbL,M^9F5@rG-Qk]V;g5?Ed0Q7F3M+%r,`C%*?D3dI7.f1gVnpQ_AR)'-.#p=[r=>k58\"3SIDQmarH'20jeO(&<hp=o$I3KA2L?hX*KVd$`LG7kbl(to5``C==*$Z0YC8%g6UC`i5A5*pT)!1D,:.-eB^rTiJ+<_2.S(D8t#:Y"o4arrY<MtDMq>rWU,CTRt?4pRC5lCJuTX(2NW]0YjD+$+?p]9Ya-I5*E%tuV_U`-b<FVaoPbg7\TbD(rL?>-U_6Oj^``Ag!B<,FJbc\Y_3oYrIWW'0?/GJ5!$/54B=Fs90msW/V.i.`_qFHGO:Xqp5tE<8-p(%FS`iq[%K58NBt3RSrnTI#2-ITdI;I;U&jm]`9<"3I_q"Ck<J9'2.%ff6V_b:-7Cb#!=liBs;,(Y1-BN91gOm$N<qCu&.Rk_SS"+k,ZAJ4V*pjO7EdXd@s6Ak8I(F5U6OrtGp"&5#'#f4pCW<fnRFfZIehAi3*^"A2`QB5UDjn)6'DB/&B^SPu#+9bWaJ/9:pipM731CsE<_#Ppg]X%fB)10#_9m``jGgk~>endstream
+endobj
+22 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 634
+>>
+stream
+Gat=g?Z2Df'ZJu*'^'$?R8OA;Tj=Qj>16NPKXP^WX]1E!SA\()WU6e@\)2=Y."BgE$ODFT\_"m:HZ+S!mV)QjPe_Ero=G9*N,4BM+7t\l\BVZ605?_C01_05&mC`ghOBYi;l*-!/MBRe1G<#!oZX(0D%*76ia@;<V!J2rF.^qS-7SkURDl[F`H]LRn>48*%^M_JhSKM'6<5Tu(59;N<I-D21+nR7h&T?5q(IHF08_9-WN8pZ/K]YQO8+7O9(H8a4,J'RYqrg'Z(8N:h*gBGS:02G^Ki%.?OuYF@?'a?YINf,BPI,NKak2-/c>(m)N6l9TMe6=CPEZ`"NUSgU+h6t(i!X+XgD83^Jju^Qq=,7C$*&:i9J=iffLh)'U;_67)=fUS&6Z^dEf[KX:-DR=U##E6?5h!:^^[P<e`2]o9ES-TA5dU.17;3Gph7<EQBB[nCYS(X!uOG5JKiL/6ZfX2uQ$(VFo-Kpis=:Arh4M^$R^G+*ei5i8-m7XTb\bGT0nZm&__ZrtnC7a=E5r-QB*:8B,<M\kl+V^[,^RMV8a3DiVBnTBp<r'm"jDfkYDY.%+D/[dB)8NDF`oNSB_ajs;*Dh4KCl]1HjMQhuu:a+NFq7C2-RGgARd5IEq-qZ~>endstream
+endobj
+23 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1425
+>>
+stream
+Gat=*@;k0a%/o$i5o_So*HI/\[qW"_J9C7%)piKYk/0A>Kq[.@U8okkP+5kPlUT(%'.:>t>6DCDo^k[OjJ,$IkSLgC=p"U=_sfR;E!1.jiL,0"nK!"9:]<Naf>qsmO5V:Mcr=2sGi6Tlr.LAj*?2+2M.m+OfJ8EfbN$R!EP]Wl']RFMIqsmjVr&![GVV<T*d-P+F*"u;^Qp),YOG%Zd-uPVTJ2_4AB&$N^_AkDO(&\i'E>^"H4D%`C[OMW<e&2X@;3QbDN/u1$b"j$m&#=4A8S@#,T0[MTT+QliE\78LC7*/WYY&LGYse6<\dtE9AmYu54$O\lq=&^<]'bZA[iGUGU2&X!Ip@9He8[*P2VS%Ql,-r11MY:,b"ac/bu3O@'3VO;4*$5BjK9nZNaTSLV,'t.=9!i@YQl668Ae_pLcYE$k4Eg;ca.Nr6u,P%g/KFq=M$!FI'@KqYn/NT._U[R'P6H(AL2QWu%YU]!=M>fn5:Y6>:Y6#g/$Agj+C1Eh;2%eZ'!C&G,sk/[:?R"Zm9#ZJlUT@klCCYi$fd/MQI`ngYVd_G&+(VJ]P1q^4SN\#*Y8pLc?menlUg/p`]gF^8I>.p6bd(8^B6e=q";<g4K-WpK7W'P\=2^*+q<W(g0a;*=4q_M2]*8?Le:Ua&c@WJ'Sj&r>D)m+b-#WL_2;iWUC>]eGSn&eo0U-CEb(onIEBn4LgKR$otoWV@.C8j'i'akDcRN@$qARXM:H)s)BAaZd6Xc$CO9\&pS@N@8]a/Seo.]K9?3W*lkSWMi?#l!.&!+Ra.#cfo+uPaD"QSqW\K++D>Jq),f*GC3_p8aE@8.1`qcZnoK,84nBN1Xt@T%8p=:j256,=M_*EVRgULep5R_BMEd^9Xfa02XK1P%b#*5!DNUF($ROrE6!`pGtplJQO$=p_2=q/EhE8cH9,9dJK@\56QXku[2(9-7hcQhRhTi?l/i>%HMF;P/4bJ:>uaeUY^P\,hVr*XeoYOF?$!NIfX%oUi5._8*Co:*s/5bN;e(mg\8tpdeSu8]Ir<&1Z\q0[\8QWWo`\W5=BpFhrk6P@!XF.-E/-t.T33>JTgjLohKMfe)$M%cg+(7Gg;pcEDp*4+0CUQ;[r>j<n>`k+0PoVfS8NOX;f?un]>PH&>!]W9!S=D$XK"EIhXK#s,oJO&mHJ<bHUD.[W$Y(h'._$n/e4%OM&#P@\b0GH>,ncF279d0dB%&:pJc-R%lgA/YK5NSNVg%-f53gI>&m?fAt%KUr)-ZD+DinBCiY<>7=EP48cTSL?#DJ^.2H=',#I]ji+,cd.XS#PR2u>3"Ui"ehK/Na?!p5ZQYiHo1_Fl9>"M$EYl7\eA/6sCI\t5=[':>ZfG9YOU]kt5FoYV<%qLuL^sr4T1N`AbNB,]AQPiS);ECT;!n6=);G/?o>t':-IfX$oKS9~>endstream
+endobj
+24 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1357
+>>
+stream
+Gat=*gMZ%0&:Ml+9G],D'Wu8oQS_k?+hNT9$eSR"TY;9T(l>QO:o$]]p81:Y]gGE_ARe5e@DIsQEb<VdbaJ!pLHj\p`u2[j&@rMsquFSJr.-eWE!l?u`SVJ\[<'jl7W?oDiMSZQFZeW$NVHT3&AeiOg2l)l#lL9"8_oCJW$Sf,R8=BO[Lh:h-3^<*b=`-@_VP1XmPZVJi!Q?fm[&\H\.]r-Q"iZc!a23+O>s,J5r23qKo&p+42Ar_ja(nQ6mSG(.?jf6$&_N%AkdY'%.88`_V_$"@:fZp0"#SBocca$Nk_4ENrD!J\)3.q.)JBj,tY&PB^^a#;tk;Nod=5.("FF*pp[YbfBQbF%UeTe&&+p&P9aRG#u!^[C!m%![=hf,2+o@)LbVjG-:O.2rR?XBF?W%e6j<J._7M:X%.!WtaP6tbph?gZ@cUoB,h12n=A4j`LPY>GQWFM0!CCY?0K:!R>n_\RP268V?:C9(]Ru_(-BW:U/Jc9rF_n/(!%!Le=/H1+;e9c^n\Rfh5oZ6Tp9HW9F&7R(8k!]B.Uji)[_s_MQFWXDgM-.p'..ShN6$(78;7q[FAmE3jPrtnAQTL#69g@H)WQb_8!\,jQFlu;jccNFAHh9.XA>d2I6?!f>CRQN';b(./t;Vp4C9CDPVeds<f<\O]Fttl:fGiZk[Vcd-lf)#8uHiY:CQd(63Pl'7J042-Y./P"RUS^8EcM]'Hn?nig!TZ^'3(.9hE0\$^76d7-2fbHZ@^Qm7mrP3"Eh9b-8LA!.=g>d%"?F(U&0&>R/=@i?'DBIj?0J"^Zjb;/j6c;0+1-E8>3,8A\33D0me=K'rj'FuK)&.[PC8CT>GgYF4Cf1K<VNg8,=J)S'cV191l/Yu=]g<#_gQ*ggr9fO2`hVMXCSFt@0eAAXiHbjKl7U'I=blnB%C!dbeNrot]6ohZupW^n';hog6"gkJ.'6eQKkoXb9-$N=;]NMf@*)CDh-Pd/'T#o5@!`<0P;l;Q3)?n4"RN4I3N]i*Jg=_\\-@9-o=]oNk-N.R/Nh.TaJ*G2JUh(UgtMXGtU/EaCV^0fRnFfm.dqTM\caW,ZK;1CQg#,Bo4&?[O=JTD[+9,PQqa(gt3(F;b75?(P5`Q%.lk^Y(eLupI!l*9,s%5R*$U;G>o4M`1um]+$-d1))]0PB@^ZtaiDEfBD$rd9K>p$=KSV[es)FH"V\2!H$IR\,bm^HPlEl5FSAZi4q9\s%HA5=24DXcf>Rm>k,"D5V3TY-6^?<,4F9h;itdW?jV9[r*eDq26OJd,*WZ<JoAP2P4(q3"W^$oA,*sap!fu>>Z](f$aXpD7FmmJ^&-%8hS`sV4?8uQSJF+pNeL)(L6kK.H.S(~>endstream
+endobj
+25 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1292
+>>
+stream
+Gau`RD/\/e&H88.EA0)^*^!Sgh\$#/cnu+`@-ub#rDXL5,FpAD&uh##'<gVLhbgZogU40'-nl$jKd1jrcTQJB%pXFnnf?flJ'=R0kCMg6/-0\I$t/cFgs.PO\a\037t#"QA+u.PU7C:^.9H*K3pP8LkZglOI.0U+POD[<mFNdV%u')]E&!+hgccHNR1@HT_!G-<jrHU3VFHpOBiFua<53O$<1;6OM4nMf)AH@)?%+_7o%$,*10']4Pquo(She7p=sf2_Xu!/\&)kZ[-7*]QbQmNp")X]</n<*P+GB>U`et8;40&N@kle@j]Aae>Mj[uepq&4b$C6+OiK<qH2qm)[5Jo@kQ(j;H*H^5KhfhJ"pj9gfRpbs0RooRG\a*WrHF,n5YSnRFcVpTiBlLL)LW>Wl#_bU)C2*:B;l25qB;K'YUidAJ8?M]9L(<"D/CSRaU'E@b,$D"i1PQbU@u:tfM!N^Q.]2(Y@,E?:?MMh!GYr!6@O2,_4A:mVPm`>1;e4=tLCj'(#H!B79)^UmBX7ml+CRB:."n6FE/=o9iu3'eEDA<*3#nL6iK>Kq,kE3)85ItXN*aZbn_b[FGE!^(mk-]F6S[KY/0Tn&s,60rZ>a`A+LLWm9[36]oaTf^%re!$IYuPUYG"P\]q^gp3YRVnP!t\=+I:D!7mUfT<&ZP)822;,YDB*n<.R^m>b&ZQf3d:O&@?]aCe6Hm`:fkq*%YepptY\>V<@tZ;9B@4-F,YoM,Y4S7)B"j?>ms<$<:2c2kh<D9,ZEHlS_&;C+u^e[HT_:OAMqA]gGb;nG`.3c'qobNuNo3^T&I77CiQ3!k3A4Wo;e[#28O.Jee-oZ>Dteqr=,Jj;b!ZkVW&hDFhIUaZPiY\!MAPfm[,>J*$[EL"=+uTY4=diR2l(60hXtdFY@\qq@KOnt'Ed2H[=5eLE%]9D\$H8UbO05E1DX[3#,G1%r_r]$M)<TXM`7KNadILt9&;dQLU:rb-7GVc64C4-U+O/<"H&(rm=u6Oj>SD3k1+'HT.S[*-Ddf_kEUoB5S7$()DWRXc[gbp8[O$+\].8-cSCg3U2cqsKcN>u30rW>)ut4fD=H3E,;j,uNnnSc!,1[Z5S"!T[BDL1=[/[Fh?Oj'B7Zgd"(BSoO(7KD+8,1o+"T2.G@6]`6H:[kUE]dX)%=-s`$frqON9kBTc<PN.unV"$EMRFG!'[u5XFW^as$dd.&$Ncor?q>0-r/)^8Lkg;9<*i3XY[8q--%G=`KZ4Ejc/W:*J>k4heSW="?.j8+DKCph8=?rAYDSX5@649P&~>endstream
+endobj
+26 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1122
+>>
+stream
+Gau0B?#SIU'Re<2\.DI^)(J(<-,jkZ5-3D@!\)K=HCG.jQ7.[!6ujR7`%C]?G=af<j!>IU1_=&V=5s0<pY8,+&E4A6hm*@Z-&8PY,)B^LCP\,rJc$:4c-QALMmcu)P9>KnpT!T,*]go:T&J(1kA:j-OE]o(!`<X_esl>TnVN]@E=Je=Yb9\M=VKAL78'>KCK=>@*/(>jRR,V.">1ktN/jcjNok>MD;Y:F#]rt:G-I3Zi*PP1ft.4!kFhNb3ZY2JW'#fJi]Ll!F"L?]9YpUD`;Og@\:=0KdG^1\eOQ@TPMr`EnH7>kgh_n*%mnPpmcTqp^BJK(U[X&Te*tl$rn.Qg!+SmF8pEm3_>M/s'kBsUIea1_d^C&0Ug/H_2A__3(uEXGhT68rbiTRo/t[?^lNj]PQ>m9#3Mo[f,hMtRh<k+8jmeGsbufmrVg$H-[6%7Y884fLJ1_S#Ai:9C)ZH\LbDg3=LIQCi!a[Qe#YkK4JY1*dPdg,u;+ho4_;E;cOJZMdrZoshU66oc;XWUV"j+`@EqT[Q`V(p1elERH%SMM5(t&bCio(/43&@&kW$d@<pi@?M2Ui?RRja]#/b3P-TkTb)GjDf2!eB`Td4;#5;pSY$$-l^DY3sr"eVmN4ji`tSVPmU2R,CALL,6,H#)jb)Y'+aI^%(UmJnLFq[V/+?o!O00MPl)`R'IT'K>DB?=+8+&/>\2a0dsRMduu-sjO-/NH#e>=;WSAk@RlZki94(TRLqAV)brGYY:YN5[\@_YS'`2+lBsLG\31oW7$@O'%=aZTqc;FPr-J/#EM!'ZG22'SX,#e6Ds#_Kf3o4;hJ7&>FjXl@>Iug5Bt(L?`4/7$7OEC:e8@ufH[![j`Jt)Xbc%-4H[\4Q9?&!Q^6<he3?L"0)D"jFZI+JpX%GZGrPYg,De*c++buo.Z3@7W#^D+cZ.Q7-aplJpO9OU6hfH6'8u'3=21D2;`g9/BF4-CII&<`kh`lNChjDg)DrH@4R`1pZhU.IAZVs=[PP'a+-K1?PB.)[S.C'lu3sg73=cK9Pdba?olFq*o:l,g'H+[!)E)J+gis$'C"A,Q:aD=Nkr]\$RCfmoJ@Pj+-+%&'nm`D\ebqTD5m\TLe5]HE=;\p>p~>endstream
+endobj
+xref
+0 27
+0000000000 65535 f 
+0000000073 00000 n 
+0000000178 00000 n 
+0000000285 00000 n 
+0000000397 00000 n 
+0000000506 00000 n 
+0000000589 00000 n 
+0000000694 00000 n 
+0000000802 00000 n 
+0000000997 00000 n 
+0000001107 00000 n 
+0000001303 00000 n 
+0000001381 00000 n 
+0000001577 00000 n 
+0000001773 00000 n 
+0000001969 00000 n 
+0000002165 00000 n 
+0000002361 00000 n 
+0000002431 00000 n 
+0000002742 00000 n 
+0000002844 00000 n 
+0000004678 00000 n 
+0000006391 00000 n 
+0000007116 00000 n 
+0000008633 00000 n 
+0000010082 00000 n 
+0000011466 00000 n 
+trailer
+<<
+/ID 
+[<94bc6889bc74c708b33a04a081270cf8><94bc6889bc74c708b33a04a081270cf8>]
+% ReportLab generated PDF document -- digest (http://www.reportlab.com)
+
+/Info 18 0 R
+/Root 17 0 R
+/Size 27
+>>
+startxref
+12680
+%%EOF

hrm_misc.py

@@ -0,0 +1,1043 @@
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+import os, re, math, json, time, shutil, random
+from dataclasses import dataclass, asdict
+from typing import Optional, Callable, Dict, Any, Iterable, Tuple, List
+from contextlib import nullcontext
+
+# Torch & friends
+import torch
+import torch.nn.functional as F
+from torch import nn
+from torch.utils.data import Dataset, DataLoader
+from tqdm import tqdm
+
+# Transformers / Datasets
+from transformers import AutoTokenizer, get_linear_schedule_with_warmup
+from datasets import load_dataset, DatasetDict
+
+# Optional: Weights & Biases
+try:
+    import wandb  # noqa
+except Exception:
+    wandb = None
+
+
+# =========================================================
+# Utils
+# =========================================================
+def set_seed(seed: int = 1337):
+    import numpy as np
+    random.seed(seed); np.random.seed(seed); torch.manual_seed(seed)
+    if torch.cuda.is_available(): torch.cuda.manual_seed_all(seed)
+
+
+def auto_device():
+    if torch.cuda.is_available(): return torch.device("cuda")
+    if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available(): return torch.device("mps")
+    return torch.device("cpu")
+
+
+def format_num(x):
+    try: return f"{x:.6g}"
+    except: return str(x)
+
+
+def save_safetensors_safe(model: nn.Module, path: str, metadata: Optional[Dict[str, str]] = None):
+    """
+    Save weights as .safetensors, handling tied weights (lm_head <- tok_emb) when needed.
+    """
+    try:
+        from safetensors.torch import save_model   # preserves shared storage & avoids duplication
+        save_model(model, path, metadata=metadata or {})
+    except Exception:
+        # Fallback that copies state_dict and de-duplicates lm_head if needed
+        try:
+            from safetensors.torch import save_file
+            state = model.state_dict()
+            if "lm_head.weight" in state and "tok_emb.weight" in state:
+                state["lm_head.weight"] = state["tok_emb.weight"].clone()
+            save_file(state, path, metadata=metadata or {})
+        except Exception as e:
+            print("[warn] safetensors not saved:", e)
+
+
+# =========================================================
+# Tokenizer helper
+# =========================================================
+def _gpt2_tokenizer_with_specials(
+    additional: Optional[List[str]] = None,
+    checkpoint_or_dir: Optional[str] = None,
+) -> AutoTokenizer:
+    """
+    If `checkpoint_or_dir` is provided, load tokenizer from there; else use 'gpt2'.
+    Ensures PAD exists (PAD→EOS), optionally adds extra specials, sets a huge model_max_length.
+    """
+    tok = None
+    if checkpoint_or_dir is not None:
+        try:
+            tok = AutoTokenizer.from_pretrained(checkpoint_or_dir, use_fast=True)
+        except Exception as e:
+            print(f"[warn] Failed to load tokenizer from '{checkpoint_or_dir}': {e}")
+            print("[warn] Falling back to 'gpt2' tokenizer.")
+
+    if tok is None:
+        tok = AutoTokenizer.from_pretrained("gpt2", use_fast=True)
+
+    if tok.eos_token is None:
+        tok.add_special_tokens({"eos_token": "</s>"})
+    if tok.pad_token is None:
+        tok.pad_token = tok.eos_token
+
+    if additional:
+        new_tokens = [t for t in additional if t not in tok.get_vocab()]
+        if new_tokens:
+            tok.add_special_tokens({"additional_special_tokens": new_tokens})
+            print(f"[info] Added {len(new_tokens)} special tokens to tokenizer")
+
+    tok.model_max_length = 10_000_000
+    tok.init_kwargs["model_max_length"] = tok.model_max_length
+    return tok
+
+
+# =========================================================
+# Fixed-block causal dataset
+# =========================================================
+class CausalChunked(Dataset):
+    """Flatten tokens then slice into non-overlapping blocks; x == labels."""
+
+    def __init__(self, token_ids: Iterable[int], block_size: int):
+        ids = list(token_ids)
+        n_full = (len(ids) // block_size) * block_size
+        n_discarded = len(ids) - n_full
+
+        if n_discarded > 0 and len(ids) > 0:
+            pct = n_discarded / len(ids) * 100
+            print(f"[info] Discarded {n_discarded} tokens ({pct:.2f}%) that didn't fit into complete blocks")
+
+        ids = ids[:n_full]
+        self.blocks = [ids[i:i + block_size] for i in range(0, n_full, block_size)]
+
+    def __len__(self) -> int:
+        return len(self.blocks)
+
+    def __getitem__(self, idx: int) -> Dict[str, torch.Tensor]:
+        x = torch.tensor(self.blocks[idx], dtype=torch.long)
+        return {"input_ids": x, "labels": x.clone()}
+
+
+# =========================================================
+# PAD-mask helper (for variable-length batches with padding)
+# =========================================================
+def mask_pad_labels(
+    input_ids: torch.Tensor,
+    labels: torch.Tensor,
+    pad_id: Optional[int] = None,
+    attention_mask: Optional[torch.Tensor] = None,
+) -> torch.Tensor:
+    """
+    Clone `labels` and set pad positions to -100 (ignored by CrossEntropyLoss).
+    Prefers `attention_mask` if provided, otherwise uses pad_id to detect padding.
+
+    Note: CausalChunked produces fixed-length blocks without padding, so this is
+    only needed if you supply your own dataloader with padding.
+    """
+    lab = labels.clone()
+    if attention_mask is not None:
+        lab[attention_mask == 0] = -100
+    elif pad_id is not None:
+        lab[input_ids == pad_id] = -100
+    return lab
+
+
+# =========================================================
+# Dataset loader (HF datasets or local txt files)
+# =========================================================
+def load_dataset_fn(
+    source: str = "hf:lemonilia/wikified_english_dictionary",
+    split: str = "train",
+    *,
+    text_field: Optional[str] = "text",
+    word_field: str = "word",
+    article_field: str = "article",
+    block_size: int = 128,
+    batch_size: int = 8,
+    num_workers: int = 0,
+    shuffle: bool = True,
+    checkpoint_or_dir: Optional[str] = None,
+    additional_specials: Optional[List[str]] = None,
+) -> Tuple[AutoTokenizer, DataLoader, Dict[str, int]]:
+    """
+    Load and tokenize a dataset for causal LM training. Returns (tokenizer, DataLoader, meta).
+
+    source:
+      - 'hf:<name_or_path>' to read a HuggingFace dataset
+      - 'txt:/path1;/path2;...' to read local text files (semicolon-separated)
+
+    Behavior:
+      • If `text_field` is present, uses it.
+      • Else if both `word_field` and `article_field` exist, merges them as:
+            "<word>\\n<article>\\n\\n"
+        while stripping any <|begin_of_thought|>...<|end_of_thought|> spans.
+      • Else, falls back to a 'text' column if available.
+      • Appends EOS between docs/files to avoid cross-boundary contamination.
+    """
+    tokenizer = _gpt2_tokenizer_with_specials(
+        additional=additional_specials,
+        checkpoint_or_dir=checkpoint_or_dir,
+    )
+    eos_id = tokenizer.eos_token_id
+    token_stream: List[int] = []
+
+    if source.startswith("hf:"):
+        ds_name = source[3:]
+        raw = load_dataset(ds_name)
+        if split not in raw:
+            raise ValueError(f"[error] Split '{split}' not found. Available: {list(raw.keys())}")
+
+        cols = raw[split].column_names
+
+        # A) explicit text field
+        if text_field is not None and text_field in cols:
+            field_to_use = text_field
+
+            def tok_map(batch):
+                return tokenizer(batch[field_to_use], add_special_tokens=False)
+
+            toks = raw.map(tok_map, batched=True, remove_columns=cols)
+
+        # B) merge word+article when requested/needed
+        elif (text_field is None or text_field not in cols) and word_field in cols and article_field in cols:
+            BEGIN_THOUGHT = re.compile(r"<\|begin_of_thought\|>.*?<\|end_of_thought\|>", re.DOTALL)
+
+            def fmt(batch):
+                out = []
+                for w, a in zip(batch[word_field], batch[article_field]):
+                    w = (w or "").strip()
+                    a = re.sub(BEGIN_THOUGHT, "", (a or "")).strip()
+                    out.append(w + "\n" + a + "\n\n")
+                return {"text": out}
+
+            raw = raw.map(fmt, batched=True)
+            raw = DatasetDict({
+                sp: d.remove_columns([c for c in d.column_names if c != "text"])
+                for sp, d in raw.items()
+            })
+
+            def tok_map(batch):
+                return tokenizer(batch["text"], add_special_tokens=False)
+
+            toks = raw.map(tok_map, batched=True, remove_columns=["text"])
+
+        # C) fallback 'text'
+        elif "text" in cols:
+            def tok_map(batch):
+                return tokenizer(batch["text"], add_special_tokens=False)
+
+            toks = raw.map(tok_map, batched=True, remove_columns=cols)
+
+        else:
+            raise ValueError(
+                f"[error] Could not find a text source.\n"
+                f"  - Requested text_field={text_field!r}\n"
+                f"  - Available columns: {cols}\n"
+                f"  - Set text_field accordingly, or set text_field=None if your dataset has "
+                f"    both '{word_field}' and '{article_field}' to auto-merge."
+            )
+
+        n_empty = 0
+        for doc in toks[split]["input_ids"]:
+            if not doc:
+                n_empty += 1
+                continue
+            token_stream.extend(doc)
+            if eos_id is not None:
+                token_stream.append(eos_id)
+
+        if n_empty > 0:
+            print(f"[info] Skipped {n_empty} empty documents")
+
+    elif source.startswith("txt:"):
+        paths = [p for p in source[4:].split(";") if p]
+        if not paths:
+            raise ValueError("[error] No file paths provided after 'txt:'")
+
+        for p in paths:
+            if not os.path.exists(p):
+                raise FileNotFoundError(f"[error] File not found: {p}")
+            with open(p, "r", encoding="utf-8") as f:
+                text = f.read()
+            if text.strip():
+                ids = tokenizer(text, add_special_tokens=False)["input_ids"]
+                token_stream.extend(ids)
+                if eos_id is not None:
+                    token_stream.append(eos_id)
+    else:
+        raise ValueError("[error] source must start with 'hf:' or 'txt:'")
+
+    if not token_stream:
+        raise ValueError("[error] No tokens extracted from the source. Check your data.")
+
+    ds = CausalChunked(token_stream, block_size)
+    if len(ds) == 0:
+        raise ValueError(
+            f"[error] Tokenized corpus ({len(token_stream)} tokens) is too small "
+            f"for block_size={block_size}. No complete blocks produced."
+        )
+
+    loader = DataLoader(
+        ds,
+        batch_size=batch_size,
+        shuffle=shuffle,
+        drop_last=True,
+        pin_memory=torch.cuda.is_available(),
+        num_workers=num_workers,
+    )
+
+    meta = {
+        "vocab_size": len(tokenizer),
+        "eos_id": eos_id,
+        "n_blocks": len(ds),
+        "n_tokens": len(token_stream),
+        "tokens_per_block": block_size,
+    }
+
+    print(f"[info] Dataset ready: {meta['n_blocks']} blocks, {meta['n_tokens']} tokens total")
+    return tokenizer, loader, meta
+
+
+# =========================================================
+# Trainer
+# =========================================================
+@dataclass
+class TrainConfig:
+    output_dir: str = "outputs/hrm_run"
+    num_epochs: int = 1
+    max_steps: Optional[int] = None                 # if set, overrides num_epochs
+    per_device_train_batch_size: int = 8
+    gradient_accumulation_steps: int = 1
+    learning_rate: float = 1e-4
+    betas: tuple = (0.9, 0.95)
+    eps: float = 1e-8
+    weight_decay: float = 0.01
+    warmup_ratio: float = 0.06
+    max_grad_norm: float = 0.5
+    log_every: int = 100
+    save_every: int = 2000
+    eval_every: int = 2000
+    save_total_limit: int = 3
+    fp16: bool = False
+    bf16: bool = True                               # prefer bf16 if supported
+    seed: int = 1337
+    resume_from: Optional[str] = None               # path to checkpoint dir
+    early_stopping_patience: Optional[int] = None   # steps without eval improvement
+    best_metric: str = "eval/loss"
+    greater_is_better: bool = False
+    torch_compile: bool = False
+
+    # Optional W&B
+    wandb_enable: bool = False
+    wandb_entity: Optional[str] = None
+    wandb_project: Optional[str] = None
+    wandb_run_name: Optional[str] = None
+
+
+def _out_get(out: Any, key: str, default=None):
+    if isinstance(out, dict):
+        return out.get(key, default)
+    return getattr(out, key, default)
+
+
+class MiniTRLTrainer:
+    """
+    TRL-like supervised trainer:
+
+    Model forward must accept (input_ids, labels) and return something with:
+      - loss (required)
+      - logits (optional but recommended; used for sanity checks)
+      - lm_loss (optional; logged if present)
+      - ponder_loss (optional; logged if present)
+
+    DataLoader must yield dicts with keys:
+      - "input_ids" and (optionally) "labels". If "labels" missing, labels=input_ids.
+      - If you pad to fixed length externally, also pass "attention_mask" so we can mask pad tokens.
+    """
+
+    def __init__(
+        self,
+        model: nn.Module,
+        train_loader: DataLoader,
+        tokenizer: Optional[AutoTokenizer] = None,
+        eval_loader: Optional[DataLoader] = None,
+        config: TrainConfig = TrainConfig(),
+        compute_metrics: Optional[Callable[[Dict[str, float]], Dict[str, float]]] = None,
+        custom_loss_fn: Optional[Callable[[Any], torch.Tensor]] = None,  # receives model outputs
+        device: Optional[torch.device] = None,
+    ):
+        self.model = model
+        self.train_loader = train_loader
+        self.eval_loader = eval_loader
+        self.tok = tokenizer
+        self.cfg = config
+        self.compute_metrics = compute_metrics
+        self.custom_loss_fn = custom_loss_fn
+        self.device = device or auto_device()
+        set_seed(self.cfg.seed)
+
+        self.model.to(self.device)
+        if self.cfg.torch_compile:
+            try:
+                self.model = torch.compile(self.model)
+            except Exception as e:
+                print("[warn] torch.compile failed:", e)
+
+        # AMP dtype
+        if self.device.type == "cuda":
+            self.amp_dtype = torch.bfloat16 if (self.cfg.bf16 and torch.cuda.is_bf16_supported()) else (torch.float16 if self.cfg.fp16 else None)
+        else:
+            self.amp_dtype = None
+
+        # Param groups with/without weight decay
+        decay, no_decay = [], []
+        for n, p in self.model.named_parameters():
+            if not p.requires_grad: 
+                continue
+            nl = n.lower()
+            if p.ndim == 1 or "norm" in nl or "bias" in nl or ("tok_emb.weight" in n):
+                no_decay.append(p)
+            else:
+                decay.append(p)
+
+        self.optimizer = torch.optim.AdamW(
+            [{"params": decay, "weight_decay": self.cfg.weight_decay},
+             {"params": no_decay, "weight_decay": 0.0}],
+            lr=self.cfg.learning_rate, betas=self.cfg.betas, eps=self.cfg.eps
+        )
+
+        # Scheduler
+        steps_per_epoch = math.ceil(len(self.train_loader) / max(1, self.cfg.gradient_accumulation_steps))
+        total_updates = self.cfg.max_steps if self.cfg.max_steps is not None else self.cfg.num_epochs * max(1, steps_per_epoch)
+        total_updates = max(1, total_updates)  # guard
+        warmup_steps = int(self.cfg.warmup_ratio * total_updates)
+        self.scheduler = get_linear_schedule_with_warmup(self.optimizer, warmup_steps, total_updates)
+
+        # GradScaler only for fp16
+        self.scaler = torch.cuda.amp.GradScaler(enabled=(self.amp_dtype == torch.float16 and self.device.type == "cuda"))
+
+        # State
+        self.global_step = 0
+        self.best_metric_val = float("-inf") if self.cfg.greater_is_better else float("inf")
+        self.no_improve_steps = 0
+
+        os.makedirs(self.cfg.output_dir, exist_ok=True)
+        self._maybe_resume()
+
+        # W&B
+        self._wandb_run = None
+        if self.cfg.wandb_enable:
+            if wandb is None:
+                print("[warn] wandb_enable=True but wandb is not installed; proceeding without W&B.")
+            else:
+                self._wandb_run = wandb.init(
+                    entity=self.cfg.wandb_entity,
+                    project=self.cfg.wandb_project or "hrm",
+                    name=self.cfg.wandb_run_name,
+                    config=asdict(self.cfg),
+                )
+
+    # -------------------------- public API --------------------------
+    def train(self):
+        self.model.train()
+        log_acc_loss = 0.0
+        log_acc_tokens = 0
+        t0 = time.time()
+
+        max_updates = self.cfg.max_steps
+        if max_updates is None:
+            steps_per_epoch = math.ceil(len(self.train_loader) / max(1, self.cfg.gradient_accumulation_steps))
+            max_updates = self.cfg.num_epochs * max(1, steps_per_epoch)
+
+        pbar = tqdm(total=max_updates, initial=self.global_step, desc="Training", dynamic_ncols=True)
+
+        while self.global_step < max_updates:
+            for batch in self.train_loader:
+                if self.global_step >= max_updates:
+                    break
+
+                input_ids = batch["input_ids"].to(self.device)
+                labels = batch.get("labels", input_ids).to(self.device)
+
+                # Mask pads only if attention_mask/pad present
+                pad_id = getattr(self.tok, "pad_token_id", None) if self.tok is not None else (
+                    getattr(getattr(self.model, "config", None), "pad_token_id", None)
+                )
+                attn = batch.get("attention_mask", None)
+                attn = attn.to(self.device) if attn is not None else None
+                labels = mask_pad_labels(input_ids, labels, pad_id=pad_id, attention_mask=attn)
+
+                ctx = (torch.autocast(device_type=self.device.type, dtype=self.amp_dtype)
+                       if (self.amp_dtype is not None and self.device.type in ("cuda", "mps"))
+                       else nullcontext())
+
+                with ctx:
+                    out = self.model(input_ids=input_ids, labels=labels)
+                    loss = _out_get(out, "loss")
+                    if self.custom_loss_fn is not None:
+                        loss = self.custom_loss_fn(out)
+                    loss = loss / max(1, self.cfg.gradient_accumulation_steps)
+
+                logits = _out_get(out, "logits", None)
+                if logits is not None:
+                    if not torch.isfinite(logits).all():
+                        mx = logits.detach().float().abs().max().item()
+                        raise FloatingPointError(f"logits non-finite (max|logit|={mx})")
+                if not torch.isfinite(loss):
+                    lmax = (logits.detach().float().abs().max().item() if logits is not None else float("nan"))
+                    print(f"[dbg] non-finite loss; max|logit|={lmax}, lm={_out_get(out,'lm_loss')}, ponder={_out_get(out,'ponder_loss')}")
+                    raise FloatingPointError("Loss became non-finite.")
+
+                if self.scaler.is_enabled():
+                    self.scaler.scale(loss).backward()
+                else:
+                    loss.backward()
+
+                do_step = ((self.global_step + 1) % self.cfg.gradient_accumulation_steps == 0)
+                if do_step:
+                    if self.scaler.is_enabled():
+                        self.scaler.unscale_(self.optimizer)
+                    torch.nn.utils.clip_grad_norm_(self.model.parameters(), self.cfg.max_grad_norm)
+
+                    if self.scaler.is_enabled():
+                        prev_scale = self.scaler.get_scale()
+                        self.scaler.step(self.optimizer)
+                        self.scaler.update()
+                        if self.scaler.get_scale() >= prev_scale:
+                            self.scheduler.step()
+                    else:
+                        self.optimizer.step()
+                        self.scheduler.step()
+
+                    self.optimizer.zero_grad(set_to_none=True)
+                    self.global_step += 1
+                    pbar.update(1)
+
+                # Logging accumulators (token-weighted). Count only non-pad tokens.
+                tokens = int((labels != -100).sum().item())
+                lm_for_log = _out_get(out, "lm_loss", loss.detach())
+                log_acc_loss += float(lm_for_log) * max(1, tokens)
+                log_acc_tokens += max(1, tokens)
+
+                if self.global_step % max(1, self.cfg.log_every) == 0:
+                    avg_loss = log_acc_loss / max(1, log_acc_tokens)
+                    msg = {
+                        "step": self.global_step,
+                        "lr": self.scheduler.get_last_lr()[0],
+                        "avg_lm_loss": avg_loss,
+                        "ppl~": math.exp(min(20.0, avg_loss)),
+                        "ponder": (_out_get(out, "ponder_loss", None)),
+                        "elapsed_s": int(time.time() - t0),
+                    }
+                    tqdm.write("[log] " + ", ".join(f"{k}={format_num(v)}" for k, v in msg.items() if v is not None))
+                    if self._wandb_run is not None:
+                        self._wandb_run.log({k: v for k, v in msg.items() if isinstance(v, (int, float))})
+                    log_acc_loss = 0.0
+                    log_acc_tokens = 0
+
+                # Eval / early stop
+                if self.eval_loader and self.global_step % max(1, self.cfg.eval_every) == 0:
+                    metrics = self.evaluate()
+                    improved = self._check_improve(metrics[self.cfg.best_metric])
+                    if self._wandb_run is not None:
+                        self._wandb_run.log(metrics)
+                    if self.cfg.early_stopping_patience is not None:
+                        if improved:
+                            self.no_improve_steps = 0
+                        else:
+                            self.no_improve_steps += self.cfg.eval_every
+                            if self.no_improve_steps >= self.cfg.early_stopping_patience:
+                                tqdm.write("[early-stop] patience exhausted.")
+                                self._save_checkpoint(tag="final")
+                                pbar.close()
+                                return
+
+                if self.global_step % max(1, self.cfg.save_every) == 0:
+                    self._save_checkpoint()
+
+        pbar.close()
+        self._save_checkpoint(tag="final")
+
+    @torch.no_grad()
+    def evaluate(self) -> Dict[str, float]:
+        self.model.eval()
+        total_loss = 0.0
+        total_tokens = 0
+        total_ponder = 0.0
+        n_batches = 0
+
+        for batch in tqdm(self.eval_loader, desc="Eval", leave=False):
+            input_ids = batch["input_ids"].to(self.device)
+            labels = batch.get("labels", input_ids).to(self.device)
+
+            pad_id = getattr(self.tok, "pad_token_id", None) if self.tok is not None else (
+                getattr(getattr(self.model, "config", None), "pad_token_id", None)
+            )
+            attn = batch.get("attention_mask", None)
+            attn = attn.to(self.device) if attn is not None else None
+            labels = mask_pad_labels(input_ids, labels, pad_id=pad_id, attention_mask=attn)
+
+            out = self.model(input_ids=input_ids, labels=labels)
+            lm = float(_out_get(out, "lm_loss", _out_get(out, "loss")))
+            tokens = int((labels != -100).sum().item())
+
+            total_loss += lm * max(1, tokens)
+            total_tokens += max(1, tokens)
+            pl = _out_get(out, "ponder_loss", None)
+            if pl is not None:
+                total_ponder += float(pl)
+            n_batches += 1
+
+        avg_loss = total_loss / max(1, total_tokens)
+        ppl = math.exp(min(20.0, avg_loss))
+        avg_ponder = (total_ponder / max(1, n_batches)) if n_batches > 0 else float("nan")
+        metrics = {"eval/loss": avg_loss, "eval/ppl": ppl, "eval/ponder": avg_ponder, "step": self.global_step}
+        tqdm.write("[eval] " + ", ".join(f"{k}={format_num(v)}" for k, v in metrics.items()))
+        self.model.train()
+        return metrics
+
+    # -------------------------- checkpoints --------------------------
+    def _save_checkpoint(self, tag: Optional[str] = None):
+        tag = tag or f"step{self.global_step}"
+        ckpt_dir = os.path.join(self.cfg.output_dir, f"ckpt-{tag}")
+        os.makedirs(ckpt_dir, exist_ok=True)
+
+        # trainer state (resumable)
+        torch.save({
+            "model": self.model.state_dict(),
+            "opt": self.optimizer.state_dict(),
+            "sched": self.scheduler.state_dict(),
+            "scaler": (self.scaler.state_dict() if self.scaler.is_enabled() else None),
+            "global_step": self.global_step,
+            "config": asdict(self.cfg),
+        }, os.path.join(ckpt_dir, "trainer_state.pt"))
+
+        # weights-only safetensors + minimal config
+        save_safetensors_safe(self.model, os.path.join(ckpt_dir, "model.safetensors"),
+                              metadata={"note": "MiniTRLTrainer save", "global_step": str(self.global_step)})
+        with open(os.path.join(ckpt_dir, "config.json"), "w") as f:
+            json.dump({"global_step": self.global_step, **asdict(self.cfg)}, f, indent=2)
+
+        self._prune_checkpoints()
+
+    def _prune_checkpoints(self):
+        if self.cfg.save_total_limit is None: 
+            return
+        subs = [d for d in os.listdir(self.cfg.output_dir) if d.startswith("ckpt-")]
+        if len(subs) <= self.cfg.save_total_limit:
+            return
+        subs = sorted(subs, key=lambda s: os.path.getmtime(os.path.join(self.cfg.output_dir, s)))
+        for d in subs[:-self.cfg.save_total_limit]:
+            shutil.rmtree(os.path.join(self.cfg.output_dir, d), ignore_errors=True)
+
+    def _maybe_resume(self):
+        if not self.cfg.resume_from:
+            return
+        state_path = os.path.join(self.cfg.resume_from, "trainer_state.pt")
+        if not os.path.exists(state_path):
+            print(f"[resume] not found: {state_path}")
+            return
+        ckpt = torch.load(state_path, map_location="cpu")
+        self.model.load_state_dict(ckpt["model"], strict=False)
+        self.optimizer.load_state_dict(ckpt["opt"])
+        self.scheduler.load_state_dict(ckpt["sched"])
+        if ckpt.get("scaler") and self.scaler.is_enabled():
+            self.scaler.load_state_dict(ckpt["scaler"])
+        self.global_step = int(ckpt.get("global_step", 0))
+        print(f"[resume] loaded from {self.cfg.resume_from} @ step {self.global_step}")
+
+    def _check_improve(self, val: float) -> bool:
+        improved = (val > self.best_metric_val) if self.cfg.greater_is_better else (val < self.best_metric_val)
+        if improved:
+            self.best_metric_val = val
+        return improved
+
+
+# =========================================================
+# Checkpoint helpers (complete save)
+# =========================================================
+def _state_dict_for_safetensors(model):
+    """
+    Build a CPU state_dict suitable for safetensors.
+    If lm_head.weight is tied to tok_emb.weight, omit lm_head.weight to avoid duplicate storage.
+    """
+    tied = hasattr(model, "lm_head") and hasattr(model, "tok_emb") and (
+        getattr(model.lm_head, "weight", None) is getattr(model.tok_emb, "weight", None)
+    )
+    sd_cpu = {k: v.detach().cpu() for k, v in model.state_dict().items()}
+    if tied and "lm_head.weight" in sd_cpu:
+        sd_cpu.pop("lm_head.weight")
+    return sd_cpu, tied
+
+
+def retie_output_embedding(model):
+    """
+    Re-tie output and input embeddings after loading weights, if model provides get_*_embeddings().
+    """
+    if hasattr(model, "get_input_embeddings") and hasattr(model, "get_output_embeddings"):
+        inp = model.get_input_embeddings()
+        out = model.get_output_embeddings()
+        if inp is not None and out is not None and out.weight.data_ptr() != inp.weight.data_ptr():
+            out.weight = inp.weight
+
+
+def _chain_get(obj, attrs, default=None):
+    """
+    Safe chained getattr: _chain_get(model, ["L_mod", "attn", "num_heads"], default=None)
+    """
+    cur = obj
+    for a in attrs:
+        if not hasattr(cur, a):
+            return default
+        cur = getattr(cur, a)
+    return cur
+
+
+def save_model_complete(model, save_dir, tokenizer=None, training_args=None, metadata=None):
+    """
+    Save model with all details: weights (.pt + .safetensors), config, architecture,
+    parameter summaries, tokenizer (optional), and a README.
+
+    Returns: save_dir
+    """
+    os.makedirs(save_dir, exist_ok=True)
+    from datetime import datetime
+    from collections import OrderedDict
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    print(f"Saving model to: {save_dir}")
+
+    # 1) Weights (.pt)
+    print("1. Saving model weights (.pt)...")
+    checkpoint = {
+        "model_state_dict": model.state_dict(),
+        "timestamp": timestamp,
+    }
+    if training_args and "optimizer_state" in training_args:
+        checkpoint["optimizer_state_dict"] = training_args["optimizer_state"]
+    if training_args and "scheduler_state" in training_args:
+        checkpoint["scheduler_state_dict"] = training_args["scheduler_state"]
+    if training_args and "epoch" in training_args:
+        checkpoint["epoch"] = training_args["epoch"]
+    if training_args and "global_step" in training_args:
+        checkpoint["global_step"] = training_args["global_step"]
+    torch.save(checkpoint, os.path.join(save_dir, "model.pt"))
+    print("   ✓ Saved: model.pt")
+
+    # 1b) Weights (.safetensors)
+    print("1b. Saving model weights (.safetensors)...")
+    try:
+        from safetensors.torch import save_file
+        sd_cpu, tied = _state_dict_for_safetensors(model)
+        save_file(sd_cpu, os.path.join(save_dir, "model.safetensors"))
+        if tied:
+            print("   ℹ Weight tying detected: excluded lm_head.weight (re-tie on load).")
+        print("   ✓ Saved: model.safetensors")
+    except ImportError:
+        print("   ⚠ safetensors not installed, skipping .safetensors format")
+    except Exception as e:
+        print(f"   ⚠ Could not save safetensors: {e}")
+
+    # 2) Save a minimal config (best-effort introspection)
+    print("2. Saving model config...")
+    vocab_size = getattr(model, "vocab_size", None)
+    d_model    = getattr(model, "d_model", None)
+    n_heads    = _chain_get(model, ["L_mod", "attn", "num_heads"], default=None)
+    d_ff       = _chain_get(model, ["L_mod", "mlp", "w1", "out_features"], default=None)
+    dropout    = _chain_get(model, ["L_mod", "drop", "p"], default=None)
+    k_l_steps  = getattr(model, "k_l_steps", None)
+    max_cycles = getattr(model, "max_cycles", None)
+    ponder_w   = getattr(model, "ponder_w", None)
+    has_out_norm = hasattr(model, "out_norm")
+    tied_flag = hasattr(model, "lm_head") and hasattr(model, "tok_emb") and (
+        getattr(model.lm_head, "weight", None) is getattr(model.tok_emb, "weight", None)
+    )
+    config = {
+        "model_type": type(model).__name__,
+        "vocab_size": vocab_size,
+        "d_model": d_model,
+        "n_heads": n_heads,
+        "d_ff": d_ff,
+        "dropout": dropout,
+        "k_l_steps": k_l_steps,
+        "max_cycles": max_cycles,
+        "ponder_loss_weight": ponder_w,
+        "has_out_norm": has_out_norm,
+        "weight_tying": tied_flag,
+        "tie_word_embeddings": tied_flag,
+    }
+    with open(os.path.join(save_dir, "config.json"), "w") as f:
+        json.dump(config, f, indent=2)
+    print("   ✓ Saved: config.json")
+
+    # 3) Architecture string
+    print("3. Saving model architecture...")
+    with open(os.path.join(save_dir, "architecture.txt"), "w") as f:
+        f.write(str(model))
+    print("   ✓ Saved: architecture.txt")
+
+    # 4) Parameter details
+    print("4. Saving parameter details...")
+    param_info = []
+    total_params = 0
+    trainable_params = 0
+    for name, p in model.named_parameters():
+        n = p.numel()
+        total_params += n
+        if p.requires_grad:
+            trainable_params += n
+        param_info.append({
+            "name": name,
+            "shape": list(p.shape),
+            "dtype": str(p.dtype),
+            "requires_grad": p.requires_grad,
+            "num_params": n,
+            "device": str(p.device),
+        })
+    param_summary = {
+        "total_parameters": total_params,
+        "trainable_parameters": trainable_params,
+        "non_trainable_parameters": total_params - trainable_params,
+        "size_mb": total_params * 4 / (1024 ** 2),  # float32 estimate
+        "parameters": param_info,
+    }
+    with open(os.path.join(save_dir, "parameters.json"), "w") as f:
+        json.dump(param_summary, f, indent=2)
+    print("   ✓ Saved: parameters.json")
+    print(f"   Total parameters: {total_params:,}")
+    print(f"   Trainable: {trainable_params:,}")
+    print(f"   Model size: {total_params * 4 / (1024**2):.2f} MB")
+
+    # 5) Layer-wise breakdown (top-level children)
+    print("5. Saving layer-wise breakdown...")
+    from collections import OrderedDict
+    layer_params = OrderedDict()
+    for name, module in model.named_children():
+        num_params = sum(p.numel() for p in module.parameters())
+        layer_params[name] = {
+            "num_params": num_params,
+            "percentage": 100 * num_params / total_params if total_params > 0 else 0,
+        }
+    with open(os.path.join(save_dir, "layer_params.json"), "w") as f:
+        json.dump(layer_params, f, indent=2)
+    print("   ✓ Saved: layer_params.json")
+
+    # 6) Training args (if provided)
+    if training_args:
+        print("6. Saving training arguments...")
+        serializable_args = {}
+        for k, v in training_args.items():
+            if isinstance(v, (int, float, str, bool, list, dict, type(None))):
+                serializable_args[k] = v
+            else:
+                serializable_args[k] = str(v)
+        with open(os.path.join(save_dir, "training_args.json"), "w") as f:
+            json.dump(serializable_args, f, indent=2)
+        print("   ✓ Saved: training_args.json")
+
+    # 7) Metadata
+    print("7. Saving metadata...")
+    metadata_full = {
+        "timestamp": timestamp,
+        "pytorch_version": torch.__version__,
+        "cuda_available": torch.cuda.is_available(),
+        "cuda_version": torch.version.cuda if torch.cuda.is_available() else None,
+        "device": str(next(model.parameters()).device),
+        "dtype": str(next(model.parameters()).dtype),
+    }
+    if metadata:
+        metadata_full.update(metadata)
+    with open(os.path.join(save_dir, "metadata.json"), "w") as f:
+        json.dump(metadata_full, f, indent=2)
+    print("   ✓ Saved: metadata.json")
+
+    # 8) Tokenizer (optional)
+    if tokenizer is not None:
+        print("8. Saving tokenizer...")
+        try:
+            tokenizer.save_pretrained(save_dir)
+            print("   ✓ Saved tokenizer files")
+        except Exception as e:
+            print(f"   ⚠ Could not save tokenizer: {e}")
+
+    # 9) README
+    print("9. Creating README...")
+    readme_content = f"""# HRM/LM Model Checkpoint
+
+## Model Information
+- **Model Type**: {config['model_type']}
+- **Timestamp**: {timestamp}
+- **Total Parameters**: {total_params:,}
+- **Trainable Parameters**: {trainable_params:,}
+- **Model Size**: {total_params * 4 / (1024**2):.2f} MB
+
+## Architecture (best-effort introspection)
+- **Vocabulary Size**: {config['vocab_size']}
+- **Hidden Dimension**: {config['d_model']}
+- **Attention Heads**: {config['n_heads']}
+- **FFN Dimension**: {config['d_ff']}
+- **Dropout**: {config['dropout']}
+- **L-mod Steps**: {config['k_l_steps']}
+- **Max Cycles**: {config['max_cycles']}
+- **Has Output Norm**: {config['has_out_norm']}
+- **Weight Tying**: {config['weight_tying']} (tok_emb ↔ lm_head)
+
+## Files
+- `model.pt` — Full checkpoint (PyTorch)
+- `model.safetensors` — Safetensors (excludes lm_head if tied)
+- `config.json` — Model configuration summary
+- `architecture.txt` — Stringified architecture
+- `parameters.json` — Parameter metadata
+- `layer_params.json` — Layer-wise parameter counts
+- `training_args.json` — Training hyperparameters (if provided)
+- `metadata.json` — Environment/device metadata
+- Tokenizer files (if provided)
+"""
+    with open(os.path.join(save_dir, 'README.md'), 'w') as f:
+        f.write(readme_content)
+        print(f"   ✓ Saved: README.md")
+
+    print("\n" + "="*60)
+    print("SAVE COMPLETE!")
+    print("="*60)
+    print(f"Location: {save_dir}")
+    print(f"Files saved: {len(os.listdir(save_dir))}")
+    print("\nSummary:")
+    print(f"  Total parameters: {total_params:,}")
+    print(f"  Model size: {total_params * 4 / (1024**2):.2f} MB")
+    print(f"  Config saved: ✓")
+    print(f"  Weights saved: ✓")
+    print(f"  Tokenizer saved: {'✓' if tokenizer else '✗'}")
+    print("="*60)
+    return save_dir
+
+
+# =========================================================
+# Minimal CLI (dynamic model loading via --load-fn module:function)
+# =========================================================
+def _load_via_callable(load_fn: str, **kwargs):
+    """
+    load_fn: 'module.submodule:function_name' (e.g., 'hrm_utils:load_hrm')
+    kwargs: forwarded to the function
+    """
+    if ":" not in load_fn:
+        raise ValueError("load_fn must look like 'module.submodule:function_name'")
+    mod_name, fn_name = load_fn.split(":", 1)
+    import importlib
+    mod = importlib.import_module(mod_name)
+    fn = getattr(mod, fn_name)
+    return fn(**kwargs)
+
+
+def main():
+    import argparse
+    p = argparse.ArgumentParser(description="All-in-one HRM/LM data + trainer + checkpointing")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # prepare data
+    sp = sub.add_parser("prepare", help="Tokenize and build a quick dataloader")
+    sp.add_argument("--source", default="hf:lemonilia/wikified_english_dictionary")
+    sp.add_argument("--split", default="train")
+    sp.add_argument("--text-field", default="text")
+    sp.add_argument("--block-size", type=int, default=128)
+    sp.add_argument("--batch-size", type=int, default=8)
+    sp.add_argument("--tokenizer-dir", default=None)
+
+    # train
+    st = sub.add_parser("train", help="Train a model via dynamic loader")
+    st.add_argument("--load-fn", required=True, help="module:function (e.g. hrm_utils:load_hrm)")
+    st.add_argument("--load-args", default="{}", help="JSON dict of kwargs to pass to load-fn (e.g. '{\"name\":\"hrm_v0.04\",\"device\":\"cuda\",\"with_tokenizer\":true}')")
+    st.add_argument("--source", default="hf:lemonilia/wikified_english_dictionary")
+    st.add_argument("--split", default="train")
+    st.add_argument("--text-field", default="text")
+    st.add_argument("--block-size", type=int, default=128)
+    st.add_argument("--batch-size", type=int, default=8)
+    st.add_argument("--epochs", type=int, default=1)
+    st.add_argument("--lr", type=float, default=1e-4)
+    st.add_argument("--output-dir", default="outputs/hrm_run")
+    st.add_argument("--wandb", action="store_true")
+    st.add_argument("--wandb-entity", default=None)
+    st.add_argument("--wandb-project", default=None)
+    st.add_argument("--wandb-run-name", default=None)
+
+    # save checkpoint (complete)
+    ss = sub.add_parser("save", help="Save a fully-documented checkpoint for an already-loaded model")
+    ss.add_argument("--load-fn", required=True)
+    ss.add_argument("--load-args", default="{}")
+    ss.add_argument("--save-dir", default="saved_models/hrm_export")
+    ss.add_argument("--with-tokenizer", action="store_true")
+
+    args = p.parse_args()
+
+    if args.cmd == "prepare":
+        tok, loader, meta = load_dataset_fn(
+            source=args.source,
+            split=args.split,
+            text_field=args.text_field,
+            block_size=args.block_size,
+            batch_size=args.batch_size,
+            checkpoint_or_dir=args.tokenizer_dir,
+        )
+        print("[ok] Prepared one pass through dataloader:")
+        for i, b in enumerate(loader):
+            print(" batch", i, {k: v.shape for k, v in b.items()})
+            if i > 2: break
+
+    elif args.cmd == "train":
+        load_kwargs = json.loads(args.load_args or "{}")
+        obj = _load_via_callable(args.load_fn, **load_kwargs)
+        if isinstance(obj, tuple) and len(obj) >= 2:
+            model, tokenizer = obj[0], obj[1]
+        else:
+            # assume loader returns just model; tokenizer is optional/None
+            model, tokenizer = obj, None
+
+        tok, train_loader, _ = load_dataset_fn(
+            source=args.source,
+            split=args.split,
+            text_field=args.text_field,
+            block_size=args.block_size,
+            batch_size=args.batch_size,
+            checkpoint_or_dir=(tokenizer.name_or_path if tokenizer is not None else None),
+        )
+        tokenizer = tokenizer or tok
+
+        cfg = TrainConfig(
+            output_dir=args.output_dir,
+            num_epochs=args.epochs,
+            learning_rate=args.lr,
+            wandb_enable=bool(args.wandb),
+            wandb_entity=args.wandb_entity,
+            wandb_project=args.wandb_project,
+            wandb_run_name=args.wandb_run_name,
+        )
+        trainer = MiniTRLTrainer(
+            model=model,
+            train_loader=train_loader,
+            tokenizer=tokenizer,
+            eval_loader=None,  # plug one in if you want
+            config=cfg,
+        )
+        trainer.train()
+
+    elif args.cmd == "save":
+        load_kwargs = json.loads(args.load_args or "{}")
+        obj = _load_via_callable(args.load_fn, **load_kwargs)
+        if isinstance(obj, tuple) and len(obj) >= 2:
+            model, tokenizer = obj[0], obj[1]
+        else:
+            model, tokenizer = obj, None
+        save_model_complete(model, args.save_dir, tokenizer=(tokenizer if args.with_tokenizer else None))
+
+
+if __name__ == "__main__":
+    main()

hrm_utils.py

@@ -0,0 +1,498 @@
+# hrm_utils.py — Minimal, robust HRM loader + tokenizer support
+# --------------------------------------------------------------
+# - Handles .pt/.bin/.safetensors (single file or HF sharded index)
+# - Adapts q/k/v names to torch.nn.MultiheadAttention format
+# - Infers config if config.json is missing
+# - Prefers checkpoint vocab_size over config to avoid shape mismatches
+# - Optional tokenizer load (local files) + embedding resize + weight tying
+# - Returns (model, tokenizer) when with_tokenizer=True (else just model)
+
+import os, json, glob, math, inspect
+from typing import Optional, Dict, Any
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+# ---------------- Blocks ----------------
+class RMSNorm(nn.Module):
+    def __init__(self, d, eps=1e-6):
+        super().__init__()
+        self.eps = eps
+        self.weight = nn.Parameter(torch.ones(d))
+    def forward(self, x):
+        return self.weight * (x * torch.rsqrt(x.pow(2).mean(dim=-1, keepdim=True) + self.eps))
+
+class SinusoidalPositionalEmbedding(nn.Module):
+    def __init__(self, d_model, max_len=8192):
+        super().__init__()
+        pe = torch.zeros(max_len, d_model)
+        pos = torch.arange(0, max_len).unsqueeze(1)
+        div = torch.exp(torch.arange(0, d_model, 2) * (-math.log(10000.0) / d_model))
+        pe[:, 0::2] = torch.sin(pos * div)
+        pe[:, 1::2] = torch.cos(pos * div)
+        self.register_buffer("pe", pe, persistent=False)
+    def forward(self, L: int):
+        return self.pe[:L].unsqueeze(0)
+
+class SwiGLU(nn.Module):
+    def __init__(self, d_model, d_ff, pdrop=0.1):
+        super().__init__()
+        self.w1 = nn.Linear(d_model, d_ff, bias=False)
+        self.w2 = nn.Linear(d_model, d_ff, bias=False)
+        self.w3 = nn.Linear(d_ff, d_model, bias=False)
+        self.drop = nn.Dropout(pdrop)
+    def forward(self, x):
+        return self.drop(self.w3(F.silu(self.w1(x)) * self.w2(x)))
+
+class AttnBlock(nn.Module):
+    def __init__(self, d_model, n_heads, d_ff, pdrop=0.1):
+        super().__init__()
+        self.norm1 = RMSNorm(d_model)
+        self.attn  = nn.MultiheadAttention(d_model, n_heads, dropout=pdrop, batch_first=True)
+        self.drop  = nn.Dropout(pdrop)
+        self.norm2 = RMSNorm(d_model)
+        self.mlp   = SwiGLU(d_model, d_ff, pdrop)
+    def forward(self, x, attn_mask=None, key_padding_mask=None):
+        if attn_mask is not None:
+            assert attn_mask.dtype == torch.bool and attn_mask.dim() == 2
+        if key_padding_mask is not None:
+            assert key_padding_mask.dtype == torch.bool and key_padding_mask.dim() == 2
+        h = self.norm1(x)
+        a, _ = self.attn(h, h, h, attn_mask=attn_mask, key_padding_mask=key_padding_mask, need_weights=False)
+        x = x + self.drop(a)
+        x = x + self.drop(self.mlp(self.norm2(x)))
+        return x
+
+# ---------------- Model ----------------
+class HRMForCausalLM(nn.Module):
+    def __init__(self, vocab_size: int, d_model=512, n_heads=8, d_ff=2048, dropout=0.1,
+                 k_l_steps=4, max_cycles=8, ponder_loss_weight=1e-2):
+        super().__init__()
+        assert d_model % n_heads == 0, "d_model must be divisible by n_heads"
+        self.vocab_size = vocab_size
+        self.d_model    = d_model
+        self.k_l_steps  = k_l_steps
+        self.max_cycles = max_cycles
+        self.ponder_w   = ponder_loss_weight
+
+        self.tok_emb = nn.Embedding(vocab_size, d_model)
+        self.pos_emb = SinusoidalPositionalEmbedding(d_model, max_len=8192)
+        self.in_net  = nn.Sequential(nn.Linear(d_model, d_model), nn.GELU(), RMSNorm(d_model))
+
+        self.L_mod = AttnBlock(d_model, n_heads, d_ff, dropout)
+        self.H_mod = AttnBlock(d_model, n_heads, d_ff, dropout)
+
+        self.halt_head = nn.Linear(d_model, 1)
+        nn.init.constant_(self.halt_head.bias, -1.5)
+
+        self.out_norm = RMSNorm(d_model)
+
+        self.lm_head   = nn.Linear(d_model, vocab_size, bias=False)
+        self.lm_head.weight = self.tok_emb.weight  # tie
+
+        self._cached_causal_bool = {}
+        self.apply(self._init_weights)
+
+    def _init_weights(self, m):
+        if isinstance(m, (nn.Linear, nn.Embedding)):
+            nn.init.normal_(m.weight, mean=0.0, std=0.02)
+        if isinstance(m, nn.Linear) and m.bias is not None:
+            nn.init.zeros_(m.bias)
+
+    def _causal_bool_mask(self, L: int, device):
+        k = (L, device)
+        if k not in self._cached_causal_bool:
+            self._cached_causal_bool[k] = torch.triu(torch.ones(L, L, dtype=torch.bool, device=device), 1)
+        return self._cached_causal_bool[k]
+
+    def forward(self, input_ids, attention_mask=None, labels=None):
+        B, L = input_ids.shape
+        device = input_ids.device
+        x_tok = self.tok_emb(input_ids)
+        pos   = self.pos_emb(L).to(device=device, dtype=x_tok.dtype)  # keep dtype aligned
+        x     = self.in_net(x_tok + pos)
+
+        causal_bool = self._causal_bool_mask(L, device)
+        key_padding_mask = (attention_mask == 0) if attention_mask is not None else None
+
+        z_L = x.clone()
+        z_H = torch.zeros_like(x)
+
+        eps = 1e-6
+        rema = torch.ones((B, L), device=device, dtype=x_tok.dtype)
+        collected_H = torch.zeros_like(z_H)
+        ponder_terms = []
+
+        for c in range(self.max_cycles):
+            for _ in range(self.k_l_steps):
+                z_L = self.L_mod(z_L + z_H + x, attn_mask=causal_bool, key_padding_mask=key_padding_mask)
+            z_H = self.H_mod(z_H + z_L, attn_mask=causal_bool, key_padding_mask=key_padding_mask)
+
+            p_halt = torch.sigmoid(self.halt_head(z_H)).squeeze(-1).clamp(eps, 1 - eps)
+            last = torch.full_like(p_halt, fill_value=(c == self.max_cycles - 1), dtype=torch.bool)
+            halt_p = torch.where(last, torch.ones_like(p_halt), p_halt)
+
+            contrib = (rema * halt_p).unsqueeze(-1)
+            collected_H = collected_H + contrib * z_H
+
+            ponder_terms.append(rema * halt_p)
+            rema = rema * (1.0 - halt_p)
+            if torch.all(rema < 1e-4):
+                break
+
+        collected_H = self.out_norm(collected_H)
+        logits = self.lm_head(collected_H)
+
+        loss = lm_loss = ponder = None
+        if labels is not None:
+            sl = logits[:, :-1, :].contiguous()
+            y  = labels[:, 1:].contiguous()
+            B_, Lm1, V = sl.shape
+            lm_loss = F.cross_entropy(sl.float().view(B_ * Lm1, V), y.view(B_ * Lm1))
+            ponder  = torch.stack(ponder_terms, dim=-1).sum(dim=-1).mean()
+            loss    = lm_loss + self.ponder_w * ponder
+
+        return {"loss": loss, "logits": logits, "lm_loss": lm_loss, "ponder_loss": ponder}
+
+    # ---- HF-style hooks ----
+    def get_input_embeddings(self):
+        return self.tok_emb
+    def set_input_embeddings(self, new_emb):
+        self.tok_emb = new_emb
+        if hasattr(self, "lm_head"):
+            self.lm_head.weight = self.tok_emb.weight
+    def tie_weights(self):
+        if hasattr(self, "lm_head") and hasattr(self, "tok_emb"):
+            self.lm_head.weight = self.tok_emb.weight
+
+# -------------- Loader helpers --------------
+def _resolve_device(device: Optional[str]) -> torch.device:
+    if device is None or device == "auto":
+        if torch.cuda.is_available(): return torch.device("cuda")
+        if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available(): return torch.device("mps")
+        return torch.device("cpu")
+    return torch.device(device)
+
+def _resolve_dtype(dtype: str) -> torch.dtype:
+    d = str(dtype).lower()
+    if d in ("fp32","float32","f32"): return torch.float32
+    if d in ("bf16","bfloat16"):      return torch.bfloat16
+    if d in ("fp16","float16","half"):return torch.float16
+    if d == "auto":
+        if torch.cuda.is_available() and getattr(torch.cuda, "is_bf16_supported", lambda: False)(): return torch.bfloat16
+        return torch.float32
+    raise ValueError(f"Unknown dtype {dtype}")
+
+def _find_checkpoint(path_or_dir: str) -> str:
+    if os.path.isfile(path_or_dir): return path_or_dir
+    if not os.path.isdir(path_or_dir): raise FileNotFoundError(f"Not a file or directory: {path_or_dir}")
+    st = glob.glob(os.path.join(path_or_dir, "*.safetensors"))
+    if len(st) == 1: return st[0]
+    if len(st) > 1:
+        for cand in ("model.safetensors","pytorch_model.safetensors"):
+            p = os.path.join(path_or_dir, cand)
+            if os.path.exists(p): return p
+        return sorted(st)[0]
+    for idx in ("model.safetensors.index.json","pytorch_model.bin.index.json"):
+        p = os.path.join(path_or_dir, idx)
+        if os.path.exists(p): return p
+    for cand in ("pytorch_model.bin","model.bin","model.pt"):
+        p = os.path.join(path_or_dir, cand)
+        if os.path.exists(p): return p
+    pt = glob.glob(os.path.join(path_or_dir, "*.pt")) + glob.glob(os.path.join(path_or_dir, "*.bin"))
+    if pt: return sorted(pt)[0]
+    raise FileNotFoundError(f"No checkpoint found in {path_or_dir}")
+
+def _torch_load(path: str):
+    try:
+        return torch.load(path, map_location="cpu", weights_only=True)
+    except TypeError:
+        return torch.load(path, map_location="cpu")
+
+def _normalize_keys(sd: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
+    def strip(k: str) -> str:
+        for pref in ("module.","model.","transformer."):
+            if k.startswith(pref): return k[len(pref):]
+        return k
+    return {strip(k): v for k, v in sd.items()}
+
+def _adapt_attention_keys(sd: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
+    sd = dict(sd)
+    def handle(prefix: str):
+        qkv_w = sd.pop(f"{prefix}.qkv.weight", None)
+        if qkv_w is not None:
+            sd[f"{prefix}.in_proj_weight"] = qkv_w
+        qkv_b = sd.pop(f"{prefix}.qkv.bias", None)
+        if qkv_b is not None:
+            sd[f"{prefix}.in_proj_bias"] = qkv_b
+
+        q_w = sd.pop(f"{prefix}.q_proj.weight", None)
+        k_w = sd.pop(f"{prefix}.k_proj.weight", None)
+        v_w = sd.pop(f"{prefix}.v_proj.weight", None)
+        if q_w is not None and k_w is not None and v_w is not None:
+            sd[f"{prefix}.in_proj_weight"] = torch.cat([q_w, k_w, v_w], dim=0)
+
+        q_b = sd.pop(f"{prefix}.q_proj.bias", None)
+        k_b = sd.pop(f"{prefix}.k_proj.bias", None)
+        v_b = sd.pop(f"{prefix}.v_proj.bias", None)
+        if q_b is not None and k_b is not None and v_b is not None:
+            sd[f"{prefix}.in_proj_bias"] = torch.cat([q_b, k_b, v_b], dim=0)
+
+        o_w = sd.pop(f"{prefix}.o.weight", None)
+        if o_w is not None:
+            sd[f"{prefix}.out_proj.weight"] = o_w
+        o_b = sd.pop(f"{prefix}.o.bias", None)
+        if o_b is not None:
+            sd[f"{prefix}.out_proj.bias"] = o_b
+
+        if f"{prefix}.in_proj_weight" in sd and f"{prefix}.in_proj_bias" not in sd:
+            E = sd[f"{prefix}.in_proj_weight"].shape[1]
+            sd[f"{prefix}.in_proj_bias"] = torch.zeros(3 * E, dtype=sd[f"{prefix}.in_proj_weight"].dtype)
+    for blk in ("L_mod.attn", "H_mod.attn"):
+        handle(blk)
+    return sd
+
+def _load_state_dict(ckpt_path: str) -> Dict[str, torch.Tensor]:
+    if ckpt_path.endswith(".safetensors"):
+        from safetensors.torch import load_file as safe_load
+        return _normalize_keys(safe_load(ckpt_path, device="cpu"))
+    if ckpt_path.endswith("model.safetensors.index.json"):
+        base = os.path.dirname(ckpt_path)
+        with open(ckpt_path, "r", encoding="utf-8") as f:
+            idx = json.load(f)
+        from safetensors import safe_open
+        state = {}
+        for shard in sorted(set(idx.get("weight_map", {}).values())):
+            with safe_open(os.path.join(base, shard), framework="pt", device="cpu") as sf:
+                for k in sf.keys():
+                    state[k] = sf.get_tensor(k)
+        return _normalize_keys(state)
+    if ckpt_path.endswith("pytorch_model.bin.index.json"):
+        base = os.path.dirname(ckpt_path)
+        with open(ckpt_path, "r", encoding="utf-8") as f:
+            idx = json.load(f)
+        state = {}
+        for shard in sorted(set(idx.get("weight_map", {}).values())):
+            part = _torch_load(os.path.join(base, shard))
+            if isinstance(part, dict) and "state_dict" in part:
+                part = part["state_dict"]
+            state.update(part)
+        return _normalize_keys(state)
+    if ckpt_path.endswith((".pt",".bin")):
+        obj = _torch_load(ckpt_path)
+        if isinstance(obj, dict) and "state_dict" in obj:
+            obj = obj["state_dict"]
+        return _normalize_keys(obj)
+    if ckpt_path.endswith(".json"):
+        raise ValueError("Pass the directory, not the index/config JSON.")
+    raise ValueError(f"Unsupported checkpoint type: {ckpt_path}")
+
+def _load_config_if_any(path_or_dir: str) -> Optional[Dict[str, Any]]:
+    p = path_or_dir if path_or_dir.endswith(".json") else os.path.join(path_or_dir, "config.json")
+    if os.path.exists(p):
+        with open(p, "r", encoding="utf-8") as f:
+            return json.load(f)
+    return None
+
+def _infer_config_from_state(sd: Dict[str, torch.Tensor]) -> Dict[str, Any]:
+    te = sd.get("tok_emb.weight", None)
+    if te is None:
+        te = sd.get("lm_head.weight", None)
+    if te is None:
+        raise ValueError("Cannot infer config: missing tok_emb.weight (or lm_head.weight).")
+    vocab_size, d_model = te.shape
+    w1 = sd.get("L_mod.mlp.w1.weight", None)
+    if w1 is None:
+        w1 = sd.get("H_mod.mlp.w1.weight", None)
+    d_ff = int(w1.shape[0]) if w1 is not None else int(4 * d_model)
+    return dict(vocab_size=int(vocab_size), d_model=int(d_model), n_heads=8, d_ff=int(d_ff),
+                dropout=0.1, k_l_steps=4, max_cycles=8, ponder_loss_weight=1e-2)
+
+_ALLOWED_KW = {"vocab_size","d_model","n_heads","d_ff","dropout","k_l_steps","max_cycles","ponder_loss_weight"}
+_DROP_KEYS = {"weight_tying","tie_word_embeddings","torch_dtype","architectures","model_type",
+              "initializer_range","layer_norm_eps","max_position_embeddings","use_cache"}
+
+def _sanitize_and_map_config(raw_cfg: Dict[str, Any], ModelCls):
+    cfg = dict(raw_cfg) if raw_cfg else {}
+    for src, dst in {"hidden_size":"d_model","num_attention_heads":"n_heads","intermediate_size":"d_ff"}.items():
+        if src in cfg and dst not in cfg:
+            cfg[dst] = cfg[src]
+    if "vocab_size" not in cfg and raw_cfg and "vocab_size" in raw_cfg:
+        cfg["vocab_size"] = raw_cfg["vocab_size"]
+    for k in list(cfg.keys()):
+        if k in _DROP_KEYS:
+            cfg.pop(k, None)
+    cfg = {k: v for k, v in cfg.items() if k in _ALLOWED_KW}
+    allowed = set(inspect.signature(ModelCls.__init__).parameters.keys()) - {"self"}
+    cfg = {k: v for k, v in cfg.items() if k in allowed}
+    return cfg
+
+def _complete_and_filter_for_model(sd: Dict[str, torch.Tensor], model: nn.Module) -> Dict[str, torch.Tensor]:
+    sd2 = dict(sd)
+    msd = model.state_dict()
+    for blk in ("L_mod.attn", "H_mod.attn"):
+        ipw = f"{blk}.in_proj_weight"
+        ipb = f"{blk}.in_proj_bias"
+        if ipw in sd2 and ipb not in sd2 and ipb in msd:
+            E = sd2[ipw].shape[1]
+            sd2[ipb] = torch.zeros(3 * E, dtype=sd2[ipw].dtype)
+        opw = f"{blk}.out_proj.weight"
+        opb = f"{blk}.out_proj.bias"
+        if opw in sd2 and opb not in sd2 and opb in msd:
+            out_dim = msd[opb].shape[0]
+            sd2[opb] = torch.zeros(out_dim, dtype=sd2[opw].dtype)
+    # Drop unknown or mismatched-shape keys
+    sd2 = {k: v for k, v in sd2.items() if (k in msd) and (tuple(v.shape) == tuple(msd[k].shape))}
+    return sd2
+
+# -------------- Tokenizer helpers --------------
+def _load_local_tokenizer(tok_dir: str):
+    tok = None
+    try:
+        from transformers import AutoTokenizer, PreTrainedTokenizerFast, GPT2TokenizerFast
+        try:
+            tok = AutoTokenizer.from_pretrained(tok_dir, local_files_only=True, use_fast=True, trust_remote_code=True)
+            return tok
+        except Exception as e:
+            print(f"[hrm_loader] AutoTokenizer fallback: {e}")
+        tj = os.path.join(tok_dir, "tokenizer.json")
+        if tok is None and os.path.exists(tj):
+            try:
+                from tokenizers import Tokenizer
+                core = Tokenizer.from_file(tj)
+                spec_path = os.path.join(tok_dir, "special_tokens_map.json")
+                spec = {}
+                if os.path.exists(spec_path):
+                    with open(spec_path, "r", encoding="utf-8") as f:
+                        spec = json.load(f)
+                tok = PreTrainedTokenizerFast(tokenizer_object=core, **{k:v for k,v in spec.items() if isinstance(v,str)})
+                return tok
+            except Exception as e:
+                print(f"[hrm_loader] tokenizer.json fallback failed: {e}")
+        vv = os.path.join(tok_dir, "vocab.json")
+        mm = os.path.join(tok_dir, "merges.txt")
+        if tok is None and os.path.exists(vv) and os.path.exists(mm):
+            try:
+                tok = GPT2TokenizerFast(vocab_file=vv, merges_file=mm)
+                spec_path = os.path.join(tok_dir, "special_tokens_map.json")
+                if os.path.exists(spec_path):
+                    with open(spec_path, "r", encoding="utf-8") as f:
+                        spec = json.load(f)
+                    st = {k: spec[k] for k in ["bos_token","eos_token","unk_token","pad_token","sep_token","cls_token","mask_token"] if k in spec}
+                    if st:
+                        tok.add_special_tokens(st)
+                return tok
+            except Exception as e:
+                print(f"[hrm_loader] GPT2TokenizerFast fallback failed: {e}")
+    except Exception as e:
+        print(f"[hrm_loader] transformers/tokenizers unavailable or failed: {e}")
+    return tok
+
+def _maybe_resize_embeddings_(model: nn.Module, vocab_size_new: int):
+    vocab_size_old = model.tok_emb.num_embeddings
+    if vocab_size_new == vocab_size_old:
+        return
+    device = next(model.parameters()).device
+    dtype  = next(model.parameters()).dtype
+    d_model = model.d_model
+    old_w = model.tok_emb.weight.data.detach().to(device=device, dtype=dtype)
+    new_emb = nn.Embedding(vocab_size_new, d_model, device=device, dtype=dtype)
+    nn.init.normal_(new_emb.weight, mean=0.0, std=0.02)
+    keep = min(vocab_size_old, vocab_size_new)
+    new_emb.weight.data[:keep] = old_w[:keep]
+    model.tok_emb = new_emb
+    new_head = nn.Linear(d_model, vocab_size_new, bias=False, device=device, dtype=dtype)
+    model.lm_head = new_head
+    model.lm_head.weight = model.tok_emb.weight
+    print(f"[hrm_loader] resized embeddings: {vocab_size_old} -> {vocab_size_new}")
+
+def _vocab_from_sd(sd: Dict[str, torch.Tensor]) -> Optional[int]:
+    te = sd.get("tok_emb.weight", None)
+    if te is None:
+        te = sd.get("lm_head.weight", None)
+    return int(te.shape[0]) if te is not None else None
+
+# -------------- Public loader --------------
+def load_hrm(
+    checkpoint_or_dir: str,
+    device: Optional[str] = "auto",
+    dtype: str = "auto",
+    strict: bool = True,
+    override_config: Optional[Dict[str, Any]] = None,
+    ModelCls=None,
+    with_tokenizer: bool = False,
+    tokenizer_path: Optional[str] = None,
+):
+    if ModelCls is None:
+        ModelCls = HRMForCausalLM
+
+    ckpt = _find_checkpoint(checkpoint_or_dir)
+    sd = _load_state_dict(ckpt)
+    sd = _adapt_attention_keys(sd)
+
+    # NEW: If lm_head.weight is absent but tok_emb.weight exists (tied-weights checkpoint),
+    # mirror it to avoid "missing lm_head.weight" in load_state_dict.
+    if "lm_head.weight" not in sd and "tok_emb.weight" in sd:
+        sd["lm_head.weight"] = sd["tok_emb.weight"]
+
+    cfg_dir = checkpoint_or_dir if os.path.isdir(checkpoint_or_dir) else os.path.dirname(ckpt)
+    raw_cfg = _load_config_if_any(cfg_dir) or _infer_config_from_state(sd)
+    if override_config:
+        raw_cfg.update(override_config)
+    cfg = _sanitize_and_map_config(raw_cfg, ModelCls)
+
+    # Prefer checkpoint vocab_size to avoid size mismatches
+    sd_vocab = _vocab_from_sd(sd)
+    if sd_vocab is not None and (cfg.get("vocab_size") is None or cfg["vocab_size"] != sd_vocab):
+        print(f"[hrm_loader] adjusting vocab_size config {cfg.get('vocab_size')} -> {sd_vocab} from checkpoint")
+        cfg["vocab_size"] = sd_vocab
+
+    dev = _resolve_device(device)
+    dt  = _resolve_dtype(dtype)
+
+    model = ModelCls(**cfg)
+    sd = _complete_and_filter_for_model(sd, model)
+
+    # Load weights (safe: shapes now match)
+    ik = model.load_state_dict(sd, strict=False)
+    missing = list(getattr(ik, "missing_keys", []))
+    unexpected = list(getattr(ik, "unexpected_keys", []))
+    if missing or unexpected:
+        print(f"[hrm_loader] load_state_dict: missing={len(missing)} unexpected={len(unexpected)}")
+        if missing:   print("  missing (sample):", missing[:8])
+        if unexpected:print("  unexpected (sample):", unexpected[:8])
+        if strict:
+            raise RuntimeError(
+                "Strict load requested but state_dict mismatch remains.\n"
+                f"Missing (n={len(missing)}): {missing[:12]}\n"
+                f"Unexpected (n={len(unexpected)}): {unexpected[:12]}"
+            )
+
+    model.to(dev)
+    if dt != torch.float32:
+        model.to(dtype=dt)  # parameters + buffers
+
+    try:
+        if hasattr(model, "lm_head") and hasattr(model, "tok_emb") and model.lm_head.weight is not model.tok_emb.weight:
+            model.lm_head.weight = model.tok_emb.weight
+    except Exception:
+        pass
+
+    model.eval()
+
+    tokenizer = None
+    if with_tokenizer:
+        tdir = tokenizer_path or cfg_dir
+        tokenizer = _load_local_tokenizer(tdir)
+        if tokenizer is None:
+            print(f"[hrm_loader] WARNING: could not load tokenizer from {tdir}")
+        else:
+            try:
+                _maybe_resize_embeddings_(model, len(tokenizer))
+            except Exception as e:
+                print(f"[hrm_loader] embedding resize check failed: {e}")
+
+    return (model, tokenizer) if with_tokenizer else model
+
+__all__ = ["HRMForCausalLM", "load_hrm"]

hrm_utils_API_Reference.pdf

@@ -0,0 +1,200 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document http://www.reportlab.com
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R /F3 4 0 R /F4 5 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
+>>
+endobj
+5 0 obj
+<<
+/BaseFont /Symbol /Name /F4 /Subtype /Type1 /Type /Font
+>>
+endobj
+6 0 obj
+<<
+/Contents 16 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+7 0 obj
+<<
+/Contents 17 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+8 0 obj
+<<
+/Contents 18 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+9 0 obj
+<<
+/Contents 19 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+10 0 obj
+<<
+/Contents 20 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+11 0 obj
+<<
+/Contents 21 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+12 0 obj
+<<
+/Contents 22 0 R /MediaBox [ 0 0 612 792 ] /Parent 15 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+13 0 obj
+<<
+/PageMode /UseNone /Pages 15 0 R /Type /Catalog
+>>
+endobj
+14 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20251016093952+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20251016093952+00'00') /Producer (ReportLab PDF Library - www.reportlab.com) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+15 0 obj
+<<
+/Count 7 /Kids [ 6 0 R 7 0 R 8 0 R 9 0 R 10 0 R 11 0 R 12 0 R ] /Type /Pages
+>>
+endobj
+16 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1905
+>>
+stream
+Gat=+D,8nW&H9tY(qD[VoSeV?84k@,ih2*"E0n#t-]G.G*[b0.YIhCNEoP-sm+QHL2c,u7_<gU6c9=&Ulsh-Ko_%TiPQC\FJ\t,&r#SNEn;k4,Qs@P,akk?,^KrqaHNP+.buBqTGh7u!koQ8hNAn/daAWUq?/qnsr="HfImB3](cjI@Kr*q2JtU^7_K`4r,)<MpBD@>j9$AO8LWL'o]SD-**JO'<^2)[9Nr-#8dlXPgTp+/Sr4\#cF2N'jYnU*P@[-@0A0T#-GZLW-@BQ$\'N?8%>^a;:TQA(L1)\>]6q1OG.?X4L$9,sSf_=<.=VO2;"cA%5">Wq4-=_uNBB_f?N#i>BF0/\T>15+2a2%l'J]4^h\($!@R0_LRDQ_8iLd[j(.Ib!)`e?npZ24XBs$KU65s9EX'ZQF_e)CCLRZYjtk("/oTgZ2Z#MM5"6"8!i4iN924iV(7kW/Tf$bIEm+4Y%CcLfu76W4d"^m7F@VVt1iUBdW`e?<e<jS->$j8P+E7*8,6n;G=\ZE;jj^d%(0_eR@YI.0>Pe9AT9]5&TZ#0SctUf6Pp.>0OhLr@/CbJIQE$E).[T[SE"oPk58B89Y10(U%i)9,oBm`NB`+*iO;:/o6WEM<&N#>S6_%_R=U(!?N`Mp)8R[;]1Fk]oI3m)4c#j!Q;P4_o86p]LDT'_TA@-`&,Mo][Yp's;mmBe#_4Sk_Mp_:35DP=2O?5B/go)h^s6Z<VX"#?oDI8K5n;-YetrfJG"B+o,@YCp;eZ>4=\&A80C/[SuXnd7ga\<$K>'ngt2`;g`1h[,n&XXu7<.*/kUYZAHMp`hKSeNcTnr>XDA`/nH)%O")='WDdJc\m1/dN[`5i)7%nA69^rSY=`ME=$mrN2(_@b:W[Uk)siVd5SKuk&?N@V`7$J"dlBVXON4_](>_*OQu]=!]A&GU#JLS@4-.Kt`h%gCq=aopLj<U+?ZWS6.NRE)Qju0d1u^.chmm.]r0C2'WH*X:&tBdhE6.IUHUf3S>\TB5o3H(b[AN>@(fjB.CRd'j`PFDq&f];jn2`/nO&'*>U#54`[gXsp403Z&G3?Q6_67k(ah[60U7<7"Z,%/"du<&V@Kc_^,_&H;mO4uUkAPBmos&!me`nBh(F#\%[T?Prne%_Z0o"5te(XMI%*dW]SE9?('>ZmW?aI38iH_Fu2lB\ZU5>NeSX#JbU<la%k.t,I#Q&K0QarqGKfj"E@d3OpdG1NC*k5JrG/9kO:*ej[`fn@oQV;,Vm^5CLOW:CECo+^:3G#UmYXN.=`hGGcF+Gg(gdZ5<03(OJXplV]grbOIHWW=>ORPk+:bc?GI7r2(Pm?H3VOLKD5tm+h<31U!C1JTPiADaSF%`qN4D]Xnc2DQ1KBh-g))AGM!"Ur*klLI3'^u>T>;<,Leo"/>.\9b3nldh@$_\/k.Jr8u@')>$i*f9/N(26[;hInnmA;?h`lktEke-YkJuVr0KjnqF19<J7T'%_B4;O@mc9PLT4!Jsm#EkIVYD/?5O65rbqa"\2=g&d6ZrYQpo*4L#h6!XM?O+9=O:(4gdluOEY3:HQ`L*kbeK:KH7Z],[s*eql[DC7jNXgBUK/Ha'%,?fVrOUDPpj976RKVYlOn+=o=p)H?8b?HqdT[jerSI[uE9HY(Cu@%*$:q.sWjnu1$pH9d&K)GA<?GV8#(%TkPO3ek(=uO(DSdW)h%p%RUge\6,b+paRUKNdLd]=o1+dNKOtJ/]X6<A2d=s3@2j9<<PFAViC'<fZ<G!,D#,H]M^?/6Jo"7@$/ugt<gV3>i1&S.@Y?b2+FpWhm(&mH#96Rg!>.e#b*7J#8oMucbWM.CX<4udqL)!9&L%S)(DDe%A,>#1WkZE^o6lN&/0Fa;eJl[sg$_qu8CdVS:l>IQ;6E.3?Mec_9hZ*'KDc$~>endstream
+endobj
+17 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1092
+>>
+stream
+Gau0BgMY_1&:Ml+bZ!W!`*gG.9pLK=)Pn'G1pZt2K\#i62V;?A]0N=knXWrq#]:868B;F\4.#V#1M:koB[Gemh_55Dp7ZruJ_(#h#-[-s_!f)us6/^g>C1P=g^\G>2OVFHeg\Jj,WPrk"n0Y<eaJsb2,'HnIH268^5+JR8JDRR]pdoP+!SV]nM0g"q6&<)\U^_KUWf)p8505?#u_0tOj9?V6%Z?%H33gOrAu0@fNb\Wf-bX:[%)nTaL^A@$D0t5D0#Zp@/*;h#tO/OB-/+*qiMXmbkQ+@KI.6SGn%jh(jn?a)JH[57'MJ[@pnp^A-m&c`)<Dcf+F^H:f8H&:CtALL=;RKR>-O@iGfU.DKd0ns6NKc^0.(40%'1$18J^*1BZqH*1ih&EJ-'9-X)Ys'dS'ZC-8WM>KuKH&*O%nrg>6c4:Jo@\(j#3LW?W'eB9q>-j$%<&"VO4g(l9Nn@4!FlASA7I+.F$C/VKl!$N_u$G#n;,s*((B=ks_EP`K]Rcb?$UJ\_>8\7g7>KST3Qe47Si#$?TdVk>AHS:RI]og<$fiBK(VK3ufR#cf20hTYVZoSQ]UALlW#$_0:'P=qb?8a=b?"0&!Bo.4"dA@:+%5>qYQUT9i%B0)#<QT^%d*Y.8fo#DH`;H@?&V-TN!l\WuWs]b8,hNG>`\auuI%'Ee9k1&RZq=j:_4s+ab#QS@\Z%&6g?/\dUIbA=19NHbd[]$"MCW'HRqZJ@07`n3JWboj1gRU=5Z1FbKPPh4:[8CU8b#?XLHJ;W&0Z[k04[%nrr!Q`N/W1,!jRj*9bf>+rRB<m5@U&ro#YNPR@2NYgLrIX(;298nMs(:Kc7B?Trb2UF>Q9!\[gOpLg!+_XTW]^B&&3l;crRX/$3R%f8``9,I^B?Yl[S9DS0N.S-r=*2@_1B`a1F424"ufH7Wb#%%(QSC*PGh5(\&rji1j!@,YlJa%0h]/pN3'/M\1nOLMgg"8:"eqo=$'nVa1-!da!pE[n@?^UefHX18ub4026/eo(Dig$Y*MgpL^?AEH8W_sqogg"=V"''%-bce>dD9V7);D0$&&7XeYlM.YI1[PAIk2(>8))`[[%<n$J:~>endstream
+endobj
+18 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1704
+>>
+stream
+Gau0DD/\/e&H88.EPO9X*ZRUeZ/'L@d'V%Q5gH[RkW[LI5Y8?-Kb@CJC6JPl*@Y-?[orlRJ2F)ta60up5'O@92Z>\uGFS_>NoB?I!QToa'HH$$@3!(\n]BArVmbr=<Z_P>&0Jk?Y1mR%R%<09:?)f@9@8q2:1&?gD=+6BI5e_M`<T:5_Lk]%`rEpN([_3?r7T`^I,J%0r-V_qW@1Z='MWI:6$@/!#KI]aDRHSO6Yg?Pf[dUd3T`_%=PnVVaYIWWP*49cpL8]N"8GIO'Z,rC9SMH$Zh?q>,j!M3f'51+P:2[^5C*>];qhLJR#6Q;o+ZY+F3!+Fahg%aM-S[AGBoTO(QVkVhdoZ@>a4LTVHa[LAm<QheRQZfWG(/Tj_rnLj>i0+@SRF7b!hWC,32)5n;4I(Ht?rGSo0X[FP$)tR<@CN>ZeS/d],cRP@:Yp/4L"F`,c\-%X4..Og/^,,9:]I@VQC+.p?IOl/gji)K[uNMMV`c0&fA-,YNXfVkhCI!cta#VE,YMku8WG(/dl<<^Z)s/2*96'B?4pUhN5\"CFQH"U2kY@^X^rlRWmV&bS!,MOcatL@$03crh,'U;PL1@9j)7Erho@:!#us!nsjfM!Z5cUb:s2.'?^9d**V_1DjE4L['SHV)4C'!"28m<"Mo3qSje=3/-R-E=uGOqa9fhe@"oHW,G;PA-$/N;CLFVVsb]D`T_J/Qn(dm;q/T1;WqT&Iq!m1jeN:UASBh+q<(8aWg!Y\1^A=C[Z@gf?AJkZM+<>4.l#Lc@hd_,_/oLo^hY33J*9(P&p4T2(n@Hml2eL'b:(r5K'M/s+)ENLD'85^0d)f$\f^$i4<%.tm3:BU.,_;=QD,..hJd]JZu+ngPj*ZI$]LpNdtL&YXXGD*/B7mXJ7&N6BcH>dMqEC$']Bq3mi/BYY>i?4;Gl-,hKrJ;h`''OkqIG4cGUS/p,&eCZg,1,qaR2Ui\A@m!G;'#ZtL47I_]&Ji_aUi#?p?RTnCHc,?@j1Tp>>XLUM!5,&R)O;RSkQ(UBodca$FUQ4SKq,h!Alpf\Z?fJCsAN>[`mQ!J/_g!2,=[[goQ#J)qhi*-/5jKWa390I-*U@2.fP0IF2KrR4V?]Ss^r5YaN4UC@f$#;UfN?s;@H&j0f.?%T#-:&iqR<gTnX%^oV)/`s>pKiu%h`HQIG.fTIM[:$1)r9E0?^gCieKANHe2k<'^b$7KrtR!Zr\5+&jI7S-82`!?N)l-I1FASOgSe.!<NTj!oT.CLX.FtS4*SurXg^N8J+Pm>Yj_Ejn$m?PA:"(_RD,dPCt3SW&D:lY6`hb_d!U9D3@?iD$,9a=+F%#[d%'te-1VY+-a+6S9BGV?#[[=R^q8*UaCt%H5>EEFjd)MbXqa0<pi*r0r>e)-=FH;=$!"-C2i$g?NpB]-s17O][XT2MQRTI*G:]Mj!<s)'2M+u3@YHjUj.`?jYFsN*N3^MGfOn9=9>-jZAC>m-LT#Y0o*UA<GYX0O\":18Ug%TcZ2L4=>:-L7WlcO?-CJ8/X7PpR?SI%L\<nush\_lscOW1P,4Y\sNi7"\l0?5Egpt-Sfr[JSTf$eM9&3";#ij[HWioUAjG?GVEtnROSDLW%kb\o"JKqfgERPPQ6]EtB>ZhUDO[Fft`9[6J*'4>_Mp/oO1oH#k>CMdH<.Ds[X8^D\[pV4&XBs&Se8^73^#ZPdX7``59=!L:IiI&5KE~>endstream
+endobj
+19 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 297
+>>
+stream
+GarW4;+ne\'SYHA.h7B^$&_M=e*2Jq_?</8666B.Y'4_o8S]6th`&Y^@:NOJj<Wpc69$_b4K_lt]I;RMEc;&e"(/89e2p\\q+:A]9pmeoJd[(8eNV;gDO\RGq*`E"ZmQ1L4Ha75Ui488m0C#*+39HuW,JWH_#O%JiK/b$O25hJ[^>A&Y+285?.nMC;aLaj*47emC`0o(H\gg=>hPP(f9N/HW3/52N14oF_u(ClYgk0b4XhDT((;5#ropM*UjVfhJ/_UZ]8fAIFkKYm:I$"f#O7c/:#\u0qZA*na,XpY~>endstream
+endobj
+20 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 849
+>>
+stream
+Gatn$;/b/B'SYH?'j$hN_$4UI+JhW"<2?f_d#PNe;aHO;*:QMce99P`^OEU);&V/;?&=4Ij.(0DhoQ</=!,M47iB)jJ<M\he:f"Ge8opI9].[>gc&';e+Xh(:>LL#.E_:oCY-P2Tl3@=218i/Q+DKnUXXFG:30C]1o>'qUQe8a$*tt=+#&UD4DV>Ip]\J]A+i832+)lOmPjbrL7U!Q[tY\k1$`sIh*!:=5>DAR\B(mP,bAIrGImUsmlB4Pd"?m*Y`>m8J*At/`aQksOq*$ueHQel#``J='o,@YS`[38q%/^R@g2&R3p?D.B^0UZZ&!&;bmM88&/5r.apA?;>dRr&k6'M!g+Y6^[Z($JJo6[()4'S3I*WPh%&\<GjG<E7Pb%,DXuR`oD+-$8R6uW8M,Q)0)IafrUA(+WD3EUb9n%jXNXbS)goA6ScdH"WKJ",YA4qC&K$K]!J&D`;29,U$f-NtChmGR09Cmm/)Ag!:X)AgD)/cTpYB<&$g$L$_3r''i6Wt;;^a`NA#o-@_>0d,Wp&4;__H_@.d.Y-4U5Z\`NcO6[K3T^fjRP=/LiiQ#6*7!T85+3j*05qte]A)/*I2""6%GBS;u-`g\A9Ci.nBs^N5Qh`S<<u1H3=1!LrrO6ORAaT+/.,e5&$%K/cUO+k8edblpb#=5Za.`M8p=Q$Zu^`HIIf1QEiht)WPq^,qVX6A[W_)2!oMZ#3[(QmAm"B0uHdq8sm<?liu[T]*mK6DV/PZ2RH+rG+,.rYCTt1]iU5k)Tsj`1(Vs53QS8hU][A98Vd?r6'*CXM?poG'$lDrAq?rQ0hs%BeH:9I!YDJ)[*H5HHXV6"LB8BD!G2=-56~>endstream
+endobj
+21 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1119
+>>
+stream
+Gau1.D/Ymt&BE]&;r"E&D)3(Co$BpSd62$0enUbqb=K^*UN$C'g*TJDot0Z$-#Jf_Lhm?rC2ELV]-$5-fnKu"G5g*S!T(D,2R1*dJfB=/=:Vj-nA.9!40fr0%XQ\+L7JoNq([lX)tlaSQH.A>R$Z)F?*FQ'VNX78#$UKXkV#iM'+OE@o#27')IC5r>f0"G;U%$7aYC<7i1:ddhrrau4;d`abGFX8$U*N:*^_<9TkBm04deqh(R")A9NsaDQiMbh9D#Wb3NaK98msD:*`oj+(_glc$/!GHfuCSRe/f+/jIa@\p2fbM0n)h.:+X@Ne<hX-'ne\9a=WrWSF+;EDL_.8ZQfR?6K$Rt!8n8)"Ak!-")sMoR]"OcL"ZN)M'5KI7=`dOdM\ir8ecdCmEN$>,N9JZWAMtP`h82sGLRbOmcY46hrdZ;(][>5>`JIa=S[VmX$d"Uma.?kjSA_\<H+1uB=8kW&`X1bA^fZh2P'FDfp(LhfNdV-Rk:JVqiS?rn)(Ke&,"71bsf/TY8?:hZ3I#coXR^F!6Y)#r4>u41:.RtV(&N?abL&&'uVXt.9Em,la:Nl_UYQBME9P]G8iqPMUr5O63T2r]>\e!pLXg&eUp<*/37a3hotbs)/!]1>e_n.e9KuL;VZR[MA<(9]`q?!i\g$r)K?35(-7!q&_&UIpNQ!nHhianqX<cuOn_TPMaVSQ-[n`Ae^c\gHVV("m%nsO:*J)#VOt+/s"QN&VI075J&gW?pRB(-&[0k`E2>OjMt%l(p_"GblbF546n&i2r?KibT`,Q!dO_6;T2>]BX-=6#RE;t5FumMJhjhQmZC<JXl]s%:QuMTu/d2X(FG5u,l_JT(S\3%NfS![e;T+eYW$NIje:G(QiNoJ"\kt+k9##@WL2G"%^&/T<6kZUDLUG?jp*@XEUZ^+rRu^Vt?'?S^3NOK$=;9#I^DPEc=L-'GWS0H)>,#6:geaRRa9j1eQ7M.&EqP)r8RHsJi&HE-jUE\4YB51N+0XMg():Rc:I3C2jcj(3H0%mj;V:!&\J$B+<iRpTf45cb*EL0DLU:iaC$Sn7J>.ka!">h_V[F\c\tWE*qb'&h^f1pM9U_D^<Yk-pI'*5DKa*Qd"3+=C?i~>endstream
+endobj
+22 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 827
+>>
+stream
+Gasammr-o6&H0m]EC-*.[a^9CUa]3;D:8,lPI`4##`@F48A+*:*)k#ZqOO0D>L[D/,f#H/h7\%$i"48Qh.P+8HqrYk.gJ7nF:3K4(6Eut0BqQlKKn=P65IC;&C[\SU%?'jlZ,=cr.IOZ%3`uI7i#e[=<-cW(95D`#3dd3hcnkXoUK>[6--2\p:D9'gJ0]E(mHsGMcXsg&22_eQnF&Z`NJc^/R?AWVUIuQg+G%dOI;H[NlaG@>:;A'4QIfsW.i(3CH@<[&#QtV<rG>O6a+,!2_,^RD&Vr+\%'c?q]Ue3F;:;%#4FAqS-@S^Fij]k,i1li/O#OlE7P\d"qBk6QBTQ1>u:d>Lf/8dW)FG!2cemi7S;1mL9c#L8>a(g&qXlqS]N=:R4]^npWmMV3)U?/:b?A.QBpV?)WrF$<Hk8p[K]fSjq2bp>>N<"l"7X"iI^s2g;'O"-1d_Mhuh#Xkc=p!X9qq'@qN=sFQm7)<$.oN&rV'kf\>;_hVft=7r^(J+\:3BSbP_Ic%s9`!_;4@,ULtKU?7iFK+/,gX20`8H/[(*G:qppkg$Z-+-'Bt)%)lI6g)AUl2`2VM$@?a>t_l`U;jW,aLp7Z%1/SRZ3oTHBC0ql5aKgXnGVg+n@.T@amUKhh$KKN]#hU!ES$[b.R!H5ZtD-GG#Htp3V9\b7FQ.X9U25<FWL)@W2RQY?U[-95L`pBa8Zakj$h$*^r#"j%\CDleG%Z/R6)=d6@#h+<E<YaU-^?E;lpp<Yck8WEU/8=Qt(3\`bV4O(rSR0,%%%=NZ&h429cja"(HelaX\(r(a4(",HXrhlMA<AH3BGH(,(;[~>endstream
+endobj
+xref
+0 23
+0000000000 65535 f 
+0000000073 00000 n 
+0000000134 00000 n 
+0000000241 00000 n 
+0000000353 00000 n 
+0000000458 00000 n 
+0000000535 00000 n 
+0000000730 00000 n 
+0000000925 00000 n 
+0000001120 00000 n 
+0000001315 00000 n 
+0000001511 00000 n 
+0000001707 00000 n 
+0000001903 00000 n 
+0000001973 00000 n 
+0000002257 00000 n 
+0000002356 00000 n 
+0000004353 00000 n 
+0000005537 00000 n 
+0000007333 00000 n 
+0000007721 00000 n 
+0000008661 00000 n 
+0000009872 00000 n 
+trailer
+<<
+/ID 
+[<c1487d187859f418a42d51747ddcf18d><c1487d187859f418a42d51747ddcf18d>]
+% ReportLab generated PDF document -- digest (http://www.reportlab.com)
+
+/Info 14 0 R
+/Root 13 0 R
+/Size 23
+>>
+startxref
+10790
+%%EOF