PyPI - reactifact - Versions diffs - 0.6.0__py3-none-any.whl - Mend

reactifact 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (103) hide show

reactifact/__init__.py +96 -0
reactifact/__main__.py +10 -0
reactifact/_extras.py +36 -0
reactifact/agents.py +173 -0
reactifact/artifacts.py +130 -0
reactifact/branching.py +255 -0
reactifact/budget.py +41 -0
reactifact/chat.py +373 -0
reactifact/checkpoints.py +329 -0
reactifact/cli/__init__.py +73 -0
reactifact/cli/branch.py +77 -0
reactifact/cli/common.py +67 -0
reactifact/cli/context.py +53 -0
reactifact/cli/graph.py +21 -0
reactifact/cli/replay.py +69 -0
reactifact/cli/scenario.py +94 -0
reactifact/cli/trace.py +45 -0
reactifact/commit.py +97 -0
reactifact/commit_log.py +235 -0
reactifact/consume.py +96 -0
reactifact/context.py +599 -0
reactifact/effects.py +232 -0
reactifact/eval.py +319 -0
reactifact/events.py +34 -0
reactifact/interrupt.py +22 -0
reactifact/llm_agent.py +172 -0
reactifact/operations.py +192 -0
reactifact/patches.py +112 -0
reactifact/produce.py +226 -0
reactifact/prompts.py +111 -0
reactifact/providers/__init__.py +153 -0
reactifact/providers/_retry.py +61 -0
reactifact/providers/anthropic.py +182 -0
reactifact/providers/azure.py +31 -0
reactifact/providers/cerebras.py +11 -0
reactifact/providers/chat.py +417 -0
reactifact/providers/contracts.py +105 -0
reactifact/providers/deepseek.py +11 -0
reactifact/providers/fake.py +40 -0
reactifact/providers/fireworks.py +17 -0
reactifact/providers/gemini.py +284 -0
reactifact/providers/github_models.py +13 -0
reactifact/providers/groq.py +18 -0
reactifact/providers/image.py +157 -0
reactifact/providers/mistral.py +17 -0
reactifact/providers/nvidia.py +18 -0
reactifact/providers/ollama.py +18 -0
reactifact/providers/openai.py +44 -0
reactifact/providers/openrouter.py +70 -0
reactifact/providers/perplexity.py +11 -0
reactifact/providers/qwen.py +17 -0
reactifact/providers/speech.py +347 -0
reactifact/providers/together.py +17 -0
reactifact/providers/video.py +407 -0
reactifact/providers/xai.py +11 -0
reactifact/providers/zai.py +11 -0
reactifact/py.typed +0 -0
reactifact/recipes/__init__.py +63 -0
reactifact/recipes/inputs.py +34 -0
reactifact/recipes/memory.py +166 -0
reactifact/recipes/resolve.py +51 -0
reactifact/recipes/rollback.py +87 -0
reactifact/recipes/search.py +81 -0
reactifact/recipes/skills.py +108 -0
reactifact/recipes/status.py +79 -0
reactifact/recipes/text.py +202 -0
reactifact/relations.py +104 -0
reactifact/replay.py +187 -0
reactifact/resources.py +45 -0
reactifact/runtime.py +498 -0
reactifact/scheduler.py +188 -0
reactifact/session.py +75 -0
reactifact/sources.py +498 -0
reactifact/streaming.py +58 -0
reactifact/structured.py +245 -0
reactifact/testing/__init__.py +48 -0
reactifact/testing/assertions.py +326 -0
reactifact/testing/exceptions.py +27 -0
reactifact/testing/fault.py +164 -0
reactifact/testing/lab.py +350 -0
reactifact/testing/mock.py +166 -0
reactifact/testing/record.py +50 -0
reactifact/testing/registry.py +87 -0
reactifact/tool_use.py +528 -0
reactifact/tools.py +111 -0
reactifact/tracing/__init__.py +29 -0
reactifact/tracing/langfuse.py +125 -0
reactifact/tracing/models.py +93 -0
reactifact/tracing/postgres.py +220 -0
reactifact/tracing/store.py +254 -0
reactifact/tracing/templates/ui.html +196 -0
reactifact/tracing/templates/ui_run.html +264 -0
reactifact/tracing/tracer.py +370 -0
reactifact/tracing/web.py +117 -0
reactifact/triggers.py +41 -0
reactifact/viz.py +248 -0
reactifact/web.py +117 -0
reactifact-0.6.0.dist-info/METADATA +226 -0
reactifact-0.6.0.dist-info/RECORD +103 -0
reactifact-0.6.0.dist-info/WHEEL +5 -0
reactifact-0.6.0.dist-info/entry_points.txt +2 -0
reactifact-0.6.0.dist-info/licenses/LICENSE +21 -0
reactifact-0.6.0.dist-info/top_level.txt +1 -0

reactifact/tracing/templates/ui_run.html ADDED Viewed

@@ -0,0 +1,264 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>Trace #__RUN_ID__ · reactifact</title>
+<script>(function(){try{var s=localStorage.getItem('reactifact-theme');var d=s?s==='dark':true;document.documentElement.classList.toggle('dark',d);}catch(e){document.documentElement.classList.add('dark');}})();</script>
+<style>
+  :root{
+    --bg:#f7f7f9;--panel:#ffffff;--panel-alt:#fafafc;--border:#e6e6ee;--border-strong:#d3d3de;
+    --text:#17171f;--muted:#6f6f7e;--accent:#4f46e5;--accent-soft:#eef0ff;
+    --ok:#15803d;--err:#b91c1c;--ok-soft:#e9f7ef;--err-soft:#fdeeee;
+    --hover:#f4f4f8;--shadow:0 1px 2px rgba(16,16,30,.04),0 1px 6px rgba(16,16,30,.05);
+    --pre-bg:#fafafc;--pre-border:#ececf2;
+    --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+  }
+  html.dark{
+    --bg:#0f1016;--panel:#171820;--panel-alt:#1d1e27;--border:#262733;--border-strong:#33344a;
+    --text:#e7e7f0;--muted:#9a9aae;--accent:#8b93ff;--accent-soft:#232448;
+    --ok:#3ecf7c;--err:#f97c7c;--ok-soft:#123522;--err-soft:#3c1718;
+    --hover:#1f202b;--shadow:0 1px 2px rgba(0,0,0,.4),0 1px 8px rgba(0,0,0,.3);
+    --pre-bg:#101116;--pre-border:#2a2b38;
+  }
+  *{box-sizing:border-box;}
+  body{margin:0;background:var(--bg);color:var(--text);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Inter,sans-serif;font-size:14px;line-height:1.5;-webkit-font-smoothing:antialiased;}
+  header{position:sticky;top:0;z-index:10;background:var(--panel);border-bottom:1px solid var(--border);backdrop-filter:saturate(1.4) blur(6px);}
+  .header-inner{max-width:1240px;margin:0 auto;padding:0 28px;height:56px;display:flex;align-items:center;gap:14px;}
+  .logo{display:flex;align-items:center;gap:9px;color:var(--text);text-decoration:none;}
+  .logo b{font-size:15px;letter-spacing:.1px;}
+  .logo .sub{color:var(--muted);font-family:var(--mono);font-size:12px;font-weight:400;}
+  .spacer{flex:1;}
+  #theme{border:1px solid var(--border);background:var(--panel);color:var(--text);border-radius:8px;padding:5px 11px;font-size:12.5px;cursor:pointer;}
+  #theme:hover{border-color:var(--accent);color:var(--accent);}
+  main{max-width:1240px;margin:0 auto;padding:28px;}
+  .crumbs{display:flex;align-items:center;gap:8px;font-size:13px;margin-bottom:16px;color:var(--muted);}
+  .crumbs a{color:var(--muted);text-decoration:none;font-weight:550;}
+  .crumbs a:hover{color:var(--accent);}
+  .crumbs .sep{opacity:.5;} .crumbs b{color:var(--text);font-family:var(--mono);}
+  .head-row{display:flex;align-items:center;gap:12px;flex-wrap:wrap;margin-bottom:20px;}
+  .head-row h1{font-size:21px;margin:0;font-weight:650;font-family:var(--mono);letter-spacing:-.2px;}
+  .badge{display:inline-flex;align-items:center;gap:7px;font-size:12.5px;font-weight:600;border-radius:20px;padding:3px 12px;}
+  .badge.ok{background:var(--ok-soft);color:var(--ok);} .badge.err{background:var(--err-soft);color:var(--err);}
+  .badge .dot{width:8px;height:8px;border-radius:50%;} .badge.ok .dot{background:var(--ok);} .badge.err .dot{background:var(--err);}
+  .card{background:var(--panel);border:1px solid var(--border);border-radius:12px;box-shadow:var(--shadow);padding:18px 20px;margin-bottom:20px;}
+  .card h2{font-size:11px;font-weight:650;letter-spacing:.7px;text-transform:uppercase;color:var(--muted);margin:0 0 14px;}
+  .meta-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:14px 22px;}
+  .meta-item{display:flex;flex-direction:column;gap:2px;}
+  .meta-item .k{font-size:11px;font-weight:600;color:var(--muted);text-transform:uppercase;letter-spacing:.5px;}
+  .meta-item .v{font-size:13.5px;font-weight:550;font-variant-numeric:tabular-nums;word-break:break-all;}
+  .meta-item .v.mono{font-family:var(--mono);}
+  .agents{display:flex;flex-direction:column;gap:12px;}
+  details.agent{border:1px solid var(--border);border-radius:12px;background:var(--panel);box-shadow:var(--shadow);overflow:hidden;}
+  details.agent>summary{display:flex;align-items:center;gap:12px;padding:12px 16px;cursor:pointer;font-size:14px;}
+  details.agent>summary:hover{background:var(--hover);}
+  .caret{color:var(--muted);transition:transform .15s;} details[open]>.caret,.caret.open{transform:rotate(90deg);}
+  .agent .muted,.spans-stat{color:var(--muted);font-size:12.5px;font-variant-numeric:tabular-nums;}
+  .agent-body{padding:6px 16px 16px;border-top:1px solid var(--border);background:var(--panel-alt);}
+  .chips{display:flex;flex-wrap:wrap;gap:6px;margin:10px 0;}
+  .chip{display:inline-flex;align-items:center;gap:6px;background:var(--accent-soft);color:var(--accent);border-radius:12px;padding:2px 9px;font-family:var(--mono);font-size:11.5px;}
+  .spans{display:flex;flex-direction:column;gap:8px;}
+  details.node{border:1px solid var(--border);border-left:3px solid var(--accent);border-radius:10px;background:var(--panel);overflow:hidden;}
+  details.node summary{display:flex;align-items:center;gap:10px;padding:9px 14px;cursor:pointer;font-size:13px;}
+  details.node summary:hover{background:var(--hover);}
+  .s-dot{width:9px;height:9px;border-radius:50%;flex:none;} .s-dot.ok{background:var(--ok);} .s-dot.err{background:var(--err);}
+  .nid{font-family:var(--mono);font-weight:600;}
+  .ntype{color:var(--muted);font-family:var(--mono);font-size:12px;}
+  .stat{color:var(--muted);font-size:12px;font-variant-numeric:tabular-nums;margin-left:auto;white-space:nowrap;}
+  .node-body{padding:0 14px 14px;border-top:1px solid var(--border);}
+  .io-grid{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:12px;}
+  @media(max-width:700px){.io-grid{grid-template-columns:1fr;}}
+  .io h3{font-size:11px;font-weight:650;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:0 0 8px;}
+  .io{background:var(--panel);border:1px solid var(--border);border-radius:8px;padding:10px 12px;}
+  details.io-more summary{cursor:pointer;font-size:11.5px;color:var(--muted);font-family:var(--mono);}
+  .art{font-family:var(--mono);font-size:12.5px;padding:3px 0;color:var(--text);}
+  .art-head{display:flex;gap:8px;align-items:baseline;}
+  .art .tag{color:var(--accent);background:var(--accent-soft);border-radius:5px;padding:0 6px;font-size:11px;}
+  .art .atype{color:var(--muted);}
+  .art code{color:var(--muted);}
+  .art .ver{color:var(--muted);}
+  .adata{background:var(--pre-bg);border:1px solid var(--pre-border);color:var(--text);border-radius:6px;padding:6px 8px;margin:4px 0 0;font-size:11.5px;white-space:pre-wrap;word-break:break-word;max-height:140px;overflow:auto;}
+  .muted{color:var(--muted);font-family:var(--mono);font-size:12px;}
+  .llm h3{font-size:11px;font-weight:650;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:14px 0 8px;}
+  details.llm-call{border:1px solid var(--border);border-radius:8px;margin-bottom:8px;background:var(--panel);}
+  details.llm-call summary{display:flex;align-items:center;gap:10px;padding:8px 12px;cursor:pointer;font-size:13px;}
+  details.llm-call summary:hover{background:var(--hover);}
+  .role{padding:6px 10px;border-left:2px solid var(--border);margin:6px 0;font-size:12.5px;white-space:pre-wrap;word-break:break-word;}
+  .role.user{border-left-color:var(--accent);}
+  .role.assistant{border-left-color:var(--ok);}
+  .role.tool{border-left-color:var(--muted);}
+  .role-label{font-size:10.5px;font-weight:650;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);display:block;margin-bottom:2px;}
+  .err-box{margin-top:12px;background:var(--err-soft);border:1px solid var(--err);color:var(--err);border-radius:8px;padding:10px 12px;font-family:var(--mono);font-size:12.5px;white-space:pre-wrap;}
+  .empty{padding:32px;text-align:center;color:var(--muted);}
+  .diag-head{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin-bottom:10px;}
+  #copy-mermaid{border:1px solid var(--border);background:var(--panel);color:var(--text);border-radius:8px;padding:5px 11px;font-size:12.5px;cursor:pointer;}
+  #copy-mermaid:hover{border-color:var(--accent);color:var(--accent);}
+  .diag-hint{color:var(--muted);font-size:12px;}
+  #mermaid{background:var(--panel-alt);border:1px solid var(--border);border-radius:10px;padding:14px;overflow:auto;}
+  #mermaid:empty{display:none;}
+  .diag-fallback{color:var(--muted);font-size:12.5px;}
+  .diag-error{color:var(--err);font-size:12.5px;}
+  #mermaid-src{margin-top:10px;}
+  #mermaid-src summary{cursor:pointer;font-size:11.5px;color:var(--muted);font-family:var(--mono);}
+  #mermaid-pre{background:var(--pre-bg);border:1px solid var(--pre-border);color:var(--text);border-radius:6px;padding:10px;font-family:var(--mono);font-size:11.5px;white-space:pre-wrap;word-break:break-word;margin:8px 0 0;max-height:360px;overflow:auto;}
+</style>
+</head>
+<body>
+<header>
+  <div class="header-inner">
+    <a class="logo" href="/traces">
+      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+        <circle cx="5" cy="12" r="2.6" fill="currentColor"/>
+        <circle cx="19" cy="5" r="2.6" fill="currentColor"/>
+        <circle cx="19" cy="19" r="2.6" fill="currentColor"/>
+        <path d="M7.4 11 16.6 6M7.4 13l9.2 5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+      </svg>
+      <b>reactifact <span style="color:var(--accent)">traces</span></b>
+      <span class="sub">artifact run observer</span>
+    </a>
+    <div class="spacer"></div>
+    <button id="theme" title="toggle dark mode">dark</button>
+  </div>
+</header>
+<main>
+  <div class="crumbs"><a href="/traces">traces</a><span class="sep">/</span><b id="cid">#…</b></div>
+  <div class="head-row" id="head"></div>
+  <section class="card"><h2>Run</h2><div class="meta-grid" id="meta"></div></section>
+  <section class="card"><h2>Work by agent</h2><div class="agents" id="agents"></div></section>
+  <section class="card"><h2>Sequence</h2><div class="diag-head"><button id="copy-mermaid">copy</button><span class="diag-hint">mermaid — rendered live; paste the source into mermaid.live / GitHub</span></div><div id="mermaid" class="mermaid"></div><details id="mermaid-src"><summary>show source</summary><pre id="mermaid-pre"></pre></details></section>
+  <section class="card"><h2>Evidence graph</h2><div class="diag-head"><button id="copy-graph">copy</button><span class="diag-hint">provenance: written artifacts + patch.link edges (§34)</span></div><div id="mermaid-graph" class="mermaid"></div><details id="graph-src"><summary>show source</summary><pre id="graph-pre"></pre></details></section>
+</main>
+<script>
+const RUN_ID=__RUN_ID__;
+const MERMAID_SRC=__MERMAID__;
+const MERMAID_GRAPH_SRC=__MERMAID_GRAPH__;
+function applyTheme(dark){document.documentElement.classList.toggle('dark',dark);document.getElementById('theme').textContent=dark?'light':'dark';try{localStorage.setItem('reactifact-theme',dark?'dark':'light');}catch(_){}}
+function initTheme(){let s=null;try{s=localStorage.getItem('reactifact-theme');}catch(_){}applyTheme(s?s==='dark':true);}
+document.getElementById('theme').addEventListener('click',()=>applyTheme(!document.documentElement.classList.contains('dark')));
+async function load(){
+  const res=await fetch('/api/traces/'+RUN_ID);
+  if(!res.ok){document.getElementById('cid').textContent='#'+RUN_ID+' — not found';return;}
+  render(await res.json());
+}
+function meta(k,v,mono){return '<div class="meta-item"><span class="k">'+k+'</span><span class="v'+(mono?' mono':'')+'">'+v+'</span></div>';}
+function fmtTime(t){try{const d=typeof t==='number'?new Date(t*1000):new Date(t);return d.toLocaleString();}catch(_){return '—';}}
+function escapeHtml(s){return String(s??'').replace(/[&<>"']/g,(ch)=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[ch]));}
+function typeCounts(arts){const m={};for(const a of arts||[]){const k=a.data_type||'artifact';m[k]=(m[k]||0)+1;}return m;}
+function chipsHtml(arts){
+  return Object.entries(typeCounts(arts)).map(([t,n])=>'<span class="chip">'+escapeHtml(t)+' '+n+'</span>').join('');
+}
+const SHOWN=6;
+function artsBlock(arts){
+  const list=arts||[]; const n=list.length;
+  if(!n) return '<div class="art" style="color:var(--muted)">—</div>';
+  const chips=chipsHtml(list);
+  if(n<=SHOWN) return chips+'<div class="art-list">'+list.map(artHtml).join('')+'</div>';
+  const first=list.slice(0,SHOWN).map(artHtml).join('');
+  const rest=list.slice(SHOWN).map(artHtml).join('');
+  return chips+'<div class="art-list">'+first+'<details class="io-more" open><summary>… + '+(n-SHOWN)+' more</summary>'+rest+'</details></div>';
+}
+function render(t){
+  document.title='Trace #'+t.id+' · reactifact';
+  document.getElementById('cid').textContent='#'+t.id;
+  const cls=t.outcome==='completed'?'ok':'err';
+  document.getElementById('head').innerHTML='<h1>#'+escapeHtml(t.id)+'</h1><span class="badge '+cls+'"><span class="dot"></span>'+escapeHtml(t.outcome)+'</span>';
+  document.getElementById('meta').innerHTML=
+    meta('session',escapeHtml(t.session_id||'—'),true)+
+    meta('duration',Number(t.duration_ms).toFixed(1)+' <small>ms</small>')+
+    meta('spans',String((t.spans||[]).length))+
+    meta('created',fmtTime(t.started_at));
+  const spans=t.spans||[];
+  const byAgent={};
+  for(const s of spans){(byAgent[s.agent]=byAgent[s.agent]||[]).push(s);}
+  const keys=Object.keys(byAgent);
+  document.getElementById('agents').innerHTML = keys.length
+    ? keys.map(agent=>agentHtml(agent,byAgent[agent])).join('')
+    : '<div class="empty">no spans recorded</div>';
+}
+function agentHtml(agent,list){
+  const ms=list.reduce((a,s)=>a+Number(s.latency_ms||0),0)/list.length;
+  let writes=0,llm=0;
+  const readsAgg={};
+  for(const s of list){
+    writes+=(s.writes||[]).length; llm+=(s.llm_calls||[]).length;
+    for(const r of s.reads||[]){const t=r.data_type||'artifact';readsAgg[t]=(readsAgg[t]||0)+1;}
+  }
+  const chips=Object.entries(readsAgg)
+    .map(([t,n])=>'<span class="chip">'+escapeHtml(t)+' '+n+'</span>').join('');
+  return '<details class="agent" open>'+
+    '<summary><span class="caret">▸</span><b>'+escapeHtml(agent)+'</b>'+
+    '<span class="muted">'+list.length+' spans · '+ms.toFixed(1)+' ms avg</span>'+
+    '<span class="stat">'+writes+' writes · '+llm+' llm · '+'<span class="spans-stat">'+(Object.keys(readsAgg).join(', '))+'</span></span></summary>'+
+    '<div class="agent-body">'+
+    (chips?'<div class="chips">'+chips+'</div>':'')+
+    '<div class="spans">'+list.map(spanHtml).join('')+'</div>'+
+    '</div></details>';
+}
+function spanHtml(s){
+  const ok=!s.error;
+  const errBlock=s.error?'<div class="err-box">'+escapeHtml(s.error)+'</div>':'';
+  const reads=(s.reads||[]).length?('<div class="io"><h3>reads</h3>'+artsBlock(s.reads)+'</div>'):'';
+  const writes=(s.writes||[]).length?('<div class="io"><h3>writes</h3>'+artsBlock(s.writes)+'</div>'):'';
+  const io=(reads||writes)?'<div class="io-grid">'+reads+writes+'</div>':'';
+  const llm=(s.llm_calls||[]).map(llmHtml).join('');
+  return '<details class="node">'+
+    '<summary><span class="caret">▸</span><span class="s-dot '+(ok?'ok':'err')+'"></span>'+
+    '<span class="nid">'+escapeHtml(s.agent)+'</span>'+
+    '<span class="ntype">'+escapeHtml(s.event_type)+'</span>'+
+    '<span class="stat">'+Number(s.latency_ms).toFixed(1)+' ms · '+(s.llm_calls||[]).length+' llm'+(ok?'':' · failed')+'</span></summary>'+
+    '<div class="node-body">'+errBlock+io+(llm?'<div class="llm"><h3>LLM calls</h3>'+llm+'</div>':'')+'</div></details>';
+}
+function artHtml(a){
+  const op=('<span class="tag">'+escapeHtml(a.op_type||'read')+'</span>');
+  const type=a.data_type?'<span class="atype">['+escapeHtml(a.data_type)+']</span>':'';
+  const data=a.data?'<pre class="adata">'+escapeHtml(a.data)+'</pre>':'';
+  return '<div class="art"><div class="art-head">'+op+' '+type+' <code>'+escapeHtml(a.artifact_id.slice(0,8))+'</code> <span class="ver">v'+a.version+'</span></div>'+data+'</div>';
+}
+function llmHtml(c){
+  const detail=(c.messages||[]).map(m=>'<div class="role '+escapeHtml(m.role)+'"><span class="role-label">'+escapeHtml(m.role)+'</span>'+escapeHtml(m.content||'')+'</div>').join('');
+  return '<details class="llm-call"><summary><span class="caret">▸</span><b>'+escapeHtml(c.provider||'llm')+'</b> <span class="muted">'+escapeHtml(c.model||'')+'</span> <span class="stat">'+c.prompt_tokens+' in / '+c.completion_tokens+' out · '+Number(c.latency_ms).toFixed(1)+' ms'+(c.error?' · err':'')+'</span></summary>'+
+    '<div class="node-body">'+(c.error?'<div class="err-box">'+escapeHtml(c.error)+'</div>':'')+detail+(c.response?'<div class="role assistant"><span class="role-label">response</span>'+escapeHtml(c.response)+'</div>':'')+'</div></details>';
+}
+function mountMermaid(src, nodeId, preId){
+  const pre=document.getElementById(preId);
+  pre.textContent=src||'no provenance recorded';
+  if(!src) return;
+  const el=document.getElementById(nodeId);
+  const s=document.createElement('script');
+  s.src='https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
+  s.onload=()=>{
+    const dark=document.documentElement.classList.contains('dark');
+    window.mermaid.initialize({startOnLoad:false,theme:dark?'dark':'default'});
+    el.textContent=src;
+    try{window.mermaid.run({nodes:[el]});}
+    catch(err){el.innerHTML='<div class="diag-error">Mermaid could not render: '+escapeHtml(err&&err.message?err.message:String(err))+'</div>';}
+  };
+  s.onerror=()=>{el.innerHTML='<div class="diag-fallback">Mermaid JS unavailable (offline) — the diagram source is shown below.</div>';};
+  document.head.appendChild(s);
+}
+function fallbackCopy(text){
+  const ta=document.createElement('textarea');ta.value=text;document.body.appendChild(ta);ta.select();
+  try{document.execCommand('copy');}catch(_){}document.body.removeChild(ta);
+}
+function initCopy(){
+  const bind=(btnId,src)=>{const btn=document.getElementById(btnId);btn.addEventListener('click',()=>{
+    const done=()=>{btn.textContent='copied';setTimeout(()=>btn.textContent='copy',900);};
+    const text=src||'';
+    if(navigator.clipboard){navigator.clipboard.writeText(text).then(done).catch(()=>{fallbackCopy(text);done();});}
+    else{fallbackCopy(text);done();}
+  });};
+  bind('copy-mermaid',MERMAID_SRC);
+  bind('copy-graph',MERMAID_GRAPH_SRC);
+}
+initTheme(); load(); mountMermaid(MERMAID_SRC,'mermaid','mermaid-pre'); mountMermaid(MERMAID_GRAPH_SRC,'mermaid-graph','graph-pre'); initCopy();
+</script>
+</body>
+</html>

reactifact/tracing/tracer.py ADDED Viewed

@@ -0,0 +1,370 @@
+"""Trace delivery: `Tracer` (observer) and `CompositeTracer` (fan-out).
+`Tracer` is what the Runtime sees as the source of run events. It is configured
+with one or more sinks (`TraceStore`, later Langfuse/Postgres) and on
+`on_turn_end` pushes the collected `RunTrace` to each sink:
+    Runtime(ctx, agents, tracer=Tracer(store=TraceStore("traces.db")))
+`RecordingLLM` is a wrapper over the LLM provider: while tracing is enabled, it intercepts
+`complete()` and writes `LLMCall` (tokens from `usage`, attribution to the agent via
+`asyncio.current_task()`). Producers know nothing about it — they simply
+call `context.resources.llm` as before.
+"""
+from __future__ import annotations
+import asyncio
+import json
+import time
+import uuid
+from collections.abc import AsyncIterator, Callable, Iterable
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+from ..patches import Create, Link, Update
+from ..providers import LLMProvider, LLMRequest, LLMResponse, LLMResponseChunk
+from .models import AgentSpan, ArtifactRef, LLMCall, RelationRef, RunTrace
+from .store import TraceSink, TraceStore
+if TYPE_CHECKING:
+    from ..agents import Agent
+    from ..commit import Read, Write
+    from ..context import Context
+    from ..events import Event
+    from ..patches import Patch
+#: Up to what size to truncate artifact/response data in a trace.
+TRACE_TRUNCATE = 1500
+def _clip(value: str, limit: int = TRACE_TRUNCATE) -> str:
+    if len(value) <= limit:
+        return value
+    return value[:limit] + "…"
+def _clip_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        {
+            "role": msg.get("role", ""),
+            "content": _clip(str(msg.get("content") or "")),
+        }
+        for msg in messages
+    ]
+class Tracer:
+    """Observer of runs for the Runtime (§54).
+    Runtime invokes `on_turn_begin` / `on_span` (sync, no I/O) and
+    `on_turn_end` (async — the sinks write to SQLite/Postgres/Langfuse).
+    `on_turn_end` awaits each sink's `export`, so sinks are async stores.
+    """
+    def __init__(
+        self,
+        sink: TraceSink | None = None,
+        *,
+        store: TraceStore | None = None,
+        sinks: Iterable[TraceSink] | None = None,
+    ):
+        self.sinks: list[TraceSink] = []
+        if sink is not None:
+            self.sinks.append(sink)
+        if store is not None:
+            self.sinks.append(store)
+        if sinks is not None:
+            self.sinks.extend(sinks)
+    def on_turn_begin(
+        self, run_id: str, *, session_id: str, started_at: datetime
+    ) -> None:
+        pass
+    def on_span(self, span: AgentSpan) -> None:
+        pass
+    async def on_turn_end(self, trace: RunTrace) -> None:
+        for sink in self.sinks:
+            await sink.export(trace)
+class RecordingLLM(LLMProvider):
+    """LLM wrapper: records calls (prompt/response/tokens) into `on_call`."""
+    def __init__(
+        self,
+        inner: LLMProvider,
+        on_call: Callable[[LLMCall], None],
+        agent_of: Callable[[], str],
+        provider: str = "",
+    ):
+        self._inner = inner
+        self._on_call = on_call
+        self._agent_of = agent_of
+        self._provider = provider or type(inner).__name__
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        started = time.monotonic()
+        try:
+            response = await self._inner.complete(request)
+        except Exception as exc:  # noqa: BLE001 — record and re-raise
+            self._record(request, None, (time.monotonic() - started) * 1000, str(exc))
+            raise
+        self._record(request, response, (time.monotonic() - started) * 1000, None)
+        return response
+    def stream(self, request: LLMRequest) -> AsyncIterator[LLMResponseChunk]:
+        return self._inner.stream(request)
+    def _record(
+        self,
+        request: LLMRequest,
+        response: LLMResponse | None,
+        latency_ms: float,
+        error: str | None,
+    ) -> None:
+        usage = dict(response.usage if response is not None else {})
+        call = LLMCall(
+            agent=self._agent_of(),
+            provider=self._provider,
+            model=str(getattr(self._inner, "model", "") or ""),
+            messages=_clip_messages(
+                [
+                    m.model_dump() if hasattr(m, "model_dump") else m.__dict__
+                    for m in request.messages
+                ]
+            ),
+            response=_clip(response.text) if response is not None else "",
+            prompt_tokens=int(usage.get("prompt_tokens") or usage.get("prompt") or 0),
+            completion_tokens=int(
+                usage.get("completion_tokens") or usage.get("completion") or 0
+            ),
+            latency_ms=round(latency_ms, 1),
+            error=error,
+        )
+        self._on_call(call)
+class CompositeTracer:
+    """Distributes events to all passed observers (local + Langfuse)."""
+    def __init__(self, tracers: Iterable[Tracer]):
+        self.tracers = list(tracers)
+    def on_turn_begin(
+        self, run_id: str, *, session_id: str, started_at: datetime
+    ) -> None:
+        for tracer in self.tracers:
+            tracer.on_turn_begin(run_id, session_id=session_id, started_at=started_at)
+    def on_span(self, span: AgentSpan) -> None:
+        for tracer in self.tracers:
+            tracer.on_span(span)
+    async def on_turn_end(self, trace: RunTrace) -> None:
+        for tracer in self.tracers:
+            await tracer.on_turn_end(trace)
+class RunTracer:
+    """Runtime's tracing collaborator (§54).
+    Builds `ArtifactRef`/`RelationRef`/`AgentSpan`/`RunTrace` and delivers
+    them to the configured `Tracer`, so `Runtime` only calls into this at a
+    few well-defined points instead of interleaving span-building with the
+    dispatch loop. Owns: wrapping `resources.llm` in `RecordingLLM` on
+    construction, the task→agent attribution that wrapper needs to attribute
+    an LLM call to the agent that made it, the per-turn span buffer, and the
+    artifact-data truncation cache (`ArtifactRef.data` is memoized per
+    `(artifact_id, version)` for one turn, since the same artifact is often
+    referenced — as a read — by several spans in a generation).
+    A no-op when `tracer` is None (the common case, no tracing configured):
+    every method still works, `record_span` just returns `None` and nothing
+    is buffered or sent anywhere.
+    """
+    def __init__(self, context: Context, tracer: Tracer | CompositeTracer | None):
+        self._context = context
+        self.tracer = tracer
+        self._agent_by_task: dict[asyncio.Task[Any], str] = {}
+        self._pending_llm: dict[str, list[LLMCall]] = {}
+        self._trace_data_cache: dict[tuple[str, int], str] = {}
+        self.run_id = ""
+        self.spans: list[AgentSpan] = []
+        if self.tracer is not None and context.resources.llm is not None:
+            context.resources.llm = RecordingLLM(
+                context.resources.llm,
+                on_call=self._record_llm,
+                agent_of=self._current_agent_name,
+            )
+    @property
+    def enabled(self) -> bool:
+        return self.tracer is not None
+    # ---- task -> agent attribution, for RecordingLLM.agent_of ----
+    def register_task(self, task: asyncio.Task[Any] | None, agent_name: str) -> None:
+        if task is not None:
+            self._agent_by_task[task] = agent_name
+    def unregister_task(self, task: asyncio.Task[Any] | None) -> None:
+        if task is not None:
+            self._agent_by_task.pop(task, None)
+    def _current_agent_name(self) -> str:
+        task = asyncio.current_task()
+        if task is None:
+            return ""
+        return self._agent_by_task.get(task, "")
+    def _record_llm(self, call: LLMCall) -> None:
+        self._pending_llm.setdefault(call.agent, []).append(call)
+    # ---- ArtifactRef / RelationRef builders ----
+    def _artifact_data(self, artifact_id: str) -> Any | None:
+        artifact = self._context.get(artifact_id)
+        return artifact.data if artifact is not None else None
+    def artifact_ref(
+        self,
+        artifact_id: str,
+        version: int,
+        op_type: str,
+        model: Any | None,
+    ) -> ArtifactRef:
+        data: str | None = None
+        if model is not None:
+            key = (artifact_id, version)
+            data = self._trace_data_cache.get(key)
+            if data is None:
+                data = _clip(
+                    json.dumps(model.model_dump(mode="json"), ensure_ascii=False)
+                )
+                self._trace_data_cache[key] = data
+        return ArtifactRef(
+            artifact_id=artifact_id,
+            version=version,
+            op_type=op_type,
+            data_type=type(model).__name__ if model is not None else "",
+            data=data,
+        )
+    @staticmethod
+    def _type_name(artifact_id: str, context: Context | None) -> str:
+        artifact = context.get(artifact_id) if context is not None else None
+        data = artifact.data if artifact is not None else None
+        return type(data).__name__ if data is not None else ""
+    def read_refs(self, reads: list[Read]) -> list[ArtifactRef]:
+        return [
+            self.artifact_ref(
+                read.artifact_id,
+                read.version,
+                "read",
+                self._artifact_data(read.artifact_id),
+            )
+            for read in reads
+        ]
+    def write_refs(self, patch: Patch, writes: list[Write]) -> list[ArtifactRef]:
+        ops_by_id: dict[str, tuple[str, Any | None]] = {}
+        for op in patch.operations:
+            artifact_id = getattr(op, "artifact_id", None)
+            if artifact_id is None:
+                continue
+            if isinstance(op, Create):
+                model: Any | None = op.data
+            elif isinstance(op, Update):
+                model = op.new_data
+            else:
+                model = None
+            ops_by_id[artifact_id] = (op.to_dict().get("type", ""), model)
+        return [
+            self.artifact_ref(
+                w.artifact_id,
+                w.version,
+                ops_by_id.get(w.artifact_id, ("", None))[0],
+                ops_by_id.get(w.artifact_id, ("", None))[1],
+            )
+            for w in writes
+        ]
+    def relation_refs(self, patch: Patch) -> list[RelationRef]:
+        """Provenance edges (`patch.link`) recorded for the span (§34)."""
+        refs: list[RelationRef] = []
+        for op in patch.operations:
+            if not isinstance(op, Link):
+                continue
+            refs.append(
+                RelationRef(
+                    source_id=op.artifact_id,
+                    relation=op.relation,
+                    target_id=op.target_id,
+                    source_type=self._type_name(op.artifact_id, self._context),
+                    target_type=self._type_name(op.target_id, self._context),
+                )
+            )
+        return refs
+    # ---- per-turn lifecycle ----
+    def begin_turn(self, *, session_id: str) -> None:
+        if self.tracer is None:
+            return
+        self.run_id = str(uuid.uuid4())
+        self.spans = []
+        self._trace_data_cache = {}
+        self.tracer.on_turn_begin(
+            self.run_id, session_id=session_id, started_at=datetime.now(UTC)
+        )
+    def record_span(
+        self,
+        agent: Agent,
+        event: Event,
+        reads: list[Read],
+        latency_ms: float,
+        *,
+        error: BaseException | None = None,
+    ) -> AgentSpan | None:
+        """Builds, buffers and delivers one span — or a no-op if disabled.
+        `error is not None` covers the isolated-error path; the success path
+        (a span whose `writes`/`relations` are filled in once the patch is
+        applied, see `Runtime._commit_patches_to_apply`) passes it as `None`.
+        """
+        if self.tracer is None:
+            return None
+        span = AgentSpan(
+            agent=agent.name,
+            event_type=event.type.value,
+            reads=self.read_refs(reads),
+            latency_ms=latency_ms,
+            llm_calls=self._pending_llm.pop(agent.name, []),
+            error=f"{type(error).__name__}: {error}" if error is not None else None,
+            started_at=datetime.now(UTC),
+        )
+        self.spans.append(span)
+        self.tracer.on_span(span)
+        return span
+    async def end_turn(
+        self, *, session_id: str, duration_ms: float, outcome: str
+    ) -> None:
+        if self.tracer is None:
+            return
+        await self.tracer.on_turn_end(
+            RunTrace(
+                id=self.run_id,
+                session_id=session_id,
+                started_at=datetime.now(UTC),
+                duration_ms=duration_ms,
+                outcome=outcome,
+                spans=self.spans,
+            )
+        )