Build a Grammar and Pronunciation Enrichment Pipeline for Tagalog Cards with Kiro Workshop

Audience: professional developers building content-enrichment pipelines and educational tooling
Duration: 2 hours
Primary AWS AI service: Kiro
Project output: a Kiro-guided deterministic enrichment pipeline that adds grammar breakdowns and pronunciation guides to Tagalog cards.

Workshop Summary

This workshop guides developers through enriching Tagalog cards with grammar notes and pronunciation support. Participants use Kiro to define deterministic boundaries, build glossaries, generate helper text, patch structured content or HTML, and validate coverage. The exercises emphasize reviewable language assistance: automation can prepare explanations, but human oversight keeps learner-facing grammar, sound guidance, and examples clear, accurate, consistent, and useful overall.

Workshop objective

Developers build a pipeline that extracts Tagalog sentences, adds grammar explanations, generates pronunciation guides, patches HTML or structured card data, and validates coverage.

2-hour agenda

Step 1 — Create Kiro steering for enrichment boundaries

Developer action

1. Generate steering docs in Kiro.
2. Add enrichment-specific rules.
3. Ask Kiro what should be deterministic and what needs review.
4. Commit steering before writing scripts.

Kiro prompt sample

Create steering docs for a Tagalog grammar and pronunciation enrichment pipeline. Use deterministic Python helpers, topic glossaries, pronunciation maps, fallback rules, BeautifulSoup patching, validation checks, and native-speaker review reminders.

System design decision

1. Make Step 1 — Create Kiro steering for enrichment boundaries explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — .kiro/steering/enrichment.md

# Enrichment Steering

- Keep grammar and pronunciation enrichment deterministic.
- Use glossary dictionaries for known words.
- Use pronunciation maps for common words.
- Use transparent fallback rules for unknown words.
- Do not rewrite the Tagalog sentence during enrichment.
- Mark helper output as draft until native-speaker reviewed.
- Print validation counts after every batch.

Code explanation

• Business logic: The steering file defines enrichment scope and quality expectations.
• Code logic: Kiro uses the file as persistent context when generating scripts, tests, hooks, and docs.
• Expected result: Kiro-generated enrichment code should preserve Tagalog sentences and add reviewable helper sections.

Step 2 — Build a local grammar glossary

Developer action

1. Create glossary.py.
2. Add common words and event loanwords.
3. Add transparent fallback behavior.
4. Ask Kiro to generate glossary tests.

Kiro prompt sample

Create a beginner-friendly Tagalog glossary module. Include po, opo, saan, ang, paki, puwede, salamat, tubig, bayad, workshop, badge, registration, volunteer. Return short explanations and fallback text for unknown words.

System design decision

1. Make Step 2 — Build a local grammar glossary explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — glossary.py

import re

DEFINITIONS = {
    "po": "politeness marker used to show respect",
    "opo": "polite form of yes",
    "saan": "where; asks for a place or direction",
    "ang": "focus marker before the main noun or idea",
    "paki": "please; softens a request",
    "puwede": "may or can",
    "salamat": "thank you",
    "tubig": "water",
    "bayad": "payment",
    "workshop": "English loanword used locally for a workshop session",
    "registration": "English loanword used for event check-in"
}

def token_key(word):
    return re.sub(r"[^a-zA-ZñÑáéíóúÁÉÍÓÚ]", "", word).lower()

def explain_word(word):
    key = token_key(word)
    return DEFINITIONS.get(key, f"needs review; useful local word: {word}")

def grammar_breakdown(sentence):
    seen = set()
    output = []
    for word in sentence.split():
        key = token_key(word)
        if key and key not in seen:
            seen.add(key)
            output.append((word.strip(".,?!"), explain_word(word)))
    return output[:6]

Code explanation

• Business logic: The glossary creates consistent beginner grammar notes for known words and transparent fallback notes for unknown words.
• Code logic: It normalizes tokens, checks a dictionary, avoids duplicates, and returns up to six word explanations.
• Expected result: Calling grammar_breakdown('Saan po ang registration?') returns explanations for Saan, po, ang, and registration.

Step 3 — Generate pronunciation with curated and fallback rules

Developer action

1. Create pronunciation.py.
2. Add curated pronunciations for high-frequency words.
3. Add vowel fallback for unknown words.
4. Ask Kiro to test known and unknown tokens.

Kiro prompt sample

Create a pronunciation helper for Tagalog cards. Use curated pronunciations for common words and transparent fallback rules for unknown words. Return a full guide and word-level chunks.

System design decision

1. Make Step 3 — Generate pronunciation with curated and fallback rules explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — pronunciation.py

import re

PRON = {"salamat": "sah-lah-maht", "po": "poh", "saan": "sah-ahn", "kayo": "kah-yoh", "tubig": "too-beeg", "bayad": "bah-yahd", "pumasok": "poo-mah-sohk"}
VOWELS = {"a": "ah", "e": "eh", "i": "ee", "o": "oh", "u": "oo"}

def clean(word):
    return re.sub(r"[^a-zA-ZñÑ]", "", word).lower()

def fallback(word):
    return "".join(VOWELS.get(ch, ch) for ch in clean(word)) or word

def pronounce_word(word):
    return PRON.get(clean(word), fallback(word))

def pronunciation_guide(sentence):
    chunks = [(w.strip(".,?!"), pronounce_word(w)) for w in sentence.split() if clean(w)]
    return {"full": " ".join(sound for _, sound in chunks), "chunks": chunks}

Code explanation

• Business logic: The helper gives every Tagalog sentence a pronunciation guide for practice.
• Code logic: Known words use curated values; unknown words use vowel fallback; output includes full and chunked forms.
• Expected result: Calling pronunciation_guide('Paki-check po kung pumasok ang bayad.') returns a readable guide and word chunks.

Step 4 — Add glossary coverage reporting

Developer action

1. Scan all Tagalog sentences.
2. Count known and unknown tokens.
3. Export frequent unknown words.
4. Ask Kiro to suggest glossary additions for reviewer approval.

Kiro prompt sample

Create a glossary coverage report. Scan Tagalog sentences, count words not found in the glossary, rank unknown tokens by frequency, and export a JSON report for reviewer approval. Do not automatically add definitions without review.

System design decision

1. Make Step 4 — Add glossary coverage reporting explicit before coding: Professional developers should not rely on hidden assumptions when using AI-assisted engineering. The workshop first writes the rule into steering or specs so Kiro has durable project context. This makes generated code more consistent, gives reviewers something concrete to inspect, and prevents repeated explanation in every chat. The decision also helps new developers understand why a file exists, what problem it solves, and which behavior is allowed or disallowed.
2. Keep the implementation deterministic and reviewable: Kiro can help generate code, tests, and documentation, but the workshop output should be reproducible. Deterministic scripts, explicit configuration, stable schemas, and validation reports make the result easier to debug. When every transformation has a visible input and output, developers can review diffs, rerun checks, and explain the system to another engineer. This is especially important for language-learning content where correctness and cultural context require human review.
3. Attach validation to the workflow, not only the final demo: The workshop treats validation as part of system design. Each step has a check, a report, or a hook so defects appear close to the change that caused them. This approach lets Kiro act as a coding assistant and quality reviewer while developers stay in control. The result is a practical professional workflow: plan with specs, guide with steering, implement in small tasks, validate output, and document handoff.

Code sample — glossary_coverage.py

import json
from collections import Counter
from glossary import DEFINITIONS, token_key

def coverage_report(sentences, output="glossary-coverage.json"):
    unknown = Counter()
    total = 0
    for sentence in sentences:
        for word in sentence.split():
            key = token_key(word)
            if not key:
                continue
            total += 1
            if key not in DEFINITIONS:
                unknown[key] += 1
    payload = {"totalTokens": total, "knownDefinitionCount": len(DEFINITIONS), "unknownTokenCount": sum(unknown.values()), "topUnknown": unknown.most_common(30)}
    with open(output, "w", encoding="utf-8") as file:
        json.dump(payload, file, indent=2, ensure_ascii=False)
    return payload

Code explanation

• Business logic: The report tells developers and reviewers which glossary gaps are most important.
• Code logic: It tokenizes sentences, compares normalized tokens with glossary keys, counts unknown words, and writes JSON output.
• Expected result: Running the report produces a ranked list of unknown tokens that reviewers can approve for future definitions.

Additional Hands-on Developer Labs

These labs are unique to Workshop 5 — Grammar and Pronunciation Enrichment Pipeline. They extend the deterministic enrichment workflow with glossary governance, pronunciation confidence, patch provenance, reviewer exports, and regression checks. The focus is enrichment quality, not general workspace setup.

Hands-on Lab A — Add glossary decision states for reviewer governance

Developer action

• Ask Kiro to extend the glossary from a simple definition map into reviewable records.
• Add decision states for approved, needs-review, and blocked.
• Update explain_word so blocked words do not produce learner-facing explanations.
• Generate tests for approved, unknown, and blocked glossary entries.

Kiro prompt sample

Refactor the glossary into reviewable glossary records.
Each record should include definition, partOfSpeech, decisionState, reviewerNote, and lastReviewedAt.
Approved entries may appear in learner output.
Needs-review entries should be marked draft.
Blocked entries should be excluded from learner-facing grammar notes.
Create tests for all decision states.

System design decision

• Glossary governance protects learner output: Grammar explanations are teaching content, so a word definition needs review status, not only text.
• Blocked entries must fail closed: If a reviewer blocks an explanation, the enrichment pipeline should omit it or label it safely instead of publishing it.
• Structured records support future review tools: A record shape can be exported to CSV, reviewed by native speakers, and imported back into the pipeline.

Code sample — glossary_records.py

from dataclasses import dataclass, asdict
from typing import Literal

DecisionState = Literal["approved", "needs-review", "blocked"]

@dataclass(frozen=True)
class GlossaryRecord:
    term: str
    definition: str
    partOfSpeech: str
    decisionState: DecisionState = "needs-review"
    reviewerNote: str = "Needs native-speaker review."
    lastReviewedAt: str | None = None

GLOSSARY: dict[str, GlossaryRecord] = {
    "po": GlossaryRecord(
        term="po",
        definition="politeness marker used to show respect",
        partOfSpeech="particle",
        decisionState="approved",
        reviewerNote="Common beginner-safe explanation.",
        lastReviewedAt="2026-06-01"
    ),
    "bayad": GlossaryRecord(
        term="bayad",
        definition="payment",
        partOfSpeech="noun",
        decisionState="needs-review"
    )
}

def learner_definition(term: str) -> dict:
    record = GLOSSARY.get(term.lower())
    if record is None:
        return {"term": term, "definition": "needs review", "decisionState": "needs-review"}
    if record.decisionState == "blocked":
        return {"term": record.term, "definition": "blocked from learner output", "decisionState": "blocked"}
    return asdict(record)

Code explanation

• Business logic: The record model separates approved learner content from draft or blocked explanations.
• Code logic: GlossaryRecord stores review metadata, and learner_definition returns safe output based on decision state.
• Expected result: Enrichment can continue while clearly marking which glossary notes are approved, draft, or blocked.

Hands-on Lab B — Add pronunciation confidence and reviewer flags

Developer action

• Ask Kiro to add confidence metadata to pronunciation output.
• Mark curated pronunciations as high confidence and fallback pronunciations as low confidence.
• Export low-confidence tokens for review.
• Add a validation threshold for the maximum allowed low-confidence token ratio.

Kiro prompt sample

Add pronunciation confidence to the pronunciation helper.
Curated map entries should return confidence high.
Fallback entries should return confidence low and reviewRequired true.
Create a report of low-confidence tokens by frequency.
Fail validation if more than 25 percent of token pronunciations are low confidence.

System design decision

• Fallback output should be transparent: A fallback pronunciation is useful for coverage but should not appear equally trusted as curated guidance.
• Confidence supports prioritization: Reviewers can focus on high-frequency low-confidence tokens first.
• Thresholds make quality measurable: The pipeline can fail when too much output depends on fallback rules.

Code sample — pronunciation_confidence.py

import re
from collections import Counter

PRON = {"salamat": "sah-lah-maht", "po": "poh", "saan": "sah-ahn"}
VOWELS = {"a": "ah", "e": "eh", "i": "ee", "o": "oh", "u": "oo"}


def clean(word: str) -> str:
    return re.sub(r"[^a-zA-ZñÑ]", "", word).lower()


def fallback(word: str) -> str:
    return "".join(VOWELS.get(ch, ch) for ch in clean(word)) or word


def pronounce_token(word: str) -> dict:
    key = clean(word)
    if key in PRON:
        return {"word": word, "sound": PRON[key], "confidence": "high", "reviewRequired": False}
    return {"word": word, "sound": fallback(word), "confidence": "low", "reviewRequired": True}


def low_confidence_report(sentences: list[str]) -> dict:
    low = Counter()
    total = 0
    for sentence in sentences:
        for word in sentence.split():
            result = pronounce_token(word)
            if clean(word):
                total += 1
            if result["confidence"] == "low":
                low[clean(word)] += 1
    return {"totalTokens": total, "lowConfidenceTokens": sum(low.values()), "topLowConfidence": low.most_common(20)}

Code explanation

• Business logic: Pronunciation output now tells reviewers which guidance is curated and which needs review.
• Code logic: The helper returns structured token metadata and a ranked report of low-confidence words.
• Expected result: The enrichment pipeline can produce full pronunciation coverage while prioritizing human review.

Hands-on Lab C — Add enrichment provenance to every patched card

Developer action

• Ask Kiro to stamp each enriched card with pipeline version, source file, card ID, and enrichment timestamp.
• Render provenance as a hidden comment or structured JSON sidecar.
• Add validation that every enriched card has provenance.
• Generate a diff report that lists newly enriched cards.

Kiro prompt sample

Add enrichment provenance to HTML patching.
For every card patched with grammar or pronunciation, record cardId, sourceFile, enrichmentVersion, enrichedAt, grammarTermCount, and pronunciationTokenCount.
Write provenance to enrichment-provenance.json and validate that every patched card appears in it.

System design decision

• Patching needs traceability: When HTML is modified after generation, developers need to know which script changed which card.
• Sidecar files avoid UI clutter: Reviewers and developers can inspect provenance without adding noise to learner-facing pages.
• Versioning supports regression review: A changed enrichment version can trigger targeted review of affected cards.

Code sample — enrichment_provenance.py

from datetime import datetime, timezone
import json
from pathlib import Path

ENRICHMENT_VERSION = "grammar-pron-v1"


def provenance_record(card_id: str, source_file: str, grammar_terms: int, pronunciation_tokens: int) -> dict:
    return {
        "cardId": card_id,
        "sourceFile": source_file,
        "enrichmentVersion": ENRICHMENT_VERSION,
        "enrichedAt": datetime.now(timezone.utc).isoformat(),
        "grammarTermCount": grammar_terms,
        "pronunciationTokenCount": pronunciation_tokens
    }


def write_provenance(records: list[dict], path: str = "enrichment-provenance.json") -> None:
    ordered = sorted(records, key=lambda item: (item["sourceFile"], item["cardId"]))
    Path(path).write_text(json.dumps(ordered, indent=2, ensure_ascii=False), encoding="utf-8")

Code explanation

• Business logic: Provenance makes enrichment patches auditable after the workshop.
• Code logic: Records are sorted for stable diffs and written as UTF-8 JSON.
• Expected result: Reviewers can trace each grammar/pronunciation section back to a source file and pipeline version.

Hands-on Lab D — Build a grammar-note length and readability validator

Developer action

• Ask Kiro to create readability rules for beginner grammar notes.
• Limit each definition to a short phrase or sentence.
• Flag notes that contain advanced terminology unless approved.
• Export failures with card ID, term, and reason.

Kiro prompt sample

Create a validator for beginner-friendly grammar notes.
Each definition should be at most 18 words.
Flag advanced terms such as enclitic, absolutive, ergative, morphosyntax, and aspect unless allowAdvanced is true.
Return JSON failures with cardId, term, definition, and reason.

System design decision

• Beginner readability is testable: Grammar notes can be mechanically checked for length and advanced terminology.
• Validators complement human review: The script catches obvious complexity before reviewers spend time on nuance.
• Allowlist keeps flexibility: Advanced notes can still exist when deliberately approved.

Code sample — validate_grammar_notes.py

ADVANCED_TERMS = {"enclitic", "absolutive", "ergative", "morphosyntax", "aspect"}


def word_count(text: str) -> int:
    return len([part for part in text.split() if part.strip()])


def validate_note(card_id: str, term: str, definition: str, allow_advanced: bool = False) -> list[dict]:
    failures = []
    if word_count(definition) > 18:
        failures.append({"cardId": card_id, "term": term, "reason": "definition too long"})
    lowered = definition.lower()
    if not allow_advanced:
        blocked = sorted(word for word in ADVANCED_TERMS if word in lowered)
        if blocked:
            failures.append({"cardId": card_id, "term": term, "reason": f"advanced terminology: {', '.join(blocked)}"})
    return failures

Code explanation

• Business logic: The validator keeps helper text suitable for beginners.
• Code logic: It checks word count and blocked advanced terms, returning structured failures.
• Expected result: Long or overly technical grammar notes are flagged before publication.

Hands-on Lab E — Create enrichment snapshot tests for HTML patching

Developer action

• Ask Kiro to create a small fixture HTML file with one card.
• Run the patcher against the fixture.
• Assert that grammar, pronunciation, review note, and provenance markers exist.
• Avoid full-page snapshots unless the patcher is intentionally layout-sensitive.

Kiro prompt sample

Create regression tests for the HTML enrichment patcher.
Use a tiny fixture with one card and one Natural Tagalog span.
After patching, assert that grammar breakdown, pronunciation guide, draft review note, and card provenance marker are present.
Do not compare the entire HTML document.

System design decision

• Patchers are easy to break: A small selector change can silently stop enrichment from appearing.
• Targeted assertions reduce brittleness: Tests should protect required sections without failing on harmless formatting changes.
• Fixture-driven tests document assumptions: Future developers can see the expected HTML shape.

Code sample — tests/test_enrichment_patch.py

from bs4 import BeautifulSoup


def add_enrichment(html_text: str) -> str:
    soup = BeautifulSoup(html_text, "html.parser")
    card = soup.select_one(".sentence-card")
    grammar = soup.new_tag("section", **{"class": "grammar-breakdown"})
    grammar.string = "Grammar breakdown: draft"
    pronunciation = soup.new_tag("section", **{"class": "pronunciation-guide"})
    pronunciation.string = "Pronunciation guide: draft"
    card.append(grammar)
    card.append(pronunciation)
    card.append(soup.new_string("\n<!-- enrichmentVersion: grammar-pron-v1 -->\n"))
    return str(soup)


def test_patcher_adds_required_enrichment_sections():
    html = "<article class='sentence-card'><span lang='tl'>Saan po?</span></article>"
    patched = add_enrichment(html)
    assert "grammar-breakdown" in patched
    assert "pronunciation-guide" in patched
    assert "enrichmentVersion: grammar-pron-v1" in patched

Code explanation

• Business logic: The test protects required enrichment sections in generated cards.
• Code logic: A minimal fixture is patched and checked with targeted assertions.
• Expected result: Selector or patcher regressions are caught before a full batch run.

Hands-on Lab F — Export a reviewer packet for enrichment decisions

Developer action

• Ask Kiro to combine glossary gaps, low-confidence pronunciations, and long grammar notes into one reviewer packet.
• Write both JSON and CSV outputs.
• Include suggestedAction values such as approve-definition, fix-pronunciation, and shorten-note.
• Add a summary count by action type.

Kiro prompt sample

Create an enrichment reviewer packet.
Combine glossary unknowns, low-confidence pronunciation tokens, and grammar-note readability failures.
Export enrichment-review-packet.json and enrichment-review-packet.csv.
Each row should include issueType, tokenOrTerm, exampleSentence, frequency, suggestedAction, and reviewerDecision.

System design decision

• Review packets reduce reviewer friction: A single artifact is easier to review than separate console outputs.
• Suggested actions make triage faster: Reviewers can approve, correct, block, or request rewrite without interpreting raw validation logs.
• Empty reviewerDecision preserves human authority: The pipeline prepares work but does not claim final approval.

Code sample — review_packet.py

import csv
import json
from collections import Counter
from pathlib import Path

COLUMNS = ["issueType", "tokenOrTerm", "exampleSentence", "frequency", "suggestedAction", "reviewerDecision"]


def write_review_packet(rows: list[dict], json_path="enrichment-review-packet.json", csv_path="enrichment-review-packet.csv") -> dict:
    summary = Counter(row["suggestedAction"] for row in rows)
    payload = {"summary": dict(summary), "items": rows}
    Path(json_path).write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
    with open(csv_path, "w", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=COLUMNS)
        writer.writeheader()
        for row in rows:
            writer.writerow({column: row.get(column, "") for column in COLUMNS})
    return {"json": json_path, "csv": csv_path, "summary": dict(summary)}

Code explanation

• Business logic: The reviewer packet converts enrichment issues into reviewable work items.
• Code logic: It writes stable JSON and CSV outputs and summarizes suggested actions.
• Expected result: Native-speaker and curriculum reviewers can work from one consolidated packet.

Reference architecture notes

• Kiro capabilities emphasized in this workshop: enrichment steering, deterministic glossary records, pronunciation confidence reporting, HTML patch provenance, validation generation, fixture-based regression tests, and reviewer-packet documentation.
• Product scope: grammar and pronunciation helper text for Tagalog learning cards. Helper output remains draft until reviewed by native Tagalog speakers.
• Runtime scope: local Python enrichment pipeline first. Optional automation can later run the same validators in CI before packaging static learning artifacts.