classify_items.py 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  1. #!/usr/bin/env python3
  2. """Classify candidate items by urgency/importance and emit only the urgent ones.
  3. The proactive-monitor pattern: a fetch step (watcher script, inbox dump, feed) produces a JSON list
  4. of candidate items (stdin or --input-file); one call to the auxiliary ``monitor`` model scores the
  5. whole batch and ONLY items at/above --threshold are printed. Empty stdout -> the cron job's
  6. [SILENT]/empty-stdout path suppresses delivery, so quiet intervals never spam. A classifier failure
  7. exits non-zero (never silently swallowed). Items are opaque objects; a title/subject/summary/text
  8. field helps, and id/guid/message_id/url is echoed back for upstream dedup.
  9. Usage: cat items.json | python classify_items.py --threshold 7 --criteria "Urgent if ..."
  10. """
  11. from __future__ import annotations
  12. import argparse
  13. import json
  14. import sys
  15. from typing import Any, Dict, List, Optional
  16. _ID_KEYS = ("id", "guid", "message_id", "url", "link")
  17. _VIEW_KEYS = ("title", "subject", "summary", "text", "body", "from", "sender", "url")
  18. def _eprint(*args: Any) -> None:
  19. print(*args, file=sys.stderr)
  20. def _load_items(input_file: Optional[str]) -> list[dict[str, Any]]:
  21. if input_file:
  22. with open(input_file, encoding="utf-8-sig") as f:
  23. raw = f.read()
  24. else:
  25. raw = sys.stdin.read()
  26. raw = raw.strip()
  27. if not raw:
  28. return []
  29. try:
  30. data = json.loads(raw)
  31. except json.JSONDecodeError as e:
  32. _eprint(f"classify_items: input is not valid JSON: {e}")
  33. sys.exit(2)
  34. if isinstance(data, dict):
  35. # Allow {"items": [...]} or a single object.
  36. if isinstance(data.get("items"), list):
  37. return data["items"]
  38. return [data]
  39. if isinstance(data, list):
  40. return [x for x in data if isinstance(x, dict)]
  41. _eprint("classify_items: expected a JSON list or {items: [...]}")
  42. sys.exit(2)
  43. def _item_id(item: dict[str, Any], index: int) -> str:
  44. return next((str(item[key]) for key in _ID_KEYS if item.get(key)), f"item-{index}")
  45. def _build_prompt(items: list[dict[str, Any]], criteria: str) -> str:
  46. lines = [f"USER IMPORTANCE CRITERIA:\n{criteria}\n", "ITEMS:"]
  47. for i, item in enumerate(items):
  48. # Compact view of the salient fields; the whole object when none are present.
  49. view = {k: item[k] for k in _VIEW_KEYS if k in item} or item
  50. lines.append(f"[{i}] {json.dumps(view, ensure_ascii=False)[:1200]}")
  51. lines.append("\nReturn the JSON array of scores now (one object per item, same order).")
  52. return "\n".join(lines)
  53. def _parse_scores(content: str, n_items: int) -> dict[int, dict[str, Any]]:
  54. text = (content or "").strip()
  55. # Tolerate accidental markdown fences.
  56. if text.startswith("```"):
  57. text = text.strip("`")
  58. if "\n" in text:
  59. text = text.split("\n", 1)[1]
  60. try:
  61. arr = json.loads(text)
  62. except json.JSONDecodeError:
  63. # Last-ditch: find the first [...] block.
  64. start = text.find("[")
  65. end = text.rfind("]")
  66. if not (start >= 0 and end > start):
  67. _eprint("classify_items: classifier returned no JSON array")
  68. return {}
  69. try:
  70. arr = json.loads(text[start : end + 1])
  71. except json.JSONDecodeError:
  72. _eprint("classify_items: could not parse classifier output")
  73. return {}
  74. if not isinstance(arr, list):
  75. return {}
  76. return {
  77. obj["index"]: obj
  78. for obj in arr
  79. if isinstance(obj, dict)
  80. and isinstance(obj.get("index"), int)
  81. and 0 <= obj["index"] < n_items
  82. }
  83. def _render_text(surfaced: list) -> str:
  84. blocks = []
  85. for i, item, s in surfaced:
  86. title = item.get("title") or item.get("subject") or item.get("summary") or _item_id(item, i)
  87. block = f"## [{s.get('score')}/10] {title}"
  88. if url := item.get("url") or item.get("link") or "":
  89. block += f"\n{url}"
  90. if reason := s.get("reason", ""):
  91. block += f"\n_{reason}_"
  92. blocks.append(block)
  93. return "\n\n".join(blocks)
  94. def main() -> int:
  95. parser = argparse.ArgumentParser(description="Classify items by urgency; emit only urgent ones.")
  96. parser.add_argument("--criteria", required=True, help="Plain-language importance criteria.")
  97. parser.add_argument("--threshold", type=int, default=7, help="Minimum score (0-10) to surface. Default 7.")
  98. parser.add_argument("--input-file", default=None, help="Read items JSON from this file instead of stdin.")
  99. parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format for surfaced items.")
  100. args = parser.parse_args()
  101. items = _load_items(args.input_file)
  102. if not items:
  103. return 0 # nothing to classify -> silent (the common quiet-interval case)
  104. # Import here so --help works without the package importable.
  105. try:
  106. from agent.auxiliary_client import call_llm
  107. except Exception as e: # pragma: no cover - import guard
  108. _eprint(f"classify_items: cannot import auxiliary client: {e}")
  109. return 3
  110. prompt = _build_prompt(items, args.criteria)
  111. try:
  112. resp = call_llm(
  113. task="monitor", messages=[{"role": "user", "content": prompt}], max_tokens=1024,
  114. temperature=0,
  115. )
  116. content = resp.choices[0].message.content
  117. if not isinstance(content, str):
  118. content = str(content) if content else ""
  119. except Exception as e:
  120. # A broken monitor must not quietly swallow important items: non-zero exit -> cron alerts.
  121. _eprint(f"classify_items: classifier call failed: {e}")
  122. return 4
  123. scores = _parse_scores(content, len(items))
  124. surfaced = []
  125. for i, item in enumerate(items):
  126. s = scores.get(i)
  127. score = s.get("score") if isinstance(s, dict) else None
  128. if isinstance(score, int) and score >= args.threshold:
  129. surfaced.append((i, item, s))
  130. if not surfaced:
  131. return 0 # below threshold -> silent; empty stdout suppresses delivery
  132. if args.format == "json":
  133. out = [
  134. {
  135. "id": _item_id(item, i), "score": s.get("score"),
  136. "reason": s.get("reason", ""), "item": item,
  137. }
  138. for (i, item, s) in surfaced
  139. ]
  140. print(json.dumps(out, ensure_ascii=False, indent=2))
  141. else:
  142. print(_render_text(surfaced))
  143. return 0
  144. if __name__ == "__main__":
  145. sys.exit(main())