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

yera/models/model_atlas.py

@@ -0,0 +1,139 @@
+from yera.models.model_factory import LLMContextFactory
+
+
+def _id_to_attr(id_: str) -> str:
+    return id_.replace("-", "_").replace(":", "_")
+
+
+# noinspection PyUnresolvedReferences
+class ModelAtlas:
+    @staticmethod
+    def from_yera_config(yera_config) -> "ModelAtlas":
+        root = ModelAtlas()
+
+        for path, cfg in yera_config.models.llm.items():
+            parts = path.split(".")
+            current = root
+            for part in parts[:-1]:
+                if not hasattr(current, part):
+                    setattr(current, part, ModelAtlas())
+                current = getattr(current, part)
+
+            attr_name = parts[-1].replace("-", "_").replace(":", "_")
+            factory = LLMContextFactory(
+                cfg, yera_config.credentials.providers[cfg.credentials]
+            )
+            setattr(current, attr_name, factory)
+
+        root.default = yera_config.defaults.models.llm
+        return root
+
+    def __init__(self):
+        self.default = None
+
+    def __dir__(self):
+        # Prioritise instance attributes (the dynamic model paths)
+        instance_attrs = list(self.__dict__.keys())
+
+        # Add essential class attributes but filter out private and dunder
+        class_attrs = [
+            attr
+            for attr in object.__dir__(self)
+            if not attr.startswith("_") and attr not in instance_attrs
+        ]
+
+        # Instance attributes first for better tab completion
+        return instance_attrs + class_attrs
+
+    def _ipython_key_completions_(self):
+        return [k for k in self.__dict__ if not k.startswith("_")]
+
+    def __getitem__(self, key: str):
+        current = self
+        for part in key.split("."):
+            current = getattr(current, _id_to_attr(part), None)
+            if current is None:
+                raise KeyError(key)
+        return current
+
+    def list_models(self):
+        attrs = [getattr(self, n) for n in dir(self)]
+        attrs = [a for a in attrs if isinstance(a, ModelAtlas | LLMContextFactory)]
+
+        models = []
+        for attr in attrs:
+            if isinstance(attr, ModelAtlas):
+                models += attr.list_models()
+            if isinstance(attr, LLMContextFactory):
+                models.append(attr)
+
+        return models
+
+    def _repr_html_(self):
+        """Rich HTML representation for Jupyter notebooks"""
+
+        def build_tree_html(atlas, prefix=""):
+            items = []
+            for key in sorted(atlas.__dict__.keys()):
+                if key.startswith("_"):
+                    continue
+                value = getattr(atlas, key)
+                if isinstance(value, ModelAtlas):
+                    items.append(
+                        f"<li><b>{key}/</b><ul>{build_tree_html(value, prefix + '  ')}</ul></li>"
+                    )
+                elif isinstance(value, LLMContextFactory):
+                    # Show model info if available
+                    model_info = f" <span style='color: #666; font-size: 0.9em;'>({value.config.provider if hasattr(value, 'config') else 'model'})</span>"
+                    items.append(f"<li>{key}{model_info}</li>")
+            return "".join(items)
+
+        html = f"""
+        <div style="font-family: monospace; line-height: 1.6;">
+            <b>ModelAtlas</b>
+            <ul style="list-style-type: none; padding-left: 20px;">
+                {build_tree_html(self)}
+            </ul>
+        </div>
+        """
+        return html
+
+    def _build_text_tree(self, prefix: str = "") -> str:
+        lines = []
+
+        names = sorted(k for k in self.__dict__ if not k.startswith("_"))
+        names = [
+            n
+            for n in names
+            if isinstance(getattr(self, n), ModelAtlas | LLMContextFactory)
+        ]
+
+        for idx, name in enumerate(names):
+            child = getattr(self, name)
+            connector = "└── " if idx == len(names) - 1 else "├── "
+            child_prefix = prefix + ("    " if idx == len(names) - 1 else "│   ")
+
+            if isinstance(child, ModelAtlas):
+                lines.append(f"{prefix}{connector}{name}/")
+                lines.append(child._build_text_tree(child_prefix))
+            elif isinstance(child, LLMContextFactory):
+                lines.append(f"{prefix}{connector}{name}")
+
+        if self.default:
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def __str__(self) -> str:
+        return (
+            f"┌─ [LLMs]\n├─ Default: {_id_to_attr(self.default)}\n│\n"
+            + self._build_text_tree()
+        )
+
+    def set_default(self, path):
+        self.default = path
+
+    def get_default(self):
+        if self.default:
+            return self[self.default]()
+        return None

yera/models/model_definition.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ModelDefinition(BaseModel):
+    name: str
+    type: Literal["LLM", "TTS", "STS", "VLM"] = "LLM"
+    security_rank: int
+    interface_cls: str
+    args: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    default_quant: str | None = None
+    quant_files: dict[str, str] = Field(default_factory=dict)
+
+    def build_kwargs(self, **kwargs) -> dict:
+        new_quant = kwargs.pop("quant", self.default_quant)
+
+        if new_quant and len(self.quant_files) == 0:
+            raise ValueError(
+                f"Cannot set a quant for {self.name}. "
+                f"Its definition has no model files - is this an API-based model?"
+            )
+
+        if new_quant and new_quant not in self.quant_files:
+            available = ", ".join(self.quant_files.keys())
+            raise ValueError(
+                f"The quant '{new_quant}' was not found for model {self.name}. "
+                f"Available quants are {available}."
+            )
+
+        kws = {**self.args, **kwargs}
+
+        if new_quant:
+            kws["model_path"] = Path(self.quant_files[new_quant])
+
+        return kws

yera/models/model_factory.py

@@ -0,0 +1,33 @@
+from typing import TYPE_CHECKING
+
+from yera.models.llm_context import LLMContext
+from yera.models.llm_interfaces.interface_registry import get_interface
+from yera.models.llm_workspace import LLMWorkspace
+
+if TYPE_CHECKING:
+    from yera.config2.dataclasses import LLMConfig
+
+
+class LLMContextFactory:
+    def __init__(self, model_cfg: "LLMConfig", creds_map: dict[str, str]):
+        from yera.config2.dataclasses import LLMConfig
+
+        if not isinstance(model_cfg, LLMConfig):
+            raise TypeError(
+                f"model_cfg must be type LLMConfig. Was {type(model_cfg).__name__}."
+            )
+
+        self.model_cfg = model_cfg
+        self.creds_map = creds_map
+
+        self.llm_cls = get_interface(self.model_cfg.interface)
+        if self.llm_cls is None:
+            raise ValueError(
+                f"Could not find llm interface class '{self.model_cfg.interface}'"
+            )
+
+    def __call__(self, **kwargs) -> LLMContext:
+        # todo: metaclass magic for runtime signature generation from config
+        interface = self.llm_cls(self.model_cfg, kwargs, creds_map=self.creds_map)
+        # todo: workspace inheritance goes here
+        return LLMContext(interface=interface, workspace=LLMWorkspace())

yera/opaque/__init__.py

@@ -0,0 +1,9 @@
+from .base import OpaqueCallable as OpaqueCallable
+from .decorator import opaque as opaque
+from .opaque_function import OpaqueFunction as OpaqueFunction
+
+__all__ = [
+    "OpaqueCallable",
+    "OpaqueFunction",
+    "opaque",
+]

yera/opaque/base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class OpaqueCallable(ABC):
+    """Base class for callables that should appear as single opaque nodes in the graph."""
+
+    @abstractmethod
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the opaque callable with the given arguments."""
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of the opaque callable."""
+        pass
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name})"

yera/opaque/decorator.py

@@ -0,0 +1,8 @@
+from collections.abc import Callable
+
+from yera.opaque.opaque_function import OpaqueFunction
+
+
+def opaque(func: Callable) -> OpaqueFunction:
+    """Decorator to mark a function as opaque to the tracer."""
+    return OpaqueFunction(func)

yera/opaque/markdown.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from yera.opaque.base import OpaqueCallable
+from yera.yil.tracing.markdown_tracing import MarkdownTracingContext
+
+
+class Markdown(OpaqueCallable):
+    """Trace-only opaque callable for markdown blocks.
+
+    This is a YIL-first API surface for markdown. It is intended to be used
+    *only* inside a tracing context. Calling it directly in normal Python
+    execution is an error.
+    """
+
+    @property
+    def name(self) -> str:
+        """Get the name of the opaque callable."""
+        return "markdown"
+
+    def __call__(self, content: Any | None = None) -> MarkdownTracingContext:
+        """Call markdown during tracing to create MarkdownInit operations.
+
+        When called inside a tracing context:
+        - Delegates to tracing module to create MarkdownInit operation
+        - Returns a MarkdownTracingContext representing the markdown block
+
+        When called outside a tracing context:
+        - Raises RuntimeError (trace-only contract)
+
+        Args:
+            content: Content for the markdown block (can be Tracer, literal, or None).
+                    If None, creates a markdown block with no initial content.
+
+        Returns:
+            MarkdownTracingContext representing the markdown block (in tracing context)
+            or raises RuntimeError (outside tracing context)
+
+        """
+        from yera.yil.tracing.markdown_tracing import trace_markdown
+
+        return trace_markdown(content)
+
+
+# Trace-only markdown implementation for OpGraph.
+#
+# This is used during tracing to create MarkdownInit/MarkdownAppend operations.
+# In the future, this will be the only markdown implementation (chat/blocks/markdown.py
+# will be removed), and execution will happen via OpGraph executor.
+#
+# For now, this exists alongside yera.chat.markdown which provides direct execution
+# for MVP demos. This implementation ONLY works in a tracing context.
+markdown = Markdown()
+
+
+__all__ = ["Markdown", "markdown"]

yera/opaque/opaque_function.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from yera.config.config_utils import extract_function_config
+from yera.opaque.base import OpaqueCallable
+
+
+class OpaqueFunction(OpaqueCallable):
+    """Wrapper for functions marked with @yk.opaque decorator."""
+
+    def __init__(self, func: Callable):
+        self._func = func
+        self._function_config = extract_function_config(func)
+        functools.update_wrapper(self, func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._func(*args, **kwargs)
+
+    @property
+    def name(self) -> str:
+        """Get the name of the opaque function."""
+        return self._function_config.name

yera/tools/__init__.py

@@ -0,0 +1,29 @@
+from .atlas_tool import AtlasTool as AtlasTool
+from .base import Tool as Tool
+from .decorated_tool import DecoratedTool as DecoratedTool
+from .decorator import tool as tool
+from .tool_atlas import get_tool_atlas as get_tool_atlas
+from .tool_utils import (
+    extract_tool_config as extract_tool_config,
+)
+from .tool_utils import (
+    load_tools_config as load_tools_config,
+)
+from .tool_utils import (
+    reconstruct_tool_function as reconstruct_tool_function,
+)
+from .tool_utils import (
+    save_tool as save_tool,
+)
+
+__all__ = [
+    "AtlasTool",
+    "DecoratedTool",
+    "Tool",
+    "extract_tool_config",
+    "get_tool_atlas",
+    "load_tools_config",
+    "reconstruct_tool_function",
+    "save_tool",
+    "tool",
+]

yera/tools/atlas_tool.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from yera.config.tool_config import ToolConfig
+from yera.tools.base import Tool
+from yera.tools.tool_utils import reconstruct_tool_function
+
+
+class AtlasTool(Tool):
+    def __init__(self, tool_config: ToolConfig):
+        super().__init__(tool_config)
+        self._callable: Callable | None = None
+
+    def __call__(self, *args, **kwargs) -> Any:
+        # Tool is reconstructed lazily from tool_config the first time it is called, and cached for subsequent calls
+        if self._callable is None:
+            self._callable = reconstruct_tool_function(self.tool_config)
+        return self._callable(*args, **kwargs)

yera/tools/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from yera.config.tool_config import ToolConfig
+from yera.opaque import OpaqueCallable
+
+
+class Tool(OpaqueCallable, ABC):
+    """Abstract base class for all Yera tools. Tools are a specialisation of opaque callables."""
+
+    def __init__(self, tool_config: ToolConfig):
+        self.tool_config = tool_config
+
+    @abstractmethod
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the tool with the given arguments."""
+        pass
+
+    @property
+    def name(self) -> str:
+        """Get the name of the tool."""
+        return self.tool_config.function_config.name

yera/tools/decorated_tool.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from yera.config.tool_config import ToolConfig
+from yera.tools.base import Tool
+
+
+class DecoratedTool(Tool):
+    def __init__(self, func: Callable, tool_config: ToolConfig):
+        super().__init__(tool_config)
+        self._func = func
+        functools.update_wrapper(self, func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._func(*args, **kwargs)

yera/tools/decorator.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+
+from yera.config.tool_config import ToolConfig
+from yera.tools import tool_utils
+from yera.tools.decorated_tool import DecoratedTool
+
+logger = logging.getLogger(__name__)
+
+
+def tool(security_rank: int, save: bool = False, cfg_path: Path | str | None = None):
+    if not isinstance(security_rank, int) or security_rank < 0:
+        raise ValueError("security_rank must be a non-negative integer")
+
+    def decorator(func: Callable) -> DecoratedTool:
+        tool_config: ToolConfig = tool_utils.extract_tool_config(
+            func, security_rank=security_rank
+        )
+
+        wrapper = DecoratedTool(func, tool_config)
+
+        if save:
+            try:
+                tool_utils.save_tool(
+                    func, cfg_path=cfg_path, security_rank=security_rank
+                )
+            except Exception as e:
+                logger.warning("Failed to save tool '%s': %s", func.__name__, e)
+
+        return wrapper
+
+    return decorator

yera/tools/tool_atlas.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from yera.config.tool_config import ToolConfig
+from yera.tools.atlas_tool import AtlasTool
+from yera.tools.tool_utils import load_tools_config
+
+
+class ToolAtlas:
+    @staticmethod
+    def from_config_map(config_map: dict[str, ToolConfig]) -> ToolAtlas:
+        root = ToolAtlas()
+
+        for path, cfg in config_map.items():
+            parts = path.split(".")
+            current = root
+            for part in parts[:-1]:
+                if not hasattr(current, part):
+                    setattr(current, part, ToolAtlas())
+                current = getattr(current, part)
+
+            setattr(current, parts[-1].replace("-", "_"), AtlasTool(cfg))
+
+        return root
+
+    def __getitem__(self, key: str):
+        current = self
+        for part in key.split("."):
+            current = getattr(current, part, None)
+            if current is None:
+                raise KeyError(key)
+        return current
+
+    def list_tools(self):
+        attrs = [getattr(self, n) for n in dir(self)]
+        attrs = [a for a in attrs if isinstance(a, ToolAtlas | AtlasTool)]
+
+        tools = []
+        for attr in attrs:
+            if isinstance(attr, ToolAtlas):
+                tools += attr.list_tools()
+            if isinstance(attr, AtlasTool):
+                tools.append(attr)
+
+        return tools
+
+
+def get_tool_atlas(cfg_path: Path | str | None = None) -> ToolAtlas:
+    raw_cfg_map = load_tools_config(cfg_path)
+    return ToolAtlas.from_config_map(raw_cfg_map)