llm-function 0.0.1__py3-none-any.whl

llm_function/llm_function.py

@@ -0,0 +1,518 @@
+"""
+`llm_function` helps you build reusable LLM functions with normal Python signatures.
+
+You define a function with Pydantic input and output models, describe what it should do
+in the docstring, and provide a set of available tools. At runtime, `llm_function`
+uses [`workflow_auto_assembler`](https://pypi.org/project/workflow-auto-assembler/) to
+assemble and execute a workflow that satisfies that typed function contract.
+
+The result is an LLM-backed function that can be reused like any other Python function,
+while still being grounded in explicit tools, schemas, and config.
+
+Tool definition and discovery live in
+[`llm_function_tools`](https://pypi.org/project/llm-function-tools/).
+"""
+
+import asyncio
+import attrs
+import attrsx
+import inspect
+import threading
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional, Type, get_type_hints
+from pydantic import BaseModel
+from workflow_auto_assembler import WorkflowAutoAssembler
+from typing import Any, Optional, Sequence
+from pydantic import BaseModel, Field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+from pydantic import BaseModel, Field, SkipValidation
+from workflow_auto_assembler import LlmFunctionItem, make_uid
+from llm_function_tools import (
+    ToolSpec,
+    load_tools_from_module,
+    load_tools_from_python_file,
+    tool_from_callable,
+)
+
+__design_choices__ = {}
+
+class LlmRuntimeConfig(BaseModel):
+    """
+    Reusable runtime settings for llm_function execution.
+    """
+
+    llm_handler_params: dict = Field(description="Parameters passed to WorkflowAutoAssembler LLM handler.")
+    storage_path: Optional[str] = Field(default=None, description="Optional storage path for workflow persistence.")
+    force_replan: bool = Field(default=False, description="Force workflow replanning instead of reusing cached workflows.")
+    max_retry: Optional[int] = Field(default=None, description="Optional max retry override for planning loops.")
+    reset_loops: Optional[int] = Field(default=None, description="Optional reset loop override for planning loops.")
+    compare_params: Optional[dict] = Field(default=None, description="Optional compare parameters for workflow validation.")
+    test_params: Optional[list] = Field(default=None, description="Optional test cases for planning/validation.")
+
+
+class LlmFunctionConfig(BaseModel):
+    """
+    Bundled llm_function configuration for future config-driven decorator usage.
+    """
+
+    runtime: LlmRuntimeConfig = Field(description="Runtime settings for workflow execution.")
+    tool_sources: Optional[Sequence[Any]] = Field(default=None, description="Configured tool sources for runtime loading.")
+    tool_registry: Optional[Any] = Field(default=None, description="Optional prebuilt tool registry.")
+
+    model_config = {
+        "arbitrary_types_allowed": True,
+    }
+
+class ResolvedTool(BaseModel):
+    """
+    Runtime-ready tool definition with provenance metadata.
+    """
+
+    tool_spec: ToolSpec = Field(description="Normalized tool definition.")
+    func: SkipValidation[Callable[..., Any]] = Field(description="Runtime callable for the tool.")
+    source_type: str = Field(description="Source kind, for example file or module.")
+    location_type: str = Field(description="Location kind, for example local or external.")
+    package_name: Optional[str] = Field(default=None, description="Optional package name.")
+    package_version: Optional[str] = Field(default=None, description="Optional resolved package version.")
+    module_name: Optional[str] = Field(default=None, description="Python module that defined the tool.")
+    file_path: Optional[str] = Field(default=None, description="Local file path when the tool was loaded from a file.")
+    origin_ref: Optional[str] = Field(default=None, description="Original source reference used to load the tool.")
+    metadata: dict = Field(default_factory=dict, description="Additional runtime metadata.")
+
+    model_config = {
+        "arbitrary_types_allowed": True,
+    }
+
+
+@attrsx.define
+class InMemoryToolSource:
+    """
+    Resolve tools directly from callables, ToolSpec objects, or ResolvedTool objects.
+    """
+
+    tools: Sequence[Union[Callable[..., Any], ToolSpec, ResolvedTool]] = attrs.field()
+    location_type: str = attrs.field(default="local")
+    package_name: Optional[str] = attrs.field(default=None)
+    package_version: Optional[str] = attrs.field(default=None)
+    origin_ref: Optional[str] = attrs.field(default=None)
+
+    def __attrs_post_init__(self):
+        self.tools = list(self.tools)
+
+    def load_tools(self) -> List[ResolvedTool]:
+        """
+        Resolve in-memory tools into runtime tool records.
+        """
+
+        resolved_tools: List[ResolvedTool] = []
+        for item in self.tools:
+            if isinstance(item, ResolvedTool):
+                resolved_tools.append(item)
+                continue
+
+            tool_spec = item if isinstance(item, ToolSpec) else tool_from_callable(item)
+            resolved_tools.append(
+                ResolvedTool(
+                    tool_spec=tool_spec,
+                    func=tool_spec.func,
+                    source_type="memory",
+                    location_type=self.location_type,
+                    package_name=self.package_name,
+                    package_version=self.package_version,
+                    module_name=getattr(tool_spec.func, "__module__", None),
+                    origin_ref=self.origin_ref,
+                )
+            )
+
+        return resolved_tools
+
+
+@attrsx.define
+class PythonModuleToolSource:
+    """
+    Resolve tools from an importable Python module.
+    """
+
+    module_name: str = attrs.field()
+    include_plain_typed: bool = attrs.field(default=False)
+    location_type: str = attrs.field(default="local")
+    package_name: Optional[str] = attrs.field(default=None)
+    package_version: Optional[str] = attrs.field(default=None)
+
+    def load_tools(self) -> List[ResolvedTool]:
+        """
+        Import module and resolve tools declared inside it.
+        """
+
+        resolved_tools: List[ResolvedTool] = []
+        for tool_spec in load_tools_from_module(
+            self.module_name,
+            include_plain_typed=self.include_plain_typed,
+        ):
+            resolved_tools.append(
+                ResolvedTool(
+                    tool_spec=tool_spec,
+                    func=tool_spec.func,
+                    source_type="module",
+                    location_type=self.location_type,
+                    package_name=self.package_name,
+                    package_version=self.package_version,
+                    module_name=self.module_name,
+                    origin_ref=self.module_name,
+                )
+            )
+
+        return resolved_tools
+
+
+@attrsx.define
+class PythonFileToolSource:
+    """
+    Resolve tools from a standalone Python file path.
+    """
+
+    file_path: str = attrs.field()
+    include_plain_typed: bool = attrs.field(default=False)
+    location_type: str = attrs.field(default="local")
+    package_name: Optional[str] = attrs.field(default=None)
+    package_version: Optional[str] = attrs.field(default=None)
+    module_name: Optional[str] = attrs.field(default=None)
+
+    def load_tools(self) -> List[ResolvedTool]:
+        """
+        Import file and resolve tools declared inside it.
+        """
+
+        resolved_path = str(Path(self.file_path).expanduser().resolve())
+        resolved_tools: List[ResolvedTool] = []
+        for tool_spec in load_tools_from_python_file(
+            resolved_path,
+            include_plain_typed=self.include_plain_typed,
+            module_name=self.module_name,
+        ):
+            resolved_tools.append(
+                ResolvedTool(
+                    tool_spec=tool_spec,
+                    func=tool_spec.func,
+                    source_type="file",
+                    location_type=self.location_type,
+                    package_name=self.package_name,
+                    package_version=self.package_version,
+                    module_name=getattr(tool_spec.func, "__module__", self.module_name),
+                    file_path=resolved_path,
+                    origin_ref=resolved_path,
+                )
+            )
+
+        return resolved_tools
+
+
+@attrsx.define
+class ToolRegistry:
+    """
+    Aggregate tools from one or more sources and expose WAA-compatible tool lists.
+    """
+
+    sources: Sequence[object] = attrs.field()
+    _resolved_tools: Optional[List[ResolvedTool]] = attrs.field(default=None)
+
+    def __attrs_post_init__(self):
+        self.sources = list(self.sources)
+
+    def load_tools(self, reload: bool = False) -> List[ResolvedTool]:
+        """
+        Resolve all configured sources into runtime tools.
+        """
+
+        if self._resolved_tools is not None and not reload:
+            return list(self._resolved_tools)
+
+        resolved_tools: List[ResolvedTool] = []
+        seen_keys = set()
+
+        for source in self.sources:
+            for resolved_tool in source.load_tools():
+                dedupe_key = (
+                    resolved_tool.tool_spec.name,
+                    resolved_tool.module_name,
+                    resolved_tool.file_path,
+                    resolved_tool.package_name,
+                    resolved_tool.package_version,
+                )
+                if dedupe_key in seen_keys:
+                    continue
+                seen_keys.add(dedupe_key)
+                resolved_tools.append(resolved_tool)
+
+        self._resolved_tools = resolved_tools
+        return list(self._resolved_tools)
+
+    @staticmethod
+    def _safe_source_code(func: Callable[..., Any]) -> str:
+        """
+        Best-effort source capture for stable tool hashing.
+        """
+
+        try:
+            return inspect.getsource(func)
+        except (OSError, TypeError):
+            return getattr(func, "__qualname__", getattr(func, "__name__", ""))
+
+    def build_available_tools(self) -> Dict[str, Any]:
+        """
+        Convert resolved tools into WorkflowAutoAssembler-compatible structures.
+        """
+
+        available_functions: List[LlmFunctionItem] = []
+        available_callables: Dict[str, Callable[..., Any]] = {}
+
+        for resolved_tool in self.load_tools():
+            llm_func_item = {
+                "name": resolved_tool.tool_spec.name,
+                "description": resolved_tool.tool_spec.description,
+                "input_schema_json": resolved_tool.tool_spec.input_model.model_json_schema(),
+                "output_schema_json": resolved_tool.tool_spec.output_model.model_json_schema(),
+                "code": self._safe_source_code(resolved_tool.func),
+            }
+            func_id = make_uid(d=llm_func_item)
+
+            available_functions.append(
+                LlmFunctionItem(
+                    func_id=func_id,
+                    name=llm_func_item["name"],
+                    description=llm_func_item["description"],
+                    input_schema_json=llm_func_item["input_schema_json"],
+                    output_schema_json=llm_func_item["output_schema_json"],
+                )
+            )
+            available_callables[func_id] = resolved_tool.func
+
+        return {
+            "available_functions": available_functions,
+            "available_callables": available_callables,
+            "resolved_tools": self.load_tools(),
+        }
+
+__package_metadata__ = {
+    "author": "Kyrylo Mordan",
+    "author_email": "parachute.repo@gmail.com",
+    "description": "Llm function is a decorator that uses llm to assemble reusable workflows from available tools to match input and output models.",
+    "url" : 'https://kiril-mordan.github.io/adaptive-reusables/llm-function/',
+}
+
+
+@attrsx.define
+class LlmFunction:
+    available_functions: Optional[List[Any]] = attrs.field(default=None)
+    available_callables: Optional[Dict[str, Callable[..., Any]]] = attrs.field(default=None)
+    tool_registry: Optional[ToolRegistry] = attrs.field(default=None)
+    tool_sources: Optional[List[object]] = attrs.field(default=None)
+    config: Optional[LlmFunctionConfig] = attrs.field(default=None)
+    llm_handler_params: Optional[dict] = attrs.field(default=None)
+    storage_path: Optional[str] = attrs.field(default=None)
+    force_replan: bool = attrs.field(default=False)
+    max_retry: Optional[int] = attrs.field(default=None)
+    reset_loops: Optional[int] = attrs.field(default=None)
+    compare_params: Optional[dict] = attrs.field(default=None)
+    test_params: Optional[list] = attrs.field(default=None)
+    resolved_tools: Optional[Dict[str, Any]] = attrs.field(default=None, init=False)
+
+    def __attrs_post_init__(self):
+        self._apply_config_defaults()
+
+        if self.llm_handler_params is None:
+            raise ValueError("llm_handler_params is required either directly or via config.")
+
+        self.resolved_tools = self._resolve_available_tools()
+
+    def _apply_config_defaults(self):
+        if self.config is None:
+            return
+
+        if self.llm_handler_params is None:
+            self.llm_handler_params = self.config.runtime.llm_handler_params
+        if self.storage_path is None:
+            self.storage_path = self.config.runtime.storage_path
+        if self.force_replan is False:
+            self.force_replan = self.config.runtime.force_replan
+        if self.max_retry is None:
+            self.max_retry = self.config.runtime.max_retry
+        if self.reset_loops is None:
+            self.reset_loops = self.config.runtime.reset_loops
+        if self.compare_params is None:
+            self.compare_params = self.config.runtime.compare_params
+        if self.test_params is None:
+            self.test_params = self.config.runtime.test_params
+        if self.tool_registry is None:
+            self.tool_registry = self.config.tool_registry
+        if self.tool_sources is None and self.config.tool_sources is not None:
+            self.tool_sources = list(self.config.tool_sources)
+
+    def _normalize_task_description(self, func: Callable[..., Any]) -> str:
+        task_description = inspect.cleandoc(func.__doc__ or "").strip()
+        if not task_description:
+            raise ValueError("Decorated function must define a docstring to use as task_description.")
+
+        return task_description
+
+    def _extract_io_models(self, func: Callable[..., Any]) -> tuple[Type[BaseModel], Type[BaseModel], str]:
+        signature = inspect.signature(func)
+        params = list(signature.parameters.values())
+        if len(params) != 1:
+            raise ValueError("Decorated function must accept exactly one parameter annotated with a BaseModel subclass.")
+
+        input_param = params[0]
+        hints = get_type_hints(func)
+        input_model = hints.get(input_param.name)
+        output_model = hints.get("return")
+
+        if not inspect.isclass(input_model) or not issubclass(input_model, BaseModel):
+            raise TypeError("Decorated function input annotation must be a Pydantic BaseModel subclass.")
+
+        if not inspect.isclass(output_model) or not issubclass(output_model, BaseModel):
+            raise TypeError("Decorated function return annotation must be a Pydantic BaseModel subclass.")
+
+        return input_model, output_model, input_param.name
+
+    def _coerce_run_inputs(self, input_model: Type[BaseModel], run_inputs: Any) -> BaseModel:
+        if isinstance(run_inputs, input_model):
+            return run_inputs
+
+        if hasattr(input_model, "model_validate"):
+            return input_model.model_validate(run_inputs)
+
+        return input_model.parse_obj(run_inputs)
+
+    def _run_coro_blocking(self, coro):
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(coro)
+
+        result: Dict[str, Any] = {}
+        error: Dict[str, BaseException] = {}
+
+        def _thread_main():
+            try:
+                result["value"] = asyncio.run(coro)
+            except BaseException as exc:  # pragma: no cover
+                error["value"] = exc
+
+        thread = threading.Thread(target=_thread_main, daemon=True)
+        thread.start()
+        thread.join()
+
+        if "value" in error:
+            raise error["value"]
+
+        return result["value"]
+
+    def _resolve_available_tools(self) -> Dict[str, Any]:
+        if self.tool_registry is not None and self.tool_sources is not None:
+            raise ValueError("Use either tool_registry or tool_sources, not both.")
+
+        if self.tool_registry is not None:
+            return self.tool_registry.build_available_tools()
+
+        if self.tool_sources is not None:
+            return ToolRegistry(sources=self.tool_sources).build_available_tools()
+
+        if self.available_functions is None or self.available_callables is None:
+            raise ValueError(
+                "Provide either available_functions and available_callables, or tool_registry/tool_sources."
+            )
+
+        return {
+            "available_functions": self.available_functions,
+            "available_callables": self.available_callables,
+            "resolved_tools": None,
+        }
+
+    def as_decorator(self):
+        def decorator(func: Callable[..., Any]):
+            signature = inspect.signature(func)
+            task_description = self._normalize_task_description(func)
+            input_model, output_model, input_name = self._extract_io_models(func)
+
+            async def _invoke_async(run_inputs: Any):
+                wa = WorkflowAutoAssembler(
+                    available_functions=self.resolved_tools["available_functions"],
+                    available_callables=self.resolved_tools["available_callables"],
+                    storage_path=self.storage_path,
+                    llm_handler_params=self.llm_handler_params,
+                )
+
+                return await wa.actualize_workflow(
+                    task_description=task_description,
+                    force_replan=self.force_replan,
+                    run_inputs=self._coerce_run_inputs(input_model=input_model, run_inputs=run_inputs),
+                    test_params=self.test_params,
+                    compare_params=self.compare_params,
+                    input_model=input_model,
+                    output_model=output_model,
+                    max_retry=self.max_retry,
+                    reset_loops=self.reset_loops,
+                )
+
+            if inspect.iscoroutinefunction(func):
+
+                @wraps(func)
+                async def async_wrapper(*args, **kwargs):
+                    bound = signature.bind(*args, **kwargs)
+                    return await _invoke_async(bound.arguments[input_name])
+
+                async_wrapper.input_model = input_model
+                async_wrapper.output_model = output_model
+                async_wrapper.task_description = task_description
+                async_wrapper.ainvoke = _invoke_async
+                async_wrapper.resolved_tools = self.resolved_tools["resolved_tools"]
+                return async_wrapper
+
+            @wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                bound = signature.bind(*args, **kwargs)
+                return self._run_coro_blocking(_invoke_async(bound.arguments[input_name]))
+
+            sync_wrapper.input_model = input_model
+            sync_wrapper.output_model = output_model
+            sync_wrapper.task_description = task_description
+            sync_wrapper.ainvoke = _invoke_async
+            sync_wrapper.resolved_tools = self.resolved_tools["resolved_tools"]
+            return sync_wrapper
+
+        return decorator
+
+
+def llm_function(
+    *,
+    available_functions: Optional[List[Any]] = None,
+    available_callables: Optional[Dict[str, Callable[..., Any]]] = None,
+    tool_registry: Optional[ToolRegistry] = None,
+    tool_sources: Optional[List[object]] = None,
+    config: Optional[LlmFunctionConfig] = None,
+    llm_handler_params: Optional[dict] = None,
+    storage_path: Optional[str] = None,
+    force_replan: bool = False,
+    max_retry: Optional[int] = None,
+    reset_loops: Optional[int] = None,
+    compare_params: Optional[dict] = None,
+    test_params: Optional[list] = None,
+):
+    """
+    Decorate a typed function and route its calls through WorkflowAutoAssembler.
+    """
+    return LlmFunction(
+        available_functions=available_functions,
+        available_callables=available_callables,
+        tool_registry=tool_registry,
+        tool_sources=tool_sources,
+        config=config,
+        llm_handler_params=llm_handler_params,
+        storage_path=storage_path,
+        force_replan=force_replan,
+        max_retry=max_retry,
+        reset_loops=reset_loops,
+        compare_params=compare_params,
+        test_params=test_params,
+    ).as_decorator()

llm_function/mkdocs/docs/css/extra.css

@@ -0,0 +1,38 @@
+/* Ensure tables are scrollable horizontally */
+table {
+  display: block;
+  width: 100%;
+  overflow-x: auto;
+  white-space: nowrap;
+}
+
+/* Ensure tables and their parent divs don't overflow the content area */
+.dataframe {
+  display: block;
+  width: 100%;
+  overflow-x: auto;
+  white-space: nowrap;
+}
+
+.dataframe thead th {
+  text-align: right;
+}
+
+.dataframe tbody tr th {
+  vertical-align: top;
+}
+
+.dataframe tbody tr th:only-of-type {
+  vertical-align: middle;
+}
+
+/* Ensure the whole content area is scrollable */
+.md-content__inner {
+  overflow-x: auto;
+  padding: 20px; /* Add some padding for better readability */
+}
+
+/* Fix layout issues caused by the theme */
+.md-main__inner {
+  max-width: none;
+}

llm_function/mkdocs/docs/index.md

@@ -0,0 +1,24 @@
+# Intro
+
+[![PyPiVersion](https://img.shields.io/pypi/v/llm-function)](https://pypi.org/project/llm-function/) 
+
+`llm_function` helps you build reusable LLM functions with normal Python signatures.
+
+You define a function with Pydantic input and output models, describe what it should do
+in the docstring, and provide a set of available tools. At runtime, `llm_function`
+uses [`workflow_auto_assembler`](https://pypi.org/project/workflow-auto-assembler/) to
+assemble and execute a workflow that satisfies that typed function contract.
+
+The result is an LLM-backed function that can be reused like any other Python function,
+while still being grounded in explicit tools, schemas, and config.
+
+Tool definition and discovery live in
+[`llm_function_tools`](https://pypi.org/project/llm-function-tools/).
+
+
+## Installation
+
+```bash
+pip install llm-function
+```
+