diff --git a/.gitignore b/.gitignore index cddd2625..4baba5d4 100644 --- a/.gitignore +++ b/.gitignore @@ -162,4 +162,9 @@ cython_debug/ # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. .idea/ + +# MacOS **/.DS_Store + +# VSCode +.vscode/ diff --git a/README.md b/README.md index acb69d55..2402873c 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,9 @@ # Ragna -## Local install +> **Note** +> This project is in active development. -```bash -$ conda env create --file environment.yml -$ conda activate ragna-dev -$ pip install --editable '.[complete]' -$ ragna --version -$ ragna ls -``` +## Local development -## Minimal example - -```python -import asyncio - -from ragna import Rag -from ragna.assistant import RagnaDemoAssistant -from ragna.source_storage import RagnaDemoSourceStorage - - -async def main(): - rag = Rag() - - path = "ragna.txt" - with open(path, "w") as file: - file.write("Ragna is an OSS RAG app with Python and REST API.\n") - - async with await rag.new_chat( - documents=[path], - source_storage=RagnaDemoSourceStorage, - assistant=RagnaDemoAssistant, - ) as chat: - print(await chat.answer("What is Ragna?")) - - -# This is only needed when running module as script. -# If inside a notebook, the code inside the main function can be run directly. -if __name__ == "__main__": - asyncio.run(main()) -``` - -## Documentation - -Ragna uses Sphinx to build it's documentation. - -You can contribute to the documentation at `docs/source`, -and start a development build that auto-refreshes on new changes with: - -```bash -sphinx-autobuild docs/source docs/build/html -``` - -which serves the docs website at [http://127.0.0.1:8000](http://127.0.0.1:8000). +* Setup: [docs/community/contribute.md](docs/community/contribute.md) +* Quickstart: [docs/get-started.md](docs/get-started.md#minimal-example) diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/community/brand.md b/docs/community/brand.md new file mode 100644 index 00000000..2ecb1dcf --- /dev/null +++ b/docs/community/brand.md @@ -0,0 +1 @@ +# Brand guidelines diff --git a/docs/community/contribute.md b/docs/community/contribute.md new file mode 100644 index 00000000..f9a4bf23 --- /dev/null +++ b/docs/community/contribute.md @@ -0,0 +1,49 @@ +# Contribute to Ragna + + + +## Fork and clone the repository + +```bash +git clone https://github.com//ragna.git +``` + +## Set up development environment + +Create and activate a conda environment: + +```bash +conda env create --file environment.yaml +conda activate ragna-dev +``` + +## Contribute code + +Install Ragna in editable mode: + +```bash +pip install --editable '.[complete]' +``` + +Verify your installation: + +```bash +ragna --version +ragna ls +``` + +## Contribute documentation + +Ragna uses MkDocs to build it's documentation. + +You can contribute to narrative documentation at `docs/`, +and configure the docs website using `mkdocs.yml` + +To start a development build that auto-refreshes on new changes, +run the following from the root directory: + +```bash +mkdocs serve +``` + +This serves the docs website at [http://127.0.0.1:8000](http://127.0.0.1:8000). diff --git a/docs/explanations/understand-rag.md b/docs/explanations/understand-rag.md new file mode 100644 index 00000000..02df1c34 --- /dev/null +++ b/docs/explanations/understand-rag.md @@ -0,0 +1 @@ +# What is RAG? diff --git a/docs/get-started.md b/docs/get-started.md new file mode 100644 index 00000000..a640c909 --- /dev/null +++ b/docs/get-started.md @@ -0,0 +1,37 @@ +# Get started + +## Installation + + + + +## Minimal example + +```python +import asyncio + +from ragna import Rag +from ragna.assistant import RagnaDemoAssistant +from ragna.source_storage import RagnaDemoSourceStorage + + +async def main(): + rag = Rag() + + path = "ragna.txt" + with open(path, "w") as file: + file.write("Ragna is an OSS RAG app with Python and REST API.\n") + + async with await rag.new_chat( + documents=[path], + source_storage=RagnaDemoSourceStorage, + assistant=RagnaDemoAssistant, + ) as chat: + print(await chat.answer("What is Ragna?")) + + +# This is only needed when running module as script. +# If inside a notebook, the code inside the main function can be run directly. +if __name__ == "__main__": + asyncio.run(main()) +``` diff --git a/docs/source/index.md b/docs/index.md similarity index 55% rename from docs/source/index.md rename to docs/index.md index 7aeb7eb0..9e52ef9e 100644 --- a/docs/source/index.md +++ b/docs/index.md @@ -1,10 +1,16 @@ -# Ragna +--- +title: Welcome +--- - +# Ragna -Ragna is a toolkit for building RAG-based LLM applications. +A toolkit for building RAG-based LLM applications, it provides: -It provides: * **Python API** for RAG orchestration * **REST API** for building web applications * **Ready-to-use web application** with UI for uploading documents, selecting models, and chat interface. + + diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 747ffb7b..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/references/changelog.md b/docs/references/changelog.md new file mode 100644 index 00000000..d7de275f --- /dev/null +++ b/docs/references/changelog.md @@ -0,0 +1 @@ +# Release notes diff --git a/docs/references/cli.md b/docs/references/cli.md new file mode 100644 index 00000000..340209fd --- /dev/null +++ b/docs/references/cli.md @@ -0,0 +1 @@ +# CLI reference diff --git a/docs/references/python-api.md b/docs/references/python-api.md new file mode 100644 index 00000000..7bbec0b5 --- /dev/null +++ b/docs/references/python-api.md @@ -0,0 +1 @@ +# Python API reference diff --git a/docs/references/rest-api.md b/docs/references/rest-api.md new file mode 100644 index 00000000..2fdd5e02 --- /dev/null +++ b/docs/references/rest-api.md @@ -0,0 +1 @@ +# REST API reference diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 82d0679c..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,48 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html -import datetime -import importlib.metadata - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "Ragna" -metadata = importlib.metadata.metadata("Ragna") - -author = ", ".join( - author_email.split("<", 1)[0].strip() - for author_email in metadata["Author-email"].split(",") -) -copyright = f"{datetime.datetime.today().year}, {author}" - -release = metadata["Version"] -version = ".".join(release.split(".")[:2]) - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - # https://myst-parser.readthedocs.io/en/latest/intro.html - "myst_parser", - # https://sphinx-design.readthedocs.io/en/latest/index.html - "sphinx_design", - # https://sphinx-inline-tabs.readthedocs.io/en/latest/ - "sphinx_inline_tabs", - # https://sphinx-copybutton.readthedocs.io/en/latest/ - "sphinx_copybutton", - # https://sphinxext-opengraph.readthedocs.io/en/latest/ - "sphinxext.opengraph", -] - -templates_path = ["_templates"] -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -# https://pradyunsg.me/furo/ -html_theme = "furo" -html_static_path = ["_static"] diff --git a/docs/tutorials/python-api.md b/docs/tutorials/python-api.md new file mode 100644 index 00000000..8a19e5e2 --- /dev/null +++ b/docs/tutorials/python-api.md @@ -0,0 +1 @@ +# Use the Python API diff --git a/docs/tutorials/rest-api.md b/docs/tutorials/rest-api.md new file mode 100644 index 00000000..a1b30685 --- /dev/null +++ b/docs/tutorials/rest-api.md @@ -0,0 +1 @@ +# Explore the REST API diff --git a/docs/tutorials/web-app.md b/docs/tutorials/web-app.md new file mode 100644 index 00000000..9ddf0695 --- /dev/null +++ b/docs/tutorials/web-app.md @@ -0,0 +1 @@ +# Set up a web application diff --git a/environment.yml b/environment.yml index f0b48646..5e1962ec 100644 --- a/environment.yml +++ b/environment.yml @@ -14,10 +14,6 @@ dependencies: - mypy - pre-commit # documentation - - sphinx - - myst-parser - - sphinx-copybutton - - furo - - sphinx-design - - sphinx-inline-tabs - - sphinxext-opengraph + - mkdocs + - mkdocs-material + - mkdocstrings diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..c95c7bbb --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,5 @@ +site_name: Ragna +theme: + name: material + features: + - navigation.sections