# AgentForge
[](https://github.com/i365dev/agent_forge/actions/workflows/ci.yml)
[](https://hex.pm/packages/agent_forge)
[](https://hexdocs.pm/agent_forge)
[](https://github.com/i365dev/agent_forge/blob/main/LICENSE)
AgentForge is a lightweight, signal-driven workflow framework for Elixir, designed for building flexible and maintainable data processing pipelines.
```mermaid
graph TB
Signal[Signal] --> Handler[Handler]
Handler --> Store[Store]
Handler --> Flow[Flow]
Flow --> Runtime[Runtime]
```
## Features
- 🔄 **Signal-driven Architecture**: Build workflows around immutable signals
- 🧩 **Composable Primitives**: Core building blocks for common patterns
- 🔀 **Flexible Flows**: Chain handlers into dynamic processing pipelines
- 📦 **State Management**: Track and update workflow state
- âš¡ **Async Support**: Handle asynchronous operations
- 🛠**Configuration-based**: Define workflows in YAML
- 💪 **Type-safe**: Leverages Elixir's pattern matching
- 🔌 **Plugin System**: Extend functionality with custom plugins
## Quick Start
```elixir
# Add to mix.exs
def deps do
[
{:agent_forge, "~> 0.2.1"}
]
end
# Run
mix deps.get
```
> **Note**: AgentForge 0.2.1 introduces the plugin system with improved code quality! See the [Plugin System Guide](guides/plugin_system.md) for more details.
### Simple Example
```elixir
defmodule Example do
alias AgentForge.{Flow, Signal, Primitives}
def run do
# Define workflow steps
validate = Primitives.transform(fn data ->
if data.valid?, do: data, else: raise "Invalid data"
end)
process = Primitives.transform(fn data ->
Map.put(data, :processed, true)
end)
notify = Primitives.notify(
[:console],
format: &("Processed: #{inspect(&1)}")
)
# Compose workflow
workflow = [validate, process, notify]
# Execute
signal = Signal.new(:start, %{valid?: true})
{:ok, result, _state} = Flow.process(workflow, signal, %{})
IO.inspect(result)
end
end
```
## Core Components
### Signals
Immutable messages that flow through the system:
```elixir
signal = Signal.new(:user_action, %{id: 1})
```
### Primitives
Building blocks for common patterns:
- **Branch**: Conditional processing
- **Transform**: Data modification
- **Loop**: Iteration handling
- **Wait**: Async operations
- **Notify**: Event notifications
### Flows
Compose handlers into pipelines:
```elixir
workflow = [&validate/2, &process/2, ¬ify/2]
```
## Execution Limits
AgentForge now supports execution limits for flows to prevent long-running processes:
```elixir
# Create a handler
handler = fn signal, state ->
# Processing logic...
{{:emit, Signal.new(:done, result)}, state}
end
# Apply timeout limit
{:ok, result, state} = AgentForge.process_with_limits(
[handler],
signal,
%{},
timeout_ms: 5000 # Execution limited to 5 seconds
)
# Get execution statistics in the result
{:ok, result, state, stats} = AgentForge.process_with_limits(
[handler],
signal,
%{},
return_stats: true
)
# Or retrieve the last execution statistics afterwards
stats = AgentForge.get_last_execution_stats()
```
The execution limits feature supports the following options:
- `timeout_ms`: Maximum execution time in milliseconds (default: `30000`)
- `collect_stats`: Whether to collect execution statistics (default: `true`)
- `return_stats`: Whether to include statistics in the return value (default: `false`)
See the documentation for more details.
## Documentation
- [AgentForge Design Philosophy & Architecture Guide](guides/design_guide.md)
- [Getting Started Guide](guides/getting_started.md)
- [Core Concepts](guides/core_concepts.md)
- [Contribution Guidelines](CONTRIBUTING.md)
## Examples
- [Data Processing](examples/data_processing.exs): Basic data transformation pipeline
- [Async Workflow](examples/async_workflow.exs): Handling async operations
- [Configuration-based](examples/config_workflow.exs): YAML-defined workflows
## Design Philosophy
AgentForge focuses on:
- **Simplicity**: Clean, understandable codebase
- **Flexibility**: Adaptable to various use cases
- **Maintainability**: Well-documented, tested code
- **Composability**: Build complex flows from simple parts
## Use Cases
- ✅ Data Processing Pipelines
- ✅ Event-driven Workflows
- ✅ Multi-step Validations
- ✅ Async Task Orchestration
- ✅ Business Process Automation
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/USERNAME/agent_forge.git
cd agent_forge
# Get dependencies
mix deps.get
# Run tests
mix test
# Generate documentation
mix docs
```
### Pre-release Checklist
- [ ] All tests pass (`mix test`)
- [ ] Test coverage is acceptable (`mix coveralls.html` - check coverage/excoveralls.html)
- [ ] Code is formatted (`mix format`)
- [ ] Documentation generates without errors (`mix docs`)
- [ ] Version number is correct in mix.exs
- [ ] CHANGELOG.md is updated
- [ ] GitHub Actions workflows are in place
- [ ] All examples run without errors
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for guidelines.
1. Read the [AgentForge Design Philosophy & Architecture Guide](guides/design_guide.md)
2. Fork the repository
3. Create your feature branch (`git checkout -b feature/amazing-feature`)
4. Run the tests (`mix test`)
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
