README.md

metadata

title: GitHub Profile AI Reviewer
emoji: 🧪
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

GitHub Profile AI Reviewer

FastAPI service that rates a public GitHub user profile out of 100.

The API accepts a GitHub username and returns a rating_score, developer level, language breakdown, contribution signals, streak data, and model metadata.

Folder Structure

app/
  main.py              FastAPI app entrypoint and static frontend serving
  api/                 HTTP routes for health checks and profile analysis
  schemas.py           Request and response models
  service.py           Application service layer
  ai/                  Embedding and scoring logic
  clients/             GitHub API clients and queries
  core/                Settings and logging
  graph/               Active analysis workflow
  static/index.html    Browser API console
backend/               Legacy LangGraph prototype pipeline
experiments/           Standalone prototype files
scripts/               Developer utilities and CLI helpers
src/                   React documentation website

Token Behavior

GITHUB_TOKEN is optional.

When GITHUB_TOKEN is set, the service uses GitHub GraphQL for richer profile and contribution data. When it is empty, users can still rate any public GitHub username through GitHub's public REST API. Public REST mode is limited by GitHub's unauthenticated rate limits and cannot see private contribution data.

If you hit GitHub's public rate limit, add a valid token to .env and restart the server. Public mode keeps its request count low and caches successful GitHub responses for GITHUB_CACHE_TTL_SECONDS to avoid wasting quota during repeated tests.

Environment

Copy .env.example to .env and adjust only what you need:

GITHUB_TOKEN=
GITHUB_API_URL=https://api.github.com/graphql
GITHUB_REST_API_URL=https://api.github.com
GITHUB_PUBLIC_REPO_LIMIT=20
GITHUB_FETCH_COMMIT_COUNTS=false
GITHUB_CACHE_TTL_SECONDS=900
APP_HOST=0.0.0.0
APP_PORT=8000
SCORING_BACKEND=heuristic

Keep SCORING_BACKEND=heuristic unless you have trained model weights. The neural backend is experimental.

Run Locally

Run the React documentation website from the repository root:

npm install
npm run dev

Open:

http://localhost:5173/

Run the FastAPI backend separately:

On Windows PowerShell, use a project virtual environment:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

If py -3.12 is not installed, use your available Python launcher version:

py -0p

The default requirements start the API with deterministic fallback embeddings. Optional ML packages are separate:

python -m pip install -r requirements-ml.txt

On macOS/Linux:

python3 -m pip install -r requirements.txt
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Open the browser console UI:

http://localhost:8000/

Request a rating:

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"username":"octocat"}'

Deploy With Docker

docker compose up --build -d

The API and index.html console will be available on http://localhost:${APP_PORT:-8000}.

Useful deployment commands:

docker compose ps
docker compose logs -f api
docker compose down

For a cloud VM, install Docker, clone the repo, create .env, then run the same docker compose up --build -d command. If you deploy behind a domain or reverse proxy, forward public traffic to container port 8000.

Build the React documentation site:

npm install
npm run build

The static output is generated in dist/. You can deploy dist/ to Netlify, Vercel, GitHub Pages, Nginx, or any static hosting provider.

Use The API In index.html

The frontend at app/static/index.html calls the API with fetch:

<script>
  async function analyze(username) {
    const response = await fetch("/analyze", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ username }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.detail || "Analyze request failed");
    }

    return response.json();
  }
</script>

Use a full base URL only when the HTML is hosted somewhere else:

fetch("https://your-domain.com/analyze", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "octocat" }),
});

Response Fields

• rating_score: main score from 0 to 100.
• hiring_readiness_score: compatibility alias for the same 0 to 100 score.
• public_activity.public_commits: public commits counted for the user.
• public_activity.public_prs_created: public pull requests created by the user.
• model_info.data_source: graphql when a server token is configured, otherwise rest-public.

In rest-public mode, GitHub exposes these counts from recent public events only. With authenticated GraphQL mode, the counts come from GitHub's contribution totals.