rdc 0.1.0__py3-none-any.whl

gwd/__init__.py

@@ -0,0 +1,69 @@
+"""gwd — get work done. Native task executor.
+
+Public API:
+    execute_task()  — run a task against a project
+    classify_task() — determine if a task is simple or complex
+"""
+
+from .types import TaskComplexity, ExecutionStep, OnStepCallback
+
+
+async def execute_task(
+    task: str,
+    project_path: str,
+    project_context: dict | None = None,
+    client=None,
+    model: str | None = None,
+    on_step: OnStepCallback | None = None,
+    max_iterations: int = 50,
+    force_complexity: TaskComplexity | None = None,
+) -> str:
+    """Execute a task against a project directory.
+
+    Routes to SingleAgentExecutor for simple tasks or
+    MultiAgentOrchestrator for complex tasks.
+
+    Args:
+        task: What to do.
+        project_path: Filesystem path to the project.
+        project_context: Optional dict with purpose, stack, conventions, etc.
+        client: Optional OpenAI-compatible client. Auto-created if None.
+        model: Optional model override. Auto-detected if None.
+        on_step: Optional callback for streaming execution steps.
+        max_iterations: Max tool-use iterations (for simple tasks).
+        force_complexity: Override automatic classification.
+
+    Returns:
+        Final result string.
+    """
+    from .client import create_client, default_model
+    from .classify import classify_task as _classify
+
+    if client is None:
+        client = create_client()
+    if model is None:
+        model = default_model()
+
+    context = {"project_path": project_path}
+    if project_context:
+        context.update(project_context)
+
+    complexity = force_complexity or _classify(task)
+
+    if complexity == TaskComplexity.SIMPLE:
+        from .executor import SingleAgentExecutor
+        executor = SingleAgentExecutor(
+            client=client,
+            model=model,
+            context=context,
+            max_iterations=max_iterations,
+        )
+        return await executor.run(task, on_step=on_step)
+    else:
+        from .orchestrator import MultiAgentOrchestrator
+        orch = MultiAgentOrchestrator(
+            client=client,
+            model=model,
+            context=context,
+        )
+        return await orch.run(task, project_context=context, on_step=on_step)

gwd/__main__.py

@@ -0,0 +1,70 @@
+"""CLI entry point: python -m gwd "task description" --project /path"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from .types import TaskComplexity, ExecutionStep
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="gwd",
+        description="Get Work Done — native task executor",
+    )
+    parser.add_argument("task", help="Task description")
+    parser.add_argument("--project", "-p", default=".", help="Project directory (default: .)")
+    parser.add_argument("--model", "-m", help="Model override (e.g. gpt-4o, anthropic/claude-sonnet-4-20250514)")
+    parser.add_argument("--max-iterations", type=int, default=50, help="Max tool-use iterations")
+    parser.add_argument("--force-simple", action="store_true", help="Force simple (single-agent) execution")
+    parser.add_argument("--force-complex", action="store_true", help="Force complex (multi-agent) execution")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        logging.basicConfig(level=logging.DEBUG, format="%(levelname)s %(name)s: %(message)s")
+    else:
+        logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    force = None
+    if args.force_simple:
+        force = TaskComplexity.SIMPLE
+    elif args.force_complex:
+        force = TaskComplexity.COMPLEX
+
+    async def on_step(step: ExecutionStep):
+        if step.type == "text":
+            print(step.content)
+        elif step.type == "tool_call":
+            tool_info = step.tool_name
+            if step.tool_args:
+                brief = {k: (v[:60] + "..." if isinstance(v, str) and len(v) > 60 else v)
+                         for k, v in step.tool_args.items()}
+                tool_info += f" {brief}"
+            print(f"  -> {tool_info}")
+        elif step.type == "tool_result" and step.is_error:
+            print(f"  !! {step.result[:200]}")
+        elif step.type == "error":
+            print(f"ERROR: {step.content}", file=sys.stderr)
+        elif step.type == "status" and args.verbose:
+            print(f"[{step.content}]")
+
+    from . import execute_task
+
+    result = asyncio.run(execute_task(
+        task=args.task,
+        project_path=args.project,
+        model=args.model,
+        on_step=on_step,
+        max_iterations=args.max_iterations,
+        force_complexity=force,
+    ))
+
+    if not result.startswith("ERROR") and result != "Task completed":
+        print(f"\n--- Result ---\n{result}")
+
+
+if __name__ == "__main__":
+    main()

gwd/classify.py

@@ -0,0 +1,63 @@
+"""Task complexity classifier.
+
+Determines whether a task should be handled by a single agent (simple)
+or the multi-agent orchestrator (complex).
+"""
+
+import re
+
+from .types import TaskComplexity
+
+# Keywords that suggest complexity
+COMPLEX_KEYWORDS = {
+    "refactor", "implement", "integrate", "migrate", "redesign",
+    "add endpoint", "add api", "add auth", "authentication",
+    "add feature", "build", "create system", "set up", "setup",
+    "convert", "rewrite", "architect",
+}
+
+# Keywords that suggest simplicity
+SIMPLE_KEYWORDS = {
+    "list", "show", "print", "rename", "typo", "fix typo",
+    "change", "update", "add import", "remove", "delete",
+    "move", "copy", "format", "lint", "log",
+}
+
+
+def classify_task(description: str) -> TaskComplexity:
+    """Classify a task as simple or complex.
+
+    Heuristic based on word count and keyword matching.
+    Default bias: SIMPLE.
+    """
+    desc_lower = description.lower().strip()
+    words = desc_lower.split()
+    word_count = len(words)
+
+    # Very short tasks are simple
+    if word_count <= 8:
+        # Unless they contain complex keywords
+        for kw in COMPLEX_KEYWORDS:
+            if kw in desc_lower:
+                return TaskComplexity.COMPLEX
+        return TaskComplexity.SIMPLE
+
+    # Long tasks are complex
+    if word_count > 20:
+        # Unless they only contain simple keywords
+        has_complex = any(kw in desc_lower for kw in COMPLEX_KEYWORDS)
+        if has_complex:
+            return TaskComplexity.COMPLEX
+        # Even long tasks that are just verbose simple requests stay simple
+        has_simple = any(kw in desc_lower for kw in SIMPLE_KEYWORDS)
+        if has_simple and not has_complex:
+            return TaskComplexity.SIMPLE
+        return TaskComplexity.COMPLEX
+
+    # Medium length — check keywords
+    for kw in COMPLEX_KEYWORDS:
+        if kw in desc_lower:
+            return TaskComplexity.COMPLEX
+
+    # Default bias: simple
+    return TaskComplexity.SIMPLE

gwd/client.py

@@ -0,0 +1,46 @@
+"""LLM client factory for gwd.
+
+Creates an OpenAI-compatible client from environment variables.
+Priority: OPENROUTER_API_KEY > OPENAI_API_KEY > ANTHROPIC_API_KEY > localhost Ollama.
+"""
+
+import os
+
+from openai import OpenAI
+
+
+def create_client(api_key: str | None = None, base_url: str | None = None) -> OpenAI:
+    """Create an OpenAI-compatible client.
+
+    If api_key/base_url are provided, uses them directly.
+    Otherwise auto-detects from environment variables.
+    """
+    if api_key:
+        return OpenAI(api_key=api_key, base_url=base_url)
+
+    # Auto-detect from env
+    or_key = os.getenv("OPENROUTER_API_KEY")
+    if or_key:
+        return OpenAI(api_key=or_key, base_url="https://openrouter.ai/api/v1")
+
+    oai_key = os.getenv("OPENAI_API_KEY")
+    if oai_key:
+        return OpenAI(api_key=oai_key)
+
+    anthropic_key = os.getenv("ANTHROPIC_API_KEY")
+    if anthropic_key:
+        return OpenAI(api_key=anthropic_key, base_url="https://openrouter.ai/api/v1")
+
+    # Fallback to local Ollama
+    return OpenAI(api_key="ollama", base_url="http://localhost:11434/v1")
+
+
+def default_model() -> str:
+    """Pick the default model based on which env var is set."""
+    if os.getenv("OPENROUTER_API_KEY"):
+        return "anthropic/claude-sonnet-4-20250514"
+    if os.getenv("OPENAI_API_KEY"):
+        return "gpt-4o"
+    if os.getenv("ANTHROPIC_API_KEY"):
+        return "anthropic/claude-sonnet-4-20250514"
+    return "qwen3.5"

gwd/executor.py

@@ -0,0 +1,165 @@
+"""SingleAgentExecutor — core tool-use loop for gwd.
+
+Mirrors WebNativeProvider.run() but decoupled from RDC. Uses OpenAI-compatible
+client to drive a tool-use agentic loop.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from openai import OpenAI
+
+from .prompts import executor_prompt
+from .tools import AGENT_TOOLS, execute_tool
+from .types import ExecutionStep, OnStepCallback
+
+logger = logging.getLogger(__name__)
+
+
+class SingleAgentExecutor:
+    """Core tool-use loop executor."""
+
+    def __init__(
+        self,
+        client: OpenAI,
+        model: str,
+        context: dict[str, Any] | None = None,
+        max_iterations: int = 50,
+    ):
+        self.client = client
+        self.model = model
+        self.context = context or {}
+        self.max_iterations = max_iterations
+        self._cancelled = False
+        self._step_index = 0
+
+    async def _emit(
+        self,
+        on_step: OnStepCallback | None,
+        step_type: str,
+        subtask_id: str = "",
+        **kwargs,
+    ) -> ExecutionStep:
+        step = ExecutionStep(
+            type=step_type,
+            step_index=self._step_index,
+            subtask_id=subtask_id,
+            **kwargs,
+        )
+        self._step_index += 1
+        if on_step:
+            try:
+                await on_step(step)
+            except Exception as e:
+                logger.warning(f"on_step callback error: {e}")
+        return step
+
+    async def run(
+        self,
+        task: str,
+        on_step: OnStepCallback | None = None,
+        subtask_id: str = "",
+    ) -> str:
+        """Run the tool-use loop until completion.
+
+        Each call starts with a completely fresh conversation (system + user task).
+        This follows the Ralph Wiggum Loop pattern — no carried-over context
+        between attempts, preventing drift and hallucination accumulation.
+
+        Args:
+            task: The task description for the agent.
+            on_step: Optional callback for streaming execution steps.
+            subtask_id: Optional subtask ID for step attribution.
+
+        Returns:
+            Final text output from the agent.
+        """
+        self._cancelled = False
+        self._step_index = 0
+
+        project_path = self.context.get("project_path", ".")
+        system = executor_prompt(self.context)
+
+        await self._emit(on_step, "status", subtask_id, content=f"Starting with model {self.model}")
+
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": task},
+        ]
+
+        final_text = ""
+
+        for iteration in range(self.max_iterations):
+            if self._cancelled:
+                await self._emit(on_step, "status", subtask_id, content="Cancelled")
+                return "Task cancelled"
+
+            try:
+                response = await asyncio.to_thread(
+                    lambda: self.client.chat.completions.create(
+                        model=self.model,
+                        messages=messages,
+                        tools=AGENT_TOOLS,
+                        max_tokens=4096,
+                    )
+                )
+            except Exception as e:
+                await self._emit(on_step, "error", subtask_id, content=str(e), is_error=True)
+                return f"LLM error: {e}"
+
+            choice = response.choices[0]
+            msg = choice.message
+
+            if msg.content:
+                final_text = msg.content
+                await self._emit(on_step, "text", subtask_id, content=msg.content)
+
+            if not msg.tool_calls:
+                await self._emit(on_step, "status", subtask_id, content="Completed")
+                return final_text or "Task completed"
+
+            messages.append(msg.model_dump())
+
+            for tc in msg.tool_calls:
+                tool_name = tc.function.name
+                try:
+                    tool_args = json.loads(tc.function.arguments) if tc.function.arguments else {}
+                except (json.JSONDecodeError, TypeError):
+                    tool_args = {}
+
+                await self._emit(
+                    on_step, "tool_call", subtask_id,
+                    tool_name=tool_name,
+                    tool_args=tool_args,
+                )
+
+                result_str, is_err = await execute_tool(tool_name, tool_args, project_path)
+
+                await self._emit(
+                    on_step, "tool_result", subtask_id,
+                    tool_name=tool_name,
+                    result=result_str,
+                    is_error=is_err,
+                )
+
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": result_str,
+                })
+
+            if choice.finish_reason == "stop":
+                await self._emit(on_step, "status", subtask_id, content="Completed")
+                return final_text or "Task completed"
+
+        await self._emit(
+            on_step, "error", subtask_id,
+            content=f"Reached maximum iterations ({self.max_iterations})",
+            is_error=True,
+        )
+        return f"Reached maximum iterations ({self.max_iterations})"
+
+    def cancel(self):
+        self._cancelled = True

gwd/orchestrator.py

@@ -0,0 +1,224 @@
+"""MultiAgentOrchestrator — plan, execute, verify, review loop.
+
+Uses the Ralph Wiggum Loop pattern (Geoffrey Huntley): each retry starts
+with a completely fresh context. The agent discovers current state from
+disk (git diff, file reads) rather than carrying forward a polluted
+conversation history. This prevents drift and hallucination accumulation.
+
+Flow:
+    Plan -> [wave1: subtasks in parallel] -> [wave2: ...] -> Summary
+
+Per subtask (max 3 attempts):
+    Fresh executor -> Verify -> pass? done : wipe context, loop
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from openai import OpenAI
+
+from .executor import SingleAgentExecutor
+from .planner import PlannerAgent
+from .types import (
+    ExecutionStep,
+    OnStepCallback,
+    Plan,
+    Subtask,
+    SubtaskStatus,
+    VerifyResult,
+)
+from .verifier import Verifier
+
+logger = logging.getLogger(__name__)
+
+MAX_SUBTASK_ATTEMPTS = 3
+
+
+class MultiAgentOrchestrator:
+    """Orchestrates complex tasks: plan -> wave execution -> verify -> summary."""
+
+    def __init__(
+        self,
+        client: OpenAI,
+        model: str,
+        context: dict[str, Any] | None = None,
+    ):
+        self.client = client
+        self.model = model
+        self.context = context or {}
+        self._cancelled = False
+        self._step_index = 0
+
+    async def _emit(self, on_step: OnStepCallback | None, step_type: str, **kwargs):
+        step = ExecutionStep(type=step_type, step_index=self._step_index, **kwargs)
+        self._step_index += 1
+        if on_step:
+            try:
+                await on_step(step)
+            except Exception:
+                pass
+
+    async def run(
+        self,
+        task: str,
+        project_context: dict[str, Any] | None = None,
+        on_step: OnStepCallback | None = None,
+    ) -> str:
+        """Execute a complex task via plan -> execute -> verify loop."""
+        self._cancelled = False
+        self._step_index = 0
+
+        context = dict(self.context)
+        if project_context:
+            context.update(project_context)
+
+        # Phase 1: Create plan
+        await self._emit(on_step, "status", content="Creating execution plan...")
+
+        planner = PlannerAgent(
+            client=self.client,
+            model=self.model,
+            context=context,
+        )
+        plan = await planner.create_plan(task, on_step=on_step)
+
+        await self._emit(
+            on_step, "text",
+            content=f"Plan: {plan.analysis}\nSubtasks: {len(plan.subtasks)}",
+        )
+
+        if not plan.subtasks:
+            return "No subtasks to execute"
+
+        # Phase 2: Execute waves
+        waves = plan.waves()
+        results: dict[str, str] = {}
+
+        for wave_idx, wave in enumerate(waves):
+            if self._cancelled:
+                return "Orchestration cancelled"
+
+            await self._emit(
+                on_step, "status",
+                content=f"Wave {wave_idx + 1}/{len(waves)}: {len(wave)} subtask(s)",
+            )
+
+            # Run subtasks in this wave concurrently
+            coros = [
+                self._execute_subtask(subtask, context, on_step)
+                for subtask in wave
+            ]
+            wave_results = await asyncio.gather(*coros, return_exceptions=True)
+
+            for subtask, result in zip(wave, wave_results):
+                if isinstance(result, Exception):
+                    subtask.status = SubtaskStatus.FAILED
+                    subtask.result = str(result)
+                    results[subtask.id] = f"FAILED: {result}"
+                else:
+                    results[subtask.id] = result
+
+        # Phase 3: Summary
+        summary_parts = [f"Task: {task}", f"Plan: {plan.analysis}", ""]
+        for st in plan.subtasks:
+            status_icon = "+" if st.status == SubtaskStatus.PASSED else "-"
+            summary_parts.append(f"  [{status_icon}] {st.id}. {st.description}")
+            if st.result:
+                result_preview = st.result[:200] + "..." if len(st.result) > 200 else st.result
+                summary_parts.append(f"      {result_preview}")
+
+        summary = "\n".join(summary_parts)
+        await self._emit(on_step, "text", content=summary)
+        return summary
+
+    async def _execute_subtask(
+        self,
+        subtask: Subtask,
+        context: dict[str, Any],
+        on_step: OnStepCallback | None,
+    ) -> str:
+        """Execute a single subtask using the Ralph Wiggum Loop pattern.
+
+        Each attempt gets a completely fresh executor with no prior conversation
+        history. The agent discovers current project state from disk (git diff,
+        file reads) rather than inheriting a potentially polluted context.
+
+        On retry, only a short factual note about the attempt number is included
+        in the task prompt — no accumulated failure messages or suggestions that
+        could bias the agent toward the same broken approach.
+        """
+        subtask.status = SubtaskStatus.RUNNING
+        await self._emit(
+            on_step, "status",
+            content=f"Subtask {subtask.id}: {subtask.description[:80]}",
+            subtask_id=subtask.id,
+        )
+
+        verifier = Verifier(
+            client=self.client,
+            model=self.model,
+            context=context,
+        )
+
+        last_verification: VerifyResult | None = None
+
+        for attempt in range(1, MAX_SUBTASK_ATTEMPTS + 1):
+            subtask.attempts = attempt
+
+            # Fresh executor each attempt — no carried-over conversation
+            executor = SingleAgentExecutor(
+                client=self.client,
+                model=self.model,
+                context=context,
+            )
+
+            # Build task prompt: original description + minimal retry hint
+            if attempt == 1:
+                task_prompt = subtask.description
+            else:
+                # Only tell the agent it's a retry and to check current state.
+                # Don't feed back the previous error/suggestion — let it
+                # discover the actual state from disk with fresh eyes.
+                task_prompt = (
+                    f"{subtask.description}\n\n"
+                    f"Note: This is attempt {attempt}/{MAX_SUBTASK_ATTEMPTS}. "
+                    f"A previous attempt may have made partial progress. "
+                    f"Start by checking git diff and the current state of relevant files "
+                    f"before making any changes."
+                )
+
+            result = await executor.run(
+                task=task_prompt,
+                on_step=on_step,
+                subtask_id=subtask.id,
+            )
+
+            # Verify
+            last_verification = await verifier.verify(subtask, on_step=on_step)
+
+            if last_verification.passed:
+                subtask.status = SubtaskStatus.PASSED
+                subtask.result = result
+                await self._emit(
+                    on_step, "status",
+                    content=f"Subtask {subtask.id} passed (attempt {attempt})",
+                    subtask_id=subtask.id,
+                )
+                return result
+
+            # Failed — log and loop with fresh context
+            await self._emit(
+                on_step, "status",
+                content=f"Subtask {subtask.id} failed verification (attempt {attempt}): {last_verification.output[:100]}",
+                subtask_id=subtask.id,
+            )
+
+        # All attempts exhausted
+        subtask.status = SubtaskStatus.FAILED
+        fail_msg = last_verification.output if last_verification else "unknown error"
+        subtask.result = f"Failed after {MAX_SUBTASK_ATTEMPTS} attempts: {fail_msg}"
+        return subtask.result
+
+    def cancel(self):
+        self._cancelled = True