Python, tooling, and compute options

Tooling you will actually use

ShipAI assumes a working engineer laptop, not a research cluster with a dedicated ops team. The tooling choices below are not arbitrary — they mirror what AI engineering teams actually use in 2025–2026, scaled down for a solo learner.

You do not need an NVIDIA 4090 on day one. The setup and literacy modules stay CPU-friendly. The mini-LLM module is designed to train a tiny model on CPU or free Colab. The SLM module may need a free or cheap GPU hour for LoRA fine-tuning — plan for that, but do not let hardware anxiety block you from starting.

Callout — pick uv or poetry, not both: Switching package managers mid-course creates merge conflicts in lockfiles and wastes time. If you are unsure, uv is faster for fresh projects; poetry is fine if you already use it at work.

Python environment setup

Why 3.11+

Python 3.11 brought meaningful speedups and improved error messages. Python 3.12+ works too. Avoid 3.9 or 3.10 for new projects — some modern AI libraries have already dropped support for older versions.

Recommended baseline with uv

# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Pin Python version
uv python install 3.11

# Inside course-portfolio
cd course-portfolio
uv init --name course-portfolio   # or add pyproject.toml by hand
uv add pytest httpx pydantic python-dotenv

If you prefer poetry:

poetry init
poetry add pytest httpx pydantic python-dotenv
poetry env use python3.11

Both workflows should produce a lockfile (uv.lock or poetry.lock) that you commit. Never commit .venv/ — it is machine-specific and bloated.

Core dependencies and why

• pytest — the course standard for deterministic tests; golden fixtures and parsers get pytest files from day one.
• httpx — modern HTTP client for API calls; you will log LLM requests with it in the next lesson.
• pydantic — schema validation for configs, tool outputs, and eval results; appears again in agent modules.
• python-dotenv — loads .env without committing secrets; pairs with the API keys lesson.

Add more dependencies per module. Resist the urge to pip install everything upfront — pinned, incremental deps are easier to debug.

Make as your contract with reviewers

A root Makefile turns your portfolio into something runnable without reading three README files. Start minimal:

.PHONY: doctor
doctor:
	@python -c "import sys; assert sys.version_info >= (3, 11), sys.version"
	@python -c "import httpx, pydantic; print('deps ok')"
	@command -v docker >/dev/null && docker version --format 'docker ok' || echo 'docker: missing (ok for Onboarding)'
	@echo "doctor: pass"

As the course progresses, you will add targets like test, train-tiny-gpt, serve, and eval. The pattern stays the same: one documented entrypoint, exit code 0 on success, loud failure on missing deps.

Make is not fashionable in every stack, but it is universal enough that a hiring manager on macOS, Linux, or WSL can run your project. If you strongly prefer just or task, document the equivalent — but ShipAI examples use Make.

Compute options: map, don't overbuy

AI courses often open with "buy a GPU" or "use our cloud." ShipAI separates literacy compute from training compute so you spend money and time deliberately.

Local CPU

Sufficient for: API literacy, agent prototypes that call hosted models, tiny bigram models, sklearn baselines, pytest suites, and most RAG prototyping with embedding APIs. If you only have a laptop without a discrete GPU, you can reach the agent modules before needing heavy local training.

Local GPU

Nicer for mini-LLM and SLM modules: faster iteration, no Colab session timeouts. Not required. Apple Silicon (M-series) can run small models via MLX or CPU fallback; NVIDIA GPUs with CUDA are the straightforward path for PyTorch training.

Colab / Kaggle / cloud notebooks

Fine for training scripts you run occasionally. Workflow: develop locally, upload or git-pull the script, train, download checkpoints (model.pt, metrics JSON) back into course-portfolio. Document the notebook URL and runtime (e.g., "Colab T4, 45 min") in your README — reproducibility includes where the job ran.

Docker

Becomes important when you compose services: vector DB, inference server, FastAPI app, Redis for caching. You do not need Docker for the setup module, but install it if you can — make doctor will report whether it is present.

Callout: Prefer documenting how you ran a train job over chasing the biggest GPU. Portfolio reviewers care about reproducibility, honest metrics, and clear entrypoints — not whether you owned a 4090.

Engineering problem (staff framing)

AI work fails on environment entropy more than algorithms. Build a deterministic lab: same commands → same results for you and a reviewer.

Diagram — Compute decision tree

flowchart TD
  N{Need GPU?} -->|No| CPU[CPU / Apple Silicon]
  N -->|Brief| Colab[Notebook + export scripts]
  N -->|Recurring| Cloud[Cloud GPU + checkpoints]
  CPU --> Art[Git: code, configs, evals]
  Colab --> Art
  Cloud --> Art

Precise definitions & mental model

• Isolated envs (uv/venv), lockfiles, doctor scripts, artifact boundaries (weights out of git).

Tradeoffs — when to use what

Failure modes (interview + on-call)

• Notebook-only experiments with no exported scripts.
• Committing .venv or weights; assuming CUDA APIs on MPS.

Production & OSS practices

CI CPU smoke tests + optional GPU job; OpenAI-compatible local servers so providers are swappable.

Deep dive (FAANG / OSS bar)

Push «python-tooling-and-compute» past tutorial depth: write the interface contract (inputs/outputs/invariants), list three measurable metrics, and name two degrade modes if the happy path fails. Add a short threat note: what an attacker or noisy tool result could do, and which layer catches it (schema, policy, HITL, or eval gate).

flowchart LR
  Contract[Interface contract] --> Metrics
  Metrics --> Degrade[Degrade modes]
  Degrade --> Threat[Threat + control]

Micro-project: make doctor

In m0/ (create the directory if it does not exist):

1. Wire make doctor (or uv run make doctor) so it fails loudly on missing Python version or core deps. Exit code must be non-zero on failure.
2. Print a short JSON or text report: Python version, OS, Docker present?, CUDA present? (CUDA check can be optional — torch.cuda.is_available() if torch is installed, or nvidia-smi if available).
3. Commit under m0/doctor/ with a brief README explaining what the script checks.

Example report shape:

{
  "python": "3.11.9",
  "platform": "darwin",
  "docker": true,
  "cuda": false
}

This artifact becomes the first row in your setup module README summary and proves your environment is reproducible.

Checklist

• Python ≥ 3.11 available
• Locked dependency workflow chosen (uv or poetry)
• make doctor exits 0 on your machine
• Report committed to the portfolio