README updated to meet sysadminctl.services format

Author: pereidax86

README.md

@@ -1,142 +1,156 @@
-# SynapsIA
+# SynapsIA ✍️
 
 **SynapsIA** is the digital scribe of the new era. Its name comes from the fusion of **Synapse**, the neural connections where knowledge resides, and **AI**, the intelligence that brings it to life.
 
-It is not a simple reader; it is a craftsman of knowledge. Just as an ancient scribe forged texts that would last for centuries, **SynapsIA** ingests your documents, from the simplest to the most complex, and forges an intricate network of synaptic connections. Every piece of data, every concept, and every relationship becomes a golden thread in a vast knowledge base.
-
-The result is a coherent, living digital mind, ready to be interrogated. Ask it a question, and it will respond with wisdom drawn from your own texts, allowing other AI systems to drink from this fountain of pure, contextualized knowledge.
+It is not a simple reader; it is a craftsman of knowledge. Just as an ancient scribe forged texts that would last for centuries, **SynapsIA** ingests your documents and forges an intricate network of synaptic connections. The result is a coherent, living digital mind, ready to be interrogated by other AI systems.
 
 > **SynapsIA: Forging knowledge, one synapse at a time.**
 
 ---
 
-## Technical Purpose
+## 🚀 Features
 
-`synapsia.py` is a command-line script that uses the LlamaIndex library to process a set of documents. It reads the files, splits them into chunks, and uses an embedding model (via an Ollama service) to convert them into numerical vectors. Finally, it stores these vectors in a persistent index on disk, creating a knowledge base ready to be used by a RAG (Retrieval-Augmented Generation) application.
+* **Ollama-Powered:** Leverages local Ollama services for all embedding tasks, keeping your data private.
+* **RAG-Ready:** Processes your documents into a persistent, optimized vector index, creating the "knowledge base" for any RAG application (like [Kondoo](https://github.com/sysadminctl-services/kondoo)).
+* **Tunable Ingestion:** Provides fine-grained control over `chunk-size` and `chunk-overlap` so you can optimize your knowledge base for Q&A, summarization, or other tasks.
+* **Built-in Query Tool:** Includes a companion script, `synapsia_query.py`, to immediately test and debug your new knowledge base with your local LLMs.
 
-## Prerequisites
+## ⚡ Prerequisites
 
-1.  **Python 3.9+**: A recent version of Python installed on your local machine. We highly recommend using a virtual environment (`python -m venv .venv`).
-2.  **Python Dependencies**: Install the required libraries by running `pip install -r requirements.txt` from within the `SynapsIA` directory.
-3.  **Ollama Service**: The script needs to connect to a running Ollama instance. You can launch one using Podman. This command creates a persistent named volume called `synapsia_storage` to store the downloaded models, so you don't have to download them again every time.
+Before you begin, ensure you have the following installed and running:
 
+1.  **Python 3.9+**: A recent version of Python. We highly recommend using a virtual environment (`python -m venv .venv`).
+2.  **Python Dependencies**: Install the required libraries:
+    ```bash
+    pip install -r requirements.txt
+    ```
+3.  **Ollama Service**: The script needs to connect to a running Ollama instance. You can launch one using Podman:
     ```bash
     # Launch the Ollama container in the background
+    # This uses a persistent volume to save your models
     podman run -d --rm -p 11434:11434 --name ollama-synapsia -v synapsia_storage:/root/.ollama ollama/ollama
     ```
-
-4.  **Embedding Model**: Ensure the embedding model is available in your Ollama instance. **After starting the container**, pull the model using `podman exec`:
-
+4.  **Embedding Model**: After starting the container, pull your desired embedding model:
     ```bash
     # Tell the running 'ollama-synapsia' container to download the model
     podman exec -it ollama-synapsia ollama pull mxbai-embed-large
     ```
 
-## Usage
+---
+
+## ✍️ Ingesting Knowledge (`synapsia.py`)
 
-The script is run from the terminal inside the `SynapsIA` project directory. It uses named arguments to specify paths and options.
+This is the main script for processing your documents.
 
 **Command Syntax:**
 ```bash
 python synapsia.py --docs <path_to_docs> --knowledge <path_to_knowledge_base> [OPTIONS]
 ```
 
 ### Required Arguments
-
 * `--docs <path>`: The relative or absolute path to the directory containing your source documents.
+
 * `--knowledge <path>`: The relative or absolute path to the output directory where the knowledge base will be saved.
 
 ### Options
-
 * `--embed-model <model_name>`: The name of the embedding model to use from Ollama.
-    * **Default:** `mxbai-embed-large`
+    Default: `mxbai-embed-large`
+
 * `--ollama-url <url>`: The base URL of the Ollama API service.
-    * **Default:** `http://localhost:11434`
-* `--embed-batch-size <number>`: Number of chunks to process at a time for embeddings.
-    * **Default:** `5`
-* `--chunk-size <number>`: The size of text chunks in tokens. Ideal for tuning how context is stored.
-    * **Default:** `1024`
-* `--chunk-overlap <number>`: The number of overlapping tokens between consecutive chunks to maintain context.
-    * **Default:** `20`
+    Default: `http://localhost:11434`
+
+* `--embed-batch-size <number>`: Number of chunks to process at a time.
+    Default: `5`
+
+* `--chunk-size <number>`: The size of text chunks in tokens.
+    Default: `1024`
+
+* `--chunk-overlap <number>`: The number of overlapping tokens between consecutive chunks.
+    Default: `20`
+
 * `-h`, `--help`: Show the help message and exit.
 
-### Examples
+### Ingestion Examples
 
-#### Basic Usage
+#### 1. Basic Usage
+Process documents from `./my_docs/` and save the index to `./my_kb/`.
 
 ```bash
 python synapsia.py --docs ./my_docs/ --knowledge ./my_kb/
 ```
 
-#### Advanced Usage (Custom Model)
+#### 2. Advanced Usage (Custom Model)
 
-To run the script using a different embedding model, like `nomic-embed-text`:
+Use a different embedding model.
 
 ```bash
 python synapsia.py --docs ./my_docs/ --knowledge ./my_kb/ --embed-model nomic-embed-text
 ```
 
-#### Advanced Usage (Tuned for Q&A)
-
-This command is optimized for dense, factual documents like FAQs. It uses a smaller chunk size for more precise answers, a corresponding overlap to maintain context between chunks, and a very dynamic progress bar.
+#### 3. Advanced Usage (Tuned for Q&A)
+Optimized for dense, factual documents. Uses a smaller chunk size for more precise answers.
 
 ```bash
-
 python synapsia.py \
     --docs ./faq_docs/ \
     --knowledge ./faq_kb/ \
     --chunk-size 256 \
-    --chunk-overlap 25 \
-    --embed-batch-size 1
+    --chunk-overlap 25
 ```
 
-## Querying the Knowledge Base
+---
 
-Once you have created a knowledge base with `synapsia.py`, you can ask it questions using the `synapsia_query.py` script. This tool loads the indexed knowledge, sends your query to a local LLM, and uses the documents as context to provide a relevant answer.
+## ❓ Querying Knowledge (synapsia_query.py)
+
+Use this script to test your new knowledge base. It loads the index, sends your query to a local LLM (via Ollama), and provides a RAG-generated answer.
+
+**Command Syntax**:
 
-**Command Syntax:**
 ```bash
 python synapsia_query.py --knowledge <path_to_knowledge_base> --query "Your question here" [OPTIONS]
 ```
 
 ### Required Arguments
-
 * `--knowledge <path>`: The path to the directory where the knowledge base was saved.
 
 * `--query <question>`: The question you want to ask, enclosed in quotes.
 
 ### Options
 
 * `--llm-model <model_name>`: The name of the LLM to use from Ollama for generating the answer.
-    * **Default:** `llama3`
-
-* `--top-k <number>`: The number of most relevant text chunks to retrieve from the knowledge base to build the answer.
-    * **Default:** `3`
+    Default: `llama3`
 
-* `--show-context`: A flag that, when present, displays the source text chunks and their relevance scores. This is extremely useful for debugging and understanding the model's reasoning.
+* `--top-k <number>`: The number of relevant text chunks to retrieve.
+    Default: `3`
 
-* `--embed-model`, `--ollama-url`: These should generally match the values used during the ingestion process.
+* `--show-context`: A flag that displays the source text chunks and their relevance scores. Extremely useful for debugging.
 
-### Examples
+* `--embed-model`, `--ollama-url`: These should match the values used during the ingestion process.
 
-### Basic Question
+### Query Examples
 
-A simple query to get a direct answer from the knowledge base.
+#### 1. Basic Question
 
+Get a direct answer from the knowledge base.
 
 ```bash
 python synapsia_query.py \
     --knowledge ./my_kb/ \
     --query "What is the main purpose of Ansible?"
 ```
 
-### Debugging Query
-A query to not only get an answer but also see the top 2 source chunks that the RAG system used as context. This is ideal for fine-tuning your ingestion parameters.
+#### 2. Debugging Query
+
+Get an answer and see the top 2 source chunks used as context.
 
 ```bash
 python synapsia_query.py \
     --knowledge ./faq_kb/ \
     --query "How do I reset my password?" \
     --top-k 2 \
     --show-context
-```
+```
+
+## ⚖️ License
+
+This project is licensed under the MIT License. See the LICENSE file for details.