From a4a2c0bdb5dbdca3da896c2cbeeaa0e8e6e68230 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Tue, 18 Nov 2025 19:54:37 -0500
Subject: [PATCH 01/11] Refines dashboard UI for clarity and modern polish

Improves dashboard and table visuals with more consistent spacing, new typography utilities, and subtle animations for a more modern, readable, and interactive feel. Updates badge and button sizing for compactness, enhances sidebar and workflow node visuals, and reworks execution/header sections for higher information density and easier scanning. Aims to boost usability and professional appeal without altering core logic.
---
 .../components/EnhancedExecutionsTable.tsx    |  29 +-
 .../src/components/Navigation/SidebarNew.tsx  |  37 +-
 .../src/components/SearchWithFilters.tsx      |   9 +-
 .../components/WorkflowDAG/WorkflowNode.tsx   |  16 +-
 .../components/execution/ExecutionHeader.tsx  | 484 +++++++++---------
 .../web/client/src/components/ui/badge.tsx    |  26 +-
 .../web/client/src/components/ui/button.tsx   |   9 +-
 control-plane/web/client/src/index.css        |   9 +
 .../src/pages/EnhancedDashboardPage.tsx       | 169 +++---
 9 files changed, 430 insertions(+), 358 deletions(-)

diff --git a/control-plane/web/client/src/components/EnhancedExecutionsTable.tsx b/control-plane/web/client/src/components/EnhancedExecutionsTable.tsx
index 09909455..b471e06b 100644
--- a/control-plane/web/client/src/components/EnhancedExecutionsTable.tsx
+++ b/control-plane/web/client/src/components/EnhancedExecutionsTable.tsx
@@ -226,11 +226,11 @@ export function EnhancedExecutionsTable({
 
   return (
     <div className="space-y-4">
-      <Card>
+      <Card className="overflow-hidden border-border/60 shadow-sm">
         <CardContent className="p-0">
-          <div className="border-b border-border px-3 py-2 bg-muted/40">
+          <div className="sticky top-0 z-10 border-b border-border/60 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60 px-3 py-2.5">
             <div
-              className="grid items-center text-xs font-semibold uppercase tracking-wide text-muted-foreground"
+              className="grid items-center text-[10px] font-semibold uppercase tracking-wider text-muted-foreground"
               style={{ gridTemplateColumns: COLUMN_TEMPLATE }}
             >
               <SortableHeaderCell
@@ -262,7 +262,7 @@ export function EnhancedExecutionsTable({
                 onSortChange={onSortChange}
                 align="right"
               />
-              <div className="flex items-center justify-center gap-1 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              <div className="flex items-center justify-center gap-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
                 <ShieldCheck className="h-3 w-3" /> VC
               </div>
               <SortableHeaderCell
@@ -272,11 +272,11 @@ export function EnhancedExecutionsTable({
                 sortOrder={sortOrder}
                 onSortChange={onSortChange}
               />
-              <div className="text-right text-xs font-semibold uppercase tracking-wide text-muted-foreground"></div>
+              <div className="text-right text-[10px] font-semibold uppercase tracking-wider text-muted-foreground"></div>
             </div>
           </div>
 
-          <div ref={parentRef} className="relative h-[60vh] overflow-y-auto">
+          <div ref={parentRef} className="relative h-[60vh] overflow-y-auto bg-muted/5">
             <div
               style={{
                 height: `${virtualizer.getTotalSize()}px`,
@@ -293,7 +293,7 @@ export function EnhancedExecutionsTable({
                 return (
                   <div
                     key={virtualRow.key}
-                    className="absolute left-0 right-0 px-3"
+                    className="absolute left-0 right-0 px-2"
                     style={{
                       transform: `translateY(${virtualRow.start}px)`,
                       height: `${virtualRow.size}px`,
@@ -301,15 +301,18 @@ export function EnhancedExecutionsTable({
                   >
                     <div
                       className={cn(
-                        "grid h-full cursor-pointer items-center rounded-lg px-3 transition-colors",
-                        "bg-card hover:bg-[var(--row-hover-bg)] dark:hover:bg-[var(--dark-row-hover-bg)]"
+                        "grid h-full cursor-pointer items-center rounded-md px-3 transition-all duration-200 relative overflow-hidden group",
+                        "bg-card border border-transparent hover:border-border/60 hover:shadow-sm hover:bg-card"
                       )}
                       style={{ gridTemplateColumns: COLUMN_TEMPLATE }}
                       onMouseEnter={() => setHoveredRow(execution.execution_id)}
                       onMouseLeave={() => setHoveredRow(null)}
                       onClick={() => onExecutionClick?.(execution)}
                     >
-                      <div className="flex items-center">
+                      {/* Hover Accent Bar */}
+                      <div className="absolute left-0 top-0 bottom-0 w-0.5 bg-primary opacity-0 group-hover:opacity-100 transition-opacity" />
+
+                      <div className="flex items-center pl-2">
                         <StatusPill status={execution.status} />
                       </div>
 
@@ -332,13 +335,13 @@ export function EnhancedExecutionsTable({
                       </div>
 
                       <div className="flex items-center">
-                        <span className="text-body-small">
+                        <span className="text-xs text-muted-foreground font-mono">
                           {execution.relative_time}
                         </span>
                       </div>
 
                       <div className="flex items-center justify-end">
-                        <span className="font-mono text-body-small">
+                        <span className="font-mono text-xs text-foreground">
                           {execution.duration_display}
                         </span>
                       </div>
@@ -350,7 +353,7 @@ export function EnhancedExecutionsTable({
                       </div>
 
                       <div className="flex items-center">
-                        <span className="font-mono text-body-small">
+                        <span className="font-mono text-xs text-muted-foreground group-hover:text-foreground transition-colors">
                           …{execution.execution_id.slice(-8)}
                         </span>
                       </div>
diff --git a/control-plane/web/client/src/components/Navigation/SidebarNew.tsx b/control-plane/web/client/src/components/Navigation/SidebarNew.tsx
index a315fcd2..038e7db1 100644
--- a/control-plane/web/client/src/components/Navigation/SidebarNew.tsx
+++ b/control-plane/web/client/src/components/Navigation/SidebarNew.tsx
@@ -14,6 +14,7 @@ import {
   useSidebar,
 } from "@/components/ui/sidebar";
 import { Icon } from "@/components/ui/icon";
+import { cn } from "@/lib/utils";
 
 interface SidebarNewProps {
   sections: NavigationSection[];
@@ -24,19 +25,19 @@ export function SidebarNew({ sections }: SidebarNewProps) {
   const isCollapsed = state === "collapsed";
 
   return (
-    <Sidebar collapsible="icon">
+    <Sidebar collapsible="icon" className="border-r border-border/40 bg-sidebar/95 backdrop-blur supports-[backdrop-filter]:bg-sidebar/60">
       {/* Header - Add bottom spacing and subtle border separator for visual hierarchy */}
-      <SidebarHeader className="pb-4 border-b border-border-secondary">
+      <SidebarHeader className="pb-3 border-b border-border/40">
         <SidebarMenu>
           <SidebarMenuItem>
-            <SidebarMenuButton size="lg" asChild>
+            <SidebarMenuButton size="lg" asChild className="active:scale-[0.98] transition-transform">
               <NavLink to="/dashboard">
-                <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground shadow-sm">
                   <Icon name="dashboard" size={16} />
                 </div>
                 <div className="grid flex-1 text-left text-sm leading-tight">
-                  <span className="truncate font-semibold">AgentField</span>
-                  <span className="truncate text-xs">Open Control Plane</span>
+                  <span className="truncate font-semibold tracking-tight">AgentField</span>
+                  <span className="truncate text-[10px] text-muted-foreground font-mono">v1.0.0</span>
                 </div>
               </NavLink>
             </SidebarMenuButton>
@@ -45,15 +46,15 @@ export function SidebarNew({ sections }: SidebarNewProps) {
       </SidebarHeader>
 
       {/* Content - Add spacing between groups */}
-      <SidebarContent className="space-y-6">
+      <SidebarContent className="space-y-4 px-2">
         {sections.map((section) => (
-          <SidebarGroup key={section.id} className="space-y-1">
+          <SidebarGroup key={section.id} className="space-y-0.5">
             {/* Apply caption styling for clear header differentiation */}
-            <SidebarGroupLabel className="text-caption text-nav-text-tertiary">
+            <SidebarGroupLabel className="text-[10px] uppercase tracking-wider font-semibold text-muted-foreground/70 px-2 mb-1">
               {section.title}
             </SidebarGroupLabel>
             {/* Add gap after header */}
-            <SidebarGroupContent className="mt-4">
+            <SidebarGroupContent>
               <SidebarMenu>
                 {section.items.map((item) => (
                   <SidebarMenuItem key={item.id}>
@@ -62,8 +63,9 @@ export function SidebarNew({ sections }: SidebarNewProps) {
                         isActive={false}
                         tooltip={isCollapsed ? item.label : undefined}
                         disabled
+                        className="h-8 text-[13px]"
                       >
-                        {item.icon && <Icon name={item.icon} size={16} />}
+                        {item.icon && <Icon name={item.icon} size={15} />}
                         <span>{item.label}</span>
                       </SidebarMenuButton>
                     ) : (
@@ -73,9 +75,18 @@ export function SidebarNew({ sections }: SidebarNewProps) {
                             asChild
                             isActive={isActive}
                             tooltip={isCollapsed ? item.label : undefined}
+                            className={cn(
+                              "h-8 text-[13px] transition-all duration-200 relative",
+                              isActive
+                                ? "bg-sidebar-accent text-sidebar-accent-foreground font-medium shadow-sm"
+                                : "text-muted-foreground hover:text-foreground hover:bg-sidebar-accent/50"
+                            )}
                           >
-                            <span className="flex items-center gap-2">
-                              {item.icon && <Icon name={item.icon} size={16} />}
+                            <span className="flex items-center gap-2.5">
+                              {isActive && (
+                                <div className="absolute left-0 top-1/2 -translate-y-1/2 h-4 w-0.5 bg-primary rounded-r-full" />
+                              )}
+                              {item.icon && <Icon name={item.icon} size={15} className={cn(isActive ? "text-primary" : "text-muted-foreground")} />}
                               <span>{item.label}</span>
                             </span>
                           </SidebarMenuButton>
diff --git a/control-plane/web/client/src/components/SearchWithFilters.tsx b/control-plane/web/client/src/components/SearchWithFilters.tsx
index 006ff483..64b390a7 100644
--- a/control-plane/web/client/src/components/SearchWithFilters.tsx
+++ b/control-plane/web/client/src/components/SearchWithFilters.tsx
@@ -144,8 +144,13 @@ export function SearchWithFilters({
             />
           </div>
 
-          {/* Dropdown indicator */}
-          <div className="flex items-center pr-3">
+          {/* Command Hint & Dropdown indicator */}
+          <div className="flex items-center pr-3 gap-2">
+            {!inputValue && tags.length === 0 && (
+              <kbd className="pointer-events-none hidden h-5 select-none items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground opacity-100 sm:flex">
+                <span className="text-xs">⌘</span>K
+              </kbd>
+            )}
             <ChevronDown
               size={16}
               className={cn(
diff --git a/control-plane/web/client/src/components/WorkflowDAG/WorkflowNode.tsx b/control-plane/web/client/src/components/WorkflowDAG/WorkflowNode.tsx
index e3105242..4a1fef31 100644
--- a/control-plane/web/client/src/components/WorkflowDAG/WorkflowNode.tsx
+++ b/control-plane/web/client/src/components/WorkflowDAG/WorkflowNode.tsx
@@ -307,12 +307,12 @@ export const WorkflowNode = memo(({ data, selected }: WorkflowNodeProps) => {
   }
 
   const baseShadow =
-    "0 12px 24px -14px color-mix(in srgb, var(--foreground) 22%, transparent)";
+    "0 4px 12px -2px color-mix(in srgb, var(--foreground) 10%, transparent), 0 2px 6px -1px color-mix(in srgb, var(--foreground) 6%, transparent)";
   const accentShadow = `0 0 0 1px ${borderColor}`;
-  const glowShadow = isDimmed ? "" : `0 0 18px ${glowColor}`;
+  const glowShadow = isDimmed ? "" : `0 0 12px -2px ${glowColor}`;
   const compositeShadow = [accentShadow, baseShadow, glowShadow].filter(Boolean).join(", ");
 
-  const baseBackground = `linear-gradient(135deg, color-mix(in srgb, ${statusColorVar} 12%, transparent), var(--card))`;
+  const baseBackground = `linear-gradient(145deg, color-mix(in srgb, ${statusColorVar} 8%, transparent), var(--card))`;
   let background = baseBackground;
 
   if (!hasHighlight) {
@@ -357,22 +357,22 @@ export const WorkflowNode = memo(({ data, selected }: WorkflowNodeProps) => {
   return (
     <div
       className={cn(
-        "relative h-[100px] rounded-xl border-2 bg-card/95 backdrop-blur-sm transition-transform duration-200",
-        "cursor-pointer group overflow-hidden shadow-lg",
-        !isDimmed && "hover:scale-[1.02]"
+        "relative h-[100px] rounded-xl border bg-card/90 backdrop-blur-md transition-all duration-300 animate-fade-in",
+        "cursor-pointer group overflow-hidden",
+        !isDimmed && "hover:scale-[1.01] hover:shadow-xl"
       )}
       style={{
         width: `${nodeWidth}px`,
         borderColor,
         boxShadow: compositeShadow,
-        opacity: isDimmed ? 0.35 : 1,
+        opacity: isDimmed ? 0.4 : 1,
         filter: isDimmed ? "grayscale(65%) saturate(70%)" : undefined,
         background,
       }}
     >
       {/* Agent color left border accent */}
       <div
-        className="absolute left-0 top-0 bottom-0 w-1 rounded-l-xl"
+        className="absolute left-0 top-0 bottom-0 w-[3px] rounded-l-xl opacity-80"
         style={{
           background: `linear-gradient(to bottom, ${agentColor.primary}, ${agentColor.border})`,
         }}
diff --git a/control-plane/web/client/src/components/execution/ExecutionHeader.tsx b/control-plane/web/client/src/components/execution/ExecutionHeader.tsx
index 3b5178d9..64aa0fe4 100644
--- a/control-plane/web/client/src/components/execution/ExecutionHeader.tsx
+++ b/control-plane/web/client/src/components/execution/ExecutionHeader.tsx
@@ -10,7 +10,6 @@ import { useNavigate } from "react-router-dom";
 import type { WorkflowExecution } from "../../types/executions";
 import type { CanonicalStatus } from "../../utils/status";
 import { DIDDisplay } from "../did/DIDDisplay";
-import { Button } from "../ui/button";
 import StatusIndicator from "../ui/status-indicator";
 import { VerifiableCredentialBadge } from "../vc";
 import { cn } from "../../lib/utils";
@@ -54,10 +53,10 @@ function WebhookStat({
 
   return (
     <div className="flex flex-col gap-1">
-      <span className="text-[10px] uppercase tracking-wide text-muted-foreground/80">
+      <span className="text-label text-muted-foreground/80">
         {label}
       </span>
-      <span className={cn("text-sm font-medium", toneClasses[tone] ?? toneClasses.muted)}>
+      <span className={cn("text-sm font-medium font-mono", toneClasses[tone] ?? toneClasses.muted)}>
         {value}
       </span>
     </div>
@@ -102,8 +101,6 @@ export function ExecutionHeader({
 }: ExecutionHeaderProps) {
   const navigate = useNavigate();
   const normalizedStatus = normalizeStatus(execution.status);
-  const statusLabel =
-    normalizedStatus.charAt(0).toUpperCase() + normalizedStatus.slice(1);
   const workflowTags = execution.workflow_tags ?? [];
   const webhookEvents = Array.isArray(execution.webhook_events)
     ? [...execution.webhook_events].sort(
@@ -134,7 +131,7 @@ export function ExecutionHeader({
     : webhookSuccessCount > 0
       ? `${webhookSuccessCount} delivered`
       : webhookPending
-        ? "Pending webhook"
+        ? "Pending"
         : "Registered";
 
   const handleNavigateBack = () => {
@@ -152,266 +149,269 @@ export function ExecutionHeader({
     navigate(`/executions?session_id=${execution.session_id}`);
 
   return (
-    <div className="space-y-4">
-      {/* Back Navigation */}
-      <div className="flex items-center">
-        <Button
-          variant="ghost"
-          size="sm"
+    <div className="space-y-6">
+      {/* Breadcrumb Navigation */}
+      <div className="flex items-center text-sm text-muted-foreground">
+        <button
           onClick={handleNavigateBack}
-          className="flex items-center gap-2 text-muted-foreground hover:text-foreground -ml-2"
+          className="flex items-center gap-1 hover:text-foreground transition-colors"
         >
-          <ArrowLeft className="w-4 h-4" />
-          Back to Executions
-        </Button>
+          <ArrowLeft className="w-3.5 h-3.5" />
+          Executions
+        </button>
+        <span className="mx-2 text-border">/</span>
+        <span className="font-mono text-foreground">{truncateId(execution.execution_id)}</span>
       </div>
 
-      {/* Main Header - Clean Linear Style */}
-      <div className="space-y-3">
-        <div className="flex flex-wrap items-center gap-3 text-body">
-          <h1 className="text-heading-1">
-            {execution.reasoner_id}
-          </h1>
-          <StatusIndicator
-            status={normalizedStatus}
-            animated={normalizedStatus === "running"}
-            className="text-base"
-          />
-          <span className="text-body">{statusLabel}</span>
-          {webhookRegistered && (
-            <HoverCard>
-              <HoverCardTrigger asChild>
-                <Badge
-                  variant="outline"
-                  className={cn(
-                    "text-xs flex items-center gap-1 cursor-pointer",
-                    webhookFailureCount > 0
-                      ? "border-destructive/40 text-destructive"
-                      : webhookSuccessCount > 0
-                        ? "border-emerald-500/40 text-emerald-500"
-                        : "border-border text-muted-foreground",
-                  )}
-                >
-                  <RadioTower className="h-3 w-3" />
-                  {webhookBadgeLabel}
-                </Badge>
-              </HoverCardTrigger>
-              <HoverCardContent className="w-80 space-y-3">
-                <div className="flex items-start justify-between gap-3">
-                  <div>
-                    <p className="text-body font-medium text-text-primary">
-                      {webhookPending
-                        ? "Awaiting first delivery"
-                        : latestWebhookEvent
-                          ? `Last webhook ${formatWebhookStatusLabel(latestWebhookEvent.status)}`
-                          : "Webhook registered"}
-                    </p>
-                    <p className="text-body-small">
-                      {webhookPending &&
-                        "We will display the latest delivery details as soon as the callback is reported."}
-                      {!webhookPending && latestWebhookEvent && (
-                        <>
-                          {formatWebhookStatusLabel(latestWebhookEvent.status)}
-                          {latestWebhookEvent.http_status ? ` • HTTP ${latestWebhookEvent.http_status}` : ""}
-                        </>
+      {/* Main Header */}
+      <div className="space-y-6">
+        {/* Top Row: Title & Status */}
+        <div className="flex flex-col gap-4 md:flex-row md:items-start md:justify-between">
+          <div className="space-y-1">
+            <div className="flex items-center gap-3">
+              <h1 className="text-heading-2 font-semibold tracking-tight">
+                {execution.reasoner_id}
+              </h1>
+              <StatusIndicator
+                status={normalizedStatus}
+                animated={normalizedStatus === "running"}
+                className="text-sm"
+              />
+              {webhookRegistered && (
+                <HoverCard>
+                  <HoverCardTrigger asChild>
+                    <Badge
+                      variant="outline"
+                      className={cn(
+                        "cursor-pointer gap-1.5 font-mono",
+                        webhookFailureCount > 0
+                          ? "border-destructive/40 text-destructive"
+                          : webhookSuccessCount > 0
+                            ? "border-emerald-500/40 text-emerald-500"
+                            : "border-border text-muted-foreground",
                       )}
-                      {!webhookPending && !latestWebhookEvent && "No deliveries recorded yet."}
-                    </p>
-                  </div>
-                  {latestWebhookTimestamp && (
-                    <span className="text-body-small text-muted-foreground whitespace-nowrap">
-                      {latestWebhookTimestamp}
-                    </span>
-                  )}
-                </div>
+                    >
+                      <RadioTower className="h-3 w-3" />
+                      {webhookBadgeLabel}
+                    </Badge>
+                  </HoverCardTrigger>
+                  <HoverCardContent className="w-80 space-y-3">
+                    <div className="flex items-start justify-between gap-3">
+                      <div>
+                        <p className="text-sm font-medium text-foreground">
+                          {webhookPending
+                            ? "Awaiting first delivery"
+                            : latestWebhookEvent
+                              ? `Last webhook ${formatWebhookStatusLabel(latestWebhookEvent.status)}`
+                              : "Webhook registered"}
+                        </p>
+                        <p className="text-xs text-muted-foreground mt-1">
+                          {webhookPending &&
+                            "We will display the latest delivery details as soon as the callback is reported."}
+                          {!webhookPending && latestWebhookEvent && (
+                            <>
+                              {formatWebhookStatusLabel(latestWebhookEvent.status)}
+                              {latestWebhookEvent.http_status ? ` • HTTP ${latestWebhookEvent.http_status}` : ""}
+                            </>
+                          )}
+                          {!webhookPending && !latestWebhookEvent && "No deliveries recorded yet."}
+                        </p>
+                      </div>
+                      {latestWebhookTimestamp && (
+                        <span className="text-xs text-muted-foreground whitespace-nowrap font-mono">
+                          {latestWebhookTimestamp}
+                        </span>
+                      )}
+                    </div>
 
-                <div className="grid grid-cols-3 gap-2">
-                  <WebhookStat
-                    label="Delivered"
-                    value={webhookSuccessCount}
-                    tone={webhookSuccessCount > 0 ? "success" : "muted"}
-                  />
-                  <WebhookStat
-                    label="Failed"
-                    value={webhookFailureCount}
-                    tone={webhookFailureCount > 0 ? "danger" : "muted"}
-                  />
-                  <WebhookStat
-                    label={"Attempts"}
-                    value={webhookSuccessCount + webhookFailureCount}
-                  />
-                </div>
+                    <div className="grid grid-cols-3 gap-2 pt-2 border-t border-border/50">
+                      <WebhookStat
+                        label="Delivered"
+                        value={webhookSuccessCount}
+                        tone={webhookSuccessCount > 0 ? "success" : "muted"}
+                      />
+                      <WebhookStat
+                        label="Failed"
+                        value={webhookFailureCount}
+                        tone={webhookFailureCount > 0 ? "danger" : "muted"}
+                      />
+                      <WebhookStat
+                        label="Attempts"
+                        value={webhookSuccessCount + webhookFailureCount}
+                      />
+                    </div>
 
-                {latestWebhookEvent?.error_message && (
-                  <div className="text-body-small text-destructive bg-destructive/10 border border-destructive/20 rounded px-3 py-2">
-                    {latestWebhookEvent.error_message}
-                  </div>
-                )}
-              </HoverCardContent>
-            </HoverCard>
-          )}
-        </div>
+                    {latestWebhookEvent?.error_message && (
+                      <div className="text-xs font-mono text-destructive bg-destructive/5 border border-destructive/20 rounded px-2 py-1.5 break-all">
+                        {latestWebhookEvent.error_message}
+                      </div>
+                    )}
+                  </HoverCardContent>
+                </HoverCard>
+              )}
+            </div>
 
-        <div className="flex flex-wrap items-center gap-4 text-body-small">
-          <div className="flex items-center gap-2 group">
-            <span>Agent:</span>
-            <code className="font-mono text-xs text-foreground bg-muted/30 px-1.5 py-0.5 rounded">
-              {execution.agent_node_id}
-            </code>
-            <CopyButton
-              value={execution.agent_node_id}
-              variant="ghost"
-              size="icon"
-              className="h-4 w-4 p-0 opacity-0 transition-opacity group-hover:opacity-100 [&_svg]:h-3 [&_svg]:w-3"
-              tooltip="Copy agent node ID"
-            />
+            {/* Tags Row */}
+            {workflowTags.length > 0 && (
+              <div className="flex flex-wrap gap-2 pt-1">
+                {workflowTags.map((tag) => (
+                  <Badge key={tag} variant="secondary" className="font-normal text-[10px] px-1.5 py-0">
+                    {tag}
+                  </Badge>
+                ))}
+              </div>
+            )}
           </div>
 
+          {/* Primary Actions / VC Status */}
           <div className="flex items-center gap-2">
-            <span>DID:</span>
-            <DIDDisplay
-              nodeId={execution.agent_node_id}
-              variant="inline"
-              className="text-xs"
-            />
-          </div>
-
-          <div className="flex items-center gap-2 group">
-            <span>ID:</span>
-            <code className="font-mono text-xs text-foreground bg-muted/30 px-1.5 py-0.5 rounded">
-              {truncateId(execution.execution_id)}
-            </code>
-            <CopyButton
-              value={execution.execution_id}
-              variant="ghost"
-              size="icon"
-              className="h-4 w-4 p-0 opacity-0 transition-opacity group-hover:opacity-100 [&_svg]:h-3 [&_svg]:w-3"
-              tooltip="Copy execution ID"
-            />
+             {vcLoading ? (
+                <Badge variant="outline" className="animate-pulse">Loading VC...</Badge>
+              ) : vcStatus?.has_vc ? (
+                <VerifiableCredentialBadge
+                  hasVC={vcStatus.has_vc}
+                  status={vcStatus.status}
+                  vcData={vcStatus as any}
+                  executionId={execution.execution_id}
+                  showCopyButton={false}
+                  showVerifyButton={false}
+                />
+              ) : null}
           </div>
+        </div>
 
-          {vcLoading ? (
-            <div className="flex items-center gap-2">
-              <span>VC:</span>
-              <span className="text-body-small">Loading…</span>
+        {/* Metadata Grid - The "Developer Dashboard" Look */}
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 p-4 rounded-lg border border-border/60 bg-muted/20">
+          {/* Column 1: Identity */}
+          <div className="space-y-3">
+            <div className="space-y-1">
+              <div className="text-label">Execution ID</div>
+              <div className="flex items-center gap-2 group">
+                <code className="font-mono text-xs text-foreground">
+                  {execution.execution_id}
+                </code>
+                <CopyButton
+                  value={execution.execution_id}
+                  variant="ghost"
+                  size="icon-sm"
+                  className="opacity-0 group-hover:opacity-100 transition-opacity"
+                />
+              </div>
             </div>
-          ) : vcStatus?.has_vc ? (
-            <div className="flex items-center gap-2">
-              <span>VC:</span>
-              <VerifiableCredentialBadge
-                hasVC={vcStatus.has_vc}
-                status={vcStatus.status}
-                vcData={vcStatus as any}
-                executionId={execution.execution_id}
-                showCopyButton={false}
-                showVerifyButton={false}
-              />
+            <div className="space-y-1">
+              <div className="text-label">Agent Node</div>
+              <div className="flex items-center gap-2 group">
+                <code className="font-mono text-xs text-foreground">
+                  {truncateId(execution.agent_node_id)}
+                </code>
+                <DIDDisplay
+                  nodeId={execution.agent_node_id}
+                  variant="inline"
+                  className="text-[10px]"
+                />
+                <CopyButton
+                  value={execution.agent_node_id}
+                  variant="ghost"
+                  size="icon-sm"
+                  className="opacity-0 group-hover:opacity-100 transition-opacity"
+                />
+              </div>
             </div>
-          ) : null}
-        </div>
-
-        <div className="flex flex-wrap items-center gap-4 text-body-small">
-          <div className="flex items-center gap-2 group">
-            <span>Workflow:</span>
-            <button
-              type="button"
-              onClick={handleNavigateWorkflow}
-              className="font-medium text-foreground hover:underline"
-            >
-              {execution.workflow_name ?? truncateId(execution.workflow_id)}
-            </button>
-            <CopyButton
-              value={execution.workflow_id}
-              variant="ghost"
-              size="icon"
-              className="h-4 w-4 p-0 opacity-0 transition-opacity group-hover:opacity-100 [&_svg]:h-3 [&_svg]:w-3"
-              tooltip="Copy workflow ID"
-            />
           </div>
 
-          {execution.session_id && (
-            <div className="flex items-center gap-2 group">
-              <span>Session:</span>
-              <button
-                type="button"
-                onClick={handleNavigateSession}
-                className="font-medium text-foreground hover:underline"
-              >
-                {truncateId(execution.session_id)}
-              </button>
-              <CopyButton
-                value={execution.session_id}
-                variant="ghost"
-                size="icon"
-                className="h-4 w-4 p-0 opacity-0 transition-opacity group-hover:opacity-100 [&_svg]:h-3 [&_svg]:w-3"
-                tooltip="Copy session ID"
-              />
+          {/* Column 2: Context */}
+          <div className="space-y-3">
+            <div className="space-y-1">
+              <div className="text-label">Workflow</div>
+              <div className="flex items-center gap-2 group">
+                <button
+                  type="button"
+                  onClick={handleNavigateWorkflow}
+                  className="font-medium text-sm text-foreground hover:underline truncate max-w-[180px] text-left"
+                >
+                  {execution.workflow_name ?? truncateId(execution.workflow_id)}
+                </button>
+                <CopyButton
+                  value={execution.workflow_id}
+                  variant="ghost"
+                  size="icon-sm"
+                  className="opacity-0 group-hover:opacity-100 transition-opacity"
+                />
+              </div>
             </div>
-          )}
-
-          <div className="flex items-center gap-2 group">
-            <span>Request:</span>
-            <code className="font-mono text-xs text-foreground bg-muted/30 px-1.5 py-0.5 rounded">
-              {execution.agentfield_request_id
-                ? truncateId(execution.agentfield_request_id)
-                : "n/a"}
-            </code>
-            {execution.agentfield_request_id && (
-              <CopyButton
-                value={execution.agentfield_request_id}
-                variant="ghost"
-                size="icon"
-                className="h-4 w-4 p-0 opacity-0 transition-opacity group-hover:opacity-100 [&_svg]:h-3 [&_svg]:w-3"
-                tooltip="Copy request ID"
-              />
+            {execution.session_id && (
+              <div className="space-y-1">
+                <div className="text-label">Session</div>
+                <div className="flex items-center gap-2 group">
+                  <button
+                    type="button"
+                    onClick={handleNavigateSession}
+                    className="font-mono text-xs text-foreground hover:underline"
+                  >
+                    {truncateId(execution.session_id)}
+                  </button>
+                  <CopyButton
+                    value={execution.session_id}
+                    variant="ghost"
+                    size="icon-sm"
+                    className="opacity-0 group-hover:opacity-100 transition-opacity"
+                  />
+                </div>
+              </div>
             )}
           </div>
-        </div>
 
-        {workflowTags.length > 0 && (
-          <div className="flex flex-wrap items-center gap-2 text-body-small">
-            <span>Tags:</span>
-            <div className="flex flex-wrap gap-2">
-              {workflowTags.map((tag) => (
-                <Badge key={tag} variant="secondary" className="font-normal">
-                  {tag}
-                </Badge>
-              ))}
+          {/* Column 3: Performance */}
+          <div className="space-y-3">
+            <div className="space-y-1">
+              <div className="text-label">Duration</div>
+              <div className="flex items-center gap-1.5 text-sm font-medium font-mono">
+                <Clock className="w-3.5 h-3.5 text-muted-foreground" />
+                {formatDuration(execution.duration_ms)}
+              </div>
+            </div>
+            <div className="space-y-1">
+              <div className="text-label">Retries</div>
+              <div className="flex items-center gap-1.5 text-sm font-medium font-mono">
+                <RotateCcw className="w-3.5 h-3.5 text-muted-foreground" />
+                {execution.retry_count}
+              </div>
             </div>
-          </div>
-        )}
-
-        <div className="flex flex-wrap items-center gap-6 pt-2 text-sm">
-          <div className="flex items-center gap-2">
-            <Clock className="w-4 h-4 text-muted-foreground" />
-            <span className="text-muted-foreground">Duration:</span>
-            <span className="font-medium text-foreground">
-              {formatDuration(execution.duration_ms)}
-            </span>
-          </div>
-
-          <div className="flex items-center gap-2">
-            <ArrowDown className="w-4 h-4 text-muted-foreground" />
-            <span className="text-muted-foreground">Input:</span>
-            <span className="font-medium text-foreground">
-              {formatBytes(execution.input_size)}
-            </span>
-          </div>
-
-          <div className="flex items-center gap-2">
-            <ArrowUp className="w-4 h-4 text-muted-foreground" />
-            <span className="text-muted-foreground">Output:</span>
-            <span className="font-medium text-foreground">
-              {formatBytes(execution.output_size)}
-            </span>
           </div>
 
-          <div className="flex items-center gap-2">
-            <RotateCcw className="w-4 h-4 text-muted-foreground" />
-            <span className="text-muted-foreground">Retries:</span>
-            <span className="font-medium text-foreground">
-              {execution.retry_count}
-            </span>
+          {/* Column 4: I/O */}
+          <div className="space-y-3">
+            <div className="space-y-1">
+              <div className="text-label">Data Transfer</div>
+              <div className="flex items-center gap-3 text-xs font-mono">
+                <div className="flex items-center gap-1">
+                  <ArrowDown className="w-3 h-3 text-muted-foreground" />
+                  <span>{formatBytes(execution.input_size)}</span>
+                </div>
+                <div className="flex items-center gap-1">
+                  <ArrowUp className="w-3 h-3 text-muted-foreground" />
+                  <span>{formatBytes(execution.output_size)}</span>
+                </div>
+              </div>
+            </div>
+            <div className="space-y-1">
+              <div className="text-label">Request ID</div>
+              <div className="flex items-center gap-2 group">
+                <code className="font-mono text-xs text-muted-foreground">
+                  {execution.agentfield_request_id
+                    ? truncateId(execution.agentfield_request_id)
+                    : "n/a"}
+                </code>
+                {execution.agentfield_request_id && (
+                  <CopyButton
+                    value={execution.agentfield_request_id}
+                    variant="ghost"
+                    size="icon-sm"
+                    className="opacity-0 group-hover:opacity-100 transition-opacity"
+                  />
+                )}
+              </div>
+            </div>
           </div>
         </div>
       </div>
diff --git a/control-plane/web/client/src/components/ui/badge.tsx b/control-plane/web/client/src/components/ui/badge.tsx
index b57b3b2b..1f867f47 100644
--- a/control-plane/web/client/src/components/ui/badge.tsx
+++ b/control-plane/web/client/src/components/ui/badge.tsx
@@ -13,7 +13,7 @@ import {
 import type { IconComponent, IconWeight } from "@/components/ui/icon-bridge"
 
 const badgeVariants = cva(
-  "inline-flex items-center gap-1.5 rounded-lg border border-transparent px-2.5 py-1 text-xs font-medium transition-all duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+  "inline-flex items-center gap-1.5 rounded-md border border-transparent px-2 py-0.5 text-xs font-medium transition-all duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
   {
     variants: {
       variant: {
@@ -31,32 +31,32 @@ const badgeVariants = cva(
         outline:
           "text-text-primary border border-border bg-transparent hover:bg-bg-hover shadow-sm",
         metadata:
-          "rounded-md bg-muted/40 text-text-secondary border border-border/60 px-2 py-1 text-body-small font-medium",
+          "rounded-md bg-muted/40 text-text-secondary border border-border/60 px-1.5 py-0.5 text-[10px] font-medium font-mono",
         count:
-          "rounded-full bg-bg-secondary text-text-primary border border-border-secondary px-2 py-0.5 text-caption font-semibold uppercase tracking-wide",
+          "rounded-full bg-bg-secondary text-text-primary border border-border-secondary px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide",
         pill:
-          "rounded-full bg-muted/30 text-text-primary border border-border/40 px-3 py-1 text-body-small",
+          "rounded-full bg-muted/30 text-text-primary border border-border/40 px-2.5 py-0.5 text-[11px]",
 
         // Status variants with standardized colors and icons
         success:
-          cn(getStatusBadgeClasses("success" satisfies StatusTone)),
+          cn(getStatusBadgeClasses("success" satisfies StatusTone), "font-mono tracking-tight"),
         failed:
-          cn(getStatusBadgeClasses("error" satisfies StatusTone)),
+          cn(getStatusBadgeClasses("error" satisfies StatusTone), "font-mono tracking-tight"),
         running:
-          cn(getStatusBadgeClasses("info" satisfies StatusTone)),
+          cn(getStatusBadgeClasses("info" satisfies StatusTone), "font-mono tracking-tight"),
         pending:
-          cn(getStatusBadgeClasses("warning" satisfies StatusTone)),
+          cn(getStatusBadgeClasses("warning" satisfies StatusTone), "font-mono tracking-tight"),
 
         // Additional status variants for degraded states
         degraded:
-          cn(getStatusBadgeClasses("warning" satisfies StatusTone)),
+          cn(getStatusBadgeClasses("warning" satisfies StatusTone), "font-mono tracking-tight"),
         unknown:
-          cn(getStatusBadgeClasses("neutral" satisfies StatusTone)),
+          cn(getStatusBadgeClasses("neutral" satisfies StatusTone), "font-mono tracking-tight"),
       },
       size: {
-        sm: "px-2 py-0.5 text-xs",
-        md: "px-2.5 py-1 text-xs",
-        lg: "px-3 py-1.5 text-sm",
+        sm: "px-1.5 py-0 text-[10px]",
+        md: "px-2 py-0.5 text-xs",
+        lg: "px-3 py-1 text-sm",
       },
     },
     defaultVariants: {
diff --git a/control-plane/web/client/src/components/ui/button.tsx b/control-plane/web/client/src/components/ui/button.tsx
index fe87aacc..9cfef372 100644
--- a/control-plane/web/client/src/components/ui/button.tsx
+++ b/control-plane/web/client/src/components/ui/button.tsx
@@ -5,7 +5,7 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "@/lib/utils"
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 active:scale-[0.98] active:translate-y-[0.5px]",
   {
     variants: {
       variant: {
@@ -21,10 +21,11 @@ const buttonVariants = cva(
         link: "text-primary underline-offset-4 hover:underline",
       },
       size: {
-        default: "h-9 px-4 py-2",
-        sm: "h-8 rounded-md px-3 text-sm",
+        default: "h-8 px-4 py-2", // Compact default for developer tools
+        sm: "h-7 rounded-md px-3 text-xs",
         lg: "h-10 rounded-md px-8 text-base",
-        icon: "h-9 w-9",
+        icon: "h-8 w-8",
+        "icon-sm": "h-7 w-7",
       },
     },
     defaultVariants: {
diff --git a/control-plane/web/client/src/index.css b/control-plane/web/client/src/index.css
index 7e83ca4e..22258801 100644
--- a/control-plane/web/client/src/index.css
+++ b/control-plane/web/client/src/index.css
@@ -187,6 +187,15 @@ main:focus,
   letter-spacing: 0.05em;
 }
 
+.text-label {
+  font-size: 10px;
+  line-height: 1.2;
+  color: var(--text-tertiary);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
 /* Interactive elements */
 .interactive-hover {
   transition: all var(--transition-fast);
diff --git a/control-plane/web/client/src/pages/EnhancedDashboardPage.tsx b/control-plane/web/client/src/pages/EnhancedDashboardPage.tsx
index 32285af9..3cd42123 100644
--- a/control-plane/web/client/src/pages/EnhancedDashboardPage.tsx
+++ b/control-plane/web/client/src/pages/EnhancedDashboardPage.tsx
@@ -242,13 +242,13 @@ export function EnhancedDashboardPage() {
   const generatedAt = formatTimestamp(data.generated_at);
 
   return (
-    <div className="space-y-8">
+    <div className="space-y-6 animate-fade-in">
       <PageHeader
         title="Dashboard"
         description="Monitor agent health, workflow performance, and system throughput across your distributed cluster."
         aside={
           <div className="flex flex-wrap items-center gap-2">
-            <Badge variant="pill" size="sm">
+            <Badge variant="pill" size="sm" className="font-mono">
               {generatedAt}
             </Badge>
             <Button
@@ -276,30 +276,32 @@ export function EnhancedDashboardPage() {
         />
       )}
 
-      <OverviewStrip
-        overview={data.overview}
-        trends={data.execution_trends.last_24h}
-      />
+      <div className="animate-slide-in" style={{ animationDelay: "50ms" }}>
+        <OverviewStrip
+          overview={data.overview}
+          trends={data.execution_trends.last_24h}
+        />
+      </div>
 
       <ResponsiveGrid
         columns={{ base: 1, md: 6, lg: 12 }}
         flow="dense"
         className="auto-rows-[minmax(220px,auto)] md:auto-rows-[minmax(240px,auto)] lg:auto-rows-[minmax(260px,auto)]"
-        gap="lg"
+        gap="md"
       >
-        <ResponsiveGrid.Item span={{ md: 6, lg: 7, xl: 8, "2xl": 7 }}>
+        <ResponsiveGrid.Item span={{ md: 6, lg: 7, xl: 8, "2xl": 7 }} className="animate-slide-in" style={{ animationDelay: "100ms" }}>
           <ExecutionTrendsCard
             trendPoints={data.execution_trends.last_7_days}
             windowMetrics={data.execution_trends.last_24h}
           />
         </ResponsiveGrid.Item>
-        <ResponsiveGrid.Item span={{ md: 3, lg: 5, xl: 4, "2xl": 5 }}>
+        <ResponsiveGrid.Item span={{ md: 3, lg: 5, xl: 4, "2xl": 5 }} className="animate-slide-in" style={{ animationDelay: "150ms" }}>
           <IncidentPanel incidents={data.incidents} />
         </ResponsiveGrid.Item>
-        <ResponsiveGrid.Item span={{ md: 3, lg: 7, xl: 6, "2xl": 7 }}>
+        <ResponsiveGrid.Item span={{ md: 3, lg: 7, xl: 6, "2xl": 7 }} className="animate-slide-in" style={{ animationDelay: "200ms" }}>
           <WorkflowInsightsPanel insights={data.workflows} />
         </ResponsiveGrid.Item>
-        <ResponsiveGrid.Item span={{ md: 6, lg: 5, xl: 6, "2xl": 5 }}>
+        <ResponsiveGrid.Item span={{ md: 6, lg: 5, xl: 6, "2xl": 5 }} className="animate-slide-in" style={{ animationDelay: "250ms" }}>
           <ReasonerActivityPanel
             reasoners={reasonerStats}
             agentSummary={data.agent_health}
@@ -396,13 +398,13 @@ function ExecutionTrendsCard({
       interactive={false}
       className="flex h-full flex-col"
     >
-      <CardHeader className="flex flex-row items-center justify-between space-y-0">
+      <CardHeader className="flex flex-row items-center justify-between space-y-0 p-5 pb-2">
         <CardTitle className="flex items-center gap-2">
           <BarChart3 className="h-4 w-4" /> Velocity & reliability
         </CardTitle>
         <Badge variant="pill">Last 7 days</Badge>
       </CardHeader>
-      <CardContent className="flex flex-1 flex-col gap-8">
+      <CardContent className="flex flex-1 flex-col gap-6 p-5 pt-0">
         <div className="h-52 w-full">
           <ResponsiveContainer width="100%" height="100%">
             <ComposedChart
@@ -507,11 +509,11 @@ interface MetricTileProps {
 
 function MetricTile({ label, value, helper }: MetricTileProps) {
   return (
-    <div className="rounded-xl border border-border/60 bg-muted/20 px-4 py-3">
-      <p className="text-caption text-text-tertiary">{label}</p>
-      <p className="mt-2 text-heading-2">{value}</p>
+    <div className="rounded-xl border border-border/60 bg-muted/20 px-4 py-3 transition-all hover:bg-muted/30">
+      <p className="text-label">{label}</p>
+      <p className="mt-2 text-heading-2 font-mono tracking-tight">{value}</p>
       {helper && (
-        <p className="text-body-small text-text-secondary mt-1">{helper}</p>
+        <p className="text-xs text-text-secondary mt-1 font-medium">{helper}</p>
       )}
     </div>
   );
@@ -521,6 +523,24 @@ interface WorkflowInsightsPanelProps {
   insights: EnhancedDashboardResponse["workflows"];
 }
 
+function ProgressBar({ value, className }: { value: number; className?: string }) {
+  const colorClass =
+    value >= 95
+      ? "bg-emerald-500"
+      : value >= 80
+        ? "bg-amber-500"
+        : "bg-destructive";
+
+  return (
+    <div className={cn("h-1.5 w-full rounded-full bg-muted overflow-hidden", className)}>
+      <div
+        className={cn("h-full rounded-full transition-all duration-500", colorClass)}
+        style={{ width: `${Math.max(0, Math.min(100, value))}%` }}
+      />
+    </div>
+  );
+}
+
 function WorkflowInsightsPanel({ insights }: WorkflowInsightsPanelProps) {
   return (
     <Card
@@ -528,44 +548,53 @@ function WorkflowInsightsPanel({ insights }: WorkflowInsightsPanelProps) {
       interactive={false}
       className="flex h-full flex-col"
     >
-      <CardHeader>
+      <CardHeader className="p-5 pb-2">
         <CardTitle className="flex items-center gap-2">
           <Zap className="h-4 w-4" /> Workflow intelligence
         </CardTitle>
       </CardHeader>
-      <CardContent className="flex flex-1 flex-col min-h-0">
-        <ResponsiveGrid variant="detail" gap="lg" align="start" className="flex-1 min-h-0">
+      <CardContent className="flex flex-1 flex-col min-h-0 p-5 pt-0">
+        <ResponsiveGrid variant="detail" gap="md" align="start" className="flex-1 min-h-0">
           <InsightsGroup
             title="Top workflows"
             empty="No executions recorded in the last 7 days."
             items={insights.top_workflows}
-            render={(workflow: WorkflowStat) => (
+            render={(workflow: WorkflowStat, index: number) => (
               <Link
                 to={`/workflows/${workflow.workflow_id}/enhanced`}
                 className={cn(
-                  "block transition-colors hover:border-border hover:bg-muted/30 min-w-0",
+                  "group relative block transition-all hover:border-border hover:bg-muted/30 min-w-0",
                   cardVariants({ variant: "muted", interactive: false }),
-                  "px-3 py-3"
+                  "pl-10 pr-3 py-3"
                 )}
               >
-                <div className="space-y-1 text-sm text-foreground min-w-0">
-                  <p className="font-medium text-foreground truncate">
-                    {workflow.name || workflow.workflow_id}
-                  </p>
-                  <p className="text-body-small text-text-secondary">
-                    {numberFormatter.format(workflow.total_executions)} runs ·{" "}
-                    {formatPercentage(workflow.success_rate)} success
-                  </p>
+                {/* Rank Badge */}
+                <div className="absolute left-3 top-3 flex h-5 w-5 items-center justify-center rounded-full bg-background border border-border text-[10px] font-mono font-medium text-muted-foreground shadow-sm group-hover:border-primary/50 group-hover:text-primary transition-colors">
+                  {index + 1}
                 </div>
-                <div className="mt-2 min-w-0">
-                  <Badge
-                    variant="outline"
-                    className="inline-flex justify-start rounded-full text-[10px] leading-4 text-left max-w-full"
-                  >
-                    <span className="truncate">
-                      Last run {formatTimestamp(workflow.last_activity)}
+
+                <div className="space-y-2 min-w-0">
+                  <div className="flex justify-between items-start gap-2">
+                    <p className="font-medium text-sm text-foreground truncate">
+                      {workflow.name || workflow.workflow_id}
+                    </p>
+                    <span className="text-xs font-mono text-muted-foreground whitespace-nowrap">
+                      {numberFormatter.format(workflow.total_executions)} runs
                     </span>
-                  </Badge>
+                  </div>
+
+                  <div className="space-y-1">
+                    <div className="flex justify-between text-[10px] text-muted-foreground">
+                      <span>Success Rate</span>
+                      <span className={cn(
+                        "font-mono",
+                        workflow.success_rate >= 95 ? "text-emerald-500" : workflow.success_rate >= 80 ? "text-amber-500" : "text-destructive"
+                      )}>
+                        {formatPercentage(workflow.success_rate)}
+                      </span>
+                    </div>
+                    <ProgressBar value={workflow.success_rate} />
+                  </div>
                 </div>
               </Link>
             )}
@@ -580,21 +609,28 @@ function WorkflowInsightsPanel({ insights }: WorkflowInsightsPanelProps) {
                 <Link
                   to={`/executions/${run.execution_id}`}
                   className={cn(
-                    "block transition-colors hover:border-border hover:bg-muted/20 min-w-0",
+                    "group block transition-all hover:border-primary/30 hover:shadow-md min-w-0 relative overflow-hidden",
                     cardVariants({ variant: "muted", interactive: false }),
-                    "px-3 py-2 text-xs"
+                    "px-3 py-2.5 text-xs bg-background/50 backdrop-blur-sm border-primary/20"
                   )}
                 >
+                  <div className="absolute top-0 left-0 w-0.5 h-full bg-primary/50 group-hover:bg-primary transition-colors" />
                   <div className="flex items-center justify-between min-w-0 gap-2">
-                    <p className="font-medium text-foreground truncate">
-                      {run.name || run.workflow_id}
-                    </p>
-                    <span className="text-text-tertiary flex-shrink-0">
+                    <div className="flex items-center gap-2 min-w-0">
+                      <span className="relative flex h-2 w-2">
+                        <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-primary opacity-75"></span>
+                        <span className="relative inline-flex rounded-full h-2 w-2 bg-primary"></span>
+                      </span>
+                      <p className="font-medium text-foreground truncate">
+                        {run.name || run.workflow_id}
+                      </p>
+                    </div>
+                    <span className="text-primary font-mono text-[10px] flex-shrink-0 bg-primary/10 px-1.5 py-0.5 rounded-full">
                       {formatDuration(run.elapsed_ms)}
                     </span>
                   </div>
-                  <p className="mt-1 text-text-secondary truncate">
-                    {run.execution_id} · {run.reasoner_id}
+                  <p className="mt-1.5 pl-4 text-muted-foreground truncate font-mono text-[10px]">
+                    {run.execution_id}
                   </p>
                 </Link>
               )}
@@ -611,12 +647,19 @@ function WorkflowInsightsPanel({ insights }: WorkflowInsightsPanelProps) {
                     "px-3 py-2 text-xs min-w-0"
                   )}
                 >
-                  <p className="font-medium text-foreground truncate">
-                    {execution.name || execution.workflow_id}
-                  </p>
-                  <p className="mt-1 text-text-secondary truncate">
-                    {formatDuration(execution.duration_ms)} · Completed{" "}
-                    {formatTimestamp(execution.completed_at)}
+                  <div className="flex justify-between items-center gap-2">
+                    <p className="font-medium text-foreground truncate">
+                      {execution.name || execution.workflow_id}
+                    </p>
+                    <span className={cn(
+                      "font-mono text-[10px] px-1.5 py-0.5 rounded-full",
+                      execution.duration_ms > 60000 ? "bg-amber-500/10 text-amber-600" : "bg-muted text-muted-foreground"
+                    )}>
+                      {formatDuration(execution.duration_ms)}
+                    </span>
+                  </div>
+                  <p className="mt-1 text-muted-foreground truncate text-[10px]">
+                    Completed {formatTimestamp(execution.completed_at)}
                   </p>
                 </div>
               )}
@@ -633,7 +676,7 @@ interface InsightsGroupProps<T> {
   title: string;
   empty: string;
   items: T[];
-  render: (item: T) => React.ReactElement;
+  render: (item: T, index: number) => React.ReactElement;
 }
 
 function InsightsGroup<T>({
@@ -644,15 +687,15 @@ function InsightsGroup<T>({
 }: InsightsGroupProps<T>) {
   return (
     <div className="space-y-4">
-      <div className="flex items-center gap-2 text-caption text-text-tertiary">
-        <GitCommit className="h-4 w-4" />
+      <div className="flex items-center gap-2 text-label">
+        <GitCommit className="h-3.5 w-3.5" />
         {title}
       </div>
-      <div className="space-y-4">
+      <div className="space-y-3">
         {items.length === 0 ? (
-          <p className="text-body-small text-text-secondary">{empty}</p>
+          <p className="text-xs text-muted-foreground italic pl-1">{empty}</p>
         ) : (
-          items.map((item, index) => <div key={index}>{render(item)}</div>)
+          items.map((item, index) => <div key={index}>{render(item, index)}</div>)
         )}
       </div>
     </div>
@@ -670,12 +713,12 @@ function IncidentPanel({ incidents }: IncidentPanelProps) {
       interactive={false}
       className="flex h-full flex-col"
     >
-      <CardHeader className="pb-3">
+      <CardHeader className="p-5 pb-2">
         <CardTitle className="flex items-center gap-2">
           <AlertTriangle className="h-4 w-4 text-destructive" /> Incident log
         </CardTitle>
       </CardHeader>
-      <CardContent className="flex flex-1 flex-col gap-4">
+      <CardContent className="flex flex-1 flex-col gap-4 p-5 pt-0">
         <div className="flex items-center justify-between text-body">
           <span className="text-text-secondary">
             {incidents.length} issues in the last 7 days
@@ -768,7 +811,7 @@ function ReasonerActivityPanel({
 }: ReasonerActivityPanelProps) {
   return (
     <Card variant="surface" interactive={false} className="flex h-full flex-col">
-      <CardHeader className="space-y-4">
+      <CardHeader className="space-y-4 p-5 pb-2">
         <CardTitle className="flex items-center gap-2">
           <Cpu className="h-4 w-4" /> Reasoner activity
         </CardTitle>
@@ -790,7 +833,7 @@ function ReasonerActivityPanel({
           />
         </div>
       </CardHeader>
-      <CardContent className="flex flex-1 flex-col gap-4 min-h-0">
+      <CardContent className="flex flex-1 flex-col gap-4 min-h-0 p-5 pt-0">
         {reasoners.length === 0 ? (
           <p className="text-body-small">
             No recent reasoner activity. Trigger a workflow or execution to

From 5feb5292b91321df0abc5368f78be2ed24145d85 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Wed, 19 Nov 2025 09:49:40 -0500
Subject: [PATCH 02/11] updated readme

---
 README.md | 324 ++++++++++++++++--------------------------------------
 1 file changed, 93 insertions(+), 231 deletions(-)

diff --git a/README.md b/README.md
index a805d0d6..313e80fc 100644
--- a/README.md
+++ b/README.md
@@ -2,307 +2,169 @@
 
 <img src="assets/github hero.png" alt="AgentField - Kubernetes, for AI Agents" width="100%" />
 
-> **👋 Welcome Early Adopter!**
->
-> You've discovered AgentField before our official launch. We're currently in private beta, gathering feedback from early users to shape the future of the autonomous software. Feel free to explore and test, and we'd love to hear your thoughts! Share feedback via [GitHub Issues](https://github.com/Agent-Field/agentfield/issues) or email us at contact@agentfield.ai. Please note that features and APIs are still being refined before our public release.
-
-### Kubernetes for AI Agents - **Deploy, Scale, Observe, and Prove**
-
-Open-source (Apache-2.0) **control plane** that runs AI agents like microservices.
-Every agent gets **REST/gRPC APIs**, **async execution & webhooks**, **built-in observability**, and **cryptographic identity & audit**.
+# The Control Plane for Autonomous Software
 
+### **Deploy, Scale, Observe, and Prove.**
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Go](https://img.shields.io/badge/go-1.21+-00ADD8.svg)](https://go.dev/)
 [![Python](https://img.shields.io/badge/python-3.9+-3776AB.svg)](https://www.python.org/)
 [![Deploy with Docker](https://img.shields.io/badge/deploy-docker-2496ED.svg)](https://docs.docker.com/)
 
-**[📚 Docs](https://agentfield.ai/docs)** • **[⚡ Quickstart](#quickstart-in-60-seconds)** • **[🧠 Why AgentField](#why-agentfield)**
+**[📚 Documentation](https://agentfield.ai/docs)** • **[⚡ Quick Start](#-quick-start-in-60-seconds)** • **[🧠 The Paradigm Shift](#-why-agentfield)**
 
 </div>
 
 ---
 
-## 🚀 **Ship Production-Ready AI Agents in Minutes**
-
-✅ **Write agents in Python/Go** (or any language via REST/gRPC)
-
-✅ **Deploy independently** like microservices-zero coordination between teams
-
-✅ **Get production infrastructure automatically**:
-- **IAM & cryptographic audit trails** - W3C DIDs + Verifiable Credentials
-- **REST APIs, streaming, async queues** - auto-generated endpoints
-- **Built-in observability & metrics** - Prometheus + workflow DAGs
-
-✅ **Run anywhere**: local dev, Docker, Kubernetes, cloud
-
-```bash
-curl -fsSL https://agentfield.ai/install.sh | bash && af init my-agent --defaults
-```
-
-**[📚 Full Docs](https://agentfield.ai/docs)** • **[⚡ Quick Start](https://agentfield.ai/docs/quick-start)** • **[🎯 Examples](https://github.com/agentfield/agentfield-examples)**
+> **👋 Welcome Early Adopter!**
+>
+> You've discovered AgentField before our official launch. We're currently in private beta, building the infrastructure for the next generation of software. We'd love your feedback via [GitHub Issues](https://github.com/Agent-Field/agentfield/issues).
 
 ---
 
-## 🚀 Try AgentField in 2 Minutes
+## 🚀 What is AgentField?
 
-### Option 1: Local Install
+**AgentField is "Kubernetes for AI Agents."**
 
-```bash
-# macOS/Linux - install CLI
-curl -fsSL https://agentfield.ai/install.sh | bash
+It is an open-source **Control Plane** that treats AI agents as first-class citizens. Instead of building fragile, monolithic scripts, AgentField lets you deploy agents as **independent microservices** that can discover each other, coordinate complex workflows, and scale infinitely—all with built-in observability and cryptographic trust.
 
-# Start control plane + create your first agent
-af init my-agent --defaults && cd my-agent
-af run
-```
+### The "Aha!" Moment
 
-### Option 2: Docker Compose
-
-```bash
-git clone https://github.com/agentfield/agentfield
-cd agentfield && docker compose up
-```
+Write standard Python (or Go). Get a production-grade distributed system automatically.
 
-Your control plane is running at `http://localhost:8080`
+```python
+from agentfield import Agent
 
-<details>
-<summary><code>export AGENT_CALLBACK_URL="http://host.docker.internal:8001"</code></summary>
+# 1. Define an Agent (It's just a microservice)
+app = Agent(node_id="researcher", model="gpt-4o")
 
-**Heads-up:** When your agent nodes run outside the Docker network (local shell, another VM, etc.) they can't be reached through `localhost`. Before starting any agent, set a callback URL that the control plane can dial:
+# 2. Create a Skill (Deterministic code)
+@app.skill()
+def fetch_url(url: str) -> str:
+    return requests.get(url).text
 
-```bash
-export AGENT_CALLBACK_URL="http://host.docker.internal:8001"
+# 3. Create a Reasoner (AI-powered logic)
+# This automatically becomes a REST API endpoint: POST /execute/researcher.summarize
+@app.reasoner()
+async def summarize(url: str) -> dict:
+    content = fetch_url(url)
+    # Native AI call with structured output
+    return await app.ai(f"Summarize this content: {content}")
+
+# 4. Run it
+if __name__ == "__main__":
+    app.run()
 ```
 
-Replace `host.docker.internal` with whatever host/IP the control plane can reach if you're on Linux or a remote machine.
+**What just happened?**
+*   ✅ **Instant API:** Your function is now `POST /api/v1/execute/researcher.summarize`.
+*   ✅ **Async & Durable:** It runs on a durable execution engine. If the server crashes, it resumes.
+*   ✅ **Observable:** You get a full execution DAG, metrics, and logs automatically.
+*   ✅ **Auditable:** Every step produced a cryptographically signed Verifiable Credential (VC).
 
-</details>
+---
 
-**[📚 Full quickstart guide →](https://agentfield.ai/docs/quick-start)**
+## 🧠 Why AgentField?
 
-```python
-from agentfield import Agent
+**The Paradigm Shift: From "Chatbots" to "Systems"**
 
-# Create an agent
-app = Agent(node_id="greeting-agent",
-            model="openrouter/meta-llama/llama-4-maverick")
+Most agent frameworks are designed for prototyping single-loop chatbots. But when you try to build **production systems** with multiple agents, you hit a wall.
 
-# Decorate a function-becomes a REST endpoint automatically
-@app.reasoner()
-async def say_hello(name: str) -> dict:
+| 🔴 The Old Way (Frameworks) | 💚 The AgentField Way (Infrastructure) |
+| :--- | :--- |
+| **Monolithic Deployment**<br>One team's bug crashes the whole system. | **Microservices Architecture**<br>Teams deploy agents independently. Zero coordination required. |
+| **"Trust Me" Logs**<br>Text logs that can be edited or lost. | **Cryptographic Proof**<br>Every action is signed (W3C DIDs). You can prove *exactly* what the AI did in court. |
+| **Black Box Execution**<br>Agent A calls Agent B... and context is lost. | **Distributed Tracing**<br>Visualize the entire DAG. See how data flows across the network. |
+| **Fragile State**<br>Restart the server, lose the memory. | **Durable Execution**<br>Workflows can run for days. State is persisted and recoverable. |
+| **Manual Plumbing**<br>Build your own queues, webhooks, and APIs. | **Batteries Included**<br>REST/gRPC, Async Queues, Webhooks, and Shared Memory out of the box. |
 
-    message = await app.ai(f"Generate a personalized greeting for {name}")
+---
 
-    return {"greeting": message}
-```
+## ⚡ Quick Start in 60 Seconds
 
-**Deploy:**
+### 1. Install the CLI
 ```bash
-export OPENROUTER_API_KEY="sk-..."
-af run
+curl -fsSL https://agentfield.ai/install.sh | bash
 ```
 
-**Call from anywhere** (REST API auto-generated):
+### 2. Initialize a New Agent
 ```bash
-curl -X POST http://localhost:8080/api/v1/execute/greeting-agent.say_hello \
-  -H "Content-Type: application/json" \
-  -d '{"input": {"name": "Alice"}}'
+af init my-first-agent --defaults
+cd my-first-agent
 ```
 
-**You automatically get:**
-- ✅ REST API at `/execute/greeting-agent.say_hello` (OpenAPI spec at `/openapi.yaml`)
-- ✅ Async execution: `/execute/async/...` with webhook callbacks (HMAC-signed)
-- ✅ Prometheus metrics: `/metrics`
-- ✅ Workflow Observability
-
-
-**[📚 Docs](https://agentfield.ai/docs)** • **[⚡ More examples](https://github.com/agentfield/agentfield-examples)**
-
-
-
-## Why AgentField?
-
-**TL;DR:** Most agent frameworks are built for prototypes. AgentField is infrastructure for production. If you've tried running multi-agent systems in production, you've hit these problems: agents deployed as a monolith (one team's change redeploys everyone), no proof of what your AI did for auditors, manual service discovery between agents, and building your own queues/webhooks/state management for long running AI nested calls. AgentField ships as a control plane + agent nodes architecture - like Kubernetes for autonomous software. Deploy agents independently, get cryptographic audit trails, and coordinate through zero-config shared memory. Every reasoner becomes a REST endpoint automatically.
+### 3. Run It
+```bash
+# Starts the Control Plane + Your Agent
+af run
+```
 
-### From Prototype to Production
+Your Control Plane is now live at **`http://localhost:8080`**.
+Open the dashboard to see your agent in action!
 
-| 🔴 Building Without AgentField                                                                                                                                                          | 💚 Building With AgentField                                                                                                                                                                                                          |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **No cryptographic identity** - agents are names in logs; when regulators ask "prove this AI made this decision," you have editable logs with no tamper-proof record                   | **DIDs + Verifiable Credentials** - every agent gets a W3C DID; every execution produces a signed VC; export cryptographic proof chains that auditors verify offline with `af verify audit.json`                                    |
-| **Monolithic deployments** - all agents in one codebase; Marketing team's update redeploys Support team's agents; coordination nightmare across teams                                  | **Control plane coordinates independent agents** - each team deploys their agent on their own schedule; discovery/routing/orchestration handled by stateless control plane; zero coordination needed                                |
-| **Lost context across agent boundaries** - Agent A calls Agent B, you can't trace the full execution; no visibility into multi-agent workflows                                         | **Context propagation built-in** - `workflow_id`, `execution_id`, `session_id` flow automatically through headers; see complete DAG of which agent called which, when, why - distributed tracing without instrumentation            |
-| **Manual state management** - set up Redis/database yourself; handle race conditions; write sync logic for agents to share data                                                        | **Zero-config shared memory fabric** - `await app.memory.set("key", val)` works across distributed agents; hierarchical scopes (workflow/session/actor/global); real-time change events via `@app.memory.on_change("key")`          |
-| **DIY async infrastructure** - implement PostgreSQL queues with `FOR UPDATE SKIP LOCKED`, build webhook delivery with HMAC signing and retries, handle backpressure, graceful shutdown | **Durable execution ships working** - PostgreSQL-backed queues, automatic retries with exponential backoff, HMAC webhook delivery (GitHub-style), fair scheduling, Prometheus metrics, health checks for K8s - no assembly required |
-| **Timeout hell for nested AI calls** - HTTP timeouts kill long-running reasoners; Agent A calls Agent B calls Agent C fails after 60s; build custom async queues and polling infrastructure | **Durable async execution** - reasoners run for hours/days without timeout; nested agent workflows (A→B→C) work natively; async endpoints + webhooks built-in; no external queue infrastructure needed |
-| **Hardcoded integrations** - manually wire up service discovery; build custom REST wrappers for frontend teams; maintain API gateway; coordinate URLs across deployments               | **Auto-discovery + instant APIs** - call any agent via `await app.call("agent.function")`; every `@app.reasoner()` becomes `/api/v1/execute/agent.function` automatically; React/iOS/Android call via HTTP, no SDK needed           |
+---
 
+## 🏗️ Architecture
 
-## 🎨 See It In Action
+AgentField is composed of a **Control Plane** (Go) and **Agent Nodes** (Python/Go/Any).
 
 <div align="center">
-
-<img src="assets/UI.png" alt="AgentField Dashboard" width="90%" />
-
-<br/>
-
-**Real-time Scaling/Observability • Execution traces • IAM • Verifiable Credentials**
-
-*Everything you need to run production AI agents-built in, zero configuration*
-
+<img src="assets/arch.png" alt="AgentField Architecture Diagram" width="80%" />
 </div>
 
+1.  **Control Plane:** The brain. Stateless, scalable. Handles routing, state, and verification.
+2.  **Agent Nodes:** Your code. Lightweight microservices that connect to the plane.
+3.  **Shared Memory Fabric:** Zero-config distributed state management.
 
+---
 
-## What You Get Out-of-the-Box
-
-🧩 Scale Infrastructure - deploy like microservices
-	•	Durable async execution for long-running & nested AI workflows (hours/days, no timeouts)
-	•	Auto-generated queues, webhooks (HMAC-signed), event streaming
-	•	Auto-discovery & cross-agent calls; context propagation
-	•	Horizontal scaling & many more..!
+## 💎 Key Features
 
-🔐 Trust & Governance - cryptographic proof for every decision
-	•	W3C IDs & Verifiable Credentials
-	•	Tamper-proof audit trails; runtime policy enforcement
-	•	Offline verification for auditors
+### 🛡️ Identity & Trust (The Enterprise Killer Feature)
+Every agent gets a **W3C Decentralized Identifier (DID)**. Every execution produces a **Verifiable Credential (VC)**.
+*   **Audit Trails:** Export a cryptographic chain of custody for every decision.
+*   **Policy Enforcement:** "Only agents signed by 'Finance Team' can access this data."
 
-🛰 Production Hardening - observability & reliability built in
-	•	Auto-generated workflow DAGs
-	•	Prometheus metrics, structured logs
-	•	Graceful shutdowns, retries, zero-config memory
+### 🧩 Durable Async Execution
+Long-running tasks? No problem.
+*   **No Timeouts:** Reasoners can run for hours or days.
+*   **Webhooks:** Get notified via HMAC-signed webhooks when a job is done.
+*   **Retries:** Automatic exponential backoff for failures.
 
-**Learn more:** [Features](https://agentfield.ai/docs/features) • [Identity & Trust](https://agentfield.ai/docs/why-agentfield/vs-agent-frameworks)
+### 🔌 Interoperability
+*   **REST & gRPC:** Call agents from React, iOS, or `curl`.
+*   **Language Agnostic:** Write agents in Python, Go, or any language with a gRPC client.
 
 ---
 
-## 🏗️ Architecture
+## 🎨 See It In Action
 
 <div align="center">
-<img src="assets/arch.png" alt="AgentField Architecture Diagram" width="80%" />
+<img src="assets/UI.png" alt="AgentField Dashboard" width="90%" />
+<br/>
+<i>Real-time Observability • Execution DAGs • Verifiable Credentials</i>
 </div>
 
 ---
 
-| Layer         | What It Does                                                  |
-| ------------- | ------------------------------------------------------------- |
-| Control Plane | Stateless Go service; routes, observes, verifies, scales      |
-| Agent Nodes   | Your independent agent microservices (Python/Go/REST/gRPC)    |
-| Interfaces    | Backends via REST; frontends & external APIs via webhooks/SSE |
-
-Each agent is a microservice. Teams deploy independently; the control plane makes them behave as one coherent system.
-
-**More:** [Architecture](https://agentfield.ai/docs/architecture) • [API Reference](https://agentfield.ai/docs/api)
-
-
-## Real-Time & Async
-
-- **Unified API:** `POST /api/v1/execute/{agent.reasoner}`
-- **Async runs:** `/execute/async/...` + signed webhooks
-- **Live streams:** Server-Sent Events (SSE) for real-time output
-- **Auto retries, backpressure, dead-letter queues**
-
-**Docs:** [API Reference](https://agentfield.ai/docs/api) • [Observability](https://agentfield.ai/docs/observability)
-
-
-## Identity & Audit (opt-in per agent)
-
-- DIDs auto-issued for agents (`did:web` / `did:key`)
-- Verifiable Credentials (W3C JSON-LD) for each execution
-- Input/output hashing for proof integrity
-- Offline verification for auditors (`af vc verify audit.json`)
-
-**Docs:** [Identity & Trust](https://agentfield.ai/docs/why-agentfield/vs-agent-frameworks)
-
-
-
-## Installation
-
-### macOS / Linux
-
-```bash
-curl -fsSL https://agentfield.ai/get | bash
-agentfield --version
-```
-
-### Docker Compose
-
-```bash
-git clone https://github.com/Agent-Field/agentfield
-cd agentfield && docker compose up
-```
-
-**Full guides:** [Installation](https://agentfield.ai/docs/installation) • [Deployment](https://agentfield.ai/docs/deployment)
-
----
-
-## When to Use (and When Not)
-
-### ✅ Use AgentField If:
-
-- You're building **multi-agent systems** that need to coordinate
-- You need **independent deployment**-multiple teams, different schedules
-- You need **production infrastructure**: REST APIs, async queues, observability, health checks
-- You need **compliance/audit trails** (finance, healthcare, legal)
-- You want to **call agents from frontends** (React, mobile) without custom wrappers
-- You're scaling to **multiple environments** (dev, staging, prod) and need consistency
-
-### ❌ Start with a Framework If:
-
-- You're building a **single-agent chatbot** that will never scale beyond one service
-- You don't need REST APIs, observability, or multi-agent coordination
-- You're prototyping and don't plan to deploy to production
-
-### The Bottom Line
-
-**Frameworks = Build agents** (perfect for learning)
-**AgentField = Build and run agents at any scale** (perfect from prototype to production)
-
-You can start with AgentField and skip migration pain later. Or start with a framework and migrate when you hit the pain points above.
-
-
-
-## Community
+## 🤝 Community & Support
 
-We're building AgentField in the open. Join us:
+We are building the operating system for the agentic future. Join us!
 
-- **[📚 Documentation](https://agentfield.ai/docs)** - Guides, API reference, examples
-- **[💡 GitHub Discussions](https://github.com/agentfield/agentfield/discussions)** - Feature requests, Q&A
-- **[🐦 Twitter/X](https://x.com/agentfield_dev)** - Updates and announcements
+*   **[📚 Documentation](https://agentfield.ai/docs)** - Deep dives and API references.
+*   **[💡 GitHub Discussions](https://github.com/agentfield/agentfield/discussions)** - Feature requests and Q&A.
+*   **[🐦 Twitter/X](https://x.com/agentfield_dev)** - Updates and announcements.
 
 ### Contributing
-
-Apache 2.0 licensed. Built by developers like you.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
-
-
-
-
-## 📖 Resources
-
-- **[📚 Documentation](https://agentfield.ai/docs)** - Complete guides and API reference
-- **[⚡ Quick Start Tutorial](https://agentfield.ai/docs/quick-start)** - Build your first agent in 5 minutes
-- **[🏗️ Architecture Deep Dive](https://agentfield.ai/docs/architecture)** - How AgentField works under the hood
-- **[📦 Examples Repository](https://github.com/agentfield/agentfield-examples)** - Production-ready agent templates
-- **[📝 Blog](https://agentfield.ai/blog)** - Tutorials, case studies, best practices
+AgentField is Apache 2.0 licensed. We welcome contributions from the community. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
 
 ---
 
 <div align="center">
 
-### ⭐ Star us to follow development
-
-**Built by developers who got tired of duct-taping agents together**
-
-**Join the future of autonomous software**
-
-**[🌐 Website](https://agentfield.ai) • [📚 Docs](https://agentfield.ai/docs) • [🐦 Twitter](https://x.com/agentfield_dev)**
-
-**License:** [Apache 2.0](LICENSE)
-
----
+**Built by developers who got tired of duct-taping agents together.**
 
-*We believe autonomous software needs infrastructure that respects what makes it different-agents that reason, decide, and coordinate-while providing the same operational excellence that made traditional software successful.*
+**[🌐 Website](https://agentfield.ai)**
 
 </div>

From 5906f9b5273abe0239679ac0efb8c6689d72942e Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Wed, 19 Nov 2025 10:12:07 -0500
Subject: [PATCH 03/11] Revamps README for clarity and production focus

Refines messaging to position the project as "Kubernetes for AI Agents"
and emphasizes production-oriented infrastructure over frameworks.
Streamlines quick start, enhances feature explanations, and adds
guidance for various user types. Improves onboarding, troubleshooting,
and interoperability instructions, making the project more accessible
and appealing for backend, platform, and enterprise teams.
---
 README.md | 168 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 102 insertions(+), 66 deletions(-)

diff --git a/README.md b/README.md
index 313e80fc..831d2c6e 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 <img src="assets/github hero.png" alt="AgentField - Kubernetes, for AI Agents" width="100%" />
 
-# The Control Plane for Autonomous Software
+# Kubernetes for AI Agents
 
 ### **Deploy, Scale, Observe, and Prove.**
 
@@ -11,7 +11,7 @@
 [![Python](https://img.shields.io/badge/python-3.9+-3776AB.svg)](https://www.python.org/)
 [![Deploy with Docker](https://img.shields.io/badge/deploy-docker-2496ED.svg)](https://docs.docker.com/)
 
-**[📚 Documentation](https://agentfield.ai/docs)** • **[⚡ Quick Start](#-quick-start-in-60-seconds)** • **[🧠 The Paradigm Shift](#-why-agentfield)**
+**[📚 Documentation](https://agentfield.ai/docs)** • **[⚡ Quick Start](#-quick-start-in-60-seconds)** • **[🧠 Why AgentField](#-why-agentfield)**
 
 </div>
 
@@ -57,114 +57,150 @@ if __name__ == "__main__":
     app.run()
 ```
 
-**What just happened?**
-*   ✅ **Instant API:** Your function is now `POST /api/v1/execute/researcher.summarize`.
-*   ✅ **Async & Durable:** It runs on a durable execution engine. If the server crashes, it resumes.
-*   ✅ **Observable:** You get a full execution DAG, metrics, and logs automatically.
-*   ✅ **Auditable:** Every step produced a cryptographically signed Verifiable Credential (VC).
+**What you get for free:**
+*   ✅ **Instant API:** `POST /api/v1/execute/researcher.summarize`
+*   ✅ **Durable Execution:** Resumes automatically if the server crashes.
+*   ✅ **Observability:**  You get a full execution DAG, metrics, and logs automatically.
+*   ✅ **Audit:** Every step produces a cryptographically signed Verifiable Credential.
 
 ---
 
-## 🧠 Why AgentField?
-
-**The Paradigm Shift: From "Chatbots" to "Systems"**
-
-Most agent frameworks are designed for prototyping single-loop chatbots. But when you try to build **production systems** with multiple agents, you hit a wall.
-
-| 🔴 The Old Way (Frameworks) | 💚 The AgentField Way (Infrastructure) |
-| :--- | :--- |
-| **Monolithic Deployment**<br>One team's bug crashes the whole system. | **Microservices Architecture**<br>Teams deploy agents independently. Zero coordination required. |
-| **"Trust Me" Logs**<br>Text logs that can be edited or lost. | **Cryptographic Proof**<br>Every action is signed (W3C DIDs). You can prove *exactly* what the AI did in court. |
-| **Black Box Execution**<br>Agent A calls Agent B... and context is lost. | **Distributed Tracing**<br>Visualize the entire DAG. See how data flows across the network. |
-| **Fragile State**<br>Restart the server, lose the memory. | **Durable Execution**<br>Workflows can run for days. State is persisted and recoverable. |
-| **Manual Plumbing**<br>Build your own queues, webhooks, and APIs. | **Batteries Included**<br>REST/gRPC, Async Queues, Webhooks, and Shared Memory out of the box. |
-
----
-
-## ⚡ Quick Start in 60 Seconds
+## 🚀 Quick Start in 60 Seconds
 
-### 1. Install the CLI
+### 1. Install
 ```bash
 curl -fsSL https://agentfield.ai/install.sh | bash
 ```
 
-### 2. Initialize a New Agent
+### 2. Initialize
 ```bash
-af init my-first-agent --defaults
-cd my-first-agent
+af init my-agent --defaults && cd my-agent
 ```
 
-### 3. Run It
+### 3. Run
 ```bash
-# Starts the Control Plane + Your Agent
 af run
 ```
 
-Your Control Plane is now live at **`http://localhost:8080`**.
-Open the dashboard to see your agent in action!
+### 4. Call
+```bash
+curl -X POST http://localhost:8080/api/v1/execute/researcher.summarize \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"url": "https://example.com"}}'
+```
+
+<details>
+<summary>🐳 <strong>Docker / Troubleshooting</strong></summary>
+
+If you are running AgentField in Docker, you may need to set a callback URL so the Control Plane can reach your agent:
+
+```bash
+export AGENT_CALLBACK_URL="http://host.docker.internal:8001"
+```
+</details>
 
 ---
 
-## 🏗️ Architecture
+## 🧠 Why AgentField?
 
-AgentField is composed of a **Control Plane** (Go) and **Agent Nodes** (Python/Go/Any).
+**Software is starting to behave less like scripts and more like reasoning systems.**
+Once agents act across APIs, data layers, and critical paths, they need infrastructure: identity, routing, retries, observability, policies. We built AgentField because agents should behave as predictably as microservices.
 
-<div align="center">
-<img src="assets/arch.png" alt="AgentField Architecture Diagram" width="80%" />
-</div>
+### From Prototype to Production
+
+Most frameworks (LangChain, CrewAI) are great for prototyping. But when you move to production, you hit walls: **Non-deterministic execution times**, **Multi-agent coordination**, and **Compliance**.
 
-1.  **Control Plane:** The brain. Stateless, scalable. Handles routing, state, and verification.
-2.  **Agent Nodes:** Your code. Lightweight microservices that connect to the plane.
-3.  **Shared Memory Fabric:** Zero-config distributed state management.
+AgentField isn't a framework you extend. It's **infrastructure** that solves these problems out of the box.
+
+| Capability       | Traditional Frameworks           | AgentField (Infrastructure)                   |
+| :--------------- | :------------------------------- | :-------------------------------------------- |
+| **Architecture** | Monolithic application           | **Distributed Microservices**                 |
+| **Team Model**   | Single team, single repo         | **Independent teams & deployments**           |
+| **Integration**  | Custom SDK per language          | **Standard REST/gRPC APIs**                   |
+| **Coordination** | Manual message passing           | **Service Discovery & Auto-DAGs**             |
+| **Memory**       | Configure vector stores manually | **Zero-config Scoped Memory & Vector Search** |
+| **Async**        | Roll your own queues             | **Durable Queues, Webhooks, Retries**         |
+| **Trust**        | "Trust me" logs                  | **DIDs & Verifiable Credentials**             |
+
+---
+
+## 🎯 Who is this for?
+
+*   **Backend Engineers** shipping AI into production who want standard APIs, not magic.
+*   **Platform Teams** who don't want to build another homegrown orchestrator.
+*   **Enterprise Teams** in regulated industries (Finance, Health) needing audit trails.
+*   **Frontend Developers** who just want to `fetch()` an agent without Python headaches.
 
 ---
 
 ## 💎 Key Features
 
-### 🛡️ Identity & Trust (The Enterprise Killer Feature)
-Every agent gets a **W3C Decentralized Identifier (DID)**. Every execution produces a **Verifiable Credential (VC)**.
-*   **Audit Trails:** Export a cryptographic chain of custody for every decision.
-*   **Policy Enforcement:** "Only agents signed by 'Finance Team' can access this data."
+### 🧩 Scale Infrastructure
+*   **Control Plane:** Stateless Go service that handles routing and state.
+*   **Async by Default:** Fire-and-forget or wait for results. Handles long-running tasks (hours/days) with **Webhooks**.
+*   **Shared Memory Fabric:** Built-in, scoped memory (Workflow/Session/User) with **Vector Search** out of the box. No Redis/Pinecone required.
 
-### 🧩 Durable Async Execution
-Long-running tasks? No problem.
-*   **No Timeouts:** Reasoners can run for hours or days.
-*   **Webhooks:** Get notified via HMAC-signed webhooks when a job is done.
-*   **Retries:** Automatic exponential backoff for failures.
+### 🛡️ Identity & Trust
+*   **W3C DIDs:** Every agent has a cryptographic identity.
+*   **Verifiable Credentials:** Prove *exactly* what the AI did.
+*   **Policy:** "Only agents signed by 'Finance' can access this tool."
 
-### 🔌 Interoperability
-*   **REST & gRPC:** Call agents from React, iOS, or `curl`.
-*   **Language Agnostic:** Write agents in Python, Go, or any language with a gRPC client.
+### 🔭 Observability
+*   **DAG Visualization:** See the logic flow in real-time.
+*   **Metrics:** Prometheus endpoints at `/metrics`.
+*   **Logs:** Structured, correlated logs.
 
 ---
 
-## 🎨 See It In Action
+## 🔌 Interoperability
+
+Call your agents from anywhere. No SDK required.
+
+**Frontend (React/Next.js):**
+```javascript
+const response = await fetch("http://localhost:8080/api/v1/execute/researcher.summarize", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ input: { url: "https://example.com" } }),
+});
+const result = await response.json();
+```
+
+---
+
+## 🏗️ Architecture
 
 <div align="center">
-<img src="assets/UI.png" alt="AgentField Dashboard" width="90%" />
-<br/>
-<i>Real-time Observability • Execution DAGs • Verifiable Credentials</i>
+<img src="assets/arch.png" alt="AgentField Architecture Diagram" width="80%" />
 </div>
 
 ---
 
-## 🤝 Community & Support
+## ⚖️ Is AgentField for you?
 
-We are building the operating system for the agentic future. Join us!
+### ✅ YES if:
+*   You are building **multi-agent systems**.
+*   You need **independent deployment** (multiple teams).
+*   You need **compliance/audit trails**.
+*   You want **production infrastructure** (Queues, Retries, APIs).
 
-*   **[📚 Documentation](https://agentfield.ai/docs)** - Deep dives and API references.
-*   **[💡 GitHub Discussions](https://github.com/agentfield/agentfield/discussions)** - Feature requests and Q&A.
-*   **[🐦 Twitter/X](https://x.com/agentfield_dev)** - Updates and announcements.
-
-### Contributing
-AgentField is Apache 2.0 licensed. We welcome contributions from the community. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+### ❌ NO if:
+*   You are building a **single-agent chatbot**.
+*   You are just **prototyping** and don't care about scale yet.
 
 ---
 
-<div align="center">
+## 🤝 Community
 
-**Built by developers who got tired of duct-taping agents together.**
+**Agents are becoming part of production backends. They need identity, governance, and infrastructure. That’s why AgentField exists.**
+
+*   **[📚 Documentation](https://agentfield.ai/docs)**
+*   **[💡 GitHub Discussions](https://github.com/agentfield/agentfield/discussions)**
+*   **[🐦 Twitter/X](https://x.com/agentfield_dev)**
+*   **[📦 Examples](https://github.com/agentfield/agentfield-examples)**
 
+<div align="center">
+**Built by developers who got tired of duct-taping agents together.**
 **[🌐 Website](https://agentfield.ai)**
 
 </div>

From 7cd458c34edc2fd2f2f1a61a5d9b4708b40c2bff Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Wed, 19 Nov 2025 10:14:51 -0500
Subject: [PATCH 04/11] Adds UI screenshot to showcase dashboard features

Introduces a "See It In Action" section with a visual preview,
highlighting real-time observability and execution DAGs to help
users quickly understand key capabilities and interface.
---
 README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 831d2c6e..644e590a 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,16 @@ export AGENT_CALLBACK_URL="http://host.docker.internal:8001"
 
 ---
 
+## 🎨 See It In Action
+
+<div align="center">
+<img src="assets/UI.png" alt="AgentField Dashboard" width="100%" />
+<br/>
+<i>Real-time Observability • Execution DAGs • Verifiable Credentials</i>
+</div>
+
+---
+
 ## 🧠 Why AgentField?
 
 **Software is starting to behave less like scripts and more like reasoning systems.**

From 24a44ba96f35c470e4fe4e0c0d80a010d20687f0 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Wed, 19 Nov 2025 10:15:59 -0500
Subject: [PATCH 05/11] Clarifies beta status and feedback channels in docs

Updates the documentation to better communicate the project's private beta phase, encourage exploration and feedback, and provide direct contact details for early users. Removes a redundant section header for improved clarity.
---
 README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 644e590a..329b9add 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@
 
 > **👋 Welcome Early Adopter!**
 >
-> You've discovered AgentField before our official launch. We're currently in private beta, building the infrastructure for the next generation of software. We'd love your feedback via [GitHub Issues](https://github.com/Agent-Field/agentfield/issues).
+> You've discovered AgentField before our official launch. We're currently in private beta, gathering feedback from early users to shape the future of the autonomous software. Feel free to explore and test, and we'd love to hear your thoughts! Share feedback via [GitHub Issues](https://github.com/Agent-Field/agentfield/issues) or email us at contact@agentfield.ai. Please note that features and APIs are still being refined before our public release.
 
 ---
 
@@ -29,7 +29,6 @@
 
 It is an open-source **Control Plane** that treats AI agents as first-class citizens. Instead of building fragile, monolithic scripts, AgentField lets you deploy agents as **independent microservices** that can discover each other, coordinate complex workflows, and scale infinitely—all with built-in observability and cryptographic trust.
 
-### The "Aha!" Moment
 
 Write standard Python (or Go). Get a production-grade distributed system automatically.
 

From c39a630d5cb7cb047f85023c70b361b1cf6cecc0 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Thu, 20 Nov 2025 15:06:29 -0500
Subject: [PATCH 06/11] Add deep research example with planning and research
 routers

---
 .../deep_research/README.md                   | 168 ++++++++++
 .../deep_research/__init__.py                 |   1 +
 .../python_agent_nodes/deep_research/main.py  |  51 +++
 .../deep_research/requirements.txt            |   3 +
 .../deep_research/routers/__init__.py         |   6 +
 .../deep_research/routers/planning.py         | 306 ++++++++++++++++++
 .../deep_research/routers/research.py         | 169 ++++++++++
 .../deep_research/schemas.py                  | 127 ++++++++
 8 files changed, 831 insertions(+)
 create mode 100644 examples/python_agent_nodes/deep_research/README.md
 create mode 100644 examples/python_agent_nodes/deep_research/__init__.py
 create mode 100644 examples/python_agent_nodes/deep_research/main.py
 create mode 100644 examples/python_agent_nodes/deep_research/requirements.txt
 create mode 100644 examples/python_agent_nodes/deep_research/routers/__init__.py
 create mode 100644 examples/python_agent_nodes/deep_research/routers/planning.py
 create mode 100644 examples/python_agent_nodes/deep_research/routers/research.py
 create mode 100644 examples/python_agent_nodes/deep_research/schemas.py

diff --git a/examples/python_agent_nodes/deep_research/README.md b/examples/python_agent_nodes/deep_research/README.md
new file mode 100644
index 00000000..942e5115
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/README.md
@@ -0,0 +1,168 @@
+# Deep Research Agent (Recursive Planning)
+
+A research agent that uses recursive planning to break down complex research questions into manageable subtasks, forming a topological graph that can be executed in parallel.
+
+## Highlights
+
+- **Recursive Planning** – Automatically breaks down research questions into subtasks with configurable depth
+- **Topological Graph** – Identifies task dependencies and parallelization opportunities
+- **Simple & Elegant** – Uses AgentField primitives for clean, maintainable code
+- **Single Router Architecture** – All planning logic in one router for simplicity
+
+## Architecture
+
+### Recursive Planning System
+
+1. **Research Plan Creation** (`create_research_plan`)
+   - Takes a research question and breaks it down recursively
+   - Identifies dependencies between tasks
+   - Groups tasks for parallel execution
+   - Returns a complete `ResearchPlan` with topological structure
+
+2. **Task Refinement** (`refine_task`)
+   - Helper reasoner for recursive task decomposition
+   - Can be called to further break down complex tasks
+   - Respects maximum depth constraints
+
+## Project Structure
+
+```
+deep_research/
+├── main.py            # Agent bootstrap
+├── schemas.py         # Pydantic models for planning
+├── routers/
+│   ├── __init__.py
+│   └── planning.py    # Recursive planning router
+├── requirements.txt
+└── README.md
+```
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+pip install -r examples/python_agent_nodes/deep_research/requirements.txt
+```
+
+### 2. Run the Agent
+
+```bash
+python examples/python_agent_nodes/deep_research/main.py
+```
+
+### 3. Create a Research Plan
+
+POST to `/reasoners/planning_create_research_plan`:
+
+```json
+{
+  "research_question": "What are the environmental impacts of electric vehicles compared to traditional vehicles?",
+  "max_depth": 3,
+  "max_tasks_per_level": 5
+}
+```
+
+### Response Format
+
+```json
+{
+  "research_question": "What are the environmental impacts of electric vehicles compared to traditional vehicles?",
+  "tasks": [
+    {
+      "task_id": "task_1",
+      "description": "Research manufacturing environmental impact of EVs",
+      "dependencies": [],
+      "depth": 1,
+      "can_parallelize": true
+    },
+    {
+      "task_id": "task_2",
+      "description": "Research manufacturing environmental impact of traditional vehicles",
+      "dependencies": [],
+      "depth": 1,
+      "can_parallelize": true
+    },
+    {
+      "task_id": "task_3",
+      "description": "Research operational emissions of EVs",
+      "dependencies": [],
+      "depth": 1,
+      "can_parallelize": true
+    },
+    {
+      "task_id": "task_4",
+      "description": "Compare manufacturing impacts",
+      "dependencies": ["task_1", "task_2"],
+      "depth": 2,
+      "can_parallelize": false
+    },
+    {
+      "task_id": "task_5",
+      "description": "Synthesize overall comparison",
+      "dependencies": ["task_3", "task_4"],
+      "depth": 3,
+      "can_parallelize": false
+    }
+  ],
+  "max_depth": 3,
+  "total_tasks": 5,
+  "parallelizable_groups": [
+    ["task_1", "task_2", "task_3"],
+    ["task_4"],
+    ["task_5"]
+  ]
+}
+```
+
+## Available Endpoints
+
+### Reasoners
+
+- **`/reasoners/planning_create_research_plan`** – Create a recursive research plan
+  - Parameters: `research_question`, `max_depth` (default: 3), `max_tasks_per_level` (default: 5)
+  - Returns: `ResearchPlan` with tasks, dependencies, and parallelization groups
+
+- **`/reasoners/planning_refine_task`** – Recursively refine a single task
+  - Parameters: `task_description`, `parent_context`, `current_depth`, `max_depth`
+  - Returns: List of `Subtask` objects
+
+## Design Notes
+
+### Recursive Planning Strategy
+
+The planner uses a hierarchical approach:
+1. **Top-level decomposition**: Break the main question into 3-5 major areas
+2. **Recursive refinement**: For each area, break it down further if needed
+3. **Dependency identification**: Determine which tasks need results from others
+4. **Parallelization grouping**: Group tasks that can run simultaneously
+
+### Task Dependencies
+
+- **Independent tasks**: No dependencies, can run in parallel
+- **Sequential tasks**: Depend on one or more previous tasks
+- **Synthesis tasks**: Typically depend on all component tasks
+
+### Topological Graph
+
+The plan forms a DAG (Directed Acyclic Graph) where:
+- Nodes are tasks
+- Edges are dependencies
+- Tasks at the same level with no dependencies can run in parallel
+- The `parallelizable_groups` field identifies execution batches
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTFIELD_SERVER` | Control plane server URL | `http://localhost:8080` |
+| `AI_MODEL` | Primary LLM | `openrouter/openai/gpt-4o-mini` |
+| `PORT` | Agent server port | Auto-assigned |
+
+## Next Steps
+
+- Add task execution reasoners to actually perform research
+- Implement parallel execution using AgentField's workflow capabilities
+- Add result synthesis to combine findings from all tasks
+- Create visualization tools for the task graph
+- Add progress tracking and checkpointing
diff --git a/examples/python_agent_nodes/deep_research/__init__.py b/examples/python_agent_nodes/deep_research/__init__.py
new file mode 100644
index 00000000..47056d65
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/__init__.py
@@ -0,0 +1 @@
+"""Deep Research Agent with Recursive Planning."""
diff --git a/examples/python_agent_nodes/deep_research/main.py b/examples/python_agent_nodes/deep_research/main.py
new file mode 100644
index 00000000..c45d8d7e
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/main.py
@@ -0,0 +1,51 @@
+"""Deep Research Agent with Recursive Planning."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import sys
+
+from agentfield import AIConfig, Agent
+
+if __package__ in (None, ""):
+    current_dir = Path(__file__).resolve().parent
+    if str(current_dir) not in sys.path:
+        sys.path.insert(0, str(current_dir))
+
+from routers import planning_router, research_router
+
+app = Agent(
+    node_id="deep-research",
+    agentfield_server=f"{os.getenv('AGENTFIELD_SERVER', 'http://localhost:8080')}",
+    ai_config=AIConfig(
+        model=os.getenv("AI_MODEL", "openrouter/deepseek/deepseek-v3.1-terminus"),
+    ),
+)
+
+app.include_router(planning_router)
+app.include_router(research_router)
+
+
+if __name__ == "__main__":
+    print("🔬 Deep Research Agent")
+    print("🧠 Node ID: deep-research")
+    print(f"🌐 Control Plane: {app.agentfield_server}")
+    print("\n🎯 Architecture: Recursive Planning + Research Execution")
+    print("  1. Recursive Task Decomposition → Breaks research into subtasks")
+    print("  2. Topological Graph → Identifies dependencies and parallelization")
+    print("  3. Research Execution → Tavily search with citation tracking")
+    print("  4. Findings Synthesis → Structured results with sources")
+    print("\n✨ Features:")
+    print("  - Recursive task breakdown with configurable depth")
+    print("  - Automatic dependency detection")
+    print("  - Parallel execution planning")
+    print("  - Web search integration (Tavily)")
+    print("  - Citation tracking and structured findings")
+    print("  - Elegant and simple AgentField primitives")
+
+    port_env = os.getenv("PORT")
+    if port_env is None:
+        app.run(auto_port=True, host="::")
+    else:
+        app.run(port=int(port_env), host="::")
diff --git a/examples/python_agent_nodes/deep_research/requirements.txt b/examples/python_agent_nodes/deep_research/requirements.txt
new file mode 100644
index 00000000..afc26f24
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/requirements.txt
@@ -0,0 +1,3 @@
+pydantic>=2.7.4
+agentfield>=0.1.6
+tavily-python>=0.3.0
diff --git a/examples/python_agent_nodes/deep_research/routers/__init__.py b/examples/python_agent_nodes/deep_research/routers/__init__.py
new file mode 100644
index 00000000..650e25bd
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/routers/__init__.py
@@ -0,0 +1,6 @@
+"""Router modules for deep research agent."""
+
+from .planning import planning_router
+from .research import research_router
+
+__all__ = ["planning_router", "research_router"]
diff --git a/examples/python_agent_nodes/deep_research/routers/planning.py b/examples/python_agent_nodes/deep_research/routers/planning.py
new file mode 100644
index 00000000..e80df29f
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/routers/planning.py
@@ -0,0 +1,306 @@
+"""Recursive planning router for deep research agent."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import List
+
+from agentfield import AgentRouter
+
+from schemas import (
+    ResearchPlan,
+    Subtask,
+    TaskDescriptions,
+    TaskDependenciesList,
+)
+
+
+planning_router = AgentRouter(prefix="planning")
+
+
+def _build_topological_groups(tasks: List[Subtask]) -> List[List[str]]:
+    """
+    Build topological groups using topological sort.
+
+    Groups tasks by dependency level - all tasks at the same level
+    can run in parallel. Returns list of groups, where each group
+    contains task IDs that can execute in parallel.
+    """
+    task_map = {task.task_id: task for task in tasks}
+
+    # Calculate in-degree for each task (how many dependencies it has)
+    in_degree = {task_id: len(task.dependencies) for task_id, task in task_map.items()}
+
+    # Topological sort - group by level
+    level_groups: List[List[str]] = []
+    remaining = set(task_map.keys())
+
+    while remaining:
+        # Find all tasks with no remaining dependencies (current level)
+        current_level = [task_id for task_id in remaining if in_degree[task_id] == 0]
+
+        if not current_level:
+            # Circular dependency or error - add remaining tasks
+            current_level = list(remaining)
+
+        level_groups.append(current_level)
+        remaining -= set(current_level)
+
+        # Decrease in-degree for tasks that depend on current level
+        for task_id in current_level:
+            for dep_task in tasks:
+                if task_id in dep_task.dependencies and dep_task.task_id in remaining:
+                    in_degree[dep_task.task_id] -= 1
+
+    # Return groups with more than one task (parallelizable)
+    return [group for group in level_groups if len(group) > 1]
+
+
+@planning_router.reasoner()
+async def create_research_plan(
+    research_question: str,
+    max_depth: int = 3,
+    max_tasks_per_level: int = 5,
+) -> ResearchPlan:
+    """
+    Create a recursive research plan by breaking down a question into subtasks.
+
+    This reasoner recursively decomposes a research question into smaller,
+    manageable subtasks, forming a topological graph that can be executed
+    in parallel where dependencies allow.
+    """
+    # First, get initial breakdown from LLM - simplified to just descriptions
+    initial_response = await planning_router.ai(
+        system=(
+            "You are an expert research planner breaking down questions into a hierarchical task graph.\n\n"
+            "## PHILOSOPHY\n"
+            "You are creating two types of tasks:\n"
+            "1. **Leaf tasks** (no dependencies) = Specific questions that need web search\n"
+            "   - These are atomic research questions answerable via web search\n"
+            "   - Example: 'What is AgentField?' or 'What are AgentField's features?'\n\n"
+            "2. **Parent tasks** (have dependencies) = Questions answered by synthesizing children\n"
+            "   - These combine answers from child tasks\n"
+            "   - Example: 'Summarize AgentField' depends on 'What is AgentField?' and 'What are features?'\n\n"
+            "## DEPENDENCY MEANING\n"
+            "A task depends on another if it needs that task's ANSWER to proceed.\n"
+            "Dependencies mean: 'I need answers from those tasks to answer this.'\n\n"
+            "## YOUR TASK\n"
+            "Break the research question into 3-5 major research areas.\n"
+            "Each area should be a specific, searchable question (leaf task).\n"
+            "These will be refined recursively, and synthesis tasks will be created later.\n\n"
+            f"Maximum {max_tasks_per_level} tasks.\n\n"
+            "Return ONLY a JSON object with a 'descriptions' array."
+        ),
+        user=(
+            f"Research Question: {research_question}\n\n"
+            f"Break this into 3-5 major research areas as specific, searchable questions. "
+            f"Return only the descriptions array."
+        ),
+        schema=TaskDescriptions,
+    )
+
+    # Build initial Subtask objects from descriptions
+    initial_plan = [
+        Subtask(
+            task_id=f"task_{idx + 1}",
+            description=desc,
+            dependencies=[],
+            depth=1,
+            can_parallelize=True,
+        )
+        for idx, desc in enumerate(initial_response.descriptions)
+    ]
+
+    # Recursively refine each task
+    all_tasks: List[Subtask] = []
+
+    async def refine_recursively(
+        task: Subtask, parent_context: str = ""
+    ) -> List[Subtask]:
+        """Recursively refine a task by calling the refine_task reasoner."""
+        if task.depth >= max_depth:
+            # Base case: task is specific enough
+            return [task]
+
+        # Directly call the refine_task reasoner - this creates a workflow node
+        refined_tasks = await refine_task(
+            task_description=task.description,
+            parent_context=parent_context or research_question,
+            current_depth=task.depth,
+            max_depth=max_depth,
+        )
+
+        # Update task IDs to maintain hierarchy and recursively refine
+        result_tasks: List[Subtask] = []
+        for idx, refined_task in enumerate(refined_tasks):
+            new_task_id = f"{task.task_id}_{idx + 1}"
+            new_task = Subtask(
+                task_id=new_task_id,
+                description=refined_task.description,
+                dependencies=refined_task.dependencies,
+                depth=task.depth + 1,
+                can_parallelize=len(refined_task.dependencies) == 0,
+            )
+
+            # Recursively refine if still not at max depth
+            if new_task.depth < max_depth:
+                further_refined = await refine_recursively(new_task, task.description)
+                result_tasks.extend(further_refined)
+            else:
+                result_tasks.append(new_task)
+
+        # If no refinement happened, return the original task
+        return result_tasks if result_tasks else [task]
+
+    # Refine initial tasks - can run in parallel since they're independent
+    refinement_tasks = [
+        refine_recursively(initial_task, research_question)
+        for initial_task in initial_plan
+    ]
+    refined_results = await asyncio.gather(*refinement_tasks)
+
+    # Flatten the results
+    for refined_list in refined_results:
+        all_tasks.extend(refined_list)
+
+    # Identify dependencies between tasks
+    tasks_for_analysis = [
+        {"task_id": task.task_id, "description": task.description} for task in all_tasks
+    ]
+    dependencies_response = await identify_dependencies(
+        tasks_for_analysis, research_question
+    )
+
+    # Update task dependencies
+    task_map = {task.task_id: task for task in all_tasks}
+    dependency_map = {
+        dep.task_id: dep.depends_on for dep in dependencies_response.dependencies
+    }
+
+    for task in all_tasks:
+        if task.task_id in dependency_map:
+            task.dependencies = dependency_map[task.task_id]
+            # Validate dependencies exist
+            task.dependencies = [dep for dep in task.dependencies if dep in task_map]
+            task.can_parallelize = len(task.dependencies) == 0
+
+    # Build topological groups using topological sort
+    parallelizable_groups = _build_topological_groups(all_tasks)
+
+    return ResearchPlan(
+        research_question=research_question,
+        tasks=all_tasks,
+        max_depth=max(task.depth for task in all_tasks) if all_tasks else 0,
+        total_tasks=len(all_tasks),
+        parallelizable_groups=parallelizable_groups,
+    )
+
+
+@planning_router.reasoner()
+async def refine_task(
+    task_description: str,
+    parent_context: str = "",
+    current_depth: int = 0,
+    max_depth: int = 3,
+) -> List[Subtask]:
+    """
+    Recursively refine a single task into smaller subtasks.
+
+    This is a helper reasoner that can be called recursively to break down
+    complex tasks into more manageable pieces. Each call creates a workflow node.
+    """
+
+    if current_depth >= max_depth:
+        # Return the task as-is if we've hit max depth
+        return [
+            Subtask(
+                task_id=f"leaf_{current_depth}",
+                description=task_description,
+                dependencies=[],
+                depth=current_depth,
+                can_parallelize=True,
+            )
+        ]
+
+    # Use AI to determine if task needs further breakdown - simplified schema
+    result_response = await planning_router.ai(
+        system=(
+            "You are a task decomposition expert. Break down research tasks into "
+            "smaller subtasks.\n\n"
+            "Return ONLY a JSON object with a 'descriptions' array.\n"
+            "- If the task is specific enough, return it as a single-item array\n"
+            "- If it needs breakdown, return 2-4 smaller task descriptions\n"
+            "- Each description should be independently researchable\n\n"
+            f"Current depth: {current_depth} of {max_depth}. "
+            f"Only break down if still too complex."
+        ),
+        user=(
+            f"Task: {task_description}\n"
+            f"{f'Context: {parent_context}' if parent_context else ''}\n\n"
+            f"Break this into smaller tasks if needed, or return as-is if specific enough."
+        ),
+        schema=TaskDescriptions,
+    )
+
+    # Build Subtask objects from descriptions
+    refined_tasks = [
+        Subtask(
+            task_id=f"subtask_{idx}",
+            description=desc,
+            dependencies=[],
+            depth=current_depth + 1,
+            can_parallelize=True,
+        )
+        for idx, desc in enumerate(result_response.descriptions)
+    ]
+
+    return refined_tasks
+
+
+@planning_router.reasoner()
+async def identify_dependencies(
+    tasks: List[dict], research_question: str
+) -> TaskDependenciesList:
+    """
+    Identify dependencies between tasks based on their descriptions.
+
+    Takes a list of tasks with id and description, and identifies which
+    tasks need results from other tasks before they can execute.
+    """
+    # Format tasks for the prompt
+    tasks_text = "\n".join(
+        f"- {task['task_id']}: {task['description']}" for task in tasks
+    )
+
+    response = await planning_router.ai(
+        system=(
+            "You are a dependency analysis expert identifying task relationships.\n\n"
+            "## DEPENDENCY PHILOSOPHY\n"
+            "A task depends on another if it needs that task's ANSWER to proceed.\n"
+            "Dependencies mean: 'I need answers from those tasks to answer this.'\n\n"
+            "## DEPENDENCY PATTERNS\n"
+            "- **Comparison tasks** depend on individual research tasks\n"
+            "  Example: 'Compare X and Y' depends on 'What is X?' and 'What is Y?'\n\n"
+            "- **Synthesis tasks** depend on all component tasks\n"
+            "  Example: 'Summarize AgentField' depends on 'What is AgentField?' and 'What are features?'\n\n"
+            "- **Analysis tasks** depend on data-gathering tasks\n"
+            "  Example: 'Analyze trends' depends on 'What are the trends?'\n\n"
+            "## KEY PRINCIPLE\n"
+            "If a task can be answered by combining other tasks' findings, mark dependencies.\n"
+            "Leaf tasks (no dependencies) will be answered via web search.\n"
+            "Parent tasks (have dependencies) will synthesize from children's answers.\n\n"
+            "Return ONLY a JSON object with a 'dependencies' array. Each item:\n"
+            "- task_id: the task ID\n"
+            "- depends_on: array of task IDs it depends on (empty if independent/leaf task)\n\n"
+            "Be conservative - only mark dependencies when clearly needed."
+        ),
+        user=(
+            f"Research Question: {research_question}\n\n"
+            f"Tasks:\n{tasks_text}\n\n"
+            f"Identify dependencies. For each task, determine if it needs answers from other tasks. "
+            f"Return dependency mappings for all tasks."
+        ),
+        schema=TaskDependenciesList,
+    )
+
+    return response
diff --git a/examples/python_agent_nodes/deep_research/routers/research.py b/examples/python_agent_nodes/deep_research/routers/research.py
new file mode 100644
index 00000000..f801620d
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/routers/research.py
@@ -0,0 +1,169 @@
+"""Research execution router with Tavily integration."""
+
+from __future__ import annotations
+
+import os
+from typing import List
+
+from agentfield import AgentRouter
+
+from schemas import Citation, ResearchFindings, SearchQueries, TaskResult
+
+
+research_router = AgentRouter(prefix="research")
+
+
+@research_router.reasoner()
+async def generate_search_queries(
+    task_description: str, research_question: str
+) -> SearchQueries:
+    """Generate focused search queries for a research task."""
+    response = await research_router.ai(
+        system=(
+            "You are a search query expert. Generate 2-4 focused search queries "
+            "optimized for web search that will help answer the research task.\n\n"
+            "Each query should be:\n"
+            "- Specific and targeted\n"
+            "- Use relevant keywords\n"
+            "- Different angles/aspects of the task\n\n"
+            "Return ONLY a JSON object with a 'queries' array of search strings."
+        ),
+        user=(
+            f"Research Question: {research_question}\n"
+            f"Task: {task_description}\n\n"
+            f"Generate 2-4 search queries to research this task."
+        ),
+        schema=SearchQueries,
+    )
+    return response
+
+
+@research_router.reasoner()
+async def execute_search(queries: List[str]) -> dict:
+    """Execute Tavily search for given queries."""
+    try:
+        from tavily import TavilyClient
+    except ImportError:
+        raise ImportError("tavily-python not installed. Run: pip install tavily-python")
+
+    api_key = os.getenv("TAVILY_API_KEY")
+    if not api_key:
+        raise ValueError("TAVILY_API_KEY environment variable not set")
+
+    client = TavilyClient(api_key=api_key)
+
+    # Execute searches in parallel
+    all_results = []
+    for query in queries:
+        try:
+            result = client.search(
+                query=query,
+                search_depth="advanced",
+                max_results=5,
+                include_answer=False,
+                include_raw_content=True,
+            )
+            all_results.append(result)
+        except Exception as e:
+            # Continue with other queries if one fails
+            all_results.append({"error": str(e), "query": query})
+
+    # Combine results
+    combined = {
+        "results": [],
+        "queries": queries,
+    }
+
+    for result in all_results:
+        if "error" not in result and "results" in result:
+            combined["results"].extend(result["results"])
+
+    return combined
+
+
+@research_router.reasoner()
+async def synthesize_findings(
+    task_description: str,
+    research_question: str,
+    search_results: dict,
+) -> ResearchFindings:
+    """Synthesize search results into structured findings with citations."""
+    # Format search results for the prompt
+    results_text = ""
+    citations_data = []
+
+    for idx, result in enumerate(search_results.get("results", [])[:10]):
+        title = result.get("title", "Untitled")
+        url = result.get("url", "")
+        content = result.get("content", "")
+        raw_content = result.get("raw_content", "")
+
+        excerpt = raw_content[:500] if raw_content else content[:300]
+        results_text += f"\n[{idx+1}] {title}\nURL: {url}\nContent: {excerpt}\n"
+
+        citations_data.append({"url": url, "title": title, "excerpt": excerpt})
+
+    response = await research_router.ai(
+        system=(
+            "You are a research synthesis expert. Synthesize search results into "
+            "structured findings with numbered points.\n\n"
+            "Format findings as:\n"
+            "1. First finding [1] (reference by number)\n"
+            "2. Second finding [2]\n"
+            "etc.\n\n"
+            "Extract citations: for each numbered reference, provide URL, title, and excerpt.\n\n"
+            "Assess confidence: 'high' if comprehensive, 'medium' if partial, 'low' if insufficient."
+        ),
+        user=(
+            f"Research Question: {research_question}\n"
+            f"Task: {task_description}\n\n"
+            f"Search Results:{results_text}\n\n"
+            f"Synthesize findings with numbered points and citations. "
+            f"Reference sources by number [1], [2], etc."
+        ),
+        schema=ResearchFindings,
+    )
+
+    # Map citations from search results
+    citation_map = {idx + 1: Citation(**c) for idx, c in enumerate(citations_data)}
+
+    # Update citations in response based on references in findings
+    final_citations = []
+    for i in range(1, len(citations_data) + 1):
+        if f"[{i}]" in response.findings and i in citation_map:
+            final_citations.append(citation_map[i])
+
+    response.citations = final_citations
+    return response
+
+
+@research_router.reasoner()
+async def execute_research_task(
+    task_id: str,
+    task_description: str,
+    research_question: str,
+) -> TaskResult:
+    """Orchestrate research execution: queries → search → synthesize."""
+    # Generate search queries
+    queries_response = await generate_search_queries(
+        task_description, research_question
+    )
+
+    # Execute search
+    search_results = await execute_search(queries_response.queries)
+
+    # Synthesize findings
+    findings_response = await synthesize_findings(
+        task_description, research_question, search_results
+    )
+
+    # Convert to TaskResult
+    sources = [f"{c.title} ({c.url})" for c in findings_response.citations]
+
+    return TaskResult(
+        task_id=task_id,
+        description=task_description,
+        findings=findings_response.findings,
+        sources=sources,
+        confidence=findings_response.confidence,
+    )
diff --git a/examples/python_agent_nodes/deep_research/schemas.py b/examples/python_agent_nodes/deep_research/schemas.py
new file mode 100644
index 00000000..10971fe8
--- /dev/null
+++ b/examples/python_agent_nodes/deep_research/schemas.py
@@ -0,0 +1,127 @@
+"""Schemas for deep research agent with recursive planning."""
+
+from __future__ import annotations
+
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class Subtask(BaseModel):
+    """A single subtask in the research plan."""
+
+    task_id: str = Field(description="Unique identifier for this task")
+    description: str = Field(
+        description="Clear description of what needs to be researched"
+    )
+    dependencies: List[str] = Field(
+        default_factory=list,
+        description="List of task_ids that must complete before this task can start",
+    )
+    depth: int = Field(
+        default=0, description="Recursion depth - how many levels deep this task is"
+    )
+    can_parallelize: bool = Field(
+        default=True,
+        description="Whether this task can run in parallel with others (if no dependencies)",
+    )
+
+
+class SubtaskList(BaseModel):
+    """Wrapper for a list of subtasks - used for AI schema validation."""
+
+    tasks: List[Subtask] = Field(description="List of subtasks")
+
+
+class TaskDescriptions(BaseModel):
+    """Simple schema for task descriptions - just a list of strings."""
+
+    descriptions: List[str] = Field(
+        description="List of task descriptions, one per line. Each should be a clear, specific research task."
+    )
+
+
+class TaskDependencies(BaseModel):
+    """Dependency mapping for a single task."""
+
+    task_id: str = Field(description="The task ID")
+    depends_on: List[str] = Field(
+        default_factory=list,
+        description="List of task IDs that must complete before this task can start",
+    )
+
+
+class TaskDependenciesList(BaseModel):
+    """Wrapper for a list of task dependencies - used for AI schema validation."""
+
+    dependencies: List[TaskDependencies] = Field(
+        description="List of task dependency mappings"
+    )
+
+
+class ResearchPlan(BaseModel):
+    """Complete research plan with topological task graph."""
+
+    research_question: str = Field(description="The original research question")
+    tasks: List[Subtask] = Field(description="All subtasks in the plan")
+    max_depth: int = Field(
+        description="Maximum recursion depth reached during planning"
+    )
+    total_tasks: int = Field(description="Total number of tasks in the plan")
+    parallelizable_groups: List[List[str]] = Field(
+        default_factory=list,
+        description="Groups of task_ids that can be executed in parallel",
+    )
+
+
+class TaskResult(BaseModel):
+    """Result from executing a single research task."""
+
+    task_id: str
+    description: str
+    findings: str = Field(description="Research findings for this task")
+    sources: List[str] = Field(
+        default_factory=list, description="Sources or references used"
+    )
+    confidence: str = Field(description="Confidence level: 'high', 'medium', or 'low'")
+
+
+class ResearchReport(BaseModel):
+    """Final synthesized research report."""
+
+    research_question: str
+    executive_summary: str = Field(description="High-level summary of findings")
+    detailed_findings: List[TaskResult] = Field(
+        description="Detailed findings for each task"
+    )
+    conclusions: str = Field(description="Final conclusions and recommendations")
+    overall_confidence: str = Field(
+        description="Overall confidence: 'high', 'medium', or 'low'"
+    )
+
+
+class SearchQueries(BaseModel):
+    """Simple schema for search queries - list of strings."""
+
+    queries: List[str] = Field(
+        description="List of search query strings optimized for web search"
+    )
+
+
+class Citation(BaseModel):
+    """Citation for a source with URL, title, and excerpt."""
+
+    url: str = Field(description="Source URL")
+    title: str = Field(description="Source title")
+    excerpt: str = Field(description="Relevant excerpt from the source")
+
+
+class ResearchFindings(BaseModel):
+    """Structured research findings with numbered points and citations."""
+
+    findings: str = Field(
+        description="Research findings as numbered points (1. ... 2. ... etc.) with inline citations"
+    )
+    citations: List[Citation] = Field(
+        default_factory=list, description="List of citations referenced in findings"
+    )
+    confidence: str = Field(description="Confidence level: 'high', 'medium', or 'low'")

From 207eb9fe74779c091d759a3e6ee92be0bbeb87db Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Thu, 20 Nov 2025 15:06:46 -0500
Subject: [PATCH 07/11] Update research router in deep research example

---
 .../deep_research/routers/research.py         | 21 ++++++++++++-------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/examples/python_agent_nodes/deep_research/routers/research.py b/examples/python_agent_nodes/deep_research/routers/research.py
index f801620d..b628b44f 100644
--- a/examples/python_agent_nodes/deep_research/routers/research.py
+++ b/examples/python_agent_nodes/deep_research/routers/research.py
@@ -17,21 +17,26 @@
 async def generate_search_queries(
     task_description: str, research_question: str
 ) -> SearchQueries:
-    """Generate focused search queries for a research task."""
+    """Generate focused search queries for a leaf research task."""
     response = await research_router.ai(
         system=(
-            "You are a search query expert. Generate 2-4 focused search queries "
-            "optimized for web search that will help answer the research task.\n\n"
+            "You are a search query expert generating queries for a leaf task.\n\n"
+            "## CONTEXT\n"
+            "This is a LEAF TASK - it will be answered via web search.\n"
+            "Leaf tasks are atomic research questions that need specific web search results.\n\n"
+            "## YOUR TASK\n"
+            "Generate 2-4 focused search queries optimized for web search.\n\n"
             "Each query should be:\n"
-            "- Specific and targeted\n"
-            "- Use relevant keywords\n"
-            "- Different angles/aspects of the task\n\n"
+            "- Specific and targeted to answer the task question\n"
+            "- Use relevant keywords and terminology\n"
+            "- Cover different angles/aspects of the task\n"
+            "- Designed to find specific answers, not general information\n\n"
             "Return ONLY a JSON object with a 'queries' array of search strings."
         ),
         user=(
             f"Research Question: {research_question}\n"
-            f"Task: {task_description}\n\n"
-            f"Generate 2-4 search queries to research this task."
+            f"Leaf Task (needs web search): {task_description}\n\n"
+            f"Generate 2-4 search queries that will find specific answers to this question."
         ),
         schema=SearchQueries,
     )

From 294f2573c5e961e2d407724fa903ed6f9116ea1b Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Thu, 20 Nov 2025 15:08:32 -0500
Subject: [PATCH 08/11] Add synthesize_from_dependencies function to research
 router

---
 .../deep_research/routers/research.py         | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/examples/python_agent_nodes/deep_research/routers/research.py b/examples/python_agent_nodes/deep_research/routers/research.py
index b628b44f..a646bd9c 100644
--- a/examples/python_agent_nodes/deep_research/routers/research.py
+++ b/examples/python_agent_nodes/deep_research/routers/research.py
@@ -172,3 +172,68 @@ async def execute_research_task(
         sources=sources,
         confidence=findings_response.confidence,
     )
+
+
+@research_router.reasoner()
+async def synthesize_from_dependencies(
+    task_id: str,
+    task_description: str,
+    research_question: str,
+    dependency_findings: List[TaskResult],
+) -> TaskResult:
+    """
+    Synthesize answer for a parent task from its children's findings.
+
+    This is for tasks that have dependencies - they synthesize from
+    child task answers rather than searching the web.
+    """
+    # Format dependency findings for the prompt
+    children_text = "\n\n".join(
+        f"Child Task {idx + 1} ({dep.task_id}): {dep.description}\n"
+        f"Answer: {dep.findings}\n"
+        f"Sources: {', '.join(dep.sources) if dep.sources else 'N/A'}"
+        for idx, dep in enumerate(dependency_findings)
+    )
+
+    response = await research_router.ai(
+        system=(
+            "You are answering a PARENT TASK by synthesizing answers from child tasks.\n\n"
+            "## CONTEXT\n"
+            "This is a parent task - it depends on child tasks that have already been answered.\n"
+            "Your job is to combine the child answers to answer the parent question.\n\n"
+            "## IMPORTANT\n"
+            "- Do NOT search the web - use ONLY the provided child findings\n"
+            "- Synthesize and combine the child answers\n"
+            "- Create a coherent answer to the parent question\n"
+            "- Reference which child tasks contributed to each point\n\n"
+            "## OUTPUT FORMAT\n"
+            "Provide a structured answer with numbered points.\n"
+            "Reference child tasks like: 'Based on Child Task 1, ...'\n"
+            "Assess confidence based on completeness of child answers."
+        ),
+        user=(
+            f"Research Question: {research_question}\n\n"
+            f"Parent Task: {task_description}\n\n"
+            f"Child Task Answers:\n{children_text}\n\n"
+            f"Synthesize an answer to the parent task by combining the child task findings. "
+            f"Do not search - use only the provided child answers."
+        ),
+        schema=ResearchFindings,
+    )
+
+    # Collect sources from all dependencies
+    all_sources = []
+    for dep in dependency_findings:
+        all_sources.extend(dep.sources)
+
+    # Add references to child tasks
+    child_refs = [f"Child task {dep.task_id}" for dep in dependency_findings]
+    all_sources.extend(child_refs)
+
+    return TaskResult(
+        task_id=task_id,
+        description=task_description,
+        findings=response.findings,
+        sources=list(set(all_sources)),  # Deduplicate
+        confidence=response.confidence,
+    )

From 1bb263328d993b278367a2be307d97600d3707a1 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Thu, 20 Nov 2025 15:22:49 -0500
Subject: [PATCH 09/11] Add task deduplication and search strategy features to
 planning and research routers

Introduces new classes for task merging and search strategies in schemas. Enhances planning router with functions for deduplicating tasks and deciding search strategies based on dependencies. Updates research router to execute tasks with enhanced search capabilities using dependency context. Improves task management by ensuring distinct and non-overlapping tasks, and refines user prompts for clarity and specificity.
---
 .../deep_research/routers/planning.py         | 349 +++++++++++++++++-
 .../deep_research/routers/research.py         | 128 ++++++-
 .../deep_research/schemas.py                  |  29 ++
 3 files changed, 493 insertions(+), 13 deletions(-)

diff --git a/examples/python_agent_nodes/deep_research/routers/planning.py b/examples/python_agent_nodes/deep_research/routers/planning.py
index e80df29f..500b4703 100644
--- a/examples/python_agent_nodes/deep_research/routers/planning.py
+++ b/examples/python_agent_nodes/deep_research/routers/planning.py
@@ -9,9 +9,13 @@
 
 from schemas import (
     ResearchPlan,
+    ResearchReport,
+    SearchStrategy,
     Subtask,
     TaskDescriptions,
     TaskDependenciesList,
+    TaskMergeList,
+    TaskResult,
 )
 
 
@@ -56,6 +60,43 @@ def _build_topological_groups(tasks: List[Subtask]) -> List[List[str]]:
     return [group for group in level_groups if len(group) > 1]
 
 
+def _get_execution_levels(tasks: List[Subtask]) -> List[List[str]]:
+    """
+    Get all execution levels using topological sort.
+
+    Returns ALL levels (not just parallelizable groups).
+    Level 0 = leaf tasks (no dependencies, need search)
+    Level 1+ = parent tasks (have dependencies, synthesize from children)
+    """
+    task_map = {task.task_id: task for task in tasks}
+
+    # Calculate in-degree for each task
+    in_degree = {task_id: len(task.dependencies) for task_id, task in task_map.items()}
+
+    # Topological sort - group by level
+    level_groups: List[List[str]] = []
+    remaining = set(task_map.keys())
+
+    while remaining:
+        # Find all tasks with no remaining dependencies (current level)
+        current_level = [task_id for task_id in remaining if in_degree[task_id] == 0]
+
+        if not current_level:
+            # Circular dependency or error - add remaining tasks
+            current_level = list(remaining)
+
+        level_groups.append(current_level)
+        remaining -= set(current_level)
+
+        # Decrease in-degree for tasks that depend on current level
+        for task_id in current_level:
+            for dep_task in tasks:
+                if task_id in dep_task.dependencies and dep_task.task_id in remaining:
+                    in_degree[dep_task.task_id] -= 1
+
+    return level_groups
+
+
 @planning_router.reasoner()
 async def create_research_plan(
     research_question: str,
@@ -81,20 +122,26 @@ async def create_research_plan(
             "2. **Parent tasks** (have dependencies) = Questions answered by synthesizing children\n"
             "   - These combine answers from child tasks\n"
             "   - Example: 'Summarize AgentField' depends on 'What is AgentField?' and 'What are features?'\n\n"
+            "## CRITICAL: DISTINCT TASKS\n"
+            "Each task must be DISTINCT and NON-OVERLAPPING.\n"
+            "- Do NOT create tasks that ask the same question in different words\n"
+            "- Each task should cover a unique aspect or angle\n"
+            "- Avoid redundancy - if two tasks would find the same information, merge them\n\n"
             "## DEPENDENCY MEANING\n"
             "A task depends on another if it needs that task's ANSWER to proceed.\n"
             "Dependencies mean: 'I need answers from those tasks to answer this.'\n\n"
             "## YOUR TASK\n"
-            "Break the research question into 3-5 major research areas.\n"
+            "Break the research question into 3-5 DISTINCT major research areas.\n"
             "Each area should be a specific, searchable question (leaf task).\n"
+            "Ensure each task is unique and non-overlapping.\n"
             "These will be refined recursively, and synthesis tasks will be created later.\n\n"
             f"Maximum {max_tasks_per_level} tasks.\n\n"
             "Return ONLY a JSON object with a 'descriptions' array."
         ),
         user=(
             f"Research Question: {research_question}\n\n"
-            f"Break this into 3-5 major research areas as specific, searchable questions. "
-            f"Return only the descriptions array."
+            f"Break this into 3-5 DISTINCT major research areas as specific, searchable questions. "
+            f"Ensure each task is unique and covers different aspects. Return only the descriptions array."
         ),
         schema=TaskDescriptions,
     )
@@ -163,6 +210,42 @@ async def refine_recursively(
     for refined_list in refined_results:
         all_tasks.extend(refined_list)
 
+    # Deduplicate similar/redundant tasks
+    tasks_for_dedup = [
+        {"task_id": task.task_id, "description": task.description} for task in all_tasks
+    ]
+    merge_response = await deduplicate_tasks(tasks_for_dedup, research_question)
+
+    # Apply merges: keep the keep_task_id, remove merge_task_ids, update dependencies
+    task_map = {task.task_id: task for task in all_tasks}
+    tasks_to_remove = set()
+
+    for merge in merge_response.merges:
+        if merge.keep_task_id in task_map:
+            # Update dependencies: if any task depends on a merged task, point to kept task
+            for task in all_tasks:
+                if merge.keep_task_id != task.task_id:
+                    # Replace merged task IDs with kept task ID in dependencies
+                    if merge.keep_task_id in task.dependencies:
+                        # Already depends on kept task, remove merged ones
+                        task.dependencies = [
+                            dep
+                            for dep in task.dependencies
+                            if dep not in merge.merge_task_ids
+                        ]
+                    else:
+                        # Replace merged task IDs with kept task ID
+                        task.dependencies = [
+                            merge.keep_task_id if dep in merge.merge_task_ids else dep
+                            for dep in task.dependencies
+                        ]
+
+            # Mark merged tasks for removal
+            tasks_to_remove.update(merge.merge_task_ids)
+
+    # Remove merged tasks
+    all_tasks = [task for task in all_tasks if task.task_id not in tasks_to_remove]
+
     # Identify dependencies between tasks
     tasks_for_analysis = [
         {"task_id": task.task_id, "description": task.description} for task in all_tasks
@@ -227,17 +310,23 @@ async def refine_task(
         system=(
             "You are a task decomposition expert. Break down research tasks into "
             "smaller subtasks.\n\n"
+            "## CRITICAL: DISTINCT SUBTASKS\n"
+            "When breaking down, create DISTINCT, NON-OVERLAPPING subtasks:\n"
+            "- Each subtask should cover a unique aspect\n"
+            "- Do NOT create subtasks that ask the same question\n"
+            "- Ensure each subtask is independently researchable\n\n"
             "Return ONLY a JSON object with a 'descriptions' array.\n"
             "- If the task is specific enough, return it as a single-item array\n"
-            "- If it needs breakdown, return 2-4 smaller task descriptions\n"
-            "- Each description should be independently researchable\n\n"
+            "- If it needs breakdown, return 2-4 DISTINCT smaller task descriptions\n"
+            "- Each description must be unique and non-overlapping\n\n"
             f"Current depth: {current_depth} of {max_depth}. "
             f"Only break down if still too complex."
         ),
         user=(
             f"Task: {task_description}\n"
             f"{f'Context: {parent_context}' if parent_context else ''}\n\n"
-            f"Break this into smaller tasks if needed, or return as-is if specific enough."
+            f"Break this into DISTINCT smaller tasks if needed, or return as-is if specific enough. "
+            f"Ensure each subtask is unique and non-overlapping."
         ),
         schema=TaskDescriptions,
     )
@@ -278,6 +367,11 @@ async def identify_dependencies(
             "## DEPENDENCY PHILOSOPHY\n"
             "A task depends on another if it needs that task's ANSWER to proceed.\n"
             "Dependencies mean: 'I need answers from those tasks to answer this.'\n\n"
+            "## CRITICAL: AVOID REDUNDANT DEPENDENCIES\n"
+            "- Do NOT mark dependencies if tasks ask the same question\n"
+            "- Do NOT mark dependencies if a task can be answered independently\n"
+            "- Only mark dependencies when a task truly needs another task's answer\n"
+            "- If two tasks would find the same information, they should NOT depend on each other\n\n"
             "## DEPENDENCY PATTERNS\n"
             "- **Comparison tasks** depend on individual research tasks\n"
             "  Example: 'Compare X and Y' depends on 'What is X?' and 'What is Y?'\n\n"
@@ -292,15 +386,256 @@ async def identify_dependencies(
             "Return ONLY a JSON object with a 'dependencies' array. Each item:\n"
             "- task_id: the task ID\n"
             "- depends_on: array of task IDs it depends on (empty if independent/leaf task)\n\n"
-            "Be conservative - only mark dependencies when clearly needed."
+            "Be conservative - only mark dependencies when clearly needed. "
+            "Avoid redundant dependencies between similar tasks."
         ),
         user=(
             f"Research Question: {research_question}\n\n"
             f"Tasks:\n{tasks_text}\n\n"
             f"Identify dependencies. For each task, determine if it needs answers from other tasks. "
+            f"DO NOT mark dependencies if tasks ask the same question or can be answered independently. "
             f"Return dependency mappings for all tasks."
         ),
         schema=TaskDependenciesList,
     )
 
     return response
+
+
+@planning_router.reasoner()
+async def deduplicate_tasks(tasks: List[dict], research_question: str) -> TaskMergeList:
+    """
+    Identify and merge similar/redundant tasks.
+
+    Finds tasks that ask the same question or cover the same information,
+    and suggests which tasks to merge into others.
+    """
+    tasks_text = "\n".join(
+        f"- {task['task_id']}: {task['description']}" for task in tasks
+    )
+
+    response = await planning_router.ai(
+        system=(
+            "You are a task deduplication expert. Identify tasks that are redundant or ask the same question.\n\n"
+            "## YOUR TASK\n"
+            "Find tasks that:\n"
+            "- Ask the same question in different words\n"
+            "- Cover the same information/research area\n"
+            "- Are essentially duplicates\n\n"
+            "For each group of similar tasks:\n"
+            "- Keep the most specific/clear task (keep_task_id)\n"
+            "- Mark others to merge (merge_task_ids)\n\n"
+            "## IMPORTANT\n"
+            "- Only merge tasks that are truly redundant\n"
+            "- Keep tasks that cover different aspects, even if related\n"
+            "- Be conservative - when in doubt, don't merge\n\n"
+            "Return ONLY a JSON object with a 'merges' array. "
+            "Each merge has keep_task_id and merge_task_ids."
+        ),
+        user=(
+            f"Research Question: {research_question}\n\n"
+            f"Tasks:\n{tasks_text}\n\n"
+            f"Identify redundant tasks and suggest merges. Return merge instructions."
+        ),
+        schema=TaskMergeList,
+    )
+
+    return response
+
+
+@planning_router.reasoner()
+async def decide_search_strategy(
+    task_description: str,
+    research_question: str,
+    dependency_findings: List[TaskResult],
+) -> SearchStrategy:
+    """
+    Decide whether a parent task should:
+    - synthesize_only: Answer from children's findings alone
+    - enhanced_search: Need additional web search with dependency context
+
+    Examples:
+    - "Summarize X" when we have "What is X?" → synthesize_only
+    - "Compare X to Y" when we have "What is X?" → enhanced_search (need Y info)
+    """
+    children_text = "\n".join(
+        f"- {dep.task_id}: {dep.description}\n  Answer: {dep.findings[:200]}..."
+        for dep in dependency_findings
+    )
+
+    response = await planning_router.ai(
+        system=(
+            "You are a task strategy expert deciding how to answer a parent task.\n\n"
+            "## TWO STRATEGIES\n"
+            "1. **synthesize_only**: Can answer from children's findings alone\n"
+            "   - Example: 'Summarize X' when we have 'What is X?' and 'What are X's features?'\n"
+            "   - Example: 'List all features' when we have individual feature tasks\n\n"
+            "2. **enhanced_search**: Needs additional web search with dependency context\n"
+            "   - Example: 'Compare X to Y' when we have 'What is X?' but need Y info\n"
+            "   - Example: 'Analyze market trends' when we have data but need external context\n"
+            "   - Example: 'Find competitors' when we have product info but need market research\n\n"
+            "## DECISION CRITERIA\n"
+            "- If the task asks for information NOT in children → enhanced_search\n"
+            "- If the task can be answered by combining children → synthesize_only\n"
+            "- If the task needs external context/comparison → enhanced_search\n"
+            "- If the task is pure synthesis/summary → synthesize_only\n\n"
+            "Return ONLY a JSON object with 'strategy' ('synthesize_only' or 'enhanced_search') "
+            "and 'reasoning' (brief explanation)."
+        ),
+        user=(
+            f"Research Question: {research_question}\n\n"
+            f"Parent Task: {task_description}\n\n"
+            f"Child Task Answers:\n{children_text}\n\n"
+            f"Decide: Can we answer the parent task from children alone, or do we need additional search? "
+            f"Return strategy and reasoning."
+        ),
+        schema=SearchStrategy,
+    )
+
+    return response
+
+
+async def _execute_task_smart(
+    task: Subtask,
+    research_question: str,
+    completed_results: dict[str, TaskResult],
+) -> TaskResult:
+    """
+    Smart task executor that routes to search or synthesis based on dependencies and strategy.
+
+    - Leaf tasks (no deps) → search via execute_research_task
+    - Parent tasks (has deps) → decide strategy:
+      - synthesize_only → synthesize_from_dependencies
+      - enhanced_search → execute_research_task_with_context
+    """
+    from routers.research import (
+        execute_research_task,
+        execute_research_task_with_context,
+        synthesize_from_dependencies,
+    )
+
+    if not task.dependencies:
+        # Leaf task - search for answers
+        return await execute_research_task(
+            task_id=task.task_id,
+            task_description=task.description,
+            research_question=research_question,
+        )
+    else:
+        # Parent task - get dependency findings
+        dependency_findings = [
+            completed_results[dep_id]
+            for dep_id in task.dependencies
+            if dep_id in completed_results
+        ]
+
+        # Decide strategy: synthesize_only or enhanced_search
+        strategy = await decide_search_strategy(
+            task_description=task.description,
+            research_question=research_question,
+            dependency_findings=dependency_findings,
+        )
+
+        if strategy.strategy == "synthesize_only":
+            # Pure synthesis from children
+            return await synthesize_from_dependencies(
+                task_id=task.task_id,
+                task_description=task.description,
+                research_question=research_question,
+                dependency_findings=dependency_findings,
+            )
+        else:
+            # Enhanced search with dependency context
+            return await execute_research_task_with_context(
+                task_id=task.task_id,
+                task_description=task.description,
+                research_question=research_question,
+                dependency_findings=dependency_findings,
+            )
+
+
+@planning_router.reasoner()
+async def execute_deep_research(
+    research_question: str,
+    max_depth: int = 3,
+    max_tasks_per_level: int = 5,
+) -> ResearchReport:
+    """
+    Complete deep research orchestrator.
+
+    Takes a research question and:
+    1. Creates recursive research plan with dependencies
+    2. Executes tasks in topological order (leaf tasks search, parent tasks synthesize)
+    3. Synthesizes final comprehensive report
+    """
+    # Step 1: Create research plan
+    plan = await create_research_plan(
+        research_question=research_question,
+        max_depth=max_depth,
+        max_tasks_per_level=max_tasks_per_level,
+    )
+
+    # Step 2: Get execution levels (topological order)
+    execution_levels = _get_execution_levels(plan.tasks)
+    task_map = {task.task_id: task for task in plan.tasks}
+    completed_results: dict[str, TaskResult] = {}
+
+    # Step 3: Execute tasks level by level
+    for level_idx, level_tasks in enumerate(execution_levels):
+        # Execute tasks in parallel within each level
+        execution_coroutines = [
+            _execute_task_smart(
+                task=task_map[task_id],
+                research_question=research_question,
+                completed_results=completed_results,
+            )
+            for task_id in level_tasks
+            if task_id in task_map
+        ]
+
+        if execution_coroutines:
+            level_results = await asyncio.gather(*execution_coroutines)
+            for result in level_results:
+                completed_results[result.task_id] = result
+
+    # Step 4: Synthesize final report
+    all_findings = list(completed_results.values())
+
+    # Build context for final synthesis
+    findings_text = "\n\n".join(
+        f"Task {r.task_id}: {r.description}\n"
+        f"Findings: {r.findings}\n"
+        f"Sources: {', '.join(r.sources) if r.sources else 'Synthesized from child tasks'}\n"
+        f"Confidence: {r.confidence}"
+        for r in all_findings
+    )
+
+    synthesis = await planning_router.ai(
+        system=(
+            "You are a research synthesis expert creating a comprehensive final report.\n\n"
+            "## CONTEXT\n"
+            "You are synthesizing findings from multiple research tasks into a final report.\n"
+            "Each task has been answered (either via web search for leaf tasks, or "
+            "synthesis for parent tasks).\n\n"
+            "## YOUR TASK\n"
+            "Create a comprehensive research report that:\n"
+            "1. Provides an executive summary answering the main research question\n"
+            "2. Organizes detailed findings by topic/theme\n"
+            "3. Draws conclusions and key insights\n"
+            "4. Assesses overall confidence based on all task findings\n\n"
+            "Structure the report clearly and comprehensively."
+        ),
+        user=(
+            f"Research Question: {research_question}\n\n"
+            f"All Task Findings:\n{findings_text}\n\n"
+            f"Create a comprehensive research report that synthesizes all findings "
+            f"to answer the research question. Include executive summary, detailed findings, "
+            f"conclusions, and overall confidence assessment."
+        ),
+        schema=ResearchReport,
+    )
+
+    # Attach detailed findings
+    synthesis.detailed_findings = all_findings
+
+    return synthesis
diff --git a/examples/python_agent_nodes/deep_research/routers/research.py b/examples/python_agent_nodes/deep_research/routers/research.py
index a646bd9c..70df2e13 100644
--- a/examples/python_agent_nodes/deep_research/routers/research.py
+++ b/examples/python_agent_nodes/deep_research/routers/research.py
@@ -15,15 +15,30 @@
 
 @research_router.reasoner()
 async def generate_search_queries(
-    task_description: str, research_question: str
+    task_description: str,
+    research_question: str,
+    dependency_context: str = "",
 ) -> SearchQueries:
-    """Generate focused search queries for a leaf research task."""
+    """Generate focused search queries for a research task, optionally with dependency context."""
+    context_section = ""
+    if dependency_context:
+        context_section = (
+            "\n## DEPENDENCY CONTEXT\n"
+            "You have answers from child tasks. Use this context to enhance your search queries:\n"
+            f"{dependency_context}\n\n"
+            "Your queries should:\n"
+            "- Build on the provided context\n"
+            "- Fill gaps or find additional information needed\n"
+            "- Use context to make queries more specific and targeted\n"
+        )
+
     response = await research_router.ai(
         system=(
-            "You are a search query expert generating queries for a leaf task.\n\n"
+            "You are a search query expert generating queries for a research task.\n\n"
             "## CONTEXT\n"
-            "This is a LEAF TASK - it will be answered via web search.\n"
-            "Leaf tasks are atomic research questions that need specific web search results.\n\n"
+            "This task will be answered via web search.\n"
+            "Generate queries optimized for finding specific answers.\n\n"
+            f"{context_section}"
             "## YOUR TASK\n"
             "Generate 2-4 focused search queries optimized for web search.\n\n"
             "Each query should be:\n"
@@ -35,7 +50,8 @@ async def generate_search_queries(
         ),
         user=(
             f"Research Question: {research_question}\n"
-            f"Leaf Task (needs web search): {task_description}\n\n"
+            f"Task (needs web search): {task_description}\n\n"
+            f"{f'Context from dependencies: {dependency_context}' if dependency_context else ''}\n\n"
             f"Generate 2-4 search queries that will find specific answers to this question."
         ),
         schema=SearchQueries,
@@ -237,3 +253,103 @@ async def synthesize_from_dependencies(
         sources=list(set(all_sources)),  # Deduplicate
         confidence=response.confidence,
     )
+
+
+@research_router.reasoner()
+async def execute_research_task_with_context(
+    task_id: str,
+    task_description: str,
+    research_question: str,
+    dependency_findings: List[TaskResult],
+) -> TaskResult:
+    """
+    Execute research task with dependency context for enhanced search.
+
+    This is for parent tasks that need additional web search beyond
+    what their children provide. Uses dependency context to enhance queries.
+    """
+    # Format dependency context for query generation
+    dependency_context = "\n\n".join(
+        f"Child Task {idx + 1} ({dep.task_id}): {dep.description}\n"
+        f"Answer: {dep.findings}"
+        for idx, dep in enumerate(dependency_findings)
+    )
+
+    # Generate enhanced search queries with context
+    queries_response = await generate_search_queries(
+        task_description=task_description,
+        research_question=research_question,
+        dependency_context=dependency_context,
+    )
+
+    # Execute search
+    search_results = await execute_search(queries_response.queries)
+
+    # Synthesize findings (can reference both search results and dependency context)
+    results_text = ""
+    citations_data = []
+
+    for idx, result in enumerate(search_results.get("results", [])[:10]):
+        title = result.get("title", "Untitled")
+        url = result.get("url", "")
+        content = result.get("content", "")
+        raw_content = result.get("raw_content", "")
+
+        excerpt = raw_content[:500] if raw_content else content[:300]
+        results_text += f"\n[{idx+1}] {title}\nURL: {url}\nContent: {excerpt}\n"
+
+        citations_data.append({"url": url, "title": title, "excerpt": excerpt})
+
+    # Synthesize with both search results and dependency context
+    response = await research_router.ai(
+        system=(
+            "You are a research synthesis expert. Synthesize findings from web search "
+            "AND dependency context into structured findings.\n\n"
+            "## CONTEXT\n"
+            "You have:\n"
+            "1. Web search results (new information)\n"
+            "2. Dependency context (answers from child tasks)\n\n"
+            "## YOUR TASK\n"
+            "Combine both sources to answer the task question comprehensively.\n"
+            "Format findings as:\n"
+            "1. First finding [1] (reference by number)\n"
+            "2. Second finding [2]\n"
+            "etc.\n\n"
+            "Extract citations: for each numbered reference, provide URL, title, and excerpt.\n\n"
+            "Assess confidence: 'high' if comprehensive, 'medium' if partial, 'low' if insufficient."
+        ),
+        user=(
+            f"Research Question: {research_question}\n"
+            f"Task: {task_description}\n\n"
+            f"Dependency Context (from child tasks):\n{dependency_context}\n\n"
+            f"Web Search Results:{results_text}\n\n"
+            f"Synthesize findings combining both sources. "
+            f"Reference web sources by number [1], [2], etc."
+        ),
+        schema=ResearchFindings,
+    )
+
+    # Map citations from search results
+    citation_map = {idx + 1: Citation(**c) for idx, c in enumerate(citations_data)}
+
+    # Update citations in response based on references in findings
+    final_citations = []
+    for i in range(1, len(citations_data) + 1):
+        if f"[{i}]" in response.findings and i in citation_map:
+            final_citations.append(citation_map[i])
+
+    response.citations = final_citations
+
+    # Collect sources from dependencies and search
+    all_sources = []
+    for dep in dependency_findings:
+        all_sources.extend(dep.sources)
+    all_sources.extend([f"{c.title} ({c.url})" for c in final_citations])
+
+    return TaskResult(
+        task_id=task_id,
+        description=task_description,
+        findings=response.findings,
+        sources=list(set(all_sources)),  # Deduplicate
+        confidence=response.confidence,
+    )
diff --git a/examples/python_agent_nodes/deep_research/schemas.py b/examples/python_agent_nodes/deep_research/schemas.py
index 10971fe8..f7f7a8d4 100644
--- a/examples/python_agent_nodes/deep_research/schemas.py
+++ b/examples/python_agent_nodes/deep_research/schemas.py
@@ -125,3 +125,32 @@ class ResearchFindings(BaseModel):
         default_factory=list, description="List of citations referenced in findings"
     )
     confidence: str = Field(description="Confidence level: 'high', 'medium', or 'low'")
+
+
+class TaskMerge(BaseModel):
+    """Task merge instruction for deduplication."""
+
+    keep_task_id: str = Field(description="Task ID to keep (most specific)")
+    merge_task_ids: List[str] = Field(
+        description="Task IDs to merge into the kept task"
+    )
+
+
+class TaskMergeList(BaseModel):
+    """List of task merges for deduplication."""
+
+    merges: List[TaskMerge] = Field(
+        default_factory=list, description="List of task merge instructions"
+    )
+
+
+class SearchStrategy(BaseModel):
+    """Search strategy decision for a parent task."""
+
+    strategy: str = Field(
+        description="Strategy: 'synthesize_only' or 'enhanced_search'"
+    )
+    reasoning: str = Field(
+        default="",
+        description="Brief reasoning for the strategy choice",
+    )

From 695ba6c014778aa8ec18ee7226bdadae00a38f56 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Thu, 20 Nov 2025 15:24:49 -0500
Subject: [PATCH 10/11] Update README for deep research example

---
 .../deep_research/README.md                   | 188 +++++-------------
 1 file changed, 49 insertions(+), 139 deletions(-)

diff --git a/examples/python_agent_nodes/deep_research/README.md b/examples/python_agent_nodes/deep_research/README.md
index 942e5115..01eb5206 100644
--- a/examples/python_agent_nodes/deep_research/README.md
+++ b/examples/python_agent_nodes/deep_research/README.md
@@ -1,168 +1,78 @@
-# Deep Research Agent (Recursive Planning)
+# Deep Research Agent
 
-A research agent that uses recursive planning to break down complex research questions into manageable subtasks, forming a topological graph that can be executed in parallel.
+A research agent that uses recursive planning to break down research questions into subtasks, forms a topological graph for parallel execution, deduplicates tasks, and synthesizes comprehensive reports.
 
-## Highlights
+## Features
 
-- **Recursive Planning** – Automatically breaks down research questions into subtasks with configurable depth
-- **Topological Graph** – Identifies task dependencies and parallelization opportunities
-- **Simple & Elegant** – Uses AgentField primitives for clean, maintainable code
-- **Single Router Architecture** – All planning logic in one router for simplicity
-
-## Architecture
-
-### Recursive Planning System
-
-1. **Research Plan Creation** (`create_research_plan`)
-   - Takes a research question and breaks it down recursively
-   - Identifies dependencies between tasks
-   - Groups tasks for parallel execution
-   - Returns a complete `ResearchPlan` with topological structure
-
-2. **Task Refinement** (`refine_task`)
-   - Helper reasoner for recursive task decomposition
-   - Can be called to further break down complex tasks
-   - Respects maximum depth constraints
-
-## Project Structure
-
-```
-deep_research/
-├── main.py            # Agent bootstrap
-├── schemas.py         # Pydantic models for planning
-├── routers/
-│   ├── __init__.py
-│   └── planning.py    # Recursive planning router
-├── requirements.txt
-└── README.md
-```
+- **Recursive Planning** – Breaks down questions into subtasks with configurable depth
+- **Task Deduplication** – Merges redundant tasks
+- **Smart Search Strategy** – Decides synthesis-only vs enhanced search for parent tasks
+- **Topological Execution** – Parallel execution with dependency management
+- **Web Search** – Tavily API integration with citation tracking
 
 ## Quick Start
 
-### 1. Install Dependencies
+### 1. Install & Setup
 
 ```bash
 pip install -r examples/python_agent_nodes/deep_research/requirements.txt
+export TAVILY_API_KEY="your-tavily-api-key"
 ```
 
-### 2. Run the Agent
+### 2. Run Agent
 
 ```bash
 python examples/python_agent_nodes/deep_research/main.py
 ```
 
-### 3. Create a Research Plan
-
-POST to `/reasoners/planning_create_research_plan`:
+### 3. Execute Research
 
-```json
-{
-  "research_question": "What are the environmental impacts of electric vehicles compared to traditional vehicles?",
-  "max_depth": 3,
-  "max_tasks_per_level": 5
-}
-```
-
-### Response Format
-
-```json
-{
-  "research_question": "What are the environmental impacts of electric vehicles compared to traditional vehicles?",
-  "tasks": [
-    {
-      "task_id": "task_1",
-      "description": "Research manufacturing environmental impact of EVs",
-      "dependencies": [],
-      "depth": 1,
-      "can_parallelize": true
-    },
-    {
-      "task_id": "task_2",
-      "description": "Research manufacturing environmental impact of traditional vehicles",
-      "dependencies": [],
-      "depth": 1,
-      "can_parallelize": true
-    },
-    {
-      "task_id": "task_3",
-      "description": "Research operational emissions of EVs",
-      "dependencies": [],
-      "depth": 1,
-      "can_parallelize": true
-    },
-    {
-      "task_id": "task_4",
-      "description": "Compare manufacturing impacts",
-      "dependencies": ["task_1", "task_2"],
-      "depth": 2,
-      "can_parallelize": false
-    },
-    {
-      "task_id": "task_5",
-      "description": "Synthesize overall comparison",
-      "dependencies": ["task_3", "task_4"],
-      "depth": 3,
-      "can_parallelize": false
-    }
-  ],
-  "max_depth": 3,
-  "total_tasks": 5,
-  "parallelizable_groups": [
-    ["task_1", "task_2", "task_3"],
-    ["task_4"],
-    ["task_5"]
-  ]
-}
+```bash
+curl -X POST http://localhost:8080/reasoners/planning_execute_deep_research \
+  -H "Content-Type: application/json" \
+  -d '{
+    "research_question": "What is AgentField.ai?",
+    "max_depth": 3,
+    "max_tasks_per_level": 5
+  }'
 ```
 
-## Available Endpoints
-
-### Reasoners
-
-- **`/reasoners/planning_create_research_plan`** – Create a recursive research plan
-  - Parameters: `research_question`, `max_depth` (default: 3), `max_tasks_per_level` (default: 5)
-  - Returns: `ResearchPlan` with tasks, dependencies, and parallelization groups
-
-- **`/reasoners/planning_refine_task`** – Recursively refine a single task
-  - Parameters: `task_description`, `parent_context`, `current_depth`, `max_depth`
-  - Returns: List of `Subtask` objects
+## Architecture
 
-## Design Notes
+1. **Plan Creation** – Recursively breaks question into distinct tasks
+2. **Deduplication** – Merges redundant tasks
+3. **Dependency Identification** – Maps task dependencies
+4. **Execution** – Topological order:
+   - Leaf tasks → web search
+   - Parent tasks → synthesis or enhanced search (with context)
+5. **Synthesis** – Final report from all findings
 
-### Recursive Planning Strategy
+## Endpoints
 
-The planner uses a hierarchical approach:
-1. **Top-level decomposition**: Break the main question into 3-5 major areas
-2. **Recursive refinement**: For each area, break it down further if needed
-3. **Dependency identification**: Determine which tasks need results from others
-4. **Parallelization grouping**: Group tasks that can run simultaneously
+### Main
+- **`/reasoners/planning_execute_deep_research`** – Complete workflow (recommended)
+  - Params: `research_question`, `max_depth` (default: 3), `max_tasks_per_level` (default: 5)
 
-### Task Dependencies
+### Planning
+- `/reasoners/planning_create_research_plan` – Create plan only
+- `/reasoners/planning_deduplicate_tasks` – Deduplicate tasks
+- `/reasoners/planning_identify_dependencies` – Identify dependencies
+- `/reasoners/planning_decide_search_strategy` – Decide search strategy
 
-- **Independent tasks**: No dependencies, can run in parallel
-- **Sequential tasks**: Depend on one or more previous tasks
-- **Synthesis tasks**: Typically depend on all component tasks
+### Research
+- `/reasoners/research_execute_research_task` – Execute leaf task (search)
+- `/reasoners/research_execute_research_task_with_context` – Execute with dependency context
+- `/reasoners/research_synthesize_from_dependencies` – Synthesize from children
 
-### Topological Graph
+## Task Types
 
-The plan forms a DAG (Directed Acyclic Graph) where:
-- Nodes are tasks
-- Edges are dependencies
-- Tasks at the same level with no dependencies can run in parallel
-- The `parallelizable_groups` field identifies execution batches
+- **Leaf Tasks** (no deps) → Web search
+- **Parent Tasks** (has deps) → Synthesis-only or enhanced search with context
 
 ## Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `AGENTFIELD_SERVER` | Control plane server URL | `http://localhost:8080` |
-| `AI_MODEL` | Primary LLM | `openrouter/openai/gpt-4o-mini` |
-| `PORT` | Agent server port | Auto-assigned |
-
-## Next Steps
-
-- Add task execution reasoners to actually perform research
-- Implement parallel execution using AgentField's workflow capabilities
-- Add result synthesis to combine findings from all tasks
-- Create visualization tools for the task graph
-- Add progress tracking and checkpointing
+| Variable            | Description               | Default                                      |
+| ------------------- | ------------------------- | -------------------------------------------- |
+| `TAVILY_API_KEY`    | Tavily API key (required) | -                                            |
+| `AGENTFIELD_SERVER` | Control plane URL         | `http://localhost:8080`                      |
+| `AI_MODEL`          | LLM model                 | `openrouter/deepseek/deepseek-v3.1-terminus` |

From e36a723bd03f9d3fdc1f41a3a8328df5ac8e9804 Mon Sep 17 00:00:00 2001
From: santoshkumarradha <instrument.santosh@gmail.com>
Date: Thu, 20 Nov 2025 15:25:45 -0500
Subject: [PATCH 11/11] Format code with ruff

---
 examples/python_agent_nodes/deep_research/routers/research.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/python_agent_nodes/deep_research/routers/research.py b/examples/python_agent_nodes/deep_research/routers/research.py
index 70df2e13..dcc71a3a 100644
--- a/examples/python_agent_nodes/deep_research/routers/research.py
+++ b/examples/python_agent_nodes/deep_research/routers/research.py
@@ -120,7 +120,7 @@ async def synthesize_findings(
         raw_content = result.get("raw_content", "")
 
         excerpt = raw_content[:500] if raw_content else content[:300]
-        results_text += f"\n[{idx+1}] {title}\nURL: {url}\nContent: {excerpt}\n"
+        results_text += f"\n[{idx + 1}] {title}\nURL: {url}\nContent: {excerpt}\n"
 
         citations_data.append({"url": url, "title": title, "excerpt": excerpt})
 
@@ -296,7 +296,7 @@ async def execute_research_task_with_context(
         raw_content = result.get("raw_content", "")
 
         excerpt = raw_content[:500] if raw_content else content[:300]
-        results_text += f"\n[{idx+1}] {title}\nURL: {url}\nContent: {excerpt}\n"
+        results_text += f"\n[{idx + 1}] {title}\nURL: {url}\nContent: {excerpt}\n"
 
         citations_data.append({"url": url, "title": title, "excerpt": excerpt})