Metadata-Version: 2.4
Name: autonomous-qa-agent
Version: 1.0.2
Summary: Autonomous QA Agent — scan, test, and fix any codebase automatically
License: MIT
Keywords: qa,testing,autonomous,ai,code-quality
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.28
Requires-Dist: websockets>=12.0
Requires-Dist: rich>=13.0

# QA Agent — Complete Client Guide

## What This Does

QA Agent autonomously scans your entire codebase, writes test cases for every function, runs them, finds bugs, explains them clearly, and fixes them automatically — then asks for your approval before committing anything.

**Supports:** Python, Kotlin, Java, Vert.x, JavaScript, TypeScript, Go, Rust, React, Vue, ML/AI models, and more.

---

## Prerequisites (Client Machine)

| Requirement | Version | How to install |
|-------------|---------|----------------|
| Docker Desktop | 24+ | https://docker.com/products/docker-desktop |
| Python | 3.10+ | https://python.org |
| 16GB RAM | — | For running LLM models locally |
| 20GB disk | — | For Docker images + LLM models |

> **Privacy guarantee:** Your code NEVER leaves your machine. The LLM runs locally via Ollama.

---

## Install (One Command)

```bash
# Mac / Linux / Windows WSL:
curl -fsSL https://install.qa-agent.dev | bash

# Windows (PowerShell):
irm https://install.qa-agent.dev/windows | iex
```

This automatically:
1. Checks Docker is running
2. Starts all 7 AI services in Docker
3. Downloads LLM models (qwen2.5-coder — private, runs locally)
4. Installs the `qa-agent` CLI
5. Runs a health check

---

## First Scan

```bash
# Go to your project directory
cd /path/to/your/codebase

# Run full autonomous scan
qa-agent scan .
```

**What you'll see:**
```
QA Agent — Autonomous scan
Repo: /path/to/your/codebase
Languages: all
Mode: exhaustive

[scanning]   Found 1,247 source files
[indexing]   Indexed 3,891 functions
[generating] Generated 3,891 test files (parallel, 4 workers)
[running]    2,847/3,891 tests passing
[healing]    Self-healed 891 wrong assertion values
[fixing]     Analysing 153 real failures...

┌─────────────────────────────────────────────┐
│  Bug Fix Proposal                           │
│  File: src/payment/calculator.kt            │
│  Confidence: 94%                            │
│                                             │
│  Root cause: Tax rate multiplied instead    │
│  of applied as percentage                   │
│                                             │
│  Diff:                                      │
│  - return amount * taxRate                  │
│  + return amount * (taxRate / 100.0)        │
└─────────────────────────────────────────────┘
Approve this patch? [y/N]: y

[PASS] Patch committed and verified.

╔══════════════════════════════════════════════╗
║         QA Agent — Scan Report               ║
║  Status: PASS                                ║
║  Files scanned:    1,247                     ║
║  Functions tested: 3,891                     ║
║  Tests passed:     3,891 / 3,891  (100%)     ║
║  Bugs found:       153                       ║
║  Bugs fixed:       153 / 153                 ║
║  Time:             14m 32s                   ║
║  YOUR CODEBASE IS GREEN                      ║
╚══════════════════════════════════════════════╝
```

---

## Common Commands

```bash
# Full scan (all files, all languages)
qa-agent scan .

# Only scan files changed since last commit (fast re-scan)
qa-agent scan . --changed-only

# Scan specific languages only
qa-agent scan . --lang python,kotlin,java

# CI/CD mode — auto-approve patches (no prompts)
qa-agent scan . --auto-approve

# Check system health
qa-agent doctor

# Check status of a running scan
qa-agent status <job-id>

# Approve/reject a pending patch
qa-agent approve <job-id> <patch-id>
qa-agent approve <job-id> <patch-id> --reject
```

---

## CI/CD Integration

### GitHub Actions
```yaml
name: QA Agent Scan
on: [push, pull_request]
jobs:
  qa-scan:
    runs-on: self-hosted   # needs Docker + qa-agent installed
    steps:
      - uses: actions/checkout@v4
      - name: Run QA Agent
        run: qa-agent scan . --auto-approve --output json > qa-report.json
      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: qa-report
          path: qa-report.json
```

### GitLab CI
```yaml
qa-scan:
  stage: test
  tags: [docker]
  script:
    - qa-agent scan . --auto-approve
  artifacts:
    paths: [qa-report.json]
```

---

## Configuration

Create `.qa-agent.env` in your repo root:

```env
# LLM Provider: ollama (local) | openai | anthropic
LLM_PROVIDER=ollama

# For cloud LLMs (faster, requires API key)
# LLM_PROVIDER=openai
# OPENAI_API_KEY=sk-...

# Models
TEST_GEN_MODEL=qwen2.5-coder:1.5b   # fast, for test generation
PATCH_MODEL=qwen2.5-coder:7b         # accurate, for bug fixing

# Scan behaviour
MAX_CHUNKS=1000                       # max functions to generate tests for
MAX_FIX_ATTEMPTS=3                    # LLM retry limit per bug
```

---

## Supported Languages

| Language | Test Framework | Status |
|----------|---------------|--------|
| Python | pytest | ✅ |
| Kotlin | JUnit 5 + Maven | ✅ |
| Java | JUnit 5 + Maven | ✅ |
| Vert.x (Java/Kotlin) | JUnit 5 | ✅ |
| JavaScript | Jest | ✅ |
| TypeScript | Jest | ✅ |
| Go | go test | ✅ |
| Rust | cargo test | ✅ |
| React/Vue/Svelte | Jest + Testing Library | ✅ |
| ML (PyTorch/TF) | pytest | ✅ |

---

## How It Works (Under the Hood)

```
Your codebase
      │
      ▼
  qa-agent scan .
      │
   [Brain — LangGraph AI]
      │
      ├── Scan: finds all source files (git-aware, skips unchanged)
      ├── Index: tree-sitter AST → function-level chunks → Qdrant
      ├── Generate: LLM writes positive + negative + edge-case tests
      ├── Run: executes tests in isolated Docker sandbox
      ├── Heal: fixes wrong assertion values automatically
      ├── Fix: LLM analyses real bugs → proposes patches → YOU approve
      └── Report: full summary with pass rate, bugs found/fixed
```

**Key guarantees:**
- Code stays on your machine (Ollama runs locally)
- Nothing is committed without your approval
- Re-scans only process changed files (git diff)
- Known bug patterns are cached (instant fix second time)

---

## Uninstall

```bash
# Stop and remove all containers + data
docker compose -f ~/.qa-agent/docker-compose.yml down -v

# Remove CLI
pip uninstall qa-agent

# Remove models (optional, frees ~8GB)
docker exec qa-ollama ollama rm qwen2.5-coder:7b
docker exec qa-ollama ollama rm qwen2.5-coder:1.5b
```

---

## Troubleshooting

```bash
# Check all services are running
qa-agent doctor

# View logs
docker compose logs qa-brain --tail=50
docker compose logs qa-celery --tail=50

# Restart services
docker compose restart

# Common issues:
# "Ollama not responding" → docker restart qa-ollama
# "Tests not generating" → check OLLAMA_HOST in qa-app logs
# "Scan hangs" → qa-agent status <job-id> to check phase
```
