@acarmisc/backstage-plugin-litellm 0.33.0 → 0.34.0

package/README.md

@@ -1,97 +1,86 @@
 # @acarmisc/backstage-plugin-litellm
 
-Frontend for the **Backstage LiteLLM Governance Plugin** — lets developers manage LiteLLM virtual API keys and monitor AI model usage directly from Backstage.
+Frontend for the **Backstage LiteLLM Governance Plugin** — lets developers manage
+their LiteLLM virtual keys and follow their AI usage and budgets from Backstage.
 
-Built with the [New Frontend System](https://backstage.io/docs/frontend-system/) (`@backstage/frontend-plugin-api`) and Material-UI.
+Built for the [New Frontend System](https://backstage.io/docs/frontend-system/)
+(`@backstage/frontend-plugin-api`). It needs the backend,
+[`@acarmisc/backstage-plugin-litellm-backend`](https://www.npmjs.com/package/@acarmisc/backstage-plugin-litellm-backend),
+which talks to LiteLLM and enforces every rule.
 
-Pair this package with the backend, [`@acarmisc/backstage-plugin-litellm-backend`](https://www.npmjs.com/package/@acarmisc/backstage-plugin-litellm-backend), which proxies requests to your LiteLLM instance and resolves Backstage identity.
-
-Full setup docs, configuration reference, and architecture notes live in the [project README](https://github.com/acarmisc/backstage-plugin-litellm-govai#readme).
-
-## Screenshots
-
-| View | Preview |
-|------|---------|
-| Home widget — `LiteLLMHomeWidget` | ![Home widget](../../docs/screenshots/home-widget.png) |
-| Overview / Usage Analytics | ![Usage analytics](../../docs/screenshots/usage-analytics.png) |
-| Keys tab — virtual key inventory | ![Keys tab](../../docs/screenshots/keys-tab.png) |
-| Generate New Key dialog | ![Generate New Key dialog](../../docs/screenshots/generate-key-dialog.png) |
-| Models tab | ![Models tab](../../docs/screenshots/models-tab.png) |
-| Compact "Create Key" card | ![Create Key card](../../docs/screenshots/key-card.png) |
+Full documentation — adoption guide, configuration, permissions, security model
+and architecture — starts at the
+[project README](https://github.com/acarmisc/backstage-plugin-litellm-govai#readme).
 
 ## Installation
 
-This plugin is designed to be used **within a Backstage monorepo**.
-
 ```bash
-yarn add --cwd packages/app @acarmisc/backstage-plugin-litellm
+yarn --cwd packages/app add @acarmisc/backstage-plugin-litellm
 ```
 
-You'll also need the backend package installed and configured — see its [README](https://www.npmjs.com/package/@acarmisc/backstage-plugin-litellm-backend) for `app-config.yaml` setup.
-
-## Usage
-
-### Full page
-
-The `LiteLLMPage` component renders the four-tab governance view: **Overview** (usage KPIs + charts), **Keys** (virtual key inventory), **Teams** (team-scoped usage), and **Models** (proxy model catalog).
+If your app discovers features from its dependencies (`app.packages: all`),
+the plugin is picked up automatically. Otherwise register it:
 
 ```tsx
-import { litellmPlugin, LiteLLMPage } from '@acarmisc/backstage-plugin-litellm';
-
 // packages/app/src/App.tsx
-<Route path="/litellm" element={<LiteLLMPage />} />
-```
-
-![Usage Analytics full page](../../docs/screenshots/usage-analytics-overview.png)
+import { createApp } from '@backstage/frontend-defaults';
+import litellmPlugin from '@acarmisc/backstage-plugin-litellm';
 
-### Home page widget
-
-`LiteLLMHomeWidget` is a compact card for the Backstage homepage. It shows the signed-in user's own usage — identity is resolved server-side from the Backstage token, so no `userId` prop is required. The header includes a `Today` / `7d` / `30d` period selector and a daily-spend sparkline.
-
-```tsx
-import { LiteLLMHomeWidget } from '@acarmisc/backstage-plugin-litellm';
-
-<LiteLLMHomeWidget defaultPeriod="7d" />
+const app = createApp({
+  features: [litellmPlugin],
+});
 ```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `defaultPeriod` | `'today' \| '7d' \| '30d'` | `'7d'` | Period shown on first render |
-| `title` | `string` | `'LiteLLM Usage'` | Card title override |
+This adds the `/litellm` page and the `liteLlmApiRef` API used by every
+component below.
 
-A slimmer **Create Key** card variant is available for surfaces that only need a one-click shortcut into the key-mint flow:
+## The `/litellm` page
 
-![Create Key card](../../docs/screenshots/key-card.png)
+Tabs: **Overview** (usage KPIs and charts), **Keys** (your virtual keys: edit,
+block / unblock, reset spend, delete), **Teams** (team usage, and team
+management for admins), **Models** (the proxy's model catalogue) and **Audit
+Log** (members of `litellm.audit.group` only). `?tab=<name>` opens a tab and
+`?generate=1` opens the Generate New Key dialog.
 
-### Keys tab
+![The /litellm page](https://raw.githubusercontent.com/acarmisc/backstage-plugin-litellm-govai/main/docs/images/overview.png)
 
-The **Keys** tab lists every virtual key you own with its alias, key ID, creation and expiry dates, budget bar (`$spent / $limit`), TPM/RPM, and model scope. Each row exposes inline actions: edit, block/unblock, reset spend, and delete.
+## Homepage components
 
-![Keys tab](../../docs/screenshots/keys-tab.png)
+| Component | What it shows |
+|---|---|
+| `LiteLLMHomeWidget` | Spend and tokens for `Today` / `7d` / `30d` with a daily sparkline |
+| `LiteLLMBudgetWidget` | The budget hierarchy (key → personal → team → global) with a meter per limit |
+| `LiteLLMBudgetGauges` | A condensed budget card: one ring per level and a month-to-date chart |
+| `GenerateKeyButton` | The shared "Generate New Key" button (`onClick`, or `to="/litellm?generate=1"`) |
 
-### Generate New Key dialog
-
-The dialog walks the user through aliasing the key, picking a duration, binding a team, restricting model access, setting a max budget, and configuring per-key TPM/RPM caps. Failures (e.g. duplicate alias) surface inline with the upstream error code preserved.
-
-![Generate New Key dialog](../../docs/screenshots/generate-key-dialog.png)
+```tsx
+import {
+  LiteLLMHomeWidget,
+  LiteLLMBudgetGauges,
+} from '@acarmisc/backstage-plugin-litellm';
 
-### Models tab
+<LiteLLMHomeWidget defaultPeriod="7d" />
+<LiteLLMBudgetGauges />
+```
 
-The **Models** tab lists every model the LiteLLM proxy exposes, with per-model input/output cost, max input/output token limits, and capabilities. The team selector scopes the list to the models the bound team is allowed to call.
+Props for each component are documented in
+[docs/frontend.md](https://github.com/acarmisc/backstage-plugin-litellm-govai/blob/main/docs/frontend.md).
 
-![Models tab](../../docs/screenshots/models-tab.png)
+![LiteLLMBudgetGauges](https://raw.githubusercontent.com/acarmisc/backstage-plugin-litellm-govai/main/docs/images/budget-gauges.png)
 
-## Exports
+To try it without a backend, run `npm start` in this package: it serves the
+plugin with mock data at `http://localhost:3000/litellm` (see
+[CONTRIBUTING.md](https://github.com/acarmisc/backstage-plugin-litellm-govai/blob/main/CONTRIBUTING.md#run-the-frontend-with-mock-data)).
 
-- `litellmPlugin` — the frontend plugin instance
-- `LiteLLMPage` — main plugin page (keys, usage, team context)
-- `LiteLLMHomeWidget` — homepage usage summary card
-- `KeyFormDialog` — shared key form for both generating and editing a key (surfaces failures inline, warns on duplicate aliases, team-scoped model picker, unlimited-budget toggle when gated on)
-- `GenerateKeyDialog` — deprecated wrapper around `KeyFormDialog` with `mode="create"`
-- `DashboardHeader`, `KeysTable`, `UsageStats`, `TeamUsage` — individual page sections, exported for composition
-- `LiteLlmApi`, `liteLlmApiRef` — API client and its Backstage API ref
+## Other exports
 
-Note: `DashboardHeader` and `KeysTable` are composition pieces driven by `LiteLLMPage` and their props differ from older versions. `LiteLLMPage` is the supported entry point; composing the sections directly means keeping them in sync with the page's data wiring (keys, models, teams, and the `onGenerateKeyClick`/`onEditKey` callbacks).
+- `litellmPlugin` (also the default export)
+- `LiteLLMPage`, and the building blocks it uses: `DashboardHeader`,
+  `KeysTable`, `UsageStats`, `TeamUsage`, `KeyFormDialog`, `ManageTeamDialog`.
+  Prefer `LiteLLMPage`; composing the pieces yourself means wiring their data
+  and callbacks the way the page does.
+- `LiteLlmApi`, `liteLlmApiRef`, the shared API types, and the
+  `litellmTeam*Permission` definitions.
 
 ## License
 

package/dist/components/KeyFormDialog.d.ts

@@ -26,5 +26,3 @@ export interface KeyFormDialogProps {
     onGetConfig: () => Promise<LiteLlmConfig>;
 }
 export declare const KeyFormDialog: FC<KeyFormDialogProps>;
-export declare function fmtCost(perToken?: number): string | null;
-export declare function formatContextWindow(maxInput?: number, maxOutput?: number): string | null;

package/dist/components/LiteLLMBudgetGauges.d.ts

@@ -82,5 +82,4 @@ export interface LiteLLMBudgetGaugesProps {
     teams?: TeamInfo[];
     keys?: VirtualKey[];
 }
-export { monthToDateRange } from '../dates';
 export declare const LiteLLMBudgetGauges: FC<LiteLLMBudgetGaugesProps>;

package/dist/components/keyFormHelpers.d.ts

@@ -1,5 +1,4 @@
 import { VirtualKey, ModelInfo, GenerateKeyRequest, UpdateKeyRequest } from '../types';
-export declare const generateDefaultAlias: (username?: string) => string;
 export declare const createForm: (username?: string) => GenerateKeyRequest;
 export declare const editForm: (k: VirtualKey) => UpdateKeyRequest;
 export declare function isModelAllowedByTeam(model: ModelInfo, teamModels?: string[]): boolean;

package/dist/hooks/useCopyToClipboard.d.ts

@@ -2,11 +2,6 @@
  * Pure helper: determine if the Clipboard API is available.
  */
 export declare function isClipboardApiAvailable(): boolean;
-/**
- * Pure helper: fallback copy via textarea and document.execCommand.
- * Returns true if successful, false otherwise.
- */
-export declare function fallbackCopyToClipboard(text: string): boolean;
 /**
  * Pure helper: create a timer for the copied state.
  * Returns the timer ID so the caller can manage cleanup.

package/dist/index.cjs.js

@@ -1843,8 +1843,6 @@ var init_KeysTable = __esm({
         setPruneSubmitting(true);
         try {
           await onPruneExpiredKeys();
-        } catch (error) {
-          console.error("Failed to prune expired keys:", error);
         } finally {
           setPruneSubmitting(false);
           setPruneConfirmCount(null);
@@ -1913,7 +1911,8 @@ var init_KeysTable = __esm({
                         bgcolor: (0, import_styles7.alpha)(theme.palette.text.primary, theme.palette.mode === "dark" ? 0.08 : 0.05),
                         px: 0.75,
                         py: 0.375,
-                        borderRadius: "5px"
+                        borderRadius: "5px",
+                        whiteSpace: "nowrap"
                       }),
                       children: shortKeyId(keyId)
                     }
@@ -5897,15 +5896,6 @@ var init_dates = __esm({
   }
 });
 
-// src/permissions.ts
-var import_backstage_plugin_litellm_common5;
-var init_permissions = __esm({
-  "src/permissions.ts"() {
-    "use strict";
-    import_backstage_plugin_litellm_common5 = require("@acarmisc/backstage-plugin-litellm-common");
-  }
-});
-
 // src/feedback.ts
 function toastFor(kind, errorMsg) {
   switch (kind) {
@@ -6014,7 +6004,7 @@ function initDateRange() {
   else start.setDate(start.getDate() - 7);
   return { start, end };
 }
-var import_react13, import_Box17, import_Alert6, import_Button7, import_Typography15, import_Tabs2, import_Tab2, import_Grid2, import_Accordion2, import_AccordionSummary2, import_AccordionDetails2, import_ExpandMore, import_react_router_dom, import_react_use2, import_core_plugin_api5, import_core_components3, import_plugin_permission_react3, import_jsx_runtime18, PERIOD_LS_KEY2, PAGE_TABS, isPageTab, LiteLLMPage;
+var import_react13, import_Box17, import_Alert6, import_Button7, import_Typography15, import_Tabs2, import_Tab2, import_Grid2, import_Accordion2, import_AccordionSummary2, import_AccordionDetails2, import_ExpandMore, import_react_router_dom, import_react_use2, import_core_plugin_api5, import_core_components3, import_plugin_permission_react3, import_backstage_plugin_litellm_common5, import_jsx_runtime18, PERIOD_LS_KEY2, PAGE_TABS, isPageTab, LiteLLMPage;
 var init_LiteLLMPage = __esm({
   "src/components/LiteLLMPage.tsx"() {
     "use strict";
@@ -6046,7 +6036,7 @@ var init_LiteLLMPage = __esm({
     init_AuditLog();
     init_api();
     init_dates();
-    init_permissions();
+    import_backstage_plugin_litellm_common5 = require("@acarmisc/backstage-plugin-litellm-common");
     init_feedback();
     init_teamMemberManager();
     init_unprovisionedCopy();
@@ -6672,7 +6662,6 @@ var index_exports = {};
 __export(index_exports, {
   DashboardHeader: () => DashboardHeader,
   GenerateKeyButton: () => GenerateKeyButton,
-  GenerateKeyDialog: () => GenerateKeyDialog,
   KeyFormDialog: () => KeyFormDialog,
   KeysTable: () => KeysTable,
   LiteLLMBudgetGauges: () => LiteLLMBudgetGauges,
@@ -6683,13 +6672,14 @@ __export(index_exports, {
   ManageTeamDialog: () => ManageTeamDialog,
   TeamUsage: () => TeamUsage,
   UsageStats: () => UsageStats,
+  default: () => litellmPlugin,
   liteLlmApiRef: () => liteLlmApiRef,
   litellmPlugin: () => litellmPlugin,
-  litellmTeamCreatePermission: () => import_backstage_plugin_litellm_common5.litellmTeamCreatePermission,
-  litellmTeamKnowledgebaseManagePermission: () => import_backstage_plugin_litellm_common5.litellmTeamKnowledgebaseManagePermission,
-  litellmTeamManagePermission: () => import_backstage_plugin_litellm_common5.litellmTeamManagePermission,
-  litellmTeamMcpManagePermission: () => import_backstage_plugin_litellm_common5.litellmTeamMcpManagePermission,
-  litellmTeamMembersManagePermission: () => import_backstage_plugin_litellm_common5.litellmTeamMembersManagePermission
+  litellmTeamCreatePermission: () => import_backstage_plugin_litellm_common6.litellmTeamCreatePermission,
+  litellmTeamKnowledgebaseManagePermission: () => import_backstage_plugin_litellm_common6.litellmTeamKnowledgebaseManagePermission,
+  litellmTeamManagePermission: () => import_backstage_plugin_litellm_common6.litellmTeamManagePermission,
+  litellmTeamMcpManagePermission: () => import_backstage_plugin_litellm_common6.litellmTeamMcpManagePermission,
+  litellmTeamMembersManagePermission: () => import_backstage_plugin_litellm_common6.litellmTeamMembersManagePermission
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -7620,30 +7610,7 @@ var LiteLLMBudgetGauges = ({
 // src/index.ts
 init_KeyFormDialog();
 init_GenerateKeyButton();
-
-// src/components/GenerateKeyDialog.tsx
-init_KeyFormDialog();
-var import_jsx_runtime22 = require("react/jsx-runtime");
-var GenerateKeyDialog = (props) => /* @__PURE__ */ (0, import_jsx_runtime22.jsx)(
-  KeyFormDialog,
-  {
-    open: props.open,
-    onClose: props.onClose,
-    mode: "create",
-    keys: props.keys,
-    models: props.models,
-    teams: props.teams,
-    username: props.username,
-    keyGenerationSettings: props.keyGenerationSettings,
-    onCreateKey: props.onGenerateKey,
-    onUpdateKey: async () => {
-    },
-    onGetConfig: props.onGetConfig
-  }
-);
-
-// src/index.ts
 init_ManageTeamDialog();
 init_api();
-init_permissions();
+var import_backstage_plugin_litellm_common6 = require("@acarmisc/backstage-plugin-litellm-common");
 //# sourceMappingURL=index.cjs.js.map