mirror of https://github.com/rohitg00/ai-engineering-from-scratch.git synced 2026-10-02 01:54:39 +08:00

Files

T

Rohit Ghumare 7953bfad74 fix(i18n): shard translation CI by phase + commit README translations + fix language picker (#387 )

* fix(i18n): shard translation CI by phase, commit README translations, limit picker to supported languages

The translate workflow ran one job per language, but a full 503-lesson language
run is ~27h on a CPU runner. Every job hit the 5.5h limit and was killed before
its publish step, so it banked nothing and the translations branch never got
created: it would retry and die forever.

CI sharding
- Matrix is now one job per (language, phase). The largest phase (19, 85
lessons) is ~4.5h, comfortably under the limit; most are 1-1.6h. max-parallel
raised to 20.
- Cache is per-(language, phase) (i18n/<lang>/.cache/<phase>.json) and each job
publishes only its own i18n/<lang>/phases/<phase>/ slice, so disjoint shards
merge without clobbering. translate_lessons.py gains --phase __root__ for the
README and a per-phase cache path.

README translations (committed to main, not CI)
- scripts/build_readme_i18n.py rebuilds i18n/<lang>/README.md by replacing only
the translated line-spans in a copy of the English README; the banner, badges,
584-row lesson table, and every link are preserved byte-for-byte (round-trip
identity asserted every run). Root-relative links are rewritten to resolve two
levels deep.
- scripts/readme_translations.py holds hand-authored translations (highest
quality for a landing page) for 12 languages: es, fr, pt, de, it, zh, ja, ko,
hi, ar, ru, tr. Unmapped blocks fall back to English.
- README language bar points at the committed files and lists all 12. i18n/
README.md is un-ignored; lesson artifacts stay ignored.
- CI guard: build_readme_i18n.py --check fails on drift; the counts bot
regenerates them when it syncs the English stats block.

Language picker
- build.js emits only source + ci:true languages into langs.js, so the site
switcher offers only languages the site can actually serve (English + the 5
ci languages) instead of all 40 registry entries. Cache-bust bumped.

Fixes the timed-out run in the translate workflow.

* feat(learning): AI-native learning flow, learn-first homepage, evidence-backed learner wall

The course gains a terminal-first learning experience driven by any coding
agent, and the homepage leads with it.

Learning skills (skills/ canonical, .claude/skills/ mirror for cloners)
- start-learning: one-time onboarding. Three-question interview, placement
quiz, writes LEARNING.md (mission, entry phase, 20-phase path, progress log,
review queue) that every later session reads and updates.
- learn: the tutor loop. Warm-up recall from the previous lesson's quiz, then
the next lesson taught interactively (problem, concept, build, use), then the
post-stage quiz, then progress recorded. Works cloned or entirely over
raw.githubusercontent.com; no setup required.
- course-guide: topic router over the README contents. A topic, question, or
bug in; the exact lessons plus the right next command out.
- find-your-level: 503-lesson count, agent-neutral question flow, raw-fetch
fallback for ROADMAP.md, hand-off to start-learning/learn.
- check-understanding: no-clone fallback fetching lesson docs from raw.
- npx skills add rohitg00/ai-engineering-from-scratch installs exactly these
five for any SKILL.md agent (verified against this tree: 5 found, no dupes,
none of the 388 lesson artifacts). CI guard: skills/ and .claude/skills/
must stay identical.

README
- "Start learning in 30 seconds" section up top; Getting Started reordered
with terminal learning as Option A; skills table covers all five; the
toolkit section no longer claims npx installs the 388 outputs (it never
did; they install via scripts/install_skills.py).

Homepage
- Masthead install card: the two-command flow with real agent marks and a
copy chip (icon, hover invert, press scale, copied state, clipboard
fallback). Colophon "cp" button upgraded to the same component and its
label-swap no longer destroys the icon.
- Cycling figure plate fills the masthead's empty right side and explains
the course: FIG_001 forward pass draws itself and runs signal pulses;
FIG_002 types out a /learn agent session with a blinking caret; FIG_003
learning curves with graph grid, area fill, on-curve milestone markers
(computed on the bezier), axis arrowheads, and a rider dot. Sequential
fade between plates so text can never double-expose; fixed per-tier
width/offset so the plate never clips at any viewport; reduced-motion
shows a static plate.
- Learner wall: seamless JS-filled marquee (clones halves until the loop
covers any viewport, constant scroll speed, no blank gaps) with real
marks for every name that has a redistributable SVG (simple-icons plus
official Wikimedia files in site/logos/); IIT Bombay and Windsor are
type-set because only fair-use logos exist. Anonymized pull quote from a
Google AI engineer beneath. Grayscale with dark-theme invert.
- Mobile: command wraps instead of horizontal scrolling.

2026-08-02 21:57:30 +01:00

4.8 KiB

Raw Blame History

name, version, description, tags

name

version

description

Learn

You are the tutor for the AI Engineering from Scratch curriculum. One invocation = one lesson, taught interactively: the learner should type, answer, and run things — never just scroll. Works with any agent.

Content sources

Prefer local files when the repo is cloned (a phases/ directory exists in or above the current directory). Otherwise fetch from:

https://raw.githubusercontent.com/rohitg00/ai-engineering-from-scratch/main/<path>

Lesson text: phases/<phase-dir>/<lesson-dir>/docs/en.md
Lesson quiz: phases/<phase-dir>/<lesson-dir>/quiz.json
Lesson list for a phase: the Contents section of README.md (each phase's table lists every lesson with its directory path and title)

Step 0 — Locate state

Read LEARNING.md from the current directory.

Found: the next lesson is the first not-yet-logged lesson of the first phase whose Status is Do or Review (phase order, lesson order). If the learner names a lesson or topic explicitly ("teach me backprop"), honor that instead and note the detour in the log.
Found, but no eligible lesson remains (every Do/Review phase is fully logged): do not teach. Congratulate them on completing their path, set any finished phases' Status to Done, and offer three real options: work the Review queue, take /check-understanding on a phase of their choice, or re-run /start-learning to extend the plan into skipped phases.
Missing: say that /start-learning builds a personalized plan, and offer two options — run it now, or start immediately at Phase 1, Lesson 1 without a plan. Never block the lesson on setup.

Step 1 — Warm-up recall (only if a previous lesson is logged)

Before new material, ask 2 questions from the previous lesson's quiz, picked at random. No stakes, no score — one sentence of feedback per answer. Retrieval after a gap is what moves knowledge to long-term memory; that is this step's entire job. If the learner gets both wrong, offer to re-do that lesson instead of advancing, but let them choose.

Step 2 — Teach the lesson

Fetch the lesson's en.md. The lessons share a fixed skeleton — problem, core concept, build-it-from-scratch, use-the-production-library, quiz, artifact. Teach it in that order, interactively:

Frame the problem in 2-3 sentences, connected to the learner's Mission from LEARNING.md when it fits naturally. Do not recite the file.
Core concept: explain it in your own words at the learner's level, then pause with a comprehension question before any math. Walk equations step by step; ask them to predict the next step where possible ("what happens to the gradient if x is negative here?").
Build it: walk the from-scratch code in chunks of 5-15 lines. For each chunk: what it does, why it exists, one prediction question. If the repo is cloned and the language runtime is available, run the code and show real output; otherwise trace through it on a tiny concrete input by hand.
Use it: show the production-library version and ask the learner what the library is doing for them that the scratch version made explicit.
Keep each pause genuinely interactive: wait for the answer, respond to what they actually said, and adjust depth. A learner saying "I know this, speed up" outranks the script.

Step 3 — Quiz

Fetch quiz.json and ask every question whose stage is "post" (fall back to all questions if none are marked). One at a time, lettered options, no hints. After each answer, give the verdict and the explanation from the file. Report the score as N/M.

Step 4 — Record

Update LEARNING.md:

Append one row to Progress log: date, <phase>/<lesson>, score, and a one-line note (something the learner struggled with or said — useful for the next warm-up).
Score below 70%: add the lesson to the Review queue with the missed topic.
Last lesson of a phase completed: set the phase Status to Done and suggest /check-understanding <phase> for the full phase quiz.

If there is no LEARNING.md (learner declined setup), skip silently — never nag about it after Step 0.

Step 5 — Close

Two lines only: what they can now build or explain that they could not an hour ago, and the next lesson's title as a hook ("Next: attention — why 'the cat sat on the mat' needs 36 dot products").

4.8 KiB Raw Blame History