owi-litellm-tool/README.md

LiteLLM Dashboard — Open WebUI Tool

A simple, three-function Open WebUI Tool for checking LiteLLM proxy health, cost breakdowns, and recent request history.

Functions

litellm_health

Check LiteLLM proxy health and authentication status. Returns which models are healthy/unhealthy, their rate limits, and any auth errors.

litellm_cost

Get LiteLLM cost breakdown for a date range. Returns per-model and per-day spend, token counts, cache hit rate, and request stats.

Parameters:

• start_date (str, required): Start date — YYYY-MM-DD or natural language shortcut (e.g. "2026-06-01", "today", "yesterday", "monday", "last monday", "two days ago", "this week", "last month")
• end_date (str, required): End date — YYYY-MM-DD or natural language shortcut
• hide_zero_spend (bool, default false): When True, force-hide models with sub-$0.001 spend. When False, use the valve-configured default (see default_hide_zero_spend below). This two-level design lets the human set a default via valves while allowing the SLM to explicitly override on a per-call basis.

litellm_history

Get recent LiteLLM request history. Returns the most recent N requests with model, call type, status, duration, token counts, cache hit %, and per-request cost. Useful for understanding which models are being called and how much individual requests cost.

Parameters:

• limit (int, 1-50, default 20): Number of recent requests to show
• show_cost (bool, default true): Include per-request cost
• show_failed (bool, default true): Include failed requests. Set false to hide auth failures, routing errors, and probe noise.

Cost awareness: This function hits /spend/logs which returns all historical logs. For large deployments, this can be a heavy query. Use reasonable limit values.

Valves (Configuration)

Valve	Default	Purpose
litellm_url	http://localhost:4000	LiteLLM proxy base URL
litellm_master_key	(empty)	LiteLLM master API key (password field)
default_hide_zero_spend	True	Default behavior for zero-spend model filtering. When True, models with sub-$0.001 spend are hidden by default. The per-call hide_zero_spend parameter can override this.

Both valves are passed at runtime — no hardcoded keys. The tool is portable to any LiteLLM proxy instance.

Installation

1. Copy/import litellm_dashboard.py to your Open WebUI Workspace
2. Configure the two valves with your LiteLLM proxy URL and master key
3. Enable the tool in the chat's tools menu (per-chat) or enable it for the model in model settings (always-on with that model)

Requirements

• requests (standard pip package)
• Open WebUI 0.4.0+
• A running LiteLLM proxy instance

Design Principles

• Three functions, that's it. No scope creep.
• Portable. No hardcoded URLs or keys.
• Token-efficient. Strips litellm_metadata (~2KB/model) from health responses. Formats cost data as readable text, not raw JSON dumps.
• General-purpose. Works with any LiteLLM proxy instance.
• Read-only. GET endpoints only. No mutations, no risk.

Documentation

• ARCHITECTURE.md — Full architecture and design doc: API endpoints, response processing, stripped fields, error paths, future considerations, changelog.
• This README — Quick reference: install, functions, valves, design principles.

Changelog

v1.3.2 (2026-06-26)

• feat: Hardcore FinOps Audit Engine (TASK-004) — added _audit_cost helper and static MODEL_PRICING registry to verify reported spend against actual provider caching rates.
• feat: Real-time request cost auditing in litellm_history output.
• fix: Robust cache-extraction logic supporting nested metadata structures for Gemini/z.ai models.

v1.2.0 (2026-06-13)

• feat: Natural language date shortcuts for litellm_cost() — today, yesterday, monday, last week, etc.
• feat: hide_zero_spend parameter for litellm_cost() — default True hides sub-$0.001 models with summary line; per-call parameter can override
• fix: Cost report header shows resolved YYYY-MM-DD dates instead of raw shortcuts

v1.1.0 (2026-06-13)

• Initial public release
• Three functions: litellm_health, litellm_cost, litellm_history
• Valve-based configuration (no hardcoded keys)
• Token-efficient response formatting

License

MIT