System Requirements Document for ai-agents-agentic

1. Introduction

Product intent. ai-agents-agentic is a self-guided learning product that turns a complete beginner into someone who has built and shipped a working agentic AI project in 6.5 weeks. It exists because the AI field is loud, fast-moving, and hostile to newcomers: a fresher with zero Python knowledge has no way to tell which of a thousand tutorials matter, in what order, or how far along they are. This product replaces that noise with a single ordered route — numbered weeks, named concepts, one build per week, and a visible position marker so the learner always knows where they are and what comes next.

The product is not a course platform, not a video library, and not a chatbot tutor. It is a roadmap: a structured, week-by-week plan with concrete deliverables, plus a downloadable PDF of that same plan so the learner can carry it away from the screen.

Audience. The primary and only accepted human audience is the Fresher AI Learner — a beginner starting from zero Python knowledge who wants to learn AI, AI agents, and agentic AI within a 1.5-month timeline, and who needs demonstrable built projects (a GitHub-packaged repository with a clean README, plus a short blog post) to support job interviews.

What the product must deliver. A structured 1.5-month (approximately 6.5 weeks) roadmap covering Python foundations, LLM concepts, LLM application building with prompt engineering and RAG, agents and agentic AI with frameworks and multi-agent handoff, and a final polish phase — with an emphasis on building something every week and picking one framework (LangGraph recommended). The roadmap must also be available as a generated PDF.

2. System Overview

ai-agents-agentic is a small, focused web product with three first-party surfaces and one generated document. It is delivered as a custom web application with a backend that renders the roadmap content and produces the PDF.

Actors.

There are no other accepted human personas. There are no provider-owned or external-destination surfaces in the current scope: the learner's GitHub repository and blog post are produced by the learner on external platforms that this product does not integrate with, own, or automate.

Accepted behavior at a glance.

• An anonymous landing surface that explains what the roadmap is, who it is for, and how long it takes, and offers two ways forward: start the roadmap, or download the PDF.
• A roadmap surface presenting the full 6.5-week route as one continuous vertical sequence of week bands, each with its number, title, hours estimate, deliverable, concepts, hands-on task, and build-this project.
• A PDF surface where the generated roadmap document is produced and downloaded.

Narrow exclusions. The product does not host video lessons, does not grade or assess the learner, does not track or persist learner progress across sessions, does not create or manage accounts, does not connect to the learner's GitHub or blog accounts, and does not provide an AI tutor or chat interface. The learner's own weekly builds happen outside this product, in the learner's own development environment.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. All three surfaces are first-party application surfaces. The roadmap content is authored into the product and served by the application backend; the PDF is generated by the application backend from that same roadmap content, so the PDF and the on-screen roadmap can never disagree.

Access ownership. All three surfaces are reachable without any identity, sign-in, or account. This is deliberate and matches the source: the learner is a single fresher following a public roadmap, there is no durable learner-specific state to own, no commitment or value transfer to bind to a participant, and no private data to protect. The product therefore establishes no application-owned identity, no sign-in, no session continuity, and no account management. Nothing in the product is gated.

Current vs. future boundary. Everything described in this document is current. There is no accepted future phase, no deferred capability, and no roadmap item for the product itself. The 6.5-week timeline in the product is the learner's timeline, not a delivery schedule for this software.

What the product does not claim. The product does not verify that the learner completed a week, does not store which week the learner is on, and does not send reminders. The "current week" marker described in the design direction is a visual wayfinding device on the roadmap page, not persisted learner state.

2c. Page Content and Component Coverage

Landing

Purpose. Anonymous first impression that explains the AI and agentic AI learning roadmap, its beginner audience, and its 1.5-month scope, before the learner enters the roadmap.

Information and state.

• Headline: "From zero Python to your first agentic AI project in 6.5 weeks", set left-flush and ragged right, with "agentic AI" marked by an accent underline.
• A single ruled fact row in monospace: 7 WEEKS · 1 PROJECT / WEEK · 1 SHIPPED REPO.
• A short plain-language statement of who this is for: a fresher starting from zero Python knowledge.
• A short plain-language statement of what the learner ends with: a GitHub-packaged project with a clean README and a short blog post.
• The roadmap line map as the hero image: seven coloured horizontal lines fanning from a single origin dot, each labelled WEEK 01–WEEK 07, the last line running past the viewport edge.

Primary actions.

• Start Week 01 — solid primary-red rectangle, square-ish corners, uppercase white label, with a 1px black offset rule beneath it, positioned bottom-left under the headline column. Navigates to the Roadmap.
• Download the roadmap PDF — quieter monospace text link with an accent underline, sitting beside the primary control. Navigates to the Roadmap PDF surface.

Supporting actions.

• None. The landing surface has exactly two ways forward and no secondary navigation into other product areas.

Domain entities.

• Roadmap (title, total duration, week count, weekly build cadence).
• Week (number, title, signal colour) — referenced only as line-map labels on this surface.

Component responsibilities.

• HeroHeadline — renders the display headline with the accent-marked phrase; must wrap and scale so no word is clipped at 375px, 768px, or 1280px.
• FactRow — renders the three monospace facts separated by hairline rules; wraps to stacked rows on narrow viewports.
• LineMapHero — renders the seven-line fan diagram; decorative and permitted to bleed off the right edge, but must never overlap the headline, fact row, or either control.
• PrimaryCTA — the Start Week 01 control.
• SecondaryCTA — the PDF download text link.

States.

• Loading — the landing surface is static content; no loading state is required. If the roadmap summary facts are fetched, the fact row renders a neutral placeholder of the same height so the layout does not shift.
• Empty — not applicable; the landing surface always has content.
• Success — the learner reads the scope and chooses one of the two controls.
• Error — if the roadmap summary cannot be fetched, the headline and the two controls still render, and the fact row is omitted rather than showing broken values.
• Recovery — the learner can still proceed to the Roadmap or the Roadmap PDF; neither control depends on the summary fetch.

Roadmap

Purpose. Presents the structured week-by-week roadmap covering Python foundations, LLM concepts, LLM application building, RAG, agents, agentic AI, projects, and polish activities.

Information and state.

• A persistent left rail on desktop (280px, sticky) listing Weeks 01–07 as coloured stations, with the current week marked by a filled circle and a progress line that draws down the rail as the learner scrolls.
• Seven full-width week bands in one continuous vertical route, each with:
  • a numbered header row: week number, week title, colour stripe, hours estimate, and deliverable;
  • a 3px colour stripe on the left edge in that week's signal colour;
  • left-flush sub-blocks for Concepts, Hands-on task, and Build this.
• Inline concept pictograms (24px, 2px stroke) beside the definitions of token, embedding, tool, loop, and handoff.
• Ruled code panels in monospace with an uppercase filename label and a red 3px left edge, showing a real minimal LLM call and a tool definition.
• Schematic flow diagrams for pipeline concepts (prompt → LLM → tool call → observation → loop) and a transit-style line map for the whole 6.5 weeks.

Week content (the accepted route).

Primary actions.

• Scroll and read the route — the learner moves through the seven bands in order.
• Jump to a week — selecting a station on the left rail scrolls to that week band.
• Download the roadmap PDF — a control on the roadmap surface that navigates to the Roadmap PDF surface.

Supporting actions.

• Expand or collapse a week band's sub-blocks to reduce reading load while keeping the header row visible.
• Copy a code panel's contents to the clipboard.

Domain entities.

• Roadmap (title, total duration ≈ 6.5 weeks / 1.5 months, week count 7, cadence "1 project / week").
• Week (number, title, signal colour, hours estimate, deliverable).
• Concept (name, plain-language definition, pictogram).
• Hands-on task (description, associated week).
• Build project (name, description, associated week).
• Code sample (filename, language, body).
• Pipeline diagram (ordered stages).

Component responsibilities.

• LineMapRail — sticky desktop rail; collapses to a horizontal scrollable line strip pinned under the header on tablet, and to a 7-dot progress row with the week number in monospace on mobile. Marks the current week and draws the progress line on scroll.
• WeekBand — full-width band with colour stripe, ruled header row, and the three sub-blocks.
• WeekHeaderRow — renders WEEK 03 · RAG & VECTOR STORES · 12 HRS · DELIVERABLE: DOC Q&A BOT in condensed uppercase plus monospace.
• ConceptBlock — concept name, definition, and inline pictogram.
• TaskBlock — hands-on task description.
• BuildBlock — the week's build-this project.
• CodePanel — monospace code with filename label and red left edge.
• PipelineDiagram — schematic flow diagram for a pipeline concept.
• PdfDownloadControl — the control that leads to the Roadmap PDF surface.

States.

• Loading — the rail renders as seven neutral stations and each band renders its header row with placeholder text at final height, so nothing shifts when content arrives.
• Empty — not applicable; the roadmap always contains all seven weeks. If a single week's optional sub-block has no content, that sub-block is omitted and the band closes up cleanly.
• Success — all seven bands render in order with their colour stripes, headers, and sub-blocks; the rail shows the current week and the progress line tracks scroll position.
• Error — if roadmap content fails to load, the surface shows a plain message that the roadmap could not be loaded, plus a retry control and a link to the Roadmap PDF surface, which is generated independently.
• Recovery — retry reloads the roadmap content; if it still fails, the learner can still obtain the full route from the PDF surface.
• Reduced motion — with prefers-reduced-motion, the rail is static with the current week simply filled, all bands render fully visible, and no colour bar wipes in.

Roadmap PDF

Purpose. Provides the generated roadmap as a downloadable PDF document for the learner to save and follow.

Information and state.

• The generated PDF document itself, containing the same seven-week route as the Roadmap surface: week numbers, titles, hours estimates, deliverables, concepts, hands-on tasks, and build-this projects.
• The same per-week signal colours as the on-screen roadmap, so a week's colour means the same thing in both places.
• Document metadata shown on the surface: document title, the 1.5-month / 6.5-week scope, and the generation timestamp.

Primary actions.

• Download the roadmap PDF — retrieves the generated PDF file to the learner's device.

Supporting actions.

• Regenerate — re-requests the PDF if the learner wants a fresh copy.

Domain entities.

• Roadmap PDF document (title, generated timestamp, file size, page count).
• Roadmap (the same entity rendered on the Roadmap surface).

Component responsibilities.

• PdfPanel — a white panel on the warm paper ground with a 1px hairline rule, presenting the document metadata and the download control.
• DownloadControl — the primary-red download control.
• RegenerateControl — the quieter secondary control.

States.

• Loading — the panel shows that the document is being prepared, with the download control disabled.
• Empty — not applicable; the document is always generated from the roadmap content.
• Success — the panel shows the document metadata and an enabled download control; the learner downloads the file.
• Error — if generation fails, the panel states that the PDF could not be generated, keeps the download control disabled, and offers a retry.
• Recovery — retry re-runs generation; if it fails again, the learner is directed back to the Roadmap surface, which carries the same content on screen.

3. Functional Requirements

FR-01 — Structured 1.5-month roadmap from zero

As a Fresher AI Learner I should receive a structured 1.5-month (approximately 6.5 weeks) learning roadmap that starts from zero Python knowledge and ends with AI, AI agents, and agentic AI so that I have one ordered route to follow instead of an unstructured pile of tutorials.

• Provenance: explicit
• Trigger / input: The learner opens the Roadmap surface.
• Observable result: Seven numbered week bands render in order, covering foundations, LLM concepts, LLM application building, RAG, agents and agentic AI, and polish, with a total scope stated as 1.5 months / approximately 6.5 weeks.
• Access state: No identity required; the roadmap is publicly readable.
• Failure / recovery: If roadmap content fails to load, the surface states the failure and offers retry plus a link to the PDF surface, which carries the same route.
• Continuation: The learner proceeds to Week 01 and works forward.
• Owner: Roadmap page.

FR-02 — Python foundations from zero

As a Fresher AI Learner I should be taught Python basics — functions, classes, error handling, and virtual environments — as the first stage of the roadmap so that I can write and run Python before I touch any AI tooling.

• Provenance: explicit
• Trigger / input: The learner reads Week 01 of the roadmap.
• Observable result: Week 01 presents functions, classes, error handling, and virtual environments as named concepts with a hands-on task and a build-this deliverable.
• Access state: No identity required.
• Failure / recovery: If the learner cannot run Python locally, the week's hands-on task states the prerequisite plainly so the gap is visible rather than silent.
• Continuation: The learner moves to Week 02 once the Week 01 build is done.
• Owner: Roadmap page (Week 01 band).

FR-03 — Core LLM concepts

As a Fresher AI Learner I should learn what an LLM is, what tokens are, what a context window is, what temperature does, and what embeddings are so that I understand the vocabulary before I write code against it.

• Provenance: explicit
• Trigger / input: The learner reads Week 02 of the roadmap.
• Observable result: Week 02 defines each of these five concepts in plain language, each with its inline pictogram where one applies.
• Access state: No identity required.
• Failure / recovery: Not applicable; this is static explanatory content.
• Continuation: The learner proceeds to calling an LLM API.
• Owner: Roadmap page (Week 02 band).

FR-04 — Call an LLM API from a simple Python script

As a Fresher AI Learner I should practise calling an LLM API from a simple Python script so that I have made a real model call myself rather than only read about one.

• Provenance: explicit
• Trigger / input: The learner reads the Week 02 hands-on task and code panel.
• Observable result: Week 02 includes a ruled code panel showing a real minimal LLM call in Python, with the filename labelled, and a hands-on task instructing the learner to run it and observe the response.
• Access state: No identity required. The learner's own API credentials are used in the learner's own environment; this product does not store or proxy them.
• Failure / recovery: The code panel and task note the common failure of a missing or invalid API key so the learner can recognise it.
• Continuation: The learner moves to prompt engineering in Week 03.
• Owner: Roadmap page (Week 02 band).

FR-05 — Prompt engineering

As a Fresher AI Learner I should learn prompt engineering — system prompts, few-shot prompting, and structured JSON output so that I can make a model produce reliable, machine-usable results.

• Provenance: explicit
• Trigger / input: The learner reads Week 03 of the roadmap.
• Observable result: Week 03 presents system prompts, few-shot prompting, and structured JSON output as named concepts, with a hands-on task and a build-this deliverable that returns structured JSON.
• Access state: No identity required.
• Failure / recovery: The week notes that malformed JSON output is a normal failure mode and that the prompt is the thing to fix.
• Continuation: The learner moves to RAG in Week 04.
• Owner: Roadmap page (Week 03 band).

FR-06 — RAG: chunking, vector databases, retrieval + generation

As a Fresher AI Learner I should learn RAG — chunking, vector databases such as Chroma and FAISS, and the retrieval-plus-generation pattern so that I can ground a model's answers in my own documents.

• Provenance: explicit
• Trigger / input: The learner reads Week 04 of the roadmap.
• Observable result: Week 04 presents chunking, vector databases (naming Chroma and FAISS), and retrieval + generation as named concepts, with a schematic pipeline diagram and a hands-on task.
• Access state: No identity required.
• Failure / recovery: The week notes that poor retrieval quality is the usual cause of a bad answer, and points back to chunking as the first thing to adjust.
• Continuation: The learner builds the Week 04 project.
• Owner: Roadmap page (Week 04 band).

FR-07 — Build a small document Q&A bot

As a Fresher AI Learner I should build a small document Q&A bot as the Week 04 project so that I have a working RAG application I can show.

• Provenance: explicit
• Trigger / input: The learner reads the Week 04 build-this block.
• Observable result: Week 04 names the document Q&A bot as its deliverable, with the retrieval + generation pipeline it must implement.
• Access state: No identity required. The build happens in the learner's own environment.
• Failure / recovery: The week states the expected failure mode (answers that ignore the documents) and the corrective step (revisit chunking and retrieval).
• Continuation: The learner moves to frameworks in Week 05.
• Owner: Roadmap page (Week 04 band).

FR-08 — What makes something an agent

As a Fresher AI Learner I should learn what makes something an agent — tools, memory, planning, and loops so that I can tell an agent apart from a plain LLM call.

• Provenance: explicit
• Trigger / input: The learner reads Week 06 of the roadmap.
• Observable result: Week 06 presents tools, memory, planning, and loops as the defining properties, each with its inline pictogram, and includes a schematic loop diagram (prompt → LLM → tool call → observation → loop).
• Access state: No identity required.
• Failure / recovery: The week notes that an agent looping without terminating is the characteristic failure and that a loop bound is the fix.
• Continuation: The learner proceeds to frameworks and multi-agent work.
• Owner: Roadmap page (Week 06 band).

FR-09 — Agent frameworks: LangChain / LangGraph and CrewAI

As a Fresher AI Learner I should be introduced to LangChain / LangGraph and CrewAI for multi-agent work, and be told to pick one framework with LangGraph recommended so that I commit to one toolchain instead of scattering my time across several.

• Provenance: explicit
• Trigger / input: The learner reads Week 05 of the roadmap.
• Observable result: Week 05 names LangChain / LangGraph and CrewAI, states the recommendation to pick one framework, and names LangGraph as the recommended choice.
• Access state: No identity required.
• Failure / recovery: Not applicable; this is guidance content.
• Continuation: The learner builds the single-agent project using the chosen framework.
• Owner: Roadmap page (Week 05 band).

FR-10 — Build a single agent using 2–3 tools

As a Fresher AI Learner I should build a single agent that uses 2–3 tools — search, calculator, and file read — as the Week 05 project so that I have a working agent that decides when to call a tool.

• Provenance: explicit
• Trigger / input: The learner reads the Week 05 build-this block.
• Observable result: Week 05 names the single agent as its deliverable and names search, calculator, and file read as the tools, with a ruled code panel showing a tool definition.
• Access state: No identity required. The build happens in the learner's own environment.
• Failure / recovery: The week notes that a tool the agent never calls, or calls with the wrong arguments, is the usual first failure, and points at the tool definition and description as the fix.
• Continuation: The learner moves to multi-agent work in Week 06.
• Owner: Roadmap page (Week 05 band).

FR-11 — Build a multi-agent system with handoff

As a Fresher AI Learner I should build a multi-agent system where agents hand off to each other so that I have demonstrated agentic AI rather than a single agent.

• Provenance: explicit
• Trigger / input: The learner reads the Week 06 build-this block.
• Observable result: Week 06 names the multi-agent system as its deliverable and describes agent-to-agent handoff, with the handoff pictogram used inline.
• Access state: No identity required. The build happens in the learner's own environment.
• Failure / recovery: The week notes that a handoff which loses context is the characteristic failure, and points at what must be passed across the handoff as the fix.
• Continuation: The learner moves to the polish phase in Week 07.
• Owner: Roadmap page (Week 06 band).

FR-12 — Polish phase: GitHub packaging and a blog post

As a Fresher AI Learner I should complete a polish phase in which I package one project on GitHub with a clean README and write a short blog post explaining what I built so that I have something concrete to show in an interview.

• Provenance: explicit
• Trigger / input: The learner reads Week 07 of the roadmap.
• Observable result: Week 07 names two deliverables: a GitHub-packaged project with a clean README, and a short blog post explaining what was built.
• Access state: No identity required. The repository and the blog post live on the learner's own external platforms; this product does not connect to, publish to, or verify them.
• Failure / recovery: The week states what a clean README must contain so the learner can tell whether the deliverable is actually done.
• Continuation: The learner has completed the roadmap and holds a shipped repository plus a published post.
• Owner: Roadmap page (Week 07 band).

FR-13 — Build something every week

As a Fresher AI Learner I should see a build deliverable attached to every week of the roadmap so that I am producing something concrete each week rather than only reading.

• Provenance: explicit
• Trigger / input: The learner reads the roadmap.
• Observable result: Every one of the seven week bands carries a named deliverable in its header row and a build-this block in its body.
• Access state: No identity required.
• Failure / recovery: Not applicable; this is a structural property of the roadmap.
• Continuation: The learner carries a finished build into the next week.
• Owner: Roadmap page.

FR-14 — Generate and download the roadmap as a PDF

As a Fresher AI Learner I should generate and download the roadmap as a PDF so that I can save it, print it, and follow it away from the screen.

• Provenance: explicit
• Trigger / input: The learner activates the PDF download control on the Landing or Roadmap surface, or opens the Roadmap PDF surface directly.
• Observable result: A PDF document containing the same seven-week route as the on-screen roadmap is produced and downloaded to the learner's device, with the same per-week signal colours.
• Access state: No identity required; the PDF is publicly downloadable.
• Failure / recovery: If generation fails, the surface states the failure, keeps the download control disabled, and offers a retry; if it fails again, the learner is directed back to the Roadmap surface, which carries the same content on screen.
• Continuation: The learner follows the downloaded document and returns to the Roadmap surface for the interactive route.
• Owner: Roadmap PDF page.

FR-15 — Understand the roadmap's scope before committing

As a Fresher AI Learner I should understand what this roadmap is, who it is for, and how long it takes before I start so that I can decide whether to commit to it.

• Provenance: required_inference
• Trigger / input: The learner arrives at the Landing surface with no prior context.
• Observable result: The Landing surface states the beginner starting point (zero Python), the total scope (6.5 weeks / 1.5 months), the weekly cadence (one project per week), and the end state (one shipped repository), and offers exactly two ways forward: start the roadmap, or download the PDF.
• Access state: Anonymous; no identity required.
• Failure / recovery: If the roadmap summary cannot be fetched, the headline and both controls still render and the fact row is omitted rather than showing broken values.
• Continuation: The learner selects Start Week 01 and lands on the Roadmap surface, or downloads the PDF.
• Owner: Landing page.

4. User Personas

Fresher AI Learner

Product context. A fresher in India starting from zero Python knowledge who wants to learn AI, AI agents, and agentic AI. They have 1.5 months. They are not looking for a course catalogue or a video library — they are looking for someone to tell them, in order, what to do next. The AI field's volume of competing advice is the actual obstacle: the risk is not difficulty, it is paralysis and drift.

Primary goal. Complete a structured 6.5-week route from zero Python to a shipped agentic AI project, and finish with demonstrable artifacts — a GitHub-packaged repository with a clean README and a short blog post — that they can point at in a job interview.

Distinct accepted responsibilities.

• Follow the roadmap in order, week by week, from Python foundations through LLM concepts, prompt engineering, RAG, frameworks, agents and agentic AI, to polish.
• Learn the specific named concepts at each stage: functions, classes, error handling, and virtual environments; what an LLM is, tokens, context windows, temperature, and embeddings; system prompts, few-shot prompting, and structured JSON output; chunking, vector databases (Chroma / FAISS), and retrieval + generation; tools, memory, planning, and loops.
• Practise calling an LLM API from a simple Python script.
• Build something every week, with a named deliverable each week.
• Pick one framework and commit to it, with LangGraph as the recommended choice.
• Build a small document Q&A bot.
• Build a single agent using 2–3 tools (search, calculator, file read).
• Build a multi-agent system where agents hand off to each other.
• Package one project on GitHub with a clean README and write a short blog post explaining what was built.
• Download and keep the roadmap as a PDF so the plan is available away from the screen.

Relevant inputs and decisions.

• The decision to commit to a 1.5-month plan at all, made on the Landing surface from the stated scope.
• The decision of which framework to adopt, made in Week 05, where LangGraph is recommended.
• The decision of which project to package and write about in Week 07.
• The learner's own API credentials and local development environment, which they supply themselves; this product neither holds nor proxies them.

Interactions with other accepted participants. The Fresher AI Learner is the only accepted human participant. There is no instructor, mentor, cohort, reviewer, or administrator in the product. The learner's interaction with the application is one-directional: the application presents the route and the PDF; the learner reads, builds, and returns. The learner's GitHub repository and blog post are produced on external platforms that this product does not connect to.

Observable success. The learner reaches Week 07, has a GitHub repository packaged with a clean README, has published a short blog post explaining what was built, and has a downloaded PDF of the roadmap they followed.

What makes this role's work different. The learner is not an operator of the product — they are a reader of it. There is no data for them to enter, no state for them to manage, no configuration to perform, and nothing to administer. Their work happens almost entirely outside the product, in their own editor and terminal; the product's entire job is to make the order and the next step unmistakable so that the outside work actually happens. That is why the roadmap is a single continuous route with a visible position marker rather than a browsable catalogue, and why the PDF matters as much as the screen: the plan has to survive leaving the browser.

5. Core User Flows

Flow 1 — Decide to commit and enter the roadmap

1. The Fresher AI Learner arrives at the Landing surface with no prior context and no account.
2. The learner reads the headline "From zero Python to your first agentic AI project in 6.5 weeks" and the ruled fact row 7 WEEKS · 1 PROJECT / WEEK · 1 SHIPPED REPO.
3. The learner reads the plain-language statements of who this is for (a fresher starting from zero Python) and what they end with (a GitHub-packaged project with a clean README and a short blog post).
4. The learner sees the line map hero — seven coloured lines fanning from one origin, labelled WEEK 01 through WEEK 07 — and understands the shape of the route before reading a single week.
5. The learner decides to commit and activates Start Week 01.
6. The Roadmap surface opens at Week 01.
7. Failure and recovery: if the roadmap summary facts fail to load, the headline and both controls still render and the fact row is omitted; the learner can still proceed to the Roadmap or download the PDF.

Flow 2 — Work the route week by week

1. On the Roadmap surface, the learner sees the sticky left rail listing Weeks 01–07 as coloured stations, with the current week marked by a filled circle.
2. The learner reads the Week 01 band: the ruled header row (WEEK 01 · PYTHON FOUNDATIONS · <hours> HRS · DELIVERABLE: <build>), then the left-flush Concepts, Hands-on task, and Build this sub-blocks.
3. The learner works through functions, classes, error handling, and virtual environments, and completes the Week 01 build in their own environment.
4. The learner scrolls to Week 02. The colour bar wipes in from the left as the band enters the viewport, once, and the progress line on the rail advances.
5. In Week 02 the learner reads the definitions of what an LLM is, tokens, context windows, temperature, and embeddings, each with its inline pictogram, then reads the ruled code panel labelled with its filename showing a real minimal LLM call.
6. The learner runs the LLM call from a simple Python script in their own environment using their own API credentials, and sees a response printed.
7. Failure and recovery: if the call fails on a missing or invalid API key, the week's notes let the learner recognise that specific failure and fix it in their own environment.
8. The learner continues to Week 03 and learns system prompts, few-shot prompting, and structured JSON output, and builds a script that returns structured JSON.
9. Failure and recovery: if the model returns malformed JSON, the learner adjusts the prompt, which the week identifies as the fix.
10. The learner continues to Week 04 and learns chunking, vector databases (Chroma / FAISS), and retrieval + generation, following the schematic pipeline diagram.
11. The learner builds the Week 04 deliverable: a small document Q&A bot.

12. Failure and recovery: if the bot's answers ignore the learner's documents, the week identifies retrieval quality as the cause and chunking as the first thing to adjust.
13. The learner continues to Week 05, reads the introduction to LangChain / LangGraph and CrewAI, and makes the decision to pick one framework, taking LangGraph as the recommended choice.
14. The learner builds the Week 05 deliverable: a single agent using 2–3 tools — search, calculator, and file read — following the ruled code panel that shows a tool definition.
15. Failure and recovery: if the agent never calls a tool, or calls it with the wrong arguments, the week points at the tool definition and its description as the fix.
16. The learner continues to Week 06 and learns what makes something an agent — tools, memory, planning, and loops — following the loop diagram (prompt → LLM → tool call → observation → loop).
17. The learner builds the Week 06 deliverable: a multi-agent system where agents hand off to each other, using the handoff pictogram as the reference for what crosses the boundary.
18. Failure and recovery: if a handoff loses context, the week identifies what must be passed across the handoff as the fix.
19. The learner continues to Week 07 and reads the polish phase.
20. The learner packages one project on GitHub with a clean README, using the week's statement of what a clean README must contain to judge whether the deliverable is done.
21. The learner writes and publishes a short blog post explaining what was built.
22. The learner has completed the route and holds a shipped repository plus a published post.
23. Continuation: the learner keeps the roadmap for reference and can revisit any week band by selecting its station on the rail.

Flow 3 — Download and follow the roadmap as a PDF

1. From the Landing surface, the learner activates the quieter Download the roadmap PDF text link; or, from the Roadmap surface, the learner activates the PDF download control.
2. The Roadmap PDF surface opens and shows the document metadata: title, the 1.5-month / 6.5-week scope, and the generation timestamp.
3. While the document is being prepared, the panel shows a preparing state and the download control is disabled.
4. The document is generated from the same roadmap content that the Roadmap surface renders, so the seven weeks, their hours estimates, their deliverables, and their per-week signal colours match exactly.
5. The panel shows the document metadata and the download control becomes enabled.
6. The learner activates Download the roadmap PDF and the file is saved to their device.
7. The learner reads the PDF away from the screen, printing it or keeping it open beside their editor, and follows the same seven-week route.
8. Failure and recovery: if generation fails, the panel states that the PDF could not be generated, keeps the download control disabled, and offers a retry. If the retry also fails, the learner is directed back to the Roadmap surface, which carries the same content on screen.
9. Continuation: the learner returns to the Roadmap surface for the interactive route and the position marker, and re-downloads the PDF if they want a fresh copy.

6. Visuals, Colors and Theme

Muse and headline. Erik Spiekermann — typography as infrastructure. The roadmap is a transit map: seven lines (weeks), stations (topics), interchanges (where Python meets LLMs, where RAG meets agents), and a terminus (a shipped project). The register is reassurance through order, not hype: a nervous fresher should read this as guidance, not as an exam paper.

Mode. Light mode only.

Colour tokens.

Week signal colours — each maps to exactly one week and stays consistent across the rail, the band stripe, and the PDF:

The blues that exist are one line colour among seven, not the brand. There is no blue-on-white SaaS accent anywhere in this product.

Typography.

• Headings: Fira Sans Condensed, weights 700–800, tracking -0.01em. Sentence case for roadmap titles; uppercase at 0.14em tracking for micro-labels (WEEK 03, PROJECT, SHIP IT). Large, left-flush, ragged right, never centred.
• Body: Fira Sans.
• Data and code: Fira Mono, 14px for API snippets and file paths.
• Scale: 1.25 modular with a display jump — 20 / 24 / 30 / 38 / 56 / 84.
• Display clamp: clamp(40px, 9vw, 84px) for the landing headline; clamp(28px, 4.5vw, 46px) for section titles; 24–30px for week titles; body 17px / 1.65 line height; micro-labels 12px uppercase at 0.14em.

Shape language. Hard-edged and diagrammatic. Radii of 2px and 4px at most on controls; square cards; 1px hairline rules as the dominant structural element; thick 3px colour bars as week identity stripes on the left edge of every card. No blobs, no soft shadows — depth comes from rules, colour blocks, and offset solid fills. Pictograms are 24px line icons with a consistent 2px stroke, one per concept: token, embedding, tool, loop, handoff.

Layout. A 12-column grid with a persistent left rail on desktop: a vertical line map listing Weeks 01–07 as coloured stations with the current week marked by a filled circle, 280px wide and sticky on scroll. Content occupies columns 4–12 in a single reading column of max 68ch for prose, while week cards break out to full grid width with their colour stripe. On tablet the rail collapses to a horizontal scrollable line strip pinned under the header; on mobile it becomes a 7-dot progress row with the week number in Fira Mono. The roadmap is one continuous vertical route, not a card grid: each week is a full-width band with a numbered header row, then left-flush sub-blocks. Horizontal rules separate every band; nothing floats.

Imagery. Diagrammatic, not photographic: schematic flow diagrams for pipeline concepts (prompt → LLM → tool call → observation → loop), a transit-style line map for the whole 6.5 weeks, small pictograms for tokens / embeddings / vector store / agent handoff, and Fira Mono code blocks showing a real minimal LLM call and a tool definition. For the "ship it" week, one documentary-style photograph of a desk with a laptop and notebook, desaturated warm, cropped to the grid — never a stock person pointing at a screen. No 3D renders, no gradient blobs.

Explicitly avoided. Blue-indigo primary accents on white (#2563EB, #4F46E5, #6366F1 and neighbours); Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for headings or body; gradient-blob heroes and glassmorphism panels; a uniform grid of identical hover-lift cards for the seven weeks; centred headline + subtext + pill button hero composition; 3D renders, particle fields, or AI-generated abstract imagery; soft shadows, border radii over 8px, or rounded-pill buttons; week colours used as decorative confetti.

Readable content integrity. Headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering any part of them. The line map hero and the pipeline diagrams may bleed off an edge or be cropped as decoration, but must never cover readable text or a control.

7. Signature Design Concept

The wayfinding poster.

The Landing surface is a poster, not a SaaS hero. Full-bleed warm paper #F4F1EA fills the viewport. The left two-thirds carries the headline set in Fira Sans Condensed 800 at clamp(40px, 9vw, 84px), left-flush and ragged right, breaking across four lines:

From zero Python to your first agentic AI project in 6.5 weeks

The words "agentic AI" are underlined in accent #F2B705 — a marker stroke, not a highlight block.

Directly beneath, a single row of three Fira Mono facts separated by hairline rules: 7 WEEKS · 1 PROJECT / WEEK · 1 SHIPPED REPO. On narrow viewports this row wraps to three stacked ruled lines rather than shrinking below legibility.

The right third is the hero image, and the hero image is the roadmap itself: seven coloured horizontal lines fanning out from a single dot at the left, each labelled WEEK 01–WEEK 07 in 12px uppercase, the last line running past the viewport edge to imply continuation. There is no illustration, no product screenshot, no floating card. The route is the picture.

The primary CTA is a solid #C8102E rectangle with square corners and a 4px radius, white uppercase label START WEEK 01, with a 1px black offset rule beneath it, sitting bottom-left under the headline column — never centred. Beside it, quieter, sits Download the roadmap PDF as a Fira Mono text link with a yellow underline.

The whole composition is a transit poster for a six-and-a-half-week journey: it tells the learner where the line starts, how many stops there are, and that it keeps going past the edge of what they can currently see.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief.

• Focal subject. The seven-line roadmap fan bleeding off the right edge of the viewport, with the oversized condensed headline occupying the left two-thirds.
• Input → transformation → outcome thesis. As the learner scrolls the landing surface, the seven lines extend slightly further off the right edge and the fact row's hairline rules draw in from the left, so the poster resolves from a static image into a legible route before the learner reaches the Start Week 01 control. Nothing is revealed that was not already there; the motion only orders the reading.
• Motion vocabulary. Short and purposeful, 160–220ms ease-out. Hairline rules draw in from the left. The accent underline beneath "agentic AI" settles into place once. No parallax, no bounce, no hover-lift.
• Composed first frame. Warm paper ground; headline fully set and legible across four lines; the accent underline already present; the fact row already present; the seven-line fan already visible with its WEEK 01–WEEK 07 labels; both controls fully rendered and legible. The first frame is a complete poster — motion only adds ordering, never content.
• Reduced-motion state. With prefers-reduced-motion, the poster renders fully composed and static: no rule draw-in, no underline settle, no line extension. Every element is visible and legible in its final position.

Roadmap surface motion. The rail's active-station fill transitions in 160–220ms ease-out. A week band's colour bar wipes in from the left once when the band enters the viewport, and does not repeat. A progress line draws down the left rail as the learner scrolls. Micro-labels tick over instantly. Hover states are colour and underline changes only — no lift, no shadow, no scale. With prefers-reduced-motion, the rail is static with the current week simply filled, all bands render fully visible, and no colour bar wipes in.

No 3D. The direction specifies flat hero dimensionality and explicitly avoids 3D renders and particle fields. No Canvas, WebGL, or 3D scene is required or expected for this product.

9. Non-Functional Requirements

• NFR-01 — Timeline fidelity. The roadmap must present a total scope of 1.5 months, approximately 6.5 weeks, and must not present a longer or shorter route. Provenance: explicit (hard constraint). Rationale: the learner's available time is the defining constraint of the product.
• NFR-02 — Zero-prerequisite entry. No part of the roadmap may assume prior Python knowledge. Week 01 must begin at functions, classes, error handling, and virtual environments. Provenance: explicit (hard constraint). Rationale: the learner is starting from zero; any assumed prerequisite breaks the route at its first step.
• NFR-03 — Weekly build cadence. Every week must carry a named deliverable. A week without a build is a defect. Provenance: explicit. Rationale: the source requires building something every week.
• NFR-04 — Single-framework guidance. The roadmap must present one framework recommendation (LangGraph) rather than an open menu, while still naming LangChain / LangGraph and CrewAI. Provenance: explicit. Rationale: the source requires picking one framework; an open menu reintroduces the paralysis the product exists to remove.
• NFR-05 — PDF and screen agreement. The generated PDF must be produced from the same roadmap content the Roadmap surface renders, so week numbers, titles, hours estimates, deliverables, and per-week signal colours match exactly. Provenance: required_inference. Rationale: a learner following the PDF and a learner following the screen must be following the same plan.
• NFR-06 — Anonymous access. All three surfaces must be reachable without identity, sign-in, or account creation. Provenance: required_inference, consistent with the accepted access contract. Rationale: there is no durable learner-specific state, no commitment, and no private data in the product; gating would add friction with no benefit.

• NFR-07 — No learner progress persistence. The product must not store which week the learner is on or whether a week was completed. The current-week marker is a visual wayfinding device, not persisted state. Provenance: required_inference. Rationale: no accepted requirement establishes progress tracking, and inventing it would create an account-management obligation the source does not support.
• NFR-08 — Readable content integrity. Headlines, labels, numbers, card text, and controls must remain entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no element covering any part of them. Provenance: explicit (design constraint).
• NFR-09 — Reduced-motion support. With prefers-reduced-motion, the rail must be static with the current week filled, all week bands must render fully visible, and no colour bar may wipe in. Provenance: explicit (design constraint).
• NFR-10 — Colour consistency. Each week's signal colour must map to exactly one week and remain identical across the rail, the band stripe, and the PDF. Provenance: explicit (design constraint).
• NFR-11 — No credential handling. The product must not collect, store, or proxy the learner's LLM API credentials. Code samples show the call; the learner supplies their own key in their own environment. Provenance: required_inference. Rationale: the source places all building in the learner's own environment and establishes no account or secret storage.
• NFR-12 — No external platform integration. The product must not connect to, publish to, or verify the learner's GitHub repository or blog post. Provenance: required_inference. Rationale: the source names these as the learner's own deliverables, not as product capabilities.

10. Tech Stack

• Frontend: React — a single-page application serving the Landing, Roadmap, and Roadmap PDF surfaces. [Default — not specified by user]
• Backend: Python with FastAPI — serves roadmap content and generates the roadmap PDF from that same content. [Default — not specified by user]
• PDF generation: A Python PDF library invoked by the backend, rendering the roadmap with the same per-week signal colours as the on-screen route. [Default — not specified by user]
• Storage: None required for current scope. The roadmap is authored content, not user data; there is no learner state to persist. [Default — not specified by user]
• Containerization: Docker with docker-compose, running the frontend and the backend as two services. [Default — not specified by user]
• Kubernetes: Not required. The product is a small, stateless, low-traffic learning site. [Default — not specified by user]

11. Assumptions and Constraints

Constraints (source-stated, binding).

• The timeline is 1.5 months. The roadmap must fit within it.
• The learner is starting from zero Python knowledge. No prior programming is assumed.
• The roadmap must cover Python basics (functions, classes, error handling, virtual environments), LLM concepts (what an LLM is, tokens, context windows, temperature, embeddings), LLM app building (prompt engineering with system prompts, few-shot, structured JSON output; RAG with chunking, vector databases such as Chroma / FAISS, retrieval + generation; a small document Q&A bot), agents and agentic AI (tools, memory, planning, loops; LangChain / LangGraph and CrewAI; a single agent with 2–3 tools; a multi-agent system with handoff), and a polish phase (GitHub packaging with a clean README, plus a short blog post).
• The roadmap must emphasize building something every week and picking one framework, with LangGraph recommended.
• A PDF of the roadmap must be generated.

Assumptions (narrow, labeled).

• A-01. The learner has access to a computer on which they can install Python and run scripts. This is implied by the requirement to practise calling an LLM API from a simple Python script, but the product does not supply or verify the environment.
• A-02. The learner obtains their own LLM API credentials. The product shows the call and does not provide, store, or proxy a key.
• A-03. The learner has or creates their own GitHub account and blog platform. The product names these as Week 07 deliverables and does not integrate with either.
• A-04. The seven-week structure is the concrete realization of the stated 1.5-month / approximately 6.5-week timeline. The source states the duration and the phases; the week count is the natural decomposition of that duration.
• A-05. The "current week" marker on the roadmap rail is a visual wayfinding device derived from scroll position, not persisted learner progress. No accepted requirement establishes progress tracking.
• A-06. The product is delivered in English. The source is written in English and names no other language.

Explicit exclusions.

• No video lessons, no course catalogue, and no media library.
• No assessment, grading, or certification.
• No learner accounts, sign-in, or session continuity.
• No persisted progress tracking or completion state.
• No reminders, notifications, or scheduling.
• No AI tutor, chat interface, or conversational guidance.
• No integration with GitHub, blog platforms, or any external service.
• No instructor, mentor, cohort, reviewer, or administrator role.

12. Glossary

• Agent — A system in which an LLM can use tools, hold memory, plan, and run in a loop, rather than producing a single response. Distinguished from a plain LLM call by those four properties.
• Agentic AI — The practice of building systems composed of one or more agents that plan, act through tools, and hand off work to each other toward a goal.
• Chunking — Splitting source documents into smaller passages before embedding them, so that retrieval can return a passage small enough to be useful in a prompt.
• Context window — The maximum amount of text, measured in tokens, that a model can consider at once.
• CrewAI — A framework for building multi-agent systems, named in the roadmap alongside LangChain / LangGraph.
• Embedding — A numeric vector representation of text, used to compare meaning and to retrieve relevant passages.
• FAISS — A vector database / similarity search library, named in the roadmap alongside Chroma.
• Few-shot prompting — Supplying a small number of worked examples in a prompt so the model follows the intended pattern.
• Handoff — The point at which one agent passes work and context to another agent in a multi-agent system.
• LangChain — A framework for building LLM applications, named in the roadmap alongside LangGraph.
• LangGraph — A framework for building agent workflows, named in the roadmap and recommended as the single framework to pick.
• LLM — Large Language Model; a model that generates text from a prompt.
• Loop — The agent cycle of prompt → LLM → tool call → observation → repeat, which must terminate.

• Memory — State an agent carries across steps of its loop or across turns.
• Multi-agent system — A system of two or more agents that coordinate, including by handing off to each other.
• Prompt engineering — Designing the instructions given to a model, including system prompts, few-shot examples, and output format constraints such as structured JSON.
• RAG (Retrieval-Augmented Generation) — Retrieving relevant passages from a document store and supplying them to the model so its answer is grounded in those documents.
• Retrieval + generation — The two-stage RAG pattern: find relevant passages, then generate an answer conditioned on them.
• Structured JSON output — Constraining a model's response to valid JSON so downstream code can consume it.
• System prompt — The instruction that sets a model's role and rules for a conversation.
• Temperature — A model setting that controls how random or deterministic its output is.
• Token — The unit of text a model reads and generates; roughly a word fragment.
• Tool — A function an agent can call, such as search, a calculator, or file read.
• Vector database — A store of embeddings that supports similarity search; Chroma and FAISS are named in the roadmap.
• Virtual environment — An isolated Python environment that keeps a project's dependencies separate from the system Python.