# muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection architecture

> Architecture diagram of the GitHub repository muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection
- Repository: https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection

## Overview

1. **Repository purpose**
   - This repo packages a deployment-oriented harmful-speech detection system that routes each input text through a skill-inference stage, a symbolic expert router, and a set of task-specific Llama 3.1 LoRA adapters.
   - It is split into three clear areas: model/routing logic, serving backend, and static presentation assets.

2. **Core runtime pipeline**
   - The main inference flow is: raw text in → skill extraction → router selection of experts → adapter-based generation/prediction → multilabel harm labels out.
   - The canonical single-request entrypoint is `symbolic-moe/predict_post.py`, which the backend adapter uses for live inference.

3. **Symbolic skill inference layer**
   - `symbolic-moe/skill_inference.py` infers ontology-level skills from user text using the Llama 3.1 base model plus a controlled skill vocabulary in `skills.txt`.
   - `symbolic-moe/skill_parsing.py` constrains and normalizes predicted skills so downstream routing works on a stable symbolic representation.
   - This stage is the first major boundary: it converts unstructured text into structured routing features.

4. **Expert routing subsystem**
   - `symbolic-moe/route_and_predict_nb.py` contains the Bernoulli Naive Bayes router that selects the top-2 experts per example from the inferred skills.
   - The router is trained from skill-annotated pools such as `profile_pool_skills.jsonl`, `validation_pool_skills.jsonl`, and `test_pool_skills.jsonl`.
   - This is the decision layer that maps a skill profile to one or more specialist models.

5. **Expert execution and adapter switching**
   - The system uses a shared Llama 3.1 base model with separate LoRA expert adapters stored under `saves/llama31-8b/.../qlora`.
   - `symbolic-moe/model_utils.py` is the boundary that keeps the base model resident and swaps adapters instead of reloading full checkpoints for every task.
   - The four experts correspond to the task directories in `saves/llama31-8b/`: `dynahate`, `jigsaw_threat`, `kaggle_cyberbullying`, and `tweeteval_offensive`.

6. **Prediction aggregation**
   - `symbolic-moe/predict_post.py` ties together skill inference, routing, expert execution, and label filtering into a single request-response flow.
   - It returns the final multilabel output with confidences after keeping only the labels relevant to the target task.
   - This file is effectively the runtime composition layer for the whole system.

7. **Offline profile and dataset artifacts**
   - `symbolic-moe/build_profiles.py` and `profiles.json` support constructing and storing learned expert profiles.
   - The repo also retains the pools used for training and validation of routing: `profile_pool.jsonl`, `validation_pool.jsonl`, and `test_pool.jsonl`, plus their skill-annotated counterparts.
   - These assets are the offline data foundation for the symbolic router and expert-selection logic.

8. **Evaluation and observability**
   - `symbolic-moe/evaluate_outputs.py` scores model outputs and records evaluation traces.
   - `symbolic-moe/langsmith_utils.py` and `symbolic-moe/langsmith_workflows.py` integrate with LangSmith for trace capture, dataset upload, backfilling, review queues, and hard-case analysis.
   - LangSmith is not part of the live request path; it is an evaluation/inspection layer for debugging routing and model behavior.

9. **Serving backend**
   - `web app/backend/` is a FastAPI service that exposes the detection pipeline to clients.
   - The primary API surface is `POST /api/detect`, with readiness/liveness endpoints for deployment health checks.
   - `web app/backend/app/services/` contains the service abstraction layer, including local pipeline execution, remote inference support, and adapter selection/factory logic.

10. **Backend deployment modes**
   - The backend is designed to run either locally in-process or against a remote/Colab GPU workflow.
   - `web app/COLAB_BACKEND.md` and `web app/SERML_Backend.ipynb` describe the Colab-oriented serving path, while `web app/backend/app/services/remote_inference.py` suggests a separate remote execution boundary.
   - `predict_post_adapter.py` bridges the backend API contract to the symbolic inference pipeline.

11. **Backend application structure**
   - `web app/backend/app/main.py` is the service entrypoint, with `app/api/routes_detect.py` defining request routes and `app/schemas.py` defining request/response shapes.
   - `app/config.py`, `app/logging_config.py`, and `app/audit.py` provide operational concerns such as configuration, logging, and auditability.
   - `web app/backend/storage/` and `web app/backend/logs/` are runtime persistence areas for local state and logs.

12. **Presentation and static site**
   - `docs/index.html` and `docs/assets/` power the GitHub Pages project page, which is a separate presentation surface from the model backend.
   - `project.html` appears to be an additional static project artifact, while `.nojekyll` enables direct Pages hosting behavior.
   - This part of the repo is purely informational/demo-facing and does not participate in inference.

13. **Model artifacts and saved outputs**
   - The `saves/` tree contains the trained LoRA adapter bundles and tokenizer/config metadata for each specialist task.
   - Files such as `adapter_model.safetensors`, `adapter_config.json`, `trainer_state.json`, `train_results.json`, and `eval_results.json` document both training and evaluation outcomes for each expert.
   - These artifacts are the deployable model layer consumed by the runtime, separate from the symbolic router code.

14. **Architecture boundary summary**
   - The cleanest diagram is: client/UI → FastAPI backend → canonical prediction flow in `symbolic-moe` → shared Llama base model plus task adapters → response.
   - Orthogonal to that, offline training/evaluation pipelines generate the router artifacts, skill vocab, expert profiles, and adapter checkpoints.
   - LangSmith and the static docs site sit beside the runtime as observability and presentation subsystems, not as inference dependencies.

Main entry points: [`symbolic-moe/predict_post.py`](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/predict_post.py) (Predict flow), [`web app/backend/app/api/routes_detect.py`](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/api/routes_detect.py) (Detect API), [`symbolic-moe/skill_inference.py`](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skill_inference.py) (Skill inference), [`symbolic-moe/route_and_predict_nb.py`](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/route_and_predict_nb.py) (NB router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime pipeline"]
  node_n_predict_post["Predict flow<br/>runtime composition<br/>[predict_post.py]"]
  node_n_skill_inf["Skill inference<br/>symbolic extractor<br/>[skill_inference.py]"]
  node_n_skill_parse["Skill parsing<br/>normalization<br/>[skill_parsing.py]"]
  node_n_router["NB router<br/>expert router"]
  node_n_model_utils["Model utils<br/>adapter manager<br/>[model_utils.py]"]
end

subgraph group_grp_backend["Serving backend"]
  node_n_api["Detect API<br/>fastapi route<br/>[routes_detect.py]"]
  node_n_main["Backend main<br/>service entrypoint<br/>[main.py]"]
  node_n_schema["API schemas<br/>request models<br/>[schemas.py]"]
  node_n_service_factory["Pipeline factory<br/>service wiring"]
  node_n_predict_adapter["Predict adapter<br/>bridge layer"]
  node_n_remote["Remote inference<br/>execution boundary"]
end

subgraph group_grp_offline["Offline artifacts"]
  node_n_eval["Evaluation<br/>scoring and traces"]
  node_n_langsmith["LangSmith<br/>observability"]
  node_n_profiles["Profiles<br/>offline artifacts<br/>[profiles.json]"]
  node_n_skills_vocab["Skills vocab<br/>ontology<br/>[skills.txt]"]
  node_n_adapters[("LoRA experts<br/>model artifacts")]
end

subgraph group_grp_presentation["Presentation"]
  node_n_docs["Docs site<br/>static presentation<br/>[index.html]"]
end

node_n_client(("Client / UI<br/>request source"))

node_n_client -->|"POST /api/detect"| node_n_api
node_n_api -->|"validates"| node_n_schema
node_n_main -->|"mounts"| node_n_api
node_n_api -->|"selects pipeline"| node_n_service_factory
node_n_service_factory -->|"local path"| node_n_predict_adapter
node_n_service_factory -->|"remote path"| node_n_remote
node_n_predict_adapter -->|"calls"| node_n_predict_post
node_n_predict_post -->|"extracts skills"| node_n_skill_inf
node_n_skill_inf -->|"normalizes"| node_n_skill_parse
node_n_skill_parse -->|"routes on"| node_n_router
node_n_router -->|"selects expert"| node_n_model_utils
node_n_model_utils -->|"loads swaps"| node_n_adapters
node_n_predict_post -->|"infers with"| node_n_adapters
node_n_router -->|"trained from"| node_n_profiles
node_n_skill_inf -->|"constrained by"| node_n_skills_vocab
node_n_eval -->|"scores outputs"| node_n_predict_post
node_n_langsmith -->|"supports"| node_n_eval
node_n_docs -.->|"informational"| node_n_client

click node_n_api "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/web app/backend/app/api/routes_detect.py"
click node_n_main "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/web app/backend/app/main.py"
click node_n_schema "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/web app/backend/app/schemas.py"
click node_n_service_factory "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/web app/backend/app/services/pipeline_factory.py"
click node_n_predict_adapter "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/web app/backend/app/services/predict_post_adapter.py"
click node_n_remote "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/web app/backend/app/services/remote_inference.py"
click node_n_predict_post "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/predict_post.py"
click node_n_skill_inf "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skill_inference.py"
click node_n_skill_parse "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skill_parsing.py"
click node_n_router "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/route_and_predict_nb.py"
click node_n_model_utils "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/model_utils.py"
click node_n_eval "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/evaluate_outputs.py"
click node_n_langsmith "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/langsmith_workflows.py"
click node_n_profiles "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/profiles.json"
click node_n_skills_vocab "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skills.txt"
click node_n_adapters "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/tree/main/saves/llama31-8b"
click node_n_docs "https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/docs/index.html"

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_n_predict_post,node_n_skill_inf,node_n_skill_parse,node_n_router,node_n_model_utils toneBlue
class node_n_api,node_n_main,node_n_schema,node_n_service_factory,node_n_predict_adapter,node_n_remote toneAmber
class node_n_eval,node_n_langsmith,node_n_profiles,node_n_skills_vocab,node_n_adapters toneMint
class node_n_docs toneRose
class node_n_client toneNeutral
```

## Components

### Runtime pipeline

Live symbolic routing and prediction flow used for inference.

- [Predict flow](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/predict_post.py): runtime composition · Canonical request-response inference flow for a single example. · `symbolic-moe/predict_post.py`
- [Skill inference](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skill_inference.py): symbolic extractor · Converts raw text into ontology-level skills. · `symbolic-moe/skill_inference.py`
- [Skill parsing](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skill_parsing.py): normalization · Constrains and normalizes predicted skills for routing. · `symbolic-moe/skill_parsing.py`
- [NB router](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/route_and_predict_nb.py): expert router · Bernoulli Naive Bayes selector that chooses top experts. · `symbolic-moe/route_and_predict_nb.py`
- [Model utils](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/model_utils.py): adapter manager · Keeps the base model resident and swaps LoRA adapters. · `symbolic-moe/model_utils.py`

### Serving backend

FastAPI service that exposes the detection pipeline to clients.

- [Detect API](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/api/routes_detect.py): fastapi route · Primary POST endpoint for inference requests. · `web app/backend/app/api/routes_detect.py`
- [Backend main](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/main.py): service entrypoint · Application startup and API wiring. · `web app/backend/app/main.py`
- [API schemas](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/schemas.py): request models · Request and response shapes for the service contract. · `web app/backend/app/schemas.py`
- [Pipeline factory](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/services/pipeline_factory.py): service wiring · Chooses local or remote execution path. · `web app/backend/app/services/pipeline_factory.py`
- [Predict adapter](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/services/predict_post_adapter.py): bridge layer · Adapts backend requests to the symbolic prediction pipeline. · `web app/backend/app/services/predict_post_adapter.py`
- [Remote inference](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/HEAD/web%20app/backend/app/services/remote_inference.py): execution boundary · Separate remote or Colab-oriented execution path. · `web app/backend/app/services/remote_inference.py`

### Offline artifacts

Training, routing, and evaluation assets that support deployment.

- [Evaluation](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/evaluate_outputs.py): scoring and traces · Scores outputs and records evaluation traces. · `symbolic-moe/evaluate_outputs.py`
- [LangSmith](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/langsmith_workflows.py): observability · Trace capture, dataset upload, review queues, and analysis workflows. · `symbolic-moe/langsmith_workflows.py`
- [Profiles](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/profiles.json): offline artifacts · Learned expert profiles and skill pools for routing. · `symbolic-moe/profiles.json`
- [Skills vocab](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/symbolic-moe/skills.txt): ontology · Controlled skill vocabulary used by skill inference. · `symbolic-moe/skills.txt`
- [LoRA experts](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/tree/main/saves/llama31-8b): model artifacts · Task-specific adapter bundles for the specialist models. · `saves/llama31-8b`

### Presentation

Static project pages and demo-facing assets.

- [Docs site](https://github.com/muditbaid/skill-based-expert-routing-system-for-multilabel-hate-speech-detection/blob/main/docs/index.html): static presentation · GitHub Pages-style project page and assets. · `docs/index.html`

### Other components

- **Client / UI**: request source · Any external caller sending text for detection.

## Connections

- Client / UI → Detect API: POST /api/detect · Client sends text detection request.
- Detect API → API schemas: validates · Request and response payloads are shaped by schemas.
- Backend main → Detect API: mounts · Service entrypoint registers detection routes.
- Detect API → Pipeline factory: selects pipeline · API delegates execution path selection.
- Pipeline factory → Predict adapter: local path · Chooses in-process adapter-backed inference.
- Pipeline factory → Remote inference: remote path · Optionally routes to remote or Colab execution.
- Predict adapter → Predict flow: calls · Backend adapter bridges into canonical symbolic prediction flow.
- Predict flow → Skill inference: extracts skills · Raw text is converted into structured skills.
- Skill inference → Skill parsing: normalizes · Predicted skills are constrained to the stable ontology.
- Skill parsing → NB router: routes on · Normalized skills feed expert selection.
- NB router → Model utils: selects expert · Router chooses which adapter to activate for prediction.
- Model utils → LoRA experts: loads swaps · Shared base model switches among task-specific LoRA experts.
- Predict flow → LoRA experts: infers with · Final predictions are produced via the shared base model plus adapters.
- NB router → Profiles: trained from · Router is built from skill-annotated profile pools.
- Skill inference → Skills vocab: constrained by · Skill extraction uses the controlled vocabulary.
- Evaluation → Predict flow: scores outputs · Evaluation consumes runtime predictions and traces.
- LangSmith → Evaluation: supports · Observability layer captures traces and review workflows for evaluation.
- Docs site → Client / UI: informational · Static site provides project-facing presentation but not inference.
