dhrona 0.1.1__py3-none-any.whl

dhrona/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

dhrona/_modidx.py

@@ -0,0 +1,63 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/drona',
+                'doc_host': 'https://Karthik777.github.io',
+                'git_url': 'https://github.com/Karthik777/drona',
+                'lib_path': 'dhrona'},
+  'syms': { 'dhrona.core': { 'dhrona.core.Assessment': ('core.html#assessment', 'dhrona/core.py'),
+                             'dhrona.core.Finding': ('core.html#finding', 'dhrona/core.py'),
+                             'dhrona.core._failure_findings': ('core.html#_failure_findings', 'dhrona/core.py'),
+                             'dhrona.core._failure_key': ('core.html#_failure_key', 'dhrona/core.py'),
+                             'dhrona.core._first_research_finding': ('core.html#_first_research_finding', 'dhrona/core.py'),
+                             'dhrona.core._is_fossick_repo': ('core.html#_is_fossick_repo', 'dhrona/core.py'),
+                             'dhrona.core._loads': ('core.html#_loads', 'dhrona/core.py'),
+                             'dhrona.core._segments': ('core.html#_segments', 'dhrona/core.py'),
+                             'dhrona.core._tc': ('core.html#_tc', 'dhrona/core.py'),
+                             'dhrona.core._tool_name': ('core.html#_tool_name', 'dhrona/core.py'),
+                             'dhrona.core.as_tools': ('core.html#as_tools', 'dhrona/core.py'),
+                             'dhrona.core.assess_history': ('core.html#assess_history', 'dhrona/core.py'),
+                             'dhrona.core.assess_turn': ('core.html#assess_turn', 'dhrona/core.py'),
+                             'dhrona.core.bypass_tool': ('core.html#bypass_tool', 'dhrona/core.py'),
+                             'dhrona.core.call_valid': ('core.html#call_valid', 'dhrona/core.py'),
+                             'dhrona.core.completion_valid': ('core.html#completion_valid', 'dhrona/core.py'),
+                             'dhrona.core.dhrona_version': ('core.html#dhrona_version', 'dhrona/core.py'),
+                             'dhrona.core.load_rounds': ('core.html#load_rounds', 'dhrona/core.py'),
+                             'dhrona.core.main': ('core.html#main', 'dhrona/core.py'),
+                             'dhrona.core.prepare_chat': ('core.html#prepare_chat', 'dhrona/core.py'),
+                             'dhrona.core.read_history': ('core.html#read_history', 'dhrona/core.py'),
+                             'dhrona.core.receipt_path': ('core.html#receipt_path', 'dhrona/core.py'),
+                             'dhrona.core.register_completion': ('core.html#register_completion', 'dhrona/core.py'),
+                             'dhrona.core.round_calls': ('core.html#round_calls', 'dhrona/core.py'),
+                             'dhrona.core.round_msgs': ('core.html#round_msgs', 'dhrona/core.py'),
+                             'dhrona.core.round_valid': ('core.html#round_valid', 'dhrona/core.py'),
+                             'dhrona.core.tool_args': ('core.html#tool_args', 'dhrona/core.py'),
+                             'dhrona.core.warm_start': ('core.html#warm_start', 'dhrona/core.py')},
+            'dhrona.rounds': { 'dhrona.rounds._add_review': ('rounds.html#_add_review', 'dhrona/rounds.py'),
+                               'dhrona.rounds._history_dicts': ('rounds.html#_history_dicts', 'dhrona/rounds.py'),
+                               'dhrona.rounds._part_dict': ('rounds.html#_part_dict', 'dhrona/rounds.py'),
+                               'dhrona.rounds._print_commands': ('rounds.html#_print_commands', 'dhrona/rounds.py'),
+                               'dhrona.rounds._prompts': ('rounds.html#_prompts', 'dhrona/rounds.py'),
+                               'dhrona.rounds._turn_msgs': ('rounds.html#_turn_msgs', 'dhrona/rounds.py'),
+                               'dhrona.rounds._write_dlg': ('rounds.html#_write_dlg', 'dhrona/rounds.py'),
+                               'dhrona.rounds.accept': ('rounds.html#accept', 'dhrona/rounds.py'),
+                               'dhrona.rounds.accept_cli': ('rounds.html#accept_cli', 'dhrona/rounds.py'),
+                               'dhrona.rounds.bootstrap_prompt': ('rounds.html#bootstrap_prompt', 'dhrona/rounds.py'),
+                               'dhrona.rounds.capture': ('rounds.html#capture', 'dhrona/rounds.py'),
+                               'dhrona.rounds.capture_cli': ('rounds.html#capture_cli', 'dhrona/rounds.py'),
+                               'dhrona.rounds.clean_dialog': ('rounds.html#clean_dialog', 'dhrona/rounds.py'),
+                               'dhrona.rounds.compiled_history': ('rounds.html#compiled_history', 'dhrona/rounds.py'),
+                               'dhrona.rounds.latest_session': ('rounds.html#latest_session', 'dhrona/rounds.py'),
+                               'dhrona.rounds.read_dialog': ('rounds.html#read_dialog', 'dhrona/rounds.py'),
+                               'dhrona.rounds.start_cli': ('rounds.html#start_cli', 'dhrona/rounds.py'),
+                               'dhrona.rounds.start_commands': ('rounds.html#start_commands', 'dhrona/rounds.py'),
+                               'dhrona.rounds.start_round': ('rounds.html#start_round', 'dhrona/rounds.py')},
+            'dhrona.sessions': { 'dhrona.sessions.export_cli': ('sessions.html#export_cli', 'dhrona/sessions.py'),
+                                 'dhrona.sessions.export_session': ('sessions.html#export_session', 'dhrona/sessions.py'),
+                                 'dhrona.sessions.import_cli': ('sessions.html#import_cli', 'dhrona/sessions.py'),
+                                 'dhrona.sessions.import_session': ('sessions.html#import_session', 'dhrona/sessions.py')},
+            'dhrona.tools': { 'dhrona.tools._detail_key': ('tools.html#_detail_key', 'dhrona/tools.py'),
+                              'dhrona.tools._epoch': ('tools.html#_epoch', 'dhrona/tools.py'),
+                              'dhrona.tools.fmt_report': ('tools.html#fmt_report', 'dhrona/tools.py'),
+                              'dhrona.tools.tool_report': ('tools.html#tool_report', 'dhrona/tools.py'),
+                              'dhrona.tools.tools_cli': ('tools.html#tools_cli', 'dhrona/tools.py')}}}

dhrona/core.py

@@ -0,0 +1,223 @@
+"""Assess Ramabana tool routes and build a Urai warm-start history.
+
+Docs: https://Karthik777.github.io/drona/core.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_core.ipynb.
+
+# %% auto #0
+__all__ = ['RAMABANA_HISTORY', 'SHELL_TOOLS', 'ROUND_REVISION', 'ROUNDS_DIR', 'SEEDS_DIR', 'Finding', 'Assessment',
+           'read_history', 'tool_args', 'bypass_tool', 'assess_turn', 'assess_history', 'call_valid', 'as_tools',
+           'round_calls', 'round_valid', 'load_rounds', 'round_msgs', 'warm_start', 'dhrona_version', 'receipt_path',
+           'register_completion', 'completion_valid', 'prepare_chat', 'main']
+
+# %% ../nbs/00_core.ipynb #d04693b6
+from dataclasses import dataclass, asdict
+import json, re, sys, time, uuid, inspect, functools
+from fastcore.basics import ifnone
+from fastcore.xtras import Path
+from fastcore.script import call_parse
+from fastcore.xdg import xdg_state_home, xdg_config_home
+from fastcore.foundation import L
+from urai import ToolCall, mk_tool_res_msg
+import dhrona
+
+# %% ../nbs/00_core.ipynb #2edea58c
+@dataclass(frozen=True)
+class Finding:
+    "One tool-route problem in a recorded turn."
+    kind: str
+    tool: str
+    index: int
+    message: str
+
+@dataclass(frozen=True)
+class Assessment:
+    "The route score and findings for one or more turns."
+    score: int
+    calls: int
+    findings: tuple[Finding, ...]
+
+# %% ../nbs/00_core.ipynb #8e5631ea
+RAMABANA_HISTORY = Path.home()/'.config/ramabana/agent-history.jsonl'
+
+def _loads(s):
+    try: return json.loads(s)
+    except (json.JSONDecodeError, TypeError): return None
+
+def read_history(
+    path=RAMABANA_HISTORY, # Ramabana `agent-history.jsonl` path
+    session=None,         # optional session id
+):
+    "Read completed Ramabana turns in append order, skipping partial lines."
+    r = L(Path(path).expanduser().readlines()).map(_loads).filter(lambda x: isinstance(x, dict))
+    return r if not session else r.filter(lambda x: x.get('session')==session)
+
+def tool_args(action):
+    "The call arguments of `action` as a dict."
+    a = action.get('args')
+    if isinstance(a, str): a = _loads(a)
+    return a if isinstance(a, dict) else {}
+
+# %% ../nbs/00_core.ipynb #cf182995
+_RESEARCH_TOOLS = {'web_search', 'read_url', 'search_code', 'run_shell'}
+_SCHEMA_ERRS = ('could not parse commands', 'JSONDecodeError', 'JSON decoder')
+SHELL_TOOLS = (
+    (r'git\s+status\b', 'git_status'), (r'git\s+diff\b', 'git_diff'), (r'git\s+(log|show)\b', 'git_log'),
+    (r'git\s+commit\b', 'git_commit'), (r'git\s+(checkout|switch)\b', 'git_checkout'), (r'git\s+stash\b', 'git_stash'),
+    (r'git\s+(push|pull|fetch)\b', 'git_remote'), (r'(rg|grep|ag)\b', 'grep'), (r'(find|fd)\b', 'ls'), (r'(ls|tree)\b', 'ls'),
+    (r'(sed|perl)\s+-p?i\b', 'replace_text'), (r'(cat\s*>|tee\b)', 'create_file'), (r'sed\s+-n\b|(cat|head|tail|nl)\b', 'view_file'),
+    (r'(curl|wget)\b', 'read_url'))
+_PREFIX = re.compile(r'^(env(\s+-u\s+\S+|\s+\w+=\S+)*\s+|(\w+=\S+\s+)+)')
+_GIT_OPTS = re.compile(r'^git\s+((-[Cc]\s+\S+|--\S+)\s+)+')
+
+def _segments(command):
+    for s in re.split(r'&&|;|\|\|', command):
+        s = _GIT_OPTS.sub('git ', _PREFIX.sub('', s.strip()))
+        if s and not s.startswith('cd '): yield s.split('|')[0].strip()
+
+def bypass_tool(command, offered=None):
+    "The dedicated tool `command` stands in for, if any."
+    if not command: return None
+    if re.search(r'&\s*$', command.strip()) and not command.strip().endswith('&&'): hit = 'run_shell_bg'
+    else: hit = next((t for s in _segments(command) for rx,t in SHELL_TOOLS if re.match(rx, s)), None)
+    return hit if hit and (offered is None or hit in offered) else None
+
+def _is_fossick_repo(action):
+    text = ' '.join(str(v) for v in tool_args(action).values())
+    return action.get('tool') == 'run_shell' and 'fossick read-gh-repo' in text
+
+def _first_research_finding(prompt, activities):
+    if 'github' not in prompt.lower() or 'fossick' not in prompt.lower(): return None
+    research = ((i, action) for i, action in enumerate(activities) if action.get('tool') in _RESEARCH_TOOLS)
+    index, action = next(research, (None, None))
+    if action is None or _is_fossick_repo(action): return None
+    return Finding('route', action.get('tool', ''), index, 'Use fossick read-gh-repo as the first repository research call.')
+
+def _failure_key(action): return (action.get('tool', ''), json.dumps(tool_args(action), sort_keys=True, default=str))
+
+def _failure_findings(index, action, failed):
+    if action.get('ok') is not False: return ()
+    tool, detail, findings = action.get('tool', ''), str(action.get('detail', '')), []
+    key = _failure_key(action)
+    if key in failed: findings.append(Finding('repeat_failure', tool, index, 'Diagnose or change route before repeating a failed call.'))
+    failed.add(key)
+    if any(s in detail for s in _SCHEMA_ERRS):
+        findings.append(Finding('schema', tool, index, 'Send arguments that match the tool schema exactly.'))
+    if tool == 'run_shell' and ('usage:' in detail or 'unrecognized arguments' in detail):
+        findings.append(Finding('tool_protocol', tool, index, 'Read the project command contract before retrying.'))
+    return tuple(findings)
+
+def assess_turn(turn):
+    "Assess the tool route recorded in one Ramabana turn."
+    activities, findings, failed, bypassed = turn.get('activity') or [], [], set(), set()
+    route_finding = _first_research_finding(turn.get('prompt', ''), activities)
+    if route_finding: findings.append(route_finding)
+    for ind, a in enumerate(activities):
+        if a.get('tool') == 'run_shell' and (t := bypass_tool(str(tool_args(a).get('command', '')))) and t not in bypassed:
+            bypassed.add(t); findings.append(Finding('bypass', 'run_shell', ind, f'Use {t} instead of run_shell for this.'))
+        findings.extend(_failure_findings(ind, a, failed))
+    return Assessment(max(0, 100 - 20*len(findings)), len(activities), tuple(findings))
+
+def assess_history(turns):
+    "Assess several turns as one route corpus."
+    assessments = [assess_turn(t) for t in turns]
+    findings = tuple(f for a in assessments for f in a.findings)
+    return Assessment(max(0, 100 - 20*len(findings)), sum(a.calls for a in assessments), findings)
+
+# %% ../nbs/00_core.ipynb #2d9bf58b
+ROUND_REVISION = 1
+ROUNDS_DIR = xdg_config_home()/'dhrona/rounds'
+SEEDS_DIR = Path(dhrona.__file__).parent/'seeds'
+
+def call_valid(args, fn):
+    "Would `fn` accept `args` as keyword arguments?"
+    try: inspect.signature(fn).bind(**args); return True
+    except (TypeError, ValueError): return False
+
+def _tool_name(f):
+    if isinstance(f, str): return f
+    if isinstance(f, functools.partial): return _tool_name(f.func)
+    if callable(f): return getattr(f, '__name__', type(f).__name__)
+    raise TypeError('tools must be tool callables, names, or a name→callable dict')
+
+def as_tools(tools):
+    "Tools keyed by name, from a dict or an iterable of callables, partials, or names (a name maps to `None`)."
+    return dict(tools) if isinstance(tools, dict) else {_tool_name(f): None if isinstance(f, str) else f for f in tools}
+
+def round_calls(rnd):
+    "The `(tool, arguments)` pairs an accepted round makes."
+    return [(p['name'], p.get('arguments') or {}) for m in rnd['history'] for p in m['content'] if p['type']=='tool_use']
+
+def round_valid(rnd, tools):
+    "Do all of `rnd`'s calls bind to `tools`? A `None` tool checks the name only."
+    return all(n in tools and (tools[n] is None or call_valid(a, tools[n])) for n,a in round_calls(rnd))
+
+def load_rounds(dirs=None):
+    "Accepted rounds from the library and packaged seeds, skipping unreadable files."
+    rs = [_loads(p.read_text()) for d in ifnone(dirs, [ROUNDS_DIR, SEEDS_DIR]) for p in sorted(Path(d).glob('*.json'))]
+    return [r for r in rs if isinstance(r, dict) and r.get('meta', {}).get('status')=='accepted']
+
+def _tc(p): return ToolCall(p['name'], p.get('arguments') or {}, **({'id': p['id']} if p.get('id') else {}))
+
+def round_msgs(rnd):
+    "Canonical Urai messages from an accepted round."
+    res, tcs = [], {}
+    for m in rnd['history']:
+        parts = m['content']
+        if m['role']=='tool':
+            res += [mk_tool_res_msg(tcs.get(p.get('id')) or _tc(p), p.get('text', '')) for p in parts if p['type']=='tool_result']
+            continue
+        msg = {'role': m['role'], 'content': '\n'.join(p['text'] for p in parts if p['type']=='text' and p.get('text'))}
+        if calls := [_tc(p) for p in parts if p['type']=='tool_use']:
+            tcs.update({tc['id']: tc for tc in calls}); msg['tool_calls'] = calls
+        res.append(msg)
+    return res
+
+def warm_start(tools=None, model=None, limit=2, dirs=None):
+    "Canonical Urai history from accepted rounds that fit the offered tools."
+    rs = load_rounds(dirs)
+    if tools is not None:
+        tools = as_tools(tools)
+        rs = [r for r in rs if round_valid(r, tools)]
+    rs = sorted(rs, key=lambda r: r['meta'].get('model') != model)[:limit]
+    return [m for r in rs for m in round_msgs(r)]
+
+def dhrona_version():
+    "The warm-start revision."
+    return f'{dhrona.__version__}:{ROUND_REVISION}'
+
+def receipt_path(state=None):
+    "The completion receipt file."
+    return Path(state) if state else xdg_state_home()/'dhrona/completions.json'
+
+def register_completion(state=None):
+    "Record one clean round and return its completion id."
+    path, cid = receipt_path(state), uuid.uuid4().hex
+    records = path.read_json() if path.exists() else {}
+    records[cid] = {'version': dhrona_version(), 'at': time.time()}
+    path.write_json(records, indent=2)
+    return cid
+
+def completion_valid(cid, state=None):
+    "Does `cid` name a completion for the current round?"
+    path = receipt_path(state)
+    if not cid or not path.exists(): return False
+    return (path.read_json().get(cid) or {}).get('version') == dhrona_version()
+
+def prepare_chat(chat, tools=None, model=None):
+    "Prepend the Dhrona warm start to an empty Urai-compatible chat."
+    if chat.hist: raise ValueError('Dhrona prepares an empty chat only')
+    chat.hist = chat.fmt2hist(warm_start(tools, model))
+    if hasattr(chat, '_recreate_conv'): chat._recreate_conv()
+    return chat
+
+# %% ../nbs/00_core.ipynb #f4e8294d
+@call_parse
+def main(
+    history: str=str(RAMABANA_HISTORY), # Ramabana history path
+    session: str=None,                  # optional session id
+):
+    "Assess persisted Ramabana tool routes."
+    if not Path(history).expanduser().exists(): sys.exit(f'No history at {history}')
+    a = assess_history(read_history(history, session))
+    print(json.dumps({'score': a.score, 'calls': a.calls, 'findings': [asdict(f) for f in a.findings]}, indent=2))

dhrona/rounds.py

@@ -0,0 +1,186 @@
+"""Capture, review, accept, and start curated tool-use rounds.
+
+Docs: https://Karthik777.github.io/drona/rounds.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/01_rounds.ipynb.
+
+# %% auto #0
+__all__ = ['REVIEW_KEY', 'read_dialog', 'clean_dialog', 'latest_session', 'capture', 'compiled_history', 'accept',
+           'bootstrap_prompt', 'start_commands', 'start_round', 'capture_cli', 'accept_cli', 'start_cli']
+
+# %% ../nbs/01_rounds.ipynb #af82ef79
+from dataclasses import asdict
+from fastcore.xtras import Path
+import json, shlex, subprocess
+from aidialog.dialog import Dialog, snote, sprompt
+from aidialog.hist import chat2dlg, dlg2chat
+from aidialog.ipynb import read_ipynb, write_ipynb
+from aidialog.msg_parts import Msg, Text, ToolUse, ToolResult
+from fastcore.script import call_parse
+from .core import RAMABANA_HISTORY, ROUNDS_DIR, assess_history, dhrona_version, read_history
+
+# %% ../nbs/01_rounds.ipynb #d4f6b8c0
+REVIEW_KEY = 'dhrona'
+
+def read_dialog(source):
+    "Read a Dhrona dialog notebook."
+    if not (dlg := read_ipynb(source)): raise ValueError(f'Could not read dialog {source}')
+    return dlg
+
+def _prompts(dlg): return [m for m in dlg if m.msg_type == sprompt and not m.skipped]
+
+def clean_dialog(source):
+    "Prompt messages from a Dhrona notebook, without review notes."
+    dlg = read_dialog(source)
+    if not (prompts := _prompts(dlg)): raise ValueError('Dialog contains no prompt turns')
+    return Dialog(prompts, name=dlg.name, meta=dlg.meta)
+
+def _add_review(dlg, report, text):
+    dlg.meta[REVIEW_KEY] = report
+    dlg.mk_message(f'# Dhrona review\n\n{text}', idx=0, msg_type=snote, skipped=1, meta={REVIEW_KEY: report})
+
+def _write_dlg(dlg, output):
+    output = Path(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    write_ipynb(dlg, output)
+    return output
+
+# %% ../nbs/01_rounds.ipynb #252210fa
+def latest_session(turns):
+    "The newest session id in `turns`."
+    return turns[-1].get('session') if turns else None
+
+def _turn_msgs(turn, ti=0):
+    "One Ramabana archive turn as typed Aidialog messages; `ti` keeps fallback call ids unique across turns."
+    user = Msg('user', [Text(turn.get('prompt', ''))])
+    replies = []
+    for i, action in enumerate(turn.get('activity') or []):
+        call_id = action.get('action_id') or action.get('id') or f'call_{ti}_{i}'
+        tool = action.get('tool', '')
+        args = action.get('args') or {}
+        replies += [
+            Msg('assistant', [ToolUse(id=call_id, name=tool, arguments=args)]),
+            Msg('tool', [ToolResult(id=call_id, name=tool, arguments=args, text=str(action.get('detail', '')))]),
+        ]
+    if text := turn.get('reply', ''): replies.append(Msg('assistant', [Text(text)]))
+    return [user, *replies]
+
+def capture(
+    output,                 # review notebook path
+    session='latest',       # Ramabana session id, prefix, or `latest`
+    history=RAMABANA_HISTORY, # Ramabana history path
+    name=None,              # round name; output stem when omitted
+):
+    "Capture one persisted Ramabana session as a review notebook."
+    turns = read_history(history)
+    if not turns: raise ValueError('Ramabana history has no completed turns')
+    if session == 'latest': session = latest_session(turns)
+    matches = [t for t in turns if str(t.get('session', '')).startswith(session)]
+    ids = {t.get('session') for t in matches}
+    if not matches: raise ValueError(f'No Ramabana session matches {session!r}')
+    if len(ids) > 1: raise ValueError(f'Ramabana session prefix {session!r} is ambiguous')
+    assessment = assess_history(matches)
+    msgs = [m for ti, turn in enumerate(matches) for m in _turn_msgs(turn, ti)]
+    dlg = chat2dlg(msgs, name or Path(output).stem, mx=None)
+    report = {'version': dhrona_version(), 'session': matches[0].get('session'), 'model': matches[-1].get('model'),
+              'status': 'review', 'score': assessment.score,
+              'findings': [asdict(f) for f in assessment.findings]}
+    _add_review(dlg, report, 'Edit this dialog in Leela. Remove poor routes and sensitive content. Set `reviewer` when accepting.')
+    return _write_dlg(dlg, output)
+
+# %% ../nbs/01_rounds.ipynb #c2ca7765
+def compiled_history(source):
+    "Canonical Aidialog history from an accepted round."
+    dlg = clean_dialog(source)
+    if (dlg.meta.get(REVIEW_KEY) or {}).get('status') != 'accepted': raise ValueError('Round has not been accepted')
+    return dlg2chat(dlg, plain=True)
+
+def accept(
+    source,         # reviewed dialog notebook
+    reviewer,       # person accepting the round
+    output=None,    # compiled JSON path; `<source>.json` when omitted
+    install=False,  # also write to the rounds library (`True` for `ROUNDS_DIR`, or a directory)
+):
+    "Accept a reviewed dialog and write its canonical history."
+    if not reviewer.strip(): raise ValueError('reviewer is required')
+    dlg = read_dialog(source)
+    if not (prompts := _prompts(dlg)): raise ValueError('Round contains no prompt turns')
+    history = dlg2chat(Dialog(prompts, name=dlg.name), plain=True)
+    if not history or history[0].role != 'user': raise ValueError('Round must start with a user turn')
+    meta = dict(dlg.meta.get(REVIEW_KEY) or {})
+    tools = sorted({p.name for m in history for p in m.content if isinstance(p, ToolUse)})
+    meta.update(status='accepted', reviewer=reviewer, accepted_version=dhrona_version(), tools=tools)
+    dlg.meta[REVIEW_KEY] = meta
+    dlg.save(source)
+    output = Path(output) if output else Path(source).with_suffix('.json')
+    data = {'meta': meta, 'history': _history_dicts(history)}
+    output.write_json(data, indent=2)
+    if install:
+        lib = (ROUNDS_DIR if install is True else Path(install))/f'{dlg.name or Path(source).stem}.json'
+        lib.parent.mkdir(parents=True, exist_ok=True)
+        lib.write_json(data, indent=2)
+    return output
+
+def _part_dict(part):
+    data = {'type': str(getattr(part.type, 'value', part.type))}
+    data.update({k:v for k,v in vars(part).items() if v not in (None, False, {}, []) and k != 'raw'})
+    return data
+
+def _history_dicts(history):
+    return [{'role': m.role, 'content': [_part_dict(p) for p in m.content]} for m in history]
+
+# %% ../nbs/01_rounds.ipynb #7df69513
+def bootstrap_prompt(source):
+    "A compact prompt containing one accepted worked round."
+    history = compiled_history(source)
+    rows = ['The following reviewed Dhrona round demonstrates the tool route to follow.']
+    for m in history:
+        if m.role == 'user': rows.append(f'User: {m.text}')
+        elif m.role == 'assistant':
+            for p in m.content:
+                if isinstance(p, Text) and p.text: rows.append(f'Assistant: {p.text}')
+                elif isinstance(p, ToolUse): rows.append(f'Assistant tool: {p.name}({json.dumps(p.arguments, sort_keys=True)})')
+        elif m.role == 'tool':
+            for p in m.content:
+                if isinstance(p, ToolResult): rows.append(f'Tool result: {p.text}')
+    rows.append('Reply with exactly: DHRONA_READY')
+    return '\n\n'.join(rows)
+
+def start_commands(
+    source,   # accepted review notebook
+    root='.', # Ramabana root
+    model=None, # optional model name
+):
+    "The bootstrap and resume commands for an accepted round."
+    prompt = bootstrap_prompt(source)
+    cmd = ['ramabana', '--root', root]
+    if model: cmd += ['--model', model]
+    cmd += [prompt]
+    return cmd, ['ramabana', '--root', root, '--resume', 'latest']
+
+def start_round(source, root='.', model=None, launch=False):
+    "Prepare or launch Ramabana with an accepted Dhrona round."
+    first, resume = start_commands(source, root, model)
+    if not launch: return {'bootstrap': first, 'resume': resume}
+    subprocess.run(first, check=True)
+    return subprocess.run(resume, check=True).returncode
+
+# %% ../nbs/01_rounds.ipynb #5f8482bd
+def _print_commands(commands):
+    for name, command in commands.items(): print(f'{name}: {shlex.join(command)}')
+
+@call_parse
+def capture_cli(output: str, session: str='latest', history: str=str(RAMABANA_HISTORY), name: str=None):
+    "Capture a saved Ramabana session for review."
+    print(capture(output, session, history, name))
+
+@call_parse
+def accept_cli(source: str, reviewer: str='', output: str=None, install: bool=False):
+    "Accept a reviewed round and compile its history."
+    print(accept(source, reviewer, output, install))
+
+@call_parse
+def start_cli(source: str, root: str='.', model: str=None, launch: bool=False):
+    "Prepare or launch Ramabana with an accepted round."
+    result = start_round(source, root, model, launch)
+    if isinstance(result, dict): _print_commands(result)

dhrona/seeds/fossick-github.json

@@ -0,0 +1,45 @@
+{
+  "meta": {
+    "name": "fossick-github",
+    "status": "accepted",
+    "reviewer": "Karthik",
+    "tools": ["run_shell"],
+    "model": null
+  },
+  "history": [
+    {
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "Use FOSSICK to research the AnswerDotAI llmdojo GitHub repository."}
+      ]
+    },
+    {
+      "role": "assistant",
+      "content": [
+        {"type": "text", "text": "The request names a GitHub repository and FOSSICK, so use its repository reader first."},
+        {
+          "type": "tool_use",
+          "id": "call_fossick",
+          "name": "run_shell",
+          "arguments": {
+            "command": "fossick read-gh-repo https://github.com/AnswerDotAI/llmdojo --globs 'README*,llmdojo/*.py,pyproject.toml' --limit 30",
+            "cwd": ".",
+            "timeout": 120
+          }
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "content": [
+        {"type": "tool_result", "id": "call_fossick", "name": "run_shell", "text": "# llmdojo\nLLM coding agents imitate what their context shows."}
+      ]
+    },
+    {
+      "role": "assistant",
+      "content": [
+        {"type": "text", "text": "FOSSICK read the repository directly. I will use its source files as the evidence."}
+      ]
+    }
+  ]
+}

dhrona/sessions.py

@@ -0,0 +1,82 @@
+"""Move reviewed dialogs between Ramabana, Claude Code, and Codex.
+
+Docs: https://Karthik777.github.io/drona/sessions.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/02_sessions.ipynb.
+
+# %% auto #0
+__all__ = ['HOSTS', 'import_session', 'export_session', 'import_cli', 'export_cli', 'clean_dialog']
+
+# %% ../nbs/02_sessions.ipynb #9ba09521
+from fastcore.xtras import Path
+import json
+
+from fastcore.script import call_parse
+from llmsurgery import ant, oai
+from llmsurgery.sess import path_dlg, sess_dlg
+
+from .rounds import REVIEW_KEY, capture, clean_dialog, bootstrap_prompt, _add_review, _write_dlg
+_all_ = ['clean_dialog']
+
+# %% ../nbs/02_sessions.ipynb #aa0b5b0e
+HOSTS = ('ramabana', 'claude', 'codex')
+
+def import_session(
+    host,            # `ramabana`, `claude`, or `codex`
+    output,          # review notebook path
+    session='latest', # session id, prefix, or `latest`
+    cwd=None,        # project directory for Claude or newest-session lookup
+    history=None,    # Ramabana history path
+    codex_home=None, # optional Codex home
+    name=None,       # dialog name
+):
+    "Import one host session as an Aidialog review notebook."
+    if host not in HOSTS: raise ValueError(f'host must be one of {HOSTS}')
+    if host == 'ramabana':
+        kwargs = {} if history is None else {'history': history}
+        return capture(output, session=session, name=name, **kwargs)
+    if session == 'latest':
+        if host == 'claude':
+            path = max(ant.sess_dir(cwd).glob('*.jsonl'), key=lambda p:p.stat().st_mtime)
+        else: _, path = oai.project_thread(cwd or '.', codex_home or oai.CODEX_HOME)
+        dlg = path_dlg('ant' if host == 'claude' else 'oai', path, name=name, mx=None)
+    else: dlg = sess_dlg(session, cwd=cwd, codex_home=codex_home, name=name, mx=None)
+    source = dict(dlg.meta.get('llmsurgery') or {})
+    source['host'] = host
+    review = {'status': 'review', 'source': source}
+    _add_review(dlg, review, 'Edit this dialog in Leela before exporting it.')
+    return _write_dlg(dlg, output)
+
+# %% ../nbs/02_sessions.ipynb #d8739129
+def export_session(
+    source,          # Dhrona review notebook
+    host,            # `ramabana`, `claude`, or `codex`
+    output=None,     # JSON output for Ramabana or Codex
+    cwd=None,        # Claude project directory
+):
+    "Compile one Dhrona notebook for a target host."
+    if host not in HOSTS: raise ValueError(f'host must be one of {HOSTS}')
+    dlg = clean_dialog(source)
+    if host == 'claude': return ant.dlg2sess(dlg, cwd=cwd)
+    if host == 'codex':
+        items = list(oai.dlg2items(dlg))
+        if output: Path(output).write_json(items, indent=2)
+        return items
+    prompt = bootstrap_prompt(source)
+    if output: Path(output).write_text(prompt)
+    return prompt
+
+# %% ../nbs/02_sessions.ipynb #b895cc91
+@call_parse
+def import_cli(host: str, output: str, session: str='latest', cwd: str=None,
+               history: str=None, codex_home: str=None, name: str=None):
+    "Import a host session as a review notebook."
+    print(import_session(host, output, session, cwd, history, codex_home, name))
+
+@call_parse
+def export_cli(source: str, host: str, output: str=None, cwd: str=None):
+    "Compile a review notebook for another host."
+    result = export_session(source, host, output, cwd)
+    if host == 'claude': print(result)
+    elif output: print(output)
+    else: print(json.dumps(result, indent=2) if host == 'codex' else result)

dhrona/tools.py

@@ -0,0 +1,83 @@
+"""Measure which tools agents call, how often they fail, and where the shell stands in for a dedicated tool.
+
+Docs: https://Karthik777.github.io/drona/tools.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/03_tools.ipynb.
+
+# %% auto #0
+__all__ = ['HISTORIES', 'tool_report', 'fmt_report', 'tools_cli']
+
+# %% ../nbs/03_tools.ipynb #ba1f72ae
+from collections import Counter, defaultdict
+from datetime import datetime
+from json import dumps
+import re, sys
+from fastcore.xtras import Path
+from fastcore.foundation import L
+from fastcore.script import call_parse
+
+from .core import read_history, tool_args, bypass_tool
+
+# %% ../nbs/03_tools.ipynb #55021db5
+HISTORIES = L(Path.home()/f'.config/{app}/{kind}-history.jsonl' for app in ('ramabana', 'leela') for kind in ('agent', 'inline')).filter(Path.exists)
+
+def _epoch(t):
+    "`t` as seconds since the epoch, from a number, numeric string, or ISO date."
+    if t in (None, ''): return None
+    try: return float(t)
+    except ValueError:
+        try: return datetime.fromisoformat(t).timestamp()
+        except ValueError: raise ValueError(f'--since must be an epoch or ISO date, got {t!r}') from None
+
+def _detail_key(detail):
+    "The first line of `detail` with digits normalised, so repeated failures group together."
+    return re.sub(r'\d+', 'N', str(detail or '').partition('\n')[0])[:80]
+
+def tool_report(
+    turns,      # history turns from `read_history`
+    since=None, # epoch or ISO date lower bound on `at`
+    model=None, # restrict to one model name
+):
+    "Per-tool call and failure counts, shell bypasses, and the same split per model."
+    since, calls, fails, details, bypass = _epoch(since), Counter(), Counter(), defaultdict(Counter), Counter()
+    models = defaultdict(lambda: dict(calls=0, shell=0, bypass=0))
+    for t in turns:
+        if (since and (t.get('at') or 0) < since) or (model and t.get('model') != model): continue
+        m = models[t.get('model') or '?']
+        for a in t.get('activity') or []:
+            tool = a.get('tool') or '?'
+            calls[tool] += 1; m['calls'] += 1
+            if a.get('ok') is False: fails[tool] += 1; details[tool][_detail_key(a.get('detail'))] += 1
+            if tool == 'run_shell':
+                m['shell'] += 1
+                if b := bypass_tool(tool_args(a).get('command')): bypass[b] += 1; m['bypass'] += 1
+    tools = {k: dict(calls=v, fails=fails[k], fail_rate=round(fails[k]/v, 3), failures=[[d,n] for d,n in details[k].most_common(3)])
+             for k,v in calls.most_common()}
+    return dict(calls=sum(calls.values()), tools=tools, bypass=dict(bypass.most_common()), models=dict(models))
+
+def fmt_report(r):
+    "`r` as a text table followed by bypass and per-model summary lines."
+    w = max(map(len, r['tools']), default=4)
+    rows = [f"{'tool':<{w}}  calls  fail%  top failure"]
+    rows += [f"{t:<{w}}  {v['calls']:>5}  {100*v['fail_rate']:>4.0f}%  {v['failures'][0][0] if v['failures'] else ''}" for t,v in r['tools'].items()]
+    rows.append(f"\n{r['calls']} calls; bypass: " + (', '.join(f'{k}={v}' for k,v in r['bypass'].items()) or 'none'))
+    rows += [f"{m}: {v['calls']} calls, {v['shell']} shell, {v['bypass']} bypass" for m,v in r['models'].items()]
+    return '\n'.join(rows)
+
+
+# %% ../nbs/03_tools.ipynb #ce493ed0
+@call_parse
+def tools_cli(
+    history: str='',  # comma-separated history paths (default: every known history)
+    since: str='',    # epoch or ISO date lower bound
+    model: str='',    # restrict to one model
+    json: bool=False, # print the report as JSON
+):
+    "Report tool usage, failures and shell bypasses across agent histories."
+    paths = L(history.split(',')).filter().map(lambda p: Path(p).expanduser()) if history else HISTORIES
+    if missing := paths.filter(Path.exists, negate=True): print(f"No history at {', '.join(map(str, missing))}", file=sys.stderr)
+    if not (paths := paths.filter(Path.exists)): sys.exit('No history files found')
+    try: r = tool_report(paths.map(read_history).concat(), since or None, model or None)
+    except ValueError as e: sys.exit(str(e))
+    print(dumps(r, indent=2) if json else fmt_report(r))
+

dhrona-0.1.1.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: dhrona
+Version: 0.1.1
+Summary: train agents to choose and use the right tools
+Project-URL: Repository, https://github.com/Karthik777/drona
+Project-URL: Documentation, https://Karthik777.github.io/drona/
+Author-email: Karthik <karthik.rajgopal@hotmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: nbdev
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Requires-Dist: aidialog>=0.0.27
+Requires-Dist: fastcore>=2.1.16
+Requires-Dist: llmsurgery>=0.0.16
+Requires-Dist: uraiyadal>=0.0.1
+Description-Content-Type: text/markdown
+
+# dhrona
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+Dhrona measures how agents use their tools and teaches better routes. It reads Ramabana and Leela session history, reports tool use and failures, flags poor routes, and turns reviewed sessions into a library of accepted rounds that any Urai chat can replay as a warm start.
+
+## The loop
+
+1.  **Measure** — `dhrona-tools` reports calls, failure rate and shell bypasses per tool and per model; `dhrona` scores routes in a session.
+2.  **Capture** — `dhrona-capture` turns a finished Ramabana session into an Aidialog review notebook.
+3.  **Review in Leela** — open the notebook, remove detours and sensitive content, keep the route future models should imitate.
+4.  **Accept** — `dhrona-accept --install` records the reviewer, the tools used and the model, compiles canonical history, and installs it in the rounds library.
+5.  **Warm start** — `warm_start(tools, model)` replays accepted rounds whose recorded calls still bind to the offered tools’ live signatures, same-model rounds first.
+
+Re-run `dhrona-tools` after a change to see whether tool use moved.
+
+## Install
+
+``` sh
+pip install dhrona
+```
+
+## Measure tool use
+
+`dhrona-tools` measures tool use across the Ramabana and Leela histories: calls and failure rate per tool, shell commands that bypass a dedicated tool, and the same split per model. It is the before/after instrument for tool culling.
+
+``` sh
+dhrona-tools --since 2026-09-19
+dhrona-tools --json > baselines/tools.json
+```
+
+[`assess_turn`](https://Karthik777.github.io/drona/core.html#assess_turn) scores observable tool actions. It does not infer quality from the assistant narrative.
+
+``` python
+turn = {
+    'prompt': 'Use fossick to research https://github.com/AnswerDotAI/llmdojo',
+    'activity': [{'tool': 'web_search', 'ok': True, 'args': {'query': 'llmdojo'}}],
+}
+assessment = assess_turn(turn)
+assessment
+```
+
+Findings are `route` (generic search before FOSSICK), `schema` (arguments that failed to decode), `bypass` (a shell command a dedicated tool covers), `tool_protocol` (command-line usage error) and `repeat_failure`. Every finding lowers the score by 20 points, including each distinct `bypass` in a turn, so shelling out for `git diff` or `cat` costs points. Run `dhrona` to assess the default Ramabana history. Pass `--session` to limit the report to one session.
+
+## Curate a round
+
+Ramabana already records completed turns. Capture reads that archive after the conversation ends. It does not monitor a live process.
+
+``` sh
+ramabana --root /path/to/project
+# finish the useful conversation, then quit
+dhrona-capture training/github-research.ipynb --session latest
+leela training
+```
+
+Open `github-research.ipynb` in Leela. Remove detours and sensitive content. Keep the route that future models should imitate. Save the notebook, then accept it with a reviewer name.
+
+``` sh
+dhrona-accept training/github-research.ipynb --reviewer Karthik --install
+```
+
+Acceptance updates the notebook metadata with the reviewer, the tools the round calls and the session model, and writes `github-research.json` as derived canonical history. `--install` also copies it into the rounds library (`~/.config/dhrona/rounds/`), where [`warm_start`](https://Karthik777.github.io/drona/core.html#warm_start) finds it. An unaccepted notebook cannot start a session.
+
+`dhrona-start` prints the Ramabana bootstrap and resume commands by default. `--launch` runs them.
+
+``` sh
+dhrona-start training/github-research.ipynb --root /path/to/project
+dhrona-start training/github-research.ipynb --root /path/to/project --launch
+```
+
+Ramabana receives the accepted round as its first bootstrap turn and saves it. Dhrona then resumes that session. Leela can use [`compiled_history`](https://Karthik777.github.io/drona/rounds.html#compiled_history) directly when it adds prepared-history support.
+
+## Warm start a chat
+
+[`warm_start`](https://Karthik777.github.io/drona/core.html#warm_start) returns canonical Urai history from the accepted rounds in the library and the seeds packaged with dhrona. Pass the tools you offer (a list of callables or tool names, or a name → callable dict) and only rounds whose recorded calls bind to those signatures ([`call_valid`](https://Karthik777.github.io/drona/core.html#call_valid)) are replayed; a round for a renamed or re-parameterised tool is skipped rather than taught. Pass it to any Urai or Rishi chat through `messages=`, or call [`prepare_chat`](https://Karthik777.github.io/drona/core.html#prepare_chat) on an empty chat.
+
+``` python
+def run_shell(command, cwd='.', timeout=60): ...
+history = warm_start([run_shell])
+[(message['role'], message.get('name')) for message in history]
+```
+
+A completion receipt includes the package version and round revision. [`completion_valid`](https://Karthik777.github.io/drona/core.html#completion_valid) rejects receipts from an older round.
+
+## Move sessions between hosts
+
+Aidialog notebooks are the interchange format. Ramabana, Claude, and Codex sessions can all be imported for review in Leela.
+
+``` sh
+dhrona-import ramabana training/round.ipynb --session latest
+dhrona-import claude training/round.ipynb --session latest --cwd /path/to/project
+dhrona-import codex training/round.ipynb --session latest --cwd /path/to/project
+```
+
+The same reviewed notebook can become a Ramabana bootstrap, a resumable Claude session, or Codex-native Responses items.
+
+``` sh
+dhrona-export training/round.ipynb ramabana --output training/round.txt
+dhrona-export training/round.ipynb claude --cwd /path/to/project
+dhrona-export training/round.ipynb codex --output training/round-items.json
+```
+
+Claude Code can resume the id printed by the Claude export. Codex export does not create a resumable rollout because llmsurgery has no public rollout writer. The exported items remain suitable for inspection, datasets, and a future Codex launcher.
+
+## Command line
+
+| Command | Purpose |
+|----|----|
+| `dhrona` | Score tool routes in Ramabana history |
+| `dhrona-tools` | Tool use, failures and bypasses per tool and per model |
+| `dhrona-capture` | Save a Ramabana session as a review notebook |
+| `dhrona-accept` | Accept a reviewed round; `--install` adds it to the library |
+| `dhrona-start` | Bootstrap and resume Ramabana with an accepted round |
+| `dhrona-import` | Import a Ramabana, Claude or Codex session as a notebook |
+| `dhrona-export` | Export a notebook for Ramabana, Claude or Codex |
+
+## Develop
+
+``` sh
+uv sync --all-extras --group dev
+uv run nbdev-prepare
+```

dhrona-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+dhrona/__init__.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+dhrona/_modidx.py,sha256=qqQWLZRzj2NYCDTEU5FHilB2-5ztW3PQRnPIH56ocfo,6191
+dhrona/core.py,sha256=GXcWf2qb03MokbcDIsF3IWZ3NMpK6Bek3nSdBE60L8c,10647
+dhrona/rounds.py,sha256=UFjTEVSz9cDt2z_YvEe1Lsf0R2jg-ep6GMvrHfpPRVs,8634
+dhrona/sessions.py,sha256=y4tzw3KpCxdKaGzLFe5dFGGmbpeK49fkki5HLG5EDtg,3459
+dhrona/tools.py,sha256=7BG9kU_NK55PD2a1QU_zT9hRQEEkA_wEaCkXL5ZuNbM,4141
+dhrona/seeds/fossick-github.json,sha256=ZslyC5f-Jl7lQhGbrAXAf6euXWvdfr69mbjTKOi8Wg4,1265
+dhrona-0.1.1.dist-info/METADATA,sha256=eMF4mNsxtqS7BL8Bad49VbRicL_paa4HjeKwC_WhEw8,7186
+dhrona-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+dhrona-0.1.1.dist-info/entry_points.txt,sha256=MNOLhRlEcNP4wYv2iZlUvLQwdeA-rtHQFjpmLvjAgQI,326
+dhrona-0.1.1.dist-info/licenses/LICENSE,sha256=xV8xoN4VOL0uw9X8RSs2IMuD_Ss_a9yAbtGNeBWZwnw,11337
+dhrona-0.1.1.dist-info/RECORD,,

dhrona-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

dhrona-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,11 @@
+[console_scripts]
+dhrona = dhrona.core:main
+dhrona-accept = dhrona.rounds:accept_cli
+dhrona-capture = dhrona.rounds:capture_cli
+dhrona-export = dhrona.sessions:export_cli
+dhrona-import = dhrona.sessions:import_cli
+dhrona-start = dhrona.rounds:start_cli
+dhrona-tools = dhrona.tools:tools_cli
+
+[nbdev]
+dhrona = dhrona._modidx:d

dhrona-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2022, fastai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.