enrich_writeback.py

skills/client-enrich/scripts/enrich_writeback.py

1. #!/usr/bin/env python3
2. """
3. enrich_writeback.py: deterministic write-back for the client-enrich skill.
5. Honors the quarterly-outreach scraping-dump contract:
6. - writes ONLY under `## Research` (its four subsections) + frontmatter
7. - NEVER touches `## Human Notes`, the title line, Order History, Outreach Log, Links
8. - updates frontmatter keys only if currently empty or "[TBD]" (unless --force)
9. - always bumps the stub's existing date key (`last_modified`, else `updated`)
10. - leaves the rest of the file byte-identical
12. Usage:
13. python3 enrich_writeback.py --stub PATH --payload payload.json [--force] [--date YYYY-MM-DD]
15. payload.json schema (all keys optional; omit what you don't have):
16. {
17. "frontmatter": {
18. "title": "Head of Events & Brand Marketing",
19. "seniority": "director",
20. "city": "Denver",
21. "state": "Colorado",
22. "linkedin": "https://www.linkedin.com/in/example-jordan-reyes",
23. "company": "Brightwater Provisions",
24. "company_linkedin": "https://www.linkedin.com/company/example-brightwater-provisions"
25. },
26. "person": ["- Headline: ...", "- Current: Head of Events ... at Brightwater Provisions (since 2024-09)", "..."],
27. "company": ["- Industry: consumer goods", "- Employees: ~60", "..."],
28. "signals": ["- Headcount up ~25% over 12 months", "..."],
29. "sources": ["Apollo enrichment (people-match), 2026-06-16", "https://..."]
30. }
32. person/company/signals/sources are lists of pre-formatted markdown lines
33. (strings). Bullets ("- ") are written as-is; the script does not reformat them.
34. """
35. import argparse, json, re, sys, datetime
37. from _stub import fm_set, split_frontmatter
39. SUBSECTIONS = [
40. ("person", "### Person / LinkedIn"),
41. ("company", "### Company"),
42. ("signals", "### Recent News & Signals"),
43. ("sources", "### Sources"),
44. ]
45. # canonical order in the stub template
46. RESEARCH_ORDER = ["### Company", "### Person / LinkedIn",
47. "### Recent News & Signals", "### Sources"]
48. KEY_BY_HEADING = {h: k for k, h in SUBSECTIONS}
50. FM_KEYS = ["title", "seniority", "city", "state", "linkedin",
51. "industry", "company_website",
52. "company", "company_linkedin"]
55. def load(path):
56. with open(path, "r", encoding="utf-8") as f:
57. return f.read()
60. DATE_KEYS = ("last_modified", "updated") # vault stubs use last_modified
62. def bump_updated(fm, date):
63. """Stamp the file's existing date key. Never introduce a second one.
65. Vault stubs (and everything the weekly driver writes) carry `last_modified`;
66. older hand-made files may carry `updated`. Writing a fixed `updated:` key
67. would add a second date key that then drifts from the first, so stamp
68. whichever key is present, preferring last_modified; add one only if neither is.
69. """
70. for key in DATE_KEYS:
71. if re.search(rf'(?m)^{key}:[ \t]*.*$', fm):
72. return re.sub(rf'(?m)^{key}:[ \t]*.*$', f"{key}: '{date}'", fm, count=1)
73. return fm.rstrip() + f"\nlast_modified: '{date}'"
76. def build_research_block(payload, date):
77. out = ["## Research",
78. f"<!-- Enriched {date} via client-enrich skill. Sourced below. Never overwrite Human Notes. -->"]
79. for heading in RESEARCH_ORDER:
80. key = KEY_BY_HEADING[heading]
81. out.append(heading)
82. lines = payload.get(key) or []
83. if lines:
84. out.extend(lines)
85. else:
86. out.append("[TBD]")
87. return "\n".join(out) + "\n"
90. def replace_research(body, new_block):
91. # Research starts at "## Research" and ends just before the next "## " heading
92. m = re.search(r'(?m)^## Research\s*$', body)
93. if not m:
94. sys.exit("ERROR: no '## Research' section found in stub.")
95. start = m.start()
96. nxt = re.search(r'(?m)^## (?!Research).*$', body[start + 1:])
97. if not nxt:
98. sys.exit("ERROR: no section after '## Research' (expected '## Human Notes').")
99. end = start + 1 + nxt.start()
100. return body[:start] + new_block + "\n" + body[end:]
103. def main():
104. ap = argparse.ArgumentParser()
105. ap.add_argument("--stub", required=True)
106. ap.add_argument("--payload", required=True)
107. ap.add_argument("--force", action="store_true",
108. help="overwrite non-empty frontmatter values too")
109. ap.add_argument("--date", default=datetime.date.today().isoformat())
110. args = ap.parse_args()
112. text = load(args.stub)
113. with open(args.payload, "r", encoding="utf-8") as f:
114. payload = json.load(f)
116. fm, body = split_frontmatter(text)
117. before_human = body.split("## Human Notes", 1)
118. human_snapshot = ("## Human Notes" + before_human[1]) if len(before_human) > 1 else None
120. changed = []
121. for key in FM_KEYS:
122. if key in payload.get("frontmatter", {}):
123. val = str(payload["frontmatter"][key]).strip()
124. if val:
125. fm, did = fm_set(fm, key, val, args.force)
126. if did:
127. changed.append(key)
128. fm = bump_updated(fm, args.date)
130. body = replace_research(body, build_research_block(payload, args.date))
132. # guard: Human Notes must be untouched
133. if human_snapshot is not None:
134. after = body.split("## Human Notes", 1)
135. after_human = ("## Human Notes" + after[1]) if len(after) > 1 else None
136. if after_human != human_snapshot:
137. sys.exit("ABORT: Human Notes section would change; refusing to write.")
139. out = f"---\n{fm}\n---\n{body}"
140. with open(args.stub, "w", encoding="utf-8") as f:
141. f.write(out)
143. print(f"OK {args.stub}")
144. print(f" frontmatter updated: {', '.join(changed) if changed else '(none - already filled)'}")
145. print(f" research subsections written: "
146. f"{', '.join(k for k,_ in SUBSECTIONS if payload.get(k))}")
149. if __name__ == "__main__":
150. main()