deer-agent-framework 0.0__tar.gz

deer_agent_framework-0.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, DunderLab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

deer_agent_framework-0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: deer-agent-framework
+Version: 0.0
+Summary: DEER - Deterministic Executable Engine for Runtime-agents
+Author: Yeison
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich
+Requires-Dist: prompt_toolkit
+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"
+Dynamic: license-file
+
+# DEER: Deterministic Executable Engine for Runtime Agents
+
+### **Stop building "Vibe-based" Agents. Start Engineering Deterministic Agents.**
+
+**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/)
+
+---
+
+## Why DEER?
+
+Most agent frameworks suffer from **"Prompt Drift"**: you change one word in a system prompt and the whole logic breaks. DEER replaces "vibes" with **Deterministic Agents** powered by **Code Contracts**.
+
+*   **Logic over Prompts:** Define your **Deterministic Agent**'s behavior in Python, not in a 2000-word text file.
+*   **Typed Tooling:** Every tool has a Pydantic-validated input and output. No more "hallucinated" arguments.
+*   **Jailed by Design:** Built-in filesystem sandboxing (Jail) ensures your **Deterministic Agent** can't escape its directory.
+*   **Verification Loops:** The agent doesn't just "execute"; it validates the result against the original goal using deterministic traces.
+
+---
+
+## The DEER Workflow: Code-First Implementation
+
+### 1. Define your Deterministic Agent's Identity
+Forget about telling the AI to "act like a specialist." Define a high-level `DeterministicAgent` with clear boundaries and a specific tool registry.
+
+```python
+from pathlib import Path
+from deer.core.agent import DeterministicAgent
+from deer.drivers import get_driver_from_parser
+from .tools import registry
+
+agent = DeterministicAgent(
+    description="Python Architecture Specialist",
+    identity=(
+        "You are a Principal Python Architect. You possess authoritative expertise "
+        "in advanced module resolution and dependency management."
+    ),
+    driver=get_driver_from_parser(),
+    registry=registry,
+    jail_path=Path.cwd() / "sandbox", # Strict security boundary
+    format_response="markdown",
+    max_tries_for_plan=5
+)
+
+if __name__ == "__main__":
+    agent.repl() # Instant interactive shell
+```
+
+### 2. Assemble your Tool Registry
+Combine built-in managers (File, Git, Search) into a single, cohesive unit of execution for your **Deterministic Agent**.
+
+```python
+from deer.tools.registry import ToolRegistry
+from deer.tools.builtin import FileManager, GitManager, SearchManager
+
+registry = ToolRegistry()
+
+# Add specialized capabilities with zero-config
+registry.register(
+    FileManager(),
+    GitManager(),
+    SearchManager(),
+)
+```
+
+### 3. Create Custom Tools with Pydantic Validation
+Extending your **Deterministic Agent** is as simple as writing a class. The `@tool` decorator automatically generates the JSON schema for the LLM, ensuring perfect compatibility.
+
+```python
+from deer.tools import ToolProvider, tool, Return
+
+class MyCustomProvider(ToolProvider):
+    @tool(modifies_state=True)
+    def deploy_module(self, name: str, version: str) -> Return(status=str, job_id=int):
+        """Deploys a specific python module to the internal repo."""
+        # Your deterministic logic here
+        return {"status": "success", "job_id": 12345}
+```
+
+---
+
+## Built-in Deterministic Agents
+
+The framework includes pre-configured **Deterministic Agents** in the `deer/builtins/` directory. These serve as both ready-to-use tools and reference implementations for building your own specialized architects and managers.
+
+---
+
+## Technical Differentiation
+
+| Feature | Traditional Frameworks (LangChain, etc.) | **DEER Deterministic Agents** |
+| :--- | :--- | :--- |
+| **Execution Flow** | Probabilistic (LLM decides next step) | **Deterministic** (Backend-validated Plan) |
+| **Tool Arguments** | Often Hallucinated | **Strictly Typed** (Pydantic Models) |
+| **Security** | None / Manual | **Built-in Jail (Sandbox)** |
+| **Debugging** | Black box / Tricky logs | **Step-by-Step Trace Replay** |
+| **Output** | Raw Text | **Validated & Humanized Data** |
+
+---
+
+## The "Assembly Line" Lifecycle
+
+A **Deterministic Agent** in DEER doesn't just "chat". It processes requests through a linear production line:
+
+1.  **Refinement:** The **Deterministic Agent** improves the user's goal for technical clarity.
+2.  **Planning:** The agent generates a complete JSON pipeline *before* executing anything.
+3.  **Static Analysis:** The `PlanValidator` checks the plan for cycles or type mismatches.
+4.  **Jailed Execution:** Tools run inside a secure sandbox.
+5.  **Verification:** A secondary "judge" loop confirms the result matches the goal.
+
+---
+
+## Empirical Evidence: Engineering vs. Vibes
+
+DEER isn't just a "good idea"—it's a measured engineering framework. Below is the data from **100 consecutive executions** of a complex Python architecture task using the `gemma4:31b` model.
+
+### 1. Planning Determinism
+While traditional agents hallucinate different paths every time, DEER's planning and validation loop ensures high predictability. 
+
+![Deterministic Path Frequencies](assets/planification_validation_paths_frequencies.svg)
+*Figure 1: Path frequency distribution. 90% of executions follow the same validated optimal path, ensuring production-grade reliability.*
+
+### 2. Full Trace Introspección
+Every decision, tool call, and validation step is recorded. This allows for deep auditing and performance profiling.
+
+![Trace Step Analysis](assets/planification_validation_paths.svg)
+*Figure 2: Multi-trace step analysis showing the density and consistency of the agent's internal logic across multiple runs.*
+
+---
+
+## Installation
+
+```bash
+pip install git+https://github.com/dunderlab/deer-agent-framework.git
+```
+
+*Requires Python 3.12+ and a valid LLM API Key (Gemini, Ollama, etc.).*
+
+---
+
+## License
+Licensed under the **BSD 2-Clause License**. See [LICENSE](LICENSE) for details.
+
+---
+**Built for developers who trust code, not prompts.**

deer_agent_framework-0.0/README.md

@@ -0,0 +1,146 @@
+# DEER: Deterministic Executable Engine for Runtime Agents
+
+### **Stop building "Vibe-based" Agents. Start Engineering Deterministic Agents.**
+
+**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/)
+
+---
+
+## Why DEER?
+
+Most agent frameworks suffer from **"Prompt Drift"**: you change one word in a system prompt and the whole logic breaks. DEER replaces "vibes" with **Deterministic Agents** powered by **Code Contracts**.
+
+*   **Logic over Prompts:** Define your **Deterministic Agent**'s behavior in Python, not in a 2000-word text file.
+*   **Typed Tooling:** Every tool has a Pydantic-validated input and output. No more "hallucinated" arguments.
+*   **Jailed by Design:** Built-in filesystem sandboxing (Jail) ensures your **Deterministic Agent** can't escape its directory.
+*   **Verification Loops:** The agent doesn't just "execute"; it validates the result against the original goal using deterministic traces.
+
+---
+
+## The DEER Workflow: Code-First Implementation
+
+### 1. Define your Deterministic Agent's Identity
+Forget about telling the AI to "act like a specialist." Define a high-level `DeterministicAgent` with clear boundaries and a specific tool registry.
+
+```python
+from pathlib import Path
+from deer.core.agent import DeterministicAgent
+from deer.drivers import get_driver_from_parser
+from .tools import registry
+
+agent = DeterministicAgent(
+    description="Python Architecture Specialist",
+    identity=(
+        "You are a Principal Python Architect. You possess authoritative expertise "
+        "in advanced module resolution and dependency management."
+    ),
+    driver=get_driver_from_parser(),
+    registry=registry,
+    jail_path=Path.cwd() / "sandbox", # Strict security boundary
+    format_response="markdown",
+    max_tries_for_plan=5
+)
+
+if __name__ == "__main__":
+    agent.repl() # Instant interactive shell
+```
+
+### 2. Assemble your Tool Registry
+Combine built-in managers (File, Git, Search) into a single, cohesive unit of execution for your **Deterministic Agent**.
+
+```python
+from deer.tools.registry import ToolRegistry
+from deer.tools.builtin import FileManager, GitManager, SearchManager
+
+registry = ToolRegistry()
+
+# Add specialized capabilities with zero-config
+registry.register(
+    FileManager(),
+    GitManager(),
+    SearchManager(),
+)
+```
+
+### 3. Create Custom Tools with Pydantic Validation
+Extending your **Deterministic Agent** is as simple as writing a class. The `@tool` decorator automatically generates the JSON schema for the LLM, ensuring perfect compatibility.
+
+```python
+from deer.tools import ToolProvider, tool, Return
+
+class MyCustomProvider(ToolProvider):
+    @tool(modifies_state=True)
+    def deploy_module(self, name: str, version: str) -> Return(status=str, job_id=int):
+        """Deploys a specific python module to the internal repo."""
+        # Your deterministic logic here
+        return {"status": "success", "job_id": 12345}
+```
+
+---
+
+## Built-in Deterministic Agents
+
+The framework includes pre-configured **Deterministic Agents** in the `deer/builtins/` directory. These serve as both ready-to-use tools and reference implementations for building your own specialized architects and managers.
+
+---
+
+## Technical Differentiation
+
+| Feature | Traditional Frameworks (LangChain, etc.) | **DEER Deterministic Agents** |
+| :--- | :--- | :--- |
+| **Execution Flow** | Probabilistic (LLM decides next step) | **Deterministic** (Backend-validated Plan) |
+| **Tool Arguments** | Often Hallucinated | **Strictly Typed** (Pydantic Models) |
+| **Security** | None / Manual | **Built-in Jail (Sandbox)** |
+| **Debugging** | Black box / Tricky logs | **Step-by-Step Trace Replay** |
+| **Output** | Raw Text | **Validated & Humanized Data** |
+
+---
+
+## The "Assembly Line" Lifecycle
+
+A **Deterministic Agent** in DEER doesn't just "chat". It processes requests through a linear production line:
+
+1.  **Refinement:** The **Deterministic Agent** improves the user's goal for technical clarity.
+2.  **Planning:** The agent generates a complete JSON pipeline *before* executing anything.
+3.  **Static Analysis:** The `PlanValidator` checks the plan for cycles or type mismatches.
+4.  **Jailed Execution:** Tools run inside a secure sandbox.
+5.  **Verification:** A secondary "judge" loop confirms the result matches the goal.
+
+---
+
+## Empirical Evidence: Engineering vs. Vibes
+
+DEER isn't just a "good idea"—it's a measured engineering framework. Below is the data from **100 consecutive executions** of a complex Python architecture task using the `gemma4:31b` model.
+
+### 1. Planning Determinism
+While traditional agents hallucinate different paths every time, DEER's planning and validation loop ensures high predictability. 
+
+![Deterministic Path Frequencies](assets/planification_validation_paths_frequencies.svg)
+*Figure 1: Path frequency distribution. 90% of executions follow the same validated optimal path, ensuring production-grade reliability.*
+
+### 2. Full Trace Introspección
+Every decision, tool call, and validation step is recorded. This allows for deep auditing and performance profiling.
+
+![Trace Step Analysis](assets/planification_validation_paths.svg)
+*Figure 2: Multi-trace step analysis showing the density and consistency of the agent's internal logic across multiple runs.*
+
+---
+
+## Installation
+
+```bash
+pip install git+https://github.com/dunderlab/deer-agent-framework.git
+```
+
+*Requires Python 3.12+ and a valid LLM API Key (Gemini, Ollama, etc.).*
+
+---
+
+## License
+Licensed under the **BSD 2-Clause License**. See [LICENSE](LICENSE) for details.
+
+---
+**Built for developers who trust code, not prompts.**

deer_agent_framework-0.0/deer/__init__.py

@@ -0,0 +1,36 @@
+import os
+from pathlib import Path
+
+
+def load_env_file(env_path: Path) -> None:
+    """Reads a .env file and loads its variables into os.environ natively."""
+    try:
+        with open(env_path, "r", encoding="utf-8") as f:
+            for line in f:
+                # Strip whitespace and ignore empty lines or comments
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+
+                # Split by the first '=' found
+                if "=" in line:
+                    key, value = line.split("=", 1)
+                    # Strip quotes if the value is wrapped in them
+                    key = key.strip()
+                    value = value.strip().strip("'\"")
+
+                    # Set the environment variable
+                    os.environ[key] = value
+    except IOError as e:
+        # Log or handle the error if the file exists but can't be read
+        pass
+
+
+# Your configuration logic remains clean and dependency-free
+local_env = Path(".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)

deer_agent_framework-0.0/deer/builtins/__init__.py

@@ -0,0 +1,7 @@
+import os
+
+agents = {
+    "python_manager": os.path.join(
+        os.path.dirname(__file__), "python_manager", "agent.py"
+    ),
+}

deer_agent_framework-0.0/deer/builtins/python_manager/agent.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from deer.core.agent import DeterministicAgent
+from deer.drivers import get_driver_from_parser
+
+if __package__:
+    from .tools import registry
+else:
+    from tools import registry
+
+agent = DeterministicAgent(
+    description="Python Architecture Specialist expert in module lifecycle, dependency management, and package distribution.",
+    identity=(
+        "You are a Principal Python Architect and Core Ecosystem Specialist. You possess authoritative expertise "
+        "in advanced module resolution, dependency management architectures, package distribution, and internal "
+        "or public repository management. Your knowledge spans the entire lifecycle of Python code: from how "
+        "modules are imported and structured at runtime, to how dependencies are resolved, isolated, packaged, "
+        "and deployed across diverse environments."
+    ),
+    driver=get_driver_from_parser(),
+    registry=registry,
+    jail_path=Path.cwd(),
+    format_response="markdown",
+    max_tries_for_plan=5,
+    rollback=None,
+)
+
+if __name__ == "__main__":
+    agent.repl()

deer_agent_framework-0.0/deer/builtins/python_manager/tools.py

@@ -0,0 +1,54 @@
+from deer.tools.registry import ToolRegistry
+from deer.tools.builtin import FileManager, GitManager, SearchManager
+
+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",
+    # ],
+)
+
+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",
+    # ],
+)
+
+registry.register(
+    fileManager,
+    gitManager,
+    searchManager,
+)

deer_agent_framework-0.0/deer/core/__init__.py

@@ -0,0 +1 @@
+from .agent import DeterministicAgent