fj-llm 0.2.0__tar.gz

fj_llm-0.2.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: fj-llm
+Version: 0.2.0
+Summary: Lightweight, config-driven client for multiple LLM providers
+Author-email: Simon Bloch <simon.j.bloch@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# fj-llm
+
+Lightweight, config-driven Python client for multiple LLM providers. One interface, any provider — no provider SDK required.
+
+## Install
+
+```
+pip install fj-llm
+```
+
+## Providers
+
+| Provider  | Config key   | Env var              |
+|-----------|--------------|----------------------|
+| OpenAI    | `openai`     | `OPENAI_API_KEY`     |
+| Anthropic | `anthropic`  | `ANTHROPIC_API_KEY`  |
+| DeepSeek  | `deepseek`   | `DEEPSEEK_API_KEY`   |
+| Google    | `google`     | `GOOGLE_API_KEY`     |
+
+## Configuration
+
+On first use, a default config is created at `~/.config/fj_llm/config.yaml`. Edit it to add your API keys and define model aliases:
+
+```yaml
+models:
+  gpt-best:
+    provider: openai
+    model_name: gpt-4o
+    api_key_env: OPENAI_API_KEY
+    base_url: https://api.openai.com/v1
+    max_tokens: 4000
+    temperature: 0.1
+    pricing:
+      input_per_1m_tokens: 2.50
+      output_per_1m_tokens: 10.00
+    fallback: gpt-light        # optional: alias to use on quota exhaustion
+
+  gpt-light:
+    provider: openai
+    model_name: gpt-4o-mini
+    api_key_env: OPENAI_API_KEY
+    base_url: https://api.openai.com/v1
+    max_tokens: 4000
+    temperature: 0.1
+    pricing:
+      input_per_1m_tokens: 0.15
+      output_per_1m_tokens: 0.60
+
+defaults:
+  retry_attempts: 3
+  retry_delay: 1.0
+  timeout: 30
+```
+
+For Cloud Functions or other environments without filesystem access, set the `FJ_LLM_CONFIG` environment variable to a JSON string of the same structure.
+
+## Usage
+
+```python
+from fj_llm import LLMClient
+
+client = LLMClient()
+response = client.query("gpt-best", "Summarise this in one sentence.", context=long_text)
+
+if response.success:
+    print(response.content)
+    print(f"Cost: ${response.cost:.6f}")
+else:
+    print(f"Error: {response.error}")
+```
+
+### Cost logging
+
+Every successful call is appended as a JSONL record to `~/.local/share/fj_llm/costs.jsonl`. Override the path via the `FJ_LLM_COST_LOG` env var, or set `cost_log` in the config file.
+
+### CLI
+
+```
+llm-query gpt-best "What is the capital of France?"
+```
+
+## License
+
+MIT

fj_llm-0.2.0/README.md

@@ -0,0 +1,84 @@
+# fj-llm
+
+Lightweight, config-driven Python client for multiple LLM providers. One interface, any provider — no provider SDK required.
+
+## Install
+
+```
+pip install fj-llm
+```
+
+## Providers
+
+| Provider  | Config key   | Env var              |
+|-----------|--------------|----------------------|
+| OpenAI    | `openai`     | `OPENAI_API_KEY`     |
+| Anthropic | `anthropic`  | `ANTHROPIC_API_KEY`  |
+| DeepSeek  | `deepseek`   | `DEEPSEEK_API_KEY`   |
+| Google    | `google`     | `GOOGLE_API_KEY`     |
+
+## Configuration
+
+On first use, a default config is created at `~/.config/fj_llm/config.yaml`. Edit it to add your API keys and define model aliases:
+
+```yaml
+models:
+  gpt-best:
+    provider: openai
+    model_name: gpt-4o
+    api_key_env: OPENAI_API_KEY
+    base_url: https://api.openai.com/v1
+    max_tokens: 4000
+    temperature: 0.1
+    pricing:
+      input_per_1m_tokens: 2.50
+      output_per_1m_tokens: 10.00
+    fallback: gpt-light        # optional: alias to use on quota exhaustion
+
+  gpt-light:
+    provider: openai
+    model_name: gpt-4o-mini
+    api_key_env: OPENAI_API_KEY
+    base_url: https://api.openai.com/v1
+    max_tokens: 4000
+    temperature: 0.1
+    pricing:
+      input_per_1m_tokens: 0.15
+      output_per_1m_tokens: 0.60
+
+defaults:
+  retry_attempts: 3
+  retry_delay: 1.0
+  timeout: 30
+```
+
+For Cloud Functions or other environments without filesystem access, set the `FJ_LLM_CONFIG` environment variable to a JSON string of the same structure.
+
+## Usage
+
+```python
+from fj_llm import LLMClient
+
+client = LLMClient()
+response = client.query("gpt-best", "Summarise this in one sentence.", context=long_text)
+
+if response.success:
+    print(response.content)
+    print(f"Cost: ${response.cost:.6f}")
+else:
+    print(f"Error: {response.error}")
+```
+
+### Cost logging
+
+Every successful call is appended as a JSONL record to `~/.local/share/fj_llm/costs.jsonl`. Override the path via the `FJ_LLM_COST_LOG` env var, or set `cost_log` in the config file.
+
+### CLI
+
+```
+llm-query gpt-best "What is the capital of France?"
+```
+
+## License
+
+MIT

fj_llm-0.2.0/fj_llm/__init__.py

@@ -0,0 +1,9 @@
+"""
+FJ_LLM (LLM Tools) - Unified interface for multiple LLM providers
+"""
+
+from .client import LLMClient, LLMResponse
+
+__version__ = "0.2.0"
+__all__ = ["LLMClient", "LLMResponse"]
+

fj_llm-0.2.0/fj_llm/client.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+"""
+Unified LLM Client Interface
+Supports multiple LLM providers with a consistent API
+"""
+
+import json
+import logging
+import os
+import time
+import yaml
+import requests
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+_logger = logging.getLogger("fj_llm")
+
+_DEFAULT_COST_LOG = Path("~/.local/share/fj_llm/costs.jsonl").expanduser()
+
+
+class QuotaExceededError(Exception):
+    """API quota exhausted — non-retryable, triggers fallback model."""
+    pass
+
+
+@dataclass
+class LLMResponse:
+    """Standardized response format"""
+    content: str
+    model: str
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    cost: Optional[float] = None
+    success: bool = True
+    error: Optional[str] = None
+
+
+class LLMClient:
+    def __init__(self, config_path: str = "~/.config/fj_llm/config.yaml", config_dict: Optional[Dict] = None):
+        """
+        Initialize LLM Client with flexible config loading.
+        Priority: config_dict → FJ_LLM_CONFIG env var → config file
+        """
+        self.session = requests.Session()
+
+        if config_dict:
+            self.config = config_dict
+        else:
+            self.config_path = Path(config_path).expanduser()
+            self.config = self._load_config()
+
+        cost_log_env = os.getenv("FJ_LLM_COST_LOG")
+        cost_log_cfg = self.config.get("cost_log")
+        if cost_log_env:
+            self._cost_log = Path(cost_log_env)
+        elif cost_log_cfg:
+            self._cost_log = Path(cost_log_cfg).expanduser()
+        else:
+            self._cost_log = _DEFAULT_COST_LOG
+
+    def _load_config(self) -> Dict[str, Any]:
+        env_config = os.getenv("FJ_LLM_CONFIG")
+        if env_config:
+            try:
+                return json.loads(env_config)
+            except json.JSONDecodeError as e:
+                _logger.warning("Failed to parse FJ_LLM_CONFIG: %s", e)
+
+        if not self.config_path.exists():
+            self._create_default_config()
+
+        with open(self.config_path, "r") as f:
+            return yaml.safe_load(f)
+
+    def _create_default_config(self):
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        default_config = {
+            "models": {
+                "deepseek-light": {
+                    "provider": "deepseek",
+                    "model_name": "deepseek-chat",
+                    "api_key_env": "DEEPSEEK_API_KEY",
+                    "base_url": "https://api.deepseek.com/v1",
+                    "max_tokens": 4000,
+                    "temperature": 0.1,
+                    "pricing": {
+                        "input_per_1m_tokens": 0.14,
+                        "output_per_1m_tokens": 0.28,
+                    },
+                },
+                "deepseek-reasoner": {
+                    "provider": "deepseek",
+                    "model_name": "deepseek-reasoner",
+                    "api_key_env": "DEEPSEEK_API_KEY",
+                    "base_url": "https://api.deepseek.com/v1",
+                    "max_tokens": 8000,
+                    "temperature": 0.0,
+                    "pricing": {
+                        "input_per_1m_tokens": 55.0,
+                        "output_per_1m_tokens": 55.0,
+                    },
+                },
+                "claude-sonnet": {
+                    "provider": "anthropic",
+                    "model_name": "claude-sonnet-4-6",
+                    "api_key_env": "ANTHROPIC_API_KEY",
+                    "base_url": "https://api.anthropic.com/v1",
+                    "max_tokens": 4000,
+                    "temperature": 0.1,
+                    "pricing": {
+                        "input_per_1m_tokens": 3.0,
+                        "output_per_1m_tokens": 15.0,
+                    },
+                },
+            },
+            "defaults": {
+                "retry_attempts": 3,
+                "retry_delay": 1.0,
+                "timeout": 30,
+            },
+        }
+
+        with open(self.config_path, "w") as f:
+            yaml.dump(default_config, f, default_flow_style=False)
+
+        print(f"Created default config at {self.config_path}")
+        print("Please update with your API keys!")
+
+    def query(self, model_alias: str, prompt: str, context: Optional[str] = None) -> LLMResponse:
+        """Unified LLM query with automatic timing, logging, and cost tracking."""
+        t0 = time.time()
+        response = self._do_query(model_alias, prompt, context)
+        latency_ms = int((time.time() - t0) * 1000)
+
+        if response.success:
+            _logger.info(
+                "llm/%s ok — %d in + %d out tokens, $%.6f, %dms",
+                model_alias, response.input_tokens or 0, response.output_tokens or 0,
+                response.cost or 0.0, latency_ms,
+            )
+            self._append_cost_log(model_alias, response, latency_ms)
+        else:
+            _logger.error("llm/%s failed — %s", model_alias, response.error)
+
+        return response
+
+    def _append_cost_log(self, alias: str, response: "LLMResponse", latency_ms: int) -> None:
+        try:
+            self._cost_log.parent.mkdir(parents=True, exist_ok=True)
+            record = {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "alias": alias,
+                "model": response.model,
+                "input_tokens": response.input_tokens,
+                "output_tokens": response.output_tokens,
+                "cost_usd": response.cost,
+                "latency_ms": latency_ms,
+            }
+            with open(self._cost_log, "a") as f:
+                f.write(json.dumps(record) + "\n")
+        except Exception:
+            pass  # never crash the caller over logging
+
+    def _do_query(self, model_alias: str, prompt: str, context: Optional[str] = None, _is_fallback: bool = False) -> LLMResponse:
+        if model_alias not in self.config["models"]:
+            return LLMResponse(content="", model=model_alias, success=False, error=f"Unknown model alias: {model_alias}")
+
+        model_config = self.config["models"][model_alias]
+
+        full_prompt = prompt
+        if context:
+            full_prompt = f"Context:\n{context}\n\nTask:\n{prompt}"
+
+        for attempt in range(self.config["defaults"]["retry_attempts"]):
+            try:
+                provider = model_config["provider"]
+                if provider == "deepseek":
+                    response = self._query_deepseek(model_config, full_prompt)
+                elif provider == "anthropic":
+                    response = self._query_anthropic(model_config, full_prompt)
+                elif provider == "openai":
+                    response = self._query_openai(model_config, full_prompt)
+                elif provider in ("google", "gemini"):
+                    response = self._query_google(model_config, full_prompt)
+                else:
+                    return LLMResponse(content="", model=model_alias, success=False, error=f"Unsupported provider: {provider}")
+
+                if response.success:
+                    return response
+
+            except QuotaExceededError as e:
+                fallback = model_config.get("fallback")
+                if fallback and not _is_fallback:
+                    _logger.warning("llm/%s quota exceeded, falling back to %s", model_alias, fallback)
+                    return self._do_query(fallback, prompt, context, _is_fallback=True)
+                return LLMResponse(content="", model=model_alias, success=False, error=f"Quota exceeded, no fallback: {e}")
+
+            except Exception as e:
+                if attempt == self.config["defaults"]["retry_attempts"] - 1:
+                    return LLMResponse(content="", model=model_alias, success=False, error=f"Failed after {attempt + 1} attempts: {e}")
+                time.sleep(self.config["defaults"]["retry_delay"] * (2 ** attempt))
+
+        return LLMResponse(content="", model=model_alias, success=False, error="Max retries exceeded")
+
+    def _query_deepseek(self, model_config: Dict, prompt: str) -> LLMResponse:
+        api_key = os.getenv(model_config["api_key_env"])
+        if not api_key:
+            raise ValueError(f"API key not found: {model_config['api_key_env']}")
+
+        payload = {
+            "model": model_config["model_name"],
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": model_config["max_tokens"],
+            "temperature": model_config["temperature"],
+        }
+        resp = self.session.post(
+            f"{model_config['base_url']}/chat/completions",
+            json=payload,
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            timeout=self.config["defaults"]["timeout"],
+        )
+        if resp.status_code != 200:
+            raise Exception(f"API error: {resp.status_code} - {resp.text}")
+
+        data = resp.json()
+        usage = data.get("usage", {})
+        input_tokens = usage.get("prompt_tokens", 0)
+        output_tokens = usage.get("completion_tokens", 0)
+        return LLMResponse(
+            content=data["choices"][0]["message"]["content"],
+            model=model_config["model_name"],
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=usage.get("total_tokens", input_tokens + output_tokens),
+            cost=self._calculate_cost(input_tokens, output_tokens, model_config["pricing"]),
+            success=True,
+        )
+
+    def _query_openai(self, model_config: Dict, prompt: str) -> LLMResponse:
+        api_key = os.getenv(model_config["api_key_env"])
+        if not api_key:
+            raise ValueError(f"API key not found: {model_config['api_key_env']}")
+
+        model_name = model_config["model_name"]
+        payload: Dict[str, Any] = {
+            "model": model_name,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_completion_tokens": model_config["max_tokens"],
+        }
+        # o-series reasoning models don't accept temperature
+        if not (model_name[0] == "o" and model_name[1:2].isdigit()):
+            payload["temperature"] = model_config["temperature"]
+
+        resp = self.session.post(
+            f"{model_config.get('base_url', 'https://api.openai.com/v1')}/chat/completions",
+            json=payload,
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            timeout=self.config["defaults"]["timeout"],
+        )
+        if resp.status_code != 200:
+            if resp.status_code == 429:
+                try:
+                    if resp.json().get("error", {}).get("code") == "insufficient_quota":
+                        raise QuotaExceededError(f"OpenAI quota exceeded ({model_name})")
+                except (ValueError, KeyError):
+                    pass
+            raise Exception(f"API error: {resp.status_code} - {resp.text}")
+
+        data = resp.json()
+        usage = data.get("usage", {})
+        input_tokens = usage.get("prompt_tokens", 0)
+        output_tokens = usage.get("completion_tokens", 0)
+        return LLMResponse(
+            content=data["choices"][0]["message"]["content"],
+            model=model_name,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=usage.get("total_tokens", input_tokens + output_tokens),
+            cost=self._calculate_cost(input_tokens, output_tokens, model_config["pricing"]),
+            success=True,
+        )
+
+    def _query_anthropic(self, model_config: Dict, prompt: str) -> LLMResponse:
+        api_key = os.getenv(model_config["api_key_env"])
+        if not api_key:
+            raise ValueError(f"API key not found: {model_config['api_key_env']}")
+
+        resp = self.session.post(
+            f"{model_config['base_url']}/messages",
+            json={
+                "model": model_config["model_name"],
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": model_config["max_tokens"],
+                "temperature": model_config["temperature"],
+            },
+            headers={
+                "x-api-key": api_key,
+                "Content-Type": "application/json",
+                "anthropic-version": "2023-06-01",
+            },
+            timeout=self.config["defaults"]["timeout"],
+        )
+        if resp.status_code != 200:
+            if resp.status_code in (400, 429):
+                try:
+                    err = resp.json().get("error", {})
+                    if "credit balance" in err.get("message", "") or err.get("type") == "insufficient_quota":
+                        raise QuotaExceededError(f"Anthropic quota exhausted ({model_config['model_name']})")
+                except (ValueError, KeyError):
+                    pass
+            raise Exception(f"API error: {resp.status_code} - {resp.text}")
+
+        data = resp.json()
+        usage = data.get("usage", {})
+        input_tokens = usage.get("input_tokens", 0)
+        output_tokens = usage.get("output_tokens", 0)
+        return LLMResponse(
+            content=data["content"][0]["text"],
+            model=model_config["model_name"],
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=input_tokens + output_tokens,
+            cost=self._calculate_cost(input_tokens, output_tokens, model_config["pricing"]),
+            success=True,
+        )
+
+    def _query_google(self, model_config: Dict, prompt: str) -> LLMResponse:
+        api_key = os.getenv(model_config["api_key_env"])
+        if not api_key:
+            raise ValueError(f"API key not found: {model_config['api_key_env']}")
+
+        url = f"{model_config['base_url']}/models/{model_config['model_name']}:generateContent?key={api_key}"
+        resp = self.session.post(
+            url,
+            json={
+                "contents": [{"parts": [{"text": prompt}]}],
+                "generationConfig": {
+                    "maxOutputTokens": model_config["max_tokens"],
+                    "temperature": model_config["temperature"],
+                },
+            },
+            headers={"Content-Type": "application/json"},
+            timeout=self.config["defaults"]["timeout"],
+        )
+        if resp.status_code != 200:
+            raise Exception(f"API error: {resp.status_code} - {resp.text}")
+
+        data = resp.json()
+        candidates = data.get("candidates", [])
+        if not candidates:
+            raise Exception(f"No candidates in response: {data}")
+        content = candidates[0].get("content", {}).get("parts", [{}])[0].get("text", "")
+
+        usage = data.get("usageMetadata", {})
+        input_tokens = usage.get("promptTokenCount", 0)
+        output_tokens = usage.get("candidatesTokenCount", 0)
+        return LLMResponse(
+            content=content,
+            model=model_config["model_name"],
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=usage.get("totalTokenCount", input_tokens + output_tokens),
+            cost=self._calculate_cost(input_tokens, output_tokens, model_config["pricing"]),
+            success=True,
+        )
+
+    def _calculate_cost(self, input_tokens: int, output_tokens: int, pricing: Dict) -> float:
+        return (input_tokens / 1_000_000) * pricing["input_per_1m_tokens"] + \
+               (output_tokens / 1_000_000) * pricing["output_per_1m_tokens"]
+
+    def list_models(self) -> list:
+        return list(self.config["models"].keys())
+
+    def get_model_info(self, model_alias: str) -> Optional[Dict]:
+        return self.config["models"].get(model_alias)
+
+
+def main():
+    import sys
+
+    client = LLMClient()
+    if len(sys.argv) < 3:
+        print("Usage: llm-query <model_alias> <prompt>")
+        print("Available models:", ", ".join(client.list_models()))
+        sys.exit(1)
+
+    model_alias = sys.argv[1]
+    prompt = " ".join(sys.argv[2:])
+    print(f"Querying {model_alias}...")
+    response = client.query(model_alias, prompt)
+
+    if response.success:
+        print(f"\nResponse ({response.input_tokens} in + {response.output_tokens} out = {response.total_tokens} tokens, ${response.cost:.6f}):")
+        print("-" * 50)
+        print(response.content)
+    else:
+        print(f"Error: {response.error}")
+
+
+if __name__ == "__main__":
+    main()

fj_llm-0.2.0/fj_llm/ping.py

@@ -0,0 +1,112 @@
+"""
+Quick connectivity check for each supported provider.
+Uses hardcoded minimal configs so it works independently of the user's config file.
+Requires only the relevant API key env var to be set.
+"""
+
+import os
+import sys
+from typing import Optional
+from fj_llm.client import LLMClient, LLMResponse
+
+PING_PROMPT = "Reply with exactly one word: pong"
+
+_PING_CONFIGS = {
+    "openai": {
+        "models": {
+            "ping": {
+                "provider": "openai",
+                "model_name": "gpt-4o-mini",
+                "api_key_env": "OPENAI_API_KEY",
+                "base_url": "https://api.openai.com/v1",
+                "max_tokens": 10,
+                "temperature": 0.0,
+                "pricing": {"input_per_1m_tokens": 0.15, "output_per_1m_tokens": 0.60},
+            }
+        },
+        "defaults": {"retry_attempts": 1, "retry_delay": 0.0, "timeout": 15},
+    },
+    "anthropic": {
+        "models": {
+            "ping": {
+                "provider": "anthropic",
+                "model_name": "claude-haiku-4-5-20251001",
+                "api_key_env": "ANTHROPIC_API_KEY",
+                "base_url": "https://api.anthropic.com/v1",
+                "max_tokens": 10,
+                "temperature": 0.0,
+                "pricing": {"input_per_1m_tokens": 0.80, "output_per_1m_tokens": 4.00},
+            }
+        },
+        "defaults": {"retry_attempts": 1, "retry_delay": 0.0, "timeout": 15},
+    },
+    "deepseek": {
+        "models": {
+            "ping": {
+                "provider": "deepseek",
+                "model_name": "deepseek-chat",
+                "api_key_env": "DEEPSEEK_API_KEY",
+                "base_url": "https://api.deepseek.com/v1",
+                "max_tokens": 10,
+                "temperature": 0.0,
+                "pricing": {"input_per_1m_tokens": 0.14, "output_per_1m_tokens": 0.28},
+            }
+        },
+        "defaults": {"retry_attempts": 1, "retry_delay": 0.0, "timeout": 15},
+    },
+    "google": {
+        "models": {
+            "ping": {
+                "provider": "google",
+                "model_name": "gemini-2.5-flash",
+                "api_key_env": "GEMINI_API_KEY",
+                "base_url": "https://generativelanguage.googleapis.com/v1beta",
+                "max_tokens": 100,
+                "temperature": 0.0,
+                "pricing": {"input_per_1m_tokens": 0.075, "output_per_1m_tokens": 0.30},
+            }
+        },
+        "defaults": {"retry_attempts": 1, "retry_delay": 0.0, "timeout": 15},
+    },
+}
+
+SUPPORTED_PROVIDERS = list(_PING_CONFIGS.keys())
+
+
+def ping(provider: str) -> LLMResponse:
+    """Send a minimal prompt to the given provider. Raises ValueError for unknown providers."""
+    if provider not in _PING_CONFIGS:
+        raise ValueError(f"Unknown provider '{provider}'. Choose from: {', '.join(SUPPORTED_PROVIDERS)}")
+    client = LLMClient(config_dict=_PING_CONFIGS[provider])
+    return client.query("ping", PING_PROMPT)
+
+
+def main():
+    """CLI entry point: llm-ping [provider ...]"""
+    targets = sys.argv[1:] if len(sys.argv) > 1 else SUPPORTED_PROVIDERS
+
+    unknown = [t for t in targets if t not in _PING_CONFIGS]
+    if unknown:
+        print(f"Unknown provider(s): {', '.join(unknown)}")
+        print(f"Supported: {', '.join(SUPPORTED_PROVIDERS)}")
+        sys.exit(1)
+
+    results = {}
+    for provider in targets:
+        key_env = _PING_CONFIGS[provider]["models"]["ping"]["api_key_env"]
+        if not os.getenv(key_env):
+            print(f"  {provider:<12} SKIP  ({key_env} not set)")
+            results[provider] = None
+            continue
+
+        resp = ping(provider)
+        if resp.success:
+            snippet = resp.content.strip().replace("\n", " ")[:40]
+            print(f"  {provider:<12} OK    '{snippet}'  ({resp.input_tokens}in/{resp.output_tokens}out  ${resp.cost:.6f})")
+        else:
+            print(f"  {provider:<12} FAIL  {resp.error}")
+        results[provider] = resp
+
+    failed = [p for p, r in results.items() if r is not None and not r.success]
+    if failed:
+        sys.exit(1)

fj_llm-0.2.0/fj_llm.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: fj-llm
+Version: 0.2.0
+Summary: Lightweight, config-driven client for multiple LLM providers
+Author-email: Simon Bloch <simon.j.bloch@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# fj-llm
+
+Lightweight, config-driven Python client for multiple LLM providers. One interface, any provider — no provider SDK required.
+
+## Install
+
+```
+pip install fj-llm
+```
+
+## Providers
+
+| Provider  | Config key   | Env var              |
+|-----------|--------------|----------------------|
+| OpenAI    | `openai`     | `OPENAI_API_KEY`     |
+| Anthropic | `anthropic`  | `ANTHROPIC_API_KEY`  |
+| DeepSeek  | `deepseek`   | `DEEPSEEK_API_KEY`   |
+| Google    | `google`     | `GOOGLE_API_KEY`     |
+
+## Configuration
+
+On first use, a default config is created at `~/.config/fj_llm/config.yaml`. Edit it to add your API keys and define model aliases:
+
+```yaml
+models:
+  gpt-best:
+    provider: openai
+    model_name: gpt-4o
+    api_key_env: OPENAI_API_KEY
+    base_url: https://api.openai.com/v1
+    max_tokens: 4000
+    temperature: 0.1
+    pricing:
+      input_per_1m_tokens: 2.50
+      output_per_1m_tokens: 10.00
+    fallback: gpt-light        # optional: alias to use on quota exhaustion
+
+  gpt-light:
+    provider: openai
+    model_name: gpt-4o-mini
+    api_key_env: OPENAI_API_KEY
+    base_url: https://api.openai.com/v1
+    max_tokens: 4000
+    temperature: 0.1
+    pricing:
+      input_per_1m_tokens: 0.15
+      output_per_1m_tokens: 0.60
+
+defaults:
+  retry_attempts: 3
+  retry_delay: 1.0
+  timeout: 30
+```
+
+For Cloud Functions or other environments without filesystem access, set the `FJ_LLM_CONFIG` environment variable to a JSON string of the same structure.
+
+## Usage
+
+```python
+from fj_llm import LLMClient
+
+client = LLMClient()
+response = client.query("gpt-best", "Summarise this in one sentence.", context=long_text)
+
+if response.success:
+    print(response.content)
+    print(f"Cost: ${response.cost:.6f}")
+else:
+    print(f"Error: {response.error}")
+```
+
+### Cost logging
+
+Every successful call is appended as a JSONL record to `~/.local/share/fj_llm/costs.jsonl`. Override the path via the `FJ_LLM_COST_LOG` env var, or set `cost_log` in the config file.
+
+### CLI
+
+```
+llm-query gpt-best "What is the capital of France?"
+```
+
+## License
+
+MIT

fj_llm-0.2.0/fj_llm.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+fj_llm/__init__.py
+fj_llm/client.py
+fj_llm/ping.py
+fj_llm.egg-info/PKG-INFO
+fj_llm.egg-info/SOURCES.txt
+fj_llm.egg-info/dependency_links.txt
+fj_llm.egg-info/entry_points.txt
+fj_llm.egg-info/requires.txt
+fj_llm.egg-info/top_level.txt
+tests/test_client.py
+tests/test_integration.py

fj_llm-0.2.0/fj_llm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fj_llm-0.2.0/fj_llm.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+llm-ping = fj_llm.ping:main
+llm-query = fj_llm.client:main

fj_llm-0.2.0/fj_llm.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.25.0
+pyyaml>=5.4.0
+
+[dev]
+pytest>=7.0

fj_llm-0.2.0/fj_llm.egg-info/top_level.txt

@@ -0,0 +1 @@
+fj_llm

fj_llm-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fj-llm"
+version = "0.2.0"
+description = "Lightweight, config-driven client for multiple LLM providers"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Simon Bloch", email = "simon.j.bloch@gmail.com" }]
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.25.0",
+    "pyyaml>=5.4.0",
+]
+
+[project.scripts]
+llm-query = "fj_llm.client:main"
+llm-ping = "fj_llm.ping:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["fj_llm*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fj_llm-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fj_llm-0.2.0/tests/test_client.py

@@ -0,0 +1,262 @@
+"""Unit tests for fj_llm.client — all HTTP calls are mocked."""
+
+import json
+import pytest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from fj_llm import LLMClient, LLMResponse
+from fj_llm.client import QuotaExceededError
+
+MINIMAL_CONFIG = {
+    "models": {
+        "test-openai": {
+            "provider": "openai",
+            "model_name": "gpt-4o-mini",
+            "api_key_env": "OPENAI_API_KEY",
+            "base_url": "https://api.openai.com/v1",
+            "max_tokens": 100,
+            "temperature": 0.1,
+            "pricing": {"input_per_1m_tokens": 0.15, "output_per_1m_tokens": 0.60},
+        },
+        "test-anthropic": {
+            "provider": "anthropic",
+            "model_name": "claude-haiku-4-5-20251001",
+            "api_key_env": "ANTHROPIC_API_KEY",
+            "base_url": "https://api.anthropic.com/v1",
+            "max_tokens": 100,
+            "temperature": 0.1,
+            "pricing": {"input_per_1m_tokens": 0.80, "output_per_1m_tokens": 4.00},
+        },
+        "test-deepseek": {
+            "provider": "deepseek",
+            "model_name": "deepseek-chat",
+            "api_key_env": "DEEPSEEK_API_KEY",
+            "base_url": "https://api.deepseek.com/v1",
+            "max_tokens": 100,
+            "temperature": 0.1,
+            "pricing": {"input_per_1m_tokens": 0.14, "output_per_1m_tokens": 0.28},
+        },
+        "test-google": {
+            "provider": "google",
+            "model_name": "gemini-1.5-flash",
+            "api_key_env": "GOOGLE_API_KEY",
+            "base_url": "https://generativelanguage.googleapis.com/v1beta",
+            "max_tokens": 100,
+            "temperature": 0.1,
+            "pricing": {"input_per_1m_tokens": 0.075, "output_per_1m_tokens": 0.30},
+        },
+        "test-with-fallback": {
+            "provider": "openai",
+            "model_name": "gpt-4o",
+            "api_key_env": "OPENAI_API_KEY",
+            "base_url": "https://api.openai.com/v1",
+            "max_tokens": 100,
+            "temperature": 0.1,
+            "pricing": {"input_per_1m_tokens": 2.50, "output_per_1m_tokens": 10.00},
+            "fallback": "test-openai",
+        },
+    },
+    "defaults": {"retry_attempts": 2, "retry_delay": 0.0, "timeout": 10},
+}
+
+
+def make_client(**kwargs):
+    return LLMClient(config_dict=MINIMAL_CONFIG, **kwargs)
+
+
+def openai_response(content="hello", in_tok=10, out_tok=5):
+    mock = MagicMock()
+    mock.status_code = 200
+    mock.json.return_value = {
+        "choices": [{"message": {"content": content}}],
+        "usage": {"prompt_tokens": in_tok, "completion_tokens": out_tok, "total_tokens": in_tok + out_tok},
+    }
+    return mock
+
+
+def anthropic_response(content="hello", in_tok=10, out_tok=5):
+    mock = MagicMock()
+    mock.status_code = 200
+    mock.json.return_value = {
+        "content": [{"text": content}],
+        "usage": {"input_tokens": in_tok, "output_tokens": out_tok},
+    }
+    return mock
+
+
+def deepseek_response(content="hello", in_tok=10, out_tok=5):
+    return openai_response(content, in_tok, out_tok)
+
+
+def google_response(content="hello", in_tok=10, out_tok=5):
+    mock = MagicMock()
+    mock.status_code = 200
+    mock.json.return_value = {
+        "candidates": [{"content": {"parts": [{"text": content}]}}],
+        "usageMetadata": {"promptTokenCount": in_tok, "candidatesTokenCount": out_tok, "totalTokenCount": in_tok + out_tok},
+    }
+    return mock
+
+
+class TestConfigLoading:
+    def test_config_dict_used_directly(self):
+        client = make_client()
+        assert "test-openai" in client.config["models"]
+
+    def test_env_var_config(self, monkeypatch):
+        monkeypatch.setenv("FJ_LLM_CONFIG", json.dumps(MINIMAL_CONFIG))
+        client = LLMClient(config_path="/nonexistent/path.yaml")
+        assert "test-openai" in client.config["models"]
+
+    def test_unknown_model_returns_error(self):
+        client = make_client()
+        response = client.query("nonexistent", "hello")
+        assert not response.success
+        assert "Unknown model alias" in response.error
+
+
+class TestCostCalculation:
+    def test_cost_calculation(self):
+        client = make_client()
+        pricing = {"input_per_1m_tokens": 2.0, "output_per_1m_tokens": 10.0}
+        cost = client._calculate_cost(1_000_000, 500_000, pricing)
+        assert abs(cost - 7.0) < 1e-9
+
+    def test_zero_tokens(self):
+        client = make_client()
+        pricing = {"input_per_1m_tokens": 2.0, "output_per_1m_tokens": 10.0}
+        assert client._calculate_cost(0, 0, pricing) == 0.0
+
+
+class TestOpenAIProvider:
+    def test_successful_query(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+        client = make_client()
+        with patch.object(client.session, "post", return_value=openai_response("world", 20, 10)):
+            resp = client.query("test-openai", "hello")
+        assert resp.success
+        assert resp.content == "world"
+        assert resp.input_tokens == 20
+        assert resp.output_tokens == 10
+        assert resp.cost > 0
+
+    def test_quota_exceeded_raises(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+        client = make_client()
+        mock_resp = MagicMock()
+        mock_resp.status_code = 429
+        mock_resp.json.return_value = {"error": {"code": "insufficient_quota"}}
+        mock_resp.text = "quota"
+        with patch.object(client.session, "post", return_value=mock_resp):
+            resp = client.query("test-openai", "hello")
+        assert not resp.success
+        assert "Quota exceeded" in resp.error
+
+    def test_fallback_on_quota(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+        client = make_client()
+        quota_resp = MagicMock()
+        quota_resp.status_code = 429
+        quota_resp.json.return_value = {"error": {"code": "insufficient_quota"}}
+        quota_resp.text = "quota"
+        with patch.object(client.session, "post", side_effect=[quota_resp, openai_response("fallback!")]):
+            resp = client.query("test-with-fallback", "hello")
+        assert resp.success
+        assert resp.content == "fallback!"
+
+    def test_missing_api_key(self, monkeypatch):
+        monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+        client = make_client()
+        resp = client.query("test-openai", "hello")
+        assert not resp.success
+
+
+class TestAnthropicProvider:
+    def test_successful_query(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+        client = make_client()
+        with patch.object(client.session, "post", return_value=anthropic_response("claude says hi", 15, 8)):
+            resp = client.query("test-anthropic", "hello")
+        assert resp.success
+        assert resp.content == "claude says hi"
+        assert resp.total_tokens == 23
+
+    def test_quota_exceeded(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+        client = make_client()
+        mock_resp = MagicMock()
+        mock_resp.status_code = 400
+        mock_resp.json.return_value = {"error": {"message": "credit balance too low", "type": "invalid_request_error"}}
+        mock_resp.text = "credits"
+        with patch.object(client.session, "post", return_value=mock_resp):
+            resp = client.query("test-anthropic", "hello")
+        assert not resp.success
+        assert "Quota exceeded" in resp.error
+
+
+class TestDeepSeekProvider:
+    def test_successful_query(self, monkeypatch):
+        monkeypatch.setenv("DEEPSEEK_API_KEY", "test-key")
+        client = make_client()
+        with patch.object(client.session, "post", return_value=deepseek_response("deepseek reply", 12, 6)):
+            resp = client.query("test-deepseek", "hello")
+        assert resp.success
+        assert resp.content == "deepseek reply"
+
+
+class TestGoogleProvider:
+    def test_successful_query(self, monkeypatch):
+        monkeypatch.setenv("GOOGLE_API_KEY", "test-key")
+        client = make_client()
+        with patch.object(client.session, "post", return_value=google_response("gemini reply", 8, 4)):
+            resp = client.query("test-google", "hello")
+        assert resp.success
+        assert resp.content == "gemini reply"
+        assert resp.input_tokens == 8
+
+    def test_empty_candidates_raises(self, monkeypatch):
+        monkeypatch.setenv("GOOGLE_API_KEY", "test-key")
+        client = make_client()
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {"candidates": [], "usageMetadata": {}}
+        with patch.object(client.session, "post", return_value=mock_resp):
+            resp = client.query("test-google", "hello")
+        assert not resp.success
+
+
+class TestRetryBehavior:
+    def test_retries_on_transient_error(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+        client = make_client()
+        err_resp = MagicMock()
+        err_resp.status_code = 500
+        err_resp.text = "server error"
+        with patch.object(client.session, "post", side_effect=[
+            Exception("transient"), openai_response("ok")
+        ]):
+            resp = client.query("test-openai", "hello")
+        assert resp.success
+
+    def test_exhausted_retries_returns_error(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+        client = make_client()
+        with patch.object(client.session, "post", side_effect=Exception("always fails")):
+            resp = client.query("test-openai", "hello")
+        assert not resp.success
+        assert "Failed after" in resp.error
+
+
+class TestCostLog:
+    def test_cost_log_written(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+        log_path = tmp_path / "costs.jsonl"
+        monkeypatch.setenv("FJ_LLM_COST_LOG", str(log_path))
+        client = LLMClient(config_dict=MINIMAL_CONFIG)
+        with patch.object(client.session, "post", return_value=openai_response()):
+            client.query("test-openai", "hello")
+        assert log_path.exists()
+        record = json.loads(log_path.read_text().strip())
+        assert record["alias"] == "test-openai"
+        assert record["cost_usd"] > 0

fj_llm-0.2.0/tests/test_integration.py

@@ -0,0 +1,60 @@
+"""
+Integration tests — hit real APIs. Skipped automatically if the API key env var is not set.
+Run explicitly: pytest tests/test_integration.py -v
+"""
+
+import os
+import pytest
+from fj_llm.ping import ping
+
+
+def _key(provider: str) -> str:
+    keys = {
+        "openai": "OPENAI_API_KEY",
+        "anthropic": "ANTHROPIC_API_KEY",
+        "deepseek": "DEEPSEEK_API_KEY",
+        "google": "GEMINI_API_KEY",
+    }
+    return keys[provider]
+
+
+def integration(provider: str):
+    """Decorator: skip the test if the provider's API key is not set."""
+    return pytest.mark.skipif(
+        not os.getenv(_key(provider)),
+        reason=f"{_key(provider)} not set",
+    )
+
+
+@integration("openai")
+def test_ping_openai():
+    resp = ping("openai")
+    assert resp.success, resp.error
+    assert resp.content.strip()
+    assert resp.input_tokens and resp.input_tokens > 0
+    assert resp.cost and resp.cost > 0
+
+
+@integration("anthropic")
+def test_ping_anthropic():
+    resp = ping("anthropic")
+    assert resp.success, resp.error
+    assert resp.content.strip()
+    assert resp.input_tokens and resp.input_tokens > 0
+    assert resp.cost and resp.cost > 0
+
+
+@integration("deepseek")
+def test_ping_deepseek():
+    resp = ping("deepseek")
+    assert resp.success, resp.error
+    assert resp.content.strip()
+    assert resp.input_tokens and resp.input_tokens > 0
+
+
+@integration("google")
+def test_ping_google():
+    resp = ping("google")
+    assert resp.success, resp.error
+    assert resp.content.strip()
+    assert resp.input_tokens and resp.input_tokens > 0