← Files Critical Thinking CoachARCHIVED FILE

skills/instructions/scripts/session_controller.py

10.8 KB · Nov 21, 2026 · 12:50 UTC

↓ Download file

See the change to this file →

"""Local PHIL 205 scheduling/difficulty/generation bookkeeping, not a grading engine.

No network or persistent learner store. Optional host execution only.
It schedules verdict, focal target, operation family, and surface-form dimensions.
Semantic prompt audits and student evaluation remain the Coach's responsibility.
"""
from __future__ import annotations
import copy, json, random, secrets, sys
from pathlib import Path
from typing import Any

LEVELS=('easier','ordinary','challenging')
CONFIG=json.loads((Path(__file__).resolve().parents[1]/'lookup'/'course-config.json').read_text())

def _check_scope(mode:str,target:int)->list[int]:
    if mode not in ('target-specific','integrated'): raise ValueError('Mode must be target-specific or integrated.')
    if isinstance(target,bool) or target not in CONFIG['active_target_ids']: raise ValueError('Target is not active in this release.')
    return [target] if mode=='target-specific' else [n for n in CONFIG['active_target_ids'] if n<=target]

def _rng(s:dict[str,Any])->random.Random:
    r=random.Random(f"{s['seed']}:{s['draw_index']}"); s['draw_index']+=1; return r

def _reset_streaks(s):
    s['success_streak']=s['miss_streak']=0; s['pending_choice']=None; s['dismissed_level_suggestion']=None

def new_state(mode:str,target:int,*,seed:int|None=None)->dict[str,Any]:
    included=_check_scope(mode,target)
    return {'schema_version':3,'release':CONFIG['release_version'],'seed':secrets.randbits(128) if seed is None else seed,
            'draw_index':0,'mode':mode,'target':target,'included':included,'level':'ordinary','explicit_level':False,
            'success_streak':0,'miss_streak':0,'challenge_declined':False,'pending_choice':None,
            'dismissed_level_suggestion':None,'generated_count':0,'previous_sufficient':False,
            'verdict_queue':[],'target_queue':[],'family_queues':{},'t6_mode_queue':[],'t6_supplied_successes':0,
            'last_target':None,'target_run':0,'recent_dimensions':[],'pending_case':None,'history':[]}

def change_scope(s,mode,target):
    included=_check_scope(mode,target)
    if s['pending_case'] is not None: raise ValueError('Finish or skip pending case before changing scope.')
    s.update(mode=mode,target=target,included=included,target_queue=[],family_queues={},t6_mode_queue=[],last_target=None,target_run=0,recent_dimensions=[])
    _reset_streaks(s)
    if not s['explicit_level']: s['level']='ordinary'

def choose_level(s,level,*,explicit=True):
    if level not in LEVELS: raise ValueError('Unknown difficulty level.')
    if s['pending_case'] is not None: raise ValueError('Apply difficulty change after pending case.')
    s.update(level=level,explicit_level=explicit); _reset_streaks(s)

def _new_verdict_batch(s):
    r=_rng(s); length=r.choice(CONFIG['scheduling']['verdict_batch_lengths']); k=int(length*CONFIG['scheduling']['sufficient_fraction'])
    start=1 if s['generated_count']==0 or s['previous_sufficient'] else 0
    available=length-start; compressed=sorted(r.sample(range(available-k+1),k)); indices={start+v+i for i,v in enumerate(compressed)}
    s['verdict_queue']=['sufficient' if i in indices else 'unsettled' for i in range(length)]

def _max_run(seq,last,run):
    largest=run
    for t in seq:
        run=run+1 if t==last else 1; last=t; largest=max(largest,run)
    return largest

def _new_target_batch(s):
    if len(s['included'])==1: s['target_queue']=s['included']*5; return
    r=_rng(s); copies=r.choice(CONFIG['scheduling']['target_copies_per_batch']); pool=s['included']*copies
    for _ in range(10000):
        r.shuffle(pool)
        if _max_run(pool,s['last_target'],s['target_run'])<=3: s['target_queue']=pool.copy(); return
    raise RuntimeError('Could not draw target batch.')

def _new_family_batch(s,target):
    r=_rng(s); base=list(CONFIG['generation']['families'][str(target)])
    # Repeat to provide a larger queue while preserving configured weights.
    pool=base*r.choice([2,3,4]); r.shuffle(pool); s['family_queues'][str(target)]=pool

def _choose_dimension(s,key):
    values=CONFIG['generation'][key]; r=_rng(s)
    recent=[d.get(key) for d in s['recent_dimensions'][-3:]]
    candidates=[v for v in values if recent.count(v)<2] or values
    return r.choice(candidates)

def _new_t6_mode_batch(s):
    r=_rng(s); base=list(CONFIG['generation']['target6_unsettled_prompt_modes'])
    pool=base*r.choice([2,3,4])
    # Shuffle until the task form does not form a long mechanical run.
    for _ in range(1000):
        r.shuffle(pool)
        if _max_run(pool,None,0)<=2:
            s['t6_mode_queue']=pool.copy(); return
    s['t6_mode_queue']=pool.copy()

def _t6_scaffold_unlocked(s):
    required=CONFIG['generation']['target6_scaffold']['required_independent_successes']
    return s.get('t6_supplied_successes',0)>=required

def _next_t6_mode(s):
    if not _t6_scaffold_unlocked(s):
        return CONFIG['generation']['target6_scaffold']['initial_mode']
    if not s['t6_mode_queue']: _new_t6_mode_batch(s)
    return s['t6_mode_queue'].pop(0)

def next_plan(s):
    if s['pending_case'] is not None: return copy.deepcopy(s['pending_case'])
    if s['pending_choice'] is not None: raise ValueError('Resolve pending difficulty choice.')
    if not s['verdict_queue']: _new_verdict_batch(s)
    if not s['target_queue']: _new_target_batch(s)
    verdict=s['verdict_queue'].pop(0); focal=s['target_queue'].pop(0)
    fq=s['family_queues'].get(str(focal),[])
    if not fq: _new_family_batch(s,focal); fq=s['family_queues'][str(focal)]
    family=fq.pop(0)
    plan={'number':s['generated_count']+1,'focal_target':focal,'verdict':verdict,'level':s['level'],
          'operation_family':family,'surface_forms':_choose_dimension(s,'surface_forms'),
          'evidence_forms':_choose_dimension(s,'evidence_forms'),'conclusion_forms':_choose_dimension(s,'conclusion_forms'),
          'focused_followups':0}
    if focal==6:
        if verdict=='unsettled':
            plan['causal_task_mode']=_next_t6_mode(s)
        elif not _t6_scaffold_unlocked(s):
            plan['causal_task_mode']='two-rivals-supplied-sufficient'
        else:
            plan['causal_task_mode']='sufficient'
    s['generated_count']+=1; s['previous_sufficient']=verdict=='sufficient'
    s['target_run']=s['target_run']+1 if focal==s['last_target'] else 1; s['last_target']=focal
    s['pending_case']=plan; return copy.deepcopy(plan)

def add_followup(s):
    p=s['pending_case']
    if p is None: raise ValueError('No pending case.')
    if p['focused_followups']>=CONFIG['difficulty']['max_focused_followups']: raise ValueError('Follow-up ceiling reached.')
    p['focused_followups']+=1; return p['focused_followups']

def register_dimensions(s,*,salient_cues=None,reasoning_route=None,hinge_location=None):
    p=s['pending_case']
    if p is None: raise ValueError('No pending case.')
    record={k:p.get(k) for k in ('focal_target','operation_family','surface_forms','evidence_forms','conclusion_forms')}
    record.update(salient_cues=salient_cues or [],reasoning_route=reasoning_route,hinge_location=hinge_location)
    s['recent_dimensions'].append(record); s['recent_dimensions']=s['recent_dimensions'][-CONFIG['generation']['max_recent_fingerprints']:]
    return record

def _adjustment(s,to_level,why):
    if s['explicit_level']:
        key=f"{s['level']}->{to_level}"
        if s['dismissed_level_suggestion']==key: return {'kind':'continue','level':s['level']}
        result={'kind':'suggest','to_level':to_level,'reason':why,'key':key}; s['pending_choice']=result; return result
    s['level']=to_level; _reset_streaks(s); return {'kind':'changed','level':to_level,'reason':why}

def finish_case(s,*,independent_correct=False,assisted=False,defective=False,skipped=False,followups_were_unnecessary=False):
    p=s['pending_case']
    if p is None: raise ValueError('No pending case.')
    assisted=assisted or (p['focused_followups']>0 and not followups_were_unnecessary)
    success=independent_correct and not assisted
    rec={**p,'independent_correct':success if not(defective or skipped) else None,'assisted':assisted,'defective':defective,'skipped':skipped}
    s['history'].append(rec); s['pending_case']=None
    if defective: return {'kind':'excluded_defective','level':s['level']}
    if skipped: _reset_streaks(s); return {'kind':'unscored_skip','level':s['level']}
    if success and p.get('focal_target')==6 and p.get('verdict')=='unsettled' and p.get('causal_task_mode')=='two-rivals-supplied':
        required=CONFIG['generation']['target6_scaffold']['required_independent_successes']
        s['t6_supplied_successes']=min(required,s.get('t6_supplied_successes',0)+1)
        if s['t6_supplied_successes']>=required:
            s['t6_mode_queue']=[]
    if success: s['success_streak']+=1; s['miss_streak']=0
    else: s['miss_streak']+=1; s['success_streak']=0
    d=CONFIG['difficulty']
    if s['miss_streak']>=d['misses_to_step_down']:
        if s['level']=='challenging': return _adjustment(s,'ordinary','three_independent_misses')
        if s['level']=='ordinary': return _adjustment(s,'easier','three_independent_misses')
    if s['level']=='easier' and s['success_streak']>=d['easier_successes_to_return']: return _adjustment(s,'ordinary','three_independent_successes')
    if s['level']=='ordinary' and s['success_streak']>=d['ordinary_successes_to_offer_challenge'] and not s['challenge_declined']:
        result={'kind':'offer_challenging','to_level':'challenging','reason':'six_independent_successes'}; s['pending_choice']=result; return result
    return {'kind':'continue','level':s['level']}

def answer_choice(s,accept):
    choice=s['pending_choice']
    if choice is None: raise ValueError('No pending difficulty choice.')
    if accept: s['level']=choice['to_level']; _reset_streaks(s); return {'kind':'changed','level':s['level']}
    if choice['kind']=='offer_challenging': s['challenge_declined']=True
    else: s['dismissed_level_suggestion']=choice['key']
    s['pending_choice']=None; return {'kind':'continue','level':s['level']}

def dispatch(req):
    if req['action']=='start': return {'state':new_state(req['mode'],req['target'],seed=req.get('seed'))}
    s=copy.deepcopy(req['state']); action=req['action']; result=None
    if action=='next': result=next_plan(s)
    elif action=='followup': result=add_followup(s)
    elif action=='register': result=register_dimensions(s,**req.get('dimensions',{}))
    elif action=='finish': result=finish_case(s,**req.get('result',{}))
    elif action=='scope': change_scope(s,req['mode'],req['target'])
    elif action=='level': choose_level(s,req['level'],explicit=req.get('explicit',True))
    elif action=='choice': result=answer_choice(s,req['accept'])
    else: raise ValueError('Unknown action.')
    return {'state':s,'result':result}

if __name__=='__main__':
    try: print(json.dumps(dispatch(json.load(sys.stdin)),ensure_ascii=False))
    except (ValueError,TypeError,KeyError,RuntimeError) as exc:
        print(json.dumps({'error':str(exc)})); sys.exit(2)

SHA-256: d17929914056bf5648118ba446708cf500216050cf4e06c632bf6fd39de0f09f