Add docs

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[docs]
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: github-pages
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

Makefile

@@ -13,7 +13,7 @@ ifndef UV_VERSION
 	UV_VERSION := 0.8.0
 endif
 
-.PHONY: uv_check venv sync update format lint test release
+.PHONY: uv_check venv sync update format lint test docs docs-server release
 
 # Check installed UV version and install if needed
 uv_check:
@@ -82,6 +82,17 @@ lint:
 test:
 	@python -B -m pytest -v --cov=$(SOURCES_PATH) --rootdir=$(TESTS_PATH)
 
+# Build and serve documentation locally
+docs-server:
+	@echo '# Starting documentation server...'
+	@mkdocs serve --dev-addr 127.0.0.1:8000
+
+# Build documentation for production
+docs:
+	@echo '# Building documentation...'
+	@mkdocs build --clean
+	@echo '...documentation built in site/ directory!'
+
 release: lint test
 	@echo '# Preparing release...'
 	@uv build

README.md

@@ -1,7 +1,9 @@
 # 🏎️ draive 🏁
 
+[![PyPI](https://img.shields.io/pypi/v/draive)](https://pypi.org/project/draive/)
 ![Python Version](https://img.shields.io/badge/Python-3.12+-blue)
 ![License](https://img.shields.io/badge/License-MIT-green)
+[![Docs](https://img.shields.io/badge/Documentation-yellow)](https://miquido.github.io/draive/)
 ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/miquido/draive?utm_source=oss&utm_medium=github&utm_campaign=miquido%2Fdraive&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
 
 🏎️ An all-in-one, flexible Python library for building powerful LLM workflows and AI apps. 🏎️
@@ -12,24 +14,20 @@ If you've ever felt like you’re stitching together glue code and hoping for th
 
 ## 🚀 Quick start
 
-Dive straight into the code and learn how to use draive with our interactive [guides](https://github.com/miquido/draive/tree/main/guides).
-For quick solutions to common problems, explore our [cookbooks](https://github.com/miquido/draive/tree/main/cookbooks).
-
 Here’s what a simple Draive setup looks like:
 
 ```python
 from draive import ctx, TextGeneration, tool
 from draive.openai import OpenAI, OpenAIChatConfig
 
-
 @tool # simply annotate a function as a tool
 async def current_time(location: str) -> str:
     return f"Time in {location} is 9:53:22"
 
 async with  ctx.scope( # create execution context
     "example", # give it a name
     OpenAIChatConfig(model="gpt-4o-mini"), # prepare configuration
-    disposables=[OpenAI()], # define resources and service clients available
+    disposables=(OpenAI(),), # define resources and service clients available
 ):
     result: str = await TextGeneration.generate( # choose a right generation abstraction
         instruction="You are a helpful assistant", # provide clear instructions
@@ -41,6 +39,8 @@ async with  ctx.scope( # create execution context
     # output: The current time in Kraków is 9:53:22.
 ```
 
+Read the [Draive Documentation](https://miquido.github.io/draive/) for all required knowledge.
+
 For full examples, head over to the [Draive Examples](https://github.com/miquido/draive-examples) repository.
 
 ## ❓ What is Draive good for?

cookbooks/BasicDataExtraction.md → docs/cookbooks/BasicDataExtraction.md

@@ -58,15 +58,15 @@ from draive.openai import OpenAIChatConfig, OpenAI
 async with ctx.scope(
     "data_extraction",
     # define used LMM to be OpenAI within the context
-    OpenAIChatConfig(model="gpt-4o-mini")
+    OpenAIChatConfig(model="gpt-4o-mini"),
     disposables=(OpenAI(),),
 ):
     result: PersonalData = await ModelGeneration.generate(
         # define model to generate
         PersonalData,
         # provide additional instructions
         # note that the data structure will be automatically explained to LLM
-        instruction="Please extract information from the given input",
+        instruction="Extract information from the given input",
         # we will provide the document as an input
         input=document,
     )
@@ -90,14 +90,14 @@ from draive import ctx, ModelGeneration
 async with ctx.scope(
     "customized_extraction",
     # define used LMM to be OpenAI within the context
-    OpenAIChatConfig(model="gpt-4o-mini")
+    OpenAIChatConfig(model="gpt-4o-mini"),
     disposables=(OpenAI(),),
 ):
     result: PersonalData = await ModelGeneration.generate(
         PersonalData,
         instruction=(
             # provide extended instructions and take full control over the prompt
-            "Please extract information from the given input."
+            "Extract information from the given input."
             " Put it into the JSON according to the following description:\n"
             "{schema}"  # 'schema' is the name of the format argument used to fill in the schema
         ),

cookbooks/BasicMCP.md → docs/cookbooks/BasicMCP.md

@@ -6,7 +6,6 @@ For this example we've created a directory in our home folder and its structure
 ```
 checkmeout/
     .. file1
-    .. file10
     .. file2
     .. file3
 ```

cookbooks/BasicRAG.md → docs/cookbooks/BasicRAG.md

@@ -14,7 +14,7 @@ load_env() # load .env variables
 We are going to use a the same text about John Doe as we did in [Basic Data Extraction](./BasicDataExtraction.md) as our input. After assigning it to a variable we will prepare it for embedding by splitting the original text to smaller chunks. This allows to fit the data into limited context windows and to additionally filter out unnecessary information. We are going to use a basic splitter looking for paragraphs structure defined by multiple subsequent newlines in the text. Chunks will be put into a structured envelope which allows to store additional information such as a full text of the document or additional metadata.
 
 ```python
-from draive import DataModel, count_text_tokens, ctx, split_text
+from draive import DataModel, Tokenization, ctx, split_text
 from draive.openai import OpenAI
 
 # document is a short text about John Doe
@@ -45,7 +45,7 @@ async with ctx.scope(
             separators=("\n\n", " "),
             part_size=64,
             part_overlap_size=16,
-            count_size=count_text_tokens,
+            count_size=Tokenization.count_tokens,
         )
     ]
 
@@ -87,10 +87,11 @@ When we have prepared the data, we can now use a vector index to make it searcha
 from collections.abc import Sequence
 
 from draive import VectorIndex
+from draive.helpers import VolatileVectorIndex
 from draive.openai import OpenAIEmbeddingConfig, OpenAI
 
 # prepare vector index
-vector_index: VectorIndex = VectorIndex.volatile()
+vector_index = VolatileVectorIndex()
 async with ctx.scope(
     "indexing",
     # use vector index
@@ -104,7 +105,7 @@ async with ctx.scope(
         DocumentChunk,
         values=document_chunks,
         # define what value will be embedded for each chunk
-        indexed_value=DocumentChunk._.content,
+        attribute=DocumentChunk._.content,
     )
 ```