Portfolio

Overview

Most AI portfolios are the same project with a different colour scheme: a chat wrapper around an API key, deployed once, README generated by the model it calls.

A reviewer spends about ninety seconds before deciding. In that time they are answering three questions — does it work, did you handle the parts that are hard because a model is involved, and can you explain a decision in your own words. This lesson is about what those ninety seconds actually look like, and how to build a project that survives them.

Theory

A reviewer asks three questions, in order. Does it work, and can I see it working without cloning it? Did this person handle the parts that are hard because a model is involved? Can they explain a tradeoff in their own words? Everything else is decoration.

Lead with what it does and how to see it. The first screen of the README should be one sentence and a screenshot or a clip. A reviewer gives you ten seconds before deciding whether to keep reading, and "npm install" is not what keeps them.

Zero-setup demo beats detailed setup instructions. A live link removes every excuse not to look. If you cannot host it, a thirty-second recording is the next best thing — and both beat a perfect installation guide nobody follows.

Show the AI-specific work, because that is what is being assessed. Anyone can call an API. What separates you is the eval set, the retry and fallback path, the token budget, the cost per request, the thing you did when the model returned nonsense.

An honest limitations section reads as competence, not weakness. "Chunking is naive, this breaks on tables" tells a reviewer you know where the edges are. Its absence suggests you never looked.

Visual Diagram

The path is linear and unforgiving: title and one-line description first (do they even understand what this is), then a demo link or GIF (do they believe it's real), then a short "what was hard" section (do they see AI-engineering judgment, not just working code), then — only for reviewers who are still interested — the actual code. Most reviewers drop off after any one of the first three steps fails to deliver. The entire job of a portfolio write-up is keeping the reviewer moving down that path.

Examples

Concrete portfolio entries built from projects already in this course, written the way a reviewer would want to see them:

• The Day 18 RAG project, written up as: "Answers questions over [dataset] with cited sources. Eval set of 20 questions scores 85% exact-match after adding a re-ranking step, up from 60% with naive top-k retrieval — the re-ranking step was the single biggest quality lever." That last clause is the tradeoff/judgment signal.
• The Day 24 agent workbench, written up as: "An agent that can look up an order and draft (never auto-send) a refund email using three tools. Capped at 6 tool calls per run after early testing showed it could loop indefinitely on ambiguous requests — a concrete failure mode, and the fix, in one sentence."
• The Day 30 capstone, written up with a cost line: "Costs approximately $0.004 per interaction at current usage; caching cut that from $0.011." A specific number a reviewer can sanity-check beats "optimized for cost."

Code

A small script that turns a project's evaluation results into the kind of concrete, skimmable table a README should lead with — the "evidence, not adjectives" principle from the Theory section, automated so it's easy to keep up to date as your eval set grows.

interface EvalCase {
  id: string;
  passed: boolean;
  latencyMs: number;
  costUsd: number;
}

interface EvalSummary {
  total: number;
  passed: number;
  passRate: number;
  p95LatencyMs: number;
  avgCostUsd: number;
}

function summarize(results: EvalCase[]): EvalSummary {
  const total = results.length;
  const passed = results.filter((r) => r.passed).length;
  const sortedLatency = [...results].map((r) => r.latencyMs).sort((a, b) => a - b);
  const p95Index = Math.min(sortedLatency.length - 1, Math.floor(sortedLatency.length * 0.95));

  return {
    total,
    passed,
    passRate: total === 0 ? 0 : passed / total,
    p95LatencyMs: sortedLatency[p95Index] ?? 0,
    avgCostUsd: total === 0 ? 0 : results.reduce((sum, r) => sum + r.costUsd, 0) / total,
  };
}

/** Renders a Markdown table suitable for pasting straight into a README's
 * "Results" section — the kind of concrete number a reviewer trusts more
 * than a paragraph of adjectives. */
function toMarkdownTable(summary: EvalSummary): string {
  const rows = [
    ["Metric", "Value"],
    ["Eval cases", `${summary.total}`],
    ["Pass rate", `${(summary.passRate * 100).toFixed(1)}%`],
    ["p95 latency", `${summary.p95LatencyMs.toFixed(0)}ms`],
    ["Avg cost / request", `$${summary.avgCostUsd.toFixed(4)}`],
  ];
  return rows.map((row) => `| ${row.join(" | ")} |`).join("\n").replace(
    /^(\| Metric \| Value \|)\n/,
    "$1\n| --- | --- |\n",
  );
}

// Example usage — run against real logged eval results, not made-up numbers.
const results: EvalCase[] = [
  { id: "q1", passed: true, latencyMs: 820, costUsd: 0.0021 },
  { id: "q2", passed: true, latencyMs: 1340, costUsd: 0.0034 },
  { id: "q3", passed: false, latencyMs: 2100, costUsd: 0.0041 },
];

console.log(toMarkdownTable(summarize(results)));

Wire this to the eval harness you already built in Week 3 and Day 25's monitoring work — the same eval set that catches regressions in production is the exact data a portfolio README should be quoting. A number that's actually computed from your own eval runs is worth more than a hand-written claim, and it costs you nothing extra to generate since the eval infrastructure already exists.

Real Product Example

Look at how well-regarded open-source AI tooling structures its own README — the Vercel AI SDK repository is a good reference precisely because it's read by thousands of engineers deciding, in seconds, whether to adopt it. The README leads with a minimal working code example before any explanation of internals, links out to full documentation rather than trying to be the documentation, and keeps badges (build status, npm version, license) compact and above the fold rather than scattered through the page. None of that is an accident — it's the same 90-second-skim optimization this lesson is about, applied at the scale of a library instead of a portfolio project. The mechanism that generalizes: a reader should be able to understand what the thing does and see it work before they're asked to understand how it's built.

Common Mistakes

Senior Tips

Exercises

Mini Project

Write up the capstone. Turn your agent workbench (Day 24) or AI SaaS project (Days 19-26) into a portfolio entry that could survive a real 90-second review.

1. Write a README with, in order: a one-sentence description, a demo link or GIF, a "results" table generated from real eval data, a short "what was hard" section naming one concrete tradeoff, and an honest limitations list.
2. Deploy or record a demo that requires zero setup to view.
3. Have someone else — a classmate, a friend, anyone who hasn't seen the project — read only the README for 90 seconds and tell you what they think it does. If they get it wrong, the README failed, not the reader.
4. Revise based on what they misunderstood.

Resources

• Make a README: a compact, practical guide to what sections a README needs and why, with a template that maps directly onto the structure this lesson recommends.
• awesome-readme: a curated list of real, well-regarded project READMEs worth studying for structure and tone before writing your own.
• Hamel Husain — Your AI Product Needs Evals: the same evaluation discipline from Week 3 and Day 25, reframed here as the source of the concrete numbers a strong portfolio write-up quotes.