litellm-pulse 0.2.0__tar.gz

litellm_pulse-0.2.0/.dockerignore

@@ -0,0 +1,7 @@
+.git
+.gitignore
+__pycache__
+*.pyc
+.venv
+.ruff_cache
+*.egg-info

litellm_pulse-0.2.0/.github/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.2.0"}

litellm_pulse-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[BUG] "
+labels: ["bug"]
+---
+
+## Description
+
+<!-- A clear description of the bug. -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What you expected to happen. -->
+
+## Actual Behavior
+
+<!-- What actually happened. -->
+
+## Environment
+
+- LiteLLM Pulse version:
+- Deployment (Docker / uv run):
+- Python version:
+- Relevant config (`LITELLM_PULSE_*` env vars):
+
+## Logs
+
+<!-- Relevant log output. Set LITELLM_PULSE_LOG_LEVEL=debug if needed. -->

litellm_pulse-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussions
+    url: https://github.com/jakepenzak/litellm-pulse/discussions
+    about: Ask questions and share ideas in Discussions.

litellm_pulse-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: "[FEATURE] "
+labels: ["enhancement"]
+---
+
+## Problem
+
+<!-- What problem does this feature solve? -->
+
+## Proposed Solution
+
+<!-- What you'd like to see happen. -->
+
+## Alternatives Considered
+
+<!-- Any alternative solutions you've thought about. -->
+
+## Additional Context
+
+<!-- Anything else relevant (screenshots, links, etc.). -->

litellm_pulse-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- Brief description of the changes -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+- [ ] Refactor / cleanup
+
+## Checklist
+
+- [ ] `pre-commit run --all-files` passes
+- [ ] `uv run pytest` passes (or no tests changed)
+- [ ] Documentation updated if needed
+- [ ] Changes are backwards-compatible (or noted below)
+
+## Additional Notes
+
+<!-- Anything else reviewers should know -->

litellm_pulse-0.2.0/.github/pr-labeler.yml

@@ -0,0 +1,16 @@
+clear-prexisting: false # Whether to remove preexisting labels from the PR in favor of the generated one
+include-title: true # Consider the PR title when adding labels
+label-for-breaking-changes: "type: breaking" # Label to be used when the message has the breaking change syntax '!:' E.g. "feat!: This break things"
+label-mapping: # Label to array of types for mapping
+  "type: build": ["build"]
+  "type: ci": ["ci"]
+  "type: docs": ["docs"]
+  "type: feat": ["feat"]
+  "type: fix": ["fix"]
+  "type: perf": ["perf"]
+  "type: refactor": ["refactor"]
+  "type: style": ["style"]
+  "type: test": ["test"]
+  "type: revert": ["revert"]
+  "type: chore": ["chore"]
+  "type: release": ["release"]

litellm_pulse-0.2.0/.github/release-please-config.json

@@ -0,0 +1,20 @@
+{
+  "release-type": "python",
+  "package-name": "litellm-pulse",
+  "include-component-in-tag": false,
+  "changelog-sections": [
+    { "type": "feat", "section": "✨ Features", "hidden": false },
+    { "type": "fix", "section": "🐛 Bug Fixes", "hidden": false },
+    { "type": "perf", "section": "⚡ Performance", "hidden": false },
+    { "type": "refactor", "section": "♻️ Refactoring", "hidden": false },
+    { "type": "docs", "section": "📚 Documentation", "hidden": false },
+    { "type": "test", "section": "🧪 Tests", "hidden": false },
+    { "type": "ci", "section": "🔧 CI/CD", "hidden": false },
+    { "type": "build", "section": "📦 Build System", "hidden": false },
+    { "type": "style", "section": "🎨 Code Style", "hidden": false },
+    { "type": "chore", "section": "🔨 Miscellaneous", "hidden": false }
+  ],
+  "packages": {
+    ".": {}
+  }
+}

litellm_pulse-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+    push:
+        branches: [main]
+    pull_request:
+        branches: [main]
+
+permissions:
+    contents: read
+
+jobs:
+    lint:
+        name: Lint & Format
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.12"
+
+            - name: Install pre-commit
+              run: pip install pre-commit
+
+            - name: Run pre-commit
+              run: pre-commit run --all-files
+
+    test:
+        name: Test
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ["3.11", "3.12", "3.13", "3.14"]
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Install uv
+              uses: astral-sh/setup-uv@v6
+              with:
+                  version: "latest"
+
+            - name: Set up Python ${{ matrix.python-version }}
+              run: uv python install ${{ matrix.python-version }}
+
+            - name: Install dependencies
+              run: uv sync --dev
+
+            - name: Run tests
+              run: uv run pytest -v

litellm_pulse-0.2.0/.github/workflows/pr-validator.yml

@@ -0,0 +1,69 @@
+name: Conventional Commit PR Validator
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened]
+
+jobs:
+  check-PR-title:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    env:
+      PR_TITLE_RAW: ${{ github.event.pull_request.title }}
+    steps:
+      - name: Get PR Title
+        id: pr_title
+        shell: bash
+        run: |
+          {
+            echo 'PR_TITLE<<EOF'
+            echo "$PR_TITLE_RAW"
+            echo 'EOF'
+          } >> "$GITHUB_ENV"
+
+      - name: Validate PR Title
+        id: validate_pr_title
+        run: |
+          if [[ ! "$PR_TITLE" =~ ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test|release)(\(.+\))?!?:\ .+ ]]; then
+            echo "INVALID_TITLE=true" >> $GITHUB_ENV
+            echo "PR title does not follow the required format: `<type>[optional scope]: description`"
+          else
+            echo "INVALID_TITLE=false" >> $GITHUB_ENV
+            echo "PR title is valid."
+          fi
+        shell: bash
+
+      - name: Comment on PR if invalid
+        if: ${{ env.INVALID_TITLE == 'true' }}
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            :stop_sign: **ACTION NEEDED - PR Title** :stop_sign:
+
+            `litellm-pulse` follows [Conventional Commit format](https://www.conventionalcommits.org/en/v1.0.0/) for PR titles.
+
+            Please update your PR title to match the specification.
+
+            Test out your PR title [here](https://regex101.com/?regex=%5E%28build%7Cchore%7Cci%7Cdocs%7Cfeat%7Cfix%7Cperf%7Crefactor%7Crevert%7Cstyle%7Ctest%7Crelease%29%28%5C%28.%2B%5C%29%29%3F%21%3F%3A%5C+.%2B&testString=fix%28atest._-%29%21%3A+This.-+_+is+a+..+test%0A&flags=s&flavor=java&delimiter=%22).
+
+            For the list of acceptable prefixes & examples, see [README.md](https://github.com/jakepenzak/litellm-pulse/blob/main/README.md).
+
+            The current PR title is: `${{ env.PR_TITLE }}`
+
+      - name: Fail if invalid
+        if: ${{ env.INVALID_TITLE == 'true' }}
+        run: exit 1
+
+  label-PR:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: grafana/pr-labeler-action@50737759cb150f5d312de1a45559027156db8bab
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/pr-labeler.yml

litellm_pulse-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  packages: write
+
+jobs:
+  release-please:
+    name: Create Release
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release-please.outputs.releases_created }}
+      tag_name: ${{ steps.release-please.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release-please
+        with:
+          config-file: .github/release-please-config.json
+          manifest-file: .github/.release-please-manifest.json
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  build-and-publish:
+    name: Build & Publish to GHCR
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+
+      - name: Extract version
+        id: version
+        run: |
+          TAG="${{ needs.release-please.outputs.tag_name }}"
+          VERSION="${TAG#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "major_minor=$(cut -d. -f1,2 <<<"$VERSION")" >> "$GITHUB_OUTPUT"
+          echo "major=$(cut -d. -f1 <<<"$VERSION")" >> "$GITHUB_OUTPUT"
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=${{ steps.version.outputs.version }}
+            type=raw,value=${{ steps.version.outputs.major_minor }}
+            type=raw,value=${{ steps.version.outputs.major }}
+            type=raw,value=latest
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}
+          skip-existing: true

litellm_pulse-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.ruff_cache/
+dist/
+build/
+data/
+*.db
+*.db-wal
+*.db-shm
+
+# Test reports
+.coverage
+tests/reports/

litellm_pulse-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v4.6.0
+      hooks:
+          - id: trailing-whitespace
+          - id: end-of-file-fixer
+          - id: detect-private-key
+          - id: check-yaml
+          - id: check-json
+          - id: check-toml
+          - id: check-xml
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.15.8
+      hooks:
+          - id: ruff-check
+            types_or: [python, pyi, jupyter]
+            args: [--fix]
+
+          - id: ruff-format
+            types_or: [python, pyi, jupyter]
+
+exclude: ^assets/

litellm_pulse-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

litellm_pulse-0.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.2.0](https://github.com/jakepenzak/litellm-pulse/compare/v0.1.0...v0.2.0) (2026-06-24)
+
+
+### ✨ Features
+
+* add support for configurable timezones ([#9](https://github.com/jakepenzak/litellm-pulse/issues/9)) ([fd3d0fe](https://github.com/jakepenzak/litellm-pulse/commit/fd3d0fea2b63825b40d426a6f4e03ab6d78a2743))
+* authentication support for scraping LiteLLM `/metrics` endpoint ([#7](https://github.com/jakepenzak/litellm-pulse/issues/7)) ([0ea7d13](https://github.com/jakepenzak/litellm-pulse/commit/0ea7d13aa69248b9dcf46e7692e03fc143ff5fc8))
+
+
+### 🔧 CI/CD
+
+* add pr labeler and pypi release ([#12](https://github.com/jakepenzak/litellm-pulse/issues/12)) ([c9afc16](https://github.com/jakepenzak/litellm-pulse/commit/c9afc16c48853b859e6e0407d795d6835b104070))
+
+## 0.1.0 (2026-06-21)
+
+Initial release of `litellm-pulse`, a lightweight service that scrapes LiteLLM Prometheus metrics and exposes them as JSON for Homepage widgets and Home Assistant sensors. Features a FastAPI application with a Prometheus text format parser, SQLite time-series storage with daily/weekly/monthly aggregates and counter reset detection, and REST endpoints for cost and token metrics. Includes 49 pytest tests, pre-commit linting with ruff, and CI/CD pipelines with automated releases via release-please and Docker image publishing to GHCR.
+
+### ✨ Features
+
+* initial `litellm-pulse` metrics exporter ([00f72f2](https://github.com/jakepenzak/litellm-pulse/commit/00f72f299801e5daaaa0c7362795a9d4980b5e8f))
+* SQLite time-series storage with daily/weekly/monthly aggregates ([c24ce5f](https://github.com/jakepenzak/litellm-pulse/commit/c24ce5f453f12a170bfe8f3cb86a7ba5c30af2d9))
+
+### 🔧 CI/CD
+
+* add CI/CD, release-please, tests, and project infrastructure ([4b184d3](https://github.com/jakepenzak/litellm-pulse/commit/4b184d3b99635cc1ce49a00a89405ef5b956409d))

litellm_pulse-0.2.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY litellm_pulse/ litellm_pulse/
+
+RUN uv sync --no-dev
+
+RUN mkdir -p /app/data
+
+VOLUME /app/data
+
+EXPOSE 8000
+
+CMD ["uv", "run", "litellm-pulse"]

litellm_pulse-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Pieniazek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

litellm_pulse-0.2.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: help venv tests coverage run
+
+help:
+	@printf "Usage: make <target> \n\n"
+	@printf "Targets:\n"
+	@printf "   venv            Create/sync virtual environment and install hooks.\n"
+	@printf "   tests           Run tests with pytest.\n"
+	@printf "   coverage        Serve coverage report at http://localhost:8080.\n"
+	@printf "   run             Run the server locally.\n"
+	@printf "   help            Show this help message.\n"
+
+venv:
+	@echo "Syncing venv based on lock file..."
+	@uv sync --all-extras --all-groups --frozen
+	@uv run pre-commit install
+
+tests:
+	@echo "Running tests with pytest..."
+	@uv run pytest tests/
+
+run:
+	@echo "Starting LiteLLM Pulse..."
+	@uv run litellm-pulse
+
+coverage:
+	@echo "Serving coverage report at http://localhost:8080 ..."
+	@uv run python -m http.server 8080 -d tests/reports/htmlcov