hegelion 0.4.0__py3-none-any.whl

hegelion/core/logging_utils.py

@@ -0,0 +1,67 @@
+"""Structured logging utilities for Hegelion."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from typing import Any, Dict
+
+# Configure logging level from environment
+LOG_LEVEL = os.getenv("HEGELION_LOG_LEVEL", "WARNING").upper()
+
+# Create logger
+logger = logging.getLogger("hegelion")
+logger.setLevel(getattr(logging, LOG_LEVEL, logging.WARNING))
+
+
+# JSON formatter for structured logs
+class JSONFormatter(logging.Formatter):
+    """Format log records as JSON for structured logging."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_data: Dict[str, Any] = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        # Add extra fields from record
+        if hasattr(record, "extra_fields"):
+            log_data.update(record.extra_fields)
+
+        return json.dumps(log_data)
+
+
+# Setup handler if not already configured
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(JSONFormatter())
+    logger.addHandler(handler)
+
+
+def log_phase(phase: str, **kwargs: Any) -> None:
+    """Log a dialectical phase with structured data."""
+    extra = {"extra_fields": {"phase": phase, **kwargs}}
+    logger.info(f"Phase: {phase}", extra=extra)
+
+
+def log_error(error_type: str, message: str, **kwargs: Any) -> None:
+    """Log an error with structured data."""
+    extra = {"extra_fields": {"error_type": error_type, **kwargs}}
+    logger.error(message, extra=extra)
+
+
+def log_metric(metric_name: str, value: Any, **kwargs: Any) -> None:
+    """Log a metric with structured data."""
+    extra = {"extra_fields": {"metric": metric_name, "value": value, **kwargs}}
+    logger.debug(f"Metric: {metric_name}={value}", extra=extra)
+
+
+__all__ = ["logger", "log_phase", "log_error", "log_metric"]

hegelion/core/models.py

@@ -0,0 +1,293 @@
+"""Data models for Hegelion dialectical reasoning results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+class ValidationError(Exception):
+    """Raised when validation fails."""
+
+    pass
+
+
+@dataclass
+class ContradictionResult:
+    """A structured contradiction extracted during antithesis."""
+
+    description: str
+    evidence: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary format."""
+        result = {"description": self.description}
+        if self.evidence:
+            result["evidence"] = self.evidence
+        return result
+
+
+@dataclass
+class ResearchProposal:
+    """A research proposal extracted during synthesis."""
+
+    description: str
+    testable_prediction: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary format."""
+        result = {"description": self.description}
+        if self.testable_prediction:
+            result["testable_prediction"] = self.testable_prediction
+        return result
+
+
+@dataclass
+class HegelionResult:
+    """
+    Main result object for Hegelion dialectical reasoning.
+
+    This is the public API output that excludes internal conflict scoring.
+    """
+
+    query: str = None  # Default to None to fail validation if missing (as per corrected tests)
+    mode: str = "synthesis"
+    thesis: str = ""
+    antithesis: str = ""
+    synthesis: str = ""
+    contradictions: List[Dict[str, Any]] = None
+    research_proposals: List[Dict[str, Any]] = None
+    metadata: Dict[str, Any] = None
+    trace: Optional[Dict[str, Any]] = None  # Full trace including raw LLM calls
+    timestamp: Optional[str] = None
+    validation_score: Optional[float] = None
+
+    def __post_init__(self):
+        if self.contradictions is None:
+            self.contradictions = []
+        if self.research_proposals is None:
+            self.research_proposals = []
+        # metadata defaults to None as per tests
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        metadata_val = self.metadata
+        if hasattr(metadata_val, "to_dict"):
+            metadata_val = metadata_val.to_dict()
+
+        result = {
+            "query": self.query,
+            "mode": self.mode,
+            "thesis": self.thesis,
+            "antithesis": self.antithesis,
+            "synthesis": self.synthesis,
+            "contradictions": self.contradictions,
+            "research_proposals": self.research_proposals,
+            "metadata": metadata_val,
+        }
+        if self.trace is not None:
+            result["trace"] = self.trace
+        return result
+
+    def model_dump(self) -> Dict[str, Any]:
+        """Alias for to_dict to satisfy Pydantic-style tests."""
+        data = self.to_dict()
+        data["timestamp"] = self.timestamp
+        data["validation_score"] = self.validation_score
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> HegelionResult:
+        """Create a HegelionResult from a dictionary."""
+        metadata_data = data.get("metadata", {})
+        # Try to convert metadata to object if it looks like one, to satisfy tests
+        # that expect object access. But keep as dict if it fails or is empty.
+        # Note: The type hint says Dict, but tests expect object.
+        metadata_obj = metadata_data
+        if isinstance(metadata_data, dict) and "thesis_time_ms" in metadata_data:
+            try:
+                # Reconstruct HegelionMetadata
+                # We need to handle optional fields carefully
+                metadata_obj = HegelionMetadata(
+                    thesis_time_ms=metadata_data.get("thesis_time_ms", 0.0),
+                    antithesis_time_ms=metadata_data.get("antithesis_time_ms", 0.0),
+                    synthesis_time_ms=metadata_data.get("synthesis_time_ms"),
+                    total_time_ms=metadata_data.get("total_time_ms", 0.0),
+                    backend_provider=metadata_data.get("backend_provider"),
+                    backend_model=metadata_data.get("backend_model"),
+                    debug=metadata_data.get("debug"),
+                )
+            except Exception:
+                pass
+
+        return cls(
+            query=data.get("query", ""),
+            mode=data.get("mode", "synthesis"),
+            thesis=data.get("thesis", ""),
+            antithesis=data.get("antithesis", ""),
+            synthesis=data.get("synthesis", ""),
+            contradictions=data.get("contradictions", []),
+            research_proposals=data.get("research_proposals", []),
+            metadata=metadata_obj,
+            trace=data.get("trace"),
+            timestamp=data.get("timestamp"),
+            validation_score=data.get("validation_score"),
+        )
+
+
+@dataclass
+class HegelionTrace:
+    """Complete dialectical trace for debugging and analysis."""
+
+    thesis: str
+    antithesis: str
+    synthesis: Optional[str]
+    contradictions_found: int
+    research_proposals: List[str]
+    internal_conflict_score: Optional[float] = None  # Internal use only
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "thesis": self.thesis,
+            "antithesis": self.antithesis,
+            "synthesis": self.synthesis,
+            "contradictions_found": self.contradictions_found,
+            "research_proposals": self.research_proposals,
+        }
+        # Only include conflict score in debug mode
+        if self.internal_conflict_score is not None:
+            result["internal_conflict_score"] = self.internal_conflict_score
+        return result
+
+
+@dataclass
+class HegelionMetadata:
+    """Metadata about Hegelion execution."""
+
+    thesis_time_ms: float
+    antithesis_time_ms: float
+    synthesis_time_ms: Optional[float]
+    total_time_ms: float
+    backend_provider: Optional[str] = None
+    backend_model: Optional[str] = None
+    debug: Optional[Dict[str, Any]] = None  # Debug information including internal scores
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "thesis_time_ms": self.thesis_time_ms,
+            "antithesis_time_ms": self.antithesis_time_ms,
+            "synthesis_time_ms": self.synthesis_time_ms,
+            "total_time_ms": self.total_time_ms,
+        }
+        if self.backend_provider:
+            result["backend_provider"] = self.backend_provider
+        if self.backend_model:
+            result["backend_model"] = self.backend_model
+        if self.debug:
+            result["debug"] = self.debug
+        return result
+
+
+# Legacy output model (for backward compatibility, but deprecated)
+class HegelionOutput:
+    """
+    Legacy output model that includes conflict_score.
+
+    DEPRECATED: Use HegelionResult instead. This class is maintained for backward compatibility
+    but should not be used in new code.
+    """
+
+    def __init__(
+        self,
+        result: str,
+        mode: str,
+        conflict_score: float,
+        trace: HegelionTrace,
+        metadata: HegelionMetadata,
+    ):
+        self.result = result
+        self.mode = mode
+        self.conflict_score = conflict_score  # This field is deprecated
+        self.trace = trace
+        self.metadata = metadata
+
+    def to_hegelion_result(self, include_debug_conflict_score: bool = False) -> HegelionResult:
+        """Convert to the new HegelionResult format."""
+        debug_info = None
+        if include_debug_conflict_score:
+            debug_info = {"internal_conflict_score": self.conflict_score}
+
+        # Convert contradictions to structured format
+        contradictions = []
+        for i, contr_desc in enumerate(
+            self.trace.research_proposals[: self.trace.contradictions_found]
+        ):
+            contradictions.append({"description": contr_desc})
+
+        return HegelionResult(
+            query="",  # Not available in legacy format
+            mode=self.mode,
+            thesis=self.trace.thesis,
+            antithesis=self.trace.antithesis,
+            synthesis=self.trace.synthesis or "",
+            contradictions=contradictions,
+            research_proposals=[{"description": rp} for rp in self.trace.research_proposals],
+            metadata={
+                "thesis_time_ms": self.metadata.thesis_time_ms,
+                "antithesis_time_ms": self.metadata.antithesis_time_ms,
+                "synthesis_time_ms": self.metadata.synthesis_time_ms,
+                "total_time_ms": self.metadata.total_time_ms,
+                "debug": debug_info,
+            },
+            trace=self.trace.to_dict(),
+        )
+
+
+# Backwards compatibility alias (older tests / code expect DialecticOutput)
+# DialecticOutput used to be the public name — map it to the current HegelionResult
+DialecticOutput = HegelionResult
+
+
+@dataclass
+class PromptWorkflow:
+    query: str
+    thesis: str
+    antithesis: str
+    synthesis: str
+    instructions: Optional[str] = None
+
+    def model_dump(self) -> Dict[str, Any]:
+        return {
+            "query": self.query,
+            "thesis": self.thesis,
+            "antithesis": self.antithesis,
+            "synthesis": self.synthesis,
+            "instructions": self.instructions,
+        }
+
+
+@dataclass
+class WorkflowResult:
+    workflow: Dict[str, Any]
+    results: List[Dict[str, Any]]
+
+    def model_dump(self) -> Dict[str, Any]:
+        return {
+            "workflow": self.workflow,
+            "results": self.results,
+        }
+
+
+@dataclass
+class ResultMetadata:
+    source: str
+    confidence: str
+    tags: List[str]
+
+
+@dataclass
+class ConfidenceScore:
+    score: float
+    reasoning: str

hegelion/core/parsing.py

@@ -0,0 +1,271 @@
+"""Parsing utilities for Hegelion dialectical reasoning."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import List, Optional
+
+
+def parse_contradiction_header(text: str) -> Optional[str]:
+    """Parse a contradiction header line and extract the description.
+
+    Supports variations:
+    - CONTRADICTION: description
+    - **CONTRADICTION**: description
+    - **CONTRADICTION:** description
+    - Contradiction 1: description
+    - contradiction: description (case insensitive)
+    """
+    colon_index = text.find(":")
+    if colon_index == -1:
+        return None
+
+    # Strip markdown from the prefix only
+    prefix = text[:colon_index].strip()
+
+    # Remove leading and trailing markdown markers from the prefix
+    for marker in ["**", "__", "*", "_"]:
+        if prefix.startswith(marker):
+            prefix = prefix[len(marker) :].strip()
+        if prefix.endswith(marker):
+            prefix = prefix[: -len(marker)].strip()
+
+    prefix = prefix.upper()
+
+    # Remove numbering (e.g., "CONTRADICTION 1" -> "CONTRADICTION")
+    prefix_parts = prefix.split()
+    if prefix_parts and prefix_parts[0] == "CONTRADICTION":
+        # Valid contradiction header
+        detail = text[colon_index + 1 :].strip() or "Unspecified contradiction"
+
+        # Strip markdown from the description as well
+        for marker in ["**", "__", "*", "_"]:
+            if detail.startswith(marker):
+                detail = detail[len(marker) :].strip()
+                break
+
+        return detail
+
+    return None
+
+
+def strip_markdown_wrappers(text: str) -> str:
+    """Remove markdown formatting wrappers like **, __, *, _ from text."""
+    trimmed = text.strip()
+    if not trimmed:
+        return ""
+    markers = ("**", "__", "*", "_")
+    changed = True
+    while changed and trimmed:
+        changed = False
+        for marker in markers:
+            if (
+                trimmed.startswith(marker)
+                and trimmed.endswith(marker)
+                and len(trimmed) > 2 * len(marker)
+            ):
+                trimmed = trimmed[len(marker) : -len(marker)].strip()
+                changed = True
+    return trimmed
+
+
+def extract_contradictions(text: str) -> List[str]:
+    """Extract structured contradictions from antithesis text.
+
+    Supports formats:
+    CONTRADICTION: [description]
+    EVIDENCE: [supporting evidence]
+    **CONTRADICTION**: [description]  (markdown)
+    Contradiction 1: [description]    (numbered)
+
+    Handles multiline evidence by accumulating lines until next CONTRADICTION.
+    """
+    contradictions: List[str] = []
+    pending: Optional[str] = None
+    evidence_buffer: List[str] = []
+
+    for raw_line in text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped:
+            continue
+
+        cleaned = strip_markdown_wrappers(stripped)
+        if not cleaned:
+            continue
+
+        # Check if this is a new contradiction header
+        header = parse_contradiction_header(cleaned)
+        if header:
+            # Save previous contradiction with accumulated evidence
+            if pending:
+                if evidence_buffer:
+                    combined_evidence = " ".join(evidence_buffer).strip()
+                    contradictions.append(f"{pending} — {combined_evidence}")
+                else:
+                    contradictions.append(pending)
+                evidence_buffer = []
+            pending = header
+            continue
+
+        if not pending:
+            continue
+
+        # Check if this is evidence
+        normalized = cleaned.upper()
+        if normalized.startswith("EVIDENCE"):
+            # Extract evidence text after colon
+            evidence_line = cleaned.split(":", 1)[1].strip() if ":" in cleaned else cleaned
+            if evidence_line:
+                evidence_buffer.append(evidence_line)
+        elif evidence_buffer:
+            # Continuation of evidence (multiline)
+            evidence_buffer.append(cleaned)
+
+    # Save final pending contradiction
+    if pending:
+        if evidence_buffer:
+            combined_evidence = " ".join(evidence_buffer).strip()
+            contradictions.append(f"{pending} — {combined_evidence}")
+        else:
+            contradictions.append(pending)
+
+    return contradictions
+
+
+def extract_research_proposals(text: str) -> List[str]:
+    """Extract research proposals from synthesis text.
+
+    Supports formats:
+    - RESEARCH_PROPOSAL: [description]
+    - TESTABLE_PREDICTION: [falsifiable claim]
+    - PREDICTION 1: [claim]  (numbered)
+    - TEST_PREDICTION: [claim]  (variations)
+
+    Handles multiline predictions by accumulating until next header.
+    """
+    proposals: List[str] = []
+    current: Optional[str] = None
+    prediction_buffer: List[str] = []
+
+    def _is_research_header(upper_line: str) -> bool:
+        """Check if line is a research proposal header."""
+        return upper_line.startswith("RESEARCH_PROPOSAL:") or upper_line.startswith(
+            "RESEARCH PROPOSAL:"
+        )
+
+    def _is_prediction_header(upper_line: str) -> bool:
+        """Check if line is a prediction header (with variations)."""
+        # Match: TESTABLE_PREDICTION, TESTABLE PREDICTION, TEST_PREDICTION,
+        # PREDICTION 1, PREDICTION:, etc.
+        if upper_line.startswith("TESTABLE") and "PREDICTION" in upper_line:
+            return True
+        if upper_line.startswith("TEST") and "PREDICTION" in upper_line:
+            return True
+        # Handle numbered predictions: "PREDICTION 1:", "PREDICTION 2:", etc.
+        if re.match(r"PREDICTION\s*\d*\s*:", upper_line):
+            return True
+        return False
+
+    for line in text.splitlines():
+        normalized = line.strip()
+        if not normalized:
+            continue
+
+        cleaned = strip_markdown_wrappers(normalized)
+        upper = cleaned.upper()
+
+        # New research proposal header: flush previous
+        if _is_research_header(upper):
+            # Flush any existing current proposal
+            if current:
+                if prediction_buffer:
+                    combined_pred = " ".join(prediction_buffer).strip()
+                    proposals.append(f"{current} | Prediction: {combined_pred}")
+                else:
+                    proposals.append(current)
+            elif prediction_buffer:
+                # Standalone prediction before a new proposal
+                combined_pred = " ".join(prediction_buffer).strip()
+                proposals.append(f"Prediction: {combined_pred}")
+
+            # Start new proposal
+            current = cleaned.split(":", 1)[1].strip() if ":" in cleaned else cleaned
+            prediction_buffer = []
+            continue
+
+        # Prediction header: start/replace prediction buffer
+        if _is_prediction_header(upper):
+            # If we have a current proposal, attach the prediction to it (don't flush yet)
+            # If we have a standalone prediction buffer, flush it first
+            if current is None and prediction_buffer:
+                # Flush standalone prediction before starting new one
+                combined_prev = " ".join(prediction_buffer).strip()
+                if combined_prev:
+                    proposals.append(f"Prediction: {combined_prev}")
+                prediction_buffer = []
+
+            # Start new prediction (will be attached to current proposal if exists)
+            prediction_text = cleaned.split(":", 1)[1].strip() if ":" in cleaned else ""
+            if prediction_text:
+                prediction_buffer = [prediction_text]
+            continue
+
+        # Continuation for multiline prediction
+        if prediction_buffer and cleaned:
+            prediction_buffer.append(cleaned)
+
+    # Flush tail
+    if current:
+        if prediction_buffer:
+            combined_pred = " ".join(prediction_buffer).strip()
+            proposals.append(f"{current} | Prediction: {combined_pred}")
+        else:
+            proposals.append(current)
+    elif prediction_buffer:
+        combined_pred = " ".join(prediction_buffer).strip()
+        proposals.append(f"Prediction: {combined_pred}")
+
+    return proposals
+
+
+def parse_conflict_value(response: str) -> float:
+    """Parse a conflict value from LLM response JSON."""
+    if not response:
+        return 0.0
+    candidates = [response.strip()]
+    candidates.extend(re.findall(r"\{.*?\}", response, flags=re.DOTALL))
+    for candidate in candidates:
+        try:
+            data = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        conflict_value = data.get("conflict")
+        try:
+            value = float(conflict_value)
+        except (TypeError, ValueError):
+            continue
+        return float(max(0.0, min(1.0, value)))
+    return 0.0
+
+
+def conclusion_excerpt(text: str, max_paragraphs: int = 2, max_chars: int = 1500) -> str:
+    """Extract a conclusion excerpt from text for conflict analysis."""
+    paragraphs = [segment.strip() for segment in text.split("\n\n") if segment.strip()]
+    if not paragraphs:
+        excerpt = text.strip()
+    else:
+        excerpt = "\n\n".join(paragraphs[-max_paragraphs:])
+    if len(excerpt) > max_chars:
+        return excerpt[-max_chars:]
+    return excerpt
+
+
+__all__ = [
+    "extract_contradictions",
+    "extract_research_proposals",
+    "parse_conflict_value",
+    "conclusion_excerpt",
+    "parse_contradiction_header",
+    "strip_markdown_wrappers",
+]