# varsha-1428/multi-agent-system architecture

> Architecture diagram of the GitHub repository varsha-1428/multi-agent-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/varsha-1428/multi-agent-system
- Repository: https://github.com/varsha-1428/multi-agent-system

## Overview

This repository generates three candidate images from a user prompt, scores prompt alignment and cross-image consensus, and iteratively improves only failed candidates using vision feedback. LangGraph coordinates generation, evaluation, pass/fail routing, and regeneration; evaluation combines CLIP-based measures into a thresholded result. The README documents weighted scoring and the feedback loop. The scorer implementation was not excerpted, so its role and connection are supported by the README and source index rather than inspected source.

Main entry points: [`graph/image_generation_graph.py`](https://github.com/varsha-1428/multi-agent-system/blob/main/graph/image_generation_graph.py) (Workflow Graph), [`agents/agent1.py`](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent1.py) (Agent 1), [`agents/agent2.py`](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent2.py) (Agent 2), [`agents/agent3.py`](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent3.py) (Agent 3)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow Orchestration"]
  node_entry["Application Entry<br/>[main.py]"]
  node_workflow["Workflow Graph"]
  node_state["Workflow State<br/>[state.py]"]
end

subgraph group_generation["Image Generation"]
  node_agent1["Agent 1<br/>[agent1.py]"]
  node_agent2["Agent 2<br/>[agent2.py]"]
  node_agent3["Agent 3<br/>[agent3.py]"]
  node_baseagent["Agent Interface<br/>[base_agent.py]"]
  node_images["Generated Images"]
end

subgraph group_evaluation["Image Evaluation"]
  node_matcher["Description Matcher"]
  node_validator["Consensus Validator<br/>[consensus.py]"]
  node_evaluation["Evaluation Coordinator<br/>[evaluate.py]"]
  node_combiner["Score Combiner<br/>[scorer.py]"]
end

subgraph group_refinement["Feedback Refinement"]
  node_feedback["Vision Feedback<br/>[feedback.py]"]
end

node_user(("User Prompt"))
node_huggingface["Hugging Face Inference"]
node_groq["Groq Vision Model"]

node_user -->|"provides prompt"| node_entry
node_entry -->|"invokes graph"| node_workflow
node_workflow -->|"uses schema"| node_state
node_workflow -->|"generates with"| node_agent1
node_workflow -->|"generates with"| node_agent2
node_workflow -->|"generates with"| node_agent3
node_agent1 -->|"implements"| node_baseagent
node_agent2 -->|"implements"| node_baseagent
node_agent3 -->|"implements"| node_baseagent
node_agent1 -->|"requests image"| node_huggingface
node_agent2 -->|"requests image"| node_huggingface
node_agent3 -->|"requests image"| node_huggingface
node_agent1 -->|"saves image"| node_images
node_agent2 -->|"saves image"| node_images
node_agent3 -->|"saves image"| node_images
node_workflow -->|"evaluates images"| node_evaluation
node_evaluation -->|"scores alignment"| node_matcher
node_evaluation -->|"scores consensus"| node_validator
node_evaluation -->|"combines scores"| node_combiner
node_workflow -->|"requests feedback"| node_feedback
node_feedback -->|"analyzes image"| node_groq
node_workflow -->|"regenerates failed"| node_agent1
node_workflow -->|"regenerates failed"| node_agent2
node_workflow -->|"regenerates failed"| node_agent3

click node_entry "https://github.com/varsha-1428/multi-agent-system/blob/main/main.py"
click node_workflow "https://github.com/varsha-1428/multi-agent-system/blob/main/graph/image_generation_graph.py"
click node_state "https://github.com/varsha-1428/multi-agent-system/blob/main/workflow/state.py"
click node_agent1 "https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent1.py"
click node_agent2 "https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent2.py"
click node_agent3 "https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent3.py"
click node_baseagent "https://github.com/varsha-1428/multi-agent-system/blob/main/agents/base_agent.py"
click node_matcher "https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/description_match.py"
click node_validator "https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/consensus.py"
click node_evaluation "https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/evaluate.py"
click node_combiner "https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/scorer.py"
click node_feedback "https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/feedback.py"
click node_images "https://github.com/varsha-1428/multi-agent-system/tree/main/images"

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_entry,node_workflow,node_state,node_user toneBlue
class node_agent1,node_agent2,node_agent3,node_baseagent,node_images toneAmber
class node_matcher,node_validator,node_evaluation,node_combiner toneMint
class node_feedback toneRose
class node_huggingface,node_groq toneIndigo
```

## Components

### Workflow Orchestration

- [Application Entry](https://github.com/varsha-1428/multi-agent-system/blob/main/main.py): `main.py`
- [Workflow Graph](https://github.com/varsha-1428/multi-agent-system/blob/main/graph/image_generation_graph.py): `graph/image_generation_graph.py`
- [Workflow State](https://github.com/varsha-1428/multi-agent-system/blob/main/workflow/state.py): `workflow/state.py`

### Image Generation

- [Agent 1](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent1.py): `agents/agent1.py`
- [Agent 2](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent2.py): `agents/agent2.py`
- [Agent 3](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/agent3.py): `agents/agent3.py`
- [Agent Interface](https://github.com/varsha-1428/multi-agent-system/blob/main/agents/base_agent.py): `agents/base_agent.py`
- [Generated Images](https://github.com/varsha-1428/multi-agent-system/tree/main/images): `images`

### Image Evaluation

- [Description Matcher](https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/description_match.py): `evaluator/description_match.py`
- [Consensus Validator](https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/consensus.py): `evaluator/consensus.py`
- [Evaluation Coordinator](https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/evaluate.py): `evaluator/evaluate.py`
- [Score Combiner](https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/scorer.py): `evaluator/scorer.py`

### Feedback Refinement

- [Vision Feedback](https://github.com/varsha-1428/multi-agent-system/blob/main/evaluator/feedback.py): `evaluator/feedback.py`

### Other components

- **User Prompt**
- **Hugging Face Inference**
- **Groq Vision Model**

## Connections

- User Prompt → Application Entry: provides prompt (evidence: `main.py`)
- Application Entry → Workflow Graph: invokes graph (evidence: `main.py`)
- Workflow Graph → Workflow State: uses schema (evidence: `graph/image_generation_graph.py`)
- Workflow Graph → Agent 1: generates with (evidence: `graph/image_generation_graph.py`)
- Workflow Graph → Agent 2: generates with (evidence: `graph/image_generation_graph.py`)
- Workflow Graph → Agent 3: generates with (evidence: `graph/image_generation_graph.py`)
- Agent 1 → Agent Interface: implements (evidence: `agents/agent1.py`)
- Agent 2 → Agent Interface: implements (evidence: `agents/agent2.py`)
- Agent 3 → Agent Interface: implements (evidence: `agents/agent3.py`)
- Agent 1 → Hugging Face Inference: requests image (evidence: `agents/agent1.py`)
- Agent 2 → Hugging Face Inference: requests image (evidence: `agents/agent2.py`)
- Agent 3 → Hugging Face Inference: requests image (evidence: `agents/agent3.py`)
- Agent 1 → Generated Images: saves image (evidence: `agents/agent1.py`)
- Agent 2 → Generated Images: saves image (evidence: `agents/agent2.py`)
- Agent 3 → Generated Images: saves image (evidence: `agents/agent3.py`)
- Workflow Graph → Evaluation Coordinator: evaluates images (evidence: `graph/image_generation_graph.py`)
- Evaluation Coordinator → Description Matcher: scores alignment (evidence: `evaluator/evaluate.py`)
- Evaluation Coordinator → Consensus Validator: scores consensus (evidence: `evaluator/evaluate.py`)
- Evaluation Coordinator → Score Combiner: combines scores (evidence: `evaluator/evaluate.py`)
- Workflow Graph → Vision Feedback: requests feedback (evidence: `graph/image_generation_graph.py`)
- Vision Feedback → Groq Vision Model: analyzes image (evidence: `evaluator/feedback.py`)
- Workflow Graph → Agent 1: regenerates failed (evidence: `graph/image_generation_graph.py`)
- Workflow Graph → Agent 2: regenerates failed (evidence: `graph/image_generation_graph.py`)
- Workflow Graph → Agent 3: regenerates failed (evidence: `graph/image_generation_graph.py`)
