Skip to content

Commit ffe086d

Browse files
hummbl-devClaude (agent)claude
authored
feat: PyPI packaging + publish workflow + platform design doc (#56)
- Update pyproject.toml: name=arbiter-score, version=0.6.0, full metadata (URLs, keywords, classifiers, Python 3.14) - Add MANIFEST.in for sdist - Add publish.yml GitHub Action (trusted publishing to PyPI) - Add docs/PLATFORM_DESIGN.md with specs for Cloud API, GitHub App, and Dashboard (requires human infra setup) Co-authored-by: Claude (agent) <claude@agents.hummbl.io> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent e9f32c7 commit ffe086d

4 files changed

Lines changed: 176 additions & 7 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
permissions:
9+
id-token: write # Required for trusted publishing
10+
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- uses: actions/setup-python@v5
18+
with:
19+
python-version: '3.12'
20+
21+
- name: Install build tools
22+
run: pip install build
23+
24+
- name: Build package
25+
run: python -m build
26+
27+
- name: Verify package
28+
run: |
29+
pip install dist/*.whl
30+
arbiter --help
31+
echo "Package installs and runs correctly"
32+
33+
- name: Upload build artifacts
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: dist
37+
path: dist/
38+
39+
publish:
40+
needs: build
41+
runs-on: ubuntu-latest
42+
if: github.event_name == 'release'
43+
environment: pypi
44+
steps:
45+
- uses: actions/download-artifact@v4
46+
with:
47+
name: dist
48+
path: dist/
49+
50+
- name: Publish to PyPI
51+
uses: pypa/gh-action-pypi-publish@release/v1

‎MANIFEST.in‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include LICENSE
2+
include README.md
3+
include ROADMAP.md
4+
include CONTRIBUTING.md
5+
recursive-include src/arbiter *.py
6+
recursive-include benchmarks *.json
7+
recursive-include examples *.yml *.md

‎docs/PLATFORM_DESIGN.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Platform Design — Phase 5 Infrastructure
2+
3+
Design specs for features requiring deployment infrastructure.
4+
Code is buildable; deployment needs human action (account setup, DNS, secrets).
5+
6+
---
7+
8+
## A: Arbiter Cloud (REST API)
9+
10+
**What**: Hosted scoring API — `POST /score` with a GitHub URL, get a score back.
11+
12+
**Architecture**:
13+
```
14+
Client → Arbiter API (Cloudflare Workers or Fly.io)
15+
├── Clone repo (shallow, temp)
16+
├── Run analyzers
17+
├── Return JSON score
18+
└── Record in audit trail
19+
```
20+
21+
**Endpoints**:
22+
- `POST /v1/score` — score a repo by URL
23+
- `POST /v1/certify` — full certification
24+
- `GET /v1/leaderboard` — current leaderboard
25+
- `GET /v1/health` — service health
26+
27+
**Auth**: API key in `X-Arbiter-Key` header. Free tier: 10 scores/day. Paid: unlimited.
28+
29+
**Deployment**: `arbiter serve` already exists. Wrap in Dockerfile, deploy to Fly.io.
30+
31+
**Human action needed**:
32+
- [ ] Create Fly.io account or Cloudflare Workers project
33+
- [ ] Set up domain: api.hummbl.io or arbiter.hummbl.io
34+
- [ ] Configure secrets: GITHUB_TOKEN for cloning
35+
36+
---
37+
38+
## B: GitHub App
39+
40+
**What**: Install on an org → automatic PR quality checks on every push.
41+
42+
**How it works**:
43+
1. PR opened → GitHub sends webhook to Arbiter API
44+
2. Arbiter clones the PR branch
45+
3. Runs `arbiter diff --base main`
46+
4. Posts score as PR check + comment
47+
5. Fails the check if below threshold
48+
49+
**App manifest** (register at github.com/settings/apps/new):
50+
```yaml
51+
name: HUMMBL Arbiter
52+
description: Deterministic code quality scoring
53+
url: https://hummbl.io/audit
54+
webhook_url: https://api.hummbl.io/github/webhook
55+
permissions:
56+
checks: write
57+
pull_requests: write
58+
contents: read
59+
events:
60+
- pull_request
61+
```
62+
63+
**Human action needed**:
64+
- [ ] Register GitHub App at github.com/settings/apps
65+
- [ ] Set webhook secret
66+
- [ ] Deploy webhook receiver (part of Arbiter Cloud API)
67+
- [ ] Create installation flow page on hummbl.io
68+
69+
---
70+
71+
## C: Dashboard
72+
73+
**What**: Web UI showing fleet scores, trends, team leaderboard.
74+
75+
**Architecture**: Static HTML generated by `arbiter leaderboard --html` + weekly GitHub Action.
76+
For v1, no backend needed — just static files served from GitHub Pages or hummbl.io.
77+
78+
**Pages**:
79+
- `/leaderboard` — top repos by quality score (generated weekly)
80+
- `/repo/:name` — individual repo score card (future)
81+
- `/certify` — certification status page (future)
82+
83+
**Human action needed**:
84+
- [ ] Add GitHub Pages to arbiter repo, or
85+
- [ ] Deploy to hummbl.io/audit subdirectory
86+
- [ ] Wire weekly Action to push generated HTML
87+
88+
---
89+
90+
## Implementation Order
91+
92+
1. **PyPI package** (this PR) — enables `pip install arbiter-score`
93+
2. **Leaderboard HTML** (parallel PR) — static page ready to deploy
94+
3. **Webhooks** (parallel PR) — notification module
95+
4. **Arbiter Cloud** — after PyPI is live, wrap `serve` in Docker
96+
5. **GitHub App** — after Cloud API is live
97+
6. **Dashboard** — leaderboard HTML is v1; expand later
98+
99+
---
100+
101+
*Powered by [HUMMBL](https://hummbl.io) — governed AI for enterprise.*

‎pyproject.toml‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,38 @@ requires = ["setuptools>=82.0.1"]
33
build-backend = "setuptools.build_meta"
44

55
[project]
6-
name = "arbiter"
7-
version = "0.2.0"
8-
description = "Agent-aware code quality system for multi-agent codebases"
6+
name = "arbiter-score"
7+
version = "0.6.0"
8+
description = "Deterministic, polyglot code quality scoring with governance integration"
99
readme = "README.md"
1010
license = "MIT"
1111
requires-python = ">=3.11"
1212
authors = [
13-
{name = "Reuben Bowlby"},
14-
{name = "Daniel Matha"},
13+
{name = "Reuben Bowlby", email = "reuben@hummbl.io"},
1514
]
15+
keywords = ["code-quality", "linting", "scoring", "governance", "arbiter", "hummbl"]
1616
classifiers = [
17-
"Development Status :: 3 - Alpha",
17+
"Development Status :: 4 - Beta",
1818
"Intended Audience :: Developers",
19+
"Topic :: Software Development :: Quality Assurance",
20+
"Topic :: Software Development :: Testing",
1921
"Programming Language :: Python :: 3.11",
2022
"Programming Language :: Python :: 3.12",
2123
"Programming Language :: Python :: 3.13",
24+
"Programming Language :: Python :: 3.14",
2225
]
2326

27+
[project.urls]
28+
Homepage = "https://hummbl.io/audit"
29+
Repository = "https://github.com/hummbl-dev/arbiter"
30+
Documentation = "https://github.com/hummbl-dev/arbiter#readme"
31+
Changelog = "https://github.com/hummbl-dev/arbiter/releases"
32+
Issues = "https://github.com/hummbl-dev/arbiter/issues"
33+
2434
[project.optional-dependencies]
2535
analyzers = ["ruff>=0.4.0", "radon>=6.0.1", "vulture>=2.16", "bandit>=1.9.4"]
2636
test = ["pytest>=9.0.3"]
27-
all = ["arbiter[analyzers,test]"]
37+
all = ["ruff>=0.4.0", "radon>=6.0.1", "vulture>=2.16", "bandit>=1.9.4", "pytest>=9.0.3"]
2838

2939
[project.scripts]
3040
arbiter = "arbiter.__main__:main"

0 commit comments

Comments
 (0)