Metadata-Version: 2.4
Name: ecdallm
Version: 0.3.11
Summary: Retrieval-Augmented Generation - (RAG)
License: MIT
License-File: LICENSE
Keywords: rag,llm,nlp,data,vector
Author: EDC - Erasmus Data Collaboratory
Author-email: ziabakhshganji@rsm.nl
Requires-Python: >=3.11,<3.15
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: bs4 (>=0.0.2,<0.0.3)
Requires-Dist: chromadb (>=1.5.0,<2.0.0)
Requires-Dist: docx2txt (>=0.9,<0.10)
Requires-Dist: faiss-cpu (>=1.13.2,<2.0.0)
Requires-Dist: fastapi (>=0.128.5,<0.129.0)
Requires-Dist: fastembed (>=0.7.4,<0.8.0)
Requires-Dist: faster-whisper (>=1.2.1,<2.0.0)
Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
Requires-Dist: langchain (>=1.2.9,<2.0.0)
Requires-Dist: langchain-chroma (>=1.1.0,<2.0.0)
Requires-Dist: langchain-community (>=0.4.1,<0.5.0)
Requires-Dist: langchain-openai (>=1.1.8,<2.0.0)
Requires-Dist: langchain-text-splitters (>=1.1.0,<2.0.0)
Requires-Dist: openai (>=2.18.0,<3.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pypdf (>=6.7.0,<7.0.0)
Requires-Dist: pytest (>=9.0.2,<10.0.0)
Requires-Dist: python-docx (>=1.2.0,<2.0.0)
Requires-Dist: python-multipart (>=0.0.22,<0.0.23)
Requires-Dist: reportlab (>=4.4.9,<5.0.0)
Requires-Dist: scikit-learn (>=1.8.0,<2.0.0)
Requires-Dist: sentence-transformers (>=5.2.2,<6.0.0)
Requires-Dist: sounddevice (>=0.5.5,<0.6.0)
Requires-Dist: soundfile (>=0.13.1,<0.14.0)
Requires-Dist: symspellpy (>=6.9.0,<7.0.0)
Requires-Dist: typer (>=0.21.1,<0.22.0)
Requires-Dist: uvicorn (>=0.40.0,<0.41.0)
Project-URL: Homepage, https://ecda.eur.nl/erasmus-data-collaboratory/
Project-URL: Repository, https://github.com/Erasmus-Data-Collaboratory/ecdallm
Description-Content-Type: text/markdown

# ecdallm

[![PyPI
version](https://badge.fury.io/py/ecdallm.svg)](https://pypi.org/project/ecdallm/)
[![Python
versions](https://img.shields.io/pypi/pyversions/ecdallm.svg)](https://pypi.org/project/ecdallm/)
[![License](https://img.shields.io/pypi/l/ecdallm.svg)](LICENCE)

**ecdallm** is a lightweight Retrieval-Augmented Generation (RAG)
application that lets you chat with your own documents using either a
**local LLM** or an **external OpenAI-compatible provider**.

It combines:

- FastAPI web interface
- Local embedding pipeline (FastEmbed)
- Persistent vector storage (ChromaDB)
- Document ingestion (PDF, TXT, DOCX)
- CLI launcher
- Local LLM support (e.g., LM Studio)
- External LLM support (OpenAI-compatible APIs)

The goal is to provide a simple, reproducible environment for
**document-grounded LLM interaction** with flexible model connectivity.

------------------------------------------------------------------------

## Overview

`ecdallm` allows you to:

1. Upload documents
2. Index them into a vector database
3. Run semantic retrieval
4. Query an LLM with grounded context

All embeddings and vector storage run locally.

The chat model can run:

- locally (LM Studio, Ollama, etc.)
- externally (OpenRouter or OpenAI-compatible APIs)

This makes the system suitable for:

- research environments
- private document analysis
- offline experimentation
- RAG prototyping
- hybrid local/cloud workflows

------------------------------------------------------------------------

## Prerequisites

Make sure Python 3 is installed.

On some systems (especially macOS installations from python.org), the
commands are named `python3` and `pip3` instead of `python` and `pip`.

You can check which commands are available:

```bash
python --version
python3 --version

pip --version
pip3 --version
```

If `python` or `pip` returns:

```bash
command not found
```

use the `python3` / `pip3` variants instead.

Typical macOS setup:

```bash
python3 --version
pip3 --version
```

------------------------------------------------------------------------

## Installation

Install from PyPI:

```bash
pip install ecdallm
```

If your system uses `pip3`:

```bash
pip3 install ecdallm
```

------------------------------------------------------------------------

## Running the application

Start the CLI:

```bash
ecdallm
```

If the command is not found, try:

```bash
python3 -m ecdallm
```

or ensure your Python scripts directory is in your `PATH`.

The CLI will:

- find a free port (starting from 8000)
- start the FastAPI server
- open the browser automatically

Example output:

```text
ecdallm running at http://127.0.0.1:8000/
INFO: Uvicorn running on http://127.0.0.1:8000
```

------------------------------------------------------------------------

## LLM Configuration

When the application starts, click **Continue** and choose:

- Local LLM
- External LLM

Configuration is stored in the browser session.

Embeddings always run locally using FastEmbed with:

```text
nomic-embed-text-v1.5
```

------------------------------------------------------------------------

## Using a local LLM

`ecdallm` expects an OpenAI-compatible endpoint.

For example, with **LM Studio**:

1. Start LM Studio server
2. Load a chat model
3. Enable the local API server

Typical endpoint:

```text
http://localhost:1234/v1
```

Default configuration:

```text
Base URL: http://localhost:1234/v1
API Key: lm-studio
```

The backend automatically detects the available chat model via:

```text
GET /models
```

------------------------------------------------------------------------

## Using an external LLM

`ecdallm` can connect to any **OpenAI-compatible API provider**.

Examples include:

- OpenRouter
- OpenAI-compatible gateways
- Self-hosted inference APIs

Example configuration (OpenRouter):

```text
Base URL: https://openrouter.ai/api/v1
Model: openrouter/aurora-alpha
API Key: sk-or-...
```

Steps:

1. Create an account with the provider
2. Generate an API key
3. Choose a chat model
4. Enter the configuration in the web interface

When validating, `ecdallm`:

- checks connectivity
- performs a test chat completion
- stores configuration in session storage

Your API key is sent only to your backend for validation and is **not
used directly in the browser**.

Embeddings remain local.

------------------------------------------------------------------------

## Supported document types

- PDF
- TXT
- DOCX

------------------------------------------------------------------------

## Workflow

### 1. Upload documents

Use the **Upload** page to add files.

### 2. Index documents

Files are automatically indexed into ChromaDB using FastEmbed.

### 3. Chat with documents

Open the **Chat** page and ask questions.

The assistant will:

- retrieve relevant chunks
- build a grounded prompt
- query the configured LLM
- return a concise answer

------------------------------------------------------------------------

## Project structure

```text
ecdallm/
├── cli.py
└── app/
    ├── main.py
    ├── rag.py
    ├── paths.py
    ├── search_engine.py
    ├── vector.py
    ├── templates/
    ├── static/
    ├── uploads/
    └── rag_store/
```

------------------------------------------------------------------------

## Notes

Embeddings and retrieval always run locally.

The chat model can be:

- local (LM Studio, Ollama, etc.)
- external (OpenAI-compatible providers)

This keeps the system flexible while maintaining local document
processing.

------------------------------------------------------------------------

## Erasmus Data Collaboratory

Developed by the Erasmus Data Collaboratory (ECDA).

- Zaman Ziabakhshganji --- creator and maintainer
- Farshad Radman --- co-author and contributor
- Jos van Dongen --- co-author and contributor

------------------------------------------------------------------------

## License

MIT License

