AgentForge

AgentForge is a lightweight, signal-driven workflow framework for Elixir, designed for building flexible and maintainable data processing pipelines.

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

# Add to mix.exs
def deps do
  [
    {:agent_forge, "~> 0.2.0"}
  ]
end

# Run
mix deps.get

Note: AgentForge 0.2.0 introduces the plugin system! See the Plugin System Guide for more details.

Simple Example

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:

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:

workflow = [&validate/2, &process/2, &notify/2]

Execution Limits

AgentForge now supports execution limits for flows to prevent long-running processes:

# 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
• Getting Started Guide
• Core Concepts
• Contribution Guidelines

Examples

• Data Processing: Basic data transformation pipeline
• Async Workflow: Handling async operations
• Configuration-based: 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

# 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 for guidelines.

1. Read the AgentForge Design Philosophy & Architecture Guide
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 file for details.