Merge branch 'features/refactor-new-repo'

# Conflicts:
#	README.md
#	services/workers/hosts/192.168.100.71/vllm/0/run-gemma-3-12b-it-vllm.sh
#	services/workers/hosts/192.168.100.71/vllm/1/run-gemma-3-12b-it-vllm.sh

Author: Paweł Kędzia

.version

@@ -1 +1 @@
-0.3.1
+0.4.0

CHANGELOG.md

@@ -14,4 +14,5 @@
 | 0.2.3   | New web configurator: Handling projects, configs for each user separately. First Available strategy is more powerful, a lot of improvements to efficiency.                                                                                                                                  |
 | 0.2.4   | Anonymizer module, integration anonymization with any endpoint (using dynamic payload analysis and full payload anonymisation), dedicated `/api/anonymize_text` endpoint as memory only anonymization. Whole router may be run in `FORCE_ANONYMISATION` mode.                               |
 | 0.3.0   | Anonymization available with three strategies: `fast_masker`, `genai`, `prov_masker`.                                                                                                                                                                                                       |
-| 0.3.1   | Refactoring `lb.strategies` to be more flexible modular. Introduced `MaskerPipeline` and `GuardrailPipeline` both configured via env. Removed genai-based masking endpoint.                                                                                                                 |
+| 0.3.1   | Refactoring `lb.strategies` to be more flexible modular. Introduced `MaskerPipeline` and `GuardrailPipeline` both configured via env. Removed genai-based masking endpoint.                                                                                                                 |
+| 0.4.0   | The main repository is divided into dedicated ones: plugins, services, web — separate repositories. Clean up the whole repository. Examples of integration with llamaindex, langchain, openai, litellm and haystack.                                                                        |

README.md

@@ -12,11 +12,16 @@ a ready‑made image in your own infrastructure.
   and optional Prometheus metrics.
 - **llm_router_lib** is a Python SDK that wraps the API with typed request/response models, automatic retries, token
   handling and a rich exception hierarchy, letting developers focus on application logic rather than raw HTTP calls.
-- **llm_router_web** offers ready‑to‑use Flask UIs – an anonymizer UI that masks sensitive data and a configuration
+- [**llm_router_web**](https://github.com/radlab-dev-group/llm-router-web) offers ready‑to‑use Flask UIs – an anonymizer
+  UI that masks sensitive data and a configuration
   manager for model/user settings – demonstrating how to consume the router from a browser.
-- **llm_router_plugins** (e.g., the **fast_masker** plugin) deliver a rule‑based text anonymisation engine with
+- [**llm_router_plugins**](https://github.com/radlab-dev-group/llm-router-plugins) (e.g., the **fast_masker** plugin)
+  deliver a rule‑based text anonymisation engine with
   a comprehensive set of Polish‑specific masking rules (emails, IPs, URLs, phone numbers, PESEL, NIP, KRS, REGON,
   monetary amounts, dates, etc.) and an extensible architecture for custom rules and validators.
+- [**llm_router_services**](https://github.com/radlab-dev-group/llm-router-services) provides HTTP services that
+  implement the core functionality used by the LLM‑Router’s plugin system. The services expose guardrail and masking
+  capabilities through Flask applications.
 
 All components run on Python 3.10+ using `virtualenv` and require only the listed dependencies, making the suite easy to
 install, extend, and deploy in both development and production environments.
@@ -62,21 +67,6 @@ project README:
 
 #### Base requirements
 
-> **Prerequisite**: `radlab-ml-utils`
->
-> This project uses the
-> [radlab-ml-utils](https://github.com/radlab-dev-group/ml-utils)
-> library for machine learning utilities
-> (e.g., experiment/result logging with Weights & Biases/wandb).
-> Install it before working with ML-related parts:
->
-> ```bash
-> pip install git+https://github.com/radlab-dev-group/ml-utils.git
-> ```
->
-> For more options and details, see the library README:
-> https://github.com/radlab-dev-group/ml-utils
-
 ```shell script
 python3 -m venv .venv
 source .venv/bin/activate
@@ -118,7 +108,7 @@ metrics for monitoring and alerting.
 LLM_ROUTER_MINIMUM=1 python3 -m llm_router_api.rest_api
 ```
 
-### 📦 Docker
+## 📦 Docker
 
 Run the container with the default configuration:
 
@@ -157,7 +147,7 @@ docker run \
 
 ---
 
-### Configuration (via environment)
+## 🛠️ Configuration (via environment)
 
 A full list of environment variables is available at the link
 [.env list](llm_router_api/README.md#environment-variables)
@@ -194,7 +184,7 @@ a description of the streaming mechanisms can be found at the link:
 
 ---
 
-## 🛠️ Development
+## 🔧 Development
 
 - **Python**3.10+ (project is tested on 3.10.6)
 - All dependencies are listed in `requirements.txt`. Install them inside the virtualenv.

install.md

@@ -1,168 +1,119 @@
-# llm‑router-LIB — Python client library
-
-**llm‑router** is a lightweight Python client for interacting with the LLM‑Router API.
-It provides typed request models, convenient service wrappers, and robust error handling so you can focus on building
-LLM‑driven applications rather than dealing with raw HTTP calls.
-
----  
+# llm_router_lib
 
 ## Overview
 
-`llm_router_lib` is the official Python SDK for the **LLM‑Router**
-project <https://github.com/radlab-dev-group/llm-router>.
-
-It abstracts the HTTP layer behind a small, well‑typed API:
-
-* **Typed payloads** built with *pydantic* (e.g., `GenerativeConversationModel`).
-* **Service objects** that know the endpoint URL and the model class they expect.
-* **Automatic token handling**, request retries, and exponential back‑off.
-* **Rich exception hierarchy** (`LLMRouterError`, `AuthenticationError`, `RateLimitError`, `ValidationError`).
-
----  
+`llm_router_lib` is ** a collection of data‑model definitions**.
+It supplies the **foundation** for request/response structures used by the
+`llm_router_api` package **and** provides a **thin, opinionated client wrapper**
+that makes interacting with the LLM Router service straightforward.
 
-## Features
+Key components:
 
-| Feature                            | Description                                                                    |
-|------------------------------------|--------------------------------------------------------------------------------|
-| **Typed request/response models**  | Guarantees payload correctness at runtime using Pydantic.                      |
-| **Built‑in conversation services** | Simple `conversation_with_model` and `extended_conversation_with_model` calls. |
-| **Retry & timeout**                | Configurable request timeout and automatic retries with exponential back‑off.  |
-| **Authentication**                 | Bearer‑token support; raises `AuthenticationError` on 401/403.                 |
-| **Rate‑limit handling**            | Detects HTTP 429 and raises `RateLimitError`.                                  |
-| **Extensible**                     | Add custom services or models by extending the base classes.                   |
-| **Test suite**                     | Ready‑to‑run unit tests in `llm_router_lib/tests`.                             |
+| Package             | Purpose                                                                                                                                                                                                                                                                                                                                                    |
+|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`data_models`**   | `pydantic` models that define the shape of payloads sent to the router (e.g. `GenerativeConversationModel`, `ExtendedGenerativeConversationModel`, utility models for question generation, translation, etc.). These models are shared with the API side, ensuring both client and server speak the same contract.                                         |
+| **`client.py`**     | `LLMRouterClient` – a lightweight wrapper around the router’s HTTP API. It offers high‑level methods (`conversation_with_model`, `extended_conversation_with_model`) that accept either plain dictionaries **or** the aforementioned data‑model instances. The client handles payload validation, provider selection, error mapping, and response parsing. |
+| **`services`**      | Low‑level service classes (`ConversationService`, `ExtendedConversationService`) that perform the actual HTTP calls via `HttpRequester`. They are used internally by the client but can be reused directly if finer‑grained control is needed.                                                                                                             |
+| **`exceptions.py`** | Custom exception hierarchy (`LLMRouterError`, `AuthenticationError`, `RateLimitError`, `ValidationError`) that mirrors the router’s error semantics, making error handling in user code clean and explicit.                                                                                                                                                |
+| **`utils/http.py`** | `HttpRequester` – a small wrapper around `requests` providing retries, time‑outs and logging. It is the networking backbone for the client wrapper.                                                                                                                                                                                                        |
 
----  
+In short, `llm_router_lib` provides **both** the data contract (the “schema”) **and** a convenient Pythonic client to
+consume the router service.
 
 ## Installation
 
-The library is pure Python and works with **Python 3.10+**.
+The library targets **Python 3.10.6** and uses a `virtualenv`. Install it in editable mode for development:
 
-```shell script
-# Create a virtualenv (recommended)
-python -m venv .venv
+``` bash
+# Clone the repository (if you haven't already)
+git clone https://github.com/radlab-dev-group/llm-router.git
+cd llm-router/llm_router_lib
+
+# Create and activate a virtual environment
+python3 -m venv .venv
 source .venv/bin/activate
 
-# Install from the repository (editable mode)
+# Install the package and its dependencies
 pip install -e .
 ```
 
-If you prefer a regular installation from a wheel or source distribution, use:
-
-```shell script
-pip install .
-```
-
-> **Note** – The project relies only on the packages listed in the repository’s `requirements.txt`
-> (pydantic, requests, etc.), all of which are installed automatically by `pip`.
-
----  
+All runtime dependencies (`requests`, `pydantic`, `rdl_ml_utils`) are declared in the project’s `requirements.txt`.
 
 ## Quick start
 
-```python
-from llm_router_lib.client import LLMRouterClient
-from llm_router_lib.data_models.builtin_chat import GenerativeConversationModel
+``` python
+from llm_router_lib import LLMRouterClient
 
-# Initialise the client (replace with your own endpoint and token)
+# Initialise the client – point it at the router’s base URL
 client = LLMRouterClient(
-    api="https://api.your-llm-router.com",
-    token="YOUR_ACCESS_TOKEN"
+    api="http://localhost:8080/api",   # router base URL
+    token="YOUR_ROUTER_TOKEN",         # optional, if router requires auth
 )
 
-# Build a request payload
-payload = GenerativeConversationModel(
-    model_name="google/gemma-3-12b-it",
-    user_last_statement="Hello, how are you?",
-    historical_messages=[{"user": "Hi"}],
-    temperature=0.7,
-    max_new_tokens=128,
-)
+# Build a payload using the provided data model (validation is automatic)
+payload = {
+    "model_name": "google/gemma-3-12b-it",
+    "user_last_statement": "Hello, how are you?",
+    "temperature": 0.7,
+    "max_new_tokens": 128,
+}
 
-# Call the API
+# Call the standard conversation endpoint
 response = client.conversation_with_model(payload)
 
-print(response)  # → dict with the model's answer and metadata
+print(response)   # → {'status': True, 'body': {...}}
 ```
 
-### Extended conversation
+You can also pass a `pydantic` model instance directly:
 
-```python
-from llm_router_lib.data_models.builtin_chat import ExtendedGenerativeConversationModel
+```
+python
+from llm_router_lib.data_models.builtin_chat import GenerativeConversationModel
 
-payload = ExtendedGenerativeConversationModel(
+model = GenerativeConversationModel(
     model_name="google/gemma-3-12b-it",
-    user_last_statement="Explain quantum entanglement.",
-    system_prompt="Answer as a friendly professor.",
-    temperature=0.6,
-    max_new_tokens=256,
+    user_last_statement="Hello, how are you?",
+    temperature=0.7,
+    max_new_tokens=128,
 )
 
-response = client.extended_conversation_with_model(payload)
-print(response)
+response = client.conversation_with_model(model)
 ```
 
----  
-
-## Core concepts
-
-### Client
-
-`LLMRouterClient` is the entry point. It handles:
-
-* Base URL normalization.
-* Optional bearer token injection.
-* Construction of the internal `HttpRequester`.
+## Data models
 
-All public methods accept either a **dict** or a **pydantic model**; models are automatically serialized with
-`.model_dump()`.
+All request payloads are defined in `llm_router_lib/data_models`.  
+Common base:
 
-### Data models
-
-Located in `llm_router_lib/data_models/`.  
-Key models:
-
-| Model                                        | Purpose                                                           |
-|----------------------------------------------|-------------------------------------------------------------------|
-| `GenerativeConversationModel`                | Simple chat payload (model name, user message, optional history). |
-| `ExtendedGenerativeConversationModel`        | Same as above, plus a `system_prompt`.                            |
-| `GenerateQuestionFromTextsModel`             | Generate questions from a list of texts.                          |
-| `TranslateTextModel`, `SimplifyTextModel`, … | Various utility models for text transformation.                   |
-| `OpenAIChatModel`                            | Payload for direct OpenAI‑compatible chat calls.                  |
-
-All models inherit from a common `_GenerativeOptions` base that defines temperature, token limits, language, etc.
-
-### Services
-
-Implemented in `llm_router_lib/services/`.  
-Each service extends `_BaseConversationService` and defines:
-
-* `endpoint` – the API path (e.g., `/api/conversation_with_model`).
-* `model_cls` – the Pydantic model class used for validation.
-
-The service’s `call()` method performs the HTTP POST and returns a parsed JSON dictionary, raising `LLMRouterError` on
-malformed responses.
+``` python
+class BaseModelOptions(BaseModel):
+    """Options shared across many endpoint models."""
+    mask_payload: bool = False
+    masker_pipeline: Optional[List[str]] = None
+```
 
-### Utilities
+### Conversation models
 
-* `llm_router_lib/utils/http.py` – thin wrapper around `requests` with retry logic, response validation, and logging.
-* Logging is integrated via the standard library `logging` module; you can inject your own logger when constructing the
-  client.
+| Model                                 | Required fields                     | Optional / extra fields                                   |
+|---------------------------------------|-------------------------------------|-----------------------------------------------------------|
+| `GenerativeConversationModel`         | `model_name`, `user_last_statement` | `temperature`, `max_new_tokens`, `historical_messages`, … |
+| `ExtendedGenerativeConversationModel` | All of the above + `system_prompt`  | –                                                         |
 
-### Error handling
+Utility models for other built‑in endpoints (question generation, translation,
+article creation, context‑based answering, etc.) follow the same pattern and
+inherit from `BaseModelOptions`.
 
-| Exception             | When raised                                               |
-|-----------------------|-----------------------------------------------------------|
-| `LLMRouterError`      | Generic SDK‑level error (e.g., non‑JSON response).        |
-| `AuthenticationError` | HTTP 401/403 – missing or invalid token.                  |
-| `RateLimitError`      | HTTP 429 – the server throttled the request.              |
-| `ValidationError`     | HTTP 400 – request payload failed server‑side validation. |
+## Thin client wrapper (`LLMRouterClient`)
 
-All exceptions inherit from `LLMRouterError`, allowing a single `except LLMRouterError:` clause to catch any SDK‑related
-problem.
+`LLMRouterClient` offers a **high‑level API** that abstracts away the low‑level
+HTTP details:
 
----
+| Method                                      | Description                                                                                                    |
+|---------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| `conversation_with_model(payload)`          | Calls `/api/conversation_with_model`. Accepts a dict **or** a `GenerativeConversationModel`.                   |
+| `extended_conversation_with_model(payload)` | Calls `/api/extended_conversation_with_model`. Accepts a dict **or** an `ExtendedGenerativeConversationModel`. |
 
-## License
+Internally the client:
 
-`llm_router_lib` is released under the **MIT License**. See the `LICENSE` file for details.  
+1. **Validates** the payload (via the corresponding `pydantic` model if a model instance is supplied).
+2. **Selects** an appropriate provider using the router’s load‑balancing