First off, thank you for considering contributing to the litellm-debug skill! It's community members like you that keep diagnostic tools accurate as upstream projects evolve.
This project follows the Agent Skills open format for giving agents new capabilities. We are building a read-side, investigative tool for LiteLLM deployments.
Before contributing, please read our foundational documents:
dev/intent.md— What this skill is and isn't.dev/roadmap.md— Our phased approach and acceptance criteria.dev/decisions.md— Our architectural decisions.dev/practices.md— How we build day-to-day (tooling, TUI, etc).
We strictly follow a Tier Model (Public, User, Admin, Telemetry, Database). Our goal is always to use the lowest fidelity tier that can answer the user's question, and we rely on Spec Anchoring to ensure our tests are based on reality, not guesswork.
A great way to get started and understand how this project works is to validate the completeness of our Public tier tests. LiteLLM frequently adds new configuration and UI endpoints, and it's our job to ensure our smoke tests cover the full public attack surface.
Here is the exact loop you can run to contribute:
Clone the repo and install dependencies:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .envAdd your proxy URL to .env: LITELLM_BASE_URL=https://your-proxy.com
We never guess endpoint paths. We derive them from upstream. Run the spec pin tool to download the openapi.json for your LiteLLM version:
python scripts/litellm/spec_pin.pyRun our developer discovery tool. This parses the downloaded OpenAPI spec for any endpoint that does not require security, and then dynamically pings your live proxy to see which ones return 200 OK:
python scripts/dev/find_public_endpoints.pyLook at the output of the script. Are there endpoints returning 200 OK that are not currently listed in our tests?
Check tests/litellm/public/test_public.py and scripts/litellm/diagnose_public.py.
If you find a new public endpoint (e.g., a new .well-known config or public /ui/ path):
- Add it to
test_public_config_endpointsintests/litellm/public/test_public.py. - Add it to the
ENDPOINTSdictionary inscripts/litellm/diagnose_public.py. - Create a Pull Request!
When filing an issue, make sure to answer these questions:
- What version of LiteLLM is your proxy running? (You can check
/health/readiness) - What tier were you trying to debug (Public, User, Admin)?
- What did you expect the skill to do?
- What happened instead?
If you find a security vulnerability in how we handle credentials or traces, please do NOT open a public issue. Email the maintainers directly.
- Ensure your tests pass (
pytest tests/litellm/public -v). - Ensure missing credentials cause a test to
skipgracefully, notfail. - We review PRs weekly. After feedback, we expect a response within a week or two, or we may close the PR to keep the queue clean.