ai-microcore 5.0.0.dev8__tar.gz → 5.1.0__tar.gz

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-microcore
-Version: 5.0.0.dev8
+Version: 5.1.0
 Summary: # Minimalistic Foundation for AI Applications
 Keywords: llm,large language models,ai,similarity search,ai search,gpt,openai,framework,adapter,anthropic,google gemini,google vertex ai
 Author-email: Vitalii Stepanenko <mail@vitaliy.in>
@@ -116,21 +116,14 @@ For the full list of available configuration options, you may also check [`micro
 
 ### Installing vendor-specific packages
 For models working not via OpenAI API, you may need to install additional packages:
-#### Anthropic Claude 3
+#### Anthropic Claude
 ```bash
 pip install anthropic
 ```
-#### Google Gemini via AI Studio
+#### Google Gemini via AI Studio or Vertex AI
 ```bash
-pip install google-generativeai
+pip install google-genai
 ```
-#### Google Gemini via Vertex AI
-```bash
-pip install vertexai
-```
-📌Additionally for working through [Vertex AI](https://cloud.google.com/vertex-ai) you need to
-[install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
-and [configure the authorization](https://cloud.google.com/sdk/docs/authorizing).
 
 #### Local language models via Hugging Face Transformers
 
@@ -207,7 +200,7 @@ ai_response = llm('What is your model name?')
 # - For chat completion models elements are treated as separate messages
 # - For completion LLMs elements are treated as text lines
 llm(['1+2', '='])
-llm('1+2=', model='gpt-4')
+llm('1+2=', model='gpt-5.2')
 
 # To specify a message role, you can use dictionary or classes
 llm(dict(role='system', content='1+2='))
@@ -313,9 +306,61 @@ Text generation using HF/Transformers model locally (example with Qwen 3 0.6B).
  
 #### [Other examples](https://github.com/llm-microcore/microcore/tree/main/examples)
 
+## 📚 Guides & Reference<a id="-guides--reference"></a>
+
+For more detailed information, check out these articles:
+
+- [Custom HTTP Headers](https://github.com/Nayjest/ai-microcore/blob/main/doc/features/http_headers.md)
+- [File Cache](https://github.com/Nayjest/ai-microcore/blob/main/doc/features/file_cache.md)
+
 ## Python functions as AI tools
+*Usage Example*:
+```python
+from microcore.ai_func import ai_func
+
+@ai_func
+def search_products(
+    query: str,
+    category: str = "all",
+    max_results: int = 10,
+    in_stock_only: bool = False
+):
+    """
+    Search for products in the catalog.
+
+    Args:
+        query: Search terms to find matching products
+        category: Product category to filter by (e.g., "electronics", "clothing")
+        max_results: Maximum number of results to return
+        in_stock_only: If True, only return products currently in stock
+
+    Returns:
+        List of matching products with name, price, and availability
+    """
+    # Implementation would go here
+    pass
+```
+*Output*:
+```
+# Search for products in the catalog.
+
+Args:
+    query: Search terms to find matching products
+    category: Product category to filter by (e.g., "electronics", "clothing")
+    max_results: Maximum number of results to return
+    in_stock_only: If True, only return products currently in stock
+
+Returns:
+    List of matching products with name, price, and availability
+{
+  "call": "search_products",
+  "query": <str>,
+  "category": <str> (default = "all"),
+  "max_results": <int> (default = 10),
+  "in_stock_only": <bool> (default = False)
+}
 
-@TODO
+```
 
 ## 🤖 AI Modules
 **This is an experimental feature.**

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/README.md

@@ -81,21 +81,14 @@ For the full list of available configuration options, you may also check [`micro
 
 ### Installing vendor-specific packages
 For models working not via OpenAI API, you may need to install additional packages:
-#### Anthropic Claude 3
+#### Anthropic Claude
 ```bash
 pip install anthropic
 ```
-#### Google Gemini via AI Studio
+#### Google Gemini via AI Studio or Vertex AI
 ```bash
-pip install google-generativeai
+pip install google-genai
 ```
-#### Google Gemini via Vertex AI
-```bash
-pip install vertexai
-```
-📌Additionally for working through [Vertex AI](https://cloud.google.com/vertex-ai) you need to
-[install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
-and [configure the authorization](https://cloud.google.com/sdk/docs/authorizing).
 
 #### Local language models via Hugging Face Transformers
 
@@ -172,7 +165,7 @@ ai_response = llm('What is your model name?')
 # - For chat completion models elements are treated as separate messages
 # - For completion LLMs elements are treated as text lines
 llm(['1+2', '='])
-llm('1+2=', model='gpt-4')
+llm('1+2=', model='gpt-5.2')
 
 # To specify a message role, you can use dictionary or classes
 llm(dict(role='system', content='1+2='))
@@ -278,9 +271,61 @@ Text generation using HF/Transformers model locally (example with Qwen 3 0.6B).
  
 #### [Other examples](https://github.com/llm-microcore/microcore/tree/main/examples)
 
+## 📚 Guides & Reference<a id="-guides--reference"></a>
+
+For more detailed information, check out these articles:
+
+- [Custom HTTP Headers](https://github.com/Nayjest/ai-microcore/blob/main/doc/features/http_headers.md)
+- [File Cache](https://github.com/Nayjest/ai-microcore/blob/main/doc/features/file_cache.md)
+
 ## Python functions as AI tools
+*Usage Example*:
+```python
+from microcore.ai_func import ai_func
+
+@ai_func
+def search_products(
+    query: str,
+    category: str = "all",
+    max_results: int = 10,
+    in_stock_only: bool = False
+):
+    """
+    Search for products in the catalog.
+
+    Args:
+        query: Search terms to find matching products
+        category: Product category to filter by (e.g., "electronics", "clothing")
+        max_results: Maximum number of results to return
+        in_stock_only: If True, only return products currently in stock
+
+    Returns:
+        List of matching products with name, price, and availability
+    """
+    # Implementation would go here
+    pass
+```
+*Output*:
+```
+# Search for products in the catalog.
+
+Args:
+    query: Search terms to find matching products
+    category: Product category to filter by (e.g., "electronics", "clothing")
+    max_results: Maximum number of results to return
+    in_stock_only: If True, only return products currently in stock
+
+Returns:
+    List of matching products with name, price, and availability
+{
+  "call": "search_products",
+  "query": <str>,
+  "category": <str> (default = "all"),
+  "max_results": <int> (default = 10),
+  "in_stock_only": <bool> (default = False)
+}
 
-@TODO
+```
 
 ## 🤖 AI Modules
 **This is an experimental feature.**

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/microcore/__init__.py

@@ -231,4 +231,4 @@ __all__ = [
     # "wrappers",
 ]
 
-__version__ = "5.0.0dev8"
+__version__ = "5.1.0"

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/microcore/configuration.py

@@ -150,18 +150,6 @@ class _AnthropicEnvVars:
     ANTHROPIC_API_KEY: str = from_env()
 
 
-@dataclass
-class _GoogleVertexAiEnvVars:
-    """@deprecated, use _GoogleGenAiEnvVars instead"""
-    GOOGLE_VERTEX_ACCESS_TOKEN: str = from_env()
-    GOOGLE_VERTEX_PROJECT_ID: str = from_env()
-    GOOGLE_VERTEX_LOCATION: str = from_env()
-    GOOGLE_VERTEX_GCLOUD_AUTH: bool = from_env(dtype=bool)
-
-    GOOGLE_VERTEX_RESPONSE_VALIDATION: bool = from_env(dtype=bool, default=False)
-    GOOGLE_GEMINI_SAFETY_SETTINGS: dict = from_env(dtype=dict)
-
-
 @dataclass
 class _GoogleGenAiEnvVars:
     # see https://docs.cloud.google.com/docs/authentication/application-default-credentials
@@ -216,6 +204,9 @@ class LLMConfig(
     i. e. temperature, max_tokens, etc.
     """
 
+    HTTP_HEADERS: dict = from_env(dtype=dict)
+    """Additional HTTP headers to add to LLM API requests"""
+
     AZURE_DEPLOYMENT_ID: str = from_env()
 
     INFERENCE_FUNC: Union[Callable, str] = from_env()
@@ -344,6 +335,8 @@ class LLMConfig(
         self._resolve_model()
 
     def _validate_local_llm(self):
+        if self.HTTP_HEADERS:
+            logging.warning("HTTP_HEADERS will be ignored for local models")
         if self.CHAT_MODE is None:
             logging.warning(
                 "When using local models, "

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/microcore/llm/anthropic.py

@@ -96,16 +96,18 @@ def _extract_sys_msg(prepared_messages: list[dict]) -> tuple[str, list[dict]]:
 
 
 def make_llm_functions(config: Config) -> tuple[LLMFunctionType, LLMAsyncFunctionType]:
-    sync_client = anthropic.Anthropic(
-        api_key=config.LLM_API_KEY,
-        base_url=config.LLM_API_BASE,
+    client_params = {
+        "api_key": config.LLM_API_KEY,
+        "base_url": config.LLM_API_BASE,
         **config.INIT_PARAMS,
-    )
-    async_client = anthropic.AsyncAnthropic(
-        api_key=config.LLM_API_KEY,
-        base_url=config.LLM_API_BASE,
-        **config.INIT_PARAMS,
-    )
+    }
+    if config.HTTP_HEADERS:
+        if "default_headers" not in client_params:
+            client_params["default_headers"] = {}
+        client_params["default_headers"].update(config.HTTP_HEADERS)
+
+    sync_client = anthropic.Anthropic(**client_params)
+    async_client = anthropic.AsyncAnthropic(**client_params)
 
     async def allm(prompt, **kwargs):
         args, options = _prepare_llm_arguments(config, kwargs)

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/microcore/llm/google_genai.py

@@ -1,10 +1,14 @@
+"""
+Client for Google GenAI SDK to interact with Google Gemini models.
+"""
 import asyncio
 import json
-from typing import Any, Optional
+from typing import Any, Optional, Mapping
 from dataclasses import dataclass
 
 from google import genai
 from google.genai import types
+from google.genai.types import HttpOptions
 from google.oauth2.service_account import Credentials
 
 from ..configuration import Config, LLMCredentialError
@@ -59,6 +63,22 @@ def _load_service_account_info(config: Config) -> Optional[dict]:
             )
     return None
 
+def inject_headers(headers: Mapping[str,str], params: dict) -> None:
+    """
+    Inject extra HTTP headers into the params dictionary for Google GenAI client.
+    """
+    if "http_options" not in params:
+        params["http_options"] = {}
+    http_options = params["http_options"]
+    if isinstance(http_options, dict):
+        if "headers" not in http_options:
+            http_options["headers"] = {}
+        http_options["headers"].update(headers)
+    elif isinstance(http_options, HttpOptions):
+        if http_options.headers is None:
+            http_options.headers = {}
+        http_options.headers.update(headers)
+
 
 class GoogleClient(BaseAIChatClient):
     """
@@ -71,6 +91,9 @@ class GoogleClient(BaseAIChatClient):
         super().__init__(config)
         client_params = {**config.INIT_PARAMS}
 
+        if config.HTTP_HEADERS:
+            inject_headers(config.HTTP_HEADERS, client_params)
+
         if config.GOOGLE_GENAI_USE_VERTEXAI is not None:
             client_params["vertexai"] = config.GOOGLE_GENAI_USE_VERTEXAI
 
@@ -222,6 +245,10 @@ class _GenerationContext:
         model_name = kwargs.pop("model", client.config.MODEL)
         callbacks = prepare_callbacks(client.config, kwargs, set_stream=False)
         is_image = is_image_model(model_name)
+        stream = kwargs.pop("stream", False) or (callbacks and not is_image)
+        if "extra_headers" in kwargs:  # OpenAI compatible extra headers injection
+            extra_headers = kwargs.pop("extra_headers")
+            inject_headers(extra_headers, kwargs)
         return _GenerationContext(
             model_name=model_name,
             save=kwargs.pop("save", True),
@@ -231,7 +258,7 @@ class _GenerationContext:
             genai_client=client.genai_client,
             config=client.config,
             is_image_model=is_image,
-            stream=callbacks and not is_image
+            stream=stream,
         )
 
 

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/microcore/llm/openai.py

@@ -1,11 +1,15 @@
+"""
+OpenAI LLM client implementation.
+"""
 import asyncio
 import base64
+from typing import Any
 
 import openai
 from openai.types import CompletionChoice, ImagesResponse
 
 from ..lm_client import BaseAIChatClient, BaseAsyncAIClient
-from ..message_types import TMsgContentPart
+from ..message_types import TMsgContentPart, TMsgContent
 from ..configuration import Config
 from ..llm_backends import ApiPlatform
 from .._prepare_llm_args import prepare_prompt
@@ -111,6 +115,11 @@ class OpenAIClient(BaseAIChatClient):
                 "base_url": config.LLM_API_BASE,
                 **config.INIT_PARAMS,
             }
+        if config.HTTP_HEADERS:
+            if "default_headers" not in client_params:  # maybe set in INIT_PARAMS
+                client_params["default_headers"] = {}
+            client_params["default_headers"].update(config.HTTP_HEADERS)
+
         self.oai_client = client_type(**client_params)
         self.aio = AsyncOpenAIClient(
             oai_connection=async_client_type(**client_params),
@@ -132,6 +141,18 @@ class OpenAIClient(BaseAIChatClient):
             return image_to_oai(img)
         return content_part
 
+    def _convert_message_content(self, message_content: TMsgContent) -> Any:
+        """
+        Convert the message content into a format suitable for the LLM inference chat API.
+        """
+        if isinstance(message_content, str):
+            # Prevent conversion of string content into dict(type=text, text=...)
+            # because Azure OpenAI fails with Error 400
+            # when passing "azure_search" data source like following:
+            # llm(..., extra_body={"data_sources"=[{"type": "azure_search",...}]})
+            return message_content
+        return super()._convert_message_content(message_content)
+
     def load_models(self, **kwargs) -> dict:
         models_iter = self.oai_client.models.list(**kwargs)
         return {model.id: model for model in models_iter}

{ai_microcore-5.0.0.dev8 → ai_microcore-5.1.0}/microcore/llm_backends.py

@@ -166,6 +166,7 @@ class ApiPlatform(SafeStrEnum):
         return LLM_API_BASE_URLS.get(self.api_type(), {}).get(self)
 
 
+# Human-readable labels for API platforms not following val.replace('_', ' ').title() pattern
 _API_PLATFORM_CUSTOM_LABELS: dict[ApiPlatform, str] = {
     ApiPlatform.OPENAI: "OpenAI",
     ApiPlatform.GOOGLE_AI_STUDIO: "Google AI Studio",