Metadata-Version: 2.4
Name: ragbucket
Version: 0.1.0
Summary: Portable executable RAG artifacts for Python
Author: Anik Chand
License: MIT
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

> Portable executable RAG artifacts for Python.

RagBucket introduces a portable `.rag` artifact format that packages:

- semantic vector memory
- chunked knowledge
- retrieval metadata
- RAG configuration

into a single reusable file.

Build once. Load anywhere.

---

# What is RagBucket?

Traditional machine learning models are portable:

- `model.pt`
- `model.onnx`
- `model.gguf`

But Retrieval-Augmented Generation (RAG) systems are fragmented.

A RAG pipeline usually depends on:

- vector databases
- embedding pipelines
- chunking logic
- metadata
- retrievers
- external storage

RagBucket solves this by introducing:

# `.rag`

A portable executable RAG artifact format.

---

# Core Idea

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

The `.rag` artifact contains:

- vector embeddings
- FAISS index
- document chunks
- retrieval metadata
- configuration manifest

allowing RAG systems to become:

- portable
- reusable
- shareable
- executable

---

# Features

- Portable `.rag` artifact format
- Built-in FAISS vector indexing
- Semantic retrieval pipeline
- Groq-powered answer generation
- Lightweight architecture
- Fully local artifact packaging
- Simple Python API
- Extensible runtime design

---

# Installation

## Using uv

```bash
uv add ragbucket
```

---

## Using pip

```bash
pip install ragbucket
```

---

# Build a `.rag` Artifact

```python
from ragbucket import RagBuilder

builder = RagBuilder()

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

This generates:

```text
finance_bot.rag
```

---

# Use a `.rag` Artifact

```python
from ragbucket import RagRuntime

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

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

print(response)
```

---

# Internal `.rag` Structure

```text
finance_bot.rag
│
├── vectors.faiss
├── chunks.json
├── manifest.json
```

---

# Architecture

```text
Raw Documents
↓
Chunker
↓
Embedding Engine
↓
FAISS Indexer
↓
Packager
↓
.rag Artifact
↓
Runtime Loader
↓
Semantic Retrieval
↓
LLM Generation
```

---

# Current Stack

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

---

# Example Workflow

## Step 1 — Create Artifact

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

## Step 2 — Load Artifact

```python
rag = RagRuntime(
    rag_path="demo.rag",
    api_key="..."
)
```

## Step 3 — Ask Questions

```python
rag.ask("What are transformers?")
```

---

# Why RagBucket?

RagBucket treats RAG systems as:

# portable intelligence artifacts

instead of:

# fragmented pipelines.

This allows developers to:

- package knowledge systems
- distribute RAG artifacts
- reuse retrieval memory
- separate knowledge from generation

---

# Roadmap

## Phase 1

- `.rag` artifact builder
- FAISS serialization
- runtime loading

## Phase 2

- configurable retrieval
- metadata filtering
- hybrid search

## Phase 3

- Milvus support
- reranking
- evaluation pipelines

## Phase 4

- distributed artifact registry
- `.rag` marketplace
- runtime optimization

---

# Project Structure

```text
ragbucket/
│
├── builder/
├── runtime/
├── schemas/
├── utils/
└── constants.py
```

---

# License

MIT License

---

# Vision

RagBucket aims to become:

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