zrb 1.5.8__py3-none-any.whl → 1.5.10__py3-none-any.whl

zrb/builtin/llm/tool/file.py

@@ -132,9 +132,7 @@ def list_files(
                     all_files.append(full_path)
         # Return paths relative to the original path requested
         try:
-            rel_files = [
-                os.path.relpath(f, os.path.dirname(abs_path)) for f in all_files
-            ]
+            rel_files = [os.path.relpath(f, abs_path) for f in all_files]
             return json.dumps({"files": sorted(rel_files)})
         except (
             ValueError

zrb/llm_config.py

@@ -5,62 +5,45 @@ from pydantic_ai.models.openai import OpenAIModel
 from pydantic_ai.providers import Provider
 from pydantic_ai.providers.openai import OpenAIProvider
 
+from zrb.util.string.conversion import to_boolean
+
 DEFAULT_SYSTEM_PROMPT = """
-You are a highly capable AI assistant with access to tools. Your primary goal is to
-provide accurate, reliable, and helpful responses.
-
-Key Instructions:
-1.  **Prioritize Tool Use:** Always attempt to use available tools to find
-    information or perform actions before asking the user.
-2.  **Correct Tool Invocation:** Use tools precisely as defined. Provide arguments
-    in valid JSON where required. Do not pass arguments to tools that don't accept
-    them. Handle tool errors gracefully and retry or adapt your strategy if necessary.
-3.  **Accuracy is Paramount:** Ensure all information, code, or outputs provided are
-    correct and reliable. Verify facts and generate executable code when requested.
-4.  **Clarity and Conciseness:** Respond clearly and directly to the user's query
-    after gathering the necessary information. Avoid unnecessary conversation.
-5.  **Context Awareness:** Understand the user's request fully to provide the most
-    relevant and effective assistance.
+You have access to tools.
+Your goal is to complete the user's task efficiently.
+Analyze the request and use the available tools proactively to achieve the goal.
+Infer parameters and actions from the context.
+Do not ask for confirmation unless strictly necessary due to ambiguity or
+missing critical information.
+Apply relevant domain knowledge and best practices.
+Respond directly and concisely upon task completion or when clarification is essential.
 """.strip()
 
 DEFAULT_PERSONA = """
 You are an expert in various fields including technology, science, history, and more.
 """.strip()
 
+# Concise summarization focused on preserving critical context for continuity.
 DEFAULT_SUMMARIZATION_PROMPT = """
-You are a summarization assistant. Your task is to synthesize the provided 
-conversation history and the existing context (which might contain a
-previous 'history_summary') into a comprehensive, updated summary
-Carefully review the '# Current Context' which includes any previous summary
-('history_summary').
-Then, review the '# Conversation History to Summarize'.
-Combine the information from both the existing context/summary and the new
-history. Create a single, coherent summary that captures ALL essential
-information, including:
-- Key decisions made
-- Actions taken (including tool usage and their results)
-- Important facts or data points mentioned
-- Outcomes of discussions or actions
-- Any unresolved questions or pending items
-The goal is to provide a complete yet concise background so that the main
-assistant can seamlessly continue the conversation without losing critical
-context from the summarized parts.
-Output *only* the updated summary text."
+You are a summarization assistant. Create an updated, concise summary integrating
+the previous summary (if any) with the new conversation history.
+Your primary goal is to preserve ALL critical context needed for the main assistant
+to continue the task effectively. This includes key facts, decisions, tool usage
+results, and essential background. Do not omit details that would force the main
+assistant to re-gather information.
+Output *only* the updated summary text.
 """.strip()
 
 DEFAULT_CONTEXT_ENRICHMENT_PROMPT = """
 You are an information extraction assistant.
-Analyze the conversation history and current context to extract key facts such as:
-  - user_name
-  - user_roles
-  - preferences
-  - goals
-  - etc
-Return only a JSON object containing a single key "response",
-whose value is another JSON object with these details.
+Analyze the conversation history and current context to extract key facts like
+user_name, user_roles, preferences, goals, etc.
+Return only a JSON object containing a single key "response", whose value is
+another JSON object with these details.
 If nothing is found, output {"response": {}}.
 """.strip()
 
+DEFAULT_SPECIAL_INSTRUCTION_PROMPT = ""  # Default to empty
+
 
 class LLMConfig:
 
@@ -71,8 +54,12 @@ class LLMConfig:
         default_api_key: str | None = None,
         default_persona: str | None = None,
         default_system_prompt: str | None = None,
+        default_special_instruction_prompt: str | None = None,
         default_summarization_prompt: str | None = None,
         default_context_enrichment_prompt: str | None = None,
+        default_summarize_history: bool | None = None,
+        default_history_summarization_threshold: int | None = None,
+        default_enrich_context: bool | None = None,
     ):
         self._default_model_name = (
             default_model_name
@@ -99,6 +86,11 @@ class LLMConfig:
             if default_persona is not None
             else os.getenv("ZRB_LLM_PERSONA", None)
         )
+        self._default_special_instruction_prompt = (
+            default_special_instruction_prompt
+            if default_special_instruction_prompt is not None
+            else os.getenv("ZRB_LLM_SPECIAL_INSTRUCTION_PROMPT", None)
+        )
         self._default_summarization_prompt = (
             default_summarization_prompt
             if default_summarization_prompt is not None
@@ -109,6 +101,21 @@ class LLMConfig:
             if default_context_enrichment_prompt is not None
             else os.getenv("ZRB_LLM_CONTEXT_ENRICHMENT_PROMPT", None)
         )
+        self._default_summarize_history = (
+            default_summarize_history
+            if default_summarize_history is not None
+            else os.getenv("ZRB_LLM_SUMMARIZE_HISTORY", "true").lower() == "true"
+        )
+        self._default_history_summarization_threshold = (
+            default_history_summarization_threshold
+            if default_history_summarization_threshold is not None
+            else int(os.getenv("ZRB_LLM_HISTORY_SUMMARIZATION_THRESHOLD", "5"))
+        )
+        self._default_enrich_context = (
+            default_enrich_context
+            if default_enrich_context is not None
+            else to_boolean(os.getenv("ZRB_LLM_ENRICH_CONTEXT", "0"))
+        )
         self._default_provider = None
         self._default_model = None
 
@@ -127,17 +134,23 @@ class LLMConfig:
         )
 
     def get_default_system_prompt(self) -> str:
-        system_prompt = (
+        return (
             DEFAULT_SYSTEM_PROMPT
             if self._default_system_prompt is None
             else self._default_system_prompt
         )
-        persona = (
+
+    def get_default_persona(self) -> str:
+        return (
             DEFAULT_PERSONA if self._default_persona is None else self._default_persona
         )
-        if persona is not None:
-            return f"{persona}\n{system_prompt}"
-        return system_prompt
+
+    def get_default_special_instruction_prompt(self) -> str:
+        return (
+            DEFAULT_SPECIAL_INSTRUCTION_PROMPT
+            if self._default_special_instruction_prompt is None
+            else self._default_special_instruction_prompt
+        )
 
     def get_default_summarization_prompt(self) -> str:
         return (
@@ -164,12 +177,24 @@ class LLMConfig:
             provider=self.get_default_model_provider(),
         )
 
+    def get_default_summarize_history(self) -> bool:
+        return self._default_summarize_history
+
+    def get_default_history_summarization_threshold(self) -> int:
+        return self._default_history_summarization_threshold
+
+    def get_default_enrich_context(self) -> bool:
+        return self._default_enrich_context
+
     def set_default_persona(self, persona: str):
         self._default_persona = persona
 
     def set_default_system_prompt(self, system_prompt: str):
         self._default_system_prompt = system_prompt
 
+    def set_default_special_instruction_prompt(self, special_instruction_prompt: str):
+        self._default_special_instruction_prompt = special_instruction_prompt
+
     def set_default_summarization_prompt(self, summarization_prompt: str):
         self._default_summarization_prompt = summarization_prompt
 
@@ -191,5 +216,16 @@ class LLMConfig:
     def set_default_model(self, model: Model | str | None):
         self._default_model = model
 
+    def set_default_summarize_history(self, summarize_history: bool):
+        self._default_summarize_history = summarize_history
+
+    def set_default_history_summarization_threshold(
+        self, history_summarization_threshold: int
+    ):
+        self._default_history_summarization_threshold = history_summarization_threshold
+
+    def set_default_enrich_context(self, enrich_context: bool):
+        self._default_enrich_context = enrich_context
+
 
 llm_config = LLMConfig()

zrb/task/any_task.py

@@ -12,12 +12,28 @@ if TYPE_CHECKING:
 
 
 class AnyTask(ABC):
-    """Abstract base class representing a task in the system.
-
-    This class defines the interface for tasks, including methods for retrieving
-    task metadata (such as name, color, and description), handling inputs and
-    environment variables, and managing task dependencies (upstreams and fallbacks).
-    It also includes methods for running tasks synchronously or asynchronously.
+    """Abstract base class defining the interface for all executable tasks within Zrb.
+
+    This interface specifies the essential properties and methods that any concrete
+    task implementation must provide. It covers:
+
+    - **Metadata:** Properties like `name`, `description`, `color`, and `icon` for
+      identification and UI representation.
+    - **Configuration:** Properties for defining `inputs` (user-provided parameters)
+      and `envs` (environment variables).
+    - **Execution Control:** Properties like `cli_only` to restrict execution context.
+    - **Dependency Management:** Properties for `upstreams` (prerequisites),
+      `fallbacks` (error handling), `successors` (post-completion tasks), and
+      `readiness_checks` (for long-running tasks). Methods like `append_*` allow
+      programmatic modification of these dependencies.
+    - **Context Management:** `get_ctx` method to retrieve the task's specific
+      execution context.
+    - **Execution Methods:** `run` (synchronous) and `async_run` (asynchronous)
+      entry points, along with internal execution helpers (`exec_root_tasks`,
+      `exec_chain`, `exec`) defining the execution lifecycle.
+
+    Concrete task classes (like `BaseTask`) inherit from `AnyTask` and provide
+    the actual implementation for these abstract members.
     """
 
     @property

zrb/task/base/context.py

@@ -0,0 +1,108 @@
+import os
+from typing import TYPE_CHECKING
+
+from zrb.context.any_context import AnyContext
+from zrb.context.any_shared_context import AnySharedContext
+from zrb.env.any_env import AnyEnv
+from zrb.input.any_input import AnyInput
+from zrb.session.any_session import AnySession
+from zrb.task.any_task import AnyTask
+
+if TYPE_CHECKING:
+    # Keep BaseTask under TYPE_CHECKING for functions that need it
+    from zrb.task.base_task import BaseTask
+
+
+def build_task_context(task: AnyTask, session: AnySession) -> AnyContext:
+    """
+    Retrieves the context for the task from the session and enhances it
+    with the task's specific environment variables.
+    """
+    ctx = session.get_ctx(task)
+    # Enhance session ctx with current task env
+    for env in task.envs:
+        env.update_context(ctx)
+    return ctx
+
+
+def fill_shared_context_inputs(
+    task: AnyTask, shared_context: AnySharedContext, str_kwargs: dict[str, str] = {}
+):
+    """
+    Populates the shared context with input values provided via kwargs.
+    """
+    for task_input in task.inputs:
+        if task_input.name not in shared_context.input:
+            str_value = str_kwargs.get(task_input.name, None)
+            task_input.update_shared_context(shared_context, str_value)
+
+
+def fill_shared_context_envs(shared_context: AnySharedContext):
+    """
+    Injects OS environment variables into the shared context if they don't already exist.
+    """
+    os_env_map = {
+        key: val for key, val in os.environ.items() if key not in shared_context.env
+    }
+    shared_context.env.update(os_env_map)
+
+
+def combine_inputs(
+    existing_inputs: list[AnyInput],
+    new_inputs: list[AnyInput | None] | AnyInput | None,
+):
+    """
+    Combines new inputs into an existing list, avoiding duplicates by name.
+    Modifies the existing_inputs list in place.
+    """
+    input_names = [task_input.name for task_input in existing_inputs]
+    if isinstance(new_inputs, AnyInput):
+        new_inputs_list = [new_inputs]
+    elif new_inputs is None:
+        new_inputs_list = []
+    else:
+        new_inputs_list = new_inputs
+
+    for task_input in new_inputs_list:
+        if task_input is None:
+            continue
+        if task_input.name not in input_names:
+            existing_inputs.append(task_input)
+            input_names.append(task_input.name)  # Update names list
+
+
+def get_combined_envs(task: "BaseTask") -> list[AnyEnv]:
+    """
+    Aggregates environment variables from the task and its upstreams.
+    """
+    envs = []
+    for upstream in task.upstreams:
+        envs.extend(upstream.envs)  # Use extend for list concatenation
+
+    # Access _envs directly as task is BaseTask
+    task_envs: list[AnyEnv | None] | AnyEnv | None = task._envs
+    if isinstance(task_envs, AnyEnv):
+        envs.append(task_envs)
+    elif isinstance(task_envs, list):
+        # Filter out None while extending
+        envs.extend(env for env in task_envs if env is not None)
+
+    # Filter out None values efficiently from the combined list
+    return [env for env in envs if env is not None]
+
+
+def get_combined_inputs(task: "BaseTask") -> list[AnyInput]:
+    """
+    Aggregates inputs from the task and its upstreams, avoiding duplicates.
+    """
+    inputs: list[AnyInput] = []
+    for upstream in task.upstreams:
+        combine_inputs(inputs, upstream.inputs)
+
+    # Access _inputs directly as task is BaseTask
+    task_inputs: list[AnyInput | None] | AnyInput | None = task._inputs
+    if task_inputs is not None:
+        combine_inputs(inputs, task_inputs)
+
+    # Filter out None values (although combine_inputs should handle this)
+    return [task_input for task_input in inputs if task_input is not None]

zrb/task/base/dependencies.py

@@ -0,0 +1,57 @@
+from typing import TypeVar
+
+from zrb.task.any_task import AnyTask
+
+T = TypeVar("T", bound="AnyTask")
+
+
+def get_dependency_list(task: AnyTask, attr_name: str) -> list[AnyTask]:
+    """
+    Safely retrieves a list of dependencies (upstreams, fallbacks, etc.)
+    from a task attribute, handling None or single-task values.
+    """
+    dependencies = getattr(task, attr_name, None)
+    if dependencies is None:
+        return []
+    elif isinstance(dependencies, list):
+        # Ensure all elements are AnyTask (or compatible) if needed,
+        # but for now, assume the list contains tasks.
+        return dependencies
+    # Assume it's a single AnyTask instance
+    return [dependencies]
+
+
+def append_dependency(
+    task: T, attr_name: str, dependencies_to_add: AnyTask | list[AnyTask]
+) -> None:
+    """
+    Appends one or more dependencies to the specified attribute list of a task,
+    ensuring the attribute becomes a list and avoiding duplicates.
+
+    Modifies the attribute on the task object directly.
+    """
+    # Retrieve the current list, handling None or single item cases
+    current_deps_list = getattr(task, attr_name, None)
+    if current_deps_list is None:
+        current_deps_list = []
+    elif not isinstance(current_deps_list, list):
+        current_deps_list = [current_deps_list]
+    else:
+        # Create a copy to avoid modifying the original list if no changes occur
+        current_deps_list = list(current_deps_list)
+
+    if isinstance(dependencies_to_add, list):
+        new_deps = dependencies_to_add
+    else:
+        new_deps = [dependencies_to_add]  # Ensure it's always a list
+
+    added = False
+    for dep in new_deps:
+        # Check for existence before appending
+        if dep not in current_deps_list:
+            current_deps_list.append(dep)
+            added = True
+
+    # Update the attribute on the task object only if changes were made
+    if added:
+        setattr(task, attr_name, current_deps_list)