emdash-core 0.1.7__py3-none-any.whl

emdash_core/agent/providers/transformers_provider.py

@@ -0,0 +1,217 @@
+"""Local Transformers-based LLM provider.
+
+Uses HuggingFace transformers to run models locally without API calls.
+Requires: pip install transformers torch accelerate
+"""
+
+import logging
+from typing import Any, Optional
+
+from .base import LLMProvider, LLMResponse, ToolCall
+
+log = logging.getLogger(__name__)
+
+
+# Model specifications: model_id -> (context_limit, description)
+LOCAL_MODELS = {
+    "microsoft/Phi-3-mini-4k-instruct": (4096, "Phi-3 Mini 4K - 3.8B params, good for summaries"),
+    "microsoft/Phi-3-mini-128k-instruct": (131072, "Phi-3 Mini 128K - 3.8B params, long context"),
+    "TinyLlama/TinyLlama-1.1B-Chat-v1.0": (2048, "TinyLlama - 1.1B params, very fast"),
+    "Qwen/Qwen2.5-1.5B-Instruct": (32768, "Qwen 2.5 1.5B - fast and capable"),
+    "Qwen/Qwen2.5-3B-Instruct": (32768, "Qwen 2.5 3B - balanced speed/quality"),
+}
+
+DEFAULT_LOCAL_MODEL = "Qwen/Qwen2.5-1.5B-Instruct"
+
+
+class TransformersProvider(LLMProvider):
+    """
+    Local LLM provider using HuggingFace Transformers.
+
+    Runs models locally - no API key or network required.
+    Models are lazy-loaded on first use to avoid startup overhead.
+
+    Usage:
+        provider = TransformersProvider("Qwen/Qwen2.5-1.5B-Instruct")
+        response = provider.chat([{"role": "user", "content": "Hello"}])
+        print(response.content)
+
+    Or via factory:
+        provider = get_provider("local:Qwen/Qwen2.5-1.5B-Instruct")
+    """
+
+    def __init__(self, model: str = DEFAULT_LOCAL_MODEL):
+        """Initialize with a model name.
+
+        Args:
+            model: HuggingFace model ID (e.g., "Qwen/Qwen2.5-1.5B-Instruct")
+        """
+        # Strip local: prefix if present
+        if model.startswith("local:"):
+            model = model[6:]
+        elif model.startswith("transformers:"):
+            model = model[13:]
+
+        super().__init__(model)
+        self._pipeline = None
+        self._tokenizer = None
+
+    @property
+    def is_available(self) -> bool:
+        """Check if transformers is installed."""
+        try:
+            import transformers
+            import torch
+            return True
+        except ImportError:
+            return False
+
+    def _get_pipeline(self):
+        """Lazy-load the text generation pipeline."""
+        if self._pipeline is None:
+            if not self.is_available:
+                raise ImportError(
+                    "transformers and torch are required for local LLM. "
+                    "Install with: pip install transformers torch accelerate"
+                )
+
+            from transformers import pipeline
+            import torch
+
+            log.info(f"Loading local model: {self.model}")
+
+            # Determine device and dtype
+            if torch.cuda.is_available():
+                device_map = "auto"
+                torch_dtype = torch.float16
+                log.info("Using CUDA GPU")
+            elif torch.backends.mps.is_available():
+                device_map = "mps"
+                torch_dtype = torch.float16
+                log.info("Using Apple MPS")
+            else:
+                device_map = "cpu"
+                torch_dtype = torch.float32
+                log.info("Using CPU (slower)")
+
+            self._pipeline = pipeline(
+                "text-generation",
+                model=self.model,
+                device_map=device_map,
+                torch_dtype=torch_dtype,
+                trust_remote_code=True,
+            )
+            log.info(f"Model loaded: {self.model}")
+
+        return self._pipeline
+
+    def chat(
+        self,
+        messages: list[dict],
+        tools: Optional[list[dict]] = None,
+        system: Optional[str] = None,
+        reasoning: bool = False,
+    ) -> LLMResponse:
+        """Generate response using local model.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            tools: Tool schemas (not supported for local models)
+            system: Optional system prompt
+            reasoning: Enable reasoning mode (not supported)
+
+        Returns:
+            LLMResponse with generated content
+        """
+        if tools:
+            log.warning("Tool calling not supported with local transformers models")
+
+        pipe = self._get_pipeline()
+
+        # Build messages list with system prompt
+        chat_messages = []
+        if system:
+            chat_messages.append({"role": "system", "content": system})
+        chat_messages.extend(messages)
+
+        # Use the pipeline's chat template
+        try:
+            result = pipe(
+                chat_messages,
+                max_new_tokens=512,
+                do_sample=True,
+                temperature=0.7,
+                top_p=0.9,
+                return_full_text=False,
+            )
+
+            content = result[0]["generated_text"]
+
+            # Handle case where result is a list of messages
+            if isinstance(content, list) and len(content) > 0:
+                content = content[-1].get("content", "")
+
+            return LLMResponse(content=content.strip(), raw=result)
+
+        except Exception as e:
+            log.error(f"Generation failed: {e}")
+            # Fallback to simple prompt format
+            return self._fallback_generate(chat_messages)
+
+    def _fallback_generate(self, messages: list[dict]) -> LLMResponse:
+        """Fallback generation using simple prompt format."""
+        pipe = self._get_pipeline()
+
+        # Build a simple prompt
+        parts = []
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                parts.append(f"System: {content}")
+            elif role == "user":
+                parts.append(f"User: {content}")
+            elif role == "assistant":
+                parts.append(f"Assistant: {content}")
+        parts.append("Assistant:")
+
+        prompt = "\n".join(parts)
+
+        result = pipe(
+            prompt,
+            max_new_tokens=512,
+            do_sample=True,
+            temperature=0.7,
+            top_p=0.9,
+            return_full_text=False,
+        )
+
+        content = result[0]["generated_text"]
+        return LLMResponse(content=content.strip(), raw=result)
+
+    def get_context_limit(self) -> int:
+        """Get the context window size for this model."""
+        if self.model in LOCAL_MODELS:
+            return LOCAL_MODELS[self.model][0]
+        # Default conservative limit
+        return 2048
+
+    def format_tool_result(self, tool_call_id: str, result: str) -> dict:
+        """Format a tool result message (not supported)."""
+        return {"role": "tool", "content": result, "tool_call_id": tool_call_id}
+
+    def format_assistant_message(self, response: LLMResponse) -> dict:
+        """Format an assistant response for message history."""
+        return {"role": "assistant", "content": response.content or ""}
+
+    @classmethod
+    def list_models(cls) -> list[dict]:
+        """List available local models."""
+        return [
+            {
+                "id": model_id,
+                "context_limit": spec[0],
+                "description": spec[1],
+            }
+            for model_id, spec in LOCAL_MODELS.items()
+        ]

emdash_core/agent/research/__init__.py

@@ -0,0 +1,81 @@
+"""Deep Research Agent module.
+
+This module provides a multi-agent research system for deep code exploration.
+
+Components:
+- PlannerAgent: Creates research plans with prioritized questions
+- ResearcherAgent: Executes tool macros and collects evidence
+- CriticAgent: Evaluates research quality and team value adherence
+- SynthesizerAgent: Generates final reports
+- ResearchController: Orchestrates the research loop
+- DeepResearchAgent: Main entry point
+
+Team Values Enforced:
+- V1: Truth over fluency - prefer "unknown" over guesses
+- V2: Evidence-first - all claims must be backed by tool outputs
+- V3: Reviewer-first - output includes review checklists
+- V4: Cost awareness - minimize tool calls, use budget limits
+- V5: Actionable outcomes - end with concrete tasks
+- V6: Team alignment - use team vocabulary
+"""
+
+from .state import (
+    EvidenceItem,
+    Claim,
+    Gap,
+    ResearchQuestion,
+    ResearchPlan,
+    FollowUpQuestion,
+    Contradiction,
+    ValuesViolation,
+    CritiqueScores,
+    Critique,
+    IterationResult,
+    ResearchState,
+)
+from .planner import PlannerAgent
+from .researcher import ResearcherAgent
+from .critic import CriticAgent
+from .synthesizer import SynthesizerAgent
+from .controller import ResearchController
+from .agent import DeepResearchAgent, research
+from .macros import (
+    ToolMacro,
+    MacroStep,
+    MacroExecutor,
+    get_macro,
+    list_macros,
+    suggest_macros,
+)
+
+__all__ = [
+    # State
+    "EvidenceItem",
+    "Claim",
+    "Gap",
+    "ResearchQuestion",
+    "ResearchPlan",
+    "FollowUpQuestion",
+    "Contradiction",
+    "ValuesViolation",
+    "CritiqueScores",
+    "Critique",
+    "IterationResult",
+    "ResearchState",
+    # Agents
+    "PlannerAgent",
+    "ResearcherAgent",
+    "CriticAgent",
+    "SynthesizerAgent",
+    "ResearchController",
+    "DeepResearchAgent",
+    # Convenience
+    "research",
+    # Macros
+    "ToolMacro",
+    "MacroStep",
+    "MacroExecutor",
+    "get_macro",
+    "list_macros",
+    "suggest_macros",
+]

emdash_core/agent/research/agent.py

@@ -0,0 +1,143 @@
+"""Deep Research Agent - main entry point.
+
+Provides a simple interface for deep code research using the
+multi-agent research system.
+"""
+
+from typing import Optional
+
+from rich.console import Console
+
+from ..events import AgentEventEmitter, NullEmitter
+from .controller import ResearchController
+from .state import ResearchState
+
+
+class DeepResearchAgent:
+    """High-level interface for deep code research.
+
+    Wraps the ResearchController with a simpler API.
+
+    Example:
+        agent = DeepResearchAgent()
+        report = agent.research("How does authentication work?")
+        print(report)
+    """
+
+    def __init__(
+        self,
+        model_tier: str = "fast",
+        verbose: bool = True,
+        emitter: Optional[AgentEventEmitter] = None,
+    ):
+        """Initialize the deep research agent.
+
+        Args:
+            model_tier: Model tier (fast, standard, powerful)
+            verbose: Whether to print progress
+            emitter: Event emitter for unified output
+        """
+        self.model_tier = model_tier
+        self.verbose = verbose
+        self.emitter = emitter or NullEmitter(agent_name="DeepResearchAgent")
+        self.console = Console()
+
+        self.controller = ResearchController(
+            model_tier=model_tier,
+            verbose=verbose,
+            emitter=self.emitter,
+        )
+
+        self._last_state: Optional[ResearchState] = None
+
+    def research(
+        self,
+        goal: str,
+        context: str = "",
+        max_iterations: int = 3,
+        budgets: Optional[dict] = None,
+    ) -> str:
+        """Conduct deep research on a topic.
+
+        Args:
+            goal: Research goal/question
+            context: Additional context
+            max_iterations: Maximum research iterations
+            budgets: Resource budgets
+
+        Returns:
+            Final research report as markdown
+        """
+        report, state = self.controller.research(
+            goal=goal,
+            context=context,
+            max_iterations=max_iterations,
+            budgets=budgets,
+        )
+
+        self._last_state = state
+        return report
+
+    def get_last_state(self) -> Optional[ResearchState]:
+        """Get the state from the last research run.
+
+        Returns:
+            ResearchState or None if no research has been run
+        """
+        return self._last_state
+
+    def get_summary(self) -> str:
+        """Get a summary of the last research run.
+
+        Returns:
+            Summary string
+        """
+        if not self._last_state:
+            return "No research has been conducted yet."
+
+        state = self._last_state
+
+        lines = [
+            f"Research: {state.plan.goal}",
+            f"Iterations: {state.iteration}",
+            f"Evidence: {len(state.get_all_evidence())}",
+            f"Claims: {len(state.get_all_claims())}",
+            f"Gaps: {len(state.get_all_gaps())}",
+            f"Status: {'Approved' if state.is_approved() else 'In Progress'}",
+            f"Budget used: {state.budget_used_percent():.0f}%",
+        ]
+
+        return "\n".join(lines)
+
+
+def research(
+    goal: str,
+    context: str = "",
+    model_tier: str = "fast",
+    max_iterations: int = 3,
+    verbose: bool = True,
+) -> str:
+    """Convenience function for quick research.
+
+    Args:
+        goal: Research goal/question
+        context: Additional context
+        model_tier: Model tier to use
+        max_iterations: Maximum iterations
+        verbose: Whether to print progress
+
+    Returns:
+        Research report as markdown
+
+    Example:
+        report = research("How does the payment system work?")
+    """
+    agent = DeepResearchAgent(
+        model_tier=model_tier,
+        verbose=verbose,
+    )
+    return agent.research(
+        goal=goal,
+        context=context,
+        max_iterations=max_iterations,
+    )

emdash_core/agent/research/controller.py

@@ -0,0 +1,254 @@
+"""Research controller for orchestrating the research loop.
+
+The Controller manages the research cycle:
+1. Plan -> questions
+2. Research -> evidence, claims
+3. Critique -> decision
+4. If not approved, back to 2 or adjust plan
+5. Synthesize final report
+"""
+
+from typing import Optional
+
+from rich.console import Console
+
+from ..events import AgentEventEmitter, NullEmitter
+from .state import (
+    ResearchPlan,
+    ResearchState,
+    IterationResult,
+)
+from .planner import PlannerAgent
+from .researcher import ResearcherAgent
+from .critic import CriticAgent
+from .synthesizer import SynthesizerAgent
+
+
+# Model tiers for escalation
+MODEL_TIERS = {
+    "fast": "gpt-4o-mini",
+    "standard": "gpt-4o",
+    "powerful": "gpt-4o",
+}
+
+
+class ResearchController:
+    """Orchestrates the multi-agent research loop.
+
+    The Controller coordinates:
+    - PlannerAgent: Creates research plan
+    - ResearcherAgent: Executes tools, collects evidence
+    - CriticAgent: Evaluates progress
+    - SynthesizerAgent: Writes final report
+
+    It handles model tier escalation and budget management.
+    """
+
+    def __init__(
+        self,
+        model_tier: str = "fast",
+        verbose: bool = True,
+        emitter: Optional[AgentEventEmitter] = None,
+    ):
+        """Initialize the research controller.
+
+        Args:
+            model_tier: Initial model tier (fast, standard, powerful)
+            verbose: Whether to print progress
+            emitter: Event emitter for unified output
+        """
+        self.model_tier = model_tier
+        self.verbose = verbose
+        self.console = Console()
+        self.emitter = emitter or NullEmitter(agent_name="ResearchController")
+
+        # Initialize agents with current model tier
+        model = MODEL_TIERS.get(model_tier, "gpt-4o-mini")
+        self.planner = PlannerAgent(model=model, verbose=verbose)
+        self.researcher = ResearcherAgent(model=model, verbose=verbose, emitter=self.emitter)
+        self.critic = CriticAgent(model=model, verbose=verbose)
+        self.synthesizer = SynthesizerAgent(model=model, verbose=verbose)
+
+    def research(
+        self,
+        goal: str,
+        context: str = "",
+        max_iterations: int = 3,
+        budgets: Optional[dict] = None,
+    ) -> tuple[str, ResearchState]:
+        """Execute the full research loop.
+
+        Args:
+            goal: Research goal
+            context: Additional context
+            max_iterations: Maximum iterations
+            budgets: Resource budgets
+
+        Returns:
+            Tuple of (final_report, research_state)
+        """
+        if self.verbose:
+            self.console.print(f"\n[bold cyan]Starting research: {goal}[/bold cyan]\n")
+
+        # Phase 1: Planning
+        plan = self.planner.create_plan(
+            goal=goal,
+            context=context,
+            max_iterations=max_iterations,
+            budgets=budgets,
+        )
+
+        # Initialize state
+        state = ResearchState(plan=plan)
+
+        # Phase 2: Research Loop
+        while state.iteration < plan.max_iterations:
+            if self.verbose:
+                self.console.print(f"\n[cyan]--- Iteration {state.iteration + 1} ---[/cyan]")
+
+            # Get questions for this iteration
+            questions = self._get_questions_for_iteration(state)
+            if not questions:
+                if self.verbose:
+                    self.console.print("[yellow]No more questions to investigate[/yellow]")
+                break
+
+            # Run research
+            evidence, updated_context = self.researcher.run_macros(
+                questions=questions,
+                context=state.context,
+                budget=state.remaining_budget,
+            )
+
+            # Update context
+            state.context.update(updated_context)
+
+            # Update budget
+            state.remaining_budget["tool_calls"] = max(
+                0,
+                state.remaining_budget.get("tool_calls", 0) - len(evidence)
+            )
+
+            # Generate claims
+            all_prior_claims = state.get_all_claims()
+            claims = self.researcher.propose_claims(
+                goal=plan.goal,
+                questions=questions,
+                evidence=evidence,
+                prior_claims=all_prior_claims,
+            )
+
+            # Identify gaps
+            gaps = self.researcher.identify_gaps(plan, claims, evidence)
+
+            # Critique
+            critique = self.critic.evaluate(
+                plan=plan,
+                evidence=evidence,
+                claims=claims,
+                gaps=gaps,
+                iteration=state.iteration,
+                budget_used_percent=state.budget_used_percent(),
+            )
+
+            # Record iteration
+            result = IterationResult(
+                iteration=state.iteration,
+                evidence=evidence,
+                claims=claims,
+                gaps=gaps,
+                critique=critique,
+                model_tier=self.model_tier,
+            )
+            state.history.append(result)
+            state.iteration += 1
+
+            # Check decision
+            if critique.decision == "APPROVE":
+                if self.verbose:
+                    self.console.print("[green]Research APPROVED[/green]")
+                break
+
+            elif critique.decision == "ESCALATE":
+                if self._escalate_model():
+                    if self.verbose:
+                        self.console.print(f"[yellow]Escalated to {self.model_tier}[/yellow]")
+                else:
+                    if self.verbose:
+                        self.console.print("[yellow]Cannot escalate further[/yellow]")
+                    break
+
+            elif critique.decision == "REJECT":
+                if self.verbose:
+                    self.console.print("[red]Research REJECTED[/red]")
+                    for issue in critique.must_fix:
+                        self.console.print(f"  - {issue}")
+                # Try to fix in next iteration
+
+            # Add follow-up questions to queue
+            for followup in critique.follow_up_questions:
+                if followup.qid and followup.qid not in state.answered_questions:
+                    if followup.qid not in state.question_queue:
+                        state.question_queue.insert(0, followup.qid)
+
+        # Phase 3: Synthesis
+        report = self.synthesizer.write(plan, state.history)
+
+        return report, state
+
+    def _get_questions_for_iteration(
+        self,
+        state: ResearchState,
+    ) -> list:
+        """Get questions to investigate in this iteration.
+
+        Prioritizes P0, then P1, then follow-ups from Critic.
+
+        Args:
+            state: Current research state
+
+        Returns:
+            List of ResearchQuestion objects
+        """
+        questions = []
+
+        # Take from queue
+        qids_to_process = state.question_queue[:3]  # Up to 3 at a time
+
+        for qid in qids_to_process:
+            question = state.get_question_by_qid(qid)
+            if question and qid not in state.answered_questions:
+                questions.append(question)
+                state.answered_questions.add(qid)
+
+        # Remove processed from queue
+        for qid in qids_to_process:
+            if qid in state.question_queue:
+                state.question_queue.remove(qid)
+
+        return questions
+
+    def _escalate_model(self) -> bool:
+        """Escalate to a more powerful model tier.
+
+        Returns:
+            True if escalation was possible
+        """
+        tiers = ["fast", "standard", "powerful"]
+        current_idx = tiers.index(self.model_tier) if self.model_tier in tiers else 0
+
+        if current_idx >= len(tiers) - 1:
+            return False
+
+        self.model_tier = tiers[current_idx + 1]
+        model = MODEL_TIERS[self.model_tier]
+
+        # Reinitialize agents with new model
+        self.planner = PlannerAgent(model=model, verbose=self.verbose)
+        self.researcher = ResearcherAgent(
+            model=model, verbose=self.verbose, emitter=self.emitter
+        )
+        self.critic = CriticAgent(model=model, verbose=self.verbose)
+        self.synthesizer = SynthesizerAgent(model=model, verbose=self.verbose)
+
+        return True