cross-ai-core

Multi-provider AI dispatcher with MD5-keyed response caching and unified error handling.

Supports Anthropic, xAI (Grok), OpenAI, Google Gemini, Perplexity, and Ollama (local/LAN, keyless) through a single consistent interface.

Requirements

• Python 3.10 or newer (3.11 recommended for development)
• No upper version limit — tested on 3.10–3.13

Install

Install only the provider(s) you need:

pip install "cross-ai-core[anthropic]"   # Claude
pip install "cross-ai-core[gemini]"      # Google Gemini
pip install "cross-ai-core[openai]"      # OpenAI (ChatGPT)
pip install "cross-ai-core[xai]"         # xAI Grok  (uses the OpenAI SDK)
pip install cross-ai-core                # Perplexity or Ollama (uses requests, no extra SDK)

Install all providers at once (used by cross-st, which runs multiple providers simultaneously):

pip install "cross-ai-core[all]"

Dependencies

requests is always installed — it is used for the Perplexity and Ollama providers and general HTTP.
The three provider SDKs are optional extras; pip installs only what you request.

Quick start

Calls are dispatched through agents — named (provider, model) pairs. See the cross-st Agents wiki page for the full concept; the minimal version is one JSON file at ~/.cross_ai_models.json:

{
  "version": 2,
  "agents": {
    "xai":       {"make": "xai",       "model": null},
    "anthropic": {"make": "anthropic", "model": null}
  }
}

If you also use cross-st, running st-admin --setup once will detect every API key in ~/.crossenv and seed one starter agent per provider for you. Standalone users can write the file by hand or set CROSS_AI_AGENTS_FILE=/path/to/file.json to point at an alternative.

import os
from dotenv import load_dotenv
load_dotenv(os.path.expanduser("~/.crossenv"))  # your app loads keys; the library reads os.environ

from cross_ai_core import process_prompt, get_content_auto, get_default_ai

agent  = get_default_ai()           # DEFAULT_AGENT env var, then DEFAULT_AI (legacy),
                                    # then first agent in ~/.cross_ai_models.json
result = process_prompt(
    agent,
    "Explain transformer attention in 3 sentences.",
    system="You are a concise technical writer.",   # omit to use each provider's default
    verbose=False,
    use_cache=True,
)
print(get_content_auto(result.response))            # auto-dispatches via the _make stamp

Breaking change in 0.8.0: built-in provider names are no longer auto-registered as self-agents. process_prompt("xai", …) raises ValueError: Unsupported AI model: 'xai'. No agents defined. if the registry is empty. Define at least one agent (above) before the first call.

For older callers, get_content(agent, result.response) still works (it alias-resolves the agent → provider make internally).

Configuration (environment variables)

The library only reads from os.environ — it never calls load_dotenv() itself.
Load your .env or ~/.crossenv before importing.
You only need to set API keys for the providers you actually use.

Caching

Responses are cached by MD5 hash of the request payload in ~/.cross_api_cache/.
The cache is safe to delete at any time.

# Bypass cache for one call
result = process_prompt(provider, prompt, verbose=False, use_cache=False)

# Check if a response was served from cache
if result.was_cached:
    print("from cache")

Development

cd ~/github/cross-ai-core
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"     # installs the package + pytest + pytest-mock

Run the test suite:

python -m pytest tests/ -v

Tests use mocks — no real API keys required.

Note: Keep each repo's .venv separate; do not share it with dependent projects.

Adding a provider

1. Create cross_ai_core/ai_<name>.py implementing BaseAIHandler (get_payload, get_client, get_cached_response, get_model, get_make, get_content, put_content, get_data_content, get_title, get_usage).
2. Register in cross_ai_core/ai_handler.py: add to AI_HANDLER_REGISTRY and AI_LIST.

Documentation

• API reference — all public functions, AIResponse, parallel calls, error handling
• Providers — per-provider guide: models, API keys, strengths, free tiers
• Changelog

Used by

Building something with cross-ai-core? Open a PR or issue to get listed here.

Community & support

Questions, ideas, bug reports, or just want to share what you're building?

• 💬 crossai.dev community forum — Discourse-powered discussion for cross-ai-core, cross-st, and the wider Cross family. Ask questions, share prompts, or compare provider results. Invite-only sign-up keeps it friction-free for real users; see the cross-st wiki for the one-command onboarding (st-admin --discourse-setup).
• 🐛 GitHub issues — bug reports and feature requests.
• 🎬 YouTube @crossaicore — walkthroughs and release notes.

Tagline: AI reports. Cross-examined.

License

MIT — free for personal, academic, and open-source use.
See COMMERCIAL_LICENSE.md for organizational and commercial use.