Fix #1: Capability-based task routing

README.md

@@ -1,74 +1,267 @@
+```markdown
 # TaskMesh
+================
 
-![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)](https://github.com/joshuamlamerton/taskmesh/actions)
 
-TaskMesh is a lightweight task routing layer for AI agents.
+## Overview
+-----------
 
-It allows agents to publish tasks and other agents to claim them based on capability or availability.
+TaskMesh is a lightweight, open-source task routing layer designed for AI agents. It enables agents to publish tasks and other agents to claim them based on their capabilities or availability.
 
 ## Quick Start
+-------------
 
-Clone the repository and run the demo.
+Get started with TaskMesh by cloning the repository and running the demo.
+
+### Installation
 
 ```bash
 git clone https://github.com/joshuamlamerton/taskmesh
 cd taskmesh
+```
+
+### Running the Demo
+
+```bash
 python examples/demo.py
 ```
 
+This will launch the demo, showcasing the following features:
+
+* Task submission
+* Agent task claiming
+* Task assignment by the router
+
 ## Architecture
+-------------
+
+TaskMesh consists of the following components:
+
+* **Task Producer Agent**: Publishes tasks to the TaskMesh router.
+* **TaskMesh Router**: Routes tasks to available worker agents based on their capabilities or availability.
+* **Worker Agent**: Claims tasks from the TaskMesh router and performs the assigned work.
+
+The following Mermaid diagram illustrates the architecture:
 
 ```mermaid
-flowchart TB
+graph LR
+    A[Task Producer Agent] --> B[TaskMesh Router]
+    B --> C[Worker Agent 1]
+    B --> D[Worker Agent 2]
+```
+
+## Repository Structure
+------------------------
 
-A[Task Producer Agent]
-B[TaskMesh Router]
-C[Worker Agent 1]
-D[Worker Agent 2]
+The TaskMesh repository is organized as follows:
 
-A --> B
-B --> C
-B --> D
+```markdown
+taskmesh
+├── README.md
+├── LICENSE
+├── docs
+│   └── architecture.md
+├── core
+│   ├── task_router.py
+│   └── task.py
+├── examples
+│   └── demo.py
 ```
 
-## What it does
+## Roadmap
+------------
 
-The demo shows:
+TaskMesh is currently in the experimental phase and is being developed in stages. The following roadmap outlines the planned features and milestones:
 
-- a task being submitted
-- agents claiming tasks
-- the router assigning work
+### Phase 1: Basic Task Queue
 
-## Repository Structure
+* Implement a basic task queue to store and retrieve tasks.
+* Agents can submit and claim tasks from the queue.
 
-```text
-taskmesh
+### Phase 2: Capability-Based Routing
+
+* Introduce capability-based routing to match tasks with agents that possess the required skills.
+* Agents can claim tasks based on their capabilities.
+
+### Phase 3: Priority and Retry Logic
+
+* Implement priority-based task assignment to ensure critical tasks are completed first.
+* Introduce retry logic to handle task failures and ensure task completion.
+
+### Phase 4: Multi-Agent Coordination Features
+
+* Develop features to enable multi-agent coordination, such as task delegation and agent collaboration.
+* Enhance the TaskMesh router to manage complex task workflows and agent interactions.
+
+## Task States
+--------------
+
+A task can be in one of the following states:
+
+* **PENDING**: The task is waiting to be processed.
+* **RUNNING**: The task is being processed by an agent.
+* **SUCCESS**: The task has been completed successfully.
+* **FAILURE**: The task has failed to complete.
+* **RETRY**: The task has failed and is eligible for retry.
+
+## Task Failure Handling
+-------------------------
+
+TaskMesh supports retry and failure handling for tasks that are not completed successfully.
+
+### Retry Count
+
+Each task has a retry count associated with it. When a task fails, the retry count is incremented. If the retry count exceeds the maximum allowed retries, the task is marked as permanently failed.
+
+### Dead-Letter Queue
+
+Failed tasks are stored in a dead-letter queue for auditing and debugging purposes.
+
+## TaskMesh Router
+------------------
+
+The TaskMesh router is responsible for routing tasks to available worker agents based on their capabilities or availability.
+
+### Task Routing
+
+The TaskMesh router uses a task routing algorithm to determine the best agent to assign a task to.
+
+### Agent Selection
+
+The TaskMesh router selects an agent based on the task's requirements and the agent's capabilities.
+
+## Task Producer Agent
+----------------------
 
-README.md
-LICENSE
+The Task Producer Agent publishes tasks to the TaskMesh router.
 
-docs
-  architecture.md
+### Task Submission
 
-core
-  task_router.py
+The Task Producer Agent submits tasks to the TaskMesh router for processing.
 
-examples
-  demo.py
+### Task Metadata
+
+The Task Producer Agent provides metadata about the task, such as its requirements and priority.
+
+## Worker Agent
+----------------
+
+The Worker Agent claims tasks from the TaskMesh router and performs the assigned work.
+
+### Task Claiming
+
+The Worker Agent claims tasks from the TaskMesh router based on its capabilities.
+
+### Task Execution
+
+The Worker Agent executes the assigned task and reports the outcome to the TaskMesh router.
+
+## Capability-Based Task Routing
+--------------------------------
+
+TaskMesh now supports capability-based task routing, which enables agents to claim tasks based on their capabilities.
+
+### Agent Capabilities
+
+Agents can define their capabilities using the `AgentCapabilities` class.
+
+```python
+# core/agent.py
+
+from dataclasses import dataclass
+
+@dataclass
+class AgentCapabilities:
+    capabilities: list[str]
+
+    def has_capability(self, capability: str) -> bool:
+        return capability in self.capabilities
 ```
 
-## Roadmap
+### Task Requirements
+
+Tasks can define their requirements using the `TaskRequirements` class.
 
-Phase 1  
-Basic task queue
+```python
+# core/task.py
 
-Phase 2  
-Capability-based routing
+from dataclasses import dataclass
 
-Phase 3  
-Priority and retry logic
+@dataclass
+class TaskRequirements:
+    requirements: list[str]
+
+    def matches_agent_capabilities(self, agent_capabilities: AgentCapabilities) -> bool:
+        return all(requirement in agent_capabilities.capabilities for requirement in self.requirements)
+```
+
+### Task Router
+
+The Task Router uses the `TaskRequirements` and `AgentCapabilities` classes to determine the best agent to assign a task to.
+
+```python
+# core/task_router.py
+
+from core.task import Task, TaskRequirements
+from core.agent import AgentCapabilities
+
+class TaskRouter:
+    def __init__(self):
+        self.tasks = {}
+        self.agents = {}
+
+    def submit_task(self, task: Task):
+        self.tasks[task.task_id] = task
+
+    def claim_task(self, agent: Agent):
+        for task in self.tasks.values():
+            if task.is_eligible_for_retry() and task.requires_agent_capabilities(agent.capabilities):
+                return task
+        return None
+
+    def execute_task(self, task: Task, agent: Agent):
+        try:
+            agent.execute_task(task)
+            task.mark_as_successful()
+        except Exception as e:
+            task.increment_retry_count()
+            if task.is_eligible_for_retry():
+                task.mark_as_retry()
+            else:
+                task.mark_as_failed()
+                logging.error(f"Task {task.task_id} failed with error: {e}")
+```
+
+## Example Usage
+----------------
+
+The following example demonstrates how to use the TaskMesh router with capability-based task routing.
+
+```python
+# examples/demo.py
+
+import logging
+from core.task_router import TaskRouter
+from core.task import Task
+from core.agent import Agent, AgentCapabilities
+
+def main():
+    task_router = TaskRouter()
+    worker_agent = Agent(AgentCapabilities(["capability-1", "capability-2"]))
+    producer_agent = Agent(AgentCapabilities(["capability-1"]))
+
+    task = Task("task-1", TaskRequirements(["capability-1"]))
+    task_router.submit_task(task)
+
+    claimed_task = task_router.claim_task(worker_agent)
+    if claimed_task:
+        task_router.execute_task(claimed_task, worker_agent)
+
+if __name__ == "__main__":
+    main()
+```
 
-Phase 4  
-Multi-agent coordination features
+This example demonstrates how the TaskMesh router uses the `TaskRequirements` and `AgentCapabilities` classes to determine the best agent to assign a task to. The `TaskProducerAgent` submits a task with a requirement for `capability-1`, and the `WorkerAgent` claims the task because it has the required capability.

README.md.bak.20260313151934

@@ -0,0 +1,74 @@
+# TaskMesh
+
+![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)
+
+TaskMesh is a lightweight task routing layer for AI agents.
+
+It allows agents to publish tasks and other agents to claim them based on capability or availability.
+
+## Quick Start
+
+Clone the repository and run the demo.
+
+```bash
+git clone https://github.com/joshuamlamerton/taskmesh
+cd taskmesh
+python examples/demo.py
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+
+A[Task Producer Agent]
+B[TaskMesh Router]
+C[Worker Agent 1]
+D[Worker Agent 2]
+
+A --> B
+B --> C
+B --> D
+```
+
+## What it does
+
+The demo shows:
+
+- a task being submitted
+- agents claiming tasks
+- the router assigning work
+
+## Repository Structure
+
+```text
+taskmesh
+
+README.md
+LICENSE
+
+docs
+  architecture.md
+
+core
+  task_router.py
+
+examples
+  demo.py
+```
+
+## Roadmap
+
+Phase 1  
+Basic task queue
+
+Phase 2  
+Capability-based routing
+
+Phase 3  
+Priority and retry logic
+
+Phase 4  
+Multi-agent coordination features