hegelion 0.4.0__py3-none-any.whl

hegelion/__init__.py

@@ -0,0 +1,45 @@
+"""
+Hegelion: Dialectical Reasoning Harness for LLMs
+
+A Python package that generates structured thesis-antithesis-synthesis responses
+using Large Language Models, making reasoning patterns and contradictions explicit.
+"""
+
+from .core.core import (
+    run_dialectic,
+    run_benchmark,
+    run_dialectic_sync,
+    run_benchmark_sync,
+    dialectic,
+    quickstart,
+    dialectic_sync,
+    quickstart_sync,
+)
+from .core.models import HegelionResult
+from .training.datasets import export_training_data, to_dpo_dataset, to_instruction_tuning_dataset
+from .core.agent import HegelionAgent
+from .core.autocoding_state import AutocodingState
+from .core.prompt_autocoding import AutocodingPrompt, PromptDrivenAutocoding
+
+__version__ = "0.4.0"
+__author__ = "Hegelion Contributors"
+
+__all__ = [
+    "run_dialectic",
+    "run_benchmark",
+    "run_dialectic_sync",
+    "run_benchmark_sync",
+    "dialectic",
+    "quickstart",
+    "dialectic_sync",
+    "quickstart_sync",
+    "HegelionResult",
+    "HegelionAgent",
+    "to_dpo_dataset",
+    "to_instruction_tuning_dataset",
+    "export_training_data",
+    # Autocoding (g3-style coach-player loop)
+    "AutocodingState",
+    "AutocodingPrompt",
+    "PromptDrivenAutocoding",
+]

hegelion/core/__init__.py

@@ -0,0 +1,29 @@
+from .core import (
+    run_dialectic,
+    run_benchmark,
+    run_dialectic_sync,
+    run_benchmark_sync,
+    dialectic,
+    quickstart,
+    dialectic_sync,
+    quickstart_sync,
+)
+from .models import HegelionResult
+from .agent import HegelionAgent
+from .config import get_config, set_config_value, ConfigurationError
+
+__all__ = [
+    "run_dialectic",
+    "run_benchmark",
+    "run_dialectic_sync",
+    "run_benchmark_sync",
+    "dialectic",
+    "quickstart",
+    "dialectic_sync",
+    "quickstart_sync",
+    "HegelionResult",
+    "HegelionAgent",
+    "get_config",
+    "set_config_value",
+    "ConfigurationError",
+]

hegelion/core/agent.py

@@ -0,0 +1,166 @@
+"""Agent helpers for using Hegelion inside reflexive/action loops."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, List, Optional, Union
+
+from .backends import LLMBackend
+from .core import run_dialectic, run_dialectic_sync
+from .models import HegelionResult
+from .personas import Persona
+
+# Extract the actionable move from a synthesized answer.
+ActionExtractor = Callable[[HegelionResult], str]
+
+
+def default_action_extractor(result: HegelionResult) -> str:
+    """
+    Pull a concrete action line from the synthesis when present.
+
+    Falls back to returning the entire synthesis when no explicit action is
+    detected. This keeps the agent usable with existing prompts while still
+    preferring concise commands when the model provides them.
+    """
+
+    for line in result.synthesis.splitlines():
+        lowered = line.strip().lower()
+        if lowered.startswith(("action:", "next action:", "next_action:", "do:", "action ->")):
+            # Preserve the original casing of the action line for readability.
+            return line.split(":", 1)[1].strip() if ":" in line else line.strip()
+    return result.synthesis.strip()
+
+
+@dataclass
+class AgentStep:
+    """Container for a single agent turn."""
+
+    observation: str
+    result: HegelionResult
+    action: str
+
+    def to_dict(self) -> dict:
+        """Serialize to a plain dict (handy for logging)."""
+
+        return {
+            "observation": self.observation,
+            "action": self.action,
+            "result": self.result.to_dict(),
+        }
+
+
+class HegelionAgent:
+    """
+    Lightweight wrapper that runs the dialectic before acting.
+
+    Useful for Reflexion-style agents: the agent critiques its own plan
+    (thesis → antithesis) and only acts on the synthesized recommendation.
+    """
+
+    def __init__(
+        self,
+        *,
+        goal: Optional[str] = None,
+        backend: Optional[LLMBackend] = None,
+        model: Optional[str] = None,
+        personas: Optional[Union[List[Persona], str]] = None,
+        iterations: int = 1,
+        use_search: bool = False,
+        debug: bool = False,
+        action_extractor: Optional[ActionExtractor] = None,
+        action_guidance: Optional[str] = None,
+    ) -> None:
+        self.goal = goal
+        self.backend = backend
+        self.model = model
+        self.personas = personas
+        self.iterations = iterations
+        self.use_search = use_search
+        self.debug = debug
+        self._action_extractor = action_extractor or default_action_extractor
+        self.action_guidance = action_guidance
+        self.history: List[AgentStep] = []
+
+    @classmethod
+    def for_coding(
+        cls,
+        goal: Optional[str] = None,
+        **kwargs,
+    ) -> "HegelionAgent":
+        """
+        Convenience constructor tuned for coding agents.
+
+        Adds guidance that nudges the dialectic toward concrete edits, tests, and
+        verification steps to reduce hallucinations in code suggestions.
+        """
+
+        guidance = (
+            "Focus on code changes, tests, and reproducible commands. Prefer minimal"
+            " diffs, name exact files, and include validation steps. Reject actions"
+            " that rely on unverified APIs or assumptions."
+        )
+        return cls(goal=goal, action_guidance=guidance, **kwargs)
+
+    def _build_query(self, observation: str) -> str:
+        """Shape the agent observation into a dialectic-friendly query."""
+
+        parts = []
+        if self.goal:
+            parts.append(f"Goal: {self.goal}")
+        parts.append(f"Observation: {observation}")
+        if self.action_guidance:
+            parts.append(f"Context: {self.action_guidance}")
+        parts.append(
+            "Run a full thesis → antithesis → synthesis pass on the next step."
+            " The antithesis must adversarially attack hallucinations, unverifiable"
+            " claims, and risky assumptions. The synthesis should propose a single"
+            " concrete, testable action that survives critique and lists any checks"
+            " needed to de-risk it. Return the action first, then the reasoning."
+        )
+        return "\n\n".join(parts)
+
+    async def deliberate(self, observation: str) -> HegelionResult:
+        """Run the full dialectic for an observation and return the result."""
+
+        query = self._build_query(observation)
+        return await run_dialectic(
+            query,
+            debug=self.debug,
+            backend=self.backend,
+            model=self.model,
+            personas=self.personas,
+            iterations=self.iterations,
+            use_search=self.use_search,
+        )
+
+    async def act(self, observation: str) -> AgentStep:
+        """Deliberate, extract an action, record it, and return the step."""
+
+        result = await self.deliberate(observation)
+        action = self._action_extractor(result)
+        step = AgentStep(observation=observation, result=result, action=action)
+        self.history.append(step)
+        return step
+
+    def act_sync(self, observation: str) -> AgentStep:
+        """Synchronous convenience wrapper around ``act``."""
+
+        query = self._build_query(observation)
+        result = run_dialectic_sync(
+            query,
+            debug=self.debug,
+            backend=self.backend,
+            model=self.model,
+            personas=self.personas,
+            iterations=self.iterations,
+            use_search=self.use_search,
+        )
+        action = self._action_extractor(result)
+        step = AgentStep(observation=observation, result=result, action=action)
+        self.history.append(step)
+        return step
+
+    def reset_history(self) -> None:
+        """Clear stored agent turns."""
+
+        self.history.clear()

hegelion/core/autocoding_state.py

@@ -0,0 +1,293 @@
+"""State management for dialectical autocoding sessions.
+
+This module provides stateless state management for the coach-player
+autocoding loop based on the g3 paper's adversarial cooperation paradigm.
+State is passed explicitly between tool calls to maintain fresh context each turn.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class AutocodingState:
+    """State for a dialectical autocoding session.
+
+    This state is passed explicitly between tool calls, enabling fresh
+    context each turn while maintaining session continuity.
+
+    Attributes:
+        session_id: Unique identifier for this autocoding session.
+        requirements: The requirements document (source of truth).
+        current_turn: Current turn number (0-indexed).
+        max_turns: Maximum turns before timeout.
+        phase: Current phase - init | player | coach | approved | timeout.
+        status: Session status - active | approved | rejected | timeout.
+        turn_history: List of turn records with feedback and scores.
+        last_coach_feedback: Most recent coach feedback for player context.
+        quality_scores: List of compliance scores from each coach turn.
+        approval_threshold: Minimum score threshold for approval (0-1).
+    """
+
+    session_id: str
+    requirements: str
+    current_turn: int = 0
+    max_turns: int = 10
+    phase: str = "init"
+    status: str = "active"
+    turn_history: List[Dict[str, Any]] = field(default_factory=list)
+    last_coach_feedback: Optional[str] = None
+    quality_scores: List[float] = field(default_factory=list)
+    approval_threshold: float = 0.9
+
+    def __post_init__(self) -> None:
+        """Validate state after initialization."""
+        valid_phases = {"init", "player", "coach", "approved", "timeout"}
+        valid_statuses = {"active", "approved", "rejected", "timeout"}
+
+        if self.phase not in valid_phases:
+            raise ValueError(f"Invalid phase: {self.phase}. Must be one of {valid_phases}")
+        if self.status not in valid_statuses:
+            raise ValueError(f"Invalid status: {self.status}. Must be one of {valid_statuses}")
+        if not 0 <= self.approval_threshold <= 1:
+            raise ValueError(f"approval_threshold must be 0-1, got {self.approval_threshold}")
+
+    @classmethod
+    def create(
+        cls,
+        requirements: str,
+        max_turns: int = 10,
+        approval_threshold: float = 0.9,
+    ) -> "AutocodingState":
+        """Create a new autocoding session.
+
+        Args:
+            requirements: The requirements document (source of truth).
+            max_turns: Maximum turns before timeout.
+            approval_threshold: Minimum score threshold for approval.
+
+        Returns:
+            A new AutocodingState ready for the first player turn.
+        """
+        return cls(
+            session_id=str(uuid.uuid4()),
+            requirements=requirements,
+            max_turns=max_turns,
+            approval_threshold=approval_threshold,
+            phase="player",  # Start with player phase
+            status="active",
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize state to a dictionary for MCP transport.
+
+        Returns:
+            Dictionary representation of the state.
+        """
+        return {
+            "session_id": self.session_id,
+            "requirements": self.requirements,
+            "current_turn": self.current_turn,
+            "max_turns": self.max_turns,
+            "phase": self.phase,
+            "status": self.status,
+            "turn_history": self.turn_history,
+            "last_coach_feedback": self.last_coach_feedback,
+            "quality_scores": self.quality_scores,
+            "approval_threshold": self.approval_threshold,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AutocodingState":
+        """Deserialize state from a dictionary.
+
+        Args:
+            data: Dictionary representation of the state.
+
+        Returns:
+            Reconstructed AutocodingState.
+        """
+        return cls(
+            session_id=data["session_id"],
+            requirements=data["requirements"],
+            current_turn=data.get("current_turn", 0),
+            max_turns=data.get("max_turns", 10),
+            phase=data.get("phase", "init"),
+            status=data.get("status", "active"),
+            turn_history=data.get("turn_history", []),
+            last_coach_feedback=data.get("last_coach_feedback"),
+            quality_scores=data.get("quality_scores", []),
+            approval_threshold=data.get("approval_threshold", 0.9),
+        )
+
+    def advance_to_coach(self) -> "AutocodingState":
+        """Advance state from player phase to coach phase.
+
+        Returns:
+            New state with coach phase active.
+
+        Raises:
+            ValueError: If not in player phase or session not active.
+        """
+        if self.phase != "player":
+            raise ValueError(f"Cannot advance to coach from phase: {self.phase}")
+        if self.status != "active":
+            raise ValueError(f"Cannot advance: session status is {self.status}")
+
+        return AutocodingState(
+            session_id=self.session_id,
+            requirements=self.requirements,
+            current_turn=self.current_turn,
+            max_turns=self.max_turns,
+            phase="coach",
+            status="active",
+            turn_history=self.turn_history.copy(),
+            last_coach_feedback=self.last_coach_feedback,
+            quality_scores=self.quality_scores.copy(),
+            approval_threshold=self.approval_threshold,
+        )
+
+    def advance_turn(
+        self,
+        coach_feedback: str,
+        approved: bool,
+        compliance_score: Optional[float] = None,
+    ) -> "AutocodingState":
+        """Advance state after coach review.
+
+        Args:
+            coach_feedback: Feedback from the coach agent.
+            approved: Whether the coach approved the implementation.
+            compliance_score: Optional compliance score (0-1).
+
+        Returns:
+            New state with updated turn, feedback, and status.
+        """
+        if self.phase != "coach":
+            raise ValueError(f"Cannot advance turn from phase: {self.phase}")
+
+        new_turn = self.current_turn + 1
+        new_history = self.turn_history.copy()
+        new_scores = self.quality_scores.copy()
+
+        # Record turn history
+        turn_record = {
+            "turn": self.current_turn,
+            "feedback": coach_feedback,
+            "approved": approved,
+            "score": compliance_score,
+        }
+        new_history.append(turn_record)
+
+        if compliance_score is not None:
+            new_scores.append(compliance_score)
+
+        # Determine next phase and status
+        if approved:
+            new_phase = "approved"
+            new_status = "approved"
+        elif new_turn >= self.max_turns:
+            new_phase = "timeout"
+            new_status = "timeout"
+        else:
+            new_phase = "player"
+            new_status = "active"
+
+        return AutocodingState(
+            session_id=self.session_id,
+            requirements=self.requirements,
+            current_turn=new_turn,
+            max_turns=self.max_turns,
+            phase=new_phase,
+            status=new_status,
+            turn_history=new_history,
+            last_coach_feedback=coach_feedback,
+            quality_scores=new_scores,
+            approval_threshold=self.approval_threshold,
+        )
+
+    def is_complete(self) -> bool:
+        """Check if the session has completed (approved or timeout).
+
+        Returns:
+            True if session is no longer active.
+        """
+        return self.status in {"approved", "rejected", "timeout"}
+
+    def turns_remaining(self) -> int:
+        """Get the number of turns remaining.
+
+        Returns:
+            Number of turns left before timeout.
+        """
+        return max(0, self.max_turns - self.current_turn)
+
+    def average_score(self) -> Optional[float]:
+        """Calculate average compliance score across turns.
+
+        Returns:
+            Average score, or None if no scores recorded.
+        """
+        if not self.quality_scores:
+            return None
+        return sum(self.quality_scores) / len(self.quality_scores)
+
+    def summary(self) -> str:
+        """Generate a human-readable summary of session state.
+
+        Returns:
+            Summary string for display.
+        """
+        avg_score = self.average_score()
+        score_str = f"{avg_score:.1%}" if avg_score is not None else "N/A"
+
+        return (
+            f"Session: {self.session_id[:8]}...\n"
+            f"Turn: {self.current_turn + 1}/{self.max_turns}\n"
+            f"Phase: {self.phase}\n"
+            f"Status: {self.status}\n"
+            f"Avg Score: {score_str}"
+        )
+
+
+def save_session(state: AutocodingState, filepath: str) -> None:
+    """Save an autocoding session to a JSON file.
+
+    Args:
+        state: The AutocodingState to save.
+        filepath: Path to save the session JSON file.
+    """
+    path = Path(filepath)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(path, "w") as f:
+        json.dump(state.to_dict(), f, indent=2)
+
+
+def load_session(filepath: str) -> AutocodingState:
+    """Load an autocoding session from a JSON file.
+
+    Args:
+        filepath: Path to the session JSON file to load.
+
+    Returns:
+        Reconstructed AutocodingState.
+
+    Raises:
+        FileNotFoundError: If the session file doesn't exist.
+        json.JSONDecodeError: If the file is not valid JSON.
+        ValueError: If the JSON doesn't contain valid session data.
+    """
+    path = Path(filepath)
+    if not path.exists():
+        raise FileNotFoundError(f"Session file not found: {filepath}")
+
+    with open(path, "r") as f:
+        data = json.load(f)
+
+    return AutocodingState.from_dict(data)