# naveen457/rl-based-adaptive-mas architecture

> Architecture diagram of the GitHub repository naveen457/rl-based-adaptive-mas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naveen457/rl-based-adaptive-mas
- Repository: https://github.com/naveen457/rl-based-adaptive-mas

## Overview

AMAS accepts tasks through a CLI or HTTP API, profiles task context, and uses an active tabular Q-learning controller to adapt an agent architecture before execution. The runtime bridges the adapted architecture to a workflow, runs specialist agents and tools, and returns a finalized answer; evaluation and a separate offline neural-policy research branch support the system. Edges are limited to README workflow statements and source-index references; unsampled implementations are represented only where the README documents the capability.

Main entry points: [`app/runtime/orchestrator.py`](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/runtime/orchestrator.py) (Runtime orchestrator), [`app/runtime/llm_execution.py`](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/runtime/llm_execution.py) (LLM executor), [`app/architecture/manager.py`](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/manager.py) (Architecture manager), [`app/rl/meta_task.py`](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_task.py) (Task profiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Task entry"]
  node_cli["CLI<br/>[main.py]"]
  node_http["HTTP API<br/>[server.py]"]
end

subgraph group_adapt["Adaptive architecture"]
  node_profiler["Task profiler<br/>[meta_task.py]"]
  node_state_encoder["State encoder<br/>[state.py]"]
  node_q_controller["Tabular Q-learning<br/>[q_learning.py]"]
  node_actions["Architecture actions<br/>[actions.py]"]
  node_manager["Architecture manager<br/>[manager.py]"]
  node_architecture["Architecture model<br/>[models.py]"]
end

subgraph group_execution["Agent execution"]
  node_adapter["Workflow adapter"]
  node_builder["Dynamic graph builder<br/>[dynamic_builder.py]"]
  node_orchestrator["Runtime orchestrator<br/>[orchestrator.py]"]
  node_planner["Planner<br/>[planner.py]"]
  node_registry["Agent registry<br/>[registry.py]"]
  node_specialists["Specialist agents"]
  node_llm_executor["LLM executor<br/>[llm_execution.py]"]
  node_tool_executor["Tool executor<br/>[tool_executor.py]"]
  node_tools["External tools"]
  node_finalizer["Finalizer<br/>[finalizer.py]"]
end

subgraph group_state["State and evaluation"]
  node_memory[("Thread memory<br/>[store.py]")]
  node_mongo[("MongoDB<br/>[mongo_client.py]")]
  node_evaluation["Task evaluation<br/>[evaluator.py]"]
  node_reward["Reward calculation<br/>[reward.py]"]
end

subgraph group_research["Offline policy research"]
  node_neural_policy["Neural meta-policy"]
  node_meta_eval["Meta-policy evaluation<br/>[meta_evaluation.py]"]
end

node_user(("User"))

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_http
node_cli -->|"profiles task"| node_profiler
node_http -->|"profiles task"| node_profiler
node_profiler -->|"provides context"| node_state_encoder
node_state_encoder -->|"encodes state"| node_q_controller
node_q_controller -->|"selects mutation"| node_actions
node_actions -->|"describes mutation"| node_manager
node_manager -->|"validates architecture"| node_architecture
node_manager -->|"supplies architecture"| node_adapter
node_adapter -->|"configures workflow"| node_builder
node_orchestrator -->|"runs planning"| node_planner
node_orchestrator -->|"adapts architecture"| node_adapter
node_orchestrator -->|"invokes graph"| node_builder
node_orchestrator -->|"executes agents"| node_llm_executor
node_planner -->|"reads capabilities"| node_registry
node_llm_executor -->|"runs specialists"| node_specialists
node_llm_executor -->|"runs tool calls"| node_tool_executor
node_tool_executor -.->|"dispatches tools"| node_tools
node_llm_executor -->|"finalizes response"| node_finalizer
node_orchestrator -->|"stores messages"| node_memory
node_memory -->|"uses connection"| node_mongo
node_evaluation -->|"evaluates structure"| node_architecture
node_reward -->|"scores performance"| node_evaluation
node_neural_policy -.->|"evaluated by"| node_meta_eval

click node_cli "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/main.py"
click node_http "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/server.py"
click node_profiler "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_task.py"
click node_state_encoder "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/state.py"
click node_q_controller "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/q_learning.py"
click node_actions "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/actions.py"
click node_manager "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/manager.py"
click node_architecture "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/models.py"
click node_adapter "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/graph/adaptive_integration.py"
click node_builder "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/graph/dynamic_builder.py"
click node_orchestrator "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/runtime/orchestrator.py"
click node_planner "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/planner.py"
click node_registry "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/registry.py"
click node_specialists "https://github.com/naveen457/rl-based-adaptive-mas/tree/main/app/agents"
click node_llm_executor "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/runtime/llm_execution.py"
click node_tool_executor "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/tool_executor.py"
click node_tools "https://github.com/naveen457/rl-based-adaptive-mas/tree/main/app/tools"
click node_finalizer "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/finalizer.py"
click node_memory "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/memory/store.py"
click node_mongo "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/memory/mongo_client.py"
click node_evaluation "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/evaluation/evaluator.py"
click node_reward "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/evaluation/reward.py"
click node_neural_policy "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_neural_trainer.py"
click node_meta_eval "https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_evaluation.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_cli,node_http,node_user toneBlue
class node_profiler,node_state_encoder,node_q_controller,node_actions,node_manager,node_architecture toneAmber
class node_adapter,node_builder,node_orchestrator,node_planner,node_registry,node_specialists,node_llm_executor,node_tool_executor,node_tools,node_finalizer toneMint
class node_memory,node_mongo,node_evaluation,node_reward toneRose
class node_neural_policy,node_meta_eval toneIndigo
```

## Components

### Task entry

- [CLI](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/main.py): `app/main.py`
- [HTTP API](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/server.py): `app/server.py`

### Adaptive architecture

- [Task profiler](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_task.py): `app/rl/meta_task.py`
- [State encoder](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/state.py): `app/rl/state.py`
- [Tabular Q-learning](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/q_learning.py): `app/rl/q_learning.py`
- [Architecture actions](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/actions.py): `app/architecture/actions.py`
- [Architecture manager](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/manager.py): `app/architecture/manager.py`
- [Architecture model](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/architecture/models.py): `app/architecture/models.py`

### Agent execution

- [Workflow adapter](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/graph/adaptive_integration.py): `app/graph/adaptive_integration.py`
- [Dynamic graph builder](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/graph/dynamic_builder.py): `app/graph/dynamic_builder.py`
- [Runtime orchestrator](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/runtime/orchestrator.py): `app/runtime/orchestrator.py`
- [Planner](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/planner.py): `app/agents/planner.py`
- [Agent registry](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/registry.py): `app/agents/registry.py`
- [Specialist agents](https://github.com/naveen457/rl-based-adaptive-mas/tree/main/app/agents): `app/agents`
- [LLM executor](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/runtime/llm_execution.py): `app/runtime/llm_execution.py`
- [Tool executor](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/tool_executor.py): `app/agents/tool_executor.py`
- [External tools](https://github.com/naveen457/rl-based-adaptive-mas/tree/main/app/tools): `app/tools`
- [Finalizer](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/agents/finalizer.py): `app/agents/finalizer.py`

### State and evaluation

- [Thread memory](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/memory/store.py): `app/memory/store.py`
- [MongoDB](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/memory/mongo_client.py): `app/memory/mongo_client.py`
- [Task evaluation](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/evaluation/evaluator.py): `app/evaluation/evaluator.py`
- [Reward calculation](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/evaluation/reward.py): `app/evaluation/reward.py`

### Offline policy research

- [Neural meta-policy](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_neural_trainer.py): `app/rl/meta_neural_trainer.py`
- [Meta-policy evaluation](https://github.com/naveen457/rl-based-adaptive-mas/blob/main/app/rl/meta_evaluation.py): `app/rl/meta_evaluation.py`

### Other components

- **User**

## Connections

- User → CLI: submits task
- User → HTTP API: submits task
- CLI → Task profiler: profiles task (evidence: `app/main.py`)
- HTTP API → Task profiler: profiles task (evidence: `app/server.py`)
- Task profiler → State encoder: provides context (evidence: `app/rl/state.py`)
- State encoder → Tabular Q-learning: encodes state (evidence: `app/rl/q_learning.py`)
- Tabular Q-learning → Architecture actions: selects mutation (evidence: `app/rl/q_learning.py`)
- Architecture actions → Architecture manager: describes mutation (evidence: `app/architecture/manager.py`)
- Architecture manager → Architecture model: validates architecture (evidence: `app/architecture/manager.py`)
- Architecture manager → Workflow adapter: supplies architecture (evidence: `app/graph/adaptive_integration.py`)
- Workflow adapter → Dynamic graph builder: configures workflow (evidence: `app/graph/adaptive_integration.py`)
- Runtime orchestrator → Planner: runs planning (evidence: `app/runtime/orchestrator.py`)
- Runtime orchestrator → Workflow adapter: adapts architecture (evidence: `app/runtime/orchestrator.py`)
- Runtime orchestrator → Dynamic graph builder: invokes graph (evidence: `app/runtime/orchestrator.py`)
- Runtime orchestrator → LLM executor: executes agents (evidence: `app/runtime/orchestrator.py`)
- Planner → Agent registry: reads capabilities (evidence: `app/agents/planner.py`)
- LLM executor → Specialist agents: runs specialists (evidence: `app/runtime/llm_execution.py`)
- LLM executor → Tool executor: runs tool calls (evidence: `app/runtime/llm_execution.py`)
- Tool executor → External tools: dispatches tools
- LLM executor → Finalizer: finalizes response (evidence: `app/runtime/llm_execution.py`)
- Runtime orchestrator → Thread memory: stores messages (evidence: `app/runtime/orchestrator.py`)
- Thread memory → MongoDB: uses connection (evidence: `app/memory/store.py`)
- Task evaluation → Architecture model: evaluates structure (evidence: `app/evaluation/evaluator.py`)
- Reward calculation → Task evaluation: scores performance (evidence: `app/evaluation/reward.py`)
- Neural meta-policy → Meta-policy evaluation: evaluated by
