keycall 0.1.0__py3-none-any.whl

keycall/__init__.py

@@ -0,0 +1,63 @@
+"""KeyCall: one consistent interface for validating AI-provider API keys,
+listing and filtering their models, and making normalized calls."""
+
+from ._client import AsyncKeyCall, KeyCall
+from ._enums import ModelCategory, Operation, ProviderProtocol
+from ._errors import ErrorCode, KeyCallError
+from ._types import (
+    AudioInput,
+    AudioOutput,
+    EmbeddingOutput,
+    FileInput,
+    FileOutput,
+    ImageInput,
+    ImageOutput,
+    InputPart,
+    InvocationResult,
+    Message,
+    MessageRole,
+    Model,
+    ModelDiscovery,
+    OutputPart,
+    TextGenerationRequest,
+    TextInput,
+    TextOutput,
+    TranscriptOutput,
+    UnknownOutput,
+    Usage,
+    VideoOutput,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncKeyCall",
+    "AudioInput",
+    "AudioOutput",
+    "EmbeddingOutput",
+    "ErrorCode",
+    "FileInput",
+    "FileOutput",
+    "ImageInput",
+    "ImageOutput",
+    "InputPart",
+    "InvocationResult",
+    "KeyCall",
+    "KeyCallError",
+    "Message",
+    "MessageRole",
+    "Model",
+    "ModelCategory",
+    "ModelDiscovery",
+    "Operation",
+    "OutputPart",
+    "ProviderProtocol",
+    "TextGenerationRequest",
+    "TextInput",
+    "TextOutput",
+    "TranscriptOutput",
+    "UnknownOutput",
+    "Usage",
+    "VideoOutput",
+    "__version__",
+]

keycall/_cache.py

@@ -0,0 +1,65 @@
+"""Credential-dependent availability cache (PRD section 11.1).
+
+Process-local, bounded, in-memory, cleared on restart. Keyed by provider +
+base URL + HMAC credential fingerprint — never the raw key or an unkeyed
+digest. Stores the full pre-filter model tuple; category filtering happens
+locally so switching filters never re-contacts the provider.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import datetime
+
+from ._types import Model
+
+__all__ = ["AvailabilityCache", "CachedModels"]
+
+_MAX_ENTRIES = 64
+DEFAULT_TTL_SECONDS = 300.0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CachedModels:
+    models: tuple[Model, ...]
+    fetched_at: datetime
+
+
+class AvailabilityCache:
+    def __init__(self, *, ttl_seconds: float = DEFAULT_TTL_SECONDS) -> None:
+        self._ttl = ttl_seconds
+        self._lock = threading.Lock()
+        self._entries: OrderedDict[tuple[str, str, str], tuple[float, CachedModels]] = OrderedDict()
+
+    def get(self, provider: str, base_url: str, fingerprint: str) -> CachedModels | None:
+        key = (provider, base_url, fingerprint)
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                return None
+            expires_at, cached = entry
+            if time.monotonic() >= expires_at:
+                del self._entries[key]
+                return None
+            self._entries.move_to_end(key)
+            return cached
+
+    def put(self, provider: str, base_url: str, fingerprint: str, cached: CachedModels) -> None:
+        key = (provider, base_url, fingerprint)
+        with self._lock:
+            self._entries[key] = (time.monotonic() + self._ttl, cached)
+            self._entries.move_to_end(key)
+            while len(self._entries) > _MAX_ENTRIES:
+                self._entries.popitem(last=False)
+
+    def invalidate(self, provider: str, base_url: str, fingerprint: str) -> None:
+        with self._lock:
+            self._entries.pop((provider, base_url, fingerprint), None)
+
+
+# One process-local cache shared by all clients, matching the process-local
+# HMAC fingerprint secret.
+shared_cache = AvailabilityCache()

keycall/_capabilities.py

@@ -0,0 +1,32 @@
+"""Maintained per-model capability evidence (PRD section 8).
+
+Small and deliberately conservative: an entry here blocks a request before
+it reaches the provider, so entries require confirmed evidence that the
+provider rejects the parameter. Wrong entries block valid calls — when
+unsure, leave the model out and let the provider's own 400 answer.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["rejects_sampling_params"]
+
+# Model families whose APIs reject temperature/top_p outright.
+# OpenAI reasoning families are documented: o-series and gpt-5 accept only
+# the default temperature and error on an explicit value.
+_SAMPLING_REJECTING = (
+    re.compile(r"^o\d"),        # o1, o3, o4-mini, ...
+    re.compile(r"^gpt-5"),      # gpt-5 family (Responses API)
+    # Anthropic deprecated temperature/top_p/top_k for newer reasoning and
+    # Opus models: sending them returns 400. Claude Opus 4.7+ and the newer
+    # Sonnet generations are affected; behavior is now controlled by prompting.
+    re.compile(r"^claude-opus-4-[7-9]"),
+    re.compile(r"^claude-opus-[5-9]"),
+    re.compile(r"^claude-sonnet-[5-9]"),
+)
+
+
+def rejects_sampling_params(model_id: str) -> bool:
+    lowered = model_id.lower()
+    return any(pattern.match(lowered) for pattern in _SAMPLING_REJECTING)

keycall/_catalog/catalog.json

@@ -0,0 +1,82 @@
+{
+  "schema_version": "1",
+  "catalog_version": "2026.08.05.1",
+  "verified_at": "2026-08-03T00:00:00Z",
+  "providers": {
+    "openai": {
+      "aliases": [],
+      "protocol": "openai",
+      "base_url": "https://api.openai.com/v1",
+      "auth": { "scheme": "bearer", "header": "Authorization" },
+      "operations": {
+        "list_models": { "method": "GET", "path": "/models" },
+        "text_generation": { "method": "POST", "path": "/responses" }
+      },
+      "provider_request_id_header": "x-request-id"
+    },
+    "anthropic": {
+      "aliases": ["claude"],
+      "protocol": "anthropic",
+      "base_url": "https://api.anthropic.com",
+      "auth": { "scheme": "api_key", "header": "x-api-key" },
+      "api_version_header": { "name": "anthropic-version", "value": "2023-06-01" },
+      "operations": {
+        "list_models": { "method": "GET", "path": "/v1/models" },
+        "text_generation": { "method": "POST", "path": "/v1/messages" }
+      },
+      "provider_request_id_header": "request-id"
+    },
+    "gemini": {
+      "aliases": ["google", "google-gemini"],
+      "protocol": "gemini",
+      "base_url": "https://generativelanguage.googleapis.com/v1beta",
+      "auth": { "scheme": "api_key", "header": "x-goog-api-key" },
+      "operations": {
+        "list_models": { "method": "GET", "path": "/models" },
+        "text_generation": { "method": "POST", "path": "/models/{model}:generateContent" }
+      },
+      "provider_request_id_header": null
+    },
+    "deepseek": {
+      "aliases": [],
+      "protocol": "openai-compatible",
+      "base_url": "https://api.deepseek.com",
+      "auth": { "scheme": "bearer", "header": "Authorization" },
+      "operations": {
+        "list_models": { "method": "GET", "path": "/models" },
+        "text_generation": { "method": "POST", "path": "/chat/completions" }
+      },
+      "provider_request_id_header": null
+    },
+    "perplexity": {
+      "aliases": ["pplx"],
+      "protocol": "openai-compatible",
+      "base_url": "https://api.perplexity.ai",
+      "auth": { "scheme": "bearer", "header": "Authorization" },
+      "operations": {
+        "list_models": { "method": "GET", "path": "/v1/models" },
+        "text_generation": { "method": "POST", "path": "/v1/sonar" }
+      },
+      "provider_request_id_header": null,
+      "model_discovery": "catalog",
+      "model_discovery_note": "GET /v1/models is scoped to the Agent API: it returns vendor-prefixed router models (anthropic/..., perplexity/sonar) that POST /v1/sonar rejects. Sonar models are not API-discoverable, so they are maintained here. The list call still runs to validate the credential. Verified live 2026-08-05.",
+      "models": [
+        { "id": "sonar", "categories": ["text_generation"] },
+        { "id": "sonar-pro", "categories": ["text_generation"] },
+        { "id": "sonar-reasoning-pro", "categories": ["text_generation"] }
+      ],
+      "min_max_output_tokens": 16
+    },
+    "moonshot": {
+      "aliases": ["kimi"],
+      "protocol": "openai-compatible",
+      "base_url": "https://api.moonshot.ai/v1",
+      "auth": { "scheme": "bearer", "header": "Authorization" },
+      "operations": {
+        "list_models": { "method": "GET", "path": "/models" },
+        "text_generation": { "method": "POST", "path": "/chat/completions" }
+      },
+      "provider_request_id_header": null
+    }
+  }
+}

keycall/_classify.py

@@ -0,0 +1,59 @@
+"""Conservative model classification (PRD section 8).
+
+Precedence: explicit provider metadata first (the Gemini adapter passes
+supported generation methods through), then maintained identifier rules.
+Conflicts and unknowns resolve to UNKNOWN — an unknown model must never
+silently enter the default text picker.
+"""
+
+from __future__ import annotations
+
+from ._enums import ModelCategory
+
+__all__ = ["classify_model_id"]
+
+# Ordered: first match wins. More specific non-text signals come before the
+# broad text-family patterns so "gpt-image-1" never classifies as text.
+_RULES: tuple[tuple[tuple[str, ...], ModelCategory], ...] = (
+    (("embed",), ModelCategory.EMBEDDING),
+    (("whisper", "transcribe"), ModelCategory.TRANSCRIPTION),
+    (("tts", "speech"), ModelCategory.SPEECH_GENERATION),
+    (("realtime",), ModelCategory.REALTIME),
+    (("dall-e", "image", "imagen", "flux"), ModelCategory.IMAGE_GENERATION),
+    (("sora", "veo"), ModelCategory.VIDEO_GENERATION),
+    # Ambiguous or out-of-taxonomy families stay unknown rather than
+    # guessing: moderation/reranking/guard models, audio-hybrid previews.
+    (("moderation", "rerank", "guard", "audio"), ModelCategory.UNKNOWN),
+)
+
+_TEXT_MARKERS: tuple[str, ...] = (
+    "gpt",
+    "chatgpt",
+    "claude",
+    "gemini",
+    "gemma",
+    "deepseek",
+    "sonar",
+    "moonshot",
+    "kimi",
+    "mistral",
+    "llama",
+    "qwen",
+    "glm",
+    "grok",
+)
+
+
+def classify_model_id(model_id: str) -> ModelCategory:
+    """Classify by identifier rules alone. Adapters with provider metadata
+    should prefer that evidence and only fall back here."""
+    lowered = model_id.lower()
+    for markers, category in _RULES:
+        if any(marker in lowered for marker in markers):
+            return category
+    if any(marker in lowered for marker in _TEXT_MARKERS):
+        return ModelCategory.TEXT_GENERATION
+    # OpenAI reasoning families: o1, o3, o4-mini, ...
+    if len(lowered) >= 2 and lowered[0] == "o" and lowered[1].isdigit():
+        return ModelCategory.TEXT_GENERATION
+    return ModelCategory.UNKNOWN

keycall/_cli.py

@@ -0,0 +1,197 @@
+"""keycall CLI: live credential verification (PRD section 14.2).
+
+Each target gets one model-list call. With --generate, KeyCall walks the
+filtered text models in provider order and reports the outcome of every
+attempt until one succeeds or the attempt budget runs out.
+
+This is *reported* fallthrough, not the silent fallthrough PRD section 14.3
+forbids: each skipped model is printed with the reason it was skipped, so
+provider drift (retired models still advertised, modality mismatches, quota
+walls) stays visible instead of being masked. A credential failure stops
+immediately — no point trying more models with a key the provider rejected.
+
+Keys never appear in output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ._enums import ModelCategory
+from ._errors import ErrorCode, KeyCallError
+from ._sanitize import safe_display_name
+from ._sources import SourceError, Target, load_targets, remind_deletion
+
+_GENERATION_PROMPT = "Reply with the single word: ok"
+_GENERATION_MAX_TOKENS = 16
+_DEFAULT_ATTEMPTS = 8
+
+# The credential itself is the problem: stop immediately, since no other
+# model will fare better with a key the provider has rejected.
+_CREDENTIAL_FAILURES = frozenset(
+    {ErrorCode.INVALID_API_KEY, ErrorCode.PERMISSION_DENIED}
+)
+# Everything else is model-scoped and worth trying the next candidate for.
+# Rate limits included, deliberately: providers meter per model and tier, so
+# a 429 on one model says nothing about the next (Gemini free tier gives
+# 2.5-pro zero quota while flash-latest answers fine). Exhausting the budget
+# on rate limits is reported as unverified, never as a failed adapter
+# (PRD 14.2: rate limits are distinct from adapter incompatibility).
+
+
+def _verify_target(
+    target: Target, *, generate: bool, attempts: int = _DEFAULT_ATTEMPTS
+) -> tuple[bool, list[str]]:
+    """Returns (ok, report_lines). Never raises for provider failures."""
+    from ._client import KeyCall
+    from ._types import Message, TextInput
+
+    label = target.display_name
+    lines = []
+    try:
+        with KeyCall(
+            provider=target.provider,
+            api_key=target.key,
+            protocol=target.protocol,
+            base_url=target.base_url,
+        ) as client:
+            # Verification must hit the live provider, never cached data.
+            discovery = client.list_models(
+                categories={ModelCategory.TEXT_GENERATION}, refresh=True
+            )
+            text_models = discovery.models
+            lines.append(
+                f"✓ {label} ({client.provider}): key accepted, "
+                f"{len(text_models)} text model(s)"
+            )
+            if not generate:
+                return True, lines
+            if not text_models:
+                lines.append(f"✗ {label}: no text models available to generate with")
+                return False, lines
+
+            messages = [Message(role="user", content=[TextInput(text=_GENERATION_PROMPT)])]
+            rate_limited = False
+            for position, candidate in enumerate(text_models[:attempts]):
+                try:
+                    result = client.generate_text(
+                        model=candidate.id,
+                        messages=messages,
+                        max_output_tokens=_GENERATION_MAX_TOKENS,
+                    )
+                except KeyCallError as error:
+                    lines.append(
+                        f"  ✗ {candidate.id} (position {position}): "
+                        f"{error.code.value} — {error.message}"
+                    )
+                    if error.code in _CREDENTIAL_FAILURES:
+                        lines.append(f"✗ {label}: credential rejected")
+                        return False, lines
+                    if error.code is ErrorCode.RATE_LIMITED:
+                        rate_limited = True
+                    continue
+                usage = result.usage.total_tokens
+                skipped = f", {position} advertised model(s) skipped" if position else ""
+                lines.append(
+                    f"✓ {label}: generated with {candidate.id} "
+                    f"(filtered position {position}{skipped}, "
+                    f"{result.round_trip_duration_ms:.0f} ms, "
+                    f"total tokens: {usage if usage is not None else 'unreported'})"
+                )
+                return True, lines
+
+            tried = min(attempts, len(text_models))
+            if rate_limited:
+                lines.append(
+                    f"! {label}: generation unverified — quota/rate limited "
+                    f"({tried} attempted of {len(text_models)})"
+                )
+            else:
+                lines.append(
+                    f"✗ {label}: no advertised text model was invocable "
+                    f"({tried} attempted of {len(text_models)})"
+                )
+            return False, lines
+    except KeyCallError as error:
+        lines.append(
+            f"✗ {label} ({target.provider}): {error.code.value} — {error.message}"
+            + (" [retryable]" if error.retryable else "")
+        )
+        return False, lines
+
+
+def _run_verify(args: argparse.Namespace) -> int:
+    try:
+        targets, warnings = load_targets(
+            args.source or "-",
+            provider=args.provider,
+            protocol=args.protocol,
+            base_url=args.base_url,
+        )
+    except SourceError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+
+    for warning in warnings:
+        if args.strict_credentials:
+            print(f"error (strict): {warning.message}", file=sys.stderr)
+            return 2
+        print(f"warning: {warning.message}", file=sys.stderr)
+
+    all_ok = True
+    for target in targets:
+        ok, lines = _verify_target(target, generate=args.generate, attempts=args.attempts)
+        all_ok = all_ok and ok
+        for line in lines:
+            print(safe_display_name(line, max_length=300))
+
+    if args.source:
+        reminder = remind_deletion(args.source)
+        if reminder:
+            print(reminder, file=sys.stderr)
+
+    return 0 if all_ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="keycall")
+    subparsers = parser.add_subparsers(dest="command")
+
+    verify = subparsers.add_parser(
+        "verify", help="verify credentials against live providers"
+    )
+    verify.add_argument(
+        "--source",
+        "-s",
+        help="TXT/JSON/TOML target file, env:VAR_NAME, or omit for interactive prompt",
+    )
+    verify.add_argument("--provider", help="provider name (env:/interactive sources)")
+    verify.add_argument("--protocol", help="protocol override (custom targets)")
+    verify.add_argument("--base-url", dest="base_url", help="base URL (custom targets)")
+    verify.add_argument(
+        "--generate",
+        action="store_true",
+        help="also make one bounded text generation per target",
+    )
+    verify.add_argument(
+        "--attempts",
+        type=int,
+        default=_DEFAULT_ATTEMPTS,
+        help=f"max models to try per target with --generate (default {_DEFAULT_ATTEMPTS})",
+    )
+    verify.add_argument(
+        "--strict-credentials",
+        action="store_true",
+        help="treat credential-file warnings as errors",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "verify":
+        return _run_verify(args)
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())