Posted on
• Artificial Intelligence

Artificial Intelligence GitHub Portfolio

Author
  • User
    linuxbash
    Posts by this author
    Posts by this author

Build an AI GitHub Portfolio from the Command Line: A Linux-First Guide

If a recruiter, maintainer, or collaborator wants to know whether you can ship AI, they’ll open your GitHub—long before they read your resume. The strongest signal you can send is a clean, reproducible portfolio that runs on any Linux box with a couple of commands. This guide shows you how to create a professional Artificial Intelligence GitHub portfolio entirely from the terminal, with automation, testing, CI, and a shareable demo.

What you’ll get:

  • A minimal but professional project structure

  • Reproducible environments and data handling

  • Quality gates (linting, tests) and GitHub Actions CI

  • A demo app and container so others can try your work quickly

Why this works (and why it matters)

  • Reproducibility beats screenshots: If people can run it, they’ll trust it.

  • Structure communicates maturity: Clear directories and Makefile targets reduce friction for reviewers.

  • CI shows engineering rigor: Tests and linting prove you can maintain quality at scale.

  • Demos land the point: A small web UI or notebook makes your work accessible.

  • Containers remove excuses: If it runs in a container, it runs on their machine.

0) Prerequisites: Install core tools

Run one of the following blocks based on your distribution.

# Debian/Ubuntu (apt)
sudo apt update
sudo apt install -y git make python3 python3-venv python3-pip git-lfs podman

# Fedora/RHEL/CentOS (dnf)
sudo dnf install -y git make python3 python3-pip git-lfs podman

# openSUSE (zypper)
sudo zypper refresh
sudo zypper install -y git make python3 python3-venv python3-pip git-lfs podman

  • git: version control

  • make: convenient task runner via Makefile targets

  • python3, python3-venv, python3-pip: runtime and virtual environments

  • git-lfs: for large files and artifacts (models, data samples)

  • podman: rootless containers (Docker alternative); you can swap for Docker if you prefer

Initialize Git LFS once:

git lfs install

1) Scaffold a clean, review-friendly repository

Create a minimal, professional layout that reviewers will recognize immediately.

# Replace "ai-portfolio-sample" with your project name
set -euo pipefail
name=ai-portfolio-sample
mkdir -p "$name"/{src,notebooks,data/{raw,processed},models,tests,scripts,configs,.github/workflows}
cat > "$name"/README.md <<'EOF'
# AI Portfolio: Project Title

One-liner value proposition (what problem this solves).

## Quickstart

- Setup: `make setup`

- Train: `make train`

- Test: `make test`

- Run demo: `make run`

## Project Structure

- src/: source code

- notebooks/: exploratory work (keep clean & versioned)

- data/: raw and processed data (tracked with DVC or small samples with Git LFS)

- models/: trained models and artifacts

- tests/: unit and integration tests

- scripts/: CLI tools and one-off automation

- configs/: hyperparams, experiment configs
EOF

cat > "$name"/.gitignore <<'EOF'
.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/
.data_cache/
.dvc/
*.lock
EOF

cat > "$name"/LICENSE <<'EOF'
MIT License
Copyright (c) YEAR YOUR_NAME
Permission is hereby granted, free of charge, to any person obtaining a copy...
EOF

cat > "$name"/Makefile <<'EOF'
.PHONY: setup lock lint test train run clean

VENV=.venv
PY=$(VENV)/bin/python
PIP=$(VENV)/bin/pip

setup: $(VENV)/bin/activate requirements.txt
    $(PIP) install -r requirements.txt
    pre-commit install

$(VENV)/bin/activate:
    python3 -m venv $(VENV)
    $(PIP) install --upgrade pip

lock:
    $(PIP) freeze > requirements.lock

lint:
    $(VENV)/bin/ruff check .
    $(VENV)/bin/black --check .

test:
    $(VENV)/bin/pytest -q

train:
    $(PY) src/train.py

run:
    $(PY) app.py

clean:
    rm -rf $(VENV) __pycache__ .pytest_cache .mypy_cache .ruff_cache
    find . -type f -name '*.pyc' -delete
EOF

Initialize Git:

cd "$name"
git init
git add .
git commit -m "chore: initial scaffold"

2) Reproducible environment and baseline model

Pin dependencies and keep them lightweight. Start with a scikit-learn baseline—fast to run, easy to review.

cat > requirements.txt <<'EOF'
numpy
pandas
scikit-learn
joblib
matplotlib
jupyter
dvc
pre-commit
black
ruff
pytest
gradio
EOF

Add a simple training script:

cat > src/train.py <<'EOF'
import joblib
from pathlib import Path
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

def main():
    X, y = load_iris(return_X_y=True, as_frame=True)
    Xtr, Xte, ytr, yte = train_test_split(X, y, test_size=0.2, random_state=42)
    clf = RandomForestClassifier(n_estimators=100, random_state=42)
    clf.fit(Xtr, ytr)
    acc = clf.score(Xte, yte)
    print(f"Validation accuracy: {acc:.3f}")
    Path("models").mkdir(parents=True, exist_ok=True)
    joblib.dump(clf, "models/iris_rf.joblib")

if __name__ == "__main__":
    main()
EOF

Create a tiny smoke test to ensure training works:

cat > tests/test_train.py <<'EOF'
from pathlib import Path
import subprocess
import sys

def test_train_produces_model(tmp_path, monkeypatch):
    # Run training in project root so paths resolve
    res = subprocess.run([sys.executable, "src/train.py"], capture_output=True, text=True)
    assert res.returncode == 0, res.stderr
    assert Path("models/iris_rf.joblib").exists()
EOF

Bootstrap the environment and run:

make setup
make train
make test

Commit your baseline:

git add .
git commit -m "feat: baseline model, tests, and environment"

3) Manage data and artifacts the right way (Git LFS + DVC)

Small sample data and model binaries belong behind Git LFS; larger datasets belong outside Git via DVC. This keeps your repo fast and pushes heavy content to appropriate storage.

Track model artifacts with Git LFS:

git lfs track "models/*.joblib"
git add .gitattributes
git commit -m "chore: track model artifacts via Git LFS"

Initialize DVC for larger data pipelines:

. .venv/bin/activate
dvc init
git add .dvc .gitignore
git commit -m "chore: init dvc"

Example DVC pipeline (optional but powerful):

cat > dvc.yaml <<'EOF'
stages:
  train:
    cmd: .venv/bin/python src/train.py
    deps:
      - src/train.py
    outs:
      - models/iris_rf.joblib
EOF

Run and track:

dvc repro
git add dvc.yaml dvc.lock models/.gitignore
git commit -m "feat: track training as a DVC pipeline"

You can later add a remote (S3, SSH, GCS, etc.) and push:

# Example: SSH remote
dvc remote add -d storage ssh://user@host:/path/to/dvc-storage
dvc push

4) Quality gates and CI that impress maintainers

Automate linting and tests locally with pre-commit and in CI with GitHub Actions.

Pre-commit configuration:

cat > .pre-commit-config.yaml <<'EOF'
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.7
    hooks:
      - id: ruff
        args: [--fix]
  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: end-of-file-fixer
      - id: trailing-whitespace
EOF

pre-commit install
pre-commit run -a
git add .
git commit -m "chore: pre-commit (ruff, black) and initial formatting"

Add a simple GitHub Actions workflow:

cat > .github/workflows/ci.yml <<'EOF'
name: ci

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Lint
        run: |
          ruff check .
          black --check .
      - name: Test
        run: pytest -q
EOF

Commit and push to GitHub:

git add .
git commit -m "ci: add GitHub Actions for lint and test"
git branch -M main
git remote add origin git@github.com:YOUR_USER/ai-portfolio-sample.git
git push -u origin main

Optional badges in your README:

![CI](https://github.com/YOUR_USER/ai-portfolio-sample/actions/workflows/ci.yml/badge.svg)

5) A tiny demo users can try (plus containerization)

A small Gradio app lowers the friction for reviewers to interact with your model.

cat > app.py <<'EOF'
import gradio as gr
import joblib
from pathlib import Path

MODEL_PATH = Path("models/iris_rf.joblib")

def predict(sepal_length, sepal_width, petal_length, petal_width):
    if not MODEL_PATH.exists():
        return "Model not found. Run `make train` first."
    clf = joblib.load(MODEL_PATH)
    pred = clf.predict([[sepal_length, sepal_width, petal_length, petal_width]])[0]
    return f"Predicted class: {int(pred)}"

with gr.Blocks() as app:
    gr.Markdown("# Iris Classifier")
    sl = gr.Number(label="Sepal length")
    sw = gr.Number(label="Sepal width")
    pl = gr.Number(label="Petal length")
    pw = gr.Number(label="Petal width")
    out = gr.Textbox(label="Prediction")
    btn = gr.Button("Predict")
    btn.click(predict, inputs=[sl, sw, pl, pw], outputs=out)

if __name__ == "__main__":
    app.launch(server_name="0.0.0.0", server_port=7860)
EOF

Run it locally:

make train
make run
# Open http://127.0.0.1:7860

Containerize with Podman (rootless by default). Create a Containerfile:

cat > Containerfile <<'EOF'
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir --upgrade pip \
 && pip install --no-cache-dir -r requirements.txt

COPY . /app
EXPOSE 7860
CMD ["python", "app.py"]
EOF

Build and run:

podman build -t ai-portfolio-sample:latest -f Containerfile .
podman run --rm -p 7860:7860 ai-portfolio-sample:latest
# Open http://127.0.0.1:7860

Commit your demo:

git add app.py Containerfile
git commit -m "feat: add gradio demo and container"
git push

Real-world polish you can add next

  • Add examples/ with minimal datasets and commands users can copy-paste.

  • Publish a model card (MODEL_CARD.md) that states data sources, limitations, ethics.

  • Add a benchmark script and report (scripts/bench.sh + benchmarks.md).

  • Create a devcontainer (.devcontainer/) for Codespaces/VS Code reproducibility.

  • Use release tags and GitHub Releases for versioned models and changelogs.

Conclusion and Call to Action

A clean AI GitHub portfolio isn’t about flashy models—it’s about clarity, reproducibility, and respect for your reviewers’ time. You now have:

  • A Linux-first scaffold

  • Reproducible environment and data handling

  • Automated quality checks and CI

  • A demo and container to try instantly

Your next steps:

  • Pick a simple dataset or problem you care about.

  • Implement the scaffold above and push to GitHub today.

  • Iterate: add a second project, link them from a top-level profile README, and keep shipping.

When you’re ready, share your repo with a colleague and ask a single question: “Was it easy to run?” Then smooth the edges, and keep going.

Related posts