Spaces:

mukunda1729
/

why-this-stack

Running

App Files Files Community

mukunda1729 commited on 23 days ago

Commit

835eee6

verified ·

1 Parent(s): b0c78d8

Initial: manifesto for the agent reliability stack

Browse files

Files changed (2) hide show

README.md +11 -5
index.html +69 -17

README.md CHANGED Viewed

@@ -1,10 +1,16 @@
 ---
-title: Why This Stack
-emoji: 🐢
-colorFrom: indigo
-colorTo: gray
 sdk: static
 pinned: false
 ---
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

 ---
+title: Why The Agent Stack
+emoji: 🧭
+colorFrom: yellow
+colorTo: red
 sdk: static
 pinned: false
+license: mit
+short_description: "Why these 5 small libraries matter for agent reliability."
+tags:
+  - llm
+  - agents
+  - reliability
 ---
+The thinking behind The Agent Reliability Stack.

index.html CHANGED Viewed

@@ -1,19 +1,71 @@
 <!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>Why this stack — Agent Reliability</title>
+<style>
+  :root { --bg: #1a1a1a; --fg: #e8e6e1; --muted: #9a9690; --accent: #d4a853; --card: #232323; --border: #353535; }
+  * { box-sizing: border-box; }
+  body { font: 17px/1.6 -apple-system, BlinkMacSystemFont, 'SF Pro Text', sans-serif; background: var(--bg); color: var(--fg); margin: 0; padding: 2rem 1.25rem; }
+  main { max-width: 720px; margin: 0 auto; }
+  h1 { color: var(--accent); font-size: 2.1rem; margin: 0 0 0.5rem; }
+  h2 { color: var(--accent); font-size: 1.4rem; margin: 2.2rem 0 0.8rem; }
+  .lede { color: var(--muted); font-size: 1.1rem; }
+  blockquote { border-left: 3px solid var(--accent); padding: 0.4rem 1rem; margin: 1.2rem 0; color: var(--muted); font-style: italic; }
+  ul li { margin-bottom: 0.4rem; }
+  code { background: var(--card); padding: 0.1rem 0.4rem; border-radius: 4px; font-family: ui-monospace, SF Mono, monospace; font-size: 0.88em; color: var(--accent); }
+  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>🧭 Why this stack</h1>
+  <p class="lede">An honest take on what's actually broken about long-running AI agents — and why fixing it doesn't need a framework.</p>
+  <h2>The problem isn't agents. It's the boring parts.</h2>
+  <p>Most agent failures aren't reasoning failures. They're plumbing failures:</p>
+  <ul>
+    <li>Context window blew up halfway through a long task.</li>
+    <li>The model called a tool with the wrong arg shape and the run died.</li>
+    <li>The model "answered" but you can't parse the JSON.</li>
+    <li>A tool quietly fetched something it shouldn't have, and you only noticed in the bill.</li>
+    <li>You changed a prompt, output looks fine, but a downstream tool is silently using stale data.</li>
+  </ul>
+  <p>None of this is glamorous. None of it is novel research. All of it is wrecking your agents in production right now.</p>
+  <h2>Five small fixes</h2>
+  <blockquote>fit · guard · snap · vet · cast</blockquote>
+  <ul>
+    <li><strong>fit</strong> — fit messages into a token budget so the run doesn't 4xx</li>
+    <li><strong>guard</strong> — declarative URL allowlist so tools can't fetch what they shouldn't</li>
+    <li><strong>snap</strong> — snapshot tool-call traces so you catch silent regressions</li>
+    <li><strong>vet</strong> — validate tool args before execution, return retry hints to the model</li>
+    <li><strong>cast</strong> — extract + validate JSON from messy LLM output</li>
+  </ul>
+  <h2>What it isn't</h2>
+  <p>This isn't a framework. There's no orchestration layer. No vendor lock-in. Each library is one job, ~200 lines, no runtime dependencies. Use one or use all five. Drop it into LangChain or LlamaIndex or your own loop — doesn't care.</p>
+  <h2>BYO LLM</h2>
+  <p>Nothing in here calls a model. <code>vet</code> doesn't know what an LLM is. <code>fit</code> doesn't either — it just counts tokens. <code>cast</code> assumes you've already gotten a string back from somewhere. You wire it up.</p>
+  <h2>Why MIT, why no sponsorship</h2>
+  <p>MIT, all the way down — Python, JavaScript, MCP servers, datasets. No commercial tier. No paid features. Take it, fork it, embed it in a closed-source product if you want.</p>
+  <p>Sponsor links are intentionally absent — the author is on H1B, taking outside payments isn't allowed. Best contribution is filing an issue when something breaks, or starring the repos.</p>
+  <h2>Try it</h2>
+  <ul>
+    <li><a href="https://huggingface.co/spaces/mukunda1729/agent-stack-demo">Live demo</a> — all 5 libraries in one Space</li>
+    <li><a href="https://mukundakatta.github.io/agent-stack/">Landing page</a> — install commands + links</li>
+    <li><a href="https://github.com/MukundaKatta">GitHub</a> — source for everything</li>
+  </ul>
+  <footer>
+    Built by <a href="https://github.com/MukundaKatta">Mukunda Katta</a> · MIT licensed
+  </footer>
+</main>
+</body>
 </html>