Skip to content

AgentForge is a powerful and flexible signal-driven workflow framework designed for building intelligent, dynamic, and adaptive systems.

License

Notifications You must be signed in to change notification settings

i365dev/agent_forge

Repository files navigation

AgentForge

CI Hex.pm Docs License

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]
Loading

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.1"}
  ]
end

# Run
mix deps.get

Note: AgentForge 0.2.1 introduces the plugin system with improved code quality! 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

Examples

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.

About

AgentForge is a powerful and flexible signal-driven workflow framework designed for building intelligent, dynamic, and adaptive systems.

Topics

Resources

License

Stars

Watchers

Forks