# wso2-incubator/research-rac architecture

> Architecture diagram of the GitHub repository wso2-incubator/research-rac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wso2-incubator/research-rac
- Repository: https://github.com/wso2-incubator/research-rac

## Overview

This library wraps ReAct agent tool execution so completed actions can be recorded, retried or recovered after failure, and compensated in dependency-aware rollback order. Framework adaptors connect that core workflow to LangChain/LangGraph, CrewAI, and Strands; MCP adds tool discovery and compensation-pair metadata. Extraction strategies derive undo parameters, while retry and error policies guide recovery. The README documents these capabilities, but several implementation links are based on the source index rather than inspected call sites; uncertain connections are omitted.

Main entry points: [`src/react_agent_compensation/core/recovery_manager.py`](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/recovery_manager.py) (Recovery manager), [`src/react_agent_compensation/langchain_adaptor/agent.py`](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/langchain_adaptor/agent.py) (LangChain adaptor), [`src/react_agent_compensation/strands_adaptor/hooks.py`](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/strands_adaptor/hooks.py) (Strands hooks), [`src/react_agent_compensation/langchain_adaptor/middleware.py`](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/langchain_adaptor/middleware.py) (LangChain middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integrations["Agent integrations"]
  node_langchain["LangChain adaptor<br/>[agent.py]"]
  node_crewai["CrewAI adaptor<br/>[tool_wrapper.py]"]
  node_strands["Strands hooks<br/>[hooks.py]"]
  node_crewai_middleware["Crew middleware<br/>[middleware.py]"]
  node_langchain_middleware["LangChain middleware<br/>[middleware.py]"]
  node_strands_adapters["Strands adapters<br/>[adapters.py]"]
end

subgraph group_recovery["Recovery core"]
  node_manager["Recovery manager"]
  node_transaction_log[("Transaction log<br/>[transaction_log.py]")]
  node_models["Action models<br/>[models.py]"]
  node_batch["Batch coordination<br/>[manager.py]"]
end

subgraph group_extraction["Extraction and MCP"]
  node_mcp_client["MCP client<br/>[client.py]"]
  node_mcp_parser["MCP discovery<br/>[parser.py]"]
  node_mcp_metadata["MCP metadata<br/>[metadata.py]"]
  node_extraction["Parameter extraction"]
  node_path_resolver["Path resolver<br/>[path_resolver.py]"]
  node_llm_extract["LLM extraction<br/>[extraction.py]"]
  node_llm_match["LLM matching<br/>[matching.py]"]
end

subgraph group_policy["Recovery policies"]
  node_config["Recovery config<br/>[config.py]"]
  node_errors["Error strategies<br/>[base.py]"]
  node_retry["Retry strategies<br/>[base.py]"]
end

node_user(("Agent user"))

node_user -->|"invokes agent"| node_langchain
node_user -->|"starts crew"| node_crewai
node_user -->|"invokes agent"| node_strands
node_langchain -->|"wraps tools"| node_langchain_middleware
node_crewai -->|"uses middleware"| node_crewai_middleware
node_strands -->|"records actions"| node_manager
node_strands -->|"adapts tools"| node_strands_adapters
node_langchain_middleware -->|"recovers actions"| node_manager
node_crewai_middleware -->|"recovers actions"| node_manager
node_manager -->|"records actions"| node_transaction_log
node_transaction_log -->|"stores records"| node_models
node_manager -->|"extracts undo parameters"| node_extraction
node_manager -->|"uses policies"| node_config
node_manager -->|"classifies failures"| node_errors
node_manager -->|"uses retry policy"| node_retry
node_extraction -->|"resolves paths"| node_path_resolver
node_extraction -->|"supports extraction"| node_llm_extract
node_langchain_middleware -->|"uses dynamic matching"| node_llm_match
node_mcp_client -->|"discovers tool metadata"| node_mcp_parser
node_mcp_client -->|"delegates rollback"| node_manager
node_mcp_parser -->|"extracts metadata"| node_mcp_metadata
node_mcp_parser -->|"registers compensation pairs"| node_manager
node_langchain -.->|"connects MCP tools"| node_mcp_client
node_manager -.->|"coordinates batches"| node_batch

click node_langchain "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/langchain_adaptor/agent.py"
click node_crewai "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/crewai_adaptor/tool_wrapper.py"
click node_strands "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/strands_adaptor/hooks.py"
click node_mcp_client "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/mcp/client.py"
click node_mcp_parser "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/mcp/parser.py"
click node_mcp_metadata "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/mcp/metadata.py"
click node_manager "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/recovery_manager.py"
click node_transaction_log "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/transaction_log.py"
click node_models "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/models.py"
click node_config "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/config.py"
click node_errors "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/errors/base.py"
click node_retry "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/retry/base.py"
click node_extraction "https://github.com/wso2-incubator/research-rac/tree/main/src/react_agent_compensation/core/extraction"
click node_path_resolver "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/extraction/path_resolver.py"
click node_llm_extract "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/llm/extraction.py"
click node_llm_match "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/llm/matching.py"
click node_crewai_middleware "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/crewai_adaptor/middleware.py"
click node_langchain_middleware "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/langchain_adaptor/middleware.py"
click node_strands_adapters "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/strands_adaptor/adapters.py"
click node_batch "https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/batch/manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_langchain,node_crewai,node_strands,node_crewai_middleware,node_langchain_middleware,node_strands_adapters,node_user toneBlue
class node_manager,node_transaction_log,node_models,node_batch toneAmber
class node_mcp_client,node_mcp_parser,node_mcp_metadata,node_extraction,node_path_resolver,node_llm_extract,node_llm_match toneMint
class node_config,node_errors,node_retry toneRose
```

## Components

### Agent integrations

- [LangChain adaptor](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/langchain_adaptor/agent.py): `src/react_agent_compensation/langchain_adaptor/agent.py`
- [CrewAI adaptor](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/crewai_adaptor/tool_wrapper.py): `src/react_agent_compensation/crewai_adaptor/tool_wrapper.py`
- [Strands hooks](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/strands_adaptor/hooks.py): `src/react_agent_compensation/strands_adaptor/hooks.py`
- [Crew middleware](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/crewai_adaptor/middleware.py): `src/react_agent_compensation/crewai_adaptor/middleware.py`
- [LangChain middleware](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/langchain_adaptor/middleware.py): `src/react_agent_compensation/langchain_adaptor/middleware.py`
- [Strands adapters](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/strands_adaptor/adapters.py): `src/react_agent_compensation/strands_adaptor/adapters.py`

### Recovery core

- [Recovery manager](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/recovery_manager.py): `src/react_agent_compensation/core/recovery_manager.py`
- [Transaction log](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/transaction_log.py): `src/react_agent_compensation/core/transaction_log.py`
- [Action models](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/models.py): `src/react_agent_compensation/core/models.py`
- [Batch coordination](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/batch/manager.py): `src/react_agent_compensation/core/batch/manager.py`

### Extraction and MCP

- [MCP client](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/mcp/client.py): `src/react_agent_compensation/core/mcp/client.py`
- [MCP discovery](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/mcp/parser.py): `src/react_agent_compensation/core/mcp/parser.py`
- [MCP metadata](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/mcp/metadata.py): `src/react_agent_compensation/core/mcp/metadata.py`
- [Parameter extraction](https://github.com/wso2-incubator/research-rac/tree/main/src/react_agent_compensation/core/extraction): `src/react_agent_compensation/core/extraction`
- [Path resolver](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/extraction/path_resolver.py): `src/react_agent_compensation/core/extraction/path_resolver.py`
- [LLM extraction](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/llm/extraction.py): `src/react_agent_compensation/llm/extraction.py`
- [LLM matching](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/llm/matching.py): `src/react_agent_compensation/llm/matching.py`

### Recovery policies

- [Recovery config](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/config.py): `src/react_agent_compensation/core/config.py`
- [Error strategies](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/errors/base.py): `src/react_agent_compensation/core/errors/base.py`
- [Retry strategies](https://github.com/wso2-incubator/research-rac/blob/main/src/react_agent_compensation/core/retry/base.py): `src/react_agent_compensation/core/retry/base.py`

### Other components

- **Agent user**

## Connections

- Agent user → LangChain adaptor: invokes agent (evidence: `README.md`)
- Agent user → CrewAI adaptor: starts crew (evidence: `README.md`)
- Agent user → Strands hooks: invokes agent (evidence: `README.md`)
- LangChain adaptor → LangChain middleware: wraps tools (evidence: `src/react_agent_compensation/langchain_adaptor/agent.py`)
- CrewAI adaptor → Crew middleware: uses middleware (evidence: `src/react_agent_compensation/crewai_adaptor/tool_wrapper.py`)
- Strands hooks → Recovery manager: records actions (evidence: `src/react_agent_compensation/strands_adaptor/hooks.py`)
- Strands hooks → Strands adapters: adapts tools (evidence: `src/react_agent_compensation/strands_adaptor/hooks.py`)
- LangChain middleware → Recovery manager: recovers actions (evidence: `src/react_agent_compensation/langchain_adaptor/middleware.py`)
- Crew middleware → Recovery manager: recovers actions (evidence: `src/react_agent_compensation/crewai_adaptor/middleware.py`)
- Recovery manager → Transaction log: records actions (evidence: `src/react_agent_compensation/core/recovery_manager.py`)
- Transaction log → Action models: stores records (evidence: `src/react_agent_compensation/core/transaction_log.py`)
- Recovery manager → Parameter extraction: extracts undo parameters (evidence: `src/react_agent_compensation/core/recovery_manager.py`)
- Recovery manager → Recovery config: uses policies (evidence: `src/react_agent_compensation/core/recovery_manager.py`)
- Recovery manager → Error strategies: classifies failures (evidence: `src/react_agent_compensation/core/recovery_manager.py`)
- Recovery manager → Retry strategies: uses retry policy (evidence: `src/react_agent_compensation/core/recovery_manager.py`)
- Parameter extraction → Path resolver: resolves paths (evidence: `src/react_agent_compensation/core/extraction/base.py`)
- Parameter extraction → LLM extraction: supports extraction (evidence: `src/react_agent_compensation/core/extraction/composite.py`)
- LangChain middleware → LLM matching: uses dynamic matching (evidence: `src/react_agent_compensation/langchain_adaptor/middleware.py`)
- MCP client → MCP discovery: discovers tool metadata (evidence: `src/react_agent_compensation/core/mcp/client.py`)
- MCP client → Recovery manager: delegates rollback (evidence: `src/react_agent_compensation/core/mcp/client.py`)
- MCP discovery → MCP metadata: extracts metadata (evidence: `src/react_agent_compensation/core/mcp/parser.py`)
- MCP discovery → Recovery manager: registers compensation pairs (evidence: `src/react_agent_compensation/core/mcp/parser.py`)
- LangChain adaptor → MCP client: connects MCP tools (evidence: `README.md`)
- Recovery manager → Batch coordination: coordinates batches
