vrr/free-claude-code
2
0
Fork 0
mirror of https://github.com/Alishahryar1/free-claude-code.git synced 2026-07-09 16:00:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
free-claude-code/config/provider_catalog.py
Ali Khokhar 85b601884d
Some checks are pending
CI / Ban suppressions and legacy annotations (push) Waiting to run
Details
CI / pytest (push) Waiting to run
Details
CI / ruff-check (push) Waiting to run
Details
CI / ruff-format (push) Waiting to run
Details
CI / ty (push) Waiting to run
Details
Remove legacy future annotation imports (#982) 
## Problem

Python 3.14 provides native lazy annotations, but the codebase still
relied on legacy future annotation imports. Those imports also made
type-only import cycles easier to hide instead of fixing ownership
boundaries.

## Changes

| Before | After |
| --- | --- |
| Python files used `from __future__ import annotations`. | Python files
rely on Python 3.14 native lazy annotations. |
| Some runtime modules used `TYPE_CHECKING` or local imports for
required dependencies. | Runtime modules use top-level owner-module
imports with explicit boundaries. |
| Local and GitHub guardrails only rejected type ignore suppressions. |
Local and GitHub guardrails reject type ignore suppressions and legacy
future annotation imports. |
| Agent docs only documented the no-type-ignore rule. | Agent docs
document the Python 3.14 annotation and import-boundary rules. |

<!-- greptile_comment -->

<details open><summary><h3>Greptile Summary</h3></summary>

This PR moves the codebase to Python 3.14 native lazy annotations. The
main changes are:

- Removed legacy `from __future__ import annotations` imports across
Python modules.
- Promoted selected runtime dependencies from `TYPE_CHECKING` or local
imports to explicit owner-module imports.
- Added local, GitHub, and contract-test guardrails to reject legacy
future annotation imports.
- Updated agent docs with the annotation and import-boundary rules.
- Bumped the package patch version for production-file changes.
</details>

<h3>Confidence Score: 5/5</h3>

Safe to merge with low risk.

The changes are mostly mechanical annotation cleanup with matching CI
and contract-test guardrails. Reviewed import-boundary updates did not
show a confirmed runtime cycle or dependency break.

No files require special attention.

<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>

**What T-Rex did**
- Performed an end-to-end validation of the guardrail contract suite: an
environment check confirmed uv availability, a guardrail pytest run used
CPython 3.14.0 with 5 passing contract tests, 3 focused CI-script tests
passed, and the direct CI suppressions guardrail command (including the
legacy future-annotations grep) also passed.

<a
href="https://app.greptile.com/trex/runs/13303335/artifacts"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=4"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"><img
alt="View all artifacts"
src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"></picture></a>

<sub><a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex</sub>
</details>

<details open><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| api/runtime.py | Moves messaging, CLI manager, session, limiter, and
tree dependencies from local/type-checking imports to explicit top-level
owner-module imports. |
| messaging/platforms/telegram.py | Removes future annotations and
promotes Telegram SDK type imports into the existing availability guard.
|
| messaging/platforms/telegram_inbound.py | Removes future annotations
and imports Telegram SDK types at module scope for inbound
normalization. |
| tests/contracts/test_import_boundaries.py | Adds an AST contract that
rejects legacy future annotation imports across Python files. |
| scripts/ci.sh | Extends the local suppression check to reject legacy
future annotation imports alongside type-ignore suppressions. |
| scripts/ci.ps1 | Mirrors the local PowerShell CI suppression check for
legacy future annotations. |
| .github/workflows/tests.yml | Renames and broadens the GitHub
guardrail job to reject both type suppressions and legacy future
annotations. |
| pyproject.toml | Bumps the patch version for production-file changes.
|

</details>

<details open><summary><h3>Sequence Diagram</h3></summary>

<a href="#gh-light-mode-only">

```mermaid
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Dev as Developer/CI
participant Guard as Suppression guard
participant AST as Import-boundary contract test
participant Py as Python modules

Dev->>Guard: Run local/GitHub suppression check
Guard->>Py: "Scan *.py for type ignores and future annotations"
Guard-->>Dev: Fail if legacy annotation import remains
Dev->>AST: Run pytest contract tests
AST->>Py: Parse imports with ast
AST-->>Dev: Assert no future annotations/import-boundary violations
Py-->>Dev: Use Python 3.14 native lazy annotations
```

</a>
<a href="#gh-dark-mode-only">

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Dev as Developer/CI
participant Guard as Suppression guard
participant AST as Import-boundary contract test
participant Py as Python modules

Dev->>Guard: Run local/GitHub suppression check
Guard->>Py: "Scan *.py for type ignores and future annotations"
Guard-->>Dev: Fail if legacy annotation import remains
Dev->>AST: Run pytest contract tests
AST->>Py: Parse imports with ast
AST-->>Dev: Assert no future annotations/import-boundary violations
Py-->>Dev: Use Python 3.14 native lazy annotations
```

</a>
</details>

<sub>Reviews (2): Last reviewed commit: ["Remove legacy future
annotations
import"](6e6cda69da)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=41875785)</sub>

<!-- /greptile_comment -->
2026-07-04 21:41:51 -07:00

312 lines
12 KiB
Python
Raw Blame History

"""Neutral provider catalog: IDs, credentials, defaults, proxy and capability metadata.
Adapter factories live in :mod:`providers.runtime.factory`; this module stays free of
provider implementation imports (see contract tests).
"""
from dataclasses import dataclass
from typing import Literal
TransportType = Literal["openai_chat", "anthropic_messages"]
# Default upstream base URLs (also re-exported via :mod:`providers.defaults`)
NVIDIA_NIM_DEFAULT_BASE = "https://integrate.api.nvidia.com/v1"
# Moonshot Kimi Anthropic-compatible Messages API (POST …/messages).
KIMI_DEFAULT_BASE = "https://api.moonshot.ai/anthropic/v1"
WAFER_DEFAULT_BASE = "https://pass.wafer.ai/v1"
MINIMAX_DEFAULT_BASE = "https://api.minimax.io/anthropic/v1"
# DeepSeek Chat Completions API; cache usage is reported on this endpoint.
DEEPSEEK_DEFAULT_BASE = "https://api.deepseek.com"
FIREWORKS_DEFAULT_BASE = "https://api.fireworks.ai/inference/v1"
# Cloudflare account-scoped AI REST root; provider appends /accounts/{id}/ai/v1.
CLOUDFLARE_AI_REST_ROOT = "https://api.cloudflare.com/client/v4"
OPENROUTER_DEFAULT_BASE = "https://openrouter.ai/api/v1"
MISTRAL_DEFAULT_BASE = "https://api.mistral.ai/v1"
# Codestral IDE/personal endpoint (distinct from La Plateforme ``api.mistral.ai`` keys).
CODESTRAL_DEFAULT_BASE = "https://codestral.mistral.ai/v1"
LMSTUDIO_DEFAULT_BASE = "http://localhost:1234/v1"
LLAMACPP_DEFAULT_BASE = "http://localhost:8080/v1"
OLLAMA_DEFAULT_BASE = "http://localhost:11434"
OPENCODE_DEFAULT_BASE = "https://opencode.ai/zen/v1"
OPENCODE_GO_DEFAULT_BASE = "https://opencode.ai/zen/go/v1"
# Z.ai Anthropic-compatible Messages API (not OpenAI Coding Plan chat completions).
ZAI_DEFAULT_BASE = "https://api.z.ai/api/anthropic/v1"
# Google AI Studio Gemini API OpenAI-compat layer (not Vertex AI).
GEMINI_DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta/openai/"
GROQ_DEFAULT_BASE = "https://api.groq.com/openai/v1"
CEREBRAS_DEFAULT_BASE = "https://api.cerebras.ai/v1"
@dataclass(frozen=True, slots=True)
class ProviderDescriptor:
"""Metadata for building :class:`~providers.base.ProviderConfig` and factory wiring."""
provider_id: str
display_name: str
transport_type: TransportType
capabilities: tuple[str, ...]
credential_env: str | None = None
credential_url: str | None = None
credential_attr: str | None = None
static_credential: str | None = None
default_base_url: str | None = None
base_url_attr: str | None = None
proxy_attr: str | None = None
PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
"nvidia_nim": ProviderDescriptor(
provider_id="nvidia_nim",
display_name="NVIDIA NIM",
transport_type="openai_chat",
credential_env="NVIDIA_NIM_API_KEY",
credential_url="https://build.nvidia.com/settings/api-keys",
credential_attr="nvidia_nim_api_key",
default_base_url=NVIDIA_NIM_DEFAULT_BASE,
proxy_attr="nvidia_nim_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"open_router": ProviderDescriptor(
provider_id="open_router",
display_name="OpenRouter",
transport_type="anthropic_messages",
credential_env="OPENROUTER_API_KEY",
credential_url="https://openrouter.ai/keys",
credential_attr="open_router_api_key",
default_base_url=OPENROUTER_DEFAULT_BASE,
proxy_attr="open_router_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),
),
"gemini": ProviderDescriptor(
provider_id="gemini",
display_name="Gemini",
transport_type="openai_chat",
credential_env="GEMINI_API_KEY",
credential_url="https://aistudio.google.com/apikey",
credential_attr="gemini_api_key",
default_base_url=GEMINI_DEFAULT_BASE,
proxy_attr="gemini_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"deepseek": ProviderDescriptor(
provider_id="deepseek",
display_name="DeepSeek",
transport_type="openai_chat",
credential_env="DEEPSEEK_API_KEY",
credential_url="https://platform.deepseek.com/api_keys",
credential_attr="deepseek_api_key",
default_base_url=DEEPSEEK_DEFAULT_BASE,
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"mistral": ProviderDescriptor(
provider_id="mistral",
display_name="Mistral",
transport_type="openai_chat",
credential_env="MISTRAL_API_KEY",
credential_url="https://console.mistral.ai/",
credential_attr="mistral_api_key",
default_base_url=MISTRAL_DEFAULT_BASE,
proxy_attr="mistral_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"mistral_codestral": ProviderDescriptor(
provider_id="mistral_codestral",
display_name="Mistral Codestral",
transport_type="openai_chat",
credential_env="CODESTRAL_API_KEY",
credential_url="https://console.mistral.ai/",
credential_attr="codestral_api_key",
default_base_url=CODESTRAL_DEFAULT_BASE,
proxy_attr="codestral_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"opencode": ProviderDescriptor(
provider_id="opencode",
display_name="OpenCode Zen",
transport_type="openai_chat",
credential_env="OPENCODE_API_KEY",
credential_url="https://opencode.ai/auth",
credential_attr="opencode_api_key",
default_base_url=OPENCODE_DEFAULT_BASE,
proxy_attr="opencode_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"opencode_go": ProviderDescriptor(
provider_id="opencode_go",
display_name="OpenCode Go",
transport_type="openai_chat",
credential_env="OPENCODE_API_KEY",
credential_url="https://opencode.ai/auth",
credential_attr="opencode_api_key",
default_base_url=OPENCODE_GO_DEFAULT_BASE,
proxy_attr="opencode_go_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"wafer": ProviderDescriptor(
provider_id="wafer",
display_name="Wafer",
transport_type="anthropic_messages",
credential_env="WAFER_API_KEY",
credential_url="https://www.wafer.ai/pass",
credential_attr="wafer_api_key",
default_base_url=WAFER_DEFAULT_BASE,
proxy_attr="wafer_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),
),
"kimi": ProviderDescriptor(
provider_id="kimi",
display_name="Kimi",
transport_type="anthropic_messages",
credential_env="KIMI_API_KEY",
credential_url="https://platform.moonshot.cn/console/api-keys",
credential_attr="kimi_api_key",
default_base_url=KIMI_DEFAULT_BASE,
proxy_attr="kimi_proxy",
capabilities=(
"chat",
"streaming",
"tools",
"thinking",
"native_anthropic",
),
),
"minimax": ProviderDescriptor(
provider_id="minimax",
display_name="MiniMax",
transport_type="anthropic_messages",
credential_env="MINIMAX_API_KEY",
credential_url="https://platform.minimax.io/user-center/basic-information/interface-key",
credential_attr="minimax_api_key",
default_base_url=MINIMAX_DEFAULT_BASE,
proxy_attr="minimax_proxy",
capabilities=(
"chat",
"streaming",
"tools",
"thinking",
"native_anthropic",
"rate_limit",
),
),
"cerebras": ProviderDescriptor(
provider_id="cerebras",
display_name="Cerebras",
transport_type="openai_chat",
credential_env="CEREBRAS_API_KEY",
credential_url="https://cloud.cerebras.ai",
credential_attr="cerebras_api_key",
default_base_url=CEREBRAS_DEFAULT_BASE,
proxy_attr="cerebras_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"groq": ProviderDescriptor(
provider_id="groq",
display_name="Groq",
transport_type="openai_chat",
credential_env="GROQ_API_KEY",
credential_url="https://console.groq.com/keys",
credential_attr="groq_api_key",
default_base_url=GROQ_DEFAULT_BASE,
proxy_attr="groq_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
"fireworks": ProviderDescriptor(
provider_id="fireworks",
display_name="Fireworks",
transport_type="anthropic_messages",
credential_env="FIREWORKS_API_KEY",
credential_url="https://fireworks.ai/account/api-keys",
credential_attr="fireworks_api_key",
default_base_url=FIREWORKS_DEFAULT_BASE,
proxy_attr="fireworks_proxy",
capabilities=(
"chat",
"streaming",
"tools",
"thinking",
"native_anthropic",
"rate_limit",
),
),
"cloudflare": ProviderDescriptor(
provider_id="cloudflare",
display_name="Cloudflare",
transport_type="openai_chat",
credential_env="CLOUDFLARE_API_TOKEN",
credential_url="https://dash.cloudflare.com/profile/api-tokens",
credential_attr="cloudflare_api_token",
default_base_url=CLOUDFLARE_AI_REST_ROOT,
proxy_attr="cloudflare_proxy",
capabilities=(
"chat",
"streaming",
"tools",
"thinking",
"rate_limit",
),
),
"zai": ProviderDescriptor(
provider_id="zai",
display_name="Z.ai",
transport_type="anthropic_messages",
credential_env="ZAI_API_KEY",
credential_attr="zai_api_key",
default_base_url=ZAI_DEFAULT_BASE,
proxy_attr="zai_proxy",
capabilities=(
"chat",
"streaming",
"tools",
"thinking",
"native_anthropic",
"rate_limit",
),
),
"lmstudio": ProviderDescriptor(
provider_id="lmstudio",
display_name="LM Studio",
transport_type="openai_chat",
static_credential="lm-studio",
default_base_url=LMSTUDIO_DEFAULT_BASE,
base_url_attr="lm_studio_base_url",
proxy_attr="lmstudio_proxy",
capabilities=("chat", "streaming", "tools", "local"),
),
"llamacpp": ProviderDescriptor(
provider_id="llamacpp",
display_name="llama.cpp",
transport_type="anthropic_messages",
static_credential="llamacpp",
default_base_url=LLAMACPP_DEFAULT_BASE,
base_url_attr="llamacpp_base_url",
proxy_attr="llamacpp_proxy",
capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),
),
"ollama": ProviderDescriptor(
provider_id="ollama",
display_name="Ollama",
transport_type="anthropic_messages",
static_credential="ollama",
default_base_url=OLLAMA_DEFAULT_BASE,
base_url_attr="ollama_base_url",
capabilities=(
"chat",
"streaming",
"tools",
"thinking",
"native_anthropic",
"local",
),
),
}
# Key order:
# NVIDIA NIM first (README default), DeepSeek fourth, Wafer ninth / Kimi tenth;
# MiniMax follows the native Anthropic remotes; then cerebras / groq / fireworks /
# Cloudflare overlap; remainder and locals last per project plan (
# github.com/cheahjs/free-llm-api-resources Free Providers TOC as rough guide beyond fixed slots).
# ``SUPPORTED_PROVIDER_IDS`` inherits this insertion order for UI and error-message listing.
SUPPORTED_PROVIDER_IDS: tuple[str, ...] = tuple(PROVIDER_CATALOG.keys())
if len(set(SUPPORTED_PROVIDER_IDS)) != len(SUPPORTED_PROVIDER_IDS):
raise AssertionError("Duplicate provider ids in PROVIDER_CATALOG key order")
Reference in a new issue View git blame Copy permalink