Merge update at 1.30 (PR:lfnovo#75)

Author: leejangthegreat

CHANGELOG.md

@@ -5,6 +5,91 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- **Proxy Configuration** - Simplified proxy handling by delegating entirely to httpx
+  - Esperanto now uses standard environment variables: `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`
+  - **BREAKING**: Removed `ESPERANTO_PROXY` environment variable support
+  - **BREAKING**: Removed `config={"proxy": "..."}` parameter support
+  - Migration: Replace `ESPERANTO_PROXY` with `HTTP_PROXY` and `HTTPS_PROXY`
+
+## [2.17.2] - 2026-01-24
+
+### Fixed
+
+- **LangChain Connection Error from Garbage Collection** - Fixed "Connection error" when using `to_langchain()` (#73)
+  - When Esperanto model was garbage collected, shared httpx clients were closed, breaking LangChain
+  - Now creates fresh httpx clients for LangChain with same configuration (timeout, SSL, proxy)
+  - Affected providers: OpenAI, Groq, Perplexity, OpenAI-compatible, Azure
+  - Fixes: lfnovo/open-notebook#460
+
+## [2.17.1] - 2026-01-24
+
+### Fixed
+
+- **Config Dict API Key Not Unpacked** - Fixed providers ignoring `api_key` passed via config dict (#68)
+  - Affected providers: OpenRouter, DeepSeek, xAI (LLM), Groq (STT)
+  - These providers inherit from OpenAI-compatible parent classes and were checking for `api_key` before the config dict was unpacked
+  - Now correctly extracts `api_key` and `base_url` from config dict before setting provider defaults
+  - Example that now works:
+    ```python
+    model = AIFactory.create_language(
+        "openrouter",
+        "anthropic/claude-3.5-sonnet",
+        config={"api_key": "sk-or-v1-xxxxx"}
+    )
+    ```
+
+## [2.17.0] - 2026-01-23
+
+### Added
+
+- **Unified Tool Calling** - Added tool/function calling support across all LLM providers (#67)
+  - Define tools once using `Tool` and `ToolFunction` types, use with any provider
+  - Consistent interface: `chat_complete(messages, tools=tools)`
+  - Support for `tool_choice` parameter: `"auto"`, `"required"`, `"none"`, or specific tool
+  - Support for `parallel_tool_calls` parameter
+  - Multi-turn conversations with tool results (`role="tool"` messages)
+  - Tool call validation with `validate_tool_calls=True` parameter
+  - New types: `Tool`, `ToolFunction`, `ToolCall`, `FunctionCall`, `ToolCallValidationError`
+  - Validation utilities: `validate_tool_call()`, `validate_tool_calls()`, `find_tool_by_name()`
+  - Tested providers: OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek, xAI, OpenRouter, Azure, Ollama
+  - Full documentation at `docs/features/tool-calling.md`
+  - Examples at `examples/tool_calling/`
+
+- **Real Integration Tests for Tool Calling** - Added tests that call actual APIs (#71)
+  - Validates tool calling works correctly across 10 providers
+  - Tests both basic tool calls and multi-turn conversations
+  - Perplexity skipped (doesn't support tool calling)
+
+### Fixed
+
+- **Streaming Validation Warning** - Added warning when `validate_tool_calls=True` is used with streaming (#71)
+  - Tool call validation requires the complete response
+  - Now emits `UserWarning` instead of silently ignoring the parameter
+  - Affects all providers consistently
+
+### Changed
+
+- Moved mocked tool calling tests from `tests/integration/` to `tests/unit/`
+
+## [2.16.0] - 2026-01-21
+
+### Added
+
+- **Ollama Context Window Configuration** - Added `num_ctx` support for Ollama provider
+  - Default context window increased to 128,000 tokens (Ollama's default of 2,048 was causing context truncation)
+  - Configurable via `config={"num_ctx": 32768}`
+  - Passed to LangChain's ChatOllama via `to_langchain()`
+
+- **Ollama Keep Alive Configuration** - Added `keep_alive` support for Ollama provider
+  - Controls how long models stay loaded in memory
+  - No default set (doesn't force memory usage on users)
+  - Examples: `"5m"` (5 minutes), `"0"` (unload immediately), `"-1"` (keep indefinitely)
+  - Configurable via `config={"keep_alive": "10m"}`
+
 ## [2.15.0] - 2026-01-16
 
 ### Added

CLAUDE.md

@@ -148,11 +148,44 @@ Factory imports providers dynamically via `_import_provider_class()`:
 All providers convert API responses to Esperanto's common types:
 
 - Language: `ChatCompletion` / `ChatCompletionChunk`
+- Language (tools): `Tool`, `ToolFunction`, `ToolCall`, `FunctionCall`
 - Embedding: `List[List[float]]`
 - Reranker: `RerankResponse`
 - STT: `TranscriptionResponse`
 - TTS: `AudioResponse`
 
+### Tool Calling
+
+Esperanto provides unified tool/function calling across all LLM providers:
+
+```python
+from esperanto import AIFactory
+from esperanto.common_types import Tool, ToolFunction
+
+# Define tools once - works with any provider
+tools = [
+    Tool(
+        type="function",
+        function=ToolFunction(
+            name="get_weather",
+            description="Get weather for a city",
+            parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
+        )
+    )
+]
+
+# Use with any provider - identical code
+model = AIFactory.create_language("openai", "gpt-4o")  # or "anthropic", "google", etc.
+response = model.chat_complete(messages, tools=tools)
+
+# Tool calls in response
+if response.choices[0].message.tool_calls:
+    for tc in response.choices[0].message.tool_calls:
+        print(f"{tc.function.name}: {tc.function.arguments}")
+```
+
+See [docs/features/tool-calling.md](docs/features/tool-calling.md) for full documentation.
+
 ### Providers ↔ Utils
 
 All providers use utility mixins:

docs/capabilities/llm.md

@@ -189,6 +189,7 @@ response = model.chat_complete(messages)
 
 ## Advanced Topics
 
+- **Tool/Function Calling**: [docs/features/tool-calling.md](../features/tool-calling.md) - Let models call functions
 - **Timeout Configuration**: [docs/advanced/timeout-configuration.md](../advanced/timeout-configuration.md)
 - **LangChain Integration**: [docs/advanced/langchain-integration.md](../advanced/langchain-integration.md)
 - **Model Discovery**: [docs/advanced/model-discovery.md](../advanced/model-discovery.md)
@@ -305,9 +306,47 @@ if msg.thinking:
     print(f"Model's reasoning: {msg.thinking}")
 ```
 
+### Tool Calling
+
+```python
+from esperanto import AIFactory
+from esperanto.common_types import Tool, ToolFunction
+
+# Define a tool
+tools = [
+    Tool(
+        type="function",
+        function=ToolFunction(
+            name="get_weather",
+            description="Get weather for a location",
+            parameters={
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"]
+            }
+        )
+    )
+]
+
+# Use tools with any provider
+model = AIFactory.create_language("openai", "gpt-4o")
+response = model.chat_complete(
+    [{"role": "user", "content": "What's the weather in Tokyo?"}],
+    tools=tools
+)
+
+# Check for tool calls
+if response.choices[0].message.tool_calls:
+    for tc in response.choices[0].message.tool_calls:
+        print(f"Tool: {tc.function.name}, Args: {tc.function.arguments}")
+```
+
+See [Tool Calling Guide](../features/tool-calling.md) for complete documentation.
+
 ## See Also
 
 - [Provider Setup Guides](../providers/README.md)
+- [Tool Calling](../features/tool-calling.md)
 - [Embedding Models](./embedding.md)
 - [Speech-to-Text](./speech-to-text.md)
 - [Text-to-Speech](./text-to-speech.md)

docs/configuration.md

@@ -418,51 +418,48 @@ All provider types that use HTTP clients:
 
 ## Proxy Configuration
 
-Configure HTTP proxy for all provider connections. Useful for corporate networks, VPNs, or routing traffic through specific endpoints.
+Esperanto uses the standard HTTP proxy environment variables supported by most tools and libraries. Proxy configuration is handled automatically by the underlying httpx library.
 
-### Setting a Proxy
-
-**Via environment variable (recommended):**
+### Environment Variables
 
 ```bash
-ESPERANTO_PROXY=http://proxy.example.com:8080
-```
+# HTTP proxy (for http:// requests)
+HTTP_PROXY=http://proxy.example.com:8080
+http_proxy=http://proxy.example.com:8080
 
-**Via config parameter:**
+# HTTPS proxy (for https:// requests)
+HTTPS_PROXY=http://proxy.example.com:8080
+https_proxy=http://proxy.example.com:8080
 
-```python
-model = AIFactory.create_language(
-    "openai", "gpt-4",
-    config={"proxy": "http://proxy.example.com:8080"}
-)
+# Hosts to bypass proxy (comma-separated)
+NO_PROXY=localhost,127.0.0.1,.internal.com
+no_proxy=localhost,127.0.0.1,.internal.com
 ```
 
+Both uppercase and lowercase versions are supported.
+
 ### Proxy URL Formats
 
 ```bash
 # HTTP proxy
-ESPERANTO_PROXY=http://proxy.example.com:8080
+HTTP_PROXY=http://proxy.example.com:8080
 
-# HTTPS proxy
-ESPERANTO_PROXY=https://secure-proxy.example.com:443
+# HTTPS proxy (note: proxy URL is usually http://, not https://)
+HTTPS_PROXY=http://proxy.example.com:8080
 
 # Proxy with authentication
-ESPERANTO_PROXY=http://username:password@proxy.example.com:8080
+HTTP_PROXY=http://username:password@proxy.example.com:8080
 ```
 
-### Priority Order
-
-1. **Config parameter** `proxy` (highest priority)
-2. **Environment variable** `ESPERANTO_PROXY`
-3. **Default** `None` (no proxy)
-
 ### Common Use Cases
 
 **Corporate network with proxy:**
 
 ```bash
 # In .env
-ESPERANTO_PROXY=http://corporate-proxy.internal:3128
+HTTP_PROXY=http://corporate-proxy.internal:3128
+HTTPS_PROXY=http://corporate-proxy.internal:3128
+NO_PROXY=localhost,127.0.0.1,.internal.com
 ```
 
 ```python
@@ -471,17 +468,21 @@ model = AIFactory.create_language("openai", "gpt-4")
 embedder = AIFactory.create_embedding("openai", "text-embedding-3-small")
 ```
 
-**Different proxy per instance:**
+**Bypass proxy for local services:**
+
+```bash
+# In .env
+HTTP_PROXY=http://proxy.example.com:8080
+HTTPS_PROXY=http://proxy.example.com:8080
+NO_PROXY=localhost,127.0.0.1,ollama.local
+```
 
 ```python
-# Use specific proxy for this instance
-model = AIFactory.create_language(
-    "openai", "gpt-4",
-    config={"proxy": "http://special-proxy.example.com:8080"}
-)
+# External APIs go through proxy
+model = AIFactory.create_language("openai", "gpt-4")
 
-# Another instance without proxy (if ESPERANTO_PROXY is not set)
-model_no_proxy = AIFactory.create_language("ollama", "llama3")
+# Local Ollama bypasses proxy (if in NO_PROXY)
+local_model = AIFactory.create_language("ollama", "llama3")
 ```
 
 ### Proxy Configuration Applies To