formist-cli 0.1.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.
@@ -0,0 +1,152 @@
1
+ """``fm usage-tokens``: system-wide LLM token spend, over ``GET /admin/usage/tokens``.
2
+
3
+ Read-only; there is nothing to apply here.
4
+
5
+ A zero can mean "measured, and it really is zero" or "unmeasured", and
6
+ those are different facts. Every bucket the server returns carries
7
+ ``unmeasured_calls`` / ``unpriced_calls`` and the derived
8
+ ``tokens_are_lower_bound`` / ``cost_is_lower_bound`` flags. This
9
+ renderer prints them on every row, not only when they are non-zero,
10
+ since a flag that only sometimes appears is easy to miss when scanning
11
+ a column.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import json
18
+
19
+ from formist_cli import api, context
20
+ from formist_cli.cli_support import PLATFORM_ADMIN_GATE_NOTE, add_admin_flag
21
+ from formist_cli.cli_support import as_dict as _shared_usage_payload
22
+ from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
23
+
24
+ GROUP_BY_CHOICES = ("source", "operation", "space", "user", "model", "provider", "day")
25
+
26
+
27
+ class UsageTokensError(Exception):
28
+ """A refusal about the usage-tokens surface, written for an operator."""
29
+
30
+
31
+ def render(payload: dict) -> str:
32
+ lines = [
33
+ f"window {payload.get('since')} .. {payload.get('until')}"
34
+ f" group_by={payload.get('group_by')}",
35
+ f"regions {', '.join(payload.get('regions') or [])}",
36
+ ]
37
+ if payload.get("meter_enabled") is False:
38
+ lines.append(
39
+ " TOKEN_METER_ENABLED is OFF on this deployment, every number below "
40
+ "is stale by however long it has been off"
41
+ )
42
+ lines.append("")
43
+ lines.append(_row("TOTAL", payload.get("totals") or {}))
44
+ lines.append("")
45
+ groups = payload.get("groups") or []
46
+ if not groups:
47
+ lines.append("(no rows in this window)")
48
+ for g in groups:
49
+ lines.append(_row(str(g.get("label") or g.get("key") or "(unattributed)"), g))
50
+ if payload.get("truncated"):
51
+ lines.append(
52
+ f"\n{len(groups)} of {payload.get('group_count')} groups shown, MORE "
53
+ "EXIST. Raise --limit for the rest."
54
+ )
55
+ return "\n".join(lines)
56
+
57
+
58
+ def _row(label: str, bucket: dict) -> str:
59
+ """Render one bucket. The two lower-bound flags are printed
60
+ unconditionally, since a flag that only shows up when it fires is
61
+ easy to miss when scanning.
62
+ """
63
+ tokens_flag = "LOWER BOUND" if bucket.get("tokens_are_lower_bound") else "measured"
64
+ cost_flag = "LOWER BOUND" if bucket.get("cost_is_lower_bound") else "priced"
65
+ return (
66
+ f"{label:<28.28} calls={bucket.get('calls', 0):<6} "
67
+ f"tokens={bucket.get('total_tokens', 0):<10} ({tokens_flag}) "
68
+ f"cost=${bucket.get('estimated_cost_usd', 0):<10} ({cost_flag}) "
69
+ # Subsets of tokens above, not additive, same as cached_input_tokens,
70
+ # which this line does not print either (see `--json` for the full
71
+ # per-bucket breakdown). Surfaced here because cache_write is priced
72
+ # at a premium.
73
+ f"cache_write={bucket.get('cache_write_tokens', 0)} "
74
+ f"reasoning={bucket.get('reasoning_tokens', 0)} "
75
+ f"unmeasured={bucket.get('unmeasured_calls', 0)} "
76
+ f"unpriced={bucket.get('unpriced_calls', 0)} "
77
+ f"failed={bucket.get('failed_calls', 0)}"
78
+ )
79
+
80
+
81
+ _HELP = "system-wide LLM token spend, aggregated across every region (admin, read-only)"
82
+
83
+ _DESCRIPTION = """Total LLM token spend across the whole deployment, sliceable by
84
+ source, operation, space, user, model, provider or day.
85
+
86
+ fm usage-tokens --host evane
87
+ fm usage-tokens --host evane --group-by space --since 2026-09-01
88
+ fm usage-tokens --host evane --group-by model --space <space-uuid>
89
+
90
+ A zero in this table can mean "measured, and it really is zero" or "the
91
+ backend reported no usage"; those are different facts. Every row is labelled
92
+ `measured`/`LOWER BOUND` (tokens) and `priced`/`LOWER BOUND` (cost) so the two
93
+ are never read as the same thing. `unmeasured`/`unpriced`/`failed` are the
94
+ counts behind those labels.
95
+ """
96
+
97
+
98
+ def _add_arguments(parser: argparse.ArgumentParser) -> None:
99
+ parser.add_argument(
100
+ "--host",
101
+ default=argparse.SUPPRESS,
102
+ metavar="HOST",
103
+ help="deployment name or API origin (default: formist, or `fm use` for reads); "
104
+ "a write never inherits it",
105
+ )
106
+ parser.add_argument("--group-by", dest="group_by", choices=GROUP_BY_CHOICES, default="source")
107
+ parser.add_argument("--since", default=None, help="ISO-8601; default: 7 days before --until")
108
+ parser.add_argument("--until", default=None, help="ISO-8601; default: now")
109
+ parser.add_argument("--space", dest="space_id", default=None, help="filter to one space UUID")
110
+ parser.add_argument("--user", dest="user_id", default=None, help="filter to one user UUID")
111
+ parser.add_argument("--source", default=None)
112
+ parser.add_argument("--operation", default=None)
113
+ parser.add_argument("--model", default=None)
114
+ parser.add_argument("--provider", default=None)
115
+ parser.add_argument("--limit", type=int, default=None, help="max groups returned (server caps it)")
116
+ parser.add_argument("--json", action="store_true", help="raw JSON instead of a report")
117
+
118
+
119
+ def add_parser(subparsers) -> argparse.ArgumentParser:
120
+ parser = subparsers.add_parser(
121
+ "usage-tokens", help=_HELP, description=_DESCRIPTION, epilog=PLATFORM_ADMIN_GATE_NOTE,
122
+ formatter_class=argparse.RawDescriptionHelpFormatter,
123
+ )
124
+ _add_arguments(parser)
125
+ add_admin_flag(parser)
126
+ return parser
127
+
128
+
129
+ def build_standalone_parser() -> argparse.ArgumentParser:
130
+ return _build_standalone_parser(add_parser)
131
+
132
+
133
+ def run(args) -> int:
134
+ ctx = context.resolve(args, need_token=True)
135
+ params: dict[str, str] = {"group_by": getattr(args, "group_by", None) or "source"}
136
+ for flag in (
137
+ "since", "until", "space_id", "user_id", "source", "operation", "model", "provider",
138
+ ):
139
+ value = getattr(args, flag, None)
140
+ if value is not None:
141
+ params[flag] = str(value)
142
+ if getattr(args, "limit", None) is not None:
143
+ params["limit"] = str(args.limit)
144
+
145
+ payload = api.admin_get(ctx.target, "/admin/usage/tokens", token=ctx.token, params=params)
146
+ payload = _usage_payload(payload)
147
+ print(json.dumps(payload, indent=2, ensure_ascii=False) if args.json else render(payload))
148
+ return 0
149
+
150
+
151
+ def _usage_payload(payload: object) -> dict:
152
+ return _shared_usage_payload(payload, what="/admin/usage/tokens", error=UsageTokensError)
formist_cli/users.py ADDED
@@ -0,0 +1,384 @@
1
+ """``fm users`` - platform user rows, over routes that already exist.
2
+
3
+ GET /admin/users every user, paginated
4
+ GET /admin/users/{id} one user
5
+ GET /admin/users/{id}/spaces their memberships, with region and role
6
+
7
+ The defect this command can fall into is not the HTTP call: it is a
8
+ report that is true about what it fetched and false about what exists.
9
+ ``/admin/users`` is paginated and capped by ``MAX_LIMIT``, so printing 50
10
+ rows without saying there are 312 tells an operator the platform has 50
11
+ users. Every number on screen is real and the conclusion is wrong.
12
+
13
+ :func:`render_list` therefore reports shown and total together, and names
14
+ the flag that widens the view. It also stays quiet when nothing was
15
+ truncated: an alarm that fires when nothing is wrong is an alarm nobody
16
+ reads, and then it is not there for the case that matters.
17
+
18
+ What the surface cannot do is said in ``--help`` because the operator
19
+ meets that and not this file. ``/admin/users`` takes ``limit``/``offset``
20
+ and nothing else: there is no ``q``. An empty page therefore does not
21
+ mean "no such user", and a ``--help`` that stayed silent would invite
22
+ exactly that reading.
23
+
24
+ Reports what can be known, and labels how far each field can be trusted.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import argparse
30
+ import json
31
+
32
+ from formist_cli import api, context
33
+ from formist_cli.cli_support import (
34
+ PLATFORM_ADMIN_GATE_NOTE,
35
+ add_admin_flag,
36
+ pagination_footer,
37
+ render_grant_rows,
38
+ )
39
+ from formist_cli.cli_support import as_dict as _shared_as_dict
40
+ from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
41
+ from formist_cli.targets import require_space_id
42
+
43
+ SUBJECTS = (
44
+ "list", "show", "spaces", "grants",
45
+ "create", "set", "add-space", "remove-space",
46
+ )
47
+ DEFAULT_SUBJECT = "list"
48
+
49
+ #: Write subjects, resolved with ``for_write=True`` (never inherits ``--env``
50
+ #: from ``fm use``), same reasoning as every other mutating command in this CLI.
51
+ _WRITE_SUBJECTS = frozenset({"create", "set", "add-space", "remove-space"})
52
+
53
+
54
+ class UsersError(Exception):
55
+ """A refusal about the user surface, written for an operator."""
56
+
57
+
58
+ def canonical_subject(subject: str | None) -> str:
59
+ if subject is None:
60
+ return DEFAULT_SUBJECT
61
+ value = subject.strip().lower()
62
+ if value not in SUBJECTS:
63
+ raise UsersError(
64
+ f"unknown subcommand {subject!r}. Valid: {', '.join(SUBJECTS)}.\n"
65
+ " list every user on the platform (paginated)\n"
66
+ " show one user by id\n"
67
+ " spaces a user's space memberships, with region and role\n"
68
+ " grants every credential this deployment holds for them (admin)\n"
69
+ " create provision a user by email (no password, magic-link/OAuth)\n"
70
+ " set update name and/or --platform-admin on/off\n"
71
+ " add-space assign (or re-role) a user in a space\n"
72
+ " remove-space unassign a user from a space"
73
+ )
74
+ return value
75
+
76
+
77
+ # ===========================================================================
78
+ # Rendering
79
+ # ===========================================================================
80
+ def render_list(payload: dict) -> str:
81
+ """A scannable table that never overstates how much of the platform it saw."""
82
+ items = payload.get("items") or []
83
+ total = payload.get("total")
84
+ offset = int(payload.get("offset") or 0)
85
+
86
+ lines = [
87
+ f"{'email':<38} {'name':<22} {'admin':<6} {'waiting':<8} id",
88
+ f"{'-' * 38} {'-' * 22} {'-' * 6} {'-' * 8} {'-' * 8}",
89
+ ]
90
+ for row in items:
91
+ lines.append(
92
+ f"{str(row.get('email') or '-'):<38.38} "
93
+ f"{str(row.get('name') or '-'):<22.22} "
94
+ f"{('yes' if row.get('is_platform_admin') else ''):<6} "
95
+ f"{('yes' if row.get('waiting') else ''):<8} "
96
+ f"{_short(row.get('id'))}"
97
+ )
98
+
99
+ lines.append("\n" + pagination_footer(shown=len(items), total=total, offset=offset))
100
+ return "\n".join(lines)
101
+
102
+
103
+ def render_user(payload: dict) -> str:
104
+ return json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=True)
105
+
106
+
107
+ def render_spaces(payload: dict) -> str:
108
+ """A user's memberships. Says so when there are none.
109
+
110
+ Blank output is indistinguishable from a command that failed quietly, which is
111
+ the single most common way a read tool misleads.
112
+ """
113
+ items = payload.get("items") or []
114
+ if not items:
115
+ return "(this user is a member of no spaces)"
116
+ lines = [
117
+ f"{'space':<38} {'region':<8} {'role':<10} id",
118
+ f"{'-' * 38} {'-' * 8} {'-' * 10} {'-' * 8}",
119
+ ]
120
+ for row in items:
121
+ lines.append(
122
+ f"{str(row.get('name') or '-'):<38.38} "
123
+ f"{str(row.get('region') or '-'):<8} "
124
+ f"{str(row.get('role') or '-'):<10} "
125
+ f"{_short(row.get('space_id'))}"
126
+ )
127
+ return "\n".join(lines)
128
+
129
+
130
+ def render_grants(payload: dict) -> str:
131
+ """Every credential held for one user, plus WHERE we looked.
132
+
133
+ ``regions_scanned`` is printed rather than dropped: personal connectors are
134
+ region-local, so "this user has no Google connector" and "we only searched one
135
+ database" would otherwise be the same empty table.
136
+ """
137
+ items = payload.get("items") or []
138
+ regions = payload.get("regions_scanned") or []
139
+ body = render_grant_rows(items)
140
+ return f"{body}\n\nregions scanned: {', '.join(str(r) for r in regions) or '(none)'}"
141
+
142
+
143
+ def render_membership_change(payload: dict, *, removed: bool) -> str:
144
+ """The result of ``add-space`` / ``remove-space``, an operator-facing line,
145
+ not a raw dict, because the interesting fact (which role, which space) is
146
+ two keys the server already named."""
147
+ if removed:
148
+ return f"removed user={payload.get('user_id')} space={payload.get('space_id')}"
149
+ return (
150
+ f"assigned user={payload.get('user_id')} space={payload.get('space_id')} "
151
+ f"role={payload.get('role')}"
152
+ )
153
+
154
+
155
+ def _short(value) -> str:
156
+ text = str(value or "-")
157
+ return text[:8] if len(text) > 8 else text
158
+
159
+
160
+ # ===========================================================================
161
+ # CLI
162
+ # ===========================================================================
163
+ _HELP = "platform user rows: list, show one, or list a user's spaces (admin)"
164
+
165
+ _DESCRIPTION = """Read platform user rows over the admin API.
166
+
167
+ THESE ROWS LIVE IN THE GLOBAL DATABASE regardless of which region a space
168
+ is in: auth is not per-region. Pointing this at a regional API and seeing
169
+ nothing would mean the admin surface is not served there, never that the
170
+ user is absent. /admin is Global-only and `fm` refuses to send it
171
+ elsewhere before opening a socket.
172
+
173
+ THERE IS NO SERVER-SIDE SEARCH. `/admin/users` accepts limit and offset and
174
+ nothing else: no `q`, no email filter. So an empty page means "not on this
175
+ page", NOT "no such user". Page with --offset, or pipe --json to a filter.
176
+
177
+ Every listing reports how many rows it showed AND how many exist, because a
178
+ page of 50 printed on its own reads as a platform with 50 users.
179
+
180
+ WRITES (``create`` / ``set`` / ``add-space`` / ``remove-space``)
181
+ ------------------------------------------------------------------
182
+ These reach the same mutating ``/admin/users*`` routes the admin panel
183
+ uses. Every mutating ``/admin`` route writes a ``platform_audit_log`` row
184
+ on the server regardless of which client called it; that is a server-side
185
+ property, not something this CLI has to arrange.
186
+
187
+ None of the four has a server-side dry run (unlike ``fm space-plan``,
188
+ which was built with one): each takes effect immediately, the same as
189
+ clicking the equivalent button in the admin panel. ``--env`` therefore
190
+ never inherits from ``fm use`` on a write, same rule as everywhere else in
191
+ this CLI: a write must be told, not remembered.
192
+
193
+ ``set --platform-admin off`` on your own account is refused by the server
194
+ (``cannot-self-demote``); revoking the platform's last admin is refused too
195
+ (``last-platform-admin``); both errors are printed verbatim, not swallowed.
196
+ """
197
+
198
+
199
+
200
+ def _add_arguments(parser: argparse.ArgumentParser) -> None:
201
+ parser.add_argument(
202
+ "subject", nargs="?",
203
+ help=f"one of: {', '.join(SUBJECTS)} (default: {DEFAULT_SUBJECT})",
204
+ )
205
+ parser.add_argument(
206
+ "user_id", nargs="?",
207
+ help="user UUID (for `show` / `spaces` / `grants` / `set` / `add-space` / `remove-space`)",
208
+ )
209
+ parser.add_argument(
210
+ "--host",
211
+ default=argparse.SUPPRESS,
212
+ metavar="HOST",
213
+ help="deployment name or API origin (default: formist, or `fm use` for reads); "
214
+ "a write never inherits it",
215
+ )
216
+ parser.add_argument("--limit", type=int, default=None, help="rows per page (server caps it)")
217
+ parser.add_argument("--offset", type=int, default=None, help="skip this many rows")
218
+ parser.add_argument("--json", action="store_true", help="raw JSON instead of a table")
219
+ parser.add_argument("--email", default=None, help="`create`: the new user's email")
220
+ parser.add_argument("--name", default=None, help="`create`/`set`: display name")
221
+ parser.add_argument(
222
+ "--platform-admin", dest="platform_admin", choices=("on", "off"), default=None,
223
+ help="`set`: grant/revoke User.is_platform_admin, the highest-blast-radius "
224
+ "flag on this whole surface",
225
+ )
226
+ parser.add_argument(
227
+ "--space", default=None,
228
+ help="`add-space`/`remove-space`: the space UUID (never a name)",
229
+ )
230
+ parser.add_argument(
231
+ "--role", default="USER",
232
+ help="`add-space`: OWNER, ADMIN, USER or VIEWER (default: USER)",
233
+ )
234
+ add_admin_flag(parser)
235
+
236
+
237
+ def add_parser(subparsers) -> argparse.ArgumentParser:
238
+ parser = subparsers.add_parser(
239
+ "users", help=_HELP, description=_DESCRIPTION, epilog=PLATFORM_ADMIN_GATE_NOTE,
240
+ formatter_class=argparse.RawDescriptionHelpFormatter,
241
+ )
242
+ _add_arguments(parser)
243
+ return parser
244
+
245
+
246
+ def build_standalone_parser() -> argparse.ArgumentParser:
247
+ """The same parser, detached, so ``--help`` can be asserted in a test.
248
+
249
+ See :func:`formist_cli.cli_support.build_standalone_parser` for why the
250
+ body lives there; this stays a one-line, no-argument wrapper so callers
251
+ keep calling ``users.build_standalone_parser()``.
252
+ """
253
+ return _build_standalone_parser(add_parser)
254
+
255
+
256
+ def run(args) -> int:
257
+ subject = canonical_subject(getattr(args, "subject", None))
258
+ if subject in _WRITE_SUBJECTS:
259
+ return _run_write(subject, args)
260
+ # need_token is redundant for this command and kept on purpose. Every read
261
+ # below goes through api.admin_get, which has its own "no stored session"
262
+ # refusal, so removing this changes nothing observable here.
263
+ #
264
+ # It stays because this is one command in a series, and other commands
265
+ # reach api.get, which does not guard. A resolver that refuses for some
266
+ # commands and not others is the drift this module was extracted to end.
267
+ ctx = context.resolve(args, need_token=True)
268
+
269
+ params: dict[str, str] = {}
270
+ if getattr(args, "limit", None) is not None:
271
+ params["limit"] = str(args.limit)
272
+ if getattr(args, "offset", None) is not None:
273
+ params["offset"] = str(args.offset)
274
+
275
+ if subject == "list":
276
+ payload = api.admin_get(ctx.target, "/admin/users", token=ctx.token, params=params)
277
+ print(json.dumps(payload, indent=2) if args.json else render_list(_as_dict(payload)))
278
+ return 0
279
+
280
+ user_id = getattr(args, "user_id", None)
281
+ if not user_id:
282
+ raise UsersError(
283
+ f"`fm users {subject}` needs a user id.\n"
284
+ "-> `fm users list` prints them (id is the last column)."
285
+ )
286
+
287
+ if subject == "show":
288
+ payload = api.admin_get(ctx.target, f"/admin/users/{user_id}", token=ctx.token)
289
+ print(render_user(_as_dict(payload)))
290
+ return 0
291
+
292
+ if subject == "grants":
293
+ payload = api.admin_get(
294
+ ctx.target, f"/admin/users/{user_id}/grants", token=ctx.token
295
+ )
296
+ if args.json:
297
+ print(json.dumps(payload, indent=2))
298
+ else:
299
+ print(render_grants(_as_dict(payload)))
300
+ return 0
301
+
302
+ payload = api.admin_get(ctx.target, f"/admin/users/{user_id}/spaces", token=ctx.token)
303
+ print(json.dumps(payload, indent=2) if args.json else render_spaces(_as_dict(payload)))
304
+ return 0
305
+
306
+
307
+ def _run_write(subject: str, args) -> int:
308
+ """The four mutating subjects. Resolved ``for_write=True``, see the module
309
+ docstring: none of these has a server-side dry run, so ``--env`` must be told
310
+ on every call rather than inherited from ``fm use``."""
311
+ ctx = context.resolve(args, for_write=True, need_token=True)
312
+
313
+ if subject == "create":
314
+ email = (getattr(args, "email", None) or "").strip()
315
+ if not email:
316
+ raise UsersError("`fm users create` needs --email <address>")
317
+ body = {"email": email}
318
+ if getattr(args, "name", None):
319
+ body["name"] = args.name
320
+ payload = api.admin_post(ctx.target, "/admin/users", body, token=ctx.token)
321
+ print(json.dumps(payload, indent=2) if args.json else render_user(_as_dict(payload)))
322
+ return 0
323
+
324
+ user_id = getattr(args, "user_id", None)
325
+ if not user_id:
326
+ raise UsersError(
327
+ f"`fm users {subject}` needs a user id.\n"
328
+ "-> `fm users list` prints them (id is the last column)."
329
+ )
330
+
331
+ if subject == "set":
332
+ fields: dict = {}
333
+ if getattr(args, "name", None):
334
+ fields["name"] = args.name
335
+ if getattr(args, "platform_admin", None) is not None:
336
+ fields["is_platform_admin"] = args.platform_admin == "on"
337
+ if not fields:
338
+ raise UsersError(
339
+ "nothing to set. Name at least one of:\n"
340
+ " --name <text>\n"
341
+ " --platform-admin on|off"
342
+ )
343
+ payload = api.admin_patch(
344
+ ctx.target, f"/admin/users/{user_id}", fields, token=ctx.token
345
+ )
346
+ print(json.dumps(payload, indent=2) if args.json else render_user(_as_dict(payload)))
347
+ return 0
348
+
349
+ space = getattr(args, "space", None)
350
+ if not space:
351
+ raise UsersError(
352
+ f"`fm users {subject}` needs --space <uuid>.\n"
353
+ "-> `fm spaces --host evane` prints them."
354
+ )
355
+ space = require_space_id(space)
356
+
357
+ if subject == "add-space":
358
+ body = {"space_id": space, "role": args.role}
359
+ payload = api.admin_post(
360
+ ctx.target, f"/admin/users/{user_id}/spaces", body, token=ctx.token
361
+ )
362
+ payload = _as_dict(payload)
363
+ print(json.dumps(payload, indent=2) if args.json else
364
+ render_membership_change(payload, removed=False))
365
+ return 0
366
+
367
+ # remove-space
368
+ payload = api.admin_delete(
369
+ ctx.target, f"/admin/users/{user_id}/spaces/{space}", token=ctx.token
370
+ )
371
+ payload = _as_dict(payload)
372
+ print(json.dumps(payload, indent=2) if args.json else
373
+ render_membership_change(payload, removed=True))
374
+ return 0
375
+
376
+
377
+ def _as_dict(payload: object) -> dict:
378
+ """:func:`formist_cli.cli_support.as_dict`, bound to this command's error type.
379
+
380
+ The body moved to ``cli_support`` when ``fm space-plan`` needed the identical
381
+ check; this stays as the one-line binding so the call sites here, and callers
382
+ asserting on ``users._as_dict`` directly, are unchanged.
383
+ """
384
+ return _shared_as_dict(payload, what="/admin/users", error=UsersError)