# Attribution: who composed each line

lines.author names the voice (Guru, Bhagat, Bhatt or Gursikh) of every line. It is metadata about the scripture and never changes a character of it. This page explains where the value comes from an…

- Page: <https://docs.gurbanisoul.com/data/architecture/attribution/>
- Updated: 2026-10-27
- Pinned copy of `Algorythmos-AI/sggs-data` `docs/architecture/attribution.md` at `c36e317`; the canonical file is <https://github.com/Algorythmos-AI/sggs-data/blob/c36e3172bdf38a61070849bb604b38da89ca5d8b/docs/architecture/attribution.md>
- From the Sri Guru Granth Sahib Ji — Knowledge Base wiki. Sri Guru Granth Sahib Ji is quoted verbatim, cited by Ang, and never altered.

---

`lines.author` names the voice (Guru, Bhagat, Bhatt or Gursikh) of every line. It is metadata
*about* the scripture and never changes a character of it. This page explains where the value
comes from and how it is proven.

## Why a dedicated pass

`build_corpus.py` reads a composition's author from its heading and carries it forward until the
next heading that names someone. Several kinds of printed evidence were not read, so authorship
"bled" from one composition into the next. A line-level audit (2026-10-23) against an independent
edition found 1,047 lines affected, for example:

- Baba Sheikh Farid Ji's saloks (Angs 1377–1384) tagged as Guru Amar Das Ji's or Guru Arjan Dev Ji's,
  because a `ਮਃ ੩ ॥` label inside his collection was never closed;
- Bhagats Dhanna, Sain, Pipa, Sadhna and Parmanand, and Baba Sundar Ji (Ramkali Sadu), absent from
  the author list because their headings use inflected names (`ਧੰਨੇ ਜੀ ਕੀ`, `ਸਧਨੇ ਕੀ`) or bare labels
  (`ਪੀਪਾ ॥`, `ਸ੍ਰੀ ਸੈਣੁ ॥`);
- Japji with no author at all (no Mahalla is printed over it).

## The rules (`pipeline/attribution.py`, post-pass 4 of `build_corpus.py`)

Each rule is tied to something printed in the Granth:

| Rule | Evidence |
|---|---|
| **P** | A numbered pauri label names its Mahalla: `ਪਉੜੀ ੫ ॥` (Guru Arjan Dev Ji's pauris in Guru Ram Das Ji's Gauri Vaar). |
| **L** | A heading or bare label names the voice of the next shabad/salok: `ਆਸਾ ਬਾਣੀ ਭਗਤ ਧੰਨੇ ਜੀ ਕੀ`, `ਧੰਨਾ ॥`, `ਮਃ ੫ ॥`. A label covers **one** shabad or salok. |
| **C** | A shabad under an unnamed heading (`ਬਾਣੀ ਭਗਤਾਂ ਕੀ`, `ਸਾਰੰਗ ॥`) is signed in its final stanza with one Bhagat's pen-name and never `ਨਾਨਕ`. Words that are also ordinary vocabulary (`ਨਾਮੇ` "in the Name", `ਸੈਣੁ` "friend", `ਧੰਨਾ` "blessed", `ਪਰਮਾਨੰਦ` "bliss") count only in a strict signing position (`ਕਹਿ`, `ਬਦਤਿ`, `ਪ੍ਰਣਵੈ`, `… ਭਣੈ`). |
| **N** | An unsigned shabad takes the signer of its numbered series: the running count (`॥੨॥੧॥`, `॥੨॥੨॥`, `॥੪॥੩॥`) continues with no heading between. |
| **S** | In a Bhagat's salok collection (`ਸਲੋਕ ਸੇਖ ਫਰੀਦ ਕੇ`) every salok is the collection's, except one introduced by a `ਮਃ N ॥` label, which ends at its own number. |
| **H** | Otherwise a section heading's named Bhagat repairs bleed from a Guru or a missing tag. It never moves a line from one Bhagat to another. |
| **V** | A bare `ਸਲੋਕੁ ॥` in a Guru's Vaar that opens with `ਕਬੀਰ`/`ਫਰੀਦਾ` is that Bhagat's salok. |
| **E** | Approved editorial decisions in `pipeline/attribution_ledger.json`. |

A heading that names a Mahalla always wins over a pen-name in the verse (Ang 326:
`ਗਉੜੀ ਕਬੀਰ ਜੀ ਕੀ ਨਾਲਿ ਰਲਾਇ ਲਿਖਿਆ ਮਹਲਾ ੫` stays Guru Arjan Dev Ji's).

## The ledger (`pipeline/attribution_ledger.json`)

| Status | Meaning |
|---|---|
| `approved` | Applied by rule E (Japji → Guru Nanak Dev Ji; Ramkali Sadu → Baba Sundar Ji). |
| `proposed` | Recorded for scholarly review, changes nothing: Bhai Mardana's saloks (Ang 553), Raagmala, the per-Bhatt splits, Surdas's single line (Ang 1253), saloks signed by other Bhagats inside Kabir's collection. |
| `keep` | Our tag stands on printed evidence although the independent edition differs (Angs 326, 1136, 1253). |

## The gate (`pipeline/verify_attribution.py`)

```bash
python3 pipeline/verify_attribution.py <pre.jsonl> corpus/sggs.jsonl --oracle database.sqlite \
  --review-dir validation/attribution-review
```

1. Only `author` differs between the previous and the new corpus (text, `comp_id`, `line_no`,
   `is_header`, markers are identical).
2. The pass is idempotent.
3. Every line that still disagrees with the independent edition lies inside a ledger entry.

The review pack (`validation/attribution-review/README.md`) lists each re-attributed composition
with its printed heading and its first and last verse, verbatim, for human review.

The independent edition (`database.sqlite`, pinned by `pipeline/shabados.SHA256SUMS`) is a
cross-check only: it is never copied into the corpus, never shipped and never cited.
`pipeline/attribution_audit.py` aligns it line by line to produce the diff.