talentprism-cli 0.3.0__py3-none-any.whl
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.
- talentprism_cli/LICENSE.txt +17 -0
- talentprism_cli/README.md +70 -0
- talentprism_cli/__init__.py +1 -0
- talentprism_cli/__main__.py +5 -0
- talentprism_cli/auth.py +222 -0
- talentprism_cli/cli.py +1158 -0
- talentprism_cli/config.py +311 -0
- talentprism_cli/config_store.py +144 -0
- talentprism_cli/credentials.py +154 -0
- talentprism_cli/errors.py +48 -0
- talentprism_cli/format.py +96 -0
- talentprism_cli/loopback.py +143 -0
- talentprism_cli/network_bootstrap.py +113 -0
- talentprism_cli/oauth.py +193 -0
- talentprism_cli/readonly_api.py +327 -0
- talentprism_cli/sequence_writes.py +74 -0
- talentprism_cli/skill.py +165 -0
- talentprism_cli/transport.py +277 -0
- talentprism_cli-0.3.0.dist-info/METADATA +93 -0
- talentprism_cli-0.3.0.dist-info/RECORD +24 -0
- talentprism_cli-0.3.0.dist-info/WHEEL +5 -0
- talentprism_cli-0.3.0.dist-info/entry_points.txt +2 -0
- talentprism_cli-0.3.0.dist-info/licenses/talentprism_cli/LICENSE.txt +17 -0
- talentprism_cli-0.3.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
import json
|
|
5
|
+
import sys
|
|
6
|
+
from typing import TextIO
|
|
7
|
+
from urllib.parse import urlencode
|
|
8
|
+
|
|
9
|
+
from .config import resolve_config
|
|
10
|
+
from .errors import TalentPrismError
|
|
11
|
+
from .format import format_output
|
|
12
|
+
from .network_bootstrap import bootstrap_network_from_env
|
|
13
|
+
from .transport import APIClient, RequestFn
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def main(argv: list[str] | None = None) -> int:
|
|
17
|
+
return run(argv if argv is not None else sys.argv[1:])
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def run(
|
|
21
|
+
argv: list[str],
|
|
22
|
+
*,
|
|
23
|
+
stdout: TextIO = sys.stdout,
|
|
24
|
+
stderr: TextIO = sys.stderr,
|
|
25
|
+
request: RequestFn | None = None,
|
|
26
|
+
env: dict[str, str] | None = None,
|
|
27
|
+
) -> int:
|
|
28
|
+
parser = _build_parser()
|
|
29
|
+
try:
|
|
30
|
+
bootstrap_network_from_env(env)
|
|
31
|
+
args = parser.parse_args(argv)
|
|
32
|
+
config = resolve_config(env=env, enforce_safe_permissions=True)
|
|
33
|
+
client = APIClient(config, request=request)
|
|
34
|
+
payload = _dispatch(args, client)
|
|
35
|
+
if args.command == "whoami":
|
|
36
|
+
payload = {**payload, "profile": config.profile, "base_url": config.base_url}
|
|
37
|
+
stdout.write(format_output(payload, "json"))
|
|
38
|
+
return 0
|
|
39
|
+
except TalentPrismError as exc:
|
|
40
|
+
error = exc
|
|
41
|
+
except ValueError as exc:
|
|
42
|
+
error = TalentPrismError(
|
|
43
|
+
code="invalid_input",
|
|
44
|
+
type="invalid_input",
|
|
45
|
+
message=str(exc),
|
|
46
|
+
remediation="Review the read-only command arguments and try again.",
|
|
47
|
+
)
|
|
48
|
+
except RuntimeError as exc:
|
|
49
|
+
error = TalentPrismError(
|
|
50
|
+
code="network_bootstrap_failed",
|
|
51
|
+
type="invalid_input",
|
|
52
|
+
message=str(exc),
|
|
53
|
+
remediation="Set TALENTPRISM_HOST_CACHE_PATH to a writable cache file path and retry.",
|
|
54
|
+
)
|
|
55
|
+
except OSError as exc:
|
|
56
|
+
error = TalentPrismError(
|
|
57
|
+
code="network_bootstrap_failed",
|
|
58
|
+
type="transient",
|
|
59
|
+
message=f"Could not resolve the TalentPrism host: {exc}",
|
|
60
|
+
remediation="Check network connectivity and DNS, then retry.",
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
stderr.write(format_output(error.to_payload(), "json"))
|
|
64
|
+
return error.exit_code
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _build_parser() -> argparse.ArgumentParser:
|
|
68
|
+
parser = argparse.ArgumentParser(prog="tp-readonly")
|
|
69
|
+
parser.add_argument("--json", action="store_true")
|
|
70
|
+
|
|
71
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
72
|
+
|
|
73
|
+
whoami = subparsers.add_parser("whoami")
|
|
74
|
+
whoami.add_argument("--json", action="store_true")
|
|
75
|
+
|
|
76
|
+
chats = subparsers.add_parser("chats")
|
|
77
|
+
chats_subparsers = chats.add_subparsers(dest="action", required=True)
|
|
78
|
+
chats_summary = chats_subparsers.add_parser("summary")
|
|
79
|
+
chats_summary.add_argument("--days", type=int, default=7)
|
|
80
|
+
chats_summary.add_argument("--sequence")
|
|
81
|
+
chats_summary.add_argument("--candidate", type=int)
|
|
82
|
+
chats_summary.add_argument("--limit", type=int)
|
|
83
|
+
chats_summary.add_argument("--json", action="store_true")
|
|
84
|
+
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)
|
|
87
|
+
chats_messages.add_argument("--limit", type=int)
|
|
88
|
+
chats_messages.add_argument("--json", action="store_true")
|
|
89
|
+
chats_diagnose = chats_subparsers.add_parser("diagnose")
|
|
90
|
+
chats_diagnose.add_argument("--chat-id", type=int, required=True)
|
|
91
|
+
chats_diagnose.add_argument("--json", action="store_true")
|
|
92
|
+
|
|
93
|
+
# Read-only prod diagnostics. These exist here, not only in cli.py, because the health sweep
|
|
94
|
+
# runs through this path and must never be able to reach a write.
|
|
95
|
+
ops = subparsers.add_parser("ops")
|
|
96
|
+
ops_subparsers = ops.add_subparsers(dest="action", required=True)
|
|
97
|
+
ops_delivery = ops_subparsers.add_parser("delivery-status")
|
|
98
|
+
ops_delivery.add_argument("--candidate", type=int)
|
|
99
|
+
ops_delivery.add_argument("--sequence")
|
|
100
|
+
ops_delivery.add_argument("--channel", choices=["sms", "email", "phone"])
|
|
101
|
+
ops_delivery.add_argument("--days", type=int, default=3)
|
|
102
|
+
ops_delivery.add_argument("--limit", type=int)
|
|
103
|
+
ops_delivery.add_argument("--json", action="store_true")
|
|
104
|
+
ops_decisions = ops_subparsers.add_parser("decision-logs")
|
|
105
|
+
ops_decisions.add_argument("--loop", choices=["nudge", "keepwarm"])
|
|
106
|
+
ops_decisions.add_argument("--days", type=int, default=3)
|
|
107
|
+
ops_decisions.add_argument("--candidate", type=int)
|
|
108
|
+
ops_decisions.add_argument("--chat-id", type=int)
|
|
109
|
+
ops_decisions.add_argument("--outcome")
|
|
110
|
+
ops_decisions.add_argument("--skip-reason")
|
|
111
|
+
ops_decisions.add_argument("--limit", type=int)
|
|
112
|
+
ops_decisions.add_argument("--json", action="store_true")
|
|
113
|
+
|
|
114
|
+
recruiter_actions = subparsers.add_parser("recruiter-actions")
|
|
115
|
+
recruiter_actions_subparsers = recruiter_actions.add_subparsers(dest="action", required=True)
|
|
116
|
+
actions_list = recruiter_actions_subparsers.add_parser("list")
|
|
117
|
+
actions_list.add_argument("--days", type=int, default=7)
|
|
118
|
+
actions_list.add_argument("--candidate", type=int)
|
|
119
|
+
actions_list.add_argument("--status")
|
|
120
|
+
actions_list.add_argument("--assignment-status")
|
|
121
|
+
actions_list.add_argument("--unresolved", action="store_true")
|
|
122
|
+
actions_list.add_argument("--limit", type=int)
|
|
123
|
+
actions_list.add_argument("--json", action="store_true")
|
|
124
|
+
actions_show = recruiter_actions_subparsers.add_parser("show")
|
|
125
|
+
actions_show.add_argument("action_id")
|
|
126
|
+
actions_show.add_argument("--json", action="store_true")
|
|
127
|
+
|
|
128
|
+
# Config reads belong on the read-only path too: the health sweep asks "why is this off"
|
|
129
|
+
# and must never be able to reach team_config.update from here.
|
|
130
|
+
team_config = subparsers.add_parser("team-config")
|
|
131
|
+
team_config_subparsers = team_config.add_subparsers(dest="action", required=True)
|
|
132
|
+
team_config_read = team_config_subparsers.add_parser("read")
|
|
133
|
+
team_config_read.add_argument("--workflow")
|
|
134
|
+
team_config_read.add_argument("--json", action="store_true")
|
|
135
|
+
team_config_senders = team_config_subparsers.add_parser("senders")
|
|
136
|
+
team_config_senders.add_argument("--json", action="store_true")
|
|
137
|
+
team_config_compare = team_config_subparsers.add_parser("compare")
|
|
138
|
+
team_config_compare.add_argument("--other-team", type=int, required=True)
|
|
139
|
+
team_config_compare.add_argument("--json", action="store_true")
|
|
140
|
+
|
|
141
|
+
candidates = subparsers.add_parser("candidates")
|
|
142
|
+
candidates_subparsers = candidates.add_subparsers(dest="action", required=True)
|
|
143
|
+
candidates_show = candidates_subparsers.add_parser("show")
|
|
144
|
+
candidates_show.add_argument("candidate_id")
|
|
145
|
+
candidates_show.add_argument("--conversations", action="store_true")
|
|
146
|
+
candidates_show.add_argument("--reminders", action="store_true")
|
|
147
|
+
candidates_show.add_argument("--json", action="store_true")
|
|
148
|
+
# Slice 2 evidence reads. They belong on the read-only path too: the health sweep asks
|
|
149
|
+
# "did this actually persist?" and must never be able to reach a write to find out.
|
|
150
|
+
candidates_provenance = candidates_subparsers.add_parser("provenance")
|
|
151
|
+
candidates_provenance.add_argument("candidate_id", type=int)
|
|
152
|
+
candidates_provenance.add_argument("--field")
|
|
153
|
+
candidates_provenance.add_argument("--days", type=int)
|
|
154
|
+
candidates_provenance.add_argument("--limit", type=int)
|
|
155
|
+
candidates_provenance.add_argument("--json", action="store_true")
|
|
156
|
+
candidates_timeline = candidates_subparsers.add_parser("timeline")
|
|
157
|
+
candidates_timeline.add_argument("candidate_id", type=int)
|
|
158
|
+
candidates_timeline.add_argument("--kinds")
|
|
159
|
+
candidates_timeline.add_argument("--days", type=int)
|
|
160
|
+
candidates_timeline.add_argument("--limit", type=int)
|
|
161
|
+
candidates_timeline.add_argument("--json", action="store_true")
|
|
162
|
+
candidates_records = candidates_subparsers.add_parser("records")
|
|
163
|
+
candidates_records.add_argument("candidate_id", type=int)
|
|
164
|
+
candidates_records.add_argument("--record-type")
|
|
165
|
+
candidates_records.add_argument("--days", type=int)
|
|
166
|
+
candidates_records.add_argument("--limit", type=int)
|
|
167
|
+
candidates_records.add_argument("--json", action="store_true")
|
|
168
|
+
|
|
169
|
+
leads = subparsers.add_parser("leads")
|
|
170
|
+
leads_subparsers = leads.add_subparsers(dest="action", required=True)
|
|
171
|
+
leads_maturity = leads_subparsers.add_parser("maturity")
|
|
172
|
+
leads_maturity.add_argument("candidate_id", type=int)
|
|
173
|
+
leads_maturity.add_argument("--json", action="store_true")
|
|
174
|
+
leads_consent = leads_subparsers.add_parser("consent-evidence")
|
|
175
|
+
leads_consent.add_argument("--candidate", type=int)
|
|
176
|
+
leads_consent.add_argument("--limit", type=int)
|
|
177
|
+
leads_consent.add_argument("--json", action="store_true")
|
|
178
|
+
|
|
179
|
+
capabilities = subparsers.add_parser("capabilities")
|
|
180
|
+
capabilities_subparsers = capabilities.add_subparsers(dest="action", required=True)
|
|
181
|
+
capabilities_invoke = capabilities_subparsers.add_parser("invoke")
|
|
182
|
+
capabilities_invoke.add_argument("capability")
|
|
183
|
+
capabilities_invoke.add_argument("--input-json", default="{}")
|
|
184
|
+
capabilities_invoke.add_argument("--json", action="store_true")
|
|
185
|
+
|
|
186
|
+
return parser
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def _dispatch(args: argparse.Namespace, client: APIClient):
|
|
190
|
+
if args.command == "whoami":
|
|
191
|
+
return client.get("/api/whoami/")
|
|
192
|
+
if args.command == "chats":
|
|
193
|
+
if args.action == "diagnose":
|
|
194
|
+
# Diagnose is scoped to one chat, so it takes no window flags to read here.
|
|
195
|
+
return _invoke_capability(client, "chats.diagnose", {"chat_id": args.chat_id})
|
|
196
|
+
inputs: dict[str, object] = {"days": args.days}
|
|
197
|
+
if getattr(args, "limit", None):
|
|
198
|
+
inputs["limit"] = args.limit
|
|
199
|
+
if getattr(args, "sequence", None):
|
|
200
|
+
inputs["sequence_id"] = args.sequence
|
|
201
|
+
if getattr(args, "candidate", None):
|
|
202
|
+
inputs["candidate_id"] = args.candidate
|
|
203
|
+
if args.action == "summary":
|
|
204
|
+
return _invoke_capability(client, "chats.summary", inputs)
|
|
205
|
+
if args.action == "messages":
|
|
206
|
+
inputs["chat_id"] = args.chat_id
|
|
207
|
+
return _invoke_capability(client, "chats.messages", inputs)
|
|
208
|
+
if args.command == "ops":
|
|
209
|
+
if args.action == "delivery-status":
|
|
210
|
+
return _invoke_capability(client, "ops.delivery_status", _set_inputs(args, _DELIVERY_INPUTS))
|
|
211
|
+
if args.action == "decision-logs":
|
|
212
|
+
return _invoke_capability(client, "ops.decision_logs", _set_inputs(args, _DECISION_INPUTS))
|
|
213
|
+
if args.command == "recruiter-actions":
|
|
214
|
+
if args.action == "list":
|
|
215
|
+
return _invoke_capability(client, "recruiter_actions.list", _set_inputs(args, _ACTION_LIST_INPUTS))
|
|
216
|
+
if args.action == "show":
|
|
217
|
+
return _invoke_capability(client, "recruiter_actions.show", {"action_id": args.action_id})
|
|
218
|
+
if args.command == "team-config":
|
|
219
|
+
if args.action == "read":
|
|
220
|
+
return _invoke_capability(client, "team_config.read", _set_inputs(args, {"workflow": "workflow"}))
|
|
221
|
+
if args.action == "senders":
|
|
222
|
+
return _invoke_capability(client, "team_config.senders", {})
|
|
223
|
+
if args.action == "compare":
|
|
224
|
+
return _invoke_capability(client, "team_config.compare", {"other_team_id": args.other_team})
|
|
225
|
+
if args.command == "candidates":
|
|
226
|
+
if args.action == "show":
|
|
227
|
+
params = {}
|
|
228
|
+
if args.conversations:
|
|
229
|
+
params["conversations"] = "1"
|
|
230
|
+
if args.reminders:
|
|
231
|
+
params["reminders"] = "1"
|
|
232
|
+
query = urlencode(params)
|
|
233
|
+
suffix = f"?{query}" if query else ""
|
|
234
|
+
return client.get(f"/api/candidates/{args.candidate_id}/{suffix}")
|
|
235
|
+
if args.action in _EVIDENCE_CAPABILITIES:
|
|
236
|
+
capability, mapping = _EVIDENCE_CAPABILITIES[args.action]
|
|
237
|
+
inputs = {"candidate_id": args.candidate_id, **_set_inputs(args, mapping)}
|
|
238
|
+
return _invoke_capability(client, capability, inputs)
|
|
239
|
+
if args.command == "leads":
|
|
240
|
+
if args.action == "maturity":
|
|
241
|
+
return _invoke_capability(client, "leads.maturity", {"candidate_id": args.candidate_id})
|
|
242
|
+
if args.action == "consent-evidence":
|
|
243
|
+
return _invoke_capability(client, "leads.consent_evidence", _set_inputs(args, _CONSENT_SWEEP_INPUTS))
|
|
244
|
+
if args.command == "capabilities" and args.action == "invoke":
|
|
245
|
+
return _invoke_capability(client, args.capability, _load_json_object(args.input_json))
|
|
246
|
+
raise TalentPrismError(
|
|
247
|
+
code="invalid_command",
|
|
248
|
+
type="invalid_input",
|
|
249
|
+
message="Unsupported read-only command.",
|
|
250
|
+
remediation=(
|
|
251
|
+
"Use whoami, chats summary/messages/diagnose, ops delivery-status/decision-logs, "
|
|
252
|
+
"recruiter-actions list/show, team-config read/senders/compare, "
|
|
253
|
+
"candidates show/provenance/timeline/records, leads maturity/consent-evidence, "
|
|
254
|
+
"or capabilities invoke."
|
|
255
|
+
),
|
|
256
|
+
)
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
_DELIVERY_INPUTS = {
|
|
260
|
+
"candidate": "candidate_id",
|
|
261
|
+
"sequence": "sequence_id",
|
|
262
|
+
"channel": "channel",
|
|
263
|
+
"days": "days",
|
|
264
|
+
"limit": "limit",
|
|
265
|
+
}
|
|
266
|
+
_DECISION_INPUTS = {
|
|
267
|
+
"loop": "loop",
|
|
268
|
+
"days": "days",
|
|
269
|
+
"candidate": "candidate_id",
|
|
270
|
+
"chat_id": "chat_id",
|
|
271
|
+
"outcome": "outcome",
|
|
272
|
+
"skip_reason": "skip_reason",
|
|
273
|
+
"limit": "limit",
|
|
274
|
+
}
|
|
275
|
+
_EVIDENCE_CAPABILITIES = {
|
|
276
|
+
"provenance": ("candidates.provenance", {"field": "field", "days": "days", "limit": "limit"}),
|
|
277
|
+
"timeline": ("candidates.timeline", {"kinds": "kinds", "days": "days", "limit": "limit"}),
|
|
278
|
+
"records": ("candidates.records", {"record_type": "record_type", "days": "days", "limit": "limit"}),
|
|
279
|
+
}
|
|
280
|
+
_CONSENT_SWEEP_INPUTS = {"candidate": "candidate_id", "limit": "limit"}
|
|
281
|
+
_ACTION_LIST_INPUTS = {
|
|
282
|
+
"days": "days",
|
|
283
|
+
"candidate": "candidate_id",
|
|
284
|
+
"status": "status",
|
|
285
|
+
"assignment_status": "assignment_status",
|
|
286
|
+
"unresolved": "unresolved",
|
|
287
|
+
"limit": "limit",
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
def _set_inputs(args: argparse.Namespace, mapping: dict[str, str]) -> dict[str, object]:
|
|
292
|
+
"""Only the flags the operator actually set; omitted ones fall through to capability defaults."""
|
|
293
|
+
inputs: dict[str, object] = {}
|
|
294
|
+
for arg_name, input_name in mapping.items():
|
|
295
|
+
value = getattr(args, arg_name, None)
|
|
296
|
+
if value not in (None, "", False):
|
|
297
|
+
inputs[input_name] = value
|
|
298
|
+
return inputs
|
|
299
|
+
|
|
300
|
+
|
|
301
|
+
def _invoke_capability(client: APIClient, capability: str, inputs: dict[str, object]):
|
|
302
|
+
return client.post(
|
|
303
|
+
"/api/capabilities/invoke/",
|
|
304
|
+
{"capability": capability, "inputs": inputs, "confirmed_write": False},
|
|
305
|
+
)
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def _load_json_object(raw: str) -> dict[str, object]:
|
|
309
|
+
try:
|
|
310
|
+
payload = json.loads(raw)
|
|
311
|
+
except json.JSONDecodeError as exc:
|
|
312
|
+
raise TalentPrismError(
|
|
313
|
+
code="invalid_json",
|
|
314
|
+
type="invalid_input",
|
|
315
|
+
message="Input JSON must be valid JSON.",
|
|
316
|
+
details={"input": raw},
|
|
317
|
+
remediation="Fix the JSON string and rerun the command.",
|
|
318
|
+
) from exc
|
|
319
|
+
if not isinstance(payload, dict):
|
|
320
|
+
raise TalentPrismError(
|
|
321
|
+
code="invalid_json",
|
|
322
|
+
type="invalid_input",
|
|
323
|
+
message="Input JSON must decode to an object.",
|
|
324
|
+
details={"input": raw},
|
|
325
|
+
remediation="Wrap the fields in a JSON object and rerun the command.",
|
|
326
|
+
)
|
|
327
|
+
return payload
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""`tp sequences create|update-step2|update-outreach`: read the sequence file, name the capability.
|
|
2
|
+
|
|
3
|
+
These commands go through the same preview + approval-token flow as every other CLI write. This
|
|
4
|
+
module only turns a file into `(capability, inputs, command)`; `cli.py` sends it. `create` is a
|
|
5
|
+
single atomic capability covering all three sections, so no half-built sequence can exist and no
|
|
6
|
+
partial-failure recovery path is needed.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
import json
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
from .errors import TalentPrismError
|
|
16
|
+
|
|
17
|
+
SEQUENCE_WRITE_ACTIONS = ("create", "update-step2", "update-outreach")
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def sequence_write_request(args: argparse.Namespace) -> tuple[str, dict, str]:
|
|
21
|
+
payload = load_sequence_file(args.file)
|
|
22
|
+
if args.action == "create":
|
|
23
|
+
inputs = {"step1": payload["step1"], "step2": payload["step2"], "step3": payload["step3"]}
|
|
24
|
+
return "sequences.create_draft", inputs, "tp sequences create"
|
|
25
|
+
if args.action == "update-step2":
|
|
26
|
+
inputs = {"sequence_id": args.sequence_id, "step2": payload["step2"]}
|
|
27
|
+
return "sequences.update_settings", inputs, "tp sequences update-step2"
|
|
28
|
+
inputs = {"sequence_id": args.sequence_id, "step3": payload["step3"]}
|
|
29
|
+
return "sequences.update_outreach", inputs, "tp sequences update-outreach"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def load_sequence_file(file_path: str) -> dict:
|
|
33
|
+
path = Path(file_path)
|
|
34
|
+
try:
|
|
35
|
+
contents = path.read_text(encoding="utf-8")
|
|
36
|
+
except OSError as exc:
|
|
37
|
+
raise TalentPrismError(
|
|
38
|
+
code="sequence_file_unreadable",
|
|
39
|
+
type="invalid_input",
|
|
40
|
+
message=f"Could not read sequence file: {path}",
|
|
41
|
+
remediation="Check the file path and permissions.",
|
|
42
|
+
) from exc
|
|
43
|
+
|
|
44
|
+
try:
|
|
45
|
+
if path.suffix.lower() in {".yaml", ".yml"}:
|
|
46
|
+
import yaml
|
|
47
|
+
|
|
48
|
+
payload = yaml.safe_load(contents)
|
|
49
|
+
else:
|
|
50
|
+
payload = json.loads(contents)
|
|
51
|
+
except (ValueError, ImportError) as exc:
|
|
52
|
+
raise TalentPrismError(
|
|
53
|
+
code="sequence_file_malformed",
|
|
54
|
+
type="invalid_input",
|
|
55
|
+
message="Sequence file must be valid YAML or JSON.",
|
|
56
|
+
remediation="Fix the file syntax and ensure it has step1, step2, and step3 sections.",
|
|
57
|
+
) from exc
|
|
58
|
+
|
|
59
|
+
if not isinstance(payload, dict):
|
|
60
|
+
raise _invalid_sequence_file()
|
|
61
|
+
missing = [section for section in ("step1", "step2", "step3") if section not in payload]
|
|
62
|
+
if missing:
|
|
63
|
+
raise _invalid_sequence_file(details={"missing_sections": missing})
|
|
64
|
+
return payload
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _invalid_sequence_file(details: dict | None = None) -> TalentPrismError:
|
|
68
|
+
return TalentPrismError(
|
|
69
|
+
code="sequence_file_invalid",
|
|
70
|
+
type="invalid_input",
|
|
71
|
+
message="Sequence file must contain step1, step2, and step3 sections.",
|
|
72
|
+
details=details or {},
|
|
73
|
+
remediation="Add explicit step1, step2, and step3 sections that mirror the wizard API payloads.",
|
|
74
|
+
)
|
talentprism_cli/skill.py
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
COMMANDS = [
|
|
5
|
+
"tp login [--profile <name>] [--base-url <url>] [--no-browser]",
|
|
6
|
+
"tp logout [--profile <name>]",
|
|
7
|
+
"tp config get",
|
|
8
|
+
"tp config set <name> [--api-key <key>] [--base-url <url>]",
|
|
9
|
+
"tp config set-profile <name>",
|
|
10
|
+
"tp whoami",
|
|
11
|
+
"tp sequences list [--status <status>] [--all]",
|
|
12
|
+
"tp sequences show <uuid>",
|
|
13
|
+
"tp sequences summary <uuid>",
|
|
14
|
+
"tp candidates list --sequence <uuid> [--all]",
|
|
15
|
+
"tp candidates search --query <text> [--all]",
|
|
16
|
+
"tp candidates show <id> [--conversations] [--reminders]",
|
|
17
|
+
"tp candidates add-note <id> --text <note> [--confirm-write --approval-token <token>]",
|
|
18
|
+
"tp candidates send-email <id> [--recipient <email>] --subject <subject> --body <body> [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
|
|
19
|
+
"tp candidates send-sms <id> --message <message> [--recipient <phone>] [--sequence <uuid>] [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
|
|
20
|
+
"tp candidates engaged --sequence <uuid> [--all]",
|
|
21
|
+
"tp candidates provenance <id> [--field <name>] [--days <n>] [--limit <n>]",
|
|
22
|
+
"tp candidates timeline <id> [--kinds <list>] [--days <n>] [--limit <n>]",
|
|
23
|
+
"tp candidates records <id> [--record-type <type>] [--days <n>] [--limit <n>]",
|
|
24
|
+
"tp leads maturity <id>",
|
|
25
|
+
"tp leads consent-evidence [--candidate <id>] [--limit <n>]",
|
|
26
|
+
"tp reminders list [--owner <id>] [--due <when>] [--status <status>] [--all]",
|
|
27
|
+
"tp reminders create [--candidate <id>] --due <when> --text <text> [--confirm-write --approval-token <token>]",
|
|
28
|
+
"tp reminders complete <id> [--confirm-write --approval-token <token>]",
|
|
29
|
+
"tp capabilities list",
|
|
30
|
+
"tp capabilities mcp",
|
|
31
|
+
"tp capabilities commands",
|
|
32
|
+
"tp capabilities invoke <name> --input-json <json> [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
|
|
33
|
+
"tp capabilities preview <name> --input-json <json>",
|
|
34
|
+
"tp capabilities verify <name> --input-json <json>",
|
|
35
|
+
"tp campaigns summary <uuid>",
|
|
36
|
+
"tp campaigns next-actions <uuid>",
|
|
37
|
+
"tp campaigns deliverability <uuid>",
|
|
38
|
+
"tp copilot brief [--recruiter <id>] [--since <when>]",
|
|
39
|
+
"tp copilot ask <prompt>",
|
|
40
|
+
"tp interviews list --sequence <uuid> [--all]",
|
|
41
|
+
"tp interviews show <uuid>",
|
|
42
|
+
"tp interviews create-link --candidate <id> --sequence <uuid> [--base-url <url>] [--confirm-write --approval-token <token>]",
|
|
43
|
+
"tp recruiters notify --candidate <id> --sequence <uuid> --update <text> [--update <text> ...] [--action-needed <text>] [--action-tag <tag>] [--subject <text>] [--message <text>] [--force-channel <channel> ...] [--confirm-write --approval-token <token>]",
|
|
44
|
+
"tp metrics",
|
|
45
|
+
"tp metrics --sequence <uuid>",
|
|
46
|
+
"tp activity summary [--days <n>] [--sequence <uuid>]",
|
|
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>]",
|
|
49
|
+
"tp chats diagnose --chat-id <id>",
|
|
50
|
+
"tp ops delivery-status [--candidate <id>] [--sequence <uuid>] [--channel sms|email|phone] [--days <n>] [--limit <n>]",
|
|
51
|
+
"tp ops decision-logs [--loop nudge|keepwarm] [--days <n>] [--candidate <id>] [--chat-id <id>] [--outcome <outcome>] [--skip-reason <reason>] [--limit <n>]",
|
|
52
|
+
"tp recruiter-actions list [--days <n>] [--unresolved] [--status <status>] [--assignment-status <status>] [--action-type <type>] [--priority <p>] [--candidate <id>] [--limit <n>]",
|
|
53
|
+
"tp recruiter-actions show <action-id>",
|
|
54
|
+
"tp recruiter-actions complete <action-id> [--note <text>] [--confirm-write --approval-token <token>]",
|
|
55
|
+
"tp recruiter-actions escalate <action-id> --reason <text> [--priority <p>] [--confirm-write --approval-token <token>]",
|
|
56
|
+
"tp team-config read [--workflow <name>]",
|
|
57
|
+
"tp team-config senders",
|
|
58
|
+
"tp team-config compare --other-team <id>",
|
|
59
|
+
"tp team-config preview-change --set <field>=<value>",
|
|
60
|
+
"tp team-config update --set <field>=<value> (--eval-run <ref> | --eval-waiver <reason>) [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
|
|
61
|
+
"tp sequences create --file <path> [--dry-run] [--confirm-write --approval-token <token>]",
|
|
62
|
+
"tp sequences update-step2 <uuid> --file <path> [--confirm-write --approval-token <token>]",
|
|
63
|
+
"tp sequences update-outreach <uuid> --file <path> [--confirm-write --approval-token <token>]",
|
|
64
|
+
"tp skill print",
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def skill_markdown() -> str:
|
|
69
|
+
command_list = "\n".join(f"- `{command}`" for command in COMMANDS)
|
|
70
|
+
return f"""---
|
|
71
|
+
name: talentprism
|
|
72
|
+
description: Use the TalentPrism `tp` CLI for API-backed, team-scoped recruiting reads and confirmed, auditable writes.
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
# TalentPrism CLI
|
|
76
|
+
|
|
77
|
+
Use `tp` instead of browser automation when you need to inspect TalentPrism sequences, candidates, interviews, metrics, or create draft sequences.
|
|
78
|
+
|
|
79
|
+
## Install
|
|
80
|
+
|
|
81
|
+
Install with `pipx install talentprism-cli` or `uv tool install talentprism-cli`.
|
|
82
|
+
|
|
83
|
+
## Auth
|
|
84
|
+
|
|
85
|
+
A person signs in with `tp login`: it opens the browser, you pick a team and approve, and the CLI stores a short-lived access token plus a rotating refresh token in `~/.talentprism/config.toml` (mode 0600). Tokens refresh automatically; `tp logout` revokes them. Use `--no-browser` over SSH: it prints a URL and you paste back the redirected address. `tp config get` shows how you are authenticated.
|
|
86
|
+
|
|
87
|
+
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
|
+
|
|
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.
|
|
90
|
+
|
|
91
|
+
A `not_authorized` error is never a reason to rotate the key. It means the key worked and its user lacks the role.
|
|
92
|
+
|
|
93
|
+
## Commands
|
|
94
|
+
|
|
95
|
+
{command_list}
|
|
96
|
+
|
|
97
|
+
## Output And Errors
|
|
98
|
+
|
|
99
|
+
Use `--output json` when an agent needs structured data. Use `tp capabilities list --json` to discover typed Agent Capability schemas and policies generated by the Django registry; use `tp capabilities mcp --json` for MCP-style tool metadata; use `tp capabilities commands --json` to generate `tp capabilities invoke ...` examples from the live registry; use `tp capabilities invoke <name> --input-json <json>` for registry-driven execution. A write command without approval flags is a non-mutating proposal and returns its resolved preview plus a 15-minute, one-shot approval token. Execute only by repeating the exact command and arguments with `--confirm-write --approval-token <token>`. Successful command data is written to stdout. Errors are JSON on stderr with `code`, `type`, `message`, `details`, and `remediation`.
|
|
100
|
+
|
|
101
|
+
Chat and message counts never include simulator or eval-fork conversations - they carry a real team and a real candidate but were typed by a tester, so counting them as engagement has repeatedly misled production audits. `tp activity summary` reports what it left out under `excluded` (`chats`, `chat_messages`), so "12 conversations" is never silently "9 real plus 3 test runs".
|
|
102
|
+
|
|
103
|
+
## Preview, Verify, And Idempotency
|
|
104
|
+
|
|
105
|
+
`tp capabilities preview <name>` resolves what a write would actually do without doing it: exact recipients and counts, the exact rendered message, the resolved sender, the resolved sending window, and every exclusion with its reason. A preview is a read, so it never needs `--confirm-write`. Run it before any send.
|
|
106
|
+
|
|
107
|
+
Every write approval is bound to the capability name and the SHA-256 hash of the exact normalized inputs. It expires after 15 minutes and can be consumed once. A changed recipient, body, due date, setting, or idempotency key is a different write and requires a new preview. `--confirm-write` and `--approval-token` must always be passed together.
|
|
108
|
+
|
|
109
|
+
`tp capabilities verify <name>` re-reads the durable record a write claims to have produced. **Send proof is path-dependent**: ordered-outbox sends (`candidate_outreach.send_sms`, TinyLLM SMS turns) record the Twilio SID on `OutboundSMSMessage.twilio_sid` and write no touchpoint; touchpoint sends (`send_bulk_sms`, keep-warm) record it on `OutreachTouchpoint.message_sid` and write no queue row. The absence of a row in either model is not evidence that nothing was sent - check which path was used first. `tp ops delivery-status` reports both paths with that warning attached.
|
|
110
|
+
|
|
111
|
+
Pass `--idempotency-key <key>` to any write. Repeating the same call with the same key returns the original receipt instead of performing the action twice. Use it for anything that could be retried.
|
|
112
|
+
|
|
113
|
+
**Candidate-facing sends require a key.** `candidate_outreach.send_sms` and `candidate_outreach.send_email` reject a call with no `idempotency_key`, because a duplicate there is a real second message to a real candidate. `tp candidates send-sms` and `tp candidates send-email` generate one for you, so typing the command still works with no extra arguments; pass `--idempotency-key` when you want a retry of that exact command to replay instead of sending again. Calling those capabilities through `tp capabilities invoke` requires the key in `--input-json`.
|
|
114
|
+
|
|
115
|
+
`tp capabilities commands --json` reports `preview_supported`, `verify_supported`, and the reason when a write is exempt from preview.
|
|
116
|
+
|
|
117
|
+
Exit codes: 0 success, 2 invalid input, 3 auth, 4 not found, 5 validation, 6 transient failure, 7 schema mismatch.
|
|
118
|
+
|
|
119
|
+
## Production Diagnostics
|
|
120
|
+
|
|
121
|
+
**Reach for `tp` before `kamal`.** Deploys and true infrastructure work stay on kamal; diagnostics do not. Every command below is a team-scoped, audited read through the capability registry, so it needs no shell quoting, no base64, and leaves an audit trail.
|
|
122
|
+
|
|
123
|
+
- `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
|
+
- `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
|
+
- `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.
|
|
126
|
+
- `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.
|
|
127
|
+
|
|
128
|
+
`ops.*` reads require the admin role - see Auth above. Everything else here works for a plain member.
|
|
129
|
+
|
|
130
|
+
## Evidence Reads
|
|
131
|
+
|
|
132
|
+
These answer "show me the record, not the conclusion". All are member-level reads.
|
|
133
|
+
|
|
134
|
+
- `tp candidates provenance <id>` - per-field history of what we know: old value, new value, what wrote it, and when. Add `--field rate_preference` for one fact. A stored value with no event behind it comes back under `unattributed`: it is real, but nothing records where it came from. There is no named actor on a memory change, only a write source (`tinyllm`, `webhook`, `vapi`) - report it that way.
|
|
135
|
+
- `tp candidates timeline <id>` - one chronological view across chats, outreach, calls, learned facts, applications, referrals, alerts and handoffs. Entries describing the same event are merged and list what they absorbed under `related_records`; `totals_by_kind` counts source rows and stays true when the page is truncated.
|
|
136
|
+
- `tp candidates records <id>` - existence check: is there actually an application / referral / alert subscription / recruiter handoff / audited profile update? Use it whenever a transcript claims an action succeeded. `absent` is the answer, not an empty result.
|
|
137
|
+
- `tp leads maturity <id>` - completeness with the missing facts named and where each would come from. Compare `computed` against `stored`: when they disagree the stored tier is stale and must not be used to package the lead.
|
|
138
|
+
- `tp leads consent-evidence --candidate <id>` - the sharing decision plus the verbatim quote, traced back to the message the candidate actually sent. **A decision with no quote, or a quote that is not in the candidate's own words, is reported as `unevidenced` and must never be repeated as a clean decline**: `share_consent=False` permanently blocks a lead from being sold and is never re-asked. Run it with no `--candidate` for a team-wide structural sweep, which checks only whether a quote exists at all. A quote traced to a `Simulator Chat` or `Eval Fork:` conversation (`quote_source.is_simulator_chat`) was typed by a tester, not sent by the candidate: it is `unevidenced` too, and the write gate now refuses to record a decline on that basis.
|
|
139
|
+
|
|
140
|
+
## Team Configuration
|
|
141
|
+
|
|
142
|
+
- `tp team-config read` - what this team is actually configured to do, and **why a workflow is off**. It reports the model that really runs (a model missing from the runtime's supported list falls back to the platform default, so what is stored is not what runs), whether the model honours the configured reasoning effort, which planners and workers are active, the team's custom instructions, and one row per gated workflow naming the model field that gates it and how to turn it on. `--workflow keepwarm` narrows it to one.
|
|
143
|
+
- `tp team-config senders` - configured numbers, which one resolves as default, and where recruiter alerts land. **It never returns a credential**: Messaging Service SIDs, webhook secrets and embed tokens come back as configured / not configured with a four-character tail. Admin only.
|
|
144
|
+
- `tp team-config compare --other-team <id>` - diff against another team you belong to. It refuses a team you are not a member of. Admin only.
|
|
145
|
+
- `tp team-config preview-change --set <field>=<value>` - what the change would really do. A setting the runtime would ignore is reported as `no_change` with the reason, so a config edit that would have achieved nothing is caught before it is made.
|
|
146
|
+
- `tp team-config update ...` - return the exact non-mutating proposal. Repeat it unchanged with `--confirm-write --approval-token <token>` to apply it and invalidate the runtime config cache. Admin only.
|
|
147
|
+
|
|
148
|
+
**The eval gate is enforced here, not just documented.** Changing the model, provider, temperature, reasoning effort, a worker enable flag, or a tool-gating flag changes production agent behaviour, and `team_config.update` refuses such a change unless you record either `--eval-run` (the suite and verdict covering it) or `--eval-waiver` (why it ships without one). Either is accepted and both are written to the audit row; only saying nothing is refused. A waiver is not an eval run - it is a named decision to skip one, on the record. Every such change also owes an entry in the agent changelog, which this CLI does not write.
|
|
149
|
+
|
|
150
|
+
## Sequence Files
|
|
151
|
+
|
|
152
|
+
`tp sequences create --file <path>` reads a YAML or JSON file with `step1` (parsed job draft), `step2` (candidate-experience settings) and `step3` (outreach templates), and creates a **Draft** sequence. Without approval flags it returns a preview (title, Draft status, each outreach step's channel) and a token; repeat the exact command with `--confirm-write --approval-token <token>` to create it. Creation is one transaction: if any section is rejected nothing is created, so there is no half-built sequence to repair. `--dry-run` only echoes the parsed file. `tp sequences update-step2 <uuid>` and `update-outreach <uuid>` re-apply one section to an existing Draft the same way. Step 2 overwrites every setting: a key left out of the file is reset, and the preview lists those keys under `omitted_settings`. These three commands never activate a sequence or send outreach; activation is a separate write (`sequence_setup.launch`, see Safety Boundaries).
|
|
153
|
+
|
|
154
|
+
## Safety Boundaries
|
|
155
|
+
|
|
156
|
+
Reads are team-scoped through Django permissions. Every registry write exposed by the CLI—including draft sequence creation and updates, notes, reminders, candidate sends, interview links, recruiter notifications/actions, and team configuration—first returns a preview and a capability-and-input-bound approval token. The server rejects missing, expired, reused, cross-team, cross-user, cross-source, cross-capability, or changed-input approvals. The CLI can add notes, create and complete reminders, send emails and SMS to candidates, create interview links, notify recruiters, complete and escalate recruiter actions, create and update draft sequences, and (admins only) update team configuration. The CLI does not trigger voice calls and has no command to delete data or to pause, resume or delete a sequence. It does not bypass Django permissions or team scoping.
|
|
157
|
+
|
|
158
|
+
`tp capabilities invoke` can also run any other write capability the server registers for the CLI, behind the same preview and approval. Run `tp capabilities commands --json` for the live list. As of this writing it includes `sequence_setup.launch` (activates a draft sequence), `campaign_setup.run_tests`, `candidates.update_profile` (changes candidate profile fields), `reminders.snooze` and `reminders.cancel`, `recruiter_email.send`, `shortlists.send_packet` and `sequence_setup.save_voice_assistant`. Use them only when the recruiter has asked for exactly that.
|
|
159
|
+
|
|
160
|
+
**Candidate sends refuse a do-not-contact recipient.** `candidate_outreach.send_sms` and `.send_email` fail with `recipient_suppressed` when the candidate has `CandidateMemory.do_not_contact` set, is marked inactive, or has an unsubscribed/suppressed/invalid contact point on that channel. That is a compliance stop, not a transient error: do not retry it. The same exclusions appear in `tp capabilities preview` before you send.
|
|
161
|
+
|
|
162
|
+
## Unsupported
|
|
163
|
+
|
|
164
|
+
Do not use this CLI for triggering voice calls, deleting data, pausing, resuming or deleting sequences, bulk messaging outside the gated outreach commands, or direct database access. Activating a sequence and changing candidate profile fields are possible only through `tp capabilities invoke` with preview and approval, and only when the recruiter asked for exactly that.
|
|
165
|
+
"""
|