# desmondchoy/mtech-policy-recsys architecture

> Architecture diagram of the GitHub repository desmondchoy/mtech-policy-recsys, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/desmondchoy/mtech-policy-recsys
- Repository: https://github.com/desmondchoy/mtech-policy-recsys

## Overview

##### Main Components
- Data Inputs:
- Policy Documents: “data/policies/raw/” (PDFs) and their processed JSONs in “data/policies/processed/”.
- Transcripts: Raw transcripts in “data/transcripts/raw/” (synthetic and real) and processed transcripts in “data/transcripts/processed/”.
- Coverage Requirements: Defined in “data/coverage_requirements/coverage_requirements.py”.
- Data Generation & Preparation:
- Personalities and Transcript Generation Scripts: “scripts/data_generation/generate_personalities.py” and “scripts/data_generation/generate_transcripts.py” along with corresponding notebooks.
- Policy Extraction: “scripts/extract_policy_tier.py” which uses Google Gemini API.
- Transcript Evaluation and Processing:
- Evaluation: “scripts/evaluation/eval_transcript_main.py” along with evaluators, processors, and the related utilities.
- Transcript Processing: “src/utils/transcript_processing.py”, which regenerates structured (parsed) JSON transcripts.
- Multi-Agent Orchestration (Core Agents):
- Agents in “src/agents/”: These include the analyzer, extractor, voting agent, and cs_agent. The extractor agent (especially in “src/agents/extractor.py”) extracts requirements from transcripts.
- Prompts and LLM Service: “src/prompts/” and “src/models/llm_service.py” indicating the connection to external LLMs (Google Gemini and OpenAI via CrewAI).
- Report/Comparison Generation:
- “scripts/generate_policy_comparison.py” uses extracted requirements and processed policy JSONs to produce Markdown reports which reside in “results/”.
- Web Interface (for user interaction):
- Located in “src/web/app.py”.

##### Relationships and Interactions
- Raw Policy PDFs flow into the Policy Extraction component (via extract_policy_tier.py) to generate Structured Policy JSON.
- Raw Transcripts and coverage requirements, plus generated personalities, feed into the Transcript Generation script to produce raw transcript files.
- Raw transcripts flow into an Evaluation component (eval_transcript_main.py); evaluation results determine pass/fail decisions.
- Transcripts that pass evaluation are further processed/parsed via the transcript_processing.py script to create standardized JSON transcripts.
- Requirement Extraction:
- Parsed transcripts are then fed to the Extractor Agent (src/agents/extractor.py) that leverages the LLM service (with associated prompts) to extract customer requirements in a structured JSON format saved to “data/extracted_customer_requirements/”.
- Policy Comparison and Reporting:
- The output from the requirement extraction along with the processed policy data is provided as input to the Policy Comparison Report Generation Script. This step utilizes the LLM (via LLM service) to generate comparison reports in Markdown.
- (Future) Analyzer Agent:
- Once all inputs are available (policy, requirements, comparison reports), a designated analyzer agent is expected to generate personalized policy recommendations.
- Finally, the Web UI:
- This component (src/web/app.py) would offer an interactive interface for customers to query or review recommendations and reports.

##### Architectural Patterns and Design Principles
- Modularization & Separation of Concerns: Notice clear separation between data ingestion/generation, processing, multi-agent orchestration, and reporting.
- Use of External APIs: Emphasize the integration with external LLM APIs (Google Gemini and OpenAI) which power key decision processes in the agents.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Collection & Preparation
    subgraph "Data Collection & Preparation"
        DP["Policy PDFs"]:::data
        DQ["Processed Policy JSONs"]:::data
        DT["Raw Transcripts"]:::data
        CR["Coverage Requirements"]:::data
        PG["Personalities Generation"]:::data
        TG["Transcript Generation"]:::process
        PE["Policy Extraction"]:::process
    end

    %% Transcript Processing
    subgraph "Transcript Processing"
        TE["Transcript Evaluation"]:::process
        TP["Transcript Processing"]:::process
    end

    %% Multi-Agent Orchestration
    subgraph "Multi-Agent Orchestration"
        EA["Extractor Agent"]:::agent
        VA["Voting Agent"]:::agent
        CSA["CS Agent"]:::agent
        RA["Recommender Agent"]:::agent
        AA["Analyzer Agent (Future)"]:::agent
        LLM["LLM Service"]:::external
        PM["Prompts"]:::external
    end

    %% Reporting
    subgraph "Reporting"
        RG["Report Generation"]:::report
        GR["Generated Reports"]:::report
    end

    %% Web Interface
    subgraph "Web Interface"
        WA["Web App"]:::report
    end

    %% Connections within Data Collection & Preparation
    DP -->|"to_extract"| PE
    PE -->|"outputs"| DQ
    DT -->|"feeds"| TG
    CR -->|"and"| TG
    PG -->|"and"| TG
    TG -->|"produces"| TE

    %% Transcript Processing Flow
    TE -->|"evaluated_to"| TP

    %% Extraction and Agent Orchestration
    TP -->|"parsed_to"| EA
    EA -->|"extracts_req_to"| RG

    %% Reporting Flow
    DQ -->|"provides_policy_to"| RG
    RG -->|"generates"| GR

    %% Future Analyzer Integration
    GR -->|"feeds_analyzer"| AA
    DQ -->|"feeds_analyzer"| AA
    EA -->|"feeds_analyzer"| AA

    %% Web Interface Connections
    GR -->|"delivers_to"| WA
    AA -->|"delivers_recos_to"| WA

    %% Multi-Agent external integrations
    EA -.->|"uses"| LLM
    VA -.->|"uses"| LLM
    RA -.->|"uses"| LLM
    EA -.->|"uses"| PM
    VA -.->|"uses"| PM
    RA -.->|"uses"| PM

    %% Click Events
    click DP "https://github.com/desmondchoy/mtech-policy-recsys/tree/main/data/policies/raw/"
    click DQ "https://github.com/desmondchoy/mtech-policy-recsys/tree/main/data/policies/processed/"
    click DT "https://github.com/desmondchoy/mtech-policy-recsys/tree/main/data/transcripts/raw/"
    click CR "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/data/coverage_requirements/coverage_requirements.py"
    click PG "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/scripts/data_generation/generate_personalities.py"
    click TG "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/scripts/data_generation/generate_transcripts.py"
    click PE "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/scripts/extract_policy_tier.py"
    click TE "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/scripts/evaluation/eval_transcript_main.py"
    click TP "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/utils/transcript_processing.py"
    click EA "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/agents/extractor.py"
    click VA "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/agents/voting.py"
    click CSA "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/agents/cs_agent.py"
    click RA "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/agents/recommender.py"
    click AA "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/agents/analyzer.py"
    click LLM "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/models/llm_service.py"
    click PM "https://github.com/desmondchoy/mtech-policy-recsys/tree/main/src/prompts/"
    click RG "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/scripts/generate_policy_comparison.py"
    click GR "https://github.com/desmondchoy/mtech-policy-recsys/tree/main/results/"
    click WA "https://github.com/desmondchoy/mtech-policy-recsys/blob/main/src/web/app.py"

    %% Styles
    classDef data fill:#e3f2fd,stroke:#1976d2,stroke-width:2px;
    classDef process fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef agent fill:#ffcdd2,stroke:#e53935,stroke-width:2px;
    classDef report fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#f0f4c3,stroke:#827717,stroke-width:2px;
```
