A framework for structured epistemic auditing in AI-generated analysis.
GoldBerry is a documentation-first open-source framework that helps any prompt-driven AI system look beyond the most obvious answer. It does this through seven analytical lenses and a linguistic diagnostic layer called the Suffixscape.
Today, this repository contains:
- the canonical GoldBerry identity files
- platform-specific prompt/integration examples
- a reference output schema
- case studies and evaluation scaffolding
- a minimal Python CLI for prompt assembly and output validation
GoldBerry is not, at this stage:
- a standalone model release
- a validated scientific measurement instrument
- a production SaaS platform
- a substitute for subject-matter expertise, lived experience, or direct consultation
GoldBerry is best understood as a structured audit framework: a way to surface what a response omits, flattens, overstates, or leaves historically ungrounded.
Large language models can produce fluent answers that feel complete while still being historically shallow, culturally flattened, power-blind, or rhetorically evasive. GoldBerry is designed to make those absences more visible.
It does this through:
- Seven lenses — recurring questions about knowledge, history, evidence, culture, power, feeling, and future consequences
- The Suffixscape — a linguistic diagnostic layer for nominalised evasion, agency diffusion, epistemic inflation, and temporal flatness
- A structured output format — so analyses can be compared, reviewed, and validated more consistently
GoldBerry currently has four stable core identity files:
agent-identity/SOUL.md— what GoldBerry is, what it is not, and how it frames its roleagent-identity/LENSES.md— the seven lenses and their satisfaction criteriaagent-identity/SUFFIXSCAPE.md— the linguistic diagnostic layeragent-identity/AGENTS.md— operating guidance for agents and deployment contexts
These files are the framework.
Everything else in the repository exists to make the framework easier to:
- inspect
- run
- compare
- evaluate
- contribute to
Load these files into your agent, in order:
agent-identity/SOUL.mdagent-identity/LENSES.mdagent-identity/SUFFIXSCAPE.mdagent-identity/AGENTS.md
Then give the agent a text, question, article, policy document, or webpage to analyse.
The Python package included here does not bundle a model. It helps you:
- assemble a GoldBerry prompt packet
- scaffold the expected response structure
- validate GoldBerry JSON outputs against the reference schema
Install locally:
python3 -m pip install -e .Build a prompt packet:
goldberry prompt --input "Analyse this policy memo"Scaffold a response template:
goldberry scaffold --input "Analyse this policy memo" --format jsonValidate a JSON output:
goldberry validate output.json| # | Lens | Corrects | Core question |
|---|---|---|---|
| 1 | 🌿 Indigenous Knowledge | Erasure of embodied and relational epistemologies | Whose knowledge is missing? |
| 2 | 📜 Deep History | Civilisational amnesia and temporal blindness | What historical process produced this? |
| 3 | 🌍 Cross-Cultural Wisdom | Universalist flattening of cultural difference | Which perspectives have been flattened? |
| 4 | 🔬 Scientific Evidence | Untethered speculation and scientism's blind spots | What does the evidence show, and what are its limits? |
| 5 | 🎨 Artistic Perception | Reduction of knowledge to propositions | What does this feel like, not just mean? |
| 6 | 🚀 Future Modelling | Static analysis that ignores trajectory | Where is this heading, and for whom? |
| 7 | 🤝 Marginalised Voices | Structural exclusion from knowledge production | Who is not at the table? |
The Suffixscape complements the lenses by flagging:
- nominalised evasion
- agency diffusion
- epistemic inflation
- temporal flatness
agent-identity/ Canonical framework files
examples/ Platform-specific prompt/integration examples
case-studies/ Worked examples with inputs, outputs, and commentary
evals/ Rubric, prompts, and evaluation scaffolding
schemas/ Reference JSON schema for GoldBerry outputs
src/goldberry/ Minimal Python package and CLI
tests/ Reference tests for prompt assembly and schema validation
site/ Static marketing/documentation page
GoldBerry is informed by real applied work, but this repository should not be read as an external validation dossier.
Read these in order if you want the trust surface:
PROVENANCE.md— where the framework came from, what is public, and what is not yet publicCLAIMS.md— which claims are inspectable, partial, or internal-onlyEVALUATION.md— how GoldBerry should be assessed and comparedevals/rubric.md— the reference rubric for judging outputsevals/RUNBOOK.md— how to reproduce the public comparison packevals/results/summary-table.md— current public comparison summary
Important limits:
- GoldBerry's scores are framework-internal qualitative judgements, not externally validated measurements.
- The framework is rooted in Western critical humanities, even where it argues for epistemic plurality.
- No prompt framework can substitute for direct engagement with the communities, traditions, or expertise it identifies as missing.
Start with:
For richer side-by-side comparisons, see:
case-studies/news-02-city-ai-traffic.mdcase-studies/policy-02-community-empowerment.mdcase-studies/research-02-ai-tutoring.md
These examples are designed to show:
- the kind of input GoldBerry is meant to work on
- what a flatter baseline response tends to do
- what GoldBerry-structured output adds
- where the framework still has limits
- how evaluator notes can justify improvement claims
Current maturity: early, but now structured for public inspection.
What exists:
- stable identity files
- portable examples
- revised provenance and claims documentation
- a reference schema
- a minimal CLI/tooling layer
- tests for core package behavior
What is still needed for a stronger v1.0:
- broader public case-study set
- benchmark comparisons across multiple models
- more robust human evaluation workflow
- richer integrations and optional hosted tooling
See ROADMAP.md.
Contributions are welcome, especially in these areas:
- worked examples and case studies
- eval methodology improvements
- platform integrations
- documentation clarity
- rigorously argued lens-extension proposals
Please read:
This repository is released under the MIT licence. See LICENCE.
Because GoldBerry is also a named framework with public-facing branding and methodological claims, please also read LICENSE-NOTES.md for plain-English guidance on reuse, attribution, and what the repository does and does not claim.
Goldberry is the River-woman's daughter in Tolkien's The Lord of the Rings — a figure associated with dwelling, seasonality, memory, and a mode of attention that resists pure instrumentality. The name is used here to point toward what gets cut when systems are optimised only for speed, convenience, and surface plausibility.
The framework points toward the river. The river is not in the framework.
