auzek 0.1.0__py3-none-any.whl

auzek/__init__.py

@@ -0,0 +1,3 @@
+"""Autonomous coding agent: plans, executes, self-verifies, and self-heals."""
+
+__version__ = "0.1.0"

auzek/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

auzek/cli.py

@@ -0,0 +1,201 @@
+"""Command-line entrypoint.
+
+    agent run "add retry logic to the API client" --provider groq
+    agent providers
+    agent plan-show
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Make output robust on Windows consoles (cp1252) so glyphs never crash a run.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+    except (AttributeError, ValueError):
+        pass
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.table import Table
+
+from .config import AgentConfig
+from .graph import build_graph
+from .llm import LLM, PROVIDERS, LLMConfigError, available_providers
+from .memory.plan_store import Plan, PlanStore
+from .runtime import Deps
+from .state import new_state
+from .tools import build_default_registry
+from .tools.base import ToolContext
+
+app = typer.Typer(add_completion=False, help="Autonomous coding agent.")
+console = Console()
+
+
+# --------------------------------------------------------------------- helpers
+def _emit(msg: str) -> None:
+    style = "cyan" if msg.startswith("[phase]") else (
+        "green" if msg.startswith(("✓", "  ✓")) else
+        "red" if msg.startswith(("✗", "  ✗")) else "dim"
+    )
+    console.print(msg, style=style)
+
+
+def _build_deps(cfg: AgentConfig, api_key: Optional[str]) -> Deps:
+    llm = LLM(
+        cfg.provider,
+        cfg.model,
+        temperature=cfg.temperature,
+        max_tokens=cfg.max_tokens,
+        api_key=api_key,
+    )
+    tool_ctx = ToolContext(workspace=cfg.workspace, deny_globs=cfg.deny_globs)
+    registry = build_default_registry(tool_ctx)
+    plan_store = PlanStore(cfg.state_dir)
+    return Deps(
+        config=cfg,
+        llm=llm,
+        tools=registry,
+        tool_ctx=tool_ctx,
+        plan_store=plan_store,
+        emit=_emit,
+    )
+
+
+def _render_plan(plan: Plan) -> None:
+    table = Table(title="Proposed Plan", show_lines=False, header_style="bold")
+    table.add_column("#", justify="right", style="cyan", no_wrap=True)
+    table.add_column("Step")
+    table.add_column("Files", style="dim")
+    for s in plan.steps:
+        table.add_row(str(s.id), s.description, ", ".join(s.files) or "—")
+    console.print(table)
+    if plan.assumptions:
+        console.print(Panel("\n".join(f"• {a}" for a in plan.assumptions),
+                            title="Assumptions", border_style="yellow"))
+
+
+# ------------------------------------------------------------------------ run
+@app.command()
+def run(
+    task: str = typer.Argument(..., help="The task/assignment in natural language."),
+    provider: Optional[str] = typer.Option(None, help=f"One of: {', '.join(PROVIDERS)}"),
+    model: Optional[str] = typer.Option(None, help="Model id (defaults per provider)."),
+    api_key: Optional[str] = typer.Option(None, help="API key (else read from env/.env)."),
+    workspace: Path = typer.Option(Path.cwd(), help="Repo to operate on."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-approve the plan."),
+    no_approval: bool = typer.Option(False, help="Disable the approval gate entirely."),
+    max_steps: Optional[int] = typer.Option(None, help="Cap on plan steps executed."),
+    auto_commit: bool = typer.Option(False, help="git-commit after each successful step."),
+    temperature: Optional[float] = typer.Option(None, help="Sampling temperature."),
+) -> None:
+    """Plan and execute a coding task autonomously."""
+    load_dotenv(workspace / ".env")
+    load_dotenv()  # also pick up CWD/home .env
+
+    overrides = {
+        "provider": provider,
+        "model": model,
+        "max_steps": max_steps,
+        "temperature": temperature,
+        "require_plan_approval": False if no_approval else None,
+        "auto_commit": True if auto_commit else None,
+    }
+    cfg = AgentConfig.load(workspace=workspace, overrides=overrides)
+
+    try:
+        deps = _build_deps(cfg, api_key)
+    except LLMConfigError as exc:
+        console.print(f"[bold red]Config error:[/] {exc}")
+        raise typer.Exit(code=2)
+
+    console.print(Panel(
+        f"[bold]{task}[/]\n\n"
+        f"provider=[cyan]{cfg.provider}[/] model=[cyan]{deps.llm.model}[/]  "
+        f"workspace=[dim]{cfg.workspace}[/]",
+        title="Autonomous Agent", border_style="blue",
+    ))
+
+    interactive = sys.stdin.isatty() and not yes and not no_approval and cfg.require_plan_approval
+    graph = build_graph(deps, interrupt_for_approval=True)
+    thread = {"configurable": {"thread_id": "main"},
+              "recursion_limit": max(60, cfg.max_steps * 3 + 30)}
+
+    state = new_state(task, str(cfg.workspace))
+    try:
+        graph.invoke(state, thread)  # runs context + planning, then interrupts
+    except LLMConfigError as exc:
+        console.print(f"[bold red]LLM error:[/] {exc}")
+        raise typer.Exit(code=2)
+
+    snapshot = graph.get_state(thread)
+    if "approval" in (snapshot.next or ()):
+        plan = Plan.model_validate(snapshot.values["plan"])
+        _render_plan(plan)
+        approved = True
+        if interactive:
+            approved = Confirm.ask("Approve this plan and begin execution?", default=True)
+        graph.update_state(thread, {"plan_approved": approved})
+
+    # Resume to completion (handles approved, rejected, and failed-planning paths).
+    final = graph.invoke(None, thread)
+    _finish(final, deps)
+
+
+def _finish(final: dict, deps: Deps) -> None:
+    phase = final.get("phase")
+    if final.get("report"):
+        console.print(Panel(Markdown(final["report"]), title="Final Report",
+                            border_style="green"))
+    if phase == "halted":
+        console.print(Panel(final.get("halt_reason", "halted"),
+                            title="Halted", border_style="red"))
+
+    tu = final.get("token_usage", {})
+    console.print(
+        f"[dim]tokens: prompt={tu.get('prompt_tokens', 0)} "
+        f"completion={tu.get('completion_tokens', 0)} "
+        f"total={tu.get('total_tokens', 0)} | "
+        f"plan: {deps.plan_store.md_path}[/]"
+    )
+    verdict = final.get("verification", {})
+    if verdict and not verdict.get("passed", False):
+        raise typer.Exit(code=1)
+
+
+# ------------------------------------------------------------------ providers
+@app.command()
+def providers() -> None:
+    """List supported LLM providers and whether a key is configured."""
+    load_dotenv()
+    avail = available_providers()
+    table = Table(title="LLM Providers", header_style="bold")
+    table.add_column("Provider", style="cyan")
+    table.add_column("Default model")
+    table.add_column("Key env var")
+    table.add_column("Ready", justify="center")
+    for name, spec in PROVIDERS.items():
+        ready = "[green]ready[/]" if avail[name] else "[dim]-[/]"
+        table.add_row(name, spec.default_model, spec.key_env or "(none)", ready)
+    console.print(table)
+
+
+@app.command("plan-show")
+def plan_show(workspace: Path = typer.Option(Path.cwd())) -> None:
+    """Print the persisted plan for a workspace, if any."""
+    store = PlanStore((workspace / ".agent"))
+    if not store.exists():
+        console.print("[yellow]No plan found in .agent/[/]")
+        raise typer.Exit(code=1)
+    console.print(Markdown(store.load().to_markdown()))
+
+
+if __name__ == "__main__":
+    app()

auzek/config.py

@@ -0,0 +1,92 @@
+"""Runtime configuration for the agent.
+
+Resolution order (highest priority first):
+    1. Explicit CLI flags
+    2. Environment variables (AGENT_*)
+    3. config.yaml in the working directory
+    4. Hard-coded defaults below
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field
+
+DEFAULT_DENY_GLOBS = [
+    ".git/**",
+    "**/.env",
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/__pycache__/**",
+    "**/dist/**",
+    "**/build/**",
+]
+
+
+class AgentConfig(BaseModel):
+    """All knobs that control a single agent run."""
+
+    # --- Model selection ---
+    provider: str = "anthropic"
+    model: str = "claude-sonnet-4-6"
+    temperature: float = 0.0
+    max_tokens: int = 8192
+
+    # --- Behaviour ---
+    max_recovery_attempts: int = 3
+    max_steps: int = 40
+    auto_commit: bool = False
+    require_plan_approval: bool = True
+
+    # --- Verification commands (auto-detected when blank) ---
+    test_command: str = ""
+    lint_command: str = ""
+    typecheck_command: str = ""
+
+    # --- Safety ---
+    deny_globs: list[str] = Field(default_factory=lambda: list(DEFAULT_DENY_GLOBS))
+
+    # --- Paths (filled in at load time) ---
+    workspace: Path = Field(default_factory=Path.cwd)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @classmethod
+    def load(
+        cls,
+        workspace: Path | None = None,
+        overrides: dict[str, Any] | None = None,
+    ) -> "AgentConfig":
+        """Build a config from yaml + env + overrides."""
+        workspace = (workspace or Path.cwd()).resolve()
+        data: dict[str, Any] = {}
+
+        # 1. config.yaml
+        cfg_path = workspace / "config.yaml"
+        if cfg_path.exists():
+            loaded = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
+            data.update({k: v for k, v in loaded.items() if v not in (None, "")})
+
+        # 2. environment variables (AGENT_PROVIDER, AGENT_MODEL, ...)
+        for field in cls.model_fields:
+            env_key = f"AGENT_{field.upper()}"
+            if env_key in os.environ and os.environ[env_key] != "":
+                data[field] = os.environ[env_key]
+
+        # 3. explicit overrides (CLI)
+        if overrides:
+            data.update({k: v for k, v in overrides.items() if v is not None})
+
+        data["workspace"] = workspace
+        return cls(**data)
+
+    @property
+    def state_dir(self) -> Path:
+        """Where the agent persists its plan and run state."""
+        d = self.workspace / ".agent"
+        d.mkdir(exist_ok=True)
+        return d

auzek/graph.py

@@ -0,0 +1,94 @@
+"""Assemble the agent as a LangGraph state machine.
+
+Flow:
+    context → planning → [approval gate] → execution ⇄ recovery → verification → report
+
+Conditional edges route on ``state['phase']`` so the same execution node can loop
+over many steps, and recovery can loop until it succeeds or hits its attempt cap.
+A checkpointer + interrupt after planning lets the CLI insert human approval.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, START, StateGraph
+
+from .nodes import (
+    context_node,
+    execution_node,
+    planning_node,
+    recovery_node,
+    report_node,
+    verification_node,
+)
+from .nodes.approval import approval_node
+from .runtime import Deps
+from .state import AgentState
+
+
+# --------------------------------------------------------------------- routers
+def _after_planning(state: AgentState) -> str:
+    return "report_node" if state.get("phase") == "halted" else "approval"
+
+
+def _after_approval(state: AgentState) -> str:
+    return "execution" if state.get("phase") == "execution" else "report_node"
+
+
+def _after_execution(state: AgentState) -> str:
+    phase = state.get("phase")
+    if phase == "recovery":
+        return "recovery"
+    if phase == "verification":
+        return "verify"
+    if phase == "halted":
+        return "report_node"
+    return "execution"  # more steps remain
+
+
+def _after_recovery(state: AgentState) -> str:
+    phase = state.get("phase")
+    if phase == "execution":
+        return "execution"
+    if phase == "verification":
+        return "verify"
+    if phase == "halted":
+        return "report_node"
+    return "recovery"  # keep trying (attempt cap enforced inside the node)
+
+
+def build_graph(deps: Deps, *, interrupt_for_approval: bool = True):
+    """Compile the agent graph bound to a set of dependencies."""
+    g = StateGraph(AgentState)
+
+    g.add_node("context", partial(context_node, deps=deps))
+    g.add_node("planning", partial(planning_node, deps=deps))
+    g.add_node("approval", partial(approval_node, deps=deps))
+    g.add_node("execution", partial(execution_node, deps=deps))
+    g.add_node("recovery", partial(recovery_node, deps=deps))
+    g.add_node("verify", partial(verification_node, deps=deps))
+    g.add_node("report_node", partial(report_node, deps=deps))
+
+    g.add_edge(START, "context")
+    g.add_edge("context", "planning")
+    g.add_conditional_edges("planning", _after_planning,
+                            {"approval": "approval", "report_node": "report_node"})
+    g.add_conditional_edges("approval", _after_approval,
+                            {"execution": "execution", "report_node": "report_node"})
+    g.add_conditional_edges("execution", _after_execution,
+                            {"execution": "execution", "recovery": "recovery",
+                             "verify": "verify", "report_node": "report_node"})
+    g.add_conditional_edges("recovery", _after_recovery,
+                            {"execution": "execution", "recovery": "recovery",
+                             "verify": "verify", "report_node": "report_node"})
+    g.add_edge("verify", "report_node")
+    g.add_edge("report_node", END)
+
+    checkpointer = MemorySaver()
+    compile_kwargs = {"checkpointer": checkpointer}
+    if interrupt_for_approval:
+        # Pause after planning so a human can approve the plan before any edits.
+        compile_kwargs["interrupt_after"] = ["planning"]
+    return g.compile(**compile_kwargs)

auzek/llm.py

@@ -0,0 +1,183 @@
+"""Multi-provider LLM gateway.
+
+Built on LiteLLM so a single code path talks to Anthropic, OpenAI, Groq,
+Google, Mistral, DeepSeek and local Ollama models. Users supply their own
+API keys via environment variables (.env) or the CLI.
+
+The rest of the agent only ever sees `LLM.chat(...)` and a normalized
+`LLMResponse`, so swapping providers never touches node logic.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+import litellm
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+# Don't let LiteLLM phone home or spam logs.
+litellm.telemetry = False
+litellm.drop_params = True  # silently drop params a given provider doesn't support
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    """How to reach a provider: the LiteLLM prefix and the env var for its key."""
+
+    prefix: str            # LiteLLM model prefix, e.g. "groq"
+    key_env: str           # env var holding the API key, e.g. "GROQ_API_KEY"
+    default_model: str     # a sensible default model id for this provider
+    needs_key: bool = True
+
+
+# Friendly provider name -> how to call it. Add new providers here only.
+PROVIDERS: dict[str, ProviderSpec] = {
+    "anthropic": ProviderSpec("anthropic", "ANTHROPIC_API_KEY", "claude-sonnet-4-6"),
+    "openai": ProviderSpec("openai", "OPENAI_API_KEY", "gpt-4o"),
+    "groq": ProviderSpec("groq", "GROQ_API_KEY", "llama-3.3-70b-versatile"),
+    "google": ProviderSpec("gemini", "GEMINI_API_KEY", "gemini-1.5-pro"),
+    "mistral": ProviderSpec("mistral", "MISTRAL_API_KEY", "mistral-large-latest"),
+    "deepseek": ProviderSpec("deepseek", "DEEPSEEK_API_KEY", "deepseek-chat"),
+    "ollama": ProviderSpec("ollama", "", "qwen2.5-coder:7b", needs_key=False),
+}
+
+
+class LLMConfigError(RuntimeError):
+    """Raised when a provider/model/key combination is unusable."""
+
+
+@dataclass
+class LLMResponse:
+    """Normalized model response."""
+
+    content: str
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    finish_reason: str = "stop"
+    usage: dict[str, int] = field(default_factory=dict)
+    raw: Any = None
+
+    @property
+    def wants_tools(self) -> bool:
+        return bool(self.tool_calls)
+
+
+class LLM:
+    """A thin, provider-agnostic chat client with tool-calling support."""
+
+    def __init__(
+        self,
+        provider: str,
+        model: str | None = None,
+        *,
+        temperature: float = 0.0,
+        max_tokens: int = 8192,
+        api_key: str | None = None,
+    ) -> None:
+        provider = provider.lower().strip()
+        if provider not in PROVIDERS:
+            raise LLMConfigError(
+                f"Unknown provider '{provider}'. "
+                f"Choose one of: {', '.join(PROVIDERS)}"
+            )
+        self.provider = provider
+        self.spec = PROVIDERS[provider]
+        self.model = model or self.spec.default_model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.api_key = api_key or os.environ.get(self.spec.key_env) or None
+
+        if self.spec.needs_key and not self.api_key:
+            raise LLMConfigError(
+                f"No API key for provider '{provider}'. "
+                f"Set {self.spec.key_env} in your environment / .env, "
+                f"or pass --api-key."
+            )
+
+    @property
+    def model_string(self) -> str:
+        """LiteLLM-style 'prefix/model'. Avoids double-prefixing."""
+        if self.model.startswith(f"{self.spec.prefix}/"):
+            return self.model
+        return f"{self.spec.prefix}/{self.model}"
+
+    def _extra_kwargs(self) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {}
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+        if self.provider == "ollama":
+            kwargs["api_base"] = os.environ.get("OLLAMA_API_BASE", "http://localhost:11434")
+        return kwargs
+
+    @retry(
+        retry=retry_if_exception_type(
+            (litellm.RateLimitError, litellm.APIConnectionError, litellm.Timeout)
+        ),
+        wait=wait_exponential(multiplier=2, min=2, max=30),
+        stop=stop_after_attempt(4),
+        reraise=True,
+    )
+    def chat(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        tool_choice: str | None = None,
+        temperature: float | None = None,
+    ) -> LLMResponse:
+        """Send a chat completion request and normalize the response."""
+        call_kwargs: dict[str, Any] = {
+            "model": self.model_string,
+            "messages": messages,
+            "temperature": self.temperature if temperature is None else temperature,
+            "max_tokens": self.max_tokens,
+            **self._extra_kwargs(),
+        }
+        if tools:
+            call_kwargs["tools"] = tools
+            call_kwargs["tool_choice"] = tool_choice or "auto"
+
+        try:
+            resp = litellm.completion(**call_kwargs)
+        except litellm.AuthenticationError as exc:  # bad/expired key
+            raise LLMConfigError(
+                f"Authentication failed for '{self.provider}'. Check {self.spec.key_env}."
+            ) from exc
+
+        choice = resp.choices[0]
+        msg = choice.message
+
+        tool_calls: list[dict[str, Any]] = []
+        for tc in getattr(msg, "tool_calls", None) or []:
+            tool_calls.append(
+                {
+                    "id": tc.id,
+                    "name": tc.function.name,
+                    "arguments": tc.function.arguments,  # JSON string
+                }
+            )
+
+        usage = {}
+        if getattr(resp, "usage", None):
+            usage = {
+                "prompt_tokens": resp.usage.prompt_tokens or 0,
+                "completion_tokens": resp.usage.completion_tokens or 0,
+                "total_tokens": resp.usage.total_tokens or 0,
+            }
+
+        return LLMResponse(
+            content=msg.content or "",
+            tool_calls=tool_calls,
+            finish_reason=choice.finish_reason or "stop",
+            usage=usage,
+            raw=resp,
+        )
+
+
+def available_providers() -> dict[str, bool]:
+    """Map provider name -> whether a usable API key is present."""
+    out: dict[str, bool] = {}
+    for name, spec in PROVIDERS.items():
+        out[name] = (not spec.needs_key) or bool(os.environ.get(spec.key_env))
+    return out

auzek/memory/__init__.py

@@ -0,0 +1 @@
+"""Durable agent memory: the plan and run state that survive crashes."""