codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/prd_stress_test.py

@@ -0,0 +1,499 @@
+"""PRD stress test via recursive decomposition.
+
+Recursively decomposes PRD goals using a tri-state classification
+(atomic / composite / ambiguous) to surface requirements gaps and
+generate a technical specification. This is a human-facing discovery
+tool — not a task generator.
+
+This module is headless — no FastAPI or HTTP dependencies.
+"""
+
+import asyncio
+import json
+import logging
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from typing import AsyncGenerator, Literal, Optional
+
+from codeframe.adapters.llm.base import Purpose
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data Models
+# ---------------------------------------------------------------------------
+
+
+class Classification(str, Enum):
+    ATOMIC = "atomic"
+    COMPOSITE = "composite"
+    AMBIGUOUS = "ambiguous"
+
+
+@dataclass
+class DecompositionNode:
+    id: str
+    title: str
+    description: str
+    classification: Classification
+    children: list["DecompositionNode"]
+    lineage: list[str]
+    depth: int
+    complexity_hint: Optional[str] = None
+    ambiguity_id: Optional[str] = None
+
+
+@dataclass
+class Ambiguity:
+    id: str
+    label: str
+    source_node_title: str
+    questions: list[str]
+    recommendation: str
+    # "blocking" ambiguities must be answered before a PRD can be refined;
+    # "warning" ambiguities are advisory and skippable (issue #562).
+    severity: Literal["blocking", "warning"] = "blocking"
+    resolved_answer: Optional[str] = None
+
+
+@dataclass
+class StressTestResult:
+    prd_title: str
+    tree: list[DecompositionNode]
+    ambiguities: list[Ambiguity]
+    tech_spec_markdown: str
+    ambiguity_report: str
+
+
+# ---------------------------------------------------------------------------
+# Prompt Constants
+# ---------------------------------------------------------------------------
+
+
+GOAL_EXTRACTION_SYSTEM = (
+    "You are a requirements analyst. Given a Product Requirements Document, "
+    "extract the high-level deliverable goals — the major features or systems "
+    "that need to be built. Return ONLY a JSON array of short goal strings. "
+    "Example: [\"User Authentication\", \"Invoice Management\", \"PDF Export\"]"
+)
+
+CLASSIFY_AND_DECOMPOSE_SYSTEM = """\
+You are a recursive requirements decomposer. Given a goal, its context (lineage \
+of ancestor goals), and the original PRD, classify the goal into exactly one of:
+
+- "atomic": Small enough to implement directly (1-2 days of work). The PRD \
+provides enough detail.
+- "composite": Clearly needs breakdown into sub-goals. The PRD provides \
+enough detail to know what the pieces are.
+- "ambiguous": You CANNOT confidently classify because the PRD is missing \
+critical information. You must explain what's missing.
+
+Return a JSON object with these fields:
+{
+  "classification": "atomic" | "composite" | "ambiguous",
+  "children": [{"title": "...", "description": "..."}],  // only if composite
+  "ambiguity_label": "SHORT LABEL",                       // only if ambiguous
+  "questions": ["question 1", "question 2"],              // only if ambiguous
+  "recommendation": "what to add to the PRD",             // only if ambiguous
+  "severity": "blocking" | "warning",                     // only if ambiguous
+  "complexity_hint": "Low" | "Low-Medium" | "Medium" | "High"  // always
+}
+
+For "severity": use "blocking" when the missing information prevents \
+implementation and must be answered; use "warning" for advisory gaps that \
+have a reasonable default and can be skipped.
+
+Return ONLY valid JSON. No markdown wrapping."""
+
+AMBIGUITY_RESOLUTION_SYSTEM = (
+    "You are a PRD editor. Given the original PRD content and a set of resolved "
+    "ambiguities (question + answer pairs), update the PRD to incorporate the "
+    "new information. Preserve the original structure and tone. Return the "
+    "complete updated PRD content."
+)
+
+
+# ---------------------------------------------------------------------------
+# Core Functions
+# ---------------------------------------------------------------------------
+
+
+def extract_goals(prd_content: str, provider) -> list[str]:
+    """Extract high-level deliverable goals from a PRD."""
+    response = provider.complete(
+        messages=[{"role": "user", "content": prd_content}],
+        purpose=Purpose.PLANNING,
+        system=GOAL_EXTRACTION_SYSTEM,
+        max_tokens=1024,
+        temperature=0.0,
+    )
+    try:
+        goals = json.loads(response.content)
+        if isinstance(goals, list):
+            return [str(g) for g in goals]
+        logger.warning("Goal extraction returned non-list: %s", type(goals).__name__)
+    except (json.JSONDecodeError, TypeError) as exc:
+        logger.warning("Failed to parse goal extraction response: %s", exc)
+    return []
+
+
+def classify_and_decompose(
+    title: str,
+    description: str,
+    lineage: list[str],
+    prd_content: str,
+    depth: int,
+    provider,
+) -> tuple[Classification, list[dict], Optional[Ambiguity], str]:
+    """Classify a goal node and optionally decompose or flag ambiguity."""
+    lineage_ctx = ""
+    if lineage:
+        lineage_ctx = "\n\nAncestor context:\n" + "\n".join(
+            f"- {desc}" for desc in lineage
+        )
+
+    user_msg = (
+        f"Goal: {title}\n"
+        f"Description: {description}\n"
+        f"Depth: {depth}{lineage_ctx}\n\n"
+        f"PRD:\n{prd_content}"
+    )
+
+    response = provider.complete(
+        messages=[{"role": "user", "content": user_msg}],
+        purpose=Purpose.PLANNING,
+        system=CLASSIFY_AND_DECOMPOSE_SYSTEM,
+        max_tokens=2048,
+        temperature=0.0,
+    )
+
+    try:
+        data = json.loads(response.content)
+    except (json.JSONDecodeError, TypeError) as exc:
+        logger.warning("Failed to parse classification for '%s': %s", title, exc)
+        return Classification.ATOMIC, [], None, "Low"
+
+    raw_cls = data.get("classification", "atomic").lower()
+    try:
+        cls = Classification(raw_cls)
+    except ValueError:
+        cls = Classification.ATOMIC
+
+    complexity = data.get("complexity_hint", "Low")
+    raw_children = data.get("children", []) if cls == Classification.COMPOSITE else []
+    # Validate children are dicts with expected keys
+    children = [
+        c for c in raw_children
+        if isinstance(c, dict) and ("title" in c or "description" in c)
+    ]
+
+    ambiguity = None
+    if cls == Classification.AMBIGUOUS:
+        raw_severity = str(data.get("severity", "blocking")).lower()
+        severity = raw_severity if raw_severity in ("blocking", "warning") else "blocking"
+        ambiguity = Ambiguity(
+            id=str(uuid.uuid4()),
+            label=data.get("ambiguity_label", "UNSPECIFIED"),
+            source_node_title=title,
+            questions=data.get("questions", []),
+            recommendation=data.get("recommendation", ""),
+            severity=severity,
+        )
+
+    return cls, children, ambiguity, complexity
+
+
+def recursive_decompose(
+    title: str,
+    description: str,
+    lineage: list[str],
+    prd_content: str,
+    depth: int,
+    max_depth: int,
+    ambiguities: list[Ambiguity],
+    provider,
+) -> DecompositionNode:
+    """Recursively decompose a goal, collecting ambiguities along the way."""
+    # Force leaf at max depth
+    if depth >= max_depth:
+        return DecompositionNode(
+            id=str(uuid.uuid4()),
+            title=title,
+            description=description,
+            classification=Classification.ATOMIC,
+            children=[],
+            lineage=lineage,
+            depth=depth,
+            complexity_hint="Unknown",
+        )
+
+    cls, child_dicts, ambiguity, complexity = classify_and_decompose(
+        title, description, lineage, prd_content, depth, provider,
+    )
+
+    if ambiguity:
+        ambiguities.append(ambiguity)
+
+    children = []
+    if cls == Classification.COMPOSITE:
+        child_lineage = lineage + [title]
+        for child_dict in child_dicts:
+            child_node = recursive_decompose(
+                child_dict.get("title", "Untitled"),
+                child_dict.get("description", ""),
+                child_lineage,
+                prd_content,
+                depth + 1,
+                max_depth,
+                ambiguities,
+                provider,
+            )
+            children.append(child_node)
+
+    return DecompositionNode(
+        id=str(uuid.uuid4()),
+        title=title,
+        description=description,
+        classification=cls,
+        children=children,
+        lineage=lineage,
+        depth=depth,
+        complexity_hint=complexity,
+        ambiguity_id=ambiguity.id if ambiguity else None,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Renderers
+# ---------------------------------------------------------------------------
+
+
+def render_tech_spec(
+    tree: list[DecompositionNode], ambiguities: list[Ambiguity]
+) -> str:
+    """Render the decomposition tree as a markdown technical specification."""
+    amb_map = {a.id: i + 1 for i, a in enumerate(ambiguities)}
+    lines = ["# Technical Specification\n"]
+
+    for node in tree:
+        _render_spec_node(node, lines, amb_map, header_level=2)
+
+    return "\n".join(lines)
+
+
+def _render_spec_node(
+    node: DecompositionNode,
+    lines: list[str],
+    amb_map: dict[str, int],
+    header_level: int,
+) -> None:
+    """Recursively render a node into the tech spec."""
+    prefix = "#" * min(header_level, 6)
+    lines.append(f"{prefix} {node.title}")
+
+    if node.classification == Classification.AMBIGUOUS:
+        amb_num = amb_map.get(node.ambiguity_id, "?") if node.ambiguity_id else "?"
+        lines.append(f"**[NEEDS CLARIFICATION — see ambiguity #{amb_num}]**\n")
+    elif node.classification == Classification.ATOMIC:
+        lines.append(f"- {node.description}")
+        if node.complexity_hint:
+            lines.append(f"- Estimated complexity: {node.complexity_hint}")
+        lines.append("")
+    else:
+        lines.append("")
+
+    for child in node.children:
+        _render_spec_node(child, lines, amb_map, header_level + 1)
+
+
+def render_ambiguity_report(ambiguities: list[Ambiguity]) -> str:
+    """Render the ambiguity list as a human-readable report."""
+    if not ambiguities:
+        return "No ambiguities found — PRD is well-specified for decomposition."
+
+    lines = [
+        f"PRD Stress Test — {len(ambiguities)} ambiguities found:\n",
+    ]
+
+    for i, amb in enumerate(ambiguities, 1):
+        lines.append(
+            f"{i}. {amb.label} (from decomposing \"{amb.source_node_title}\")"
+        )
+        lines.append("   The PRD doesn't specify:")
+        for q in amb.questions:
+            lines.append(f"   - {q}")
+        lines.append(f"   → Recommendation: {amb.recommendation}")
+        if amb.resolved_answer:
+            lines.append(f"   ✓ Resolved: {amb.resolved_answer}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def ambiguity_to_dict(amb: Ambiguity) -> dict[str, object]:
+    """Serialize an :class:`Ambiguity` for SSE / JSON transport (issue #562).
+
+    Carries the structured fields the web results view needs to render an
+    answerable card: question text, severity, and the recommendation.
+    """
+    return {
+        "id": amb.id,
+        "label": amb.label,
+        "source_node_title": amb.source_node_title,
+        "questions": list(amb.questions),
+        "recommendation": amb.recommendation,
+        "severity": amb.severity,
+        "resolved_answer": amb.resolved_answer,
+    }
+
+
+def resolve_ambiguities_into_prd(
+    prd_content: str,
+    ambiguities: list[Ambiguity],
+    provider,
+) -> str:
+    """Use LLM to update PRD content with resolved ambiguity answers."""
+    resolved = [a for a in ambiguities if a.resolved_answer]
+    if not resolved:
+        return prd_content
+
+    resolution_text = "\n".join(
+        f"- {a.label}: {', '.join(a.questions)} → Answer: {a.resolved_answer}"
+        for a in resolved
+    )
+
+    response = provider.complete(
+        messages=[{
+            "role": "user",
+            "content": (
+                f"Original PRD:\n{prd_content}\n\n"
+                f"Resolved ambiguities:\n{resolution_text}\n\n"
+                "Update the PRD to incorporate these answers."
+            ),
+        }],
+        purpose=Purpose.PLANNING,
+        system=AMBIGUITY_RESOLUTION_SYSTEM,
+        max_tokens=8192,
+        temperature=0.0,
+    )
+    updated = response.content.strip()
+    if not updated or len(updated) < len(prd_content) // 2:
+        logger.warning(
+            "PRD rewrite looks truncated (%d chars vs original %d), returning original",
+            len(updated), len(prd_content),
+        )
+        return prd_content
+    return updated
+
+
+# ---------------------------------------------------------------------------
+# Top-level Orchestrator
+# ---------------------------------------------------------------------------
+
+
+def stress_test_prd(
+    prd_content: str, provider, max_depth: int = 3
+) -> StressTestResult:
+    """Run the full PRD stress test: extract goals → recursive decompose → render."""
+    goals = extract_goals(prd_content, provider)
+
+    tree: list[DecompositionNode] = []
+    ambiguities: list[Ambiguity] = []
+
+    for goal in goals:
+        node = recursive_decompose(
+            title=goal,
+            description=goal,
+            lineage=[],
+            prd_content=prd_content,
+            depth=0,
+            max_depth=max_depth,
+            ambiguities=ambiguities,
+            provider=provider,
+        )
+        tree.append(node)
+
+    tech_spec = render_tech_spec(tree, ambiguities)
+    amb_report = render_ambiguity_report(ambiguities)
+
+    # Extract title from PRD (first heading or first line)
+    prd_title = "Untitled"
+    for line in prd_content.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("# "):
+            prd_title = stripped[2:].strip()
+            break
+        if stripped:
+            prd_title = stripped[:80]
+            break
+
+    return StressTestResult(
+        prd_title=prd_title,
+        tree=tree,
+        ambiguities=ambiguities,
+        tech_spec_markdown=tech_spec,
+        ambiguity_report=amb_report,
+    )
+
+
+async def stress_test_prd_stream(
+    prd_content: str, provider, max_depth: int = 3
+) -> AsyncGenerator[dict, None]:
+    """Async streaming variant of :func:`stress_test_prd`.
+
+    Yields progress event dicts suitable for SSE delivery as each top-level
+    goal is decomposed, so a UI can render incremental output:
+
+    - ``{"type": "goals_extracted", "goals": [...]}``
+    - ``{"type": "goal_analyzed", "goal": str, "classification": str,
+         "ambiguities_so_far": int}`` (once per top-level goal)
+    - ``{"type": "complete", "ambiguity_count": int,
+         "ambiguities": [ambiguity_to_dict(...)],
+         "tech_spec_markdown": str, "ambiguity_report": str}``
+    - ``{"type": "error", "message": str}`` if decomposition raises
+
+    The underlying ``provider.complete()`` calls are synchronous and blocking,
+    so each is offloaded via :func:`asyncio.to_thread` to keep the event loop
+    responsive. This function stays headless (no FastAPI/HTTP imports).
+    """
+    try:
+        goals = await asyncio.to_thread(extract_goals, prd_content, provider)
+        yield {"type": "goals_extracted", "goals": goals}
+
+        ambiguities: list[Ambiguity] = []
+        tree: list[DecompositionNode] = []
+
+        for goal in goals:
+            node = await asyncio.to_thread(
+                recursive_decompose,
+                goal,            # title
+                goal,            # description
+                [],              # lineage
+                prd_content,
+                0,               # depth
+                max_depth,
+                ambiguities,
+                provider,
+            )
+            tree.append(node)
+            yield {
+                "type": "goal_analyzed",
+                "goal": node.title,
+                "classification": node.classification.value,
+                "ambiguities_so_far": len(ambiguities),
+            }
+
+        tech_spec = render_tech_spec(tree, ambiguities)
+        amb_report = render_ambiguity_report(ambiguities)
+        yield {
+            "type": "complete",
+            "ambiguity_count": len(ambiguities),
+            "ambiguities": [ambiguity_to_dict(a) for a in ambiguities],
+            "tech_spec_markdown": tech_spec,
+            "ambiguity_report": amb_report,
+        }
+    except Exception as exc:  # noqa: BLE001 — surface any failure to the client
+        logger.warning("Stress test stream failed: %s", exc, exc_info=True)
+        yield {"type": "error", "message": str(exc)}

codeframe/core/progress.py

@@ -0,0 +1,126 @@
+"""Progress tracking for batch execution.
+
+Provides ETA estimation based on completed task durations.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+
+@dataclass
+class BatchProgress:
+    """Tracks batch execution progress for ETA calculation."""
+
+    total_tasks: int
+    completed_tasks: int = 0
+    failed_tasks: int = 0
+    blocked_tasks: int = 0
+    started_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    task_durations: list[float] = field(default_factory=list)
+    task_start_times: dict[str, datetime] = field(default_factory=dict)
+
+    @property
+    def processed_tasks(self) -> int:
+        """Tasks that are no longer pending."""
+        return self.completed_tasks + self.failed_tasks + self.blocked_tasks
+
+    @property
+    def remaining_tasks(self) -> int:
+        """Tasks still to be processed."""
+        return max(0, self.total_tasks - self.processed_tasks)
+
+    @property
+    def running_tasks(self) -> int:
+        """Tasks currently in progress."""
+        return len(self.task_start_times)
+
+    @property
+    def average_task_duration(self) -> Optional[float]:
+        """Average seconds per completed task."""
+        if not self.task_durations:
+            return None
+        return sum(self.task_durations) / len(self.task_durations)
+
+    @property
+    def eta_seconds(self) -> Optional[float]:
+        """Estimated seconds to completion."""
+        avg = self.average_task_duration
+        if avg is None or self.remaining_tasks == 0:
+            return None
+        return avg * self.remaining_tasks
+
+    def format_eta(self) -> str:
+        """Human-readable ETA string."""
+        eta = self.eta_seconds
+        if eta is None:
+            if self.remaining_tasks == 0:
+                return "complete"
+            return "calculating..."
+        hours, remainder = divmod(int(eta), 3600)
+        minutes, seconds = divmod(remainder, 60)
+        if hours > 0:
+            return f"{hours}h {minutes}m"
+        if minutes > 0:
+            return f"{minutes}m {seconds}s"
+        return f"{seconds}s"
+
+    @property
+    def progress_percent(self) -> float:
+        """Completion percentage (0-100)."""
+        if self.total_tasks == 0:
+            return 100.0
+        return (self.processed_tasks / self.total_tasks) * 100
+
+    @property
+    def elapsed_seconds(self) -> float:
+        """Seconds since batch started."""
+        return (datetime.now(timezone.utc) - self.started_at).total_seconds()
+
+    def format_elapsed(self) -> str:
+        """Human-readable elapsed time."""
+        elapsed = int(self.elapsed_seconds)
+        hours, remainder = divmod(elapsed, 3600)
+        minutes, seconds = divmod(remainder, 60)
+        if hours > 0:
+            return f"{hours}h {minutes}m {seconds}s"
+        if minutes > 0:
+            return f"{minutes}m {seconds}s"
+        return f"{seconds}s"
+
+    def record_task_start(self, task_id: str) -> None:
+        """Record when a task starts for duration tracking."""
+        self.task_start_times[task_id] = datetime.now(timezone.utc)
+
+    def record_task_complete(self, task_id: str) -> None:
+        """Record task completion and calculate duration."""
+        self.completed_tasks += 1
+        start_time = self.task_start_times.pop(task_id, None)
+        if start_time:
+            duration = (datetime.now(timezone.utc) - start_time).total_seconds()
+            self.task_durations.append(duration)
+
+    def record_task_failed(self, task_id: str) -> None:
+        """Record task failure."""
+        self.failed_tasks += 1
+        self.task_start_times.pop(task_id, None)
+
+    def record_task_blocked(self, task_id: str) -> None:
+        """Record task blocked."""
+        self.blocked_tasks += 1
+        self.task_start_times.pop(task_id, None)
+
+    def status_summary(self) -> str:
+        """One-line status summary."""
+        parts = []
+        if self.completed_tasks:
+            parts.append(f"{self.completed_tasks} completed")
+        if self.failed_tasks:
+            parts.append(f"{self.failed_tasks} failed")
+        if self.blocked_tasks:
+            parts.append(f"{self.blocked_tasks} blocked")
+        if self.running_tasks:
+            parts.append(f"{self.running_tasks} running")
+        if self.remaining_tasks - self.running_tasks > 0:
+            parts.append(f"{self.remaining_tasks - self.running_tasks} pending")
+        return " | ".join(parts) if parts else "starting..."

codeframe/core/proof/__init__.py

@@ -0,0 +1,34 @@
+"""PROOF9: Quality memory system with evidence-based verification.
+
+Turns every failure into a permanent proof obligation. Requirements are
+tracked in a ledger, obligations are enforced on every run, and evidence
+artifacts prove compliance.
+
+This package is headless — no FastAPI or HTTP dependencies.
+"""
+
+from codeframe.core.proof.models import (
+    Evidence,
+    EvidenceRule,
+    Gate,
+    GlitchType,
+    Obligation,
+    ReqStatus,
+    Requirement,
+    RequirementScope,
+    Source,
+    Waiver,
+)
+
+__all__ = [
+    "Evidence",
+    "EvidenceRule",
+    "Gate",
+    "GlitchType",
+    "Obligation",
+    "ReqStatus",
+    "Requirement",
+    "RequirementScope",
+    "Source",
+    "Waiver",
+]