devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/sufficiency.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..llm.invoke import LlmInvocationRequest, invoke_llm
+
+
+@dataclass(frozen=True)
+class SufficiencyResult:
+    payload: dict[str, object]
+    passed: bool
+
+
+_DIMENSIONS: tuple[tuple[str, str, re.Pattern[str], bool], ...] = (
+    ("problem", "What concrete problem is being solved?", re.compile(r"\b(problem|pain|challenge|why)\b\s*:", re.IGNORECASE), True),
+    ("users", "Who are the primary users or operators?", re.compile(r"\b(user|users|audience|customer|customers|operator|operators)\b\s*:", re.IGNORECASE), True),
+    ("goal", "What outcome should be true when this idea succeeds?", re.compile(r"\b(goal|outcome|success)\b\s*:", re.IGNORECASE), True),
+    ("scope", "What is explicitly in scope for the first story set?", re.compile(r"\b(scope|features?|include|includes)\b\s*:", re.IGNORECASE), True),
+    (
+        "constraints",
+        "What constraints or non-goals must story generation preserve?",
+        re.compile(r"\b(constraint|constraints|non-goal|non-goals|limit|limits)\b\s*:", re.IGNORECASE),
+        False,
+    ),
+    (
+        "acceptance_criteria",
+        "How will you know the idea is done or good enough?",
+        re.compile(r"\b(acceptance criteria|success criteria|done when)\b\s*:", re.IGNORECASE),
+        False,
+    ),
+)
+
+_FIELD_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("problem", re.compile(r"^\s*(problem|pain|challenge|why)\s*:\s*(.+?)\s*$", re.IGNORECASE)),
+    ("target_users", re.compile(r"^\s*(user|users|audience|customer|customers|operator|operators)\s*:\s*(.+?)\s*$", re.IGNORECASE)),
+    ("user_outcomes", re.compile(r"^\s*(goal|goals|outcome|outcomes|success)\s*:\s*(.+?)\s*$", re.IGNORECASE)),
+    ("scope", re.compile(r"^\s*(scope|feature|features|include|includes)\s*:\s*(.+?)\s*$", re.IGNORECASE)),
+    ("constraints", re.compile(r"^\s*(constraint|constraints|non-goal|non-goals|limit|limits)\s*:\s*(.+?)\s*$", re.IGNORECASE)),
+    (
+        "acceptance_criteria",
+        re.compile(r"^\s*(acceptance criteria|success criteria|done when)\s*:\s*(.+?)\s*$", re.IGNORECASE),
+    ),
+)
+
+
+def _split_listish(text: str) -> list[str]:
+    parts = re.split(r"[;\n]", text.strip())
+    items = [part.strip(" -.\t") for part in parts if part.strip(" -.\t")]
+    return items
+
+
+def extract_sufficient_idea(raw_text: str, prior_text: str | None = None) -> dict[str, object]:
+    # prior_text carries full multi-turn conversation context — use it as the primary
+    # text source for field extraction so earlier turns contribute problem/scope/etc.
+    working_text = f"{prior_text}\n{raw_text}" if prior_text else raw_text
+    summary = ""
+    extracted: dict[str, object] = {}
+
+    for raw_line in working_text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        matched = False
+        for field_name, pattern in _FIELD_PATTERNS:
+            m = pattern.match(line)
+            if not m:
+                continue
+            value = m.group(2).strip()
+            if field_name in {"target_users", "user_outcomes", "scope", "constraints", "acceptance_criteria"}:
+                extracted[field_name] = _split_listish(value)
+            else:
+                extracted[field_name] = value
+            matched = True
+            break
+
+        if not matched and not summary:
+            summary = line
+
+    if summary:
+        extracted["summary"] = summary
+
+    scope_items = extracted.get("scope")
+    if isinstance(scope_items, list) and scope_items:
+        extracted["scope"] = scope_items
+
+    return extracted
+
+
+def _normalize_string_list(value: Any) -> list[str]:
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if isinstance(value, list):
+        out: list[str] = []
+        for item in value:
+            text = str(item).strip()
+            if text:
+                out.append(text)
+        return out
+    return []
+
+
+def _first_nonempty_line(raw_text: str) -> str:
+    for raw_line in raw_text.splitlines():
+        line = raw_line.strip()
+        if line:
+            return line
+    return ""
+
+
+def _dedupe_strings(values: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for item in values:
+        text = str(item).strip()
+        key = text.casefold()
+        if not text or key in seen:
+            continue
+        seen.add(key)
+        out.append(text)
+    return out
+
+
+def _heuristic_default_list(field_name: str, raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    if field_name == "target_users":
+        if "manager" in lowered:
+            return ["managers"]
+        if "operator" in lowered:
+            return ["operators"]
+        if "team" in lowered or "teams" in lowered:
+            return ["team members"]
+        if "customer" in lowered or "client" in lowered:
+            return ["customers"]
+        return ["primary operators"]
+    if field_name == "user_outcomes":
+        return ["Complete the core workflow in one place with less manual coordination."]
+    if field_name == "scope":
+        return ["Deliver a minimal first release focused on the main workflow implied by the request."]
+    if field_name == "assumptions":
+        return ["Exact workflows, integrations, and policy constraints still need confirmation during planning."]
+    return []
+
+
+def _normalize_llm_sufficient_idea_payload(raw_text: str, payload: Any) -> dict[str, object] | None:
+    if not isinstance(payload, dict):
+        return None
+
+    summary = str(payload.get("summary") or "").strip() or _first_nonempty_line(raw_text)
+    problem = str(payload.get("problem") or "").strip()
+    if not problem:
+        return None
+
+    normalized: dict[str, object] = {
+        "summary": summary,
+        "problem": problem,
+    }
+    for field_name in ("target_users", "user_outcomes", "scope", "assumptions"):
+        values = _dedupe_strings(_normalize_string_list(payload.get(field_name)))
+        if not values:
+            values = _heuristic_default_list(field_name, raw_text)
+        if not values:
+            return None
+        normalized[field_name] = values
+    return normalized
+
+
+def _merge_sufficient_idea(
+    *,
+    raw_text: str,
+    extracted: dict[str, object],
+    llm_payload: dict[str, object] | None,
+) -> dict[str, object]:
+    if llm_payload is None:
+        return dict(extracted)
+
+    merged = dict(llm_payload)
+    for field_name, value in extracted.items():
+        if field_name in {"target_users", "user_outcomes", "scope", "constraints", "acceptance_criteria", "assumptions"}:
+            normalized = _dedupe_strings(_normalize_string_list(value))
+            if normalized:
+                merged[field_name] = normalized
+            continue
+        text = str(value).strip()
+        if text:
+            merged[field_name] = text
+
+    summary = str(merged.get("summary") or "").strip() or _first_nonempty_line(raw_text)
+    if summary:
+        merged["summary"] = summary
+    return merged
+
+
+def _llm_repo_root() -> Path:
+    return Path.cwd()
+
+
+def _extract_llm_sufficient_idea(raw_text: str, extracted: dict[str, object]) -> dict[str, object] | None:
+    if not raw_text.strip():
+        return None
+
+    prompt_payload = {
+        "task": "shape_idea_sufficiency_payload",
+        "instructions": [
+            "Return JSON only.",
+            "Shape the idea into planning-ready fields.",
+            "Preserve any explicit extracted fields as ground truth; use them as strong signals instead of overwriting them.",
+            "Infer reasonable defaults for sparse or vague inputs without inventing unnecessary detail.",
+            "Return keys: summary, problem, target_users, user_outcomes, scope, assumptions.",
+        ],
+        "raw_text": raw_text,
+        "explicit_extracted_fields": extracted,
+        "response_shape": {
+            "summary": "string",
+            "problem": "string",
+            "target_users": ["string"],
+            "user_outcomes": ["string"],
+            "scope": ["string"],
+            "assumptions": ["string"],
+        },
+    }
+
+    try:
+        result = invoke_llm(
+            LlmInvocationRequest(
+                purpose="idea_sufficiency_shape",
+                repo_root=_llm_repo_root(),
+                prompt="",
+                prompt_payload=prompt_payload,
+                delivery_model="final_only",
+                interaction_model="request_response",
+                response_contract="json_only",
+                timeout_seconds=45,
+                strength="light",
+            )
+        )
+    except Exception:
+        return None
+
+    if not result.ok or not result.contract_ok:
+        return None
+    normalized = _normalize_llm_sufficient_idea_payload(raw_text, result.parsed_json)
+    if normalized is None:
+        return None
+    return _merge_sufficient_idea(raw_text=raw_text, extracted=extracted, llm_payload=normalized)
+
+
+def _render_registered_idea_as_text(payload: dict[str, Any]) -> str | None:
+    idea = payload.get("idea") if isinstance(payload.get("idea"), dict) else payload
+    if not isinstance(idea, dict):
+        return None
+
+    problem = str(idea.get("problem") or "").strip()
+    users = _normalize_string_list(idea.get("target_users") or idea.get("users"))
+    goals = _normalize_string_list(idea.get("user_outcomes") or idea.get("goal") or idea.get("goals"))
+    scope = _normalize_string_list(idea.get("scope"))
+    constraints = _normalize_string_list(idea.get("constraints"))
+    acceptance = _normalize_string_list(idea.get("acceptance_criteria"))
+    summary = str(payload.get("summary") or idea.get("summary") or payload.get("title") or idea.get("title") or "").strip()
+
+    if not any([problem, users, goals, scope, constraints, acceptance, summary]):
+        return None
+
+    lines: list[str] = []
+    if summary:
+        lines.append(summary)
+    if problem:
+        lines.append(f"Problem: {problem}")
+    if users:
+        lines.append(f"Users: {'; '.join(users)}")
+    if goals:
+        lines.append(f"Goal: {'; '.join(goals)}")
+    if scope:
+        lines.append(f"Scope: {'; '.join(scope)}")
+    if constraints:
+        lines.append(f"Constraints: {'; '.join(constraints)}")
+    if acceptance:
+        lines.append(f"Acceptance Criteria: {'; '.join(acceptance)}")
+    return "\n".join(lines).strip() or None
+
+
+def load_idea_source(*, text: str | None, source_path: Path | None) -> tuple[str, dict[str, object]]:
+    provided = int(bool(text and text.strip())) + int(source_path is not None)
+    if provided != 1:
+        raise ValueError("Provide exactly one input source via --text or --from.")
+
+    if source_path is not None:
+        if not source_path.exists() or not source_path.is_file():
+            raise ValueError(f"Idea file not found: {source_path}")
+        loaded = source_path.read_text(encoding="utf-8")
+        if not loaded.strip():
+            raise ValueError(f"Idea file is empty: {source_path}")
+        if source_path.suffix.lower() == '.json':
+            try:
+                payload = json.loads(loaded)
+            except Exception:
+                payload = None
+            if isinstance(payload, dict):
+                rendered = _render_registered_idea_as_text(payload)
+                if rendered:
+                    return rendered, {"mode": "registered_idea_json", "source": str(source_path), "character_count": len(rendered)}
+        return loaded, {"mode": "file", "source": str(source_path), "character_count": len(loaded)}
+
+    assert text is not None
+    stripped = text.strip()
+    if not stripped:
+        raise ValueError("Idea text is empty.")
+    return stripped, {"mode": "text", "source": "inline", "character_count": len(stripped)}
+
+
+def evaluate_idea_sufficiency(raw_text: str, *, input_meta: dict[str, object]) -> SufficiencyResult:
+    lowered = raw_text.lower()
+    sentences = [chunk.strip() for chunk in re.split(r"[.!?\n]+", raw_text) if chunk.strip()]
+    extracted = extract_sufficient_idea(raw_text)
+    sufficient_idea = _extract_llm_sufficient_idea(raw_text, extracted) or extracted
+
+    identified_gaps: list[str] = []
+    discussion_points: list[str] = []
+    blockers: list[str] = []
+    score = 0
+
+    # Coverage is determined by sufficient_idea fields after LLM shaping,
+    # not by raw text patterns. If LLM produced a non-empty field, it counts as covered.
+    # Raw text patterns are only used when LLM shaping didn't produce the field.
+    coverage: dict[str, bool] = {}
+    for name, question, pattern, critical in _DIMENSIONS:
+        # Map dimension name to the corresponding sufficient_idea field
+        field_map = {
+            'problem': 'problem',
+            'users': 'target_users',
+            'goal': 'user_outcomes',
+            'scope': 'scope',
+            'constraints': 'constraints',
+            'acceptance_criteria': 'acceptance_criteria',
+        }
+        field_key = field_map.get(name, name)
+        # Check LLM-produced sufficient_idea first
+        present = bool(sufficient_idea.get(field_key) and str(sufficient_idea.get(field_key)).strip())
+        # Fall back to raw text pattern if LLM didn't fill it
+        if not present:
+            present = bool(pattern.search(lowered))
+        coverage[name] = present
+        if present:
+            score += 15
+            continue
+        identified_gaps.append(name)
+        discussion_points.append(question)
+        if critical:
+            blockers.append(name)
+
+    if len(raw_text.strip()) >= 160 and len(sentences) >= 4:
+        score += 10
+
+    score = min(score, 100)
+    passed = score >= 70 and not blockers
+
+    payload = {
+        "input": input_meta,
+        "sufficient_idea": sufficient_idea,
+        "discussion_points": discussion_points,
+        "sufficiency_quotient": score,
+        "story_generation_pass": passed,
+        "identified_gaps": identified_gaps,
+        "blockers": blockers,
+        "coverage": coverage,
+    }
+    return SufficiencyResult(payload=payload, passed=passed)
+
+
+def render_sufficiency_json(result: SufficiencyResult) -> str:
+    return json.dumps(result.payload, indent=2, sort_keys=True) + "\n"