Metadata-Version: 2.4
Name: arbiter-score
Version: 0.7.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 :: 4 - Beta
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
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)
[![Dependencies](https://img.shields.io/badge/core_deps-stdlib_only-brightgreen)]()
[![Last commit](https://img.shields.io/github/last-commit/hummbl-dev/arbiter/main)](https://github.com/hummbl-dev/arbiter/commits/main)
[![Arbiter Score](https://img.shields.io/badge/Arbiter-96.6%20A-brightgreen)](https://github.com/hummbl-dev/arbiter)
[![Complexity](https://img.shields.io/badge/Complexity-91.1%20A-brightgreen)](https://github.com/hummbl-dev/arbiter)

**Agent-aware code quality scoring for multi-agent codebases.**

In 2026, code is written by fleets of AI agents. Arbiter knows *who* wrote each line -- human or AI -- and scores quality accordingly.

Learn more at [hummbl.io](https://hummbl.io).

Repository health, validation, and stewardship expectations are tracked in [docs/REPO_HEALTH.md](docs/REPO_HEALTH.md).

## Quick Start -- 5 Minutes

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

**Example output:**

```
Arbiter Scorecard: my-repo (main)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall:  87.3  →  Grade: B

By Analyzer:
  Lint       91.2  (ruff — 3 style issues)
  Security   95.0  (bandit — clean)
  Complexity 78.5  (radon — 2 functions > complexity 10)
  Dead Code  92.0  (vulture — 1 unused import)

By Agent (last 30 days):
  claude-code   89.1  (42 commits, 1,240 LOC)
  codex         85.3  (18 commits, 890 LOC)
  human         92.7  (5 commits, 120 LOC)

Top Issues:
  • src/api/routes.py:47  complexity C (15)  — agent: codex
  • src/utils.py:12       unused import os   — agent: claude-code
  • src/models.py:89      line too long      — agent: codex

Run `arbiter serve` to view the full dashboard.
```

## Install

The Python distribution is `arbiter-score`; the installed CLI command is `arbiter`.
Do not install the separate PyPI project named `arbiter` for this tool.

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

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

## Usage

```bash
# Quick score -- no persistence, instant feedback
arbiter score /path/to/repo

# Full analysis with per-commit agent attribution
arbiter analyze /path/to/repo

# Agent leaderboard -- who writes the best code?
arbiter agents

# Start the dashboard (single HTML file, no build step)
arbiter serve --port 8080
```

## What It Scores

Arbiter wraps tools you already trust and combines them into a deterministic composite score:

| Analyzer | Tool | Weight | What It Finds |
|----------|------|--------|---------------|
| Lint | ruff | 35% | Style violations, import errors, bugbear patterns |
| Security | bandit | 30% | Hardcoded secrets, shell injection, dangerous patterns |
| Complexity | radon | 35% | Cyclomatic complexity (grade A-F per function) |
| Dead Code | vulture | penalty | Unused functions, imports, variables |
| Duplication | AST hash | penalty | Near-duplicate function bodies |
| Semgrep | semgrep | opt-in | Custom rule enforcement (enable via config) |

**Scoring:** `100 - (penalty / LOC) * normalization`. Grades: A (90+) | B (80+) | C (70+) | D (60+) | F (<60).

## What Makes Arbiter Different

| Feature | Traditional Tools | Arbiter |
|---------|------------------|---------|
| Agent attribution | None | First-class: tracks Claude, Codex, Gemini, Copilot, humans |
| Per-commit scoring | Repo-wide only | Scores each commit's changed files individually |
| Diff analysis | N/A | Score only what changed in a PR/branch |
| Agent-specific gates | N/A | Different quality thresholds per agent trust tier |
| Dashboard | SaaS login | Single HTML file with per-agent timelines and fleet view |
| Dependencies | Heavy | Analysis tools only; core is stdlib Python |

## CLI Reference

```bash
arbiter analyze <repo>                     # Full analysis + per-commit scoring + persist
arbiter score <repo> [--json] [--exclude]  # Quick score (no persist)
arbiter diff <repo> [--base main] [--json] # Score changed files vs base branch
arbiter agents                             # Agent leaderboard
arbiter trend [--days 30]                  # Quality trend
arbiter worst [--limit 20]                 # Worst files
arbiter commits [--agent claude]           # Recent commits with scores
arbiter audit-fleet <directory>            # Audit all repos in a directory
arbiter triage                             # Auto-classify repos: green/yellow/red/archive
arbiter fix <repo> [--dry-run]             # Auto-fix ruff findings + before/after score
arbiter serve [--port 8080]                # API + dashboard
```

## Tests

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

## Quality Gate

Arbiter grades itself on every push and PR. The CI runs `arbiter score .` and fails if the score drops below **90 (A grade)**.

```bash
# Run the same check locally
arbiter score . --fail-under 90

# Score only your changed files against main
arbiter diff . --base main --fail-under 80
```

## Requirements

- Python 3.11+
- git (for historian)
- Optional: ruff, radon, vulture, bandit (install via `[analyzers]` extra)

## HUMMBL Ecosystem

Part of the [HUMMBL](https://github.com/hummbl-dev) cognitive AI architecture:

- [hummbl-governance](https://github.com/hummbl-dev/hummbl-governance) -- Governance primitives that Arbiter scores against
- [base120](https://github.com/hummbl-dev/base120) -- 120 mental models for structured reasoning
- [hummbl-agent](https://github.com/hummbl-dev/hummbl-agent) -- Governed control plane for AI agent systems
- [hummbl-bibliography](https://github.com/hummbl-dev/hummbl-bibliography) -- Bibliography for the HUMMBL cognitive framework
- [mcp-server](https://github.com/hummbl-dev/mcp-server) -- MCP server for AI agent integration

Learn more at [hummbl.io](https://hummbl.io).

## License

Apache 2.0 -- see [LICENSE](LICENSE).

---

Built by [HUMMBL LLC](https://hummbl.io) from production experience coordinating Claude, Codex, Gemini, and human engineers on a 14,000+ test codebase.
