How eesuhn/kairo-core works
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.