llm-conduit 0.1.0__tar.gz

llm_conduit-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,71 @@
+name: Bug Report
+description: Report a bug or unexpected behaviour
+labels: [bug, needs-triage]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill out the sections below.
+
+  - type: input
+    id: version
+    attributes:
+      label: llm-conduit version
+      placeholder: "e.g. 0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.11.8"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: modality
+    attributes:
+      label: Affected modality
+      multiple: true
+      options:
+        - LLMClient
+        - ImageGenClient
+        - VideoGenClient
+        - EmbeddingClient
+        - Middleware (retry / rate-limit / cost / logging)
+        - Registry (ModelRegistry / ProviderRegistry)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Clear description of the bug and what you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest possible code snippet that reproduces the issue.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Full traceback / error output
+      render: text
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Provider name, OS, any other relevant details.

llm_conduit-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,9 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: Documentation
+    url: https://github.com/your-org/llm-conduit#readme
+    about: Read the README and examples/ before opening an issue.
+  - name: Discussions
+    url: https://github.com/your-org/llm-conduit/discussions
+    about: Ask questions and share ideas in Discussions.

llm_conduit-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,55 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: [enhancement]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening a request, please check that no existing issue covers this.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - New modality client
+        - New middleware
+        - New provider adapter (examples/)
+        - Registry / config
+        - Request / response models
+        - Documentation / examples
+        - CI / tooling
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What problem are you trying to solve? Why does the current SDK not cover it?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How should this work? Include API sketches or pseudocode if helpful.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What else did you consider, and why did you rule it out?
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to open a PR for this feature.

llm_conduit-0.1.0/.github/ISSUE_TEMPLATE/new_provider.yml

@@ -0,0 +1,51 @@
+name: New Provider Adapter
+description: Request or track a new provider adapter in examples/providers/
+labels: [provider, enhancement]
+assignees: []
+
+body:
+  - type: input
+    id: provider
+    attributes:
+      label: Provider name
+      placeholder: "e.g. Stability AI, Mistral, Kling, ElevenLabs"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: modalities
+    attributes:
+      label: Modalities to support
+      options:
+        - label: LLM (chat completion + streaming)
+        - label: Image generation
+        - label: Video generation
+        - label: Embeddings
+    validations:
+      required: true
+
+  - type: input
+    id: sdk
+    attributes:
+      label: Provider's official Python SDK (if any)
+      placeholder: "e.g. pip install stability-sdk"
+
+  - type: input
+    id: docs
+    attributes:
+      label: API documentation URL
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes / quirks
+      description: Anything unusual about this provider's API (auth, async jobs, rate limits, etc.)
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to open a PR with this adapter.

llm_conduit-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## Summary
+
+<!-- What does this PR do? 1–3 sentences. -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (new modality, middleware, registry capability)
+- [ ] New provider adapter (in `examples/providers/`)
+- [ ] Documentation / examples
+- [ ] Refactor / internal improvement
+- [ ] CI / tooling
+
+## Checklist
+
+- [ ] `pytest tests/` passes locally
+- [ ] `ruff check conduit_sdk tests examples` passes
+- [ ] New code has corresponding tests
+- [ ] Docstrings updated on any changed public API
+- [ ] `CHANGELOG.md` updated (for non-trivial changes)
+
+## Breaking changes
+
+<!-- Does this change the public interface of BaseClient, any abstract client, or any Pydantic model?
+     If yes, describe what breaks and why it is necessary. -->
+
+None / describe here.
+
+## Related issues
+
+Closes #

llm_conduit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,240 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ──────────────────────────────────────────────────────────────
+  # Lint & format check
+  # ──────────────────────────────────────────────────────────────
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv pip install --system ruff
+
+      - name: Run ruff (lint)
+        run: ruff check conduit_sdk tests examples
+
+      - name: Run ruff (format check)
+        run: ruff format --check conduit_sdk tests examples
+
+  # ──────────────────────────────────────────────────────────────
+  # Type checking
+  # ──────────────────────────────────────────────────────────────
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install project + all extras + dev deps
+        run: uv pip install --system -e ".[dev,openai,anthropic]"
+
+      - name: Run mypy
+        run: mypy conduit_sdk
+
+  # ──────────────────────────────────────────────────────────────
+  # Tests — matrix across Python 3.10, 3.11, 3.12
+  # ──────────────────────────────────────────────────────────────
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install project + all extras + dev deps
+        run: uv pip install --system -e ".[dev,openai,anthropic]"
+
+      - name: Run pytest with coverage
+        run: |
+          pytest tests/ \
+            --tb=short \
+            --cov=conduit_sdk \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=80
+
+      - name: Upload coverage report
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml
+          retention-days: 7
+
+  # ──────────────────────────────────────────────────────────────
+  # Run example scripts (smoke test — no API keys needed)
+  # ──────────────────────────────────────────────────────────────
+  examples:
+    name: Smoke-test examples
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install project + all extras
+        run: uv pip install --system -e ".[dev,openai,anthropic]"
+
+      - name: Run examples
+        run: |
+          for script in \
+            examples/01_basic_llm.py \
+            examples/02_streaming.py \
+            examples/03_image_generation.py \
+            examples/04_video_generation.py \
+            examples/05_embeddings.py \
+            examples/06_cost_tracking.py \
+            examples/07_custom_middleware.py \
+            examples/08_registry.py \
+            examples/09_multimodal_pipeline.py; do
+            echo "▶ Running $script"
+            python "$script"
+            echo "✓ $script passed"
+          done
+
+  # ──────────────────────────────────────────────────────────────
+  # Integration tests — real OpenAI API calls
+  # Only runs on push to main (not on every PR) to avoid burning credits.
+  # Requires OPENAI_API_KEY to be set as a GitHub repository secret.
+  # ──────────────────────────────────────────────────────────────
+  integration-openai:
+    name: Integration tests (OpenAI)
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install project with OpenAI extra
+        run: uv pip install --system -e ".[dev,openai]"
+
+      - name: Run OpenAI integration tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          pytest tests/providers/test_openai_llm.py \
+                 tests/providers/test_openai_embedding.py \
+                 tests/providers/test_openai_image.py \
+            -m integration \
+            -v \
+            --tb=short \
+            --timeout=60
+
+  # ──────────────────────────────────────────────────────────────
+  # Integration tests — real Anthropic API calls
+  # Only runs on push to main (not on every PR) to avoid burning credits.
+  # Requires ANTHROPIC_API_KEY to be set as a GitHub repository secret.
+  # ──────────────────────────────────────────────────────────────
+  integration-anthropic:
+    name: Integration tests (Anthropic)
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install project with Anthropic extra
+        run: uv pip install --system -e ".[dev,anthropic]"
+
+      - name: Run Anthropic integration tests
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          pytest tests/providers/test_anthropic_llm.py \
+            -m integration \
+            -v \
+            --tb=short \
+            --timeout=60
+
+  # ──────────────────────────────────────────────────────────────
+  # All checks must pass before merge (used as branch protection rule)
+  # ──────────────────────────────────────────────────────────────
+  ci-pass:
+    name: CI passed
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test, examples]
+    if: always()
+    steps:
+      - name: Check all jobs
+        run: |
+          if [[ "${{ needs.lint.result }}" != "success" || \
+                "${{ needs.typecheck.result }}" != "success" || \
+                "${{ needs.test.result }}" != "success" || \
+                "${{ needs.examples.result }}" != "success" ]]; then
+            echo "One or more CI jobs failed."
+            exit 1
+          fi
+          echo "All CI jobs passed."

llm_conduit-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: CodeQL Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "30 5 * * 1"   # every Monday at 05:30 UTC
+
+jobs:
+  analyze:
+    name: Analyze (Python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:python"

llm_conduit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,192 @@
+name: Publish to PyPI
+
+# ──────────────────────────────────────────────────────────────
+# Triggers
+#   Stable release : git tag v1.2.3   → PyPI  + GitHub Release
+#   Pre-release    : git tag v1.2.3b1 → TestPyPI + GitHub pre-release
+#   Manual         : Actions tab → Run workflow (choose target)
+# ──────────────────────────────────────────────────────────────
+on:
+  push:
+    tags:
+      - "v*.*.*"          # v1.0.0, v1.2.3, v0.1.0 …
+      - "v*.*.*.*"        # v1.0.0.post1 etc.
+
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        required: true
+        default: "testpypi"
+        type: choice
+        options: [testpypi, pypi]
+
+jobs:
+  # ──────────────────────────────────────────────────────────────
+  # Lint + test before we touch PyPI
+  # ──────────────────────────────────────────────────────────────
+  verify:
+    name: Verify before publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install project + dev deps
+        run: uv pip install --system -e ".[dev,openai,anthropic]"
+
+      - name: Lint
+        run: ruff check conduit_sdk tests
+
+      - name: Tests
+        run: pytest tests/ --tb=short -q
+
+  # ──────────────────────────────────────────────────────────────
+  # Build sdist + wheel
+  # ──────────────────────────────────────────────────────────────
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: verify
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: uv pip install --system build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution with twine
+        run: twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  # ──────────────────────────────────────────────────────────────
+  # Detect whether this tag is a pre-release
+  # PEP 440 pre-releases: a/b/rc suffix  e.g. v1.0.0a1, v1.0.0b2, v1.0.0rc1
+  # ──────────────────────────────────────────────────────────────
+  classify-tag:
+    name: Classify tag
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    outputs:
+      is_prerelease: ${{ steps.check.outputs.is_prerelease }}
+    steps:
+      - name: Check if pre-release tag
+        id: check
+        run: |
+          TAG="${{ github.ref_name }}"
+          if echo "$TAG" | grep -qE '(a|b|rc|alpha|beta|dev)[0-9]*$'; then
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  # ──────────────────────────────────────────────────────────────
+  # Publish stable releases → PyPI
+  # ──────────────────────────────────────────────────────────────
+  publish-pypi:
+    name: Publish → PyPI
+    runs-on: ubuntu-latest
+    needs: [build, classify-tag]
+    if: |
+      (github.event_name == 'push' && needs.classify-tag.outputs.is_prerelease == 'false') ||
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/llm-conduit
+    permissions:
+      id-token: write   # OIDC trusted publishing — no API token needed
+
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ──────────────────────────────────────────────────────────────
+  # Publish pre-releases → TestPyPI
+  # ──────────────────────────────────────────────────────────────
+  publish-testpypi:
+    name: Publish → TestPyPI
+    runs-on: ubuntu-latest
+    needs: [build, classify-tag]
+    if: |
+      (github.event_name == 'push' && needs.classify-tag.outputs.is_prerelease == 'true') ||
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi')
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/llm-conduit
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # ──────────────────────────────────────────────────────────────
+  # Auto-create GitHub Release after successful publish
+  # ──────────────────────────────────────────────────────────────
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [publish-pypi, classify-tag]
+    if: |
+      always() &&
+      github.event_name == 'push' &&
+      (needs.publish-pypi.result == 'success' || needs.publish-testpypi.result == 'success')
+    permissions:
+      contents: write   # needed to create releases
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          prerelease: ${{ needs.classify-tag.outputs.is_prerelease == 'true' }}
+          generate_release_notes: true   # auto-fills from PR titles & commits
+          files: dist/*