metamorphosis

Metamorphosis: AI-Powered Self-Review Processing System

Overview

Metamorphosis is an AI-powered text processing system designed for employee self-review workflows. It leverages LangGraph orchestration, OpenAI's language models, and Model Context Protocol (MCP) integration to provide intelligent text processing capabilities including copy editing, summarization, achievement extraction, and quality evaluation.

Core Features

🔄 Multi-Stage Text Processing Pipeline

• Copy Editing: Grammar, spelling, and style improvements using OpenAI GPT models
• Summarization: Abstractive summaries with configurable length (default 300 words)
• Achievement Extraction: Structured extraction of key accomplishments with impact areas using LangGraph agents
• RAG Enhancement: Achievement contextualization through project document retrieval and augmentation
• Quality Evaluation: Comprehensive writing quality assessment with radar chart visualization using LangGraph agents
• Visualization: Word cloud generation and evaluation radar charts

🤖 AI Agent Orchestration

• LangGraph Workflows: State-based multi-agent processing with self-reviewer agent
• Direct Tool Access: LangGraph agents directly access achievement extraction and evaluation tools (not via MCP)
• RAG Integration: Achievement evaluator with vector database for project document retrieval
• Parallel Processing: Concurrent execution of independent tasks
• Real-time Streaming: Live updates via Server-Sent Events (SSE)
• State Persistence: Thread-based conversation management

🛠️ Hybrid Tool Integration

• MCP Tools: Copy editing, summarization, and word cloud generation via MCP server
• LangGraph Tools: Achievement extraction and evaluation via direct agent tool access
• RAG System: Vector database integration for project document retrieval and achievement contextualization
• Type Safety: Pydantic models for structured outputs
• Error Handling: Comprehensive exception management

Architecture

The system implements a multi-layer architecture:

• Presentation Layer: Streamlit UI and FastAPI REST API
• Orchestration Layer: LangGraph workflows with self-reviewer agent
• Processing Layer: Hybrid approach with MCP tools server and direct LangGraph tool access
• RAG Layer: Vector database and achievement evaluator for project document retrieval
• Model Layer: Centralized model registry managing multiple OpenAI LLMs (GPT-4o-mini/GPT-4o for agents, GPT-4o for MCP tools, GPT-5 for advanced use cases)
• Data Layer: Pydantic models and structured outputs

The Processing Tools

The system provides a hybrid approach to text processing:

MCP Tools (3 tools):

1. copy_edit: Grammar and style improvements while preserving original voice
2. abstractive_summarize: Intelligent summarization with configurable word limits
3. word_cloud: Visual word cloud generation from text content

LangGraph Tools (2 tools):

4. extract_achievements: Structured extraction of key accomplishments with impact categorization
5. evaluate_review_text: Comprehensive quality assessment with scoring metrics

RAG Enhancement:

• Achievement Contextualization: Extracted achievements are enhanced through Retrieval-Augmented Generation (RAG) by accessing relevant project documents to add contextual details and validate impact claims

User Interface

The system provides a Streamlit-based web interface with:

• Real-time text processing with live updates
• Interactive controls for workflow execution
• Debug information and event inspection
• Session state management for conversation persistence

Implementation Status

✅ Completed Features

• LangGraph-based workflow orchestration with self-reviewer agent
• Hybrid tool architecture: MCP server (3 tools) + LangGraph direct tools (2 tools)
• RAG system for achievement contextualization using project documents
• Streamlit UI with real-time streaming capabilities
• FastAPI REST API with SSE support
• Comprehensive Pydantic data models
• OpenAI GPT model integration with centralized registry (GPT-4o-mini/GPT-4o for agents, GPT-4o for MCP tools, GPT-5 for advanced use cases)
• Word cloud and radar chart visualization
• Achievement extraction with impact categorization and RAG enhancement
• Quality evaluation with scoring metrics

✅ Architecture Documentation

• Complete system architecture diagrams
• Component relationship documentation
• API documentation with Swagger/ReDoc
• Comprehensive code documentation

Technical Implementation

The system is built using Python frameworks and design patterns:

Core Technologies:

• LangGraph: Multi-agent workflow orchestration with direct tool access
• FastMCP: Model Context Protocol server implementation (3 tools)
• RAG System: Vector database and retrieval for achievement contextualization
• Streamlit: Interactive web interface
• FastAPI: High-performance REST API
• Pydantic: Type-safe data validation
• OpenAI GPT: Language model integration (GPT-4o-mini/GPT-4o for agents, GPT-4o for MCP tools, GPT-5 for advanced use cases)

Key Design Principles:

• Design-by-Contract: Pre/post-condition validation with icontract
• Low Cognitive Complexity: Functions limited to CC ≤ 10
• Type Safety: Comprehensive type annotations throughout
• Error Handling: Structured exception management
• Modular Architecture: Clean separation of concerns

System Architecture

High-Level Overview

The six layers below and the labeled edges between them capture how a self-review request moves through the system.

graph TB
    UI["User Interface Layer<br/>Streamlit / NiceGUI / AG-UI"]
    ORCH["Orchestration Layer<br/>LangGraph + WorkflowExecutor"]
    PROC["Processing Layer<br/>MCP Tools + LangGraph Tools"]
    RAG["RAG Layer<br/>Project corpus retrieval"]
    MODEL["Model Layer<br/>Centralized LLM registry"]
    DATA["Data Layer<br/>Pydantic models + thread state"]

    UI -->|"HTTP / SSE: submit review text,<br/>stream live progress"| ORCH
    ORCH -->|"Invoke copy-edit, summarize,<br/>word-cloud via MCP;<br/>invoke extract/evaluate directly"| PROC
    PROC -->|"Achievement extraction queries<br/>project docs for context"| RAG
    PROC -->|"Request chat completions<br/>by registered model role"| MODEL
    ORCH -->|"Persist thread state;<br/>validate structured outputs"| DATA
    PROC -->|"Emit typed tool results<br/>(Pydantic schemas)"| DATA

    classDef uiLayer fill:#e1f5fe
    classDef orchestrationLayer fill:#f3e5f5
    classDef processingLayer fill:#e8f5e8
    classDef ragLayer fill:#fff3e0
    classDef modelLayer fill:#fce4ec
    classDef dataLayer fill:#f1f8e9

    class UI uiLayer
    class ORCH orchestrationLayer
    class PROC processingLayer
    class RAG ragLayer
    class MODEL modelLayer
    class DATA dataLayer

User Interface Layer

Clients that accept employee self-review text and display streamed results.

graph LR
    ST[Streamlit UI<br/>Real-time processing]
    NG[NiceGUI UI<br/>Continuous / tabbed modes]
    AG[AG-UI<br/>pnpm frontend]
    API[FastAPI REST API<br/>SSE streaming]

    ST --> API
    NG --> API
    AG --> API

    classDef uiLayer fill:#e1f5fe
    class ST,NG,AG,API uiLayer

Orchestration Layer

Coordinates the self-reviewer agent, workflow steps, and conversation state.

graph TB
    EX[WorkflowExecutor<br/>State management]
    LG[LangGraph Workflow<br/>Self-Reviewer Agent]
    GADK[G-ADK Agent path<br/>agent_service_gadk]

    EX --> LG
    EX --> GADK

    classDef orchestrationLayer fill:#f3e5f5
    class EX,LG,GADK orchestrationLayer

Processing Layer

Hybrid tool surface: three MCP-hosted tools and two LangGraph-native tools.

graph TB
    subgraph MCP["MCP Tools Server (3 tools)"]
        CE[copy_edit]
        AS[abstractive_summarize]
        WC[word_cloud]
    end

    subgraph LGT["LangGraph Tools (2 tools)"]
        EA[extract_achievements]
        EV[evaluate_review_text]
    end

    classDef processingLayer fill:#e8f5e8
    class CE,AS,WC,EA,EV processingLayer

RAG Layer

Contextualizes extracted achievements against the project document corpus.

graph LR
    EA[extract_achievements]
    AE[Achievement Evaluator<br/>Project retrieval]
    VE[Vector Database<br/>EmbeddedVectorDB]
    PD[Project Documents<br/>JSONL corpus]

    EA --> AE
    AE --> VE
    VE --> PD

    classDef ragLayer fill:#fff3e0
    classDef processingLayer fill:#e8f5e8
    class EA processingLayer
    class AE,VE,PD ragLayer

Model Layer

Central registry that maps each consumer to the appropriate OpenAI model.

graph TB
    MR[Model Registry<br/>Centralized LLM management]
    GPT1[GPT-4o-mini / GPT-4o<br/>LangGraph / G-ADK agents]
    GPT2[GPT-4o<br/>MCP tools]
    GPT3[GPT-5<br/>Advanced use cases]

    MR --> GPT1
    MR --> GPT2
    MR --> GPT3

    classDef modelLayer fill:#fce4ec
    class MR,GPT1,GPT2,GPT3 modelLayer

Data Layer

Typed schemas for tool outputs and thread-scoped workflow state.

graph LR
    DM[Pydantic Models<br/>Structured outputs]
    ST[State Storage<br/>Thread-based]

    classDef dataLayer fill:#f1f8e9
    class DM,ST dataLayer

Getting Started

Follow these steps to run the Employee Self-Review Wizard application:

1. Environment Setup

First, update the environment configuration by copying the example file and updating relevant variables:

cp .env.example .env
# Edit .env with your specific configuration values

2. Install Dependencies

Create the virtual environment and install all dependencies:

uv sync

3. Start the MCP Tools Server

Run the MCP tools server to provide the core functionality:

uv run ./src/metamorphosis/mcp/tools_server.py

4. Start the Agent Service

In a separate terminal, run the FastAPI service that hosts the LangGraph agents (or G-ADK agent):

uv run ./src/metamorphosis/agents/agent_service.py
(or)
uv run ./src/metamorphosis/agents/agent_service_gadk.py

5. Launch the User Interface

Finally, start the UI in another terminal:

Streamlit

streamlit run ./src/metamorphosis/ui/streamlit_ui.py

Once all services are running, you can access the application through the Streamlit interface in your web browser.

(OR)

NiceGUI

Continuous UI mode:

uv run ./src/metamorphosis/ui/nicegui/nicegui_continuous_ui.py

Tabbed UI mode:

uv run ./src/metamorphosis/ui/nicegui/nicegui_tab_ui.py

AG-UI

To use AG-UI you need node.js and pnpm. to install this refer: Node.JS pnpm

Linux/macOS:

Note: Steps 3 and 4 do not need to be run separately, as they will be executed automatically by the commands below. If you have already started those steps, please stop them and proceed with the following commands instead. These commands will start the Google ADK agent service (agent_service_gadk). This setup is supported only on macOS and Linux machines.

cd agui
pnpm dev

Windows:

Note: You need WSL to run this

cd agui
pnpm dev

For more info on AG-UI refer here