ai-microcore 5.0.0.dev7__tar.gz → 5.0.1__tar.gz

{ai_microcore-5.0.0.dev7 → ai_microcore-5.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-microcore
-Version: 5.0.0.dev7
+Version: 5.0.1
 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='))
@@ -314,8 +307,53 @@ Text generation using HF/Transformers model locally (example with Qwen 3 0.6B).
 #### [Other examples](https://github.com/llm-microcore/microcore/tree/main/examples)
 
 ## 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.dev7 → ai_microcore-5.0.1}/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='))
@@ -279,8 +272,53 @@ Text generation using HF/Transformers model locally (example with Qwen 3 0.6B).
 #### [Other examples](https://github.com/llm-microcore/microcore/tree/main/examples)
 
 ## 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.dev7 → ai_microcore-5.0.1}/microcore/__init__.py

@@ -79,7 +79,7 @@ def model_names() -> list[str]:
     Return a list of available model names from the default LLM client.
     """
     if env().default_client is None:
-        raise ValueError("No default LLM client supporting models list configured.")
+        raise ValueError("No default LLM client is configured.")
     return env().default_client.model_names()
 
 
@@ -231,4 +231,4 @@ __all__ = [
     # "wrappers",
 ]
 
-__version__ = "5.0.0.dev7"
+__version__ = "5.0.1"

{ai_microcore-5.0.0.dev7 → ai_microcore-5.0.1}/microcore/_llm_functions.py

@@ -267,9 +267,7 @@ def llm(
             save_cache(cache_name, response)
     [h(response) for h in env().llm_after_handlers]
     if tries > 0:
-        retry_params = dict(**kwargs)
-        retry_params["retries"] = tries - 1
-        setattr(response, "_retry_callback", lambda: llm(prompt, **retry_params))
+        setattr(response, "_retry_callback", lambda: llm(prompt, retries=tries - 1, **kwargs))
     if parse_json:
         parsing_params = parse_json if isinstance(parse_json, dict) else {}
         return response.parse_json(**parsing_params)
@@ -294,6 +292,13 @@ async def allm(
         parse_json (bool|dict):
             If True, parses response as JSON,
             alternatively non-empty dict can be used as parse_json arguments.
+            Default is False (no parsing).
+        file_cache (bool | str):
+            If True or non-empty string, enables file caching of LLM responses.
+            If string, it will be used as cache prefix.
+            When enabled, identical requests with identical parameters
+            will return cached responses instead of making new API calls.
+            Default is False (no caching).
         **kwargs: Parameters supported by the LLM API.
 
             See parameters supported by the OpenAI:
@@ -374,8 +379,13 @@ async def allm(
                 if file_cache:
                     delete_cache(cache_name)
                 return await allm(
-                    prompt, retries=tries - 1, parse_json=parse_json, **kwargs
+                    prompt,
+                    retries=tries - 1,
+                    parse_json=parse_json,
+                    file_cache=file_cache,
+                    **kwargs
                 )
+            raise e
     return response
 
 

{ai_microcore-5.0.0.dev7 → ai_microcore-5.0.1}/microcore/ai_func/__init__.py

@@ -80,7 +80,7 @@ def func_metadata(func, name=None) -> Dict[str, Any]:
 
     # Add descriptions from parsed docstring to parameters
     for param in parsed_docstring.params:
-        if param.arg_name in metadata.get("args", []):
+        if param.arg_name in metadata.get("args", {}):
             metadata["args"][param.arg_name]["docstr"] = param.description
 
     return metadata
@@ -190,6 +190,7 @@ def extract_tag_tool_params(
     if len(tags) > 1:
         if raise_errors:
             raise ValueError("Response contains multiple tags when only one expected")
+        logging.warning("Response contains multiple tags, but only the first one will be used.")
     tag, attrs, content = tags[0]
     return tag, [content], attrs
 

{ai_microcore-5.0.0.dev7 → ai_microcore-5.0.1}/microcore/file_storage.py

@@ -1,5 +1,15 @@
 """
-File storage functions
+File storage functionality.
+
+
+Provides a Storage class for file operations within a configured storage directory.
+Supports automatic file numbering, backups, JSON serialization, encoding detection,
+file copying, directory listing, etc.
+
+Usage:
+    from microcore import storage
+    storage.write("data.txt", "content")
+    content = storage.read("data.txt")
 """
 
 import fnmatch
@@ -15,6 +25,7 @@ from ._env import config
 from .utils import file_link, list_files
 
 _missing = object()
+"""Sentinel value to distinguish between None and 'not provided'."""
 
 
 @dataclass
@@ -224,8 +235,6 @@ class Storage:
         if isinstance(content, bytes):
             if encoding is not None:
                 logging.warning("Encoding is ignored when writing bytes content")
-            if append:
-                raise ValueError("Cannot append bytes content")
 
         if rewrite_existing is None:
             rewrite_existing = True
@@ -268,18 +277,12 @@ class Storage:
                 if file_name != fn_incremented:
                     os.rename(self.path / file_name, self.path / fn_incremented)
         (self.path / file_name).parent.mkdir(parents=True, exist_ok=True)
-        if append:
-            with (self.path / file_name).open(
-                mode="a",
-                encoding=encoding if not isinstance(content, bytes) else None,
-            ) as file:
-                file.write(content)
+        if isinstance(content, bytes):
+            with (self.path / file_name).open(mode="ab" if append else "wb") as f:
+                f.write(content)
         else:
-            if isinstance(content, bytes):
-                with (self.path / file_name).open(mode="wb") as file:
-                    file.write(content)
-            else:
-                (self.path / file_name).write_text(content, encoding=encoding)
+            with (self.path / file_name).open(mode="a" if append else "w", encoding=encoding) as f:
+                f.write(content)
         return file_name
 
     def clean(self, path: str | Path):

{ai_microcore-5.0.0.dev7 → ai_microcore-5.0.1}/microcore/images.py

@@ -87,7 +87,7 @@ class FileImage(ImageInterface):
 
 
 class FileImageList(ImageListInterface):
-    files: list[str] | None
+    files: list[str] | None = None
 
     def images(self) -> list[FileImage]:
         if not self.files:

{ai_microcore-5.0.0.dev7 → ai_microcore-5.0.1}/microcore/llm/google_genai.py

@@ -163,8 +163,9 @@ class AsyncGoogleClient(BaseAsyncAIClient):
     def __init__(self, client: GoogleClient):
         self.sync_client = client
 
-    async def load_models(self) -> dict:
-        raise NotImplementedError
+    async def load_models(self, **kwargs) -> dict:
+        models = await self.sync_client.genai_client.aio.models.list(**kwargs)
+        return {model.name: model for model in models}
 
     async def generate(
         self,
@@ -221,6 +222,7 @@ 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)
         return _GenerationContext(
             model_name=model_name,
             save=kwargs.pop("save", True),
@@ -230,7 +232,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.dev7 → ai_microcore-5.0.1}/microcore/llm/openai.py

@@ -1,11 +1,12 @@
 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
@@ -42,8 +43,7 @@ class AsyncOpenAIClient(BaseAsyncAIClient):
         config = self.sync_client.config
         args, options = _prepare_llm_arguments(config, kwargs)
         if is_image_model(args["model"]):
-            # Note: image generation is synchronous
-            return _generate_image(
+            return await _generate_image_async(
                 prompt,
                 args,
                 self.oai_client,
@@ -133,6 +133,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}
@@ -294,12 +306,8 @@ def _oai_image_response_to_images(response: ImagesResponse) -> list[Image]:
     return images
 
 
-def _generate_image(
-    prompt,
-    args,
-    connection: openai.OpenAI | openai.AsyncOpenAI,
-    options
-) -> ImageGenerationResponse | None:
+def _prepare_image_generation(prompt, args):
+    """Prepare prompt and images for image generation (shared logic)."""
     def convert_input_image(image: ImageInterface):
         if isinstance(image, FileImage):
             return open(image.file, "rb")
@@ -333,6 +341,32 @@ def _generate_image(
     if save and args.get("response_format", "b64_json") != "b64_json":
         raise ValueError("Only 'b64_json' response format is supported.")
 
+    return prompt, images, save
+
+
+def _image_generation_response(
+        response: ImagesResponse,
+        save: bool,
+        options: dict,
+) -> ImageGenerationResponse | None:
+    check_for_errors(response)
+    images = _oai_image_response_to_images(response)
+    response_attrs = response.__dict__.copy()
+    result = make_image_generation_response(images, save, response_attrs)
+    for cb in options["callbacks"]:
+        cb(result)
+    return result
+
+
+def _generate_image(
+    prompt,
+    args,
+    connection: openai.OpenAI,
+    options
+) -> ImageGenerationResponse | None:
+    """Synchronous version of image generation."""
+    prompt, images, save = _prepare_image_generation(prompt, args)
+
     if not images:
         response: ImagesResponse = connection.images.generate(prompt=prompt, **args)
     else:
@@ -341,10 +375,24 @@ def _generate_image(
             prompt=prompt,
             **args
         )
-    check_for_errors(response)
-    images = _oai_image_response_to_images(response)
-    response_attrs = response.__dict__.copy()
-    result = make_image_generation_response(images, save, response_attrs)
-    for cb in options["callbacks"]:
-        cb(result)
-    return result
+    return _image_generation_response(response, save, options)
+
+
+async def _generate_image_async(
+    prompt,
+    args,
+    connection: openai.AsyncOpenAI,
+    options
+) -> ImageGenerationResponse | None:
+    """Asynchronous version of image generation."""
+    prompt, images, save = _prepare_image_generation(prompt, args)
+
+    if not images:
+        response: ImagesResponse = await connection.images.generate(prompt=prompt, **args)
+    else:
+        response: ImagesResponse = await connection.images.edit(
+            image=images,
+            prompt=prompt,
+            **args
+        )
+    return _image_generation_response(response, save, options)