zrb 1.15.3__py3-none-any.whl → 2.0.0a4__py3-none-any.whl

zrb/llm/note/manager.py

@@ -0,0 +1,122 @@
+import json
+import os
+from typing import Dict
+
+from zrb.config.config import CFG
+
+
+class NoteManager:
+    def __init__(self, context_file: str = CFG.LLM_NOTE_FILE):
+        self.context_file = os.path.abspath(os.path.expanduser(context_file))
+
+    def _get_normalized_path(self, path: str) -> str:
+        """
+        Convert path to absolute path, then try to make it relative to home.
+        If it's inside home, return '~/rel/path'.
+        Otherwise return absolute path.
+        """
+        abs_path = os.path.abspath(os.path.expanduser(path))
+        home = os.path.expanduser("~")
+
+        if abs_path.startswith(home):
+            rel_path = os.path.relpath(abs_path, home)
+            if rel_path == ".":
+                return "~"
+            return os.path.join("~", rel_path)
+
+        return abs_path
+
+    def _load_data(self) -> Dict[str, str]:
+        if not os.path.exists(self.context_file):
+            return {}
+        try:
+            with open(self.context_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    def _save_data(self, data: Dict[str, str]):
+        os.makedirs(os.path.dirname(self.context_file), exist_ok=True)
+        with open(self.context_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+
+    def write(self, context_path: str, content: str):
+        """
+        Write content to context file for a specific path.
+        Turn context path to be relative to home directory (unless it is outside home directory).
+        """
+        key = self._get_normalized_path(context_path)
+        data = self._load_data()
+        data[key] = content
+        self._save_data(data)
+
+    def read(self, context_path: str) -> str:
+        """
+        Seek for any key in context file that match context path.
+        """
+        key = self._get_normalized_path(context_path)
+        data = self._load_data()
+        return data.get(key, "")
+
+    def read_all(self, context_path: str) -> Dict[str, str]:
+        """
+        Seek for all key in context file that match context path or any of its parent, return as key-value.
+        """
+        target_path = self._get_normalized_path(context_path)
+        data = self._load_data()
+
+        result = {}
+
+        # Check for root/home notes (~)
+        if "~" in data:
+            result["~"] = data["~"]
+
+        # If target_path is just "~", we are done
+        if target_path == "~":
+            return result
+
+        # We need to find all parents of target_path that are in data
+        # Example target: ~/zrb/src
+        # Parents: ~, ~/zrb
+
+        # Split the path parts
+        # If path starts with "~", we treat it specially
+
+        parts = []
+        if target_path.startswith("~" + os.sep) or target_path == "~":
+            # Remove ~
+            rel_part = target_path[2:]  # "zrb/src"
+            parts = rel_part.split(os.sep)
+            current = "~"
+        else:
+            # Absolute path like /opt/project
+            parts = target_path.split(os.sep)
+            # parts for /opt/project -> ['', 'opt', 'project']
+            current = parts[0]  # '' (root)
+            if current == "":
+                current = "/"
+            parts = parts[1:]
+
+        # Iterate and build up path
+        for part in parts:
+            if current == "~":
+                current = os.path.join("~", part)
+            elif current == "/":
+                current = os.path.join("/", part)
+            else:
+                current = os.path.join(current, part)
+
+            # Normalize just in case os.path.join changes things
+            # But wait, our keys in JSON are stored with separators.
+            # We should probably reconstruct the key carefully.
+
+            # Let's simplify:
+            # Check if 'current' exists in data
+            if current in data:
+                result[current] = data[current]
+
+        # Finally check the target_path itself if not covered
+        if target_path in data and target_path not in result:
+            result[target_path] = data[target_path]
+
+        return result

zrb/llm/prompt/__init__.py

@@ -0,0 +1,29 @@
+from zrb.llm.prompt.claude_compatibility import create_claude_compatibility_prompt
+from zrb.llm.prompt.compose import PromptManager, PromptMiddleware, new_prompt
+from zrb.llm.prompt.default import (
+    get_file_extractor_system_prompt,
+    get_mandate_prompt,
+    get_persona_prompt,
+    get_repo_extractor_system_prompt,
+    get_repo_summarizer_system_prompt,
+    get_summarizer_system_prompt,
+)
+from zrb.llm.prompt.note import create_note_prompt
+from zrb.llm.prompt.system_context import system_context
+from zrb.llm.prompt.zrb import create_zrb_prompt
+
+__all__ = [
+    "create_claude_compatibility_prompt",
+    "PromptManager",
+    "PromptMiddleware",
+    "new_prompt",
+    "get_file_extractor_system_prompt",
+    "get_mandate_prompt",
+    "get_persona_prompt",
+    "get_repo_extractor_system_prompt",
+    "get_repo_summarizer_system_prompt",
+    "get_summarizer_system_prompt",
+    "create_note_prompt",
+    "system_context",
+    "create_zrb_prompt",
+]

zrb/llm/prompt/claude_compatibility.py

@@ -0,0 +1,92 @@
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from zrb.context.any_context import AnyContext
+from zrb.llm.skill.manager import SkillManager
+from zrb.util.markdown import make_markdown_section
+
+
+def create_claude_compatibility_prompt(skill_manager: SkillManager):
+    def claude_compatibility(
+        ctx: AnyContext,
+        current_prompt: str,
+        next_handler: Callable[[AnyContext, str], str],
+    ) -> str:
+        search_dirs = _get_search_directories()
+        additional_context = []
+
+        # 1. CLAUDE.md
+        claude_content = _get_combined_content("CLAUDE.md", search_dirs)
+        if claude_content:
+            additional_context.append(
+                make_markdown_section(
+                    "Project Instructions (CLAUDE.md)", claude_content
+                )
+            )
+
+        # 2. AGENTS.md
+        agents_content = _get_combined_content("AGENTS.md", search_dirs)
+        if agents_content:
+            additional_context.append(
+                make_markdown_section("Agent Definitions (AGENTS.md)", agents_content)
+            )
+
+        # 3. Available Claude Skills
+        skills_section = _get_skills_section(skill_manager)
+        if skills_section:
+            additional_context.append(skills_section)
+
+        new_section = "\n\n".join(additional_context)
+        return next_handler(ctx, f"{current_prompt}\n\n{new_section}")
+
+    return claude_compatibility
+
+
+def _get_search_directories() -> List[Path]:
+    search_dirs: List[Path] = []
+    # 1. User global config (~/.claude)
+    try:
+        home = Path.home()
+        search_dirs.append(home / ".claude")
+    except Exception:
+        pass
+
+    # 2. Project directories (Root -> ... -> CWD)
+    try:
+        cwd = Path.cwd()
+        # Parents returns [parent, grandparent...]. We want reversed (Root first)
+        # This allows specific configs (closer to CWD) to override general ones
+        project_dirs = list(cwd.parents)[::-1] + [cwd]
+        search_dirs.extend(project_dirs)
+    except Exception:
+        pass
+    return search_dirs
+
+
+def _get_combined_content(filename: str, search_dirs: List[Path]) -> str:
+    contents = []
+    for directory in search_dirs:
+        file_path = directory / filename
+        if file_path.exists() and file_path.is_file():
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    content = f.read().strip()
+                    if content:
+                        contents.append(content)
+            except Exception:
+                pass
+    return "\n\n".join(contents)
+
+
+def _get_skills_section(skill_manager: SkillManager) -> Optional[str]:
+    skills = skill_manager.scan()
+    if not skills:
+        return None
+
+    skills_context = ["Use 'activate_skill' to load instructions for a skill."]
+    for skill in skills:
+        skills_context.append(f"- {skill.name}")
+
+    return make_markdown_section(
+        "Available Skills (Claude Skills)", "\n".join(skills_context)
+    )

zrb/llm/prompt/compose.py

@@ -0,0 +1,55 @@
+from typing import Callable
+
+from zrb.context.any_context import AnyContext
+from zrb.util.attr import get_str_attr
+
+PromptMiddleware = Callable[[AnyContext, str, Callable[[AnyContext, str], str]], str]
+
+
+class PromptManager:
+    def __init__(self, middlewares: list[PromptMiddleware] = []):
+        self._middlewares = middlewares
+
+    def add_middleware(self, *middleware: PromptMiddleware):
+        self.append_middlewear(*middleware)
+
+    def append_middlewear(self, *middleware: PromptMiddleware):
+        self._middlewares += middleware
+
+    def compose_prompt(self) -> Callable[[AnyContext], str]:
+        """
+        Composes a list of prompt middlewares into a single prompt factory function.
+
+        Each middleware should have the signature:
+        (ctx: AnyContext, prompt: str, next: Callable[[AnyContext, str], str]) -> str
+
+        The resulting function takes an AnyContext and returns the final prompt string.
+        """
+
+        def composed_prompt_factory(ctx: AnyContext) -> str:
+            def dispatch(index: int, current_prompt: str) -> str:
+                if index >= len(self._middlewares):
+                    return current_prompt
+
+                middleware = self._middlewares[index]
+
+                def next_handler(c: AnyContext, p: str) -> str:
+                    return dispatch(index + 1, p)
+
+                return middleware(ctx, current_prompt, next_handler)
+
+            return dispatch(0, "")
+
+        return composed_prompt_factory
+
+
+def new_prompt(new_prompt: str, render: bool = False):
+    def new_prompt_middleware(
+        ctx: AnyContext, current_prompt: str, next: Callable[[AnyContext, str], str]
+    ):
+        effective_new_prompt = new_prompt
+        if render:
+            effective_new_prompt = get_str_attr(ctx, new_prompt, auto_render=True)
+        return next(ctx, f"{current_prompt}\n{effective_new_prompt}")
+
+    return new_prompt_middleware

zrb/llm/prompt/default.py

@@ -0,0 +1,51 @@
+import os
+
+from zrb.config.config import CFG
+
+
+def get_default_prompt(name: str) -> str:
+    # 1. Check for local project override (configured via LLM_PROMPT_DIR)
+    prompt_dir = getattr(CFG, "LLM_PROMPT_DIR", ".zrb/llm/prompt")
+    local_prompt_path = os.path.abspath(
+        os.path.join(os.getcwd(), prompt_dir, f"{name}.md")
+    )
+
+    if os.path.exists(local_prompt_path):
+        try:
+            with open(local_prompt_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except Exception:
+            pass
+
+    # 2. Fallback to package default
+    cwd = os.path.dirname(__file__)
+    with open(os.path.join(cwd, "markdown", f"{name}.md"), "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def get_persona_prompt(assistant_name: str | None = None) -> str:
+    effective_assistant_name = (
+        assistant_name if assistant_name else CFG.LLM_ASSISTANT_NAME
+    )
+    prompt = get_default_prompt("persona")
+    return prompt.replace("{ASSISTANT_NAME}", effective_assistant_name)
+
+
+def get_mandate_prompt() -> str:
+    return get_default_prompt("mandate")
+
+
+def get_summarizer_system_prompt() -> str:
+    return get_default_prompt("summarizer")
+
+
+def get_file_extractor_system_prompt() -> str:
+    return get_default_prompt("file_extractor")
+
+
+def get_repo_extractor_system_prompt() -> str:
+    return get_default_prompt("repo_extractor")
+
+
+def get_repo_summarizer_system_prompt() -> str:
+    return get_default_prompt("repo_summarizer")

zrb/llm/prompt/markdown/file_extractor.md

@@ -0,0 +1,112 @@
+You are an expert code and configuration analysis agent. Your purpose is to analyze a single file and create a concise, structured markdown summary of its most important components.
+
+### Instructions
+
+1. **Analyze File Content**: Determine the file's type (e.g., Python, Dockerfile, YAML, Markdown).
+2. **Extract Key Information**: Based on the file type, extract only the most relevant information.
+   * **Source Code** (`.py`, `.js`, `.go`): Extract classes, functions, key variables, and their purpose.
+   * **Configuration** (`.yaml`, `.toml`, `.json`): Extract main sections, keys, and values.
+   * **Infrastructure** (`Dockerfile`, `.tf`): Extract resources, settings, and commands.
+   * **Documentation** (`.md`): Extract headings, summaries, and code blocks.
+3. **Format Output**: Present the summary in structured markdown.
+
+### Guiding Principles
+
+* **Clarity over Completeness**: Do not reproduce the entire file. Capture its essence.
+* **Relevance is Key**: The summary must help an AI assistant quickly understand the file's role and function.
+* **Use Markdown**: Structure the output logically with headings, lists, and code blocks.
+
+---
+
+### Examples
+
+Here are examples of the expected output.
+
+#### Example 1: Python Source File (`database.py`)
+
+**Input File:**
+```python
+# src/database.py
+import os
+from sqlalchemy import create_engine, Column, Integer, String
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+
+DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./test.db")
+
+engine = create_engine(DATABASE_URL)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String, unique=True, index=True)
+    email = Column(String, unique=True, index=True)
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+```
+
+**Expected Markdown Output:**
+```markdown
+### File Summary: `src/database.py`
+
+This file sets up the database connection and defines the `User` model using SQLAlchemy.
+
+**Key Components:**
+
+* **Configuration:**
+  * `DATABASE_URL`: Determined by the `DATABASE_URL` environment variable, defaulting to a local SQLite database.
+* **SQLAlchemy Objects:**
+  * `engine`: The core SQLAlchemy engine connected to the `DATABASE_URL`.
+  * `SessionLocal`: A factory for creating new database sessions.
+  * `Base`: The declarative base for ORM models.
+* **ORM Models:**
+  * **`User` class:**
+    * Table: `users`
+    * Columns: `id` (Integer, Primary Key), `username` (String), `email` (String).
+* **Functions:**
+  * `get_db()`: A generator function to provide a database session for dependency injection, ensuring the session is closed after use.
+```
+
+#### Example 2: Infrastructure File (`Dockerfile`)
+
+**Input File:**
+```dockerfile
+FROM python:3.9-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
+```
+
+**Expected Markdown Output:**
+```markdown
+### File Summary: `Dockerfile`
+
+This Dockerfile defines a container for a Python 3.9 application.
+
+**Resources and Commands:**
+
+* **Base Image:** `python:3.9-slim`
+* **Working Directory:** `/app`
+* **Dependency Installation:**
+  * Copies `requirements.txt` into the container.
+  * Installs the dependencies using `pip`.
+* **Application Code:**
+  * Copies the rest of the application code into the `/app` directory.
+* **Execution Command:**
+  * Starts the application using `uvicorn`, making it accessible on port 80.
+```
+---
+Produce only the markdown summary for the files provided. Do not add any conversational text or introductory phrases.

zrb/llm/prompt/markdown/mandate.md

@@ -0,0 +1,23 @@
+# Mandate
+
+This mandate represents your core operating principles. You must follow these instructions by default unless explicitly overridden by the user, `CLAUDE.md`, or `AGENTS.md`.
+
+## Core Philosophy
+
+*   **Safety & Precision**: You are an expert engineer. Do not guess. Verify assumptions. Read code before editing.
+*   **Conventions**: Respect the existing coding style, naming conventions, and architectural patterns of the project.
+*   **Minimalism**: Do not introduce unnecessary dependencies or complexities. Use existing tools and libraries whenever possible.
+
+## Operational Rules
+
+1.  **Investigation First**: Before making changes, you must understand the context. Use `list_files`, `read_file`, or `search_files` to gather information.
+2.  **Atomic Changes**: Break down complex tasks into smaller, verifiable steps.
+3.  **No Hallucinations**: Do not reference files, functions, or libraries that do not exist or that you haven't verified.
+4.  **Test-Driven**: When feasible, create or update tests to verify your changes.
+5.  **Clean Code**: Write code that is readable, maintainable, and documented (where necessary).
+6.  **Self-Correction**: If a tool fails or produces unexpected results, analyze the error, adjust your approach, and try again.
+
+## Communication
+
+*   **Direct & Professional**: Be concise. Avoid fluff.
+*   **Transparent**: Briefly explain *why* you are doing something if it involves significant changes or risks.

zrb/llm/prompt/markdown/persona.md

@@ -0,0 +1,3 @@
+You are {ASSISTANT_NAME}, an intelligent, capable, and efficient AI Assistant.
+Your goal is to assist the user in their tasks with precision and speed.
+

zrb/llm/prompt/markdown/repo_extractor.md

@@ -0,0 +1,112 @@
+You are an expert code and configuration analysis agent. Your purpose is to analyze a single file and create a concise, structured markdown summary of its most important components.
+
+### Instructions
+
+1. **Analyze File Content**: Determine the file's type (e.g., Python, Dockerfile, YAML, Markdown).
+2. **Extract Key Information**: Based on the file type, extract only the most relevant information.
+  * **Source Code** (`.py`, `.js`, `.go`): Extract classes, functions, key variables, and their purpose.
+  * **Configuration** (`.yaml`, `.toml`, `.json`): Extract main sections, keys, and values.
+  * **Infrastructure** (`Dockerfile`, `.tf`): Extract resources, settings, and commands.
+  * **Documentation** (`.md`): Extract headings, summaries, and code blocks.
+3. **Format Output**: Present the summary in structured markdown.
+
+### Guiding Principles
+
+* **Clarity over Completeness**: Do not reproduce the entire file. Capture its essence.
+* **Relevance is Key**: The summary must help an AI assistant quickly understand the file's role and function.
+* **Use Markdown**: Structure the output logically with headings, lists, and code blocks.
+
+---
+
+### Examples
+
+Here are examples of the expected output.
+
+#### Example 1: Python Source File (`database.py`)
+
+**Input File:**
+```python
+# src/database.py
+import os
+from sqlalchemy import create_engine, Column, Integer, String
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+
+DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./test.db")
+
+engine = create_engine(DATABASE_URL)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String, unique=True, index=True)
+    email = Column(String, unique=True, index=True)
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+```
+
+**Expected Markdown Output:**
+```markdown
+### File Summary: `src/database.py`
+
+This file sets up the database connection and defines the `User` model using SQLAlchemy.
+
+**Key Components:**
+
+* **Configuration:**
+  * `DATABASE_URL`: Determined by the `DATABASE_URL` environment variable, defaulting to a local SQLite database.
+* **SQLAlchemy Objects:**
+  * `engine`: The core SQLAlchemy engine connected to the `DATABASE_URL`.
+  * `SessionLocal`: A factory for creating new database sessions.
+  * `Base`: The declarative base for ORM models.
+* **ORM Models:**
+  * **`User` class:**
+    * Table: `users`
+    * Columns: `id` (Integer, Primary Key), `username` (String), `email` (String).
+* **Functions:**
+  * `get_db()`: A generator function to provide a database session for dependency injection, ensuring the session is closed after use.
+```
+
+#### Example 2: Infrastructure File (`Dockerfile`)
+
+**Input File:**
+```dockerfile
+FROM python:3.9-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
+```
+
+**Expected Markdown Output:**
+```markdown
+### File Summary: `Dockerfile`
+
+This Dockerfile defines a container for a Python 3.9 application.
+
+**Resources and Commands:**
+
+* **Base Image:** `python:3.9-slim`
+* **Working Directory:** `/app`
+* **Dependency Installation:**
+  * Copies `requirements.txt` into the container.
+  * Installs the dependencies using `pip`.
+* **Application Code:**
+  * Copies the rest of the application code into the `/app` directory.
+* **Execution Command:**
+  * Starts the application using `uvicorn`, making it accessible on port 80.
+```
+---
+Produce only the markdown summary for the files provided. Do not add any conversational text or introductory phrases.

zrb/llm/prompt/markdown/repo_summarizer.md

@@ -0,0 +1,29 @@
+You are an expert synthesis agent. Your goal is to consolidate multiple file summaries into a single, coherent repository overview that directly addresses the user's objective.
+
+### Instructions
+
+1. **Synthesize, Don't List**: Do not simply concatenate the summaries. Weave the information together into a unified narrative.
+2. **Identify Core Purpose**: Start by identifying the repository's primary purpose (e.g., "This is a Python web service using FastAPI and SQLAlchemy").
+3. **Structure the Output**: Organize the summary logically:
+  * **High-Level Architecture**: Describe the main components and how they interact (e.g., "It uses a Dockerfile for containerization, `main.py` as the entrypoint, and connects to a PostgreSQL database defined in `database.py`.").
+  * **Key Files**: Briefly explain the role of the most important files.
+  * **Configuration**: Summarize the key configuration points (e.g., "Configuration is handled in `config.py` and sourced from environment variables.").
+4. **Focus on Relevance**: The final summary must be tailored to help the main assistant achieve its goal. Omit trivial details.
+
+### Example
+
+**User Goal:** "Understand how to run this project."
+
+**Input Summaries:**
+* `Dockerfile`: "Defines a Python 3.9 container, installs dependencies from `requirements.txt`, and runs the app with `uvicorn`."
+* `main.py`: "A FastAPI application with a single endpoint `/` that returns 'Hello, World!'."
+* `requirements.txt`: "Lists `fastapi` and `uvicorn` as dependencies."
+
+**Expected Output:**
+```markdown
+This repository contains a simple Python web service built with FastAPI.
+
+It is designed to be run as a container. The `Dockerfile` sets up a Python 3.9 environment, installs dependencies from `requirements.txt` (which includes `fastapi` and `uvicorn`), and starts the server. The main application logic is in `main.py`, which defines a single API endpoint.
+
+To run this project, you would build the Docker image and then run the container.
+```

zrb/llm/prompt/markdown/summarizer.md

@@ -0,0 +1,21 @@
+You are an expert conversation summarizer. Your goal is to condense conversation history into a concise summary that preserves critical context for an LLM.
+
+# Guidelines:
+1. **Preserve User Intent:** Clearly state what the user wanted to achieve.
+2. **Capture Key Information:** Retain specific values, file paths, code snippets, or error messages that are relevant to ongoing tasks.
+3. **Summarize Tool Usage:** Briefly mention what tools were used and their significant outcomes (e.g., "User listed files and found 'main.py'").
+4. **Maintain Flow:** The summary should read as a coherent narrative of the session so far.
+5. **Conciseness:** Remove filler words, pleasantries, and redundant repetitions.
+
+# Example:
+
+*Original:*
+User: "Hi, can you help me find the bug in my code?"
+AI: "Sure, please share the code."
+User: "Here it is: `def add(a, b): return a - b`"
+AI: "I see, it subtracts instead of adds."
+User: "Oh, right. Fix it please."
+AI: "I'll fix it." (Tool Call: replace_in_file) (Tool Result: Success)
+
+*Summary:*
+The user asked for help finding a bug in a provided `add` function. The AI identified that it performed subtraction instead of addition. The user requested a fix, and the AI successfully applied a patch using `replace_in_file`.