agent-weave-lib 0.1.0__py3-none-any.whl

agent_weave/__init__.py

@@ -0,0 +1,63 @@
+"""agent-weave: Lightweight AI agent framework."""
+
+from .agent import Agent
+from .config import AgentSettings
+from .errors import (
+    AgentWeaveError,
+    ConfigurationError,
+    GuardrailViolation,
+    LLMBackendError,
+    MaxIterationsError,
+    TokenBudgetExceededError,
+    ToolExecutionError,
+    ToolNotFoundError,
+)
+from .guardrails import (
+    BlockedWordsGuardrail,
+    Guardrail,
+    GuardrailPipeline,
+    MaxLengthGuardrail,
+    PIIGuardrail,
+    RegexGuardrail,
+    TokenBudgetGuardrail,
+)
+from .models import AgentResult, AgentStep, Message, ToolCall, ToolResult
+from .team import Strategy, Team, TeamResult
+from .tool import Tool, tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Agent",
+    "Tool",
+    "tool",
+    "Team",
+    "Strategy",
+    # Settings
+    "AgentSettings",
+    # Models
+    "AgentResult",
+    "AgentStep",
+    "Message",
+    "TeamResult",
+    "ToolCall",
+    "ToolResult",
+    # Guardrails
+    "Guardrail",
+    "GuardrailPipeline",
+    "BlockedWordsGuardrail",
+    "MaxLengthGuardrail",
+    "PIIGuardrail",
+    "RegexGuardrail",
+    "TokenBudgetGuardrail",
+    # Errors
+    "AgentWeaveError",
+    "ConfigurationError",
+    "GuardrailViolation",
+    "LLMBackendError",
+    "MaxIterationsError",
+    "TokenBudgetExceededError",
+    "ToolExecutionError",
+    "ToolNotFoundError",
+]

agent_weave/agent.py

@@ -0,0 +1,177 @@
+"""Core Agent class for agent-weave."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from .config import AgentSettings
+from .errors import ConfigurationError
+from .guardrails import (
+    Guardrail,
+    GuardrailPipeline,
+    TokenBudgetGuardrail,
+)
+from .llm.base import LLMBackend
+from .memory import ConversationMemory, Memory
+from .models import AgentResult, Message
+from .react import ReActEngine
+from .tool import Tool
+
+
+class Agent:
+    """A self-contained AI agent with tools, memory, and guardrails.
+
+    Usage::
+
+        from agent_weave import Agent, tool
+        from agent_weave.llm.openai_backend import OpenAIBackend
+
+        @tool(description="Search the web")
+        def web_search(query: str) -> str:
+            return f"Results for: {query}"
+
+        agent = Agent(
+            name="researcher",
+            llm=OpenAIBackend(api_key="sk-..."),
+            tools=[web_search],
+            system_prompt="You are a research assistant.",
+        )
+
+        result = agent.run("Find the latest AI trends in 2025")
+        print(result.output)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        llm: LLMBackend,
+        tools: Sequence[Tool] | None = None,
+        system_prompt: str = "You are a helpful AI assistant.",
+        memory: Memory | None = None,
+        model: str | None = None,
+        temperature: float | None = None,
+        max_iterations: int | None = None,
+        token_budget: int | None = None,
+        output_guardrails: list[Guardrail] | None = None,
+        settings: AgentSettings | None = None,
+        verbose: bool | None = None,
+    ) -> None:
+        if not name.strip():
+            raise ConfigurationError("Agent name cannot be empty.")
+
+        self.name = name.strip()
+        self._llm = llm
+        self._tools = list(tools or [])
+        self._system_prompt = system_prompt
+        self._memory = memory or ConversationMemory()
+        self._settings = settings or AgentSettings()
+
+        self._model = model or self._settings.default_model
+        self._temperature = temperature
+        self._max_iterations = max_iterations or self._settings.max_iterations
+        self._verbose = verbose if verbose is not None else self._settings.verbose
+
+        # Guardrails.
+        self._token_budget: TokenBudgetGuardrail | None = None
+        if token_budget or self._settings.token_budget:
+            self._token_budget = TokenBudgetGuardrail(
+                budget=token_budget or self._settings.token_budget or 0
+            )
+
+        self._output_guardrails: GuardrailPipeline | None = None
+        if output_guardrails:
+            self._output_guardrails = GuardrailPipeline(output_guardrails)
+
+    @property
+    def tools(self) -> list[Tool]:
+        return list(self._tools)
+
+    @property
+    def tool_names(self) -> list[str]:
+        return [t.name for t in self._tools]
+
+    def add_tool(self, tool_instance: Tool) -> None:
+        """Register an additional tool."""
+        self._tools.append(tool_instance)
+
+    def run(self, task: str) -> AgentResult:
+        """Run the agent on a task (synchronous).
+
+        Sets up memory with system prompt + user task, then
+        runs the ReAct loop until completion.
+        """
+        self._prepare_memory(task)
+
+        engine = self._build_engine()
+        return engine.run(self.name)
+
+    async def arun(self, task: str) -> AgentResult:
+        """Run the agent on a task (asynchronous)."""
+        self._prepare_memory(task)
+
+        engine = self._build_engine()
+        return await engine.arun(self.name)
+
+    def chat(self, message: str) -> AgentResult:
+        """Continue a conversation (preserves history).
+
+        Unlike ``run()``, this does NOT reset memory. It appends
+        the new user message and continues the conversation.
+        """
+        # Ensure system prompt exists on first call.
+        if self._memory.size == 0:
+            self._memory.add(
+                Message(role="system", content=self._system_prompt)
+            )
+
+        self._memory.add(Message(role="user", content=message))
+
+        engine = self._build_engine()
+        return engine.run(self.name)
+
+    async def achat(self, message: str) -> AgentResult:
+        """Continue a conversation (async, preserves history)."""
+        if self._memory.size == 0:
+            self._memory.add(
+                Message(role="system", content=self._system_prompt)
+            )
+
+        self._memory.add(Message(role="user", content=message))
+
+        engine = self._build_engine()
+        return await engine.arun(self.name)
+
+    def reset(self) -> None:
+        """Clear memory and token budget."""
+        self._memory.clear()
+        if self._token_budget:
+            self._token_budget.reset()
+
+    def _prepare_memory(self, task: str) -> None:
+        """Reset memory and load system prompt + user task."""
+        self._memory.clear()
+        if self._token_budget:
+            self._token_budget.reset()
+
+        self._memory.add(Message(role="system", content=self._system_prompt))
+        self._memory.add(Message(role="user", content=task))
+
+    def _build_engine(self) -> ReActEngine:
+        return ReActEngine(
+            llm=self._llm,
+            tools=self._tools,
+            memory=self._memory,
+            max_iterations=self._max_iterations,
+            model=self._model,
+            temperature=self._temperature,
+            token_budget=self._token_budget,
+            output_guardrails=self._output_guardrails,
+            verbose=self._verbose,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Agent(name={self.name!r}, model={self._model!r}, "
+            f"tools={self.tool_names})"
+        )

agent_weave/cli.py

@@ -0,0 +1,109 @@
+"""CLI interface for agent-weave."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def _get_agent():
+    """Build a default agent from environment variables."""
+    from .agent import Agent
+    from .llm.openai_backend import OpenAIBackend
+
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        print("Error: OPENAI_API_KEY environment variable is required.", file=sys.stderr)
+        sys.exit(1)
+
+    model = os.getenv("AGENTWEAVE_DEFAULT_MODEL", "gpt-4o-mini")
+
+    backend = OpenAIBackend(api_key=api_key, default_model=model)
+    return Agent(
+        name="cli-agent",
+        llm=backend,
+        system_prompt="You are a helpful AI assistant. Be concise.",
+        model=model,
+    )
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Run a task with the agent."""
+    agent = _get_agent()
+    result = agent.run(args.task)
+    print(result.output)
+
+    if args.verbose:
+        print(f"\n--- Stats ---")
+        print(f"Iterations: {result.total_iterations}")
+        print(f"Tokens: {result.total_tokens:,}")
+        print(f"Tool calls: {result.total_tool_calls}")
+
+
+def cmd_chat(args: argparse.Namespace) -> None:
+    """Interactive chat with the agent."""
+    agent = _get_agent()
+    print("Agent Weave Chat (type 'quit' to exit)")
+    print("-" * 40)
+
+    while True:
+        try:
+            user_input = input("\nYou: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nGoodbye!")
+            break
+
+        if user_input.lower() in ("quit", "exit", "q"):
+            print("Goodbye!")
+            break
+
+        if not user_input:
+            continue
+
+        result = agent.chat(user_input)
+        print(f"\nAgent: {result.output}")
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    """Show library info."""
+    from . import __version__
+    info = {
+        "name": "agent-weave",
+        "version": __version__,
+        "python": sys.version,
+    }
+    print(json.dumps(info, indent=2))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agent-weave",
+        description="Lightweight AI agent framework.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Run command.
+    run_parser = subparsers.add_parser("run", help="Run a task")
+    run_parser.add_argument("task", help="The task to execute")
+    run_parser.add_argument("-v", "--verbose", action="store_true")
+    run_parser.set_defaults(func=cmd_run)
+
+    # Chat command.
+    chat_parser = subparsers.add_parser("chat", help="Interactive chat")
+    chat_parser.set_defaults(func=cmd_chat)
+
+    # Info command.
+    info_parser = subparsers.add_parser("info", help="Show library info")
+    info_parser.set_defaults(func=cmd_info)
+
+    args = parser.parse_args()
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

agent_weave/config.py

@@ -0,0 +1,51 @@
+"""Configuration for agent-weave."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _as_bool(value: str | None, *, default: bool) -> bool:
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _as_float(value: str | None, *, default: float | None) -> float | None:
+    if value is None or value.strip() == "":
+        return default
+    return float(value)
+
+
+def _as_int(value: str | None, *, default: int) -> int:
+    if value is None or value.strip() == "":
+        return default
+    return int(value)
+
+
+@dataclass
+class AgentSettings:
+    """Global settings for agent-weave."""
+
+    default_model: str = "gpt-4o-mini"
+    max_iterations: int = 10
+    request_timeout: float | None = 60.0
+    token_budget: int | None = None
+    verbose: bool = False
+
+    @classmethod
+    def from_env(cls) -> "AgentSettings":
+        return cls(
+            default_model=os.getenv("AGENTWEAVE_DEFAULT_MODEL", "gpt-4o-mini"),
+            max_iterations=_as_int(
+                os.getenv("AGENTWEAVE_MAX_ITERATIONS"), default=10
+            ),
+            request_timeout=_as_float(
+                os.getenv("AGENTWEAVE_REQUEST_TIMEOUT"), default=60.0
+            ),
+            token_budget=_as_int(
+                os.getenv("AGENTWEAVE_TOKEN_BUDGET"), default=0
+            ) or None,
+            verbose=_as_bool(os.getenv("AGENTWEAVE_VERBOSE"), default=False),
+        )

agent_weave/errors.py

@@ -0,0 +1,64 @@
+"""Custom exceptions for agent-weave."""
+
+from __future__ import annotations
+
+
+class AgentWeaveError(Exception):
+    """Base exception for agent-weave."""
+
+
+class ToolExecutionError(AgentWeaveError):
+    """Raised when a tool fails during execution."""
+
+    def __init__(self, tool_name: str, message: str) -> None:
+        self.tool_name = tool_name
+        super().__init__(f"Tool '{tool_name}' failed: {message}")
+
+
+class ToolNotFoundError(AgentWeaveError):
+    """Raised when a requested tool is not registered."""
+
+    def __init__(self, tool_name: str, available: list[str] | None = None) -> None:
+        self.tool_name = tool_name
+        avail = ", ".join(available) if available else "none"
+        super().__init__(
+            f"Tool '{tool_name}' not found. Available tools: {avail}"
+        )
+
+
+class MaxIterationsError(AgentWeaveError):
+    """Raised when the ReAct loop exceeds the maximum iterations."""
+
+    def __init__(self, max_iterations: int) -> None:
+        self.max_iterations = max_iterations
+        super().__init__(
+            f"Agent exceeded maximum iterations ({max_iterations}). "
+            "Increase max_iterations or simplify the task."
+        )
+
+
+class TokenBudgetExceededError(AgentWeaveError):
+    """Raised when the token budget is exhausted."""
+
+    def __init__(self, budget: int, used: int) -> None:
+        self.budget = budget
+        self.used = used
+        super().__init__(
+            f"Token budget exceeded: used {used:,} of {budget:,} allowed tokens."
+        )
+
+
+class LLMBackendError(AgentWeaveError):
+    """Raised when the LLM backend fails."""
+
+
+class GuardrailViolation(AgentWeaveError):
+    """Raised when a guardrail check fails."""
+
+    def __init__(self, guardrail_name: str, message: str) -> None:
+        self.guardrail_name = guardrail_name
+        super().__init__(f"Guardrail '{guardrail_name}': {message}")
+
+
+class ConfigurationError(AgentWeaveError):
+    """Raised for invalid configuration."""

agent_weave/guardrails.py

@@ -0,0 +1,144 @@
+"""Guardrails for agent-weave — input/output validators and budget controls."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import GuardrailViolation, TokenBudgetExceededError
+
+
+class Guardrail(ABC):
+    """Base class for all guardrails."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def check(self, value: str, *, context: dict[str, Any] | None = None) -> str:
+        """Validate and optionally transform the value.
+
+        Returns the (possibly modified) value.
+        Raises ``GuardrailViolation`` if the check fails.
+        """
+
+
+class MaxLengthGuardrail(Guardrail):
+    """Reject output that exceeds a character limit."""
+
+    name = "max_length"
+
+    def __init__(self, max_chars: int = 10_000) -> None:
+        self._max = max_chars
+
+    def check(self, value: str, *, context: dict[str, Any] | None = None) -> str:
+        if len(value) > self._max:
+            raise GuardrailViolation(
+                self.name,
+                f"Output length {len(value):,} exceeds limit of {self._max:,} chars.",
+            )
+        return value
+
+
+class BlockedWordsGuardrail(Guardrail):
+    """Reject output that contains any blocked words."""
+
+    name = "blocked_words"
+
+    def __init__(self, words: list[str]) -> None:
+        self._words = [w.lower() for w in words]
+
+    def check(self, value: str, *, context: dict[str, Any] | None = None) -> str:
+        lower_val = value.lower()
+        for word in self._words:
+            if word in lower_val:
+                raise GuardrailViolation(
+                    self.name, f"Blocked word detected: '{word}'"
+                )
+        return value
+
+
+class RegexGuardrail(Guardrail):
+    """Reject output that matches a forbidden regex pattern."""
+
+    name = "regex_filter"
+
+    def __init__(self, pattern: str, *, message: str = "Forbidden pattern detected.") -> None:
+        self._pattern = re.compile(pattern, re.IGNORECASE)
+        self._message = message
+
+    def check(self, value: str, *, context: dict[str, Any] | None = None) -> str:
+        if self._pattern.search(value):
+            raise GuardrailViolation(self.name, self._message)
+        return value
+
+
+class PIIGuardrail(Guardrail):
+    """Detect common PII patterns (emails, phone numbers, SSNs)."""
+
+    name = "pii_filter"
+
+    _PATTERNS = {
+        "email": re.compile(r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+"),
+        "phone": re.compile(r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b"),
+        "ssn": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+    }
+
+    def __init__(self, *, redact: bool = False) -> None:
+        self._redact = redact
+
+    def check(self, value: str, *, context: dict[str, Any] | None = None) -> str:
+        for pii_type, pattern in self._PATTERNS.items():
+            if pattern.search(value):
+                if self._redact:
+                    value = pattern.sub(f"[REDACTED_{pii_type.upper()}]", value)
+                else:
+                    raise GuardrailViolation(
+                        self.name,
+                        f"PII detected: {pii_type}. Set redact=True to auto-redact.",
+                    )
+        return value
+
+
+@dataclass
+class TokenBudgetGuardrail:
+    """Track and enforce a token budget across the agent run."""
+
+    budget: int
+    _used: int = field(default=0, init=False)
+
+    @property
+    def used(self) -> int:
+        return self._used
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self.budget - self._used)
+
+    def consume(self, tokens: int) -> None:
+        """Record token usage. Raises if budget exceeded."""
+        self._used += tokens
+        if self._used > self.budget:
+            raise TokenBudgetExceededError(self.budget, self._used)
+
+    def reset(self) -> None:
+        self._used = 0
+
+
+class GuardrailPipeline:
+    """Run a sequence of guardrails on a value."""
+
+    def __init__(self, guardrails: list[Guardrail] | None = None) -> None:
+        self._guardrails = list(guardrails or [])
+
+    def add(self, guardrail: Guardrail) -> "GuardrailPipeline":
+        self._guardrails.append(guardrail)
+        return self
+
+    def run(self, value: str, *, context: dict[str, Any] | None = None) -> str:
+        """Run all guardrails in sequence. Returns the (possibly modified) value."""
+        result = value
+        for rail in self._guardrails:
+            result = rail.check(result, context=context)
+        return result

agent_weave/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM backend modules for agent-weave."""
+
+from .base import LLMBackend
+
+__all__ = ["LLMBackend"]