feat: implement contracts and enhance UI descriptions for clarity and accuracy

src/agentic/contracts.py

@@ -0,0 +1,158 @@
+import enum
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+class FailureClass(str, enum.Enum):
+    EDA_TOOL_ERROR = "EDA_TOOL_ERROR"
+    LLM_FORMAT_ERROR = "LLM_FORMAT_ERROR"
+    LLM_SEMANTIC_ERROR = "LLM_SEMANTIC_ERROR"
+    ORCHESTRATOR_ROUTING_ERROR = "ORCHESTRATOR_ROUTING_ERROR"
+    RETRY_BUDGET_ERROR = "RETRY_BUDGET_ERROR"
+    INFRASTRUCTURE_ERROR = "INFRASTRUCTURE_ERROR"
+    UNKNOWN = "UNKNOWN"
+
+
+class StageStatus(str, enum.Enum):
+    PASS = "PASS"
+    FAIL = "FAIL"
+    RETRY = "RETRY"
+    SKIP = "SKIP"
+    ERROR = "ERROR"
+
+
+@dataclass
+class ArtifactRef:
+    key: str
+    producer: str
+    consumer: str = ""
+    required: bool = False
+    blocking: bool = False
+    value: Any = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class FailureRecord:
+    failure_class: FailureClass
+    producer: str
+    message: str
+    diagnostics: List[str] = field(default_factory=list)
+    raw_excerpt: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = asdict(self)
+        data["failure_class"] = self.failure_class.value
+        return data
+
+
+@dataclass
+class AgentResult:
+    agent: str
+    ok: bool
+    producer: str
+    payload: Dict[str, Any] = field(default_factory=dict)
+    diagnostics: List[str] = field(default_factory=list)
+    failure_class: FailureClass = FailureClass.UNKNOWN
+    raw_output: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = asdict(self)
+        data["failure_class"] = self.failure_class.value
+        return data
+
+
+@dataclass
+class StageResult:
+    stage: str
+    status: StageStatus
+    producer: str
+    failure_class: FailureClass = FailureClass.UNKNOWN
+    consumable_payload: Dict[str, Any] = field(default_factory=dict)
+    diagnostics: List[str] = field(default_factory=list)
+    artifacts_written: List[str] = field(default_factory=list)
+    next_action: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = asdict(self)
+        data["status"] = self.status.value
+        data["failure_class"] = self.failure_class.value
+        return data
+
+
+_JSON_FENCE_RE = re.compile(r"```(?:json)?\s*(\{.*?\})\s*```", re.DOTALL)
+
+
+def extract_json_object(raw_text: str) -> Optional[Dict[str, Any]]:
+    if not raw_text:
+        return None
+    match = _JSON_FENCE_RE.search(raw_text)
+    candidates = [match.group(1)] if match else []
+    stripped = raw_text.strip()
+    if stripped.startswith("{") and stripped.endswith("}"):
+        candidates.append(stripped)
+    first = stripped.find("{")
+    last = stripped.rfind("}")
+    if first != -1 and last != -1 and last > first:
+        candidates.append(stripped[first:last + 1])
+    for candidate in candidates:
+        try:
+            parsed = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    return None
+
+
+def validate_agent_payload(payload: Dict[str, Any], required_keys: List[str]) -> List[str]:
+    errors: List[str] = []
+    if not isinstance(payload, dict):
+        return ["Payload is not a JSON object."]
+    for key in required_keys:
+        if key not in payload:
+            errors.append(f"Missing required key '{key}'.")
+    return errors
+
+
+def infer_failure_class(
+    *,
+    producer: str,
+    raw_output: str = "",
+    diagnostics: Optional[List[str]] = None,
+    tool_result: Optional[Dict[str, Any]] = None,
+) -> FailureClass:
+    diag_text = "\n".join(diagnostics or [])
+    text = f"{raw_output}\n{diag_text}".lower()
+    if tool_result:
+        if tool_result.get("infra_failure"):
+            return FailureClass.INFRASTRUCTURE_ERROR
+        if tool_result.get("tool"):
+            return FailureClass.EDA_TOOL_ERROR
+    if "not valid json" in text or "missing required key" in text or "prose" in text:
+        return FailureClass.LLM_FORMAT_ERROR
+    if "timed out" in text or "tool missing" in text or "binary not found" in text:
+        return FailureClass.INFRASTRUCTURE_ERROR
+    if "cannot find" in text or "%error" in text or "warning" in text or "yosys" in text or "verilator" in text:
+        return FailureClass.EDA_TOOL_ERROR
+    if "handoff" in text or "missing artifact" in text or "routing" in text:
+        return FailureClass.ORCHESTRATOR_ROUTING_ERROR
+    if "retry" in text and "budget" in text:
+        return FailureClass.RETRY_BUDGET_ERROR
+    if producer.startswith("llm") or producer.startswith("agent"):
+        return FailureClass.LLM_SEMANTIC_ERROR
+    return FailureClass.UNKNOWN
+
+
+def materially_changed(before: str, after: str) -> bool:
+    if before == after:
+        return False
+    if not before or not after:
+        return True
+    before_norm = "\n".join(line.rstrip() for line in before.splitlines()).strip()
+    after_norm = "\n".join(line.rstrip() for line in after.splitlines()).strip()
+    return before_norm != after_norm

web/src/App.tsx

@@ -98,7 +98,7 @@ const App = () => {
           >
             {theme === 'light' ? '🌙 Dark' : '☀️ Light'}
           </button>
-          <div className="app-version">v4.0 · Multi-Agent · 2026</div>
+          <div className="app-version">AgentIC · 2026</div>
         </div>
       </aside>
 
@@ -116,8 +116,8 @@ const App = () => {
                 <h2 className="home-hero-title">Autonomous Chip Design Studio</h2>
                 <p className="home-hero-desc">
                   From natural language to fabrication-ready GDSII — powered by multi-agent
-                  collaboration, structured spec decomposition, self-healing loops, and
-                  15-stage autonomous pipeline.
+                  collaboration, intelligent specification analysis, self-healing loops, and
+                  a fully autonomous pipeline.
                 </p>
               </div>
 
@@ -125,7 +125,7 @@ const App = () => {
                 <div className="home-kpi">{designs.length}<span>Designs</span></div>
                 <div className="home-kpi">15<span>Pipeline Stages</span></div>
                 <div className="home-kpi">5<span>Core Modules</span></div>
-                <div className="home-kpi">12<span>AI Agents</span></div>
+                <div className="home-kpi">AI<span>Agents</span></div>
               </div>
 
               <div className="home-section">
@@ -133,33 +133,33 @@ const App = () => {
                 <div className="home-agent-grid">
                   <div className="agent-card">
                     <div className="agent-icon">🏗️</div>
-                    <div className="agent-name">ArchitectModule</div>
-                    <div className="agent-desc">Spec → Structured JSON (SID) contract</div>
+                    <div className="agent-name">Architect</div>
+                    <div className="agent-desc">Specification analysis and structured design decomposition</div>
                   </div>
                   <div className="agent-card">
                     <div className="agent-icon">💻</div>
                     <div className="agent-name">RTL Designer + Reviewer</div>
-                    <div className="agent-desc">Collaborative 2-agent Crew with tools</div>
+                    <div className="agent-desc">Multi-agent collaborative generation</div>
                   </div>
                   <div className="agent-card">
                     <div className="agent-icon">🧪</div>
                     <div className="agent-name">TB Designer</div>
-                    <div className="agent-desc">Verilator-safe flat procedural TBs</div>
+                    <div className="agent-desc">Automated testbench generation and validation</div>
                   </div>
                   <div className="agent-card">
                     <div className="agent-icon">🔍</div>
                     <div className="agent-name">Error Analyst</div>
-                    <div className="agent-desc">Multi-class failure diagnosis (A–E)</div>
+                    <div className="agent-desc">Intelligent failure classification</div>
                   </div>
                   <div className="agent-card">
                     <div className="agent-icon">🔄</div>
-                    <div className="agent-name">SelfReflectPipeline</div>
-                    <div className="agent-desc">Convergence-aware hardening retry</div>
+                    <div className="agent-name">Self-Healing Engine</div>
+                    <div className="agent-desc">Convergence-aware optimization and recovery</div>
                   </div>
                   <div className="agent-card">
                     <div className="agent-icon">🧠</div>
-                    <div className="agent-name">DeepDebugger</div>
-                    <div className="agent-desc">FVDebug causal graphs + for-and-against</div>
+                    <div className="agent-name">Deep Debugger</div>
+                    <div className="agent-desc">Causal failure analysis</div>
                   </div>
                 </div>
               </div>
@@ -168,15 +168,15 @@ const App = () => {
                 <h3 className="home-section-title">Pipeline Flow</h3>
                 <div className="pipeline-flow">
                   {[
-                    { icon: '📐', label: 'SPEC', sub: 'SID Decompose' },
-                    { icon: '💻', label: 'RTL_GEN', sub: '2-Agent Crew' },
-                    { icon: '🔨', label: 'RTL_FIX', sub: 'Lint + Rigor' },
-                    { icon: '🧪', label: 'VERIFY', sub: 'Sim + TB Gate' },
-                    { icon: '📊', label: 'FORMAL', sub: 'SVA + SBY' },
-                    { icon: '📈', label: 'COVERAGE', sub: 'Anti-regress' },
+                    { icon: '📐', label: 'SPEC', sub: 'Spec Analysis' },
+                    { icon: '💻', label: 'RTL_GEN', sub: 'RTL Generation' },
+                    { icon: '🔨', label: 'RTL_FIX', sub: 'Code Quality' },
+                    { icon: '🧪', label: 'VERIFY', sub: 'Functional Verify' },
+                    { icon: '📊', label: 'FORMAL', sub: 'Formal Verify' },
+                    { icon: '📈', label: 'COVERAGE', sub: 'Coverage' },
                     { icon: '🗺️', label: 'FLOOR', sub: 'Floorplan' },
-                    { icon: '🏗️', label: 'HARDEN', sub: 'Self-Reflect' },
-                    { icon: '✅', label: 'SIGNOFF', sub: 'DRC/LVS/STA' },
+                    { icon: '🏗️', label: 'HARDEN', sub: 'Optimization' },
+                    { icon: '✅', label: 'SIGNOFF', sub: 'Signoff' },
                   ].map((s, i) => (
                     <div className="pipeline-stage" key={s.label}>
                       <div className="pipeline-stage-icon">{s.icon}</div>
@@ -197,7 +197,7 @@ const App = () => {
                   </div>
                   <div className="quickstart-step">
                     <div className="quickstart-num">2</div>
-                    <div>Watch 12 AI agents build it through 15 stages</div>
+                    <div>Watch AI agents autonomously build and verify your chip</div>
                   </div>
                   <div className="quickstart-step">
                     <div className="quickstart-num">3</div>

web/src/pages/Benchmarking.tsx

@@ -28,22 +28,22 @@ export const Benchmarking: React.FC<BenchmarkingProps> = ({ selectedDesign }) =>
                         </tr>
                         <tr>
                             <td>Spec Decomposition</td>
-                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>ArchitectModule SID (automated)</td>
+                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>Automated specification analysis</td>
                             <td>Manual architecture review (weeks)</td>
                         </tr>
                         <tr>
                             <td>Verification Methodology</td>
-                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>Multi-agent diagnosis (5-class)</td>
+                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>Intelligent multi-class diagnosis</td>
                             <td>Manual waveform debugging</td>
                         </tr>
                         <tr>
                             <td>Agent Collaboration</td>
-                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>12 agents with tools + Crews</td>
+                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>Multi-agent collaborative pipeline</td>
                             <td>Siloed engineer teams</td>
                         </tr>
                         <tr>
                             <td>Self-Healing</td>
-                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>SelfReflectPipeline + convergence</td>
+                            <td style={{ color: 'var(--success)', fontWeight: 600 }}>Convergence-aware automated recovery</td>
                             <td>Manual iteration</td>
                         </tr>
                         <tr>
@@ -71,35 +71,29 @@ export const Benchmarking: React.FC<BenchmarkingProps> = ({ selectedDesign }) =>
                     <thead>
                         <tr>
                             <th>Module</th>
-                            <th>Based On</th>
-                            <th>Stage</th>
+                            <th>Capability</th>
                         </tr>
                     </thead>
                     <tbody>
                         <tr>
-                            <td style={{ fontWeight: 600 }}>ArchitectModule</td>
-                            <td>Spec2RTL-Agent</td>
-                            <td>SPEC → SID JSON decomposition</td>
+                            <td style={{ fontWeight: 600 }}>Architect</td>
+                            <td>Natural language specification decomposition and structured contract generation</td>
                         </tr>
                         <tr>
-                            <td style={{ fontWeight: 600 }}>ReActAgent</td>
-                            <td>Yao et al., 2023</td>
-                            <td>Thought→Action→Observation loops</td>
+                            <td style={{ fontWeight: 600 }}>Reasoning Agent</td>
+                            <td>Iterative reasoning with observation-driven action planning</td>
                         </tr>
                         <tr>
-                            <td style={{ fontWeight: 600 }}>SelfReflectPipeline</td>
-                            <td>Self-Reflection Retry</td>
-                            <td>HARDENING with convergence tracking</td>
+                            <td style={{ fontWeight: 600 }}>Self-Healing Pipeline</td>
+                            <td>Convergence-aware retry with metric-driven optimization</td>
                         </tr>
                         <tr>
-                            <td style={{ fontWeight: 600 }}>DeepDebuggerModule</td>
-                            <td>FVDebug</td>
-                            <td>Formal — causal graphs + For-and-Against</td>
+                            <td style={{ fontWeight: 600 }}>Deep Debugger</td>
+                            <td>Causal failure analysis with multi-perspective reasoning</td>
                         </tr>
                         <tr>
-                            <td style={{ fontWeight: 600 }}>WaveformExpertModule</td>
-                            <td>VerilogCoder</td>
-                            <td>VCD + AST back-trace diagnosis</td>
+                            <td style={{ fontWeight: 600 }}>Waveform Analyst</td>
+                            <td>Signal-level diagnostic analysis and root cause identification</td>
                         </tr>
                     </tbody>
                 </table>

web/src/pages/Documentation.tsx

@@ -202,12 +202,12 @@ export const Documentation = () => {
               <h2>Key Capabilities</h2>
               <div className="adoc-cap-grid">
                 {[
-                  { icon: '🧠', title: 'AI‑Driven RTL Generation', desc: 'SystemVerilog or Verilog‑2005 from natural language via CrewAI agent chains.' },
+                  { icon: '🧠', title: 'AI‑Driven RTL Generation', desc: 'SystemVerilog or Verilog‑2005 from natural language via multi-agent collaboration.' },
                   { icon: '🔁', title: 'Self‑Healing Pipeline', desc: 'Per‑stage guards, fingerprint dedup, bounded retries, and deterministic fallbacks.' },
-                  { icon: '📊', title: 'Formal Verification', desc: 'SVA generation, Yosys SBY integration, CDC heuristic checks.' },
+                  { icon: '📊', title: 'Formal Verification', desc: 'Assertion generation, formal property checking, and clock-domain analysis.' },
                   { icon: '📈', title: 'Coverage Closure', desc: 'Profile‑based (balanced / aggressive / relaxed) with anti‑regression backup.' },
-                  { icon: '🏗️', title: 'Physical Implementation', desc: 'OpenLane integration with convergence review and ECO patch loops.' },
-                  { icon: '✅', title: 'Silicon Signoff', desc: 'DRC/LVS, STA, power/IR‑drop, LEC checks before tapeout.' },
+                  { icon: '🏗️', title: 'Physical Implementation', desc: 'RTL-to-GDSII flow integration with convergence review and optimization loops.' },
+                  { icon: '✅', title: 'Silicon Signoff', desc: 'DRC/LVS, STA, power/IR‑drop, equivalence checks before tapeout.' },
                 ].map((cap) => (
                   <div className="adoc-cap-item" key={cap.title}>
                     <span className="adoc-cap-icon">{cap.icon}</span>
@@ -229,18 +229,18 @@ export const Documentation = () => {
                     <tr>
                       <th>Gate</th>
                       <th>Check</th>
-                      <th>Self‑Healing Response</th>
+                      <th>Recovery</th>
                       <th>Fallback</th>
                     </tr>
                   </thead>
                   <tbody>
                     {[
-                      ['Syntax', 'Verilator --lint-only', 'LLM auto-repair loop (bounded)', 'SV→Verilog strategy pivot'],
-                      ['TB Compile', 'Icarus iverilog compile', '3-cycle recovery (repair → regen → fallback)', 'Deterministic template TB'],
-                      ['Simulation', 'Runtime: TEST PASSED', 'Re-generate testbench with error analysis', 'Fingerprint dedup + skip'],
-                      ['Formal', 'SVA via Yosys SBY', 'Bounded SVA regeneration', 'Graceful degrade to coverage'],
-                      ['Coverage', 'Profile-based thresholds', 'LLM TB improvement + anti-regression', 'Restore best TB snapshot'],
-                      ['DRC/LVS', 'OpenLane signoff reports', 'ECO patch (gate → RTL fallback)', 'Fail-closed or pivot'],
+                      ['Syntax', 'Static Analysis', 'Automated Recovery', 'Strategy pivot'],
+                      ['TB Compile', 'Compilation Check', 'Automated Recovery', 'Deterministic template TB'],
+                      ['Simulation', 'Simulation Check', 'Automated Recovery', 'Dedup + skip'],
+                      ['Formal', 'Formal Property Verification', 'Automated Recovery', 'Graceful degrade to coverage'],
+                      ['Coverage', 'Profile-based thresholds', 'Automated Recovery', 'Restore best snapshot'],
+                      ['DRC/LVS', 'Physical signoff reports', 'Automated Recovery', 'Fail-closed or pivot'],
                     ].map(([gate, check, heal, fallback]) => (
                       <tr key={gate}>
                         <td><strong>{gate}</strong></td>
@@ -440,20 +440,20 @@ export const Documentation = () => {
 
 /* ── Stage descriptions ──────────────────────────── */
 const stageDescriptions: Record<string, string> = {
-  INIT: 'Create workspace directory structure, validate dependencies (Verilator, Icarus Verilog, OpenLane), and initialize build artifacts dictionary.',
-  SPEC: 'LLM generates a detailed architecture specification from the natural-language prompt, including module interfaces, FSM descriptions, and clock/reset requirements.',
-  RTL_GEN: 'Generate synthesizable RTL (SystemVerilog or Verilog-2005) from the architecture spec using a CrewAI RTL agent. Falls back to golden template library when available.',
-  RTL_FIX: 'Run Verilator lint, pre-synthesis semantic checks, and iterative LLM-based auto-repair. Supports strategy pivot (SV → Verilog-2005) when fixes stall.',
-  VERIFICATION: 'Generate self-checking testbenches, compile with Icarus Verilog, run simulation, and check for TEST PASSED. Includes TB static contract checking and fingerprint deduplication.',
-  FORMAL_VERIFY: 'Generate SVA properties, convert to Yosys SBY format, run formal property checking. Includes CDC heuristic analysis.',
-  COVERAGE_CHECK: 'Run coverage analysis with Verilator or Icarus backend. Compare against profile-based thresholds (line, branch, toggle, functional). Anti-regression guard restores best TB on coverage drop.',
+  INIT: 'Create workspace directory structure, validate dependencies, and initialize build artifacts dictionary.',
+  SPEC: 'Generate a detailed architecture specification from the natural-language prompt, including module interfaces, FSM descriptions, and clock/reset requirements.',
+  RTL_GEN: 'Generate synthesizable RTL (SystemVerilog or Verilog-2005) from the architecture spec using multi-agent collaboration. Falls back to template library when available.',
+  RTL_FIX: 'Run static analysis, pre-synthesis semantic checks, and iterative auto-repair. Supports strategy pivot (SV → Verilog-2005) when fixes stall.',
+  VERIFICATION: 'Generate self-checking testbenches, compile, run simulation, and check for passing results. Includes static contract checking and fingerprint deduplication.',
+  FORMAL_VERIFY: 'Generate formal assertions, run formal property checking. Includes clock-domain analysis.',
+  COVERAGE_CHECK: 'Run coverage analysis against profile-based thresholds (line, branch, toggle, functional). Anti-regression guard restores best testbench on coverage drop.',
   REGRESSION: 'Generate and run multiple directed test scenarios (corner cases, reset stress, rapid fire) to verify robustness beyond basic functional verification.',
-  SDC_GEN: 'Generate SDC timing constraints from the RTL module interface. Auto-detects clock ports and applies post-processing to fix multi-port get_ports syntax.',
-  FLOORPLAN: 'LLM-driven floorplan estimation based on gate count, wire routing complexity, and PDK parameters. Produces die area and utilization targets.',
-  HARDENING: 'Generate OpenLane config.tcl and run the full RTL-to-GDSII flow inside Docker. Collects metrics.csv for convergence analysis.',
+  SDC_GEN: 'Generate SDC timing constraints from the RTL module interface. Auto-detects clock ports and applies constraint post-processing.',
+  FLOORPLAN: 'Floorplan estimation based on gate count, wire routing complexity, and PDK parameters. Produces die area and utilization targets.',
+  HARDENING: 'Generate physical design configuration and run the full RTL-to-GDSII flow. Collects metrics for convergence analysis.',
   CONVERGENCE_REVIEW: 'Analyze PPA metrics (WNS, TNS, area, power, congestion) across iteration history. Determines whether to accept, resize die, or pivot strategy.',
   ECO_PATCH: 'Apply engineering change orders — gate-level patch first, RTL micro-patch fallback. Re-enters hardening loop after successful application.',
-  SIGNOFF: 'Multi-dimensional check: DRC/LVS compliance, STA timing closure, power/IR-drop analysis, logic equivalence checking, and coverage re-validation.',
+  SIGNOFF: 'Multi-dimensional check: DRC/LVS compliance, STA timing closure, power/IR-drop analysis, equivalence checking, and coverage re-validation.',
   SUCCESS: 'Build completed — all quality gates passed. GDSII, metrics, and documentation artifacts are finalized.',
   FAIL: 'Build terminated — one or more quality gates failed after exhausting retry budgets.',
 };