agex 0.1.0__tar.gz

agex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ashenfad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agex-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: agex
+Version: 0.1.0
+Summary: Library-friendly agents that work directly with your existing Python codebase.
+Author: ashenfad
+License-Expression: MIT
+Project-URL: Homepage, https://ashenfad.github.io/agex/
+Project-URL: Documentation, https://ashenfad.github.io/agex/
+Project-URL: Repository, https://github.com/ashenfad/agex
+Project-URL: Issues, https://github.com/ashenfad/agex/issues
+Keywords: agents,ai,llm,python,runtime,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tiktoken
+Requires-Dist: xxhash
+Requires-Dist: diskcache
+Requires-Dist: pydantic
+Requires-Dist: pygments
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: anyio; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Requires-Dist: pandas; extra == "test"
+Requires-Dist: anthropic; extra == "test"
+Requires-Dist: google-generativeai; extra == "test"
+Requires-Dist: openai; extra == "test"
+Requires-Dist: matplotlib; extra == "test"
+Provides-Extra: examples
+Requires-Dist: plotly[express]; extra == "examples"
+Requires-Dist: kaleido; extra == "examples"
+Requires-Dist: numpy; extra == "examples"
+Requires-Dist: nbformat; extra == "examples"
+Requires-Dist: pandas; extra == "examples"
+Requires-Dist: osmnx>=2.0.0; extra == "examples"
+Requires-Dist: folium; extra == "examples"
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai; extra == "gemini"
+Provides-Extra: all-providers
+Requires-Dist: agex[openai]; extra == "all-providers"
+Requires-Dist: agex[anthropic]; extra == "all-providers"
+Requires-Dist: agex[gemini]; extra == "all-providers"
+Dynamic: license-file
+
+# agex: Library-Friendly Agents
+
+**`agex`** (a portmanteau of **age**nt **ex**ecution) is a Python-native agentic framework that enables AI agents to work directly with your existing libraries and codebase.
+
+![agex demo gif](docs/assets/teaser.gif)
+
+**This works because** `agex` agents can accept and return complex types like `pandas.DataFrame` and `plotly.Figure` objects without intermediate JSON serialization. For a deeper dive, check out the full **[agex101.ipynb tutorial](https://ashenfad.github.io/agex/examples/agex101/)** or see **[geospatial routing with OSMnx](https://ashenfad.github.io/agex/examples/routing/)** for advanced multi-library integration.
+
+## What Makes This Different
+
+`agex` uses a subset of Python as the agent action space, executing actions in a sandboxed environment within your process. This approach avoids the complexity of JSON serialization and allows complex objects to flow directly between your code and the agent. You control exactly what functions, classes, and modules are available, creating a powerful yet secure environment.
+
+-   **Code-as-Action**: Secure, sandboxed Python execution for agents.
+-   **Library Integration**: Use your existing code directly, no tool-making required.
+-   **Workspace Persistence**: Git-like versioning for agent state and memory.
+-   **Multi-Agent**: Orchestrate agents with natural Python control flow.
+-   **Event Streams**: Real-time, notebook-friendly observability.
+-   **Benchmarking**: A framework for data-driven agent evaluation.
+
+## Documentation
+
+Complete documentation is hosted at **[ashenfad.github.io/agex](https://ashenfad.github.io/agex/)**.
+
+Key sections:
+- **[📚 Quick Start Guide](https://ashenfad.github.io/agex/quick-start/)**
+- **[🔭 The Big Picture](https://ashenfad.github.io/agex/concepts/big-picture/)**
+- **[💡 Examples](https://ashenfad.github.io/agex/examples/overview/)**
+- **[📖 API Reference](https://ashenfad.github.io/agex/api/overview/)**
+
+## Installation
+
+Install agex with your preferred LLM provider:
+
+```bash
+# Install with a specific provider
+pip install "agex[openai]"        # For OpenAI models
+pip install "agex[anthropic]"     # For Anthropic Claude models
+pip install "agex[gemini]"        # For Google Gemini models
+
+# Or install with all providers
+pip install "agex[all-providers]"
+```
+
+## Project Status
+
+> **⚠️ Pre-Release**  
+> `agex` is a new framework in active development. While the core concepts are stabilizing, the API should be considered experimental and is subject to change.
+
+For teams looking for a more battle-tested library built on the same "agents-that-think-in-code" philosophy, we highly recommend Hugging Face's excellent [`smolagents`](https://github.com/huggingface/smolagents) project. `agex` explores a different architectural path, focusing on deep runtime interoperability and a secure, sandboxed environment for direct integration with existing Python libraries.
+
+## Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on our development workflow, code style, and how to submit pull requests. For bug reports and feature requests, please use [GitHub Issues](https://github.com/ashenfad/agex/issues).

agex-0.1.0/README.md

@@ -0,0 +1,53 @@
+# agex: Library-Friendly Agents
+
+**`agex`** (a portmanteau of **age**nt **ex**ecution) is a Python-native agentic framework that enables AI agents to work directly with your existing libraries and codebase.
+
+![agex demo gif](docs/assets/teaser.gif)
+
+**This works because** `agex` agents can accept and return complex types like `pandas.DataFrame` and `plotly.Figure` objects without intermediate JSON serialization. For a deeper dive, check out the full **[agex101.ipynb tutorial](https://ashenfad.github.io/agex/examples/agex101/)** or see **[geospatial routing with OSMnx](https://ashenfad.github.io/agex/examples/routing/)** for advanced multi-library integration.
+
+## What Makes This Different
+
+`agex` uses a subset of Python as the agent action space, executing actions in a sandboxed environment within your process. This approach avoids the complexity of JSON serialization and allows complex objects to flow directly between your code and the agent. You control exactly what functions, classes, and modules are available, creating a powerful yet secure environment.
+
+-   **Code-as-Action**: Secure, sandboxed Python execution for agents.
+-   **Library Integration**: Use your existing code directly, no tool-making required.
+-   **Workspace Persistence**: Git-like versioning for agent state and memory.
+-   **Multi-Agent**: Orchestrate agents with natural Python control flow.
+-   **Event Streams**: Real-time, notebook-friendly observability.
+-   **Benchmarking**: A framework for data-driven agent evaluation.
+
+## Documentation
+
+Complete documentation is hosted at **[ashenfad.github.io/agex](https://ashenfad.github.io/agex/)**.
+
+Key sections:
+- **[📚 Quick Start Guide](https://ashenfad.github.io/agex/quick-start/)**
+- **[🔭 The Big Picture](https://ashenfad.github.io/agex/concepts/big-picture/)**
+- **[💡 Examples](https://ashenfad.github.io/agex/examples/overview/)**
+- **[📖 API Reference](https://ashenfad.github.io/agex/api/overview/)**
+
+## Installation
+
+Install agex with your preferred LLM provider:
+
+```bash
+# Install with a specific provider
+pip install "agex[openai]"        # For OpenAI models
+pip install "agex[anthropic]"     # For Anthropic Claude models
+pip install "agex[gemini]"        # For Google Gemini models
+
+# Or install with all providers
+pip install "agex[all-providers]"
+```
+
+## Project Status
+
+> **⚠️ Pre-Release**  
+> `agex` is a new framework in active development. While the core concepts are stabilizing, the API should be considered experimental and is subject to change.
+
+For teams looking for a more battle-tested library built on the same "agents-that-think-in-code" philosophy, we highly recommend Hugging Face's excellent [`smolagents`](https://github.com/huggingface/smolagents) project. `agex` explores a different architectural path, focusing on deep runtime interoperability and a secure, sandboxed environment for direct integration with existing Python libraries.
+
+## Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on our development workflow, code style, and how to submit pull requests. For bug reports and feature requests, please use [GitHub Issues](https://github.com/ashenfad/agex/issues).

agex-0.1.0/agex/__init__.py

@@ -0,0 +1,60 @@
+from .agent import (
+    Agent,
+    MemberSpec,
+    TaskFail,
+    clear_agent_registry,
+)
+from .agent.console import pprint_events
+from .agent.datatypes import TaskClarify, TaskTimeout
+from .agent.events import (
+    ActionEvent,
+    ClarifyEvent,
+    ErrorEvent,
+    Event,
+    FailEvent,
+    OutputEvent,
+    SuccessEvent,
+    TaskStartEvent,
+)
+from .llm import LLMClient, connect_llm
+from .render.view import view
+from .state import Live, Namespaced, Versioned, events
+from .state.kv import Cache, Disk, Memory
+
+__all__ = [
+    # Core Classes
+    "Agent",
+    "LLMClient",
+    # State Management
+    "Versioned",
+    "Live",
+    "Namespaced",
+    "events",
+    # Task Control Exceptions & Functions
+    "TaskFail",
+    "TaskClarify",
+    "TaskTimeout",
+    # Registration
+    "MemberSpec",
+    # Events
+    "Event",
+    "TaskStartEvent",
+    "ActionEvent",
+    "OutputEvent",
+    "SuccessEvent",
+    "FailEvent",
+    "ClarifyEvent",
+    "ErrorEvent",
+    # Agent Registry
+    "clear_agent_registry",
+    # LLM Client Factory
+    "connect_llm",
+    # View
+    "view",
+    # KV backends
+    "Memory",
+    "Disk",
+    "Cache",
+    # Console
+    "pprint_events",
+]

agex-0.1.0/agex/agent/__init__.py

@@ -0,0 +1,86 @@
+# Main agent functionality
+from ..llm import LLMClient
+from .base import BaseAgent, clear_agent_registry, register_agent, resolve_agent
+
+# Data types and exceptions
+from .datatypes import (
+    RESERVED_NAMES,
+    AttrDescriptor,
+    MemberSpec,
+    Pattern,
+    RegisteredClass,
+    RegisteredFn,
+    RegisteredItem,
+    RegisteredModule,
+    TaskContinue,
+    TaskFail,
+    TaskSuccess,
+    Visibility,
+)
+from .loop import TaskLoopMixin
+
+# Fingerprinting (usually internal, but exported for testing)
+from .registration import RegistrationMixin
+from .task import TaskMixin, clear_dynamic_dataclass_registry
+
+__all__ = [
+    # Core functionality
+    "register_agent",
+    "resolve_agent",
+    "clear_agent_registry",
+    "clear_dynamic_dataclass_registry",
+    # Task control functions
+    "TaskSuccess",
+    "TaskFail",
+    "TaskContinue",
+    # Registration types
+    "MemberSpec",
+    "AttrDescriptor",
+    "RegisteredItem",
+    "RegisteredFn",
+    "RegisteredClass",
+    "RegisteredModule",
+    # Type aliases and constants
+    "Pattern",
+    "Visibility",
+    "RESERVED_NAMES",
+    # Fingerprinting
+]
+
+
+class Agent(RegistrationMixin, TaskMixin, TaskLoopMixin, BaseAgent):
+    def __init__(
+        self,
+        primer: str | None = None,
+        timeout_seconds: float = 5.0,
+        max_iterations: int = 10,
+        max_tokens: int = 2**16,
+        # Agent identification
+        name: str | None = None,
+        # LLM configuration (optional, uses smart defaults)
+        llm_client: LLMClient | None = None,
+        # LLM retry controls
+        llm_max_retries: int = 2,
+        llm_retry_backoff: float = 0.25,
+    ):
+        """
+        An agent that can be used to execute tasks.
+
+        Args:
+            primer: A string to guide the agent's behavior.
+            timeout_seconds: The maximum time in seconds for a single action evaluation.
+            max_iterations: The maximum number of think-act cycles for a task.
+            max_tokens: The maximum number of tokens to use for context rendering.
+            name: Unique identifier for this agent (for sub-agent namespacing).
+            llm_client: An instantiated LLMClient for the agent to use.
+        """
+        super().__init__(
+            primer,
+            timeout_seconds,
+            max_iterations,
+            max_tokens,
+            name=name,
+            llm_client=llm_client,
+            llm_max_retries=llm_max_retries,
+            llm_retry_backoff=llm_retry_backoff,
+        )

agex-0.1.0/agex/agent/base.py

@@ -0,0 +1,126 @@
+import uuid
+from typing import Any, Callable, Dict, Literal
+
+from ..llm import LLMClient, connect_llm
+from .datatypes import (
+    MemberSpec,
+    RegisteredClass,
+)
+from .fingerprint import compute_agent_fingerprint_from_policy
+from .policy.policy import AgentPolicy
+
+# Global registry mapping fingerprints to agents
+_AGENT_REGISTRY: Dict[str, "BaseAgent"] = {}
+# Global registry mapping agent names to agents
+_AGENT_REGISTRY_BY_NAME: Dict[str, "BaseAgent"] = {}
+
+
+def register_agent(agent: "BaseAgent") -> str:
+    """
+    Register an agent in the global registry.
+
+    Returns the agent's fingerprint.
+    """
+    # Enforce unique agent names if provided
+    if hasattr(agent, "name") and agent.name is not None:
+        if agent.name in _AGENT_REGISTRY_BY_NAME:
+            existing_agent = _AGENT_REGISTRY_BY_NAME[agent.name]
+            if existing_agent is not agent:  # Allow re-registration of same agent
+                raise ValueError(f"Agent name '{agent.name}' already exists")
+        _AGENT_REGISTRY_BY_NAME[agent.name] = agent
+
+    fingerprint = compute_agent_fingerprint_from_policy(agent)
+    _AGENT_REGISTRY[fingerprint] = agent
+    return fingerprint
+
+
+def resolve_agent(fingerprint: str) -> "BaseAgent":
+    """
+    Resolve an agent by its fingerprint.
+
+    Raises RuntimeError if no matching agent is found.
+    """
+    agent = _AGENT_REGISTRY.get(fingerprint)
+    if not agent:
+        available = list(_AGENT_REGISTRY.keys())
+        raise RuntimeError(
+            f"No agent found with fingerprint '{fingerprint[:8]}...'. "
+            f"Available fingerprints: {[fp[:8] + '...' for fp in available]}"
+        )
+    return agent
+
+
+def clear_agent_registry() -> None:
+    """Clear the global registry. Primarily for testing."""
+    from .task import clear_dynamic_dataclass_registry
+
+    global _AGENT_REGISTRY, _AGENT_REGISTRY_BY_NAME
+    _AGENT_REGISTRY = {}
+    _AGENT_REGISTRY_BY_NAME = {}
+    clear_dynamic_dataclass_registry()
+
+
+def _random_name() -> str:
+    return f"agent_{uuid.uuid4().hex[:8]}"
+
+
+class BaseAgent:
+    def __init__(
+        self,
+        primer: str | None,
+        timeout_seconds: float,
+        max_iterations: int,
+        max_tokens: int,
+        # Agent identification
+        name: str | None = None,
+        # LLM configuration (optional, uses smart defaults)
+        llm_client: LLMClient | None = None,
+        # LLM retry controls
+        llm_max_retries: int = 2,
+        llm_retry_backoff: float = 0.25,
+    ):
+        self.name = name or _random_name()
+        self.primer = primer
+        self.timeout_seconds = timeout_seconds
+        self.max_iterations = max_iterations
+        self.max_tokens = max_tokens
+
+        # Create LLM client using the resolved configuration
+        self.llm_client = llm_client or connect_llm()
+        # LLM retry settings
+        self.llm_max_retries = llm_max_retries
+        self.llm_retry_backoff = llm_retry_backoff
+
+        # private, host-side registry for live, unpickleable objects
+        self._host_object_registry: dict[str, Any] = {}
+
+        self._policy: AgentPolicy = AgentPolicy()
+
+        # Auto-register this agent
+        self.fingerprint = register_agent(self)
+
+    def _update_fingerprint(self):
+        """Update the fingerprint after registration changes."""
+        self.fingerprint = register_agent(self)
+
+    def module(
+        self,
+        obj: Any,
+        *,
+        name: str | None = None,
+        visibility: Literal["high", "medium", "low"] = "medium",
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        configure: dict[str, MemberSpec | RegisteredClass] | None = None,
+    ) -> None:
+        """
+        Stub implementation of module registration.
+        The full implementation with include/exclude support is in RegistrationMixin.
+        This method should not be called directly - use Agent class instead.
+        """
+        raise NotImplementedError(
+            "This is a stub implementation. Use the Agent class which inherits from "
+            "RegistrationMixin for full include/exclude support."
+        )
+
+    def task(self, prompt: str | Callable) -> Callable[..., Any]: ...