Knowledge Tagging — Step 4.7
Purpose
Extract structured knowledge from every panel's narration and scene direction. This is the intelligence layer that feeds the knowledge graph. Every moment carries entities, causality, emotion, visual elements, and logic. The AI that wrote the content extracts the knowledge — not a weaker NLP tool after the fact.
When This Runs
After Step 4 (Scene Direction), before Step 5 (Art Selection). Can also be run retroactively on completed projects to backfill.
Inputs: script.md, scene-plan.md, investigation.json (if assembly already done)
Output: knowledge.json in the project folder
Schema: knowledge.json
{
"project_id": "bretton-woods-blueprint",
"title": "The Bretton Woods Blueprint",
"version": 1,
"panels": [
{
"panel_id": "panel-01",
"entities": {
"people": [
{"name": "John Maynard Keynes", "role": "British economist", "significance": "high"}
],
"places": [
{"name": "Mount Washington Hotel", "context": "Bretton Woods conference venue, New Hampshire"}
],
"institutions": [
{"name": "IMF", "type": "financial institution", "relationship": "created at this conference"}
],
"concepts": [
{"name": "reserve currency", "category": "monetary system"}
],
"events": [
{"name": "Bretton Woods Conference", "date": "July 1944", "significance": "designed postwar financial order"}
],
"mechanisms": [
{"name": "dollar-gold peg", "category": "monetary mechanism", "description": "$35/oz fixed rate"}
],
"systems": [
{"name": "Bretton Woods System", "status": "created here, collapsed 1971"}
],
"commodities": [
{"name": "gold", "role": "monetary anchor"}
]
},
"causality": [
{"from": "US gold reserves", "relation": "enabled", "to": "dollar as reserve currency"},
{"from": "British war debt", "relation": "weakened", "to": "Keynes negotiating position"}
],
"emotion": "institutional tension",
"visual_elements": ["grand hotel ballroom", "delegates in suits", "document-heavy tables", "ashtrays"],
"logic": "Power determined the outcome — the nation with the gold made the rules"
}
],
"project_knowledge": {
"entities": {
"people": [],
"places": [],
"institutions": [],
"concepts": [],
"events": [],
"mechanisms": [],
"systems": [],
"commodities": []
},
"causal_chains": [
{
"name": "Institutional Power Flow",
"description": "How the Bretton Woods conference created a chain of institutional dependency from conference to debt trap",
"steps": ["Bretton Woods Conference", "IMF creation", "conditionality", "structural adjustment", "debt dependency"],
"panels": [3, 5, 8, 11, 15]
}
],
"causal_trees": [
{
"root": "oil price spike",
"branches": [
{
"path": ["power cuts", "factory shutdowns", "job losses", "wage depression"],
"type": "economic cascade"
},
{
"path": ["demand for solar", "energy transition investment", "new industries"],
"type": "substitution cascade"
},
{
"path": ["agricultural cost increase", "food price inflation", "social unrest"],
"type": "livelihood cascade"
},
{
"path": ["inflation spike", "central bank rate hike", "credit contraction", "recession"],
"type": "monetary cascade"
}
]
}
],
"themes": ["asymmetric design", "creditor dominance", "institutional architecture as power"],
"emotions": {
"dominant": ["institutional cold", "revelation", "quiet outrage"],
"arc": "curiosity → discovery → systemic understanding → present-day implications"
},
"cross_project_links": [
{"project": "petrodollar-pact", "relationship": "Bretton Woods collapse enabled petrodollar system", "type": "causal"},
{"project": "imf-the-lender-of-last-resort", "relationship": "Bretton Woods created the IMF", "type": "causal"},
{"project": "gdp-the-number-that-rules-the-world", "relationship": "Bretton Woods adopted GDP as benchmark", "type": "institutional"}
]
}
}
Entity Categories
| Category | What It Captures | Examples |
|---|
| people | Named individuals with role and significance | Simon Kuznets (economist, high), Henry Kissinger (diplomat, high) |
| places | Locations with context for WHY they matter | Mount Washington Hotel (conference venue), Jekyll Island (Fed origin) |
| institutions | Organizations, agencies, companies | IMF, World Bank, WTO, Federal Reserve, United Fruit Company |
| concepts | Abstract ideas, metrics, theories | GDP, life expectancy, sustainability, bancor, conditionality |
| events | Named historical moments with dates | Bretton Woods Conference 1944, Volcker Shock 1979, Nixon Shock 1971 |
| mechanisms | How power operates — the machinery | structural adjustment, dollar-gold peg, petrodollar recycling |
| systems | Large-scale architectures of control | Bretton Woods System, petrodollar system, central banking system |
| commodities | Physical things that matter to the system | gold, oil, water, wheat, opium |
Causal Trees (Branching Cascades)
Real-world causality is not linear. One event triggers multiple parallel cascading effects. causal_chains capture linear sequences. causal_trees capture branching cascades.
Example: An oil price spike doesn't just cause inflation. It causes:
- Power cuts → factory shutdowns → job losses → wage depression
- Demand for solar → energy transition investment → new industries
- Agricultural cost increase → food price inflation → social unrest
- Inflation spike → central bank rate hike → credit contraction → recession
Each branch is a different domain of impact (economic, substitution, livelihood, monetary). The graph builder renders these as branching directed edges from a single root node.
When to use causal_trees vs causal_chains:
causal_chains: single linear sequence (A → B → C → D)causal_trees: one root event with multiple branching consequences
Tree types:
| Type | What It Captures |
|---|
economic cascade | Job losses, wage effects, industrial impact |
substitution cascade | Alternative demand triggered by scarcity |
livelihood cascade | Impact on agriculture, food, daily survival |
monetary cascade | Central bank response, credit, currency effects |
political cascade | Government response, elections, policy shifts |
social cascade | Protests, migration, community breakdown |
environmental cascade | Resource depletion, climate feedback loops |
Causality Types
Each causal link has a relation field. Use these relation types:
| Relation | Meaning | Example |
|---|
created | X brought Y into existence | Bretton Woods → created → IMF |
enabled | X made Y possible | US gold reserves → enabled → dollar hegemony |
caused | X directly led to Y | Structural adjustment → caused → debt trap |
enforced | X maintained Y through power | IMF → enforced → conditionality |
weakened | X diminished Y | War debt → weakened → British negotiating power |
replaced | X took over from Y | Dollar → replaced → gold standard |
resisted | X fought against Y | Bolivia → resisted → water privatization |
triggered | X set off Y as chain reaction | Oil embargo → triggered → petrodollar deal |
funded | X financially supported Y | Petrodollar recycling → funded → US deficit spending |
warned_against | X predicted danger of Y | Kuznets → warned_against → GDP as welfare measure |
collapsed | X fell apart, enabling Y | Bretton Woods → collapsed → floating exchange rates |
legitimized | X gave Y authority/cover | GDP growth → legitimized → austerity policies |
Emotion Vocabulary
Use precise emotional registers, not generic feelings:
| Register | When to Use |
|---|
institutional cold | Power operating without human face |
quiet outrage | Systemic injustice revealed without shouting |
tragic irony | The intended outcome was the opposite |
revelation | A hidden mechanism exposed |
calculated menace | Power wielded deliberately |
human cost | Abstractions become suffering |
defiance | Resistance against the system |
grim recognition | Realizing the pattern hasn't changed |
dark humor | The absurdity of power |
documentary gravity | Weight of historical consequence |
Visual Elements
Extract from scene-plan.md or image prompts. These are what the viewer would SEE:
- Physical objects: "stack of documents", "gold bars", "oil pipeline map"
- People/figures: "elderly economist", "suited delegates", "farmer in drought"
- Settings: "hotel ballroom", "trading floor", "devastated neighborhood"
- Symbolic elements: "green GDP numbers on screen", "split-frame contrast"
- Composition: "low angle looking up at monitors", "aerial devastation view"
Logic Field
One sentence that captures the ARGUMENT this panel makes. Not what happens — WHY it matters:
- "The nation with the gold made the rules"
- "A measurement tool became a weapon of control"
- "Resistance is possible but the architecture remains"
- "The system was designed to be asymmetric — this wasn't an accident"
When generating knowledge.json for a project, use this prompt structure:
Read the following narration and scene direction for panel {panel_id}.
NARRATION:
{narration_text}
SCENE DIRECTION:
{scene_direction_text}
Extract structured knowledge:
1. ENTITIES — list every person, place, institution, concept, event, mechanism, system, and commodity mentioned or implied. Include role/context for each.
2. CAUSALITY — what causal relationships does this panel establish or reference? Use relation types: created, enabled, caused, enforced, weakened, replaced, resisted, triggered, funded, warned_against, collapsed, legitimized.
3. EMOTION — what is the dominant emotional register? Use: institutional cold, quiet outrage, tragic irony, revelation, calculated menace, human cost, defiance, grim recognition, dark humor, documentary gravity.
4. VISUAL ELEMENTS — what would the viewer SEE? Physical objects, people, settings, symbolic elements.
5. LOGIC — one sentence: what argument does this panel make? Not what happens — why it matters.
Output as JSON matching the panel schema.
Project-Level Aggregation
After all panels are tagged:
- Merge entities — deduplicate across panels, keep richest description
- Build causal chains — connect panel-level causality into multi-step chains
- Identify themes — what patterns recur across the narrative?
- Map emotion arc — how does the emotional register shift across the investigation?
- Find cross-project links — which entities/systems appear in other GatorSquare projects?
Quality Gates
- Every panel MUST have at least 1 entity
- Every panel with narration about cause/effect MUST have causality entries
- Every panel MUST have an emotion tag
- Every panel MUST have visual_elements (even text-only projects — describe what WOULD be seen)
- Every panel MUST have a logic sentence
- Project-level MUST have at least 1 causal chain
- Project-level MUST have cross_project_links if shared entities exist
How build-knowledge-graph.py Uses This
The graph builder reads knowledge.json from each project:
- Nodes — every unique entity becomes a node, typed by category
- Edges — causality entries become DIRECTED edges with relation type
- Project nodes — connect to their entities via panel membership
- Cross-project edges — explicit links between projects with relationship description
- Edge weights — entities appearing in more panels = stronger connection
- Emotion metadata — stored on edges/nodes for future visualization (heat mapping)
No more spaCy guessing. No more NLP extraction. The AI that understood the content tags the knowledge.