Metadata-Version: 2.4
Name: beneissue
Version: 1.0.13
Summary: AI-powered GitHub issue automation framework
Keywords: github,automation,ai,issue-tracking,langgraph,claude,triage
Author: Benedict Lee
Author-email: Benedict Lee <leebd@hancom.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langsmith>=0.1.0
Requires-Dist: langchain-anthropic>=0.2.0
Requires-Dist: pygithub>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: pyyaml>=6.0.0
Requires-Python: >=3.11
Project-URL: Documentation, https://github.com/opendataloader-project/beneissue#readme
Project-URL: Homepage, https://github.com/opendataloader-project/beneissue
Project-URL: Issues, https://github.com/opendataloader-project/beneissue/issues
Project-URL: Repository, https://github.com/opendataloader-project/beneissue
Description-Content-Type: text/markdown

# BeneIssue

AI-Agentic issue automation for GitHub.

Drowning in GitHub issues? Install `beneissue` once, and it handles the rest automatically.

## Who is this for?

- **Open source maintainers** with 100+ issues piling up
- **Small teams** who can't afford to manually label every issue
- **Solo developers** who want typo fixes handled automatically

## What changes after you install it?

| Before | After |
|--------|-------|
| Issue opened → check it days later | Issue opened → instantly classified + labeled |
| Manually comment "need more info" | Auto-asks specific follow-up questions |
| Fix simple bugs yourself | Auto-eligible issues get auto-PR via Claude Code |

## How it works

![BeneIssue Workflow](https://raw.githubusercontent.com/opendataloader-project/beneissue/main/docs/images/workflow.png)

**Three stages:**

| Stage | What it does | Model |
|-------|--------------|-------|
| **Triage** | Classify issue → valid / invalid / duplicate / needs-info | Haiku (fast, ~$0.02) |
| **Analyze** | Find affected files, plan fix approach, check eligibility | Sonnet |
| **Fix** | Create branch, apply fix, open PR | Claude Code |

## Install once, runs forever

### 1. Install the package

```bash
pip install beneissue
```

### 2. Set up GitHub repository

**Secrets:** Go to Settings → Secrets and variables → Actions:

| Secret | Required | Description |
|--------|----------|-------------|
| `ANTHROPIC_API_KEY` | Yes | Your Claude API key |
| `LANGCHAIN_API_KEY` | No | LangSmith for tracing |

**Permissions:** Go to Settings → Actions → General → Workflow permissions:
- Enable "Allow GitHub Actions to create and approve pull requests"

### 3. Initialize in your repo

```bash
cd your-repo
beneissue init
git push
```

This creates:

```
your-repo/
├── .github/workflows/
│   └── beneissue-workflow.yml   # Triggers on issue events
└── .claude/skills/beneissue/
    ├── SKILL.md                 # Claude Code instructions
    └── beneissue-config.yml     # Your settings
```

That's it. From now on:

1. **New issue opened** → automatically triaged and labeled
2. **Auto-eligible issues** → Claude Code creates a PR
3. **Need manual control?** → just comment on the issue

### Control via issue comments

```
@beneissue triage    # Re-classify this issue
@beneissue analyze   # Run full analysis
@beneissue fix       # Attempt auto-fix now
```

No CLI needed. Just talk to the bot in the issue thread.

## GitHub Actions triggers

| Event | Trigger | Action |
|-------|---------|--------|
| Issue opened/reopened | Automatic | Runs `analyze` (triage → analyze) |
| `@beneissue triage` | Comment | Re-classify the issue |
| `@beneissue analyze` | Comment | Run full analysis |
| `@beneissue fix` | Comment | Attempt auto-fix now |
| `@beneissue run` | Comment | Full pipeline: triage → analyze → fix |

## Verify it's working

When issues get these labels automatically, you're set:
- `triage/valid` — Valid issue, ready for work
- `fix/auto-eligible` — Will be auto-fixed

## Configuration

Edit `.claude/skills/beneissue/beneissue-config.yml`:

```yaml
version: "1.0"

models:
  triage: claude-haiku-4-5    # Fast, cheap (~$0.02/call)

limits:
  daily:
    triage: 50   # ~$1/day
    analyze: 20  # ~$2-10/day
    fix: 5       # ~$5-25/day

team:
  - github_id: "your-github-id"
    available: true
    specialties: ["backend", "python"]

observability:
  langsmith:
    enabled: true
    project: "beneissue"
```

## Labels

| Label | Meaning |
|-------|---------|
| `triage/valid` | Valid issue, ready for analysis |
| `triage/invalid` | Out of scope or spam |
| `triage/duplicate` | Already reported |
| `triage/needs-info` | Waiting for more details |
| `fix/auto-eligible` | Passes checklist, will be auto-fixed |
| `fix/manual-required` | Needs human review |
| `fix/completed` | Auto-fix PR created |

## CLI (optional)

For manual runs or debugging:

| Command | Description |
|---------|-------------|
| `beneissue triage <repo> --issue <n>` | Classify issue only |
| `beneissue analyze <repo> --issue <n>` | Analyze issue only (no triage, no fix) |
| `beneissue fix <repo> --issue <n>` | Fix issue only (no triage, no analysis) |
| `beneissue run <repo> --issue <n>` | Full workflow: triage → analyze → fix |
| `beneissue init` | Initialize beneissue in current repo |
| `beneissue labels` | Sync labels to repository |
| `beneissue test` | Run policy tests |

Add `--dry-run` to triage/analyze to skip GitHub actions.

## License

Apache 2.0
