Improve documentation and code readability

README.md

@@ -1,27 +1,39 @@
 # AgentFlow
+================
 
-![License](https://img.shields.io/badge/license-Apache--2.0-blue)
-![Python](https://img.shields.io/badge/python-3.9+-blue)
-![Status](https://img.shields.io/badge/build-experimental-orange)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://www.python.org/)
+[![Status](https://img.shields.io/badge/build-experimental-orange)]()
 
-AgentFlow is a lightweight workflow engine for multi-agent systems.
+## Overview
+-----------
 
-It allows developers to define task graphs, register agents with capabilities, and execute workflows with dependency-aware scheduling.
+AgentFlow is a lightweight workflow engine designed for multi-agent systems. It enables developers to define task graphs, register agents with capabilities, and execute workflows with dependency-aware scheduling.
 
-## Why this exists
+## Problem Statement
+-------------------
 
-Most agent frameworks focus on prompts, tools, or messaging.
+Most existing agent frameworks focus on prompts, tools, or messaging, but they lack a clear execution model for:
 
-They do not provide a clear execution model for:
+* Task dependencies
+* Workflow scheduling
+* Agent capability matching
+* Execution order tracing
 
-- task dependencies
-- workflow scheduling
-- agent capability matching
-- execution order tracing
+AgentFlow addresses this gap by providing a comprehensive solution for executing complex workflows in multi-agent systems.
 
-AgentFlow explores that missing layer.
+## Key Features
+--------------
+
+* **Task Graphs**: Define workflows as directed acyclic graphs (DAGs) with dependent tasks.
+* **Agent Capabilities**: Register agents with specific capabilities and match them with tasks.
+* **Dependency-Aware Scheduling**: Schedule tasks based on their dependencies and execute them in the correct order.
+* **Execution Tracing**: Print an execution trace to the console for debugging and monitoring purposes.
 
 ## Quick Start
+--------------
+
+Get started with AgentFlow by following these steps:
 
 ```bash
 git clone https://github.com/joshuamlamerton/agentflow
@@ -30,15 +42,19 @@ python examples/demo.py
 ```
 
 ## Demo
+------
 
-The demo shows:
+The demo showcases the following features:
 
-- a workflow with dependent tasks
-- two agents with different capabilities
-- a scheduler assigning tasks in dependency order
-- an execution trace printed to the console
+* A workflow with dependent tasks
+* Two agents with different capabilities
+* A scheduler assigning tasks in dependency order
+* An execution trace printed to the console
 
 ## Architecture
+--------------
+
+The following diagram illustrates the high-level architecture of AgentFlow:
 
 ```mermaid
 flowchart TB
@@ -60,6 +76,9 @@ C --> F
 ```
 
 ## Repository Structure
+-----------------------
+
+The AgentFlow repository is organized as follows:
 
 ```text
 agentflow
@@ -83,19 +102,31 @@ tests
 ```
 
 ## Roadmap
+---------
+
+AgentFlow is currently in the experimental phase. The roadmap consists of the following phases:
+
+### Phase 1: Basic Workflow and Dependency Execution
+
+* Implement basic workflow and dependency execution
+* Develop a scheduler that assigns tasks based on their dependencies
+
+### Phase 2: DAG Visualization and Trace Export
+
+* Implement DAG visualization for debugging and monitoring purposes
+* Export execution traces in a human-readable format
 
-Phase 1  
-Basic workflow and dependency execution
+### Phase 3: Distributed Task Routing
 
-Phase 2  
-DAG visualization and trace export
+* Develop a distributed task routing system for large-scale workflows
+* Implement load balancing and task distribution across multiple agents
 
-Phase 3  
-Distributed task routing
+### Phase 4: Framework Integrations
 
-Phase 4  
-Framework integrations
+* Integrate AgentFlow with popular frameworks and libraries
+* Develop a plugin architecture for easy extension and customization
 
 ## License
+-------
 
-Apache 2.0
+AgentFlow is licensed under the Apache 2.0 license.

README.md.bak.20260313145038

@@ -0,0 +1,101 @@
+# AgentFlow
+
+![License](https://img.shields.io/badge/license-Apache--2.0-blue)
+![Python](https://img.shields.io/badge/python-3.9+-blue)
+![Status](https://img.shields.io/badge/build-experimental-orange)
+
+AgentFlow is a lightweight workflow engine for multi-agent systems.
+
+It allows developers to define task graphs, register agents with capabilities, and execute workflows with dependency-aware scheduling.
+
+## Why this exists
+
+Most agent frameworks focus on prompts, tools, or messaging.
+
+They do not provide a clear execution model for:
+
+- task dependencies
+- workflow scheduling
+- agent capability matching
+- execution order tracing
+
+AgentFlow explores that missing layer.
+
+## Quick Start
+
+```bash
+git clone https://github.com/joshuamlamerton/agentflow
+cd agentflow
+python examples/demo.py
+```
+
+## Demo
+
+The demo shows:
+
+- a workflow with dependent tasks
+- two agents with different capabilities
+- a scheduler assigning tasks in dependency order
+- an execution trace printed to the console
+
+## Architecture
+
+```mermaid
+flowchart TB
+
+A[Workflow Definition]
+B[Scheduler]
+C[Task Queue]
+D[Agent Registry]
+E[Worker Agent A]
+F[Worker Agent B]
+
+A --> B
+B --> C
+B --> D
+D --> E
+D --> F
+C --> E
+C --> F
+```
+
+## Repository Structure
+
+```text
+agentflow
+
+README.md
+LICENSE
+
+docs
+  architecture.md
+
+core
+  workflow.py
+  agent.py
+  scheduler.py
+
+examples
+  demo.py
+
+tests
+  test_basic.py
+```
+
+## Roadmap
+
+Phase 1  
+Basic workflow and dependency execution
+
+Phase 2  
+DAG visualization and trace export
+
+Phase 3  
+Distributed task routing
+
+Phase 4  
+Framework integrations
+
+## License
+
+Apache 2.0

core/agent.py

@@ -1,11 +1,68 @@
+```python
+class Task:
+    """Represents a task that can be executed by an Agent."""
+    def __init__(self, name, func):
+        """
+        Initializes a Task instance.
+
+        Args:
+            name (str): The name of the task.
+            func (callable): The function to be executed when the task is run.
+        """
+        self.name = name
+        self.func = func
+
 class Agent:
+    """Represents an agent that can execute tasks."""
     def __init__(self, name, capabilities):
+        """
+        Initializes an Agent instance.
+
+        Args:
+            name (str): The name of the agent.
+            capabilities (list[str]): A list of task names that the agent can execute.
+        """
         self.name = name
         self.capabilities = set(capabilities)
 
     def can_run(self, task_name):
+        """
+        Checks if the agent can execute a task.
+
+        Args:
+            task_name (str): The name of the task to check.
+
+        Returns:
+            bool: True if the agent can execute the task, False otherwise.
+        """
         return task_name in self.capabilities
 
     def run(self, task):
+        """
+        Executes a task.
+
+        Args:
+            task (Task): The task to be executed.
+        """
         print(f"{self.name} executing task: {task.name}")
         task.func()
+
+
+# Example usage:
+def greet():
+    print("Hello!")
+
+def farewell():
+    print("Goodbye!")
+
+task1 = Task("Greet", greet)
+task2 = Task("Farewell", farewell)
+
+agent = Agent("John", ["Greet", "Farewell"])
+
+print(agent.can_run("Greet"))  # Output: True
+print(agent.can_run("Unknown"))  # Output: False
+
+agent.run(task1)  # Output: John executing task: Greet
+agent.run(task2)  # Output: John executing task: Farewell
+```

core/agent.py.bak.20260313145000

@@ -0,0 +1,11 @@
+class Agent:
+    def __init__(self, name, capabilities):
+        self.name = name
+        self.capabilities = set(capabilities)
+
+    def can_run(self, task_name):
+        return task_name in self.capabilities
+
+    def run(self, task):
+        print(f"{self.name} executing task: {task.name}")
+        task.func()