# noahshinn/reflexion architecture

> Architecture diagram of the GitHub repository noahshinn/reflexion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noahshinn/reflexion
- Repository: https://github.com/noahshinn/reflexion

## Overview

##### Project Type and Purpose
- This is a research‐oriented, open-source toolkit for running “reflexion” experiments on multiple decision-making and reasoning tasks (AlfWorld, HotPotQA, programming benchmarks, Webshop).
- It provides configurable pipelines that instantiate agents, environments/datasets, prompts, LLM interfaces, self-reflection loops, and logging for empirical evaluation of verbal reinforcement learning strategies.

##### High-Level Architectural Overview
The system consists of:
A. Experiment Domains (top-level subfolders)
- alfworld_runs
- hotpotqa_runs
- programming_runs
- webshop_runs
Each domain is a concrete instantiation of the Reflexion framework for a particular task.

B. Core Framework Components (reused across domains)
1. Orchestrator
– main.py (or Jupyter notebook)
– run_*.sh scripts
– configuration (YAML, command-line args)
2. Agent Module
– Defines agent classes and strategies (ReAct, CoT, simple, reflexion)
– agents.py, react.py, fewshots.py, prompts.json
3. Environment / Data Module
– wraps task environments or loads datasets
– environment.py, data loaders, mocks
4. LLM Interface
– llm.py
– wrappers over OpenAI API (or other LLM backends)
5. Prompt & Reflection Manager
– Prompt templates (JSON, TXT)
– generate_reflections.py, utils.py
– Implements self-reflection context augmentation
6. Logging & Storage
– root/<run_name> directories containing trial logs (JSON, .joblib)
– utils for saving history, results, metrics

C. External Services & Tools
- OpenAI API (or any LLM endpoint)
- Local environment simulators (AlfWorld Gym)
- Jupyter for notebooks

##### Relationships and Data Flows
- Orchestrator → (reads) Configuration → spawns → Agent & Environment
- Agent → (sends) prompt & context → LLM Interface → (receives) reasoning/output
- Agent → (executes) in Environment → (returns) reward/state
- Agent → (invokes) Reflection Manager → (updates) prompt/context for next trial
- All modules → (emit) logs → Logging & Storage

##### Architectural Patterns & Design Principles
- Pipeline pattern: sequential stages (orchestration → agent → LLM → environment → reflection → logging)
- Modular & pluggable components: swap in new agent types, environments, or reflexion strategies
- Separation of concerns: distinct modules for data, logic, I/O, reflection
- Config-driven design: experiments parameterized by YAML and shell scripts

##### Technologies and Frameworks
- Python 3.x as core language
- YAML for configuration
- JSON/.joblib for logs & model checkpoints
- Jupyter Notebooks for interactive querying and visualization
- Shell scripts for pipeline execution
- OpenAI API as LLM backend
- AlfWorld Gym for environment simulation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level framework
    RF["Reflexion Framework"]:::framework

    %% Experiment Domains
    subgraph "Experiment Domains" 
        Alf["AlfWorld"]:::domain
        Hot["HotPotQA"]:::domain
        Prog["Programming"]:::domain
        Web["Webshop"]:::domain
    end

    %% Core Components
    subgraph "Core Components"
        Orch["Orchestrator"]:::core
        Agent["Agent Module"]:::core
        EnvData["Environment / Data Module"]:::core
        Prompt["Prompt & Reflection Manager"]:::core
        LLM["LLM Interface"]:::core
        Storage["Logging & Storage"]:::storage
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    Jupyter["Jupyter Notebooks"]:::external
    AlfGym["AlfWorld Gym"]:::external

    %% Connections: Domains to Core
    Alf -->|uses| Orch
    Alf -->|uses| Agent
    Alf -->|uses| EnvData
    Alf -->|uses| Prompt
    Alf -->|uses| LLM
    Alf -->|uses| Storage

    Hot -->|uses| Orch
    Hot -->|uses| Agent
    Hot -->|uses| EnvData
    Hot -->|uses| Prompt
    Hot -->|uses| LLM
    Hot -->|uses| Storage

    Prog -->|uses| Orch
    Prog -->|uses| Agent
    Prog -->|uses| EnvData
    Prog -->|uses| Prompt
    Prog -->|uses| LLM
    Prog -->|uses| Storage

    Web -->|uses| Orch
    Web -->|uses| Agent
    Web -->|uses| EnvData
    Web -->|uses| Prompt
    Web -->|uses| LLM
    Web -->|uses| Storage

    %% Data Flows and Dependencies
    Orch -->|reads configuration\nspawns| Agent
    Orch -->|reads configuration\nspawns| EnvData
    Agent -->|"prompt + context"| LLM
    LLM -->|"LLM response"| Agent
    Agent -->|"executes"| EnvData
    EnvData -->|"reward/state"| Agent
    Agent -->|"invokes"| Prompt
    Prompt -->|"augmented context"| Agent
    Orch -->|emits logs| Storage
    Agent -->|emits logs| Storage
    Prompt -->|emits logs| Storage

    %% External Service Calls
    LLM -->|calls| OpenAI
    EnvData -->|simulates| AlfGym
    Orch -->|runs notebooks| Jupyter

    %% Layout Adjustments
    classDef framework fill:#ccccff,stroke:#6666ff,color:#000;
    classDef domain fill:#ccffcc,stroke:#33aa33,color:#000;
    classDef core fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef external fill:#fff2cc,stroke:#cc9900,color:#000;
    classDef storage fill:#ffe5cc,stroke:#ff9933,color:#000;

    %% Click Events for component mapping
    click Alf "https://github.com/noahshinn/reflexion/tree/main/alfworld_runs/"
    click Hot "https://github.com/noahshinn/reflexion/tree/main/hotpotqa_runs/"
    click Prog "https://github.com/noahshinn/reflexion/tree/main/programming_runs/"
    click Web "https://github.com/noahshinn/reflexion/tree/main/webshop_runs/"
    click Orch "https://github.com/noahshinn/reflexion/blob/main/alfworld_runs/main.py"
    click Agent "https://github.com/noahshinn/reflexion/blob/main/hotpotqa_runs/agents.py"
    click EnvData "https://github.com/noahshinn/reflexion/blob/main/hotpotqa_runs/environment.py"
    click LLM "https://github.com/noahshinn/reflexion/blob/main/hotpotqa_runs/llm.py"
    click Prompt "https://github.com/noahshinn/reflexion/blob/main/alfworld_runs/generate_reflections.py"
    click Storage "https://github.com/noahshinn/reflexion/tree/main/alfworld_runs/root/"
```
