ghfind (Python)
Official Python SDK and CLI for ghfind.com — score any GitHub account 0–100 for value and trustworthiness, with roasts, head-to-head battles, leaderboards, and developer discovery.
- Deterministic scoring, no LLM.
scan,score,get_score, and the battle winner are pure computation over GitHub data. - Bring your own model. The only LLM parts are the roast prose and battle
commentary.
roast(..., byo_key=...)runs the LLM through your own OpenAI-compatible provider — or just feed the structuredscan()output to your own model. - Score anywhere. No token → the ghfind server crawls + scores for you. Have a
token →
ghfind.localruns the same open-source engine entirely on your machine (see below). Same numbers either way. - Zero dependencies. Standard library only.
pip install ghfind
CLI
ghfind score torvalds # deterministic score (no auth, cached)
ghfind roast torvalds --lang en
ghfind vs torvalds octocat
ghfind badge torvalds --markdown # a README badge that links back to ghfind
score hits the public GET /api/score endpoint: no auth, edge-cached and
rate-limited on the server, and it scores never-seen accounts live (still
deterministic, no LLM). It's the cheapest path for you and for ghfind.
| Command | What it does | Endpoint | LLM? |
|---|---|---|---|
score <user> |
Deterministic score; prints tier, sub-scores, percentile. | GET /api/score/{u} |
no |
scan <user> |
Full evidence payload (metrics, signals, red flags). Heavy — needs --api-key in prod. |
POST /api/scan |
no |
roast <user> |
Human-facing roast report + AI-adjusted score. | POST /api/scan + /api/roast |
yes* |
vs <a> <b> |
Head-to-head verdict (winner deterministic). | POST /api/vs-verdict |
yes* |
exists <user> |
Does this GitHub login exist? Runs on your IP, never touches ghfind. | api.github.com |
no |
search <query> |
Prefix autocomplete over scored accounts. | GET /api/search-users |
no |
leaderboard |
Ranked profiles. --view / --window. |
GET /api/leaderboard |
no |
developers --type language|org|repo |
Discover developers by facet. | GET /api/developers |
no |
stats |
Platform totals. | GET /api/stats |
no |
badge <user> |
Badge URL, or --markdown for a README snippet linking to the profile. |
— | no |
card <user> |
OG share-card PNG URL. | — | no |
commands [show <c>] |
Self-describing capability catalog (for agents). | — | no |
auth status |
Show host + which credentials are configured. | — | no |
* roast/vs prose is the only LLM part. Pass --byo-base-url --byo-api-key --byo-model (or GHFIND_BYO_* env vars) to run roast through your own model
instead of ghfind's.
Score locally, offline, on your own token
--local runs the crawl and scoring on your machine with your GITHUB_TOKEN
— the ghfind server is never called, so it scales infinitely and never adds load:
export GITHUB_TOKEN=ghp_xxx
ghfind score torvalds --local # crawl + score entirely on your machine
ghfind scan torvalds --local
Rule of thumb: have a token → --local (offline, unlimited); no token →
plain score (ghfind scores it for you). Output is identical.
Options & environment
--host <url> default https://ghfind.com (or GHFIND_HOST)
--api-key <key> Authorization: Bearer — bypasses Turnstile on POST /api/scan
(or GHFIND_API_KEY)
--github-token <t> for --local and exists (or GITHUB_TOKEN)
--byo-base-url/-api-key/-model your OpenAI-compatible provider for roast
--json | -o json|pretty|markdown
--lang zh|en
Library
from ghfind import GhFind
gh = GhFind() # defaults to https://ghfind.com
# Cheapest: deterministic score (no LLM). Works for ANY account —
# unseen ones are scored live. s["source"] is "indexed" or "live".
s = gh.get_score("torvalds")
print(s["final_score"], s["tier"], s["percentile"], s["source"])
# Full evidence payload:
scan = gh.scan("torvalds")
print(scan["scoring"]["final_score"], scan["scoring"]["red_flags"])
# Confirm a handle exists first (on your IP, not ghfind's):
if gh.user_exists("torvalds"):
...
# Roast with your own model (no ghfind LLM spend):
roast = gh.roast("torvalds", byo_key={
"baseURL": "https://api.openai.com/v1", "apiKey": "...", "model": "gpt-4o",
})
Every method is one atomic capability; introspect them via
from ghfind import CATALOG.
Local scoring (ghfind.local)
import os
from ghfind.local import collect_and_score
scan = collect_and_score("torvalds", token=os.environ["GITHUB_TOKEN"])
print(scan["scoring"]["final_score"], scan["scoring"]["tier"])
# Already have metrics? Score them purely (no I/O):
from ghfind.local import score_metrics
scoring = score_metrics(metrics)
ghfind.local is a faithful port of the website's collect() + score(),
verified bit-for-bit against the TS/website output. It runs entirely on your own
machine and GitHub token — no ghfind server, no LLM, no rate limits but GitHub's.
Errors
from ghfind import GhFindError
try:
gh.get_score("someone")
except GhFindError as e:
if e.status == 404:
print("no such GitHub user") # the only 404
Machine-readable API spec: https://ghfind.com/openapi.json · Agent notes: https://ghfind.com/llms.txt
JS/TS SDK/CLI: @hikariming/ghfind on npm. License: AGPL-3.0-or-later.
Metadata
Release files for ghfind 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ghfind-0.1.0.tar.gz | 31.1 kB | Without provenance | Details for ghfind-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ghfind-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ghfind-0.1.0-py3-none-any.whl |
Total release size: 66.2 kB
Release files / ghfind-0.1.0.tar.gz
| Download URL | ghfind-0.1.0.tar.gz |
|---|---|
| Size | 31.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f619dbabe3ccae0a62d62256379d0f81ab04b23eb283087d818bfaf4e74956e
|
|
BLAKE2b-256 checksum How to use checksums |
8e120e46676853997b1f0f3453a39a9eeaddf8c62636b6a4671ce2a31a3a0185
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / ghfind-0.1.0-py3-none-any.whl
| Download URL | ghfind-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7671de9f1e5a175c88ee34a37da60eb501edcef31b829c2354fa6b3f9588a23a
|
|
BLAKE2b-256 checksum How to use checksums |
701ce093169750e14c8ad80baeb670e05648b798d9d9f4d269ac182b8e4c46f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for ghfind 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.