# sourabhvamdevan/ai-based-task-orchestration-project architecture

> Architecture diagram of the GitHub repository sourabhvamdevan/ai-based-task-orchestration-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sourabhvamdevan/ai-based-task-orchestration-project
- Repository: https://github.com/sourabhvamdevan/ai-based-task-orchestration-project

## Overview

1. This repository is a Python 3.11 AI task-orchestration system centered on “Alfred,” a multi-agent environment that prioritizes personal/wellness tasks over work tasks. The architecture is split into an interactive orchestration layer, a custom RL environment, tool integrations, and training/inference paths.

2. The main runtime entrypoint is `app.py`, which README indicates launches a Gradio-based dashboard for interacting with the orchestrator. `inference.py` is the separate execution path for running a trained policy against the baseline, while the training workflow lives in `training_process/alfred_grpo_colab2.ipynb`.

3. The core control plane is `agents/orchestrator.py`. It acts as the routing layer that classifies incoming tasks by priority tier and dispatches them to specialized sub-agents. This is the key boundary where task intent becomes agent-specific execution.

4. The specialized agent layer is organized by responsibility:
   - `agents/auto_reply_agent.py` for automated responses,
   - `agents/email_agent.py` for Gmail-related actions,
   - `agents/habit_agent.py` for recurring reminders and routines,
   - `agents/knowledge_agent.py` for preference and knowledge-base handling.
   These agents are downstream of the orchestrator and encapsulate domain-specific behavior.

5. External side effects are isolated behind the `tools/` package. `tools/gmail_tool.py`, `tools/calendar_tool.py`, and `tools/reminder_tool.py` wrap integrations for email, scheduling, and reminders. `tools/llm_client.py` appears to be the shared LLM access layer, while `tools/alfred-tool.py` likely exposes a generic MCP-style tool interface used by the agents.

6. Authentication and API access are separated into `auth/alfred_auth.py`, which is the boundary for credentials and authorization against external services. The README also indicates Google Calendar and Gmail credentials are configured via environment variables, so the system depends on authenticated third-party API calls for real actions.

7. The RL environment is implemented under `env/` with `env/action_space.py` and `env/observation.py`. This is where task queues are represented as model observations and the allowed actions are defined for the policy being trained.

8. Reward shaping is isolated in `reward/rubric.py`. This module encodes the project’s priority policy: Tier 1 tasks must outrank Tier 2 tasks, routing must be correct, required parameters must be complete, tool calls must succeed, and non-actionable tasks must not trigger actions. That reward boundary is what turns orchestration quality into a training signal.

9. Synthetic training data is generated in `data/synthetic_todos.py`, which suggests the environment is fed with simulated task episodes rather than only live user data. This supports policy learning and evaluation without needing real inbox/calendar traffic for every episode.

10. The project includes reproducibility and deployment scaffolding: `requirements.txt` for Python dependencies, `Dockerfile` for containerization, `Jenkinsfile` for CI/CD, and `openenv.yaml` for environment configuration. These files define how the system is packaged, tested, and run across environments.

11. The notebook checkpoints and `training_process/` directory show that experimentation and policy optimization are notebook-driven, with GRPO/Unsloth/TRL mentioned in the README. In diagram terms, the training loop is separate from the interactive orchestrator: observations come from the environment, the policy is optimized against the rubric, and the resulting model is later exercised through inference.

12. A good architecture diagram for this repo should therefore show four main layers: input/UI and training entrypoints; orchestration and agent routing; tool/auth integrations to external services; and the RL environment/reward loop that shapes behavior. The critical data flow is task queue → observation → orchestrator/agent selection → tool call or abstention → reward feedback → policy update.

Main entry points: [`agents/orchestrator.py`](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/orchestrator.py) (Orchestrator), [`tools/alfred-tool.py`](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/alfred-tool.py) (Alfred Tool), [`agents/habit_agent.py`](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/habit_agent.py) (Habit Agent), [`tools/gmail_tool.py`](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/gmail_tool.py) (Gmail Tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entrypoints"]
  node_app_py["App<br/>dashboard entrypoint<br/>[app.py]"]
  node_inference_py["Inference<br/>policy runner<br/>[inference.py]"]
  node_training_nb["Training Notebook<br/>GRPO training"]
end

subgraph group_grp_orchestration["Orchestration"]
  node_orchestrator_py["Orchestrator<br/>routing core<br/>[orchestrator.py]"]
  node_auto_reply_agent_py["Auto Reply<br/>response agent"]
  node_email_agent_py["Email Agent<br/>gmail agent<br/>[email_agent.py]"]
  node_habit_agent_py["Habit Agent<br/>routine agent<br/>[habit_agent.py]"]
  node_knowledge_agent_py["Knowledge Agent<br/>preference agent<br/>[knowledge_agent.py]"]
end

subgraph group_grp_integrations["Integrations"]
  node_llm_client_py["LLM Client<br/>model access<br/>[llm_client.py]"]
  node_gmail_tool_py["Gmail Tool<br/>email integration<br/>[gmail_tool.py]"]
  node_calendar_tool_py["Calendar Tool<br/>schedule integration<br/>[calendar_tool.py]"]
  node_reminder_tool_py["Reminder Tool<br/>reminder integration<br/>[reminder_tool.py]"]
  node_alfred_tool_py["Alfred Tool<br/>tool interface<br/>[alfred-tool.py]"]
  node_auth_py["Auth<br/>credentials boundary<br/>[alfred_auth.py]"]
end

subgraph group_grp_rl["RL Loop"]
  node_action_space_py["Action Space<br/>rl actions<br/>[action_space.py]"]
  node_observation_py["Observation<br/>[observation.py]"]
  node_rubric_py["Rubric<br/>reward shaping<br/>[rubric.py]"]
  node_synthetic_todos_py["Synthetic Todos<br/>training data<br/>[synthetic_todos.py]"]
end

node_app_py -->|"submit tasks"| node_orchestrator_py
node_inference_py -->|"run policy"| node_orchestrator_py
node_training_nb -->|"generate episodes"| node_synthetic_todos_py
node_training_nb -->|"build observations"| node_observation_py
node_synthetic_todos_py -->|"seed tasks"| node_observation_py
node_observation_py -->|"state input"| node_orchestrator_py
node_orchestrator_py -->|"route tier"| node_auto_reply_agent_py
node_orchestrator_py -->|"route tier"| node_email_agent_py
node_orchestrator_py -->|"route tier"| node_habit_agent_py
node_orchestrator_py -->|"route tier"| node_knowledge_agent_py
node_auto_reply_agent_py -->|"compose"| node_llm_client_py
node_email_agent_py -->|"send/read"| node_gmail_tool_py
node_habit_agent_py -->|"schedule"| node_reminder_tool_py
node_habit_agent_py -->|"plan"| node_calendar_tool_py
node_knowledge_agent_py -->|"update memory"| node_llm_client_py
node_gmail_tool_py -->|"authorize"| node_auth_py
node_calendar_tool_py -->|"authorize"| node_auth_py
node_reminder_tool_py -->|"authorize"| node_auth_py
node_alfred_tool_py -->|"wraps"| node_gmail_tool_py
node_alfred_tool_py -->|"wraps"| node_calendar_tool_py
node_alfred_tool_py -->|"wraps"| node_reminder_tool_py
node_orchestrator_py -->|"choose action"| node_action_space_py
node_orchestrator_py -->|"trained against"| node_rubric_py
node_rubric_py -->|"evaluate"| node_action_space_py

click node_app_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/app.py"
click node_inference_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/inference.py"
click node_training_nb "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/training_process/alfred_grpo_colab2.ipynb"
click node_orchestrator_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/orchestrator.py"
click node_auto_reply_agent_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/auto_reply_agent.py"
click node_email_agent_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/email_agent.py"
click node_habit_agent_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/habit_agent.py"
click node_knowledge_agent_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/knowledge_agent.py"
click node_llm_client_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/llm_client.py"
click node_gmail_tool_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/gmail_tool.py"
click node_calendar_tool_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/calendar_tool.py"
click node_reminder_tool_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/reminder_tool.py"
click node_alfred_tool_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/alfred-tool.py"
click node_auth_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/auth/alfred_auth.py"
click node_action_space_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/env/action_space.py"
click node_observation_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/env/observation.py"
click node_rubric_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/reward/rubric.py"
click node_synthetic_todos_py "https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/data/synthetic_todos.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_app_py,node_inference_py,node_training_nb toneBlue
class node_orchestrator_py,node_auto_reply_agent_py,node_email_agent_py,node_habit_agent_py,node_knowledge_agent_py toneAmber
class node_llm_client_py,node_gmail_tool_py,node_calendar_tool_py,node_reminder_tool_py,node_alfred_tool_py,node_auth_py toneMint
class node_action_space_py,node_observation_py,node_rubric_py,node_synthetic_todos_py toneRose
```

## Components

### Entrypoints

User-facing runtime and training entry paths

- [App](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/app.py): dashboard entrypoint · Gradio-based interactive dashboard for task orchestration · `app.py`
- [Inference](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/inference.py): policy runner · Runs a trained policy against the baseline or environment · `inference.py`
- [Training Notebook](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/training_process/alfred_grpo_colab2.ipynb): GRPO training · Notebook-driven policy optimization workflow · `training_process/alfred_grpo_colab2.ipynb`

### Orchestration

Task routing and specialized agent execution

- [Orchestrator](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/orchestrator.py): routing core · Classifies tasks by priority tier and dispatches them to agents · `agents/orchestrator.py`
- [Auto Reply](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/auto_reply_agent.py): response agent · Handles automated response generation and reply tasks · `agents/auto_reply_agent.py`
- [Email Agent](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/email_agent.py): gmail agent · Performs Gmail-related task execution · `agents/email_agent.py`
- [Habit Agent](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/habit_agent.py): routine agent · Manages reminders, recurring routines, and habit tasks · `agents/habit_agent.py`
- [Knowledge Agent](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/agents/knowledge_agent.py): preference agent · Maintains preference and knowledge-base state · `agents/knowledge_agent.py`

### Integrations

Tooling and external service boundaries

- [LLM Client](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/llm_client.py): model access · Shared access layer for LLM calls · `tools/llm_client.py`
- [Gmail Tool](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/gmail_tool.py): email integration · Wraps Gmail API operations · `tools/gmail_tool.py`
- [Calendar Tool](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/calendar_tool.py): schedule integration · Wraps calendar operations and scheduling actions · `tools/calendar_tool.py`
- [Reminder Tool](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/reminder_tool.py): reminder integration · Wraps reminder and recurring notification actions · `tools/reminder_tool.py`
- [Alfred Tool](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/tools/alfred-tool.py): tool interface · Generic MCP-style tool interface used by agents · `tools/alfred-tool.py`
- [Auth](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/auth/alfred_auth.py): credentials boundary · Handles authorization and external service credentials · `auth/alfred_auth.py`

### RL Loop

Environment, reward, and synthetic training data

- [Action Space](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/env/action_space.py): rl actions · Defines allowed actions for the policy · `env/action_space.py`
- [Observation](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/env/observation.py): rl observations · Represents task queues as environment observations · `env/observation.py`
- [Rubric](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/reward/rubric.py): reward shaping · Encodes task priority and execution quality into reward signals · `reward/rubric.py`
- [Synthetic Todos](https://github.com/sourabhvamdevan/ai-based-task-orchestration-project/blob/master/data/synthetic_todos.py): training data · Generates synthetic task episodes for training and evaluation · `data/synthetic_todos.py`

## Connections

- App → Orchestrator: submit tasks · Interactive dashboard sends tasks into the routing core
- Inference → Orchestrator: run policy · Inference path exercises orchestration decisions
- Training Notebook → Synthetic Todos: generate episodes · Notebook uses synthetic tasks for policy optimization
- Training Notebook → Observation: build observations · Training consumes environment observations
- Synthetic Todos → Observation: seed tasks · Synthetic task episodes populate observations
- Observation → Orchestrator: state input · Observed queue state is routed through the orchestrator
- Orchestrator → Auto Reply: route tier · Dispatches tasks to the automated reply agent
- Orchestrator → Email Agent: route tier · Dispatches email tasks to the email agent
- Orchestrator → Habit Agent: route tier · Dispatches recurring routine tasks to the habit agent
- Orchestrator → Knowledge Agent: route tier · Dispatches preference and memory tasks to the knowledge agent
- Auto Reply → LLM Client: compose · Uses model access for response generation
- Email Agent → Gmail Tool: send/read · Calls Gmail operations through the tool wrapper
- Habit Agent → Reminder Tool: schedule · Uses reminder actions for routines and follow-ups
- Habit Agent → Calendar Tool: plan · Uses calendar actions for recurring scheduling
- Knowledge Agent → LLM Client: update memory · Uses the LLM layer to interpret and store preference knowledge
- Gmail Tool → Auth: authorize · Requires authenticated access to Gmail services
- Calendar Tool → Auth: authorize · Requires authenticated access to calendar services
- Reminder Tool → Auth: authorize · Requires credentialed access for reminder delivery
- Alfred Tool → Gmail Tool: wraps · Generic tool interface can expose Gmail actions
- Alfred Tool → Calendar Tool: wraps · Generic tool interface can expose calendar actions
- Alfred Tool → Reminder Tool: wraps · Generic tool interface can expose reminder actions
- Orchestrator → Action Space: choose action · Routing decisions are constrained by the available action set
- Orchestrator → Rubric: trained against · Orchestration quality is scored by the reward rubric
- Rubric → Action Space: evaluate · Reward checks whether chosen actions are valid and complete