attune-ai 2.0.0__py3-none-any.whl

attune/prompts/parser.py

@@ -0,0 +1,285 @@
+"""XML Response Parser
+
+Parses structured XML responses from LLMs for dashboard display
+and workflow automation.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Any
+
+import defusedxml.ElementTree as DefusedET
+
+
+@dataclass
+class Finding:
+    """Structured finding from XML response.
+
+    Represents a single issue, vulnerability, or code review comment
+    extracted from an LLM response.
+    """
+
+    severity: str  # critical, high, medium, low, info
+    title: str
+    location: str | None = None
+    details: str = ""
+    fix: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "severity": self.severity,
+            "title": self.title,
+            "location": self.location,
+            "details": self.details,
+            "fix": self.fix,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Finding:
+        """Create Finding from dictionary."""
+        return cls(
+            severity=data.get("severity", "medium"),
+            title=data.get("title", ""),
+            location=data.get("location"),
+            details=data.get("details", ""),
+            fix=data.get("fix", ""),
+        )
+
+
+@dataclass
+class ParsedResponse:
+    """Result of parsing an XML response.
+
+    Contains extracted structured data or fallback raw text
+    if parsing fails.
+    """
+
+    success: bool
+    raw: str
+    summary: str | None = None
+    findings: list[Finding] = field(default_factory=list)
+    checklist: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "success": self.success,
+            "raw": self.raw,
+            "summary": self.summary,
+            "findings": [f.to_dict() for f in self.findings],
+            "checklist": self.checklist,
+            "errors": self.errors,
+            "extra": self.extra,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ParsedResponse:
+        """Create ParsedResponse from dictionary."""
+        findings = [Finding.from_dict(f) for f in data.get("findings", [])]
+        return cls(
+            success=data.get("success", False),
+            raw=data.get("raw", ""),
+            summary=data.get("summary"),
+            findings=findings,
+            checklist=data.get("checklist", []),
+            errors=data.get("errors", []),
+            extra=data.get("extra", {}),
+        )
+
+    @classmethod
+    def from_raw(cls, raw: str, errors: list[str] | None = None) -> ParsedResponse:
+        """Create a fallback ParsedResponse from raw text."""
+        return cls(
+            success=False,
+            raw=raw,
+            summary=raw[:500] if raw else None,
+            errors=errors or ["No XML content found"],
+        )
+
+
+class XmlResponseParser:
+    """Parse LLM responses containing XML.
+
+    Extracts structured data from XML-formatted responses while
+    gracefully handling malformed or missing XML.
+    """
+
+    def __init__(self, fallback_on_error: bool = True):
+        """Initialize the parser.
+
+        Args:
+            fallback_on_error: If True, return raw text on parse failure
+                              instead of raising an exception.
+
+        """
+        self.fallback_on_error = fallback_on_error
+
+    def parse(self, response: str) -> ParsedResponse:
+        """Parse XML response, with graceful fallback.
+
+        Args:
+            response: The LLM response text, potentially containing XML.
+
+        Returns:
+            ParsedResponse with extracted data or fallback raw text.
+
+        """
+        if not response:
+            return ParsedResponse.from_raw("", ["Empty response"])
+
+        # Extract XML from response (may be wrapped in markdown)
+        xml_content = self._extract_xml(response)
+
+        if not xml_content:
+            if self.fallback_on_error:
+                return ParsedResponse.from_raw(response, ["No XML content found"])
+            raise ValueError("No XML content in response")
+
+        try:
+            # Use defusedxml for safe XML parsing (prevents XXE attacks)
+            root = DefusedET.fromstring(xml_content)
+
+            return ParsedResponse(
+                success=True,
+                raw=response,
+                summary=self._extract_text(root, "summary"),
+                findings=self._extract_findings(root),
+                checklist=self._extract_checklist(root),
+                extra=self._extract_extra(root),
+            )
+        except ET.ParseError as e:
+            if self.fallback_on_error:
+                return ParsedResponse.from_raw(response, [f"XML parse error: {e}"])
+            raise
+
+    def _extract_xml(self, response: str) -> str | None:
+        """Extract XML content from response.
+
+        Handles various formats:
+        - Direct XML
+        - XML in markdown code blocks
+        - XML mixed with other text
+        """
+        # Handle markdown code blocks with xml tag
+        xml_block = re.search(r"```xml\s*(.*?)\s*```", response, re.DOTALL)
+        if xml_block:
+            return xml_block.group(1).strip()
+
+        # Handle generic markdown code blocks
+        code_block = re.search(r"```\s*(.*?)\s*```", response, re.DOTALL)
+        if code_block:
+            content = code_block.group(1).strip()
+            if content.startswith("<"):
+                return content
+
+        # Try to find <response> tags
+        response_match = re.search(r"<response\b[^>]*>.*?</response>", response, re.DOTALL)
+        if response_match:
+            return response_match.group(0)
+
+        # Try to find any root XML element
+        xml_match = re.search(r"<(\w+)\b[^>]*>.*?</\1>", response, re.DOTALL)
+        if xml_match:
+            return xml_match.group(0)
+
+        # If response itself looks like XML
+        stripped = response.strip()
+        if stripped.startswith("<") and stripped.endswith(">"):
+            return stripped
+
+        return None
+
+    def _extract_text(self, root: ET.Element, tag: str) -> str | None:
+        """Extract text content from a tag."""
+        element = root.find(f".//{tag}")
+        if element is not None and element.text:
+            return element.text.strip()
+        return None
+
+    def _extract_findings(self, root: ET.Element) -> list[Finding]:
+        """Extract findings from parsed XML."""
+        findings = []
+
+        # Look for findings in various possible locations
+        for finding_el in root.findall(".//finding"):
+            findings.append(self._parse_finding(finding_el))
+
+        # Also check for <item> inside <findings>
+        findings_container = root.find(".//findings")
+        if findings_container is not None:
+            for item_el in findings_container.findall("item"):
+                findings.append(self._parse_finding(item_el))
+
+        return findings
+
+    def _parse_finding(self, element: ET.Element) -> Finding:
+        """Parse a single finding element."""
+        title = self._extract_text(element, "title") or element.get("title") or ""
+        return Finding(
+            severity=element.get("severity") or "medium",
+            title=title,
+            location=self._extract_text(element, "location"),
+            details=self._extract_text(element, "details") or "",
+            fix=self._extract_text(element, "fix") or "",
+        )
+
+    def _extract_checklist(self, root: ET.Element) -> list[str]:
+        """Extract checklist items from parsed XML."""
+        items = []
+
+        # Look for remediation-checklist
+        checklist = root.find(".//remediation-checklist")
+        if checklist is not None:
+            for item in checklist.findall("item"):
+                if item.text:
+                    items.append(item.text.strip())
+
+        # Also check for generic checklist
+        if not items:
+            checklist = root.find(".//checklist")
+            if checklist is not None:
+                for item in checklist.findall("item"):
+                    if item.text:
+                        items.append(item.text.strip())
+
+        return items
+
+    def _extract_extra(self, root: ET.Element) -> dict[str, Any]:
+        """Extract additional fields from the response."""
+        extra: dict[str, Any] = {}
+
+        # Extract verdict (for code review)
+        verdict = self._extract_text(root, "verdict")
+        if verdict:
+            extra["verdict"] = verdict
+
+        # Extract confidence (for research)
+        confidence = root.find(".//confidence")
+        if confidence is not None:
+            extra["confidence"] = {
+                "level": confidence.get("level", "medium"),
+                "reasoning": confidence.text.strip() if confidence.text else "",
+            }
+
+        # Extract key insights (for research)
+        insights = root.find(".//key-insights")
+        if insights is not None:
+            extra["key_insights"] = [i.text.strip() for i in insights.findall("insight") if i.text]
+
+        # Extract suggestions (for code review)
+        suggestions = root.find(".//suggestions")
+        if suggestions is not None:
+            extra["suggestions"] = [
+                s.text.strip() for s in suggestions.findall("suggestion") if s.text
+            ]
+
+        return extra

attune/prompts/registry.py

@@ -0,0 +1,313 @@
+"""Built-in XML Prompt Templates Registry
+
+Provides pre-configured XML templates for common workflows.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+from .templates import XmlPromptTemplate
+
+# =============================================================================
+# Response Format Definitions
+# =============================================================================
+
+SECURITY_AUDIT_RESPONSE = """<response>
+  <summary>Brief overall security assessment (1-2 sentences)</summary>
+  <findings>
+    <finding severity="critical|high|medium|low|info">
+      <title>Issue title</title>
+      <location>file:line or component</location>
+      <details>Description of the vulnerability and potential impact</details>
+      <fix>Specific remediation steps with code example if applicable</fix>
+    </finding>
+    <!-- Additional findings... -->
+  </findings>
+  <remediation-checklist>
+    <item>Priority action item 1</item>
+    <item>Priority action item 2</item>
+    <!-- Additional items... -->
+  </remediation-checklist>
+</response>"""
+
+CODE_REVIEW_RESPONSE = """<response>
+  <summary>Brief review summary (1-2 sentences)</summary>
+  <verdict>approve|approve_with_suggestions|request_changes|reject</verdict>
+  <findings>
+    <finding severity="critical|high|medium|low|info">
+      <title>Issue title</title>
+      <location>file:line</location>
+      <details>Description of the issue</details>
+      <fix>Suggested fix or improvement</fix>
+    </finding>
+    <!-- Additional findings... -->
+  </findings>
+  <suggestions>
+    <suggestion>Optional improvement suggestion</suggestion>
+    <!-- Additional suggestions... -->
+  </suggestions>
+  <remediation-checklist>
+    <item>Required change 1</item>
+    <item>Required change 2</item>
+    <!-- Additional items if request_changes... -->
+  </remediation-checklist>
+</response>"""
+
+RESEARCH_RESPONSE = """<response>
+  <summary>Research synthesis summary (2-3 sentences)</summary>
+  <key-insights>
+    <insight>Key insight or finding 1</insight>
+    <insight>Key insight or finding 2</insight>
+    <!-- Additional insights... -->
+  </key-insights>
+  <findings>
+    <finding severity="info">
+      <title>Topic or concept</title>
+      <details>Explanation with context</details>
+    </finding>
+    <!-- Additional topics if needed... -->
+  </findings>
+  <confidence level="high|medium|low">Reasoning for confidence level</confidence>
+  <remediation-checklist>
+    <item>Recommended next step 1</item>
+    <item>Recommended next step 2</item>
+  </remediation-checklist>
+</response>"""
+
+BUG_ANALYSIS_RESPONSE = """<response>
+  <summary>Root cause summary (1-2 sentences)</summary>
+  <findings>
+    <finding severity="critical|high|medium|low">
+      <title>Bug description</title>
+      <location>file:line where issue originates</location>
+      <details>Root cause analysis</details>
+      <fix>Recommended fix with code</fix>
+    </finding>
+  </findings>
+  <remediation-checklist>
+    <item>Fix step 1</item>
+    <item>Verification step</item>
+    <item>Test to add</item>
+  </remediation-checklist>
+</response>"""
+
+PERF_AUDIT_RESPONSE = """<response>
+  <summary>Performance assessment summary (1-2 sentences)</summary>
+  <performance-score>0-100</performance-score>
+  <findings>
+    <finding severity="critical|high|medium|low">
+      <title>Performance issue title</title>
+      <location>file:line or component</location>
+      <details>Description of the bottleneck and its impact</details>
+      <fix>Optimization recommendation with code example</fix>
+    </finding>
+  </findings>
+  <remediation-checklist>
+    <item>Optimization priority 1</item>
+    <item>Optimization priority 2</item>
+  </remediation-checklist>
+</response>"""
+
+REFACTOR_PLAN_RESPONSE = """<response>
+  <summary>Tech debt assessment (1-2 sentences)</summary>
+  <trajectory>increasing|stable|decreasing</trajectory>
+  <findings>
+    <finding severity="high|medium|low">
+      <title>Debt item description</title>
+      <location>file:line</location>
+      <details>Impact and complexity assessment</details>
+      <fix>Refactoring approach</fix>
+    </finding>
+  </findings>
+  <roadmap>
+    <phase priority="1|2|3">
+      <name>Phase name</name>
+      <description>What to accomplish</description>
+      <effort>high|medium|low</effort>
+    </phase>
+  </roadmap>
+  <remediation-checklist>
+    <item>Immediate action 1</item>
+    <item>Immediate action 2</item>
+  </remediation-checklist>
+</response>"""
+
+TEST_GEN_RESPONSE = """<response>
+  <summary>Test generation summary (1-2 sentences)</summary>
+  <coverage-improvement>Estimated coverage improvement</coverage-improvement>
+  <findings>
+    <finding severity="info">
+      <title>Untested area</title>
+      <location>file:function or class</location>
+      <details>Why this needs testing</details>
+      <fix>Test approach recommendation</fix>
+    </finding>
+  </findings>
+  <tests>
+    <test target="function or class name">
+      <type>unit|integration|edge-case</type>
+      <description>What this test verifies</description>
+      <code><![CDATA[
+def test_example():
+    # Test code here
+    pass
+]]></code>
+    </test>
+  </tests>
+  <remediation-checklist>
+    <item>Test to add first</item>
+    <item>Test to add second</item>
+  </remediation-checklist>
+</response>"""
+
+DOC_GEN_RESPONSE = """<response>
+  <summary>Documentation summary (1-2 sentences)</summary>
+  <sections>
+    <section name="Section Title">
+      <content>Section content in markdown</content>
+    </section>
+  </sections>
+  <findings>
+    <finding severity="info">
+      <title>Documentation gap or improvement</title>
+      <details>What needs documentation</details>
+    </finding>
+  </findings>
+  <remediation-checklist>
+    <item>Documentation improvement 1</item>
+    <item>Documentation improvement 2</item>
+  </remediation-checklist>
+</response>"""
+
+RELEASE_PREP_RESPONSE = """<response>
+  <summary>Release readiness assessment (1-2 sentences)</summary>
+  <verdict>approved|blocked|needs-review</verdict>
+  <confidence>high|medium|low</confidence>
+  <findings>
+    <finding severity="blocker|warning|info">
+      <title>Issue title</title>
+      <location>Component or area</location>
+      <details>Description of the issue</details>
+      <fix>Required action before release</fix>
+    </finding>
+  </findings>
+  <checklist>
+    <item status="pass|fail|skip">Check description</item>
+  </checklist>
+  <remediation-checklist>
+    <item>Pre-release action 1</item>
+    <item>Pre-release action 2</item>
+  </remediation-checklist>
+</response>"""
+
+DEPENDENCY_CHECK_RESPONSE = """<response>
+  <summary>Dependency security assessment (1-2 sentences)</summary>
+  <risk-level>critical|high|medium|low</risk-level>
+  <risk-score>0-100</risk-score>
+  <findings>
+    <finding severity="critical|high|medium|low">
+      <title>Vulnerability or issue</title>
+      <location>package@version</location>
+      <details>CVE or issue description</details>
+      <fix>Upgrade or mitigation recommendation</fix>
+    </finding>
+  </findings>
+  <remediation-checklist>
+    <item>Upgrade package X to version Y</item>
+    <item>Review dependency Z</item>
+  </remediation-checklist>
+</response>"""
+
+
+# =============================================================================
+# Built-in Templates
+# =============================================================================
+
+BUILTIN_TEMPLATES: dict[str, XmlPromptTemplate] = {
+    "security-audit": XmlPromptTemplate(
+        name="security-audit",
+        schema_version="1.0",
+        response_format=SECURITY_AUDIT_RESPONSE,
+    ),
+    "code-review": XmlPromptTemplate(
+        name="code-review",
+        schema_version="1.0",
+        response_format=CODE_REVIEW_RESPONSE,
+    ),
+    "research": XmlPromptTemplate(
+        name="research",
+        schema_version="1.0",
+        response_format=RESEARCH_RESPONSE,
+    ),
+    "bug-analysis": XmlPromptTemplate(
+        name="bug-analysis",
+        schema_version="1.0",
+        response_format=BUG_ANALYSIS_RESPONSE,
+    ),
+    "perf-audit": XmlPromptTemplate(
+        name="perf-audit",
+        schema_version="1.0",
+        response_format=PERF_AUDIT_RESPONSE,
+    ),
+    "refactor-plan": XmlPromptTemplate(
+        name="refactor-plan",
+        schema_version="1.0",
+        response_format=REFACTOR_PLAN_RESPONSE,
+    ),
+    "test-gen": XmlPromptTemplate(
+        name="test-gen",
+        schema_version="1.0",
+        response_format=TEST_GEN_RESPONSE,
+    ),
+    "doc-gen": XmlPromptTemplate(
+        name="doc-gen",
+        schema_version="1.0",
+        response_format=DOC_GEN_RESPONSE,
+    ),
+    "release-prep": XmlPromptTemplate(
+        name="release-prep",
+        schema_version="1.0",
+        response_format=RELEASE_PREP_RESPONSE,
+    ),
+    "dependency-check": XmlPromptTemplate(
+        name="dependency-check",
+        schema_version="1.0",
+        response_format=DEPENDENCY_CHECK_RESPONSE,
+    ),
+}
+
+
+def get_template(name: str) -> XmlPromptTemplate | None:
+    """Get a built-in template by name.
+
+    Args:
+        name: Template name (e.g., "security-audit", "code-review").
+
+    Returns:
+        XmlPromptTemplate if found, None otherwise.
+
+    """
+    return BUILTIN_TEMPLATES.get(name)
+
+
+def list_templates() -> list[str]:
+    """List all available built-in template names.
+
+    Returns:
+        List of template names.
+
+    """
+    return list(BUILTIN_TEMPLATES.keys())
+
+
+def register_template(name: str, template: XmlPromptTemplate) -> None:
+    """Register a custom template.
+
+    Args:
+        name: Template name for lookup.
+        template: XmlPromptTemplate instance.
+
+    """
+    BUILTIN_TEMPLATES[name] = template