llmentary 0.2.0__tar.gz

llmentary-0.2.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @barzoj

llmentary-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,121 @@
+name: Bug report
+description: Report a bug in the Python client or pytest plugin
+title: "[Bug]: "
+labels: [bug, needs-triage]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for a report. Remove API keys, tokens, and private prompts before
+        you submit. Security issues go to
+        https://github.com/barzoj-co/llmentary-python/security/advisories/new
+        — not here. Proxy bugs go to https://github.com/barzoj-co/llmentary.
+  - type: input
+    id: package-version
+    attributes:
+      label: Package version
+      description: The installed `llmentary` version (`python -c "import llmentary; print(llmentary.__version__)"`).
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: proxy-version
+    attributes:
+      label: Bundled proxy version
+      description: The `VERSION` file next to the wheel binary, or the `LLMENTARY_BIN` path if you did not use a bundled binary.
+      placeholder: "0.1.0 or /path/to/llmentary"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: "`python --version`"
+      placeholder: "3.13.2"
+    validations:
+      required: true
+  - type: input
+    id: pytest-version
+    attributes:
+      label: pytest version
+      description: "`pytest --version` (leave blank if you are not using the plugin)"
+      placeholder: "8.4.2"
+    validations:
+      required: false
+  - type: input
+    id: os-arch
+    attributes:
+      label: OS and architecture
+      placeholder: "Ubuntu 24.04 x86_64"
+    validations:
+      required: true
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Install method
+      options:
+        - Platform wheel
+        - sdist
+        - Editable (`pip install -e`)
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: provider
+    attributes:
+      label: Provider
+      description: Upstream LLM provider the proxy talked to.
+      placeholder: OpenAI
+    validations:
+      required: true
+  - type: dropdown
+    id: api
+    attributes:
+      label: API
+      options:
+        - Chat Completions
+        - Responses
+        - Both
+        - Neither / not applicable
+    validations:
+      required: true
+  - type: dropdown
+    id: streaming
+    attributes:
+      label: Streaming
+      options:
+        - "Yes"
+        - "No"
+        - Both
+        - Not applicable
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest snippet or test that shows the bug. Strip keys and private prompts.
+      placeholder: |
+        def test_example(llmentary):
+            ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual
+    validations:
+      required: true
+  - type: checkboxes
+    id: no-secrets
+    attributes:
+      label: Secrets
+      options:
+        - label: I removed keys and private prompts
+          required: true

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

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/barzoj-co/llmentary-python/security/advisories/new
+    about: Never file a public issue for a security report. Use GitHub private reporting.
+  - name: Proxy bugs
+    url: https://github.com/barzoj-co/llmentary/issues
+    about: Bugs in the recording proxy binary belong in barzoj-co/llmentary.
+  - name: Questions and ideas
+    url: https://github.com/barzoj-co/llmentary/discussions
+    about: Ask questions and discuss ideas with the llmentary community.

llmentary-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Propose a change to the Python client or pytest plugin
+title: "[Feature]: "
+labels: [enhancement, needs-triage]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the problem and the change you want. Proxy-side features belong
+        in https://github.com/barzoj-co/llmentary.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What is hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What should the client or plugin do?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: Other approaches you considered.
+    validations:
+      required: false

llmentary-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this change, and why? -->
+
+## Linked issue
+
+<!-- Fixes #nnn or N/A -->
+
+## Conventional type
+
+<!-- feat | fix | docs | ci | chore | refactor | test | perf | revert -->
+
+## Checklist
+
+- [ ] Tests cover the change (`pytest -m "not e2e"`; live e2e only when relevant)
+- [ ] `ruff check .` and `mypy` pass
+- [ ] Docs describe only implemented behavior
+- [ ] No secrets, API keys, or private prompts in the diff or logs
+- [ ] Breaking change is called out above (or this is not breaking)

llmentary-0.2.0/.github/labels.yml

@@ -0,0 +1,48 @@
+- name: bug
+  color: "d73a4a"
+  description: Something is broken
+- name: enhancement
+  color: "a2eeef"
+  description: New feature or request
+- name: documentation
+  color: "0075ca"
+  description: Documentation only
+- name: question
+  color: "d876e3"
+  description: Further information is requested
+- name: needs-triage
+  color: "e4e669"
+  description: Not yet reviewed
+- name: good first issue
+  color: "7057ff"
+  description: Good for newcomers
+- name: help wanted
+  color: "008672"
+  description: Extra attention is needed
+- name: breaking-change
+  color: "b60205"
+  description: Introduces a breaking change
+- name: security
+  color: "ee0701"
+  description: Security-related
+- name: dependencies
+  color: "0366d6"
+  description: Dependency updates
+- name: ci
+  color: "000000"
+  description: Continuous integration
+- name: "area: pytest-plugin"
+  color: "c5def5"
+  description: Pytest plugin
+- name: "area: assertions"
+  color: "c5def5"
+  description: Assertion helpers
+- name: "area: packaging"
+  color: "c5def5"
+  description: Packaging and wheels
+- name: "autorelease: pending"
+  color: "ededed"
+  description: release-please release PR
+- name: "autorelease: tagged"
+  color: "0e8a16"
+  description: release-please has tagged a release

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

@@ -0,0 +1,204 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    env:
+      LLMENTARY_BIN: /tmp/llmentary
+    steps:
+      - name: Checkout Python client
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+
+      - name: Fail clearly if llmentary repo token is missing
+        env:
+          HAS_REPO_TOKEN: ${{ secrets.LLMTESTLAB_REPO_TOKEN != '' }}
+        run: |
+          if [ "$HAS_REPO_TOKEN" != "true" ]; then
+            echo "::error title=Missing secret::Add secrets.LLMTESTLAB_REPO_TOKEN with read access to barzoj-co/llmentary."
+            exit 1
+          fi
+
+      - name: Checkout llmentary proxy
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          repository: barzoj-co/llmentary
+          token: ${{ secrets.LLMTESTLAB_REPO_TOKEN }}
+          path: llmentary-proxy
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+        with:
+          go-version: "1.26"
+          cache-dependency-path: llmentary-proxy/go.sum
+
+      - name: Build llmentary proxy
+        working-directory: llmentary-proxy
+        run: go build -o "$LLMENTARY_BIN" ./cmd/llmentary
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and dev tools
+        run: python -m pip install -e ".[dev]"
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy
+
+      - name: Unit and fake-upstream integration tests
+        if: matrix.python-version != '3.13'
+        run: pytest -m "not e2e"
+
+      - name: Unit and fake-upstream integration tests
+        if: matrix.python-version == '3.13'
+        run: pytest -m "not e2e" --cov --cov-report=xml:coverage.xml
+
+      - name: Upload coverage artifact
+        if: matrix.python-version == '3.13'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error
+
+  coverage:
+    name: coverage
+    needs: test
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+
+      - name: Download coverage artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: coverage-xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
+        with:
+          use_oidc: false
+          disable_search: true
+          files: ./coverage.xml
+          flags: unit
+          fail_ci_if_error: ${{ vars.CODECOV_REQUIRED == 'true' }}
+
+  openai-e2e:
+    name: OpenAI E2E
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    # Required reviewers on this environment gate OPENAI_API_KEY. Unit and
+    # fake-upstream jobs do not use it and run without approval.
+    environment: openai-e2e
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      LLMENTARY_BIN: /tmp/llmentary
+      LLMENTARY_E2E: "1"
+      LLMENTARY_UPSTREAM_BASE_URL: https://api.openai.com/v1
+      LLMENTARY_WAIT_TIMEOUT: "30"
+    steps:
+      - name: Checkout Python client
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+
+      - name: Fail clearly if required secrets are missing
+        env:
+          HAS_REPO_TOKEN: ${{ secrets.LLMTESTLAB_REPO_TOKEN != '' }}
+          HAS_OPENAI_KEY: ${{ secrets.OPENAI_API_KEY != '' }}
+        run: |
+          if [ "$HAS_REPO_TOKEN" != "true" ]; then
+            echo "::error title=Missing secret::Add secrets.LLMTESTLAB_REPO_TOKEN with read access to barzoj-co/llmentary."
+            exit 1
+          fi
+          if [ "$HAS_OPENAI_KEY" != "true" ]; then
+            echo "::error title=Missing secret::Add secrets.OPENAI_API_KEY for real OpenAI E2E tests."
+            exit 1
+          fi
+
+      - name: Checkout llmentary proxy
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          repository: barzoj-co/llmentary
+          token: ${{ secrets.LLMTESTLAB_REPO_TOKEN }}
+          path: llmentary-proxy
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+        with:
+          go-version: "1.26"
+          cache-dependency-path: llmentary-proxy/go.sum
+
+      - name: Build llmentary proxy
+        working-directory: llmentary-proxy
+        run: go build -o "$LLMENTARY_BIN" ./cmd/llmentary
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install package and dev tools
+        run: python -m pip install -e ".[dev,openai]"
+
+      - name: Real OpenAI E2E tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLMENTARY_UPSTREAM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: pytest -m e2e -vv --tb=short --durations=0
+
+  e2e-gate:
+    name: e2e-gate
+    if: ${{ always() }}
+    needs: [openai-e2e]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+      - name: Require live e2e success
+        env:
+          E2E_RESULT: ${{ needs.openai-e2e.result }}
+          EVENT_NAME: ${{ github.event_name }}
+          IS_FORK: ${{ github.event.pull_request.head.repo.fork == true }}
+        run: bash scripts/e2e-gate.sh