agentx-dev 3.0__tar.gz → 3.0.1__tar.gz

agentx_dev-3.0.1/MANIFEST.in

@@ -0,0 +1,11 @@
+graft agentx_dev
+graft examples
+include AGENTX.md
+include README.md
+include LICENSE
+prune tests
+prune examples/_sandbox
+prune examples/_sandbox_mcp
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo

{agentx_dev-3.0/agentx_dev.egg-info → agentx_dev-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.0
+Version: 3.0.1
 Summary: A lightweight LLM agent framework with multi-agent orchestration (Supervisor + dynamic specialist spawning), permission-gated default tools, MCP integration, and prompt-template presets.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License

{agentx_dev-3.0 → agentx_dev-3.0.1}/agentx_dev/__init__.py

@@ -40,6 +40,11 @@ from .Loader import (
 from .DefaultTools import DefaultTools, Permissions, DEFAULT_PERMISSIONS_PATH, mint_session_dir
 from .Session import Session
 from .WebTools import web_fetch_tool, web_search_tool
+from .Supervisor import (
+    Supervisor, AsyncSupervisor,
+    SpawnConfig, SpawnRequest,
+    SupervisorResult, SubtaskResult,
+)
 
 # MCP is an optional dependency — only re-export the names if the module imports cleanly.
 try:
@@ -145,6 +150,18 @@ __all__ = [
 
     # Session persistence
     "Session",
+
+    # Web tools (optional plug-ins, not in DefaultTools)
+    "web_search_tool",
+    "web_fetch_tool",
+
+    # Multi-agent orchestration
+    "Supervisor",
+    "AsyncSupervisor",
+    "SpawnConfig",
+    "SpawnRequest",
+    "SupervisorResult",
+    "SubtaskResult",
 ]
 
 if _MCP_AVAILABLE:

{agentx_dev-3.0 → agentx_dev-3.0.1/agentx_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.0
+Version: 3.0.1
 Summary: A lightweight LLM agent framework with multi-agent orchestration (Supervisor + dynamic specialist spawning), permission-gated default tools, MCP integration, and prompt-template presets.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License

{agentx_dev-3.0 → agentx_dev-3.0.1}/agentx_dev.egg-info/SOURCES.txt

@@ -32,4 +32,22 @@ agentx_dev/Runner/AsyncAgentRun.py
 agentx_dev/Runner/__init__.py
 agentx_dev/Runner/promptTemplate.yaml
 agentx_dev/resources/__init__.py
-agentx_dev/resources/promptTemplate.yaml
+agentx_dev/resources/promptTemplate.yaml
+examples/README.md
+examples/async_example.py
+examples/async_quickstart.py
+examples/auto_features_example.py
+examples/caching_example.py
+examples/chatbot_example.py
+examples/complete_example.py
+examples/concurrent_example.py
+examples/concurrent_tool_example.py
+examples/file_agent_demo.py
+examples/function_calling_demo.py
+examples/mcp_demo.py
+examples/observability_example.py
+examples/orchestration_demo.py
+examples/planner_example.py
+examples/supervisor_codebase_analysis_demo.py
+examples/supervisor_example.py
+examples/sync_quickstart.py

agentx_dev-3.0.1/agentx_dev.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+agentx_dev
+dist
+examples
+test_dl

agentx_dev-3.0.1/examples/README.md

@@ -0,0 +1,279 @@
+# AgentX Examples
+
+This directory contains practical examples demonstrating the enhanced features of AgentX framework.
+
+## Examples Overview
+
+### 1. `async_example.py` - Async Tool Execution
+**What it demonstrates:**
+- Creating async tools with `AsyncStandardTool` and `AsyncStructuredTool`
+- Concurrent execution of multiple tools
+- Using `AsyncAgentRunner`
+- Mixing sync and async tools
+
+**Run it:**
+```bash
+python async_example.py
+```
+
+**Key takeaways:**
+- Async tools enable concurrent I/O operations
+- Significant performance improvements for API calls
+- Backward compatible with sync tools
+
+---
+
+### 2. `caching_example.py` - Tool Result Caching
+**What it demonstrates:**
+- `InMemoryCache` for fast caching with TTL
+- `LRUCache` for capacity-limited caching
+- `FileCache` for persistent caching
+- `@cached_tool` decorator for automatic caching
+- Cache management operations
+
+**Run it:**
+```bash
+python caching_example.py
+```
+
+**Key takeaways:**
+- Caching avoids redundant expensive operations
+- Different cache types for different use cases
+- TTL support for automatic expiration
+- Decorator makes caching transparent
+
+---
+
+### 3. `observability_example.py` - Monitoring & Metrics
+**What it demonstrates:**
+- Setting up observability hooks
+- `ConsoleHook` for colored console output
+- `MetricsHook` for performance tracking
+- `FileHook` for JSON logging
+- `CallbackHook` for custom processing
+- `@track_tool_call` decorator
+
+**Run it:**
+```bash
+python observability_example.py
+```
+
+**Key takeaways:**
+- Monitor every step of agent execution
+- Collect performance metrics automatically
+- Custom callbacks for integration
+- Zero-config observability
+
+---
+
+### 4. `complete_example.py` - All Features Together
+**What it demonstrates:**
+- Complete multi-turn conversation setup
+- All enhanced features working together
+- Real-world usage patterns
+- Best practices
+
+**Run it:**
+```bash
+python complete_example.py
+```
+
+**Key takeaways:**
+- How features integrate seamlessly
+- Production-ready setup
+- Memory + Caching + Observability + Async
+
+---
+
+## Quick Start
+
+### Basic Example (No API Key Needed)
+
+```python
+# Run any example without OpenAI API
+python async_example.py
+python caching_example.py
+python observability_example.py
+```
+
+These examples demonstrate the features without requiring an OpenAI API key.
+
+### With OpenAI API
+
+To use the actual agent functionality:
+
+1. Set your API key:
+```bash
+export OPENAI_API_KEY='your-key-here'
+```
+
+2. Uncomment the agent creation code in examples
+
+3. Run the example
+
+---
+
+## Learning Path
+
+**Recommended order for learning:**
+
+1. **Start with caching** (`caching_example.py`)
+   - Easiest to understand
+   - Immediate performance benefits
+   - No async complexity
+
+2. **Add observability** (`observability_example.py`)
+   - See what's happening inside agents
+   - Learn event tracking
+   - Understand performance metrics
+
+3. **Try async tools** (`async_example.py`)
+   - Understand async benefits
+   - See concurrent execution
+   - Compare performance
+
+4. **Complete example** (`complete_example.py`)
+   - See everything together
+   - Real-world patterns
+   - Production setup
+
+---
+
+## Example Output
+
+### Caching Performance
+```
+First call (cache miss):
+  [EXECUTING] expensive_operation('test query')
+  Result: Result for: test query
+  Time: 2.01s
+
+Second call (cache hit):
+  Result: Result for: test query
+  Time: 0.00s
+```
+
+### Concurrent Execution
+```
+Executing 5 tools concurrently...
+Fetching weather for New York...
+Fetching weather for Los Angeles...
+Searching for 'AI news'...
+
+Completed in 1.05 seconds
+(vs 3+ seconds sequentially)
+```
+
+### Observability Output
+```
+[tool.call.start]
+[tool.call.complete] (123.45ms)
+[llm.call.start]
+[llm.call.complete] (456.78ms)
+
+Performance Metrics:
+  tool.call.complete: 5 calls, avg 120ms
+  llm.call.complete: 3 calls, avg 450ms
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Cached Async Tool
+```python
+from agentx_dev import AsyncStandardTool, InMemoryCache, cached_tool
+
+cache = InMemoryCache(default_ttl=300)
+
+@cached_tool(cache, ttl=60)
+async def api_call(query: str) -> str:
+    return await fetch_from_api(query)
+
+tool = AsyncStandardTool(func=api_call, name="api")
+```
+
+### Pattern 2: Monitored Agent
+```python
+from agentx_dev import observability, ConsoleHook, MetricsHook
+
+observability.add_hook(ConsoleHook(verbose=True))
+metrics = MetricsHook()
+observability.add_hook(metrics)
+
+# Use agent - events auto-tracked
+response = agent.Initialize("query")
+
+# Get metrics
+print(metrics.get_summary())
+```
+
+### Pattern 3: Memory-Managed Conversation
+```python
+from agentx_dev import TokenLimitedMemory
+
+memory = TokenLimitedMemory(max_tokens=4000)
+
+for user_query in conversation:
+    response = agent.Initialize(
+        user_query,
+        ChatHistory=memory.get_messages()
+    )
+
+    memory.add_message("user", user_query)
+    memory.add_message("assistant", response.content)
+```
+
+---
+
+## Troubleshooting
+
+### Import Errors
+```python
+# Make sure AgentX is installed
+pip install agentx-dev
+
+# Or install in development mode
+pip install -e .
+```
+
+### OpenAI API Errors
+```python
+# Set API key
+import os
+os.environ['OPENAI_API_KEY'] = 'your-key'
+
+# Or pass directly
+from agentx_dev import GPT
+chat_model = GPT(api_key='your-key')
+```
+
+### Async Errors
+```python
+# Run async functions with asyncio
+import asyncio
+
+async def main():
+    result = await async_agent.Initialize("query")
+
+asyncio.run(main())
+```
+
+---
+
+## Next Steps
+
+After running these examples:
+
+1. Read `ENHANCEMENTS.md` for detailed documentation
+2. Check `ENHANCEMENT_SUMMARY.md` for overview
+3. Explore the source code in `agentx_dev/`
+4. Build your own agent with these features!
+
+---
+
+## Questions?
+
+- **Documentation**: See `ENHANCEMENTS.md`
+- **Issues**: https://github.com/shadrach098/Bruce_framework/issues
+- **Source**: https://github.com/shadrach098/Bruce_framework

agentx_dev-3.0.1/examples/async_example.py

@@ -0,0 +1,160 @@
+"""
+Example: Async Tool Execution with AgentX
+
+This example demonstrates how to use async tools for concurrent execution,
+which is particularly useful for I/O-bound operations like API calls.
+"""
+
+import asyncio
+from agentx_dev import (
+    AsyncAgentRunner, AsyncStandardTool, AsyncStructuredTool,
+    AgentType, GPT, execute_tools_concurrently
+)
+from pydantic import BaseModel
+
+
+# Example 1: Async Standard Tool
+async def fetch_weather(location: str) -> str:
+    """Simulate fetching weather from an API."""
+    print(f"Fetching weather for {location}...")
+    await asyncio.sleep(1)  # Simulate API delay
+    return f"Weather in {location}: Sunny, 72°F"
+
+
+# Example 2: Async Structured Tool
+class SearchArgs(BaseModel):
+    query: str
+    limit: int = 10
+
+
+async def web_search(query: str, limit: int = 10) -> str:
+    """Simulate web search API call."""
+    print(f"Searching for '{query}' (limit: {limit})...")
+    await asyncio.sleep(0.5)  # Simulate API delay
+    return f"Found {limit} results for query: '{query}'"
+
+
+# Example 3: Multiple concurrent tool calls
+async def concurrent_execution_demo():
+    """Demonstrate executing multiple tools concurrently."""
+    print("=== Concurrent Tool Execution Demo ===\n")
+
+    # Create async tools
+    weather_tool = AsyncStandardTool(
+        func=fetch_weather,
+        name="weather",
+        description="Get current weather for a location"
+    )
+
+    search_tool = AsyncStructuredTool(
+        func=web_search,
+        args_schema=SearchArgs,
+        name="search",
+        description="Search the web for information"
+    )
+
+    # Define tools to execute concurrently
+    tools_to_run = [
+        {'tool': weather_tool, 'args': {'input': 'New York'}},
+        {'tool': weather_tool, 'args': {'input': 'Los Angeles'}},
+        {'tool': weather_tool, 'args': {'input': 'Chicago'}},
+        {'tool': search_tool, 'args': {'query': 'AI news', 'limit': 5}},
+        {'tool': search_tool, 'args': {'query': 'Python tutorials', 'limit': 3}}
+    ]
+
+    # Execute all tools concurrently
+    print("Executing 5 tools concurrently...")
+    start_time = asyncio.get_event_loop().time()
+
+    results = await execute_tools_concurrently(tools_to_run)
+
+    end_time = asyncio.get_event_loop().time()
+    print(f"\nCompleted in {end_time - start_time:.2f} seconds\n")
+
+    # Display results
+    for i, result in enumerate(results):
+        print(f"Result {i+1}: {result}")
+
+    print("\n" + "="*50 + "\n")
+
+
+# Example 4: Using AsyncAgentRunner
+async def agent_runner_demo():
+    """Demonstrate AsyncAgentRunner with async tools."""
+    print("=== AsyncAgentRunner Demo ===\n")
+
+    # Create tools
+    weather_tool = AsyncStandardTool(
+        func=fetch_weather,
+        name="weather",
+        description="Get current weather for a location"
+    )
+
+    search_tool = AsyncStructuredTool(
+        func=web_search,
+        args_schema=SearchArgs,
+        name="search",
+        description="Search the web for information"
+    )
+
+    # Create chat model (requires OpenAI API key)
+    # Uncomment and add your API key to run this example
+    # chat_model = GPT(model="gpt-4", api_key="your-api-key-here")
+
+    # For demo purposes, we'll skip the actual agent run
+    print("To run AsyncAgentRunner:")
+    print("1. Set your OpenAI API key")
+    print("2. Uncomment the agent creation code below\n")
+
+    # async_agent = AsyncAgentRunner(
+    #     model=chat_model,
+    #     Agent=AgentType.ReAct,
+    #     tools=[weather_tool, search_tool],
+    #     max_iterations=4
+    # )
+    #
+    # response = await async_agent.Initialize(
+    #     "What's the weather in NYC and find recent AI news?"
+    # )
+    #
+    # print(f"Agent Response: {response.content}")
+    # print(f"Tool Calls Made: {len(response.tool_calls)}")
+
+    print("\n" + "="*50 + "\n")
+
+
+# Example 5: Mixing sync and async tools
+async def mixed_tools_demo():
+    """Demonstrate using both sync and async tools together."""
+    print("=== Mixed Sync/Async Tools Demo ===\n")
+
+    # Async tool
+    async def async_calculation(x: int, y: int) -> int:
+        """Async calculation (simulating async operation)."""
+        await asyncio.sleep(0.1)
+        return x * y
+
+    # Note: In AsyncAgentRunner, sync tools still work
+    # They're just not executed concurrently
+    print("AsyncAgentRunner supports both sync and async tools.")
+    print("Async tools are executed with 'await', sync tools run normally.\n")
+
+    print("="*50 + "\n")
+
+
+async def main():
+    """Run all examples."""
+    print("\n" + "="*50)
+    print("AgentX Async Tools Examples")
+    print("="*50 + "\n")
+
+    # Run demos
+    await concurrent_execution_demo()
+    await agent_runner_demo()
+    await mixed_tools_demo()
+
+    print("All examples completed!\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentx_dev-3.0.1/examples/async_quickstart.py

@@ -0,0 +1,81 @@
+"""
+Async AsyncAgentRunner quickstart — concurrent tool execution + non-blocking LLM calls.
+
+The LLM call now uses `await model.async_initialize()` so the event loop
+is no longer blocked. Claude uses native AsyncAnthropic; GPT runs the sync
+client in a thread pool automatically.
+
+Run:
+    export OPENAI_API_KEY=sk-...
+    export ANTHROPIC_API_KEY=sk-ant-...
+    python examples/async_quickstart.py
+"""
+
+import asyncio
+from pydantic import BaseModel
+from agentx_dev import AsyncAgentRunner, AgentType, GPT, Claude
+from agentx_dev.AsyncTools import AsyncStandardTool, AsyncStructuredTool
+
+
+# --- Define async tools (I/O-bound work) ---
+
+class SearchArgs(BaseModel):
+    query: str
+    limit: int = 5
+
+
+async def web_search(query: str, limit: int = 5) -> str:
+    """Async web search (simulated)."""
+    await asyncio.sleep(0.4)  # simulated network call
+    return f"Found {limit} results for '{query}'"
+
+
+async def fetch_weather(city: str) -> str:
+    """Async weather fetch (simulated)."""
+    await asyncio.sleep(0.3)
+    return f"{city}: 19°C, light rain"
+
+
+search_tool = AsyncStructuredTool(
+    func=web_search,
+    args_schema=SearchArgs,
+    name="search",
+    description="Search the web for information.",
+)
+
+weather_tool = AsyncStandardTool(
+    func=fetch_weather,
+    name="weather",
+    description="Get current weather for a city.",
+)
+
+
+async def main():
+    # Pick a model — Claude uses native async, GPT runs in a thread pool
+    model = Claude(model="claude-sonnet-4-6", max_tokens=2048)
+    # model = GPT(model="gpt-4o")
+
+    runner = AsyncAgentRunner(
+        model=model,
+        Agent=AgentType.ReAct,
+        tools=[search_tool, weather_tool],
+        max_iterations=6,
+    )
+
+    # First call
+    r1 = await runner.Initialize(
+        "What's the weather in Berlin and search for recent AI news?"
+    )
+    print("Answer 1:", r1.content)
+    print("Tool calls:", [tc.name for tc in r1.tool_calls])
+
+    # Reusing the same runner now works correctly
+    r2 = await runner.Initialize("Search for python tutorials")
+    print("\nAnswer 2:", r2.content)
+
+    # Returned history is no longer None
+    print(f"\nHistory length: {len(r2.history)} messages")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())