syrag 0.1.0

Production-oriented Python framework for building RAG services on top of FastAPI.

SyRAG

SyRAG is a production-oriented Python framework for building Retrieval-Augmented Generation services with a small, typed API on top of FastAPI.

Supported Python versions: 3.12 and 3.13.

It currently ships:

• SyRAG application wrapper plus create_app()
• @app.ingest(...) and @app.query(...) decorators
• typed request and response schemas
• in-memory providers for local development
• Chroma vector store behind the chroma extra
• SQLite vector store in core and OpenAI providers behind the openai extra
• request context, auth hooks, tenant scoping, rate limiting, and safety guards
• OpenAPI docs, structured logging, and OpenTelemetry-compatible tracing
• a testing toolkit with fake providers and ASGI client helpers

Installation

Core package:

pip install syrag

Optional integrations:

pip install "syrag[chroma]"
pip install "syrag[openai]"
pip install "syrag[testing]"
pip install "syrag[server]"
pip install "syrag[all]"

Quick Start

Install the runtime integrations used in this example:

pip install "syrag[chroma,openai,server]"

Set OPENAI_API_KEY in your environment before starting the app.

Create main.py:

import os
from pathlib import Path

from syrag import (
    SyRAG,
    ChromaVectorStore,
    IngestRequest,
    OpenAIEmbedder,
    OpenAILLM,
    QueryRequest,
    Settings,
)

app = SyRAG(
    title="Support Bot",
    version="0.1.0",
    description="Internal support assistant",
    settings=Settings(),
)

app.register_embedder(
    "default",
    OpenAIEmbedder(
        api_key=os.environ["OPENAI_API_KEY"],
        model="text-embedding-3-small",
    ),
)
app.register_vector_store(
    "default",
    ChromaVectorStore(path=Path(".syrag/chroma"), collection_name="support_docs"),
)
app.register_llm(
    "default",
    OpenAILLM(api_key=os.environ["OPENAI_API_KEY"], model="gpt-4.1-mini"),
)
app.configure_defaults(
    embedder="default",
    vector_store="default",
    llm="default",
)


@app.ingest("/ingest")
async def ingest(request: IngestRequest) -> IngestRequest:
    return request


@app.query("/query")
async def query(request: QueryRequest) -> QueryRequest:
    return request

Serve the app with any ASGI server. With the server extra installed:

uvicorn main:app.api --reload

The framework exposes:

• POST /ingest
• POST /query
• GET /health
• OpenAPI docs at /docs

Ingest a document:

curl -X POST http://127.0.0.1:8000/ingest \
  -H "content-type: application/json" \
  -d '{"documents":["SyRAG builds typed RAG services."],"collection":"demo"}'

Query it:

curl -X POST http://127.0.0.1:8000/query \
  -H "content-type: application/json" \
  -d '{"query":"What does SyRAG build?","collection":"demo","top_k":1}'

Extension Points

SyRAG keeps the pipeline explicit. You can swap or extend:

• Chunker
• Embedder
• VectorStore
• RetrievalStrategy
• PromptAssembler
• GenerationPolicy
• LLM
• RequestContextHook
• AuthHook
• RateLimiter
• SafetyGuard

First-Party Providers

Core:

• InMemoryEmbedder
• InMemoryVectorStore
• InMemoryLLM
• PassThroughChunker
• SQLiteVectorStore

Optional chroma extra:

• ChromaVectorStore

Optional openai extra:

• OpenAIEmbedder
• OpenAILLM

Observability And Operations

SyRAG includes:

• structured error responses with stage information
• request-scoped RequestContext with request IDs and tenant IDs
• StructuredLogging and JSONLogFormatter
• OpenTelemetryTracing built on the OpenTelemetry API package
• request throttling via InMemoryRateLimiter
• payload validation via DefaultSafetyGuard

Testing

Install the testing extra to use:

• create_test_app(...)
• create_test_client(...)
• seed_documents(...)
• fake providers such as FakeEmbedder, FakeVectorStore, and FakeLLM

Docs

• Docs index
• Overview
• Architecture
• Component contracts
• Cookbook
• Provider examples
• Releasing
• MVP status

Examples

• Minimal app

Cookbook

• Qdrant vector store pipeline
• LangChain + Qdrant RAG
• LangChain agent with SyRAG tool
• LangGraph + SyRAG RAG workflow
• LlamaIndex + Qdrant RAG

Full example scripts live in examples/integrations.