BugZero Agent

This package implements the core BugZero Agent pipeline for automated incident resolution for Python services.

Phase 2 adds real-world integrations (Jira, Slack, GitHub PRs), a configuration system, stronger analysis/fix engines, and basic run history + analytics.

---

Quickstart

Install the package into a virtualenv:

pip install -e .

Run the pipeline against a local repo and a JSON incident:

bugzero resolve path/to/incident.json --repo /path/to/service

The CLI will:

• Clone or reuse the target repo (local path or git URL).
• Analyze the incident + codebase.
• Attempt fixes in a sandbox branch.
• Run tests/repro before/after fixes.
• Emit a Markdown report to stdout.

---

Phase 2 End-to-End Flows

Jira → BugZero → GitHub PR

1. Set Jira environment variables:

   • BUGZERO_JIRA_BASE_URL (e.g. https://your-org.atlassian.net)
   • BUGZERO_JIRA_EMAIL
   • BUGZERO_JIRA_API_TOKEN

2. Set optional GitHub PR behavior via config or env (see Configuration).

3. Run the Jira ingestion command from your workspace for the target repo:

   bugzero ingest-jira PROJ-123 \
     --repo /path/to/service \
     --run-tests-before \
     --create-pr \
     --pr-base main

4. BugZero will:

   • Fetch the Jira issue via JiraClient.from_env.
   • Convert it into an IncidentPayload via the Jira adapter.
   • Run the resolve_incident pipeline in a sandbox branch.
   • Run tests before and after fixes (using your configured test command).
   • If successful and --create-pr is set:
     • Commit the changes.
     • Push the branch and open a draft GitHub PR using the Markdown report as the body.

Slack → BugZero

1. Set Slack environment variables:

   • BUGZERO_SLACK_BOT_TOKEN

2. Locate the channel ID and message timestamp (ts) for the incident message in Slack.

3. Run:

   bugzero ingest-slack C0123456789 1700000000.123456 \
     --repo /path/to/service \
     --run-tests-before

4. BugZero will:

   • Fetch the message via SlackClient.from_env.
   • Convert it into an IncidentPayload via the Slack adapter (including thread text, logs, stack traces where possible).
   • Run the same resolve_incident pipeline you get from bugzero resolve.

Local Incident JSON → BugZero

You can also run incidents directly from a JSON payload:

bugzero resolve examples/incidents/runtime_error_example.json \
  --repo /path/to/service \
  --run-tests-before

The incident file is expected to contain a raw incident JSON object; the CLI wraps it into an IncidentPayload with source="cli".

---

Configuration

BugZero reads configuration per target repository from a bugzero.toml file at the repo root and then applies environment-variable overrides.

bugzero.toml schema

Minimal example:

[test]
command = "python -m pytest"
focused = true

[analysis]
ignore_paths = ["migrations/", "venv/", "tests/helpers/"]

[fix_limits]
max_modified_files = 1
max_diff_bytes = 24000
max_diff_lines = 400

[automation]
mode = "analysis_only" # or "guardrailed_auto", "auto_first"
max_auto_pr_per_run = 1
require_tests_for_auto_pr = true

[pr]
auto_create = false
base_branch = "main"
labels = ["bugzero", "automated-fix"]

• [test]
  • command: Shell command used to run tests (default: pytest).
  • focused: Whether to prefer focused test selection (e.g. only tests near suspected files) when supported.
• [analysis]
  • ignore_paths: Relative paths or directory prefixes to skip during analysis (e.g. generated code, migrations, vendored libs).
• [fix_limits]
  • max_modified_files: Guardrail for maximum number of files a single fix can touch.
  • max_diff_bytes: Approximate limit on diff size in bytes.
  • max_diff_lines: Approximate limit on total changed lines.
• [automation]
  • mode: Coarse automation mode for the repo. "analysis_only" runs analyzers and validation only and never auto-opens PRs. "guardrailed_auto" and "auto_first" allow automation subject to guardrails.
  • max_auto_pr_per_run: Upper bound on the number of PRs BugZero may open per run. The current orchestrator creates at most one PR, and a value of 0 disables auto-PR entirely.
  • require_tests_for_auto_pr: When true, BugZero will only auto-open a PR if post-fix tests ran and passed with no regressions.
• [pr]
  • auto_create: Whether BugZero should attempt to create a PR automatically when the run succeeds.
  • base_branch: Default base branch for PRs (e.g. main or develop).
  • labels: Labels to apply to created PRs (requires GitHub CLI support for labels).

Environment variable overrides

All of these are optional; missing values fall back to bugzero.toml or built-in defaults.

• Testing
  • BUGZERO_TEST_COMMAND: Overrides [test].command.
  • BUGZERO_FOCUSED_TESTS: "true"/"false" style override for [test].focused.
• Analysis
  • BUGZERO_IGNORE_PATHS: Comma-separated list of ignore patterns (e.g. migrations/,venv/).
• Fix guardrails
  • BUGZERO_MAX_FIX_FILES: Overrides max_modified_files.
  • BUGZERO_MAX_FIX_DIFF_BYTES: Overrides max_diff_bytes.
  • BUGZERO_MAX_FIX_DIFF_LINES: Overrides max_diff_lines.
• Automation
  • BUGZERO_AUTOMATION_MODE: Overrides [automation].mode (analysis_only, guardrailed_auto, or auto_first).
  • BUGZERO_MAX_AUTO_PR_PER_RUN: Integer override for [automation].max_auto_pr_per_run.
  • BUGZERO_REQUIRE_TESTS_FOR_AUTO_PR: "true"/"false" style override for [automation].require_tests_for_auto_pr.
• PR behavior
  • BUGZERO_PR_AUTO_CREATE: "true"/"false" for [pr].auto_create.
  • BUGZERO_PR_BASE: Overrides [pr].base_branch.
  • BUGZERO_PR_LABELS: Comma-separated labels.
• Jira ingestion
  • BUGZERO_JIRA_BASE_URL
  • BUGZERO_JIRA_EMAIL
  • BUGZERO_JIRA_API_TOKEN
• Slack ingestion
  • BUGZERO_SLACK_BOT_TOKEN

---

Run History and Analytics

BugZero can persist run history per repo (typically in a runs/ directory) and compute basic analytics.

Listing and inspecting runs

Runs are written automatically when the orchestrator completes. To inspect analytics:

bugzero stats --repo /path/to/service

This prints:

• Total runs
• Successful runs
• Success rate
• Average/median time-to-resolution (seconds)
• Top incident categories

For machine-readable output:

bugzero stats --repo /path/to/service --json

You can also point --repo at a different root; if it is not a valid path, BugZero falls back to a shared ~/.bugzero/runs location.

---

Extending BugZero

BugZero is designed to be extended in three main areas:

• Analyzers (e.g. language-specific codebase analyzers).
• Fix engines (strategies for generating and applying fixes).
• Integrations (new incident sources or output sinks).

Below are high-level guides based on the existing Python implementation.

Adding a new analyzer

1. Implement a new analyzer class (e.g. MyLanguageAnalyzer) in bugzero_agent/codebase_analyzer/.
2. Inherit from the shared analyzer base (see the Python analyzer for reference) and implement an analyze(repo_root, context) method that returns DiagnosisRecord objects.
3. Use the existing DefectCategory model (or extend it) to classify findings and set severity/confidence appropriately.
4. Thread your analyzer into the orchestrator so that it runs when incidents target your language or service type.

When implementing heuristics, prefer:

• AST-based analysis where possible (safer, more precise).
• Respecting config.analysis.ignore_paths to avoid noisy directories.

Adding or customizing fix strategies

The Python fix engine exposes:

• Pattern-based fixes for simple deterministic issues (e.g. missing imports, obvious NameErrors).
• LLM-driven diffs for more complex corrections, with guardrails derived from config.fix_limits.

To extend or customize:

1. Add new pattern-based rules (e.g. additional NameError patterns) in the pattern fixer module.
2. Ensure that any new rule:
   • Is deterministic and reversible when possible.
   • Honors max_modified_files, max_diff_bytes, and max_diff_lines.
3. For LLM-backed strategies, keep the LLM client usage behind a clear interface so it can be disabled or replaced.

Adding a new integration

To add a new incident source (e.g. another ticketing system or chat platform):

1. Implement a small client module under bugzero_agent/integrations/:
   • Focus on read-only operations (e.g. fetching an issue or message).
   • Use environment variables for configuration, similar to JiraClient.from_env and SlackClient.from_env.
2. Implement an adapter module that converts the external payload into an IncidentPayload:
   • Map fields like summary, description, stack traces, logs, and environment metadata.
3. Add a new CLI subcommand in bugzero_agent/cli.py:
   • Parse integration-specific identifiers (issue key, message ID, etc.).
   • Use your client + adapter to build the IncidentPayload.
   • Call the shared _run_pipeline_for_payload helper so behavior matches resolve, ingest-jira, and ingest-slack.

For new output integrations (e.g. posting reports back to Jira or Slack), follow a similar pattern but hook into the reporting layer instead of the incident source.

---

Development

• Run tests (from the project root):

  pytest

• Example service and incidents live under examples/ and can be used to experiment with the pipeline end to end.