daveloop 1.4.0__tar.gz → 1.5.0__tar.gz

daveloop-1.5.0/PKG-INFO

@@ -0,0 +1,392 @@
+Metadata-Version: 2.1
+Name: daveloop
+Version: 1.5.0
+Summary: Self-healing debug agent powered by Claude Code CLI
+Home-page: https://github.com/davebruzil/DaveLoop
+Author: Dave Bruzil
+Keywords: debugging ai claude automation agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# DaveLoop
+
+<img width="842" height="258" alt="DaveLoop Banner" src="https://github.com/user-attachments/assets/97212a83-6eb9-43ed-95c7-ec236718ee16" />
+
+### The agent that doesn't quit until the job is done.
+
+**DaveLoop** is a self-healing autonomous agent powered by LLM-driven iterative reasoning. It was designed for debugging. Then it started building features, writing test suites, fixing production workflows, and improving its own source code -- all without being asked.
+
+You give it a problem. It reasons, hypothesizes, executes, verifies, and loops until the problem is gone. No hand-holding. No copy-pasting context between retries. No pressing "approve" every 10 seconds. It just works.
+
+```bash
+pip install daveloop
+```
+
+---
+
+## What DaveLoop Has Actually Done
+
+This isn't a toy demo. These are real, logged, verifiable results from DaveLoop running autonomously.
+
+### It Upgraded Itself
+
+DaveLoop was given a feature request file and told to add capabilities to its own codebase. It read its own source code, understood the architecture, and implemented 4 major features:
+
+- **TaskQueue** -- multi-bug sequential processing with status tracking
+- **Session Memory** -- persistent history across runs via `.daveloop_history.json`
+- **InputMonitor** -- real-time interrupt system (type `wait` mid-execution to redirect it)
+- **Multi-task CLI** -- queue multiple bugs in one command
+
+It verified the syntax, tested the integration, and resolved. One session. Its own codebase. No guidance.
+
+### It Built a Complete Mobile Test Suite From Scratch
+
+Pointed at an Android Dog Dating app on an emulator, DaveLoop:
+
+1. Located and installed the APK autonomously
+2. Dumped the UI hierarchy with `uiautomator` to understand the screen layout
+3. Read the Kotlin source files to understand data models and navigation
+4. Discovered the Room DB seeds 10 mock dog profiles on fresh install
+5. **Wrote 3 comprehensive Maestro YAML test flows:**
+   - Swipe card functionality (left/right swipe with profile progression)
+   - Matches vs Chat screen separation (distinct bottom nav destinations)
+   - Chat recipient verification (message send and display)
+6. Ran all tests 3 consecutive times -- all passed
+
+**One iteration. Zero human input. From APK to passing test suite.**
+
+### It Debugged a Production n8n Workflow
+
+A WhatsApp webhook integration was returning 500 errors on every request. Hebrew and English messages both failing. DaveLoop:
+
+- Traced the data flow through the entire n8n workflow JSON
+- Found Bug #1: incorrect nested path `webhookData.data.messages` instead of `webhookData.data.messages.message`
+- Found Bug #2: the `If2` node was reading from MongoDB output (`$json.body`) instead of referencing the webhook node directly
+- Fixed both, preserving the Hebrew goodbye detection logic that was actually correct
+- Generated a test script and deployment guide
+
+Two bugs, both data structure traversal errors buried in a multi-node workflow. Found and fixed.
+
+### It Solved a Django ORM Bug in One Iteration
+
+Running against [SWE-bench](https://www.swebench.com/), DaveLoop resolved `django__django-13321` -- a real bug from the Django issue tracker -- in a single iteration. 5 minutes from start to `[DAVELOOP:RESOLVED]`.
+
+```json
+{
+  "instance_id": "django__django-13321",
+  "repo": "django/django",
+  "resolved": true,
+  "iterations": 1
+}
+```
+
+### It Fixed a Bug in tqdm (47k+ GitHub Stars)
+
+A `ZeroDivisionError` when `total=0`. DaveLoop explored the entire tqdm codebase, traced all division operations across multiple files, identified that `if total:` was treating `0` the same as `None`, and applied a targeted fix. One iteration.
+
+---
+
+## How It Works
+
+```
+You describe the bug
+       |
+       v
+  DaveLoop injects a reasoning protocol into the LLM
+       |
+       v
+  The agent analyzes: KNOWN / UNKNOWN / HYPOTHESIS / NEXT ACTION
+       |
+       v
+  Executes the fix, runs verification
+       |
+       v
+  Not fixed? Loop again with full context (--continue)
+       |
+       v
+  Fixed? --> [DAVELOOP:RESOLVED]
+  Stuck? --> [DAVELOOP:BLOCKED] (documents what it tried)
+```
+
+The key insight: even the best coding agents sometimes need multiple attempts for complex bugs. DaveLoop automates that retry loop with persistent context and structured reasoning, so each iteration builds on everything the agent already learned.
+
+---
+
+## The 4-Level Reasoning Protocol
+
+![Reasoning Example](https://github.com/user-attachments/assets/a1bbd83a-27f2-4543-9d48-ef089b3cbd75)
+
+Every iteration, DaveLoop forces the agent to state:
+
+| Level | Purpose |
+|-------|---------|
+| **KNOWN** | What facts have been established so far |
+| **UNKNOWN** | What gaps remain |
+| **HYPOTHESIS** | A testable guess about the root cause |
+| **NEXT ACTION** | The concrete step to test that hypothesis |
+
+This prevents random shotgun debugging. Each iteration's KNOWN section grows. The UNKNOWN list shrinks or shifts focus. You can watch the agent systematically close in on the bug in real time.
+
+---
+
+## Install
+
+```bash
+pip install daveloop
+```
+
+Zero external dependencies. Python 3.7+ and an LLM CLI agent.
+
+---
+
+## Use It Straight From Chat
+
+After installing, paste the following block into your global agent instructions file (the markdown file your coding agent reads for project instructions). This lets you trigger DaveLoop by just talking naturally in chat -- no terminal switching needed.
+
+<details>
+<summary><b>Click to expand -- copy this into your global agent instructions file</b></summary>
+
+```markdown
+## DaveLoop - Self-Healing Debug Agent
+
+DaveLoop is a Python wrapper that runs the coding agent in a loop until bugs are resolved. It keeps iterating until the issue is fixed.
+
+### Basic Commands
+
+\`\`\`bash
+# Basic usage - describe the bug directly
+daveloop "your bug description here"
+
+# Specify working directory
+daveloop -d /path/to/project "bug description"
+
+# Set max iterations (default is unlimited until resolved)
+daveloop -m 10 "bug description"
+
+# Read bug description from a file
+daveloop -f error.txt
+
+# Verbose output for debugging
+daveloop -v "bug description"
+\`\`\`
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-h, --help` | Show help message |
+| `-f, --file FILE` | Read bug description from file |
+| `-d, --dir DIR` | Working directory |
+| `-m, --max-iterations N` | Maximum iterations before stopping |
+| `-v, --verbose` | Enable verbose output |
+
+### How It Works
+
+1. DaveLoop sends your bug description to the coding agent
+2. The agent analyzes, hypothesizes, and attempts fixes
+3. Runs verification (build/tests)
+4. If not resolved, DaveLoop loops back with updated context
+5. Continues until `[DAVELOOP:RESOLVED]` or max iterations reached
+
+### Giving DaveLoop a Command via Chat
+
+When the user says "daveloop this" or "run daveloop" with a task, run:
+
+\`\`\`bash
+daveloop "the bug description here"
+
+# Or with a specific project directory:
+daveloop -d /path/to/project "the bug description"
+\`\`\`
+```
+
+</details>
+
+Once that's in your agent instructions file, just say:
+
+```
+daveloop this: "mongodb connection error in the lookup node"
+```
+
+or
+
+```
+run daveloop on the jwt validation bug
+```
+
+The agent picks it up and runs DaveLoop automatically. No special syntax.
+
+---
+
+## Usage
+
+### Give it a bug
+
+```bash
+daveloop "routes/order.ts has a race condition on wallet balance. two concurrent orders overdraw the account"
+```
+
+### Give it a file
+
+```bash
+daveloop --file bug-report.txt
+```
+
+### Queue multiple bugs
+
+```bash
+daveloop "fix the login crash" "fix payment validation" "add dark mode toggle"
+```
+
+### Point it at a project
+
+```bash
+daveloop --dir /path/to/project "the bug description"
+```
+
+### Limit iterations
+
+```bash
+daveloop --max-iterations 10 "fix the bug"
+```
+
+### Mobile testing mode (Maestro)
+
+```bash
+daveloop --maestro "write UI tests for the onboarding flow"
+```
+
+### Web testing mode (Playwright)
+
+```bash
+daveloop --web "test the checkout flow end to end"
+```
+
+---
+
+## Interactive Controls
+
+DaveLoop doesn't lock you out. While it's running, type:
+
+| Command | What happens |
+|---------|-------------|
+| `wait` / `pause` | Stops the current iteration. You type a correction. It resumes with your new context. |
+| `add` | Queue a new bug without stopping the current one |
+| `done` | Graceful exit, saves history |
+| `Ctrl+C` | Kill it |
+
+The `wait` command is the standout feature. When you see the agent going down the wrong path, type `wait`, tell it what you know, and it course-corrects with full context preserved.
+
+---
+
+## Three Modes
+
+### Standard Mode (default)
+Classic iterative debugging. Reads code, makes hypotheses, applies fixes, verifies.
+
+### Maestro Mode (`--maestro`)
+Autonomous mobile UI testing. Auto-detects devices/emulators, installs APKs, explores UI hierarchy, writes Maestro YAML test flows, and verifies with 3 consecutive passes.
+
+### Web Mode (`--web`)
+Playwright-based web testing. Detects your framework (React, Next.js, Vue, etc.), installs Playwright, starts dev servers, and tests with human-like interactions -- real mouse movements, drags, hovers, not just DOM manipulation.
+
+---
+
+## Session Memory
+
+DaveLoop remembers. It saves a history of past sessions in `.daveloop_history.json` and loads that context into future runs. If it fixed a similar bug before, it knows.
+
+---
+
+## SWE-bench Integration
+
+Test DaveLoop against real-world bugs from open source projects:
+
+```bash
+daveloop-swebench --file django_hash_task.json --max-iterations 15
+```
+
+Pre-configured tasks from Django, Pytest, SymPy, and Sklearn included.
+
+---
+
+## Battle-Tested On
+
+| Domain | What it solved |
+|--------|---------------|
+| **Security** | Juice-Shop race conditions, NoSQL injection, ReDoS, path traversal |
+| **Backend** | Django ORM bugs, session handling crashes |
+| **Workflow Automation** | n8n webhook failures, MongoDB connection errors, multi-node data flow bugs |
+| **Testing Frameworks** | Pytest AST rewriting issues, Material-UI flaky visual regression tests |
+| **Libraries** | tqdm ZeroDivisionError, SymPy C-code generation |
+| **Mobile** | Android Maestro test suite generation from scratch |
+| **Self** | Added features to its own codebase autonomously |
+
+---
+
+## Writing Good Bug Descriptions
+
+More context = fewer iterations.
+
+**Vague (works, but slow):**
+```bash
+daveloop "fix the bug"
+```
+
+**Specific (fast):**
+```bash
+daveloop "RACE CONDITION: routes/order.ts lines 139-148. Balance check at 141 before decrement at 142. Two concurrent $100 orders both pass and overdraw to -$100. Need atomic check+decrement."
+```
+
+Include: bug type, file location, reproduction steps, root cause if known, fix direction if you have one.
+
+---
+
+## Logs
+
+Every session is fully logged:
+
+```
+logs/
+  20260131_142120_iteration_01.log    <- what it tried
+  20260131_142120_iteration_02.log    <- what it tried next
+  20260131_142120_summary.md          <- overview
+```
+
+Every reasoning block, every file read, every edit, every command. Full audit trail.
+
+---
+
+## Why DaveLoop Exists
+
+Some bugs don't fall in one shot. Race conditions. Multi-file refactors. Subtle logic errors buried in nested data structures. Production workflows with 12 interconnected nodes.
+
+DaveLoop wraps your coding agent in a persistence layer -- structured reasoning, iterative context, session memory, and the stubbornness to keep going until the job is done or honestly admit it's stuck.
+
+It started as a debug loop. It turned out to be something more.
+
+---
+
+## License
+
+MIT
+
+---
+
+**Built by [Dave Bruzil](https://github.com/davebruzil)**
+
+```bash
+pip install daveloop
+```