Add Execution Limits and Statistics Tracking to AgentForge

[madawei2699]

Overview

This PR introduces execution limits and statistics tracking to the AgentForge framework, allowing users to set timeouts for flow processing and collect performance metrics. These features enhance the framework's reliability and observability by preventing long-running processes and providing insights into execution performance.

Key Changes

1. Timeout Support

• Added process_with_limits functionality to Flow and exposed it through the top-level API
• Implemented timeout handling using Elixir's Task module with configurable duration
• Graceful error handling when timeouts occur, preserving the most recent state

2. Execution Statistics

• Created a new ExecutionStats module for collecting and analyzing flow execution metrics
• Track key performance indicators including execution time, number of steps, and completion status
• Provide both inline stats (returned with results) and post-execution retrieval via get_last_execution_stats

3. Helper Functions

• Added always_emit/2: Creates a handler that always emits a specified signal type and data
• Added filter_type/2: Creates a handler that processes only signals of a specific type
• Added store_in_state/1: Creates a handler that stores signal data in state under a given key

4. Documentation and Examples

• Updated README with execution limits documentation
• Created a detailed guide (guides/execution_limits.md) explaining the new features
• Added a practical example (examples/limited_workflow.exs) demonstrating various timeout scenarios

5. Backward Compatibility

• Ensured that all existing tests pass without modification
• Made statistics collection optional and not returned by default
• Preserved the original function signatures for backward compatibility

Testing

• Added unit tests for the timeout and statistics features
• Created integration tests that verify end-to-end functionality
• Verified backward compatibility with existing code

Usage Example

# Apply a 5-second timeout limit
{:ok, result, state} = AgentForge.process_with_limits(
  handlers, 
  signal, 
  %{}, 
  timeout_ms: 5000
)

# Get execution statistics
{:ok, result, state, stats} = AgentForge.process_with_limits(
  handlers, 
  signal, 
  %{}, 
  return_stats: true
)

This feature helps users prevent runaway executions and gain visibility into their workflows' performance characteristics, making AgentForge more robust for production environments.

[coveralls]

Pull Request Test Coverage Report for Build eb397242e248ed91e65d1cdecfc1b2c7a60a6042-PR-7

Details

• 90 of 104 (86.54%) changed or added relevant lines in 3 files are covered.
• 2 unchanged lines in 2 files lost coverage.
• Overall coverage decreased (-0.3%) to 88.443%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
lib/agent_forge/runtime.ex	36	42	85.71%
lib/agent_forge/flow.ex	52	60	86.67%

Files with Coverage Reduction	New Missed Lines	%
lib/agent_forge/flow.ex	1	84.51%
lib/agent_forge/runtime.ex	1	87.04%

Totals
Change from base Build 91b6247ecc79546f97bd05aaa7b129aa252adf3f:	-0.3%
Covered Lines:	375
Relevant Lines:	424

---

💛 - Coveralls