deer-agent-framework 0.2a1__tar.gz → 0.2.4__tar.gz

{deer_agent_framework-0.2a1/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.2a1
+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.2a1/deer/builtins/agents → deer_agent_framework-0.2.4/deer/builtins_agents}/__init__.py

@@ -1,6 +1,6 @@
 import os
 
-available_agents = {
+agents = {
     "python_architect": os.path.join(os.path.dirname(__file__), "python_architect.py"),
     "operating_system": os.path.join(os.path.dirname(__file__), "operating_system.py"),
 }

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.2a1/deer/builtins/agents → deer_agent_framework-0.2.4/deer/builtins_agents}/operating_system.py

@@ -4,18 +4,16 @@ 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(
-    description="OS Agent",
+OperatingSystemAgent = DeterministicAgent(
+    description="Advanced OS Agent for secure system management.",
     identity=(
         "You are a capable Operating System Agent. "
         "Your goal is to assist the user by managing the system, executing tasks, and solving problems efficiently. "
@@ -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.2a1/deer/builtins/agents → 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.2a1 → deer_agent_framework-0.2.4}/deer/cli/main.py

@@ -1,40 +1,40 @@
 from rich.text import Text
-from deer.utils.console import console, error, info
-from deer.builtins.agents import available_agents
+from deer.utils.console import ConsoleColor
+from deer.builtins_agents import agents
 import importlib.util
 import sys
 import logging
 
 from .parser import drivers_parser
 
-logger = logging.getLogger("DEER")
+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]")
-    for name in available_agents:
-        console.print(f"  • [green]{name}[/green]")
-    console.print()
+    ConsoleColor.console.print()
+    ConsoleColor.console.print("[bold]Available agents[/bold]")
+    for name in agents:
+        ConsoleColor.console.print(f"  • [green]{name}[/green]")
+    ConsoleColor.console.print()
 
 
 def example():
-    console.print(f"[dim]Example:[/dim] deer {list(available_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):
@@ -64,18 +64,16 @@ def main():
 
     if selected_agent := args.agent:
 
-        if selected_agent in available_agents:
-            info(f"Launching agent '{selected_agent}'")
-            run_agent_in_process(
-                available_agents[selected_agent], args.backend, args.model
-            )
+        if selected_agent in agents:
+            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.2a1 → 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.4/deer/cli/repl.py

@@ -0,0 +1,378 @@
+import sys
+import pickle
+import logging
+import subprocess
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+from rich.text import Text
+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
+
+from deer.core import DeterministicAgent
+from deer import __version__
+
+logger = logging.getLogger(f"DEER.{__name__}")
+
+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",
+    "/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",
+    "/infocontext": "Displays context memory usage information.",
+    "/loadcontext": "Restore a saved session context",
+    "/savecontext": "Save the current session context",
+}
+
+WELCOME_MESSAGE = """
+# DEER - Deterministic Executable Engine for Runtime Agents - v{version}
+
+An LLM agent orchestration framework built for:  
+- Strict runtime control
+- Enforced tool contracts
+- Full execution traceability
+- Guaranteed reproducibility
+
+## Runtime Pipeline
+
+1. Plan      → Generate a structured execution strategy
+2. Validate  → Verify contracts, dependencies, and safety
+3. Execute   → Run approved tools and workflows
+4. Verify    → Validate outputs against expected objectives
+
+## System Guarantees
+
+- Deterministic execution flow
+- Typed tool interfaces
+- Structured validation layers
+- Full execution traceability
+- Backend-governed orchestration
+
+## Commands
+
+{commands}
+
+## System Escapes
+
+- `!<command>` → Execute an OS shell command (e.g., `!ls -la` or `!pwd`)
+
+## Shortcuts
+
+- `Tab`        → Auto-complete commands and navigate suggestions
+- `Ctrl+C`     → Stop processing the current task
+"""
+
+
+class SmartCommandCompleter(Completer):
+    def __init__(self, commands):
+        self.base_completer = WordCompleter(commands, ignore_case=False)
+
+    def get_completions(self, document, complete_event):
+        word_before_cursor = document.get_word_before_cursor()
+        if not word_before_cursor:
+            return []
+        return self.base_completer.get_completions(document, complete_event)
+
+
+class AgentREPL:
+
+    def __init__(self, agent: DeterministicAgent):
+        self.agent = agent
+
+        self.prompt_history: InMemoryHistory
+        self.load_prompt_history()
+
+        self.console = Console()
+
+    @property
+    def completer(self):
+        internal_commands = list(COMMANDS.keys())
+        return SmartCommandCompleter(internal_commands)
+
+    def load_prompt_history(self):
+        history_file = self.agent.agent_dir / "prompt_history"
+
+        if not history_file.exists():
+            self.prompt_history = InMemoryHistory()
+            return
+
+        with open(history_file, "rb") as f:
+            self.prompt_history = pickle.load(f)
+        return
+
+    def save_prompt_history(self):
+        history_file = self.agent.agent_dir / "prompt_history"
+        with open(history_file, "wb") as f:
+            pickle.dump(self.prompt_history, f)
+
+    def clear_history(self):
+        self.history = []
+        self.trace = []
+
+    def pretty_print(self, out: str):
+        self.console.print(Markdown(out))
+
+    def show_identity(self):
+        self.pretty_print(
+            f">**Agent Profile**  \n"
+            f"*{self.agent.description}*  \n"
+            f"root: {self.agent.tool_registry.jail_path}  \n"
+            f"{self.agent.driver}: {self.agent.driver.model_name}  \n"
+        )
+        print("")
+
+    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.format(version=__version__, commands=commands_formated)
+        )
+        self.show_identity()
+
+    def run_command(self, command):
+        match command:
+            case "/exit":
+                self.agent.persist_state()
+                self.console.print(
+                    "[dim]Context state persisted to disk.[/dim]\n",
+                    Markdown("----"),
+                )
+                sys.exit(0)
+
+            case "/clear":
+                self.console.clear()
+                self.show_identity()
+                self.console.print(
+                    "[dim]Console buffer cleared. Session state persists. Use /clearhistory for a full purge.[/dim]\n",
+                )
+
+            case "/clearhistory":
+                self.clear_history()
+                self.console.clear()
+                self.agent.clear_agent_history()
+                self.agent.clear_traces()
+                self.agent.persist_state()
+                self.show_identity()
+                self.console.print(
+                    "[dim]Session history purged. Memory state reset.[/dim]\n",
+                )
+
+            case "/tools":
+                tools_description = self.agent.tool_registry.describe()
+                self.console.print(
+                    Markdown(tools_description),
+                    "\n",
+                    f"[dim]Tool registry: {len(self.agent.tool_registry._tools)} modules active.[/dim]\n",
+                    f"[dim]Registry description payload: {self.agent.format_bytes(len(tools_description))}[/dim]\n",
+                    sep="",
+                )
+
+            case "/rollback":
+                self.console.print(
+                    "[dim][bold]Rollback executed.[/bold] System reverted to the last stable state.[/dim]\n",
+                )
+
+            case "/trace":
+                trace = self.agent.traces["solution"]
+                for i, step in enumerate(trace):
+                    self.console.print(f"[bold yellow]Trace {i+1}:[/bold yellow]")
+                    print(f"{step}\n")
+
+            case "/history":
+                for i, chat in enumerate(self.agent.agent_history[1:]):
+                    self.console.print(f"[bold yellow]Chat {i+1}:[/bold yellow]")
+                    print(f"{chat}\n")
+                self.console.print(
+                    f"[dim]Session history payload: {self.agent.format_bytes(len(str(self.agent.agent_history)))}[/dim]\n",
+                )
+
+            # case "/vhistory":
+            #     for i, chat in enumerate(self.agent.verificator_history[1:]):
+            #         self.console.print(f"[bold yellow]Chat {i+1}:[/bold yellow]")
+            #         print(f"{chat}\n")
+
+            case "/infocontext":
+                bytes = sum(len(str(item)) for item in self.agent.agent_history)
+                self.console.print(
+                    f"[dim][bold]History:[/bold] {len(self.agent.agent_history)} messages[/dim]\n",
+                    f"[dim][bold]Context size:[/bold] ~{self.agent.format_bytes(bytes)}[/dim]\n",
+                    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()
+                    self.console.print("[dim]Context state persisted to disk.[/dim]\n")
+                except Exception as e:
+                    self.console.print(
+                        f"[bold red]Context persistence error:[/bold red] {e}\n"
+                    )
+
+            case "/loadcontext":
+                try:
+                    self.agent.restore_state()
+                    self.console.print(
+                        "[dim]Context recovered. Session state synchronized.[/dim]\n"
+                    )
+                except Exception as e:
+                    self.console.print(
+                        f"[bold red]Context restoration error:[/bold red] {e}\n"
+                    )
+
+        self.console.print(
+            Markdown("----"),
+            end="",
+        )
+
+    def repl(self):
+        logger.setLevel(logging.CRITICAL)
+        self.show_welcome()
+        self.pretty_print(f"----")
+
+        session = PromptSession(
+            erase_when_done=True,
+            history=self.prompt_history,
+            completer=self.completer,
+            mouse_support=True,
+        )
+
+        def as_table(prompt, message="", color="cyan"):
+            table = Table.grid(expand=True)
+            table.add_column(width=len(prompt) + 1)
+            table.add_column()
+
+            table.add_row(
+                Text(prompt, style=f"bold {color}"),
+                Markdown(message),
+            )
+            return table
+
+        input_prompt = "&gt;&gt;&gt; "  # >>>
+        input_prompt_history = "USER |"
+        output_prompt_history = "DEER |"
+
+        while True:
+            try:
+                msg = session.prompt(
+                    HTML(f"<ansicyan><b>{input_prompt}</b></ansicyan>")
+                )
+                self.save_prompt_history()
+
+                if self.agent.load_context:
+                    self.agent.persist_state()
+
+            except KeyboardInterrupt:
+                continue
+            except EOFError:
+                break
+
+            msg = msg.strip()
+            if not msg:
+                continue
+
+            match msg:
+                case command if command in COMMANDS:
+                    self.console.print(
+                        as_table(f"[{command}]", color="cyan"),
+                        Text("\n"),
+                        end="",
+                    )
+                    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()
+
+                    self.console.print(
+                        as_table(f"[{cmd_to_run}]", color="cyan"),
+                        Text("\n"),
+                        end="",
+                    )
+
+                    try:
+                        # Execute the command
+                        result = subprocess.run(
+                            cmd_to_run,
+                            shell=True,
+                            capture_output=True,
+                            text=True,
+                            check=True,
+                        )
+                        self.console.print(
+                            Text(result.stdout),
+                            Markdown("----"),
+                            sep="",
+                        )
+
+                    except subprocess.CalledProcessError as e:
+                        self.console.print(
+                            f"[dim]Error executing command: {e.stderr}[/dim]",
+                            Markdown("----"),
+                            sep="",
+                        )
+                    except Exception as e:
+                        self.console.print(
+                            f"[dim]An unexpected error occurred: {e}[/dim]",
+                            Markdown("----"),
+                            sep="",
+                        )
+
+                case _:
+                    if msg.startswith("/"):
+                        self.pretty_print(
+                            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",
+                    ):
+                        try:
+                            self.console.print(
+                                as_table(input_prompt_history, msg),
+                                Text("\n"),
+                                end="",
+                            )
+
+                            # Call the LLM model
+                            response = self.agent.run(msg)
+
+                            self.console.print(
+                                as_table(output_prompt_history, response),
+                                Text("\n"),
+                                Markdown("----"),
+                                end="",
+                            )
+
+                        except KeyboardInterrupt:
+                            self.console.print(
+                                "[dim]Command aborted by user[/dim]\n",
+                                Markdown("----"),
+                                sep="",
+                            )
+                            continue
+                        except EOFError:
+                            break