dialectica 0.3.0__py3-none-any.whl

dialectica/.env.example

@@ -0,0 +1,36 @@
+# Example Environment Variables
+# Copy this file to .env and fill in your actual credentials and configurations.
+
+# --- Google AI Studio / Vertex AI ---
+# Set GOOGLE_GENAI_USE_VERTEXAI to False if using Google AI Studio API Key
+GOOGLE_GENAI_USE_VERTEXAI=False
+# Provide your Google AI Studio API Key if GOOGLE_GENAI_USE_VERTEXAI is False
+# GOOGLE_API_KEY=AIzaSy...
+
+# OR
+
+# Set GOOGLE_GENAI_USE_VERTEXAI to True if using Vertex AI on Google Cloud
+# GOOGLE_GENAI_USE_VERTEXAI=True
+# Provide your Google Cloud Project ID and Location if using Vertex AI
+# GOOGLE_CLOUD_PROJECT="your-project-id"
+# GOOGLE_CLOUD_LOCATION="your-location" #e.g. us-central1
+
+# --- OpenAI / Compatible ---
+# Provide your OpenAI API Key (or compatible service key)
+# OPENAI_API_KEY=sk-...
+# Provide the Base URL for the API endpoint (if not using standard OpenAI)
+# OPENAI_API_BASE=https://api.example.com/v1
+
+# --- OpenRouter ---
+# Provide your OpenRouter API Key
+# OPENROUTER_API_KEY=sk-or-v1-...
+
+# --- Model Configuration (ADK 2.0+) ---
+# Default model for all dynamically created agents.
+# Format: provider:model_name (e.g., google:gemini-3.5-flash, openai:gpt-4o, openrouter:google/gemini-3.1-pro)
+DEFAULT_MODEL_CONFIG=google:gemini-3.5-flash
+
+# Optional: Role-specific overrides (these override DEFAULT_MODEL_CONFIG for specific roles)
+# GENERATOR_MODEL_CONFIG=google:gemini-3.1-pro
+# DISCRIMINATOR_MODEL_CONFIG=google:gemini-3.1-pro
+# SYNTHESIZER_MODEL_CONFIG=google:gemini-3.1-pro

dialectica/__init__.py

@@ -0,0 +1,74 @@
+"""
+Dialectica — a pluggable adversarial reasoning engine.
+
+The Engine runs a beam-style tree search and delegates each stage to a
+swappable component (Generator / Evaluator / Selector / Synthesizer):
+thesis -> antithesis -> synthesis. The defaults give a Tree-of-Thoughts +
+GAN-adversarial pipeline, but any stage can be replaced without touching the
+engine.
+
+Main Components:
+- Engine: Runs the search control flow over pluggable stages
+- Generator / Evaluator / Selector / Synthesizer: the stage protocols
+- LlmGenerator, AdversarialEvaluator/SinglePassEvaluator, BeamSearch/GreedySearch,
+  LlmSynthesizer: the default implementations
+- ThoughtData / EvaluationResult: data models
+
+Example:
+    from dialectica import create_engine
+
+    engine = create_engine("Your problem here")
+    result = await engine.run()
+
+
+Configuration is read from ``os.environ`` — as a library, Dialectica does NOT
+load ``.env`` itself; the consuming application owns environment setup.
+"""
+
+from .agent import (
+    Engine,
+    build_default_components,
+    create_coordinator,
+    create_engine,
+    run_tot_workflow,
+)
+from .agent_factory import ROLE_TEMPLATES, create_agent
+from .coordinator import Coordinator
+from .gan_evaluator import AdversarialEvaluator, SinglePassEvaluator
+from .generation import LlmGenerator
+from .models import DiscriminatorVerdict, EvaluationResult, ThoughtData
+from .protocols import Evaluator, Generator, Selector, Synthesizer
+from .selection import BeamSearch, GreedySearch
+from .synthesis import LlmSynthesizer
+
+__all__ = [
+    # Main entry points
+    "create_engine",
+    "Engine",
+    "build_default_components",
+    "run_tot_workflow",
+    # Backward-compatible aliases
+    "create_coordinator",
+    "Coordinator",
+    # Stage protocols (the pluggable interfaces)
+    "Generator",
+    "Evaluator",
+    "Selector",
+    "Synthesizer",
+    # Default stage implementations
+    "LlmGenerator",
+    "AdversarialEvaluator",
+    "SinglePassEvaluator",
+    "BeamSearch",
+    "GreedySearch",
+    "LlmSynthesizer",
+    # Data models
+    "ThoughtData",
+    "EvaluationResult",
+    "DiscriminatorVerdict",
+    # Agent creation
+    "create_agent",
+    "ROLE_TEMPLATES",
+]
+
+__version__ = "0.3.0"

dialectica/agent.py

@@ -0,0 +1,149 @@
+"""
+Tree of Thoughts with GAN-style Adversarial Evaluation — composition root.
+
+``create_coordinator`` wires the default pluggable components (LLM generator,
+GAN evaluator, beam-search selector, LLM synthesizer) into a ``Coordinator``.
+To customize, build the components yourself and construct ``Coordinator``
+directly — see ``build_default_components``.
+
+Usage:
+    from dialectica.agent import create_coordinator
+
+    coordinator = create_coordinator("Your problem statement here")
+    result = await coordinator.run()
+"""
+
+import logging
+from typing import Optional
+
+from .agent_factory import create_agent
+from .coordinator import Coordinator
+from .gan_evaluator import AdversarialEvaluator
+from .generation import LlmGenerator
+from .llm_config import get_model_config
+from .models import DiscriminatorVerdict
+from .protocols import Evaluator, Generator, Selector, Synthesizer
+from .selection import BeamSearch
+from .synthesis import LlmSynthesizer
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+def build_default_components(
+    beam_width: int = 3,
+    max_gan_rounds: int = 3,
+    score_threshold: float = 7.0,
+    synthesizer_model: Optional[str] = None,
+) -> tuple[Generator, Evaluator, Selector, Synthesizer]:
+    """Build the default (generator, evaluator, selector, synthesizer).
+
+    The generator agent is shared with the evaluator so it is created once and
+    reused for both generation and GAN refinement.
+    """
+    generator_agent = create_agent(
+        role="Generator",
+        role_name="Generator",
+        model_config=get_model_config("GENERATOR"),
+    )
+    discriminator_agent = create_agent(
+        role="Discriminator",
+        role_name="Discriminator",
+        model_config=get_model_config("DISCRIMINATOR"),
+        output_schema=DiscriminatorVerdict,
+    )
+    synthesizer_agent = create_agent(
+        role="Synthesizer",
+        role_name="Synthesizer",
+        model_config=synthesizer_model or get_model_config("SYNTHESIZER"),
+    )
+
+    generator = LlmGenerator(generator_agent)
+    evaluator = AdversarialEvaluator(
+        generator=generator_agent,
+        discriminator=discriminator_agent,
+        max_rounds=max_gan_rounds,
+        score_threshold=score_threshold,
+    )
+    selector = BeamSearch(width=beam_width)
+    synthesizer = LlmSynthesizer(synthesizer_agent)
+    return generator, evaluator, selector, synthesizer
+
+
+def create_coordinator(
+    problem: str,
+    max_depth: int = 4,
+    beam_width: int = 3,
+    max_gan_rounds: int = 3,
+    score_threshold: float = 7.0,
+    synthesizer_model: Optional[str] = None,
+) -> Coordinator:
+    """Create a Coordinator wired with the default ToT + GAN components.
+
+    Args:
+        problem: The problem statement to solve
+        max_depth: Maximum depth of the thought tree (default: 4)
+        beam_width: Number of top candidates the beam keeps (default: 3)
+        max_gan_rounds: Maximum adversarial refinement rounds (default: 3)
+        score_threshold: Minimum score for a thought to continue (default: 7.0)
+        synthesizer_model: Optional specific model for synthesis
+
+    Returns:
+        Configured Coordinator instance
+
+    Example:
+        >>> coordinator = create_coordinator("Design a sustainable urban transport system")
+        >>> result = await coordinator.run()
+        >>> print(result["final_answer"])
+    """
+    logger.info(f"Creating coordinator for problem: {problem[:50]}...")
+
+    generator, evaluator, selector, synthesizer = build_default_components(
+        beam_width=beam_width,
+        max_gan_rounds=max_gan_rounds,
+        score_threshold=score_threshold,
+        synthesizer_model=synthesizer_model,
+    )
+    return Coordinator(
+        problem=problem,
+        generator=generator,
+        evaluator=evaluator,
+        selector=selector,
+        synthesizer=synthesizer,
+        max_depth=max_depth,
+        score_threshold=score_threshold,
+    )
+
+
+# Convenience wrapper for embedding the engine in other async code.
+async def run_tot_workflow(problem: str, **kwargs):
+    """Run a complete ToT workflow for a given problem.
+
+    Convenience wrapper for frameworks that need a simple async function.
+
+    Returns:
+        Dictionary with final_answer, thought_tree, best_path, and stats
+    """
+    coordinator = create_coordinator(problem, **kwargs)
+    return await coordinator.run()
+
+
+# Canonical Dialectica names. The Coordinator/create_coordinator names are kept
+# as aliases for backward compatibility.
+create_engine = create_coordinator
+Engine = Coordinator
+
+
+__all__ = [
+    "create_engine",
+    "Engine",
+    "build_default_components",
+    "run_tot_workflow",
+    # Backward-compatible aliases
+    "create_coordinator",
+    "Coordinator",
+]

dialectica/agent_factory.py

@@ -0,0 +1,139 @@
+"""Dynamic agent factory for creating specialist agents at runtime.
+
+Creates LlmAgent instances from role templates (Generator, Discriminator,
+Synthesizer, ...) with per-role prompts, tools, and model configuration.
+"""
+
+import logging
+from typing import Any
+
+from google.adk.agents import LlmAgent
+from google.adk.tools import google_search
+
+from .llm_config import get_model_config
+
+logger = logging.getLogger(__name__)
+
+
+# Agent role templates - used to generate instructions for common roles
+ROLE_TEMPLATES = {
+    "Generator": {
+        "system_prompt": """You are a {role_name} responsible for generating high-quality thoughts.
+
+Your task:
+- Generate creative, diverse, and well-reasoned thought branches
+- Each thought should be distinct and explore different angles
+- Build on the parent context when provided
+- Be specific and actionable, not vague or generic
+
+{additional_context}
+
+Generate thoughts that advance the problem-solving process.""",
+        "tools": [],
+    },
+    "Discriminator": {
+        "system_prompt": """You are a {role_name} responsible for critically evaluating thoughts.
+
+Your task:
+- Evaluate thoughts with rigorous skepticism
+- Identify logical flaws, weak assumptions, and potential issues
+- Provide specific, actionable feedback for improvement
+- Assess feasibility and quality objectively
+- Recommend termination only if the path is fundamentally flawed
+
+{additional_context}
+
+Your evaluation will drive iterative refinement, so be thorough and constructive.""",
+        "tools": [],
+    },
+    "ResearchGenerator": {
+        "system_prompt": """You are a {role_name} that combines research with thought generation.
+
+Your task:
+- Use the google_search tool to gather relevant information
+- Generate thoughts grounded in real-world facts and data
+- Synthesize research findings into actionable ideas
+- Cite sources when making claims
+
+{additional_context}
+
+Generate informed thoughts that leverage external knowledge.""",
+        "tools": [google_search],
+    },
+    "Synthesizer": {
+        "system_prompt": """You are a {role_name} responsible for integrating insights into a final answer.
+
+Your task:
+- Analyze the best-performing thought branches
+- Identify common themes and complementary insights
+- Synthesize a coherent, comprehensive solution
+- Resolve any conflicts between different approaches
+- Present the final answer clearly and completely
+
+{additional_context}
+
+Create a unified solution from the strongest reasoning paths.""",
+        "tools": [],
+    },
+}
+
+
+def create_agent(
+    role: str,
+    role_name: str | None = None,
+    additional_context: str = "",
+    tools: list[Any] | None = None,
+    model_config: str | None = None,
+    output_schema: type | None = None,
+) -> LlmAgent:
+    """Create a specialist agent with a specific role.
+
+    Args:
+        role: The agent role (Generator, Discriminator, ResearchGenerator, Synthesizer)
+        role_name: Optional custom name for the role (defaults to role)
+        additional_context: Extra context to inject into the system prompt
+        tools: Optional list of tools to give the agent
+        model_config: Optional model config string (defaults to role-based config)
+        output_schema: Optional Pydantic model forcing structured JSON output.
+            ADK disallows combining ``output_schema`` with tools, so tools are
+            dropped when a schema is supplied.
+
+    Returns:
+        LlmAgent configured for the specified role
+    """
+    if role not in ROLE_TEMPLATES:
+        logger.warning("Unknown role '%s', using Generator template", role)
+        role = "Generator"
+
+    template = ROLE_TEMPLATES[role]
+    effective_role_name = role_name or role
+
+    # Build the system prompt
+    system_prompt = template["system_prompt"].format(
+        role_name=effective_role_name,
+        additional_context=additional_context,
+    )
+
+    # output_schema and tools are mutually exclusive in ADK.
+    effective_tools = [] if output_schema else (tools if tools is not None else template["tools"])
+
+    # Get model config (use role-specific override if available)
+    effective_model = model_config if model_config else get_model_config(role)
+
+    agent = LlmAgent(
+        name=effective_role_name,
+        instruction=system_prompt,
+        model=effective_model,
+        tools=effective_tools,
+        output_schema=output_schema,
+    )
+
+    logger.info(
+        "Created agent '%s' (role=%s, tools=%d, structured=%s)",
+        effective_role_name,
+        role,
+        len(effective_tools),
+        output_schema is not None,
+    )
+
+    return agent

dialectica/agent_runtime.py

@@ -0,0 +1,28 @@
+"""Single entry point for invoking an LlmAgent.
+
+Centralizing the ADK Runner call gives every pluggable component (generator,
+evaluator, synthesizer) one shared seam — which is also the one place tests
+patch to run the engine without the network.
+"""
+
+import logging
+
+from google.adk.agents import LlmAgent
+from google.adk.runners import InMemoryRunner
+
+logger = logging.getLogger(__name__)
+
+
+async def run_agent(agent: LlmAgent, instruction: str) -> str:
+    """Run ``agent`` on ``instruction`` and return its concatenated text output."""
+    runner = InMemoryRunner(agent=agent, app_name="dialectica")
+    events = await runner.run_debug(instruction, quiet=True)
+
+    response_text = ""
+    for event in events:
+        if event.content and event.content.parts:
+            for part in event.content.parts:
+                if part.text and not part.thought:
+                    response_text += part.text
+
+    return response_text.strip()

dialectica/coordinator.py

@@ -0,0 +1,212 @@
+"""Tree-of-Thoughts search engine.
+
+The Coordinator owns the search *control flow* (build root -> expand frontier ->
+score -> select -> synthesize) but delegates every decision to injected,
+swappable components: a ``Generator``, an ``Evaluator``, a ``Selector`` and a
+``Synthesizer``. Swap any of them to retarget the engine without touching this
+file — that is what makes it general-purpose rather than a single hardcoded
+ToT+GAN pipeline.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from .models import ThoughtData, score_of
+from .protocols import Evaluator, Generator, Selector, Synthesizer
+from .validation import validate_thought_node
+
+logger = logging.getLogger(__name__)
+
+
+class Coordinator:
+    """Runs a beam-style tree search using pluggable stage components.
+
+    Phases:
+    1. Initialize - create the root, expand it into strategies, score them.
+    2. Explore    - iteratively select the frontier, expand, score, re-select.
+    3. Synthesize - combine the evaluated thoughts into a final answer.
+    """
+
+    def __init__(
+        self,
+        problem: str,
+        generator: Generator,
+        evaluator: Evaluator,
+        selector: Selector,
+        synthesizer: Synthesizer,
+        max_depth: int = 4,
+        score_threshold: float = 7.0,
+    ):
+        self.problem = problem
+        self.generator = generator
+        self.evaluator = evaluator
+        self.selector = selector
+        self.synthesizer = synthesizer
+        self.max_depth = max_depth
+        self.score_threshold = score_threshold
+
+        # State
+        self.thought_tree: dict[str, ThoughtData] = {}
+        self.active_beam: list[str] = []
+
+        logger.info(f"Coordinator initialized for problem: {problem[:50]}...")
+
+    async def run(self) -> dict[str, Any]:
+        """Execute the full search and return the answer plus tree and stats."""
+        start_time = datetime.now()
+
+        logger.info("Phase 1: Initializing thought tree")
+        await self._initialize()
+
+        logger.info("Phase 2: Exploring with beam search")
+        await self._explore()
+
+        logger.info("Phase 3: Synthesizing final answer")
+        final_answer = await self.synthesizer.synthesize(
+            self.problem, list(self.thought_tree.values())
+        )
+
+        duration = (datetime.now() - start_time).total_seconds()
+        return {
+            "final_answer": final_answer,
+            "thought_tree": {k: v.model_dump() for k, v in self.thought_tree.items()},
+            "best_path": self._get_best_path(),
+            "stats": {
+                "total_thoughts": len(self.thought_tree),
+                "max_depth_reached": max(t.depth for t in self.thought_tree.values()),
+                "duration_seconds": duration,
+            },
+        }
+
+    async def _initialize(self):
+        """Phase 1: create the root, expand into strategies, score each."""
+        root = self._add_node("root", parent_id=None, content=self.problem, depth=0, status="active")
+
+        logger.info("Generating initial strategies")
+        strategies = await self.generator.expand(root, self.problem)
+
+        strategy_ids = []
+        for i, strategy in enumerate(strategies):
+            node = self._add_node(f"root_s{i}", parent_id="root", content=strategy, depth=1)
+            if node is not None:
+                strategy_ids.append(node.thoughtId)
+
+        # Score strategies before beam selection so the beam reflects merit,
+        # not generation order. The beam is the strategies clearing the bar.
+        self.active_beam = []
+        for sid in strategy_ids:
+            score = await self._evaluate_node(self.thought_tree[sid], self.problem)
+            if score >= self.score_threshold:
+                self.active_beam.append(sid)
+
+        # Don't stall the whole run if nothing cleared the bar: seed exploration
+        # with the best strategies the selector would keep.
+        if not self.active_beam and strategy_ids:
+            kept = self.selector.select([self.thought_tree[sid] for sid in strategy_ids])
+            self.active_beam = [n.thoughtId for n in kept]
+            logger.info("No strategy passed threshold; seeding beam with top %d", len(self.active_beam))
+
+        logger.info(
+            "Scored %d strategies; %d entered the beam", len(strategy_ids), len(self.active_beam)
+        )
+
+    async def _explore(self):
+        """Phase 2: beam search — select, expand, score, repeat."""
+        iteration = 0
+        while self.active_beam and iteration < self.max_depth:
+            iteration += 1
+            logger.info(f"Explore iteration {iteration}, beam size: {len(self.active_beam)}")
+
+            frontier = self.selector.select([self.thought_tree[nid] for nid in self.active_beam])
+
+            new_beam: list[str] = []
+            for parent in frontier:
+                if parent.depth >= self.max_depth:
+                    continue
+
+                children = await self.generator.expand(parent, self.problem)
+                for i, content in enumerate(children):
+                    child = self._add_node(
+                        f"{parent.thoughtId}_c{i}",
+                        parent_id=parent.thoughtId,
+                        content=content,
+                        depth=parent.depth + 1,
+                    )
+                    if child is None:
+                        continue
+                    score = await self._evaluate_node(child, parent.thought)
+                    if score >= self.score_threshold:
+                        new_beam.append(child.thoughtId)
+
+            self.active_beam = new_beam
+            logger.info(f"Iteration {iteration} complete, new beam size: {len(self.active_beam)}")
+
+            if not self.active_beam:
+                logger.info("No candidates meet threshold, stopping exploration")
+                break
+
+    async def _evaluate_node(self, node: ThoughtData, parent_thought: str) -> float:
+        """Score ``node`` via the evaluator, persisting the refined thought.
+
+        The evaluator scores the *refined* thought, so the node's text is
+        updated to that refined version — otherwise synthesis would run on the
+        original wording while reporting the improved score.
+        """
+        result = await self.evaluator.evaluate(
+            thought_content=node.thought,
+            context={
+                "problem": self.problem,
+                "parent_thought": parent_thought,
+                "depth": node.depth,
+            },
+        )
+        node.thought = result.refined_thought or node.thought
+        node.evaluationScore = result.score
+        node.status = "evaluated"
+        node.adversarialRounds = result.adversarial_rounds
+        node.refinementHistory = result.history
+        return result.score
+
+    def _add_node(
+        self,
+        node_id: str,
+        parent_id: str | None,
+        content: str,
+        depth: int,
+        status: str = "generated",
+    ) -> ThoughtData | None:
+        """Validate and insert a node; return it, or None if validation fails."""
+        node = validate_thought_node(
+            thought_id=node_id,
+            parent_id=parent_id,
+            content=content,
+            depth=depth,
+            status=status,
+        )
+        if node is None:
+            if node_id == "root":
+                raise ValueError(f"Root node validation failed for content: {content!r}")
+            logger.warning("Skipping invalid node %s", node_id)
+            return None
+        self.thought_tree[node_id] = node
+        return node
+
+    def _get_best_path(self) -> list[str]:
+        """Get the path from root to the highest-scoring evaluated node."""
+        if not self.thought_tree:
+            return []
+
+        scored = [t for t in self.thought_tree.values() if t.evaluationScore is not None]
+        if not scored:
+            return ["root"] if "root" in self.thought_tree else []
+
+        best = max(scored, key=score_of)
+        path = []
+        current_id: str | None = best.thoughtId
+        while current_id:
+            path.append(current_id)
+            current = self.thought_tree.get(current_id)
+            current_id = current.parentId if current else None
+
+        return list(reversed(path))