The simplest RAG API for Python. Build a question and answer interface to your own content in minutes.
uvx fraggle index
uvx fraggle serve
curl -X POST http://localhost:8000/api/ask \
-H "Content-Type: application/json" \
-d '{"question": "What is Fraggle?"}'Fraggle is the successor to my badly named microllama project, modernised with:
- Provider-agnostic LLM support via any-llm
- Modern LangChain (0.3+)
- Simple deployment and usage
pip install fraggle- Prepare your content in a
source.jsonfile:
[
{
"content": "Fraggle is a RAG API for building Q&A interfaces.",
"title": "What is Fraggle",
"url": "https://example.com/docs"
},
{
"content": "You can use OpenAI or Anthropic models with Fraggle.",
"title": "Supported Models"
}
]- Set your API key:
export OPENAI_API_KEY="your-key-here"
# or
export ANTHROPIC_API_KEY="your-key-here"- Create an index of embeddings:
fraggle index- Start the API server:
fraggle serve- Query your content:
curl -X POST http://localhost:8000/api/ask \
-H "Content-Type: application/json" \
-d '{"question": "What is Fraggle?"}'Configure Fraggle with environment variables:
| Variable | Default | Description |
|---|---|---|
SOURCE_JSON_PATH |
source.json |
Path to your content JSON file |
INDEX_PATH |
faiss_index |
Path to store/load the FAISS index |
LLM_PROVIDER |
openai |
LLM provider: openai or anthropic |
LLM_MODEL |
gpt-4o-mini |
Model ID (e.g., gpt-4o, claude-3-5-sonnet-20241022) |
EMBEDDINGS_PROVIDER |
openai |
Embeddings provider |
EMBEDDINGS_MODEL |
text-embedding-3-small |
Embeddings model |
CHUNK_SIZE |
1000 |
Text chunk size for indexing |
CHUNK_OVERLAP |
100 |
Overlap between chunks |
K_CONTEXT_DOCS |
4 |
Number of documents to retrieve |
UVICORN_HOST |
0.0.0.0 |
Host to bind the server to |
UVICORN_PORT |
8000 |
Port to bind the server to |
export ANTHROPIC_API_KEY="your-key-here"
export LLM_PROVIDER="anthropic"
export LLM_MODEL="claude-3-5-sonnet-20241022"
fraggle serveStart the API server. Automatically serves the frontend at / if the frontend/ directory exists.
Create a FAISS index from your source documents.
Options:
--source: Path to source JSON file (default: source.json)--output: Path to save the index (default: faiss_index)
Generate a simple HTML frontend for your Q&A interface.
Options:
--output: Directory for frontend files (default: frontend)
Generate a Dockerfile for containerized deployment.
Non-streaming question answering.
Request:
{
"question": "What is Fraggle?"
}Response:
{
"answer": "Fraggle is a RAG API for building Q&A interfaces to your content."
}Streaming question answering (Server-Sent Events).
Request:
{
"question": "What is Fraggle?"
}Response: SSE stream of text chunks.
fraggle make-dockerfile
docker build -t fraggle .
docker run -p 8000:8000 -e OPENAI_API_KEY=your-key fraggleFor faster startup, create the index at build time by uncommenting the RUN fraggle index line in the Dockerfile.
# Clone the repo
git clone https://github.com/tomdyson/fraggle.git
cd fraggle
# Install with uv
uv sync
# Run in development mode
uv run fraggle serveFraggle improves on microllama by:
- Provider-agnostic: Use any LLM via any-llm
- Modern dependencies: LangChain 0.3+
- Better naming: Focus on RAG, not LLMs
- Same simple API and deployment story
MIT
Fraggle uses GitHub Actions to automatically publish to PyPI when you push a version tag:
# 1. Update the version in pyproject.toml
# 2. Commit and tag the release
git add pyproject.toml
git commit -m "Bump version to 0.1.x"
git tag v0.1.x
git push && git push --tagsThe GitHub Actions workflow will automatically build and publish to PyPI.
First-time setup: Configure PyPI Trusted Publishing at https://pypi.org/manage/account/publishing/ with:
- PyPI Project Name:
fraggle - Owner:
tomdyson - Repository:
fraggle - Workflow:
publish.yml - Environment:
pypi