auzek 0.1.0__tar.gz

auzek-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: auzek
+Version: 0.1.0
+Summary: Auzek — an autonomous coding agent that plans, executes, self-verifies and self-heals across multiple LLM providers.
+Author: Azaan (Auzek)
+License: MIT
+Keywords: ai,agent,autonomous,coding-agent,llm,langgraph,groq,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langgraph>=0.2.40
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: litellm>=1.51.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pathspec>=0.12
+Requires-Dist: tenacity>=8.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# Auzek
+
+> An autonomous coding agent by **Azaan (Auzek)**.
+
+**Auzek** is an autonomous coding agent that **understands the repo, plans before
+it codes, executes one step at a time, verifies its own work, and self-heals on
+failure** before moving on. It runs on **any major LLM provider** — bring your own
+API key (Anthropic, OpenAI, **Groq**, Google, Mistral, DeepSeek, or local Ollama).
+
+It is built on **LangGraph** (orchestration) and **LiteLLM** (provider gateway).
+
+```bash
+pip install auzek
+auzek run "add input validation to the /signup endpoint" --provider groq
+```
+
+---
+
+## Why it's different from a "blind" coding bot
+
+| Naive agent | This agent |
+|---|---|
+| Starts editing immediately | **Onboards** to the repo first (stack, tests, layout, git history) |
+| Holds the plan in context | Writes the plan to **disk** (`.agent/plan.md`) — survives crashes |
+| "Looks done" after writing | Marks a step done only **after running its verification** |
+| Retries forever | **Hard stop** after N recovery attempts, then escalates |
+| One giant change | **Atomic steps**, optionally **micro-committed** |
+| "Done" = code written | "Done" = full test/lint/typecheck pass + diff reviewed vs. the task |
+
+---
+
+## The lifecycle (a LangGraph state machine)
+
+```
+context → planning → [human approval] → execution ⇄ recovery → verification → report
+```
+
+1. **Context** – lists/reads files, searches code, reads git history → a briefing.
+2. **Planning** – emits a structured, ordered, atomic plan (`submit_plan` tool).
+3. **Approval** – optional human gate (pause/approve the plan).
+4. **Execution** – implements **one** step, then **runs its verification**.
+5. **Recovery** – on failure, widens investigation and retries (capped).
+6. **Verification** – runs the full suite, reviews the whole diff vs. the task.
+7. **Report** – writes an honest `.agent/report.md`.
+
+State and plan live in `.agent/` so a run is inspectable and resumable.
+
+---
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install auzek
+
+# or with pipx so the `auzek` command is globally available, isolated
+pipx install auzek
+```
+
+From source (for development):
+
+```bash
+cd Autonomous_Agent
+python -m venv .venv && . .venv/Scripts/activate   # Windows
+# or:  source .venv/bin/activate                    # macOS/Linux
+pip install -e .
+```
+
+## Configure keys
+
+```bash
+cp .env.example .env
+# fill in the provider(s) you use, e.g. GROQ_API_KEY=...
+```
+
+Check what's wired up:
+
+```bash
+auzek providers
+```
+
+## Run
+
+```bash
+# operate on the current repo
+auzek run "Add input validation to the /signup endpoint and a test for it"
+
+# pick a provider/model explicitly (Groq example)
+auzek run "Refactor utils.py to remove the duplicated date parsing" \
+    --provider groq --model llama-3.3-70b-versatile
+
+# point at another repo, auto-approve the plan, micro-commit each step
+auzek run "Fix the failing login test" \
+    --workspace ../my-project --yes --auto-commit
+```
+
+Useful flags: `--provider`, `--model`, `--api-key`, `--workspace`, `--yes`
+(auto-approve), `--no-approval`, `--max-steps`, `--auto-commit`, `--temperature`.
+
+Inspect the plan any time:
+
+```bash
+auzek plan-show --workspace ../my-project
+```
+
+---
+
+## Configuration (`config.yaml`)
+
+Verification commands auto-detect when blank; set them to be explicit:
+
+```yaml
+provider: anthropic
+model: claude-sonnet-4-6
+max_recovery_attempts: 3
+max_steps: 40
+auto_commit: false
+require_plan_approval: true
+test_command: "pytest -q"
+lint_command: "ruff check ."
+typecheck_command: "mypy ."
+```
+
+Resolution order: **CLI flags > env vars (`AGENT_*`) > `config.yaml` > defaults**.
+
+---
+
+## Project layout
+
+```
+src/auzek/
+  cli.py            # Typer CLI, approval gate, output
+  config.py         # layered config
+  llm.py            # multi-provider gateway (LiteLLM) + key handling
+  runtime.py        # shared deps + the core tool-calling loop
+  state.py          # LangGraph state schema
+  graph.py          # the state machine (nodes + conditional edges)
+  prompts.py        # per-phase system prompts
+  memory/plan_store.py   # the durable plan (json + markdown)
+  tools/            # read/write/edit, list, search, shell, git
+  nodes/            # context, planning, approval, execution, recovery,
+                    # verification, report
+```
+
+---
+
+## Adding a provider
+
+Add one line to `PROVIDERS` in [llm.py](src/auzek/llm.py):
+
+```python
+"xai": ProviderSpec("xai", "XAI_API_KEY", "grok-2-latest"),
+```
+
+LiteLLM handles the wire format; nothing else changes.
+
+---
+
+## Safety
+
+- All file access is sandboxed to the workspace; `deny_globs` blocks `.env`,
+  `.git`, `node_modules`, etc.
+- The shell tool has a destructive-command guardrail and output/time limits —
+  but it is **not** a security boundary. For untrusted tasks, run in a
+  container or VM.
+
+---
+
+## A note on SWE-bench / "beating" other models
+
+This is a strong, production-shaped **harness**. On agentic benchmarks the
+score is dominated by (a) the underlying model and (b) harness discipline —
+plan/verify/self-heal loops, tight diffs, real test execution — all of which
+this implements. To actually measure it, wire `auzek run` to the SWE-bench
+task format (clone repo at the given commit, feed the issue as the task, export
+the resulting `git diff` as the prediction patch) and run the official
+evaluation. Treat any ranking as something you **measure**, not assume.
+```
+```
+
+## License
+
+MIT

auzek-0.1.0/README.md

@@ -0,0 +1,183 @@
+# Auzek
+
+> An autonomous coding agent by **Azaan (Auzek)**.
+
+**Auzek** is an autonomous coding agent that **understands the repo, plans before
+it codes, executes one step at a time, verifies its own work, and self-heals on
+failure** before moving on. It runs on **any major LLM provider** — bring your own
+API key (Anthropic, OpenAI, **Groq**, Google, Mistral, DeepSeek, or local Ollama).
+
+It is built on **LangGraph** (orchestration) and **LiteLLM** (provider gateway).
+
+```bash
+pip install auzek
+auzek run "add input validation to the /signup endpoint" --provider groq
+```
+
+---
+
+## Why it's different from a "blind" coding bot
+
+| Naive agent | This agent |
+|---|---|
+| Starts editing immediately | **Onboards** to the repo first (stack, tests, layout, git history) |
+| Holds the plan in context | Writes the plan to **disk** (`.agent/plan.md`) — survives crashes |
+| "Looks done" after writing | Marks a step done only **after running its verification** |
+| Retries forever | **Hard stop** after N recovery attempts, then escalates |
+| One giant change | **Atomic steps**, optionally **micro-committed** |
+| "Done" = code written | "Done" = full test/lint/typecheck pass + diff reviewed vs. the task |
+
+---
+
+## The lifecycle (a LangGraph state machine)
+
+```
+context → planning → [human approval] → execution ⇄ recovery → verification → report
+```
+
+1. **Context** – lists/reads files, searches code, reads git history → a briefing.
+2. **Planning** – emits a structured, ordered, atomic plan (`submit_plan` tool).
+3. **Approval** – optional human gate (pause/approve the plan).
+4. **Execution** – implements **one** step, then **runs its verification**.
+5. **Recovery** – on failure, widens investigation and retries (capped).
+6. **Verification** – runs the full suite, reviews the whole diff vs. the task.
+7. **Report** – writes an honest `.agent/report.md`.
+
+State and plan live in `.agent/` so a run is inspectable and resumable.
+
+---
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install auzek
+
+# or with pipx so the `auzek` command is globally available, isolated
+pipx install auzek
+```
+
+From source (for development):
+
+```bash
+cd Autonomous_Agent
+python -m venv .venv && . .venv/Scripts/activate   # Windows
+# or:  source .venv/bin/activate                    # macOS/Linux
+pip install -e .
+```
+
+## Configure keys
+
+```bash
+cp .env.example .env
+# fill in the provider(s) you use, e.g. GROQ_API_KEY=...
+```
+
+Check what's wired up:
+
+```bash
+auzek providers
+```
+
+## Run
+
+```bash
+# operate on the current repo
+auzek run "Add input validation to the /signup endpoint and a test for it"
+
+# pick a provider/model explicitly (Groq example)
+auzek run "Refactor utils.py to remove the duplicated date parsing" \
+    --provider groq --model llama-3.3-70b-versatile
+
+# point at another repo, auto-approve the plan, micro-commit each step
+auzek run "Fix the failing login test" \
+    --workspace ../my-project --yes --auto-commit
+```
+
+Useful flags: `--provider`, `--model`, `--api-key`, `--workspace`, `--yes`
+(auto-approve), `--no-approval`, `--max-steps`, `--auto-commit`, `--temperature`.
+
+Inspect the plan any time:
+
+```bash
+auzek plan-show --workspace ../my-project
+```
+
+---
+
+## Configuration (`config.yaml`)
+
+Verification commands auto-detect when blank; set them to be explicit:
+
+```yaml
+provider: anthropic
+model: claude-sonnet-4-6
+max_recovery_attempts: 3
+max_steps: 40
+auto_commit: false
+require_plan_approval: true
+test_command: "pytest -q"
+lint_command: "ruff check ."
+typecheck_command: "mypy ."
+```
+
+Resolution order: **CLI flags > env vars (`AGENT_*`) > `config.yaml` > defaults**.
+
+---
+
+## Project layout
+
+```
+src/auzek/
+  cli.py            # Typer CLI, approval gate, output
+  config.py         # layered config
+  llm.py            # multi-provider gateway (LiteLLM) + key handling
+  runtime.py        # shared deps + the core tool-calling loop
+  state.py          # LangGraph state schema
+  graph.py          # the state machine (nodes + conditional edges)
+  prompts.py        # per-phase system prompts
+  memory/plan_store.py   # the durable plan (json + markdown)
+  tools/            # read/write/edit, list, search, shell, git
+  nodes/            # context, planning, approval, execution, recovery,
+                    # verification, report
+```
+
+---
+
+## Adding a provider
+
+Add one line to `PROVIDERS` in [llm.py](src/auzek/llm.py):
+
+```python
+"xai": ProviderSpec("xai", "XAI_API_KEY", "grok-2-latest"),
+```
+
+LiteLLM handles the wire format; nothing else changes.
+
+---
+
+## Safety
+
+- All file access is sandboxed to the workspace; `deny_globs` blocks `.env`,
+  `.git`, `node_modules`, etc.
+- The shell tool has a destructive-command guardrail and output/time limits —
+  but it is **not** a security boundary. For untrusted tasks, run in a
+  container or VM.
+
+---
+
+## A note on SWE-bench / "beating" other models
+
+This is a strong, production-shaped **harness**. On agentic benchmarks the
+score is dominated by (a) the underlying model and (b) harness discipline —
+plan/verify/self-heal loops, tight diffs, real test execution — all of which
+this implements. To actually measure it, wire `auzek run` to the SWE-bench
+task format (clone repo at the given commit, feed the issue as the task, export
+the resulting `git diff` as the prediction patch) and run the official
+evaluation. Treat any ranking as something you **measure**, not assume.
+```
+```
+
+## License
+
+MIT

auzek-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auzek"
+version = "0.1.0"
+description = "Auzek — an autonomous coding agent that plans, executes, self-verifies and self-heals across multiple LLM providers."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Azaan (Auzek)" }]
+keywords = ["ai", "agent", "autonomous", "coding-agent", "llm", "langgraph", "groq", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "langgraph>=0.2.40",
+    "langchain-core>=0.3.0",
+    "litellm>=1.51.0",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "python-dotenv>=1.0",
+    "rich>=13.7",
+    "typer>=0.12",
+    "gitpython>=3.1",
+    "pathspec>=0.12",
+    "tenacity>=8.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5", "mypy>=1.10", "build>=1.2", "twine>=5.0"]
+
+[project.scripts]
+auzek = "auzek.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

auzek-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auzek-0.1.0/src/auzek/__init__.py

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

auzek-0.1.0/src/auzek/__main__.py

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

auzek-0.1.0/src/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()