# ScaleXI LLM

A production-ready, multi-provider LLM proxy that gives you **one unified API** for many different model providers.

- **9 Providers**: OpenAI, Anthropic (Claude), Google (Gemini), Groq, DeepSeek, Alibaba/Qwen, Grok, local **Ollama**, and **RunPod (native API)** 
- **60+ Model Configurations**: Pricing, limits, and capabilities encoded in a single model registry
- **Structured Outputs**: Pydantic schemas with intelligent fallbacks and validation
- **Vision & Files**: Image analysis, PDF/DOCX/TXT/JSON handling, and automatic vision fallbacks
- **Web Search**: Exa + SERP (Google) integration for retrieval-augmented generation (optionally restricted to a single domain)
- **Fallbacks & Reliability**: Provider-best and global-standard fallbacks, plus detailed error logging
- **LangSmith Tracing**: Optional built-in observability — set `enable_tracing=True` and every call is traced

This package is ideal when you want a **single, consistent interface** to multiple LLM vendors, with:

- Centralized configuration for models and costs
- Unified ask function (`ask_llm`) that works across providers
- Built-in support for web search, files, and images
- Optional local-only workflows via Ollama
- Optional LangSmith tracing with token/cost tracking

## Installation

```bash
pip install scalexi_llm
```

## Quick Example

```python
from scalexi_llm import LLMProxy

llm = LLMProxy()

response, execution_time, token_usage, cost = llm.ask_llm(
    model_name="chatgpt-4o-latest",
    system_prompt="You are a helpful assistant.",
    user_prompt="Explain quantum computing in simple terms."
)

print(response)
```

## Model Listing

Inspect all registered models and their metadata (provider, pricing, limits, capabilities):

```python
import json
from scalexi_llm import LLMProxy

llm = LLMProxy(verbose=0)
models = llm.list_available_models()
print(json.dumps(models, indent=2))
```

## Domain-Restricted Web Search

```python
from scalexi_llm import LLMProxy

llm = LLMProxy()

response, _, _, _ = llm.ask_llm(
    model_name="gpt-5-mini",
    user_prompt="Find the admissions requirements",
    websearch=True,
    search_tool="both",
    search_domain="binbaz.org.sa"
)
```

## LangSmith Tracing (Optional)

```python
from scalexi_llm import LLMProxy

# pip install langsmith  (+ set LANGSMITH_API_KEY in .env)
llm = LLMProxy(enable_tracing=True)

response, exec_time, token_usage, cost = llm.ask_llm(
    model_name="chatgpt-4o-latest",
    user_prompt="What is quantum computing?"
)
# Token usage, cost, provider, and model are automatically logged to LangSmith
```

## Features at a Glance

- One `LLMProxy` class for all providers
- Unified `ask_llm` API for text, files, images, and web search (with file/image fallbacks for providers like RunPod/Ollama)
- Pydantic-based structured outputs with retry and model fallbacks
- Vision fallback when a chosen model doesn't support images
- Token and cost accounting for every call
- Optional LangSmith tracing with zero-code setup (`enable_tracing=True`)
- Comprehensive test suite (`provider_test.py`, `ollama_test.py`, `combined_test.py`)
