deer-agent-framework 0.0__py3-none-any.whl

deer/validator/__init__.py

@@ -0,0 +1 @@
+from .plan_validator import PlanValidator

deer/validator/plan_validator.py

@@ -0,0 +1,23 @@
+from typing import Callable
+from deer.schema.plan import Plan
+from deer.tools.registry import ToolRegistry
+from .rules import Rules
+
+Rule = Callable[[Plan], None]
+
+
+class PlanValidator:
+    """Validador de planes que compone múltiples reglas.
+
+    Uso:
+        validator = PlanValidator(registry)
+        validator.validate(plan)
+    """
+
+    def __init__(self, registry: ToolRegistry) -> None:
+        self.registry = registry
+
+    def validate(self, plan: Plan) -> None:
+
+        rules = Rules(plan, self.registry)
+        rules.validate()

deer/validator/rules.py

@@ -0,0 +1,98 @@
+import re
+from typing import Set
+import inspect
+import logging
+
+from deer.schema.plan import Plan
+from deer.tools.registry import ToolRegistry
+
+logger = logging.getLogger("DEER")
+
+
+class Rules:
+    """Mandatory validation rules for NOMOS executable plans."""
+
+    def __init__(self, plan: Plan, registry: ToolRegistry) -> None:
+        self.plan = plan
+        self.registry = registry
+
+    def validate(self) -> None:
+        """Dynamically discovers and executes all methods prefixed with 'check_'."""
+        checkers = inspect.getmembers(self, predicate=inspect.ismethod)
+        for name, method in checkers:
+            if name.startswith("check_"):
+                logger.debug(f"Validating rule: {name}")
+                method(self.plan)
+
+    def check_unique_step_ids(self, plan: Plan) -> None:
+        seen: Set[str] = set()
+        for s in plan.steps:
+            if s.id in seen:
+                raise ValueError(f"Duplicate step IDs detected: {s.id}")
+            seen.add(s.id)
+
+    def check_existing_references(self, plan: Plan) -> None:
+        ids = {s.id for s in plan.steps}
+        for s in plan.steps:
+            if s.input_from is not None and s.input_from not in ids:
+                raise ValueError(
+                    f"Step '{s.id}' references an unknown input_from: {s.input_from}"
+                )
+
+    def check_topological_order(self, plan: Plan) -> None:
+        """Ensures that input_from (if present) appears earlier in the sequence (preventing cycles/forward references)."""
+        index = {s.id: i for i, s in enumerate(plan.steps)}
+        for s in plan.steps:
+            if s.input_from is None:
+                continue
+            if index[s.input_from] >= index[s.id]:
+                raise ValueError(
+                    f"Invalid execution order: '{s.id}' depends on '{s.input_from}', which has not been executed yet"
+                )
+
+    def check_tools_registered(self, plan: Plan) -> None:
+        for s in plan.steps:
+            if s.tool and not self.registry.has(s.tool):
+                raise ValueError(f"Tool not found in ToolRegistry: {s.tool}")
+
+    def check_tools_registered_params(self, plan: Plan) -> None:
+        """Ensures tool steps provide exactly the parameters declared by the tool."""
+        for s in plan.steps:
+            if not s.tool:
+                continue
+
+            tool = self.registry.get(s.tool)
+            if not hasattr(tool, "params_type"):
+                continue
+
+            expected_params = set(tool.params_type or {})
+            provided_params = set(s.params or {})
+
+            missing = expected_params - provided_params
+            if missing:
+                raise ValueError(
+                    f"Step '{s.id}' is missing required params for tool "
+                    f"'{s.tool}': {', '.join(sorted(missing))}"
+                )
+
+            unknown = provided_params - expected_params
+            if unknown:
+                raise ValueError(
+                    f"Step '{s.id}' provides unknown params for tool "
+                    f"'{s.tool}': {', '.join(sorted(unknown))}"
+                )
+
+    def check_execution(self, plan: Plan) -> None:
+        for s in plan.steps:
+            if not s.tool and not s.logic:
+                raise ValueError(
+                    f"Step '{s.id}' is invalid: it must define either a 'tool' or a 'logic' block to be executed."
+                )
+
+    def check_logic_assignment(self, plan: Plan) -> None:
+        for s in plan.steps:
+            if logic := s.logic:
+                if not re.search(r"\bresult\s*=", logic):
+                    raise ValueError(
+                        f"Step '{s.id}' has invalid logic: it must assign a value to 'result' (e.g., 'result = ...')."
+                    )

deer_agent_framework-0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,52 @@
+deer/__init__.py,sha256=ifUGd9ihYllSbpPHFXmEOSLbPG9G_6h-Wsfp9NCA4w4,1164
+deer/main.py,sha256=c0wo0gsItnLi7SE5EKR_GVdfiLem1CKBKSCsnhZcl0U,1480
+deer/builtins/__init__.py,sha256=caSlXaz76tSogUhshgd8dmOPaHeBRPVh2qVMeQShAAg,131
+deer/builtins/python_manager/agent.py,sha256=-qclz3mDkh2b-mEZUmgShhbELNSeGFhb9OJsWnuLXqU,1100
+deer/builtins/python_manager/tools.py,sha256=eI5MPebDb7NHMNqseNt4IxzDZhw7lfk4BgwvuIla9ko,1193
+deer/core/__init__.py,sha256=YbWZ-Wn2_sTQf0mrWo2M0XJoo26tiSrmYj5PBKBRO-w,38
+deer/core/agent.py,sha256=Kvm7J-gCiN-E12xrwC7RO00srKUkz78afryLOxldvmY,15482
+deer/core/ui.py,sha256=q-fOzrP1ThPyfe2hfF0j6RMz6cqEtIeLxTQSrpk4094,894
+deer/drivers/__init__.py,sha256=UF0yV7dDwosr1lNO0fhMBBkS4HbClff9QGBhnWaR5Gk,1497
+deer/drivers/base_driver.py,sha256=FUhDQ_CsxfEkJFnNdrdzcVnr7MHI6DAAYD4NQeczZMY,2108
+deer/drivers/gemini_driver.py,sha256=Rr454dbuvckjOlGt8gUeWNC7KtF5aCS-RCR-ltZH1J4,2403
+deer/drivers/ollama_driver.py,sha256=WfQZjyPmOuni1KmkcspifDV9GWf6YYYDyKkrJZj3QZo,2185
+deer/executor/__init__.py,sha256=_esL73v9Gi40xb5N7UGxslIk8yHM6idQlXbzELR7XhA,31
+deer/executor/executor.py,sha256=U91of8bXGhvGyS1XuMS60Vzlro-cH3UP5OVdRb3GVQA,5282
+deer/executor/logic.py,sha256=uvPKyMPM9GqRNFbfnMvIJIJlaBfpSMma0DeS8lWWjg0,2399
+deer/executor/logic_secure.py,sha256=RpkK_LzEMiTF0TEtSE2I8kQwi67VMWeW8n51BPC1VRk,2889
+deer/planner/__init__.py,sha256=ooTZx2QA-6ySaL1JxyDSm3TQyzAhOW5fv2jPDI6iYeA,29
+deer/planner/planner.py,sha256=kwaZYTAhrG948QmylYOPhDWBPzM4I9RkZdAK9p8kfqw,2208
+deer/prompts/__init__.py,sha256=b5X52rjXI7eoqwGyUdz4K6yowKHl9K2BeL3hYJlt6CQ,313
+deer/prompts/error_explain.py,sha256=QWiFzvsjt93E5eQkDv3ZSUOE2_tz7oyd3RTmqHErVN8,1049
+deer/prompts/goal_improvement.py,sha256=_zGCOeToJ730UJUV97s_Yu_Uc-nNJv388UZOL-YzNJI,1611
+deer/prompts/goal_validation.py,sha256=c1s4uO8-oywtyaeArTyOseMDm-PcfTRSeEZPlqYzEL0,1099
+deer/prompts/humanizer.py,sha256=-a427rzJJRLtScINa5KlvvRZvqYjmRs2TtBNSUpW0FM,652
+deer/prompts/planner.py,sha256=0yrJjtTBEhDjAZjZFuEpelxwSqaliXoIdaw0xKAxHyU,4813
+deer/prompts/response_improvement.py,sha256=Vd1AackmULHrM_v-TckKNopLHFa86Lwcv8K3ktxScc4,748
+deer/schema/__init__.py,sha256=hDfzexGlSLnTvgRdmZEVScNymuspgHXSsMXJc549CmE,69
+deer/schema/io.py,sha256=ocWKvwyInrgyyjDB9YPBpA7Zm-JTzLoOvNP4PhH1gmg,976
+deer/schema/plan.py,sha256=Bxn2rDKy8Q_vus7GnRRtwbvYsrjYAgiBrVFYTiy5VH8,2169
+deer/tools/__init__.py,sha256=ZHnRX5jbMKhJLF_ks0BU_hixEqCxMvan--vueakqFsY,135
+deer/tools/base.py,sha256=k1L6FkPVClt-oqagN1fI84Ml_4WKuN_7Q-9iG0xENTk,3970
+deer/tools/decorators.py,sha256=BBmoRS5P1FXuaq8JOSEM2pglLt0u6xbv_XO_ChEizeM,3066
+deer/tools/registry.py,sha256=RSZ1t1fsa2rI_mW3XndfVvyucW2l-Xi41daOL2bFm2U,3312
+deer/tools/builtin/__init__.py,sha256=3Nw4LIQazbQJuWALxifEHUlzHbsf0U4KMNQ9KUX3reE,116
+deer/tools/builtin/file_manager.py,sha256=wnhUzRZQHiopuDZn536injBcZvxQ7yfZIUv0HlmzR4U,4052
+deer/tools/builtin/git_manager.py,sha256=_aZQ-9y_SDecx8d2_inADq6ui2ca3q-wb0XKjlgetVk,2471
+deer/tools/builtin/search_manager.py,sha256=QoRKABwzdC9gF99D9Bd0kYktfvjQ8KVmAgYyHmSROVg,4023
+deer/tracing/__init__.py,sha256=adxrIDXfgwLyNqYRDi5sUfR9WweeYHq93KGBuxMuZWA,77
+deer/tracing/logging_config.py,sha256=Do0r8UCmJEOQJRAAhVrS5myoUEY7clMKf1MWhLVBs-0,560
+deer/tracing/store.py,sha256=GXoUdfikPxTfxaEr2FAw7vb-LzraLLxu_iWCqpnkYus,584
+deer/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deer/utils/console.py,sha256=RM8G-JXn_6SqrzIc9daLspiU2L5trOr8tFomCYFYLEA,227
+deer/utils/plots/__init__.py,sha256=P7J8wm23suxDDREeZCjxzcD6brxdHP8XNkx3b18Urcw,150
+deer/utils/plots/plot_traces.py,sha256=OJSd__W6z0YpEBx4cTmgUKkodg1GQED0aZvKEcMOwMU,26659
+deer/validator/__init__.py,sha256=9gpKXZuTogJ15PeH97qkR2a2V1A67xfIhJjTqgcpXW4,42
+deer/validator/plan_validator.py,sha256=ymwBzd-HHQNgqqAsycr7K07SCYq6dvi63VMaTsyv8k8,543
+deer/validator/rules.py,sha256=Ir27wqXvG7Ghx7V1PdNXcVgFYQX6YOaXikNXS71dS7A,3761
+deer_agent_framework-0.0.dist-info/licenses/LICENSE,sha256=hOaNvKhAfQsJnPIB8u-MO0-bdaoQkLVO7k_ymroMxKw,1298
+deer_agent_framework-0.0.dist-info/METADATA,sha256=wObx0GEpXTcsIva-zc9hy6JV5WqSXxCxoOkQrAkfO2Y,6530
+deer_agent_framework-0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deer_agent_framework-0.0.dist-info/entry_points.txt,sha256=2kDeh5Omj3tcXBKn0osrZR8lrx9pmwq248Ae1QU55Vw,40
+deer_agent_framework-0.0.dist-info/top_level.txt,sha256=qERYun4uXbfcknYL72x6op65NIjQadU1mc8j38-vC74,5
+deer_agent_framework-0.0.dist-info/RECORD,,

deer_agent_framework-0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deer_agent_framework-0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+deer = deer.main:main

deer_agent_framework-0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+deer