dify-guides/_tools/make_samples.py

#!/usr/bin/env python3
"""Generates the fictional sample documents used in the guides, in English:

  02-agent-knowledge-base/school-guide-example-college.pdf
  03-school-communication/style-guide-example-college.pdf
  06-inclusive-materials/lesson-booklet-ecology.pdf   (copy in 08)
  08-chatflow-study-coach/study-planner-biology-y9-ecology.pdf
  04-agent-console/exam-timetable-example.csv
  05-transcription-tool/department-meeting-script.txt

Everything is invented: school, staff, dates, addresses. Usage: python3 _tools/make_samples.py
Requires google-chrome (headless) and python3-markdown.
"""
import shutil
import subprocess
from pathlib import Path

import markdown

ROOT = Path(__file__).resolve().parent.parent
CSS = """
@page { size: A4; margin: 2cm; }
body { font-family: "Noto Sans", "DejaVu Sans", Arial, sans-serif; font-size: 11pt; line-height: 1.45;
       color: #1a1a1a; max-width: 17cm; margin: 0 auto; }
h1 { font-size: 20pt; margin: 0 0 .2em; } h2 { font-size: 14pt; margin: 1.4em 0 .4em; color: #14532d; }
h3 { font-size: 12pt; margin: 1.1em 0 .3em; }
table { border-collapse: collapse; width: 100%; margin: .6em 0; font-size: .95em; }
th, td { border: 1px solid #cbd5e1; padding: .3em .5em; text-align: left; vertical-align: top; }
th { background: #f0fdf4; }
.kop { color: #555; margin-bottom: 1.2em; }
"""

SCHOOL_GUIDE = """
# School Guide, Example College

<p class="kop">School year 2026-2027 · fictional school for the AI Agents workshop</p>

## 1. Lesson times

The school runs a 50-minute timetable. The first lesson starts at 8.30, the last lesson ends at 16.10 at the latest. On Wednesdays lessons end at 13.50.

| Period | Time |
| --- | --- |
| 1 | 8.30 - 9.20 |
| 2 | 9.20 - 10.10 |
| Break | 10.10 - 10.30 |
| 3 | 10.30 - 11.20 |
| 4 | 11.20 - 12.10 |
| Break | 12.10 - 12.40 |
| 5 | 12.40 - 13.30 |
| 6 | 13.30 - 14.20 |
| Break | 14.20 - 14.30 |
| 7 | 14.30 - 15.20 |
| 8 | 15.20 - 16.10 |

## 2. Reporting illness and absence

If a student is ill, a parent or carer reports this before 8.15 through the parent portal or by phone to reception on 01632 960123. A sick report is valid for one day; if the student is still ill the next day, a new report is needed.

Unauthorised absence is reported to the form tutor after three periods. After sixteen hours of unauthorised absence in four weeks the school is obliged to inform the local attendance officer.

Leave outside the school holidays can only be requested from the head of year, at least six weeks in advance and with a written reason.

## 3. Homework and tests

Homework is posted in the digital learning environment by 17.00 on the day of the lesson. Students in years 7 to 9 have at most two tests per day and at most five tests per week. A test is announced at least five school days in advance.

A missed test is taken at the fixed catch-up slot: Tuesday, period 8. The student registers with the teacher within two school days of returning to school.

## 4. Phones and laptops

Phones go into the phone pouch on entering the classroom and stay there until the end of the lesson. Phones may be used during breaks and in the hall. Every student brings a charged laptop every day; the school does not lend chargers.

## 5. Form tutors and support

Every class has a form tutor. The form tutor is the first point of contact for students and parents. For questions about dyslexia, test anxiety or extra support, the form tutor refers to the support coordinator. A meeting with the support coordinator is always requested through the form tutor.

## 6. Contact

Reception: 01632 960123, on school days from 8.00 to 16.30.
Email: info@examplecollege.example
Address: 1 School Street, Exampletown
"""

STYLE_GUIDE = """
# Style guide for parent letters and news

<p class="kop">Example College, communications team · school year 2026-2027 · fictional practice document for the Dify guides</p>

## 1. Who we write for

Our parents are busy, read on their phones, and do not all have English as their first language. A letter from school must be clear at first reading: what is happening, what does it mean for my child, and what do I need to do. A parent who has to phone the school after reading has received a poor letter.

## 2. Reading level and tone

We write at CEFR level B1: short sentences (twelve words on average), everyday words, one topic per paragraph. Active, not passive: "The form tutor will call you", not "You will be called by the form tutor". Friendly and direct, without padding. No exclamation marks, no capitals for emphasis.

We address parents formally but warmly. Students are referred to by first name or "your child"; in website news "students", never "kids". Staff are addressed by first name.

| Avoid | Use instead |
| --- | --- |
| utilise, facilitate, in respect of, with regard to | use, arrange, about |
| educational professional, practitioner | teacher |
| trajectory, process | approach, plan, period |
| within the framework of | for, because |
| you are required to, you are requested to | please, could you |
| asap, re., w.r.t., n.b. | write the words in full |

## 3. Structure of a parent letter

1. A subject line that says what it is about, at most eight words. Not "Important information", but "Year 8 parents' evening on 8 October".
2. First paragraph: what, when, for whom. In two or three sentences.
3. What it means for you: what changes, what you need to do, by when. Each action on its own line, with a date.
4. Closing: who to contact with questions, with name and email address or phone number. Sign with name and role, not "the management".

A parent letter is at most one A4 page, preferably shorter. Attachments only when there is no other way; the essentials always go in the letter itself.

## 4. News on the website, the parent app and social media

Website: at most 200 words. Headline of at most eight words; the first paragraph answers who, what, where, when. End with a next step or a way to get in touch.

Parent app: at most 80 words, because parents read this on a phone. One message, one date, one action. No introduction.

Social media (the school's Instagram and LinkedIn): at most 60 words, warm in tone, with the event as the hook. At most three hashtags, always including #ExampleCollege. Photos of students only with consent (see chapter 5).

## 5. Names, photos and privacy

In news we refer to students by first name only, and never with class and surname together. Students appear recognisably in photos only with parental consent, recorded per school year in the parent portal. Without consent we photograph from behind or focus on hands and work. Grades, absence and support are never mentioned in group messages; those always go in a personal conversation.

## 6. Who writes and who checks

Form tutors and heads of year write their own letters. Letters to a whole year group or to all parents go past the communications team first. Messages about incidents, safety or the press always go through the school leadership; never publish those yourself.

## 7. Contact

Communications team, Example College: communications@examplecollege.example, on school days from 8.30 to 16.00.
"""

STUDY_PLANNER = """
# Study planner, Biology Year 9

<p class="kop">Example College · term 2, school year 2026-2027 · unit 4: Ecology · teachers: Ms De Boer (9A, 9B) and Mr Yilmaz (9C)</p>

## What this unit is about

In this unit you learn how plants, animals and their surroundings depend on each other. We start at the school pond and Example Wood behind the school, and end with the question of what people do with ecosystems: the wood, the farm next door, the cycle path the council wants to build.

## Learning objectives

By the end of this unit you can:

1. explain the terms individual, population, community and ecosystem and illustrate each with an example;
2. explain the difference between biotic and abiotic factors and give three examples of each;
3. draw a food chain and a food web and point out producers, consumers and decomposers in them;
4. explain why a food chain rarely has more than four or five links;
5. describe the carbon cycle in outline and name the role of photosynthesis and respiration in it;
6. explain what carrying capacity is and which factors influence the size of a population;
7. explain what biodiversity is and why it matters;
8. give an opinion on a human intervention in an ecosystem, with arguments from this unit.

## Schedule

| Week | Lesson | Topic | Homework for the next lesson |
| --- | --- | --- | --- |
| 1 | 1 and 2 | Section 1: What is ecology? Fieldwork at the school pond | Read booklet section 1, tasks 1 and 2 |
| 2 | 3 and 4 | Section 2: Food chains and food webs | Tasks 3, 4 and 5; open resource on food webs, part 1 (Test your knowledge) |
| 3 | 5 and 6 | Section 3: Cycles | Tasks 6 and 7; learn the glossary up to section 3 |
| 4 | 7 and 8 | Section 4: Populations and balance. Practical: counting water fleas | Tasks 8 and 9, hand in the practical report |
| 5 | 9 and 10 | Section 5: People and ecosystems. Debate on Example Wood | Tasks 10, 11 and 12 |
| 6 | 11 | Revision and practice test | Learn everything for the test |
| 6 | 12 | **Unit 4 test** | |

## The test

- **When:** Thursday 12 November 2026, in your own lesson.
- **What:** the whole booklet (sections 1 to 5), the glossary and tasks 1 to 12. The practical report counts separately.
- **How:** 25 questions, 15 multiple choice and 10 open questions. Open questions earn marks for the reasoning, not only the answer. There is always one question in which you draw or complete a food web.
- **Weighting:** the test counts twice, the practical report once.
- **Aids:** none. The drawings of the food webs are given with the questions.

## How to study this unit

- Do not learn the terms as loose words; learn them with an example from the school pond or Example Wood. The test almost always asks for an example.
- Do the tasks yourself before looking at the answers. The tasks resemble the test questions.
- Draw. You remember food webs and cycles better once you have drawn them yourself.
- Stuck? Ask in the lesson, or come to the support session: Tuesday, period 8, room B12, no sign-up needed.

## Extra practice material

Alongside the booklet we use an open educational resource on food chains and food webs with a Creative Commons licence (for example a chapter from OpenStax Biology 2e, CC BY 4.0). It is free to use at home; it contains short explanations, animations and a self-test.

## Rules and agreements

- Homework goes in your exercise book; photos of someone else's book do not count.
- If you were ill, you catch up on the practical during the support session. Tell your teacher yourself within two school days of returning.
- **AI tools:** you may use an AI helper to ask for explanations and to quiz yourself. You may not use it to produce the answers to the tasks; the tasks exist so that you learn to reason yourself, and the test asks exactly that.
- Questions outside the lesson: email biology@examplecollege.example. You get an answer within two school days. For personal matters, go to your form tutor.
"""

LESSON_BOOKLET = """
# Lesson booklet: Ecology

<p class="kop">Biology Year 9 · unit 4 · Example College · version September 2026</p>

## Section 1. What is ecology?

Ecology is the part of biology that deals with the relationships between organisms and their surroundings. An ecologist asks why a certain plant grows in one place and not in another, why there are many mice one year and few the next, and what happens when a species disappears.

To talk about this we use four terms that fit inside each other like boxes. An **individual** is one organism: one duck on the school pond. A **population** is a group of individuals of the same species living in the same place at the same time and able to breed with each other: all the mallards on and around the school pond. A **community** consists of all the populations in one place together: the ducks, the carp, the reeds, the water lilies, the dragonflies, the bacteria in the mud. An **ecosystem** is the community plus the non-living surroundings: the water, the soil, the light, the temperature.

Those non-living surroundings are the **abiotic factors**. Examples are temperature, light, water, wind, the acidity of the soil and the amount of nutrients in the water. The living surroundings are the **biotic factors**: other organisms that affect an organism, such as food, predators, competitors, pathogens and members of its own species.

An example. At the school pond, reeds grow thickly on the sunny south side and hardly at all on the shady side. Light is the abiotic factor that makes the difference here. Coots nest in the reeds; the reed stems give cover from the heron. For the coot, the reeds are a biotic factor, and so is the heron.

## Section 2. Food chains and food webs

Every organism needs energy. Plants get that energy from sunlight: through **photosynthesis** they make glucose and oxygen from water and carbon dioxide. Because plants make their own food, we call them **producers**. Animals cannot do that; they eat plants or other animals and are therefore called **consumers**. An animal that eats plants is a primary consumer, an animal that eats plant-eaters a secondary consumer, and so on. Fungi and bacteria that break down dead remains are called **decomposers**. They return nutrients to the soil and the water.

A **food chain** shows who eats whom, in a row with arrows. The arrow points in the direction the energy goes. At the school pond: water plant → water flea → stickleback → heron. The water plant is the producer, the water flea a primary consumer, the stickleback a secondary consumer and the heron a tertiary consumer. Each step in the chain is a **link** or trophic level.

In real life hardly anything eats just one thing. The heron also eats frogs, the stickleback also eats mosquito larvae, and the water flea is also eaten by dragonfly larvae. If you draw all the food chains of a community on top of each other, you get a **food web**. A food web shows how species depend on each other. If the water fleas disappear, both the stickleback and the dragonfly larva are in trouble, and after them the heron.

Why are food chains rarely longer than four or five links? Because at every link most of the energy is lost. An animal uses most of the energy from its food to move, keep warm and breathe; only a small part, roughly a tenth, becomes body mass that the next link can eat. After four links so little energy is left that a fifth link can barely exist. That is why there are far more plants than plant-eaters, and far more plant-eaters than predators. We draw this as a **pyramid of biomass**.

## Section 3. Cycles

Energy flows through an ecosystem in one direction: from the sun, through producers and consumers, to heat that leaves the ecosystem. Matter does not. Matter goes round in **cycles**. The best known is the **carbon cycle**.

Carbon is in the air as carbon dioxide (CO₂). Plants take in CO₂ and use photosynthesis to build glucose from it, and from that all the other substances of their bodies. Animals eat plants and take in the carbon that way. Plants and animals breathe: during **respiration** in their cells CO₂ is released again. When an organism dies, decomposers break down the remains and that carbon too returns to the air as CO₂. The cycle is complete.

People have added an extra route to this cycle. Coal, oil and gas are the remains of organisms from millions of years ago; the carbon in them was locked in the ground for a long time. By burning those fuels we put a lot of carbon into the air in a short time that had not been there for ages. As a result the amount of CO₂ in the atmosphere rises, and that strengthens the greenhouse effect.

Nitrogen also goes round in a cycle. Plants need nitrogen for proteins and take it up as nitrate from the soil. Bacteria in the soil make nitrate from dead remains and from nitrogen gas in the air. Manure and fertiliser add extra nitrogen to the soil. That is useful for a farmer, but if the nitrate washes into a ditch or a pond, algae start to bloom there. That is called **eutrophication**, and it is one of the reasons the school pond sometimes turns green in summer.

## Section 4. Populations and balance

How many ducks fit on the school pond? Not an unlimited number. There is a limit to the food, the nesting sites and the space. The maximum number of individuals of a species that an area can support in the long run is the **carrying capacity** of that area for that species. If a population rises above the carrying capacity, there is not enough for everyone: animals starve, have fewer young or move away, and the population shrinks again.

Factors that limit a population include food, water, space, predators, disease and the weather. Some factors act more strongly as the population grows: with many animals in a small place a disease spreads faster and predators find prey more easily. Other factors, such as a harsh winter, hit a large and a small population equally hard.

Populations affect each other. **Competition** arises when two species need the same thing, for example the same food or the same nesting site. **Predation** is the relationship between predator and prey. When there is a lot of prey, the predators have many young; the number of prey then falls, after which the number of predators falls too. So the two populations oscillate around each other. In the week 4 practical you count water fleas in two tanks, with and without a stickleback, and see this for yourself.

An ecosystem in which the populations stay roughly the same in the long run is said to be in **balance**. That balance is not static: it fluctuates, and it can shift if a factor changes permanently.

## Section 5. People and ecosystems

People change ecosystems faster and on a larger scale than any other species. We clear forest for farmland, build roads through habitats, put manure and pesticides into soil and water, and move species to places where they do not belong. Each of those interventions changes the abiotic or the biotic factors of an area, and with them the community.

**Biodiversity** is the variety of species in an area. An area with many species is usually more stable than an area with few: if one species drops out, others can take over its role in the food web. Few species live in a maize field; if disease wipes out the maize, nothing is left. Hundreds of species live in Example Wood; if ash dieback removes the ash trees, the wood survives, though it changes.

Example Wood is a good example of the choices people face. The council wants to build a cycle path through the wood so that students can get to school more safely. Nature lovers fear the path will cut the wood in two and that deer and badgers will no longer cross. The farmers next to the wood want the wood made smaller, because the badgers eat their maize. In week 5 we hold a debate about this. You are given a role and defend it with arguments from this unit: carrying capacity, food web, biodiversity, abiotic and biotic factors.

**Conservation management** is deliberate intervention in an ecosystem to preserve or restore it: mowing at the right moment, holding back water, a wildlife tunnel under a road, reintroducing a species that had disappeared. Doing nothing can also be conservation management. Which choice is right depends on what you want to achieve, and people disagree about that. Ecology does not answer the question of what you should want, but it does answer the question of what happens when you act.

## Tasks

1. Give one example each from the school pond of an individual, a population, a community and an ecosystem.
2. Name three abiotic and three biotic factors that affect the reeds at the school pond.
3. Draw the food chain from section 2 and label each link as producer or consumer, and of which order.
4. Draw a food web of the school pond with at least six species from this booklet.
5. Use the concept of energy to explain why there are more water fleas than sticklebacks in the school pond.
6. Describe in four steps how a carbon atom gets from the air, via a water plant and a duck, back into the air.
7. Explain why the school pond sometimes turns green in summer and what that has to do with the farm next to the school.
8. What is the carrying capacity of an area? Name two factors that determine the carrying capacity of the school pond for ducks.
9. Draw a graph of the number of water fleas and the number of sticklebacks over time, and explain why the lines run as they do.
10. Explain why a wood with many species copes better with a tree disease than a wood with one species.
11. Choose a party in the Example Wood debate and give two arguments using terms from this unit.
12. Think of a conservation measure for the school pond and explain what effect you expect on the food web.

## Glossary

| Term | Meaning |
| --- | --- |
| Abiotic factor | Influence from the non-living surroundings, such as light, temperature, water |
| Biotic factor | Influence from other organisms, such as food, predators, competitors |
| Biodiversity | The variety of species in an area |
| Consumer | Organism that eats other organisms |
| Carrying capacity | The maximum number of individuals of a species an area can support in the long run |
| Ecosystem | Community plus the non-living surroundings |
| Eutrophication | Excess nutrients in water, causing algae to bloom |
| Photosynthesis | Process by which plants use light to make glucose and oxygen from water and CO₂ |
| Community | All the populations in one place together |
| Population | Group of individuals of the same species in the same place and time |
| Predation | Relationship between predator and prey |
| Producer | Organism that makes its own food, usually a plant |
| Decomposer | Organism that breaks down dead remains, such as fungi and bacteria |
| Food chain | Row of organisms that eat each other, with arrows in the direction of the energy |
| Food web | All the food chains of a community on top of each other |
"""

EXAM_TIMETABLE = """day,date,subject,time,duration_minutes,topics
Monday,2026-10-12,English,09:00,60,Reading comprehension chapters 3 and 4; spelling of verb forms
Monday,2026-10-12,Mathematics,10:45,45,Chapter 2 (equations) and 3 (percentages)
Tuesday,2026-10-13,French,09:00,45,Units 3 and 4: vocabulary, present tense, être and avoir
Wednesday,2026-10-14,History,09:00,45,Chapter 5: the Republic in the Golden Age (sections 1 to 4)
Thursday,2026-10-15,Biology,10:45,45,Unit 2: cells and organs (basic material 1 to 5)
Friday,2026-10-16,German,09:00,45,Chapter 2: vocabulary, sein and haben, numbers to 100
"""

MEETING_SCRIPT = """English department meeting, Tuesday 22 September. Present are Karen, Bram and Fatima. Karen is chairing.

Karen: Good afternoon everyone. We have three items: the October test week, the new reading scheme for Year 7, and who does what at the open day. Let us start with the test week. Bram, you drafted the schedule.

Bram: I did. The Year 8 reading comprehension test is now on Monday 12 October at nine, sixty minutes. I suggest we keep that. What I do want to propose is that we merge the spelling test with the reading test, so one sixty-minute test instead of two separate ones.

Fatima: I agree. Two separate tests in one week is too much for Year 8. But then the study planner has to be updated, because it still lists two tests.

Karen: Good. Then we decide: one combined reading and spelling test on Monday 12 October, sixty minutes. Fatima, will you update the study planner?

Fatima: I will. I will have it ready by Friday.

Karen: Fine, Friday 25 September then. Item two, the reading scheme. We received two trial packages. Bram has looked at them.

Bram: Yes, and honestly I find it hard to choose. One package has much better texts for weak readers, the other has a digital environment that works far better. I would actually like to trial both for a period in one class.

Fatima: Can we afford that? And do we have the time, with the test week coming up?

Karen: I think we should not decide this today. I propose we carry it over to the next meeting, and that Bram asks the publishers in the meantime what a trial period costs. Agreed?

Bram: Agreed. I will email them this week.

Karen: Then we carry the choice of reading scheme over to the meeting of 6 October. By the way, has anyone heard what is going on with the coffee machine in the staff room? It has not worked for a week.

Fatima: I reported it to the caretaker, who would get someone to look at it.

Karen: Good, then we need not do anything with that. Item three, the open day on Saturday 7 November. We need two people at the English stand, and someone to run the taster lesson.

Bram: I will do the taster lesson, I did it last year too.

Fatima: I can be at the stand in the morning, until half past twelve.

Karen: Then I will do the afternoon at the stand. That settles it, and Bram, you send me the outline of the taster lesson before 1 November, so I can put it in the programme booklet.

Bram: Yes, will do.

Karen: Then we have covered everything. To sum up: one combined test on 12 October, Fatima updates the study planner by Friday, the reading scheme goes to 6 October and Bram asks for the trial costs, and for the open day Bram runs the taster lesson and Fatima and I are at the stand. Thanks everyone, see you next week.
"""


def to_pdf(md: str, dest: Path) -> None:
    html = (f'<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><style>{CSS}</style></head>'
            f'<body>{markdown.markdown(md, extensions=["tables"])}</body></html>')
    tmp = dest.with_suffix(".html")
    tmp.write_text(html, encoding="utf-8")
    subprocess.run(["google-chrome", "--headless=new", "--disable-gpu", "--no-pdf-header-footer",
                    f"--print-to-pdf={dest}", tmp.as_uri()], check=True, capture_output=True)
    tmp.unlink()
    print(f"{dest.relative_to(ROOT)}: {dest.stat().st_size // 1024} kB")


to_pdf(SCHOOL_GUIDE, ROOT / "02-agent-knowledge-base" / "school-guide-example-college.pdf")
to_pdf(STYLE_GUIDE, ROOT / "03-school-communication" / "style-guide-example-college.pdf")
to_pdf(LESSON_BOOKLET, ROOT / "06-inclusive-materials" / "lesson-booklet-ecology.pdf")
shutil.copy(ROOT / "06-inclusive-materials" / "lesson-booklet-ecology.pdf", ROOT / "08-chatflow-study-coach" / "lesson-booklet-ecology.pdf")
to_pdf(STUDY_PLANNER, ROOT / "08-chatflow-study-coach" / "study-planner-biology-y9-ecology.pdf")
(ROOT / "04-agent-console" / "exam-timetable-example.csv").write_text(EXAM_TIMETABLE, encoding="utf-8")
(ROOT / "05-transcription-tool" / "department-meeting-script.txt").write_text(MEETING_SCRIPT, encoding="utf-8")
print("exam-timetable-example.csv and department-meeting-script.txt written")