# 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 a locally running LLM.

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)

The goal is to provide a simple, reproducible environment for **document-grounded LLM interaction** without relying on external APIs.

---

## Overview

`ecdallm` allows you to:

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

All embeddings and vector storage run locally.

Your LLM also runs locally — for example using **LM Studio**.

This makes the system suitable for:

- research environments
- private document analysis
- offline experimentation
- RAG prototyping

---

## Installation

Install from PyPI:

```bash
pip install ecdallm
```

---

## Running the application

Start the CLI:

```bash
ecdallm
```

The CLI will:

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

Example output:

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

---

## 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:

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

You will configure this from the web interface.

---

## 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 local LLM
- return a concise answer

---

## Project structure

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

---

## Notes

At this stage, `ecdallm` is designed to work with **locally running LLMs**.
No external API calls are required for embeddings or retrieval.

This keeps the system:

- private
- reproducible
- offline-friendly

---



## 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
