talentprism-cli 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/PKG-INFO +4 -1
  2. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/pyproject.toml +1 -1
  3. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/README.md +3 -0
  4. talentprism_cli-0.4.0/talentprism_cli/__init__.py +1 -0
  5. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/cli.py +60 -13
  6. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/readonly_api.py +61 -7
  7. talentprism_cli-0.4.0/talentprism_cli/record_reads.py +175 -0
  8. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/skill.py +22 -4
  9. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/PKG-INFO +4 -1
  10. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/SOURCES.txt +1 -0
  11. talentprism_cli-0.3.0/talentprism_cli/__init__.py +0 -1
  12. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/README.md +0 -0
  13. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/setup.cfg +0 -0
  14. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/LICENSE.txt +0 -0
  15. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/__main__.py +0 -0
  16. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/auth.py +0 -0
  17. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/config.py +0 -0
  18. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/config_store.py +0 -0
  19. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/credentials.py +0 -0
  20. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/errors.py +0 -0
  21. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/format.py +0 -0
  22. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/loopback.py +0 -0
  23. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/network_bootstrap.py +0 -0
  24. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/oauth.py +0 -0
  25. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/sequence_writes.py +0 -0
  26. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli/transport.py +0 -0
  27. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/dependency_links.txt +0 -0
  28. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/entry_points.txt +0 -0
  29. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/requires.txt +0 -0
  30. {talentprism_cli-0.3.0 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: talentprism-cli
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents
5
5
  License-Expression: LicenseRef-Proprietary
6
6
  Project-URL: Homepage, https://talentprism.ai
@@ -67,6 +67,9 @@ tp sequences list --status Active --json
67
67
  tp candidates search --query "aircraft assembler North Charleston" --json
68
68
  tp activity summary --days 14 --json
69
69
  tp candidates timeline <candidate_id> --days 30 --json
70
+ tp chats messages --candidates 101,102 --role human --since 2026-11-01 --json
71
+ tp applications list --job 217565 --json
72
+ tp agent-runs list --chat-id 4204 --entries --json
70
73
  ```
71
74
 
72
75
  ## Changing data
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "talentprism-cli"
7
- version = "0.3.0"
7
+ version = "0.4.0"
8
8
  description = "Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents"
9
9
  readme = "talentprism_cli/README.md"
10
10
  license = "LicenseRef-Proprietary"
@@ -44,6 +44,9 @@ tp sequences list --status Active --json
44
44
  tp candidates search --query "aircraft assembler North Charleston" --json
45
45
  tp activity summary --days 14 --json
46
46
  tp candidates timeline <candidate_id> --days 30 --json
47
+ tp chats messages --candidates 101,102 --role human --since 2026-11-01 --json
48
+ tp applications list --job 217565 --json
49
+ tp agent-runs list --chat-id 4204 --entries --json
47
50
  ```
48
51
 
49
52
  ## Changing data
@@ -0,0 +1 @@
1
+ __version__ = "0.4.0"
@@ -12,6 +12,15 @@ from .auth import login, logout
12
12
  from .config import config_status, resolve_config, set_active_profile, set_profile_values
13
13
  from .errors import TalentPrismError, missing_api_key_error
14
14
  from .format import format_output
15
+ from .record_reads import (
16
+ RECORD_LIST_COMMANDS,
17
+ add_delivery_filters,
18
+ add_message_filters,
19
+ add_record_list_commands,
20
+ delivery_inputs,
21
+ message_inputs,
22
+ record_list_request,
23
+ )
15
24
  from .sequence_writes import SEQUENCE_WRITE_ACTIONS, load_sequence_file, sequence_write_request
16
25
  from .skill import COMMANDS, skill_markdown
17
26
  from .transport import APIClient, RequestFn
@@ -164,6 +173,7 @@ def _build_parser() -> argparse.ArgumentParser:
164
173
  candidates_show.add_argument("candidate_id")
165
174
  candidates_show.add_argument("--conversations", action="store_true")
166
175
  candidates_show.add_argument("--reminders", action="store_true")
176
+ candidates_show.add_argument("--memory", action="store_true", help="Include the current CandidateMemory facts.")
167
177
  candidates_add_note = candidate_subparsers.add_parser("add-note", parents=[common])
168
178
  candidates_add_note.add_argument("candidate_id", type=int)
169
179
  candidates_add_note.add_argument("--text", required=True)
@@ -319,12 +329,23 @@ def _build_parser() -> argparse.ArgumentParser:
319
329
  chats_summary.add_argument("--limit", type=int)
320
330
  chats_messages = chats_subparsers.add_parser("messages", parents=[common])
321
331
  chats_messages.add_argument("--chat-id", type=int)
322
- chats_messages.add_argument("--days", type=int, default=7)
332
+ # No default: a chat-scoped read covers the whole transcript; the server defaults others to 7 days.
333
+ chats_messages.add_argument("--days", type=int)
323
334
  chats_messages.add_argument("--sequence")
324
335
  chats_messages.add_argument("--candidate", type=int)
325
336
  chats_messages.add_argument("--limit", type=int)
337
+ add_message_filters(chats_messages)
326
338
  chats_diagnose = chats_subparsers.add_parser("diagnose", parents=[common])
327
339
  chats_diagnose.add_argument("--chat-id", type=int, required=True)
340
+ chats_reply_invariant = chats_subparsers.add_parser("reply-invariant", parents=[common])
341
+ chats_reply_invariant.add_argument("--days", type=int, default=1)
342
+ chats_findings = chats_subparsers.add_parser("findings", parents=[common])
343
+ chats_findings.add_argument("--since", type=int, default=1, help="Days of stored nightly findings (default 1).")
344
+ chats_findings.add_argument("--check")
345
+ chats_findings.add_argument("--chat-id", type=int)
346
+ chats_findings.add_argument("--severity")
347
+ chats_findings.add_argument("--include-resolved", action="store_true")
348
+ chats_findings.add_argument("--limit", type=int)
328
349
 
329
350
  # `tp ops ...` replaces the hand-built `kamal app exec ... manage.py shell` one-liners that
330
351
  # every prod diagnostic used to be (issue #474). Deploys stay on kamal; diagnostics do not.
@@ -336,6 +357,7 @@ def _build_parser() -> argparse.ArgumentParser:
336
357
  ops_delivery.add_argument("--channel", choices=["sms", "email", "phone"])
337
358
  ops_delivery.add_argument("--days", type=int, default=3)
338
359
  ops_delivery.add_argument("--limit", type=int)
360
+ add_delivery_filters(ops_delivery)
339
361
  ops_decisions = ops_subparsers.add_parser("decision-logs", parents=[common])
340
362
  ops_decisions.add_argument("--loop", choices=["nudge", "keepwarm"])
341
363
  ops_decisions.add_argument("--days", type=int, default=3)
@@ -345,6 +367,9 @@ def _build_parser() -> argparse.ArgumentParser:
345
367
  ops_decisions.add_argument("--skip-reason")
346
368
  ops_decisions.add_argument("--limit", type=int)
347
369
 
370
+ # Issue #778: cross-record reads that replace hand-written production shell queries.
371
+ add_record_list_commands(subparsers, [common], parser_class=TalentPrismArgumentParser)
372
+
348
373
  actions_parser = subparsers.add_parser("recruiter-actions")
349
374
  actions_subparsers = actions_parser.add_subparsers(
350
375
  dest="action", required=True, parser_class=TalentPrismArgumentParser
@@ -478,6 +503,9 @@ def _dispatch(args: argparse.Namespace, client: APIClient, stderr: TextIO):
478
503
  return _dispatch_ops(args, client)
479
504
  if args.command == "recruiter-actions":
480
505
  return _dispatch_recruiter_actions(args, client)
506
+ if args.command in RECORD_LIST_COMMANDS:
507
+ capability, inputs = record_list_request(args)
508
+ return _read_capability(client, capability, inputs)
481
509
  if args.command == "team-config":
482
510
  return _dispatch_team_config(args, client)
483
511
  raise TalentPrismError(
@@ -565,6 +593,8 @@ def _dispatch_candidates(args: argparse.Namespace, client: APIClient):
565
593
  params["conversations"] = "1"
566
594
  if args.reminders:
567
595
  params["reminders"] = "1"
596
+ if args.memory:
597
+ params["memory"] = "1"
568
598
  query = urlencode(params)
569
599
  suffix = f"?{query}" if query else ""
570
600
  return client.get(f"/api/candidates/{args.candidate_id}/{suffix}")
@@ -792,12 +822,26 @@ def _dispatch_chats(args: argparse.Namespace, client: APIClient):
792
822
  if args.action == "messages":
793
823
  if args.chat_id is not None:
794
824
  inputs["chat_id"] = args.chat_id
795
- return client.post(
796
- "/api/capabilities/invoke/",
797
- {"capability": "chats.messages", "inputs": inputs, "confirmed_write": False},
798
- )
825
+ inputs.update(message_inputs(args))
826
+ return _read_capability(client, "chats.messages", inputs)
799
827
  if args.action == "diagnose":
800
828
  return _read_capability(client, "chats.diagnose", {"chat_id": args.chat_id})
829
+ if args.action == "reply-invariant":
830
+ return _read_capability(client, "chats.reply_invariant", {"days": args.days})
831
+ if args.action == "findings":
832
+ return _read_capability(
833
+ client,
834
+ "chats.findings",
835
+ _optional_inputs(
836
+ args,
837
+ since="days",
838
+ check="check",
839
+ chat_id="chat_id",
840
+ severity="severity",
841
+ include_resolved="include_resolved",
842
+ limit="limit",
843
+ ),
844
+ )
801
845
  raise TalentPrismError(
802
846
  code="invalid_command",
803
847
  type="invalid_input",
@@ -811,14 +855,17 @@ def _dispatch_ops(args: argparse.Namespace, client: APIClient):
811
855
  return _read_capability(
812
856
  client,
813
857
  "ops.delivery_status",
814
- _optional_inputs(
815
- args,
816
- candidate="candidate_id",
817
- sequence="sequence_id",
818
- channel="channel",
819
- days="days",
820
- limit="limit",
821
- ),
858
+ {
859
+ **_optional_inputs(
860
+ args,
861
+ candidate="candidate_id",
862
+ sequence="sequence_id",
863
+ channel="channel",
864
+ days="days",
865
+ limit="limit",
866
+ ),
867
+ **delivery_inputs(args),
868
+ },
822
869
  )
823
870
  if args.action == "decision-logs":
824
871
  return _read_capability(
@@ -10,6 +10,15 @@ from .config import resolve_config
10
10
  from .errors import TalentPrismError
11
11
  from .format import format_output
12
12
  from .network_bootstrap import bootstrap_network_from_env
13
+ from .record_reads import (
14
+ RECORD_LIST_COMMANDS,
15
+ add_delivery_filters,
16
+ add_message_filters,
17
+ add_record_list_commands,
18
+ delivery_inputs,
19
+ message_inputs,
20
+ record_list_request,
21
+ )
13
22
  from .transport import APIClient, RequestFn
14
23
 
15
24
 
@@ -82,13 +91,29 @@ def _build_parser() -> argparse.ArgumentParser:
82
91
  chats_summary.add_argument("--limit", type=int)
83
92
  chats_summary.add_argument("--json", action="store_true")
84
93
  chats_messages = chats_subparsers.add_parser("messages")
85
- chats_messages.add_argument("--chat-id", type=int, required=True)
86
- chats_messages.add_argument("--days", type=int, default=7)
94
+ chats_messages.add_argument("--chat-id", type=int)
95
+ # No default: a chat-scoped read covers the whole transcript; the server defaults others to 7 days.
96
+ chats_messages.add_argument("--days", type=int)
97
+ chats_messages.add_argument("--sequence")
98
+ chats_messages.add_argument("--candidate", type=int)
87
99
  chats_messages.add_argument("--limit", type=int)
100
+ add_message_filters(chats_messages)
88
101
  chats_messages.add_argument("--json", action="store_true")
89
102
  chats_diagnose = chats_subparsers.add_parser("diagnose")
90
103
  chats_diagnose.add_argument("--chat-id", type=int, required=True)
91
104
  chats_diagnose.add_argument("--json", action="store_true")
105
+ chats_reply_invariant = chats_subparsers.add_parser("reply-invariant")
106
+ chats_reply_invariant.add_argument("--days", type=int, default=1)
107
+ chats_reply_invariant.add_argument("--json", action="store_true")
108
+ # Stored nightly findings for the team (chats.findings); --since is in days.
109
+ chats_findings = chats_subparsers.add_parser("findings")
110
+ chats_findings.add_argument("--since", type=int, default=1)
111
+ chats_findings.add_argument("--check")
112
+ chats_findings.add_argument("--chat-id", type=int)
113
+ chats_findings.add_argument("--severity")
114
+ chats_findings.add_argument("--include-resolved", action="store_true")
115
+ chats_findings.add_argument("--limit", type=int)
116
+ chats_findings.add_argument("--json", action="store_true")
92
117
 
93
118
  # Read-only prod diagnostics. These exist here, not only in cli.py, because the health sweep
94
119
  # runs through this path and must never be able to reach a write.
@@ -100,6 +125,7 @@ def _build_parser() -> argparse.ArgumentParser:
100
125
  ops_delivery.add_argument("--channel", choices=["sms", "email", "phone"])
101
126
  ops_delivery.add_argument("--days", type=int, default=3)
102
127
  ops_delivery.add_argument("--limit", type=int)
128
+ add_delivery_filters(ops_delivery)
103
129
  ops_delivery.add_argument("--json", action="store_true")
104
130
  ops_decisions = ops_subparsers.add_parser("decision-logs")
105
131
  ops_decisions.add_argument("--loop", choices=["nudge", "keepwarm"])
@@ -144,6 +170,7 @@ def _build_parser() -> argparse.ArgumentParser:
144
170
  candidates_show.add_argument("candidate_id")
145
171
  candidates_show.add_argument("--conversations", action="store_true")
146
172
  candidates_show.add_argument("--reminders", action="store_true")
173
+ candidates_show.add_argument("--memory", action="store_true")
147
174
  candidates_show.add_argument("--json", action="store_true")
148
175
  # Slice 2 evidence reads. They belong on the read-only path too: the health sweep asks
149
176
  # "did this actually persist?" and must never be able to reach a write to find out.
@@ -176,6 +203,11 @@ def _build_parser() -> argparse.ArgumentParser:
176
203
  leads_consent.add_argument("--limit", type=int)
177
204
  leads_consent.add_argument("--json", action="store_true")
178
205
 
206
+ # Issue #778 list reads: applications, agent-runs, job-alerts. All read capabilities.
207
+ json_flag = argparse.ArgumentParser(add_help=False)
208
+ json_flag.add_argument("--json", action="store_true")
209
+ add_record_list_commands(subparsers, [json_flag])
210
+
179
211
  capabilities = subparsers.add_parser("capabilities")
180
212
  capabilities_subparsers = capabilities.add_subparsers(dest="action", required=True)
181
213
  capabilities_invoke = capabilities_subparsers.add_parser("invoke")
@@ -193,7 +225,13 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
193
225
  if args.action == "diagnose":
194
226
  # Diagnose is scoped to one chat, so it takes no window flags to read here.
195
227
  return _invoke_capability(client, "chats.diagnose", {"chat_id": args.chat_id})
196
- inputs: dict[str, object] = {"days": args.days}
228
+ if args.action == "reply-invariant":
229
+ return _invoke_capability(client, "chats.reply_invariant", {"days": args.days})
230
+ if args.action == "findings":
231
+ return _invoke_capability(client, "chats.findings", _set_inputs(args, _FINDINGS_INPUTS))
232
+ inputs: dict[str, object] = {}
233
+ if getattr(args, "days", None) is not None:
234
+ inputs["days"] = args.days
197
235
  if getattr(args, "limit", None):
198
236
  inputs["limit"] = args.limit
199
237
  if getattr(args, "sequence", None):
@@ -203,11 +241,14 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
203
241
  if args.action == "summary":
204
242
  return _invoke_capability(client, "chats.summary", inputs)
205
243
  if args.action == "messages":
206
- inputs["chat_id"] = args.chat_id
244
+ if args.chat_id is not None:
245
+ inputs["chat_id"] = args.chat_id
246
+ inputs.update(message_inputs(args))
207
247
  return _invoke_capability(client, "chats.messages", inputs)
208
248
  if args.command == "ops":
209
249
  if args.action == "delivery-status":
210
- return _invoke_capability(client, "ops.delivery_status", _set_inputs(args, _DELIVERY_INPUTS))
250
+ inputs = {**_set_inputs(args, _DELIVERY_INPUTS), **delivery_inputs(args)}
251
+ return _invoke_capability(client, "ops.delivery_status", inputs)
211
252
  if args.action == "decision-logs":
212
253
  return _invoke_capability(client, "ops.decision_logs", _set_inputs(args, _DECISION_INPUTS))
213
254
  if args.command == "recruiter-actions":
@@ -229,6 +270,8 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
229
270
  params["conversations"] = "1"
230
271
  if args.reminders:
231
272
  params["reminders"] = "1"
273
+ if args.memory:
274
+ params["memory"] = "1"
232
275
  query = urlencode(params)
233
276
  suffix = f"?{query}" if query else ""
234
277
  return client.get(f"/api/candidates/{args.candidate_id}/{suffix}")
@@ -241,6 +284,9 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
241
284
  return _invoke_capability(client, "leads.maturity", {"candidate_id": args.candidate_id})
242
285
  if args.action == "consent-evidence":
243
286
  return _invoke_capability(client, "leads.consent_evidence", _set_inputs(args, _CONSENT_SWEEP_INPUTS))
287
+ if args.command in RECORD_LIST_COMMANDS:
288
+ capability, inputs = record_list_request(args)
289
+ return _invoke_capability(client, capability, inputs)
244
290
  if args.command == "capabilities" and args.action == "invoke":
245
291
  return _invoke_capability(client, args.capability, _load_json_object(args.input_json))
246
292
  raise TalentPrismError(
@@ -248,14 +294,22 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
248
294
  type="invalid_input",
249
295
  message="Unsupported read-only command.",
250
296
  remediation=(
251
- "Use whoami, chats summary/messages/diagnose, ops delivery-status/decision-logs, "
297
+ "Use whoami, chats summary/messages/diagnose/reply-invariant, ops delivery-status/decision-logs, "
252
298
  "recruiter-actions list/show, team-config read/senders/compare, "
253
299
  "candidates show/provenance/timeline/records, leads maturity/consent-evidence, "
254
- "or capabilities invoke."
300
+ "applications list, agent-runs list, job-alerts list, or capabilities invoke."
255
301
  ),
256
302
  )
257
303
 
258
304
 
305
+ _FINDINGS_INPUTS = {
306
+ "since": "days",
307
+ "check": "check",
308
+ "chat_id": "chat_id",
309
+ "severity": "severity",
310
+ "include_resolved": "include_resolved",
311
+ "limit": "limit",
312
+ }
259
313
  _DELIVERY_INPUTS = {
260
314
  "candidate": "candidate_id",
261
315
  "sequence": "sequence_id",
@@ -0,0 +1,175 @@
1
+ """Cross-record read commands (issue #778), shared by `tp` and the read-only `tp-readonly` path.
2
+
3
+ Both entry points build the same flags and send the same capability inputs, so they live here
4
+ once: the new `tp chats messages` and `tp ops delivery-status` filters, and the three list
5
+ commands `tp applications list`, `tp agent-runs list` and `tp job-alerts list`. Every one is a
6
+ read capability; nothing here can reach a write.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+
13
+ from .errors import TalentPrismError
14
+
15
+ RECORD_LIST_COMMANDS = ("applications", "agent-runs", "job-alerts")
16
+
17
+ _PAGING = {"days": "days", "since": "since", "until": "until", "limit": "limit", "offset": "offset"}
18
+
19
+
20
+ def add_range_arguments(parser: argparse.ArgumentParser) -> None:
21
+ parser.add_argument("--since", help="ISO date or datetime, inclusive. Wins over --days.")
22
+ parser.add_argument("--until", help="ISO date (through the end of that day) or datetime.")
23
+
24
+
25
+ def add_message_filters(parser: argparse.ArgumentParser) -> None:
26
+ """`chats messages` flags beyond --chat-id/--days/--sequence/--candidate/--limit."""
27
+ parser.add_argument("--chat-ids", help="Comma-separated chat ids.")
28
+ parser.add_argument("--candidates", help="Comma-separated candidate ids.")
29
+ parser.add_argument("--campaign", help="Campaign (round) UUID.")
30
+ parser.add_argument("--search", help="Case-insensitive text the message contains.")
31
+ parser.add_argument(
32
+ "--role", help="human, ai (default); system, worker, wait or all need an admin key. Comma separated."
33
+ )
34
+ add_range_arguments(parser)
35
+ parser.add_argument("--offset", type=int, help="Skip this many newer matches (the previous next_offset).")
36
+
37
+
38
+ def message_inputs(args: argparse.Namespace) -> dict:
39
+ return {
40
+ **set_inputs(
41
+ args,
42
+ {
43
+ "campaign": "campaign_id",
44
+ "search": "search",
45
+ "role": "role",
46
+ "since": "since",
47
+ "until": "until",
48
+ "offset": "offset",
49
+ },
50
+ ),
51
+ **id_list_inputs(args, {"chat_ids": "chat_ids", "candidates": "candidate_ids"}),
52
+ }
53
+
54
+
55
+ def add_delivery_filters(parser: argparse.ArgumentParser) -> None:
56
+ """`ops delivery-status` flags beyond --candidate/--sequence/--channel/--days/--limit."""
57
+ parser.add_argument("--candidates", help="Comma-separated candidate ids.")
58
+ parser.add_argument("--campaign", help="Campaign (round) UUID.")
59
+ parser.add_argument("--source", help="Exact send source tag, e.g. keepwarm or a batch name.")
60
+ add_range_arguments(parser)
61
+
62
+
63
+ def delivery_inputs(args: argparse.Namespace) -> dict:
64
+ return {
65
+ **set_inputs(args, {"campaign": "campaign_id", "source": "source", "since": "since", "until": "until"}),
66
+ **id_list_inputs(args, {"candidates": "candidate_ids"}),
67
+ }
68
+
69
+
70
+ def add_record_list_commands(subparsers, parents: list[argparse.ArgumentParser], parser_class=None) -> None:
71
+ def list_parser(command: str, help_text: str) -> argparse.ArgumentParser:
72
+ group = subparsers.add_parser(command, help=help_text)
73
+ kwargs = {"dest": "action", "required": True}
74
+ if parser_class is not None:
75
+ kwargs["parser_class"] = parser_class
76
+ parser = group.add_subparsers(**kwargs).add_parser("list", parents=parents)
77
+ parser.add_argument("--candidate", type=int)
78
+ parser.add_argument("--candidates", help="Comma-separated candidate ids.")
79
+ return parser
80
+
81
+ applications = list_parser("applications", "Job applications across the team.")
82
+ applications.add_argument("--job", help="Client job id, or several comma separated.")
83
+ applications.add_argument("--campaign", help="Campaign (round) UUID the application is credited to.")
84
+ applications.add_argument("--sequence")
85
+ applications.add_argument("--channel", help="source_channel, e.g. campaign or chat_widget.")
86
+ applications.add_argument("--status")
87
+ _add_paging(applications)
88
+
89
+ runs = list_parser("agent-runs", "TinyLLM worker runs (ExecutionRun).")
90
+ runs.add_argument("--chat-id", type=int)
91
+ runs.add_argument("--chat-ids", help="Comma-separated chat ids.")
92
+ runs.add_argument("--agent", help="Worker name, matched on any part.")
93
+ runs.add_argument("--status", choices=["pending", "running", "succeeded", "failed"])
94
+ runs.add_argument("--errors-only", action="store_true")
95
+ runs.add_argument("--entries", action="store_true", help="Include each run's transcript.")
96
+ runs.add_argument("--include-simulator", action="store_true")
97
+ _add_paging(runs)
98
+
99
+ alerts = list_parser("job-alerts", "Job-alert subscriptions across the team.")
100
+ alerts.add_argument("--active-only", action="store_true")
101
+ alerts.add_argument("--role", help="Job role, matched on any part.")
102
+ alerts.add_argument("--location", help="Location, matched on any part.")
103
+ _add_paging(alerts)
104
+
105
+
106
+ def record_list_request(args: argparse.Namespace) -> tuple[str, dict]:
107
+ """The capability and inputs for `applications|agent-runs|job-alerts list`."""
108
+ if args.command == "applications":
109
+ capability = "applications.list"
110
+ mapping = {
111
+ "job": "job_id",
112
+ "campaign": "campaign_id",
113
+ "sequence": "sequence_id",
114
+ "channel": "source_channel",
115
+ "status": "status",
116
+ }
117
+ elif args.command == "agent-runs":
118
+ capability = "agent_runs.list"
119
+ mapping = {
120
+ "chat_id": "chat_id",
121
+ "agent": "agent_name",
122
+ "status": "status",
123
+ "errors_only": "errors_only",
124
+ "entries": "include_entries",
125
+ "include_simulator": "include_simulator",
126
+ }
127
+ elif args.command == "job-alerts":
128
+ capability = "job_alerts.list"
129
+ mapping = {"active_only": "active_only", "role": "job_role", "location": "location"}
130
+ else:
131
+ raise TalentPrismError(
132
+ code="invalid_command",
133
+ type="invalid_input",
134
+ message="Unknown record list command.",
135
+ remediation="Use tp applications list, tp agent-runs list or tp job-alerts list.",
136
+ )
137
+ inputs = set_inputs(args, {"candidate": "candidate_id", **mapping, **_PAGING})
138
+ inputs.update(id_list_inputs(args, {"candidates": "candidate_ids", "chat_ids": "chat_ids"}))
139
+ return capability, inputs
140
+
141
+
142
+ def set_inputs(args: argparse.Namespace, mapping: dict[str, str]) -> dict:
143
+ """Only the flags the operator actually set; omitted ones fall through to capability defaults."""
144
+ inputs = {}
145
+ for arg_name, input_name in mapping.items():
146
+ value = getattr(args, arg_name, None)
147
+ if value not in (None, "", False):
148
+ inputs[input_name] = value
149
+ return inputs
150
+
151
+
152
+ def id_list_inputs(args: argparse.Namespace, mapping: dict[str, str]) -> dict:
153
+ """Comma-separated id flags become integer lists, refused here if one is not a number."""
154
+ inputs = {}
155
+ for arg_name, input_name in mapping.items():
156
+ raw = getattr(args, arg_name, None)
157
+ if not raw:
158
+ continue
159
+ try:
160
+ inputs[input_name] = [int(part) for part in str(raw).split(",") if part.strip()]
161
+ except ValueError:
162
+ raise TalentPrismError(
163
+ code="invalid_input",
164
+ type="invalid_input",
165
+ message=f"--{arg_name.replace('_', '-')} expects comma-separated ids, got {raw!r}.",
166
+ remediation="Pass ids like --candidates 101,102,103.",
167
+ ) from None
168
+ return inputs
169
+
170
+
171
+ def _add_paging(parser: argparse.ArgumentParser) -> None:
172
+ parser.add_argument("--days", type=int)
173
+ add_range_arguments(parser)
174
+ parser.add_argument("--limit", type=int)
175
+ parser.add_argument("--offset", type=int, help="Skip this many rows (the previous next_offset).")
@@ -13,7 +13,7 @@ COMMANDS = [
13
13
  "tp sequences summary <uuid>",
14
14
  "tp candidates list --sequence <uuid> [--all]",
15
15
  "tp candidates search --query <text> [--all]",
16
- "tp candidates show <id> [--conversations] [--reminders]",
16
+ "tp candidates show <id> [--conversations] [--reminders] [--memory]",
17
17
  "tp candidates add-note <id> --text <note> [--confirm-write --approval-token <token>]",
18
18
  "tp candidates send-email <id> [--recipient <email>] --subject <subject> --body <body> [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
19
19
  "tp candidates send-sms <id> --message <message> [--recipient <phone>] [--sequence <uuid>] [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
@@ -45,10 +45,15 @@ COMMANDS = [
45
45
  "tp metrics --sequence <uuid>",
46
46
  "tp activity summary [--days <n>] [--sequence <uuid>]",
47
47
  "tp chats summary [--days <n>] [--sequence <uuid>] [--candidate <id>] [--limit <n>]",
48
- "tp chats messages [--chat-id <id>] [--days <n>] [--sequence <uuid>] [--candidate <id>] [--limit <n>]",
48
+ "tp chats messages [--chat-id <id> | --chat-ids <ids>] [--candidate <id> | --candidates <ids>] [--sequence <uuid>] [--campaign <uuid>] [--search <text>] [--role human,ai,system,worker,wait|all] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
49
49
  "tp chats diagnose --chat-id <id>",
50
- "tp ops delivery-status [--candidate <id>] [--sequence <uuid>] [--channel sms|email|phone] [--days <n>] [--limit <n>]",
50
+ "tp chats reply-invariant [--days <n>]",
51
+ "tp chats findings [--since <days>] [--check <name>] [--chat-id <id>] [--severity P0|P1|P2] [--include-resolved]",
52
+ "tp ops delivery-status [--candidate <id> | --candidates <ids>] [--sequence <uuid>] [--campaign <uuid>] [--source <tag>] [--channel sms|email|phone] [--days <n> | --since <date> --until <date>] [--limit <n>]",
51
53
  "tp ops decision-logs [--loop nudge|keepwarm] [--days <n>] [--candidate <id>] [--chat-id <id>] [--outcome <outcome>] [--skip-reason <reason>] [--limit <n>]",
54
+ "tp applications list [--candidate <id> | --candidates <ids>] [--job <ids>] [--campaign <uuid>] [--sequence <uuid>] [--channel <source_channel>] [--status <status>] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
55
+ "tp agent-runs list [--chat-id <id> | --chat-ids <ids>] [--candidate <id> | --candidates <ids>] [--agent <name>] [--status pending|running|succeeded|failed] [--errors-only] [--entries] [--include-simulator] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
56
+ "tp job-alerts list [--candidate <id> | --candidates <ids>] [--active-only] [--role <text>] [--location <text>] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
52
57
  "tp recruiter-actions list [--days <n>] [--unresolved] [--status <status>] [--assignment-status <status>] [--action-type <type>] [--priority <p>] [--candidate <id>] [--limit <n>]",
53
58
  "tp recruiter-actions show <action-id>",
54
59
  "tp recruiter-actions complete <action-id> [--note <text>] [--confirm-write --approval-token <token>]",
@@ -86,7 +91,7 @@ A person signs in with `tp login`: it opens the browser, you pick a team and app
86
91
 
87
92
  For automation, CI and agents, use an API key: `TALENTPRISM_API_KEY` (preferred), `--api-key`, or the profile `api_key`. Precedence is `--api-key` flag, then `TALENTPRISM_API_KEY`, then login tokens, then the profile `api_key`. The default server is `https://talentprism.ai`; set `TALENTPRISM_BASE_URL` (or `--base-url`) for staging or local fleetapp. Avoid passing `--api-key` on the command line: it leaks into shell history and process listings. Non-local base URLs must use https; plain http is rejected unless `TALENTPRISM_ALLOW_INSECURE_HTTP=1` is set.
88
93
 
89
- **A key inherits its user's team role, and `ops.*` needs admin.** `tp ops delivery-status` and `tp ops decision-logs` are admin-only. A key issued from an account that is a plain *member* of the team authenticates perfectly and then fails every `ops` call with `not_authorized` (exit 3). Check with `tp whoami` before relying on a key for production diagnostics; if it is not an admin key, grant that user admin on the team or reissue the key from an admin account. Everything else in this document - including `tp chats diagnose` and all four `tp recruiter-actions` commands - works at member level.
94
+ **A key inherits its user's team role, and `ops.*` needs admin.** `tp ops delivery-status`, `tp ops decision-logs` and `tp agent-runs list` are admin-only. A key issued from an account that is a plain *member* of the team authenticates perfectly and then fails every `ops` call with `not_authorized` (exit 3). Check with `tp whoami` before relying on a key for production diagnostics; if it is not an admin key, grant that user admin on the team or reissue the key from an admin account. Everything else in this document - including `tp chats diagnose` and all four `tp recruiter-actions` commands - works at member level.
90
95
 
91
96
  A `not_authorized` error is never a reason to rotate the key. It means the key worked and its user lacks the role.
92
97
 
@@ -123,10 +128,23 @@ Exit codes: 0 success, 2 invalid input, 3 auth, 4 not found, 5 validation, 6 tra
123
128
  - `tp ops delivery-status` - was it actually sent? Reports every record on both SMS send paths with its own proof field, and classifies each as `sent`, `failed`, `in_flight`, `sent_without_sid` (marked sent but carrying no SID - never proof), or `skipped`. An empty result on one path is not evidence that nothing was sent.
124
129
  - `tp ops decision-logs` - what did the nudge and keep-warm loops decide, and what does each outcome mean. Separates dry-run sends from real ones. For keep-warm, a row saying `sent_pitch` proves nothing on its own: only a non-empty `message_sid` on the linked touchpoint does, and the payload reports that per row.
125
130
  - `tp recruiter-actions list --unresolved` - which handoffs and alerts nobody has acted on. Delivery status (`sent`, `held_for_digest`, `digest_sent`, `failed`) and human resolution (`team_queue`, `accepted`, `completed`, `escalated`) are separate fields: a delivered alert can still be untouched.
131
+ - `tp chats reply-invariant [--days <n>]` - reply-invariant ledger counts for the team: every candidate message by outcome (answered, recovered, relayed late, no reply needed, superseded, apologised, escalated, unanswered), answer latency p50/p95, and the chats escalated to a recruiter.
126
132
  - `tp chats diagnose --chat-id <id>` - conversation QA for one chat: duplicate assistant messages, candidate turns with no reply, repeated system recovery, and cross-campaign routing. Each check returns `clear`, `finding` (with message ids and timestamps), or `inconclusive` with the reason. It never guesses.
133
+ - `tp chats findings --since <days>` - the same checks, already run overnight (06:00 UTC) on every chat active in the last 72 hours and stored per finding with first_seen, last_seen and resolved_at. Use this for a team-wide view; use `diagnose` for one chat right now.
127
134
 
128
135
  `ops.*` reads require the admin role - see Auth above. Everything else here works for a plain member.
129
136
 
137
+ ## Across Records
138
+
139
+ Questions that span many chats, sends or applications. Each is one team-scoped read; filters combine. Dates are `--since`/`--until` (ISO dates; `--until 2026-09-30` covers that whole day) or `--days`. Id lists are comma separated. When `truncated` is true, pass `next_offset` back as `--offset`. A "campaign" is the bounded round (`--campaign <uuid>`), not the job sequence (`--sequence`); messages and sends record only the sequence, so for those two `--campaign` reads its execution sequence and the scope lists every campaign sharing it.
140
+
141
+ - `tp chats messages --candidates 101,102 --role human --since 2026-11-01` - what these people said, across all their chats. `--search TWIC` matches message text; `--role all` adds system, worker and wait rows (admin keys only). A read scoped to chats or candidates covers their whole history unless you pass a date; a team-wide read defaults to the last 7 days. Every response states the window it used under `range`.
142
+ - `tp ops delivery-status --campaign <uuid> --since 2026-09-01 --until 2026-09-30` - every send for a round, on both send paths, with SID and result. `--source keepwarm` (or a batch tag) narrows to one sender; `--candidates` to people. Admin only.
143
+ - `tp applications list --job 217565` - applications to a job, a round (`--campaign`), a person, or a window, with status, channel, the round each is credited to and the recruiter it went to. `source_channel` (how it arrived) and `source_campaign_id` (which round) are separate facts; neither implies the job.
144
+ - `tp agent-runs list --chat-id <id> --entries` - what the TinyLLM workers did: agent, tools used, status, error, duration, and whether the result reached the candidate. A `succeeded` run with no `delivered_at` finished but was never relayed. `--errors-only` for failures. Admin only.
145
+ - `tp job-alerts list --active-only` - alert subscriptions with totals as rows and as people (one person can hold several).
146
+ - `tp candidates show <id> --memory` - the current CandidateMemory facts. Who wrote each fact is `tp candidates provenance <id>`.
147
+
130
148
  ## Evidence Reads
131
149
 
132
150
  These answer "show me the record, not the conclusion". All are member-level reads.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: talentprism-cli
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents
5
5
  License-Expression: LicenseRef-Proprietary
6
6
  Project-URL: Homepage, https://talentprism.ai
@@ -67,6 +67,9 @@ tp sequences list --status Active --json
67
67
  tp candidates search --query "aircraft assembler North Charleston" --json
68
68
  tp activity summary --days 14 --json
69
69
  tp candidates timeline <candidate_id> --days 30 --json
70
+ tp chats messages --candidates 101,102 --role human --since 2026-11-01 --json
71
+ tp applications list --job 217565 --json
72
+ tp agent-runs list --chat-id 4204 --entries --json
70
73
  ```
71
74
 
72
75
  ## Changing data
@@ -15,6 +15,7 @@ talentprism_cli/loopback.py
15
15
  talentprism_cli/network_bootstrap.py
16
16
  talentprism_cli/oauth.py
17
17
  talentprism_cli/readonly_api.py
18
+ talentprism_cli/record_reads.py
18
19
  talentprism_cli/sequence_writes.py
19
20
  talentprism_cli/skill.py
20
21
  talentprism_cli/transport.py
@@ -1 +0,0 @@
1
- __version__ = "0.3.0"