@acarmisc/backstage-plugin-litellm 0.32.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/ManageTeamDialog.d.ts

@@ -1,5 +1,10 @@
 import { FC } from 'react';
 import { TeamInfo, ModelInfo, LiteLlmConfig, CreateTeamRequest, UpdateTeamRequest, VectorStoreInfo, McpServerInfo } from '../types';
+/** A catalog User entity flattened into what the member picker needs. */
+export interface InitialMember {
+    userEntityRef: string;
+    maxBudgetInTeam?: number;
+}
 interface ManageTeamDialogProps {
     open: boolean;
     onClose: () => void;
@@ -7,7 +12,11 @@ interface ManageTeamDialogProps {
     team?: TeamInfo;
     allModels: ModelInfo[];
     config?: LiteLlmConfig;
-    onSubmit: (payload: CreateTeamRequest | UpdateTeamRequest) => Promise<void>;
+    /**
+     * Saves the team. In create mode, `initialMembers` lists the members picked
+     * in the dialog; the parent adds them once the team exists.
+     */
+    onSubmit: (payload: CreateTeamRequest | UpdateTeamRequest, initialMembers?: InitialMember[]) => Promise<void>;
     /** When true, the Members section (edit mode only) exposes add/remove controls. */
     canManageMembers?: boolean;
     /** Called to add a member; the parent is expected to refresh `team` on success. */

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.