cross-ai-core 0.2.0__tar.gz

cross_ai_core-0.2.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: cross-ai-core
+Version: 0.2.0
+Summary: Multi-provider AI dispatcher with response caching and error handling.
+Author: b202i
+License: MIT
+Project-URL: Homepage, https://github.com/b202i/cross-ai-core
+Project-URL: Repository, https://github.com/b202i/cross-ai-core
+Project-URL: Bug Tracker, https://github.com/b202i/cross-ai-core/issues
+Keywords: ai,llm,anthropic,openai,gemini,xai,perplexity,multi-provider
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: google-genai>=1.65.0
+Requires-Dist: openai>=1.70.0
+Requires-Dist: requests>=2.32.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+
+# cross-ai-core
+
+Multi-provider AI dispatcher with MD5-keyed response caching and unified error handling.
+
+Supports **Anthropic**, **xAI**, **OpenAI**, **Google Gemini**, and **Perplexity** 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
+
+```bash
+pip install cross-ai-core
+```
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `anthropic` | ≥0.84.0 | Anthropic / Claude API client |
+| `google-genai` | ≥1.65.0 | Google Gemini API client |
+| `openai` | ≥1.70.0 | OpenAI and xAI (Grok) API client |
+| `requests` | ≥2.32.4 | HTTP for Perplexity API |
+
+## Quick start
+
+```python
+from dotenv import load_dotenv
+load_dotenv("~/.crossenv")          # your app loads keys; the library reads os.environ
+
+from cross_ai_core import process_prompt, get_content, get_default_ai
+
+provider = get_default_ai()         # reads DEFAULT_AI from env, falls back to "xai"
+result   = process_prompt(provider, "Explain transformer attention in 3 sentences.",
+                          verbose=False, use_cache=True)
+print(get_content(provider, result.response))
+```
+
+## Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DEFAULT_AI` | `xai` | Default provider when none is specified |
+| `XAI_API_KEY` | — | xAI / Grok API key |
+| `ANTHROPIC_API_KEY` | — | Anthropic / Claude API key |
+| `OPENAI_API_KEY` | — | OpenAI API key |
+| `GEMINI_API_KEY` | — | Google Gemini API key |
+| `PERPLEXITY_API_KEY` | — | Perplexity API key |
+| `CROSS_API_CACHE_DIR` | `~/.cross_api_cache/` | Response cache directory |
+| `CROSS_NO_CACHE` | — | Set to `1` to disable caching globally |
+
+The library only reads from `os.environ` — it never calls `load_dotenv()` itself.  
+Load your `.env` or `~/.crossenv` before importing.
+
+## Caching
+
+Responses are cached by MD5 hash of the request payload in `~/.cross_api_cache/`.  
+The cache is safe to delete at any time.
+
+```python
+# 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")
+```
+
+## 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`.
+
+## License
+
+MIT

cross_ai_core-0.2.0/README.md

@@ -0,0 +1,80 @@
+# cross-ai-core
+
+Multi-provider AI dispatcher with MD5-keyed response caching and unified error handling.
+
+Supports **Anthropic**, **xAI**, **OpenAI**, **Google Gemini**, and **Perplexity** 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
+
+```bash
+pip install cross-ai-core
+```
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `anthropic` | ≥0.84.0 | Anthropic / Claude API client |
+| `google-genai` | ≥1.65.0 | Google Gemini API client |
+| `openai` | ≥1.70.0 | OpenAI and xAI (Grok) API client |
+| `requests` | ≥2.32.4 | HTTP for Perplexity API |
+
+## Quick start
+
+```python
+from dotenv import load_dotenv
+load_dotenv("~/.crossenv")          # your app loads keys; the library reads os.environ
+
+from cross_ai_core import process_prompt, get_content, get_default_ai
+
+provider = get_default_ai()         # reads DEFAULT_AI from env, falls back to "xai"
+result   = process_prompt(provider, "Explain transformer attention in 3 sentences.",
+                          verbose=False, use_cache=True)
+print(get_content(provider, result.response))
+```
+
+## Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DEFAULT_AI` | `xai` | Default provider when none is specified |
+| `XAI_API_KEY` | — | xAI / Grok API key |
+| `ANTHROPIC_API_KEY` | — | Anthropic / Claude API key |
+| `OPENAI_API_KEY` | — | OpenAI API key |
+| `GEMINI_API_KEY` | — | Google Gemini API key |
+| `PERPLEXITY_API_KEY` | — | Perplexity API key |
+| `CROSS_API_CACHE_DIR` | `~/.cross_api_cache/` | Response cache directory |
+| `CROSS_NO_CACHE` | — | Set to `1` to disable caching globally |
+
+The library only reads from `os.environ` — it never calls `load_dotenv()` itself.  
+Load your `.env` or `~/.crossenv` before importing.
+
+## Caching
+
+Responses are cached by MD5 hash of the request payload in `~/.cross_api_cache/`.  
+The cache is safe to delete at any time.
+
+```python
+# 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")
+```
+
+## 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`.
+
+## License
+
+MIT

cross_ai_core-0.2.0/cross_ai_core/__init__.py

@@ -0,0 +1,76 @@
+"""
+cross_ai_core — Multi-provider AI dispatcher with caching and error handling.
+
+Public API
+----------
+::
+
+    from cross_ai_core import process_prompt, get_content, get_default_ai
+
+    result = process_prompt("gemini", prompt, verbose=False, use_cache=True)
+    text   = get_content("gemini", result.response)
+
+Supported providers: xai, anthropic, openai, perplexity, gemini
+
+Adding a provider
+-----------------
+1. Create ``cross_ai_core/ai_<name>.py`` implementing ``BaseAIHandler``.
+2. Register in ``cross_ai_core/ai_handler.py``: add to ``AI_HANDLER_REGISTRY``
+   and ``AI_LIST``.
+
+Cache
+-----
+Responses are cached by default in ``~/.cross_api_cache/``.
+Override with the ``CROSS_API_CACHE_DIR`` environment variable.
+Bypass per-call with ``use_cache=False``, or globally with ``CROSS_NO_CACHE=1``.
+
+Keys
+----
+The library reads API keys from ``os.environ``.  The calling application is
+responsible for loading ``.env`` or ``~/.crossenv`` before importing.
+"""
+
+from cross_ai_core.ai_handler import (   # noqa: F401
+    AI_HANDLER_REGISTRY,
+    AI_LIST,
+    AIResponse,
+    check_api_key,
+    get_ai_list,
+    get_ai_make,
+    get_ai_model,
+    get_content,
+    get_data_content,
+    get_data_title,
+    get_default_ai,
+    get_usage,
+    process_prompt,
+    put_content,
+)
+from cross_ai_core.ai_base import BaseAIHandler, _get_cache_dir  # noqa: F401
+from cross_ai_core.ai_error_handler import handle_api_error       # noqa: F401
+
+__version__ = "0.2.0"
+__all__ = [
+    # Core dispatch
+    "process_prompt",
+    "get_content",
+    "put_content",
+    "get_data_content",
+    "get_data_title",
+    "get_default_ai",
+    "get_ai_model",
+    "get_ai_make",
+    "get_ai_list",
+    "get_usage",
+    "check_api_key",
+    # Registry
+    "AI_HANDLER_REGISTRY",
+    "AI_LIST",
+    "AIResponse",
+    # Extension points
+    "BaseAIHandler",
+    "_get_cache_dir",
+    # Error handling
+    "handle_api_error",
+]
+

cross_ai_core-0.2.0/cross_ai_core/ai_anthropic.py

@@ -0,0 +1,234 @@
+import hashlib
+import json
+import os
+
+from anthropic import Anthropic
+
+from .ai_base import BaseAIHandler, _get_cache_dir
+
+AI_MAKE = "anthropic"
+AI_MODEL = "claude-opus-4-5"  # 02mar26
+MAX_TOKENS = 16000             # min 16000 required for extended thinking
+
+"""
+or direct Anthropic API:
+
+# Claude 3 Family (Legacy)
+claude-3-haiku-20240307
+claude-3-sonnet-20240229
+claude-3-opus-20240229
+
+# Claude 3.5 Family
+claude-3-5-haiku-20241022
+claude-3-5-sonnet-v2-20241022
+
+# Claude 3.7 Family
+claude-3-7-sonnet-20250219       # First hybrid reasoning model; extended thinking mode
+
+# Claude 4 Family (Current - 2025/2026)
+claude-sonnet-4-5                # Latest Sonnet; fast, highly capable, best for most tasks
+claude-opus-4-5                  # Most intelligent Claude 4 model; best for complex reasoning
+
+# Differences Between Claude Model Families
+
+Claude 4 Family (Current)
+
+claude-opus-4-5:
+  - Most intelligent model in the Claude 4 family
+  - Best for advanced reasoning, research synthesis, and complex multi-step tasks
+  - Highest capability, higher cost; ideal for wiki-style report generation
+  - Supports extended thinking for deep analytical work
+
+claude-sonnet-4-5:
+  - Balanced intelligence and speed in the Claude 4 family
+  - Best for high-throughput tasks, data processing, and content generation
+  - Faster and more cost-effective than Opus 4
+
+Claude 3.7 Family
+
+claude-3-7-sonnet-20250219:
+  - First hybrid reasoning model on the market
+  - Extended thinking capabilities for complex problem-solving and nuanced analysis
+  - Strong for strategic analysis and advanced coding tasks
+
+Claude 3.5 Family
+
+claude-3-5-sonnet-v2-20241022:
+  - Most intelligent in the 3.5 family; balances top-tier performance with speed
+claude-3-5-haiku-20241022:
+  - Fastest and most cost-effective in the 3.5 family
+
+Claude 3 Family (Legacy)
+
+Opus:   Strong on highly complex tasks like math and coding; R&D and advanced analysis
+Sonnet: Balances intelligence and speed for high-throughput tasks
+Haiku:  Near-instant responsiveness; live support, translations, content moderation
+"""
+
+
+class AnthropicHandler(BaseAIHandler):
+
+    @classmethod
+    def get_payload(cls, prompt: str):
+        return get_anthropic_payload(prompt)
+
+    @classmethod
+    def get_client(cls):
+        return get_anthropic_client()
+
+    @classmethod
+    def get_cached_response(cls, client, payload, verbose, use_cache):
+        return get_anthropic_cached_response(client, payload, verbose, use_cache)
+
+    @classmethod
+    def get_model(cls):
+        return AI_MODEL
+
+    @classmethod
+    def get_make(cls):
+        return AI_MAKE
+
+    @classmethod
+    def get_content(cls, gen_content):
+        return get_content(gen_content)
+
+    @classmethod
+    def put_content(cls, report, gen_content):
+        return put_content(report, gen_content)
+
+    @classmethod
+    def get_data_content(cls, select_data):
+        return get_data_content(select_data)
+
+    @classmethod
+    def get_title(cls, gen_content):
+        return get_title(gen_content)
+
+    @classmethod
+    def get_usage(cls, response: dict) -> dict:
+        """Extract token counts from an Anthropic-format response dict.
+        Note: extended thinking tokens are included in output_tokens."""
+        usage = response.get("usage", {})
+        inp = usage.get("input_tokens", 0)
+        out = usage.get("output_tokens", 0)
+        return {"input_tokens": inp, "output_tokens": out, "total_tokens": inp + out}
+
+
+def get_anthropic_cached_response(client, payload, verbose=False, use_cache=True):
+    if not use_cache:
+        if verbose:
+            print("Cache disabled; fetching fresh data.")
+        response = client.messages.create(**payload)
+        json_str = response.to_json()
+        json_response = json.loads(json_str)
+        return json_response, False  # Not cached
+    else:
+
+        # Convert param to a string for hashing
+        param_str = json.dumps(payload, sort_keys=True)
+        md5_hash = hashlib.md5(param_str.encode('utf-8')).hexdigest()
+
+        # Construct the cache file path
+        cache_dir = _get_cache_dir()
+        cache_file = os.path.join(cache_dir, f"{md5_hash}.json")
+
+        # Check if the response is already in cache
+        json_response = {"message": "init"}
+        if os.path.exists(cache_file):
+            if verbose:
+                print(f"api_cache: Using api_cache: {cache_file}")
+            with open(cache_file, 'r') as f:
+                return json.load(f), True  # Cached
+        else:
+            if verbose:
+                print("api_cache: cache miss, submitting API request")
+
+            # If not in cache, fetch the response
+            response = client.messages.create(**payload)
+            json_str = response.to_json()
+            json_response = None
+
+            try:
+                json_response = json.loads(json_str)
+            except ValueError as e:
+                print(f"api_cache: failed json conversion: {e}")
+
+            if json_response is None:
+                return {}
+
+            # Save to cache
+            if not os.path.exists(cache_dir):
+                os.makedirs(cache_dir)
+                if verbose:
+                    print(f"api_cache: api_cache dir created: {cache_dir}")
+
+            try:
+                with open(cache_file, 'w') as f:
+                    json.dump(json_response, f)
+            except Exception as e:
+                print(f"api_cache: An error occurred: {str(e)}")
+
+            if verbose:
+                print(f"api_cache: api_cache created: {cache_file}")
+
+            return json_response, False  # Fresh API call, not cached
+
+
+def get_anthropic_payload(prompt):
+    gen_payload = {  # Store parameters into a dictionary for calling X and saving with the output
+        "model": AI_MODEL,
+        "max_tokens": MAX_TOKENS,
+        "thinking": {                  # Extended thinking: deep reasoning mode (Claude 4 / 3.7+)
+            "type": "enabled",
+            "budget_tokens": 10000,    # Tokens reserved for internal reasoning (must be < max_tokens)
+        },
+        "system": "You are a seasoned investigative reporter, "
+                  "striving to be accurate, fair and balanced.",
+        "messages": [
+            {
+                "role": "user",
+                "content": prompt,
+            }
+        ],
+    }
+    return gen_payload
+
+
+def get_anthropic_client():
+    client = Anthropic(
+        api_key=os.getenv("ANTHROPIC_API_KEY"),
+        # base_url="https://api.x.ai",
+    )
+    return client
+
+
+def get_title(story_instance):
+    content = get_data_content(story_instance)
+    title = content.splitlines()[0]
+    return title
+
+
+def get_content(gen_response):
+    # Extended thinking returns multiple blocks; find the text block
+    for block in gen_response["content"]:
+        if block.get("type") == "text":
+            return block["text"]
+    return gen_response["content"][0]["text"]  # fallback
+
+
+def put_content(report, gen_response):
+    # Extended thinking returns multiple blocks; update the text block
+    for block in gen_response["content"]:
+        if block.get("type") == "text":
+            block["text"] = report
+            return gen_response
+    gen_response["content"][0]["text"] = report  # fallback
+    return gen_response
+
+
+def get_data_content(select_data):
+    # Extended thinking responses contain multiple blocks; find the text block
+    for block in select_data["gen_response"]["content"]:
+        if block.get("type") == "text":
+            return block["text"]
+    return select_data["gen_response"]["content"][0]["text"]  # fallback

cross_ai_core-0.2.0/cross_ai_core/ai_base.py

@@ -0,0 +1,52 @@
+"""
+ai_base.py — Abstract base class for all cross-ai-core provider handlers.
+
+Every provider (Anthropic, xAI, OpenAI, Gemini, Perplexity) inherits from
+BaseAIHandler and implements each classmethod.
+
+Cache directory
+---------------
+Provider handlers cache responses in a directory resolved by
+``_get_cache_dir()``.  The location defaults to ``~/.cross_api_cache/`` and
+can be overridden by setting ``CROSS_API_CACHE_DIR`` in the environment (or
+in ``~/.crossenv`` before importing the library):
+
+    CROSS_API_CACHE_DIR=~/my-project/cache
+"""
+
+import os
+from abc import ABC, abstractmethod
+
+
+def _get_cache_dir() -> str:
+    """
+    Return the API response cache directory path (as a string).
+
+    Resolution order:
+      1. ``CROSS_API_CACHE_DIR`` environment variable
+      2. ``~/.cross_api_cache/``  (default)
+    """
+    env_val = os.environ.get("CROSS_API_CACHE_DIR", "").strip()
+    return os.path.expanduser(env_val if env_val else "~/.cross_api_cache")
+
+
+class BaseAIHandler(ABC):  # Abstract Base Class
+
+    @classmethod
+    @abstractmethod
+    def get_payload(cls, prompt: str):
+        """Generate the payload for the given prompt."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def get_client(cls, *args, **kwargs):
+        """Return the client for making API requests."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def get_cached_response(cls, *args, **kwargs):
+        """Return the cached response function."""
+        pass
+