trance

trance discovers a limited set of documented credentials and signed-in coding tools already configured on your machine, then builds model objects using Pydantic AI. It is a small Python library for applications that want to reuse supported local provider setups.

Consumer subscriptions do not automatically grant general API access. A credential being present does not establish that a provider permits using it from arbitrary software. trance scans only documented local auth state. It does not search private browser stores or undocumented application stores; raw token strings are not returned or logged, although model objects may retain auth internally for requests. Supported CLI adapters may privately stage documented saved credentials for a request. Gemini CLI OAuth is surfaced only with a warning because its terms prohibit third-party access to the service through its OAuth session and may suspend or terminate accounts.

Coverage at a glance

Grok Build and the xAI API are separate credential paths. A consumer account or subscription does not by itself provide an xAI API credential. Gemini CLI OAuth is a separate, warned integration with Google's terms risk; Gemini API keys remain a separate credential path.

Install

For a checkout, install the package and development dependencies with:

uv sync --extra dev

The core dependency includes Pydantic AI's OpenAI support. Optional extras for provider integrations supported by trance are anthropic, bedrock, cerebras, cohere, crusoe, google, groq, huggingface, mistral, openrouter, and xai. The fixed compatible adapters, including Crusoe, use the core OpenAI-compatible model path, so the crusoe extra is not required for them.

Quick start

Sign in with a supported local CLI or configure a documented provider key, then scan:

from trance.discovery import scan
from pydantic_ai import Agent

found = scan()
for item in found:
    print(item.provider, item.auth_kind, item.source, item.model_name)

# Use a discovered Pydantic AI Model with Agent. Calling run() sends a request.
agents = [Agent(model=item.model) for item in found]

scan() returns list[FoundModel]. Each record identifies the provider, authentication kind, discovery source, and model name alongside a Pydantic AI Model. It constructs objects without sending a request. It does not check whether a credential is currently valid, permitted for a particular use, or within quota. A FoundModel represents a successfully constructed model; source adapters that cannot be safely connected to a supported model are skipped in the default non-strict mode. Set strict=True to raise on a source or model construction failure.

You can restrict discovery by provider ID, or pass an environment mapping and home directory for controlled runs:

from pathlib import Path
from trance.discovery import scan

found = scan(
    environ={"OPENAI_API_KEY": "sk-example-not-a-real-key"},
    home=Path("/home/me"),
    providers={"openai"},
)

Avoid printing or logging the model object: it may retain provider authentication material for requests. FoundModel and candidate representations redact their model and secret fields. The source field describes where a credential was found and is safe to display.

Discovery sources

scan() currently registers these adapters. Subscription and account integrations are scanned first; ordinary API credentials are scanned after them. A subscription login is an integration with the vendor's documented account or CLI flow. It is not a general-purpose API key.

The fixed compatible registry currently covers 22 API-key providers, including AkashML, Scaleway, Friendli, Clarifai, Meta Model API, Parasail, and Nscale. These credentials are ordinary API credentials, not subscription or account- login integrations.

The model construction path supports the registered provider IDs: API and account integrations use trance.models.build_model(), while Claude Code, Grok Build, Gemini CLI, Cody, and OpenCode use text-only CLI adapters. It creates Pydantic AI model objects without sending a request and loads optional provider dependencies lazily. Use TRANCE_MODEL_<PROVIDER> variables to override defaults where the source supports them. To use the optional Grok Build integration, install the official grok CLI and authenticate it with grok login (or grok login --device-auth on a headless machine). Discovery only checks the CLI and bounded OIDC metadata in the saved auth.json; it does not claim that the session is valid until the CLI handles a model request. The optional Gemini CLI integration similarly requires the official gemini CLI and a saved oauth_creds.json; discovery emits its terms warning whenever it finds one. The optional Cody and OpenCode integrations likewise require their respective CLIs to be installed; discovery performs only their documented local login or metadata checks and does not make a model request.

Discovery performs no live model API validation and does not establish that a credential is valid, permitted for a particular use, or within quota. It may inspect explicitly supported local files, including bounded Codex auth metadata, Grok OIDC metadata, Gemini OAuth metadata, OpenCode auth metadata, bounded AWS profiles, and local Vertex ADC metadata, run cody auth whoami and gh auth status and (when materializing a Copilot candidate) gh auth token, resolve a saved Hugging Face token, and run claude auth status plus a credentials-file existence check to detect a saved Claude subscription login. The Claude CLI is not used for a model request until a Pydantic AI request is made. Its adapter supports text requests only; it does not support Pydantic AI tools or structured output.

Cursor, Kiro, Tabnine, and Kimi Code adapters remain source-only and are intentionally excluded from scan() results because they have no safe, supported model bridge. In particular, their CLIs can expose hooks, integrations, or credential flows that cannot be constrained to the supported text-only request path.

Read the vendors' documentation for their authentication and use conditions: Codex CLI sign-in, Copilot CLI authentication, Claude Code authentication, Grok Build overview, Grok Build CLI reference, Sourcegraph Cody CLI, OpenCode documentation, Amazon Bedrock authentication, Google Vertex AI authentication, Z.AI documentation, Qwen Code Coding Plan, Hugging Face Hub login, Poe API keys, MiniMax API, Mistral Vibe.

Development

This repository uses uv and xonsh:

uv sync --extra dev
uv run pytest
uv run ruff check .