yera 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

yera/models/llm_interfaces/azure_openai.py

@@ -0,0 +1,143 @@
+from collections.abc import Iterator
+
+from openai import AzureOpenAI
+from openai.lib._pydantic import to_strict_json_schema
+
+from yera.config2.dataclasses import LLMConfig
+from yera.config2.keyring import DevKeyring
+from yera.models.data_classes import Message
+from yera.models.llm_interfaces.base import BaseLLMInterface, TBaseModel
+
+
+class AzureOpenAILLM(BaseLLMInterface):
+    def __init__(self, config: LLMConfig, overrides, creds_map):
+        kws = {**config.inference.model_dump(), **overrides}
+        self.client = None
+        self._endpoint_path = f"providers.{creds_map['endpoint']}"
+        self._api_key_path = f"providers.{creds_map['api_key']}"
+
+        self.deployment_name = config.model_id
+
+        super().__init__(**kws)
+
+    def start(self):
+        endpoint = DevKeyring.get(self._endpoint_path)
+        api_key = DevKeyring.get(self._api_key_path)
+
+        self.client = AzureOpenAI(
+            azure_endpoint=endpoint,
+            api_key=api_key,
+            api_version="2024-10-21",  # Latest GA version
+        )
+
+    def stop(self):
+        self.client.close()
+        self.client = None
+
+    def chat(
+        self,
+        messages: list[Message],
+        **openai_kw,
+    ) -> Iterator[str]:
+        openai_messages = [
+            {"role": msg.role, "content": msg.content} for msg in messages
+        ]
+
+        stream = self.client.chat.completions.create(
+            model=self.deployment_name,
+            messages=openai_messages,
+            stream=True,
+            **openai_kw,
+        )
+
+        for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+
+    def make_struct(
+        self,
+        messages: list[Message],
+        cls: type[TBaseModel],
+        **openai_kw,
+    ) -> Iterator[str]:
+        openai_messages = [
+            {"role": msg.role, "content": msg.content} for msg in messages
+        ]
+
+        try:
+            schema = to_strict_json_schema(cls)
+            stream = self.client.chat.completions.create(
+                model=self.deployment_name,
+                messages=openai_messages,
+                response_format={
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": cls.__name__,
+                        "schema": schema,
+                        "strict": True,
+                    },
+                },
+                stream=True,
+                **openai_kw,
+            )
+
+            for chunk in stream:
+                if chunk.choices and chunk.choices[0].delta.content:
+                    yield chunk.choices[0].delta.content
+
+        except Exception as e:
+            error_msg = str(e).lower()
+
+            if any(
+                phrase in error_msg
+                for phrase in [
+                    "does not support",
+                    "not supported",
+                    "not available",
+                    "unsupported",
+                ]
+            ):
+                # Fall back to tool calling
+                yield from self._make_struct_via_tools(
+                    openai_messages, cls, **openai_kw
+                )
+            else:
+                # Re-raise other errors
+                raise
+
+    def _make_struct_via_tools(
+        self,
+        messages: list[dict],
+        cls: type[TBaseModel],
+        **openai_kw,
+    ) -> Iterator[str]:
+        schema = cls.model_json_schema()
+        schema.pop("$defs", None)
+        schema.pop("definitions", None)
+
+        tool = {
+            "type": "function",
+            "function": {
+                "name": "return_structured_data",
+                "description": "Returns structured data matching the required schema",
+                "parameters": schema,
+            },
+        }
+
+        stream = self.client.chat.completions.create(
+            model=self.deployment_name,
+            messages=messages,
+            tools=[tool],
+            tool_choice={
+                "type": "function",
+                "function": {"name": "return_structured_data"},
+            },
+            stream=True,
+            **openai_kw,
+        )
+
+        for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.tool_calls:
+                tool_call = chunk.choices[0].delta.tool_calls[0]
+                if tool_call.function and tool_call.function.arguments:
+                    yield tool_call.function.arguments

yera/models/llm_interfaces/base.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+
+from yera.dsl.struct import TBaseModel
+from yera.models.data_classes import Message
+
+
+class BaseLLMInterface(ABC):
+    def __init__(self, **kwargs):
+        self.kwargs = dict(kwargs)
+
+    @abstractmethod
+    def chat(self, messages: list[Message], **kwargs) -> Iterator[str]:
+        pass
+
+    @abstractmethod
+    def make_struct(
+        self, messages: list[Message], cls: type[TBaseModel], **kwargs
+    ) -> Iterator[str]:
+        pass
+
+    def start(self):
+        return
+
+    def stop(self):
+        return

yera/models/llm_interfaces/interface_registry.py

@@ -0,0 +1,74 @@
+from collections.abc import Callable
+from importlib.util import find_spec
+
+from yera.models.llm_interfaces.base import BaseLLMInterface
+from yera.models.llm_interfaces.mock import MockLLMInterface
+
+# Cache for loaded classes
+_loaded_cache: dict[str, type[BaseLLMInterface]] = {}
+_loaders: dict[str, Callable[[], type[BaseLLMInterface]]] = {}
+_initialized = False
+
+
+def _lazy_init():
+    """Initialize the registry on first access."""
+    global _initialized
+    if _initialized:
+        return
+
+    _initialized = True
+
+    # Define all interfaces to check
+    interfaces = [
+        (
+            "llama-cpp",
+            "yera.models.llm_interfaces.llama_cpp",
+            "LlamaCppLLM",
+            "llama_cpp",
+        ),
+        (
+            "anthropic-sdk",
+            "yera.models.llm_interfaces.anthropic",
+            "AnthropicLLM",
+            "anthropic",
+        ),
+        ("openai-sdk", "yera.models.llm_interfaces.open_ai", "OpenAILLM", "openai"),
+        (
+            "azure-sdk",
+            "yera.models.llm_interfaces.azure_openai",
+            "AzureOpenAILLM",
+            "openai",
+        ),
+        (
+            "ollama",
+            "yera.models.llm_interfaces.ollama_interface",
+            "OllamaLLM",
+            "ollama",
+        ),
+    ]
+
+    # Check availability and register loaders
+    for name, module_path, class_name, check_package in interfaces:
+        if find_spec(check_package) is not None:
+
+            def loader(mod=module_path, cls=class_name, n=name):
+                if n not in _loaded_cache:
+                    module = __import__(mod, fromlist=[cls])
+                    _loaded_cache[n] = getattr(module, cls)
+                return _loaded_cache[n]
+
+            _loaders[name] = loader
+
+    # Mock is always available
+    _loaders["Mock"] = lambda: MockLLMInterface
+
+
+def get_interface(name: str) -> type[BaseLLMInterface]:
+    """Get an interface class by name, loading it lazily."""
+    _lazy_init()  # Only runs once, on first call
+
+    if name not in _loaders:
+        raise ValueError(
+            f"Interface '{name}' not available. Available: {list(_loaders.keys())}"
+        )
+    return _loaders[name]()

yera/models/llm_interfaces/llama_cpp.py

@@ -0,0 +1,136 @@
+import json
+import os
+from collections.abc import Iterator
+from contextlib import redirect_stderr
+from functools import wraps
+from pathlib import Path
+
+from llama_cpp import Llama
+
+from yera.config2.dataclasses import LLMConfig
+from yera.config2.keyring import DevKeyring
+from yera.models.data_classes import Message
+from yera.models.llm_interfaces.base import BaseLLMInterface, TBaseModel
+
+
+def assert_started(fn):
+    @wraps(fn)
+    def wrapper(self, *args, **kwargs):
+        if self._model is None:
+            raise ValueError("Model not started. Call model.start() first.")
+        return fn(self, *args, **kwargs)
+
+    return wrapper
+
+
+class LlamaCppLLM(BaseLLMInterface):
+    def __init__(self, config: LLMConfig, overrides, creds_map):
+        # make kwargs from config and overrides
+        kws = {**config.inference.model_dump(), **overrides}
+        super().__init__(**kws)
+        self._model = None
+        models_dir = Path(DevKeyring.get("providers." + creds_map["models_dir"]))
+
+        with (models_dir / "catalogue.json").open() as f:
+            catalogue = json.load(f)
+        self.model_path = Path(catalogue[config.id])
+        if not self.model_path.exists():
+            raise FileNotFoundError(self.model_path)
+
+    def start(self):
+        if self._model:
+            raise ValueError("Model already started.")
+
+        with open(os.devnull, "w") as devnull, redirect_stderr(devnull):
+            self._model = Llama(
+                model_path=str(self.model_path),
+                n_gpu_layers=self.kwargs.get("n_gpu_layers", -1),
+                n_ctx=self.kwargs.get("context_length", 8096),
+                verbose=False,
+            )
+
+    @assert_started
+    def stop(self):
+        self._model.close()
+
+    @staticmethod
+    def _process_stream(stream):
+        stream = (x["choices"][0]["delta"] for x in stream)
+        stream = (x.get("content") for x in stream)
+        stream = (x for x in stream if x is not None)
+        return stream
+
+    @assert_started
+    def chat(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float = 0.2,
+        top_p: float = 0.95,
+        top_k: int = 40,
+        min_p: float = 0.05,
+        typical_p: float = 1.0,
+        stop: str | list[str] | None = None,
+        seed: int | None = None,
+        max_tokens: int | None = None,
+        presence_penalty: float = 0.0,
+        frequency_penalty: float = 0.0,
+        repeat_penalty: float = 1.0,
+        **llama_cpp_kw,
+    ) -> Iterator[str]:
+        stream = self._model.create_chat_completion(
+            messages,
+            temperature=temperature,
+            top_p=top_p,
+            top_k=top_k,
+            min_p=min_p,
+            typical_p=typical_p,
+            stop=stop or [],
+            seed=seed,
+            max_tokens=max_tokens,
+            presence_penalty=presence_penalty,
+            frequency_penalty=frequency_penalty,
+            repeat_penalty=repeat_penalty,
+            stream=True,
+            **llama_cpp_kw,
+        )
+        return self._process_stream(stream)
+
+    @assert_started
+    def make_struct(
+        self,
+        messages: list[Message],
+        cls: type[TBaseModel],
+        *,
+        temperature: float = 0.2,
+        top_p: float = 0.95,
+        top_k: int = 40,
+        min_p: float = 0.05,
+        typical_p: float = 1.0,
+        seed: int | None = None,
+        max_tokens: int | None = None,
+        presence_penalty: float = 0.0,
+        frequency_penalty: float = 0.0,
+        repeat_penalty: float = 1.0,
+        **llama_cpp_kw,
+    ) -> Iterator[str]:
+        stream = self._model.create_chat_completion(
+            messages=messages,
+            response_format={
+                "type": "json_object",
+                "schema": cls.model_json_schema(),
+            },
+            temperature=temperature,
+            top_p=top_p,
+            top_k=top_k,
+            min_p=min_p,
+            typical_p=typical_p,
+            seed=seed,
+            max_tokens=max_tokens,
+            presence_penalty=presence_penalty,
+            frequency_penalty=frequency_penalty,
+            repeat_penalty=repeat_penalty,
+            stream=True,
+            **llama_cpp_kw,
+        )
+        return self._process_stream(stream)

yera/models/llm_interfaces/mock.py

@@ -0,0 +1,29 @@
+from yera.models.llm_interfaces.base import BaseLLMInterface
+
+
+class MockLLMInterface(BaseLLMInterface):
+    def __init__(self, config, overrides, creds_map):
+        args = {**config.inference.model_dump(), **overrides}
+
+        self.chat_response = args["chat_response"]
+        self.struct_response = args["struct_response"]
+        self.started = False
+        self.stopped = False
+        self.chat_calls = []
+        self.struct_calls = []
+        self.creds_map = creds_map
+        super().__init__(**args)
+
+    def chat(self, messages, **kwargs):
+        self.chat_calls.append((messages.copy(), kwargs))
+        yield from self.chat_response
+
+    def make_struct(self, messages, cls, **kwargs):
+        self.struct_calls.append((messages.copy(), cls, kwargs))
+        yield from self.struct_response
+
+    def start(self):
+        self.started = True
+
+    def stop(self):
+        self.stopped = True

yera/models/llm_interfaces/ollama_interface.py

@@ -0,0 +1,118 @@
+from collections.abc import Iterator
+
+from ollama import Client, ResponseError
+
+from yera.config2.dataclasses import LLMConfig
+from yera.config2.keyring import DevKeyring
+from yera.models.data_classes import Message
+from yera.models.llm_interfaces.base import BaseLLMInterface, TBaseModel
+
+
+class OllamaLLM(BaseLLMInterface):
+    def __init__(self, config: LLMConfig, overrides, creds_map):
+        kws = {**config.inference.model_dump(), **overrides}
+        self.client = None
+        self.model_id = config.model_id
+        self.creds_map = creds_map
+        super().__init__(**kws)
+
+    def start(self):
+        base_url = DevKeyring.get(f"providers.{self.creds_map['base_url']}")
+        self.client = Client(host=base_url)
+
+        # Check if Ollama server is running
+        try:
+            self.client.list()  # Simple check to see if server responds
+        except Exception as e:
+            raise ConnectionError(
+                f"Cannot connect to Ollama server at {base_url}. "
+                f"Make sure Ollama is installed and running. "
+                f"Error: {e}"
+            ) from None
+
+    def stop(self):
+        self.client = None
+
+    def chat(
+        self,
+        messages: list[Message],
+        **ollama_kw,
+    ) -> Iterator[str]:
+        ollama_messages = [
+            {"role": msg.role, "content": msg.content} for msg in messages
+        ]
+
+        try:
+            stream = self.client.chat(
+                model=self.model_id,
+                messages=ollama_messages,
+                stream=True,
+                **ollama_kw,
+            )
+
+            in_thought_block = False
+            for chunk in stream:
+                thought_token = chunk.get("message", {}).get("thinking")
+                if thought_token:
+                    if not in_thought_block:
+                        yield "\n<thinking>\n"
+                        in_thought_block = True
+                    yield thought_token
+                content_token = chunk.get("message", {}).get("content")
+                if content_token:
+                    if in_thought_block:
+                        yield "\n<thinking>\n\n"
+                        in_thought_block = False
+
+                    yield content_token
+
+        except ResponseError as e:
+            if e.status_code == 404:
+                raise ValueError(
+                    f"Model '{self.model_id}' not found. "
+                    f"Pull it with: ollama pull {self.model_id}"
+                ) from e
+            raise
+
+    def make_struct(
+        self,
+        messages: list[Message],
+        cls: type[TBaseModel],
+        **ollama_kw,
+    ) -> Iterator[str]:
+        ollama_messages = [
+            {"role": msg.role, "content": msg.content} for msg in messages
+        ]
+
+        try:
+            # Use Pydantic's model_json_schema() for structured outputs
+            stream = self.client.chat(
+                model=self.model_id,
+                messages=ollama_messages,
+                format=cls.model_json_schema(),
+                stream=True,
+                **ollama_kw,
+            )
+
+            for chunk in stream:
+                if not chunk.get("message"):
+                    continue
+
+                msg = chunk["message"]
+
+                # For structured outputs, thinking is usually separate
+                # but we will yield it if present once it won't bugger the JSON.
+                # if msg.get("thinking"):
+                #    yield msg["thinking"]
+
+                # Yield JSON content
+                if msg.get("content"):
+                    yield msg["content"]
+
+        except ResponseError as e:
+            if e.status_code == 404:
+                raise ValueError(
+                    f"Model '{self.model_id}' not found. "
+                    f"Pull it with: ollama pull {self.model_id}"
+                ) from e
+            raise

yera/models/llm_interfaces/open_ai.py

@@ -0,0 +1,150 @@
+import re
+from collections.abc import Iterator
+
+from openai import OpenAI
+from openai.lib._pydantic import to_strict_json_schema
+
+from yera.config2.dataclasses import LLMConfig
+from yera.config2.keyring import DevKeyring
+from yera.models.data_classes import Message
+from yera.models.llm_interfaces.base import BaseLLMInterface, TBaseModel
+
+
+class OpenAILLM(BaseLLMInterface):
+    def __init__(self, config: LLMConfig, overrides: dict, creds_map: dict[str, str]):
+        kws = {**config.inference.model_dump(), **overrides}
+        self.client = None
+        self.model_id = config.model_id
+        self.struct_gen = self._supports_structured_outputs(self.model_id)
+        self.creds_map = creds_map
+        super().__init__(**kws)
+
+    @staticmethod
+    def _supports_structured_outputs(model_id: str) -> bool:
+        """Check if a model supports structured outputs via response_format.
+
+        Structured outputs via response_format are supported on:
+        - gpt-4o models from 2024-08-06 onwards
+        - gpt-4o-mini models from 2024-07-18 onwards
+        - gpt-5+ and o3/o4 models
+
+        Older models can use tool calling with strict: true instead.
+
+        Args:
+            model_id: Model identifier (e.g., "gpt-4o-2024-08-06")
+
+        Returns:
+            True if model supports response_format structured outputs
+        """
+        # GPT-5+ models support structured outputs
+        if (
+            model_id.startswith("gpt-5")
+            or model_id.startswith("o3")
+            or model_id.startswith("o4")
+        ):
+            return True
+
+        # Check gpt-4o and gpt-4o-mini with date snapshots
+        gpt4o_pattern = r"gpt-4o(?:-mini)?-(\d{4})-(\d{2})-(\d{2})"
+        match = re.search(gpt4o_pattern, model_id)
+
+        if match:
+            year = int(match.group(1))
+            month = int(match.group(2))
+            day = int(match.group(3))
+            date_tuple = (year, month, day)
+
+            # gpt-4o-mini: supported from 2024-07-18+
+            if "mini" in model_id:
+                return date_tuple >= (2024, 7, 18)
+            # gpt-4o: supported from 2024-08-06+
+            return date_tuple >= (2024, 8, 6)
+
+        return False
+
+    def start(self):
+        api_key = DevKeyring.get("providers." + self.creds_map["api_key"])
+        self.client = OpenAI(api_key=api_key)
+
+    def stop(self):
+        self.client = None
+
+    def chat(
+        self,
+        messages: list[Message],
+        **openai_kw,
+    ) -> Iterator[str]:
+        openai_messages = [
+            {"role": msg.role, "content": msg.content} for msg in messages
+        ]
+        stream = self.client.chat.completions.create(
+            model=self.model_id,
+            messages=openai_messages,
+            stream=True,
+            **openai_kw,
+        )
+
+        for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+
+    def make_struct(
+        self,
+        messages: list[Message],
+        cls: type[TBaseModel],
+        **openai_kw,
+    ) -> Iterator[str]:
+        openai_messages = [
+            {"role": msg.role, "content": msg.content} for msg in messages
+        ]
+
+        if self.struct_gen:
+            schema = to_strict_json_schema(cls)
+
+            stream = self.client.chat.completions.create(
+                model=self.model_id,
+                messages=openai_messages,
+                response_format={
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": cls.__name__,
+                        "schema": schema,
+                        "strict": True,
+                    },
+                },
+                stream=True,
+                **openai_kw,
+            )
+
+            for chunk in stream:
+                if chunk.choices and chunk.choices[0].delta.content:
+                    yield chunk.choices[0].delta.content
+
+        else:
+            tool_schema = {
+                "type": "function",
+                "function": {
+                    "name": "return_structured_output",
+                    "description": f"Returns structured data conforming to the {cls.__name__} schema",
+                    "parameters": cls.model_json_schema(),
+                    "strict": True,
+                },
+            }
+
+            stream = self.client.chat.completions.create(
+                model=self.model_id,
+                messages=openai_messages,
+                tools=[tool_schema],
+                tool_choice={
+                    "type": "function",
+                    "function": {"name": "return_structured_output"},
+                },
+                stream=True,
+                **openai_kw,
+            )
+
+            for chunk in stream:
+                if chunk.choices and chunk.choices[0].delta.tool_calls:
+                    for tool_call in chunk.choices[0].delta.tool_calls:
+                        if tool_call.function and tool_call.function.arguments:
+                            yield tool_call.function.arguments

yera/models/llm_workspace.py

@@ -0,0 +1,19 @@
+from yera.models.data_classes import Message
+
+
+class LLMWorkspace:
+    def __init__(self):
+        self.messages: list[Message] = []
+        self.variables: dict = {}
+
+    def add_user_message(self, content: str | dict):
+        message = Message.user(content)
+        self.messages.append(message)
+
+    def add_sys_message(self, content: str | dict):
+        message = Message.system(content)
+        self.messages.append(message)
+
+    def add_assistant_message(self, content: str | dict):
+        message = Message.assistant(content)
+        self.messages.append(message)