agenthandler 0.92.0__py3-none-any.whl

agenthandler/budget.py

@@ -0,0 +1,94 @@
+"""Token and iteration budget tracking — thread-safe."""
+
+import threading
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .errors import AgentHandlerError
+
+
+@dataclass
+class BudgetSnapshot:
+    """Point-in-time snapshot of budget usage."""
+
+    tokens_used: int
+    token_limit: Optional[int]
+    iterations: int
+    iteration_limit: int
+
+    @property
+    def tokens_remaining(self) -> Optional[int]:
+        if self.token_limit is None:
+            return None
+        return max(0, self.token_limit - self.tokens_used)
+
+    @property
+    def iterations_remaining(self) -> int:
+        return max(0, self.iteration_limit - self.iterations)
+
+    @property
+    def is_over_token_budget(self) -> bool:
+        if self.token_limit is None:
+            return False
+        return self.tokens_used >= self.token_limit
+
+    @property
+    def is_over_iteration_limit(self) -> bool:
+        return self.iterations >= self.iteration_limit
+
+
+class BudgetTracker:
+    """Thread-safe token and iteration budget tracker.
+
+    Usage:
+        tracker = BudgetTracker(token_limit=10000, iteration_limit=5)
+        tracker.record_tokens(500)    # raises AgentHandlerError if over
+        tracker.record_iteration()    # raises AgentHandlerError if over
+        snap = tracker.snapshot()     # read current state
+    """
+
+    def __init__(self, token_limit: Optional[int] = None, iteration_limit: int = 5):
+        self._token_limit = token_limit
+        self._iteration_limit = iteration_limit
+        self._tokens_used = 0
+        self._iterations = 0
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_policy(cls, policy: Any) -> "BudgetTracker":
+        return cls(
+            token_limit=policy.token_budget,
+            iteration_limit=policy.max_iterations,
+        )
+
+    def record_tokens(self, tokens: int) -> int:
+        """Record token usage. Returns new total. Raises if over budget."""
+        with self._lock:
+            self._tokens_used += tokens
+            if self._token_limit is not None and self._tokens_used > self._token_limit:
+                raise AgentHandlerError.budget_exceeded(self._tokens_used, self._token_limit)
+            return self._tokens_used
+
+    def record_iteration(self) -> int:
+        """Record an iteration. Returns new count. Raises if over limit."""
+        with self._lock:
+            self._iterations += 1
+            if self._iterations > self._iteration_limit:
+                raise AgentHandlerError.max_iterations(self._iterations, self._iteration_limit)
+            return self._iterations
+
+    def snapshot(self) -> BudgetSnapshot:
+        """Get a point-in-time snapshot."""
+        with self._lock:
+            return BudgetSnapshot(
+                tokens_used=self._tokens_used,
+                token_limit=self._token_limit,
+                iterations=self._iterations,
+                iteration_limit=self._iteration_limit,
+            )
+
+    def reset(self) -> None:
+        """Reset all counters."""
+        with self._lock:
+            self._tokens_used = 0
+            self._iterations = 0

agenthandler/builder.py

@@ -0,0 +1,178 @@
+"""SkillBuilder — generate skills from natural language descriptions.
+
+Bring your own LLM. Pass any async callable that takes a prompt string
+and returns a string. Works with OpenAI, Anthropic, local models, whatever.
+
+Usage:
+    from agenthandler import SkillBuilder, SkillStore
+
+    async def my_llm(prompt: str) -> str:
+        return await openai.chat(messages=[{"role": "user", "content": prompt}])
+
+    builder = SkillBuilder(my_llm)
+    skill = await builder.create("A skill that researches topics on the web")
+
+    store = SkillStore("~/.agenthandler/skills")
+    store.save(skill)
+"""
+
+import json
+import re
+from typing import Any, Callable, Coroutine, Dict, Optional
+
+from .skill import Skill
+
+# The prompt that teaches the LLM how to produce a valid skill definition.
+# Kept as a module constant so users can inspect/override it.
+SKILL_GENERATION_PROMPT = """\
+You are a skill builder for AI agents. Given a natural language description of what \
+a skill should do, produce a complete skill definition as JSON.
+
+The JSON must have this structure (all fields shown — omit any that aren't relevant):
+
+```json
+{
+  "name": "snake_case_name",
+  "description": "One sentence describing what this skill does",
+  "triggers": ["keyword1", "keyword2"],
+  "version": "1.0",
+  "role": "You are a ... (persona for the agent)",
+  "task": "When the user asks ... (what the agent should do step by step)",
+  "instructions": [
+    "First instruction",
+    "Second instruction"
+  ],
+  "examples": [
+    {"user": "Example user message", "assistant": "Example response"}
+  ],
+  "output_format": "Optional template for response structure",
+  "tools": [
+    {
+      "name": "tool_name",
+      "description": "What the tool does",
+      "parameters": [
+        {"name": "param_name", "type": "string", "description": "...", "required": true}
+      ]
+    }
+  ],
+  "supervision": {
+    "max_iterations": 5,
+    "tool_timeout": 30,
+    "token_budget": 10000,
+    "on_timeout": "return_error",
+    "on_budget_exceeded": "respond_with_best_effort",
+    "require_confirm": ["dangerous_tool_name"]
+  }
+}
+```
+
+Rules:
+- name must be snake_case, short, descriptive
+- triggers are keywords/phrases that should activate this skill
+- tools: only include tools the skill actually needs. If no tools needed, omit the field
+- supervision: always include sensible limits. Think about what could go wrong:
+  - How many iterations could this reasonably need?
+  - How long should each tool call take?
+  - What's a reasonable token budget?
+  - Which tools are dangerous enough to need confirmation?
+- instructions: be specific and actionable. Include safety rules
+- on_timeout options: "return_error", "respond_with_best_effort", "kill"
+- on_budget_exceeded options: same as above
+- require_confirm: list tool names that should need human approval before running
+
+Respond with ONLY the JSON object. No markdown fences, no explanation."""
+
+SKILL_REFINEMENT_PROMPT = """\
+You are refining an existing skill definition based on user feedback.
+
+Current skill definition:
+```json
+{current_skill}
+```
+
+The user wants the following changes:
+{feedback}
+
+Apply the requested changes and return the complete updated skill definition as JSON.
+Follow the same schema as the original. Respond with ONLY the JSON object."""
+
+
+def _extract_json(text: str) -> Dict[str, Any]:
+    """Extract a JSON object from LLM output, handling markdown fences."""
+    # Strip markdown code fences if present
+    text = text.strip()
+    text = re.sub(r"^```(?:json)?\s*\n?", "", text)
+    text = re.sub(r"\n?```\s*$", "", text)
+    result: Dict[str, Any] = json.loads(text.strip())
+    return result
+
+
+class SkillBuilder:
+    """Build skills from natural language using any LLM.
+
+    Args:
+        llm: An async callable that takes a prompt string and returns a string.
+             This is your LLM — OpenAI, Anthropic, local model, whatever.
+        system_prompt: Override the default generation prompt if you want.
+    """
+
+    def __init__(
+        self,
+        llm: Callable[[str], Coroutine[Any, Any, str]],
+        system_prompt: Optional[str] = None,
+    ):
+        self._llm = llm
+        self._system_prompt = system_prompt or SKILL_GENERATION_PROMPT
+
+    async def create(self, description: str) -> Skill:
+        """Generate a skill from a natural language description.
+
+        Args:
+            description: What you want the skill to do, in plain English.
+
+        Returns:
+            A Skill object ready to save, inspect, or export.
+
+        Raises:
+            ValueError: If the LLM output can't be parsed as a valid skill.
+        """
+        prompt = f"{self._system_prompt}\n\nUser's description:\n{description}"
+        raw = await self._llm(prompt)
+
+        try:
+            data = _extract_json(raw)
+        except (json.JSONDecodeError, ValueError) as e:
+            raise ValueError(f"LLM returned invalid JSON. Raw output:\n{raw[:500]}") from e
+
+        if "name" not in data:
+            raise ValueError("LLM output missing required 'name' field")
+
+        return Skill.from_dict(data)
+
+    async def refine(self, skill: Skill, feedback: str) -> Skill:
+        """Refine an existing skill based on natural language feedback.
+
+        Args:
+            skill: The current skill to modify.
+            feedback: What to change, in plain English.
+
+        Returns:
+            An updated Skill object.
+        """
+        prompt = SKILL_REFINEMENT_PROMPT.format(
+            current_skill=skill.to_json(),
+            feedback=feedback,
+        )
+        raw = await self._llm(prompt)
+
+        try:
+            data = _extract_json(raw)
+        except (json.JSONDecodeError, ValueError) as e:
+            raise ValueError(
+                f"LLM returned invalid JSON during refinement. Raw output:\n{raw[:500]}"
+            ) from e
+
+        if "name" not in data:
+            raise ValueError("LLM output missing required 'name' field")
+
+        return Skill.from_dict(data)

agenthandler/circuit_breaker.py

@@ -0,0 +1,88 @@
+"""Circuit breaker — stops calling tools that keep failing."""
+
+import threading
+import time
+from enum import Enum
+from typing import Optional
+
+from .errors import AgentHandlerError
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Blocking calls (too many failures)
+    HALF_OPEN = "half_open"  # Allowing one test call
+
+
+class CircuitBreaker:
+    """Per-tool circuit breaker. Thread-safe.
+
+    States:
+        CLOSED  → failures < threshold, calls pass through
+        OPEN    → failures >= threshold, calls blocked until reset_after
+        HALF_OPEN → reset_after elapsed, allow one test call
+
+    Usage:
+        cb = CircuitBreaker(threshold=3, reset_after=60.0)
+        cb.check("web_search")      # raises if circuit open
+        try:
+            result = call_tool()
+            cb.record_success()
+        except:
+            cb.record_failure()
+    """
+
+    def __init__(self, threshold: int = 5, reset_after: float = 60.0):
+        self._threshold = threshold
+        self._reset_after = reset_after
+        self._consecutive_failures = 0
+        self._state = CircuitState.CLOSED
+        self._opened_at: Optional[float] = None
+        self._lock = threading.Lock()
+
+    def check(self, tool_name: str) -> None:
+        """Check if the circuit allows a call. Raises AgentHandlerError if open."""
+        with self._lock:
+            if self._state == CircuitState.CLOSED:
+                return
+            if self._state == CircuitState.OPEN:
+                # Check if enough time has passed to try again
+                if self._opened_at and (time.monotonic() - self._opened_at) >= self._reset_after:
+                    self._state = CircuitState.HALF_OPEN
+                    return
+                raise AgentHandlerError.circuit_open(tool_name, self._consecutive_failures)
+            # HALF_OPEN: allow one test call
+            return
+
+    def record_success(self) -> None:
+        """Record a successful call. Resets the breaker."""
+        with self._lock:
+            self._consecutive_failures = 0
+            self._state = CircuitState.CLOSED
+            self._opened_at = None
+
+    def record_failure(self) -> None:
+        """Record a failed call. May trip the breaker."""
+        with self._lock:
+            self._consecutive_failures += 1
+            if self._state == CircuitState.HALF_OPEN:
+                # Test call failed, reopen
+                self._state = CircuitState.OPEN
+                self._opened_at = time.monotonic()
+            elif self._consecutive_failures >= self._threshold:
+                self._state = CircuitState.OPEN
+                self._opened_at = time.monotonic()
+
+    @property
+    def state(self) -> CircuitState:
+        with self._lock:
+            # Check for auto-transition to half-open
+            if self._state == CircuitState.OPEN and self._opened_at:
+                if (time.monotonic() - self._opened_at) >= self._reset_after:
+                    self._state = CircuitState.HALF_OPEN
+            return self._state
+
+    @property
+    def consecutive_failures(self) -> int:
+        with self._lock:
+            return self._consecutive_failures