# niravrvaghasiya/skill-intelligence-engine architecture

> Architecture diagram of the GitHub repository niravrvaghasiya/skill-intelligence-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niravrvaghasiya/skill-intelligence-engine
- Repository: https://github.com/niravrvaghasiya/skill-intelligence-engine

## Overview

Skill Intelligence Engine (SIE) is a corpus-agnostic library, CLI, and small API for finding and explaining relevant skills in SKILL.md collections. Its main workflow loads a corpus, chunks skill text, retrieves candidates with BM25 and optionally dense search, fuses and optionally reranks them, then reports confidence and a route/clarify/abstain decision. Separate capabilities compose multi-intent plans and derive learning paths from declared skill relationships. The graph follows documented entry points and sampled ownership; some subsystem wiring is based on README capabilities and the file tree.

Main entry points: [`sie/router.py`](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/router.py) (CLI and router), [`sie/engine.py`](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/engine.py) (Engine), [`sie/api.py`](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/api.py) (HTTP API), [`sie/index/dense.py`](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/dense.py) (Dense index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces and orchestration"]
  node_api["HTTP API<br/>[api.py]"]
  node_engine["Engine<br/>[engine.py]"]
  node_router["CLI and router<br/>[router.py]"]
end

subgraph group_retrieval["Retrieval and ranking"]
  node_chunking["Text chunking<br/>[chunking.py]"]
  node_sparse["BM25 index<br/>[sparse.py]"]
  node_dense["Dense index<br/>[dense.py]"]
  node_vector_store[("Persisted vectors")]
  node_fusion["Rank fusion<br/>[fuse.py]"]
  node_rerank["Cross-encoder reranker<br/>[rerank.py]"]
end

subgraph group_skills["Corpus and skill graph"]
  node_ingest["Corpus ingestion<br/>[ingest.py]"]
  node_corpus["Loaded skills<br/>[corpus.py]"]
  node_graph_build["Relationship graph<br/>[build.py]"]
end

subgraph group_planning["Planning and results"]
  node_confidence["Confidence decision<br/>[confidence.py]"]
  node_compose["Multi-intent composition<br/>[compose.py]"]
  node_learning_path["Learning paths<br/>[paths.py]"]
  node_result["Ranked skill results<br/>[models.py]"]
end

node_user(("Task requester"))
node_corpus_input["SKILL.md corpus"]

node_user -->|"submits task"| node_api
node_api -->|"dispatches"| node_engine
node_user -.->|"runs query"| node_router
node_corpus_input -->|"loads files"| node_ingest
node_ingest -->|"creates skills"| node_corpus
node_engine -->|"uses retrieval"| node_router
node_engine -->|"builds graph"| node_graph_build
node_router -->|"chunks skills"| node_chunking
node_router -->|"searches BM25"| node_sparse
node_router -.->|"searches vectors"| node_dense
node_dense -->|"reads and writes"| node_vector_store
node_router -->|"fuses rankings"| node_fusion
node_router -.->|"reranks candidates"| node_rerank
node_router -->|"assesses route"| node_confidence
node_router -->|"returns ranking"| node_result
node_engine -->|"plans intents"| node_compose
node_engine -->|"requests path"| node_learning_path
node_graph_build -->|"supplies relations"| node_learning_path
node_api -->|"returns response"| node_result

click node_api "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/api.py"
click node_engine "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/engine.py"
click node_router "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/router.py"
click node_ingest "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/ingest.py"
click node_corpus "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/corpus.py"
click node_chunking "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/chunking.py"
click node_sparse "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/sparse.py"
click node_dense "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/dense.py"
click node_fusion "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/fuse.py"
click node_rerank "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/rerank.py"
click node_confidence "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/confidence.py"
click node_compose "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/compose.py"
click node_graph_build "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/graph/build.py"
click node_learning_path "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/graph/paths.py"
click node_result "https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/models.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_api,node_engine,node_router toneBlue
class node_chunking,node_sparse,node_dense,node_vector_store,node_fusion,node_rerank toneAmber
class node_ingest,node_corpus,node_graph_build toneMint
class node_confidence,node_compose,node_learning_path,node_result,node_user toneRose
class node_corpus_input toneIndigo
```

## Components

### Interfaces and orchestration

- [HTTP API](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/api.py): `sie/api.py`
- [Engine](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/engine.py): `sie/engine.py`
- [CLI and router](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/router.py): `sie/router.py`

### Retrieval and ranking

- [Text chunking](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/chunking.py): `sie/chunking.py`
- [BM25 index](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/sparse.py): `sie/index/sparse.py`
- [Dense index](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/dense.py): `sie/index/dense.py`
- **Persisted vectors**
- [Rank fusion](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/index/fuse.py): `sie/index/fuse.py`
- [Cross-encoder reranker](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/rerank.py): `sie/rerank.py`

### Corpus and skill graph

- [Corpus ingestion](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/ingest.py): `sie/ingest.py`
- [Loaded skills](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/corpus.py): `sie/corpus.py`
- [Relationship graph](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/graph/build.py): `sie/graph/build.py`

### Planning and results

- [Confidence decision](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/confidence.py): `sie/confidence.py`
- [Multi-intent composition](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/compose.py): `sie/compose.py`
- [Learning paths](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/graph/paths.py): `sie/graph/paths.py`
- [Ranked skill results](https://github.com/niravrvaghasiya/skill-intelligence-engine/blob/main/sie/models.py): `sie/models.py`

### Other components

- **Task requester**
- **SKILL.md corpus**

## Connections

- Task requester → HTTP API: submits task
- HTTP API → Engine: dispatches
- Task requester → CLI and router: runs query
- SKILL.md corpus → Corpus ingestion: loads files
- Corpus ingestion → Loaded skills: creates skills
- Engine → CLI and router: uses retrieval
- Engine → Relationship graph: builds graph
- CLI and router → Text chunking: chunks skills
- CLI and router → BM25 index: searches BM25
- CLI and router → Dense index: searches vectors
- Dense index → Persisted vectors: reads and writes
- CLI and router → Rank fusion: fuses rankings
- CLI and router → Cross-encoder reranker: reranks candidates
- CLI and router → Confidence decision: assesses route
- CLI and router → Ranked skill results: returns ranking
- Engine → Multi-intent composition: plans intents
- Engine → Learning paths: requests path
- Relationship graph → Learning paths: supplies relations
- HTTP API → Ranked skill results: returns response