# hamshika06/inkwell architecture

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

- Interactive diagram: https://gitdiagram.com/hamshika06/inkwell
- Repository: https://github.com/hamshika06/inkwell

## Overview

Inkwell is a privacy-policy clause classifier: users provide policy text, which is segmented and scored against a fixed category schema; results attach labels to source clauses. The implemented demo path supports Stage 1, including category-based FAQs. The README also describes silence detection and retrieval-based Stage 2, but the sampled runtime does not show those implementations. Data preparation, model training, prediction, and evaluation are represented as supporting layers. Edges reflect sampled calls or documented behavior; unsampled capability links are marked unverified.

Main entry points: [`inkwell/common.py`](https://github.com/hamshika06/inkwell/blob/main/inkwell/common.py) (Shared metrics and data), [`data/versions/v1`](https://github.com/hamshika06/inkwell/tree/main/data/versions/v1) (Frozen dataset), [`inkwell/predict.py`](https://github.com/hamshika06/inkwell/blob/main/inkwell/predict.py) (Model predictor), [`inkwell/stage1.py`](https://github.com/hamshika06/inkwell/blob/main/inkwell/stage1.py) (Policy segmenter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_opp115["OPP-115 preparation"]
  node_c3pa["C3PA preparation<br/>[c3pa_preprocess.py]"]
  node_combine["Dataset integration"]
  node_schema["Label schema<br/>[label_schema.json]"]
  node_frozen[("Frozen dataset")]
end

subgraph group_models["Model development"]
  node_common["Shared metrics and data<br/>[common.py]"]
  node_baseline["TF-IDF SVM training<br/>[train_baseline.py]"]
  node_encoder["Encoder training<br/>[train_encoder.py]"]
  node_loss["Masked training loss<br/>[loss.py]"]
  node_runs[("Saved model runs")]
end

subgraph group_runtime["Policy analysis"]
  node_predictor["Model predictor<br/>[predict.py]"]
  node_segment["Policy segmenter<br/>[stage1.py]"]
  node_faq["Category FAQs<br/>[stage1.py]"]
  node_silence["Silence detection"]
  node_openqa["Open Q&amp;A retrieval"]
  node_span["Clause span extraction"]
  node_demo["Local demo<br/>[server.py]"]
end

subgraph group_qa["Evaluation"]
  node_evaluate["Modern evaluation<br/>[evaluate_modern.py]"]
  node_review["Human review<br/>[modern_review.py]"]
end

node_user(("Policy user"))

node_opp115 -.->|"prepares source data"| node_combine
node_c3pa -.->|"prepares source data"| node_combine
node_combine -.->|"combined dataset"| node_frozen
node_schema -->|"loads categories"| node_common
node_common -->|"verifies checksums"| node_frozen
node_frozen -->|"training data"| node_baseline
node_frozen -->|"training data"| node_encoder
node_common -->|"provides dataset helpers"| node_baseline
node_common -->|"provides dataset helpers"| node_encoder
node_encoder -->|"computes loss"| node_loss
node_baseline -->|"saves model run"| node_runs
node_encoder -->|"saves model run"| node_runs
node_user -.->|"submits policy"| node_demo
node_demo -.->|"analyzes policy"| node_segment
node_segment -->|"scores segments"| node_predictor
node_predictor -->|"loads categories"| node_common
node_runs -->|"loads model artifacts"| node_predictor
node_segment -->|"organizes categories"| node_faq
node_segment -.->|"checks uncovered categories"| node_silence
node_user -.->|"asks question"| node_openqa
node_openqa -.->|"returns matching clauses"| node_span
node_review -->|"selects review rows"| node_frozen
node_review -.->|"provides reviewed labels"| node_evaluate
node_evaluate -->|"scores reviewed text"| node_predictor
node_predictor -->|"returns scores"| node_evaluate

click node_opp115 "https://github.com/hamshika06/inkwell/blob/main/preprocessing/opp115_preprocess.py"
click node_c3pa "https://github.com/hamshika06/inkwell/blob/main/preprocessing/c3pa_preprocess.py"
click node_combine "https://github.com/hamshika06/inkwell/blob/main/data_integration/combine_opp115_c3pa.py"
click node_schema "https://github.com/hamshika06/inkwell/blob/main/configs/label_schema.json"
click node_frozen "https://github.com/hamshika06/inkwell/tree/main/data/versions/v1"
click node_common "https://github.com/hamshika06/inkwell/blob/main/inkwell/common.py"
click node_baseline "https://github.com/hamshika06/inkwell/blob/main/scripts/train_baseline.py"
click node_encoder "https://github.com/hamshika06/inkwell/blob/main/scripts/train_encoder.py"
click node_loss "https://github.com/hamshika06/inkwell/blob/main/inkwell/loss.py"
click node_runs "https://github.com/hamshika06/inkwell/tree/main/runs"
click node_predictor "https://github.com/hamshika06/inkwell/blob/main/inkwell/predict.py"
click node_segment "https://github.com/hamshika06/inkwell/blob/main/inkwell/stage1.py"
click node_faq "https://github.com/hamshika06/inkwell/blob/main/inkwell/stage1.py"
click node_silence "https://github.com/hamshika06/inkwell/tree/main/inkwell"
click node_openqa "https://github.com/hamshika06/inkwell/tree/main/inkwell"
click node_span "https://github.com/hamshika06/inkwell/tree/main/inkwell"
click node_demo "https://github.com/hamshika06/inkwell/blob/main/demo/server.py"
click node_evaluate "https://github.com/hamshika06/inkwell/blob/main/scripts/evaluate_modern.py"
click node_review "https://github.com/hamshika06/inkwell/blob/main/scripts/modern_review.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_opp115,node_c3pa,node_combine,node_schema,node_frozen,node_user toneBlue
class node_common,node_baseline,node_encoder,node_loss,node_runs toneAmber
class node_predictor,node_segment,node_faq,node_silence,node_openqa,node_span,node_demo toneMint
class node_evaluate,node_review toneRose
```

## Components

### Data preparation

- [OPP-115 preparation](https://github.com/hamshika06/inkwell/blob/main/preprocessing/opp115_preprocess.py): `preprocessing/opp115_preprocess.py`
- [C3PA preparation](https://github.com/hamshika06/inkwell/blob/main/preprocessing/c3pa_preprocess.py): `preprocessing/c3pa_preprocess.py`
- [Dataset integration](https://github.com/hamshika06/inkwell/blob/main/data_integration/combine_opp115_c3pa.py): `data_integration/combine_opp115_c3pa.py`
- [Label schema](https://github.com/hamshika06/inkwell/blob/main/configs/label_schema.json): `configs/label_schema.json`
- [Frozen dataset](https://github.com/hamshika06/inkwell/tree/main/data/versions/v1): `data/versions/v1`

### Model development

- [Shared metrics and data](https://github.com/hamshika06/inkwell/blob/main/inkwell/common.py): `inkwell/common.py`
- [TF-IDF SVM training](https://github.com/hamshika06/inkwell/blob/main/scripts/train_baseline.py): `scripts/train_baseline.py`
- [Encoder training](https://github.com/hamshika06/inkwell/blob/main/scripts/train_encoder.py): `scripts/train_encoder.py`
- [Masked training loss](https://github.com/hamshika06/inkwell/blob/main/inkwell/loss.py): `inkwell/loss.py`
- [Saved model runs](https://github.com/hamshika06/inkwell/tree/main/runs): `runs`

### Policy analysis

- [Model predictor](https://github.com/hamshika06/inkwell/blob/main/inkwell/predict.py): `inkwell/predict.py`
- [Policy segmenter](https://github.com/hamshika06/inkwell/blob/main/inkwell/stage1.py): `inkwell/stage1.py`
- [Category FAQs](https://github.com/hamshika06/inkwell/blob/main/inkwell/stage1.py): `inkwell/stage1.py`
- [Silence detection](https://github.com/hamshika06/inkwell/tree/main/inkwell): `inkwell`
- [Open Q&A retrieval](https://github.com/hamshika06/inkwell/tree/main/inkwell): `inkwell`
- [Clause span extraction](https://github.com/hamshika06/inkwell/tree/main/inkwell): `inkwell`
- [Local demo](https://github.com/hamshika06/inkwell/blob/main/demo/server.py): `demo/server.py`

### Evaluation

- [Modern evaluation](https://github.com/hamshika06/inkwell/blob/main/scripts/evaluate_modern.py): `scripts/evaluate_modern.py`
- [Human review](https://github.com/hamshika06/inkwell/blob/main/scripts/modern_review.py): `scripts/modern_review.py`

### Other components

- **Policy user**

## Connections

- OPP-115 preparation → Dataset integration: prepares source data
- C3PA preparation → Dataset integration: prepares source data
- Dataset integration → Frozen dataset: combined dataset
- Label schema → Shared metrics and data: loads categories (evidence: `inkwell/common.py`)
- Shared metrics and data → Frozen dataset: verifies checksums (evidence: `inkwell/common.py`)
- Frozen dataset → TF-IDF SVM training: training data (evidence: `scripts/train_baseline.py`)
- Frozen dataset → Encoder training: training data (evidence: `scripts/train_encoder.py`)
- Shared metrics and data → TF-IDF SVM training: provides dataset helpers (evidence: `scripts/train_baseline.py`)
- Shared metrics and data → Encoder training: provides dataset helpers (evidence: `scripts/train_encoder.py`)
- Encoder training → Masked training loss: computes loss (evidence: `scripts/train_encoder.py`)
- TF-IDF SVM training → Saved model runs: saves model run (evidence: `scripts/train_baseline.py`)
- Encoder training → Saved model runs: saves model run (evidence: `scripts/train_encoder.py`)
- Policy user → Local demo: submits policy
- Local demo → Policy segmenter: analyzes policy
- Policy segmenter → Model predictor: scores segments (evidence: `inkwell/stage1.py`)
- Model predictor → Shared metrics and data: loads categories (evidence: `inkwell/predict.py`)
- Saved model runs → Model predictor: loads model artifacts (evidence: `inkwell/predict.py`)
- Policy segmenter → Category FAQs: organizes categories (evidence: `inkwell/stage1.py`)
- Policy segmenter → Silence detection: checks uncovered categories (evidence: `README.md`)
- Policy user → Open Q&A retrieval: asks question (evidence: `README.md`)
- Open Q&A retrieval → Clause span extraction: returns matching clauses (evidence: `README.md`)
- Human review → Frozen dataset: selects review rows (evidence: `scripts/modern_review.py`)
- Human review → Modern evaluation: provides reviewed labels
- Modern evaluation → Model predictor: scores reviewed text (evidence: `scripts/evaluate_modern.py`)
- Model predictor → Modern evaluation: returns scores (evidence: `scripts/evaluate_modern.py`)
