ragbucket 0.1.0

Portable executable RAG artifacts for Python

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

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

uv add ragbucket

---

Using pip

pip install ragbucket

---

Build a .rag Artifact

from ragbucket import RagBuilder

builder = RagBuilder()

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

This generates:

finance_bot.rag

---

Use a .rag Artifact

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

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

---

Architecture

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

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

Step 2 — Load Artifact

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

Step 3 — Ask Questions

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

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

---

License

MIT License

---

Vision

RagBucket aims to become:

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