# eesuhn/kairo-core architecture

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

- Interactive diagram: https://gitdiagram.com/eesuhn/kairo-core
- Repository: https://github.com/eesuhn/kairo-core

## Overview

##### Project type and purpose
- Kairo Core is a backend‐only, NLP-powered note-taking server.
- It exposes a REST API (via uv) that ingests raw input (audio/text), runs ML pipelines (transcription, NER, summarization), and returns structured output.
- It doubles as a research/workflow repo: it contains training scripts, DVC-driven data/model versioning, notebooks for exploration, and reporting via Weights & Biases.

##### High-level file-structure analysis
- Top-level “api/” and “src/server.py”: entry points for the HTTP server (API layer).
- “src/input_processor”: pre-processing (audio transcription, diarization).
- “src/ner” + “src/summary”: two ML services, each with trainer, predictor, model, config modules; summary splits into abstractive & extractive.
- “scripts/”: CLI wrappers around training (scripts/train), prediction (scripts/predict), data management (scripts/data), and notebook housekeeping (scripts/nb_update).
- “configs/”: YAML configs for datasets, NER labels/rules, CI hooks.
- “.dvc”, “data.dvc”, “models.dvc”: data/model versioning with DVC.
- “notebooks/” and “reports/”: exploratory analyses and experiment logs (Weights & Biases).
- “pyproject.toml”, “Makefile”, “uv.lock”: build, dependency, and invocation tooling.

##### README insights
- Emphasizes two primary use cases: running the server (`make server`) and training models (`uv run -m scripts.train.*`).
- Uses Hugging Face for data & pre-trained artifacts, Weights & Biases for experiment tracking.
- Provides an OpenAPI spec (`reports/oas.yml`) for endpoint definitions.

a. API Layer
- Client (e.g., Kairo-Web UI or any HTTP client) → uv/Gunicorn server (`api/__main__.py` or `src/server.py`) → OpenAPI endpoints.
b. Input Processing Service
- Audio/Text loader → `src/input_processor.audio_processor` → transcript + diarization.
c. NLP Pipelines (two parallel modules)
1. NER Pipeline
- Predictor (`src/ner/predictor.py`) loads model artifacts (via DVC cache) → runs inference → returns token/entity labels.
2. Summarization Pipeline
- Extractive & Abstractive sub-modules (`src/summary/extractive/*`, `src/summary/abstractive/*`).
- Each has a Predictor, Model, and Config; shredded into two flows but exposed under common summary endpoint.
d. Data & Model Versioning
- DVC directory points to remote storage (GCP/S3) for datasets & model checkpoints.
- Local cache → loaded by training scripts and inference predictors.
e. Training Subsystem (offline)
- CLI scripts in `scripts/train` invoke trainers (`src/ner/trainer.py`, `src/summary/*/trainer.py`) → log to WandB → push outputs via DVC.
f. External Services & Storage
- Hugging Face Datasets API (download).
- Weights & Biases (experiment tracking).
- DVC Remote (model & data artifacts).
- (Optional) Database or file store for user-generated notes (not present here but could be added later).

##### Relationships & interactions
- Client → API Layer → Input Processor → NER/Summary Pipelines → API Layer → Client.
- Pipelines ↔ Local DVC Cache ↔ DVC Remote Storage.
- Training Scripts → Trainer Modules → WandB → DVC Remote.
- Internal components into logical subsystems (API, Preprocessing, ML Services, Offline Training).

##### Architectural patterns & design principles
- Layered architecture: API → Service → Model → Data.
- Modularization: separate packages for each ML task.
- Configuration-driven: YAML configs drive datasets, NER rules, trainer hyperparameters.
- Version control for data/models (DVC) and experiments (WandB).
- Single monolithic service at runtime, but clear separation of concerns.

##### Essential details to capture
- Entry points (`uv run` / `Makefile` targets).
- Config management layer (`configs/*.yml`).
- DVC’s dual role in data and model pipelines.
- Dual nature of ML pipelines (online inference vs. offline training).
- Interaction with external services (Hugging Face, WandB).
- Discrete modules for NER, extractive summary, and abstractive summary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        direction TB
        Client["Client (Web UI/HTTP)"]:::external
        ServerMain["api/__main__.py"]:::api
        ServerSrc["src/server.py"]:::api
        OAS["reports/oas.yml"]:::store
    end

    %% Input Processing
    subgraph "Input Processing Service"
        direction TB
        Loader["Audio/Text Loader"]:::api
        IPMain["src/input_processor/__main__.py"]:::api
        AudioProc["src/input_processor/audio_processor.py"]:::api
    end

    %% ML Inference Services
    subgraph "ML Inference"
        direction TB
        subgraph "NER Pipeline"
            direction TB
            NERPred["src/ner/predictor.py"]:::ml
            NERModel["src/ner/model.py"]:::ml
            NERConfig["src/ner/config.py"]:::ml
        end
        subgraph "Summarization Pipeline"
            direction TB
            subgraph "Extractive Module"
                direction TB
                ExtPred["src/summary/extractive/predictor.py"]:::ml
                ExtModel["src/summary/extractive/model.py"]:::ml
                ExtConfig["src/summary/extractive/config.py"]:::ml
            end
            subgraph "Abstractive Module"
                direction TB
                AbsPred["src/summary/abstractive/predictor.py"]:::ml
                AbsModel["src/summary/abstractive/model.py"]:::ml
                AbsConfig["src/summary/abstractive/config.py"]:::ml
            end
        end
    end

    %% Data & Model Storage
    subgraph "Data/Model Storage"
        direction TB
        DVCConfig[".dvc/config"]:::store
        DataDVC["data.dvc"]:::store
        ModelsDVC["models.dvc"]:::store
        DVCCache[[Local DVC Cache]]:::store
        DVCRemote[[DVC Remote Storage]]:::store
        Configs["configs/*.yml"]:::store
    end

    %% Training Subsystem (Offline)
    subgraph "Offline Training Subsystem"
        direction TB
        subgraph "Training CLI Scripts"
            direction TB
            TrainNER["scripts/train/ner.py"]:::offline
            TrainExt["scripts/train/ext_sum.py"]:::offline
            TrainAbs["scripts/train/abs_sum.py"]:::offline
        end
        subgraph "Trainer Modules"
            direction TB
            NERTrainer["src/ner/trainer.py"]:::offline
            ExtTrainer["src/summary/extractive/trainer.py"]:::offline
            AbsTrainer["src/summary/abstractive/trainer.py"]:::offline
        end
        WandBCloud("Weights & Biases"):::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HF("Hugging Face Datasets API"):::external
    end

    %% Connections: Client to API
    Client -->|"HTTP request"| ServerMain
    ServerMain --> ServerSrc
    ServerSrc -->|"load OpenAPI spec"| OAS

    %% API to Input Processing
    ServerSrc -->|"ingest data"| Loader
    Loader --> IPMain
    IPMain --> AudioProc
    AudioProc -->|"transcript/diarization"| ServerSrc

    %% API to Inference
    ServerSrc -->|"infer NER"| NERPred
    ServerSrc -->|"infer Summary"| ExtPred
    ServerSrc --> AbsPred

    %% Inference to Models & Configs
    NERPred -->|"load model"| DVCCache
    NERPred --> NERModel
    NERPred --> NERConfig
    ExtPred -->|"load model"| DVCCache
    ExtPred --> ExtModel
    ExtPred --> ExtConfig
    AbsPred -->|"load model"| DVCCache
    AbsPred --> AbsModel
    AbsPred --> AbsConfig

    %% DVC Cache to Remote
    DVCCache -->|"pull/push"| DVCRemote

    %% Config management usage
    ServerSrc -->|"reads configs"| Configs
    NERPred --> Configs
    ExtPred --> Configs
    AbsPred --> Configs
    IPMain --> Configs

    %% Offline training flow
    TrainNER -->|"CLI start"| NERTrainer
    TrainExt --> ExtTrainer
    TrainAbs --> AbsTrainer

    NERTrainer -->|"log metrics"| WandBCloud
    ExtTrainer --> WandBCloud
    AbsTrainer --> WandBCloud

    NERTrainer -->|"push output"| DVCRemote
    ExtTrainer --> DVCRemote
    AbsTrainer --> DVCRemote

    %% External data download
    NERTrainer -->|"download data"| HF
    ExtTrainer --> HF
    AbsTrainer --> HF
    IPMain --> HF

    %% Click Events
    click ServerMain "https://github.com/eesuhn/kairo-core/blob/main/api/__main__.py"
    click ServerSrc "https://github.com/eesuhn/kairo-core/blob/main/src/server.py"
    click IPMain "https://github.com/eesuhn/kairo-core/blob/main/src/input_processor/__main__.py"
    click AudioProc "https://github.com/eesuhn/kairo-core/blob/main/src/input_processor/audio_processor.py"
    click NERPred "https://github.com/eesuhn/kairo-core/blob/main/src/ner/predictor.py"
    click NERTrainer "https://github.com/eesuhn/kairo-core/blob/main/src/ner/trainer.py"
    click NERModel "https://github.com/eesuhn/kairo-core/blob/main/src/ner/model.py"
    click NERConfig "https://github.com/eesuhn/kairo-core/blob/main/src/ner/config.py"
    click AbsPred "https://github.com/eesuhn/kairo-core/blob/main/src/summary/abstractive/predictor.py"
    click AbsTrainer "https://github.com/eesuhn/kairo-core/blob/main/src/summary/abstractive/trainer.py"
    click AbsModel "https://github.com/eesuhn/kairo-core/blob/main/src/summary/abstractive/model.py"
    click AbsConfig "https://github.com/eesuhn/kairo-core/blob/main/src/summary/abstractive/config.py"
    click ExtPred "https://github.com/eesuhn/kairo-core/blob/main/src/summary/extractive/predictor.py"
    click ExtTrainer "https://github.com/eesuhn/kairo-core/blob/main/src/summary/extractive/trainer.py"
    click ExtModel "https://github.com/eesuhn/kairo-core/blob/main/src/summary/extractive/model.py"
    click ExtConfig "https://github.com/eesuhn/kairo-core/blob/main/src/summary/extractive/config.py"
    click TrainNER "https://github.com/eesuhn/kairo-core/blob/main/scripts/train/ner.py"
    click TrainExt "https://github.com/eesuhn/kairo-core/blob/main/scripts/train/ext_sum.py"
    click TrainAbs "https://github.com/eesuhn/kairo-core/blob/main/scripts/train/abs_sum.py"
    click DataDVC "https://github.com/eesuhn/kairo-core/blob/main/data.dvc"
    click ModelsDVC "https://github.com/eesuhn/kairo-core/blob/main/models.dvc"
    click DVCConfig "https://github.com/eesuhn/kairo-core/tree/main/.dvc/config"
    click Configs "https://github.com/eesuhn/kairo-core/blob/main/configs/datasets.yml"
    click OAS "https://github.com/eesuhn/kairo-core/blob/main/reports/oas.yml"

    %% Styles
    classDef api fill:#cce5ff,stroke:#000;
    classDef ml fill:#d4edda,stroke:#000;
    classDef store fill:#fff3cd,stroke:#000;
    classDef offline fill:#e2e3e5,stroke:#000;
    classDef external fill:#f8f9fa,stroke:#000,stroke-dasharray: 2 2;
```
