Iimz%SrSSKJr SSKrSSKrSSKrSSKrSSKrSSKrSSK r SSK J r J r \ (aSSK Jr \R"\5rSqS\S'SS jrSS jrSS jr\R."S 5r\R."S 5rSSjrSSjrSSSjjrSSjrSSjr"SS5rg)zGNUBG subprocess integration for Backgammon bot AI. Manages a persistent gnubg-cli --tty subprocess for move evaluation. Falls back to random moves when GNUBG is unavailable. ) annotationsN) TYPE_CHECKINGCallable)BackgammonGameStatez bool | None _availablecXSH$n[R"U5nU(dM"Us $ g)z"Find gnubg-cli executable on PATH.)z gnubg-cliz gnubg-cli.exegnubgz gnubg.exeN)shutilwhich)namepaths U(dMXS -==SUS ---ss'M% [R"[U 55RS 5R!S 5$) a#Encode the board as a GNUBG Position ID (14-char base64 string). GNUBG position key is 80 bits built from unary-encoded checker counts: First half: NOT-on-roll player's points 1-24 (from their perspective) + bar Second half: on-roll player's points 1-24 (from their perspective) + bar Each point: N ones followed by a zero separator. 80 bits total. Packed little-endian into 10 bytes, then base64-encoded (no padding). We always encode from the on-roll player's perspective, with the opponent (not-on-roll) encoded first per the GNUBG spec. rredrP Nascii=)boardrangeappendmaxpointsbar_red bar_white current_colorextendlen bytearray enumeratebase64 b64encodebytesdecoderstrip)stater! red_countsired_bar white_counts white_bar first_counts first_bar second_counts second_barbitscount key_bytesbits rencode_position_idr@3s KKE J 2Y#aa12mmGL 2r2 CELLO#345I e#".i$.z",i$0zD QC%K  A KKi KKN QC%K  A KKj !KKN d)b. A d)b." ID"I& 3 1f q1u - '   E), - 4 4W = D DS IIrz.^\s*(\d+)\.\s+Cubeful\s+\d+-ply\s+(.*?)\s+Eq\.z!(bar|\d+)/(off|\d+)(?:\((\d+)\))?c[RU5nU(dgURS5R5n/n[R U5HjnURS5nURS5nURS5(a[ URS55OSnURXVU45 Ml U(aU$S$)zParse a single hint line into a list of (source, dest, count) tuples. Returns None if the line doesn't match. Source/dest are strings: "bar", "off", or point number strings. Count is how many checkers make that sub-move (default 1). Nr)_HINT_REmatchgroupstrip _SUBMOVE_REfinditerintr#)linemmove_strsubmovessmsrcdstr=s rparse_hint_linerRs tA wwqz!HH""8,hhqkhhqk$&HHQKKBHHQK Q5)* -  8)T)rc/nUHTup4n[[U5U5n[[U5U5n[U5HnURXg45 M MV U$)uConvert parsed GNUBG hint sub-moves to checker goals. Returns a list of (source_idx, dest_idx) pairs representing where each checker should START and where it should END UP. These are NOT individual die moves — compound moves like "24/14" become a single goal (24, 14). The bot resolves each goal into individual die steps at execution time using the game's legal move generator, which correctly handles bar-first rules, forced dice, and overshoot. )_linear_to_index _parse_linearr"r#) hint_submovescolorgoalssrc_strdst_strr=src_idxdst_idx_s r hint_to_goalsr^s^$&E#0%"=#95A"=#95AuA LL'+ ,$1 Lrc\SSKJn SSKJnJn U"U5nUbUVs/sH oU;dM UPM nnU(dUR 5 g0n UHUn U"XU 5HEn U R U R/5RU RU RU 45 MG MW U"X5S:n U (aU RS/5n U (dUR 5 g[U5HMununnUS:XdMU HunnnUU:XdMUU4X'SUSU3s s $ U SunnnUU4X'SUSU3s $ U SunnnSUSU3$[U5HununnUU:XaMU RU/5nU(dM,UHunnnUU:XdMUU4X'SUSU3s s $ SnS nUHAunnnUS :XaUS :XaS X'SUSU3s s $M%[UU- 5nUU:dM;UnUU4nMC UcMUSU4X'SUSSUS3s $ UR 5 gs snf) aKPick the next legal move that progresses toward a GNUBG goal. Examines the goal list and finds a legal move that advances a checker toward its target. Modifies `goals` in place (removes completed goals, updates source of in-progress goals). Returns an action string like "point_{src}_{dst}", or None if no goal can be progressed. r)generate_legal_moves) bar_countremaining_dice_uniqueNrrpoint_r]r)rr) movesr`r2rarbclear setdefaultsourcer# destinationgetr,abs)rXr2rW forced_dicer`rarb usable_dicedlegal_by_sourcedie_valrLon_bar bar_movesr4gsrcgdstrPrQdvmoves_from_srcbest best_distdists rresolve_next_actionrzs,7'.K"-B+Qk1Aq+ B  >@O%eGParse a GNUBG point string to linear position (bar=25, off=0).baroffr)rJ) point_strs rrUrU s"EE y>rc>US:XagUS::agUS:XaUS- $SU- $)uConvert a linear position to a board index. Linear space: bar=25, points 24→1, off=0 Board indices: bar=-1, points 0-23, off=24 Red: point N → index N-1 (point 1 = index 0) White: point N → index 24-N (point 1 = index 23) r}rrrrrr)posrWs rrTrTs1 by ax ~QwCxrc\rSrSrSrSrSrSSSjjrSSjrSSjr SSjr SS S jjr SS S jjr SS!S jjr SS!S jjrS"S#S jjr\S$Sj5r\S%Sj5rS&SjrS!SjrS'S(SjjrS)SjrS*SjrS+S,SjjrSS-SjjrS.SjrSSjrSrg)/ GnubgProcessi+aDManages a persistent gnubg-cli subprocess for move evaluation. Uses a persistent reader thread to consume stdout lines into a queue, since select() doesn't work with subprocess pipes on Windows. Commands are batched and sent together; only a single short idle wait is needed after the final command to collect all output. g?g?cSUl[R"5UlXlSUl[ R"5Ulg)NF) _proc threadingLock_lock_ply_startedqueueQueue _output_queue)selfplys r__init__GnubgProcess.__init__;s1.2 ^^%   6;kkmrc [5nU(dg[R"USSS/[R[R[RSSS9Ul[ R"5Ul[R"URSS9nUR5 URURS 9 URS UR 3S /5 URURS 9 SUl[$R'S UR 5 g![([*4a'n[$R-S U5 SUlSnAgSnAff=f)z4Start the GNUBG subprocess. Returns True on success.Fz-tz-rz-qTr)stdinstdoutstderrtextbufsize)targetdaemon) idle_waitz,set evaluation chequerplay evaluation plies znew gamez!GNUBG subprocess started (ply=%d)zFailed to start GNUBG: %sN)r subprocessPopenPIPEDEVNULLrrrrrThread _reader_loopstart_read_until_idle_STARTUP_IDLE_WAIT _send_batchrrrrOSErrorFileNotFoundErrorwarning)rexereaderes rrGnubgProcess.startBs"m #))dD$' oo!!)) DJ"'D %%T->->tLF LLN  ! !D,C,C ! D   B499+N   ! !D,C,C ! D DM HH8$)) D*+  KK3Q 7DJ sDD##E3EEcUR(aURR(aURRR5nU(dURR S5 gURR UR S55 UR(aURR(aMgggg![ [4a URR S5 gf=f)z9Persistent thread that reads stdout lines into the queue.Nz )rrreadlinerputr1 ValueErrorr)rrKs rrGnubgProcess._reader_loopgs )**!2!2zz((113&&**40""&&t{{6':; **!2!2!2*!2* G$ )    " "4 ( )sA2C5AC+C?>C?cUR UR(aqURRRS5 URRR 5 URR SS9 SUlSUlSSS5 g![ a/ URR5 N>![ a NKf=ff=f!,(df  g=f)zTerminate the subprocess.zquit rCtimeoutNF) rrrwriteflushwait Exceptionkillrrs rstopGnubgProcess.stopss ZZzzJJ$$**84JJ$$**,JJOOAO. " % Z ! )$ ZsMCA"BC C$C>C C C C CCC C#cVUR UR(aUR(d SSS5 gURXUSS9sSSS5 $![a8n[ R SU5 UR5 SnASSS5 gSnAff=f!,(df  g=f)zqGet the best move for the current position. Returns a list of (source_idx, dest_idx) pairs, or None on failure. NF pick_worstGNUBG query failed: %srrr _query_hintrrr_restartrr2rWrrs r get_best_moveGnubgProcess.get_best_movesZZ::T]]Z ''g%'P Z   4a8 Z   Z.$BA B&BBBB B(cVUR UR(aUR(d SSS5 gURXUSS9sSSS5 $![a8n[ R SU5 UR5 SnASSS5 gSnAff=f!,(df  g=f)zBGet the worst move (Whackgammon). Asks for many hints, picks last.NTrrrrs rget_worst_moveGnubgProcess.get_worst_movesZZ::T]]Z ''g$'O Z   4a8 Z   ZrcXUR UR(aUR(d SSS5 gURXU5sSSS5 $![a8n[ R SU5 UR5 SnASSS5 gSnAff=f!,(df  g=f)uvGet GNUBG's cube decision for the current position. Always queries from the on-roll player's perspective. Returns one of: "no-double" — should not double "too-good" — too good to double (would lose gammon value) "double-take" — should double, opponent should take "double-pass" — should double, opponent should drop None — on failure NzGNUBG cube query failed: %s)rrr _query_cuberrrrrs rget_cube_decisionGnubgProcess.get_cube_decisionszZZ::T]]Z ''g> Z   91= Z   Zs.$BA B &BBBB B)cUR UR(aUR(d SSS5 gURXU5nUH$nSU;dM UR 5s sSSS5 $ SSS5 g![ a8n[ RSU5 UR5 SnASSS5 gSnAff=f!,(df  g=f)znGet a human-readable cube hint string from GNUBG. Returns the "Proper cube action" line, or None on failure. NzProper cube actionzGNUBG cube hint failed: %s) rrr_setup_and_query_cuberGrrrr)rr2rWroutputrKrs rget_cube_hint_textGnubgProcess.get_cube_hint_textsZZ::T]]Z 33E'J"D+t3#zz|+Z #Z  8!< Z Zs:$CBB5B C &B>1C>CC Cc fUR UR(aUR(d SSS5 g[URUR 5VVs/sHupVU(aMUPM nnn[ U5S:a SSS5 gUR/URU5QSUSSUS3PSU3P5 URSUS 9n/n UHcn [RU 5n U (dM!U RU RS5S U RS5R535 Me U =(d SsSSS5 $s snnf![a8n [ R#S U 5 UR%5 Sn A SSS5 gSn A ff=f!,(df  g=f) ztGet ranked move hints as human-readable strings. Returns a list like ["1. 8/5 6/5", "2. 13/7"] or None on failure. NrB set dice r rhint c0[RU5SL$NrDrErKs r1GnubgProcess.get_move_hint_text..s!5T!Arrz. zGNUBG move hint failed: %s)rrrzipdice dice_usedr*r_position_commands_read_until_matchrDrEr#rFrGrrrr) rr2rW hint_countrrnu unused_dicerhintsrKrLrs rget_move_hint_textGnubgProcess.get_move_hint_textsZZ::T]]Z -0U__-MW-MTQUVq-M W{#a' Z  007#KN#31[^4DE |,//A#0 "D t,Aq  |2aggaj6F6F6H5I%JK#}$3ZX,  8!< ;Z4 5ZsT$F"#E E/E5EA'E."s:-=G ''-E+2EGrr)rrrr)rr2rWrs rr"GnubgProcess._setup_and_query_cubesj  ((/ $$U2   %% G&  rcURXU5nUHcnUR5nSU;aMSU;dSU;a SU;a g gSU;dSU;aS U;dS U;a g g S U;a g S U;dS U;dMc g 0nUHnUR5nURS5(a(SU;a"[ UR 5S5US'MQS UR5;a(SU;a"[ UR 5S5US 'MS UR5;dMSU;dM[ UR 5S5US 'M U(aOURSS5n URS S5n URS S5n [XU 5n X:XagX:Xag g g![ a GM4f=f![ [4a GMLf=f![ [4a GMdf=f)uLSend position to GNUBG and parse the cube evaluation. Returns one of: "no-double" — should not double "too-good" — too good to double (would lose gammon value) "double-take" — should double, opponent should take "double-pass" — should double, opponent should drop None — on failure rz no doublez no redoubleztoo goodztoo-goodz no-doubledoubleredoublepassdropz double-passz double-taketakerrrDoubleiN) rrrGrfloatsplitr IndexErrorrjr$) rr2rWrrrKlowequitiesline_snddtdprws rrGnubgProcess._query_cube's++E'BD**,C#3.c!]c%9$%"3*"3S=FcM($}$}# $&&(DZZ\F  &&;&+@,1&,,.2D,EH[)6<<>)h&.@.3FLLN24F.GH]+6<<>)h&.@.3FLLN24F.GH]+$ k40BmT2BmT2Brr?Dz"z$ 1" #J/ #J/s60F&,F8,G& F54F58G  G G%$G%c[URUR5VVs/sHupVU(aMUPM nnn[U5S:a&U(a USnXU/nO[R S5 gU(aSOSnUR /URU5QSUSSUS3PS U3P5 URS US 9n [R S [U 55 Sn Sn U Hn [U 5n U (dMU cU n U n M U(aU OU nU(a#[X5n[R S U5 U$[R S5 gs snnf)zSend position to GNUBG and parse the hint response. Returns a list of checker goals as (source_idx, dest_idx) pairs. These are final destinations, not individual die steps. rBrz#GNUBG query skipped: no unused diceNrdrrrrc0[RU5SL$rrrs rr*GnubgProcess._query_hint..s-T9rrzGNUBG hint response: %d lineszGNUBG goals: %sz!GNUBG: no hint parsed from output) rrrr*rdebugrrrrRr^)rr2rWrrrnrrrr last_submovesfirst_submovesrKrNchosenrXs rrGnubgProcess._query_hintlsf&)U__%EO%ETQQq%E O { a N f  ?@&SA   ((/ KN+1[^,<=  |$  '' 9(  13v;? D&t,Hx!)%-N ( #-. !&0E II' /L 56OPs EEcUR(aiURR(aMURRRUS-5 URRR5 ggg)zSend a single command to GNUBG. N)rrrr)rcommands r_sendGnubgProcess._sendsN ::$**** JJ   " "7T> 2 JJ   " " $+:rcUR(a|URR(a`URRRSRSU555 URRR 5 ggg)zSend multiple commands to GNUBG at once. All commands are written before flushing, so GNUBG processes them back-to-back with no idle gaps between them. c3*# UH oS-v M g7f)rNr).0cmds r +GnubgProcess._send_batch..s*J#:sN)rrrjoinr)rcommandss rrGnubgProcess._send_batchs[ ::$**** JJ   " "277*J*J#J K JJ   " " $+:rNcSSKnUc URn/nUR5U-nUR5U:anXSR5- n[X&5nURR [ SU5S9nUcU$URU5 UR5U:aMnU$![Ra U(aU$N8f=f)zRead GNUBG output from the queue until idle. GNUBG is considered idle when no new output arrives for `idle_wait` seconds after receiving at least one line. Use only for startup/setup where there's no specific pattern to wait for. rN{Gz?r) time _IDLE_WAIT monotonicminrrjr$r#rEmpty) rrrr$linesdeadline remaining wait_timeitems rrGnubgProcess._read_until_idles   I>>#g-nn) >>#33II1I ))--c$ 6J-K<   T"nn) ;;   s&B-B--C CcSSKn/nUR5U-nUR5U:aXSR5- nURR[ SU5S9nUcU$UR U5 U"U5(aUR U5 U$UR5U:aMU$![Ra N.f=f)uRead GNUBG output until a line matches the predicate. Returns all lines read (including the match). This is the correct way to wait for query results — it doesn't depend on idle timing, so it works regardless of how long GNUBG takes to compute. rNr#r) r$r&rrjr$r# _drain_quickrr()r predicaterr$r)r*r+r-s rrGnubgProcess._read_until_matchs >>#g-nn) >>#33I ))--c$ 6J-K<  T"T??%%e, #nn) ;;  s&B5*/B55C  C cfSSKnUR5UR-nUR5U:abX2R5- nURR [ SU5S9nUcgUR U5 UR5U:aMagg![Ra gf=f)zDrain any output that arrives quickly after a match. After seeing the first hint line, there may be more (equity details, additional hints for pick_worst). Grab them without a long wait. rNgMbP?r) r$r&r%rrjr$r#rr()rr)r$r*r+r-s rr0GnubgProcess._drain_quicks >>#doo5nn) >>#33I ))--c%6K-L< T" nn);;  s &B0BB0/B0c[RS5 UR(a"URR5 SUlSUlUR 5 g![a N+f=f)z Kill and restart the subprocess.zRestarting GNUBG subprocessNF)rrrrrrrrs rrGnubgProcess._restart sV ./ ::  !DJ    sA!! A.-A.)rrrrr)r)rrJreturnbool)r8None)@)r2rrWstrrrr8list[tuple[int, int]] | None)r2rrWr<rrr8 str | None)rCr;) r2rrWr<rrJrrr8zlist[str] | None)r2rr8 list[str])r2rrWr<r8r?)r2rrWr<rrr8r?)F) r2rrWr<rrrr9r8r=)rr<r8r:)r r?r8r:)r;N)rrrz float | Noner8r?)r1zCallable[[str], bool]rrr8r?)r)r?r8r:)__name__ __module__ __qualname____firstlineno____doc__r%rrrrrrrrrr staticmethodrrrrrrrrrr0r__static_attributes__rrrrr+s<JD#J )&*HK(14?D %$HK ( 14 ?D  % HK(14?D .HK(14?D 2 ("(( (  (  (\     "      (C"CC C  CT! 3"33 3  3 & 3r% %"&   H(  @& rr)r8r>r7)r2rr8r<)rKr<r8z!list[tuple[str, str, int]] | None)rVzlist[tuple[str, str, int]]rWr<r8list[tuple[int, int]]r) rXrGr2z'BackgammonGameState'rWr<rlzlist[int] | Noner8r>)rr<r8rJ)rrJrWr<r8rJ) rD __future__rr-loggingrrer rrtypingrrr2r getLoggerr@rr__annotations__rrr@compilerDrHrRr^rzrUrTrrrrrOs #  ** ! K ;JF ::5  jj=> *(- 4%) ^ ^ ^ ^" ^  ^B0hhr