{
 "site": "https://de-code-ai.netlify.app",
 "title": "de-code",
 "summary": "Democratizing coding with AI: workshops, course material and small apps on data analysis, app building and agentic coding with AI.",
 "generated_from": "web/ (published HTML), by src/site-index.py",
 "mcp": "https://de-code-ai.netlify.app/mcp",
 "sections": [
  {
   "id": "home",
   "title": "Home",
   "description": "de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise.",
   "url": "https://de-code-ai.netlify.app/"
  },
  {
   "id": "coding",
   "title": "Coding / skill school",
   "description": "Five-session workshop (5–9 October 2026): data analysis, data generation, app building, agentic coding, and skills and MCP with AI, with slides and Colab notebooks.",
   "url": "https://de-code-ai.netlify.app/coding/skill-school/"
  },
  {
   "id": "data-analysis",
   "title": "Data analysis",
   "description": "de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise.",
   "url": "https://de-code-ai.netlify.app/data-analysis.html"
  },
  {
   "id": "app-building",
   "title": "App building",
   "description": "de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise.",
   "url": "https://de-code-ai.netlify.app/app-building.html"
  },
  {
   "id": "agentic-ai",
   "title": "Agentic AI",
   "description": "",
   "url": "https://de-code-ai.netlify.app/agentic-ai/mcps/de-code-mcp.zip"
  },
  {
   "id": "education",
   "title": "Education",
   "description": "Educational services for institutions and public organizations, provided by resn.dev under the Democratizing coding with AI label (de-code-ai). Sessions are held on site in physical settings, or remotely over video …",
   "url": "https://de-code-ai.netlify.app/education.html"
  },
  {
   "id": "workshop",
   "title": "Workshop",
   "description": "Learn how to use AI and natural language interfaces to analyze data, generate datasets, and build useful applications without traditional coding barriers.",
   "url": "https://de-code-ai.netlify.app/workshop.html"
  },
  {
   "id": "resn-dev",
   "title": "resn.dev",
   "description": "resn.dev is the parent company behind de-code-ai: a growing set of AI-assisted coding practices that make computational work more open, practical, and approachable.",
   "url": "https://de-code-ai.netlify.app/resn-dev/"
  }
 ],
 "pages": [
  {
   "url": "https://de-code-ai.netlify.app/app-building/pwas/de-code-regex/",
   "path": "app-building/pwas/de-code-regex/index.html",
   "title": "de-code regex — Live regex trainer",
   "description": "Interactive regular expression trainer, tester and challenge runner. Install it on your phone or computer as an app (PWA); it also works offline.",
   "section": "app-building",
   "type": "app",
   "stack": "pwa",
   "headings": [
    "Interactive Regex Challenges",
    "Regex Syntax Reference"
   ],
   "words": 192,
   "updated": "2026-10-08",
   "text": "/ / g i m s 0 matches Quick Insert: \\d \\w \\s + *? ^ $ () [] {} |. Invalid Regular Expression syntax Sample Test Text Reset Match & Group Breakdown Real-time analysis No matches found for current pattern. Interactive Regex Challenges Practice solving real-world data extraction and validation problems. Progress: 0 / 0 Solved Easy 1. Match Email Addresses Write a pattern that captures standard email addresses from text. Your Regex Pattern / /g Test Sample Enter a pattern matching all expected targets. Regex Syntax Reference Quick guide to regular expression character classes, quantifiers, and anchors. Character Classes. Any character except newline \\d Digit [0-9] \\w Word character [a-zA-Z0-9_] \\s Whitespace (space, tab, newline) [abc] Any single character in set [^abc] Any single character NOT in set Quantifiers * 0 or more occurrences + 1 or more occurrences? 0 or 1 occurrence (optional) {3} Exactly 3 times {2,5} Between 2 and 5 times Anchors & Logic ^ Start of string/line $ End of string/line \\b Word boundary position a|b Matches either 'a' or 'b' Groups & Lookarounds (abc) Capturing group (?:abc) Non-capturing group (?=abc) Positive lookahead (?!abc) Negative lookahead"
  },
  {
   "url": "https://de-code-ai.netlify.app/app-building.html",
   "path": "app-building.html",
   "title": "Democratizing app building with AI",
   "description": "de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise.",
   "section": "app-building",
   "type": "page",
   "stack": "html",
   "headings": [
    "Democratizing app building with AI",
    "What we de-code",
    "Start with a question"
   ],
   "words": 125,
   "updated": "2026-07-06",
   "text": "Democratizing app building with AI de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise. Explore services What we de-code de-code data analysis Turn questions into workflows for cleaning, analyzing, visualizing, and reporting data using AI-assisted methods. de-code data generation Generate realistic example datasets, simulations, test cases, and teaching materials through natural language prompts. de-code app building Build lightweight dashboards, prototypes, forms, and internal tools using AI-supported low-code development. Coding should not be limited to specialists. de-code makes computational work more accessible, explainable, and useful for everyone. Start with a question Bring your data, idea, or workflow problem. We help translate it into practical AI-assisted tools and methods. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/",
   "path": "coding/skill-school/index.html",
   "title": "Democratizing Coding with AI (5–9 October)",
   "description": "Five-session workshop (5–9 October 2026): data analysis, data generation, app building, agentic coding, and skills and MCP with AI, with slides and Colab notebooks.",
   "section": "coding",
   "type": "page",
   "stack": "quarto",
   "headings": [
    "Abstract",
    "Sessions",
    "About the instructor"
   ],
   "words": 344,
   "updated": "2026-10-09",
   "text": "Instructor: Nils Holmberg, Lund University, Department of Communication Dates: 5–9 October (week 41), 09:00–12:00 (5–7 Oct.) and 13:00–16:00 (8–9 Oct.) TimeEdit schedule Abstract The first days focus on data. Participants analyse a survey dataset by asking questions in natural language, then use AI to generate realistic synthetic data and simulated survey respondents. Along the way they learn to write clear prompts, run the resulting code in Colab, and check every number the AI produces. The last days focus on building. Participants create small apps and dashboards and work with AI agents and their tools. They write specifications as code: plain-text files that give the AI context, hold instructions that prompts can refer to, and serve agents as blueprints for building and testing an app. Sessions Each session comes in three versions of the same content: a web page to read, slides to follow in class, and a notebook that opens in Google Colab so you can run the code yourself. With a Google account you can also ask Gemini for help in the browser, and in the later sessions we try the agentic coding app Google Antigravity. Day Session Materials Mon 5 Oct 1 · de-code data analysis slides · notebook Tue 6 Oct 2 · de-code data generation slides · notebook Wed 7 Oct 3 · de-code app building slides · notebook Thu 8 Oct 4 · de-code agentic coding slides · notebook Fri 9 Oct 5 · de-code skills and MCP slides · notebook About the instructor Nils Holmberg is a senior lecturer at the Department of Communication, Lund University. He holds a PhD in Media and Communication Science from Lund University (2016) and has a background in experimental research on digital advertising, including the use of eye-tracking to study visual attention and comprehension in online environments. His current research focuses on computational content analysis in the social sciences, applying methods such as natural language processing and computer vision to analyze and visualize patterns in digital communication, with a particular emphasis on sustainability communication and the opportunities and limitations of AI-assisted analysis."
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/01-data-analysis-slides.html",
   "path": "coding/skill-school/sessions/01-data-analysis-slides.html",
   "title": "Session 1 · de-code data analysis",
   "description": "Parts: Loading data; Describing each variable; Relating the outcome to the predictors.",
   "section": "coding",
   "type": "slides",
   "stack": "quarto",
   "headings": [
    "Topics",
    "1 Loading data",
    "1.1 Load from GitHub",
    "1.2 Alternative: upload the file to Colab",
    "1.3 Colab: install pyreadstat",
    "1.4 Same data, four formats",
    "1.5 Compare the formats",
    "1.6 Give an LLM context",
    "2 Describing each variable",
    "2.1 Descriptive statistics",
    "2.2 Frequencies",
    "2.3 Distributions",
    "2.4 Categorical variable",
    "3 Relating the outcome to the predictors",
    "3.1 Group comparison table",
    "3.2 Correlation table",
    "3.3 Visualizations",
    "3.4 Significance tests",
    "3.5 Check the AI"
   ],
   "words": 1981,
   "updated": "2026-10-10",
   "text": "Topics 1 Loading data 1.1 Load from GitHub 1.2 Alternative: upload the file to Colab 1.3 Colab: install pyreadstat 1.4 Same data, four formats 1.5 Compare the formats 1.6 Give an LLM context 2 Describing each variable 2.1 Descriptive statistics 2.2 Frequencies 2.3 Distributions 2.4 Categorical variable 3 Relating the outcome to the predictors 3.1 Group comparison table 3.2 Correlation table 3.3 Visualizations 3.4 Significance tests 3.5 Check the AI Slides Notebook 1 Loading data 1.1 Load from GitHub The sample dataset is a small simulated survey: 100 respondents, one group variable and six questionnaire items on a 1–5 scale, combined into three indices. The file lives in the course repository on GitHub. Its raw URL returns the plain file, so pandas can read it directly from the web — nothing to download first. The file is tab-separated (.tsv), so we tell read_csv that the separator is a tab (\\t). import pandas as pd url = \"https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv\" df = pd.read_csv(url, sep = \" \\t \") print (df.shape) # (rows, columns) df.head() (100, 10) IV_CAT_GROUP IV1_ITEM1 IV1_ITEM2 IV2_ITEM1 IV2_ITEM2 DV_ITEM1 DV_ITEM2 IV_INDEX1 IV_INDEX2 DV_INDEX 0 category2 4 3 1 1 1 1 3.5 1.0 1.0 1 category1 4 5 3 3 2 3 4.5 3.0 2.5 2 category2 1 2 1 1 1 1 1.5 1.0 1.0 3 category2 3 2 5 5 2 2 2.5 5.0 2.0 4 category1 2 2 1 2 1 1 2.0 1.5 1.0 1.2 Alternative: upload the file to Colab If you have the file on your own computer, you can upload it to the Colab session instead. This cell is not run on the course website; in Colab, run it and pick the file in the dialog. Uploaded files end up in /content/, the working folder of the Colab session. from google.colab import files files.upload() # choose komp014-simulated-data-n100.tsv df = pd.read_csv(\"/content/komp014-simulated-data-n100.tsv\", sep = \" \\t \") df.head() 1.3 Colab: install pyreadstat SPSS files (.sav) need the pyreadstat package, which Colab does not include. Run this cell once per Colab session before the next step. % pip install pyreadstat 1.4 Same data, four formats The same table can be stored in different file formats. Here we save df as CSV, TSV, Excel and SPSS, and attach a short label to each variable in the SPSS file. from pathlib import Path import pyreadstat labels = { \"IV_CAT_GROUP\": \"Group (category1 / category2)\", \"IV1_ITEM1\": \"IV1 item 1 (1-5)\", \"IV1_ITEM2\": \"IV1 item 2 (1-5)\", \"IV2_ITEM1\": \"IV2 item 1 (1-5)\", \"IV2_ITEM2\": \"IV2 item 2 (1-5)\", \"DV_ITEM1\": \"DV item 1 (1-5)\", \"DV_ITEM2\": \"DV item 2 (1-5)\", \"IV_INDEX1\": \"IV1 index, mean of IV1 items\", \"IV_INDEX2\": \"IV2 index, mean of IV2 items\", \"DV_INDEX\": \"DV index, mean of DV items\", } out = Path(\"data\") out.mkdir(exist_ok = True) df.to_csv(out / \"komp014.csv\", index = False) df.to_csv(out / \"komp014.tsv\", sep = \" \\t \", index = False) df.to_excel(out / \"komp014.xlsx\", index = False) pyreadstat.write_sav(df, out / \"komp014.sav\", column_labels = [labels[c] for c in df.columns]) sorted (p.name for p in out.iterdir()) ['komp014.csv', 'komp014.sav', 'komp014.tsv', 'komp014.xlsx', 'run1.txt'] 1.5 Compare the formats Now we read each file back and compare it with the original: how big is the file, are the values the same, and did the column types (whole numbers, decimals, text) survive? readers = { \"csv\": lambda p: pd.read_csv(p), \"tsv\": lambda p: pd.read_csv(p, sep = \" \\t \"), \"xlsx\": lambda p: pd.read_excel(p), \"sav\": lambda p: pyreadstat.read_sav(p)[0], } rows = [] for fmt, read in readers.items(): path = out / f\"komp014. { fmt } \" back = read(path) rows.append({ \"format\": fmt, \"bytes\": path.stat().st_size, # cast the original to the read-back types, then compare cell by cell \"same values\": back.equals(df.astype(back.dtypes.to_dict())), \"same types\": back.dtypes.astype(str).equals(df.dtypes.astype(str)), \"text file\": fmt in (\"csv\", \"tsv\"), }) pd.DataFrame(rows) format bytes same values same types text file 0 csv 3500 True True True 1 tsv 3500 True True True 2 xlsx 8663 True True False 3 sav 10037 True False False CSV / TSV are plain text: open them in any editor, small, universal. Column types are guessed again on every read, and there is no place for labels. Excel is a zipped binary format: handy for people, larger on disk, keeps types. SPSS.sav is binary and stores metadata with the data. Whole numbers come back as decimals (SPSS has one numeric type), but the variable labels travel with the file: _, meta = pyreadstat.read_sav(out / \"komp014.sav\") dict (zip (meta.column_names, meta.column_labels)) {'IV_CAT_GROUP': 'Group (category1 / category2)', 'IV1_ITEM1': 'IV1 item 1 (1-5)', 'IV1_ITEM2': 'IV1 item 2 (1-5)', 'IV2_ITEM1': 'IV2 item 1 (1-5)', 'IV2_ITEM2': 'IV2 item 2 (1-5)', 'DV_ITEM1': 'DV item 1 (1-5)', 'DV_ITEM2': 'DV item 2 (1-5)', 'IV_INDEX1': 'IV1 index, mean of IV1 items', 'IV_INDEX2': 'IV2 index, mean of IV2 items', 'DV_INDEX': 'DV index, mean of DV items'} 1.6 Give an LLM context A chat assistant cannot see your data. Paste a short description like the one below, followed by your question, and it can write code that fits your df. This cell only stores the text; it is not run on the course website. prompt = \"\"\" I am analysing a survey dataset in Python with pandas. It is already loaded as `df`. - 100 rows (respondents), 10 columns, no missing values - IV_CAT_GROUP: text, two groups, \"category1\" and \"category2\" (50 each) - IV1_ITEM1, IV1_ITEM2, IV2_ITEM1, IV2_ITEM2, DV_ITEM1, DV_ITEM2: whole numbers, questionnaire items on a 1-5 scale - IV_INDEX1, IV_INDEX2, DV_INDEX: decimals 1-5, each the mean of its two items (IV_INDEX1 = mean of IV1_ITEM1/2, and so on) - DV_INDEX is the outcome (dependent variable); IV_CAT_GROUP, IV_INDEX1 and IV_INDEX2 are the predictors (independent variables) Continue from here. Write short, commented Python code and explain the results in plain language. \"\"\" print (prompt) 2 Describing each variable 2.1 Descriptive statistics describe() summarises every numeric column: how many values (count), the average (mean), the spread (std), the smallest and largest values, and the quartiles (25%, 50% = median, 75%). We add skewness (is the distribution lopsided?) and kurtosis (are the tails heavy?). Values near 0 mean roughly symmetric and normal-shaped. numeric = df.select_dtypes(\"number\") stats = numeric.describe().T stats[\"skew\"] = numeric.skew() stats[\"kurtosis\"] = numeric.kurt() stats. round (2) count mean std min 25% 50% 75% max skew kurtosis IV1_ITEM1 100.0 3.09 1.22 1.0 2.00 3.00 4.00 5.0 -0.01 -0.86 IV1_ITEM2 100.0 3.05 1.24 1.0 2.00 3.00 4.00 5.0 -0.06 -0.94 IV2_ITEM1 100.0 2.84 1.16 1.0 2.00 3.00 3.00 5.0 0.32 -0.53 IV2_ITEM2 100.0 2.78 1.31 1.0 2.00 3.00 4.00 5.0 0.17 -1.06 DV_ITEM1 100.0 2.57 1.20 1.0 2.00 2.00 3.25 5.0 0.42 -0.79 DV_ITEM2 100.0 2.56 1.17 1.0 2.00 3.00 3.00 5.0 0.34 -0.58 IV_INDEX1 100.0 3.07 1.11 1.0 2.38 3.00 4.00 5.0 -0.03 -0.89 IV_INDEX2 100.0 2.81 1.15 1.0 2.00 2.75 3.50 5.0 0.29 -0.79 DV_INDEX 100.0 2.56 1.09 1.0 1.88 2.50 3.50 5.0 0.46 -0.52 2.2 Frequencies For the group variable and the 1–5 items, it is more useful to count how often each value occurs. The first table counts the two groups; the second shows, for each item, the share of respondents (in %) who chose each answer from 1 to 5. df[\"IV_CAT_GROUP\"].value_counts() IV_CAT_GROUP category2 50 category1 50 Name: count, dtype: int64 items = [\"IV1_ITEM1\", \"IV1_ITEM2\", \"IV2_ITEM1\", \"IV2_ITEM2\", \"DV_ITEM1\", \"DV_ITEM2\"] freq = df[items]. apply (lambda s: s.value_counts(normalize = True)).fillna(0) * 100 freq.index.name = \"answer\" freq. round (0) IV1_ITEM1 IV1_ITEM2 IV2_ITEM1 IV2_ITEM2 DV_ITEM1 DV_ITEM2 answer 1 11.0 13.0 12.0 21.0 20.0 22.0 2 21.0 21.0 28.0 23.0 35.0 26.0 3 32.0 28.0 36.0 25.0 20.0 33.0 4 20.0 24.0 12.0 19.0 18.0 12.0 5 16.0 14.0 12.0 12.0 7.0 7.0 2.3 Distributions A histogram shows how the values of one variable are spread out: each bar counts the respondents in a range of values. The smooth line is a density curve, an estimate of the shape of the distribution. Items have only five possible values, so their bars are discrete; the indices take more values and look smoother. import seaborn as sns sns.set_theme(style = \"whitegrid\") fig, axes = plt.subplots(3, 3, figsize = (9, 7.5)) for ax, col in zip (axes.flat, numeric.columns): sns.histplot(df[col], bins = 9, kde = True, color = \"#2f9e44\", ax = ax) ax.set_title(col) ax.set_xlabel(\"\") fig.tight_layout() plt.show() 2.4 Categorical variable The group variable is text, so it gets a bar chart of counts instead of a histogram. Both groups have 50 respondents: the design is balanced. fig, ax = plt.subplots(figsize = (4.5, 3.2)) sns.countplot(data = df, x = \"IV_CAT_GROUP\", color = \"#2f9e44\", ax = ax) ax.set_xlabel(\"\") plt.show() 3 Relating the outcome to the predictors 3.1 Group comparison table Now we look at two variables at a time: the outcome DV_INDEX against each predictor. We use the indices rather than the single items, since each index summarises its two items. First, the outcome split by group: does the average differ between the groups? df.groupby(\"IV_CAT_GROUP\")[\"DV_INDEX\"].agg([\"count\", \"mean\", \"std\", \"median\"]). round (2) count mean std median IV_CAT_GROUP category1 50 2.87 1.04 2.75 category2 50 2.26 1.06 2.00 3.2 Correlation table For two numeric variables, the correlation (Pearson’s r) measures how closely they move together, from −1 (opposite) through 0 (unrelated) to +1 (in step). df[[\"DV_INDEX\", \"IV_INDEX1\", \"IV_INDEX2\"]].corr(). round (2) DV_INDEX IV_INDEX1 IV_INDEX2 DV_INDEX 1.00 0.41 0.41 IV_INDEX1 0.41 1.00 0.32 IV_INDEX2 0.41 0.32 1.00 3.3 Visualizations Left: the outcome per group as a box plot (median, middle half and range) with each respondent as a dot. Middle and right: the outcome against each index, one dot per respondent, with a fitted straight line and its uncertainty band. import numpy as np np.random.seed(1) # same random jitter and uncertainty band on every run fig, axes = plt.subplots(1, 3, figsize = (10, 3.6)) sns.boxplot(data = df, x = \"IV_CAT_GROUP\", y = \"DV_INDEX\", color = \"#d3f9d8\", ax = axes[0]) sns.stripplot(data = df, x = \"IV_CAT_GROUP\", y = \"DV_INDEX\", color = \"#2f9e44\", alpha = 0.6, jitter = 0.2, ax = axes[0]) axes[0].set_xlabel(\"\") for ax, iv in zip (axes[1:], [\"IV_INDEX1\", \"IV_INDEX2\"]): sns.regplot(data = df, x = iv, y = \"DV_INDEX\", color = \"#2f9e44\", scatter_kws = { \"alpha\": 0.6 }, ax = ax, seed = 1) fig.tight_layout() plt.show() 3.4 Significance tests A significance test asks: could a difference or relationship this large plausibly appear by chance if there were none in the population? A small p -value (by convention below 0.05) says chance alone is an unlikely explanation. The effect size says how large the effect is, which p does not. Group → DV: Welch’s t-test compares the two group means; Cohen’s d is the difference in standard-deviation units (around 0.2 small, 0.5 medium, 0.8 large). Index → DV: Pearson’s correlation test; r itself is the effect size (around 0.1 small, 0.3 medium, 0.5 large). from scipy import stats as st g1, g2 = (df.loc[df[\"IV_CAT_GROUP\"] == g, \"DV_INDEX\"] for g in [\"category1\", \"category2\"]) t = st.ttest_ind(g1, g2, equal_var = False) pooled_sd = ((g1.var() + g2.var()) / 2) ** 0.5 results = [{ \"predictor\": \"IV_CAT_GROUP\", \"test\": \"Welch t-test\", \"statistic\": t.statistic, \"p\": t.pvalue, \"effect size\": (g1.mean() - g2.mean()) / pooled_sd, \"measure\": \"Cohen's d\", }] for iv in [\"IV_INDEX1\", \"IV_INDEX2\"]: r = st.pearsonr(df[iv], df[\"DV_INDEX\"]) results.append({ \"predictor\": iv, \"test\": \"Pearson correlation\", \"statistic\": r.statistic, \"p\": r.pvalue, \"effect size\": r.statistic, \"measure\": \"r\", }) results = pd.DataFrame(results). round (3) results[\"p\"] = results[\"p\"]. map (lambda p: \"<.001\" if p < 0.001 else f\" { p:.3f} \") results predictor test statistic p effect size measure 0 IV_CAT_GROUP Welch t-test 2.905 0.005 0.581 Cohen's d 1 IV_INDEX1 Pearson correlation 0.412 <.001 0.412 r 2 IV_INDEX2 Pearson correlation 0.411 <.001 0.411 r The data are simulated, so these effects were built in on purpose; with real survey data, read them as associations, not proof of cause and effect. 3.5 Check the AI AI assistants write convincing code, and sometimes convincing mistakes. Before you trust an AI-produced result, check one number yourself: Paste the context prompt from section 1.6 into a chat assistant. Ask it for the mean of DV_INDEX in each group, or the correlation between DV_INDEX and IV_INDEX1. Run its code and compare the answer with the tables above. Do they match? If not, which one is right — and why?"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/01-data-analysis.html",
   "path": "coding/skill-school/sessions/01-data-analysis.html",
   "title": "Session 1 · de-code data analysis",
   "description": "Parts: Loading data; Describing each variable; Relating the outcome to the predictors.",
   "section": "coding",
   "type": "page",
   "stack": "quarto",
   "headings": [
    "Topics",
    "1 Loading data",
    "1.1 Load from GitHub",
    "1.2 Alternative: upload the file to Colab",
    "1.3 Colab: install pyreadstat",
    "1.4 Same data, four formats",
    "1.5 Compare the formats",
    "1.6 Give an LLM context",
    "2 Describing each variable",
    "2.1 Descriptive statistics",
    "2.2 Frequencies",
    "2.3 Distributions",
    "2.4 Categorical variable",
    "3 Relating the outcome to the predictors",
    "3.1 Group comparison table",
    "3.2 Correlation table",
    "3.3 Visualizations",
    "3.4 Significance tests",
    "3.5 Check the AI"
   ],
   "words": 1981,
   "updated": "2026-10-10",
   "text": "Topics 1 Loading data 1.1 Load from GitHub 1.2 Alternative: upload the file to Colab 1.3 Colab: install pyreadstat 1.4 Same data, four formats 1.5 Compare the formats 1.6 Give an LLM context 2 Describing each variable 2.1 Descriptive statistics 2.2 Frequencies 2.3 Distributions 2.4 Categorical variable 3 Relating the outcome to the predictors 3.1 Group comparison table 3.2 Correlation table 3.3 Visualizations 3.4 Significance tests 3.5 Check the AI Slides Notebook 1 Loading data 1.1 Load from GitHub The sample dataset is a small simulated survey: 100 respondents, one group variable and six questionnaire items on a 1–5 scale, combined into three indices. The file lives in the course repository on GitHub. Its raw URL returns the plain file, so pandas can read it directly from the web — nothing to download first. The file is tab-separated (.tsv), so we tell read_csv that the separator is a tab (\\t). import pandas as pd url = \"https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv\" df = pd.read_csv(url, sep = \" \\t \") print (df.shape) # (rows, columns) df.head() (100, 10) IV_CAT_GROUP IV1_ITEM1 IV1_ITEM2 IV2_ITEM1 IV2_ITEM2 DV_ITEM1 DV_ITEM2 IV_INDEX1 IV_INDEX2 DV_INDEX 0 category2 4 3 1 1 1 1 3.5 1.0 1.0 1 category1 4 5 3 3 2 3 4.5 3.0 2.5 2 category2 1 2 1 1 1 1 1.5 1.0 1.0 3 category2 3 2 5 5 2 2 2.5 5.0 2.0 4 category1 2 2 1 2 1 1 2.0 1.5 1.0 1.2 Alternative: upload the file to Colab If you have the file on your own computer, you can upload it to the Colab session instead. This cell is not run on the course website; in Colab, run it and pick the file in the dialog. Uploaded files end up in /content/, the working folder of the Colab session. from google.colab import files files.upload() # choose komp014-simulated-data-n100.tsv df = pd.read_csv(\"/content/komp014-simulated-data-n100.tsv\", sep = \" \\t \") df.head() 1.3 Colab: install pyreadstat SPSS files (.sav) need the pyreadstat package, which Colab does not include. Run this cell once per Colab session before the next step. % pip install pyreadstat 1.4 Same data, four formats The same table can be stored in different file formats. Here we save df as CSV, TSV, Excel and SPSS, and attach a short label to each variable in the SPSS file. from pathlib import Path import pyreadstat labels = { \"IV_CAT_GROUP\": \"Group (category1 / category2)\", \"IV1_ITEM1\": \"IV1 item 1 (1-5)\", \"IV1_ITEM2\": \"IV1 item 2 (1-5)\", \"IV2_ITEM1\": \"IV2 item 1 (1-5)\", \"IV2_ITEM2\": \"IV2 item 2 (1-5)\", \"DV_ITEM1\": \"DV item 1 (1-5)\", \"DV_ITEM2\": \"DV item 2 (1-5)\", \"IV_INDEX1\": \"IV1 index, mean of IV1 items\", \"IV_INDEX2\": \"IV2 index, mean of IV2 items\", \"DV_INDEX\": \"DV index, mean of DV items\", } out = Path(\"data\") out.mkdir(exist_ok = True) df.to_csv(out / \"komp014.csv\", index = False) df.to_csv(out / \"komp014.tsv\", sep = \" \\t \", index = False) df.to_excel(out / \"komp014.xlsx\", index = False) pyreadstat.write_sav(df, out / \"komp014.sav\", column_labels = [labels[c] for c in df.columns]) sorted (p.name for p in out.iterdir()) ['komp014.csv', 'komp014.sav', 'komp014.tsv', 'komp014.xlsx', 'run1.txt'] 1.5 Compare the formats Now we read each file back and compare it with the original: how big is the file, are the values the same, and did the column types (whole numbers, decimals, text) survive? readers = { \"csv\": lambda p: pd.read_csv(p), \"tsv\": lambda p: pd.read_csv(p, sep = \" \\t \"), \"xlsx\": lambda p: pd.read_excel(p), \"sav\": lambda p: pyreadstat.read_sav(p)[0], } rows = [] for fmt, read in readers.items(): path = out / f\"komp014. { fmt } \" back = read(path) rows.append({ \"format\": fmt, \"bytes\": path.stat().st_size, # cast the original to the read-back types, then compare cell by cell \"same values\": back.equals(df.astype(back.dtypes.to_dict())), \"same types\": back.dtypes.astype(str).equals(df.dtypes.astype(str)), \"text file\": fmt in (\"csv\", \"tsv\"), }) pd.DataFrame(rows) format bytes same values same types text file 0 csv 3500 True True True 1 tsv 3500 True True True 2 xlsx 8663 True True False 3 sav 10037 True False False CSV / TSV are plain text: open them in any editor, small, universal. Column types are guessed again on every read, and there is no place for labels. Excel is a zipped binary format: handy for people, larger on disk, keeps types. SPSS.sav is binary and stores metadata with the data. Whole numbers come back as decimals (SPSS has one numeric type), but the variable labels travel with the file: _, meta = pyreadstat.read_sav(out / \"komp014.sav\") dict (zip (meta.column_names, meta.column_labels)) {'IV_CAT_GROUP': 'Group (category1 / category2)', 'IV1_ITEM1': 'IV1 item 1 (1-5)', 'IV1_ITEM2': 'IV1 item 2 (1-5)', 'IV2_ITEM1': 'IV2 item 1 (1-5)', 'IV2_ITEM2': 'IV2 item 2 (1-5)', 'DV_ITEM1': 'DV item 1 (1-5)', 'DV_ITEM2': 'DV item 2 (1-5)', 'IV_INDEX1': 'IV1 index, mean of IV1 items', 'IV_INDEX2': 'IV2 index, mean of IV2 items', 'DV_INDEX': 'DV index, mean of DV items'} 1.6 Give an LLM context A chat assistant cannot see your data. Paste a short description like the one below, followed by your question, and it can write code that fits your df. This cell only stores the text; it is not run on the course website. prompt = \"\"\" I am analysing a survey dataset in Python with pandas. It is already loaded as `df`. - 100 rows (respondents), 10 columns, no missing values - IV_CAT_GROUP: text, two groups, \"category1\" and \"category2\" (50 each) - IV1_ITEM1, IV1_ITEM2, IV2_ITEM1, IV2_ITEM2, DV_ITEM1, DV_ITEM2: whole numbers, questionnaire items on a 1-5 scale - IV_INDEX1, IV_INDEX2, DV_INDEX: decimals 1-5, each the mean of its two items (IV_INDEX1 = mean of IV1_ITEM1/2, and so on) - DV_INDEX is the outcome (dependent variable); IV_CAT_GROUP, IV_INDEX1 and IV_INDEX2 are the predictors (independent variables) Continue from here. Write short, commented Python code and explain the results in plain language. \"\"\" print (prompt) 2 Describing each variable 2.1 Descriptive statistics describe() summarises every numeric column: how many values (count), the average (mean), the spread (std), the smallest and largest values, and the quartiles (25%, 50% = median, 75%). We add skewness (is the distribution lopsided?) and kurtosis (are the tails heavy?). Values near 0 mean roughly symmetric and normal-shaped. numeric = df.select_dtypes(\"number\") stats = numeric.describe().T stats[\"skew\"] = numeric.skew() stats[\"kurtosis\"] = numeric.kurt() stats. round (2) count mean std min 25% 50% 75% max skew kurtosis IV1_ITEM1 100.0 3.09 1.22 1.0 2.00 3.00 4.00 5.0 -0.01 -0.86 IV1_ITEM2 100.0 3.05 1.24 1.0 2.00 3.00 4.00 5.0 -0.06 -0.94 IV2_ITEM1 100.0 2.84 1.16 1.0 2.00 3.00 3.00 5.0 0.32 -0.53 IV2_ITEM2 100.0 2.78 1.31 1.0 2.00 3.00 4.00 5.0 0.17 -1.06 DV_ITEM1 100.0 2.57 1.20 1.0 2.00 2.00 3.25 5.0 0.42 -0.79 DV_ITEM2 100.0 2.56 1.17 1.0 2.00 3.00 3.00 5.0 0.34 -0.58 IV_INDEX1 100.0 3.07 1.11 1.0 2.38 3.00 4.00 5.0 -0.03 -0.89 IV_INDEX2 100.0 2.81 1.15 1.0 2.00 2.75 3.50 5.0 0.29 -0.79 DV_INDEX 100.0 2.56 1.09 1.0 1.88 2.50 3.50 5.0 0.46 -0.52 2.2 Frequencies For the group variable and the 1–5 items, it is more useful to count how often each value occurs. The first table counts the two groups; the second shows, for each item, the share of respondents (in %) who chose each answer from 1 to 5. df[\"IV_CAT_GROUP\"].value_counts() IV_CAT_GROUP category2 50 category1 50 Name: count, dtype: int64 items = [\"IV1_ITEM1\", \"IV1_ITEM2\", \"IV2_ITEM1\", \"IV2_ITEM2\", \"DV_ITEM1\", \"DV_ITEM2\"] freq = df[items]. apply (lambda s: s.value_counts(normalize = True)).fillna(0) * 100 freq.index.name = \"answer\" freq. round (0) IV1_ITEM1 IV1_ITEM2 IV2_ITEM1 IV2_ITEM2 DV_ITEM1 DV_ITEM2 answer 1 11.0 13.0 12.0 21.0 20.0 22.0 2 21.0 21.0 28.0 23.0 35.0 26.0 3 32.0 28.0 36.0 25.0 20.0 33.0 4 20.0 24.0 12.0 19.0 18.0 12.0 5 16.0 14.0 12.0 12.0 7.0 7.0 2.3 Distributions A histogram shows how the values of one variable are spread out: each bar counts the respondents in a range of values. The smooth line is a density curve, an estimate of the shape of the distribution. Items have only five possible values, so their bars are discrete; the indices take more values and look smoother. import seaborn as sns sns.set_theme(style = \"whitegrid\") fig, axes = plt.subplots(3, 3, figsize = (9, 7.5)) for ax, col in zip (axes.flat, numeric.columns): sns.histplot(df[col], bins = 9, kde = True, color = \"#2f9e44\", ax = ax) ax.set_title(col) ax.set_xlabel(\"\") fig.tight_layout() plt.show() 2.4 Categorical variable The group variable is text, so it gets a bar chart of counts instead of a histogram. Both groups have 50 respondents: the design is balanced. fig, ax = plt.subplots(figsize = (4.5, 3.2)) sns.countplot(data = df, x = \"IV_CAT_GROUP\", color = \"#2f9e44\", ax = ax) ax.set_xlabel(\"\") plt.show() 3 Relating the outcome to the predictors 3.1 Group comparison table Now we look at two variables at a time: the outcome DV_INDEX against each predictor. We use the indices rather than the single items, since each index summarises its two items. First, the outcome split by group: does the average differ between the groups? df.groupby(\"IV_CAT_GROUP\")[\"DV_INDEX\"].agg([\"count\", \"mean\", \"std\", \"median\"]). round (2) count mean std median IV_CAT_GROUP category1 50 2.87 1.04 2.75 category2 50 2.26 1.06 2.00 3.2 Correlation table For two numeric variables, the correlation (Pearson’s r) measures how closely they move together, from −1 (opposite) through 0 (unrelated) to +1 (in step). df[[\"DV_INDEX\", \"IV_INDEX1\", \"IV_INDEX2\"]].corr(). round (2) DV_INDEX IV_INDEX1 IV_INDEX2 DV_INDEX 1.00 0.41 0.41 IV_INDEX1 0.41 1.00 0.32 IV_INDEX2 0.41 0.32 1.00 3.3 Visualizations Left: the outcome per group as a box plot (median, middle half and range) with each respondent as a dot. Middle and right: the outcome against each index, one dot per respondent, with a fitted straight line and its uncertainty band. import numpy as np np.random.seed(1) # same random jitter and uncertainty band on every run fig, axes = plt.subplots(1, 3, figsize = (10, 3.6)) sns.boxplot(data = df, x = \"IV_CAT_GROUP\", y = \"DV_INDEX\", color = \"#d3f9d8\", ax = axes[0]) sns.stripplot(data = df, x = \"IV_CAT_GROUP\", y = \"DV_INDEX\", color = \"#2f9e44\", alpha = 0.6, jitter = 0.2, ax = axes[0]) axes[0].set_xlabel(\"\") for ax, iv in zip (axes[1:], [\"IV_INDEX1\", \"IV_INDEX2\"]): sns.regplot(data = df, x = iv, y = \"DV_INDEX\", color = \"#2f9e44\", scatter_kws = { \"alpha\": 0.6 }, ax = ax, seed = 1) fig.tight_layout() plt.show() 3.4 Significance tests A significance test asks: could a difference or relationship this large plausibly appear by chance if there were none in the population? A small p -value (by convention below 0.05) says chance alone is an unlikely explanation. The effect size says how large the effect is, which p does not. Group → DV: Welch’s t-test compares the two group means; Cohen’s d is the difference in standard-deviation units (around 0.2 small, 0.5 medium, 0.8 large). Index → DV: Pearson’s correlation test; r itself is the effect size (around 0.1 small, 0.3 medium, 0.5 large). from scipy import stats as st g1, g2 = (df.loc[df[\"IV_CAT_GROUP\"] == g, \"DV_INDEX\"] for g in [\"category1\", \"category2\"]) t = st.ttest_ind(g1, g2, equal_var = False) pooled_sd = ((g1.var() + g2.var()) / 2) ** 0.5 results = [{ \"predictor\": \"IV_CAT_GROUP\", \"test\": \"Welch t-test\", \"statistic\": t.statistic, \"p\": t.pvalue, \"effect size\": (g1.mean() - g2.mean()) / pooled_sd, \"measure\": \"Cohen's d\", }] for iv in [\"IV_INDEX1\", \"IV_INDEX2\"]: r = st.pearsonr(df[iv], df[\"DV_INDEX\"]) results.append({ \"predictor\": iv, \"test\": \"Pearson correlation\", \"statistic\": r.statistic, \"p\": r.pvalue, \"effect size\": r.statistic, \"measure\": \"r\", }) results = pd.DataFrame(results). round (3) results[\"p\"] = results[\"p\"]. map (lambda p: \"<.001\" if p < 0.001 else f\" { p:.3f} \") results predictor test statistic p effect size measure 0 IV_CAT_GROUP Welch t-test 2.905 0.005 0.581 Cohen's d 1 IV_INDEX1 Pearson correlation 0.412 <.001 0.412 r 2 IV_INDEX2 Pearson correlation 0.411 <.001 0.411 r The data are simulated, so these effects were built in on purpose; with real survey data, read them as associations, not proof of cause and effect. 3.5 Check the AI AI assistants write convincing code, and sometimes convincing mistakes. Before you trust an AI-produced result, check one number yourself: Paste the context prompt from section 1.6 into a chat assistant. Ask it for the mean of DV_INDEX in each group, or the correlation between DV_INDEX and IV_INDEX1. Run its code and compare the answer with the tables above. Do they match? If not, which one is right — and why?"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/02-data-generation-slides.html",
   "path": "coding/skill-school/sessions/02-data-generation-slides.html",
   "title": "Session 2 · de-code data generation",
   "description": "Parts: Generate a toy dataset from a prompt; Make it realistic: a TPB survey experiment; Persona engineering.",
   "section": "coding",
   "type": "slides",
   "stack": "quarto",
   "headings": [
    "Topics",
    "Recap: session 1",
    "Ask an LLM to explain code",
    "Ask an LLM to fix an error",
    "Data analysis specification",
    "1 Generate a toy dataset from a prompt",
    "1.1 The prompt",
    "1.2 Anatomy of the prompt",
    "1.3 Run the generated code",
    "2 Make it realistic: a TPB survey experiment",
    "2.1 Background",
    "2.2 Update the prompt",
    "2.3 The generated code",
    "2.4 Your own dataset",
    "3 Persona engineering",
    "3.1 From numbers to respondents",
    "3.2 Key concepts",
    "3.3 A persona prompt"
   ],
   "words": 5018,
   "updated": "2026-10-07",
   "text": "Topics Recap: session 1 Ask an LLM to explain code Ask an LLM to fix an error Data analysis specification 1 Generate a toy dataset from a prompt 1.1 The prompt 1.2 Anatomy of the prompt 1.3 Run the generated code 2 Make it realistic: a TPB survey experiment 2.1 Background 2.2 Update the prompt 2.3 The generated code 2.4 Your own dataset 3 Persona engineering 3.1 From numbers to respondents 3.2 Key concepts 3.3 A persona prompt Slides Notebook Recap: session 1 Yesterday we loaded a small simulated survey, described each of its variables, and related the outcome to its predictors — step by step, with code and explanations. First we practise letting an LLM explain and fix code; then we condense all of yesterday’s work into one short specification. Ask an LLM to explain code Code you did not write yourself is easier to trust once you understand it. Paste a code chunk into Gemini — in the Colab side panel or in the Gemini chat — and ask for a line-by-line explanation. Here is a small plotting chunk (it contains a mistake; we come back to it below): import matplotlib.pyplot as plt steps = [\"load\", \"clean\", \"explore\", \"model\", \"report\"] minutes = [10, 25, 30, 20, 15] fig, ax = plt.subplots() ax.bar(steps, minutes, color = \"#2f9e44\", width = 0.62) ax.spines[[\"top\", \"right\"]].set_visible(xyz) ax.grid(axis = \"y\", color = \"#e6e6e6\", linewidth = 0.8) ax.set_axisbelow(True) ax.set_ylabel(\"minutes\") ax.set_title(\"Placeholder: time per analysis step\") plt.tight_layout() plt.show() A prompt that asks for comments inside the code keeps the explanation next to the line it explains: explain_prompt = \"\"\" Explain this Python code line by line for a beginner. Return the same code with a short comment above every line. Point out anything that looks wrong. \"\"\" The answer looks something like this — the same code, with a comment above each line: # load matplotlib's plotting interface under the short name plt import matplotlib.pyplot as plt # the five analysis steps: the labels on the x axis steps = [\"load\", \"clean\", \"explore\", \"model\", \"report\"] # minutes spent on each step: the bar heights, in the same order minutes = [10, 25, 30, 20, 15] # create an empty figure (fig) with one set of axes (ax) to draw on fig, ax = plt.subplots() # draw one green bar per step; width < 1 leaves gaps between the bars ax.bar(steps, minutes, color = \"#2f9e44\", width = 0.62) # meant to hide the top and right frame lines — but xyz is not defined (looks wrong!) ax.spines[[\"top\", \"right\"]].set_visible(xyz) # add light grey horizontal grid lines to make the bar heights easier to read ax.grid(axis = \"y\", color = \"#e6e6e6\", linewidth = 0.8) # draw the grid lines behind the bars, not on top of them ax.set_axisbelow(True) # label the y axis ax.set_ylabel(\"minutes\") # give the chart a title ax.set_title(\"Placeholder: time per analysis step\") # shrink the margins so labels and title fit inside the figure plt.tight_layout() # display the finished figure plt.show() Ask an LLM to fix an error Run the original chunk in Colab and it stops with an error. The message says where (the arrow ----> points at the xyz line) and what went wrong (the name xyz does not exist): NameError Traceback (most recent call last) <ipython-input-1> in <cell line: 0>() 6 fig, ax = plt.subplots() 7 ax.bar(steps, minutes, color=\"#2f9e44\", width=0.62) ----> 8 ax.spines[[\"top\", \"right\"]].set_visible(xyz) 9 ax.grid(axis=\"y\", color=\"#e6e6e6\", linewidth=0.8) 10 ax.set_axisbelow(True) NameError: name 'xyz' is not defined In Colab, click Explain error under the message and Gemini explains it and suggests a fix. In a chat, paste the code and the error message with a prompt like this: fix_prompt = \"\"\" This code stops with the error below. Explain the cause in one sentence and return the corrected code. Change as little as possible. \"\"\" The cause: set_visible() expects True or False, and xyz is an undefined name. To hide the top and right frame lines, that line becomes: ax.spines[[\"top\", \"right\"]].set_visible(False) Read the suggested fix before you run it, and ask “why?” if it is not clear. Then re-run the chunk and check that the chart looks as intended. (In the notebook this chunk fails on purpose, so Run all stops here — run the cells one at a time, or fix the xyz line first.) Data analysis specification The spec has four parts: Data (where the file is and what the columns mean), Implementation Tech Stack (which tools to build with), Analyses (the steps, in order) and Output (what the result must look like). It says what to do, not how, so it stays short. Give it to an AI agent — Antigravity, or Gemini in Colab — with the instruction “Follow ANALYSIS-SPEC.md”, and it redoes the whole analysis as one web page, data-analysis.html. Open it by double-clicking: it needs a web browser and an internet connection, but no Python. analysis_spec = \"\"\" # Analysis spec: komp014 toy dataset ## Data - URL: https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv (tab-separated, 100 rows, no missing values) - IV_CAT_GROUP: category1 / category2 - Six items 1-5: IV1_ITEM1, IV1_ITEM2, IV2_ITEM1, IV2_ITEM2, DV_ITEM1, DV_ITEM2 - Indices = item means: IV_INDEX1, IV_INDEX2, DV_INDEX (outcome) ## Implementation Tech Stack - Standalone HTML file using Observable JS libraries loaded via CDN: - `@observablehq/plot` (for data visualization including linear regression trends) - `d3-dsv` or `d3-fetch` (for parsing TSV data) - Standard JavaScript for statistical calculations (mean, SD, skew, kurtosis, Welch's t-test, Cohen's d, Pearson r) ## Analyses 1. Load: fetch TSV data; log and display row/column counts and confirm no missing values. 2. Describe: generate an HTML table with mean, SD, skewness, and kurtosis for all numeric variables; frequency tables for IV_CAT_GROUP and the six item variables. 3. Visualise: render histograms with density marks for numeric variables using Observable Plot; render bar chart for IV_CAT_GROUP frequencies. 4. Relate DV_INDEX to each predictor: calculate group means/SDs; display Pearson correlation matrix; render box plots by group and scatter plots with `Plot.linearRegression()` trendlines. 5. Test: calculate Welch's t-test and Cohen's d across groups for DV_INDEX; calculate Pearson's r with associated p-values for each index relationship. ## Output - Output a single standalone file named `data-analysis.html`. - Structure the document with styled HTML sections for each analysis step. - Include a short plain-language interpretation directly beneath each output section. - Ensure the document executes and renders interactively when opened directly in any web browser. \"\"\" with open (\"ANALYSIS-SPEC.md\", \"w\") as f: f.write(analysis_spec) Then check the agent’s work against yesterday’s results — for example Cohen’s d ≈ 0.58 for the group difference and r ≈.41 for both indices. Do the numbers match? 1 Generate a toy dataset from a prompt 1.1 The prompt In session 1 we analysed a small simulated survey. Here we see how a dataset like that is made: we describe the data we want in words, and an AI model writes the Python code that generates it. The prompt below was given to Gemini — open the Gemini chat to see the answer, or paste the prompt into a chat of your own. The cell only stores the text; it is not run. prompt = \"\"\" Write a complete, reproducible Jupyter notebook Python code cell as code snippet using numpy, pandas, scipy, and statsmodels that generates and validates a synthetic dataset of exactly 100 cases saved to komp014-simulated-data-n100.tsv. Generate continuous, normally distributed latent variables converted via fixed thresholding into five-category ordinal Likert items (1-5) forming three mean indices: - one dependent index (DV_INDEX composed of items DV_ITEM1, DV_ITEM2) - two independent indices (IV_INDEX1 composed of IV1_ITEM1, IV1_ITEM2; IV_INDEX2 composed of IV2_ITEM1, IV2_ITEM2) Ensure all item scores are symmetric and bell-shaped, scale alphas are 0.65-0.85, IV_INDEX1 and IV_INDEX2 have weak positive intercorrelations, and all predictor indices have moderate positive relationships (r = 0.30-0.50) with DV_INDEX. Also create a categorical variable: - an independent categorical variable (IV_CAT_GROUP with 50% \"category1\" and 50% \"category2\" cases), while IV_CAT_GROUP (\"category2\" vs. \"category1\") has a moderate negative relationship with DV_INDEX (Cohen's d = -0.40 to -0.60). Use a bounded, transparent seed-search loop to select the first seed satisfying these exact criteria without manually altering observations. Print the selected seed, missing value count (0), category frequencies, index descriptives (mean, SD, skewness, Cronbach's alpha), Pearson correlations, a Welch t-test with Cohen's d, and a multiple OLS regression reporting coefficients, 95% CIs, R^2, and p-values (p < 0.05 for all predictors). Return only executable Python code with concise comments. \"\"\" 1.2 Anatomy of the prompt The prompt is long, but every part has a job. Read it as a specification: Part of the prompt Example What it does Output contract “complete, reproducible … code cell”, “numpy, pandas, scipy, and statsmodels”, “Return only executable Python code” Fixes what comes back: one runnable cell, known libraries, no long explanations to delete. Sample and file “exactly 100 cases saved to komp014-simulated-data-n100.tsv” Sets the size of the data and where it ends up. Data-generating model “normally distributed latent variables converted via fixed thresholding into … Likert items (1-5)” Says how the numbers arise: a hidden continuous score per person, cut into five answer categories, like a real questionnaire. Variables and roles “DV_INDEX composed of DV_ITEM1, DV_ITEM2”, “IV_CAT_GROUP with 50% …” Names every column and says which ones are items, indices, outcome and predictors. Statistical targets “alphas 0.65-0.85”, “r = 0.30-0.50”, “Cohen’s d = -0.40 to -0.60” Plants the patterns you want students to find later — with ranges, so the result is realistic rather than perfect. Reproducibility “bounded, transparent seed-search loop”, “without manually altering observations” The code tries random seeds in order and keeps the first dataset that meets every target; nobody edits rows by hand. Validation output “Print the selected seed, … Welch t-test … OLS regression” Makes the code prove that the data meet the specification. The key idea: every number in the prompt becomes a check in the code. If you cannot check a requirement, the AI cannot reliably meet it either. 1.3 Run the generated code This is the code Gemini returned. Run it in the session notebook in Colab to test it: it searches for a seed, saves komp014-simulated-data-n100.tsv and prints the validation report. The result is a dataset like the one from session 1 — same design, different random draw. import numpy as np import pandas as pd from scipy import stats import statsmodels.api as sm def cronbach_alpha(df_items): k = df_items.shape[1] item_variances = df_items.var(axis = 0, ddof = 1). sum () total_variance = df_items. sum (axis = 1).var(ddof = 1) return (k / (k - 1)) * (1 - item_variances / total_variance) def compute_cohens_d(group2, group1): n1, n2 = len (group1), len (group2) s1, s2 = np.std(group1, ddof = 1), np.std(group2, ddof = 1) s_pooled = np.sqrt(((n1 - 1) * s1 ** 2 + (n2 - 1) * s2 ** 2) / (n1 + n2 - 2)) return (np.mean(group2) - np.mean(group1)) / s_pooled target_seed = None final_df = None # Search for seed satisfying all criteria for seed in range (1, 10000): rng = np.random.default_rng(seed) # 1. Generate correlated continuous latent variables # Order: [Latent_DV, Latent_IV1, Latent_IV2] mean_vec = [0, 0, 0] cov_matrix = [[1.00, 0.60, 0.60], # Latent DV target correlations [0.60, 1.00, 0.25], # Latent IV1 target correlations [0.60, 0.25, 1.00], # Latent IV2 target correlations] latent_indices = rng.multivariate_normal(mean_vec, cov_matrix, size = 100) # 2. Add item noise to latent variables latent_items = np.column_stack([latent_indices[:, 0] + rng.normal(0, 0.7, 100), # DV_ITEM1 latent_indices[:, 0] + rng.normal(0, 0.7, 100), # DV_ITEM2 latent_indices[:, 1] + rng.normal(0, 0.7, 100), # IV1_ITEM1 latent_indices[:, 1] + rng.normal(0, 0.7, 100), # IV1_ITEM2 latent_indices[:, 2] + rng.normal(0, 0.7, 100), # IV2_ITEM1 latent_indices[:, 2] + rng.normal(0, 0.7, 100), # IV2_ITEM2]) # 3. Categorize into symmetric 5-point Likert items using fixed cutoffs cutoffs = [- 1.2, - 0.4, 0.4, 1.2] likert_items = np.digitize(latent_items, cutoffs) + 1 df = pd.DataFrame(likert_items, columns = [\"DV_ITEM1\", \"DV_ITEM2\", \"IV1_ITEM1\", \"IV1_ITEM2\", \"IV2_ITEM1\", \"IV2_ITEM2\",],) # 4. Form Mean Indices df[\"DV_INDEX\"] = df[[\"DV_ITEM1\", \"DV_ITEM2\"]].mean(axis = 1) df[\"IV_INDEX1\"] = df[[\"IV1_ITEM1\", \"IV1_ITEM2\"]].mean(axis = 1) df[\"IV_INDEX2\"] = df[[\"IV2_ITEM1\", \"IV2_ITEM2\"]].mean(axis = 1) # 5. Create balanced categorical variable (50% category1, 50% category2) # Higher DV values get slightly higher probability for category1 to enforce negative effect for category2 dv_rank = stats.rankdata(- df[\"DV_INDEX\"]) cat_prob = dv_rank / 100.0 group2_idx = rng.choice(100, size = 50, replace = False, p = cat_prob / cat_prob. sum ()) cat_arr = np.array([\"category1\"] * 100) cat_arr[group2_idx] = \"category2\" df[\"IV_CAT_GROUP\"] = cat_arr # 6. Validate Criteria alpha_dv = cronbach_alpha(df[[\"DV_ITEM1\", \"DV_ITEM2\"]]) alpha_iv1 = cronbach_alpha(df[[\"IV1_ITEM1\", \"IV1_ITEM2\"]]) alpha_iv2 = cronbach_alpha(df[[\"IV2_ITEM1\", \"IV2_ITEM2\"]]) # Cronbach's Alphas between 0.65 and 0.85 if not (0.65 <= alpha_dv <= 0.85 and 0.65 <= alpha_iv1 <= 0.85 and 0.65 <= alpha_iv2 <= 0.85): continue # Correlations r_iv1_iv2 = df[\"IV_INDEX1\"].corr(df[\"IV_INDEX2\"]) r_iv1_dv = df[\"IV_INDEX1\"].corr(df[\"DV_INDEX\"]) r_iv2_dv = df[\"IV_INDEX2\"].corr(df[\"DV_INDEX\"]) if not (0.10 <= r_iv1_iv2 <= 0.30): # Weak positive intercorrelation continue if not (0.30 <= r_iv1_dv <= 0.50 and 0.30 <= r_iv2_dv <= 0.50): # Moderate positive with DV continue # Categorical Group Cohen's d g1 = df[df[\"IV_CAT_GROUP\"] == \"category1\"][\"DV_INDEX\"] g2 = df[df[\"IV_CAT_GROUP\"] == \"category2\"][\"DV_INDEX\"] d_val = compute_cohens_d(g2, g1) if not (- 0.60 <= d_val <= - 0.40): continue # Skewness check for items (-0.5 to 0.5 for symmetry) item_skews = [stats.skew(df[col]) for col in df.columns[: 6]] if any (abs (s) > 0.5 for s in item_skews): continue # OLS Regression validation (p-values < 0.05 for all predictors) df[\"IV_CAT_DUMMY\"] = (df[\"IV_CAT_GROUP\"] == \"category2\").astype(int) X = sm.add_constant(df[[\"IV_INDEX1\", \"IV_INDEX2\", \"IV_CAT_DUMMY\"]]) y = df[\"DV_INDEX\"] model = sm.OLS(y, X).fit() if any (p >= 0.05 for p in model.pvalues): continue # If all criteria are met: target_seed = seed final_df = df.drop(columns = [\"IV_CAT_DUMMY\"]) break # Save Dataset final_df.to_csv(\"komp014-simulated-data-n100.tsv\", sep = \" \\t \", index = False) # Print Validation Results print (f\"Selected Seed: { target_seed } \") print (f\"Missing Value Count: { final_df. isnull(). sum (). sum () } \") print (\" \\n --- Category Frequencies ---\") print (final_df[\"IV_CAT_GROUP\"].value_counts()) print (\" \\n --- Index Descriptives & Reliability ---\") indices = [\"DV_INDEX\", \"IV_INDEX1\", \"IV_INDEX2\"] items_map = { \"DV_INDEX\": [\"DV_ITEM1\", \"DV_ITEM2\"], \"IV_INDEX1\": [\"IV1_ITEM1\", \"IV1_ITEM2\"], \"IV_INDEX2\": [\"IV2_ITEM1\", \"IV2_ITEM2\"], } for idx in indices: m = final_df[idx].mean() sd = final_df[idx].std() sk = stats.skew(final_df[idx]) a = cronbach_alpha(final_df[items_map[idx]]) print (f\" { idx } -> Mean: { m:.3f}, SD: { sd:.3f}, Skewness: { sk:.3f}, Cronbach's Alpha: { a:.3f} \") print (\" \\n --- Pearson Correlations ---\") corr_matrix = final_df[[\"DV_INDEX\", \"IV_INDEX1\", \"IV_INDEX2\"]].corr() print (corr_matrix. round (3)) print (\" \\n --- Welch t-test & Cohen's d ---\") g1_dv = final_df[final_df[\"IV_CAT_GROUP\"] == \"category1\"][\"DV_INDEX\"] g2_dv = final_df[final_df[\"IV_CAT_GROUP\"] == \"category2\"][\"DV_INDEX\"] t_stat, p_val = stats.ttest_ind(g2_dv, g1_dv, equal_var = False) d_stat = compute_cohens_d(g2_dv, g1_dv) print (f\"Welch t-statistic: { t_stat:.3f}, p-value: { p_val:.4f}, Cohen's d: { d_stat:.3f} \") print (\" \\n --- Multiple OLS Regression ---\") X_final = sm.add_constant(pd.DataFrame({ \"IV_INDEX1\": final_df[\"IV_INDEX1\"], \"IV_INDEX2\": final_df[\"IV_INDEX2\"], \"IV_CAT_GROUP[category2]\": (final_df[\"IV_CAT_GROUP\"] == \"category2\").astype(int), })) ols_res = sm.OLS(final_df[\"DV_INDEX\"], X_final).fit() results_df = pd.DataFrame({ \"Coef\": ols_res.params, \"95% CI Lower\": ols_res.conf_int()[0], \"95% CI Upper\": ols_res.conf_int()[1], \"p-value\": ols_res.pvalues, }) print (results_df. round (4)) print (f\" \\n R-squared: { ols_res. rsquared:.4f} \") Selected Seed: 122 Missing Value Count: 0 --- Category Frequencies --- IV_CAT_GROUP category2 50 category1 50 Name: count, dtype: int64 --- Index Descriptives & Reliability --- DV_INDEX -> Mean: 3.155, SD: 1.232, Skewness: -0.230, Cronbach's Alpha: 0.803 IV_INDEX1 -> Mean: 3.010, SD: 1.159, Skewness: 0.113, Cronbach's Alpha: 0.693 IV_INDEX2 -> Mean: 2.925, SD: 1.175, Skewness: 0.087, Cronbach's Alpha: 0.764 --- Pearson Correlations --- DV_INDEX IV_INDEX1 IV_INDEX2 DV_INDEX 1.000 0.391 0.43 IV_INDEX1 0.391 1.000 0.14 IV_INDEX2 0.430 0.140 1.00 --- Welch t-test & Cohen's d --- Welch t-statistic: -2.994, p-value: 0.0035, Cohen's d: -0.599 --- Multiple OLS Regression --- Coef 95% CI Lower 95% CI Upper p-value const 1.2808 0.5344 2.0272 0.0010 IV_INDEX1 0.3717 0.1972 0.5462 0.0001 IV_INDEX2 0.3630 0.1892 0.5368 0.0001 IV_CAT_GROUP[category2] -0.6125 -1.0151 -0.2100 0.0032 R-squared: 0.3580 2 Make it realistic: a TPB survey experiment 2.1 Background Names like IV1_ITEM1 are fine for practice, but real studies measure real concepts. Our realistic example asks: what makes children aged 10–13 intend to start learning a musical instrument? It uses the Theory of Planned Behavior (TPB), which says that intention depends on three judgments: Attitude (ATT): would learning an instrument be fun, valuable, good for me? Subjective norm (SN): would my parents, friends and teacher approve? Perceived behavioral control (PBC): am I able to — do I have time and an instrument? Each is measured with three 1–5 agree/disagree statements, and so is the outcome, behavioral intention (BI) to start learning. The study also contains a small experiment: half the children read a short positive testimonial from another child who started an instrument (treatment), the other half read nothing like it (control). Age group, grade and gender describe the sample. The records are synthetic teaching data, not answers from real children. 2.2 Update the prompt Instead of writing a new prompt from scratch, we ask the model to revise the previous one. Send this in the same Gemini chat, so it can reuse the code it already wrote. update_prompt = \"\"\" Rewrite the previous code so that it generates a realistic synthetic dataset for a Theory of Planned Behavior (TPB) survey experiment instead of the generic one. Keep the same approach (normal latent scores, fixed thresholds into 1-5 Likert items, mean indices, bounded seed search, no manual edits, printed validation), but change: Sample: exactly 100 synthetic children aged 10-13 in Grades 4-6. Background variables: - age_group: \"10 years\", \"11 years\", \"12 years\", \"13 years\" (about 26%, 32%, 32%, 10%) - grade_level: \"Grade 4\", \"Grade 5\", \"Grade 6\", realistically dependent on age - gender: about 46% \"Girl\", 50% \"Boy\", 2% \"Non-binary\", 2% \"Prefer not to say\" - experimental_condition: exactly 50 \"control\" and 50 \"treatment\", randomly assigned and independent of everything measured before it Four constructs, three 1-5 Likert items each (1 = strongly disagree, 5 = strongly agree): - Attitude: att_fun_exciting, att_valuable_use_of_time, att_feel_good_about_self - Subjective norm: sn_parent_guardian_approval, sn_friend_approval, sn_teacher_encouragement - Perceived behavioral control: pbc_confident_can_learn, pbc_enough_spare_time, pbc_instrument_access - Behavioral intention: bi_plan_next_6_months, bi_try_best_to_learn_soon, bi_w"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/02-data-generation.html",
   "path": "coding/skill-school/sessions/02-data-generation.html",
   "title": "Session 2 · de-code data generation",
   "description": "Parts: Generate a toy dataset from a prompt; Make it realistic: a TPB survey experiment; Persona engineering.",
   "section": "coding",
   "type": "page",
   "stack": "quarto",
   "headings": [
    "Topics",
    "Recap: session 1",
    "Ask an LLM to explain code",
    "Ask an LLM to fix an error",
    "Data analysis specification",
    "1 Generate a toy dataset from a prompt",
    "1.1 The prompt",
    "1.2 Anatomy of the prompt",
    "1.3 Run the generated code",
    "2 Make it realistic: a TPB survey experiment",
    "2.1 Background",
    "2.2 Update the prompt",
    "2.3 The generated code",
    "2.4 Your own dataset",
    "3 Persona engineering",
    "3.1 From numbers to respondents",
    "3.2 Key concepts",
    "3.3 A persona prompt"
   ],
   "words": 5018,
   "updated": "2026-10-09",
   "text": "Topics Recap: session 1 Ask an LLM to explain code Ask an LLM to fix an error Data analysis specification 1 Generate a toy dataset from a prompt 1.1 The prompt 1.2 Anatomy of the prompt 1.3 Run the generated code 2 Make it realistic: a TPB survey experiment 2.1 Background 2.2 Update the prompt 2.3 The generated code 2.4 Your own dataset 3 Persona engineering 3.1 From numbers to respondents 3.2 Key concepts 3.3 A persona prompt Slides Notebook Recap: session 1 Yesterday we loaded a small simulated survey, described each of its variables, and related the outcome to its predictors — step by step, with code and explanations. First we practise letting an LLM explain and fix code; then we condense all of yesterday’s work into one short specification. Ask an LLM to explain code Code you did not write yourself is easier to trust once you understand it. Paste a code chunk into Gemini — in the Colab side panel or in the Gemini chat — and ask for a line-by-line explanation. Here is a small plotting chunk (it contains a mistake; we come back to it below): import matplotlib.pyplot as plt steps = [\"load\", \"clean\", \"explore\", \"model\", \"report\"] minutes = [10, 25, 30, 20, 15] fig, ax = plt.subplots() ax.bar(steps, minutes, color = \"#2f9e44\", width = 0.62) ax.spines[[\"top\", \"right\"]].set_visible(xyz) ax.grid(axis = \"y\", color = \"#e6e6e6\", linewidth = 0.8) ax.set_axisbelow(True) ax.set_ylabel(\"minutes\") ax.set_title(\"Placeholder: time per analysis step\") plt.tight_layout() plt.show() A prompt that asks for comments inside the code keeps the explanation next to the line it explains: explain_prompt = \"\"\" Explain this Python code line by line for a beginner. Return the same code with a short comment above every line. Point out anything that looks wrong. \"\"\" The answer looks something like this — the same code, with a comment above each line: # load matplotlib's plotting interface under the short name plt import matplotlib.pyplot as plt # the five analysis steps: the labels on the x axis steps = [\"load\", \"clean\", \"explore\", \"model\", \"report\"] # minutes spent on each step: the bar heights, in the same order minutes = [10, 25, 30, 20, 15] # create an empty figure (fig) with one set of axes (ax) to draw on fig, ax = plt.subplots() # draw one green bar per step; width < 1 leaves gaps between the bars ax.bar(steps, minutes, color = \"#2f9e44\", width = 0.62) # meant to hide the top and right frame lines — but xyz is not defined (looks wrong!) ax.spines[[\"top\", \"right\"]].set_visible(xyz) # add light grey horizontal grid lines to make the bar heights easier to read ax.grid(axis = \"y\", color = \"#e6e6e6\", linewidth = 0.8) # draw the grid lines behind the bars, not on top of them ax.set_axisbelow(True) # label the y axis ax.set_ylabel(\"minutes\") # give the chart a title ax.set_title(\"Placeholder: time per analysis step\") # shrink the margins so labels and title fit inside the figure plt.tight_layout() # display the finished figure plt.show() Ask an LLM to fix an error Run the original chunk in Colab and it stops with an error. The message says where (the arrow ----> points at the xyz line) and what went wrong (the name xyz does not exist): NameError Traceback (most recent call last) <ipython-input-1> in <cell line: 0>() 6 fig, ax = plt.subplots() 7 ax.bar(steps, minutes, color=\"#2f9e44\", width=0.62) ----> 8 ax.spines[[\"top\", \"right\"]].set_visible(xyz) 9 ax.grid(axis=\"y\", color=\"#e6e6e6\", linewidth=0.8) 10 ax.set_axisbelow(True) NameError: name 'xyz' is not defined In Colab, click Explain error under the message and Gemini explains it and suggests a fix. In a chat, paste the code and the error message with a prompt like this: fix_prompt = \"\"\" This code stops with the error below. Explain the cause in one sentence and return the corrected code. Change as little as possible. \"\"\" The cause: set_visible() expects True or False, and xyz is an undefined name. To hide the top and right frame lines, that line becomes: ax.spines[[\"top\", \"right\"]].set_visible(False) Read the suggested fix before you run it, and ask “why?” if it is not clear. Then re-run the chunk and check that the chart looks as intended. (In the notebook this chunk fails on purpose, so Run all stops here — run the cells one at a time, or fix the xyz line first.) Data analysis specification The spec has four parts: Data (where the file is and what the columns mean), Implementation Tech Stack (which tools to build with), Analyses (the steps, in order) and Output (what the result must look like). It says what to do, not how, so it stays short. Give it to an AI agent — Antigravity, or Gemini in Colab — with the instruction “Follow ANALYSIS-SPEC.md”, and it redoes the whole analysis as one web page, data-analysis.html. Open it by double-clicking: it needs a web browser and an internet connection, but no Python. analysis_spec = \"\"\" # Analysis spec: komp014 toy dataset ## Data - URL: https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv (tab-separated, 100 rows, no missing values) - IV_CAT_GROUP: category1 / category2 - Six items 1-5: IV1_ITEM1, IV1_ITEM2, IV2_ITEM1, IV2_ITEM2, DV_ITEM1, DV_ITEM2 - Indices = item means: IV_INDEX1, IV_INDEX2, DV_INDEX (outcome) ## Implementation Tech Stack - Standalone HTML file using Observable JS libraries loaded via CDN: - `@observablehq/plot` (for data visualization including linear regression trends) - `d3-dsv` or `d3-fetch` (for parsing TSV data) - Standard JavaScript for statistical calculations (mean, SD, skew, kurtosis, Welch's t-test, Cohen's d, Pearson r) ## Analyses 1. Load: fetch TSV data; log and display row/column counts and confirm no missing values. 2. Describe: generate an HTML table with mean, SD, skewness, and kurtosis for all numeric variables; frequency tables for IV_CAT_GROUP and the six item variables. 3. Visualise: render histograms with density marks for numeric variables using Observable Plot; render bar chart for IV_CAT_GROUP frequencies. 4. Relate DV_INDEX to each predictor: calculate group means/SDs; display Pearson correlation matrix; render box plots by group and scatter plots with `Plot.linearRegression()` trendlines. 5. Test: calculate Welch's t-test and Cohen's d across groups for DV_INDEX; calculate Pearson's r with associated p-values for each index relationship. ## Output - Output a single standalone file named `data-analysis.html`. - Structure the document with styled HTML sections for each analysis step. - Include a short plain-language interpretation directly beneath each output section. - Ensure the document executes and renders interactively when opened directly in any web browser. \"\"\" with open (\"ANALYSIS-SPEC.md\", \"w\") as f: f.write(analysis_spec) Then check the agent’s work against yesterday’s results — for example Cohen’s d ≈ 0.58 for the group difference and r ≈.41 for both indices. Do the numbers match? 1 Generate a toy dataset from a prompt 1.1 The prompt In session 1 we analysed a small simulated survey. Here we see how a dataset like that is made: we describe the data we want in words, and an AI model writes the Python code that generates it. The prompt below was given to Gemini — open the Gemini chat to see the answer, or paste the prompt into a chat of your own. The cell only stores the text; it is not run. prompt = \"\"\" Write a complete, reproducible Jupyter notebook Python code cell as code snippet using numpy, pandas, scipy, and statsmodels that generates and validates a synthetic dataset of exactly 100 cases saved to komp014-simulated-data-n100.tsv. Generate continuous, normally distributed latent variables converted via fixed thresholding into five-category ordinal Likert items (1-5) forming three mean indices: - one dependent index (DV_INDEX composed of items DV_ITEM1, DV_ITEM2) - two independent indices (IV_INDEX1 composed of IV1_ITEM1, IV1_ITEM2; IV_INDEX2 composed of IV2_ITEM1, IV2_ITEM2) Ensure all item scores are symmetric and bell-shaped, scale alphas are 0.65-0.85, IV_INDEX1 and IV_INDEX2 have weak positive intercorrelations, and all predictor indices have moderate positive relationships (r = 0.30-0.50) with DV_INDEX. Also create a categorical variable: - an independent categorical variable (IV_CAT_GROUP with 50% \"category1\" and 50% \"category2\" cases), while IV_CAT_GROUP (\"category2\" vs. \"category1\") has a moderate negative relationship with DV_INDEX (Cohen's d = -0.40 to -0.60). Use a bounded, transparent seed-search loop to select the first seed satisfying these exact criteria without manually altering observations. Print the selected seed, missing value count (0), category frequencies, index descriptives (mean, SD, skewness, Cronbach's alpha), Pearson correlations, a Welch t-test with Cohen's d, and a multiple OLS regression reporting coefficients, 95% CIs, R^2, and p-values (p < 0.05 for all predictors). Return only executable Python code with concise comments. \"\"\" 1.2 Anatomy of the prompt The prompt is long, but every part has a job. Read it as a specification: Part of the prompt Example What it does Output contract “complete, reproducible … code cell”, “numpy, pandas, scipy, and statsmodels”, “Return only executable Python code” Fixes what comes back: one runnable cell, known libraries, no long explanations to delete. Sample and file “exactly 100 cases saved to komp014-simulated-data-n100.tsv” Sets the size of the data and where it ends up. Data-generating model “normally distributed latent variables converted via fixed thresholding into … Likert items (1-5)” Says how the numbers arise: a hidden continuous score per person, cut into five answer categories, like a real questionnaire. Variables and roles “DV_INDEX composed of DV_ITEM1, DV_ITEM2”, “IV_CAT_GROUP with 50% …” Names every column and says which ones are items, indices, outcome and predictors. Statistical targets “alphas 0.65-0.85”, “r = 0.30-0.50”, “Cohen’s d = -0.40 to -0.60” Plants the patterns you want students to find later — with ranges, so the result is realistic rather than perfect. Reproducibility “bounded, transparent seed-search loop”, “without manually altering observations” The code tries random seeds in order and keeps the first dataset that meets every target; nobody edits rows by hand. Validation output “Print the selected seed, … Welch t-test … OLS regression” Makes the code prove that the data meet the specification. The key idea: every number in the prompt becomes a check in the code. If you cannot check a requirement, the AI cannot reliably meet it either. 1.3 Run the generated code This is the code Gemini returned. Run it in the session notebook in Colab to test it: it searches for a seed, saves komp014-simulated-data-n100.tsv and prints the validation report. The result is a dataset like the one from session 1 — same design, different random draw. import numpy as np import pandas as pd from scipy import stats import statsmodels.api as sm def cronbach_alpha(df_items): k = df_items.shape[1] item_variances = df_items.var(axis = 0, ddof = 1). sum () total_variance = df_items. sum (axis = 1).var(ddof = 1) return (k / (k - 1)) * (1 - item_variances / total_variance) def compute_cohens_d(group2, group1): n1, n2 = len (group1), len (group2) s1, s2 = np.std(group1, ddof = 1), np.std(group2, ddof = 1) s_pooled = np.sqrt(((n1 - 1) * s1 ** 2 + (n2 - 1) * s2 ** 2) / (n1 + n2 - 2)) return (np.mean(group2) - np.mean(group1)) / s_pooled target_seed = None final_df = None # Search for seed satisfying all criteria for seed in range (1, 10000): rng = np.random.default_rng(seed) # 1. Generate correlated continuous latent variables # Order: [Latent_DV, Latent_IV1, Latent_IV2] mean_vec = [0, 0, 0] cov_matrix = [[1.00, 0.60, 0.60], # Latent DV target correlations [0.60, 1.00, 0.25], # Latent IV1 target correlations [0.60, 0.25, 1.00], # Latent IV2 target correlations] latent_indices = rng.multivariate_normal(mean_vec, cov_matrix, size = 100) # 2. Add item noise to latent variables latent_items = np.column_stack([latent_indices[:, 0] + rng.normal(0, 0.7, 100), # DV_ITEM1 latent_indices[:, 0] + rng.normal(0, 0.7, 100), # DV_ITEM2 latent_indices[:, 1] + rng.normal(0, 0.7, 100), # IV1_ITEM1 latent_indices[:, 1] + rng.normal(0, 0.7, 100), # IV1_ITEM2 latent_indices[:, 2] + rng.normal(0, 0.7, 100), # IV2_ITEM1 latent_indices[:, 2] + rng.normal(0, 0.7, 100), # IV2_ITEM2]) # 3. Categorize into symmetric 5-point Likert items using fixed cutoffs cutoffs = [- 1.2, - 0.4, 0.4, 1.2] likert_items = np.digitize(latent_items, cutoffs) + 1 df = pd.DataFrame(likert_items, columns = [\"DV_ITEM1\", \"DV_ITEM2\", \"IV1_ITEM1\", \"IV1_ITEM2\", \"IV2_ITEM1\", \"IV2_ITEM2\",],) # 4. Form Mean Indices df[\"DV_INDEX\"] = df[[\"DV_ITEM1\", \"DV_ITEM2\"]].mean(axis = 1) df[\"IV_INDEX1\"] = df[[\"IV1_ITEM1\", \"IV1_ITEM2\"]].mean(axis = 1) df[\"IV_INDEX2\"] = df[[\"IV2_ITEM1\", \"IV2_ITEM2\"]].mean(axis = 1) # 5. Create balanced categorical variable (50% category1, 50% category2) # Higher DV values get slightly higher probability for category1 to enforce negative effect for category2 dv_rank = stats.rankdata(- df[\"DV_INDEX\"]) cat_prob = dv_rank / 100.0 group2_idx = rng.choice(100, size = 50, replace = False, p = cat_prob / cat_prob. sum ()) cat_arr = np.array([\"category1\"] * 100) cat_arr[group2_idx] = \"category2\" df[\"IV_CAT_GROUP\"] = cat_arr # 6. Validate Criteria alpha_dv = cronbach_alpha(df[[\"DV_ITEM1\", \"DV_ITEM2\"]]) alpha_iv1 = cronbach_alpha(df[[\"IV1_ITEM1\", \"IV1_ITEM2\"]]) alpha_iv2 = cronbach_alpha(df[[\"IV2_ITEM1\", \"IV2_ITEM2\"]]) # Cronbach's Alphas between 0.65 and 0.85 if not (0.65 <= alpha_dv <= 0.85 and 0.65 <= alpha_iv1 <= 0.85 and 0.65 <= alpha_iv2 <= 0.85): continue # Correlations r_iv1_iv2 = df[\"IV_INDEX1\"].corr(df[\"IV_INDEX2\"]) r_iv1_dv = df[\"IV_INDEX1\"].corr(df[\"DV_INDEX\"]) r_iv2_dv = df[\"IV_INDEX2\"].corr(df[\"DV_INDEX\"]) if not (0.10 <= r_iv1_iv2 <= 0.30): # Weak positive intercorrelation continue if not (0.30 <= r_iv1_dv <= 0.50 and 0.30 <= r_iv2_dv <= 0.50): # Moderate positive with DV continue # Categorical Group Cohen's d g1 = df[df[\"IV_CAT_GROUP\"] == \"category1\"][\"DV_INDEX\"] g2 = df[df[\"IV_CAT_GROUP\"] == \"category2\"][\"DV_INDEX\"] d_val = compute_cohens_d(g2, g1) if not (- 0.60 <= d_val <= - 0.40): continue # Skewness check for items (-0.5 to 0.5 for symmetry) item_skews = [stats.skew(df[col]) for col in df.columns[: 6]] if any (abs (s) > 0.5 for s in item_skews): continue # OLS Regression validation (p-values < 0.05 for all predictors) df[\"IV_CAT_DUMMY\"] = (df[\"IV_CAT_GROUP\"] == \"category2\").astype(int) X = sm.add_constant(df[[\"IV_INDEX1\", \"IV_INDEX2\", \"IV_CAT_DUMMY\"]]) y = df[\"DV_INDEX\"] model = sm.OLS(y, X).fit() if any (p >= 0.05 for p in model.pvalues): continue # If all criteria are met: target_seed = seed final_df = df.drop(columns = [\"IV_CAT_DUMMY\"]) break # Save Dataset final_df.to_csv(\"komp014-simulated-data-n100.tsv\", sep = \" \\t \", index = False) # Print Validation Results print (f\"Selected Seed: { target_seed } \") print (f\"Missing Value Count: { final_df. isnull(). sum (). sum () } \") print (\" \\n --- Category Frequencies ---\") print (final_df[\"IV_CAT_GROUP\"].value_counts()) print (\" \\n --- Index Descriptives & Reliability ---\") indices = [\"DV_INDEX\", \"IV_INDEX1\", \"IV_INDEX2\"] items_map = { \"DV_INDEX\": [\"DV_ITEM1\", \"DV_ITEM2\"], \"IV_INDEX1\": [\"IV1_ITEM1\", \"IV1_ITEM2\"], \"IV_INDEX2\": [\"IV2_ITEM1\", \"IV2_ITEM2\"], } for idx in indices: m = final_df[idx].mean() sd = final_df[idx].std() sk = stats.skew(final_df[idx]) a = cronbach_alpha(final_df[items_map[idx]]) print (f\" { idx } -> Mean: { m:.3f}, SD: { sd:.3f}, Skewness: { sk:.3f}, Cronbach's Alpha: { a:.3f} \") print (\" \\n --- Pearson Correlations ---\") corr_matrix = final_df[[\"DV_INDEX\", \"IV_INDEX1\", \"IV_INDEX2\"]].corr() print (corr_matrix. round (3)) print (\" \\n --- Welch t-test & Cohen's d ---\") g1_dv = final_df[final_df[\"IV_CAT_GROUP\"] == \"category1\"][\"DV_INDEX\"] g2_dv = final_df[final_df[\"IV_CAT_GROUP\"] == \"category2\"][\"DV_INDEX\"] t_stat, p_val = stats.ttest_ind(g2_dv, g1_dv, equal_var = False) d_stat = compute_cohens_d(g2_dv, g1_dv) print (f\"Welch t-statistic: { t_stat:.3f}, p-value: { p_val:.4f}, Cohen's d: { d_stat:.3f} \") print (\" \\n --- Multiple OLS Regression ---\") X_final = sm.add_constant(pd.DataFrame({ \"IV_INDEX1\": final_df[\"IV_INDEX1\"], \"IV_INDEX2\": final_df[\"IV_INDEX2\"], \"IV_CAT_GROUP[category2]\": (final_df[\"IV_CAT_GROUP\"] == \"category2\").astype(int), })) ols_res = sm.OLS(final_df[\"DV_INDEX\"], X_final).fit() results_df = pd.DataFrame({ \"Coef\": ols_res.params, \"95% CI Lower\": ols_res.conf_int()[0], \"95% CI Upper\": ols_res.conf_int()[1], \"p-value\": ols_res.pvalues, }) print (results_df. round (4)) print (f\" \\n R-squared: { ols_res. rsquared:.4f} \") Selected Seed: 122 Missing Value Count: 0 --- Category Frequencies --- IV_CAT_GROUP category2 50 category1 50 Name: count, dtype: int64 --- Index Descriptives & Reliability --- DV_INDEX -> Mean: 3.155, SD: 1.232, Skewness: -0.230, Cronbach's Alpha: 0.803 IV_INDEX1 -> Mean: 3.010, SD: 1.159, Skewness: 0.113, Cronbach's Alpha: 0.693 IV_INDEX2 -> Mean: 2.925, SD: 1.175, Skewness: 0.087, Cronbach's Alpha: 0.764 --- Pearson Correlations --- DV_INDEX IV_INDEX1 IV_INDEX2 DV_INDEX 1.000 0.391 0.43 IV_INDEX1 0.391 1.000 0.14 IV_INDEX2 0.430 0.140 1.00 --- Welch t-test & Cohen's d --- Welch t-statistic: -2.994, p-value: 0.0035, Cohen's d: -0.599 --- Multiple OLS Regression --- Coef 95% CI Lower 95% CI Upper p-value const 1.2808 0.5344 2.0272 0.0010 IV_INDEX1 0.3717 0.1972 0.5462 0.0001 IV_INDEX2 0.3630 0.1892 0.5368 0.0001 IV_CAT_GROUP[category2] -0.6125 -1.0151 -0.2100 0.0032 R-squared: 0.3580 2 Make it realistic: a TPB survey experiment 2.1 Background Names like IV1_ITEM1 are fine for practice, but real studies measure real concepts. Our realistic example asks: what makes children aged 10–13 intend to start learning a musical instrument? It uses the Theory of Planned Behavior (TPB), which says that intention depends on three judgments: Attitude (ATT): would learning an instrument be fun, valuable, good for me? Subjective norm (SN): would my parents, friends and teacher approve? Perceived behavioral control (PBC): am I able to — do I have time and an instrument? Each is measured with three 1–5 agree/disagree statements, and so is the outcome, behavioral intention (BI) to start learning. The study also contains a small experiment: half the children read a short positive testimonial from another child who started an instrument (treatment), the other half read nothing like it (control). Age group, grade and gender describe the sample. The records are synthetic teaching data, not answers from real children. 2.2 Update the prompt Instead of writing a new prompt from scratch, we ask the model to revise the previous one. Send this in the same Gemini chat, so it can reuse the code it already wrote. update_prompt = \"\"\" Rewrite the previous code so that it generates a realistic synthetic dataset for a Theory of Planned Behavior (TPB) survey experiment instead of the generic one. Keep the same approach (normal latent scores, fixed thresholds into 1-5 Likert items, mean indices, bounded seed search, no manual edits, printed validation), but change: Sample: exactly 100 synthetic children aged 10-13 in Grades 4-6. Background variables: - age_group: \"10 years\", \"11 years\", \"12 years\", \"13 years\" (about 26%, 32%, 32%, 10%) - grade_level: \"Grade 4\", \"Grade 5\", \"Grade 6\", realistically dependent on age - gender: about 46% \"Girl\", 50% \"Boy\", 2% \"Non-binary\", 2% \"Prefer not to say\" - experimental_condition: exactly 50 \"control\" and 50 \"treatment\", randomly assigned and independent of everything measured before it Four constructs, three 1-5 Likert items each (1 = strongly disagree, 5 = strongly agree): - Attitude: att_fun_exciting, att_valuable_use_of_time, att_feel_good_about_self - Subjective norm: sn_parent_guardian_approval, sn_friend_approval, sn_teacher_encouragement - Perceived behavioral control: pbc_confident_can_learn, pbc_enough_spare_time, pbc_instrument_access - Behavioral intention: bi_plan_next_6_months, bi_try_best_to_learn_soon, bi_w"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/03-app-building-slides.html",
   "path": "coding/skill-school/sessions/03-app-building-slides.html",
   "title": "Session 3 · de-code app building",
   "description": "Parts: What is an app?; Spec for a Shiny data app; Spec for an NLP app: word clouds.",
   "section": "coding",
   "type": "slides",
   "stack": "quarto",
   "headings": [
    "Topics",
    "1 What is an app?",
    "1.1 A flexible definition",
    "1.2 A toy app prompt",
    "1.3 The generated app",
    "2 Spec for a Shiny data app",
    "2.1 How a spec works",
    "2.2 Specs and PRDs",
    "2.3 Purpose and users",
    "2.4 Data",
    "2.5 Features and layout",
    "2.6 Behaviour",
    "2.7 Technical constraints",
    "2.8 Acceptance checks",
    "2.9 Putting it online",
    "2.10 Save the spec",
    "3 Spec for an NLP app: word clouds",
    "3.1 What an NLP app does",
    "3.2 A Python app in the notebook",
    "3.3 A JavaScript app in the browser",
    "3.4 Your turn"
   ],
   "words": 3806,
   "updated": "2026-10-07",
   "text": "Topics 1 What is an app? 1.1 A flexible definition 1.2 A toy app prompt 1.3 The generated app 2 Spec for a Shiny data app 2.1 How a spec works 2.2 Specs and PRDs 2.3 Purpose and users 2.4 Data 2.5 Features and layout 2.6 Behaviour 2.7 Technical constraints 2.8 Acceptance checks 2.9 Putting it online 2.10 Save the spec 3 Spec for an NLP app: word clouds 3.1 What an NLP app does 3.2 A Python app in the notebook 3.3 A JavaScript app in the browser 3.4 Your turn Slides Notebook 1 What is an app? 1.1 A flexible definition In this course, an app is any program that takes some input, does a job for someone, and produces output they can use — without them having to read or change the code. That makes “app” a wide term. What differs is how the input arrives, where the program runs, and who uses it: App Input Job Output Who runs it Notebook cell with settings at the top a few variables you edit analyse a dataset tables, charts, a report file you, in Colab Command-line script a file name, options convert or clean files new files you, in a terminal Spreadsheet with formulas numbers typed into cells calculate totals, charts anyone with Excel Interactive dashboard (Shiny) menus, sliders filter and summarise data live charts and tables anyone with the link Local web page (HTML + JavaScript) clicks, typed text store and show information an updated page anyone who opens the file Hosted web app forms, accounts a service pages, emails, downloads the public Chatbot (custom GPT, Gemini Gem) questions in plain language answer with set instructions text, files anyone with access Mobile app taps, camera, location everything above, on a phone screens, notifications app-store users We start at the top of the table, with an app that is a single notebook cell, and work our way down. Take the local web page row as an example: a single HTML file that runs in the browser, with nothing to install. Ask Gemini for ideas of what such an app can be: ideas_prompt = \"\"\" List 10 suggestions for simple single-page web apps. Each one should be visually impressive, somewhat interactive, and useful. \"\"\" A concrete example from statistics: an app that shows what correlation looks like. Ask Gemini to write it, save the answer as an.html file, and open it in your browser: scatter_prompt = \"\"\" Please generate code for an interactive single-page app that uses Observable JS to plot two random normally distributed variables against each other as a scatter plot with a trend line. Provide a slider that updates the strength of the association, and buttons for a positive vs a negative relationship. \"\"\" The same idea can also run on a server. Here it is as a Shiny app, hosted online: Interactive bivariate normal scatter plot. 1.2 A toy app prompt This prompt asks Gemini for a tiny report app: one Colab cell with its settings at the top. Paste the prompt into Gemini, then paste the code it returns into a new cell in Colab. The cell below only stores the text. prompt = \"\"\" Write one Google Colab Python code cell that works as a small report app. Settings at the top of the cell, as plain variables the user can edit: - DATA_URL = \"https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv\" - OUTCOME = \"DV_INDEX\", GROUP = \"IV_CAT_GROUP\", PREFIX = \"app\" The cell should: 1. load the tab-separated file from DATA_URL with pandas 2. save a summary table (count, mean, SD, min, quartiles, max) of all columns whose name contains INDEX to PREFIX-summary.csv 3. save one histogram per index as PREFIX-hist-<index>.png 4. save a box plot of OUTCOME by GROUP as PREFIX-groups.png 5. save one self-contained HTML report, PREFIX-report.html, with the summary table and all charts embedded as base64 images, so it is a single file that opens anywhere 6. print the name and size of every file it wrote Write all files to the current working folder. Use only pandas and matplotlib. Return only the code, with short comments. \"\"\" 1.3 The generated app A version of the code the model returns. Run it in the session notebook in Colab, then open the Files panel (the folder icon on the left) to see the six new files. Right-click a file to download it; open app-report.html in your browser. # ---- Settings: change these and run the cell again ---- DATA_URL = \"https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv\" OUTCOME = \"DV_INDEX\" GROUP = \"IV_CAT_GROUP\" PREFIX = \"app\" import base64 from io import BytesIO from pathlib import Path import matplotlib.pyplot as plt import pandas as pd # 1. Load the data df = pd.read_csv(DATA_URL, sep = \" \\t \") indices = [c for c in df.columns if \"INDEX\" in c] written = [] def save_figure(fig, name): \"\"\"Save a figure as PNG and return it base64-encoded for the HTML report.\"\"\" path = Path(f\" { PREFIX } - { name }.png\") fig.savefig(path, dpi = 110, bbox_inches = \"tight\") buffer = BytesIO() fig.savefig(buffer, format = \"png\", dpi = 110, bbox_inches = \"tight\") plt.close(fig) written.append(path) return base64.b64encode(buffer.getvalue()).decode() # 2. Summary table of the indices summary = df[indices].describe().T. round (2) summary_path = Path(f\" { PREFIX } -summary.csv\") summary.to_csv(summary_path) written.append(summary_path) # 3. One histogram per index images = {} for col in indices: fig, ax = plt.subplots(figsize = (4, 3)) ax.hist(df[col], bins = 9, color = \"#2f9e44\", edgecolor = \"white\") ax.set_title(col) images[f\"Distribution of { col } \"] = save_figure(fig, f\"hist- { col. lower() } \") # 4. Outcome by group fig, ax = plt.subplots(figsize = (4, 3)) df.boxplot(column = OUTCOME, by = GROUP, ax = ax, grid = False) ax.set_title(f\" { OUTCOME } by { GROUP } \") fig.suptitle(\"\") images[f\" { OUTCOME } by { GROUP } \"] = save_figure(fig, \"groups\") # 5. One self-contained HTML report with the table and all charts embedded figures = \" \\n \".join(f'<h2> { title } </h2><img src=\"data:image/png;base64, { data } \" alt=\" { title } \">' for title, data in images.items()) html = f\"\"\"<!doctype html> <html><head><meta charset=\"utf-8\"><title>Report: { OUTCOME } </title> <style>body {{ font-family: Arial, sans-serif; max-width: 800px; margin: 2em auto; }} table {{ border-collapse: collapse; }} td, th {{ padding: 4px 8px; border: 1px solid #ccc; }} </style> </head><body> <h1>Report: { OUTCOME } </h1> <p> { len (df) } rows, { df. shape[1] } columns, source: { DATA_URL } </p> <h2>Summary of the indices</h2> { summary. to_html() } { figures } </body></html>\"\"\" report_path = Path(f\" { PREFIX } -report.html\") report_path.write_text(html, encoding = \"utf-8\") written.append(report_path) # 6. Tell the user what was made print (f\"Wrote { len (written) } files:\") for path in written: print (f\" { path. name:28} { path. stat(). st_size:>8,} bytes\") summary Wrote 6 files: app-summary.csv 176 bytes app-hist-iv_index1.png 9,357 bytes app-hist-iv_index2.png 10,087 bytes app-hist-dv_index.png 10,111 bytes app-groups.png 12,931 bytes app-report.html 58,450 bytes count mean std min 25% 50% 75% max IV_INDEX1 100.0 3.07 1.11 1.0 2.38 3.00 4.0 5.0 IV_INDEX2 100.0 2.81 1.15 1.0 2.00 2.75 3.5 5.0 DV_INDEX 100.0 2.56 1.09 1.0 1.88 2.50 3.5 5.0 Changing a setting at the top — say OUTCOME = \"IV_INDEX1\" or PREFIX = \"run2\" — and running the cell again is using the app: same job, new input, new output, no code reading required. 2 Spec for a Shiny data app 2.1 How a spec works A prompt is a one-off request. A specification (spec) is a document you keep: a plain-text file that describes what an app should do and how to check it, written so that both people and AI can follow it. Writing specs as files — specifications as code — lets them do three jobs at once: Context: the AI reads the spec before it writes anything, so it knows the data, the users and the constraints instead of guessing. Instructions: prompts can stay short — “implement section 3 of SPEC.md” — because the details live in the spec. Blueprint: an AI agent such as Google Antigravity can plan the work from the spec, build the app step by step, and test it against the acceptance checks. The workflow: run the spec cells below in Colab to create SPEC.md, download it, put it in an empty folder, open that folder in Antigravity, and ask the agent: “Read SPEC.md and build the app step by step. Check every acceptance criterion and report the result.” When something is wrong, change the spec and ask again — the spec stays the single source of truth. The cells below only store text; on this page nothing is run. 2.2 Specs and PRDs In product teams, a similar document is called a product requirements document (PRD). It states the problem, who the users are, what the product must do, and how success is measured — but leaves the technical how to the developers. Our specs are small PRDs with some technical detail added (data, packages, run commands), so an AI agent can build directly from them. If you ask an AI to “write a PRD” for your app idea, you get a good first draft of a spec. 2.3 Purpose and users Start with why and for whom. One clear sentence of purpose keeps the agent from adding features nobody asked for. spec = \"\"\" # SPEC: TPB explorer (Shiny for Python) ## 1. Purpose and users Build an interactive web app that lets students explore a synthetic Theory of Planned Behavior (TPB) survey experiment: how attitude (ATT), subjective norm (SN) and perceived behavioral control (PBC) relate to children's intention (BI) to learn an instrument, and whether a peer testimonial (treatment) raised that intention. Users: course participants with no coding background. They use the app in a browser, mainly on a laptop, to look at distributions, relationships and the experiment result. \"\"\" 2.4 Data Describe the data precisely: where it is, every column and its role. The agent then writes correct loading code on the first try, and the checks at the end tell it whether it did. spec += \"\"\" ## 2. Data Load this tab-separated file at start-up (100 rows, no missing values): https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-tpb-exp-n100.tsv Columns: - Background (text): age_group (\"10 years\" to \"13 years\"), grade_level (\"Grade 4\" to \"Grade 6\"), gender (\"Girl\", \"Boy\", \"Non-binary\", \"Prefer not to say\") - Experiment (text): experimental_condition (\"control\" or \"treatment\") - Items (whole numbers 1-5, 1 = strongly disagree, 5 = strongly agree), three per scale: - ATT: att_fun_exciting, att_valuable_use_of_time, att_feel_good_about_self - SN: sn_parent_guardian_approval, sn_friend_approval, sn_teacher_encouragement - PBC: pbc_confident_can_learn, pbc_enough_spare_time, pbc_instrument_access - BI: bi_plan_next_6_months, bi_try_best_to_learn_soon, bi_want_to_start_school_year - Indices (decimals 1-5): ATT_index, SN_index, PBC_index, BI_index = mean of the three items of each scale. Recompute them from the items after loading. If loading fails or the file does not have 100 rows, show a clear error message in the app instead of crashing. \"\"\" 2.5 Features and layout Describe what the user sees and can do, screen by screen. Numbered requirements give the agent a to-do list and give you something concrete to check. spec += \"\"\" ## 3. Features and layout Page title \"TPB explorer\". A sidebar on the left, tabs on the right. Sidebar filters (all selected by default, apply to every tab): - F1 experimental condition (checkboxes) - F2 gender, F3 grade level, F4 age group (checkbox groups) - F5 a line showing \"n = <number of rows after filtering>\" - F6 a button that downloads the filtered rows as CSV Tabs: - T1 Overview: table of mean and SD of the four indices, overall and by condition - T2 Distributions: dropdown to pick one index; histogram with a density curve - T3 Relationships: dropdowns for x and y index (default PBC_index and BI_index); scatter plot with a fitted line; Pearson r and p shown above the plot - T4 Experiment: box plot of BI_index by condition with the individual points; Welch t-test (t, p) and Cohen's d for treatment vs control shown in a small table \"\"\" 2.6 Behaviour Say how the app should behave, not just what it shows: what reacts to what, and what happens in edge cases such as an empty selection. spec += \"\"\" ## 4. Behaviour - Every table, plot and number updates immediately when a filter changes. - If the filters leave fewer than 5 rows, show \"Too few rows for this view\" instead of plots and tests. - If only one condition is selected, T4 shows \"Select both conditions to compare\" instead of the test. - Round numbers to 2 decimals; show p-values below.001 as \"<.001\". - Use one colour palette across all plots; label every axis with the full construct name (for example \"Behavioral intention (BI)\"). \"\"\" 2.7 Technical constraints Constraints decide how it is built. Fixing the framework, files and libraries keeps the result small, runnable and easy to put online. spec += \"\"\" ## 5. Technical constraints - Shiny for Python, core API (from shiny import App, ui, render, reactive). - Libraries: shiny, pandas, matplotlib, scipy. Nothing else. - Files: app.py (the whole app), requirements.txt (pinned versions), README.md (how to run locally and how to deploy, see section 7). - No database, no login, no files written at run time. - Runs locally with: shiny run app.py and opens at http://127.0.0.1:8000 \"\"\" 2.8 Acceptance checks The checks are the definition of done. Each one is a statement that is either true or false, so the agent can test its own work — and so can you. spec += \"\"\" ## 6. Acceptance checks - A1 With all filters selected, F5 shows n = 100. - A2 Unticking \"treatment\" shows n = 50, and T4 shows \"Select both conditions to compare\" instead of the test. - A3 The means in T1 equal pandas df.groupby(\"experimental_condition\")[indices].mean() rounded to 2 decimals. - A4 Changing the T3 dropdowns updates the plot and r without reloading the page. - A5 The downloaded CSV has the same rows as F5 reports. - A6 shiny run app.py starts without errors or warnings in a fresh virtual environment created from requirements.txt. \"\"\" 2.9 Putting it online A spec can also describe how the app goes live, so the agent prepares the right files. Three realistic routes, from easiest to most independent: Posit Connect Cloud publishes straight from a GitHub repository and updates the app when you push changes. shinyapps.io uploads from your computer with a command-line tool. Shinylive turns the app into a static website that runs entirely in the visitor’s browser — it can be hosted on Netlify or GitHub Pages, like this course site. spec += \"\"\" ## 7. Putting it online Write these steps into README.md and make sure the files support them. Option A - Posit Connect Cloud (recommended): 1. Create a public GitHub repository with app.py, requirements.txt and README.md. 2. Sign in at https://connect.posit.cloud with the GitHub account. 3. Choose Publish, then Shiny, pick the repository, the branch (main) and app.py as the primary file, and publish. 4. Share the public URL; every push to main republishes the app. Option B - shinyapps.io: 1. Create an account at https://www.shinyapps.io and copy a token from the dashboard. 2. In a terminal: pip install rsconnect-python rsconnect add --account <account> --name <account> --token <token> --secret <secret> rsconnect deploy shiny. --name <account> --title tpb-explorer Option C - Shinylive (static site, no server): 1. In a terminal: pip install shinylive shinylive export. site 2. Upload the site folder to Netlify or GitHub Pages. The app then runs in the visitor's browser; all libraries must be available in Pyodide (shiny, pandas, matplotlib and scipy are). Never put passwords or tokens in the repository. The data are synthetic, so the app can be public. \"\"\" 2.10 Save the spec The last cell joins all parts into one file. In Colab, run all spec cells, then download SPEC.md from the Files panel and give it to Antigravity. with open (\"SPEC.md\", \"w\") as f: f.write(spec) print (spec) 3 Spec for an NLP app: word clouds 3.1 What an NLP app does Natural language processing (NLP) apps turn text into something you can see and count. A classic example is the word cloud: the more often a word occurs, the bigger it is drawn. Before counting, the text is normalised: cleaned, split into words (tokenised), and each word reduced to its dictionary form (lemmatised, so “runs” and “running” both count as “run”), with common stop words such as “the” and “and” removed. The same idea can be built in two ways, and below is a spec for each: a Python app inside the notebook, built with Gradio — a package that shows a small web interface (dropdowns, images, tables) right below a cell; a single web page that runs in any browser, written in JavaScript. 3.2 A Python app in the notebook This app cleans and tokenises text files with spaCy, draws a word cloud for each file, and scores the sentiment of every sentence. spaCy has no sentiment model of its own, so the spec names one: NLTK’s VADER, which works well on short English sentences. nlp_spec = \"\"\" # SPEC: Text explorer (word cloud and sentence sentiment) ## 1. Purpose Explore a folder of English text files: which words dominate each text, and how positive or negative each sentence is. ## 2. Data - Read every *.txt file in the current working folder (UTF-8). - If there are none, first create three short sample files (a review, a news item, a diary entry; 5-8 sentences each) so the app always has something to show. ## 3. Processing - spaCy with en_core_web_sm: split each text into sentences; tokenise and lemmatise; lowercase the lemmas and keep alphabetic ones; drop stop words, punctuation, numbers and spaces. - Word cloud (wordcloud package) from the cleaned lemmas, per file and for all files. - Sentiment per sentence with NLTK VADER (SentimentIntensityAnalyzer): the compound score from -1 to 1, and a label: positive >= 0.05, negative <= -0.05, else neutral. ## 4. Interface (Gradio, shown in the notebook) - A dropdown with \"All files\" and each file name. - The word cloud image for the selection. - A table: file, sentence number, sentence, compound score, label. - A short summary line: number of sentences and share positive / neutral / negative. - A button to download the table as CSV. ## 5. Constraints - One notebook cell that installs what is missing, then builds and launches the app: %pip install spacy wordcloud nltk gradio python -m spacy download en_core_web_sm - Download the VADER lexicon with nltk.download(\"vader_lexicon\"). - Run with demo.launch() so the interface appears below the cell. ## 6. Acceptance checks - A1 With no text files present, three sample files are created and shown. - A2 Each word cloud contains no stop words such as \"the\", \"and\" or \"is\". - A3 The table has one row per sentence; scores lie between -1 and 1. - A4 Choosing a file updates the word cloud, table and summary. - A5 The downloaded CSV has the same rows as the table. - A6 \"The\" and \"the\" count as one word (and are dropped as a stop word). \"\"\" with open (\"NLP-APP-SPEC.md\", \"w\") as f: f.write(nlp_spec) nlp_prompt = \"\"\" Read NLP-APP-SPEC.md. Plan first, then write the app as one Jupyter notebook cell in text_explorer.ipynb, run it, and check every acceptance criterion. \"\"\" 3.3 A JavaScript app in the browser The second app is one HTML file: paste a text, click Submit, and the word cloud appears next to it. All the work happens in the browser, in JavaScript: the NLP steps with wink-nlp, the layout with d3-cloud. It needs an internet connection to load these libraries, but no Python and no install — just double-click the file. For a more advanced version of the same idea, see winkjs’ context-aware word cloud. web_spec = \"\"\" # SPEC: Word cloud (single-page web app) ## 1. Purpose Paste any English text and see its most important words as a word cloud, in the browser, without Python. ## 2. Files and libraries - Exactly one file, wordcloud.html, with the CSS and JavaScript inside it. No build step, no server. - Load the libraries as ES modules from the jsdelivr CDN, with pinned major ver"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/03-app-building.html",
   "path": "coding/skill-school/sessions/03-app-building.html",
   "title": "Session 3 · de-code app building",
   "description": "Parts: What is an app?; Spec for a Shiny data app; Spec for an NLP app: word clouds.",
   "section": "coding",
   "type": "page",
   "stack": "quarto",
   "headings": [
    "Topics",
    "1 What is an app?",
    "1.1 A flexible definition",
    "1.2 A toy app prompt",
    "1.3 The generated app",
    "2 Spec for a Shiny data app",
    "2.1 How a spec works",
    "2.2 Specs and PRDs",
    "2.3 Purpose and users",
    "2.4 Data",
    "2.5 Features and layout",
    "2.6 Behaviour",
    "2.7 Technical constraints",
    "2.8 Acceptance checks",
    "2.9 Putting it online",
    "2.10 Save the spec",
    "3 Spec for an NLP app: word clouds",
    "3.1 What an NLP app does",
    "3.2 A Python app in the notebook",
    "3.3 A JavaScript app in the browser",
    "3.4 Your turn"
   ],
   "words": 3806,
   "updated": "2026-10-09",
   "text": "Topics 1 What is an app? 1.1 A flexible definition 1.2 A toy app prompt 1.3 The generated app 2 Spec for a Shiny data app 2.1 How a spec works 2.2 Specs and PRDs 2.3 Purpose and users 2.4 Data 2.5 Features and layout 2.6 Behaviour 2.7 Technical constraints 2.8 Acceptance checks 2.9 Putting it online 2.10 Save the spec 3 Spec for an NLP app: word clouds 3.1 What an NLP app does 3.2 A Python app in the notebook 3.3 A JavaScript app in the browser 3.4 Your turn Slides Notebook 1 What is an app? 1.1 A flexible definition In this course, an app is any program that takes some input, does a job for someone, and produces output they can use — without them having to read or change the code. That makes “app” a wide term. What differs is how the input arrives, where the program runs, and who uses it: App Input Job Output Who runs it Notebook cell with settings at the top a few variables you edit analyse a dataset tables, charts, a report file you, in Colab Command-line script a file name, options convert or clean files new files you, in a terminal Spreadsheet with formulas numbers typed into cells calculate totals, charts anyone with Excel Interactive dashboard (Shiny) menus, sliders filter and summarise data live charts and tables anyone with the link Local web page (HTML + JavaScript) clicks, typed text store and show information an updated page anyone who opens the file Hosted web app forms, accounts a service pages, emails, downloads the public Chatbot (custom GPT, Gemini Gem) questions in plain language answer with set instructions text, files anyone with access Mobile app taps, camera, location everything above, on a phone screens, notifications app-store users We start at the top of the table, with an app that is a single notebook cell, and work our way down. Take the local web page row as an example: a single HTML file that runs in the browser, with nothing to install. Ask Gemini for ideas of what such an app can be: ideas_prompt = \"\"\" List 10 suggestions for simple single-page web apps. Each one should be visually impressive, somewhat interactive, and useful. \"\"\" A concrete example from statistics: an app that shows what correlation looks like. Ask Gemini to write it, save the answer as an.html file, and open it in your browser: scatter_prompt = \"\"\" Please generate code for an interactive single-page app that uses Observable JS to plot two random normally distributed variables against each other as a scatter plot with a trend line. Provide a slider that updates the strength of the association, and buttons for a positive vs a negative relationship. \"\"\" The same idea can also run on a server. Here it is as a Shiny app, hosted online: Interactive bivariate normal scatter plot. 1.2 A toy app prompt This prompt asks Gemini for a tiny report app: one Colab cell with its settings at the top. Paste the prompt into Gemini, then paste the code it returns into a new cell in Colab. The cell below only stores the text. prompt = \"\"\" Write one Google Colab Python code cell that works as a small report app. Settings at the top of the cell, as plain variables the user can edit: - DATA_URL = \"https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv\" - OUTCOME = \"DV_INDEX\", GROUP = \"IV_CAT_GROUP\", PREFIX = \"app\" The cell should: 1. load the tab-separated file from DATA_URL with pandas 2. save a summary table (count, mean, SD, min, quartiles, max) of all columns whose name contains INDEX to PREFIX-summary.csv 3. save one histogram per index as PREFIX-hist-<index>.png 4. save a box plot of OUTCOME by GROUP as PREFIX-groups.png 5. save one self-contained HTML report, PREFIX-report.html, with the summary table and all charts embedded as base64 images, so it is a single file that opens anywhere 6. print the name and size of every file it wrote Write all files to the current working folder. Use only pandas and matplotlib. Return only the code, with short comments. \"\"\" 1.3 The generated app A version of the code the model returns. Run it in the session notebook in Colab, then open the Files panel (the folder icon on the left) to see the six new files. Right-click a file to download it; open app-report.html in your browser. # ---- Settings: change these and run the cell again ---- DATA_URL = \"https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv\" OUTCOME = \"DV_INDEX\" GROUP = \"IV_CAT_GROUP\" PREFIX = \"app\" import base64 from io import BytesIO from pathlib import Path import matplotlib.pyplot as plt import pandas as pd # 1. Load the data df = pd.read_csv(DATA_URL, sep = \" \\t \") indices = [c for c in df.columns if \"INDEX\" in c] written = [] def save_figure(fig, name): \"\"\"Save a figure as PNG and return it base64-encoded for the HTML report.\"\"\" path = Path(f\" { PREFIX } - { name }.png\") fig.savefig(path, dpi = 110, bbox_inches = \"tight\") buffer = BytesIO() fig.savefig(buffer, format = \"png\", dpi = 110, bbox_inches = \"tight\") plt.close(fig) written.append(path) return base64.b64encode(buffer.getvalue()).decode() # 2. Summary table of the indices summary = df[indices].describe().T. round (2) summary_path = Path(f\" { PREFIX } -summary.csv\") summary.to_csv(summary_path) written.append(summary_path) # 3. One histogram per index images = {} for col in indices: fig, ax = plt.subplots(figsize = (4, 3)) ax.hist(df[col], bins = 9, color = \"#2f9e44\", edgecolor = \"white\") ax.set_title(col) images[f\"Distribution of { col } \"] = save_figure(fig, f\"hist- { col. lower() } \") # 4. Outcome by group fig, ax = plt.subplots(figsize = (4, 3)) df.boxplot(column = OUTCOME, by = GROUP, ax = ax, grid = False) ax.set_title(f\" { OUTCOME } by { GROUP } \") fig.suptitle(\"\") images[f\" { OUTCOME } by { GROUP } \"] = save_figure(fig, \"groups\") # 5. One self-contained HTML report with the table and all charts embedded figures = \" \\n \".join(f'<h2> { title } </h2><img src=\"data:image/png;base64, { data } \" alt=\" { title } \">' for title, data in images.items()) html = f\"\"\"<!doctype html> <html><head><meta charset=\"utf-8\"><title>Report: { OUTCOME } </title> <style>body {{ font-family: Arial, sans-serif; max-width: 800px; margin: 2em auto; }} table {{ border-collapse: collapse; }} td, th {{ padding: 4px 8px; border: 1px solid #ccc; }} </style> </head><body> <h1>Report: { OUTCOME } </h1> <p> { len (df) } rows, { df. shape[1] } columns, source: { DATA_URL } </p> <h2>Summary of the indices</h2> { summary. to_html() } { figures } </body></html>\"\"\" report_path = Path(f\" { PREFIX } -report.html\") report_path.write_text(html, encoding = \"utf-8\") written.append(report_path) # 6. Tell the user what was made print (f\"Wrote { len (written) } files:\") for path in written: print (f\" { path. name:28} { path. stat(). st_size:>8,} bytes\") summary Wrote 6 files: app-summary.csv 176 bytes app-hist-iv_index1.png 9,357 bytes app-hist-iv_index2.png 10,087 bytes app-hist-dv_index.png 10,111 bytes app-groups.png 12,931 bytes app-report.html 58,450 bytes count mean std min 25% 50% 75% max IV_INDEX1 100.0 3.07 1.11 1.0 2.38 3.00 4.0 5.0 IV_INDEX2 100.0 2.81 1.15 1.0 2.00 2.75 3.5 5.0 DV_INDEX 100.0 2.56 1.09 1.0 1.88 2.50 3.5 5.0 Changing a setting at the top — say OUTCOME = \"IV_INDEX1\" or PREFIX = \"run2\" — and running the cell again is using the app: same job, new input, new output, no code reading required. 2 Spec for a Shiny data app 2.1 How a spec works A prompt is a one-off request. A specification (spec) is a document you keep: a plain-text file that describes what an app should do and how to check it, written so that both people and AI can follow it. Writing specs as files — specifications as code — lets them do three jobs at once: Context: the AI reads the spec before it writes anything, so it knows the data, the users and the constraints instead of guessing. Instructions: prompts can stay short — “implement section 3 of SPEC.md” — because the details live in the spec. Blueprint: an AI agent such as Google Antigravity can plan the work from the spec, build the app step by step, and test it against the acceptance checks. The workflow: run the spec cells below in Colab to create SPEC.md, download it, put it in an empty folder, open that folder in Antigravity, and ask the agent: “Read SPEC.md and build the app step by step. Check every acceptance criterion and report the result.” When something is wrong, change the spec and ask again — the spec stays the single source of truth. The cells below only store text; on this page nothing is run. 2.2 Specs and PRDs In product teams, a similar document is called a product requirements document (PRD). It states the problem, who the users are, what the product must do, and how success is measured — but leaves the technical how to the developers. Our specs are small PRDs with some technical detail added (data, packages, run commands), so an AI agent can build directly from them. If you ask an AI to “write a PRD” for your app idea, you get a good first draft of a spec. 2.3 Purpose and users Start with why and for whom. One clear sentence of purpose keeps the agent from adding features nobody asked for. spec = \"\"\" # SPEC: TPB explorer (Shiny for Python) ## 1. Purpose and users Build an interactive web app that lets students explore a synthetic Theory of Planned Behavior (TPB) survey experiment: how attitude (ATT), subjective norm (SN) and perceived behavioral control (PBC) relate to children's intention (BI) to learn an instrument, and whether a peer testimonial (treatment) raised that intention. Users: course participants with no coding background. They use the app in a browser, mainly on a laptop, to look at distributions, relationships and the experiment result. \"\"\" 2.4 Data Describe the data precisely: where it is, every column and its role. The agent then writes correct loading code on the first try, and the checks at the end tell it whether it did. spec += \"\"\" ## 2. Data Load this tab-separated file at start-up (100 rows, no missing values): https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-tpb-exp-n100.tsv Columns: - Background (text): age_group (\"10 years\" to \"13 years\"), grade_level (\"Grade 4\" to \"Grade 6\"), gender (\"Girl\", \"Boy\", \"Non-binary\", \"Prefer not to say\") - Experiment (text): experimental_condition (\"control\" or \"treatment\") - Items (whole numbers 1-5, 1 = strongly disagree, 5 = strongly agree), three per scale: - ATT: att_fun_exciting, att_valuable_use_of_time, att_feel_good_about_self - SN: sn_parent_guardian_approval, sn_friend_approval, sn_teacher_encouragement - PBC: pbc_confident_can_learn, pbc_enough_spare_time, pbc_instrument_access - BI: bi_plan_next_6_months, bi_try_best_to_learn_soon, bi_want_to_start_school_year - Indices (decimals 1-5): ATT_index, SN_index, PBC_index, BI_index = mean of the three items of each scale. Recompute them from the items after loading. If loading fails or the file does not have 100 rows, show a clear error message in the app instead of crashing. \"\"\" 2.5 Features and layout Describe what the user sees and can do, screen by screen. Numbered requirements give the agent a to-do list and give you something concrete to check. spec += \"\"\" ## 3. Features and layout Page title \"TPB explorer\". A sidebar on the left, tabs on the right. Sidebar filters (all selected by default, apply to every tab): - F1 experimental condition (checkboxes) - F2 gender, F3 grade level, F4 age group (checkbox groups) - F5 a line showing \"n = <number of rows after filtering>\" - F6 a button that downloads the filtered rows as CSV Tabs: - T1 Overview: table of mean and SD of the four indices, overall and by condition - T2 Distributions: dropdown to pick one index; histogram with a density curve - T3 Relationships: dropdowns for x and y index (default PBC_index and BI_index); scatter plot with a fitted line; Pearson r and p shown above the plot - T4 Experiment: box plot of BI_index by condition with the individual points; Welch t-test (t, p) and Cohen's d for treatment vs control shown in a small table \"\"\" 2.6 Behaviour Say how the app should behave, not just what it shows: what reacts to what, and what happens in edge cases such as an empty selection. spec += \"\"\" ## 4. Behaviour - Every table, plot and number updates immediately when a filter changes. - If the filters leave fewer than 5 rows, show \"Too few rows for this view\" instead of plots and tests. - If only one condition is selected, T4 shows \"Select both conditions to compare\" instead of the test. - Round numbers to 2 decimals; show p-values below.001 as \"<.001\". - Use one colour palette across all plots; label every axis with the full construct name (for example \"Behavioral intention (BI)\"). \"\"\" 2.7 Technical constraints Constraints decide how it is built. Fixing the framework, files and libraries keeps the result small, runnable and easy to put online. spec += \"\"\" ## 5. Technical constraints - Shiny for Python, core API (from shiny import App, ui, render, reactive). - Libraries: shiny, pandas, matplotlib, scipy. Nothing else. - Files: app.py (the whole app), requirements.txt (pinned versions), README.md (how to run locally and how to deploy, see section 7). - No database, no login, no files written at run time. - Runs locally with: shiny run app.py and opens at http://127.0.0.1:8000 \"\"\" 2.8 Acceptance checks The checks are the definition of done. Each one is a statement that is either true or false, so the agent can test its own work — and so can you. spec += \"\"\" ## 6. Acceptance checks - A1 With all filters selected, F5 shows n = 100. - A2 Unticking \"treatment\" shows n = 50, and T4 shows \"Select both conditions to compare\" instead of the test. - A3 The means in T1 equal pandas df.groupby(\"experimental_condition\")[indices].mean() rounded to 2 decimals. - A4 Changing the T3 dropdowns updates the plot and r without reloading the page. - A5 The downloaded CSV has the same rows as F5 reports. - A6 shiny run app.py starts without errors or warnings in a fresh virtual environment created from requirements.txt. \"\"\" 2.9 Putting it online A spec can also describe how the app goes live, so the agent prepares the right files. Three realistic routes, from easiest to most independent: Posit Connect Cloud publishes straight from a GitHub repository and updates the app when you push changes. shinyapps.io uploads from your computer with a command-line tool. Shinylive turns the app into a static website that runs entirely in the visitor’s browser — it can be hosted on Netlify or GitHub Pages, like this course site. spec += \"\"\" ## 7. Putting it online Write these steps into README.md and make sure the files support them. Option A - Posit Connect Cloud (recommended): 1. Create a public GitHub repository with app.py, requirements.txt and README.md. 2. Sign in at https://connect.posit.cloud with the GitHub account. 3. Choose Publish, then Shiny, pick the repository, the branch (main) and app.py as the primary file, and publish. 4. Share the public URL; every push to main republishes the app. Option B - shinyapps.io: 1. Create an account at https://www.shinyapps.io and copy a token from the dashboard. 2. In a terminal: pip install rsconnect-python rsconnect add --account <account> --name <account> --token <token> --secret <secret> rsconnect deploy shiny. --name <account> --title tpb-explorer Option C - Shinylive (static site, no server): 1. In a terminal: pip install shinylive shinylive export. site 2. Upload the site folder to Netlify or GitHub Pages. The app then runs in the visitor's browser; all libraries must be available in Pyodide (shiny, pandas, matplotlib and scipy are). Never put passwords or tokens in the repository. The data are synthetic, so the app can be public. \"\"\" 2.10 Save the spec The last cell joins all parts into one file. In Colab, run all spec cells, then download SPEC.md from the Files panel and give it to Antigravity. with open (\"SPEC.md\", \"w\") as f: f.write(spec) print (spec) 3 Spec for an NLP app: word clouds 3.1 What an NLP app does Natural language processing (NLP) apps turn text into something you can see and count. A classic example is the word cloud: the more often a word occurs, the bigger it is drawn. Before counting, the text is normalised: cleaned, split into words (tokenised), and each word reduced to its dictionary form (lemmatised, so “runs” and “running” both count as “run”), with common stop words such as “the” and “and” removed. The same idea can be built in two ways, and below is a spec for each: a Python app inside the notebook, built with Gradio — a package that shows a small web interface (dropdowns, images, tables) right below a cell; a single web page that runs in any browser, written in JavaScript. 3.2 A Python app in the notebook This app cleans and tokenises text files with spaCy, draws a word cloud for each file, and scores the sentiment of every sentence. spaCy has no sentiment model of its own, so the spec names one: NLTK’s VADER, which works well on short English sentences. nlp_spec = \"\"\" # SPEC: Text explorer (word cloud and sentence sentiment) ## 1. Purpose Explore a folder of English text files: which words dominate each text, and how positive or negative each sentence is. ## 2. Data - Read every *.txt file in the current working folder (UTF-8). - If there are none, first create three short sample files (a review, a news item, a diary entry; 5-8 sentences each) so the app always has something to show. ## 3. Processing - spaCy with en_core_web_sm: split each text into sentences; tokenise and lemmatise; lowercase the lemmas and keep alphabetic ones; drop stop words, punctuation, numbers and spaces. - Word cloud (wordcloud package) from the cleaned lemmas, per file and for all files. - Sentiment per sentence with NLTK VADER (SentimentIntensityAnalyzer): the compound score from -1 to 1, and a label: positive >= 0.05, negative <= -0.05, else neutral. ## 4. Interface (Gradio, shown in the notebook) - A dropdown with \"All files\" and each file name. - The word cloud image for the selection. - A table: file, sentence number, sentence, compound score, label. - A short summary line: number of sentences and share positive / neutral / negative. - A button to download the table as CSV. ## 5. Constraints - One notebook cell that installs what is missing, then builds and launches the app: %pip install spacy wordcloud nltk gradio python -m spacy download en_core_web_sm - Download the VADER lexicon with nltk.download(\"vader_lexicon\"). - Run with demo.launch() so the interface appears below the cell. ## 6. Acceptance checks - A1 With no text files present, three sample files are created and shown. - A2 Each word cloud contains no stop words such as \"the\", \"and\" or \"is\". - A3 The table has one row per sentence; scores lie between -1 and 1. - A4 Choosing a file updates the word cloud, table and summary. - A5 The downloaded CSV has the same rows as the table. - A6 \"The\" and \"the\" count as one word (and are dropped as a stop word). \"\"\" with open (\"NLP-APP-SPEC.md\", \"w\") as f: f.write(nlp_spec) nlp_prompt = \"\"\" Read NLP-APP-SPEC.md. Plan first, then write the app as one Jupyter notebook cell in text_explorer.ipynb, run it, and check every acceptance criterion. \"\"\" 3.3 A JavaScript app in the browser The second app is one HTML file: paste a text, click Submit, and the word cloud appears next to it. All the work happens in the browser, in JavaScript: the NLP steps with wink-nlp, the layout with d3-cloud. It needs an internet connection to load these libraries, but no Python and no install — just double-click the file. For a more advanced version of the same idea, see winkjs’ context-aware word cloud. web_spec = \"\"\" # SPEC: Word cloud (single-page web app) ## 1. Purpose Paste any English text and see its most important words as a word cloud, in the browser, without Python. ## 2. Files and libraries - Exactly one file, wordcloud.html, with the CSS and JavaScript inside it. No build step, no server. - Load the libraries as ES modules from the jsdelivr CDN, with pinned major ver"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/04-agentic-coding-slides.html",
   "path": "coding/skill-school/sessions/04-agentic-coding-slides.html",
   "title": "Session 4 · de-code agentic coding",
   "description": "Parts: Safety first!; Specs and agentic AI; Agent basics.",
   "section": "coding",
   "type": "slides",
   "stack": "quarto",
   "headings": [
    "Topics",
    "Recap: session 3",
    "From idea to spec",
    "1 Safety first!",
    "1.1 From chat to agents",
    "1.2 Common agent tools",
    "1.3 AGENTS.md: rules the agent reads first",
    "1.4 Guardrails and slash commands",
    "1.5 Models and tokens",
    "2 Specs and agentic AI",
    "2.1 Agentic coding tools",
    "2.2 Create a project",
    "2.3 The spec loop",
    "2.4 Iteration 1: build from a finished spec",
    "2.5 Iteration 2: change the spec",
    "2.6 Iteration 3: an app that saves data",
    "2.7 Iteration 4: a notebook app with packages",
    "2.8 Your turn",
    "3 Agent basics",
    "3.1 Brain, loop and tools",
    "3.2 Tools are ordinary functions",
    "3.3 The loop in 30 lines",
    "3.4 Agents at work: one agent, then a team",
    "3.5 Design your own agent, and going further"
   ],
   "words": 6752,
   "updated": "2026-10-08",
   "text": "Topics Recap: session 3 From idea to spec 1 Safety first! 1.1 From chat to agents 1.2 Common agent tools 1.3 AGENTS.md: rules the agent reads first 1.4 Guardrails and slash commands 1.5 Models and tokens 2 Specs and agentic AI 2.1 Agentic coding tools 2.2 Create a project 2.3 The spec loop 2.4 Iteration 1: build from a finished spec 2.5 Iteration 2: change the spec 2.6 Iteration 3: an app that saves data 2.7 Iteration 4: a notebook app with packages 2.8 Your turn 3 Agent basics 3.1 Brain, loop and tools 3.2 Tools are ordinary functions 3.3 The loop in 30 lines 3.4 Agents at work: one agent, then a team 3.5 Design your own agent, and going further Slides Notebook Recap: session 3 Yesterday we described apps in plain language, turned the descriptions into specs, and let Gemini write the code. Today an AI agent takes over that work — and we look at how agents work inside. From idea to spec The specs and apps from the course are collected in the GitHub repository cca-cce/osm-edu. The word-cloud app started as an idea in two sentences: idea_prompt = \"\"\" Make a single-page web app where I can paste a text and click Submit to see its most important words as a word cloud. Clean the text first: lowercase it, split it into words, reduce each word to its base form, and leave out common words like \"the\" and \"and\". \"\"\" Gemini turned that idea into a working page: Word Cloud Generator. From the same idea we then wrote a fuller spec, NLP-WEB-SPEC.md, which pins down the layout, the libraries, the processing steps and the acceptance checks. In section 2.4 an agent builds the app from that spec. 1 Safety first! 1.1 From chat to agents A language model such as Gemini works by predicting the next word, over and over, based on everything written so far. In a chat, that produces an answer — but only text: you copy the code, run it, and paste back the result. An AI agent adds two things: Tools — functions the model can call to act outside the chat: read and write files, search a folder, run a command in a terminal, look something up on the web. A loop — the agent plans a step, calls a tool, reads the result, and decides the next step, until the task is done or it needs your input. That makes agents powerful: you describe the goal, and the agent does the work in a folder on your computer. It also makes them risky: a tool that can write a file can overwrite one, and a tool that can run a command can delete things. So we start with safety. 1.2 Common agent tools Most coding agents — Antigravity included — offer a similar set of tools. The last column is a rough guide to how much damage a mistake could do. Tool What it does Example Risk Read file Reads the contents of a file read NLP-WEB-SPEC.md low List / find files Lists folders or finds files by name find all *.csv files low Search in files Finds text inside files where is DV_INDEX used? low Create / write file Creates a new file or replaces one write app.py medium — can overwrite Edit file Changes part of an existing file rename a variable in app.py medium Run terminal command Runs a command in a shell quarto render report.qmd high — can do anything you can Web search Searches the internet “Gradio slider example” low — but results can be wrong Fetch web page Downloads a page or file read a library’s documentation low–medium Ask the user Pauses and asks you a question “Which column is the outcome?” none — this is a good sign Plan / to-do list Writes and updates its own task list 1. load data 2. describe … none Reading is safe; writing, editing and running commands are where you want guardrails. 1.3 AGENTS.md: rules the agent reads first An AGENTS.md file is a plain Markdown file of standing instructions. The agent reads it at the start of every conversation, before your prompt, so the rules apply without you repeating them. Put one in a project folder for that project; Antigravity also reads global rules from ~/.gemini/AGENTS.md (or GEMINI.md) for all your projects. Here is a real example, used while building this course. It stores the text; save it as AGENTS.md in your project folder. agents_md = \"\"\" ## Local Python Environment This repository uses the Python virtual environment: ~/lib/python/uv-osm --- ### Environment Activation When running any Python-related command (python, pytest, quarto render with python, etc.), ALWAYS prefix the command with: source ~/lib/python/uv-osm/bin/activate && <command> If multiple commands are needed, prefer a single bash -lc invocation that activates once and runs all steps. --- ### Package Management Policy (IMPORTANT) This environment uses **uv** for dependency management. DO NOT install, upgrade, or remove any Python packages without explicitly asking first. If a dependency is required: 1. Explain why the package is needed. 2. Confirm with the user. 3. Install it using: source ~/lib/python/uv-osm/bin/activate && uv pip install <package> Rules: - Prefer `uv pip install` over `pip install`. - Never use plain `pip install`. - Never install packages globally. - Never modify requirements files or pyproject.toml without confirmation. - If a package is missing, check first before proposing installation. --- ### File System Safety Policy (IMPORTANT) You may read and inspect files anywhere. You may create, modify, or delete files ONLY inside: /tmp/ ~/tmp/ This includes any subdirectory under /tmp/ or ~/tmp/ (e.g., /tmp/project/, /tmp/test/output.txt, ~/tmp/project/). You must NEVER modify files outside /tmp/ or ~/tmp/ without explicit confirmation. If changes to project files are required: 1. Write the proposed version to /tmp/ or ~/tmp/. 2. Show or explain the changes. 3. Ask for approval before modifying the original file. Treat everything outside /tmp/ and ~/tmp/ as read-only unless explicitly approved. \"\"\" with open (\"AGENTS.md\", \"w\") as f: f.write(agents_md) The file has three policies, each closing a typical risk: Environment: always use one specific Python environment, so the agent does not run code with the wrong setup. Packages: never install or remove software without asking first — installs change your computer beyond the project. File system: read anything, but write only in scratch folders; changes to real files are proposed first and need your approval. Note the style: short, direct, with the important parts marked IMPORTANT and concrete examples. Write rules the way you would brief a new colleague. 1.4 Guardrails and slash commands Rules are one layer of safety. Combine them with these habits: Approve actions. By default the agent asks before writing files or running commands. Keep it that way; never start it with --dangerously-skip-permissions. Plan first with /plan (or agy --mode plan): the agent only investigates and proposes until you approve. Use the sandbox (agy --sandbox) to limit what commands can reach. Work in a copy of your data, keep checkpoints (git, or /rewind to go back and /diff to see what changed), and keep secrets out of the project folder. # Start the CLI agent in a project folder, in plan mode, inside the sandbox! cd ~/ projects / wordcloud - app && agy -- mode plan -- sandbox Commands that start with / control the agent itself instead of being sent as a prompt. Ten useful ones: Command What it does /help Lists commands and keyboard shortcuts /plan Plan mode: investigate and propose, change nothing yet /grill-me The agent interviews you about your idea, one question at a time /model Shows or switches the model (/model <name>) /effort Sets how hard the model thinks (low to max) /context Shows what fills the context window /usage Shows token use and remaining quota /diff Shows the changes the agent made /rewind Goes back to an earlier point, undoing changes /resume Continues an earlier conversation /grill-me is especially useful before building an app: instead of guessing what you mean, the agent asks question after question — who uses the app, which data, what counts as done — until the idea is clear. Combine it with plan mode, and end by asking for a spec: grill_prompt = \"\"\" /plan /grill-me I want a small app that shows word clouds and sentence sentiment for the text files in this folder. When you have no more questions, write the result as APP-SPEC.md with purpose, data, features, constraints and acceptance checks. \"\"\" 1.5 Models and tokens An agent can run on different models. The trade-off is always speed and cost against capability: Model family Good for Note Gemini Flash (low / medium / high) everyday tasks, quick edits, most course work fast and cheap; start here Gemini Pro harder problems, bigger plans, tricky bugs slower, uses more quota Claude (Sonnet, Opus) a second opinion, long careful reasoning also available in Antigravity GPT-OSS an open-weight alternative useful for comparison The effort level (low to max) sets how long the model thinks before acting. Switch with /model and /effort, ask another model once with /model <name> <prompt>, and list what your account can use with agy models. Models read and write tokens — pieces of words, roughly ¾ of a word each. Everything the agent sees counts: your prompt, AGENTS.md, every file it reads, every command output and its own replies. All of it must fit in the context window, the model’s working memory; when it fills up, the agent compacts older parts into a summary and details can get lost. Check usage with /context, /usage and /quota. Point the agent to the files it needs instead of letting it read everything. Keep AGENTS.md and specs short, and start a new conversation for a new task. 2 Specs and agentic AI 2.1 Agentic coding tools Every large AI maker now offers a coding agent: a model with tools and a loop that works on the files in a project folder (section 1.1). They differ in models, prices and interfaces, but they work the same way — and they all follow a good spec and an AGENTS.md: Maker Agent Where it runs Google Antigravity, Gemini CLI desktop app, code editor, terminal Anthropic Claude Code terminal, code editors, desktop and web OpenAI Codex terminal, code editors, cloud GitHub (Microsoft) Copilot agent mode VS Code and GitHub Anysphere Cursor its own code editor In this course we use Google Antigravity, which works with a Google account. It puts the same agent behind three interfaces, all downloaded from antigravity.google. Product What you see Suits Start it with Antigravity app A desktop app for managing agents, plans and results beginners; working without reading code the app icon Antigravity IDE A code editor with the agent built in reviewing code and edits closely the app icon, or antigravity-ide Antigravity CLI The agent in a terminal window quick tasks, scripts, remote computers agy The app is an agent manager: you describe the task and follow the agent’s plan, its steps and its results (artifacts) without opening a code editor — the most beginner-friendly start. The IDE is a code editor in the style of Visual Studio Code, with the agent in a side panel. You see every edit in context and can accept or reject it line by line. The CLI, agy, runs the same agent in a terminal: quick to start, works on remote computers over SSH, and runs single prompts from scripts. # Interactive session in the current folder! agy # Safer starts: plan mode, sandboxed terminal, a chosen model and effort! agy -- mode plan -- sandbox -- model gemini - 3.1 - pro - high -- effort high # One prompt, no conversation: prints the answer and exits! agy - p \"Summarise NLP-WEB-SPEC.md in three bullet points\" # Continue the most recent conversation, list available models, update the CLI! agy - c! agy models! agy update The commands are written with! so they could run from a notebook; in a normal terminal, leave the! out. In Colab they do not work — the CLI runs on your own computer. 2.2 Create a project Agents work in a project folder (the workspace). Everything the agent may touch lives there, so make a fresh one for each app. Every iteration below uses the same layout: my-app/ ├── AGENTS.md rules: environment, packages, where it may write └── <APP>-SPEC.md the task: what to build and how to check it Create an empty folder named after the app, for example wordcloud-app. Save AGENTS.md (section 1.3) and the app’s spec in it. Open the folder in the Antigravity app or IDE and confirm that you trust it — or open a terminal in the folder and run agy. The agent reads both files before it starts, so your prompts can stay short. 2.3 The spec loop A useful app spec has the same parts as in session 3, kept short: purpose, data, features, constraints and acceptance checks. With an agent, a spec is not written once — it is the thing you keep improving: Write or update the spec. Ask the agent for a plan (/plan) and read it. Approve the plan; the agent builds. Check the result against the acceptance checks — the agent first, then you. If something is wrong or missing, change the spec, not the code, and go back to step 2. We go round this loop four times, with one new thing to learn each time: Iteration App Runs in New this time 1 Word cloud the browser, one file an agent builds and tests from a finished spec 2 Word cloud, extended the browser, one file changing a spec and reviewing the change 3 Course notes the browser, three files a bigger spec, and data that is saved 4 Edge detector a Jupyter notebook packages to install; an interface inside the notebook The specs are stored in cells; run them in Colab to save each one as a file for the agent. 2.4 Iteration 1: build from a finished spec In session 3 you gave this spec to Gemini and copied its code into a file yourself. Now an agent does the whole job, from the same spec: Gemini chat (session 3) Antigravity agent (session 4) Writes wordcloud.html you copy the code into a file the agent creates the file Opens and tests it you the agent, against the acceptance checks Fixes errors you paste the error back into the chat the agent reads the error and edits the file Your role copy, paste, check, report back approve the plan, review the result This is the same specification as in session 3. If you saved NLP-WEB-SPEC.md then, copy it into the project folder; otherwise run the cell in Colab, download the file, and put it there. web_spec = \"\"\" # SPEC: Word cloud (single-page web app) ## 1. Purpose Paste any English text and see its most important words as a word cloud, in the browser, without Python. ## 2. Files and libraries - Exactly one file, wordcloud.html, with the CSS and JavaScript inside it. No build step, no server. - Load the libraries as ES modules from the jsdelivr CDN, with pinned major versions: wink-nlp@2 with wink-eng-lite-web-model@1 (NLP), d3@7 and d3-cloud@1 (word cloud). - Must work when wordcloud.html is opened directly from the folder (a file:// address) in current Chrome, Firefox, Edge and Safari. An internet connection is needed for the libraries. ## 3. Layout - Wide screens (700 px and wider): two columns. Left: a labelled text area and a Submit button. Right: the word cloud. - Narrow screens (below 700 px): one column, text area and button on top, word cloud below. - The text area starts with a short sample paragraph, so Submit works right away. ## 4. Processing (when Submit is clicked) 1. Read: take the text from the text area; if it is empty, show a short message instead of a cloud. 2. Clean: lowercase; remove web addresses, numbers and extra whitespace. 3. Tokenise with wink-nlp (readDoc). 4. Lemmatise: replace each word with its lemma (its.lemma), e.g. \"running\" -> \"run\". 5. Filter: keep words of three or more letters (a-z); drop stop words (its.stopWordFlag) and punctuation. 6. Count how often each lemma occurs and keep the 100 most frequent. ## 5. Word cloud - Layout with d3-cloud, drawn as SVG; font size scaled to frequency, the most frequent lemma largest; words horizontal. - Hovering a word shows the lemma and its count. - A line under the cloud: number of tokens and number of distinct lemmas. - Clicking Submit again replaces the old cloud. ## 6. Acceptance checks - A1 Opening wordcloud.html from the folder shows the page with no errors in the browser console. - A2 Paste a text, click Submit: a word cloud appears within a few seconds. - A3 The cloud contains no stop words such as \"the\", \"and\" or \"was\". - A4 The verbs \"runs\", \"ran\" and \"running\" all count as one lemma, \"run\". - A5 At 400 px width the cloud is below the text area; on a desktop it is to the right. - A6 Submitting a new text replaces the cloud; an empty text shows the message. \"\"\" with open (\"NLP-WEB-SPEC.md\", \"w\") as f: f.write(web_spec) Then give the agent a short prompt — the details are in the spec. Start in plan mode, read the plan, and approve it: run_prompt = \"\"\" /plan Read AGENTS.md and NLP-WEB-SPEC.md. Build wordcloud.html as specified. Open it in a browser, test every acceptance check (A1-A6, including a 400 px wide window) and report which pass. Fix anything that fails. If you cannot open a browser, tell me exactly what to check by hand. \"\"\" # The same as a single command in the CLI! agy -- mode plan - p \"Read AGENTS.md and NLP-WEB-SPEC.md and build the app.\" Finally, compare the two versions. Open the agent’s wordcloud.html next to the one you made with Gemini in session 3, paste the same text into both, and look at the clouds. Do they show the same words? If not, ask the agent why — different stop words or lemmas are the usual reasons. And check A4 yourself: “runs”, “ran” and “running” should all count as “run”. Here is a version an Antigravity agent built from this spec, published as a web page: word-cloud app. For more sample app specs, see the apps folder of the course’s GitHub repository. 2.5 Iteration 2: change the spec Users always want one more thing. Here the word cloud gets colour and a download button. In the spec loop, the change goes into the spec first: the spec stays the single, up-to-date description of the app, and the agent then brings the code in line with it. spec_update = \"\"\" ## 5. Word cloud (changed) - Colour each word by its frequency, on a sequential colour scale from light (rare) to dark (frequent); every colour must stay readable on a white background. - A \"Download PNG\" button saves the current cloud as wordcloud.png. ## 6. Acceptance checks (added) - A7 The most frequent lemma has the darkest colour, and the downloaded PNG shows the same cloud as the page. \"\"\" Ask the agent to change the spec, and to show you the change before it touches the code: update_prompt = \"\"\" /plan Update NLP-WEB-SPEC.md: replace section 5 with the new version below and add check A7. Show me the changed lines of the spec first. After I approve, update wordcloud.html to match the spec and re-check A1-A7. \"\"\" Review what changed with /diff. If the new version is worse, /rewind takes the project back to before the change (section 1.4) — then improve the wording of the spec and try again. 2.6 Iteration 3: an app that saves data Not every app needs a server. A web browser can run an app made of three plain files — HTML for the structure, CSS for the look, and JavaScript for the behaviour. You open index.html by double-clicking it, and the app runs on your own computer: no install, no account, no internet connection. There is no data file to load; instead the app creates data — your notes — and stores it in the browser. What the parts of this spec do: Files and constraints make the app local: no frameworks to install, nothing loaded from the internet, and it must work when opened straight from a folder. Data model and storage: a data model says exactly what one note is; storage says where notes are kept — here localStorage, a small database that every browser has for each page. Look and accessibility: saying how the app should look and who must be able to use it avoids an app that only works for its builder. notes_spec = \"\"\" # SPEC: Course notes (local web app) ## 1. Purpose and users A simple note-taking app for course participants to write down ideas, prompts and results during the sessions. One user, one computer, no account. ## 2. Files a"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/04-agentic-coding.html",
   "path": "coding/skill-school/sessions/04-agentic-coding.html",
   "title": "Session 4 · de-code agentic coding",
   "description": "Parts: Safety first!; Specs and agentic AI; Agent basics.",
   "section": "coding",
   "type": "page",
   "stack": "quarto",
   "headings": [
    "Topics",
    "Recap: session 3",
    "From idea to spec",
    "1 Safety first!",
    "1.1 From chat to agents",
    "1.2 Common agent tools",
    "1.3 AGENTS.md: rules the agent reads first",
    "1.4 Guardrails and slash commands",
    "1.5 Models and tokens",
    "2 Specs and agentic AI",
    "2.1 Agentic coding tools",
    "2.2 Create a project",
    "2.3 The spec loop",
    "2.4 Iteration 1: build from a finished spec",
    "2.5 Iteration 2: change the spec",
    "2.6 Iteration 3: an app that saves data",
    "2.7 Iteration 4: a notebook app with packages",
    "2.8 Your turn",
    "3 Agent basics",
    "3.1 Brain, loop and tools",
    "3.2 Tools are ordinary functions",
    "3.3 The loop in 30 lines",
    "3.4 Agents at work: one agent, then a team",
    "3.5 Design your own agent, and going further"
   ],
   "words": 6752,
   "updated": "2026-10-09",
   "text": "Topics Recap: session 3 From idea to spec 1 Safety first! 1.1 From chat to agents 1.2 Common agent tools 1.3 AGENTS.md: rules the agent reads first 1.4 Guardrails and slash commands 1.5 Models and tokens 2 Specs and agentic AI 2.1 Agentic coding tools 2.2 Create a project 2.3 The spec loop 2.4 Iteration 1: build from a finished spec 2.5 Iteration 2: change the spec 2.6 Iteration 3: an app that saves data 2.7 Iteration 4: a notebook app with packages 2.8 Your turn 3 Agent basics 3.1 Brain, loop and tools 3.2 Tools are ordinary functions 3.3 The loop in 30 lines 3.4 Agents at work: one agent, then a team 3.5 Design your own agent, and going further Slides Notebook Recap: session 3 Yesterday we described apps in plain language, turned the descriptions into specs, and let Gemini write the code. Today an AI agent takes over that work — and we look at how agents work inside. From idea to spec The specs and apps from the course are collected in the GitHub repository cca-cce/osm-edu. The word-cloud app started as an idea in two sentences: idea_prompt = \"\"\" Make a single-page web app where I can paste a text and click Submit to see its most important words as a word cloud. Clean the text first: lowercase it, split it into words, reduce each word to its base form, and leave out common words like \"the\" and \"and\". \"\"\" Gemini turned that idea into a working page: Word Cloud Generator. From the same idea we then wrote a fuller spec, NLP-WEB-SPEC.md, which pins down the layout, the libraries, the processing steps and the acceptance checks. In section 2.4 an agent builds the app from that spec. 1 Safety first! 1.1 From chat to agents A language model such as Gemini works by predicting the next word, over and over, based on everything written so far. In a chat, that produces an answer — but only text: you copy the code, run it, and paste back the result. An AI agent adds two things: Tools — functions the model can call to act outside the chat: read and write files, search a folder, run a command in a terminal, look something up on the web. A loop — the agent plans a step, calls a tool, reads the result, and decides the next step, until the task is done or it needs your input. That makes agents powerful: you describe the goal, and the agent does the work in a folder on your computer. It also makes them risky: a tool that can write a file can overwrite one, and a tool that can run a command can delete things. So we start with safety. 1.2 Common agent tools Most coding agents — Antigravity included — offer a similar set of tools. The last column is a rough guide to how much damage a mistake could do. Tool What it does Example Risk Read file Reads the contents of a file read NLP-WEB-SPEC.md low List / find files Lists folders or finds files by name find all *.csv files low Search in files Finds text inside files where is DV_INDEX used? low Create / write file Creates a new file or replaces one write app.py medium — can overwrite Edit file Changes part of an existing file rename a variable in app.py medium Run terminal command Runs a command in a shell quarto render report.qmd high — can do anything you can Web search Searches the internet “Gradio slider example” low — but results can be wrong Fetch web page Downloads a page or file read a library’s documentation low–medium Ask the user Pauses and asks you a question “Which column is the outcome?” none — this is a good sign Plan / to-do list Writes and updates its own task list 1. load data 2. describe … none Reading is safe; writing, editing and running commands are where you want guardrails. 1.3 AGENTS.md: rules the agent reads first An AGENTS.md file is a plain Markdown file of standing instructions. The agent reads it at the start of every conversation, before your prompt, so the rules apply without you repeating them. Put one in a project folder for that project; Antigravity also reads global rules from ~/.gemini/AGENTS.md (or GEMINI.md) for all your projects. Here is a real example, used while building this course. It stores the text; save it as AGENTS.md in your project folder. agents_md = \"\"\" ## Local Python Environment This repository uses the Python virtual environment: ~/lib/python/uv-osm --- ### Environment Activation When running any Python-related command (python, pytest, quarto render with python, etc.), ALWAYS prefix the command with: source ~/lib/python/uv-osm/bin/activate && <command> If multiple commands are needed, prefer a single bash -lc invocation that activates once and runs all steps. --- ### Package Management Policy (IMPORTANT) This environment uses **uv** for dependency management. DO NOT install, upgrade, or remove any Python packages without explicitly asking first. If a dependency is required: 1. Explain why the package is needed. 2. Confirm with the user. 3. Install it using: source ~/lib/python/uv-osm/bin/activate && uv pip install <package> Rules: - Prefer `uv pip install` over `pip install`. - Never use plain `pip install`. - Never install packages globally. - Never modify requirements files or pyproject.toml without confirmation. - If a package is missing, check first before proposing installation. --- ### File System Safety Policy (IMPORTANT) You may read and inspect files anywhere. You may create, modify, or delete files ONLY inside: /tmp/ ~/tmp/ This includes any subdirectory under /tmp/ or ~/tmp/ (e.g., /tmp/project/, /tmp/test/output.txt, ~/tmp/project/). You must NEVER modify files outside /tmp/ or ~/tmp/ without explicit confirmation. If changes to project files are required: 1. Write the proposed version to /tmp/ or ~/tmp/. 2. Show or explain the changes. 3. Ask for approval before modifying the original file. Treat everything outside /tmp/ and ~/tmp/ as read-only unless explicitly approved. \"\"\" with open (\"AGENTS.md\", \"w\") as f: f.write(agents_md) The file has three policies, each closing a typical risk: Environment: always use one specific Python environment, so the agent does not run code with the wrong setup. Packages: never install or remove software without asking first — installs change your computer beyond the project. File system: read anything, but write only in scratch folders; changes to real files are proposed first and need your approval. Note the style: short, direct, with the important parts marked IMPORTANT and concrete examples. Write rules the way you would brief a new colleague. 1.4 Guardrails and slash commands Rules are one layer of safety. Combine them with these habits: Approve actions. By default the agent asks before writing files or running commands. Keep it that way; never start it with --dangerously-skip-permissions. Plan first with /plan (or agy --mode plan): the agent only investigates and proposes until you approve. Use the sandbox (agy --sandbox) to limit what commands can reach. Work in a copy of your data, keep checkpoints (git, or /rewind to go back and /diff to see what changed), and keep secrets out of the project folder. # Start the CLI agent in a project folder, in plan mode, inside the sandbox! cd ~/ projects / wordcloud - app && agy -- mode plan -- sandbox Commands that start with / control the agent itself instead of being sent as a prompt. Ten useful ones: Command What it does /help Lists commands and keyboard shortcuts /plan Plan mode: investigate and propose, change nothing yet /grill-me The agent interviews you about your idea, one question at a time /model Shows or switches the model (/model <name>) /effort Sets how hard the model thinks (low to max) /context Shows what fills the context window /usage Shows token use and remaining quota /diff Shows the changes the agent made /rewind Goes back to an earlier point, undoing changes /resume Continues an earlier conversation /grill-me is especially useful before building an app: instead of guessing what you mean, the agent asks question after question — who uses the app, which data, what counts as done — until the idea is clear. Combine it with plan mode, and end by asking for a spec: grill_prompt = \"\"\" /plan /grill-me I want a small app that shows word clouds and sentence sentiment for the text files in this folder. When you have no more questions, write the result as APP-SPEC.md with purpose, data, features, constraints and acceptance checks. \"\"\" 1.5 Models and tokens An agent can run on different models. The trade-off is always speed and cost against capability: Model family Good for Note Gemini Flash (low / medium / high) everyday tasks, quick edits, most course work fast and cheap; start here Gemini Pro harder problems, bigger plans, tricky bugs slower, uses more quota Claude (Sonnet, Opus) a second opinion, long careful reasoning also available in Antigravity GPT-OSS an open-weight alternative useful for comparison The effort level (low to max) sets how long the model thinks before acting. Switch with /model and /effort, ask another model once with /model <name> <prompt>, and list what your account can use with agy models. Models read and write tokens — pieces of words, roughly ¾ of a word each. Everything the agent sees counts: your prompt, AGENTS.md, every file it reads, every command output and its own replies. All of it must fit in the context window, the model’s working memory; when it fills up, the agent compacts older parts into a summary and details can get lost. Check usage with /context, /usage and /quota. Point the agent to the files it needs instead of letting it read everything. Keep AGENTS.md and specs short, and start a new conversation for a new task. 2 Specs and agentic AI 2.1 Agentic coding tools Every large AI maker now offers a coding agent: a model with tools and a loop that works on the files in a project folder (section 1.1). They differ in models, prices and interfaces, but they work the same way — and they all follow a good spec and an AGENTS.md: Maker Agent Where it runs Google Antigravity, Gemini CLI desktop app, code editor, terminal Anthropic Claude Code terminal, code editors, desktop and web OpenAI Codex terminal, code editors, cloud GitHub (Microsoft) Copilot agent mode VS Code and GitHub Anysphere Cursor its own code editor In this course we use Google Antigravity, which works with a Google account. It puts the same agent behind three interfaces, all downloaded from antigravity.google. Product What you see Suits Start it with Antigravity app A desktop app for managing agents, plans and results beginners; working without reading code the app icon Antigravity IDE A code editor with the agent built in reviewing code and edits closely the app icon, or antigravity-ide Antigravity CLI The agent in a terminal window quick tasks, scripts, remote computers agy The app is an agent manager: you describe the task and follow the agent’s plan, its steps and its results (artifacts) without opening a code editor — the most beginner-friendly start. The IDE is a code editor in the style of Visual Studio Code, with the agent in a side panel. You see every edit in context and can accept or reject it line by line. The CLI, agy, runs the same agent in a terminal: quick to start, works on remote computers over SSH, and runs single prompts from scripts. # Interactive session in the current folder! agy # Safer starts: plan mode, sandboxed terminal, a chosen model and effort! agy -- mode plan -- sandbox -- model gemini - 3.1 - pro - high -- effort high # One prompt, no conversation: prints the answer and exits! agy - p \"Summarise NLP-WEB-SPEC.md in three bullet points\" # Continue the most recent conversation, list available models, update the CLI! agy - c! agy models! agy update The commands are written with! so they could run from a notebook; in a normal terminal, leave the! out. In Colab they do not work — the CLI runs on your own computer. 2.2 Create a project Agents work in a project folder (the workspace). Everything the agent may touch lives there, so make a fresh one for each app. Every iteration below uses the same layout: my-app/ ├── AGENTS.md rules: environment, packages, where it may write └── <APP>-SPEC.md the task: what to build and how to check it Create an empty folder named after the app, for example wordcloud-app. Save AGENTS.md (section 1.3) and the app’s spec in it. Open the folder in the Antigravity app or IDE and confirm that you trust it — or open a terminal in the folder and run agy. The agent reads both files before it starts, so your prompts can stay short. 2.3 The spec loop A useful app spec has the same parts as in session 3, kept short: purpose, data, features, constraints and acceptance checks. With an agent, a spec is not written once — it is the thing you keep improving: Write or update the spec. Ask the agent for a plan (/plan) and read it. Approve the plan; the agent builds. Check the result against the acceptance checks — the agent first, then you. If something is wrong or missing, change the spec, not the code, and go back to step 2. We go round this loop four times, with one new thing to learn each time: Iteration App Runs in New this time 1 Word cloud the browser, one file an agent builds and tests from a finished spec 2 Word cloud, extended the browser, one file changing a spec and reviewing the change 3 Course notes the browser, three files a bigger spec, and data that is saved 4 Edge detector a Jupyter notebook packages to install; an interface inside the notebook The specs are stored in cells; run them in Colab to save each one as a file for the agent. 2.4 Iteration 1: build from a finished spec In session 3 you gave this spec to Gemini and copied its code into a file yourself. Now an agent does the whole job, from the same spec: Gemini chat (session 3) Antigravity agent (session 4) Writes wordcloud.html you copy the code into a file the agent creates the file Opens and tests it you the agent, against the acceptance checks Fixes errors you paste the error back into the chat the agent reads the error and edits the file Your role copy, paste, check, report back approve the plan, review the result This is the same specification as in session 3. If you saved NLP-WEB-SPEC.md then, copy it into the project folder; otherwise run the cell in Colab, download the file, and put it there. web_spec = \"\"\" # SPEC: Word cloud (single-page web app) ## 1. Purpose Paste any English text and see its most important words as a word cloud, in the browser, without Python. ## 2. Files and libraries - Exactly one file, wordcloud.html, with the CSS and JavaScript inside it. No build step, no server. - Load the libraries as ES modules from the jsdelivr CDN, with pinned major versions: wink-nlp@2 with wink-eng-lite-web-model@1 (NLP), d3@7 and d3-cloud@1 (word cloud). - Must work when wordcloud.html is opened directly from the folder (a file:// address) in current Chrome, Firefox, Edge and Safari. An internet connection is needed for the libraries. ## 3. Layout - Wide screens (700 px and wider): two columns. Left: a labelled text area and a Submit button. Right: the word cloud. - Narrow screens (below 700 px): one column, text area and button on top, word cloud below. - The text area starts with a short sample paragraph, so Submit works right away. ## 4. Processing (when Submit is clicked) 1. Read: take the text from the text area; if it is empty, show a short message instead of a cloud. 2. Clean: lowercase; remove web addresses, numbers and extra whitespace. 3. Tokenise with wink-nlp (readDoc). 4. Lemmatise: replace each word with its lemma (its.lemma), e.g. \"running\" -> \"run\". 5. Filter: keep words of three or more letters (a-z); drop stop words (its.stopWordFlag) and punctuation. 6. Count how often each lemma occurs and keep the 100 most frequent. ## 5. Word cloud - Layout with d3-cloud, drawn as SVG; font size scaled to frequency, the most frequent lemma largest; words horizontal. - Hovering a word shows the lemma and its count. - A line under the cloud: number of tokens and number of distinct lemmas. - Clicking Submit again replaces the old cloud. ## 6. Acceptance checks - A1 Opening wordcloud.html from the folder shows the page with no errors in the browser console. - A2 Paste a text, click Submit: a word cloud appears within a few seconds. - A3 The cloud contains no stop words such as \"the\", \"and\" or \"was\". - A4 The verbs \"runs\", \"ran\" and \"running\" all count as one lemma, \"run\". - A5 At 400 px width the cloud is below the text area; on a desktop it is to the right. - A6 Submitting a new text replaces the cloud; an empty text shows the message. \"\"\" with open (\"NLP-WEB-SPEC.md\", \"w\") as f: f.write(web_spec) Then give the agent a short prompt — the details are in the spec. Start in plan mode, read the plan, and approve it: run_prompt = \"\"\" /plan Read AGENTS.md and NLP-WEB-SPEC.md. Build wordcloud.html as specified. Open it in a browser, test every acceptance check (A1-A6, including a 400 px wide window) and report which pass. Fix anything that fails. If you cannot open a browser, tell me exactly what to check by hand. \"\"\" # The same as a single command in the CLI! agy -- mode plan - p \"Read AGENTS.md and NLP-WEB-SPEC.md and build the app.\" Finally, compare the two versions. Open the agent’s wordcloud.html next to the one you made with Gemini in session 3, paste the same text into both, and look at the clouds. Do they show the same words? If not, ask the agent why — different stop words or lemmas are the usual reasons. And check A4 yourself: “runs”, “ran” and “running” should all count as “run”. Here is a version an Antigravity agent built from this spec, published as a web page: word-cloud app. For more sample app specs, see the apps folder of the course’s GitHub repository. 2.5 Iteration 2: change the spec Users always want one more thing. Here the word cloud gets colour and a download button. In the spec loop, the change goes into the spec first: the spec stays the single, up-to-date description of the app, and the agent then brings the code in line with it. spec_update = \"\"\" ## 5. Word cloud (changed) - Colour each word by its frequency, on a sequential colour scale from light (rare) to dark (frequent); every colour must stay readable on a white background. - A \"Download PNG\" button saves the current cloud as wordcloud.png. ## 6. Acceptance checks (added) - A7 The most frequent lemma has the darkest colour, and the downloaded PNG shows the same cloud as the page. \"\"\" Ask the agent to change the spec, and to show you the change before it touches the code: update_prompt = \"\"\" /plan Update NLP-WEB-SPEC.md: replace section 5 with the new version below and add check A7. Show me the changed lines of the spec first. After I approve, update wordcloud.html to match the spec and re-check A1-A7. \"\"\" Review what changed with /diff. If the new version is worse, /rewind takes the project back to before the change (section 1.4) — then improve the wording of the spec and try again. 2.6 Iteration 3: an app that saves data Not every app needs a server. A web browser can run an app made of three plain files — HTML for the structure, CSS for the look, and JavaScript for the behaviour. You open index.html by double-clicking it, and the app runs on your own computer: no install, no account, no internet connection. There is no data file to load; instead the app creates data — your notes — and stores it in the browser. What the parts of this spec do: Files and constraints make the app local: no frameworks to install, nothing loaded from the internet, and it must work when opened straight from a folder. Data model and storage: a data model says exactly what one note is; storage says where notes are kept — here localStorage, a small database that every browser has for each page. Look and accessibility: saying how the app should look and who must be able to use it avoids an app that only works for its builder. notes_spec = \"\"\" # SPEC: Course notes (local web app) ## 1. Purpose and users A simple note-taking app for course participants to write down ideas, prompts and results during the sessions. One user, one computer, no account. ## 2. Files a"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/05-skills-mcp-slides.html",
   "path": "coding/skill-school/sessions/05-skills-mcp-slides.html",
   "title": "Session 5 · de-code skills and MCP",
   "description": "Parts: Skills; MCP: Model Context Protocol; Putting it together.",
   "section": "coding",
   "type": "slides",
   "stack": "quarto",
   "headings": [
    "Topics",
    "1 Skills",
    "1.1 From prompts to skills",
    "1.2 Anatomy of a skill",
    "1.3 How agents use skills",
    "1.4 Official and custom skills",
    "1.5 A real skill: from HTML app to PWA",
    "1.6 Use the skill",
    "2 MCP: Model Context Protocol",
    "2.1 Why MCP",
    "2.2 Anatomy of MCP",
    "2.3 Skills and MCP",
    "2.4 Build a minimal MCP server",
    "2.5 An MCP server for this website",
    "2.6 Existing MCP servers",
    "3 Putting it together",
    "3.1 A skill that uses MCP",
    "3.2 The week in one table",
    "3.3 Your turn"
   ],
   "words": 5743,
   "updated": "2026-10-09",
   "text": "Topics 1 Skills 1.1 From prompts to skills 1.2 Anatomy of a skill 1.3 How agents use skills 1.4 Official and custom skills 1.5 A real skill: from HTML app to PWA 1.6 Use the skill 2 MCP: Model Context Protocol 2.1 Why MCP 2.2 Anatomy of MCP 2.3 Skills and MCP 2.4 Build a minimal MCP server 2.5 An MCP server for this website 2.6 Existing MCP servers 3 Putting it together 3.1 A skill that uses MCP 3.2 The week in one table 3.3 Your turn Slides Notebook 1 Skills 1.1 From prompts to skills This week we have given AI agents four kinds of text. Each one does a different job: Text What it says When the agent reads it Session Prompt Do this, now Once, when you send it 1–2 Spec What to build and how to check it When you point the agent to it 3–4 AGENTS.md Rules that always apply At the start of every task 4 Skill How to do a kind of task, step by step Only when the task needs it 5 A skill is a reusable procedure: a folder with instructions, and optionally scripts and templates, that teaches an agent how to do one kind of task well — the way you want it done. Write it once, and every later task of that kind starts from your best practice instead of from scratch. Like the specs and rules before it, a skill is context: text the agent reads into its context window, but only when a task needs it, so it adds know-how without crowding out the rest of the conversation. 1.2 Anatomy of a skill A skill is a folder. Only one file is required, SKILL.md; the rest is optional: skill-html-pwa/ ├── SKILL.md required: name, description, instructions ├── references/netlify.md optional: a longer document it reads only when needed ├── scripts/validate_pwa.py optional: code the agent can run to check its work └── agents/openai.yaml optional: extra settings for one agent (OpenAI Codex) This is the real skill we look at in section 1.5. A skill can also have an assets/ folder with templates and other files to copy. Here is a minimal SKILL.md: minimal_skill = \"\"\"--- name: tsv-summary description: Summarise a tab-separated data file. Use when the user asks what is in a.tsv file, or wants a quick overview of its columns before an analysis. --- # TSV summary 1. Read the file with pandas (sep=\" \\\\ t\"). 2. Report the number of rows and columns, and the missing values per column. 3. For each numeric column: mean, SD, min and max, rounded to two decimals. 4. For each text column: the five most frequent values. 5. End with two sentences on what the data seems to be about. \"\"\" SKILL.md has two parts. The front matter between the --- lines holds the skill’s name and a description of what it does and when to use it. The body is plain Markdown: the steps, rules and checks. 1.3 How agents use skills An agent may have dozens of skills, but it does not read them all. At the start it only sees each skill’s name and description — a few lines each, so they cost little of the context window (see the chart above). When your request matches a description, the agent reads that skill’s body, and opens its scripts or references only if a step needs them. This is called progressive disclosure. So the description is the trigger. Write it as what it does plus “Use when …”, with the words people actually use when they ask for that task. There are two ways to use a skill: Automatically: ask in your own words (“give me an overview of survey.tsv”) and the agent picks the matching skill. By name: type a slash command with the skill name, e.g. /tsv-summary survey.tsv. In Antigravity, a project’s skills live in.agents/skills/<name>/SKILL.md inside the project folder; skills for all your projects are configured under ~/.gemini/config. Type /skills to see which skills the agent has, and /skills reload after adding or editing one. 1.4 Official and custom skills Official skills Custom skills Written by The company behind the agent or tool You, your team or your course Examples Antigravity’s built-in skills such as /grill-me; Anthropic’s public skills for Word, Excel, PowerPoint and PDF files The HTML-to-PWA skill below Good for General tasks that are the same for everyone Your data, conventions, and quality checks Updated By the publisher By you, when your practice changes Trust Comes from a known source You know what is in it Both follow the same open format, Agent Skills, so a skill written for one agent often works in others. A skill can include scripts that run on your computer, so treat skills from others like any other software: read SKILL.md and its scripts before you install it (session 4, Safety first!). 1.5 A real skill: from HTML app to PWA A progressive web app (PWA) is a web page you can install like an app: it gets an icon on your phone or computer, opens in its own window, and keeps working offline after the first visit. The skill below turns an existing single-page HTML app — like the ones we built in sessions 3 and 4 — into a PWA, and prepares it for a static web host such as Netlify. An agent used this skill to turn a regex trainer page into the de-code regex trainer — open it on your phone and try Add to home screen. This is its SKILL.md, unchanged: skill_md = \"\"\"--- name: skill-html-pwa description: Convert an existing single-page HTML web app into a branded, installable, mobile-compatible PWA and prepare or verify it on a static live host such as Netlify. Use when adapting a supplied HTML app rather than building an unrelated site from scratch. --- # HTML app to hosted PWA Turn the supplied single-page app into a real progressive web app while preserving its purpose and behavior. Treat branding, mobile usability, installability, offline behavior, host path, and live verification as one delivery problem. ## Establish the deployment shape Before editing, inspect: - the source HTML and its scripts, styles, assets, and existing behavior; - supplied brand names, copy, colors, logos, favicons, and icons; - the requested output directory; - the host's publish root and the app's public URL path; and - existing manifests, service workers, redirects, headers, and host configuration. Infer straightforward details from the repository and requested URL. Ask only when a missing choice would materially change the product or deployment. Preserve the original source unless the user explicitly wants it edited in place. Map the filesystem to the public URL explicitly. For example, if the publish root is `web/` and the target URL is `/app-building/pwas/de-code-regex/`, the app belongs in `web/app-building/pwas/de-code-regex/`. ## Preserve and brand the app Keep the original app's useful interactions, content, saved state, and accessibility semantics unless the user requests a change. Apply requested branding consistently to: - the document title, description, theme color, and mobile metadata; - the visible primary title and subtitle; - the header or app chrome; - the favicon, application icons, and installed-app name; and - focus, selection, match, and other primary highlight states. Prefer supplied brand assets. Inspect them before use. Generate raster sizes from the supplied vector or highest-quality source when needed; do not merely rename a small bitmap as a larger icon. ## Build a real PWA Create physical, host-served files rather than Blob URLs: - `index.html` - `manifest.webmanifest` (or a correctly linked JSON manifest) - `sw.js` - at least actual 192×192 and 512×512 PNG icons - the supplied SVG or other logo assets used by the page For an app hosted below the domain root, default to relative paths: { \"id\": \"./\", \"start_url\": \"./\", \"scope\": \"./\" } Link resources with `./...` and register `./sw.js` with scope `./`. Avoid root-relative paths such as `/icons/icon.png` unless the asset intentionally lives at the origin root. A service worker cannot be registered from a `blob:` URL. The manifest should include the requested name, a short name that fits launcher UI, description, `standalone` display mode, theme and background colors, and valid icon entries. Use `purpose: \"any maskable\"` only when the artwork stays legible inside the maskable safe area. ## Design offline behavior safely Cache the local application shell during service-worker installation and provide a cached navigation fallback. Use a site-specific cache namespace and increment its version when shell files change. When removing old caches, delete only caches owned by this app. Cache storage is origin-wide even though service-worker control is scoped; never delete every cache on a host that may contain sibling apps. Browser storage is origin-wide as well: `localStorage`, `sessionStorage` and IndexedDB are shared by every app on the host. Give new keys and database names an app-specific prefix, such as `regexcraft_pattern`, and never clear all storage. Keep the source app's existing keys unless you also migrate their values, so users do not lose saved state. Prefer local CSS, JavaScript, fonts, and icons for dependable offline startup. If the source relies on CDNs and retaining them is proportionate, explain that the first visit must be online and use runtime caching deliberately. Do not claim complete offline behavior until it has been tested with network access disabled. ## Make the existing UI mobile-compatible Use a responsive viewport without disabling zoom. Keep primary body text readable, controls touch-friendly, focus visible, and text selectable where useful. Verify that: - the title and essential brand copy remain visible; - navigation condenses without becoming ambiguous; - controls do not clip or overlap; - intentional horizontal toolbars scroll without causing page-wide overflow; - editors and results remain usable on a narrow portrait screen; and - the layout also remains coherent at desktop width and 200% text enlargement. Do not replace a functioning app with a landing page or put promotional content ahead of its primary activity. ## Prepare the host The app requires HTTPS in production. Preserve the user's hosting provider and deployment workflow. Do not publish, push, or mutate a live host unless requested. For Netlify-specific placement, MIME headers, and verification, read [references/netlify.md](references/netlify.md). ## Validate before handoff Run the bundled validator: python scripts/validate_pwa.py /path/to/pwa Then serve the app over HTTP; `file://` cannot validate service workers. Check at least one desktop and one narrow mobile viewport, exercise the app's primary interaction, and inspect the actual screenshots. Verify the manifest and every icon URL, service-worker registration and cache creation, reload behavior, and offline startup after an online load. For a live URL, check response status and MIME types rather than assuming the upload path is correct. Confirm that HTML is served as HTML, the service worker as JavaScript, the manifest as `application/manifest+json` or another browser-accepted JSON type, and icons with their declared image types. Report what was created, the public-path assumption, what was directly verified, and any remaining host-side action. Distinguish \"prepared for deployment\" from \"deployed and live.\" \"\"\" What to notice: The description says what the skill does and when to use it (“Use when adapting a supplied HTML app …”), so the agent can pick it by itself. The body is a procedure with checks, not code: inspect first, keep what works, build the PWA files, make it work offline and on mobile, then validate. The Netlify details live in references/netlify.md, and the skill says to read that file only when the host is Netlify — progressive disclosure (section 1.3). A script checks what instructions alone cannot: scripts/validate_pwa.py tests the manifest, the icon sizes and the service worker. It asks for honest reporting: the agent must say whether the app is only prepared for deployment or actually deployed and live. 1.6 Use the skill Download skill-html-pwa.zip (or browse the files on GitHub), read SKILL.md and the script first (section 1.4), and unzip it into.agents/skills/ in a project folder. Check that Antigravity lists it with /skills, then try it both ways — by name and in your own words — on the word-cloud app from sessions 3 and 4: by_name = \"\"\" /skill-html-pwa Turn wordcloud.html into an installable PWA that will be hosted at https://<your-site>.netlify.app/apps/wordcloud/ \"\"\" own_words = \"\"\" Make my word-cloud page installable on my phone, so it also opens without internet. \"\"\" A good run ends with the validator’s output and a clear statement: is the app only prepared for deployment, or deployed and live? The word-cloud app loads its libraries from a CDN, so also check what the agent says about offline use — the skill tells it not to claim offline support it has not tested. 2 MCP: Model Context Protocol 2.1 Why MCP A skill teaches the agent how to do something with the tools it already has: reading and writing files, running commands. Some tasks need more: opening a web page in a real browser, reading issues on GitHub, querying a database, checking a calendar. The Model Context Protocol (MCP) is an open standard for giving an agent such new tools and data. Before MCP, every AI app needed its own connector for every service. With MCP, a service is wrapped once as an MCP server, and every agent that speaks MCP — Antigravity, Claude, ChatGPT and many code editors — can use it. It is often compared to USB-C: one plug for everything. 2.2 Anatomy of MCP Part What it is Example Host The AI app you use Antigravity Client The connection inside the host, one per server Antigravity’s link to the GitHub server Server A small program that offers capabilities The GitHub MCP server A server can offer three kinds of things: Tools — actions the agent can call, with named inputs: search_issues(query), take_screenshot(url). Resources — data the agent can read: a file, a database table, a codebook. Prompts — ready-made prompt templates the user can pick. Servers run in one of two ways (the transport): locally, as a program on your computer that the host starts and talks to (stdio), or remotely, at a web address (HTTP). One tool call goes like this: You ask: “Which issues are open in my repo?” The agent sees a matching tool in the server’s tool list and calls it, with inputs. Antigravity asks for your approval (unless you allowed that tool before). The server does the work and sends the result back. The agent reads the result and answers you — or calls the next tool. 2.3 Skills and MCP Skill MCP server Adds Know-how: steps, rules, checks Abilities and data: new tools Is Text (+ optional scripts) A running program Context cost Small until used Its tool list is loaded while it is on Write your own Easy: a Markdown file Some code (a few lines in Python) Use when You repeat a kind of task The agent cannot reach something it needs They work well together: a skill can say which MCP tools to use, and in what order. 2.4 Build a minimal MCP server A server in Python takes a few lines with the official MCP Python SDK. Each tool is an ordinary function: its name, type hints and docstring tell the agent what it does and which inputs it takes. This server offers two of the session 1 analyses as tools, plus the dataset’s codebook as a resource: server_code = ''' \"\"\"komp014 MCP server: quick analyses of a tab-separated data file.\"\"\" import pandas as pd from scipy import stats from mcp.server import MCPServer mcp = MCPServer(\"komp014\") @mcp.tool() def describe_tsv(url: str) -> dict: \"\"\"Rows, columns and the mean of every numeric column of a.tsv file.\"\"\" df = pd.read_csv(url, sep=\" \\\\ t\") means = df.select_dtypes(\"number\").mean().round(2) return {\"rows\": len(df), \"columns\": list(df.columns), \"means\": means.to_dict()} @mcp.tool() def group_difference(url: str, group: str, outcome: str) -> dict: \"\"\"Welch t-test and Cohen's d for the outcome between the two levels of group.\"\"\" df = pd.read_csv(url, sep=\" \\\\ t\") a, b = [g[outcome] for _, g in df.groupby(group)] t, p = stats.ttest_ind(a, b, equal_var=False) sd = ((a.var() * (len(a) - 1) + b.var() * (len(b) - 1)) / (len(a) + len(b) - 2)) ** 0.5 d = (a.mean() - b.mean()) / sd return {\"t\": round(float(t), 2), \"p\": round(float(p), 4), \"d\": round(float(d), 2)} @mcp.resource(\"komp014://codebook\") def codebook() -> str: \"\"\"What the columns of the komp014 toy dataset mean.\"\"\" return (\"IV_CAT_GROUP: category1/category2. Items 1-5: IV1_ITEM1, IV1_ITEM2, \" \"IV2_ITEM1, IV2_ITEM2, DV_ITEM1, DV_ITEM2. Indices are item means: \" \"IV_INDEX1, IV_INDEX2, DV_INDEX (outcome).\") if __name__ == \"__main__\": mcp.run() # local server: talks to the host over stdin/stdout ''' with open (\"komp014_server.py\", \"w\") as f: f.write(server_code) To use it, you need Python with the mcp package on your own computer (MCP servers run next to the agent, not in Colab). Try the server in the MCP Inspector, a web page where you can call its tools by hand, then add it to Antigravity and check that it is listed:! pip install \"mcp[cli]\" pandas scipy! mcp dev komp014_server.py! agy mcp add komp014 python / full / path / to / komp014_server.py! agy mcp list Then ask the agent something only the server can answer quickly: mcp_prompt = \"\"\" Use the komp014 tools: describe https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv and test whether DV_INDEX differs between the IV_CAT_GROUP levels. Explain the result in two sentences. \"\"\" The answer should report a Cohen’s d of size 0.58 (its sign shows which group scores higher) — the same effect as in session 1, now computed by a tool the agent called. 2.5 An MCP server for this website The de-code site has grown in many directions: workshop sessions with slides and notebooks, section pages, an installable app, a Shiny app and skill downloads — built with different tools, in different folders, and not all of them linked from the home page. Visitors rarely browse; they ask questions. As site managers, we can let an agent answer those questions from the site itself. The site already publishes two descriptions of everything on it: an llms.txt, a short table of contents written for AI agents, and a full content index with the text of every page. llms.txt is a list an agent can read; an MCP server adds search, so the agent asks for what it needs and gets back only the matching pages, with their links: What Kind What the agent gets list_sections() tool the site’s sections and their landing pages search_site(query, section, limit) tool the best-matching pages: title, link, type and a short snippet get_page(url) tool one page’s headings and text, to answer from its content site://llms.txt resource the overview of the whole site The server reads the content index once and keeps it in memory. Its search is deliberately simple — a match in a title counts more than one in the text, and a page that matches every word ranks first — and every tool returns a few short results instead of whole pages, which keeps the agent’s context window small (session 4). de_code_mcp_code = ''' \"\"\"de-code-mcp: an MCP server for finding pages on the de-code website in plain language.\"\"\" import json import os import re from urllib.request import urlopen from mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ToolError SITE = \"https://de-code-ai.netlify.app\" INDEX_SOURCE = os.environ.get(\"SITE_INDEX\", f\" {SITE} /site/index.json\") LLMS_SOURCE = os.environ.get(\"SITE_LLMS\", f\" {SITE} /llms.txt\") WEIGHTS = {\"title\": 5, \"headings\": 3, \"description\": 2, \"text\": 1, \"type\": 2} SKIP = {\"the\", \"and\", \"for\", \"can\", \"how\", \"what\", \"where\", \"which\", \"find\", \"site\", \"page\", \"about\"} mcp = MCPServer(\"de-code-mcp\") def read(source: str) -> str: \"\"\"Read a URL or a local file as text.\"\"\" if source.startswith(\"http\"): with urlopen(source, timeout=20) as response: return response.read().decode(\"utf-8\") with open(source, encoding=\"utf-8\") as f: return f.read() INDEX = json.loads(read(INDEX_SOURCE)) # loaded once, kept in memory PAGES = {page[\"url\"]: page for page in INDEX[\"pages\"]} def score(page: dict, words: list[str]) -> float: fields = {\"tit"
  },
  {
   "url": "https://de-code-ai.netlify.app/coding/skill-school/sessions/05-skills-mcp.html",
   "path": "coding/skill-school/sessions/05-skills-mcp.html",
   "title": "Session 5 · de-code skills and MCP",
   "description": "Parts: Skills; MCP: Model Context Protocol; Putting it together.",
   "section": "coding",
   "type": "page",
   "stack": "quarto",
   "headings": [
    "Topics",
    "1 Skills",
    "1.1 From prompts to skills",
    "1.2 Anatomy of a skill",
    "1.3 How agents use skills",
    "1.4 Official and custom skills",
    "1.5 A real skill: from HTML app to PWA",
    "1.6 Use the skill",
    "2 MCP: Model Context Protocol",
    "2.1 Why MCP",
    "2.2 Anatomy of MCP",
    "2.3 Skills and MCP",
    "2.4 Build a minimal MCP server",
    "2.5 An MCP server for this website",
    "2.6 Existing MCP servers",
    "3 Putting it together",
    "3.1 A skill that uses MCP",
    "3.2 The week in one table",
    "3.3 Your turn"
   ],
   "words": 5743,
   "updated": "2026-10-09",
   "text": "Topics 1 Skills 1.1 From prompts to skills 1.2 Anatomy of a skill 1.3 How agents use skills 1.4 Official and custom skills 1.5 A real skill: from HTML app to PWA 1.6 Use the skill 2 MCP: Model Context Protocol 2.1 Why MCP 2.2 Anatomy of MCP 2.3 Skills and MCP 2.4 Build a minimal MCP server 2.5 An MCP server for this website 2.6 Existing MCP servers 3 Putting it together 3.1 A skill that uses MCP 3.2 The week in one table 3.3 Your turn Slides Notebook 1 Skills 1.1 From prompts to skills This week we have given AI agents four kinds of text. Each one does a different job: Text What it says When the agent reads it Session Prompt Do this, now Once, when you send it 1–2 Spec What to build and how to check it When you point the agent to it 3–4 AGENTS.md Rules that always apply At the start of every task 4 Skill How to do a kind of task, step by step Only when the task needs it 5 A skill is a reusable procedure: a folder with instructions, and optionally scripts and templates, that teaches an agent how to do one kind of task well — the way you want it done. Write it once, and every later task of that kind starts from your best practice instead of from scratch. Like the specs and rules before it, a skill is context: text the agent reads into its context window, but only when a task needs it, so it adds know-how without crowding out the rest of the conversation. 1.2 Anatomy of a skill A skill is a folder. Only one file is required, SKILL.md; the rest is optional: skill-html-pwa/ ├── SKILL.md required: name, description, instructions ├── references/netlify.md optional: a longer document it reads only when needed ├── scripts/validate_pwa.py optional: code the agent can run to check its work └── agents/openai.yaml optional: extra settings for one agent (OpenAI Codex) This is the real skill we look at in section 1.5. A skill can also have an assets/ folder with templates and other files to copy. Here is a minimal SKILL.md: minimal_skill = \"\"\"--- name: tsv-summary description: Summarise a tab-separated data file. Use when the user asks what is in a.tsv file, or wants a quick overview of its columns before an analysis. --- # TSV summary 1. Read the file with pandas (sep=\" \\\\ t\"). 2. Report the number of rows and columns, and the missing values per column. 3. For each numeric column: mean, SD, min and max, rounded to two decimals. 4. For each text column: the five most frequent values. 5. End with two sentences on what the data seems to be about. \"\"\" SKILL.md has two parts. The front matter between the --- lines holds the skill’s name and a description of what it does and when to use it. The body is plain Markdown: the steps, rules and checks. 1.3 How agents use skills An agent may have dozens of skills, but it does not read them all. At the start it only sees each skill’s name and description — a few lines each, so they cost little of the context window (see the chart above). When your request matches a description, the agent reads that skill’s body, and opens its scripts or references only if a step needs them. This is called progressive disclosure. So the description is the trigger. Write it as what it does plus “Use when …”, with the words people actually use when they ask for that task. There are two ways to use a skill: Automatically: ask in your own words (“give me an overview of survey.tsv”) and the agent picks the matching skill. By name: type a slash command with the skill name, e.g. /tsv-summary survey.tsv. In Antigravity, a project’s skills live in.agents/skills/<name>/SKILL.md inside the project folder; skills for all your projects are configured under ~/.gemini/config. Type /skills to see which skills the agent has, and /skills reload after adding or editing one. 1.4 Official and custom skills Official skills Custom skills Written by The company behind the agent or tool You, your team or your course Examples Antigravity’s built-in skills such as /grill-me; Anthropic’s public skills for Word, Excel, PowerPoint and PDF files The HTML-to-PWA skill below Good for General tasks that are the same for everyone Your data, conventions, and quality checks Updated By the publisher By you, when your practice changes Trust Comes from a known source You know what is in it Both follow the same open format, Agent Skills, so a skill written for one agent often works in others. A skill can include scripts that run on your computer, so treat skills from others like any other software: read SKILL.md and its scripts before you install it (session 4, Safety first!). 1.5 A real skill: from HTML app to PWA A progressive web app (PWA) is a web page you can install like an app: it gets an icon on your phone or computer, opens in its own window, and keeps working offline after the first visit. The skill below turns an existing single-page HTML app — like the ones we built in sessions 3 and 4 — into a PWA, and prepares it for a static web host such as Netlify. An agent used this skill to turn a regex trainer page into the de-code regex trainer — open it on your phone and try Add to home screen. This is its SKILL.md, unchanged: skill_md = \"\"\"--- name: skill-html-pwa description: Convert an existing single-page HTML web app into a branded, installable, mobile-compatible PWA and prepare or verify it on a static live host such as Netlify. Use when adapting a supplied HTML app rather than building an unrelated site from scratch. --- # HTML app to hosted PWA Turn the supplied single-page app into a real progressive web app while preserving its purpose and behavior. Treat branding, mobile usability, installability, offline behavior, host path, and live verification as one delivery problem. ## Establish the deployment shape Before editing, inspect: - the source HTML and its scripts, styles, assets, and existing behavior; - supplied brand names, copy, colors, logos, favicons, and icons; - the requested output directory; - the host's publish root and the app's public URL path; and - existing manifests, service workers, redirects, headers, and host configuration. Infer straightforward details from the repository and requested URL. Ask only when a missing choice would materially change the product or deployment. Preserve the original source unless the user explicitly wants it edited in place. Map the filesystem to the public URL explicitly. For example, if the publish root is `web/` and the target URL is `/app-building/pwas/de-code-regex/`, the app belongs in `web/app-building/pwas/de-code-regex/`. ## Preserve and brand the app Keep the original app's useful interactions, content, saved state, and accessibility semantics unless the user requests a change. Apply requested branding consistently to: - the document title, description, theme color, and mobile metadata; - the visible primary title and subtitle; - the header or app chrome; - the favicon, application icons, and installed-app name; and - focus, selection, match, and other primary highlight states. Prefer supplied brand assets. Inspect them before use. Generate raster sizes from the supplied vector or highest-quality source when needed; do not merely rename a small bitmap as a larger icon. ## Build a real PWA Create physical, host-served files rather than Blob URLs: - `index.html` - `manifest.webmanifest` (or a correctly linked JSON manifest) - `sw.js` - at least actual 192×192 and 512×512 PNG icons - the supplied SVG or other logo assets used by the page For an app hosted below the domain root, default to relative paths: { \"id\": \"./\", \"start_url\": \"./\", \"scope\": \"./\" } Link resources with `./...` and register `./sw.js` with scope `./`. Avoid root-relative paths such as `/icons/icon.png` unless the asset intentionally lives at the origin root. A service worker cannot be registered from a `blob:` URL. The manifest should include the requested name, a short name that fits launcher UI, description, `standalone` display mode, theme and background colors, and valid icon entries. Use `purpose: \"any maskable\"` only when the artwork stays legible inside the maskable safe area. ## Design offline behavior safely Cache the local application shell during service-worker installation and provide a cached navigation fallback. Use a site-specific cache namespace and increment its version when shell files change. When removing old caches, delete only caches owned by this app. Cache storage is origin-wide even though service-worker control is scoped; never delete every cache on a host that may contain sibling apps. Browser storage is origin-wide as well: `localStorage`, `sessionStorage` and IndexedDB are shared by every app on the host. Give new keys and database names an app-specific prefix, such as `regexcraft_pattern`, and never clear all storage. Keep the source app's existing keys unless you also migrate their values, so users do not lose saved state. Prefer local CSS, JavaScript, fonts, and icons for dependable offline startup. If the source relies on CDNs and retaining them is proportionate, explain that the first visit must be online and use runtime caching deliberately. Do not claim complete offline behavior until it has been tested with network access disabled. ## Make the existing UI mobile-compatible Use a responsive viewport without disabling zoom. Keep primary body text readable, controls touch-friendly, focus visible, and text selectable where useful. Verify that: - the title and essential brand copy remain visible; - navigation condenses without becoming ambiguous; - controls do not clip or overlap; - intentional horizontal toolbars scroll without causing page-wide overflow; - editors and results remain usable on a narrow portrait screen; and - the layout also remains coherent at desktop width and 200% text enlargement. Do not replace a functioning app with a landing page or put promotional content ahead of its primary activity. ## Prepare the host The app requires HTTPS in production. Preserve the user's hosting provider and deployment workflow. Do not publish, push, or mutate a live host unless requested. For Netlify-specific placement, MIME headers, and verification, read [references/netlify.md](references/netlify.md). ## Validate before handoff Run the bundled validator: python scripts/validate_pwa.py /path/to/pwa Then serve the app over HTTP; `file://` cannot validate service workers. Check at least one desktop and one narrow mobile viewport, exercise the app's primary interaction, and inspect the actual screenshots. Verify the manifest and every icon URL, service-worker registration and cache creation, reload behavior, and offline startup after an online load. For a live URL, check response status and MIME types rather than assuming the upload path is correct. Confirm that HTML is served as HTML, the service worker as JavaScript, the manifest as `application/manifest+json` or another browser-accepted JSON type, and icons with their declared image types. Report what was created, the public-path assumption, what was directly verified, and any remaining host-side action. Distinguish \"prepared for deployment\" from \"deployed and live.\" \"\"\" What to notice: The description says what the skill does and when to use it (“Use when adapting a supplied HTML app …”), so the agent can pick it by itself. The body is a procedure with checks, not code: inspect first, keep what works, build the PWA files, make it work offline and on mobile, then validate. The Netlify details live in references/netlify.md, and the skill says to read that file only when the host is Netlify — progressive disclosure (section 1.3). A script checks what instructions alone cannot: scripts/validate_pwa.py tests the manifest, the icon sizes and the service worker. It asks for honest reporting: the agent must say whether the app is only prepared for deployment or actually deployed and live. 1.6 Use the skill Download skill-html-pwa.zip (or browse the files on GitHub), read SKILL.md and the script first (section 1.4), and unzip it into.agents/skills/ in a project folder. Check that Antigravity lists it with /skills, then try it both ways — by name and in your own words — on the word-cloud app from sessions 3 and 4: by_name = \"\"\" /skill-html-pwa Turn wordcloud.html into an installable PWA that will be hosted at https://<your-site>.netlify.app/apps/wordcloud/ \"\"\" own_words = \"\"\" Make my word-cloud page installable on my phone, so it also opens without internet. \"\"\" A good run ends with the validator’s output and a clear statement: is the app only prepared for deployment, or deployed and live? The word-cloud app loads its libraries from a CDN, so also check what the agent says about offline use — the skill tells it not to claim offline support it has not tested. 2 MCP: Model Context Protocol 2.1 Why MCP A skill teaches the agent how to do something with the tools it already has: reading and writing files, running commands. Some tasks need more: opening a web page in a real browser, reading issues on GitHub, querying a database, checking a calendar. The Model Context Protocol (MCP) is an open standard for giving an agent such new tools and data. Before MCP, every AI app needed its own connector for every service. With MCP, a service is wrapped once as an MCP server, and every agent that speaks MCP — Antigravity, Claude, ChatGPT and many code editors — can use it. It is often compared to USB-C: one plug for everything. 2.2 Anatomy of MCP Part What it is Example Host The AI app you use Antigravity Client The connection inside the host, one per server Antigravity’s link to the GitHub server Server A small program that offers capabilities The GitHub MCP server A server can offer three kinds of things: Tools — actions the agent can call, with named inputs: search_issues(query), take_screenshot(url). Resources — data the agent can read: a file, a database table, a codebook. Prompts — ready-made prompt templates the user can pick. Servers run in one of two ways (the transport): locally, as a program on your computer that the host starts and talks to (stdio), or remotely, at a web address (HTTP). One tool call goes like this: You ask: “Which issues are open in my repo?” The agent sees a matching tool in the server’s tool list and calls it, with inputs. Antigravity asks for your approval (unless you allowed that tool before). The server does the work and sends the result back. The agent reads the result and answers you — or calls the next tool. 2.3 Skills and MCP Skill MCP server Adds Know-how: steps, rules, checks Abilities and data: new tools Is Text (+ optional scripts) A running program Context cost Small until used Its tool list is loaded while it is on Write your own Easy: a Markdown file Some code (a few lines in Python) Use when You repeat a kind of task The agent cannot reach something it needs They work well together: a skill can say which MCP tools to use, and in what order. 2.4 Build a minimal MCP server A server in Python takes a few lines with the official MCP Python SDK. Each tool is an ordinary function: its name, type hints and docstring tell the agent what it does and which inputs it takes. This server offers two of the session 1 analyses as tools, plus the dataset’s codebook as a resource: server_code = ''' \"\"\"komp014 MCP server: quick analyses of a tab-separated data file.\"\"\" import pandas as pd from scipy import stats from mcp.server import MCPServer mcp = MCPServer(\"komp014\") @mcp.tool() def describe_tsv(url: str) -> dict: \"\"\"Rows, columns and the mean of every numeric column of a.tsv file.\"\"\" df = pd.read_csv(url, sep=\" \\\\ t\") means = df.select_dtypes(\"number\").mean().round(2) return {\"rows\": len(df), \"columns\": list(df.columns), \"means\": means.to_dict()} @mcp.tool() def group_difference(url: str, group: str, outcome: str) -> dict: \"\"\"Welch t-test and Cohen's d for the outcome between the two levels of group.\"\"\" df = pd.read_csv(url, sep=\" \\\\ t\") a, b = [g[outcome] for _, g in df.groupby(group)] t, p = stats.ttest_ind(a, b, equal_var=False) sd = ((a.var() * (len(a) - 1) + b.var() * (len(b) - 1)) / (len(a) + len(b) - 2)) ** 0.5 d = (a.mean() - b.mean()) / sd return {\"t\": round(float(t), 2), \"p\": round(float(p), 4), \"d\": round(float(d), 2)} @mcp.resource(\"komp014://codebook\") def codebook() -> str: \"\"\"What the columns of the komp014 toy dataset mean.\"\"\" return (\"IV_CAT_GROUP: category1/category2. Items 1-5: IV1_ITEM1, IV1_ITEM2, \" \"IV2_ITEM1, IV2_ITEM2, DV_ITEM1, DV_ITEM2. Indices are item means: \" \"IV_INDEX1, IV_INDEX2, DV_INDEX (outcome).\") if __name__ == \"__main__\": mcp.run() # local server: talks to the host over stdin/stdout ''' with open (\"komp014_server.py\", \"w\") as f: f.write(server_code) To use it, you need Python with the mcp package on your own computer (MCP servers run next to the agent, not in Colab). Try the server in the MCP Inspector, a web page where you can call its tools by hand, then add it to Antigravity and check that it is listed:! pip install \"mcp[cli]\" pandas scipy! mcp dev komp014_server.py! agy mcp add komp014 python / full / path / to / komp014_server.py! agy mcp list Then ask the agent something only the server can answer quickly: mcp_prompt = \"\"\" Use the komp014 tools: describe https://raw.githubusercontent.com/nils-holmberg/de-code/main/csv/komp014-simulated-data-n100.tsv and test whether DV_INDEX differs between the IV_CAT_GROUP levels. Explain the result in two sentences. \"\"\" The answer should report a Cohen’s d of size 0.58 (its sign shows which group scores higher) — the same effect as in session 1, now computed by a tool the agent called. 2.5 An MCP server for this website The de-code site has grown in many directions: workshop sessions with slides and notebooks, section pages, an installable app, a Shiny app and skill downloads — built with different tools, in different folders, and not all of them linked from the home page. Visitors rarely browse; they ask questions. As site managers, we can let an agent answer those questions from the site itself. The site already publishes two descriptions of everything on it: an llms.txt, a short table of contents written for AI agents, and a full content index with the text of every page. llms.txt is a list an agent can read; an MCP server adds search, so the agent asks for what it needs and gets back only the matching pages, with their links: What Kind What the agent gets list_sections() tool the site’s sections and their landing pages search_site(query, section, limit) tool the best-matching pages: title, link, type and a short snippet get_page(url) tool one page’s headings and text, to answer from its content site://llms.txt resource the overview of the whole site The server reads the content index once and keeps it in memory. Its search is deliberately simple — a match in a title counts more than one in the text, and a page that matches every word ranks first — and every tool returns a few short results instead of whole pages, which keeps the agent’s context window small (session 4). de_code_mcp_code = ''' \"\"\"de-code-mcp: an MCP server for finding pages on the de-code website in plain language.\"\"\" import json import os import re from urllib.request import urlopen from mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ToolError SITE = \"https://de-code-ai.netlify.app\" INDEX_SOURCE = os.environ.get(\"SITE_INDEX\", f\" {SITE} /site/index.json\") LLMS_SOURCE = os.environ.get(\"SITE_LLMS\", f\" {SITE} /llms.txt\") WEIGHTS = {\"title\": 5, \"headings\": 3, \"description\": 2, \"text\": 1, \"type\": 2} SKIP = {\"the\", \"and\", \"for\", \"can\", \"how\", \"what\", \"where\", \"which\", \"find\", \"site\", \"page\", \"about\"} mcp = MCPServer(\"de-code-mcp\") def read(source: str) -> str: \"\"\"Read a URL or a local file as text.\"\"\" if source.startswith(\"http\"): with urlopen(source, timeout=20) as response: return response.read().decode(\"utf-8\") with open(source, encoding=\"utf-8\") as f: return f.read() INDEX = json.loads(read(INDEX_SOURCE)) # loaded once, kept in memory PAGES = {page[\"url\"]: page for page in INDEX[\"pages\"]} def score(page: dict, words: list[str]) -> float: fields = {\"tit"
  },
  {
   "url": "https://de-code-ai.netlify.app/data-analysis/ailund.html",
   "path": "data-analysis/ailund.html",
   "title": "Data analysis",
   "description": "Democratizing data analysis with AI Lund: exploring the Quality of Government dataset with AI-assisted, natural language driven analysis. Run it yourself in the cloud, or read the full notebook below.",
   "section": "data-analysis",
   "type": "page",
   "stack": "html",
   "headings": [
    "de-code data analysis",
    "The notebook"
   ],
   "words": 40,
   "updated": "2026-08-22",
   "text": "de-code data analysis Democratizing data analysis with AI Lund: exploring the Quality of Government dataset with AI-assisted, natural language driven analysis. Run it yourself in the cloud, or read the full notebook below. Open in Colab Gemini session The notebook"
  },
  {
   "url": "https://de-code-ai.netlify.app/data-analysis.html",
   "path": "data-analysis.html",
   "title": "Democratizing data analysis with AI",
   "description": "de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise.",
   "section": "data-analysis",
   "type": "page",
   "stack": "html",
   "headings": [
    "Democratizing data analysis with AI",
    "What we de-code",
    "Start with a question"
   ],
   "words": 125,
   "updated": "2026-07-06",
   "text": "Democratizing data analysis with AI de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise. Explore services What we de-code de-code data analysis Turn questions into workflows for cleaning, analyzing, visualizing, and reporting data using AI-assisted methods. de-code data generation Generate realistic example datasets, simulations, test cases, and teaching materials through natural language prompts. de-code app building Build lightweight dashboards, prototypes, forms, and internal tools using AI-supported low-code development. Coding should not be limited to specialists. de-code makes computational work more accessible, explainable, and useful for everyone. Start with a question Bring your data, idea, or workflow problem. We help translate it into practical AI-assisted tools and methods. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/education/quarto.html",
   "path": "education/quarto.html",
   "title": "de-code education | Quarto markdown and notebooks",
   "description": "One source file holds the text, the code, and the output it produced. Quarto renders it to a report, a slide deck, or a website, and runs Python and R side by side, so the analysis and the writing about it stay in step.",
   "section": "education",
   "type": "page",
   "stack": "html",
   "headings": [
    "Quarto markdown and notebooks",
    "What the session covers",
    "Bring it to your organization"
   ],
   "words": 190,
   "updated": "2026-08-11",
   "text": "Quarto markdown and notebooks One source file holds the text, the code, and the output it produced. Quarto renders it to a report, a slide deck, or a website, and runs Python and R side by side, so the analysis and the writing about it stay in step. Book this session All education What the session covers Markdown that computes Write in plain markdown, drop in code cells, and render the document so every figure and number comes from the code that produced it. Python and R together Run both languages from the same document, pick whichever suits the task, and share data between cells without leaving the file. Notebooks to publication Take an existing Jupyter notebook and publish it as HTML, slides, or PDF, with output that can be rebuilt from source at any time. A document you can re-run is a document you can trust. Reproducible reporting is a practical skill, not a specialist one. Bring it to your organization Sessions run on site or over video meeting, for teams new to Quarto as well as groups already writing notebooks who want them reproducible and publishable. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/education/specs.html",
   "path": "education/specs.html",
   "title": "Specifications as code",
   "description": "de-code education on specifications as code for academics and public organizations.",
   "section": "education",
   "type": "page",
   "stack": "html",
   "headings": [
    "Specifications become code",
    "From written intent to working systems.",
    "Bring a real specification."
   ],
   "words": 229,
   "updated": "2026-09-14",
   "text": "de-code education Specifications become code PRDs, MVP specifications, acceptance criteria, and chat prompts are becoming executable interfaces. Instead of writing every line of code, teams describe what software should do and AI agents translate that intent into working systems. The craft shifts to precise, testable, and accountable specifications. View courses Plan a session Two ways into the paradigm From written intent to working systems. Both courses treat specifications as active working material: documents that guide AI-assisted building, make assumptions visible, and give teams something concrete to review and test. For academics Specification-driven research tools Turn research questions and methodological requirements into clear specifications for analyses, reproducible workflows, teaching tools, and small research applications. Move from research question to PRD, workflow, and acceptance criteria. Use prompts and AI agents to build and revise an MVP. Test outputs for validity, traceability, and reproducibility. Ask about the academic course For public organizations From service need to governed prototype Translate policy, service, and operational needs into specifications that multidisciplinary teams can inspect before AI-assisted tools are built or procured. Frame needs as user stories, constraints, and measurable outcomes. Prototype internal tools through structured prompts and MVP specs. Document responsibility, data boundaries, and quality checks. Ask about the public-sector course Bring a real specification. Courses can be shaped around a live research idea, service challenge, or early product concept from your organization. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/education.html",
   "path": "education.html",
   "title": "Education for institutions and public organizations",
   "description": "Educational services for institutions and public organizations, provided by resn.dev under the Democratizing coding with AI label (de-code-ai). Sessions are held on site in physical settings, or remotely over video …",
   "section": "education",
   "type": "page",
   "stack": "html",
   "headings": [
    "de-code education",
    "Quarto markdown and notebooks",
    "Start with a question"
   ],
   "words": 131,
   "updated": "2026-08-11",
   "text": "de-code education Educational services for institutions and public organizations, provided by resn.dev under the Democratizing coding with AI label (de-code-ai). Sessions are held on site in physical settings, or remotely over video meeting, and are built around the tools, data, and questions your teams already work with. See the Quarto session Quarto markdown and notebooks Learn to write documents where prose, code, and results live in one reproducible source file. Quarto turns markdown and notebooks into reports, slides, and websites, and runs Python and R from the same document, so an analysis and the text explaining it never drift apart. Explore the Quarto session Start with a question Tell us the setting, the audience, and the tools in use. We translate that into a session plan for your institution. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/",
   "path": "index.html",
   "title": "Democratizing coding with AI",
   "description": "de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise.",
   "section": "home",
   "type": "page",
   "stack": "html",
   "headings": [
    "Democratizing coding with AI",
    "What we de-code",
    "Start with a question"
   ],
   "words": 124,
   "updated": "2026-07-06",
   "text": "Democratizing coding with AI de-code helps people and organizations use natural language interfaces to analyze data, generate synthetic datasets, and build useful apps — without requiring traditional programming expertise. Explore services What we de-code de-code data analysis Turn questions into workflows for cleaning, analyzing, visualizing, and reporting data using AI-assisted methods. de-code data generation Generate realistic example datasets, simulations, test cases, and teaching materials through natural language prompts. de-code app building Build lightweight dashboards, prototypes, forms, and internal tools using AI-supported low-code development. Coding should not be limited to specialists. de-code makes computational work more accessible, explainable, and useful for everyone. Start with a question Bring your data, idea, or workflow problem. We help translate it into practical AI-assisted tools and methods. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/resn-dev/",
   "path": "resn-dev/index.html",
   "title": "resn.dev | Research and development by nilsh",
   "description": "resn.dev is the parent company behind de-code-ai: a growing set of AI-assisted coding practices that make computational work more open, practical, and approachable.",
   "section": "resn-dev",
   "type": "page",
   "stack": "html",
   "headings": [
    "resn.dev makes room for experiments.",
    "A parent for useful, unfinished ideas.",
    "One practice, several ways in.",
    "Explore the parent site and the research behind the work."
   ],
   "words": 159,
   "updated": "2026-08-11",
   "text": "research and development by nilsh resn.dev makes room for experiments. resn.dev is the parent company behind de-code-ai: a growing set of AI-assisted coding practices that make computational work more open, practical, and approachable. Visit resn.dev A parent for useful, unfinished ideas. de-code-ai is a subsidiary of resn.dev. It is where research becomes tangible: tools, methods, and learning spaces for democratizing coding with AI. The work is deliberately in motion, with room to test, learn, and build what proves useful. the current de-code-ai compartments One practice, several ways in. These are the working areas currently taking shape within de-code-ai. data analysis Questions, evidence, visualizations, and reports shaped with AI assistance. data generation Examples, simulations, and test data for exploration and teaching. app building Small interfaces, prototypes, and tools made from plain-language intent. agentic coding, mcp, and skills New ways to extend AI-assisted work with reusable context and capabilities. Explore the parent site and the research behind the work. Open resn.dev"
  },
  {
   "url": "https://de-code-ai.netlify.app/shiny/site/app1/",
   "path": "shiny/site/app1/index.html",
   "title": "Shiny app (Shinylive)",
   "description": "A Shiny for Python app that runs entirely in the browser with Shinylive.",
   "section": "app-building",
   "type": "app",
   "stack": "shinylive",
   "headings": [],
   "words": 0,
   "updated": "2026-06-25",
   "text": ""
  },
  {
   "url": "https://de-code-ai.netlify.app/workshop.html",
   "path": "workshop.html",
   "title": "de-code Workshop | Democratizing Coding with AI",
   "description": "Learn how to use AI and natural language interfaces to analyze data, generate datasets, and build useful applications without traditional coding barriers.",
   "section": "workshop",
   "type": "page",
   "stack": "html",
   "headings": [
    "Democratizing coding with AI",
    "About the workshop",
    "Five-day schedule",
    "Learning outcomes",
    "Workshop format",
    "Start with a question"
   ],
   "words": 288,
   "updated": "2026-05-05",
   "text": "5-Day Intensive Workshop Democratizing coding with AI Learn how to use AI and natural language interfaces to analyze data, generate datasets, and build useful applications without traditional coding barriers. View workshop schedule About the workshop de-code is a practical workshop for people who want to use AI-assisted workflows for computational work. Participants learn how to translate questions into analysis, prompts into datasets, and ideas into lightweight applications. The workshop combines short lectures, guided exercises, and a practical mini-project. Five-day schedule Day 1 Foundations: Thinking in AI-assisted workflows Introduction to AI-assisted coding, low-code paradigms, prompt-based workflows, and turning questions into executable steps. Day 2 de-code data analysis Clean, structure, analyze, visualize, and report data using natural language interfaces and AI-supported analytical workflows. Day 3 de-code data generation Generate synthetic datasets, simulations, test cases, and teaching examples from structured descriptions and prompts. Day 4 de-code app building Build lightweight dashboards, prototypes, forms, and internal tools by connecting data, logic, and user interaction. Day 5 Integration and application Combine analysis, generation, and app building into an end-to-end AI-assisted workflow, followed by mini-project presentations. Learning outcomes After the workshop, participants will be able to: Translate problems into AI-assisted workflows Analyze and visualize data using natural language Generate synthetic datasets for testing and teaching Build simple functional applications and prototypes Workshop format Short lectures Compact conceptual introductions to AI-assisted coding, data analysis, generation, and app building. Guided hands-on sessions Step-by-step exercises where participants turn natural language instructions into working computational outputs. Mini-project A small applied project where participants design and present their own de-code workflow. Start with a question Bring your data, idea, or workflow problem. Leave with a practical AI-assisted method for turning it into analysis, data, or an app. Contact de-code"
  },
  {
   "url": "https://de-code-ai.netlify.app/agentic-ai/mcps/de-code-mcp.zip",
   "path": "agentic-ai/mcps/de-code-mcp.zip",
   "title": "de-code-mcp (MCP server, zip)",
   "description": "MCP server that lets an AI agent search this website in plain language. Runs with uvx straight from GitHub, or with Python; see its README.",
   "section": "agentic-ai",
   "type": "download",
   "stack": "file",
   "headings": [],
   "words": 0,
   "updated": "2026-10-09",
   "text": ""
  },
  {
   "url": "https://de-code-ai.netlify.app/agentic-ai/skill-html-pwa.zip",
   "path": "agentic-ai/skill-html-pwa.zip",
   "title": "skill-html-pwa (agent skill, zip)",
   "description": "Agent skill that turns a single-page HTML app into an installable PWA and prepares it for Netlify. Unzip into .agents/skills/.",
   "section": "agentic-ai",
   "type": "download",
   "stack": "file",
   "headings": [],
   "words": 0,
   "updated": "2026-10-08",
   "text": ""
  }
 ]
}
