janito 1.14.3__py3-none-any.whl → 2.0.0__py3-none-any.whl

janito/llm/driver.py

@@ -0,0 +1,239 @@
+import threading
+from abc import ABC, abstractmethod
+from queue import Queue
+from janito.llm.driver_input import DriverInput
+from janito.driver_events import (
+    RequestStarted,
+    RequestFinished,
+    ResponseReceived,
+    RequestStatus,
+)
+
+
+class LLMDriver(ABC):
+    def clear_output_queue(self):
+        """Remove all items from the output queue."""
+        try:
+            while True:
+                self.output_queue.get_nowait()
+        except Exception:
+            pass
+
+    """
+    Abstract base class for LLM drivers (threaded, queue-based).
+    Subclasses must implement:
+      - _call_api: Call provider API with DriverInput.
+      - _convert_completion_message_to_parts: Convert provider message to MessagePart objects.
+      - convert_history_to_api_messages: Convert LLMConversationHistory to provider-specific messages format for API calls.
+    Workflow:
+      - Accept DriverInput via input_queue.
+      - Put DriverEvents on output_queue.
+      - Use start() to launch worker loop in a thread.
+    The driver automatically creates its own input/output queues, accessible via .input_queue and .output_queue.
+    """
+
+    available = True
+    unavailable_reason = None
+
+    def __init__(self, tools_adapter=None, provider_name=None):
+        self.input_queue = Queue()
+        self.output_queue = Queue()
+        self._thread = None
+        self.tools_adapter = tools_adapter
+        self.provider_name = provider_name
+
+    def start(self):
+        """Validate tool schemas (if any) and launch the driver's background thread to process DriverInput objects."""
+        # Validate all tool schemas before starting the thread
+        if self.tools_adapter is not None:
+            from janito.tools.tools_schema import ToolSchemaBase
+            validator = ToolSchemaBase()
+            for tool in self.tools_adapter.get_tools():
+                # Validate the tool's class (not instance)
+                validator.validate_tool_class(tool.__class__)
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def _run(self):
+        while True:
+            driver_input = self.input_queue.get()
+            if driver_input is None:
+                break  # Sentinel received, exit thread
+            try:
+                # Only process if driver_input is a DriverInput instance
+                if isinstance(driver_input, DriverInput):
+                    self.process_driver_input(driver_input)
+                else:
+                    # Optionally log or handle unexpected input types
+                    pass
+            except Exception as e:
+                import traceback
+
+                self.output_queue.put(
+                    RequestFinished(
+                        driver_name=self.__class__.__name__,
+                        request_id=getattr(driver_input.config, "request_id", None),
+                        status=RequestStatus.ERROR,
+                        error=str(e),
+                        exception=e,
+                        traceback=traceback.format_exc(),
+                    )
+                )
+
+    def handle_driver_unavailable(self, request_id):
+        self.output_queue.put(
+            RequestFinished(
+                driver_name=self.__class__.__name__,
+                request_id=request_id,
+                status=RequestStatus.ERROR,
+                error=self.unavailable_reason,
+                exception=ImportError(self.unavailable_reason),
+                traceback=None,
+            )
+        )
+
+    def emit_response_received(
+        self, driver_name, request_id, result, parts, timestamp=None, metadata=None
+    ):
+        self.output_queue.put(
+            ResponseReceived(
+                driver_name=driver_name,
+                request_id=request_id,
+                parts=parts,
+                tool_results=[],
+                timestamp=timestamp,
+                metadata=metadata or {},
+            )
+        )
+        # Debug: print summary of parts by type
+        if hasattr(self, "config") and getattr(self.config, "verbose_api", False):
+            from collections import Counter
+
+            type_counts = Counter(type(p).__name__ for p in parts)
+            print(
+                f"[verbose-api] Emitting ResponseReceived with parts: {dict(type_counts)}",
+                flush=True,
+            )
+
+    def process_driver_input(self, driver_input: DriverInput):
+
+        config = driver_input.config
+        request_id = getattr(config, "request_id", None)
+        if not self.available:
+            self.handle_driver_unavailable(request_id)
+            return
+        self.output_queue.put(
+            RequestStarted(
+                driver_name=self.__class__.__name__,
+                request_id=request_id,
+                payload={"provider_name": self.provider_name},
+            )
+        )
+        # Check for cancel_event before starting
+        if (
+            hasattr(driver_input, "cancel_event")
+            and driver_input.cancel_event is not None
+            and driver_input.cancel_event.is_set()
+        ):
+            self.output_queue.put(
+                RequestFinished(
+                    driver_name=self.__class__.__name__,
+                    request_id=request_id,
+                    status=RequestStatus.CANCELLED,
+                    reason="Canceled before start",
+                )
+            )
+            return
+        try:
+            result = self._call_api(driver_input)
+            # If result is None and cancel_event is set, treat as cancelled
+            if (
+                hasattr(driver_input, "cancel_event")
+                and driver_input.cancel_event is not None
+                and driver_input.cancel_event.is_set()
+            ):
+                self.output_queue.put(
+                    RequestFinished(
+                        driver_name=self.__class__.__name__,
+                        request_id=request_id,
+                        status=RequestStatus.CANCELLED,
+                        reason="Cancelled during processing (post-API)",
+                    )
+                )
+                return
+            if (
+                result is None
+                and hasattr(driver_input, "cancel_event")
+                and driver_input.cancel_event is not None
+                and driver_input.cancel_event.is_set()
+            ):
+                # Already handled by driver
+                return
+            # Check for cancel_event after API call (subclasses should also check during long calls)
+            if (
+                hasattr(driver_input, "cancel_event")
+                and driver_input.cancel_event is not None
+                and driver_input.cancel_event.is_set()
+            ):
+                self.output_queue.put(
+                    RequestFinished(
+                        driver_name=self.__class__.__name__,
+                        request_id=request_id,
+                        status=RequestStatus.CANCELLED,
+                        reason="Canceled during processing",
+                    )
+                )
+                return
+            message = self._get_message_from_result(result)
+            parts = (
+                self._convert_completion_message_to_parts(message) if message else []
+            )
+            timestamp = getattr(result, "created", None)
+            metadata = {"usage": getattr(result, "usage", None), "raw_response": result}
+            self.emit_response_received(
+                self.__class__.__name__, request_id, result, parts, timestamp, metadata
+            )
+        except Exception as ex:
+            import traceback
+
+            self.output_queue.put(
+                RequestFinished(
+                    driver_name=self.__class__.__name__,
+                    request_id=request_id,
+                    status=RequestStatus.ERROR,
+                    error=str(ex),
+                    exception=ex,
+                    traceback=traceback.format_exc(),
+                )
+            )
+
+    @abstractmethod
+    def _prepare_api_kwargs(self, config, conversation):
+        """
+        Subclasses must implement: Prepare API kwargs for the provider, including any tool schemas if needed.
+        """
+        pass
+
+    @abstractmethod
+    def _call_api(self, driver_input: DriverInput):
+        """Subclasses implement: Use driver_input to call provider and return result object."""
+        pass
+
+    @abstractmethod
+    def _convert_completion_message_to_parts(self, message):
+        """Subclasses implement: Convert provider message to list of MessagePart objects."""
+        pass
+
+    @abstractmethod
+    def convert_history_to_api_messages(self, conversation_history):
+        """
+        Subclasses implement: Convert LLMConversationHistory to the messages object required by their provider API.
+        :param conversation_history: LLMConversationHistory instance
+        :return: Provider-specific messages object (e.g., list of dicts for OpenAI)
+        """
+        pass
+
+    @abstractmethod
+    def _get_message_from_result(self, result):
+        """Extract the message object from the provider result. Subclasses must implement this."""
+        raise NotImplementedError("Subclasses must implement _get_message_from_result.")

janito/llm/driver_config.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class LLMDriverConfig:
+    # For OpenAI and similar providers that distinguish between completion and response tokens
+    max_completion_tokens: Optional[int] = None
+    verbose_api: Optional[bool] = None
+    """
+    Common configuration container for LLM drivers.
+    - verbose_api: Print API trace info if set
+    
+    Holds standard attributes that most LLM drivers require (used as a config or schema reference object).
+    Inspired by the OpenAI driver, but fields are generic for most LLM backends.
+    """
+    model: str = None  # Model is required but can be set from CLI
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    max_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    top_p: Optional[float] = None
+    presence_penalty: Optional[float] = None
+    frequency_penalty: Optional[float] = None
+    stop: Optional[Any] = None  # list or string, depending on backend
+    extra: dict = field(
+        default_factory=dict
+    )  # for provider-specific miscellaneous config fields
+
+    def to_dict(self) -> dict:
+        d = self.__dict__.copy()
+        d.update(d.pop("extra", {}))
+        # Remove Nones (for compatibility)
+        return {k: v for k, v in d.items() if v is not None}

janito/llm/driver_config_builder.py

@@ -0,0 +1,34 @@
+from typing import Type, Dict, Any
+from janito.llm.driver_config import LLMDriverConfig
+
+
+def build_llm_driver_config(
+    config: Dict[str, Any], driver_class: Type
+) -> LLMDriverConfig:
+    """
+    Build an LLMDriverConfig instance for the given driver class based on its declared driver_fields.
+    Only fills fields missing from given config; does not overwrite fields already provided.
+    Any config fields not in driver_fields or LLMDriverConfig fields go into .extra.
+    """
+    driver_fields = getattr(driver_class, "driver_fields", None)
+    if driver_fields is None:
+        driver_fields = set(LLMDriverConfig.__dataclass_fields__.keys()) - {
+            "model",
+            "extra",
+        }
+    base_info = {}
+    extra = {}
+    for k, v in (config or {}).items():
+        if k in driver_fields and k in LLMDriverConfig.__dataclass_fields__:
+            base_info[k] = v
+        else:
+            extra[k] = v
+    # Only set missing fields, do NOT overwrite those from CLI/user
+    for field in driver_fields:
+        if field not in base_info and field in LLMDriverConfig.__dataclass_fields__:
+            base_info[field] = (
+                None  # Optional: replace None with provider/driver default if wanted
+            )
+    return LLMDriverConfig(
+        model=config.get("model") or config.get("model_name"), extra=extra, **base_info
+    )

janito/llm/driver_input.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass, field
+from typing import Optional
+import threading
+from janito.llm.driver_config import LLMDriverConfig
+from janito.conversation_history import LLMConversationHistory
+
+
+@dataclass
+class DriverInput:
+    config: LLMDriverConfig
+    conversation_history: LLMConversationHistory
+    cancel_event: Optional[threading.Event] = field(default=None)

janito/llm/message_parts.py

@@ -0,0 +1,60 @@
+import attr
+
+
+class MessagePart:
+    """
+    Base class for all driver message parts.
+    """
+
+    type: str
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class TextMessagePart(MessagePart):
+    content: str = ""
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class InlineDataMessagePart(MessagePart):
+    content: bytes = b""
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class FileDataMessagePart(MessagePart):
+    content: str = ""
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class VideoMetadataMessagePart(MessagePart):
+    content: dict = attr.Factory(dict)
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class CodeExecutionResultMessagePart(MessagePart):
+    content: str = ""
+    stdout: str = ""
+    stderr: str = ""
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ExecutableCodeMessagePart(MessagePart):
+    content: str = ""
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class FunctionCallMessagePart(MessagePart):
+    tool_call_id: str = ""
+    function: object = (
+        None  # Should match OpenAI SDK structure (with arguments as JSON string)
+    )
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class FunctionResponseMessagePart(MessagePart):
+    name: str = ""
+    content: dict = attr.Factory(dict)
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ThoughtMessagePart(MessagePart):
+    content: bool = False

janito/llm/model.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class LLMModelInfo:
+    name: str
+    context: Any = "N/A"
+    max_input: Any = "N/A"
+    max_cot: Any = "N/A"
+    max_response: Any = "N/A"
+    thinking_supported: Any = "N/A"
+    default_temp: float = 0.2
+    open: Optional[Any] = None
+    category: Optional[str] = None
+    driver: Optional[str] = None
+    # This enables arbitrary provider-specific metadata
+    other: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = self.__dict__.copy()
+        if not self.open:
+            d.pop("open")
+        if not self.category:
+            d.pop("category")
+        if not self.driver:
+            d.pop("driver")
+        if not self.other:
+            d.pop("other")
+        return d
+
+    @staticmethod
+    def get_model_info(model_specs):
+        """
+        Standard get_model_info implementation for all providers:
+        returns a list of model info dicts, one per model in the given MODEL_SPECS dict.
+        """
+        return [m.to_dict() for m in model_specs.values()]

janito/llm/provider.py

@@ -0,0 +1,187 @@
+from abc import ABC, abstractmethod
+import importlib
+from janito.llm.driver import LLMDriver
+
+
+class LLMProvider(ABC):
+    def create_driver(self):
+        """
+        Returns a new instance of the configured driver for this provider.
+        Subclasses must implement this method.
+        """
+        raise NotImplementedError(
+            "LLMProvider subclasses must implement create_driver()."
+        )
+
+    """
+    Abstract base class for Large Language Model (LLM) providers.
+
+    Provider Usage and Driver Communication Flow:
+      1. Provider class is selected (e.g., OpenAIProvider, MistralProvider).
+      2. An instance of the provider is created. This instance is bound to a specific configuration (LLMDriverConfig) containing model, credentials, etc.
+      3. All drivers created by that provider instance are associated with the bound config.
+      4. To communicate with an LLM, call create_driver() on the provider instance, which yields a driver configured for the attached config. Every driver created via this method inherits the provider's configuration.
+
+    Key: You do not create/configure a driver directly—always go through the provider to ensure correct configuration binding to the provider instance.
+
+    Subclasses must implement the core interface for interacting with LLM APIs and define `provider_name` as a class attribute.
+    """
+
+    name: str = None  # Must be set on subclasses
+    DEFAULT_MODEL: str = None  # Should be set by subclasses
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if (
+            not hasattr(cls, "name")
+            or not isinstance(getattr(cls, "name"), str)
+            or not cls.name
+        ):
+            raise TypeError(
+                f"Class {cls.__name__} must define a class attribute 'name' (non-empty str)"
+            )
+        if (
+            not hasattr(cls, "DEFAULT_MODEL")
+            or getattr(cls, "DEFAULT_MODEL", None) is None
+        ):
+            raise TypeError(
+                f"Class {cls.__name__} must define a class attribute 'DEFAULT_MODEL' (non-empty str)"
+            )
+
+    def fill_missing_device_info(self, config):
+        """
+        Fill missing LLMDriverConfig fields (max_tokens, temperature, etc) from MODEL_SPECS for the chosen model.
+        Mutates the config in place.
+        """
+        if not hasattr(self, "MODEL_SPECS"):
+            return
+        model_name = getattr(config, "model", None) or getattr(
+            self, "DEFAULT_MODEL", None
+        )
+        model_info = self.MODEL_SPECS.get(model_name)
+        if not model_info:
+            return
+        # Handle common fields from model_info
+        spec_dict = (
+            model_info.to_dict() if hasattr(model_info, "to_dict") else dict(model_info)
+        )
+        if (
+            hasattr(config, "max_tokens")
+            and getattr(config, "max_tokens", None) is None
+        ):
+            val = spec_dict.get("max_tokens") or spec_dict.get("max_response")
+            if val is not None:
+                try:
+                    config.max_tokens = int(val)
+                except Exception:
+                    pass
+        if (
+            hasattr(config, "temperature")
+            and getattr(config, "temperature", None) is None
+        ):
+            val = spec_dict.get("temperature")
+            if val is None:
+                val = spec_dict.get("default_temp")
+            if val is not None:
+                try:
+                    config.temperature = float(val)
+                except Exception:
+                    pass
+
+    @property
+    @abstractmethod
+    def driver(self) -> LLMDriver:
+        pass
+
+    def get_model_info(self, model_name=None):
+        """
+        Return the info dict for a given model (driver, params, etc). If model_name is None, return all model info dicts.
+        MODEL_SPECS must be dict[str, LLMModelInfo].
+        """
+        if not hasattr(self, "MODEL_SPECS"):
+            raise NotImplementedError(
+                "This provider does not have a MODEL_SPECS attribute."
+            )
+        if model_name is None:
+            return {
+                name: model_info.to_dict()
+                for name, model_info in self.MODEL_SPECS.items()
+            }
+        if model_name in self.MODEL_SPECS:
+            return self.MODEL_SPECS[model_name].to_dict()
+        return None
+
+    def _validate_model_specs(self):
+        if not hasattr(self, "MODEL_SPECS"):
+            raise NotImplementedError(
+                "This provider does not have a MODEL_SPECS attribute."
+            )
+
+    def _get_model_name_from_config(self, config):
+        return (config or {}).get("model_name", getattr(self, "DEFAULT_MODEL", None))
+
+    def _get_model_spec_entry(self, model_name):
+        spec = self.MODEL_SPECS.get(model_name, None)
+        if spec is None:
+            raise ValueError(f"Model '{model_name}' not found in MODEL_SPECS.")
+        return spec
+
+    def _get_driver_name_from_spec(self, spec):
+        driver_name = None
+        if hasattr(spec, "driver") and spec.driver:
+            driver_name = spec.driver
+        elif hasattr(spec, "other") and isinstance(spec.other, dict):
+            driver_name = spec.other.get("driver", None)
+        return driver_name
+
+    def _resolve_driver_class(self, driver_name):
+        if not driver_name:
+            raise NotImplementedError(
+                "No driver class found or specified for this MODEL_SPECS entry."
+            )
+        module_root = "janito.drivers"
+        probable_path = None
+        mapping = {
+            "OpenAIResponsesModelDriver": "openai_responses.driver",
+            "OpenAIModelDriver": "openai.driver",
+            "AzureOpenAIModelDriver": "azure_openai.driver",
+            "GoogleGenaiModelDriver": "google_genai.driver",
+        }
+        if driver_name in mapping:
+            probable_path = mapping[driver_name]
+            module_path = f"{module_root}.{probable_path}"
+            mod = importlib.import_module(module_path)
+            return getattr(mod, driver_name)
+        # Attempt dynamic fallback based on convention
+        if driver_name.endswith("ModelDriver"):
+            base = driver_name[: -len("ModelDriver")]
+            mod_name = base.replace("_", "").lower()
+            module_path = f"{module_root}.{mod_name}.driver"
+            try:
+                mod = importlib.import_module(module_path)
+                return getattr(mod, driver_name)
+            except Exception:
+                pass
+        raise NotImplementedError(
+            "No driver class found for driver_name: {}".format(driver_name)
+        )
+
+    def _validate_required_config(self, driver_class, config, driver_name):
+        required = getattr(driver_class, "required_config", None)
+        if required:
+            missing = [
+                k
+                for k in required
+                if not config or k not in config or config.get(k) in (None, "")
+            ]
+            if missing:
+                raise ValueError(
+                    f"Missing required config for {driver_name}: {', '.join(missing)}"
+                )
+
+    def create_agent(self, tools_adapter=None, agent_name: str = None, **kwargs):
+        from janito.llm.agent import LLMAgent
+
+        # Dynamically create driver if supported, else fallback to existing.
+        driver = self.driver
+        return LLMAgent(self, tools_adapter, agent_name=agent_name, **kwargs)

janito/perf_singleton.py

@@ -0,0 +1,3 @@
+from janito.performance_collector import PerformanceCollector
+
+performance_collector = PerformanceCollector()