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

deer/drivers/base_driver.py

@@ -0,0 +1,56 @@
+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)

deer/drivers/gemini_driver.py

@@ -0,0 +1,62 @@
+import json
+import os
+from typing import TypeVar, Type, Optional
+
+from pydantic import BaseModel
+
+from .base_driver import LLMDriver, logger
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class GeminiDriver(LLMDriver):
+    def __init__(self, model_name: str, api_version: str = "v1beta"):
+        super().__init__(model_name)
+        self.api_key = os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            raise ValueError("GEMINI_API_KEY environment variable is not set.")
+
+        # Setup the definitive REST endpoint for Gemini
+        self.url = f"https://generativelanguage.googleapis.com/{api_version}/models/{self.model_name}:generateContent?key={self.api_key}"
+
+    def __repr__(self) -> str:
+        return "Gemini"
+
+    def generate_text(self, prompt: str) -> str:
+        logger.debug(f"Generating text with model {self.model_name} and prompt: {prompt}")
+
+        payload = {
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {"responseMimeType": "text/plain"}
+        }
+
+        try:
+            response_json = self._send_post_request(self.url, payload)
+            return response_json["candidates"][0]["content"]["parts"][0]["text"]
+        except (KeyError, IndexError) as e:
+            logger.error(f"Unexpected response structure from Gemini API: {e}")
+            raise RuntimeError("Failed to parse text from Gemini API response.")
+
+    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 = {
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {"responseMimeType": "application/json"}
+        }
+
+        if response_model:
+            payload["generationConfig"]["responseSchema"] = response_model.model_json_schema()
+
+        try:
+            response_json = self._send_post_request(self.url, payload)
+            response_text = response_json["candidates"][0]["content"]["parts"][0]["text"]
+            data = json.loads(response_text)
+        except (KeyError, IndexError, json.JSONDecodeError) as e:
+            logger.error(f"Error parsing JSON response from Gemini: {e}")
+            raise RuntimeError(f"Error processing JSON output from Gemini: {e}")
+
+        if response_model:
+            data = response_model.model_validate(data)
+
+        return data

deer/drivers/ollama_driver.py

@@ -0,0 +1,69 @@
+import json
+from typing import TypeVar, Type, Optional
+
+from pydantic import BaseModel
+
+from .base_driver import LLMDriver, logger
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class OllamaDriver(LLMDriver):
+    def __init__(self, model_name: str, host: str = "http://localhost:11434"):
+        super().__init__(model_name)
+        self.base_url = host.rstrip("/")
+        self.url = f"{self.base_url}/api/generate"
+
+        # Default fallback values for generation options if not defined externally
+        self.temperature_json = getattr(self, "temperature_json", 0.2)
+        self.top_p = getattr(self, "top_p", 0.9)
+
+    def __repr__(self) -> str:
+        return "Ollama"
+
+    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,
+            "prompt": prompt,
+            "stream": False
+        }
+
+        response_json = self._send_post_request(self.url, payload)
+        return response_json.get("response", "")
+
+    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,
+            "prompt": prompt,
+            "stream": False,
+            "options": {
+                "temperature": self.temperature_json,
+                "top_p": self.top_p,
+            }
+        }
+
+        if response_model:
+            payload["format"] = response_model.model_json_schema()
+        else:
+            payload["format"] = "json"
+
+        response_json = self._send_post_request(self.url, payload)
+        response_text = response_json.get("response", "")
+
+        try:
+            data = json.loads(response_text)
+        except json.JSONDecodeError as e:
+            if hasattr(self, "extract_json"):
+                data = self.extract_json(response_text)
+            else:
+                logger.error(f"Failed to decode JSON from response: {e}")
+                raise
+
+        if response_model:
+            data = response_model.model_validate(data)
+
+        return data

deer/executor/__init__.py

@@ -0,0 +1 @@
+from .executor import Executor

deer/executor/executor.py

@@ -0,0 +1,168 @@
+import logging
+import re
+from typing import Any, Dict
+
+from deer.schema.io import AgentOutput, StepTrace
+from deer.schema.plan import Plan
+from deer.tracing.store import TraceStore
+from deer.tools.registry import ToolRegistry
+from .logic import evaluate_logic
+
+logger = logging.getLogger("DEER")
+
+
+class Executor:
+    def __init__(self, registry: ToolRegistry) -> None:
+        self.registry = registry
+        self.trace_store = TraceStore()
+
+    def execute(self, plan: Plan, payload: {}) -> AgentOutput:
+        self.trace_store.reset()
+        context: Dict[str, Any] = {}
+        last_output: Any = None
+
+        for step in plan.steps:
+            value = self.resolve_input(step.input_from, step.id, payload, context)
+            logger.debug(f"Executing step {step.id} with input '{step.input_from}'")
+
+            try:
+                if step.logic is not None:
+                    output = self.execute_logic(
+                        logic=step.logic,
+                        input_value=value,
+                        params=step.params or {},
+                        context=context,
+                    )
+                    trace_tool = "logic"
+
+                if step.tool is not None:
+                    params = self.resolve_params(step.params or {}, value, context)
+                    output = self.execute_tool(
+                        tool_name=step.tool,
+                        params=params,
+                    )
+                    trace_tool = step.tool
+
+                context[step.id] = output
+                last_output = output
+
+                self.trace_store.append(
+                    StepTrace(
+                        step_id=step.id,
+                        tool=trace_tool,
+                        input=value,
+                        output=output,
+                    )
+                )
+            except Exception as ex:
+                self.trace_store.append(
+                    StepTrace(
+                        step_id=step.id,
+                        tool=step.tool or "logic",
+                        input=value,
+                        output=None,
+                        error=str(ex),
+                    )
+                )
+                raise
+
+        return AgentOutput(result=last_output, trace=self.trace_store.get_trace())
+
+    def resolve_input(
+        self,
+        input_from: str | None,
+        step_id: str,
+        payload: {},
+        context: Dict[str, Any],
+    ) -> Any:
+        if input_from is None:
+            return payload
+
+        if input_from not in context:
+            raise ValueError(
+                f"Unresolved dependency: '{input_from}' required by step '{step_id}'."
+            )
+
+        output = context[input_from]
+
+        # # Automatically unwrap single-key dictionaries to simplify logic and tool usage.
+        # # This ensures 'input' refers directly to the value (e.g., file content)
+        # # instead of the wrapper dictionary.
+        # if isinstance(output, dict) and len(output) == 1:
+        #     return next(iter(output.values()))
+
+        return output
+
+    def resolve_params(
+        self,
+        params: Dict[str, Any],
+        input_value: Any,
+        context: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Resolves placeholders like 'input' or step IDs in parameters."""
+        resolved = {}
+        for k, v in params.items():
+            if v == "input":
+                resolved[k] = input_value
+            elif isinstance(v, str) and v in context:
+                resolved[k] = context[v]
+            else:
+                resolved[k] = v
+        return resolved
+
+    def execute_tool(
+        self,
+        tool_name: str,
+        params: Dict[str, Any],
+    ) -> Any:
+        tool = self.registry.get(tool_name)
+        input_params = tool.validate_input(params)
+        output = tool.run(params=input_params)
+        logger.info(f"Executed tool: {tool_name}")
+        logger.debug(f"Tool {tool_name} output: {output}")
+        return tool.validate_output(output)
+
+    def execute_logic(
+        self,
+        logic: str,
+        input_value: Any,
+        params: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        # logic = self.fix_multiline_strings(logic)
+        logger.debug(f"Executing logic: {logic}")
+        return evaluate_logic(
+            logic,
+            input_value=input_value,
+            params=params,
+            context=context,
+        )
+
+    #
+    # def fix_multiline_strings(self, code: str) -> str:
+    #     pattern = r'=\s*"([^"\n]*\n(?:.*\n)*?.*?)"'
+    #
+    #     def replacer(match):
+    #         content = match.group(1)
+    #         return '= """' + content + '"""'
+    #
+    #     return re.sub(pattern, replacer, code, flags=re.MULTILINE)
+
+    # def normalize_logic(self, logic: str) -> str:
+    #     logic = logic.strip()
+    #
+    #     # multiline JSON escapes
+    #     logic = logic.replace("\\n", "\n")
+    #
+    #     # Caso: string completo serializado
+    #     try:
+    #         parsed = json.loads(logic)
+    #         if isinstance(parsed, str):
+    #             logic = parsed
+    #     except Exception:
+    #         pass
+    #
+    #     # Caso: código Python contaminado con escaping JSON
+    #     logic = logic.replace('\\"', '"')
+    #
+    #     return logic

deer/executor/logic.py

@@ -0,0 +1,75 @@
+import ast
+from typing import Any, Dict, Mapping
+from .logic_secure import ALLOWED_NODE_TYPES, SAFE_GLOBALS
+
+
+class UnsafeLogicError(ValueError):
+    """Raised when the code contains disallowed or dangerous syntax."""
+
+
+def _is_safe_variable_name(name: str) -> bool:
+    return name.isidentifier() and not name.startswith("_")
+
+
+def evaluate_logic(
+    logic_code: str,
+    *,
+    input_value: Any,
+    params: Mapping[str, Any],
+    context: Mapping[str, Any],
+) -> Any:
+    """Safely executes Python code and returns the value of 'result'."""
+
+    # 1. Parse and Validate AST
+    try:
+        tree = ast.parse(logic_code, mode="exec")
+    except SyntaxError as e:
+        raise UnsafeLogicError(f"Syntax error in logic: {e}")
+
+    _validate_ast(tree)
+
+    # 2. Prepare Scope
+    local_scope = {
+        "input": input_value,
+        "params": dict(params),
+        "context": dict(context),
+    }
+
+    # Flatten dictionaries for direct access
+    if isinstance(input_value, dict):
+        for key, value in input_value.items():
+            if _is_safe_variable_name(key):
+                local_scope[key] = value
+
+    for key, value in params.items():
+        if _is_safe_variable_name(key):
+            local_scope[key] = value
+
+    # 3. Execute
+    try:
+        compiled = compile(tree, filename="<step.logic>", mode="exec")
+        exec(compiled, SAFE_GLOBALS, local_scope)
+    except Exception as e:
+        raise RuntimeError(f"Runtime error in logic execution: {e}")
+
+    if "result" not in local_scope:
+        raise UnsafeLogicError("Logic must assign a value to the 'result' variable.")
+
+    return local_scope["result"]
+
+
+def _validate_ast(tree: ast.AST) -> None:
+    for node in ast.walk(tree):
+        if not isinstance(node, ALLOWED_NODE_TYPES):
+            raise UnsafeLogicError(f"Disallowed syntax: {type(node).__name__}")
+
+        # Do not allow access to private attributes (._secret)
+        if isinstance(node, ast.Attribute) and node.attr.startswith("_"):
+            raise UnsafeLogicError("Access to private attributes is not allowed.")
+
+        # Do not allow assignments to protected variables
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            if node.id.startswith("_") or node.id in SAFE_GLOBALS:
+                raise UnsafeLogicError(
+                    f"Cannot assign a value to protected variable: {node.id}"
+                )

deer/executor/logic_secure.py

@@ -0,0 +1,102 @@
+import ast
+import math
+
+# Allowed nodes to support mathematical logic, strings, and basic assignments
+ALLOWED_NODE_TYPES = (
+    # --- Basic Structure ---
+    ast.Module,  # Root container
+    ast.Expr,  # Standalone expressions
+    ast.Assign,  # Variable assignment (e.g., x = 10)
+    ast.Load,  # Load variable value
+    ast.Store,  # Store variable value
+    ast.Name,  # Variable names
+    ast.Constant,  # Literal values (numbers, strings, None, True, False)
+    # --- Mathematical Operations ---
+    ast.BinOp,  # Binary operations (+, -, *, /)
+    ast.UnaryOp,  # Unary operations (not, -x)
+    ast.Add,
+    ast.Sub,
+    ast.Mult,
+    ast.Div,
+    ast.FloorDiv,
+    ast.Mod,
+    ast.Pow,
+    ast.USub,
+    ast.UAdd,
+    # --- Logic and Comparison ---
+    ast.Compare,  # Comparisons (==, !=, <, etc.)
+    ast.Eq,
+    ast.NotEq,
+    ast.Lt,
+    ast.LtE,
+    ast.Gt,
+    ast.GtE,
+    ast.In,
+    ast.NotIn,
+    ast.BoolOp,  # Logical operators (and, or)
+    ast.And,
+    ast.Or,
+    ast.IfExp,  # Ternary expressions (x if condition else y)
+    # --- Data Structures and Access ---
+    ast.List,  # [1, 2, 3]
+    ast.Dict,  # {'a': 1}
+    ast.Tuple,  # (1, 2)
+    ast.Set,  # {1, 2}
+    ast.Subscript,  # Indexed/key access: list[0] or dict['k']
+    ast.Slice,  # Slicing: list[1:5]
+    ast.Attribute,  # Attribute access: object.property (required for Pydantic)
+    # --- Strings and Formatting ---
+    ast.JoinedStr,  # f-strings
+    ast.FormattedValue,  # Values inside f-strings
+    # --- Calls and Functions ---
+    ast.Call,  # Allow calling functions from _SAFE_GLOBALS
+    ast.keyword,  # Keyword arguments: func(x=1)
+    # --- Advanced Safe Flexibility ---
+    ast.ListComp,  # [x for x in items] (useful for data transformation)
+    ast.DictComp,  # {k: v for k, v in items}
+    ast.comprehension,  # Internal comprehension logic
+)
+
+SAFE_GLOBALS = {
+    # --- Sandbox Privacy ---
+    "__builtins__": {},  # Blocks access to dangerous functions like eval, exec, open
+    # --- Mathematical Constants ---
+    "pi": math.pi,
+    "e": math.e,
+    # --- Arithmetic and Numbers ---
+    "abs": abs,
+    "min": min,
+    "max": max,
+    "round": round,
+    "pow": pow,
+    "sum": sum,
+    "sqrt": math.sqrt,
+    "log": math.log,
+    "exp": math.exp,
+    "ceil": math.ceil,
+    "floor": math.floor,
+    "sin": math.sin,
+    "cos": math.cos,
+    "tan": math.tan,
+    # --- Type Conversion (Casting) ---
+    "str": str,
+    "int": int,
+    "float": float,
+    "bool": bool,
+    "list": list,
+    "dict": dict,
+    "set": set,
+    "tuple": tuple,
+    # --- Collection Processing ---
+    "len": len,
+    "range": range,
+    "enumerate": enumerate,
+    "zip": zip,
+    "sorted": sorted,  # Allows safe list sorting
+    "reversed": reversed,
+    # --- Advanced Logic ---
+    "any": any,  # Is any value True?
+    "all": all,  # Are all values True?
+    "filter": filter,
+    "map": map,
+}

deer/main.py

@@ -0,0 +1,71 @@
+import subprocess
+import sys
+
+from rich.text import Text
+
+from deer.builtins import agents
+from deer.utils.console import console, error, info
+from deer.drivers import drivers_parser
+
+
+def title():
+    console.print()
+    console.print(
+        Text(
+            "DEER",
+            style="bold cyan",
+        )
+    )
+    console.print(
+        "Deterministic Executable Engine for Runtime Agents",
+        style="dim",
+    )
+    console.print()
+
+
+def agents_list():
+    console.print()
+    console.print("[bold]Available agents[/bold]")
+    for name in agents:
+        console.print(f"  • [green]{name}[/green]")
+    console.print()
+
+
+def example():
+    console.print("[dim]Example:[/dim] deer python_manager")
+
+
+def main():
+    args = drivers_parser.parse_args()
+
+    title()
+
+    if selected_agent := args.agent:
+        if selected_agent in agents:
+            info(f"Launching agent '{selected_agent}'")
+
+            command = [
+                sys.executable,
+                agents[selected_agent],
+            ]
+
+            if args.backend:
+                command.extend(["--backend", args.backend])
+
+            if args.model:
+                command.extend(["--model", args.model])
+
+            result = subprocess.run(command)
+            sys.exit(result.returncode)
+
+        error(f"Unknown agent '{selected_agent}'")
+        agents_list()
+        sys.exit(1)
+
+    error("No agent selected")
+    example()
+    agents_list()
+
+
+if __name__ == "__main__":
+    main()

deer/planner/__init__.py

@@ -0,0 +1 @@
+from .planner import Planner

deer/planner/planner.py

@@ -0,0 +1,71 @@
+import json
+
+from deer.prompts import PLANNER_PROMPT, GOAL_IMPROVEMENT_PROMPT
+from deer.schema.io import AgentInput
+from deer.tools.registry import ToolRegistry
+from deer.drivers.base_driver import LLMDriver
+from deer.schema.plan import Plan
+
+
+class Planner:
+
+    def __init__(
+        self,
+        identity: str,
+        driver: LLMDriver | None = None,
+        registry: ToolRegistry | None = None,
+        format_response: str = "plain",
+        improve_goal: bool = True,
+    ):
+        self.llm_driver = driver
+        self.registry = registry
+        self.identity = identity
+        self.format_response = format_response
+        self.improve_goal = improve_goal
+
+        self.goal = ""
+
+    def plan(
+        self,
+        agent_input: AgentInput,
+        feedback={},
+        include_state_modifying: bool = True,
+    ) -> Plan:
+        if self.improve_goal:
+            self.run_improve_goal(agent_input=agent_input)
+        plan_prompt = self.build_prompt(
+            agent_input,
+            feedback,
+            include_state_modifying=include_state_modifying,
+        )
+        plan = self.llm_driver.generate_json(plan_prompt, response_model=Plan)
+        return plan
+
+    def run_improve_goal(self, agent_input: AgentInput):
+        goal_prompt = GOAL_IMPROVEMENT_PROMPT.format(
+            identity=self.identity,
+            goal=agent_input.goal,
+            payload=json.dumps(agent_input.payload, ensure_ascii=False),
+        )
+        improved_goal = self.llm_driver.generate_text(goal_prompt)
+        agent_input.goal = improved_goal
+        self.goal = improved_goal
+
+    def build_prompt(
+        self,
+        agent_input: AgentInput,
+        feedback={},
+        include_state_modifying=True,
+    ) -> str:
+        # As usable data must be JSON consistent.
+        agent_input.payload.update(feedback)
+        payload = json.dumps(agent_input.payload, ensure_ascii=False)
+
+        planner_prompt = PLANNER_PROMPT.format(
+            identity=self.identity,
+            goal=agent_input.goal,
+            payload=payload,
+            tools=self.registry.describe(include_state_modifying),
+            format_response=self.format_response,
+        )
+        return planner_prompt

deer/prompts/__init__.py

@@ -0,0 +1,6 @@
+from .error_explain import ERROR_EXPLAIN_PROMPT
+from .goal_improvement import GOAL_IMPROVEMENT_PROMPT
+from .humanizer import HUMANIZER_PROMPT
+from .planner import PLANNER_PROMPT
+from .response_improvement import RESPONSE_IMPROVEMENT_PROMPT
+from .goal_validation import VERIFIER_JUDGE_PROMPT, GOAL_VERIFIER_PROMPT