# bernice511/entiscribe architecture

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

- Interactive diagram: https://gitdiagram.com/bernice511/entiscribe
- Repository: https://github.com/bernice511/entiscribe

## Overview

PDF Named Entity Extractor is a Streamlit application for ingesting PDFs, extracting user-defined entities with an LLM, and evaluating results. Users upload PDFs, configure entity types, run extraction, and optionally evaluate against a gold CSV; groundedness scoring is also included. The graph follows the three documented pipelines and their main implementation layers. The README supports the overall workflow; sampled source supports the shown calls. Other UI details and unsampled evaluation metrics internals are not inferred.

Main entry points: [`src/pipeline/extract_graph.py`](https://github.com/bernice511/entiscribe/blob/main/src/pipeline/extract_graph.py) (Extraction Pipeline), [`src/pipeline/evaluate_graph.py`](https://github.com/bernice511/entiscribe/blob/main/src/pipeline/evaluate_graph.py) (Evaluation Pipeline), [`src/app.py`](https://github.com/bernice511/entiscribe/blob/main/src/app.py) (Streamlit App), [`src/ui/upload_tab.py`](https://github.com/bernice511/entiscribe/blob/main/src/ui/upload_tab.py) (Upload and Results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App and UI"]
  node_app["Streamlit App<br/>[app.py]"]
  node_sidebar["Entity Settings<br/>[sidebar.py]"]
  node_session["Session State<br/>[session.py]"]
  node_upload_ui["Upload and Results<br/>[upload_tab.py]"]
  node_evaluate_ui["Evaluation View<br/>[evaluate_tab.py]"]
end

subgraph group_ingestion["PDF Ingestion"]
  node_ingest_flow["Ingest Pipeline<br/>[ingest_graph.py]"]
  node_pdf_text["PDF Text Extraction<br/>[pdf.py]"]
  node_vector_store[("Chunking and Vector Store<br/>[vector_store.py]")]
end

subgraph group_extraction["Entity Extraction"]
  node_extract_flow["Extraction Pipeline<br/>[extract_graph.py]"]
  node_entity_schema["Dynamic Entity Schema<br/>[schema.py]"]
  node_pipeline_state["Pipeline State Types<br/>[state.py]"]
  node_claude_cli["Claude CLI Wrapper<br/>[claude_cli.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluate_flow["Evaluation Pipeline<br/>[evaluate_graph.py]"]
  node_groundedness["Groundedness Scoring<br/>[groundedness.py]"]
  node_gold_metrics["Gold Metrics<br/>[metrics.py]"]
end

node_user(("User"))
node_claude{{"Claude CLI"}}
node_gold_csv["Gold CSV"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_upload_ui
node_app -->|"renders"| node_evaluate_ui
node_sidebar -->|"updates settings"| node_session
node_sidebar -->|"loads presets"| node_entity_schema
node_upload_ui -->|"reads and updates"| node_session
node_upload_ui -->|"ingests PDFs"| node_ingest_flow
node_upload_ui -->|"runs extraction"| node_extract_flow
node_session -->|"creates store"| node_vector_store
node_ingest_flow -->|"extracts text"| node_pdf_text
node_ingest_flow -->|"chunks and stores"| node_vector_store
node_extract_flow -->|"builds schema"| node_entity_schema
node_extract_flow -->|"retrieves chunks"| node_vector_store
node_extract_flow -->|"requests structured extraction"| node_claude_cli
node_extract_flow -->|"uses state"| node_pipeline_state
node_claude_cli -->|"runs subprocess"| node_claude
node_evaluate_ui -->|"reads and updates"| node_session
node_evaluate_ui -->|"runs evaluation"| node_evaluate_flow
node_gold_csv -->|"uploads"| node_evaluate_ui
node_evaluate_flow -->|"reuses context retrieval"| node_extract_flow
node_evaluate_flow -->|"scores support"| node_groundedness
node_evaluate_flow -->|"compares gold"| node_gold_metrics
node_evaluate_flow -->|"uses state"| node_pipeline_state
node_groundedness -->|"requests judge scores"| node_claude_cli

click node_app "https://github.com/bernice511/entiscribe/blob/main/src/app.py"
click node_sidebar "https://github.com/bernice511/entiscribe/blob/main/src/ui/sidebar.py"
click node_session "https://github.com/bernice511/entiscribe/blob/main/src/session.py"
click node_upload_ui "https://github.com/bernice511/entiscribe/blob/main/src/ui/upload_tab.py"
click node_evaluate_ui "https://github.com/bernice511/entiscribe/blob/main/src/ui/evaluate_tab.py"
click node_ingest_flow "https://github.com/bernice511/entiscribe/blob/main/src/pipeline/ingest_graph.py"
click node_pdf_text "https://github.com/bernice511/entiscribe/blob/main/src/ingestion/pdf.py"
click node_vector_store "https://github.com/bernice511/entiscribe/blob/main/src/ingestion/vector_store.py"
click node_extract_flow "https://github.com/bernice511/entiscribe/blob/main/src/pipeline/extract_graph.py"
click node_entity_schema "https://github.com/bernice511/entiscribe/blob/main/src/entities/schema.py"
click node_pipeline_state "https://github.com/bernice511/entiscribe/blob/main/src/pipeline/state.py"
click node_claude_cli "https://github.com/bernice511/entiscribe/blob/main/src/llm/claude_cli.py"
click node_evaluate_flow "https://github.com/bernice511/entiscribe/blob/main/src/pipeline/evaluate_graph.py"
click node_groundedness "https://github.com/bernice511/entiscribe/blob/main/src/evaluation/groundedness.py"
click node_gold_metrics "https://github.com/bernice511/entiscribe/blob/main/src/evaluation/metrics.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_app,node_sidebar,node_session,node_upload_ui,node_evaluate_ui,node_user toneBlue
class node_ingest_flow,node_pdf_text,node_vector_store toneAmber
class node_extract_flow,node_entity_schema,node_pipeline_state,node_claude_cli toneMint
class node_evaluate_flow,node_groundedness,node_gold_metrics toneRose
class node_claude,node_gold_csv toneIndigo
```

## Components

### App and UI

- [Streamlit App](https://github.com/bernice511/entiscribe/blob/main/src/app.py): `src/app.py`
- [Entity Settings](https://github.com/bernice511/entiscribe/blob/main/src/ui/sidebar.py): `src/ui/sidebar.py`
- [Session State](https://github.com/bernice511/entiscribe/blob/main/src/session.py): `src/session.py`
- [Upload and Results](https://github.com/bernice511/entiscribe/blob/main/src/ui/upload_tab.py): `src/ui/upload_tab.py`
- [Evaluation View](https://github.com/bernice511/entiscribe/blob/main/src/ui/evaluate_tab.py): `src/ui/evaluate_tab.py`

### PDF Ingestion

- [Ingest Pipeline](https://github.com/bernice511/entiscribe/blob/main/src/pipeline/ingest_graph.py): `src/pipeline/ingest_graph.py`
- [PDF Text Extraction](https://github.com/bernice511/entiscribe/blob/main/src/ingestion/pdf.py): `src/ingestion/pdf.py`
- [Chunking and Vector Store](https://github.com/bernice511/entiscribe/blob/main/src/ingestion/vector_store.py): `src/ingestion/vector_store.py`

### Entity Extraction

- [Extraction Pipeline](https://github.com/bernice511/entiscribe/blob/main/src/pipeline/extract_graph.py): `src/pipeline/extract_graph.py`
- [Dynamic Entity Schema](https://github.com/bernice511/entiscribe/blob/main/src/entities/schema.py): `src/entities/schema.py`
- [Pipeline State Types](https://github.com/bernice511/entiscribe/blob/main/src/pipeline/state.py): `src/pipeline/state.py`
- [Claude CLI Wrapper](https://github.com/bernice511/entiscribe/blob/main/src/llm/claude_cli.py): `src/llm/claude_cli.py`

### Evaluation

- [Evaluation Pipeline](https://github.com/bernice511/entiscribe/blob/main/src/pipeline/evaluate_graph.py): `src/pipeline/evaluate_graph.py`
- [Groundedness Scoring](https://github.com/bernice511/entiscribe/blob/main/src/evaluation/groundedness.py): `src/evaluation/groundedness.py`
- [Gold Metrics](https://github.com/bernice511/entiscribe/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`

### Other components

- **User**
- **Claude CLI**
- **Gold CSV**

## Connections

- User → Streamlit App: uses (evidence: `README.md`)
- Streamlit App → Entity Settings: renders (evidence: `src/app.py`)
- Streamlit App → Upload and Results: renders (evidence: `src/app.py`)
- Streamlit App → Evaluation View: renders (evidence: `src/app.py`)
- Entity Settings → Session State: updates settings (evidence: `src/ui/sidebar.py`)
- Entity Settings → Dynamic Entity Schema: loads presets (evidence: `src/ui/sidebar.py`)
- Upload and Results → Session State: reads and updates (evidence: `src/ui/upload_tab.py`)
- Upload and Results → Ingest Pipeline: ingests PDFs (evidence: `src/ui/upload_tab.py`)
- Upload and Results → Extraction Pipeline: runs extraction (evidence: `src/ui/upload_tab.py`)
- Session State → Chunking and Vector Store: creates store (evidence: `src/session.py`)
- Ingest Pipeline → PDF Text Extraction: extracts text (evidence: `src/pipeline/ingest_graph.py`)
- Ingest Pipeline → Chunking and Vector Store: chunks and stores (evidence: `src/pipeline/ingest_graph.py`)
- Extraction Pipeline → Dynamic Entity Schema: builds schema (evidence: `src/pipeline/extract_graph.py`)
- Extraction Pipeline → Chunking and Vector Store: retrieves chunks (evidence: `src/pipeline/extract_graph.py`)
- Extraction Pipeline → Claude CLI Wrapper: requests structured extraction (evidence: `src/pipeline/extract_graph.py`)
- Extraction Pipeline → Pipeline State Types: uses state (evidence: `src/pipeline/extract_graph.py`)
- Claude CLI Wrapper → Claude CLI: runs subprocess (evidence: `src/llm/claude_cli.py`)
- Evaluation View → Session State: reads and updates (evidence: `src/ui/evaluate_tab.py`)
- Evaluation View → Evaluation Pipeline: runs evaluation (evidence: `src/ui/evaluate_tab.py`)
- Gold CSV → Evaluation View: uploads (evidence: `src/ui/evaluate_tab.py`)
- Evaluation Pipeline → Extraction Pipeline: reuses context retrieval (evidence: `src/pipeline/evaluate_graph.py`)
- Evaluation Pipeline → Groundedness Scoring: scores support (evidence: `src/pipeline/evaluate_graph.py`)
- Evaluation Pipeline → Gold Metrics: compares gold (evidence: `src/pipeline/evaluate_graph.py`)
- Evaluation Pipeline → Pipeline State Types: uses state (evidence: `src/pipeline/evaluate_graph.py`)
- Groundedness Scoring → Claude CLI Wrapper: requests judge scores (evidence: `src/evaluation/groundedness.py`)
