v0.4.3 - Package Version Alignment & PyPI Distribution

What's Changed in v0.4.3

📦 Package & Distribution Patch

• Version Alignment: Bumped project and package version to 0.4.3 across pyproject.toml, src/nexusai_client/__init__.py, and uv.lock.
• PyPI Distribution: Synchronized distribution metadata and published wheel / sdist artifacts for PyPI.
• Documentation Alignment: Synchronized package version badges and documentation references following the v0.4.2 Dynamic Model Management release.

Full Changelog: v0.4.2...v0.4.3

v0.4.2 - Dynamic Model Management, Auto-Rotation & Smart Discovery

What's Changed in v0.4.2

🚀 Dynamic Model Management & Auto-Rotation

• Automatic failover on HTTP 404 / 400: When a provider decommissions or deprecates a model (e.g. Groq deprecating \llama-3.3-70b-versatile), NexusAI intercepts the error, marks the model as unavailable, and seamlessly rotates to the next candidate model or dynamically discovers active models.
• Smart Chat Model Discovery: Providers adhering to the OpenAI-compatible standard automatically query the /models\ endpoint when needed, intelligently filtering out non-chat models (audio transcription, guardrails, embeddings, moderation).
• Resilient Fallback on Rate Limits & Timeouts: Rate limits (429) and timeouts now trigger candidate model rotation across Gemini, Groq, Cerebras, Nvidia, Mistral, Cohere, DeepSeek, OpenRouter, and OrcaRouter before failing over.
• Updated Default Models:
  • Groq: \openai/gpt-oss-120b\ (0.33s latency)
  • Gemini Free: \gemini-3.5-flash-lite\ (0.84s latency)
  • Nvidia NIM: \meta/llama-3.1-8b-instruct\ (0.46s latency)
  • Cohere: \command-r-plus-08-2024\ (0.77s latency)
  • Full candidate fallback lists for all 10 providers.

🧪 Quality & Tests

• Added test coverage for 404 auto-rotation, dynamic /models\ discovery, and rate limit rotation across providers (40 tests passing).
• Validated health status across all 10 providers in production conditions.

Full Changelog: v0.4.1...v0.4.2

v0.4.1 - Docs & Default Model Alignment for Gemini Pro

🚀 What's Changed in v0.4.1

📚 Documentation & Model Alignment

• Gemini Pro Default Model: Aligned provider matrix and integration guides across \README.md, \README_PYPI.md, and \INTEGRATION_GUIDE.md\ with \gemini-3.1-pro-preview.
• Gemini Free Docs: Verified and finalized references to \gemini-3.5-flash-lite\ intra-provider auto-rotation cascade.

📦 Distribution

• Binary wheel and sdist packages built and attached.

Full Changelog: v0.4.0...v0.4.1

v0.4.0 - Intelligent Gemini Free Model Rotation & Optimized Model Defaults

What's Changed in v0.4.0

🔄 Intelligent Gemini Free Model Rotation & HTTP 429 Failover

• Automatic 429 Failover: When hitting rate limits or daily quota exhaustion on \gemini_free, the client automatically cascades through 11 text models (\gemini-3.5-flash-lite, \gemini-3.1-flash-lite, \gemini-3.7-flash, \gemini-3.6-flash, \gemini-3.5-flash, \gemini-2.5-flash-lite, \gemini-2.5-flash, \gemma-4-31b-it, \gemma-4-26b-a4b-it) and 7 multimodal vision models.
• Dynamic Cooldown Management: Temporarily cools down depleted models to prevent wasted HTTP calls.
• Optimized Free Default: Switched default \GEMINI_FREE_MODEL\ to \gemini-3.5-flash-lite\ (500 RPD / 15 RPM).
• Pro Tier Flagship Model: Set \GEMINI_PRO_MODEL\ default to \gemini-3.1-pro\ (\gemini-3.1-pro-preview) with automatic shorthand alias normalization.
• 100% Free Multi-Provider Fallback Gateway: Added \AIGateway.auto_fallback_free()\ for instant zero-cost multi-provider resilience (Gemini Free ➔ Groq ➔ Cerebras ➔ Nvidia NIM ➔ OrcaRouter ➔ Mistral ➔ Cohere ➔ OpenRouter).

🧪 Tests & Docs

• Added comprehensive unit tests for text model rotation, vision model rotation, and \�uto_fallback_free\ (37/37 passing).
• Added dedicated cookbooks and architectural guides in READMEs and Integration Guide.

Full Changelog: v0.3.1...v0.4.0

v0.3.1 - OrcaRouter Qwen 3.8 Multimodal Vision Support

What's Changed in v0.3.1

👁️ Multimodal Vision for OrcaRouter (Qwen 3.8 27B)

• Added Qwen 3.8 27B (qwen/qwen3.8-27b-free) support across both Text and Multimodal Vision categories via OrcaRouter.
• Configured ORCAROUTER_VISION_MODEL default and dynamic environment variable resolution (ORCAROUTER_VISION_DEFAULT_MODEL).
• Integrated orcarouter_free into automatic fallback vision routing (AIGateway.auto_fallback_vision() and AIGateway.get_configured_vision_providers()).
• Added live multi-turn tool calling demo script (test_live_tools.py).
• Added unit tests validating OrcaRouter vision analysis and provider discovery (34/34 passing).

Full Changelog: v0.3.0...v0.3.1

v0.3.0 - Universal Tool Calling & Interactive Documentation

🚀 NexusAI-Client v0.3.0 — Universal Tool Calling & Interactive Documentation

📦 PyPI Package: https://pypi.org/project/nexusai-client/0.3.0/
🌐 Interactive Documentation: https://nexus-ai-client-doc.vercel.app/
📚 Integration Guide: INTEGRATION_GUIDE.md

---

🌟 Highlights of Version 0.3.0

Version 0.3.0 introduces Universal Tool Calling / Function Calling across all 10 supported AI providers, enabling production-grade autonomous agent loops (ReAct) with zero heavy SDK dependencies, along with official integration with our interactive documentation platform.

1. 🛠️ Universal Tool Calling (Function Calling)

• Standardized Data Models: ToolCall, FunctionDefinition, ToolDefinition adhering to the OpenAI JSON schema standard.
• Multi-Turn Agent History: Support for role="tool", tool_call_id, and tool_calls in ChatMessage.
• Universal Multi-Provider Protocol Translation:
  • OpenAI-Compatible Providers (Groq, Cerebras, Mistral, DeepSeek, Nvidia NIM, OpenRouter, OrcaRouter): Native tool schema forwarding and automated tool_calls response parsing.
  • Google Gemini REST API: Automatic bi-directional translation to Gemini's functionDeclarations / toolConfig and parsing of functionCall / functionResponse.
  • Cohere V2 REST API: Native tool schema integration and parsing.
• Failover-Safe Tool Calls: AIGateway.auto_fallback() and FallbackGateway preserve all tool definitions during automatic zero-cost failovers.

2. 🌐 Interactive Documentation Platform

• Official interactive documentation is now live at https://nexus-ai-client-doc.vercel.app/.
• Added documentation badges and PyPI URL metadata.

3. 🧪 Comprehensive Test Coverage

• 6 new dedicated test suites covering all tool-calling serialization, execution, multi-turn history, and fallback scenarios.
• 32/32 tests passing (100% pass rate).

---

📦 Installation & Upgrade

# With pip
pip install --upgrade nexusai-client

# With uv (Recommended)
uv add --upgrade nexusai-client

# With poetry
poetry add nexusai-client@latest

---

💡 Quick Example: Autonomous Agent Loop

import asyncio
import json
from nexusai_client import AIGateway, ChatMessage, FunctionDefinition, ToolDefinition

weather_tool = ToolDefinition(
    function=FunctionDefinition(
        name="get_weather",
        description="Get current temperature and conditions for a given city.",
        parameters={
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. Tokyo, Paris"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["city"],
        },
    )
)

async def main():
    async with AIGateway.auto_fallback() as client:
        messages = [ChatMessage(role="user", content="What is the weather in Tokyo?")]
        response = await client.chat(messages=messages, tools=[weather_tool])

        if response.has_tool_calls:
            # 1. Append assistant tool calls
            messages.append(ChatMessage(role="assistant", content=response.text, tool_calls=response.tool_calls))

            # 2. Append tool execution result (unified role="tool")
            for call in response.tool_calls:
                print(f"🔧 Tool requested: {call.name} with {call.arguments}")
                messages.append(
                    ChatMessage(
                        role="tool",
                        name=call.name,
                        tool_call_id=call.id,
                        content=json.dumps({"temperature": 19, "condition": "Clear"}),
                    )
                )

            # 3. Get final synthesis
            final = await client.chat(messages=messages)
            print(f"🤖 Final Answer:\n{final.text}")

if __name__ == "__main__":
    asyncio.run(main())

---

🔗 Useful Links

• 📦 PyPI Package: https://pypi.org/project/nexusai-client/0.3.0/
• 🌐 Interactive Documentation: https://nexus-ai-client-doc.vercel.app/
• 🐙 GitHub Repository: https://github.com/laurentvv/NexusAI-Client
• 📖 Integration Guide & Recipes: INTEGRATION_GUIDE.md

v0.2.0 - OrcaRouter Provider & Free Qwen Models

🚀 NexusAI-Client v0.2.0 — OrcaRouter Provider & Free Qwen Models

📦 PyPI Package: https://pypi.org/project/nexusai-client/0.2.0/
📚 Documentation: INTEGRATION_GUIDE.md

---

🌟 Highlights of Version 0.2.0

Version 0.2.0 introduces full native integration with OrcaRouter, a zero-margin multi-provider gateway offering access to 100% free-tier models (-free), featuring qwen/qwen3.8-27b-free as the default model.

1. 🤖 New Provider: OrcaRouter

• Direct Access: Use instantly via AIGateway("orcarouter") or AIGateway("orcarouter_free").
• Default Model: qwen/qwen3.8-27b-free (Qwen 3.8 27B Free Tier).
• Dynamic Free-Tier Discovery: Automatic detection and filtering of models ending with -free (deepseek/deepseek-v4-flash-free, deepseek/deepseek-v4-pro-free, tencent/hy3-free, orcarouter/free) in list_models(free_only=True).

2. 🔄 Enhanced Zero-Cost Fallback Chain (auto_fallback)

• OrcaRouter joins the smart Zero-Cost-First routing pipeline.
• In case of capacity limits or rate limiting (HTTP 429), the gateway fails over seamlessly to the next available provider in the chain.

3. ⚡ Improved Streaming & Error Handling

• Enhanced asynchronous HTTP error parsing on SSE streams (stream_chat / stream_text), ensuring accurate upstream error extraction before stream consumption.

4. 🛠️ Updated CLI & Diagnostics

• Full OrcaRouter support in verify_access.py (live latency benchmarks and quota inspection).
• Catalog exploration and filtering in list_all_models.py (190+ discovered models).

---

📦 Installation & Upgrade

# With pip
pip install --upgrade nexusai-client

# With uv (Recommended)
uv add --upgrade nexusai-client

# With poetry
poetry add nexusai-client@latest

---

💡 Quick Example

import asyncio
from nexusai_client import AIGateway

async def main():
    # 1. Direct call to Qwen 3.8 27B Free via OrcaRouter
    async with AIGateway("orcarouter_free") as client:
        response = await client.generate_text("Summarize key advantages of Python 3.14 in 2 sentences.")
        print(f"[{response.provider} / {response.model}]:\n{response.text}")

    # 2. Global smart zero-cost fallback chain across all 10 providers
    async with AIGateway.auto_fallback() as client:
        response = await client.generate_text("Hello from NexusAI-Client!")
        print(f"Served by: {response.provider}")

if __name__ == "__main__":
    asyncio.run(main())

---

📊 Supported Providers Matrix (10 Total)

Provider	Identifier	Tier	Default Model
Cerebras	"cerebras"	Free (CS-3)	gpt-oss-120b
Cohere	"cohere"	Free (Trial)	command-r-plus-08-2024
DeepSeek	"deepseek"	Paid (Ultra-low cost)	deepseek-chat
Gemini Free	"gemini_free"	Free (AI Studio)	gemini-2.5-flash
Gemini Pro	"gemini_pro"	Paid (Enterprise GCP)	gemini-2.5-pro
Groq	"groq"	Free (LPU)	llama-3.3-70b-versatile
Mistral AI	"mistral"	Free (Dev)	mistral-small-latest
Nvidia NIM	"nvidia_free"	Free (1k credits)	meta/llama-3.1-8b-instruct
OpenRouter	"openrouter"	Free & Paid	openrouter/free
OrcaRouter ⭐	"orcarouter"	Free & Paid	qwen/qwen3.8-27b-free

---

🔗 Useful Links

• 📦 PyPI Package: https://pypi.org/project/nexusai-client/0.2.0/
• 🐙 GitHub Repository: https://github.com/laurentvv/NexusAI-Client
• 📖 Integration Guide & Recipes: INTEGRATION_GUIDE.md