# 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](https://ollama.com).

```bash
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**

```bash
triage pallets/flask#6107
```

**HTTP API**

```bash
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)

```bash
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:

```json
{
  "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

```bash
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`.