hegelion 0.4.0__py3-none-any.whl

hegelion/scripts/hegelion_eval.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+"""Evaluation CLI for comparing Hegelion benchmark runs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+if __package__ is None or __package__ == "":  # pragma: no cover - direct execution fallback
+    import sys
+
+    sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from hegelion import HegelionResult
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Compare multiple Hegelion benchmark runs and generate a report."
+    )
+    parser.add_argument(
+        "results_files",
+        type=Path,
+        nargs="+",
+        help="Paths to one or more Hegelion JSONL results files.",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Optional path to write the comparison report in Markdown format.",
+    )
+    return parser
+
+
+def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
+    return build_parser().parse_args(argv)
+
+
+def load_results(path: Path) -> List[HegelionResult]:
+    """Load Hegelion results from a JSONL file."""
+    results = []
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            data = json.loads(line)
+            results.append(HegelionResult(**data))
+    return results
+
+
+def analyze_results(results: List[HegelionResult]) -> Dict[str, Any]:
+    """Calculate aggregate metrics for a list of results."""
+    if not results:
+        return {}
+
+    total_queries = len(results)
+    total_contradictions = sum(len(r.contradictions) for r in results)
+    total_proposals = sum(len(r.research_proposals) for r in results)
+    total_time = sum(r.metadata.get("total_time_ms", 0) for r in results)
+
+    conflict_scores = []
+    for r in results:
+        debug = r.metadata.get("debug", {})
+        if debug and "internal_conflict_score" in debug:
+            conflict_scores.append(debug["internal_conflict_score"])
+
+    avg_conflict_score = sum(conflict_scores) / len(conflict_scores) if conflict_scores else None
+
+    return {
+        "model": results[0].metadata.get("backend_model", "Unknown"),
+        "total_queries": total_queries,
+        "avg_contradictions": total_contradictions / total_queries,
+        "avg_proposals": total_proposals / total_queries,
+        "avg_time_ms": total_time / total_queries,
+        "avg_conflict_score": avg_conflict_score,
+    }
+
+
+def generate_report(analysis: List[Dict[str, Any]]) -> str:
+    """Generate a Markdown report from the analysis."""
+    report = ["# Hegelion Evaluation Report", ""]
+
+    # Summary Table
+    report.append("## Summary")
+    report.append(
+        "| Model | Queries | Avg. Contradictions | Avg. Proposals | Avg. Time (ms) | Avg. Conflict Score |"
+    )
+    report.append(
+        "|-------|---------|---------------------|----------------|----------------|---------------------|"
+    )
+    for stats in analysis:
+        conflict_score_str = (
+            f"{stats['avg_conflict_score']:.3f}"
+            if stats["avg_conflict_score"] is not None
+            else "N/A"
+        )
+        report.append(
+            f"| {stats['model']} | {stats['total_queries']} | {stats['avg_contradictions']:.2f} | "
+            f"{stats['avg_proposals']:.2f} | {stats['avg_time_ms']:.0f} | {conflict_score_str} |"
+        )
+    report.append("")
+
+    return "\n".join(report)
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    args = parse_args(argv)
+
+    all_analysis = []
+    for results_file in args.results_files:
+        if not results_file.exists():
+            print(f"Error: File not found: {results_file}", file=sys.stderr)
+            continue
+
+        results = load_results(results_file)
+        if not results:
+            print(f"Warning: No results found in: {results_file}", file=sys.stderr)
+            continue
+
+        analysis = analyze_results(results)
+        all_analysis.append(analysis)
+
+    report = generate_report(all_analysis)
+
+    if args.output:
+        args.output.write_text(report, encoding="utf-8")
+        print(f"Report written to {args.output}")
+    else:
+        print(report)
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entrypoint
+    main()

hegelion/scripts/mcp_setup.py

@@ -0,0 +1,150 @@
+"""Hegelion MCP Setup Logic and CLI helper."""
+
+import sys
+import json
+import site
+from pathlib import Path
+import hegelion
+
+
+USAGE_NOTE = """
+Hegelion MCP setup
+------------------
+Use this helper to generate the MCP snippet for Cursor / Claude Desktop.
+
+Examples:
+  hegelion-setup-mcp                # print JSON snippet
+  hegelion-setup-mcp --write        # write to ./mcp_config.json
+  hegelion-setup-mcp --write "$HOME/Library/Application Support/Claude/claude_desktop_config.json"  # macOS Claude Desktop
+
+Note: After modifying the config, quit and reopen Claude Desktop for changes to take effect.
+"""
+
+
+def get_python_path():
+    """Get the absolute path to the current python interpreter."""
+    return sys.executable
+
+
+def is_installed_in_site_packages():
+    """Check if hegelion is installed in site-packages."""
+    package_path = Path(hegelion.__file__).parent
+    for site_package in site.getsitepackages():
+        if str(package_path).startswith(site_package):
+            return True
+    # Also check user site packages
+    if site.getusersitepackages() and str(package_path).startswith(site.getusersitepackages()):
+        return True
+    return False
+
+
+def get_project_root():
+    """Get the absolute path to the project root (if running from source)."""
+    return Path(hegelion.__file__).parent.parent.absolute()
+
+
+def generate_config(python_path, project_root, is_installed):
+    """Generate the MCP config."""
+
+    env = {}
+    if not is_installed:
+        # If not installed in site-packages, we likely need PYTHONPATH
+        env["PYTHONPATH"] = str(project_root)
+
+    config = {
+        "mcpServers": {
+            "hegelion": {
+                "command": python_path,
+                "args": ["-m", "hegelion.mcp.server"],
+            },
+        }
+    }
+
+    if env:
+        config["mcpServers"]["hegelion"]["env"] = env
+
+    return config
+
+
+def print_setup_instructions(dry_run=False):
+    python_path = get_python_path()
+    is_installed = is_installed_in_site_packages()
+    project_root = get_project_root()
+
+    config = generate_config(python_path, project_root, is_installed)
+
+    snippet = config["mcpServers"]
+    json_output = json.dumps(snippet, indent=2)
+
+    print("\n" + "=" * 60)
+    print("MCP CONFIGURATION SNIPPET")
+    print("=" * 60)
+    print("Copy the snippet below into your 'Global MCP Settings' (Cursor)")
+    print("or your MCP configuration file:")
+    print("-" * 60)
+    print(json_output)
+    print("-" * 60)
+
+    print(
+        "Tools available: dialectical_workflow, dialectical_single_shot, thesis_prompt, antithesis_prompt, synthesis_prompt"
+    )
+    print("response_style options: json, sections, synthesis_only")
+    print("\nCommon config paths:")
+    print("  macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json")
+    print("  Cursor:               ~/.cursor/mcp_config.json")
+    print("  Windsurf:             ~/.codeium/windsurf/mcp_config.json")
+    print("\n⚠️  Restart Required: Quit and reopen Claude Desktop after modifying the config.")
+
+    if not is_installed:
+        print(f"\nNOTE: Detected source installation at {project_root}")
+        print("Added PYTHONPATH to ensure the server runs correctly.")
+    else:
+        print("\nNOTE: Detected installed package.")
+
+
+def _write_config(target: Path, snippet: dict) -> None:
+    target = target.expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists():
+        existing = {}
+        try:
+            existing = json.loads(target.read_text(encoding="utf-8"))
+        except Exception:
+            existing = {}
+        merged = existing.get("mcpServers", {})
+        merged.update(snippet)
+        payload = {"mcpServers": merged, **{k: v for k, v in existing.items() if k != "mcpServers"}}
+    else:
+        payload = {"mcpServers": snippet}
+    target.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    print(f"Wrote MCP config to {target}")
+
+
+def main(argv=None):  # pragma: no cover - lightweight CLI
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Generate MCP config for Hegelion", epilog=USAGE_NOTE
+    )
+    parser.add_argument(
+        "--write",
+        nargs="?",
+        const="mcp_config.json",
+        help="Write to path (default: mcp_config.json in CWD)",
+    )
+    args = parser.parse_args(argv)
+
+    python_path = get_python_path()
+    is_installed = is_installed_in_site_packages()
+    project_root = get_project_root()
+    config = generate_config(python_path, project_root, is_installed)
+    snippet = config["mcpServers"]
+
+    if args.write:
+        _write_config(Path(args.write), snippet)
+    else:
+        print_setup_instructions()
+
+
+if __name__ == "__main__":
+    main()

hegelion/search_providers.py

@@ -0,0 +1,151 @@
+"""Search providers for grounding antithesis with real-world information."""
+
+from __future__ import annotations
+
+import os
+import logging
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class SearchProvider(ABC):
+    """Abstract base class for search providers."""
+
+    @abstractmethod
+    async def search(self, query: str, max_results: int = 5) -> List[str]:
+        """Search for context snippets related to the query.
+
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+
+        Returns:
+            List of context snippets
+        """
+        pass
+
+
+class TavilySearchProvider(SearchProvider):
+    """Tavily search provider - optimized for AI agents."""
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+        try:
+            from tavily import TavilyClient
+
+            self.client = TavilyClient(api_key=api_key)
+        except ImportError:
+            raise RuntimeError("tavily-python not installed. Run: pip install tavily-python")
+
+    async def search(self, query: str, max_results: int = 5) -> List[str]:
+        """Search using Tavily's agent-optimized API."""
+        try:
+            response = self.client.search(
+                query=query,
+                search_depth="advanced",
+                max_results=max_results,
+                include_answer=True,
+                include_raw_content=False,
+            )
+
+            snippets = []
+
+            # Add the AI-generated answer if available
+            if response.get("answer"):
+                snippets.append(f"Summary: {response['answer']}")
+
+            # Add search results
+            for result in response.get("results", []):
+                content = result.get("content", "").strip()
+                url = result.get("url", "")
+                if content:
+                    snippet = f"Source: {url}\n{content}"
+                    snippets.append(snippet)
+
+            return snippets[:max_results]
+
+        except Exception as e:
+            logger.warning(f"Tavily search failed: {e}")
+            return []
+
+
+class DuckDuckGoSearchProvider(SearchProvider):
+    """DuckDuckGo search provider - free, no API key required."""
+
+    def __init__(self):
+        try:
+            from duckduckgo_search import DDGS
+
+            self.ddgs = DDGS()
+        except ImportError:
+            raise RuntimeError(
+                "duckduckgo-search not installed. Run: pip install duckduckgo-search"
+            )
+
+    async def search(self, query: str, max_results: int = 5) -> List[str]:
+        """Search using DuckDuckGo's free API."""
+        try:
+            results = self.ddgs.text(keywords=query, max_results=max_results, safesearch="moderate")
+
+            snippets = []
+            for result in results:
+                title = result.get("title", "")
+                body = result.get("body", "")
+                href = result.get("href", "")
+
+                if body:
+                    snippet = f"Title: {title}\nSource: {href}\n{body}"
+                    snippets.append(snippet)
+
+            return snippets
+
+        except Exception as e:
+            logger.warning(f"DuckDuckGo search failed: {e}")
+            return []
+
+
+def create_search_provider() -> Optional[SearchProvider]:
+    """Factory function to create the best available search provider.
+
+    Returns:
+        SearchProvider instance, or None if no providers available
+    """
+    # Try Tavily first (premium, agent-optimized)
+    tavily_key = os.environ.get("TAVILY_API_KEY")
+    if tavily_key:
+        try:
+            logger.info("Using Tavily search provider (premium)")
+            return TavilySearchProvider(tavily_key)
+        except RuntimeError as e:
+            logger.warning(f"Tavily provider failed: {e}")
+
+    # Fall back to DuckDuckGo (free)
+    try:
+        logger.info("Using DuckDuckGo search provider (free)")
+        return DuckDuckGoSearchProvider()
+    except RuntimeError as e:
+        logger.warning(f"DuckDuckGo provider failed: {e}")
+
+    logger.error(
+        "No search providers available. Install: pip install duckduckgo-search tavily-python"
+    )
+    return None
+
+
+async def search_for_context(query: str, max_results: int = 5) -> List[str]:
+    """Search for context snippets to ground the antithesis.
+
+    Args:
+        query: Search query
+        max_results: Maximum results to return
+
+    Returns:
+        List of context snippets, empty list if search fails
+    """
+    provider = create_search_provider()
+    if not provider:
+        return []
+
+    return await provider.search(query, max_results)

hegelion/training/__init__.py

@@ -0,0 +1,7 @@
+from .datasets import export_training_data, to_dpo_dataset, to_instruction_tuning_dataset
+
+__all__ = [
+    "export_training_data",
+    "to_dpo_dataset",
+    "to_instruction_tuning_dataset",
+]

hegelion/training/datasets.py

@@ -0,0 +1,123 @@
+"""
+Hegelion Datasets: Tools for converting dialectical results into training data.
+
+This module enables Hegelion to be used as a generator for RLAIF (Reinforcement Learning
+from AI Feedback) and DPO (Direct Preference Optimization) datasets.
+"""
+
+from typing import List, Literal
+import json
+from pathlib import Path
+from hegelion.core.models import HegelionResult
+
+
+def to_dpo_dataset(
+    results: List[HegelionResult],
+    output_file: str | Path,
+    rejected_source: Literal["thesis", "antithesis", "both"] = "thesis",
+) -> None:
+    """
+    Convert a list of Hegelion results into a DPO (Direct Preference Optimization) dataset.
+
+    Format:
+    {
+        "prompt": "Query...",
+        "chosen": "Synthesis...",
+        "rejected": "Thesis/Antithesis..."
+    }
+
+    Args:
+        results: List of HegelionResult objects
+        output_file: Path to save the .jsonl file
+        rejected_source: Which part of the dialectic to treat as the "rejected" (inferior) response.
+                        - 'thesis': The initial position (good, but not transcendent)
+                        - 'antithesis': The critique (critical, but one-sided)
+                        - 'both': Creates two examples per result (one vs thesis, one vs antithesis)
+    """
+
+    dataset = []
+
+    for res in results:
+        # Basic prompt format
+        prompt = f"Query: {res.query}\n\nProvide a comprehensive analysis."
+
+        # The "Chosen" response is always the Synthesis (the transcendent view)
+        chosen = res.synthesis
+
+        rejected_items = []
+        if rejected_source == "thesis" or rejected_source == "both":
+            rejected_items.append(res.thesis)
+
+        if rejected_source == "antithesis" or rejected_source == "both":
+            rejected_items.append(res.antithesis)
+
+        for rejected in rejected_items:
+            entry = {
+                "prompt": prompt,
+                "chosen": chosen,
+                "rejected": rejected,
+                "metadata": {
+                    "source": "hegelion-synthetic",
+                    "mode": res.mode,
+                    "contradictions_found": len(res.contradictions),
+                },
+            }
+            dataset.append(entry)
+
+    # Write to JSONL
+    with open(output_file, "w", encoding="utf-8") as f:
+        for entry in dataset:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    print(f"Exported {len(dataset)} DPO pairs to {output_file}")
+
+
+def to_instruction_tuning_dataset(results: List[HegelionResult], output_file: str | Path) -> None:
+    """
+    Convert results into standard instruction tuning format (Alpaca/ShareGPT style).
+
+    Format:
+    {
+        "instruction": "Query...",
+        "output": "Synthesis..."
+    }
+    """
+    dataset = []
+    for res in results:
+        entry = {
+            "instruction": res.query,
+            "input": "",
+            "output": res.synthesis,
+            "system": "You are a dialectical reasoner capable of synthesizing opposing viewpoints.",
+        }
+        dataset.append(entry)
+
+    with open(output_file, "w", encoding="utf-8") as f:
+        json.dump(dataset, f, indent=2, ensure_ascii=False)
+
+    print(f"Exported {len(dataset)} instruction tuning examples to {output_file}")
+
+
+def export_training_data(
+    results: List[HegelionResult],
+    output_file: str | Path,
+    *,
+    format: Literal["dpo", "instruction"] = "dpo",
+    rejected_source: Literal["thesis", "antithesis", "both"] = "thesis",
+) -> None:
+    """
+    Convenience wrapper for exporting Hegelion results to common training formats.
+
+    Args:
+        results: List of HegelionResult objects.
+        output_file: Destination path (``.jsonl`` for DPO, ``.json`` for instruction tuning).
+        format: ``"dpo"`` (preference pairs) or ``"instruction"`` (Alpaca-style).
+        rejected_source: Which side to treat as the rejected answer for DPO exports.
+    """
+
+    if format == "dpo":
+        to_dpo_dataset(results, output_file, rejected_source=rejected_source)
+    elif format == "instruction":
+        to_instruction_tuning_dataset(results, output_file)
+    else:
+        raise ValueError("format must be 'dpo' or 'instruction'")