simplicio-prompt 0.1.0

package/benchmarks/prompt_vs_normal_results.md

@@ -0,0 +1,148 @@
+# Prompt vs Normal Instruction Benchmark
+
+Run date: 2026-05-21
+
+Environment:
+
+- Python 3.14.3
+- Repository: `wesleysimplicio/simplicio-prompt`
+- Benchmark script: `benchmarks/prompt_vs_normal.py`
+- PDF report: `benchmarks/prompt_vs_normal_benchmark.pdf`
+- YOOL profile: `YOOL_TUPLE_LANE_CONCURRENCY=32`, `YOOL_TUPLE_MAX_LANE_CONCURRENCY=64`,
+  `YOOL_TUPLE_CPU_QUOTA_PCT=95`, `YOOL_TUPLE_QUEUE_MAXSIZE=8192`,
+  `YOOL_TUPLE_COMPRESSION_THRESHOLD=1024`
+
+## What Was Measured
+
+This benchmark does not call a hosted LLM. It compares the local operational
+behavior implied by two instruction styles:
+
+- Normal instruction: flat agent materialization and sequential execution.
+- Yool prompt: lazy `batch_spawn`, tuple-space routing, and `LaneWorkerPool`
+  fan-out.
+
+## Results
+
+### Scale Representation
+
+| Profile | Represented agents | Wall time | Peak memory |
+|---|---:|---:|---:|
+| Normal instruction, flat list | 131,072 | 217.11 ms | 28,749.88 KiB |
+| Yool prompt, lazy `batch_spawn` | 1,048,576 | 0.16 ms | 6.32 KiB |
+
+Observed improvement:
+
+- Speedup: 1,397x
+- Peak-memory reduction: 4,547x
+- The Yool prompt represented 8x more agents while using far less memory.
+
+Larger scale run:
+
+| Profile | Represented agents | Wall time | Peak memory |
+|---|---:|---:|---:|
+| Normal instruction, flat list | 262,144 | 431.45 ms | 57,542.32 KiB |
+| Yool prompt, lazy `batch_spawn` | 1,048,576 | 0.07 ms | 6.39 KiB |
+
+Observed improvement:
+
+- Speedup: 5,902x
+- Peak-memory reduction: 9,000x
+
+### Active Execution
+
+Workload: simulated yool work with 2 ms latency per task.
+
+| Profile | Tasks | Wall time | Throughput | Peak memory |
+|---|---:|---:|---:|---:|
+| Normal instruction, sequential | 256 | 603.98 ms | 423.9 tasks/s | 17.33 KiB |
+| Yool prompt, lane fan-out | 256 | 94.87 ms | 2,698.3 tasks/s | 879.82 KiB |
+
+Observed improvement:
+
+- Speedup: 6.37x
+- Throughput increase: 6.37x
+- Tradeoff: the Yool profile used more active memory because it creates tuple
+  envelopes and thread fan-out structures.
+
+Larger active run:
+
+| Profile | Tasks | Wall time | Throughput | Peak memory |
+|---|---:|---:|---:|---:|
+| Normal instruction, sequential | 512 | 1,212.88 ms | 422.1 tasks/s | 33.55 KiB |
+| Yool prompt, lane fan-out | 512 | 130.28 ms | 3,929.9 tasks/s | 1,739.41 KiB |
+
+Observed improvement:
+
+- Speedup: 9.31x
+- Throughput increase: 9.31x
+
+## Findings Beyond Speed
+
+- Token economy: the Yool prompt has a higher one-off bootstrap cost, but it
+  stops repeated chat-context orchestration as soon as work fans out.
+- Scalability: the Yool prompt can represent million-agent trees without
+  enumerating every leaf. A normal instruction tends toward flat lists or vague
+  "parallelize this" guidance.
+- Memory behavior: Yool wins massively for dormant or planned subagents through
+  lazy hierarchy and compression. For small active workloads, it spends more
+  memory on tuple metadata and lane workers.
+- Auditability: Yool execution emits tuples and receipts; normal instructions
+  usually leave only a narrative result.
+- Recovery: Yool has explicit tuple state and can resume/replay pending work.
+  Normal instructions depend on chat context or ad hoc notes.
+- Guardrails: Yool has named CPU, queue, compression, hookwall, and disk GC
+  concepts. Normal instructions rarely enforce these unless separately stated.
+- Portability: one prompt points Codex, Claude, Hermes, and local scripts at the
+  same Python files and commands.
+- Failure isolation: lane routing makes it clear which class of work failed.
+  Normal execution often mixes planning, coding, testing, and review into one
+  opaque flow.
+
+## Token Usage and Estimated Savings
+
+Token numbers below are deterministic local estimates using
+`ceil(UTF-8 bytes / 4)`. They are not provider billing measurements. The model
+compares repeated chat-context orchestration against one Yool prompt plus compact
+tuple envelopes.
+
+| Scenario | Normal tokens | Yool tokens | Savings | Savings % |
+|---|---:|---:|---:|---:|
+| One-off prompt bootstrap | 19 | 210 | -191 | -1005.26% |
+| Scale: 1,048,576 subagents | 47,185,939 | 232 | 47,185,707 | 99.9995% |
+| Active execution: 256 tasks | 11,520 | 6,610 | 4,910 | 42.62% |
+| Active execution: 512 tasks | 23,040 | 13,010 | 10,030 | 43.53% |
+
+Interpretation:
+
+- For a single tiny request, a normal instruction spends fewer tokens because it
+  carries almost no execution protocol.
+- For massive work, Yool wins because `batch_spawn` replaces millions of
+  repeated subagent descriptions with one compact tuple envelope.
+- For active multi-task execution, Yool wins once the prompt is paid once and
+  subtasks move as compact tuple envelopes.
+- The break-even point depends on how much context a normal agent repeats per
+  subtask. In this model, Yool starts saving tokens once there are multiple
+  active subtasks or any large lazy subtree.
+
+## Limitations
+
+- The active-execution speedup is strongest for I/O-bound, subprocess, API, LLM,
+  browser, and external-tool workloads. Pure Python CPU-bound work is limited by
+  the GIL unless yools delegate to subprocesses, native extensions, or remote
+  workers.
+- The benchmark measures the local runtime mechanics, not provider-specific
+  behavior inside Claude, Codex, or Hermes.
+- Token savings are estimated from prompt/orchestration shape, not from a live
+  provider token meter.
+- More concurrency can increase memory and scheduler overhead. The high-speed
+  defaults are aggressive and should be lowered on small laptops or tight CI.
+
+## Commands
+
+```bash
+python benchmarks/prompt_vs_normal.py --json
+python benchmarks/prompt_vs_normal.py --tasks 512 --scale-agents 262144 --sleep-ms 2 --json
+python benchmarks/generate_prompt_benchmark_pdf.py
+python -m ruff check benchmarks/prompt_vs_normal.py
+python -m ruff format --check benchmarks/prompt_vs_normal.py
+```

package/benchmarks/v2_safe_speed_benchmark.pdf

@@ -0,0 +1,118 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R /F3 4 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
+<<
+/Contents 11 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/Contents 12 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+7 0 obj
+<<
+/Contents 13 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+8 0 obj
+<<
+/PageMode /UseNone /Pages 10 0 R /Type /Catalog
+>>
+endobj
+9 0 obj
+<<
+/Author (wesleysimplicio/simplicio-prompt) /CreationDate (D:20260521154938-03'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260521154938-03'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (Yool Safe-Speed Benchmark V2) /Trapped /False
+>>
+endobj
+10 0 obj
+<<
+/Count 3 /Kids [ 5 0 R 6 0 R 7 0 R ] /Type /Pages
+>>
+endobj
+11 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 2409
+>>
+stream
+Gb"/)>Aqt]'RoMSR)aa2l.dr)!=MGS#I^a"X(<"TcEmmPinudmrr&E+a1!t+;cHs&TrQK03HO?Xqe"-m2FRatB`'el+S=XpS\CtW13@MmW5&I?]L/kTNkQR^Xeq1^)+atZ>%>FOJ9`7a;4Lo4JH]3pL$8t!a:L5F+Ci5-V%R!A%*1(KB_5)hcI'27oI&fPmjI=Q?RF6UbHB4tp&nZK5o3>E8UCq,oJc^7Ef.2X;_;@D%F.ck>_r,FJkMrtB_4&cXBam#QQj2g1QQ.kFe3HeGaW.O2a9bR.%8GaVC20r9/fr$eL!d-]L;)DrAo1aUW:44dFi,g-8,&=&0jl>&:)-+/UdXDT;KeELgr]<QhPdONA6-t-8aN1:'G3EKl/q>jOXMc7^$]WZH6b:4?D@N!;IYlhC(rW(G#!XOY2_;4V*&pgbSU3PbK\;S-%OJk^8T)3?T)6%Re+_`6B=dY1L!u0LTe694mG:Td0end^`_[[D1F+ko*8YqW?sT17Pc[+J-)RlH@p!XjRX!"L_&]TD7(h5=Y+sdXOrsCS/9NgWrUL.X-D/HAk&"j>sueKLH[?b:LtfG)VSeQ>C.nqODg9F&9*Nb0k3WP%J,lSkNe?X5dq`R(LN=H4>3+4:CTRRiH6WC$sdY[TA@%=h%au@+urr\Vp7[Jr+T+gr_;+]"fJ5RD4EkCuQ6]0EB,Dp]-?40278U]46M*=>=S!&o6Jn,hR-`p'.[LLV[3irGqQ!IrK8Qiqr@*0DT26=L%bgSJAjSMJVJJ4'-Xp0e1'9Yq#+I;%Z!p*1U7*Blrt28IM;sV-b.]i+B2+D27Qep+/fNejd]t1^\TZO#%mA#%h+Nn%5(8a,BVmoc\ig"1VjaXFM8-<e`hjr>d"6&_.!t=9o]'QlB`NKA4r18oU%4V;N%TR(@ZK=Js:iV@aT&K3a.q,nuGd*:&Z<SY-`kVH$:j8obdmjBP=`g,FH-748?_@Pf"6,TO12IF'%'.]Y9Ha?$8/i"$f$X>o=1"(d^3,p-Nc_T<RJdikY6Ydi[)4iX`NIIUiU99]hW9p9"Q&Y[nV1r0?l_MR!p7@=k`!QHQHg;lPiP^u_,1Ju(9-l!$TMl(H[<,+E!:J,&GNU$CdOs/1LKR$u@S+t#+XM`CWb6Hlr)/K^=750>'eD"]#YT]BEELg2@N@01\=o$*M#RWl7\EZ%F5F\,ll^2[m`=NGLNgZ`V3(]2L=^MSWfEtk3ffMW-@_k(h3(-!#P:Gmc#q.h$!#0Dn$<qAV'T([U*TT;<WMEX0]a2"+DLFZ#$iWXLoIMojeFo#jC?&E29-@=.cP0lV;Sokt$2Te`dSd.o"WrUOJXMHsAM9IN[Z71-**=7)2;td8OVLs,,2_;T)GOWSL7P::2O^.WaElG8/rf"?kkq+lcVF*(g+S#>aX2kpcX:$k.p]6bmYmhSSc<G!-T$Du_%2[]>>;$2Upo'YeSu'aePK!'J5eCpc9@Y2p7/aX7R)80e9s)U7,<F+cgV(O2o8bSkAZ@he;"N)=fW/%Q*P!L>-W/5B(JaZa4i!;D;'HDhK6QrVQJu[obeWOh<D/N%FhQk86`-'m?P+\a1?]f1bRZTKb?8/XM7lT$C*8!9FVRL>7E*)@D+i&C%\P*'/`Uu3ZqA'G4dIdHb3;''S_p"s,1u2CP@PW83[XR!mt0:?/U/"B`nAT0hNAM@8`nnm3)L(@-qMR<?[P=JY`F8:DhadMlg#H"'*nX:;b)U%-jU.P%m`ijWo`#:YAd(H=#HGN%6PKTchO]pMr1dN>lWr;$]9P8m89&5ZtPPUMReW%EQ)Fnjc4mBX('uEJp6NWaWO9ro/%G*);BS[%?m[<^#)7QB2cs`c!7a^)sk=#`1XHiV\UZRU#a3*d%eQ#+B>jD]e?>;\"+<*MPAhI$7HWUiL7Om:)r]8NAp\RWWRJX)!76G#2+OCC,8'i9[,5dO-'"F=C74F=NSEF=JJ8C>AdEVZYso-6Ok`Z.,cUj_=ib;U^2:D4DP:25a>=jQHT4*=?nT@KgkO@L7.S,-#U"IR;QcnO!n+!%^23/l`ctL0AI0jN9XJ.sqk]pJ>rB"a?;>81ni>pWF0"72islJ<1q<a8aHA*'r#(<5)'TM`Nr8BTCB5TQRqrRFHNlNSS2G9;$$NBF.'Y?nDC0"Vaj`UcsU86+%?UVI2HBb<[G/Y-).kLoWffk(FF:#&uN!`R*^8rh?nB<+8-q6!Fn%K3A]^>%B.@bJ@5l[mFL+8i-mgbe=Dfc@2VZYR9K;Hs_q@Q1+%NWtV8g;W:Jpnu"MdVE-_lp?U)Z7&o`Q\gsr8[_]bqQ,u1Lr!(\C-cVE,iu2-JBPeppOF(`c]1'gb)#o2A8LM"_[dg]t"3V=N"iGZonN6Eb+isY^8cI3b#M(/T`)"A*hO6hj'HU;=`,(2-MD%M=eKa;AIu[,Z-N~>endstream
+endobj
+12 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 2040
+>>
+stream
+Gb"/)gMRrh&:O:Sn>/Ag,Rj-7^,fqZ(+ml[6Mi0IjL)*l(IsXPI"$i$muV=Qjt7SXE%2.%6-\BVm$Z8FiE2U(Gk(M%Ce;_4KY2WK#o@,m::R$U9R\A(9MRdBn6;^:<,*^*WOS]s3X,Dr9UTDG)+(m\aq6,Ek2KnT4"MVF.B8AIjJ?6pdua1a-e)-c<LcluQ/i;O3l,shD)1W.dqo0$i!#4n90k&->;sO'POLJV8W<>n-$f4IApljM1d@2G7l#@=#KMOo9PY^-PBqS`9n9@=g57A1s/?eBZ:r&fFAu5n7+]0.XD]^DYA\Tf&pkld[AlXUrbK#4$EQ*bcL;Z5]1b>d@YSXc,3M`<le,9ZQ@NaYf7u@G^V4G`YpZW,G2_?iLI63N=fjX+H9p\om;?u$gWe?N9Or+?cmBDBKIU;*@l%OZ[,HVJ9K_lP?o/G;16KWZ],5(07!+7"3OtYe>e]!%Wb(B/_s'Ug&rt*S]nk7b:m%G1mfh,iL=2OpG4]Bt"PFN#>G!i-\(=@>K7h)PkI!ZDl(h?kBZ8.M$/B**`=,NC4&XH0Q\Z?]3gA.kE5%8.#!X2*BXP&<'V8Y4=k'm0hRu('mR"X0SRWPk!3?ssI;A&[hg_+!>_KWe18\\<_4Z)Y'b$gL&=nCL:?Y(5c+(PNn]L:[gmYhYRYB8gaEfWpcn$'ha3pGs&^6^4,M8Hs"e$/>qlk?%/qR6LIC*1!\%"<qe\6@#hcP,Lkkpr3/ZeF=pB$9_J5<jBd6W=oT,kY(6hg=\_tpP+m/>@V<8W>MBt^!Ac;tfZrZ(^>=!HA_k]THBE`=6DX@+m@<67KR;F.@*K9]!HGdaL4]m/g7,Yp'[/'4a6[7h1]RrJ:%M<*oLC.]btCCh:]%2L-a+!jXWpjj(:3I*QJe"[EKhs1hj/[Ye#PL:UX#J`;>!j2=jr2eS52t_Q<"&8ggHF;M/(O7_:ZpaXNMNOYNH"8Xm3nkZi&Ooot!?<R$ac(`pB(k/C)j2ShVliLpr/-;;5$3\UiVWcgQ6U[(T:-bA&fZ)G3F9T/`@raIdlbkFD_+@OidsZXo&Hb_AMgM=Vitj`aT*0U7_JM0^@"7>/?_"WG2)Hq#pCLXMf*_Q,"EgIa?h.LU[QYT4AeocFU2WA\Co>B:'c4X%AI46eD^+jk`?dtYmdUdaq-1j@bGpmdfJ>nJilTmIutm7?DFSrh#BWn(u]hX5Rin:oW\TEqusS"kNXH_IL$f8Q(Z,'Q]rYV#J`;:o!X:U5UQ/Z?FTA"@0Dj7EWe8LhBY#a!P(s)"Ti$u>8f%WK^.r&705kbjaKF0<qU(=:)!a8X/p,j5HVE>@_PH+(?_W>bX<D!"kg?`S>o,s=_aAcd=slSh.AiD'F&'GPq'NI]6]h7hL?3UC+CO9%qDS4&6P"&Z[1"m2iSWLc"^<ETG0EgEUR:pJQ.L='gD,D]=redS#1:8+;F?D<gkf>29..`!(U>f;mQ;,%TgQsIVu%-f4K1^J2(*M(`TM8!c;a!D2<tuC06cYKKEk1-:o+tV]sR+^<ra1X^fd1ll*lF^^ELIcg_b.c@?$ho48:)11N*dn7@LP1*cT]4GSPVQ7bRX.+;n=YT1sdR;@3#SD@GJ.XK.bpd5ZLV2CX<,FJo!>:N(-WA$Y^+S!lZM#s^"CHX>NojQJFmD!P9ZNj7faB844)eJj#MT3+*:G]ut(`Qbb"(SEgZ&rT]i$DD!WeG-5BuVHuZK%@Y`C(H+G?^;6G"c5q@;1F\D<nq_2;Qg;X6GDWDb8bPR48+l(01-l"WlWO5aos!:u<cQdU]=dZHB4q;3=pKq%YBm(m&-]"pn^T>,N-W2L`Ao6FBA;O&W&tJn=hR(m\RK>a:YZP3Q%H]Z0#51:>+2PXIV'_,J$$G@sG)*<\O8,=:@F8G.2Fdj*7!M0Q8S2mHcM[V+UI!/pTDLI^4k^)K1TKD43[OW1t%#*7R'HZ=7eL5*<=1c4!YU.*CSCOk?cp7Fq5N/Kq]LU16TU[8o#>6MQWC7gRS*3EEJ]/3uhHL7N0>=9XtEh@3NHekF&mtY?4jBjh(Pah~>endstream
+endobj
+13 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1187
+>>
+stream
+GatU2gMZ%0&:O:SbY*M/O`2V(\imJjGHjSec*m%('aSK0NgNA36;$+XfCr+MV+k^BM$kOda>:^i4>WL!8-(p5pg#^E^Fnd<]9#?Sb;G!*$!LZan&r]1,2?<JS4*bIP_M1+U0PJC.*L(-U`m!*'2^1IS+A=/akeUQ\7G\t1gk<^K<MM`MUl\]_0@5!G-!-N7p<VO`V,m':m-+2To73bN@pL0>t\H6<o"OgmB*@;VWBrmh`PrgK7HC)2S6H<2R4[c]&!ocY>'A^1!a!m#Kc?.R?NhMFlbZ\b/6t:cWCrNiIPYM=kE)G=-Os]Mo6-*M-rX=orth0;jPC*1g>T3LnB]0PPBXE:%"W@Wq9S>eQ:<1G?$To-\N/r#l!4i?Qu"bQ#P_o_XY=-f1CDXTi]]GjkTBpfkJIP/iJ0=As6/3*`RJYX3"O!c;."h)5de!pee$9<pK&23_-)Lan-L:Nf)oPjraB1?a+Y,&6["O&Yi38j3O@d(G(I.bLe*CC::g]VSB>iF\KP7/LEH%\j(+Ga6]!;5V`H$#p<i156:O#aDoN_c/UO1Be_>rH+Zk7LSr)oo3?,'iSeK*_3ck0%![##bc6?D<qJ,RrF-"])F*ht&i!%b3"VHX+j4Aeq.Xuu+N\5Ja!['bD[Mn[P2F"6(l[LFb5@d@pjeO:W:jO]Hf%=[8U,?GM/TBk6Q)ktOUA;Q?=J.?;f<@!LXmj[DiJN-r>VkL?W=M;P@%K_GSc@>.q9ksg8N^>\s0%C1\q]4'jAA`")+o=%c=[jU6:Kejn(5ZXQiaq2b/bL7bLDUdeas[3%/l*=\-Ho,8JoJKC3H-_]P-9ed/-t0^CS;V]jl<`qC$+3U0)s+!Yg+R2C,]8Wau27#8Hi<uB7tAZr&`%;<sNX4lJGD>\D7-\X%0Ab:nq[ObC[E,E#1i%,<\d$97uQdd4H[B]a",5'#N]=U'AoiehDF6muij89(+4BO>irYf:S\/3L;kt)d-GIB/lN,AT=$V%.WN`ntfNC,^jWkim&>?sdOrj$-XZP*kK62%Z]O>kobX/-iuSX$rXSb9!7[(N1UMRD!%RU+B$aEqQ7h>>\"[O`m3!bpaAoKF#^gWeVW.l4OYFb>B\6T<p!b-[MrL(t>)@!Ef+U`(VU=W><26F%&`,^!>6Z*:YO%`jtN7L/4"X>"T(%RCqXs5Eg".V\E+^[o`R~>endstream
+endobj
+xref
+0 14
+0000000000 65535 f 
+0000000061 00000 n 
+0000000112 00000 n 
+0000000219 00000 n 
+0000000331 00000 n 
+0000000440 00000 n 
+0000000645 00000 n 
+0000000850 00000 n 
+0000001055 00000 n 
+0000001124 00000 n 
+0000001438 00000 n 
+0000001510 00000 n 
+0000004011 00000 n 
+0000006143 00000 n 
+trailer
+<<
+/ID 
+[<0da54b4afa3b68d501c20ec7de58b460><0da54b4afa3b68d501c20ec7de58b460>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 9 0 R
+/Root 8 0 R
+/Size 14
+>>
+startxref
+7422
+%%EOF