# vinod1204/novelty_evaluator architecture

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

- Interactive diagram: https://gitdiagram.com/vinod1204/novelty_evaluator
- Repository: https://github.com/vinod1204/novelty_evaluator

## Overview

Novelty Evaluator accepts categorized submissions through a web UI, API, or CLI, then checks relevance and category-matched novelty against a learned baseline. The evaluator can update that baseline for highly novel submissions; the API schedules persistence and provides batch ranking and separate reasoning generation. The README also describes an LLM sentiment override and critique-and-revise reasoning loop. The sampled code supports the UI, API, evaluator, models, and baseline flow; some advertised evaluator internals and batch details are documented but not fully sampled.

Main entry points: [`src/evaluator.py`](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py) (Novelty Engine), [`src/api.py`](https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py) (HTTP API), [`frontend/src/App.tsx`](https://github.com/vinod1204/novelty_evaluator/blob/main/frontend/src/App.tsx) (Web Form), [`src/models.py`](https://github.com/vinod1204/novelty_evaluator/blob/main/src/models.py) (Submission Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Submission Interfaces"]
  node_web["Web Form<br/>[App.tsx]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_service["Evaluation Service"]
  node_api["HTTP API<br/>[api.py]"]
  node_batch["Batch Ranking<br/>[api.py]"]
  node_reasoning_api["Reasoning Route<br/>[api.py]"]
  node_submission["Submission Model<br/>[models.py]"]
  node_engine["Novelty Engine<br/>[evaluator.py]"]
  node_relevance["Relevance Gate<br/>[evaluator.py]"]
  node_category["Category Matching<br/>[evaluator.py]"]
  node_novelty["Novelty Scoring<br/>[evaluator.py]"]
end

subgraph group_learning["Baseline Learning"]
  node_store[("Baseline Data")]
  node_embeddings[("Embedding Cache")]
  node_adaptive["Adaptive Learning<br/>[evaluator.py]"]
  node_persistence["Baseline Persistence<br/>[evaluator.py]"]
end

subgraph group_ai["AI Analysis"]
  node_sentiment["Stance Override<br/>[evaluator.py]"]
  node_reasoning["Reasoning Review Loop<br/>[evaluator.py]"]
end

node_user(("Submitter"))
node_gemini{{"Google GenAI"}}
node_batch_client(("Batch Client"))

node_user -->|"enters submission"| node_web
node_web -->|"posts evaluation"| node_api
node_web -->|"requests reasoning"| node_reasoning_api
node_user -->|"enters submission"| node_cli
node_cli -->|"evaluates submission"| node_engine
node_api -->|"validates input"| node_submission
node_api -->|"evaluates submission"| node_engine
node_batch_client -.->|"sends batch"| node_batch
node_batch -->|"validates each item"| node_submission
node_batch -->|"evaluates each item"| node_engine
node_engine -->|"checks topic"| node_relevance
node_engine -->|"filters baseline"| node_category
node_engine -->|"scores similarity"| node_novelty
node_engine -->|"embeds text"| node_submission
node_engine -->|"loads baseline"| node_store
node_engine -->|"loads cache"| node_embeddings
node_novelty -->|"learns high scores"| node_adaptive
node_adaptive -->|"updates baseline"| node_persistence
node_persistence -->|"writes baseline"| node_store
node_persistence -->|"writes cache"| node_embeddings
node_api -->|"schedules save"| node_persistence
node_engine -.->|"requests embeddings"| node_gemini
node_novelty -.->|"checks opposing stance"| node_sentiment
node_sentiment -.->|"checks sentiment"| node_gemini
node_reasoning_api -->|"generates rationale"| node_engine
node_engine -.->|"drafts and reviews"| node_reasoning
node_reasoning -.->|"requests reasoning"| node_gemini

click node_web "https://github.com/vinod1204/novelty_evaluator/blob/main/frontend/src/App.tsx"
click node_cli "https://github.com/vinod1204/novelty_evaluator/blob/main/cli.py"
click node_api "https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py"
click node_batch "https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py"
click node_reasoning_api "https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py"
click node_submission "https://github.com/vinod1204/novelty_evaluator/blob/main/src/models.py"
click node_engine "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_relevance "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_category "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_novelty "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_store "https://github.com/vinod1204/novelty_evaluator/blob/main/data/baseline_submissions.json"
click node_embeddings "https://github.com/vinod1204/novelty_evaluator/blob/main/data/embeddings_cache.npz"
click node_adaptive "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_persistence "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_sentiment "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py"
click node_reasoning "https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.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_web,node_cli,node_batch_client toneBlue
class node_api,node_batch,node_reasoning_api,node_submission,node_engine,node_relevance,node_category,node_novelty toneAmber
class node_store,node_embeddings,node_adaptive,node_persistence toneMint
class node_sentiment,node_reasoning toneRose
class node_user,node_gemini toneIndigo
```

## Components

### Submission Interfaces

- [Web Form](https://github.com/vinod1204/novelty_evaluator/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [CLI](https://github.com/vinod1204/novelty_evaluator/blob/main/cli.py): `cli.py`

### Evaluation Service

- [HTTP API](https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py): `src/api.py`
- [Batch Ranking](https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py): `src/api.py`
- [Reasoning Route](https://github.com/vinod1204/novelty_evaluator/blob/main/src/api.py): `src/api.py`
- [Submission Model](https://github.com/vinod1204/novelty_evaluator/blob/main/src/models.py): `src/models.py`
- [Novelty Engine](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Relevance Gate](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Category Matching](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Novelty Scoring](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`

### Baseline Learning

- [Baseline Data](https://github.com/vinod1204/novelty_evaluator/blob/main/data/baseline_submissions.json): `data/baseline_submissions.json`
- [Embedding Cache](https://github.com/vinod1204/novelty_evaluator/blob/main/data/embeddings_cache.npz): `data/embeddings_cache.npz`
- [Adaptive Learning](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Baseline Persistence](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`

### AI Analysis

- [Stance Override](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Reasoning Review Loop](https://github.com/vinod1204/novelty_evaluator/blob/main/src/evaluator.py): `src/evaluator.py`

### Other components

- **Submitter**
- **Google GenAI**
- **Batch Client**

## Connections

- Submitter → Web Form: enters submission (evidence: `frontend/src/App.tsx`)
- Web Form → HTTP API: posts evaluation (evidence: `frontend/src/App.tsx`)
- Web Form → Reasoning Route: requests reasoning (evidence: `frontend/src/App.tsx`)
- Submitter → CLI: enters submission (evidence: `cli.py`)
- CLI → Novelty Engine: evaluates submission (evidence: `cli.py`)
- HTTP API → Submission Model: validates input (evidence: `src/api.py`)
- HTTP API → Novelty Engine: evaluates submission (evidence: `src/api.py`)
- Batch Client → Batch Ranking: sends batch (evidence: `README.md`)
- Batch Ranking → Submission Model: validates each item (evidence: `src/api.py`)
- Batch Ranking → Novelty Engine: evaluates each item (evidence: `src/api.py`)
- Novelty Engine → Relevance Gate: checks topic (evidence: `src/evaluator.py`)
- Novelty Engine → Category Matching: filters baseline (evidence: `src/evaluator.py`)
- Novelty Engine → Novelty Scoring: scores similarity (evidence: `src/evaluator.py`)
- Novelty Engine → Submission Model: embeds text (evidence: `src/evaluator.py`)
- Novelty Engine → Baseline Data: loads baseline (evidence: `src/evaluator.py`)
- Novelty Engine → Embedding Cache: loads cache (evidence: `src/evaluator.py`)
- Novelty Scoring → Adaptive Learning: learns high scores (evidence: `src/evaluator.py`)
- Adaptive Learning → Baseline Persistence: updates baseline (evidence: `src/evaluator.py`)
- Baseline Persistence → Baseline Data: writes baseline (evidence: `src/evaluator.py`)
- Baseline Persistence → Embedding Cache: writes cache (evidence: `src/evaluator.py`)
- HTTP API → Baseline Persistence: schedules save (evidence: `src/api.py`)
- Novelty Engine → Google GenAI: requests embeddings (evidence: `README.md`)
- Novelty Scoring → Stance Override: checks opposing stance (evidence: `README.md`)
- Stance Override → Google GenAI: checks sentiment (evidence: `README.md`)
- Reasoning Route → Novelty Engine: generates rationale (evidence: `src/api.py`)
- Novelty Engine → Reasoning Review Loop: drafts and reviews (evidence: `README.md`)
- Reasoning Review Loop → Google GenAI: requests reasoning (evidence: `README.md`)
