deer-agent-framework 0.2.3__tar.gz → 0.2.4__tar.gz

{deer_agent_framework-0.2.3/deer_agent_framework.egg-info → deer_agent_framework-0.2.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: deer-agent-framework
-Version: 0.2.3
+Version: 0.2.4
 Summary: DEER - Deterministic Executable Engine for Runtime-agents
-Author: Yeison
+Author: Yeison Cardona
 License: BSD-2-Clause
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -19,18 +19,15 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pydantic>=2.0
-Requires-Dist: rich>=15.0.0
-Requires-Dist: prompt_toolkit>=3.0.52
-Requires-Dist: libcst>=1.8.6
-Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: lxml>=6.1.3
+Requires-Dist: tomlkit>=0.15.1
 Requires-Dist: ruamel.yaml>=0.19.1
-Requires-Dist: lxml>=6.1.1
+Requires-Dist: libcst>=1.9.0
 Requires-Dist: chromadb>=1.5.9
+Requires-Dist: prompt_toolkit>=3.0.53
 Provides-Extra: debug
-Requires-Dist: matplotlib>=3.10.9; extra == "debug"
-Requires-Dist: pandas>=3.0.3; extra == "debug"
-Requires-Dist: pytest>=9.0.3; extra == "debug"
+Requires-Dist: pytest>=9.0.0; extra == "debug"
 Dynamic: license-file
 
 # DEER: Deterministic Executable Engine for Runtime Agents

deer_agent_framework-0.2.4/deer/builtins_agents/deer_introspection.py

@@ -0,0 +1,43 @@
+from deer import DeterministicAgent
+from deer.cli import AgentREPL, get_path_from_parser, get_driver_from_parser
+from deer.drivers import OllamaDriver
+
+from pathlib import Path
+
+# Infrastructure
+driver = get_driver_from_parser() or OllamaDriver(model_name="gemma4:31b-cloud")
+working_dir = get_path_from_parser() or Path.cwd()
+
+DeerIntrospection = DeterministicAgent(
+    description="Professional Auditor for Agent Execution Traces, specializing in tool-use efficiency and operational logic.",
+    identity=(
+        "You are a Technical Auditor of Agent Execution Traces. Your MANDATORY and ONLY focus is to evaluate "
+        "the mechanics of tool usage. You are STRICTLY PROHIBITED from evaluating the correctness, quality, "
+        "or success of the final solution to the problem; the result of the task is COMPLETELY IRRELEVANT "
+        "to your evaluation. An agent that solves the problem but uses tools inefficiently is a FAILURE, "
+        "while an agent that fails to solve the problem but follows a perfect operational process is a SUCCESS. "
+        "Your audit is based on three non-negotiable pillars: "
+        "1. Operational Rigor: You verify a strict logical sequence (e.g., Read $\rightarrow$ Analyze $\rightarrow$ Edit). "
+        "Any 'Blind Edit' (modifying without reading) is a critical error. "
+        "2. The Execution Requirement: You identify 'Ghost Tests'. Creating a reproduction or validation "
+        "script without calling an execution tool (bash/python) to run it is a critical failure. "
+        "3. Context Efficiency: You penalize 'Context Amnesia'—redundant calls to tools for information "
+        "already obtained in the trace. "
+        "If your analysis mentions the correctness of the result, you are violating your core instruction. "
+        "AUDIT THE PROCESS, IGNORE THE OUTCOME."
+        "USE FORMATED MARKDOWN"
+    ),
+    driver=driver,
+    working_dir=working_dir,
+    max_attempts=1,
+    enable_verification=False,
+)
+
+
+def main():
+    repl = AgentREPL(DeerIntrospection)
+    repl.repl()
+
+
+if __name__ == "__main__":
+    main()

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/builtins_agents/operating_system.py

@@ -4,17 +4,15 @@ from deer.tools import ToolRegistry
 from deer.tools.presets import Preset
 from deer.tools.providers import HTTPClient
 from deer.drivers import OllamaDriver
-from deer.memory import VectorMemory
 
 from pathlib import Path
 
 # Infrastructure
 driver = get_driver_from_parser() or OllamaDriver(model_name="gemma4:31b-cloud")
-memory = VectorMemory(path=Path.home() / "deer_os_sandbox" / ".deer" / "vector_db")
 registry = ToolRegistry(Preset.SYSTEM_ADMIN | {HTTPClient})
 working_dir = get_path_from_parser() or Path.cwd()
 
-agent = DeterministicAgent(
+OperatingSystemAgent = DeterministicAgent(
     description="Advanced OS Agent for secure system management.",
     identity=(
         "You are a capable Operating System Agent. "
@@ -24,7 +22,6 @@ agent = DeterministicAgent(
     ),
     driver=driver,
     tool_registry=registry,
-    vector_memory=memory,
     working_dir=working_dir,
     max_attempts=3,
     enable_verification=False,
@@ -32,7 +29,7 @@ agent = DeterministicAgent(
 
 
 def main():
-    repl = AgentREPL(agent)
+    repl = AgentREPL(OperatingSystemAgent)
     repl.repl()
 
 

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/builtins_agents/python_architect.py

@@ -4,13 +4,12 @@ from deer.tools import ToolRegistry
 from deer.tools.presets import Preset
 from deer.tools.providers import HTTPClient, SystemObserver
 from deer.drivers import OllamaDriver
-from deer.memory import VectorMemory
 
 from pathlib import Path
 
+
 # Infrastructure
 driver = get_driver_from_parser() or OllamaDriver(model_name="gemma4:31b-cloud")
-memory = VectorMemory(path=Path.cwd() / ".deer" / "vector_db")
 registry = ToolRegistry(
     Preset.CODE_REPAIR
     | Preset.CODE_EDITOR
@@ -19,7 +18,7 @@ registry = ToolRegistry(
 )
 working_dir = get_path_from_parser() or Path.cwd()
 
-agent = DeterministicAgent(
+PythonArchitectAgent = DeterministicAgent(
     description="AI specialist in Python architecture, runtime module resolution, and dependency management.",
     identity=(
         "You are an elite AI Agent operating as a Principal Python Architect and Core Ecosystem Specialist. "
@@ -30,14 +29,13 @@ agent = DeterministicAgent(
     ),
     driver=driver,
     tool_registry=registry,
-    vector_memory=memory,
     working_dir=working_dir,
     max_attempts=3,
 )
 
 
 def main():
-    repl = AgentREPL(agent)
+    repl = AgentREPL(PythonArchitectAgent)
     repl.repl()
 
 

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/cli/main.py

@@ -1,5 +1,5 @@
 from rich.text import Text
-from deer.utils.console import console, error, info
+from deer.utils.console import ConsoleColor
 from deer.builtins_agents import agents
 import importlib.util
 import sys
@@ -11,30 +11,30 @@ logger = logging.getLogger(f"DEER.{__name__}")
 
 
 def title():
-    console.print()
-    console.print(
+    ConsoleColor.console.print()
+    ConsoleColor.console.print(
         Text(
             "DEER",
             style="bold cyan",
         )
     )
-    console.print(
+    ConsoleColor.console.print(
         "Deterministic Executable Engine for Runtime Agents",
         style="dim",
     )
-    console.print()
+    ConsoleColor.console.print()
 
 
 def agents_list():
-    console.print()
-    console.print("[bold]Available agents[/bold]")
+    ConsoleColor.console.print()
+    ConsoleColor.console.print("[bold]Available agents[/bold]")
     for name in agents:
-        console.print(f"  • [green]{name}[/green]")
-    console.print()
+        ConsoleColor.console.print(f"  • [green]{name}[/green]")
+    ConsoleColor.console.print()
 
 
 def example():
-    console.print(f"[dim]Example:[/dim] deer {list(agents.keys())[0]}")
+    ConsoleColor.console.print(f"[dim]Example:[/dim] deer {list(agents.keys())[0]}")
 
 
 def run_agent_in_process(agent_path, backend=None, model=None):
@@ -65,15 +65,15 @@ def main():
     if selected_agent := args.agent:
 
         if selected_agent in agents:
-            info(f"Launching agent '{selected_agent}'")
+            ConsoleColor.on_info(f"Launching agent '{selected_agent}'")
             run_agent_in_process(agents[selected_agent], args.backend, args.model)
             sys.exit(0)
 
-        error(f"Unknown agent '{selected_agent}'")
+        ConsoleColor.on_error(f"Unknown agent '{selected_agent}'")
         agents_list()
         sys.exit(1)
 
-    error("No agent selected")
+    ConsoleColor.on_error("No agent selected")
     example()
     agents_list()
 

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/cli/parser.py

@@ -2,7 +2,7 @@ import argparse
 import os
 from pathlib import Path
 
-from deer.utils.console import error
+from deer.utils.console import ConsoleColor
 
 backends = {
     "gemini",
@@ -60,21 +60,21 @@ def get_driver_from_parser():
 
     try:
         drivers_parser.silent = True
-        args = drivers_parser.parse_args()
+        args, _ = drivers_parser.parse_known_args()
         drivers_parser.silent = False
     except:
         drivers_parser.silent = False
         return False
 
     if args.backend not in backends:
-        error(
+        ConsoleColor.on_error(
             f"Unsupported backend '{args.backend}'. "
             f"Supported backends are: {', '.join(backends)}."
         )
         return False
 
     if not args.model:
-        error("A model identifier must be provided.")
+        ConsoleColor.on_error("A model identifier must be provided.")
         return False
 
     match args.backend:
@@ -96,7 +96,7 @@ def get_path_from_parser():
 
     try:
         path_parser.silent = True
-        args = path_parser.parse_args()
+        args, _ = path_parser.parse_known_args()
         path_parser.silent = False
     except:
         path_parser.silent = False

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/cli/repl.py

@@ -7,7 +7,7 @@ from rich.console import Console
 from rich.markdown import Markdown
 from rich.table import Table
 from rich.text import Text
-from prompt_toolkit import prompt, PromptSession
+from prompt_toolkit import PromptSession
 from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import InMemoryHistory
 from prompt_toolkit.completion import Completer, WordCompleter
@@ -23,6 +23,7 @@ COMMANDS = {
     "/exit": "Terminate the session",
     "/rollback": "Revert the system to the last stable state",
     "/trace": "Display the detailed execution trace and variable resolution of the last plan.",
+    "/savetrace": "Saves the current execution trace to a file for later analysis.",
     "/history": "Display the history of messages and commands",
     "/clearhistory": "Purge all session history and reset memory state.",
     # "/vhistory": "Display the history of verifier messages and commands",
@@ -211,6 +212,15 @@ class AgentREPL:
                     sep="",
                 )
 
+            case "/savetrace":
+                try:
+                    filename = self.agent.save_trace()
+                    self.console.print(f"[dim]Trace saved in {filename}[/dim]\n")
+                except Exception as e:
+                    self.console.print(
+                        f"[bold red]Error saving trace:[/bold red] {e}\n"
+                    )
+
             case "/savecontext":
                 try:
                     self.agent.persist_state()

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/core/agent.py

@@ -69,6 +69,7 @@ class DeterministicAgent:
 
         # Planner
         self.planner = Planner(
+            identity=self.identity,
             driver=self.driver,
             tool_registry=self.tool_registry,
             max_attempts=max_attempts,
@@ -164,18 +165,7 @@ class DeterministicAgent:
         with open(filename, "wb") as f:
             pickle.dump(obj, f)
 
-        logger.info(f"Trace generated in {filename}")
-
-    def clear_working_dir(self, ignore=None):
-        for item in self.working_dir.iterdir():
-            if ignore and item in ignore:
-                continue
-
-            full_path = self.working_dir / item
-            if full_path.is_dir():
-                shutil.rmtree(full_path)
-            else:
-                full_path.unlink()
+        return filename
 
     def _execute_phase(
         self, goal: str, history: list[ChatMessage], update_history_attr: str

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/core/executor.py

@@ -39,7 +39,12 @@ class PipelineExecutor:
                 start_time = time.perf_counter()
                 try:
                     result = tool.run(params=resolved_args)
-                    status = "SUCCESS"
+
+                    if result.get("returncode", 0):
+                        status = "FAILED"
+                    else:
+                        status = "SUCCESS"
+
                     error_msg = None
                 except Exception as e:
                     result = None

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/core/planner.py

@@ -14,10 +14,11 @@ class Planner:
     It transforms the user goal, context, and tool registry into a structured ExecutionPlan.
     """
 
-    def __init__(self, driver, tool_registry: ToolRegistry, max_attempts=3):
+    def __init__(self, identity, driver, tool_registry: ToolRegistry, max_attempts=3):
         self.driver = driver
         self.tool_registry = tool_registry
         self.max_attempts = max_attempts
+        self.identity = identity
 
     def build_system_prompt(self, state_filter="BOTH") -> str:
         """
@@ -27,7 +28,7 @@ class Planner:
         tools_menu = self.tool_registry.describe(state_filter=state_filter)
 
         return (
-            "You are the DEER Deterministic Planner. Your goal is to design a rigid execution pipeline.\n\n"
+            f"{self.identity}\n\n"
             "REQUIRED STRUCTURE:\n"
             "{\n"
             '  "goal": "string",\n'
@@ -62,7 +63,7 @@ class Planner:
         else:
             verification = f"VERIFICATION TRACE:\n{trace_verification.model_dump_json(indent=2)}\n\n"
         return (
-            "You are the DEER Technical Auditor. Your goal is to synthesize the execution results into a final verdict.\n\n"
+            f"{self.identity}\n\n"
             f"USER GOAL: {goal}\n\n"
             f"ACTION TRACE:\n{trace_solution.model_dump_json(indent=2)}\n\n"
             f"{verification}"

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/evals/__init__.py

@@ -1,2 +1 @@
 from .runner import AgentRunner
-from .repl import AgentREPL

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/evals/runner.py

@@ -1,4 +1,5 @@
 from deer.core import DeterministicAgent
+import shutil
 
 
 class AgentRunner:
@@ -11,11 +12,19 @@ class AgentRunner:
         for i in range(repetitions):
 
             print(f"Working on iteration: {i+1}/{repetitions}")
-
             self.agent.clear_traces()
             self.agent.clear_agent_history()
-            self.agent.clear_working_dir(ignore=[".deer", "traces"])
-
+            self.clear_working_dir()
             self.agent.run(goal)
-
             self.agent.save_trace()
+
+    def clear_working_dir(self):
+
+        for item in self.agent.working_dir.iterdir():
+            if item.name.startswith("."):
+                continue
+
+            if item.is_dir():
+                shutil.rmtree(item)
+            else:
+                item.unlink()

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/memory/vector.py

@@ -28,16 +28,16 @@ class VectorMemory:
         )
 
     def add_document(
-        self, doc_id: str, text: str, metadata: Optional[dict[str, Any]] = None
+        self, id: str, doc: str, metadata: Optional[dict[str, Any]] = None
     ) -> None:
         """
         Add a document to the vector collection.
 
         Parameters
         ----------
-        doc_id : str
+        id : str
             Unique identifier for the document.
-        text : str
+        doc : str
             The content of the document to be embedded and stored.
         metadata : dict, optional
             Additional metadata associated with the document.
@@ -47,7 +47,7 @@ class VectorMemory:
         if "hit_count" not in meta:
             meta["hit_count"] = 0
 
-        self.collection.add(documents=[text], metadatas=[meta], ids=[doc_id])
+        self.collection.add(documents=[doc], metadatas=[meta], ids=[id])
 
     def query(self, query_text: str, n_results: int = 3) -> list[dict[str, Any]]:
         """
@@ -327,3 +327,14 @@ class VectorMemory:
             )
 
         return len(ids_to_delete)
+
+    def load_json(self, json_path: Path):
+
+        if not json_path.exists():
+            raise ValueError("bla bla")
+
+        with json_path.open("r", encoding="utf-8") as f:
+            memories = json.load(f)
+
+        for memory in memories:
+            self.add_document(**memory)

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/tools/base.py

@@ -1,3 +1,4 @@
+import os
 from abc import ABC, abstractmethod
 from typing import Any, Type
 from dataclasses import dataclass, field
@@ -64,6 +65,16 @@ class ToolProvider:
         2. If 'path' is absolute, it's checked for containment.
         3. All '..' and symlinks are resolved before validation.
         """
+        if isinstance(path, str):
+            path = self._sanitize_path(path)
+
+        # Si el agente incluyó el nombre del jail en el path (ej: 'astropy/modeling/...')
+        # lo quitamos para evitar rutas redundantes como 'astropy/astropy/...'
+        if isinstance(path, str):
+            jail_name = os.path.basename(self.jail)
+            if path.startswith(jail_name + os.sep) or path.startswith(jail_name + "/"):
+                path = path[len(jail_name) + 1 :]
+
         path = Path(path)
 
         # Handle point 2: If relative, interpret it as inside the jail.
@@ -158,6 +169,24 @@ class ToolProvider:
                 f"Please ensure it is installed and configured in your PATH."
             )
 
+    def _sanitize_path(self, path: str | Path) -> str:
+
+        if isinstance(path, Path):
+            return path
+
+        if not path:
+            return path
+
+        sanitized = path.strip().strip('"').strip("'")
+        sanitized = sanitized.replace("\n", "").replace("\r", "")
+        return sanitized
+
+    def _normalize_target(self, path, target):
+        abs_path = self.jailed_path(path)
+        abs_target = self.jailed_path(target)
+
+        return str(abs_target.relative_to(abs_path))
+
 
 class Tool(ABC):
     """Base contract for deterministic tools."""

{deer_agent_framework-0.2.3 → deer_agent_framework-0.2.4}/deer/tools/presets.py

@@ -77,6 +77,7 @@ class Preset:
         DependencyAnalyzer,
         CodeSearcher,
         GitManager,
+        FileManager,
     }
 
     # For safely modifying configuration files without touching source code.

deer_agent_framework-0.2.4/deer/tools/providers/base/base_command_runner.py

@@ -0,0 +1,54 @@
+from typing import List, get_args
+import shlex
+from deer.tools import ToolProvider
+from deer.tools.schemas import CommandOut
+
+# --- Global Constants ---
+MAX_TIMEOUT = 300
+REJECTED = {"stdout": "", "stderr": str, "returncode": -1, "message": str}
+
+
+def _failure(message: str) -> dict:
+    """Helper to construct a standardized failure response."""
+    return {"stdout": "", "stderr": message, "returncode": -1, "message": message}
+
+
+class BaseCommandRunner(ToolProvider):
+
+    @property
+    def allowed_commands(self):
+        return list(get_args(self.availableCommands))
+
+    def _execute_command(
+        self, binary: str, args: List[str], path: str, timeout_seconds: int = 60
+    ) -> CommandOut:
+        # 1. Validate path boundaries
+        path = self.jailed_path(path)
+
+        # 2. Validate timeout constraints
+        if not 1 <= timeout_seconds <= MAX_TIMEOUT:
+            return _failure(f"timeout_seconds must be between 1 and {MAX_TIMEOUT}.")
+
+        # 3. Verify binary exists in environment
+        try:
+            self.check_command(binary)
+        except Exception as e:
+            return _failure(f"Environment error: {e}")
+
+        # 4. Execution
+        try:
+            safe_command = shlex.join([binary] + args)
+            result = self.run_command(
+                safe_command, cwd=path, timeout_seconds=timeout_seconds
+            )
+        except Exception as e:
+            return _failure(f"Execution error: {e}")
+
+        # 5. Response formatting
+        exit_code = result.get("returncode", -1)
+        status_message = (
+            "Command completed successfully."
+            if exit_code == 0
+            else f"Command failed with exit code {exit_code}."
+        )
+        return {**result, "message": status_message}