zrb 1.9.17__py3-none-any.whl → 1.10.0__py3-none-any.whl

zrb/__init__.py

@@ -107,7 +107,7 @@ if TYPE_CHECKING:
     from zrb.task.base_trigger import BaseTrigger
     from zrb.task.cmd_task import CmdTask
     from zrb.task.http_check import HttpCheck
-    from zrb.task.llm.history import ConversationHistoryData
+    from zrb.task.llm.conversation_history import ConversationHistoryData
     from zrb.task.llm_task import LLMTask
     from zrb.task.make_task import make_task
     from zrb.task.rsync_task import RsyncTask

zrb/builtin/llm/history.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from zrb.config.config import CFG
 from zrb.context.any_shared_context import AnySharedContext
-from zrb.task.llm.history import ConversationHistoryData
+from zrb.task.llm.conversation_history_model import ConversationHistory
 from zrb.util.file import read_file, write_file
 
 
@@ -51,9 +51,7 @@ def read_chat_conversation(ctx: AnySharedContext) -> dict[str, Any] | list | Non
         return None
 
 
-def write_chat_conversation(
-    ctx: AnySharedContext, history_data: ConversationHistoryData
-):
+def write_chat_conversation(ctx: AnySharedContext, history_data: ConversationHistory):
     """Writes the conversation history data (including context) to a session file."""
     os.makedirs(CFG.LLM_HISTORY_DIR, exist_ok=True)
     current_session_name = ctx.session.name

zrb/builtin/llm/tool/cli.py

@@ -1,3 +1,4 @@
+import json
 import subprocess
 
 
@@ -13,17 +14,20 @@ def run_shell_command(command: str) -> str:
         command (str): The exact shell command to execute.
 
     Returns:
-        str: The combined standard output (stdout) and standard error (stderr) from the command. If the command fails, this will contain the error message.
-    Raises:
-        subprocess.CalledProcessError: If the command returns a non-zero exit code, indicating an error.
+        str: A JSON string containing return code, standard output (stdout),
+            and standard error (stderr) from the command.
+            Example: {"return_code": 0, "stdout": "ok", "stderr": ""}
     """
-    try:
-        output = subprocess.check_output(
-            command, shell=True, stderr=subprocess.STDOUT, text=True
-        )
-        return output
-    except subprocess.CalledProcessError as e:
-        # Include the error output in the exception message
-        raise subprocess.CalledProcessError(
-            e.returncode, e.cmd, e.output, e.stderr
-        ) from None
+    result = subprocess.run(
+        command,
+        shell=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.dumps(
+        {
+            "return_code": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+        }
+    )

zrb/builtin/llm/tool/file.py

@@ -218,7 +218,7 @@ def read_from_file(
 
     Returns:
         str: A JSON object containing the file path, the requested content with line numbers, the start and end lines, and the total number of lines in the file.
-             Example: '{"path": "src/main.py", "content": "1: import os\n2: \n3: print(\"Hello, World!\")", "start_line": 1, "end_line": 3, "total_lines": 3}'
+             Example: '{"path": "src/main.py", "content": "1| import os\n2| \n3| print(\"Hello, World!\")", "start_line": 1, "end_line": 3, "total_lines": 3}'
     Raises:
         FileNotFoundError: If the specified file does not exist.
     """
@@ -492,7 +492,7 @@ def read_many_files(paths: List[str]) -> str:
 
     Returns:
         str: A JSON object where keys are the file paths and values are their corresponding contents, prefixed with line numbers. If a file cannot be read, its value will be an error message.
-             Example: '{"results": {"src/api.py": "1: import ...", "config.yaml": "1: key: value"}}'
+             Example: '{"results": {"src/api.py": "1| import ...", "config.yaml": "1| key: value"}}'
     """
     results = {}
     for path in paths:

zrb/builtin/llm/tool/sub_agent.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any, Coroutine
 from zrb.context.any_context import AnyContext
 from zrb.task.llm.agent import create_agent_instance, run_agent_iteration
 from zrb.task.llm.config import get_model, get_model_settings
-from zrb.task.llm.prompt import get_combined_system_prompt
+from zrb.task.llm.prompt import get_system_and_user_prompt
 
 if TYPE_CHECKING:
     from pydantic_ai import Tool
@@ -69,14 +69,12 @@ def create_sub_agent_tool(
         )
 
         if system_prompt is None:
-            resolved_system_prompt = get_combined_system_prompt(
+            resolved_system_prompt, query = get_system_and_user_prompt(
                 ctx=ctx,
+                user_message=query,
                 persona_attr=None,
-                render_persona=False,
                 system_prompt_attr=None,
-                render_system_prompt=False,
                 special_instruction_prompt_attr=None,
-                render_special_instruction_prompt=False,
             )
         else:
             resolved_system_prompt = system_prompt

zrb/config/config.py

@@ -336,10 +336,6 @@ class Config:
         """Number of seconds to sleep when throttling is required."""
         return float(os.getenv("ZRB_LLM_THROTTLE_SLEEP", "1.0"))
 
-    @property
-    def LLM_CONTEXT_ENRICHMENT_PROMPT(self) -> str | None:
-        return os.getenv("ZRB_LLM_CONTEXT_ENRICHMENT_PROMPT", None)
-
     @property
     def LLM_SUMMARIZE_HISTORY(self) -> bool:
         return to_boolean(os.getenv("ZRB_LLM_SUMMARIZE_HISTORY", "true"))
@@ -348,14 +344,6 @@ class Config:
     def LLM_HISTORY_SUMMARIZATION_TOKEN_THRESHOLD(self) -> int:
         return int(os.getenv("ZRB_LLM_HISTORY_SUMMARIZATION_TOKEN_THRESHOLD", "20000"))
 
-    @property
-    def LLM_ENRICH_CONTEXT(self) -> bool:
-        return to_boolean(os.getenv("ZRB_LLM_ENRICH_CONTEXT", "true"))
-
-    @property
-    def LLM_CONTEXT_ENRICHMENT_TOKEN_THRESHOLD(self) -> int:
-        return int(os.getenv("ZRB_LLM_CONTEXT_ENRICHMENT_TOKEN_THRESHOLD", "20000"))
-
     @property
     def LLM_REPO_ANALYSIS_EXTRACTION_TOKEN_THRESHOLD(self) -> int:
         return int(os.getenv("ZRB_LLM_REPO_ANALYSIS_EXTRACTION_TOKEN_LIMIT", "35000"))
@@ -445,5 +433,13 @@ class Config:
             {"VERSION": self.VERSION},
         )
 
+    @property
+    def LLM_CONTEXTUAL_NOTE_FILE(self) -> str:
+        return os.getenv("LLM_CONTEXTUAL_NOTE_FILE", "ZRB_README.md")
+
+    @property
+    def LLM_LONG_TERM_NOTE_PATH(self) -> str:
+        return os.getenv("LLM_LONG_TERM_NOTE_PATH", "~/ZRB_GLOBAL_README.md")
+
 
 CFG = Config()

zrb/config/llm_config.py

@@ -34,13 +34,22 @@ _DEFAULT_INTERACTIVE_SYSTEM_PROMPT = (
     "    *   **CRITICAL:** Immediately after execution, you MUST use a tool "
     "to verify the outcome (e.g., after `write_file`, use `read_file`; "
     "after `rm`, use `ls` to confirm absence).\n\n"
-    "4.  **Report Results:**\n"
-    "    *   Provide a concise summary of the action taken.\n"
-    "    *   **You MUST explicitly state how you verified the action** (e.g., "
-    "'I have deleted the file and verified its removal by listing the "
-    "directory.').\n"
-    "    *   If an error occurs, report the error and the failed verification "
-    "step."
+    "4.  **Report Results and Handle Errors:**\n"
+    "    *   **On Success:** Provide a concise summary of the action taken "
+    "and explicitly state how you verified it.\n"
+    "    *   **On Failure (The Debugging Loop):** If a tool call fails, you "
+    "MUST NOT give up. Instead, you will enter a debugging loop:\n"
+    "        1.  **Analyze:** Scrutinize the complete error message, "
+    "including any `stdout` and `stderr`.\n"
+    "        2.  **Hypothesize:** State a clear, specific hypothesis about "
+    "the root cause of the error.\n"
+    "        3.  **Act:** Propose a concrete, single next step to fix the "
+    "issue. This could be running a command with different parameters, "
+    "modifying a file, or using another tool to gather more context.\n\n"
+    "---\n"
+    "**FINAL REMINDER:** Your last step before responding MUST be to ensure "
+    "you have followed the Execute and Verify (E+V) loop. Do not "
+    "hallucinate verifications."
 ).strip()
 
 _DEFAULT_SYSTEM_PROMPT = (
@@ -50,32 +59,36 @@ _DEFAULT_SYSTEM_PROMPT = (
     "1.  **Plan:** Internally devise a step-by-step plan. This plan MUST "
     "include verification steps for each action.\n\n"
     "2.  **Assess and Decide:** Before executing, you MUST evaluate the risk of "
-    "your plan. For any destructive actions (modifying or deleting data), "
-    "consider the command's nature and target. Based on your assessment, "
-    "decide the appropriate course of action:\n"
+    "your plan. For any destructive actions, consider the command's nature "
+    "and target. Based on your assessment, decide the appropriate course of "
+    "action:\n"
     "    *   **Low/Moderate Risk:** Proceed directly.\n"
     "    *   **High Risk:** Refuse to execute, state your plan, and explain "
     "the risk to the user.\n"
-    "    *   **Extreme Risk (e.g., operating on critical system files):** "
-    "Refuse and explain the danger.\n\n"
-    "3.  **Execute and Verify (The E+V Loop):**\n"
+    "    *   **Extreme Risk:** Refuse and explain the danger.\n\n"
+    "3.  **Execute and Verify (The E+V Loop):\n"
     "    *   Execute each step of your plan.\n"
     "    *   **CRITICAL:** After each step, you MUST use a tool to verify "
     "the outcome (e.g., check exit codes, read back file contents).\n\n"
-    "4.  **Report Final Outcome:**\n"
-    "    *   Provide a concise summary of the result.\n"
-    "    *   **You MUST explicitly state how you verified the final state**.\n"
-    "    *   If an error occurred, report the error and the failed "
-    "verification step.\n\n"
+    "4.  **Report Final Outcome:\n"
+    "    *   **On Success:** Provide a concise summary of the result and "
+    "explicitly state how you verified the final state.\n"
+    "    *   **On Failure:** Report the complete error, including `stdout` "
+    "and `stderr`. Analyze the error and provide a corrected command or a "
+    "clear explanation of the root cause.\n\n"
     "---\n"
     "**FINAL REMINDER:** Your last step before responding MUST be to ensure "
-    "you have followed the Execute and Verify (E+V) loop. If you are about "
-    "to claim an action was taken, you MUST have already completed the "
-    "corresponding verification tool call. Do not hallucinate verifications."
+    "you have followed the Execute and Verify (E+V) loop. Do not "
+    "hallucinate verifications."
 ).strip()
 
 _DEFAULT_SPECIAL_INSTRUCTION_PROMPT = (
     "## Guiding Principles\n"
+    "- **Clarify and Scope First:** Before undertaking any complex task (like "
+    "writing a new feature or a large test suite), you MUST ensure the request "
+    "is not ambiguous. If it is, ask clarifying questions. Propose a concise "
+    "plan or scope and ask for user approval before proceeding. Do not start a "
+    "multi-step task on a vague request.\n"
     "- **Safety First:** Never run commands that are destructive or could "
     "compromise the system without explicit user confirmation. When in "
     "doubt, ask.\n"
@@ -84,6 +97,17 @@ _DEFAULT_SPECIAL_INSTRUCTION_PROMPT = (
     "conventions.\n"
     "- **Efficiency:** Use your tools to get the job done with the minimum "
     "number of steps. Combine commands where possible.\n\n"
+    "## Critical Prohibitions\n"
+    "- **NEVER Assume Dependencies:** Do not use a library or framework unless "
+    "you have first verified it is an existing project dependency (e.g., in "
+    "`package.json`, `requirements.txt`).\n"
+    "- **NEVER Invent Conventions:** You MUST follow the existing conventions "
+    "discovered during your context-gathering phase. Do not introduce a new "
+    "style or pattern without a very good reason and, ideally, user "
+    "confirmation.\n"
+    "- **NEVER Commit Without Verification:** Do not use `git commit` until you "
+    "have staged the changes and run the project's own verification steps "
+    "(tests, linter, build).\n\n"
     "## Common Task Workflows\n\n"
     "**File System Operations:**\n"
     "1.  **Analyze:** Before modifying, read the file or list the "
@@ -92,10 +116,24 @@ _DEFAULT_SPECIAL_INSTRUCTION_PROMPT = (
     "3.  **Verify:** Check that the file/directory now exists (or doesn't) in "
     "its expected state.\n\n"
     "**Code & Software Development:**\n"
-    "1.  **CRITICAL: Gather Context First:** Before writing or modifying any code, "
-    "you MUST gather context to ensure your changes are idiomatic and correct. "
-    "Do not make assumptions. Your primary goal is to fit into the existing "
-    "project seamlessly.\n"
+    "1.  **CRITICAL: Gather Context First:** Before writing or modifying any "
+    "code, you MUST gather context to ensure your changes are idiomatic and "
+    "correct. Do not make assumptions. Your primary goal is to fit into the "
+    "existing project seamlessly.\n"
+    "    *   **Project Structure & Dependencies:** Check for `README.md`, "
+    "`CONTRIBUTING.md`, `package.json`, `pyproject.toml`, `build.gradle`, "
+    "etc., to understand the project's stated goals, dependencies, and "
+    "scripts (for linting, testing, building).\n"
+    "    *   **Code Style & Conventions:** Look for configuration files like "
+    "`.eslintrc`, `.prettierrc`, `.flake8`, or `ruff.toml`. Analyze "
+    "surrounding source files to determine:\n"
+    "        *   **Naming Conventions:** (e.g., `camelCase` vs. `snake_case`).\n"
+    "        *   **Typing Style:** (e.g., `List` from `typing` vs. built-in "
+    "`list`).\n"
+    "        *   **Error Handling:** (e.g., custom exceptions, `try/except` "
+    "blocks, returning error codes).\n"
+    "        *   **Architectural Patterns:** (e.g., is there a service layer? "
+    "Are components organized by feature or by type?).\n"
     "    *   **When writing a new test:** You MUST first read the full source "
     "code of the module(s) you are testing. This will inform you about the "
     "actual implementation, such as its logging methods, error handling, and "
@@ -108,65 +146,83 @@ _DEFAULT_SPECIAL_INSTRUCTION_PROMPT = (
     "context you gathered.\n"
     "3.  **Implement:** Make the changes, strictly adhering to the patterns and "
     "conventions discovered in step 1.\n"
-    "4.  **Verify:** Run all relevant tests, linters, and build commands. If a "
-    "test fails, analyze the error, read the relevant code again, and attempt "
-    "to fix the underlying issue before trying again.\n\n"
+    "4.  **Verify & Debug:** Run all relevant tests, linters, and build "
+    "commands. If a command fails, your immediate next action MUST be to "
+    "enter the **Debugging Loop**: analyze the complete error output (`stdout` "
+    "and `stderr`), hypothesize the root cause. Your next immediate action "
+    "MUST be to execute a single, concrete tool call that attempts to fix "
+    "the issue based on your hypothesis. Do not stop to ask the user for "
+    "confirmation. The goal is to resolve the error autonomously.\n\n"
     "**Research & Analysis:**\n"
     "1.  **Clarify:** Understand the core question and the desired output "
     "format.\n"
     "2.  **Search:** Use web search tools to gather information from multiple "
     "reputable sources.\n"
     "3.  **Synthesize & Cite:** Present the information clearly. For factual "
-    "claims, cite the source URL."
+    "claims, cite the source URL.\n\n"
+    "## Communicating with the User\n"
+    "- **Be Concise:** When reporting results, be brief. Focus on the outcome "
+    "and the verification step.\n"
+    "- **Explain 'Why,' Not Just 'What':** For complex changes or bug fixes, "
+    "briefly explain *why* the change was necessary (e.g., 'The previous code "
+    "was failing because it didn't handle null inputs. I've added a check to "
+    "prevent this.').\n"
+    "- **Structure Your Plans:** When you present a plan for approval, use a "
+    "numbered or bulleted list for clarity."
 ).strip()
 
 
 _DEFAULT_SUMMARIZATION_PROMPT = (
-    "You are a Conversation Historian. Your task is to create a dense, "
-    "structured snapshot of the conversation for the main assistant.\n\n"
-    "You will receive a `Previous Summary` and the `Recent Conversation "
-    "History`. Your goal is to produce an updated, rolling summary. Your "
-    "output MUST be a single block of text with two sections:\n\n"
-    "1.  `## Narrative Summary`\n"
-    "    - **Identify Key Information:** From the `Recent Conversation "
-    "History`, extract critical facts, user decisions, and final outcomes "
-    "of tasks.\n"
-    "    - **Integrate and Condense:** Integrate these key facts into the "
-    "`Previous Summary`. Discard conversational filler and intermediate "
-    "steps of completed tasks (e.g., 'User asked to see file X, I showed "
-    "them' can be discarded if the file was just a step towards a larger "
-    "goal). The summary should reflect the current state of the project or "
-    "conversation, not a log of every single turn.\n\n"
-    "2.  `## Transcript`\n"
-    "    - The Transcript is the assistant's working memory. It MUST "
-    "contain the last few turns of the conversation in full detail.\n"
-    "    - **CRITICAL REQUIREMENT:** The assistant's and user's last response "
-    "MUST be COPIED VERBATIM into the Transcript. NEVER alter or truncate them for any reason"
-).strip()
-
-
-_DEFAULT_CONTEXT_ENRICHMENT_PROMPT = (
-    "You are a ruthless Memory Curator. Your only goal is to produce a "
-    "dense, concise, and up-to-date Markdown block of long-term context. "
-    "You MUST be aggressive in your curation to keep the context small.\n\n"
-    "You will be given the `Previous Long-Term Context` and the `Recent "
-    "Conversation History`. Your job is to return a NEW, UPDATED version of "
-    "the `Long-Term Context` by following these rules:\n\n"
-    "**Curation Rules (You MUST follow these):**\n"
-    "1.  **Integrate, Don't Append:** You MUST merge new facts from the "
-    "`Recent Conversation History` into the `Previous Long-Term Context`. "
-    "Rewrite existing facts to incorporate new details. DO NOT simply "
-    "append new information at the end.\n"
-    "2.  **Discard Ephemeral Details:** You MUST delete temporary states, "
-    "resolved errors, one-off requests, and conversational filler (e.g., 'Okay, "
-    "I will do that now'). The context should be a snapshot of the current "
-    "project state and user preferences, not a log.\n"
-    "3.  **Retain Stable Facts:** You MUST retain durable information such as "
-    "user preferences (e.g., 'I prefer tabs over spaces'), project-level "
-    "decisions, or architectural choices.\n"
-    "4.  **Mark Dynamic Info:** For temporary information that is critical to "
-    "retain (e.g., CWD, the name of a file being actively edited), you MUST "
-    "add a note: `(short-term, must be re-verified)`."
+    "You are a meticulous Conversation Historian agent. Your purpose is to "
+    "process the conversation history and update the assistant's memory "
+    "using your available tools. You will be given the previous summary, "
+    "previous notes, and the latest conversation turns in JSON format.\n\n"
+    "Follow these steps:\n\n"
+    "1.  **Analyze the Recent Conversation:** Review the `Recent Conversation "
+    "(JSON)` to understand what just happened. Identify key facts, user "
+    "intentions, decisions made, and the final outcomes of any tasks.\n\n"
+    "2.  **Update Long-Term Note:**\n"
+    "    - Read the existing `Long Term` note to understand what is already "
+    "known.\n"
+    "    - Identify any new, stable, and globally relevant information from "
+    "the recent conversation. This includes user preferences, high-level "
+    "goals, or facts that will be true regardless of the current working "
+    "directory.\n"
+    "    - If you find such information, use the `write_long_term_note` tool "
+    "to save a concise, updated version of the note. Keep it brief and "
+    "factual.\n\n"
+    "3.  **Update Contextual Note:**\n"
+    "    - Read the existing `Contextual` note.\n"
+    "    - Identify new information relevant *only* to the current project "
+    "or directory. This could be the file the user is working on, the "
+    "specific bug they are fixing, or the feature they are building.\n"
+    "    - Use the `write_contextual_note` tool to save a concise, updated "
+    "note about the current working context. This note should be focused on "
+    "the immediate task at hand.\n\n"
+    "4.  **Update Narrative Summary:**\n"
+    "    - Review the `Past Conversation` summary.\n"
+    "    - Create a new, condensed narrative that integrates the key "
+    "outcomes and decisions from the recent conversation. Discard "
+    "conversational filler. The summary should be a brief story of the "
+    "project's progress.\n"
+    "    - Use the `write_past_conversation_summary` tool to save this new "
+    "summary.\n\n"
+    "5.  **Update Transcript:**\n"
+    "    - **CRITICAL:** Your final and most important task is to create a "
+    "transcript of the last few turns (around 4 turns).\n"
+    "    - From the `Recent Conversation (JSON)`, extract the messages with "
+    "the role `user` and `assistant`. Ignore roles `system` and `tool`.\n"
+    "    - Format the extracted messages into a readable dialog. For example:\n"
+    "      User: <content of user message>\n"
+    "      Assistant: <content of assistant message>\n"
+    "    - If an assistant message contains `tool_calls`, note it like this:\n"
+    "      Assistant (calling tool <tool_name>): <content of assistant message>\n"
+    "    - The content of the user and assistant messages MUST be copied "
+    "verbatim. DO NOT alter, shorten, or summarize them in any way.\n"
+    "    - Use the `write_past_conversation_transcript` tool to save this "
+    "formatted dialog string.\n\n"
+    "Your primary goal is to use your tools to persist these four distinct "
+    "pieces of information accurately and concisely."
 ).strip()
 
 
@@ -293,14 +349,6 @@ class LLMConfig:
             return CFG.LLM_SUMMARIZATION_PROMPT
         return _DEFAULT_SUMMARIZATION_PROMPT
 
-    @property
-    def default_context_enrichment_prompt(self) -> str:
-        if self._default_context_enrichment_prompt is not None:
-            return self._default_context_enrichment_prompt
-        if CFG.LLM_CONTEXT_ENRICHMENT_PROMPT is not None:
-            return CFG.LLM_CONTEXT_ENRICHMENT_PROMPT
-        return _DEFAULT_CONTEXT_ENRICHMENT_PROMPT
-
     @property
     def default_model(self) -> "Model | str | None":
         if self._default_model is not None:
@@ -327,18 +375,6 @@ class LLMConfig:
             return self._default_history_summarization_token_threshold
         return CFG.LLM_HISTORY_SUMMARIZATION_TOKEN_THRESHOLD
 
-    @property
-    def default_enrich_context(self) -> bool:
-        if self._default_enrich_context is not None:
-            return self._default_enrich_context
-        return CFG.LLM_ENRICH_CONTEXT
-
-    @property
-    def default_context_enrichment_token_threshold(self) -> int:
-        if self._default_context_enrichment_token_threshold is not None:
-            return self._default_context_enrichment_token_threshold
-        return CFG.LLM_CONTEXT_ENRICHMENT_TOKEN_THRESHOLD
-
     def set_default_persona(self, persona: str):
         self._default_persona = persona
 
@@ -354,9 +390,6 @@ class LLMConfig:
     def set_default_summarization_prompt(self, summarization_prompt: str):
         self._default_summarization_prompt = summarization_prompt
 
-    def set_default_context_enrichment_prompt(self, context_enrichment_prompt: str):
-        self._default_context_enrichment_prompt = context_enrichment_prompt
-
     def set_default_model_name(self, model_name: str):
         self._default_model_name = model_name
 
@@ -382,16 +415,6 @@ class LLMConfig:
             history_summarization_token_threshold
         )
 
-    def set_default_enrich_context(self, enrich_context: bool):
-        self._default_enrich_context = enrich_context
-
-    def set_default_context_enrichment_token_threshold(
-        self, context_enrichment_token_threshold: int
-    ):
-        self._default_context_enrichment_token_threshold = (
-            context_enrichment_token_threshold
-        )
-
     def set_default_model_settings(self, model_settings: "ModelSettings"):
         self._default_model_settings = model_settings
 

zrb/config/llm_rate_limitter.py

@@ -9,8 +9,19 @@ from zrb.config.config import CFG
 
 
 def _estimate_token(text: str) -> int:
-    enc = tiktoken.encoding_for_model("gpt-4o")
-    return len(enc.encode(text))
+    """
+    Estimates the number of tokens in a given text.
+    Tries to use the 'gpt-4o' model's tokenizer for an accurate count.
+    If the tokenizer is unavailable (e.g., due to network issues),
+    it falls back to a heuristic of 4 characters per token.
+    """
+    try:
+        # Primary method: Use tiktoken for an accurate count
+        enc = tiktoken.encoding_for_model("gpt-4o")
+        return len(enc.encode(text))
+    except Exception:
+        # Fallback method: Heuristic (4 characters per token)
+        return len(text) // 4
 
 
 class LLMRateLimiter:

zrb/task/llm/conversation_history.py

@@ -0,0 +1,128 @@
+import json
+from collections.abc import Callable
+from copy import deepcopy
+from typing import Any
+
+from zrb.attr.type import StrAttr
+from zrb.context.any_context import AnyContext
+from zrb.context.any_shared_context import AnySharedContext
+from zrb.task.llm.conversation_history_model import ConversationHistory
+from zrb.task.llm.typing import ListOfDict
+from zrb.util.attr import get_str_attr
+from zrb.util.file import write_file
+from zrb.util.run import run_async
+
+
+def get_history_file(
+    ctx: AnyContext,
+    conversation_history_file_attr: StrAttr | None,
+    render_history_file: bool,
+) -> str:
+    """Gets the path to the conversation history file, rendering if configured."""
+    return get_str_attr(
+        ctx,
+        conversation_history_file_attr,
+        "",
+        auto_render=render_history_file,
+    )
+
+
+async def read_conversation_history(
+    ctx: AnyContext,
+    conversation_history_reader: (
+        Callable[[AnySharedContext], ConversationHistory | dict | list | None] | None
+    ),
+    conversation_history_file_attr: StrAttr | None,
+    render_history_file: bool,
+    conversation_history_attr: (
+        ConversationHistory
+        | Callable[[AnySharedContext], ConversationHistory | dict | list]
+        | dict
+        | list
+    ),
+) -> ConversationHistory:
+    """Reads conversation history from reader, file, or attribute, with validation."""
+    history_file = get_history_file(
+        ctx, conversation_history_file_attr, render_history_file
+    )
+    # Use the class method defined above
+    history_data = await ConversationHistory.read_from_source(
+        ctx=ctx,
+        reader=conversation_history_reader,
+        file_path=history_file,
+    )
+    if history_data:
+        return history_data
+    # Priority 3: Callable or direct conversation_history attribute
+    raw_data_attr: Any = None
+    if callable(conversation_history_attr):
+        try:
+            raw_data_attr = await run_async(conversation_history_attr(ctx))
+        except Exception as e:
+            ctx.log_warning(
+                f"Error executing callable conversation_history attribute: {e}. "
+                "Ignoring."
+            )
+    if raw_data_attr is None:
+        raw_data_attr = conversation_history_attr
+    if raw_data_attr:
+        # Use the class method defined above
+        history_data = ConversationHistory.parse_and_validate(
+            ctx, raw_data_attr, "attribute"
+        )
+        if history_data:
+            return history_data
+    # Fallback: Return default value
+    return ConversationHistory()
+
+
+async def write_conversation_history(
+    ctx: AnyContext,
+    history_data: ConversationHistory,
+    conversation_history_writer: (
+        Callable[[AnySharedContext, ConversationHistory], None] | None
+    ),
+    conversation_history_file_attr: StrAttr | None,
+    render_history_file: bool,
+):
+    """Writes conversation history using the writer or to a file."""
+    if conversation_history_writer is not None:
+        await run_async(conversation_history_writer(ctx, history_data))
+    history_file = get_history_file(
+        ctx, conversation_history_file_attr, render_history_file
+    )
+    if history_file != "":
+        write_file(history_file, json.dumps(history_data.to_dict(), indent=2))
+
+
+def replace_system_prompt_in_history(
+    history_list: ListOfDict, replacement: str = "<main LLM system prompt>"
+) -> ListOfDict:
+    """
+    Returns a new history list where any part with part_kind 'system-prompt'
+    has its 'content' replaced with the given replacement string.
+    Args:
+        history: List of history items (each item is a dict with a 'parts' list).
+        replacement: The string to use in place of system-prompt content.
+
+    Returns:
+        A deep-copied list of history items with system-prompt content replaced.
+    """
+    new_history = deepcopy(history_list)
+    for item in new_history:
+        parts = item.get("parts", [])
+        for part in parts:
+            if part.get("part_kind") == "system-prompt":
+                part["content"] = replacement
+    return new_history
+
+
+def count_part_in_history_list(history_list: ListOfDict) -> int:
+    """Calculates the total number of 'parts' in a history list."""
+    history_part_len = 0
+    for history in history_list:
+        if "parts" in history:
+            history_part_len += len(history["parts"])
+        else:
+            history_part_len += 1
+    return history_part_len