Smart Bug Triage

Bug triage is repetitive judgment work: read the issue, classify it, rank its priority, pick an assignee. This agent does that pass in a way you can audit and reproduce. A GitHub issue goes into a LangGraph state machine that classifies, ranks, and assigns it, and every decision carries the reason it was made.

It runs fully local by default (Ollama), traces to LangFuse when you want it, and is reachable from a CLI, an HTTP API, and any MCP client.

How it works

GitHub issue ─fetch─▶ classify ─▶ rank ─▶ assign ─▶ decision + rationale
                         └──────── ChatOllama (temperature 0) ────────┘
                         every step traced to LangFuse (optional)

• classify puts the issue in one of: bug, feature, question, documentation, other.

• rank sets priority (critical / high / medium / low) against a fixed rubric.

• assign picks the best-matching engineer from a roster, and snaps an invalid pick back to a real name so an issue is never left with a made-up owner.

Decisions are reproducible because the model runs at temperature 0: the same issue triages the same way. LangFuse records the run and its LLM calls when keys are set.

Setup

Needs Python 3.10+ and a running Ollama.

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ollama pull llama3.2:3b

Everything else is optional. Copy .env.example to .env to add a GITHUB_TOKEN (higher rate limit, private repos) or LangFuse keys (tracing). With nothing set it runs local, untraced, on public repos.

Use it

CLI

triage pallets/flask#6107

HTTP API

uvicorn smart_bug_triage.api:app
curl -X POST localhost:8000/triage -H 'content-type: application/json' \
  -d '{"issue": "pallets/flask#6107"}'

Interactive docs at http://localhost:8000/docs.

MCP (stdio, for Claude Desktop and other MCP clients)

python -m smart_bug_triage.mcp_server

It exposes one tool, triage_issue(issue), where issue is owner/repo#123 or a github.com issue URL. Point a client at the command above:

{
  "mcpServers": {
    "smart-bug-triage": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "smart_bug_triage.mcp_server"]
    }
  }
}

Tracing

Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY (and LANGFUSE_HOST if self-hosting) in .env. Every run then shows up in LangFuse with the classify, rank, and assign calls nested underneath it. No keys means no tracing and no error.

Tests

pytest

The suite is offline: the LLM is faked at the seam, so it needs no Ollama and no network. It covers the issue-reference parser, the assignee coercion, and the full classify to assign graph wiring.

Layout

smart_bug_triage/
  config.py       env-read settings, the default assignee roster
  llm.py          the one place an LLM SDK is imported (swap providers here)
  github.py       fetch one issue, parse any issue reference
  graph.py        the classify to rank to assign LangGraph state machine
  tracing.py      optional LangFuse callbacks
  cli.py          triage <issue> on the command line
  api.py          FastAPI service
  mcp_server.py   MCP server exposing triage_issue
tests/            offline unit tests

Swapping the model or provider is a one-file change in llm.py; swapping the roster is the team= argument to triage() or the default in config.py.