deer-agent-framework 0.0__py3-none-any.whl

deer/prompts/error_explain.py

@@ -0,0 +1,30 @@
+ERROR_EXPLAIN_PROMPT = """
+Execution error:
+{error}
+
+Available tools:
+{tools}
+
+Analysis task:
+Determine whether the failure was caused by one of the following:
+
+1. Missing capability
+- The required operation cannot be performed because no suitable tool exists.
+
+2. Incorrect tool selection
+- A valid tool exists, but the wrong tool was selected.
+
+3. Invalid tool usage
+- A valid tool exists, but it was invoked with invalid arguments, invalid sequencing, or incompatible data.
+
+4. Logic or execution failure
+- The failure originated from executable logic, runtime behavior, or tool-side execution.
+
+Requirements:
+- Analyze the error using ONLY the available tools listed above.
+- Do NOT invent capabilities that are not explicitly available.
+- Explicitly state whether the system lacks the required tooling to complete the task.
+- If a missing capability is detected, identify the exact missing operation.
+- If a valid tool exists, identify which tool should have been used and why.
+- Keep the explanation concise, deterministic, and technical.
+"""

deer/prompts/goal_improvement.py

@@ -0,0 +1,65 @@
+GOAL_IMPROVEMENT_PROMPT = """
+System role:
+You are a deterministic prompt optimizer.
+
+Your task is to improve the user's goal prompt while preserving:
+- original intent,
+- semantic meaning,
+- requested outcome,
+- operational constraints,
+- and domain context.
+
+Do not change the task itself.
+
+The optimization must:
+- increase clarity,
+- reduce ambiguity,
+- improve structural consistency,
+- improve determinism,
+- improve executability,
+- and remove unnecessary wording.
+
+Do NOT:
+- introduce new requirements,
+- invent assumptions,
+- expand scope,
+- add explanations,
+- add conversational filler,
+- or transform concise prompts into verbose prompts.
+
+Prefer:
+- explicit instructions,
+- deterministic wording,
+- structured constraints,
+- normalized terminology,
+- and unambiguous execution semantics.
+
+Agent identity:
+{identity}
+
+The optimized prompt must reflect the agent identity when selecting:
+- terminology,
+- tools,
+- transformations,
+- formatting,
+- assumptions,
+- domain-specific reasoning,
+- and response structure.
+
+The identity provides domain expertise, but does not override deterministic execution rules.
+
+User goal:
+{goal}
+
+Runtime context (Payload):
+{payload}
+(Use the context above, including 'chat_history' if present, to resolve ambiguities, pronouns, or references to previous actions in the 'User goal').
+
+Output rules:
+- Return ONLY the optimized prompt.
+- Do not explain changes.
+- Do not use markdown.
+- Preserve the original language of the user goal.
+- Ensure the optimized goal is self-contained and explicitly mentions any files, entities, or values resolved from the context.
+
+"""

deer/prompts/goal_validation.py

@@ -0,0 +1,31 @@
+GOAL_VERIFIER_PROMPT = """
+Your ONLY task is to RETRIEVE EVIDENCE that can be used to verify whether the already-executed result satisfies the reference goal.
+
+Reference goal:
+{goal}
+
+Rules:
+1. The reference goal is NOT an instruction to execute.
+2. Do NOT perform, repeat, fix, create, write, delete, or modify anything from the reference goal.
+3. Use only available non-state-modifying tools to inspect existing state and retrieve evidence.
+4. Return raw evidence only.
+5. If evidence cannot be retrieved with the available read-only tools, return a concise statement that verification evidence is unavailable.
+"""
+
+VERIFIER_JUDGE_PROMPT = """
+User Goal: {goal}
+
+Verification Evidence (Actual State):
+{evidence}
+
+Task:
+Analyze the Verification Evidence strictly. Does it prove that the User Goal was successfully completed?
+
+Rules:
+- Respond ONLY with JSON.
+- If the evidence shows the goal is NOT met, respond with is_success: false.
+- If the evidence is missing or shows an error, respond with is_success: false.
+
+Response format:
+{{"is_success": bool, "feedback": "string explaining why"}}
+"""

deer/prompts/humanizer.py

@@ -0,0 +1,20 @@
+HUMANIZER_PROMPT = """
+You are a deterministic response synthesizer.
+Your goal is to transform technical execution results into a natural, concise, and helpful response for the user.
+
+Context:
+User Goal: {goal}
+Execution Trace: {trace}
+Final Technical Result: {result}
+
+Rules:
+- Summarize what was accomplished based on the trace.
+- If a file was created or modified, mention it.
+- If information was retrieved, present it clearly.
+- Keep the tone professional and direct.
+- Use the same language as the User Goal.
+- Do not explain the internal steps (s1, s2...) unless necessary for clarity.
+- Output ONLY the final humanized response.
+
+Response:
+"""

deer/prompts/planner.py

@@ -0,0 +1,92 @@
+PLANNER_PROMPT = """
+Sistem role:
+You are a deterministic planner for an agent that executes plans step by step.
+Your job is to transform the user's goal and initial payload into a structurally valid, deterministic, executable plan.
+
+Agent identity:
+{identity}
+(The identity provides domain expertise but does not override deterministic execution rules).
+
+Runtime executor:
+- The Executor does NOT use an LLM and executes the generated plan exactly as written.
+- Every step must be concrete, deterministic, and directly executable.
+- A plan is an ordered list of steps. Each step produces exactly one public output (tool return value or "result" variable).
+- A later step can consume the output of a previous step via "input_from".
+- Inside tool parameters ("params") or logic, you can use "input" to refer to the direct dependency output (from "input_from"), or use a previous step ID (e.g., "s1") to refer to its output.
+- In logic, "context" contains all previous outputs, and "params" are local constants.
+
+Structural & Action Rules:
+- Respond ONLY with valid JSON. No Markdown, no explanations, no text before/after.
+- Root object must contain only a "steps" list.
+- Each step must have: "id" (s1, s2...), "tool", "logic", "input_from", and "params" (a JSON object).
+- Each step must define EXACTLY one action: either "tool" (name from Available tools) or "logic" (Python script).
+- "input_from" must be null or a previous step ID. The first step MUST have "input_from": null.
+
+Logic Script Rules:
+- Use "logic" for deterministic transformations, calculations, or to provide a direct conversational response when no tools are required.
+- Do NOT use "logic" to build large Markdown documents, source-code listings, or reports containing many files.
+- If the task requires presenting large text, file contents, Markdown, or code blocks, keep those values as tool outputs or structured data and let the framework render them after execution.
+- "logic" MUST use Python syntax (True, False, None), NOT JSON (true, false, null).
+- It must assign the final step output to a variable named "result".
+- Prohibited: imports, print, open, eval, exec, functions, classes, loops, try/except, with, global/nonlocal.
+- Available names: input, params, context, pi, abs, min, max, round, str, int, float, len.
+- Prefer simple expressions and short string literals.
+- Avoid f-strings when interpolating dictionaries, tool outputs, JSON-like data, file contents, or any value that may contain braces, quotes, backticks, or newlines.
+- Do not embed Markdown code fences, triple backticks, triple quotes, or complete source files inside "logic".
+- Any multiline Python string MUST use triple quotes, but multiline strings should be avoided except for short messages.
+- A string literal assigned in "logic" should be concise; large content must remain outside "logic".
+- Never place literal newlines inside single-quoted or double-quoted strings.
+- Generated Python code MUST always be syntactically valid.
+
+Failure Handling & Task Limitations:
+- Conversational Goals: If the user goal is purely conversational (greetings, identity questions, or general knowledge) and requires no tools, solve it with a single "logic" step assigning the response to "result".
+- Missing Tools: If the user goal requires a specific technical action (e.g., file manipulation, git operations) for which no tool is available, you MUST return a valid Plan JSON with a single logic step.
+- In the case of missing technical tools, "result" must contain:
+    1. An explicit disclaimer stating that your execution is strictly limited to the provided tools and you cannot perform unauthorized actions.
+    2. A technical explanation of why the specific action cannot be completed.
+- NEVER attempt to bypass missing tools by using prohibited Python features (like 'open', 'os', or 'imports') inside a logic step.
+
+Available tools:
+{tools}
+
+Example of Success (Transforming output from a tool):
+{{
+  "steps": [
+    {{
+      "id": "s1",
+      "tool": "read_file",
+      "params": {{ "path": "hello.txt" }},
+      "input_from": null
+    }},
+    {{
+      "id": "s2",
+      "tool": null,
+      "logic": "result = content.upper()",
+      "input_from": "s1",
+      "params": {{}}
+    }}
+  ]
+}}
+
+Example of Failure (User wants to perform an action, but the specific domain tool is missing entirely from the 'Available tools' list):
+{{
+  "steps": [
+    {{
+      "id": "s1",
+      "tool": null,
+      "logic": "result = 'I cannot perform this task directly because my execution is limited to the provided tools, and no tool matching the required capability is currently available in the system configuration.'",
+      "input_from": null,
+      "params": {{}}
+    }}
+  ]
+}}
+
+
+User goal:
+{goal}
+
+Initial payload:
+{payload}
+
+Generate the final Plan JSON now.
+""".strip()

deer/prompts/response_improvement.py

@@ -0,0 +1,23 @@
+RESPONSE_IMPROVEMENT_PROMPT = """
+You are a deterministic response formatter.
+
+Your only job is formatting.
+
+Rules:
+- NEVER change the semantic meaning.
+- NEVER rewrite sentences.
+- NEVER summarize.
+- NEVER explain.
+- NEVER remove content.
+- ONLY improve formatting.
+- Add Markdown code fences when code is detected.
+- Detect the correct language for code fences when possible.
+- Preserve all code exactly.
+- Preserve indentation exactly.
+- If formatting is already correct, return the original response unchanged.
+- If the format is "markdown" and the text contains Python or Bash code, YOU MUST wrap those code blocks using "~~~" fences (e.g., ~~~python or ~~~bash).
+- Output only the final formatted response.
+
+Original response:
+{response}
+"""

deer/schema/__init__.py

@@ -0,0 +1,2 @@
+from .plan import Step, Plan
+from .io import AgentInput, AgentOutput

deer/schema/io.py

@@ -0,0 +1,40 @@
+import itertools
+from typing import Any, Dict, Optional, List
+from pydantic import BaseModel, Field, create_model
+
+_counter = itertools.count()
+
+
+class AgentInput(BaseModel):
+    goal: str = Field(..., description="Goal or task to fulfill")
+    payload: Dict[str, Any] = Field(default_factory=dict, description="Initial data")
+
+
+class StepTrace(BaseModel):
+    step_id: str
+    tool: str
+    input: Any
+    output: Any
+    error: Optional[str] = None
+
+
+class Trace(BaseModel):
+    steps: List[StepTrace] = Field(default_factory=list)
+
+
+class AgentOutput(BaseModel):
+    result: Any = None
+    trace: List[StepTrace] = Field(default_factory=list)
+    validated: bool = False
+    # image: Optional[str] = None
+
+    @property
+    def text(self):
+        return f"{str(self.result)}"
+
+
+def Return(**fields: Any) -> type[BaseModel]:
+    return create_model(
+        f"InlineModel_{next(_counter)}",
+        **{name: (field_type, ...) for name, field_type in fields.items()},
+    )

deer/schema/plan.py

@@ -0,0 +1,75 @@
+from typing import Optional, List, Dict, Any, NamedTuple
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class Step(BaseModel):
+
+    id: str = Field(..., description="Unique step identifier (e.g., s1, s2)")
+
+    tool: Optional[str] = Field(
+        None, description="Name of the tool to invoke. Optional if 'logic' is provided."
+    )
+
+    logic: Optional[str] = Field(
+        None,
+        description="Restricted Python expression executed by the deterministic runtime.",
+    )
+
+    input_from: Optional[str] = Field(
+        None,
+        description="ID of the previous step whose output will be passed as input.",
+    )
+
+    params: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Literal parameters or configuration for the tool/logic.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_string_nulls(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        for field_name in ("tool", "logic", "input_from"):
+            if data.get(field_name) == "null":
+                data[field_name] = None
+
+        return data
+
+    @field_validator("id")
+    @classmethod
+    def _non_empty_id(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Step.id cannot be empty")
+        return v
+
+    @model_validator(mode="after")
+    def _validate_action(self) -> "Step":
+        has_tool = bool(self.tool and self.tool.strip())
+        has_logic = bool(self.logic and self.logic.strip())
+
+        if has_tool == has_logic:
+            raise ValueError("A step must provide exactly one of 'tool' or 'logic'.")
+
+        return self
+
+
+class Plan(BaseModel):
+
+    steps: List[Step] = Field(
+        default_factory=list,
+        description="Ordered sequence of steps to be executed by the orchestrator.",
+    )
+
+    def step_by_id(self, step_id: str) -> Step:
+        for s in self.steps:
+            if s.id == step_id:
+                return s
+        raise KeyError(f"Step not found: {step_id}")
+
+
+class VerificationResult(NamedTuple):
+    is_success: bool
+    feedback: str
+    verification_plan: Optional[Plan] = None

deer/tools/__init__.py

@@ -0,0 +1,4 @@
+from .base import Tool, ToolProvider
+from .registry import ToolRegistry
+from .decorators import tool
+from deer.schema.io import Return

deer/tools/base.py

@@ -0,0 +1,141 @@
+from abc import ABC, abstractmethod
+from typing import Any, Type
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel
+from pathlib import Path
+import subprocess
+import shlex
+
+
+class ToolProviderError(ValueError):
+    pass
+
+
+class CommandRunnerError(ValueError):
+    pass
+
+
+@dataclass
+class ToolProvider:
+    # jail: Path | str | None = field(default=None, kw_only=True)
+    tools: list[str] | None = field(default=None, kw_only=True)
+
+    def __post_init__(self):
+        # pass
+        self.jail_ = None
+
+    @property
+    def jail(self):
+        assert self.jail_ is not None, (
+            "Filesystem jail is not configured. "
+            "The runtime cannot access the sandbox root path."
+        )
+        return self.jail_
+
+    @jail.setter
+    def jail(self, jail):
+        self.jail_ = Path(jail).resolve(strict=True)
+
+    def jailed_path(self, path: str | Path) -> Path:
+        """
+        Validates and returns a safe path within the jail.
+
+        1. If 'path' is relative, it's joined to the jail.
+        2. If 'path' is absolute, it's checked for containment.
+        3. All '..' and symlinks are resolved before validation.
+        """
+        path = Path(path)
+
+        # Handle point 2: If relative, interpret it as inside the jail.
+        # If absolute, it remains as is to be validated against the jail.
+        if not path.is_absolute():
+            path = self.jail / path
+
+        # Handle point 1: Normalize "..", symlinks, etc.
+        # strict=False allows the path to not exist yet (e.g., for creating files).
+        resolved = path.resolve(strict=False)
+
+        # Real containment verification
+        try:
+            # relative_to raises ValueError if 'resolved' is not a child of 'self.jail'
+            resolved.relative_to(self.jail)
+        except ValueError:
+            raise ToolProviderError(
+                f"Security breach: Path escapes jail: {resolved}"
+            ) from None
+
+        return resolved
+
+    def run_command(
+        self,
+        command: str,
+        *,
+        cwd: str | Path,
+        timeout_seconds: int = 30,
+    ) -> dict:
+        """Execute a command string without invoking a shell."""
+        args = shlex.split(command)
+
+        if not args:
+            raise CommandRunnerError("Command cannot be empty.")
+
+        safe_cwd = self.jail if cwd is None else self.jailed_path(cwd)
+
+        completed = subprocess.run(
+            args,
+            cwd=safe_cwd,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+
+        return {
+            "stdout": completed.stdout,
+            "stderr": completed.stderr,
+            "returncode": completed.returncode,
+        }
+
+
+class Tool(ABC):
+    """Base contract for deterministic tools."""
+
+    # input_schema: Type[Any] | None = None
+    # output_schema: Type[Any] | None = None
+    #
+    # name: str = ""
+    # description: str = ""
+    # modifies_state: bool = False
+
+    def __init__(self) -> None:
+        if not self.name:
+            self.name = self.__class__.__name__.lower()
+
+    def validate_input(self, value: Any) -> Any:
+        return self._validate_with_schema(self.params_type, value)
+
+    def validate_output(self, value: Any) -> Any:
+        return self._validate_with_schema(self.return_type, value)
+
+    def _validate_with_schema(self, schema: Type[Any] | None, value: Any) -> Any:
+        if schema is None:
+            return value
+
+        if isinstance(schema, type) and issubclass(schema, BaseModel):
+            return schema.model_validate(value)
+
+        return value
+
+    @abstractmethod
+    def run(self, params: dict[str, Any] | None = None) -> Any:
+        """Execute the tool deterministically.
+
+        Args:
+            value: Main input value.
+            params: Optional literal parameters.
+
+        Returns:
+            The deterministic output produced by the tool.
+        """
+        raise NotImplementedError

deer/tools/builtin/__init__.py

@@ -0,0 +1,3 @@
+from .file_manager import FileManager
+from .git_manager import GitManager
+from .search_manager import SearchManager

deer/tools/builtin/file_manager.py

@@ -0,0 +1,136 @@
+from deer.tools import ToolProvider, tool, Return
+
+from dataclasses import dataclass
+from pathlib import Path
+import shutil
+
+
+class FileManagerError(ValueError):
+    pass
+
+
+@dataclass
+class FileManager(ToolProvider):
+
+    @tool(modifies_state=True)
+    def new_file(self, path: str, content: str) -> Return(exists=bool):
+        """Creates a new file with the given content."""
+        safe_path = self.jailed_path(path)
+
+        safe_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(safe_path, "w") as f:
+            f.write(content)
+
+        return {
+            "exists": safe_path.exists(),
+        }
+
+    @tool()
+    def read_file(self, path: str) -> Return(content=str):
+        """Reads the content of a file."""
+        safe_path = self.jailed_path(path)
+
+        with open(safe_path, "r") as f:
+            content = f.read()
+        return {
+            "content": content,
+        }
+
+    @tool(modifies_state=True)
+    def delete_file(self, path: str) -> Return(exists=bool):
+        """Deletes a file."""
+        safe_path = self.jailed_path(path)
+
+        if safe_path.is_file():
+            safe_path.unlink()
+        else:
+            raise ValueError(f"'{path}' is not a file or does not exist.")
+
+        return {
+            "exists": not safe_path.exists(),
+        }
+
+    @tool(modifies_state=True)
+    def create_directory(self, path: str) -> Return(status=str):
+        """Creates a directory."""
+        safe_path = self.jailed_path(path)
+        safe_path.mkdir(parents=True, exist_ok=True)
+        return {"status": "success"}
+
+    @tool(modifies_state=True)
+    def delete_directory(self, path: str) -> Return(exists=bool):
+        """Removes a directory and all its contents recursively."""
+        safe_path = self.jailed_path(path)
+
+        if safe_path.is_dir():
+            shutil.rmtree(safe_path)
+        else:
+            raise ValueError(f"'{path}' is not a directory or does not exist.")
+
+        return {
+            "exists": not safe_path.exists(),
+        }
+
+    @tool()
+    def get_file_info(self, path: str) -> Return(
+        exists=bool,
+        size_bytes=int,
+        is_dir=bool,
+        is_file=bool,
+        last_modified=float,
+    ):
+        """Retrieves metadata about a file or directory, including its existence, size, type, and modification time."""
+        safe_path = self.jailed_path(path)
+        if not safe_path.exists():
+            return {"exists": False}
+
+        stats = safe_path.stat()
+        return {
+            "exists": True,
+            "size_bytes": stats.st_size,
+            "is_dir": safe_path.is_dir(),
+            "is_file": safe_path.is_file(),
+            "last_modified": stats.st_mtime,
+        }
+
+    @tool()
+    def directory_tree(self, path: str, max_depth: int) -> Return(tree=dict):
+        """Returns the directory structure as a nested dictionary."""
+        safe_path = self.jailed_path(path)
+
+        if not safe_path.exists():
+            raise FileNotFoundError(f"Path does not exist: {path}")
+
+        if not safe_path.is_dir():
+            raise ValueError(f"Path is not a directory: {path}")
+
+        def build_node(current_path: Path, depth: int = 0) -> dict:
+            relative_path = current_path.relative_to(self.jail)
+
+            node = {
+                "name": current_path.name,
+                "path": str(relative_path),
+                "type": "directory" if current_path.is_dir() else "file",
+            }
+
+            if current_path.is_file():
+                node["size_bytes"] = current_path.stat().st_size
+                return node
+
+            if depth >= max_depth:
+                node["children"] = []
+                node["truncated"] = True
+                return node
+
+            children = sorted(
+                current_path.iterdir(),
+                key=lambda item: (not item.is_dir(), item.name.lower()),
+            )
+
+            node["children"] = [build_node(child, depth + 1) for child in children]
+            return node
+
+        return {
+            "tree": build_node(safe_path),
+        }