Metadata-Version: 2.4
Name: ragbucket
Version: 0.1.2
Summary: Portable executable RAG artifacts for Python
Author: Anik Chand
License: MIT
License-File: LICENSE
Keywords: ai,faiss,groq,llm,machine-learning,rag,retrieval,vector-db
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: faiss-cpu
Requires-Dist: groq>=1.2.0
Requires-Dist: langchain
Requires-Dist: langchain-text-splitters>=1.1.2
Requires-Dist: numpy
Requires-Dist: pydantic
Requires-Dist: sentence-transformers
Description-Content-Type: text/markdown

# RagBucket

<div align="center">

### Portable Executable RAG Artifacts for Python

Build Retrieval-Augmented Generation systems as reusable, shareable, and executable `.rag` artifacts.

[PyPI](https://pypi.org/project/ragbucket/) • Portable RAG Runtime • Semantic Retrieval • Groq-Powered Generation

</div>

---

# Overview

Traditional machine learning models are portable.

```text
model.pt
model.onnx
model.gguf
```

They can be:

- saved
- shared
- deployed
- reused anywhere

But modern Retrieval-Augmented Generation (RAG) systems are different.

A typical RAG pipeline depends on:

- vector databases
- embedding models
- chunking logic
- retrievers
- metadata
- external storage systems

This makes RAG systems:

- fragmented
- difficult to distribute
- hard to reproduce
- tightly coupled to infrastructure

---

# Introducing `.rag`

RagBucket introduces:

# `.rag`

A portable executable artifact format for Retrieval-Augmented Generation systems.

The `.rag` artifact packages:

- semantic vector memory
- chunked knowledge
- retrieval metadata
- indexing structures
- runtime configuration

into a single reusable file.

---

# Core Philosophy

RagBucket treats RAG systems as:

# portable intelligence artifacts

instead of:

# fragmented retrieval pipelines

This allows developers to:

- package knowledge systems
- distribute semantic memory
- separate retrieval from generation
- reuse RAG artifacts across projects
- execute portable knowledge bases anywhere

---

# How It Works

```text
Documents
    ↓
RagBuilder
    ↓
model.rag
    ↓
RagRuntime
    ↓
Question Answering
```

The builder serializes the retrieval pipeline into a portable artifact.

The runtime loads the artifact and executes semantic retrieval using an external language model.

---

# What a `.rag` Artifact Contains

A `.rag` file stores everything required for retrieval:

- vector embeddings
- FAISS semantic index
- chunked document memory
- retrieval metadata
- artifact manifest
- runtime configuration

The only external dependency required during inference is:

- an LLM provider API key (Groq)

---

# Features

## Portable Artifact System

Serialize RAG knowledge systems into reusable `.rag` files.

## Semantic Retrieval Engine

Built-in FAISS vector indexing for fast semantic search.

## Lightweight Runtime

Load and execute `.rag` artifacts anywhere using Python.

## Groq Integration

Generate responses using Groq-hosted LLMs.

## Self-Contained Knowledge

Store retrieval memory locally inside the artifact.

## Simple Developer API

Minimal abstraction for building and querying artifacts.

## Extensible Architecture

Designed for future support of:

- hybrid retrieval
- reranking
- metadata filtering
- distributed vector stores

---

# Installation

## Using uv

```bash
uv add ragbucket
```

## Using pip

```bash
pip install ragbucket
```

---

# Creating a `.rag` Artifact

```python
from ragbucket import RagBuilder

builder = RagBuilder()

builder.build(
    documents_path="docs/",
    output_path="finance_assistant.rag"
)
```

This generates:

```text
finance_assistant.rag
```

containing:

- vector memory
- document chunks
- retrieval metadata
- semantic index

---

# Using a `.rag` Artifact

```python
from ragbucket import RagRuntime

rag = RagRuntime(
    rag_path="finance_assistant.rag",
    api_key="your_groq_api_key"
)

response = rag.ask(
    "What is EBITDA?"
)

print(response)
```

---

# Runtime Pipeline

```text
User Query
    ↓
Query Embedding
    ↓
FAISS Semantic Search
    ↓
Relevant Context Retrieval
    ↓
Groq LLM Generation
    ↓
Final Response
```

---

# Technology Stack

| Component       | Technology            |
| --------------- | --------------------- |
| Embeddings      | Sentence Transformers |
| Vector Search   | FAISS                 |
| Chunking        | LangChain             |
| Runtime         | Python                |
| Generation      | Groq                  |
| Packaging       | zipfile               |
| Artifact Format | `.rag`                |

---

# Why RagBucket Matters

Current RAG systems are deeply tied to infrastructure.

RagBucket introduces a cleaner abstraction:

```text
Knowledge
≠
Generation
```

The `.rag` artifact becomes:

- portable retrieval memory

while the external LLM becomes:

- the reasoning engine

This separation enables:

- reusable RAG systems
- portable semantic memory
- simplified deployment
- reproducible retrieval pipelines

---

# Current Scope

RagBucket currently supports:

- local artifact packaging
- FAISS vector indexing
- semantic retrieval
- Groq-powered generation

The project is intentionally lightweight and focused on:

# portable RAG execution

---

# Future Roadmap

## Planned Features

- Hybrid retrieval
- Metadata-aware search
- Artifact versioning
- Reranking support
- Multi-provider LLM runtime
- Milvus integration
- Distributed retrieval
- `.rag` registries and marketplaces

---

# Vision

RagBucket aims to become:

> “The portable runtime layer for Retrieval-Augmented Generation systems.”

A future where RAG systems can be:

- built once
- shared anywhere
- executed everywhere

through standardized portable intelligence artifacts.

---

# License

MIT License
