From 47d8f7ba3f9822215f2f0abc57a92ac5da29272c Mon Sep 17 00:00:00 2001
From: Yiorgis Gozadinos <ggozadinos@gmail.com>
Date: Tue, 2 Dec 2025 12:01:10 +0200
Subject: [PATCH] Update docs

---
 docker/README.md                |  7 ++++---
 docs/configuration/index.md     | 26 +++++++++++++-----------
 docs/configuration/providers.md | 35 +++++++++++++++++++--------------
 docs/tutorial.md                |  7 ++++---
 4 files changed, 42 insertions(+), 33 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index 60fd2af8..70917642 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -25,9 +25,10 @@ Create a configuration file `haiku.rag.yaml`:
 environment: production
 
 embeddings:
-  provider: ollama
-  model: nomic-embed-text
-  vector_dim: 768
+  model:
+    provider: ollama
+    name: nomic-embed-text
+    vector_dim: 768
 
 qa:
   model:
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 0394c1ba..af7ab533 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -35,9 +35,10 @@ A minimal configuration file with defaults:
 environment: production
 
 embeddings:
-  provider: ollama
-  model: qwen3-embedding:4b
-  vector_dim: 2560
+  model:
+    provider: ollama
+    name: qwen3-embedding:4b
+    vector_dim: 2560
 
 qa:
   model:
@@ -69,9 +70,10 @@ lancedb:
   region: ""
 
 embeddings:
-  provider: ollama
-  model: qwen3-embedding:4b
-  vector_dim: 2560
+  model:
+    provider: ollama
+    name: qwen3-embedding:4b
+    vector_dim: 2560
 
 reranking:
   model:
@@ -149,7 +151,7 @@ When using haiku.rag as a Python library, you can pass configuration directly to
 
 ```python
 from haiku.rag.config import AppConfig
-from haiku.rag.config.models import ModelConfig, QAConfig, EmbeddingsConfig
+from haiku.rag.config.models import EmbeddingModelConfig, ModelConfig, QAConfig, EmbeddingsConfig
 from haiku.rag.client import HaikuRAG
 
 # Create custom configuration
@@ -157,16 +159,16 @@ custom_config = AppConfig(
     qa=QAConfig(
         model=ModelConfig(
             provider="openai",
-            model="gpt-4o",
+            name="gpt-4o",
             temperature=0.7
         )
     ),
     embeddings=EmbeddingsConfig(
-        model=ModelConfig(
+        model=EmbeddingModelConfig(
             provider="ollama",
-            model="qwen3-embedding:4b"
-        ),
-        vector_dim=2560
+            name="qwen3-embedding:4b",
+            vector_dim=2560
+        )
     ),
     processing={"chunk_size": 512}
 )
diff --git a/docs/configuration/providers.md b/docs/configuration/providers.md
index 1f2a396c..03da0a66 100644
--- a/docs/configuration/providers.md
+++ b/docs/configuration/providers.md
@@ -73,9 +73,10 @@ If you use Ollama, you can use any pulled model that supports embeddings.
 
 ```yaml
 embeddings:
-  provider: ollama
-  model: mxbai-embed-large
-  vector_dim: 1024
+  model:
+    provider: ollama
+    name: mxbai-embed-large
+    vector_dim: 1024
 ```
 
 The Ollama base URL can be configured in your config file or via environment variable:
@@ -104,9 +105,10 @@ uv pip install haiku.rag-slim[voyageai]
 
 ```yaml
 embeddings:
-  provider: voyageai
-  model: voyage-3.5
-  vector_dim: 1024
+  model:
+    provider: voyageai
+    name: voyage-3.5
+    vector_dim: 1024
 ```
 
 Set your API key via environment variable:
@@ -121,9 +123,10 @@ OpenAI embeddings are included in the default installation:
 
 ```yaml
 embeddings:
-  provider: openai
-  model: text-embedding-3-small  # or text-embedding-3-large
-  vector_dim: 1536
+  model:
+    provider: openai
+    name: text-embedding-3-small  # or text-embedding-3-large
+    vector_dim: 1536
 ```
 
 Set your API key via environment variable:
@@ -138,9 +141,10 @@ For high-performance local inference, you can use vLLM to serve embedding models
 
 ```yaml
 embeddings:
-  provider: vllm
-  model: mixedbread-ai/mxbai-embed-large-v1
-  vector_dim: 512
+  model:
+    provider: vllm
+    name: mixedbread-ai/mxbai-embed-large-v1
+    vector_dim: 512
 
 providers:
   vllm:
@@ -155,9 +159,10 @@ providers:
 
 ```yaml
 embeddings:
-  provider: lm_studio
-  model: text-embedding-qwen3-embedding-4b
-  vector_dim: 2560
+  model:
+    provider: lm_studio
+    name: text-embedding-qwen3-embedding-4b
+    vector_dim: 2560
 
 providers:
   lm_studio:
diff --git a/docs/tutorial.md b/docs/tutorial.md
index e46bc0a8..97923d8b 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -33,9 +33,10 @@ Configure haiku.rag to use OpenAI. Create a `haiku.rag.yaml` file:
 
 ```yaml
 embeddings:
-  provider: openai
-  model: text-embedding-3-small  # or text-embedding-3-large
-  vector_dim: 1536
+  model:
+    provider: openai
+    name: text-embedding-3-small  # or text-embedding-3-large
+    vector_dim: 1536
 
 qa:
   model: