keycall 0.1.0__tar.gz

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

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        # No provider secrets: the suite runs against recorded fixtures only.
+        run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+
+      - name: Check metadata
+        run: twine check dist/*
+
+      - name: Verify package data ships
+        # catalog.json and py.typed are easy to lose to a packaging change
+        # and only fail at runtime, so assert them here.
+        run: |
+          python - <<'EOF'
+          import glob, zipfile, sys
+          wheel = sorted(glob.glob("dist/*.whl"))[-1]
+          names = zipfile.ZipFile(wheel).namelist()
+          missing = [
+              f for f in ("keycall/_catalog/catalog.json", "keycall/py.typed")
+              if f not in names
+          ]
+          if missing:
+              sys.exit(f"missing from wheel: {missing}")
+          print(f"{wheel}: package data present")
+          EOF
+
+      - name: Install from wheel and smoke test
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/*.whl
+          /tmp/smoke/bin/python -c "
+          import keycall
+          from keycall._registry import resolve_provider, catalog_version
+          assert resolve_provider('anthropic').base_url.startswith('https://')
+          print('keycall', keycall.__version__, 'catalog', catalog_version())
+          "

keycall-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,130 @@
+name: Release
+
+# Publishing is tag-driven: push a v* tag, and this builds, verifies,
+# publishes to PyPI, and cuts the GitHub release. Nothing publishes from a
+# developer machine.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: "Publish to TestPyPI instead of PyPI"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tooling
+        run: pip install build twine
+
+      - name: Verify tag matches package version
+        # A tag that disagrees with pyproject would publish the wrong version
+        # under the right name, which cannot be undone on PyPI.
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python - <<'EOF'
+          import os, sys, tomllib
+          with open("pyproject.toml", "rb") as f:
+              version = tomllib.load(f)["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if tag != version:
+              sys.exit(f"tag {tag!r} != pyproject version {version!r}")
+          print(f"version {version} matches tag")
+          EOF
+
+      - name: Run tests
+        run: |
+          pip install -e ".[dev]"
+          pytest -q
+
+      - name: Build
+        run: python -m build
+
+      - name: Check metadata
+        run: twine check dist/*
+
+      - name: Verify package data ships
+        run: |
+          python - <<'EOF'
+          import glob, zipfile, sys
+          wheel = sorted(glob.glob("dist/*.whl"))[-1]
+          names = zipfile.ZipFile(wheel).namelist()
+          missing = [
+              f for f in ("keycall/_catalog/catalog.json", "keycall/py.typed")
+              if f not in names
+          ]
+          if missing:
+              sys.exit(f"missing from wheel: {missing}")
+          EOF
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.test_pypi
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write  # OIDC for trusted publishing; no API token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for trusted publishing; no API token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # needed to create the release
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)." \
+            dist/*

keycall-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Internal design docs (PRD, naming decisions, research) — not part of the public package.
+/internal/
+
+# macOS and system files.
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+__MACOSX/
+Thumbs.db
+Desktop.ini
+
+# Local environment and tool state.
+.env
+.env.*
+.claude/
+.codex/
+
+# Live-test credential files (the .example templates stay tracked).
+keycall-test-keys.*
+!keycall-test-keys.example.*
+
+# Internal documentation (top-level project docs stay tracked).
+*.md
+!README.md
+!USAGE.md
+!CHANGELOG.md
+!CONTRIBUTING.md
+
+# Python build/runtime artifacts.
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Build/package artifacts and logs.
+*.zip
+*.tar
+*.tar.gz
+*.tgz
+*.log
+
+# Editor/project metadata.
+.idea/
+.vscode/

keycall-0.1.0/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to KeyCall are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] — 2026-08-05
+
+First release. Key validation, model discovery and filtering, and text
+generation, live-verified against every supported provider.
+
+### Added
+
+**Clients**
+
+- `KeyCall` and `AsyncKeyCall` with identical surfaces; only awaiting differs.
+- Provider and credential bound once at construction as immutable client
+  identity: no setters, no per-call override, no public `api_key` property.
+- Context-manager support; `close()` releases the credential and HTTP client.
+- Configurable `connect_timeout`, `read_timeout`, `max_response_bytes`,
+  `trust_env`, `allow_insecure_localhost`, and `allow_private_network`.
+
+**Model discovery**
+
+- `list_models(categories=..., refresh=...)` returning a `ModelDiscovery`
+  envelope with `models`, `fetched_at`, `from_cache`, `catalog_version`, and
+  `warnings`.
+- Eight-member `ModelCategory` taxonomy; text generation is the default filter.
+- Conservative classification: explicit provider metadata first, then
+  maintained identifier rules. Unclassifiable models resolve to `UNKNOWN` and
+  never enter the default text picker.
+- Process-local availability cache with a 5-minute TTL, keyed by an HMAC
+  fingerprint of the credential rather than the credential itself.
+
+**Text generation**
+
+- `invoke(TextGenerationRequest)` as the low-level primitive and
+  `generate_text(...)` as the convenience path.
+- Normalized `InvocationResult` with typed output parts, `usage`,
+  `round_trip_duration_ms`, `provider_request_id`, `finish_reason`, and
+  `warnings`.
+- `temperature` and `top_p`, validated at construction and omitted from the
+  wire body when unset. Models with maintained evidence that they reject
+  sampling parameters (OpenAI o-series and gpt-5; Anthropic Opus 4.7+,
+  Opus 5+, Sonnet 5+) fail with `MODEL_NOT_SUITABLE` before any network call.
+- Usage fields distinguish "provider reported zero" from "provider did not
+  report", which stays `None` and is never fabricated.
+
+**Providers**
+
+- OpenAI (Responses API), Anthropic (Messages), Google Gemini
+  (`generateContent`), DeepSeek, Perplexity (Sonar), Moonshot/Kimi.
+- Explicit OpenAI-compatible custom targets via `protocol` plus `base_url`.
+- Provider identity and wire protocol kept as separate concepts; named
+  providers may override their protocol's default adapter.
+
+**Errors**
+
+- Single `KeyCallError` with a typed `ErrorCode` discriminator, plus
+  `retryable`, `status_code`, `provider_request_id`, and `retry_after`.
+- Twelve normalized codes spanning credential, model, provider, transport, and
+  setup failures.
+
+**Security**
+
+- Credentials wrapped in a redacting type at the single public entry point;
+  excluded from reprs, formatting, exceptions, logs, traces, copies, and
+  pickles, with canary tests asserting absence.
+- `Credential.reveal()` called from exactly one place, the transport layer's
+  header builder.
+- Provider-originated error text scrubbed for credential values, credential
+  patterns, and control characters, then length-bounded, before reaching any
+  result, exception, log, or trace.
+- Redirects refused rather than followed while carrying a credential.
+- Response bodies read incrementally against a 10 MB cap.
+- SSRF guard rejecting literal private, loopback, link-local, and reserved IP
+  targets unless explicitly opted in.
+- DNS-rebinding guard for custom endpoints: resolves once, rejects if any
+  resolved address is private, then connects to the validated address while
+  preserving the original hostname for TLS SNI and `Host`.
+- HTTPS required for custom endpoints; plain HTTP only for localhost behind an
+  explicit flag.
+
+**Reliability**
+
+- Operation-aware retries: bounded retries with backoff and `Retry-After`
+  support for model listing; none for generation, since no supported provider
+  documents generation idempotency.
+- Explicit connect and read timeouts on every request.
+
+**CLI**
+
+- `keycall verify` for live credential verification from TXT, JSON, or TOML
+  files, an explicit `env:VAR_NAME` reference, or an interactive prompt.
+- `--generate` makes one bounded call per target, walking filtered models in
+  provider order and reporting every attempt (`--attempts`, default 8) so
+  provider drift stays visible.
+- `--strict-credentials` promotes credential-file warnings to errors.
+- Credential files are never modified or deleted; keys never appear in output.
+
+**Observability**
+
+- Optional TraceAct integration emitting `keycall.list_models` and
+  `keycall.text_generation` spans with safe fields only. Silent when TraceAct
+  is absent or the host has not configured it; disabled with one warning on an
+  incompatible version.
+
+### Known limitations
+
+- Streaming, tool calling, structured output, and non-text modalities are not
+  implemented.
+- Gemini's list endpoint advertises models an account cannot invoke and exposes
+  no lifecycle field, so they cannot be pre-filtered.
+- Perplexity's Sonar models are not API-discoverable and are maintained in the
+  bundled catalog.
+- The provider catalog ships inside the package and updates only on release.
+
+[Unreleased]: https://github.com/shehuphd/keycall/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/shehuphd/keycall/releases/tag/v0.1.0