Spaces:

mukunda1729
/

trace-format-reference

Running

App Files Files Community

mukunda1729 commited on 24 days ago

Commit

5c49f9c

verified ·

1 Parent(s): 83d94ff

Initial: agentsnap trace JSON schema reference

Browse files

Files changed (2) hide show

README.md +12 -5
index.html +76 -17

README.md CHANGED Viewed

@@ -1,10 +1,17 @@
 ---
-title: Trace Format Reference
-emoji: 📚
-colorFrom: purple
-colorTo: gray
 sdk: static
 pinned: false
 ---
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

 ---
+title: Agent Trace Format Reference
+emoji: 📸
+colorFrom: green
+colorTo: indigo
 sdk: static
 pinned: false
+license: mit
+short_description: "The agentsnap trace schema — explained field-by-field."
+tags:
+  - llm
+  - agents
+  - traces
+  - agentsnap
 ---
+Field-by-field reference for the agentsnap trace JSON schema.

index.html CHANGED Viewed

@@ -1,19 +1,78 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
 </html>

 <!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Agent Trace Format Reference</title>
+<style>
+  :root { --bg: #1a1a1a; --fg: #e8e6e1; --muted: #9a9690; --accent: #d4a853; --card: #232323; --border: #353535; }
+  * { box-sizing: border-box; }
+  body { font: 16px/1.55 -apple-system, BlinkMacSystemFont, 'SF Pro Text', sans-serif; background: var(--bg); color: var(--fg); margin: 0; padding: 2rem 1.25rem; }
+  main { max-width: 920px; margin: 0 auto; }
+  h1 { color: var(--accent); font-size: 2.1rem; margin: 0 0 0.5rem; }
+  h2 { color: var(--accent); font-size: 1.3rem; margin: 2rem 0 0.6rem; }
+  .lede { color: var(--muted); font-size: 1.05rem; }
+  pre { background: var(--card); border: 1px solid var(--border); padding: 1rem 1.1rem; border-radius: 8px; overflow-x: auto; font-family: ui-monospace, SF Mono, monospace; font-size: 0.85rem; line-height: 1.5; }
+  table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
+  th, td { text-align: left; padding: 0.6rem 0.8rem; border-bottom: 1px solid var(--border); font-size: 0.92rem; vertical-align: top; }
+  th { color: var(--accent); }
+  td code { color: var(--accent); font-family: ui-monospace, SF Mono, monospace; }
+  td.field { white-space: nowrap; }
+  a { color: var(--accent); }
+  footer { color: var(--muted); margin-top: 3rem; padding-top: 1.5rem; border-top: 1px solid var(--border); font-size: 0.9rem; }
+</style>
+</head>
+<body>
+<main>
+  <h1>📸 Agent Trace Format</h1>
+  <p class="lede">A normalized JSON shape for capturing one agent run — input, tool calls, output, and a fingerprint. Used by <code>agentsnap</code> to diff runs and detect silent regressions.</p>
+  <h2>Full example</h2>
+  <pre>{
+  "version": 1,
+  "model": "claude-sonnet-4-6",
+  "input": "search for python tutorials",
+  "output": "Here are 3 results.",
+  "tools": [
+    { "name": "web_search", "args": { "q": "python tutorials" }, "result_hash": "abc123" },
+    { "name": "fetch_page", "args": { "url": "https://example.com" }, "result_hash": "def456" }
+  ],
+  "error": null,
+  "fingerprint": { "node": "20.0", "agentsnap": "0.1.0" }
+}</pre>
+  <h2>Fields</h2>
+  <table>
+    <tr><th>Field</th><th>Type</th><th>Notes</th></tr>
+    <tr><td class="field"><code>version</code></td><td>int</td><td>Schema version. Currently <code>1</code>.</td></tr>
+    <tr><td class="field"><code>model</code></td><td>string</td><td>Model identifier. Used to skip diffs across model upgrades.</td></tr>
+    <tr><td class="field"><code>input</code></td><td>string</td><td>The user prompt that started the run.</td></tr>
+    <tr><td class="field"><code>output</code></td><td>string</td><td>Final agent response.</td></tr>
+    <tr><td class="field"><code>tools</code></td><td>array</td><td>Ordered list of tool calls. Each entry is <code>{name, args, result_hash}</code>.</td></tr>
+    <tr><td class="field"><code>tools[].name</code></td><td>string</td><td>Tool identifier (dotted path like <code>filesystem.read_file</code>).</td></tr>
+    <tr><td class="field"><code>tools[].args</code></td><td>object</td><td>Args passed to the tool. Recorded literally.</td></tr>
+    <tr><td class="field"><code>tools[].result_hash</code></td><td>string</td><td>Hash of the tool's return value. Avoid storing PII / large payloads in the trace.</td></tr>
+    <tr><td class="field"><code>error</code></td><td>string \| null</td><td>Run-level error message, if the run failed.</td></tr>
+    <tr><td class="field"><code>fingerprint</code></td><td>object</td><td>Environment metadata. <code>node</code> + <code>agentsnap</code> version are recommended; add your own keys.</td></tr>
+  </table>
+  <h2>Why hash the tool result?</h2>
+  <p>Tool results are often large (files, API payloads, search results). Hashing keeps the trace small and avoids leaking PII into your snapshot store. The hash is enough to detect "the result changed" — for "<em>how</em> did it change?", re-run with full payloads enabled.</p>
+  <h2>Diffing two traces</h2>
+  <pre>from agentsnap import diff
+result = diff(baseline_trace, current_trace)
+print(result.status)    # "match" | "drift" | "regression"
+for change in result.changes:
+    print(change.path, change.from_, "→", change.to)</pre>
+  <h2>Sample traces</h2>
+  <p>The <a href="https://huggingface.co/datasets/mukunda1729/agent-trace-samples">agent-trace-samples</a> dataset has 10 example traces (good + regressed pairs) you can drop into your tests.</p>
+  <footer>
+    Part of <a href="https://mukundakatta.github.io/agent-stack/">The Agent Reliability Stack</a> · MIT licensed
+  </footer>
+</main>
+</body>
 </html>