ragbucket 0.1.2

Portable executable RAG artifacts for Python

RagBucket

Portable Executable RAG Artifacts for Python

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

PyPI • Portable RAG Runtime • Semantic Retrieval • Groq-Powered Generation

---

Overview

Traditional machine learning models are portable.

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

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

uv add ragbucket

Using pip

pip install ragbucket

---

Creating a .rag Artifact

from ragbucket import RagBuilder

builder = RagBuilder()

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

This generates:

finance_assistant.rag

containing:

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

---

Using a .rag Artifact

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

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:

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