deer-agent-framework 0.1a2__tar.gz → 0.1a4__tar.gz

{deer_agent_framework-0.1a2 → deer_agent_framework-0.1a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deer-agent-framework
-Version: 0.1a2
+Version: 0.1a4
 Summary: DEER - Deterministic Executable Engine for Runtime-agents
 Author: Yeison
 License: BSD-2-Clause
@@ -20,8 +20,12 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2.0
-Requires-Dist: rich
-Requires-Dist: prompt_toolkit
+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: ruamel.yaml>=0.19.1
+Requires-Dist: lxml>=6.1.1
 Provides-Extra: debug
 Requires-Dist: matplotlib>=3.10.9; extra == "debug"
 Requires-Dist: pandas>=3.0.3; extra == "debug"
@@ -68,8 +72,9 @@ Forget about telling the AI to "act like a specialist." Define a high-level `Det
 ```python
 from pathlib import Path
 from deer.core.agent import DeterministicAgent
+from deer.states import ParallelGitStateManager
 from deer.drivers import get_driver_from_parser
-from .tools import registry
+from deer.tools import Preset
 
 agent = DeterministicAgent(
     description="Python Architecture Specialist",
@@ -78,10 +83,11 @@ agent = DeterministicAgent(
         "in advanced module resolution and dependency management."
     ),
     driver=get_driver_from_parser(),
-    registry=registry,
+    tool_registry=Preset.CODE_REPAIR | Preset.CODE_EDITOR | Preset.DATA_ANALYST,
     jail_path=Path.cwd() / "sandbox",  # Strict security boundary
     format_response="markdown",
-    max_retries=5
+    max_retries=5,
+    state_manager=ParallelGitStateManager(),
 )
 
 if __name__ == "__main__":
@@ -95,10 +101,10 @@ Combine built-in managers (File, Git, Search) into a single, cohesive unit of ex
 from deer.tools.registry import ToolRegistry
 from deer.tools.builtin import FileManager, GitManager, SearchManager
 
-registry = ToolRegistry()
+tool_registry = ToolRegistry()
 
 # Add specialized capabilities with zero-config
-registry.register(
+tool_registry.register(
     FileManager(),
     GitManager(),
     SearchManager(),
@@ -171,6 +177,12 @@ Every decision, tool call, and validation step is recorded. This allows for deep
 
 ## Installation
 
+From PyPI:
+```bash
+pip install deer-agent-framework
+```
+
+From GitHub (development version):
 ```bash
 pip install git+https://github.com/dunderlab/deer-agent-framework.git
 ```

{deer_agent_framework-0.1a2 → deer_agent_framework-0.1a4}/README.md

@@ -38,8 +38,9 @@ Forget about telling the AI to "act like a specialist." Define a high-level `Det
 ```python
 from pathlib import Path
 from deer.core.agent import DeterministicAgent
+from deer.states import ParallelGitStateManager
 from deer.drivers import get_driver_from_parser
-from .tools import registry
+from deer.tools import Preset
 
 agent = DeterministicAgent(
     description="Python Architecture Specialist",
@@ -48,10 +49,11 @@ agent = DeterministicAgent(
         "in advanced module resolution and dependency management."
     ),
     driver=get_driver_from_parser(),
-    registry=registry,
+    tool_registry=Preset.CODE_REPAIR | Preset.CODE_EDITOR | Preset.DATA_ANALYST,
     jail_path=Path.cwd() / "sandbox",  # Strict security boundary
     format_response="markdown",
-    max_retries=5
+    max_retries=5,
+    state_manager=ParallelGitStateManager(),
 )
 
 if __name__ == "__main__":
@@ -65,10 +67,10 @@ Combine built-in managers (File, Git, Search) into a single, cohesive unit of ex
 from deer.tools.registry import ToolRegistry
 from deer.tools.builtin import FileManager, GitManager, SearchManager
 
-registry = ToolRegistry()
+tool_registry = ToolRegistry()
 
 # Add specialized capabilities with zero-config
-registry.register(
+tool_registry.register(
     FileManager(),
     GitManager(),
     SearchManager(),
@@ -141,6 +143,12 @@ Every decision, tool call, and validation step is recorded. This allows for deep
 
 ## Installation
 
+From PyPI:
+```bash
+pip install deer-agent-framework
+```
+
+From GitHub (development version):
 ```bash
 pip install git+https://github.com/dunderlab/deer-agent-framework.git
 ```

{deer_agent_framework-0.1a2 → deer_agent_framework-0.1a4}/deer/__init__.py

@@ -1,6 +1,8 @@
 import os
 from pathlib import Path
 
+__version__ = "0.1.9"
+
 
 def load_env_file(env_path: Path) -> None:
     """Reads a .env file and loads its variables into os.environ natively."""
@@ -28,9 +30,9 @@ def load_env_file(env_path: Path) -> None:
 
 # Your configuration logic remains clean and dependency-free
 local_env = Path(".env")
-user_env = Path.home() / "deer.env"
+user_env = Path.home() / ".deer.env"
 
 if local_env.exists():
     load_env_file(local_env)
 elif user_env.exists():
-    load_env_file(user_env)
+    load_env_file(user_env)

deer_agent_framework-0.1a4/deer/builtins/python_manager/agent.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from deer.core.agent import DeterministicAgent
+from deer.states import ParallelGitStateManager
+from deer.drivers import get_driver_from_parser
+from deer.tools import Preset
+
+agent = 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. "
+        "You provide authoritative, deterministic guidance on advanced module resolution, runtime execution, "
+        "dependency isolation, and package distribution. Your expertise spans the entire Python lifecycle: "
+        "from engineering scalable code structures to resolving complex import mechanisms and optimizing "
+        "deployment pipelines across public or internal repositories."
+    ),
+    driver=get_driver_from_parser(),
+    tool_registry=Preset.CODE_REPAIR | Preset.CODE_EDITOR | Preset.DATA_ANALYST,
+    jail_path=Path.cwd(),
+    format_response="markdown",
+    max_retries=5,
+    state_manager=ParallelGitStateManager(),
+)
+
+
+def main():
+    agent.repl()
+
+
+if __name__ == "__main__":
+    main()

{deer_agent_framework-0.1a2 → deer_agent_framework-0.1a4}/deer/core/agent.py

@@ -5,10 +5,16 @@ import pickle
 import sys
 from typing import Callable
 from datetime import datetime
+import os
+import subprocess
+from pathlib import Path
 
 from prompt_toolkit import prompt
 from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import InMemoryHistory
+from prompt_toolkit.completion import WordCompleter
+from rich.console import Console
+from rich.markdown import Markdown
 
 from deer.prompts import (
     RESPONSE_IMPROVEMENT_PROMPT,
@@ -17,6 +23,7 @@ from deer.prompts import (
     GOAL_VERIFIER_PROMPT,
     VERIFIER_JUDGE_PROMPT,
 )
+from deer import __version__
 from deer.drivers.base_driver import LLMDriver
 from deer.planner.planner import Planner
 from deer.validator.plan_validator import PlanValidator
@@ -24,11 +31,19 @@ from deer.executor.executor import Executor
 from deer.core.ui import WELCOME_MESSAGE
 from deer.tools.registry import ToolRegistry, default_registry
 from deer.schema.io import AgentInput, AgentOutput
-from rich.console import Console
-from rich.markdown import Markdown
+from deer.states import BaseStateManager
 
 logger = logging.getLogger("DEER")
-prompt_history = InMemoryHistory()
+# prompt_history = InMemoryHistory()
+# prompt_history = '.deer.history'
+
+
+COMMANDS = {
+    "/tools": "Show tools and capabilities",
+    "/clear": "Clear the console and reset the session",
+    "/exit": "Terminate the session",
+    "/rollback": "Revert the system to the last stable state",
+}
 
 
 class DeterministicAgent:
@@ -38,42 +53,53 @@ class DeterministicAgent:
         identity: str = "DeterministicAgent",
         max_retries: int = 3,
         driver: LLMDriver | None = None,
-        registry: ToolRegistry | None = None,
+        tool_registry: ToolRegistry | None = None,
         format_response: str = "plaintext",
-        rollback: Callable = None,
+        state_manager: BaseStateManager = None,
         jail_path: str = None,
     ) -> None:
         assert format_response in {"markdown", "plaintext"}
 
+        self.history_filename = ".deer.history"
+        self.prompt_history = self.load_history()
+
         self.identity = identity
         self.description = description
         self.driver = driver
-        self.registry = registry or default_registry()
+
+        if isinstance(tool_registry, set):
+            tr = ToolRegistry()
+            tr.register(*[tool() for tool in tool_registry])
+            tool_registry = tr
+
+        self.tool_registry = tool_registry or default_registry()
+
         self.console = Console()
 
         self.executor = Executor(
-            registry=self.registry,
+            tool_registry=self.tool_registry,
         )
 
         self.validator = PlanValidator(
-            registry=self.registry,
+            tool_registry=self.tool_registry,
         )
 
         self.planner = Planner(
             identity=identity,
             driver=driver,
-            registry=self.registry,
+            tool_registry=self.tool_registry,
             format_response=format_response,
         )
 
+        self.state_manager = state_manager
+
         assert (
-                max_retries > 0
+            max_retries > 0
         ), f"max_tries_for_plan must be positive, got {max_retries}"
         self.max_retries = max_retries
 
         self.history = []
         self.trace = []
-        self.rollback_function = rollback
 
         if jail_path:
             self.set_jail(jail_path)
@@ -84,17 +110,17 @@ class DeterministicAgent:
         )
         logger.info(f"Identity: {self.identity}")
         logger.info(
-            f"Available tools:\n{self.registry.describe(include_state_modifying=True)}"
+            f"Available tools:\n{self.tool_registry.describe(include_state_modifying=True)}"
         )
         logger.info(f"Authorized filesystem scope is restricted to: {jail_path}")
 
     def set_jail(self, jail_path):
-        self.registry.set_jail(jail_path)
+        self.tool_registry.set_jail(jail_path)
 
     def should_verify(self, plan) -> bool:
         return any(step.tool for step in plan.steps)
 
-    def execute_plan(
+    def generate_and_execute_plan(
         self,
         agent_input: AgentInput,
         feedback: {},
@@ -113,7 +139,7 @@ class DeterministicAgent:
             feedback = {"Planning error": str(planning_error)}
             last_error_message = str(planning_error)
             return None, feedback, last_error_message, None
-        logger.info(f"Plan generated")
+        logger.info(f"1. Plan generated")
         logger.debug(f"Plan steps:")
         for step in plan.steps:
             logger.debug(f"\tstep: {step.id}")
@@ -129,7 +155,7 @@ class DeterministicAgent:
             feedback = {"verification error": str(validation_error)}
             last_error_message = str(validation_error)
             return None, feedback, last_error_message, plan
-        logger.info(f"Plan verified")
+        logger.info(f"2. Plan verified")
 
         try:
             response = self.executor.execute(
@@ -141,22 +167,28 @@ class DeterministicAgent:
             feedback = {"execution error": str(execution_error)}
             last_error_message = str(execution_error)
             return None, feedback, last_error_message, plan
-        logger.info(f"Plan executed")
+        logger.info(f"3. Plan executed")
 
         return response, feedback, last_error_message, plan
 
     def run(self, agent_input: AgentInput) -> AgentOutput:
         feedback = {}
         run_trace = {}
-
         response_validation = None
+        last_error_message = None
+
+        self.state_snapshot()
 
         for attempt_idx in range(self.max_retries):
+            self.state_restore()
+
             logger.debug(f"Attempt {attempt_idx + 1} of {self.max_retries}")
 
             run_trace[f"Attempt-{attempt_idx + 1}"] = {}
 
             for solution_idx in range(self.max_retries):
+                self.state_restore()
+
                 logger.debug(
                     f"Solution planning {solution_idx + 1} of {self.max_retries}"
                 )
@@ -164,8 +196,8 @@ class DeterministicAgent:
                     f"Solution-{solution_idx + 1}"
                 ] = datetime.now()
 
-                response, feedback, last_error_message, plan = self.execute_plan(
-                    agent_input, feedback
+                response, feedback, last_error_message, solution_steps = (
+                    self.generate_and_execute_plan(agent_input, feedback)
                 )
                 if response is None:
                     continue
@@ -176,15 +208,10 @@ class DeterministicAgent:
                     f"Agent failed to produce a response after {self.max_retries} attempts"
                 )
                 if last_error_message:
-                    last_error_message_explained = self.explain_error(
-                        last_error_message
-                    )
-                return AgentOutput(
-                    result=last_error_message_explained,
-                    trace=self.executor.trace_store.get_trace(),
-                )
+                    feedback = {"Previous Error": last_error_message}
+                continue
 
-            if not self.should_verify(plan):
+            if not self.should_verify(solution_steps):
                 break
 
             feedback_ = {}
@@ -209,7 +236,7 @@ class DeterministicAgent:
                 agent_verifier_input = AgentInput(
                     goal=goal_verifier_prompt, payload=payload_verifier
                 )
-                response_validation, feedback_, _, validation_plan = self.execute_plan(
+                response_validation, feedback_, _, _ = self.generate_and_execute_plan(
                     agent_verifier_input, feedback_, include_state_modifying=False
                 )
 
@@ -235,7 +262,16 @@ class DeterministicAgent:
             if response.validated:
                 break
 
-            self.rollback()
+        if response is None:
+            logger.warning(
+                f"Agent failed to produce a response after {self.max_retries} attempts"
+            )
+            if last_error_message:
+                last_error_message_explained = self.explain_error(last_error_message)
+            return AgentOutput(
+                result=last_error_message_explained,
+                trace=self.executor.trace_store.get_trace(),
+            )
 
         self.history.extend(
             [
@@ -261,21 +297,29 @@ class DeterministicAgent:
         )
 
         self.planner.goal = agent_input.goal
+        self.state_purge_engine()
         return response
 
-    def send(self, msg):
+    def send(self, message, print_chat: bool = False):
         user_input = AgentInput(
-            goal=msg,
+            goal=message,
             payload={
                 "chat_history": self.history,
             },
         )
-        response = self.run(user_input)
 
+        if print_chat:
+            print(f">>> {message}")
+
+        response = self.run(user_input)
         if isinstance(response.result, dict):
             response.result = self.humanize_result(response)
         else:
             response.result = self.improve_result(response)
+
+        if print_chat:
+            print(f"    {response.result}")
+
         return response
 
     def pretty_print(self, out: str):
@@ -285,12 +329,17 @@ class DeterministicAgent:
         self.history = []
         self.trace = []
 
-    def rollback(self):
-        logger.debug(f"Rolling back agent")
-        if self.rollback_function:
-            self.rollback_function()
-        else:
-            logger.debug(f"No rollback function defined")
+    def state_snapshot(self):
+        if self.state_manager:
+            self.state_manager.set_reference_state(self.tool_registry.jail_path)
+
+    def state_restore(self):
+        if self.state_manager:
+            self.state_manager.rollback_to_previous_state()
+
+    def state_purge_engine(self):
+        if self.state_manager:
+            self.state_manager.purge_engine()
 
     def humanize_result(self, output: AgentOutput) -> str:
         trace_str = ""
@@ -318,7 +367,7 @@ class DeterministicAgent:
 
     def explain_error(self, error: str):
         error_prompt = ERROR_EXPLAIN_PROMPT.format(
-            error=error, tools=self.registry.describe()
+            error=error, tools=self.tool_registry.describe()
         )
         error_explained = self.driver.generate_text(error_prompt)
         return error_explained
@@ -376,7 +425,7 @@ class DeterministicAgent:
 
     def save_trace(self, filename: str):
         obj = {
-            "tools": list(self.registry.list_tools()),
+            "tools": list(self.tool_registry.list_tools()),
             "trace": self.trace,
             "history": self.history,
         }
@@ -388,75 +437,167 @@ class DeterministicAgent:
             pickle.dump(obj, f)
 
     def show_welcome(self):
+
+        commands_formated = ""
+        for command in COMMANDS:
+            commands_formated += (
+                f"- {('`'+command+'`').ljust(12, ' ')} → {COMMANDS[command]}\n "
+            )
+
         self.console.clear()
-        self.pretty_print(WELCOME_MESSAGE)
+        self.pretty_print(
+            WELCOME_MESSAGE.format(version=__version__, commands=commands_formated)
+        )
         self.pretty_print(
             f">**Agent Profile**  \n"
             f"*{self.description}*  \n"
-            f"root: {self.registry.jail_path}  \n"
+            f"root: {self.tool_registry.jail_path}  \n"
             f"{self.driver}: {self.driver.model_name}  \n"
         )
         print("\n")
 
+    def run_command(self, command):
+        match command:
+            case "/exit":
+                sys.exit(0)
+
+            case "/clear":
+                self.clear_history()
+                self.console.clear()
+                self.pretty_print(f">**Agent Profile**  \n*{self.description}*")
+                print("\n")
+
+            case "/tools":
+                self.pretty_print(
+                    self.tool_registry.describe(
+                        include_state_modifying=True, markdown=True
+                    )
+                )
+                print("\n")
+
+            case "/rollback":
+                self.state_restore()
+                self.pretty_print(
+                    "**Rollback executed.** System reverted to the last stable state."
+                )
+                print("\n")
+
     def repl(self):
         logger.setLevel(logging.CRITICAL)
         self.show_welcome()
 
         while True:
-            msg = prompt(
-                HTML("<ansicyan><b>&gt;&gt;&gt; </b></ansicyan>"),
-                history=prompt_history,
-            )
-
-            self.console.status("[cyan]Planning...", spinner="dots")
-
-            match msg.strip():
-                case "exit;":
-                    sys.exit(0)
+            try:
+                msg = prompt(
+                    HTML("<ansicyan><b>&gt;&gt;&gt; </b></ansicyan>"),
+                    history=self.prompt_history,
+                    completer=self.completer,
+                )
+                self.save_history()
+            except KeyboardInterrupt:
+                continue
+            except EOFError:
+                break
 
-                case "clear;":
-                    self.clear_history()
-                    self.console.clear()
-                    self.pretty_print(f">**Agent Profile**  \n*{self.description}*")
-                    print("\n")
+            msg = msg.strip()
+            if not msg:
+                continue
 
-                case "tools;":
-                    self.pretty_print(
-                        self.registry.describe(
-                            include_state_modifying=True, markdown=True
+            match msg:
+                case command if command in COMMANDS:
+                    self.run_command(command)
+
+                case command if command.startswith("!"):
+                    # Remove the '!' from the start to get only the command
+                    cmd_to_run = command[1:].strip()
+
+                    try:
+                        # Execute the command
+                        result = subprocess.run(
+                            cmd_to_run,
+                            shell=True,
+                            capture_output=True,
+                            text=True,
+                            check=True,
                         )
-                    )
-                    print("\n")
-
-                case "rollback;":
-                    self.rollback()
-                    self.pretty_print(
-                        "**Rollback executed.** System reverted to the last stable state."
-                    )
-                    print("\n")
+                        print(result.stdout)
+                    except subprocess.CalledProcessError as e:
+                        print(f"Error executing command: {e.stderr}")
+                    except Exception as e:
+                        print(f"An unexpected error occurred: {e}")
 
                 case _:
-                    if not msg or msg.endswith(";"):
+                    if msg.startswith("/"):
+                        logging.warning(
+                            f"Command `{msg}` not recognized. Did you mean one of these: {list(COMMANDS)}"
+                        )
                         continue
-
                     with self.console.status(
                         "[dim]processing request[/]",
                         spinner="point",
                         spinner_style="dim",
                     ):
-                        output = self.send(msg)
-                        self.pretty_print(f"    {output.text}")
-                        print("\n")
-
-    def iterate_debug(self, chain_messages: list[str], repetitions: int, path: str):
+                        try:
+                            output = self.send(msg)
+                            self.pretty_print(f"    {output.text}")
+
+                            print("\n")
+                        except KeyboardInterrupt:
+                            self.console.print("[dim]Command aborted by user[/]\n")
+                            self.state_restore()
+                            continue
+                        except EOFError:
+                            break
+
+    def iterate_debug(
+        self,
+        chain_messages: list[str],
+        repetitions: int,
+        path: str,
+        callback: Callable = None,
+    ):
         logger.setLevel(logging.DEBUG)
+        os.makedirs(path, exist_ok=True)
         for i in range(repetitions):
             self.clear_history()
-            self.rollback()
             name = f"{self.driver.model_name}-{datetime.now().timestamp()}"
+
+            formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+            file_handler = logging.FileHandler(f"{path}/{name}.log")
+            file_handler.setFormatter(formatter)
+            logger.addHandler(file_handler)
+            logger.info("Starting debug mode")
+            logger.info(f"Model: {self.driver.model_name}")
+            logger.info("Tools:")
+            logger.info(self.tool_registry.describe(include_state_modifying=True))
+            logger.removeHandler(file_handler)
+            file_handler.close()
+
             self.generate_chat_log(
                 chain_messages,
                 print_chat=True,
                 save_log=f"{path}/{name}.log",
             )
             self.save_trace(f"{path}/{name}.trace")
+            if callback:
+                callback()
+
+    def load_history(self):
+        history_file = Path.home() / self.history_filename
+        if not history_file.exists():
+            self.prompt_history = InMemoryHistory()
+            return self.prompt_history
+
+        with open(history_file, "rb") as f:
+            self.prompt_history = pickle.load(f)
+        return self.prompt_history
+
+    def save_history(self):
+        history_file = Path.home() / self.history_filename
+        with open(history_file, "wb") as f:
+            pickle.dump(self.prompt_history, f)
+
+    @property
+    def completer(self):
+        internal_commands = ["/tools", "/clear", "/exit", "/rollback"]
+        return WordCompleter(internal_commands, ignore_case=False)