Metadata-Version: 2.4
Name: arbiter-score
Version: 1.1.0
Summary: Deterministic, polyglot code quality scoring with governance integration
Author-email: Reuben Bowlby <reuben@hummbl.io>
License: Apache-2.0
Project-URL: Homepage, https://hummbl.io/audit
Project-URL: Repository, https://github.com/hummbl-dev/arbiter
Project-URL: Documentation, https://github.com/hummbl-dev/arbiter#readme
Project-URL: Changelog, https://github.com/hummbl-dev/arbiter/releases
Project-URL: Issues, https://github.com/hummbl-dev/arbiter/issues
Keywords: code-quality,linting,scoring,governance,arbiter,hummbl
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: libcst>=1.4.0
Provides-Extra: analyzers
Requires-Dist: ruff>=0.4.0; extra == "analyzers"
Requires-Dist: radon>=6.0.1; extra == "analyzers"
Requires-Dist: vulture>=2.16; extra == "analyzers"
Requires-Dist: bandit>=1.9.4; extra == "analyzers"
Provides-Extra: test
Requires-Dist: pytest>=9.0.3; extra == "test"
Provides-Extra: all
Requires-Dist: ruff>=0.4.0; extra == "all"
Requires-Dist: radon>=6.0.1; extra == "all"
Requires-Dist: vulture>=2.16; extra == "all"
Requires-Dist: bandit>=1.9.4; extra == "all"
Requires-Dist: pytest>=9.0.3; extra == "all"
Dynamic: license-file

# Arbiter

[![CI](https://github.com/hummbl-dev/arbiter/actions/workflows/ci.yml/badge.svg)](https://github.com/hummbl-dev/arbiter/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/arbiter-score)](https://pypi.org/project/arbiter-score/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

**Agent attribution for code quality.**  
Install `arbiter-score`, run `arbiter score`, and quickly see which AI agent or human produced your highest-risk code.

```bash
pip install "arbiter-score[analyzers]"
arbiter score .
```

Example output:

```
┌──────────────────────┬──────────┬────────┐
│ Agent                │ Quality  │ Grade  │
├──────────────────────┼──────────┼────────┤
│ claude               │ 72.3%    │ C      │
│ gpt-4o               │ 88.1%    │ B      │
│ copilot              │ 91.4%    │ A      │
│ human (you)          │ 94.2%    │ A      │
└──────────────────────┴──────────┴────────┘
```

Every team using AI coding tools has a "who wrote this mess?" moment. Arbiter makes that visible -- per file, per commit, and per author -- then grades the code quality signal.

```bash
pip install "arbiter-score[analyzers]"    # one-time install
arbiter score .                         # grade everything
arbiter diff . --base main              # only changed files in this branch
arbiter agents                          # author leaderboard
arbiter trend --days 30                 # quality over time
arbiter worst --limit 20                # highest-risk files
arbiter audit-fleet ./repos             # score every repo in a directory
arbiter serve                           # start web dashboard
```

## Why Arbiter exists

AI-written code often optimizes for speed over maintainability. The result can include unused imports, high complexity, duplicated logic, and risky patterns. Standard linters catch some symptoms; Arbiter also attributes risk back to the contributor model/actor so you can review the right places first.

In practice, teams tune gates per agent tier (for example: stricter thresholds for autonomous agents, looser for exploratory branches) and keep human review focused on high-risk commits.

## What makes Arbiter different

| Feature | Traditional tools | Arbiter |
|---------|------------------|---------|
| Agent attribution | None | First-class: tracks contribution source (AI and humans) |
| Per-commit scoring | Repository-wide only | Scores changed files by commit and author |
| Diff analysis | Optional / limited | Scores only what changed in PR/branch workflows |
| Review workflows | Static report | Supports agent-specific gate thresholds |
| Dashboard output | SaaS + build steps | Local, single-file HTML dashboard endpoint |
| Core runtime | Multi-tool runtime | Lightweight core (LibCST only); optional analyzer dependencies |

## Scoring model

| Analyzer | Weight | Finds |
|----------|--------|-------|
| Lint (ruff) | 35% | Style violations, import errors, bugbear patterns |
| Security (bandit) | 30% | Hardcoded secrets, shell injection, risky command patterns |
| Complexity (radon) | 35% | Cyclomatic complexity by function (A-F) |
| Dead code (vulture) | penalty | Unused functions, imports, variables |
| Duplication (AST hash) | penalty | Near-duplicate function bodies |

Arbiter computes a normalized score from analyzer penalties and total lines of code.

Common format:

`100 - (penalty / LOC) * normalization`

Grades: A (90+), B (80+), C (70+), D (60+), F (<60).

## Install

### From PyPI (recommended)

```bash
pip install arbiter-score                    # core (LibCST runtime)
pip install "arbiter-score[analyzers]"       # + ruff, radon, vulture, bandit
```

**Note:** The PyPI package is `arbiter-score` (not `arbiter`, which is different). The CLI command is `arbiter`.

### From source

```bash
git clone https://github.com/hummbl-dev/arbiter.git && cd arbiter
pip install -e ".[analyzers]"
```

### Tests

```bash
pip install -e ".[test]"
python -m pytest tests/ -v
```

## Requirements

- Python 3.11+
- git

## Quality gates

Arbiter enforces quality checks in CI.

```bash
arbiter score . --fail-under 90 --json
arbiter diff . --base main --fail-under 80
```

## Common gotchas

- Use `arbiter-score` package name to avoid installing the wrong package.
- Run from repository root for consistent path reporting and results.
- Optional analyzers improve signal quality, but many core checks run without the analyzer extras installed.

## License

Apache 2.0 — see [LICENSE](LICENSE).

---

Built by [HUMMBL](https://hummbl.io).
