byllm 0.4.1__py2.py3-none-any.whl

byllm/__init__.py

@@ -0,0 +1,8 @@
+"""byLLM Package."""
+
+from byllm.llm import Model
+from byllm.mtir import MTIR
+from byllm.plugin import by
+from byllm.types import Image, MockToolCall, Video
+
+__all__ = ["by", "Image", "MockToolCall", "Model", "MTIR", "Video"]

byllm/llm.py

@@ -0,0 +1,101 @@
+"""LLM abstraction module.
+
+This module provides a LLM class that abstracts LiteLLM and offers
+enhanced functionality and interface for language model operations.
+"""
+
+# flake8: noqa: E402
+
+import os
+from typing import Generator
+
+from byllm.mtir import MTIR
+
+# This will prevent LiteLLM from fetching pricing information from
+# the bellow URL every time we import the litellm and use a cached
+# local json file. Maybe we we should conditionally enable this.
+# https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
+os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"
+
+from .llm_connector import LLMConnector
+from .types import CompletionResult
+
+SYSTEM_PERSONA = """\
+This is a task you must complete by returning only the output.
+Do not include explanations, code, or extra text—only the result.
+"""  # noqa E501
+
+INSTRUCTION_TOOL = """
+Use the tools provided to reach the goal. Call one tool at a time with \
+proper args—no explanations, no narration. Think step by step, invoking tools \
+as needed. When done, always call finish_tool(output) to return the final \
+output. Only use tools.
+"""  # noqa E501
+
+
+class Model:
+    """A wrapper class that abstracts LiteLLM functionality.
+
+    This class provides a simplified and enhanced interface for interacting
+    with various language models through LiteLLM.
+    """
+
+    def __init__(self, model_name: str, **kwargs: object) -> None:
+        """Initialize the JacLLM instance.
+
+        Args:
+            model: The model name to use (e.g., "gpt-3.5-turbo", "claude-3-sonnet-20240229")
+            api_key: API key for the model provider
+            **kwargs: Additional configuration options
+        """
+        self.llm_connector = LLMConnector.for_model(model_name, **kwargs)
+
+    def __call__(self, **kwargs: object) -> "Model":
+        """Construct the call parameters and return self (factory pattern).
+
+        Example:
+            ```jaclang
+            llm = JacLLM(model="gpt-3.5-turbo", api_key="your_api_key")
+
+            # The bellow call will construct the parameter and return self.
+            def answer_user_query(query: str) -> str by
+                llm(
+                    temperature=0.7,
+                    max_tokens=100,
+                );
+            ```
+        """
+        self.llm_connector.call_params = kwargs
+        return self
+
+    @property
+    def call_params(self) -> dict[str, object]:
+        """Get the call parameters for the LLM."""
+        return self.llm_connector.call_params
+
+    def invoke(self, mtir: MTIR) -> object:
+        """Invoke the LLM with the given caller and arguments."""
+        if mtir.stream:
+            return self._completion_streaming(mtir)
+
+        # Invoke the LLM and handle tool calls.
+        while True:
+            resp = self._completion_no_streaming(mtir)
+            if resp.tool_calls:
+                for tool_call in resp.tool_calls:
+                    if tool_call.is_finish_call():
+                        return tool_call.get_output()
+                    else:
+                        mtir.add_message(tool_call())
+            else:
+                break
+
+        return resp.output
+
+    def _completion_no_streaming(self, mtir: MTIR) -> CompletionResult:
+        """Perform a completion request with the LLM."""
+        return self.llm_connector.dispatch_no_streaming(mtir)
+
+    def _completion_streaming(self, mtir: MTIR) -> Generator[str, None, None]:
+        """Perform a streaming completion request with the LLM."""
+        return self.llm_connector.dispatch_streaming(mtir)

byllm/llm_connector.py

@@ -0,0 +1,228 @@
+"""LLM Connector for Litellm, MockLLM, Proxy server, etc.
+
+This module provides an abstract base class for LLM connectors and concrete implementations
+for different LLM services. It includes methods for dispatching requests and handling responses.
+"""
+
+# flake8: noqa: E402
+
+import json
+import logging
+import os
+import random
+import time
+from abc import ABC, abstractmethod
+from typing import Generator, override
+
+# This will prevent LiteLLM from fetching pricing information from
+# the bellow URL every time we import the litellm and use a cached
+# local json file. Maybe we we should conditionally enable this.
+# https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
+os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"
+
+import litellm
+from litellm._logging import _disable_debugging
+
+from openai import OpenAI
+
+from .mtir import MTIR
+
+from .types import (
+    CompletionResult,
+    LiteLLMMessage,
+    MockToolCall,
+    ToolCall,
+)
+
+DEFAULT_BASE_URL = "http://localhost:4000"
+MODEL_MOCK = "mockllm"
+
+
+class LLMConnector(ABC):
+    """Abstract base class for LLM connectors."""
+
+    def __init__(self, model_name: str, **kwargs: object) -> None:
+        """Initialize the LLM connector with a model."""
+        self.model_name = model_name
+        self.config = kwargs
+        # The parameters for the llm call like temprature, top_k, max_token, etc.
+        # This is only applicable for the next call passed from `by llm(**kwargs)`.
+        self.call_params: dict[str, object] = {}
+
+    @staticmethod
+    def for_model(model_name: str, **kwargs: object) -> "LLMConnector":
+        """Construct the appropriate LLM connector based on the model name."""
+        if model_name.lower().strip() == MODEL_MOCK:
+            return MockLLMConnector(model_name, **kwargs)
+        if kwargs.get("proxy_url"):
+            kwargs["base_url"] = kwargs.pop("proxy_url")
+            return LiteLLMConnector(True, model_name, **kwargs)
+        return LiteLLMConnector(False, model_name, **kwargs)
+
+    def make_model_params(self, mtir: MTIR) -> dict:
+        """Prepare the parameters for the LLM call."""
+        params = {
+            "model": self.model_name,
+            "api_base": (
+                self.config.get("base_url")
+                or self.config.get("host")
+                or self.config.get("api_base")
+            ),
+            "api_key": self.config.get("api_key"),
+            "messages": mtir.get_msg_list(),
+            "tools": mtir.get_tool_list() or None,
+            "response_format": mtir.get_output_schema(),
+            "temperature": self.call_params.get("temperature", 0.7),
+            "max_tokens": self.call_params.get("max_tokens"),
+            # "top_k": self.call_params.get("top_k", 50),
+            # "top_p": self.call_params.get("top_p", 0.9),
+        }
+        return params
+
+    def log_info(self, message: str) -> None:
+        """Log a message to the console."""
+        # FIXME: The logger.info will not always log so for now I'm printing to stdout
+        # remove and log properly.
+        if bool(self.config.get("verbose", False)):
+            print(message)
+
+    @abstractmethod
+    def dispatch_no_streaming(self, mtir: MTIR) -> CompletionResult:
+        """Dispatch the LLM call without streaming."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def dispatch_streaming(self, mtir: MTIR) -> Generator[str, None, None]:
+        """Dispatch the LLM call with streaming."""
+        raise NotImplementedError()
+
+
+# -----------------------------------------------------------------------------
+# Mock LLM Connector
+# -----------------------------------------------------------------------------
+
+
+class MockLLMConnector(LLMConnector):
+    """LLM Connector for a mock LLM service that simulates responses."""
+
+    @override
+    def dispatch_no_streaming(self, mtir: MTIR) -> CompletionResult:
+        """Dispatch the mock LLM call with the given request."""
+        output = self.config["outputs"].pop(0)  # type: ignore
+
+        if isinstance(output, MockToolCall):
+            self.log_info(
+                f"Mock LLM call completed with tool call:\n{output.to_tool_call()}"
+            )
+            return CompletionResult(
+                output=None,
+                tool_calls=[output.to_tool_call()],
+            )
+
+        self.log_info(f"Mock LLM call completed with response:\n{output}")
+
+        return CompletionResult(
+            output=output,
+            tool_calls=[],
+        )
+
+    @override
+    def dispatch_streaming(self, mtir: MTIR) -> Generator[str, None, None]:
+        """Dispatch the mock LLM call with the given request."""
+        output = self.config["outputs"].pop(0)  # type: ignore
+        if mtir.stream:
+            while output:
+                chunk_len = random.randint(3, 10)
+                yield output[:chunk_len]  # Simulate token chunk
+                time.sleep(random.uniform(0.01, 0.05))  # Simulate network delay
+                output = output[chunk_len:]
+
+
+# -----------------------------------------------------------------------------
+# LiteLLM Connector
+# -----------------------------------------------------------------------------
+
+
+class LiteLLMConnector(LLMConnector):
+    """LLM Connector for LiteLLM, a lightweight wrapper around OpenAI API."""
+
+    def __init__(self, proxy: bool, model_name: str, **kwargs: object) -> None:
+        """Initialize the LiteLLM connector."""
+        super().__init__(model_name, **kwargs)
+        self.proxy = proxy
+
+        # Every litellm call will be logged to the tty and that pollutes the output.
+        # When there is a by llm() call in the jaclang.
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+        _disable_debugging()
+        litellm.drop_params = True
+
+    @override
+    def dispatch_no_streaming(self, mtir: MTIR) -> CompletionResult:
+        """Dispatch the LLM call without streaming."""
+        # Construct the parameters for the LLM call
+        params = self.make_model_params(mtir)
+
+        # Call the LiteLLM API
+        self.log_info(f"Calling LLM: {self.model_name} with params:\n{params}")
+        if self.proxy:
+            client = OpenAI(
+                base_url=params.pop("api_base", "htpp://localhost:4000"),
+                api_key=params.pop("api_key"),
+            )
+            response = client.chat.completions.create(**params)
+        else:
+            response = litellm.completion(**params)
+
+        # Output format:
+        # https://docs.litellm.ai/docs/#response-format-openai-format
+        #
+        # TODO: Handle stream output (type ignoring stream response)
+        message: LiteLLMMessage = response.choices[0].message  # type: ignore
+        mtir.add_message(message)
+
+        output_content: str = message.content  # type: ignore
+        self.log_info(f"LLM call completed with response:\n{output_content}")
+        output_value = mtir.parse_response(output_content)
+
+        tool_calls: list[ToolCall] = []
+        for tool_call in message.tool_calls or []:  # type: ignore
+            if tool := mtir.get_tool(tool_call["function"]["name"]):
+                args_json = json.loads(tool_call["function"]["arguments"])
+                args = tool.parse_arguments(args_json)
+                tool_calls.append(
+                    ToolCall(call_id=tool_call["id"], tool=tool, args=args)
+                )
+            else:
+                raise RuntimeError(
+                    f"Attempted to call tool: '{tool_call['function']['name']}' which was not present."
+                )
+
+        return CompletionResult(
+            output=output_value,
+            tool_calls=tool_calls,
+        )
+
+    @override
+    def dispatch_streaming(self, mtir: MTIR) -> Generator[str, None, None]:
+        """Dispatch the LLM call with streaming."""
+        # Construct the parameters for the LLM call
+        params = self.make_model_params(mtir)
+
+        # Call the LiteLLM API
+        self.log_info(f"Calling LLM: {self.model_name} with params:\n{params}")
+        if self.proxy:
+            client = OpenAI(
+                base_url=params.pop("api_base"),
+                api_key=params.pop("api_key"),
+            )
+
+            # Call the LiteLLM API
+            response = client.chat.completions.create(**params, stream=True)
+        else:
+            response = litellm.completion(**params, stream=True)  # type: ignore
+
+        for chunk in response:
+            if chunk.choices and chunk.choices[0].delta:
+                delta = chunk.choices[0].delta
+                yield delta.content or ""

byllm/mtir.py

@@ -0,0 +1,194 @@
+"""MTIR (Meaning Typed Intermediate Representation) module for JacLang runtime library."""
+
+import inspect
+import json
+from dataclasses import dataclass
+from types import MethodType
+from typing import Callable, get_type_hints
+
+from byllm.schema import json_to_instance, type_to_schema
+from byllm.types import (
+    LiteLLMMessage,
+    Media,
+    Message,
+    MessageRole,
+    MessageType,
+    Text,
+    Tool,
+)
+
+
+SYSTEM_PERSONA = """\
+This is a task you must complete by returning only the output.
+Do not include explanations, code, or extra text—only the result.
+"""  # noqa E501
+
+INSTRUCTION_TOOL = """
+Use the tools provided to reach the goal. Call one tool at a time with \
+proper args—no explanations, no narration. Think step by step, invoking tools \
+as needed. When done, always call finish_tool(output) to return the final \
+output. Only use tools.
+"""  # noqa E501
+
+
+@dataclass
+class MTIR:
+    """A class representing the MTIR for JacLang."""
+
+    # All the context required to dispatch an LLM invocation.
+    messages: list[MessageType]
+    resp_type: type | None
+    stream: bool
+    tools: list[Tool]
+    call_params: dict[str, object]
+
+    # FIXME: Comeup with a better name
+    @staticmethod
+    def factory(
+        caller: Callable, args: dict[int | str, object], call_params: dict[str, object]
+    ) -> "MTIR":
+        """Create an MTIR instance."""
+        # Prepare the tools for the LLM call.
+        tools = [Tool(func) for func in call_params.get("tools", [])]  # type: ignore
+
+        # Construct the input information from the arguments.
+        param_names = list(inspect.signature(caller).parameters.keys())
+        inputs_detail: list[str] = []
+        media_inputs: list[Media] = []
+
+        for key, value in args.items():
+            if isinstance(value, Media):
+                media_inputs.append(value)
+                continue
+
+            if isinstance(key, str):
+                inputs_detail.append(f"{key} = {value}")
+            else:
+                # TODO: Handle *args, **kwargs properly.
+                if key < len(param_names):
+                    inputs_detail.append(f"{param_names[key]} = {value}")
+                else:
+                    inputs_detail.append(f"arg = {value}")
+        incl_info = call_params.get("incl_info")
+        if incl_info and isinstance(incl_info, dict):
+            for key, value in incl_info.items():
+                if isinstance(value, Media):
+                    media_inputs.append(value)
+                else:
+                    inputs_detail.append(f"{key} = {value}")
+
+        if isinstance(caller, MethodType):
+            inputs_detail.insert(0, f"self = {caller.__self__}")
+
+        # Prepare the messages for the LLM call.
+        messages: list[MessageType] = [
+            Message(
+                role=MessageRole.SYSTEM,
+                content=SYSTEM_PERSONA + (INSTRUCTION_TOOL if tools else ""),
+            ),
+            Message(
+                role=MessageRole.USER,
+                content=[
+                    Text(
+                        Tool.get_func_description(caller)
+                        + "\n\n"
+                        + "\n".join(inputs_detail)
+                    ),
+                    *media_inputs,
+                ],
+            ),
+        ]
+
+        # Prepare return type.
+        return_type = get_type_hints(caller).get("return")
+        is_streaming = bool(call_params.get("stream", False))
+
+        if is_streaming:
+            if return_type is not str:
+                raise RuntimeError(
+                    "Streaming responses are only supported for str return types."
+                )
+            if tools:
+                raise RuntimeError(
+                    "Streaming responses are not supported with tool calls yet."
+                )
+
+        # TODO: Support mockllm for mocktesting.
+        # Invoke streaming request, this will result in a generator that the caller
+        # should either do .next() or .__iter__() by calling `for tok in resp: ...`
+        if is_streaming and tools:
+            raise RuntimeError(
+                "Streaming responses are not supported with tool calls yet."
+            )
+
+        if len(tools) > 0:
+            finish_tool = Tool.make_finish_tool(return_type or str)
+            tools.append(finish_tool)
+
+        return MTIR(
+            messages=messages,
+            tools=tools,
+            resp_type=return_type,
+            stream=is_streaming,
+            call_params=call_params,
+        )
+
+    def dispatch_params(self) -> dict[str, object]:
+        """Dispatch the parameters for the MTIR."""
+        params = {
+            "messages": self.get_msg_list(),
+            "tools": self.get_tool_list() or None,
+            "response_format": self.get_output_schema(),
+            "temperature": self.call_params.get("temperature", 0.7),
+            # "max_tokens": self.call_params.get("max_tokens", 100),
+            # "top_k": self.call_params.get("top_k", 50),
+            # "top_p": self.call_params.get("top_p", 0.9),
+        }
+        return params
+
+    def add_message(self, message: MessageType) -> None:
+        """Add a message to the request."""
+        self.messages.append(message)
+
+    def get_msg_list(self) -> list[dict[str, object] | LiteLLMMessage]:
+        """Return the messages in a format suitable for LLM API."""
+        return [
+            msg.to_dict() if isinstance(msg, Message) else msg for msg in self.messages
+        ]
+
+    def parse_response(self, response: str) -> object:
+        """Parse the response from the LLM."""
+        # To use validate_json the string should contains quotes.
+        #     example: '"The weather at New York is sunny."'
+        # but the response from LLM will not have quotes, so
+        # we need to check if it's string and return early.
+        if self.resp_type is None or self.resp_type is str or response.strip() == "":
+            return response
+        if self.resp_type:
+            json_dict = json.loads(response)
+            return json_to_instance(json_dict, self.resp_type)
+        return response
+
+    def get_tool(self, tool_name: str) -> Tool | None:
+        """Get a tool by its name."""
+        for tool in self.tools:
+            if tool.func.__name__ == tool_name:
+                return tool
+        return None
+
+    def get_tool_list(self) -> list[dict]:
+        """Return the tools in a format suitable for LLM API."""
+        return [tool.get_json_schema() for tool in self.tools]
+
+    def get_output_schema(self) -> dict | None:
+        """Return the JSON schema for the response type."""
+        assert (
+            len(self.tools) == 0 or self.get_tool("finish_tool") is not None
+        ), "Finish tool should be present in the tools list."
+        if len(self.tools) == 0 and self.resp_type:
+            if self.resp_type is str:
+                return None  # Strings are default and not using a schema.
+            return type_to_schema(self.resp_type)
+        # If the are tools, the final output will be sent to the finish_tool
+        # thus there is no output schema.
+        return None

byllm/plugin.py

@@ -0,0 +1,40 @@
+"""Plugin for Jac's with_llm feature."""
+
+from typing import Callable
+
+from byllm.llm import Model
+from byllm.mtir import MTIR
+
+from jaclang.runtimelib.machine import hookimpl
+
+
+class JacMachine:
+    """Jac's with_llm feature."""
+
+    @staticmethod
+    @hookimpl
+    def call_llm(model: Model, mtir: MTIR) -> object:
+        """Call JacLLM and return the result."""
+        return model.invoke(mtir=mtir)
+
+
+def by(model: Model) -> Callable:
+    """Python library mode decorator for Jac's by llm() syntax."""
+
+    def _decorator(caller: Callable) -> Callable:
+        def _wrapped_caller(*args: object, **kwargs: object) -> object:
+            invoke_args: dict[int | str, object] = {}
+            for i, arg in enumerate(args):
+                invoke_args[i] = arg
+            for key, value in kwargs.items():
+                invoke_args[key] = value
+            mtir = MTIR.factory(
+                caller=caller,
+                args=invoke_args,
+                call_params=model.llm_connector.call_params,
+            )
+            return JacMachine.call_llm(model, mtir)
+
+        return _wrapped_caller
+
+    return _decorator

byllm/schema.py

@@ -0,0 +1,265 @@
+"""Schema generation for OpenAI compatible APIs.
+
+This module provides functionality to generate JSON schemas for classes and types
+and to validate instances against these schemas.
+"""
+
+from dataclasses import is_dataclass
+from enum import Enum
+from types import FunctionType, UnionType
+from typing import Callable, Union, get_args, get_origin, get_type_hints
+
+from pydantic import TypeAdapter
+
+
+_SCHEMA_OBJECT_WRAPPER = "schema_object_wrapper"
+_SCHEMA_DICT_WRAPPER = "schema_dict_wrapper"
+
+
+def _type_to_schema(ty: type, title: str = "", desc: str = "") -> dict:
+
+    title = title.replace("_", " ").title()
+    context = ({"title": title} if title else {}) | (
+        {"description": desc} if desc else {}
+    )
+
+    semstr: str = ty._jac_semstr if hasattr(ty, "_jac_semstr") else ""
+    semstr = semstr or (ty.__doc__ if hasattr(ty, "__doc__") else "") or ""  # type: ignore
+
+    semstr_inner: dict[str, str] = (
+        ty._jac_semstr_inner if hasattr(ty, "_jac_semstr_inner") else {}
+    )
+
+    # Raise on unsupported types
+    if ty in (list, dict, set, tuple):
+        raise ValueError(
+            f"Untyped {ty.__name__} is not supported for schema generation. "
+            f"Use {ty.__name__}[T, ...] instead."
+        )
+
+    # Handle primitive types
+    if ty is type(None):
+        return {"type": "null"} | context
+    if ty is bool:
+        return {"type": "boolean"} | context
+    if ty is int:
+        return {"type": "integer"} | context
+    if ty is float:
+        return {"type": "number"} | context
+    if ty is str:
+        return {"type": "string"} | context
+
+    # Handle Union
+    if get_origin(ty) in (Union, UnionType):
+        args = get_args(ty)
+        return {
+            "anyOf": [_type_to_schema(arg) for arg in args],
+            "title": title,
+        } | context
+
+    # Handle annotated list
+    if get_origin(ty) is list:
+        item_type: type = get_args(ty)[0]
+        return {
+            "type": "array",
+            "items": _type_to_schema(item_type),
+        } | context
+
+    # Handle annotated tuple/set
+    if get_origin(ty) in (tuple, set):
+        origin = get_origin(ty).__name__  # type: ignore
+        args = get_args(ty)
+        if len(args) == 2 and args[1] is Ellipsis:
+            item_type = args[0]
+            return {
+                "type": "array",
+                "items": _type_to_schema(item_type),
+            } | context
+        raise ValueError(
+            f"Unsupported {origin} type for schema generation: {ty}. "
+            f"Only {origin} of the form {origin}[T, ...] are supported."
+        )
+
+    # Handle annotated dictionaries
+    if get_origin(ty) is dict:
+        return _convert_dict_to_schema(ty) | context
+
+    # Handle dataclass
+    if is_dataclass(ty):
+        fields: dict[str, type] = {
+            name: type
+            for name, type in get_type_hints(ty).items()
+            if not name.startswith("_")
+        }
+        properties = {
+            name: _type_to_schema(type, name, semstr_inner.get(name, ""))  # type: ignore
+            for name, type in fields.items()
+        }
+        return {
+            "title": title or ty.__name__,
+            "description": semstr,
+            "type": "object",
+            "properties": properties,
+            "required": list(fields.keys()),
+            "additionalProperties": False,
+        }
+
+    # Handle enums
+    if isinstance(ty, type) and issubclass(ty, Enum):
+        enum_type = None
+        enum_values = []
+        for member in ty.__members__.values():
+            enum_values.append(member.value)
+            if enum_type is None:
+                enum_type = type(member.value)
+            elif type(member.value) is not enum_type:
+                raise ValueError(
+                    f"Enum {ty.__name__} has mixed types. Not supported for schema generation."
+                )
+            enum_type = enum_type or int
+        enum_desc = f"\nThe value *should* be one in this list: {enum_values}"
+        if enum_type not in (int, str):
+            raise ValueError(
+                f"Enum {ty.__name__} has unsupported type {enum_type}. "
+                "Only int and str enums are supported for schema generation."
+            )
+        return {
+            "description": semstr + enum_desc,
+            "type": "integer" if enum_type is int else "string",
+        }
+
+    # Handle functions
+    if isinstance(ty, FunctionType):
+        hints = get_type_hints(ty)
+        hints.pop("return", None)
+        params = {
+            name: _type_to_schema(type, name, semstr_inner.get(name, ""))
+            for name, type in hints.items()
+        }
+        return {
+            "title": title or ty.__name__,
+            "type": "function",
+            "description": semstr,
+            "properties": params,
+            "required": list(params.keys()),
+            "additionalProperties": False,
+        }
+
+    raise ValueError(
+        f"Unsupported type for schema generation: {ty}. "
+        "Only primitive types, dataclasses, and Union types are supported."
+    )
+
+
+def _name_of_type(ty: type) -> str:
+    if get_origin(ty) in (Union, UnionType):
+        names = [_name_of_type(arg) for arg in get_args(ty)]
+        return "_or_".join(names)
+    if hasattr(ty, "__name__"):
+        return ty.__name__
+    return "type"
+
+
+def _convert_dict_to_schema(ty_dict: type) -> dict:
+    """Convert a dictionary type to a schema."""
+    if get_origin(ty_dict) is not dict:
+        raise ValueError(f"Expected a dictionary type, got {ty_dict}.")
+    key_type, value_type = get_args(ty_dict)
+    return {
+        "type": "object",
+        "title": _SCHEMA_DICT_WRAPPER,
+        "properties": {
+            _SCHEMA_DICT_WRAPPER: {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "key": _type_to_schema(key_type),
+                        "value": _type_to_schema(value_type),
+                    },
+                    "required": ["key", "value"],
+                    "additionalProperties": False,
+                },
+            }
+        },
+        "additionalProperties": False,
+        "required": [_SCHEMA_DICT_WRAPPER],
+    }
+
+
+def _decode_dict(json_obj: dict) -> dict:
+    """Decode a JSON dictionary to a Python dictionary."""
+    if not isinstance(json_obj, dict):
+        return json_obj
+    if _SCHEMA_DICT_WRAPPER in json_obj:
+        items = json_obj[_SCHEMA_DICT_WRAPPER]
+        return {item["key"]: _decode_dict(item["value"]) for item in items}
+    return {key: _decode_dict(value) for key, value in json_obj.items()}
+
+
+def _wrap_to_object(schema: dict[str, object]) -> dict[str, object]:
+    """Wrap the schema in an object with a type."""
+    if "type" in schema and schema["type"] == "object":
+        return schema
+    return {
+        "type": "object",
+        "title": _SCHEMA_OBJECT_WRAPPER,
+        "properties": {
+            _SCHEMA_OBJECT_WRAPPER: schema,
+        },
+        "required": [_SCHEMA_OBJECT_WRAPPER],
+        "additionalProperties": False,
+    }
+
+
+def _unwrap_from_object(json_obj: dict) -> dict:
+    """Unwrap the schema from an object with a type."""
+    if _SCHEMA_OBJECT_WRAPPER in json_obj:
+        return json_obj[_SCHEMA_OBJECT_WRAPPER]
+    return json_obj
+
+
+def type_to_schema(resp_type: type) -> dict[str, object]:
+    """Return the JSON schema for the response type."""
+    type_name = _name_of_type(resp_type)
+    schema = _type_to_schema(resp_type, type_name)
+    schema = _wrap_to_object(schema)
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": type_name,
+            "schema": schema,
+            "strict": True,
+        },
+    }
+
+
+def tool_to_schema(
+    func: Callable, description: str, params_desc: dict[str, str]
+) -> dict[str, object]:
+    """Return the JSON schema for the tool type."""
+    schema = _type_to_schema(func)  # type: ignore
+    properties: dict[str, object] = schema.get("properties", {})  # type: ignore
+    required: list[str] = schema.get("required", [])  # type: ignore
+    for param_name, param_info in properties.items():
+        param_info["description"] = params_desc.get(param_name, "")  # type: ignore
+    return {
+        "type": "function",
+        "function": {
+            "name": func.__name__,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+                "additionalProperties": False,
+            },
+        },
+    }
+
+
+def json_to_instance(json_obj: dict, ty: type) -> object:
+    """Convert a JSON dictionary to an instance of the given type."""
+    json_obj = _unwrap_from_object(json_obj)
+    json_obj = _decode_dict(json_obj)
+    return TypeAdapter(ty).validate_python(json_obj)

byllm/types.py

@@ -0,0 +1,346 @@
+"""Type definitions for LLM interactions.
+
+This module defines the types used in the LLM interactions, including messages,
+tools, and tool calls. It provides a structured way to represent messages,
+tool calls, and tools that can be used in LLM requests and responses.
+"""
+
+import base64
+import mimetypes
+import os
+from dataclasses import dataclass
+from enum import StrEnum
+from io import BytesIO
+from typing import Callable, TypeAlias, get_type_hints
+
+from PIL.Image import open as open_image
+
+from litellm.types.utils import Message as LiteLLMMessage
+
+from pydantic import TypeAdapter
+
+from .schema import tool_to_schema
+
+# The message can be a jaclang defined message or what ever the llm
+# returned object that was feed back to the llm as it was given (dict).
+MessageType: TypeAlias = "Message | LiteLLMMessage"
+
+
+class MessageRole(StrEnum):
+    """Enum for message roles in LLM interactions."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+@dataclass
+class Message:
+    """Message class for LLM interactions."""
+
+    role: MessageRole
+    content: "str | list[Media]"
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert the message to a dictionary."""
+        if isinstance(self.content, str):
+            return {
+                "role": self.role.value,
+                "content": self.content,
+            }
+
+        media_contents = []
+        for media in self.content:
+            media_contents.extend(media.to_dict())
+        return {
+            "role": self.role.value,
+            "content": media_contents,
+        }
+
+
+@dataclass
+class ToolCallResultMsg(Message):
+    """Result of a tool call in LLM interactions."""
+
+    tool_call_id: str
+    name: str  # Function name.
+
+    def __post_init__(self) -> None:
+        """Post-initialization to set the role of the message."""
+        self.role = MessageRole.TOOL  # Maybe this should be an assertion?
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert the tool call result message to a dictionary."""
+        return {
+            "role": self.role.value,
+            "content": self.content,
+            "tool_call_id": self.tool_call_id,
+            "name": self.name,
+        }
+
+
+@dataclass
+class Tool:
+    """Tool class for LLM interactions."""
+
+    func: Callable
+    description: str = ""
+    params_desc: dict[str, str] = None  # type: ignore
+
+    def __post_init__(self) -> None:
+        """Post-initialization to validate the function."""
+        self.func.__annotations__ = get_type_hints(self.func)
+        self.description = Tool.get_func_description(self.func)
+        if hasattr(self.func, "_jac_semstr_inner"):
+            self.params_desc = self.func._jac_semstr_inner  # type: ignore
+        else:
+            self.params_desc = {
+                name: str(type) for name, type in self.func.__annotations__.items()
+            }
+
+    def __call__(self, *args: list, **kwargs: dict) -> object:
+        """Call the tool function with the provided arguments."""
+        # If there is an error with the finish tool, we throw the exception.
+        # Since it's the user's responsibility to handle it.
+        if self.is_finish_tool():
+            return self.func(*args, **kwargs)
+        try:
+            # TODO: Shoud I json serialize or this is fine?
+            return self.func(*args, **kwargs)
+        except Exception as e:
+            # For the LLM if the tool failed, it'll see the error message
+            # and make decision based on that.
+            return str(e)
+
+    def get_name(self) -> str:
+        """Return the name of the tool function."""
+        return self.func.__name__
+
+    @staticmethod
+    def get_func_description(func: Callable) -> str:
+        """Get the description of the function."""
+        if hasattr(func, "_jac_semstr"):
+            return func._jac_semstr  # type: ignore
+        return func.__doc__ or func.__name__
+
+    @staticmethod
+    def make_finish_tool(resp_type: type) -> "Tool":
+        """Create a finish tool that returns the final output."""
+
+        def finish_tool(final_output: object) -> object:
+            return TypeAdapter(resp_type).validate_python(final_output)
+
+        finish_tool.__annotations__["return"] = resp_type
+        finish_tool.__annotations__["final_output"] = resp_type
+        return Tool(
+            func=finish_tool,
+            description="This tool is used to finish the tool calls and return the final output.",
+            params_desc={
+                "final_output": "The final output of the tool calls.",
+            },
+        )
+
+    def is_finish_tool(self) -> bool:
+        """Check if the tool is a finish tool."""
+        return self.get_name() == "finish_tool"
+
+    def get_json_schema(self) -> dict[str, object]:
+        """Return the JSON schema for the tool function."""
+        return tool_to_schema(self.func, self.description, self.params_desc)
+
+    def parse_arguments(self, args_json: dict) -> dict:
+        """Parse the arguments from JSON to the function's expected format."""
+        args = {}
+        annotations = self.func.__annotations__
+        for arg_name, arg_json in args_json.items():
+            if arg_type := annotations.get(arg_name):
+                args[arg_name] = TypeAdapter(arg_type).validate_python(arg_json)
+        return args
+
+
+@dataclass
+class ToolCall:
+    """Tool call class for LLM interactions."""
+
+    call_id: str
+    tool: Tool
+    args: dict
+
+    def __call__(self) -> ToolCallResultMsg:
+        """Call the tool with the provided arguments."""
+        result = self.tool(**self.args)
+        return ToolCallResultMsg(
+            role=MessageRole.TOOL,
+            content=str(result),
+            tool_call_id=self.call_id,
+            name=self.tool.get_name(),
+        )
+
+    def __str__(self) -> str:
+        """Return the string representation of the tool call."""
+        params = ", ".join(f"{k}={v}" for k, v in self.args.items())
+        return f"{self.tool.get_name()}({params})"
+
+    def is_finish_call(self) -> bool:
+        """Check if the tool is a finish tool."""
+        return self.tool.is_finish_tool()
+
+    def get_output(self) -> object:
+        """Get the output from the finish tool call."""
+        assert (
+            self.is_finish_call()
+        ), "This method should only be called for finish tools."
+        return self.tool(**self.args)
+
+
+@dataclass
+class MockToolCall:
+    """Mock tool call for testing purposes."""
+
+    tool: Callable
+    args: dict
+
+    def to_tool_call(self) -> ToolCall:
+        """Convert the mock tool call to a ToolCall."""
+        return ToolCall(
+            call_id="",  # Call ID is not used in mock calls.
+            tool=Tool(self.tool),
+            args=self.args,
+        )
+
+
+@dataclass
+class CompletionResult:
+    """Result of the completion from the LLM."""
+
+    output: object
+    tool_calls: list[ToolCall]
+
+
+# -----------------------------------------------------------------------------
+# Media content types
+# -----------------------------------------------------------------------------
+
+
+@dataclass
+class Media:
+    """Base class for message content."""
+
+    def to_dict(self) -> list[dict]:
+        """Convert the content to a dictionary."""
+        raise NotImplementedError("Subclasses must implement this method.")
+
+
+@dataclass
+class Text(Media):
+    """Class representing text content in a message."""
+
+    text: str
+
+    def to_dict(self) -> list[dict]:
+        """Convert the text content to a dictionary."""
+        return [{"type": "text", "text": self.text}]
+
+
+@dataclass
+class Image(Media):
+    """Class representing an image."""
+
+    url: str
+    mime_type: str | None = None
+
+    def __post_init__(self) -> None:
+        """Post-initialization to ensure the URL is a string."""
+        if self.url.startswith(("http://", "https://", "gs://")):
+            self.url = self.url.strip()
+        else:
+            if not os.path.exists(self.url):
+                raise ValueError(f"Image file does not exist: {self.url}")
+            image = open_image(self.url)
+
+            # python<3.13 mimetypes doesn't support `webp` format as it wasn't an IANA standard
+            # until November 2024 (RFC-9649:  https://www.rfc-editor.org/rfc/rfc9649.html).
+            if (image.format and image.format.lower()) == "webp":
+                self.mime_type = "image/webp"
+            else:
+                self.mime_type = mimetypes.types_map.get(
+                    "." + (image.format or "png").lower()
+                )
+            with BytesIO() as buffer:
+                image.save(buffer, format=image.format, quality=100)
+                base64_image = base64.b64encode(buffer.getvalue()).decode("utf-8")
+                self.url = f"data:{self.mime_type};base64,{base64_image}"
+
+    def to_dict(self) -> list[dict]:
+        """Convert the image to a dictionary."""
+        image_url = {"url": self.url}
+        if self.mime_type:
+            image_url["format"] = self.mime_type
+        return [
+            {
+                "type": "image_url",
+                "image_url": image_url,
+            }
+        ]
+
+
+# Ref: https://cookbook.openai.com/examples/gpt_with_vision_for_video_understanding
+@dataclass
+class Video(Media):
+    """Class representing a video."""
+
+    path: str
+    fps: int = 1
+    _base64frames: list[str] | None = None
+
+    def __post_init__(self) -> None:
+        """Post-initialization to ensure the path is a string."""
+        if not os.path.exists(self.path):
+            raise ValueError(f"Video file does not exist: {self.path}")
+
+    def load_frames(self) -> None:
+        """Load video frames as base64-encoded images."""
+        try:
+            import cv2
+        except ImportError:
+            raise ImportError(
+                "OpenCV is required to process video files."
+                "Install `pip install byllm[video]` for video capabilities."
+            )
+
+        self._base64frames = []
+        video = cv2.VideoCapture(self.path)
+        total_frames = int(video.get(cv2.CAP_PROP_FRAME_COUNT))
+
+        target_fps = self.fps
+        source_fps = video.get(cv2.CAP_PROP_FPS)
+        frames_to_skip = (
+            int(source_fps / target_fps) - 1 if target_fps < source_fps else 1
+        )
+
+        curr_frame = 0
+        while curr_frame < total_frames - 1:
+            video.set(cv2.CAP_PROP_POS_FRAMES, curr_frame)
+            success, frame = video.read()
+            if not success:
+                raise ValueError("Failed to read video frame.")
+            _, buffer = cv2.imencode(".jpg", frame)
+            self._base64frames.append(base64.b64encode(buffer).decode("utf-8"))
+            curr_frame += frames_to_skip
+
+    def to_dict(self) -> list[dict]:
+        """Convert the video to a dictionary."""
+        if self._base64frames is None:
+            self.load_frames()
+        assert (
+            self._base64frames is not None
+        ), "Frames must be loaded before conversion."
+
+        return [
+            {
+                "type": "image_url",
+                "image_url": f"data:image/jpeg;base64,{frame}",
+            }
+            for frame in self._base64frames
+        ]

byllm-0.4.1.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.3
+Name: byllm
+Version: 0.4.1
+Summary: byLLM Provides Easy to use APIs for different LLM Providers to be used with Jaseci's Jaclang Programming Language.
+License: MIT
+Keywords: llm,jaclang,jaseci,byLLM
+Author: Jason Mars
+Author-email: jason@jaseci.org
+Maintainer: Jason Mars
+Maintainer-email: jason@jaseci.org
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: tools
+Provides-Extra: video
+Requires-Dist: jaclang (==0.8.5)
+Requires-Dist: litellm (>=1.75.5.post1)
+Requires-Dist: loguru (>=0.7.2,<0.8.0)
+Requires-Dist: pillow (>=10.4.0,<10.5.0)
+Description-Content-Type: text/markdown
+
+# byLLM - AI Integration Framework for Jac-lang
+
+[![PyPI version](https://img.shields.io/pypi/v/mtllm.svg)](https://pypi.org/project/mtllm/) [![tests](https://github.com/jaseci-labs/jaseci/actions/workflows/test-jaseci.yml/badge.svg?branch=main)](https://github.com/jaseci-labs/jaseci/actions/workflows/test-jaseci.yml)
+
+Meaning Typed Programming (MTP) is a programming paradigm for AI integration where prompt engineering is hidden through code semantics. byLLM is the plugin built, exploring this hypothesis. byLLM is built as a plugin to the Jaseci ecosystem. This plugin can be installed as a PyPI package.
+
+```bash
+pip install byllm
+```
+
+## Basic Example
+
+A basic usecase of MTP can be demonstrated as follows:
+
+```python
+import from byllm {Model}
+
+glob llm = Model(model_name="openai\gpt-4o");
+
+def translate_to(language: str, phrase: str) -> str by llm();
+
+with entry {
+    output = translate_to(language="Welsh", phrase="Hello world");
+    print(output);
+}
+```
+
+## AI-Powered Object Generation
+
+```python
+import from byllm {Model}
+
+glob llm = Model(model_name="gpt-4o");
+
+obj Task {
+    has description: str,
+        priority: int,
+        estimated_time: int;
+}
+
+sem Task.priority = "priority between 0 (highest priority) and 10(lowest priority)";
+
+def create_task(description: str, previous_tasks: list[Task]) -> Task by llm();
+
+with entry {
+    tasks = [];
+    new_task = create_task("Write documentation for the API", tasks);
+    print(f"Task: {new_task.description}, Priority: {new_task.priority}, Time: {new_task.estimated_time}min");
+}
+```
+
+The `by` abstraction allows to automate semantic extraction from existing code semantics, eliminating manual prompt engineering while leveraging type annotations for structured AI responses.
+
+## Documentation and Examples
+
+**📚 Full Documentation**: [Jac byLLM Documentation](https://www.jac-lang.org/learn/jac-byllm/with_llm/)
+
+**🎮 Complete Examples**:
+- [Fantasy Trading Game](https://www.jac-lang.org/learn/examples/mtp_examples/fantasy_trading_game/) - Interactive RPG with AI-generated characters
+- [RPG Level Generator](https://www.jac-lang.org/learn/examples/mtp_examples/rpg_game/) - AI-powered game level creation
+- [RAG Chatbot Tutorial](https://www.jac-lang.org/learn/examples/rag_chatbot/Overview/) - Building chatbots with document retrieval
+
+**🔬 Research**: The research journey of MTP is available on [Arxiv](https://arxiv.org/abs/2405.08965).
+
+## Quick Links
+
+- [Getting Started Guide](https://www.jac-lang.org/learn/jac-byllm/with_llm/)
+- [Model Configuration](https://www.jac-lang.org/learn/jac-byllm/model_declaration/)
+- [Jac Language Documentation](https://www.jac-lang.org/)
+- [GitHub Repository](https://github.com/jaseci-labs/jaseci)

byllm-0.4.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+byllm/__init__.py,sha256=Iqi_KAnRkr5vC9OYMWa9e5vZE3PiR2ror_Th1wa8F9Q,226
+byllm/llm.py,sha256=fjraqQaT1uiwxTjLW7Wm8TDnnl7N5xDztA2KhyUfIQE,3560
+byllm/llm_connector.py,sha256=XK8ftsafTYWq7aAjDxk4R4OeyJ1P1ou2qrZAXOU9xmU,8546
+byllm/mtir.py,sha256=V4fpc0-j_7pb8rVMV8yskc9XczUCtHczrj5OZGXKA8g,7083
+byllm/plugin.py,sha256=T_uSAkiyuPiufo5SEUNcgMOU0Ns5Zbg7BPfMo_ihC9s,1132
+byllm/schema.py,sha256=PGaEiNlbm9CjIJu1lE2kv8QrfudfD2I3LvHfkMqxQkI,8812
+byllm/types.py,sha256=Uh6j0AcdHZ0zZ_KESu-ZBBpI9yoA7kw4yU550N4E-Tk,11117
+byllm-0.4.1.dist-info/METADATA,sha256=RQYnecvetizswVO-4TmSJ6r3G4aFrgkK99rjnK_isw0,3990
+byllm-0.4.1.dist-info/WHEEL,sha256=5druYqcII7zHXzX7qmN0TH895Jg3yuTtfjMgJIVBrKE,92
+byllm-0.4.1.dist-info/entry_points.txt,sha256=hUzQdaP8qTKkAqHfBpcqxQK02wixeyyzx3y-s6KyrQg,37
+byllm-0.4.1.dist-info/RECORD,,

byllm-0.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py2.py3-none-any

byllm-0.4.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[jac]
+byllm=byllm.plugin:JacMachine
+