deer-agent-framework 0.0__tar.gz → 0.1a2__tar.gz

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

@@ -1,8 +1,21 @@
 Metadata-Version: 2.4
 Name: deer-agent-framework
-Version: 0.0
+Version: 0.1a2
 Summary: DEER - Deterministic Executable Engine for Runtime-agents
 Author: Yeison
+License: BSD-2-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -21,8 +34,18 @@ Dynamic: license-file
 
 **DEER** is the first framework designed for building **Deterministic Agents** in production environments where "it usually works" isn't good enough. While other frameworks rely on massive system prompts and probabilistic loops, DEER subordinates LLMs to rigid, code-defined software structures.
 
-[![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)](LICENSE)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)
+![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)
+![GitHub top language](https://img.shields.io/github/languages/top/dunderlab/deer-agent-framework)
+![PyPI - License](https://img.shields.io/pypi/l/deer-agent-framework)
+![PyPI](https://img.shields.io/pypi/v/deer-agent-framework)
+![PyPI - Status](https://img.shields.io/pypi/status/deer-agent-framework)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/deer-agent-framework)
+![GitHub last commit](https://img.shields.io/github/last-commit/dunderlab/deer-agent-framework)
+![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/dunderlab/deer-agent-framework)
+![Upload Python Package](https://github.com/dunderlab/deer-agent-framework/actions/workflows/python-publish.yml/badge.svg)
+
+[//]: # ([![Documentation Status](https://readthedocs.org/projects/chaski-confluent/badge/?version=latest)](https://chaski-confluent.readthedocs.io/en/latest/?badge=latest))
 
 ---
 
@@ -56,13 +79,13 @@ agent = DeterministicAgent(
     ),
     driver=get_driver_from_parser(),
     registry=registry,
-    jail_path=Path.cwd() / "sandbox", # Strict security boundary
+    jail_path=Path.cwd() / "sandbox",  # Strict security boundary
     format_response="markdown",
-    max_tries_for_plan=5
+    max_retries=5
 )
 
 if __name__ == "__main__":
-    agent.repl() # Instant interactive shell
+    agent.repl()  # Instant interactive shell
 ```
 
 ### 2. Assemble your Tool Registry

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

@@ -4,8 +4,18 @@
 
 **DEER** is the first framework designed for building **Deterministic Agents** in production environments where "it usually works" isn't good enough. While other frameworks rely on massive system prompts and probabilistic loops, DEER subordinates LLMs to rigid, code-defined software structures.
 
-[![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)](LICENSE)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)
+![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)
+![GitHub top language](https://img.shields.io/github/languages/top/dunderlab/deer-agent-framework)
+![PyPI - License](https://img.shields.io/pypi/l/deer-agent-framework)
+![PyPI](https://img.shields.io/pypi/v/deer-agent-framework)
+![PyPI - Status](https://img.shields.io/pypi/status/deer-agent-framework)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/deer-agent-framework)
+![GitHub last commit](https://img.shields.io/github/last-commit/dunderlab/deer-agent-framework)
+![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/dunderlab/deer-agent-framework)
+![Upload Python Package](https://github.com/dunderlab/deer-agent-framework/actions/workflows/python-publish.yml/badge.svg)
+
+[//]: # ([![Documentation Status](https://readthedocs.org/projects/chaski-confluent/badge/?version=latest)](https://chaski-confluent.readthedocs.io/en/latest/?badge=latest))
 
 ---
 
@@ -39,13 +49,13 @@ agent = DeterministicAgent(
     ),
     driver=get_driver_from_parser(),
     registry=registry,
-    jail_path=Path.cwd() / "sandbox", # Strict security boundary
+    jail_path=Path.cwd() / "sandbox",  # Strict security boundary
     format_response="markdown",
-    max_tries_for_plan=5
+    max_retries=5
 )
 
 if __name__ == "__main__":
-    agent.repl() # Instant interactive shell
+    agent.repl()  # Instant interactive shell
 ```
 
 ### 2. Assemble your Tool Registry

{deer_agent_framework-0.0 → deer_agent_framework-0.1a2}/deer/builtins/python_manager/agent.py

@@ -21,7 +21,7 @@ agent = DeterministicAgent(
     registry=registry,
     jail_path=Path.cwd(),
     format_response="markdown",
-    max_tries_for_plan=5,
+    max_retries=5,
     rollback=None,
 )
 

deer_agent_framework-0.1a2/deer/builtins/python_manager/tools.py

@@ -0,0 +1,112 @@
+from deer.tools.registry import ToolRegistry
+from deer.tools.builtin import (
+    FileManager,
+    GitManager,
+    SearchManager,
+    MemoryManager,
+    NetworkManager,
+    RuntimeManager,
+    StructuredDataInspector,
+    SystemInspector,
+)
+
+jail_path = "/Users/yeison/Development/deer-agent-framework/sandbox/root"
+
+registry = ToolRegistry()
+
+fileManager = FileManager(
+    # tools=[
+    #     "new_file",
+    #     "read_file",
+    #     "delete_file",
+    #     "create_directory",
+    #     "get_file_info",
+    #     "directory_tree",
+    #     "patch_file",
+    # ],
+)
+
+gitManager = GitManager(
+    # tools=[
+    #     "git_status",
+    #     "git_current_branch",
+    #     "git_log",
+    #     "git_diff",
+    #     "git_staged_diff",
+    #     "git_show",
+    #     "git_add",
+    #     "git_commit",
+    #     "git_restore",
+    # ],
+)
+
+searchManager = SearchManager(
+    # tools=[
+    #     "search_text",
+    #     "search_regex",
+    #     "search_text_ignore_case",
+    #     "search_regex_ignore_case",
+    #     "find_files",
+    #     "search_file_names",
+    #     "list_files",
+    #     "search_by_extension",
+    #     "search_text_in_files",
+    #     "files_with_matches",
+    #     "files_without_matches",
+    #     "count_matches",
+    # ],
+)
+
+memoryManager = MemoryManager(
+    # tools=[
+    #     "store_key_insight",
+    #     "retrieve_key_insight",
+    #     "list_memory_keys",
+    #     "clear_context_memory",
+    # ]
+)
+
+networkManager = NetworkManager(
+    # tools=[
+    #     "fetch_endpoint",
+    #     "download_asset",
+    #     "check_url_availability",
+    # ]
+)
+
+runtimeManager = RuntimeManager(
+    # tools=[
+    #     "execute_test_suite",
+    #     "compile_source_code",
+    #     "check_process_status",
+    #     "terminate_process",
+    # ]
+)
+
+structuredDataInspector = StructuredDataInspector(
+    # tools=[
+    #     "inspect_json_keys",
+    #     "preview_csv_columns",
+    #     "query_sqlite_metadata",
+    #     "execute_sqlite_statement",
+    # ]
+)
+
+systemInspector = SystemInspector(
+    # tools=[
+    #     "get_environment_variable",
+    #     "list_active_processes",
+    #     "check_network_sockets",
+    # ]
+)
+
+registry.register(
+    fileManager,
+    gitManager,
+    searchManager,
+    memoryManager,
+    networkManager,
+    runtimeManager,
+    structuredDataInspector,
+    systemInspector,
+)

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

@@ -24,7 +24,6 @@ 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
 
@@ -37,7 +36,7 @@ class DeterministicAgent:
         self,
         description: str = "",
         identity: str = "DeterministicAgent",
-        max_tries_for_plan: int = 3,
+        max_retries: int = 3,
         driver: LLMDriver | None = None,
         registry: ToolRegistry | None = None,
         format_response: str = "plaintext",
@@ -68,9 +67,9 @@ class DeterministicAgent:
         )
 
         assert (
-            max_tries_for_plan > 0
-        ), f"max_tries_for_plan must be positive, got {max_tries_for_plan}"
-        self.max_tries_for_plan = max_tries_for_plan
+                max_retries > 0
+        ), f"max_tries_for_plan must be positive, got {max_retries}"
+        self.max_retries = max_retries
 
         self.history = []
         self.trace = []
@@ -152,14 +151,14 @@ class DeterministicAgent:
 
         response_validation = None
 
-        for attempt_idx in range(self.max_tries_for_plan):
-            logger.debug(f"Attempt {attempt_idx + 1} of {self.max_tries_for_plan}")
+        for attempt_idx in range(self.max_retries):
+            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_tries_for_plan):
+            for solution_idx in range(self.max_retries):
                 logger.debug(
-                    f"Solution planning {solution_idx + 1} of {self.max_tries_for_plan}"
+                    f"Solution planning {solution_idx + 1} of {self.max_retries}"
                 )
                 run_trace[f"Attempt-{attempt_idx + 1}"][
                     f"Solution-{solution_idx + 1}"
@@ -174,7 +173,7 @@ class DeterministicAgent:
 
             if response is None:
                 logger.warning(
-                    f"Agent failed to produce a response after {self.max_tries_for_plan} attempts"
+                    f"Agent failed to produce a response after {self.max_retries} attempts"
                 )
                 if last_error_message:
                     last_error_message_explained = self.explain_error(
@@ -199,9 +198,9 @@ class DeterministicAgent:
                     for s in response.trace
                 ],
             }
-            for verification_idx in range(self.max_tries_for_plan):
+            for verification_idx in range(self.max_retries):
                 logger.debug(
-                    f"Verification planning {verification_idx + 1} of {self.max_tries_for_plan}"
+                    f"Verification planning {verification_idx + 1} of {self.max_retries}"
                 )
                 run_trace[f"Attempt-{attempt_idx + 1}"][
                     f"Verification-{verification_idx + 1}"
@@ -229,7 +228,7 @@ class DeterministicAgent:
 
             if response_validation is None:
                 logger.warning(
-                    f"Agent failed to verificate after {self.max_tries_for_plan} attempts"
+                    f"Agent failed to verificate after {self.max_retries} attempts"
                 )
                 continue
 

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

@@ -5,6 +5,8 @@ import os
 from .base_driver import LLMDriver
 from .gemini_driver import GeminiDriver
 from .ollama_driver import OllamaDriver
+from .openai_driver import OpenAIDriver
+from .azure_driver import AzureOpenAIDriver
 
 from deer.utils.console import error
 
@@ -12,6 +14,7 @@ backends = {
     "gemini",
     "openai",
     "ollama",
+    "azure",
 }
 
 drivers_parser = argparse.ArgumentParser(description="DEER Agent Framework CLI")
@@ -62,5 +65,7 @@ def get_driver_from_parser():
             return OllamaDriver(model_name=args.model)
 
         case "openai":
-            pass
-            # return OpenAIDriver(model_name=args.model)
+            return OpenAIDriver(model_name=args.model)
+
+        case "azure":
+            return AzureOpenAIDriver(model_name=args.model)

deer_agent_framework-0.1a2/deer/drivers/azure_driver.py

@@ -0,0 +1,41 @@
+import os
+from typing import Optional
+
+from .base_driver import OpenAIStandardDriver
+
+
+class AzureOpenAIDriver(OpenAIStandardDriver):
+    def __init__(
+        self,
+        model_name: str,
+        api_version: str = "2024-02-15-preview"
+    ):
+        super().__init__(model_name)
+        self.api_key = os.getenv("AZURE_OPENAI_API_KEY")
+        self.endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
+        self.api_version = api_version
+
+        if not self.api_key:
+            raise ValueError("AZURE_OPENAI_API_KEY environment variable is not set.")
+        if not self.endpoint:
+            raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is not set.")
+
+        # In Azure, the "model" in the payload is often ignored in favor of the deployment in the URL,
+        # but we keep it for compatibility with the base class logic.
+        self.base_url = self.endpoint.rstrip("/")
+
+    @property
+    def url(self) -> str:
+        # Azure URL format: {endpoint}/openai/deployments/{deployment_id}/chat/completions?api-version={api_version}
+        # We assume model_name is the deployment name.
+        return f"{self.base_url}/openai/deployments/{self.model_name}/chat/completions?api-version={self.api_version}"
+
+    @property
+    def headers(self) -> dict:
+        return {
+            "api-key": self.api_key,
+            "Content-Type": "application/json"
+        }
+
+    def __repr__(self) -> str:
+        return "AzureOpenAI"

deer_agent_framework-0.1a2/deer/drivers/base_driver.py

@@ -0,0 +1,123 @@
+from typing import Protocol, Type, TypeVar
+import re
+import json
+import urllib.request
+import urllib.error
+from typing import TypeVar, Type, Optional, Any
+import logging
+
+from pydantic import BaseModel
+
+# T represents any class inheriting from BaseModel
+T = TypeVar("T", bound=BaseModel)
+logger = logging.getLogger("DEER-LLM")
+
+
+class LLMDriver(Protocol):
+    """Contract for drivers supporting Architectural Brilliance."""
+    temperature_json = 0.0
+    top_p = 1.0
+
+    def __init__(self, model_name: str):
+        self.model_name = model_name
+
+    def _send_post_request(self, url: str, payload: dict, headers: Optional[dict] = None) -> dict:
+        """Centralized helper to handle HTTP POST requests for all drivers."""
+        if headers is None:
+            headers = {"Content-Type": "application/json"}
+        else:
+            headers.setdefault("Content-Type", "application/json")
+
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=headers)
+
+        try:
+            with urllib.request.urlopen(req) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8")
+            logger.error(f"HTTP Error {e.code}: {error_body}")
+            raise RuntimeError(f"API request failed with status {e.code}: {error_body}")
+        except urllib.error.URLError as e:
+            logger.error(f"URL Error: {e.reason}")
+            raise RuntimeError(f"Failed to reach server: {e.reason}")
+
+    def generate_text(self, prompt: str) -> str:
+        raise NotImplementedError("Subclasses must implement generate_text")
+
+    def generate_json(self, prompt: str, response_model: Optional[Type[T]] = None) -> T:
+        raise NotImplementedError("Subclasses must implement generate_json")
+
+    def extract_json(self, text: str) -> dict:
+        text = text.strip()
+        text = re.sub(r"^```(?:json)?\s*", "", text)
+        text = re.sub(r"^json\s*", "", text)
+        text = re.sub(r"\s*```$", "", text)
+        return json.loads(text)
+
+
+class OpenAIStandardDriver(LLMDriver):
+    """Base driver for OpenAI-compatible APIs."""
+
+    def __init__(self, model_name: str):
+        super().__init__(model_name)
+        # Use defaults from LLMDriver protocol if not set
+        self.temperature_json = getattr(self, "temperature_json", 0.0)
+        self.top_p = getattr(self, "top_p", 1.0)
+
+    @property
+    def url(self) -> str:
+        raise NotImplementedError("Subclasses must implement url property")
+
+    @property
+    def headers(self) -> dict:
+        raise NotImplementedError("Subclasses must implement headers property")
+
+    def generate_text(self, prompt: str) -> str:
+        logger.debug(f"Generating text with model {self.model_name} and prompt: {prompt}")
+
+        payload = {
+            "model": self.model_name,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": self.temperature_json,
+            "top_p": self.top_p,
+        }
+
+        try:
+            response_json = self._send_post_request(self.url, payload, headers=self.headers)
+            return response_json["choices"][0]["message"]["content"]
+        except (KeyError, IndexError) as e:
+            logger.error(f"Unexpected response structure from API: {e}")
+            raise RuntimeError(f"Failed to parse text from API response: {e}")
+
+    def generate_json(self, prompt: str, response_model: Optional[Type[T]] = None) -> T:
+        logger.debug(f"Generating JSON with model {self.model_name} and prompt: {prompt}")
+
+        payload = {
+            "model": self.model_name,
+            "messages": [{"role": "user", "content": prompt}],
+            "response_format": {"type": "json_object"},
+            "temperature": self.temperature_json,
+            "top_p": self.top_p,
+        }
+
+        try:
+            response_json = self._send_post_request(self.url, payload, headers=self.headers)
+            response_text = response_json["choices"][0]["message"]["content"]
+            data = json.loads(response_text)
+        except (KeyError, IndexError, json.JSONDecodeError) as e:
+            logger.error(f"Error parsing JSON response from API: {e}")
+            # Try fallback extraction
+            try:
+                # We need to reach the response_text if it was already assigned before error
+                if 'response_text' in locals():
+                    data = self.extract_json(response_text)
+                else:
+                    raise
+            except Exception:
+                raise RuntimeError(f"Error processing JSON output from API: {e}")
+
+        if response_model:
+            data = response_model.model_validate(data)
+
+        return data

deer_agent_framework-0.1a2/deer/drivers/openai_driver.py

@@ -0,0 +1,26 @@
+import os
+from typing import Optional
+
+from .base_driver import OpenAIStandardDriver
+
+
+class OpenAIDriver(OpenAIStandardDriver):
+    def __init__(self, model_name: str):
+        super().__init__(model_name)
+        self.api_key = os.getenv("OPENAI_API_KEY")
+        if not self.api_key:
+            raise ValueError("OPENAI_API_KEY environment variable is not set.")
+
+    @property
+    def url(self) -> str:
+        return "https://api.openai.com/v1/chat/completions"
+
+    @property
+    def headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json"
+        }
+
+    def __repr__(self) -> str:
+        return "OpenAI"

{deer_agent_framework-0.0 → deer_agent_framework-0.1a2}/deer/schema/io.py

@@ -38,3 +38,6 @@ def Return(**fields: Any) -> type[BaseModel]:
         f"InlineModel_{next(_counter)}",
         **{name: (field_type, ...) for name, field_type in fields.items()},
     )
+
+
+CommandOut = Return(stdout=str, stderr=str, returncode=int, message=str)

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

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

{deer_agent_framework-0.0 → deer_agent_framework-0.1a2}/deer/tools/base.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel
 from pathlib import Path
 import subprocess
 import shlex
-
+import shutil
 
 class ToolProviderError(ValueError):
     pass
@@ -18,13 +18,29 @@ class CommandRunnerError(ValueError):
 
 @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
 
+        for command in self.commands or []:
+            self.check_command(command)
+
+    @property
+    def commands(self):
+        """Return the list of commands to be verified at agent startup."""
+        return []
+
+    @property
+    def allowed_commands(self):
+        """Return the list of allowed execution commands.
+
+        If a command is not present in this list, its execution will fail
+        at runtime.
+        """
+        return []
+
     @property
     def jail(self):
         assert self.jail_ is not None, (
@@ -75,11 +91,36 @@ class ToolProvider:
         timeout_seconds: int = 30,
     ) -> dict:
         """Execute a command string without invoking a shell."""
-        args = shlex.split(command)
+
+        try:
+            args = shlex.split(command)
+        except ValueError as e:
+            return {
+                "stdout": "",
+                "stderr": str(e),
+                "returncode": -1,
+                "message": f"Shell expansion error: {e}",
+            }
 
         if not args:
             raise CommandRunnerError("Command cannot be empty.")
 
+        if self.allowed_commands:
+            is_allowed = False
+            for allowed_cmd in self.allowed_commands:
+                allowed_args = shlex.split(allowed_cmd)
+                if len(args) >= len(allowed_args) and args[: len(allowed_args)] == allowed_args:
+                    is_allowed = True
+                    break
+
+            if not is_allowed:
+                return {
+                    "stdout": "",
+                    "stderr": f"Command '{command}' is not allowed.",
+                    "returncode": -1,
+                    "message": f"Security restriction: '{command}' is not in the allowed list or doesn't match an allowed prefix.",
+                }
+
         safe_cwd = self.jail if cwd is None else self.jailed_path(cwd)
 
         completed = subprocess.run(
@@ -95,8 +136,22 @@ class ToolProvider:
             "stdout": completed.stdout,
             "stderr": completed.stderr,
             "returncode": completed.returncode,
+            "message": "",
         }
 
+    def check_command(self, command: str | Path) -> None:
+        """
+        Validates if a command exists in the operating system.
+        Raises CommandRunnerError if the executable is not found in the PATH.
+        """
+        # Convert to string for compatibility with Windows and Python < 3.12
+        cmd_str = str(command)
+        if shutil.which(cmd_str) is None:
+            raise CommandRunnerError(
+                f"The command '{cmd_str}' is not available on the system. "
+                f"Please ensure it is installed and configured in your PATH."
+            )
+
 
 class Tool(ABC):
     """Base contract for deterministic tools."""

deer_agent_framework-0.1a2/deer/tools/builtin/__init__.py

@@ -0,0 +1,8 @@
+from .file_manager import FileManager
+from .git_manager import GitManager
+from .search_manager import SearchManager
+from .memory_manager import MemoryManager
+from .network_manager import NetworkManager
+from .runtime_manager import RuntimeManager
+from .structured_data_inspector import StructuredDataInspector
+from .system_inspector import SystemInspector