syrag 0.1.0__tar.gz

syrag-0.1.0/.env.example

@@ -0,0 +1,12 @@
+SYRAG_APP_NAME=SyRAG
+SYRAG_APP_VERSION=0.1.0
+SYRAG_ENVIRONMENT=development
+SYRAG_HOST=127.0.0.1
+SYRAG_PORT=8000
+SYRAG_RELOAD=true
+SYRAG_DEFAULTS__EMBEDDER=default
+SYRAG_DEFAULTS__VECTOR_STORE=memory
+SYRAG_DEFAULTS__LLM=grounded
+SYRAG_BOOTSTRAP__REGISTER_IN_MEMORY_DEFAULTS=true
+SYRAG_PROVIDERS__IN_MEMORY__EMBEDDER_DIMENSIONS=16
+SYRAG_PROVIDERS__IN_MEMORY__LLM_MAX_CONTEXT_DOCUMENTS=3

syrag-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Local agent/editor metadata
+.codex
+.codex/
+.gemini/

syrag-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to SyRAG will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-30
+
+### Added
+
+- Added the `SyRAG` application wrapper on top of FastAPI.
+- Added typed ingest and query decorators.
+- Added typed request, response, document, chunk, citation, and request-context schemas.
+- Added protocol-based extension points for chunking, embedding, vector storage, retrieval, prompt assembly, generation policy, LLM generation, request context, auth, rate limiting, and safety validation.
+- Added in-memory providers for local development and tests.
+- Added optional Chroma vector store provider behind the `chroma` extra.
+- Added `SQLiteVectorStore` for lightweight persistent vector storage.
+- Added optional OpenAI embedder and LLM providers behind the `openai` extra.
+- Added tenant-aware request context and tenant normalization.
+- Added structured SyRAG error responses with stage and category metadata.
+- Added OpenTelemetry-compatible tracing integration.
+- Added structured logging and JSON log formatting.
+- Added default rate limiting and safety guard implementations.
+- Added OpenAPI examples and documented framework route responses.
+- Added a downstream testing toolkit with fake providers and ASGI client helpers.
+- Added provider contract tests across first-party provider implementations.
+- Added cookbook documentation for Qdrant, LangChain, LangGraph, and LlamaIndex RAG integration patterns.
+- Added package extras for `chroma`, `openai`, `testing`, `server`, and `all`.
+- Added a minimal OpenAI and Chroma-backed application example.
+- Added release, contribution, security, and community documentation for open-source use.
+- Added CI for linting, type checking, tests, package building, and package metadata checks.
+- Added tag-driven PyPI publishing workflow through PyPI Trusted Publishing.
+
+### Changed
+
+- Renamed the public package, import namespace, CLI, and framework branding to `syrag` / `SyRAG` before the first public release.
+- Set supported Python versions to `3.12` and `3.13`.
+- Updated first-time-user documentation to use OpenAI-backed generation and embeddings with a local vector store.
+
+### Notes
+
+- This is the first planned public release.

syrag-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our standard
+
+Participation in this project should remain respectful, direct, and constructive.
+
+Expected behavior:
+
+- discuss technical issues in good faith
+- give clear, actionable feedback
+- assume mistakes can be corrected without hostility
+- keep criticism focused on ideas, code, and behavior
+
+Unacceptable behavior:
+
+- harassment or personal attacks
+- discriminatory language
+- doxxing, threats, or intimidation
+- repeated bad-faith disruption of discussions or review
+
+## Enforcement
+
+Project maintainers may remove comments, issues, pull requests, or contributors
+that violate these standards.
+
+## Reporting
+
+Until a public project contact is published, report serious conduct concerns
+privately to the maintainer through the repository host once the project is
+public.

syrag-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for contributing to SyRAG.
+
+## Development setup
+
+1. Install Python `3.12` or `3.13`.
+2. Install dependencies with `uv sync`.
+3. Run checks before opening a change:
+
+```bash
+env UV_CACHE_DIR=/tmp/uv-cache uv run ruff check .
+env UV_CACHE_DIR=/tmp/uv-cache uv run mypy .
+env UV_CACHE_DIR=/tmp/uv-cache uv run pytest
+```
+
+## Scope
+
+Contributions should preserve these project constraints:
+
+- keep the public framework surface explicit and typed
+- avoid adding heavy provider-specific dependencies to the core package
+- prefer small, well-tested changes over large speculative rewrites
+
+## Pull requests
+
+- include tests for behavior changes
+- update docs when the public API or package behavior changes
+- avoid unrelated refactors in the same change
+- keep compatibility claims aligned with the actual tested runtime matrix
+
+## Reporting issues
+
+When reporting a bug, include:
+
+- Python version
+- installed extras, if any
+- minimal reproduction steps
+- expected behavior
+- actual behavior

syrag-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Abdelaziz Marzoug
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

syrag-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: syrag
+Version: 0.1.0
+Summary: Production-oriented Python framework for building RAG services on top of FastAPI.
+Project-URL: Repository, https://github.com/a-marzoug/syrag
+Project-URL: Issues, https://github.com/a-marzoug/syrag/issues
+Project-URL: Documentation, https://github.com/a-marzoug/syrag/tree/main/docs
+Author: A. Marzoug
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai,fastapi,llm,rag,retrieval-augmented-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.12
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: opentelemetry-api>=1.0.0
+Requires-Dist: pydantic-settings>=2.13.1
+Provides-Extra: all
+Requires-Dist: chromadb>=1.0.0; extra == 'all'
+Requires-Dist: httpx>=0.28.1; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'all'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=1.0.0; extra == 'chroma'
+Provides-Extra: openai
+Requires-Dist: httpx>=0.28.1; extra == 'openai'
+Provides-Extra: server
+Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'server'
+Provides-Extra: testing
+Requires-Dist: httpx>=0.28.1; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# 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:
+
+```bash
+pip install syrag
+```
+
+Optional integrations:
+
+```bash
+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:
+
+```bash
+pip install "syrag[chroma,openai,server]"
+```
+
+Set `OPENAI_API_KEY` in your environment before starting the app.
+
+Create `main.py`:
+
+```python
+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:
+
+```bash
+uvicorn main:app.api --reload
+```
+
+The framework exposes:
+
+- `POST /ingest`
+- `POST /query`
+- `GET /health`
+- OpenAPI docs at `/docs`
+
+Ingest a document:
+
+```bash
+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:
+
+```bash
+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](docs/index.md)
+- [Overview](docs/overview.md)
+- [Architecture](docs/architecture.md)
+- [Component contracts](docs/component-contracts.md)
+- [Cookbook](docs/cookbook/index.md)
+- [Provider examples](docs/provider-examples.md)
+- [Releasing](docs/releasing.md)
+- [MVP status](docs/mvp-roadmap.md)
+
+## Examples
+
+- [Minimal app](examples/minimal_app.py)
+
+## Cookbook
+
+- [Qdrant vector store pipeline](docs/cookbook/qdrant.md)
+- [LangChain + Qdrant RAG](docs/cookbook/langchain.md)
+- [LangChain agent with SyRAG tool](examples/integrations/langchain_syrag_agent.py)
+- [LangGraph + SyRAG RAG workflow](docs/cookbook/langgraph.md)
+- [LlamaIndex + Qdrant RAG](docs/cookbook/llamaindex.md)
+
+Full example scripts live in [examples/integrations](examples/integrations).

syrag-0.1.0/README.md

@@ -0,0 +1,209 @@
+# 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:
+
+```bash
+pip install syrag
+```
+
+Optional integrations:
+
+```bash
+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:
+
+```bash
+pip install "syrag[chroma,openai,server]"
+```
+
+Set `OPENAI_API_KEY` in your environment before starting the app.
+
+Create `main.py`:
+
+```python
+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:
+
+```bash
+uvicorn main:app.api --reload
+```
+
+The framework exposes:
+
+- `POST /ingest`
+- `POST /query`
+- `GET /health`
+- OpenAPI docs at `/docs`
+
+Ingest a document:
+
+```bash
+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:
+
+```bash
+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](docs/index.md)
+- [Overview](docs/overview.md)
+- [Architecture](docs/architecture.md)
+- [Component contracts](docs/component-contracts.md)
+- [Cookbook](docs/cookbook/index.md)
+- [Provider examples](docs/provider-examples.md)
+- [Releasing](docs/releasing.md)
+- [MVP status](docs/mvp-roadmap.md)
+
+## Examples
+
+- [Minimal app](examples/minimal_app.py)
+
+## Cookbook
+
+- [Qdrant vector store pipeline](docs/cookbook/qdrant.md)
+- [LangChain + Qdrant RAG](docs/cookbook/langchain.md)
+- [LangChain agent with SyRAG tool](examples/integrations/langchain_syrag_agent.py)
+- [LangGraph + SyRAG RAG workflow](docs/cookbook/langgraph.md)
+- [LlamaIndex + Qdrant RAG](docs/cookbook/llamaindex.md)
+
+Full example scripts live in [examples/integrations](examples/integrations).

syrag-0.1.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected security vulnerabilities.
+
+Until a dedicated security contact is published, report vulnerabilities
+privately to the maintainer through the repository host once the project is
+public.
+
+When reporting a vulnerability, include:
+
+- affected version
+- impact summary
+- reproduction steps or proof of concept
+- any suggested mitigation if available
+
+## Scope
+
+Security reports are most useful when they affect:
+
+- request authentication and authorization hooks
+- tenant isolation
+- provider request handling
+- data leakage across query or ingest boundaries
+- denial-of-service or resource exhaustion paths