# serpent

**Repository Path**: efreets/serpent

## Basic Information

- **Project Name**: serpent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <picture>
    <img alt="Serpent Logo" src="logo.svg" height="25%" width="25%">
  </picture>
<br>

<h2>Serpent</h2>

[![Tests](https://img.shields.io/github/actions/workflow/status/CogitatorTech/serpent/tests.yml?label=tests&style=flat&labelColor=282c34&logo=github)](https://github.com/CogitatorTech/serpent/actions/workflows/tests.yml)
[![Code Quality](https://img.shields.io/codefactor/grade/github/CogitatorTech/serpent?label=code%20quality&style=flat&labelColor=282c34&logo=codefactor)](https://www.codefactor.io/repository/github/CogitatorTech/serpent)
[![Docs](https://img.shields.io/badge/docs-read-blue?style=flat&labelColor=282c34&logo=read-the-docs)](https://cogitatortech.github.io/serpent/)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-007ec6?style=flat&labelColor=282c34&logo=open-source-initiative)](https://github.com/CogitatorTech/serpent)

A modular RAG framework for C++

</div>

---

Serpent is a small C++ framework for building RAG (retrieval-augmented generation) pipelines and AI-powered applications.

## Features

- **Modular Design**: Swap components via clean interfaces
- **Hybrid Search**: hnswlib (dense) + BM25 (sparse) + RRF fusion
- **Dual LLM Support**: Local models (llama.cpp) + Cloud APIs (OpenRouter)
- **Document Loaders**: PDF, DOCX, and plain text

---

## Architecture

```mermaid
graph TB
    subgraph Loaders["Document Loaders"]
        TXT["TextLoader"]
        PDF["PdfLoader"]
        DOCX["DocxLoader"]
    end

    subgraph Chunking["Text Chunking"]
        RC["RecursiveChunker"]
    end

    subgraph Core["Core"]
        DS["MemoryDocumentStore"]
        SQL["SqliteStore"]
    end

    subgraph Retrieval["Retrieval"]
        HNSW["HNSWStore<br/>(Dense Vectors)"]
        BM25["BM25Index<br/>(Sparse)"]
        HR["HybridRetriever"]
        RRF["RRF Fusion"]
    end

    subgraph Providers["LLM Providers"]
        LLAMA["LlamaCppProvider<br/>(Local)"]
        OR["OpenRouterProvider<br/>(Cloud)"]
    end

    subgraph Utils["Utilities"]
        MM["ModelManager"]
    end

    TXT & PDF & DOCX --> RC
    RC --> DS
    DS --> SQL
    DS --> HNSW & BM25
    HNSW & BM25 --> HR
    HR --> RRF
    RRF --> LLAMA & OR
    MM --> LLAMA
```

---

## Quickstart

To be added.

---

## Documentation

To be added.

---

### Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to make a contribution.

### License

Serpent is available under either of the following licenses:

* MIT License ([LICENSE-MIT](LICENSE-MIT))
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))

### Acknowledgements

* The logo is from [here](https://www.svgrepo.com/svg/405246/dragon) with some modifications.