intake-ai-cli 0.1.0__py3-none-any.whl

intake/analyze/models.py

@@ -0,0 +1,152 @@
+"""Data models for the analysis pipeline.
+
+All models are dataclasses (lightweight, no validation overhead).
+These flow between analyze sub-phases and into the generate module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Requirement:
+    """A single extracted requirement (functional or non-functional)."""
+
+    id: str
+    type: str  # "functional" | "non_functional"
+    title: str
+    description: str
+    acceptance_criteria: list[str]
+    source: str
+    priority: str = "medium"
+    risk_score: float = 0.0
+
+
+@dataclass
+class Conflict:
+    """A contradiction detected between two sources."""
+
+    id: str
+    description: str
+    source_a: dict[str, str]
+    source_b: dict[str, str]
+    recommendation: str
+    severity: str = "medium"  # "low" | "medium" | "high"
+
+
+@dataclass
+class OpenQuestion:
+    """An ambiguity that cannot be resolved from available sources."""
+
+    id: str
+    question: str
+    context: str
+    source: str
+    recommendation: str
+
+
+@dataclass
+class RiskItem:
+    """Risk assessment for a requirement or group of requirements."""
+
+    id: str
+    requirement_ids: list[str]
+    description: str
+    probability: str  # "low" | "medium" | "high"
+    impact: str  # "low" | "medium" | "high"
+    mitigation: str
+    category: str  # "technical" | "scope" | "integration" | "security" | "performance"
+
+
+@dataclass
+class TechDecision:
+    """A technical design decision linked to a requirement."""
+
+    decision: str
+    justification: str
+    requirement: str
+
+
+@dataclass
+class TaskItem:
+    """An atomic implementation task."""
+
+    id: int
+    title: str
+    description: str
+    files: list[str]
+    dependencies: list[int]
+    checks: list[str]
+    estimated_minutes: int = 15
+
+
+@dataclass
+class FileAction:
+    """A file to create or modify."""
+
+    path: str
+    description: str
+    action: str = "create"  # "create" | "modify"
+
+
+@dataclass
+class AcceptanceCheck:
+    """An executable acceptance check."""
+
+    id: str
+    name: str
+    type: str  # "command" | "files_exist" | "pattern_present" | "pattern_absent"
+    required: bool = True
+    tags: list[str] = field(default_factory=list)
+    command: str = ""
+    paths: list[str] = field(default_factory=list)
+    glob: str = ""
+    patterns: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DesignResult:
+    """Output of the design analysis phase."""
+
+    components: list[str] = field(default_factory=list)
+    files_to_create: list[FileAction] = field(default_factory=list)
+    files_to_modify: list[FileAction] = field(default_factory=list)
+    tech_decisions: list[TechDecision] = field(default_factory=list)
+    tasks: list[TaskItem] = field(default_factory=list)
+    acceptance_checks: list[AcceptanceCheck] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AnalysisResult:
+    """Complete output of the analysis pipeline.
+
+    Aggregates requirements, conflicts, questions, risks, and design.
+    This is the primary data structure consumed by the generate module.
+    """
+
+    functional_requirements: list[Requirement] = field(default_factory=list)
+    non_functional_requirements: list[Requirement] = field(default_factory=list)
+    open_questions: list[OpenQuestion] = field(default_factory=list)
+    conflicts: list[Conflict] = field(default_factory=list)
+    risks: list[RiskItem] = field(default_factory=list)
+    design: DesignResult = field(default_factory=DesignResult)
+    duplicates_removed: int = 0
+    total_cost: float = 0.0
+    model_used: str = ""
+
+    @property
+    def all_requirements(self) -> list[Requirement]:
+        """All requirements (functional + non-functional)."""
+        return self.functional_requirements + self.non_functional_requirements
+
+    @property
+    def requirement_count(self) -> int:
+        """Total number of requirements."""
+        return len(self.functional_requirements) + len(self.non_functional_requirements)
+
+    @property
+    def task_count(self) -> int:
+        """Total number of tasks."""
+        return len(self.design.tasks)

intake/analyze/prompts.py

@@ -0,0 +1,208 @@
+"""System prompts for the LLM analysis pipeline.
+
+Each prompt is a template string with named placeholders.
+Never hardcode model-specific instructions — keep them provider-agnostic.
+"""
+
+from __future__ import annotations
+
+EXTRACTION_PROMPT = """You are a senior software requirements analyst.
+
+You are given {n_sources} requirement sources for a software project.
+Your job is to analyze ALL sources and produce a structured result.
+
+OUTPUT LANGUAGE: {language}
+REQUIREMENTS FORMAT: {requirements_format}
+
+INSTRUCTIONS:
+
+1. FUNCTIONAL REQUIREMENTS (FR-XX):
+   - Extract ALL functional requirements from all sources
+   - EARS format: "When [trigger], the system shall [behavior], so that [outcome]"
+   - For each requirement, list concrete and verifiable acceptance criteria
+   - Indicate which source each requirement comes from (source number)
+
+2. NON-FUNCTIONAL REQUIREMENTS (NFR-XX):
+   - Performance, security, scalability, accessibility, etc.
+   - Each with concrete metrics when possible
+
+3. CONFLICTS:
+   - If two sources contradict each other, document it
+   - Indicate what each source says and your recommendation
+
+4. OPEN QUESTIONS:
+   - Ambiguities that cannot be resolved with the available information
+   - For each, indicate which source generates it and a recommendation
+
+5. TECHNICAL DEPENDENCIES:
+   - Libraries, external services, APIs that will be needed
+
+Respond ONLY with valid JSON, no markdown or additional text.
+
+RESPONSE SCHEMA:
+{{
+  "functional_requirements": [
+    {{
+      "id": "FR-01",
+      "title": "Short title",
+      "description": "When ..., the system shall ..., so that ...",
+      "acceptance_criteria": ["AC-01.1: ...", "AC-01.2: ..."],
+      "source": "Source 1",
+      "priority": "high|medium|low"
+    }}
+  ],
+  "non_functional_requirements": [
+    {{
+      "id": "NFR-01",
+      "title": "Short title",
+      "description": "The system shall ...",
+      "acceptance_criteria": ["AC-NFR-01.1: ..."],
+      "source": "Source 1",
+      "priority": "high|medium|low"
+    }}
+  ],
+  "conflicts": [
+    {{
+      "id": "CONFLICT-01",
+      "description": "Conflict description",
+      "source_a": {{"source": "Source 1", "says": "..."}},
+      "source_b": {{"source": "Source 2", "says": "..."}},
+      "recommendation": "...",
+      "severity": "high|medium|low"
+    }}
+  ],
+  "open_questions": [
+    {{
+      "id": "Q-01",
+      "question": "...?",
+      "context": "Why this matters",
+      "source": "Source that generates the ambiguity",
+      "recommendation": "Suggestion"
+    }}
+  ],
+  "dependencies": ["authlib", "postgresql", "redis"]
+}}
+"""
+
+
+RISK_ASSESSMENT_PROMPT = """You are a senior software risk analyst.
+
+Given these extracted requirements and detected conflicts, assess the
+implementation risks.
+
+For each risk, provide:
+- Which requirements are affected
+- Probability (low/medium/high)
+- Impact (low/medium/high)
+- Category (technical/scope/integration/security/performance)
+- Concrete mitigation strategy
+
+OUTPUT LANGUAGE: {language}
+
+REQUIREMENTS:
+{requirements_json}
+
+CONFLICTS:
+{conflicts_json}
+
+Respond ONLY with valid JSON.
+
+RESPONSE SCHEMA:
+{{
+  "risks": [
+    {{
+      "id": "RISK-01",
+      "requirement_ids": ["FR-01", "NFR-03"],
+      "description": "...",
+      "probability": "medium",
+      "impact": "high",
+      "category": "technical",
+      "mitigation": "..."
+    }}
+  ]
+}}
+"""
+
+
+DESIGN_PROMPT = """You are a senior software architect.
+
+You are given:
+1. Extracted and structured requirements
+2. Existing project structure (file tree)
+3. Project tech stack
+
+Your job is to produce:
+
+1. TECHNICAL DESIGN:
+   - Architecture components
+   - Files to create and modify (real paths)
+   - Technical decisions with justification linked to requirements
+
+2. TASK PLAN:
+   - Atomic tasks, each implementable in 5-30 minutes by an agent
+   - Ordered by dependencies (DAG)
+   - Each task with: affected files, verification checks
+
+3. EXECUTABLE ACCEPTANCE CRITERIA:
+   - Shell commands that validate if a requirement is met
+   - Code patterns that must exist or not exist
+   - Files that must exist
+
+OUTPUT LANGUAGE: {language}
+DESIGN DEPTH: {design_depth}
+TASK GRANULARITY: {task_granularity}
+
+PROJECT STACK: {stack}
+FILE TREE:
+{file_tree}
+
+REQUIREMENTS:
+{requirements_json}
+
+Respond ONLY with valid JSON.
+
+RESPONSE SCHEMA:
+{{
+  "components": ["component1", "component2"],
+  "files_to_create": [
+    {{"path": "src/auth/handler.py", "description": "Authentication handler"}}
+  ],
+  "files_to_modify": [
+    {{"path": "src/main.py", "description": "Add auth middleware"}}
+  ],
+  "tech_decisions": [
+    {{"decision": "Use JWT for auth",
+      "justification": "Stateless, scalable", "requirement": "FR-01"}}
+  ],
+  "tasks": [
+    {{
+      "id": 1,
+      "title": "Set up auth module",
+      "description": "Create src/auth/ with handler and middleware",
+      "files": ["src/auth/handler.py", "src/auth/middleware.py"],
+      "dependencies": [],
+      "checks": ["pytest tests/test_auth.py -q"],
+      "estimated_minutes": 15
+    }}
+  ],
+  "acceptance_checks": [
+    {{
+      "id": "unit-tests",
+      "name": "Unit tests pass",
+      "type": "command",
+      "command": "pytest tests/ -q",
+      "required": true,
+      "tags": ["test"]
+    }},
+    {{
+      "id": "auth-module-exists",
+      "name": "Auth module created",
+      "type": "files_exist",
+      "paths": ["src/auth/handler.py"],
+      "required": true,
+      "tags": ["structure"]
+    }}
+  ],
+  "dependencies": ["pyjwt", "bcrypt"]
+}}
+"""

intake/analyze/questions.py

@@ -0,0 +1,59 @@
+"""Open questions validation and enrichment.
+
+Validates open questions extracted by the LLM and filters out
+low-quality or incomplete entries.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import structlog
+
+if TYPE_CHECKING:
+    from intake.analyze.models import OpenQuestion
+
+logger = structlog.get_logger()
+
+
+def validate_questions(questions: list[OpenQuestion]) -> list[OpenQuestion]:
+    """Validate and filter extracted open questions.
+
+    Removes questions that lack essential fields (question text,
+    context, or recommendation).
+
+    Args:
+        questions: Raw questions from the extraction phase.
+
+    Returns:
+        Filtered list of valid open questions.
+    """
+    valid: list[OpenQuestion] = []
+
+    for question in questions:
+        if _is_valid(question):
+            valid.append(question)
+        else:
+            logger.debug(
+                "question_filtered",
+                id=question.id,
+                reason="missing required fields",
+            )
+
+    filtered = len(questions) - len(valid)
+    if filtered > 0:
+        logger.info(
+            "questions_validated",
+            total=len(questions),
+            valid=len(valid),
+            filtered=filtered,
+        )
+
+    return valid
+
+
+def _is_valid(question: OpenQuestion) -> bool:
+    """Check that a question has all required fields populated."""
+    if not question.question.strip():
+        return False
+    return bool(question.context.strip())

intake/analyze/risks.py

@@ -0,0 +1,70 @@
+"""Risk assessment — parses LLM risk analysis into typed models.
+
+Called after extraction when config.spec.risk_assessment is True.
+"""
+
+from __future__ import annotations
+
+import structlog
+
+from intake.analyze.models import RiskItem
+
+logger = structlog.get_logger()
+
+
+def parse_risks(raw: dict[str, object]) -> list[RiskItem]:
+    """Parse the LLM risk assessment response into typed RiskItem list.
+
+    Args:
+        raw: Parsed JSON dict from the LLM risk assessment call.
+
+    Returns:
+        List of validated RiskItem instances.
+    """
+    items: list[RiskItem] = []
+
+    for entry in _get_list(raw, "risks"):
+        risk = _parse_risk_item(entry)
+        if _is_valid(risk):
+            items.append(risk)
+        else:
+            logger.debug(
+                "risk_filtered",
+                id=risk.id,
+                reason="missing required fields",
+            )
+
+    logger.info("risks_parsed", count=len(items))
+    return items
+
+
+def _parse_risk_item(item: dict[str, object]) -> RiskItem:
+    """Parse a single risk item from the LLM output."""
+    req_ids = item.get("requirement_ids", [])
+    if not isinstance(req_ids, list):
+        req_ids = []
+
+    return RiskItem(
+        id=str(item.get("id", "")),
+        requirement_ids=[str(r) for r in req_ids],
+        description=str(item.get("description", "")),
+        probability=str(item.get("probability", "medium")),
+        impact=str(item.get("impact", "medium")),
+        mitigation=str(item.get("mitigation", "")),
+        category=str(item.get("category", "technical")),
+    )
+
+
+def _is_valid(risk: RiskItem) -> bool:
+    """Check that a risk has all required fields populated."""
+    if not risk.description.strip():
+        return False
+    return bool(risk.mitigation.strip())
+
+
+def _get_list(data: dict[str, object], key: str) -> list[dict[str, object]]:
+    """Safely extract a list from a dict, returning empty list on failure."""
+    value = data.get(key, [])
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]