Metadata-Version: 2.4
Name: atlas-ragkit
Version: 1.2.9
Summary: Atlas RAGKit Ã¢â‚¬â€ Local-First RAG Engineering Platform
Author: Rishi Bhanushali
License: MIT
Keywords: rag,llm,ai,local,retrieval,augmented,generation,nlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: groq>=0.9.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: scikit-learn>=1.2.0
Provides-Extra: local-embeddings
Requires-Dist: sentence-transformers>=2.2.2; extra == "local-embeddings"
Provides-Extra: chroma
Requires-Dist: chromadb>=0.4.0; extra == "chroma"
Provides-Extra: visualizer
Requires-Dist: umap-learn>=0.5.3; extra == "visualizer"
Requires-Dist: gitpython>=3.1.0; extra == "visualizer"
Provides-Extra: all
Requires-Dist: atlas-ragkit[chroma,local-embeddings,visualizer]; extra == "all"
Dynamic: license-file

# ⚡ Atlas RAGKit — Local-First RAG Engineering Platform

[![PyPI version](https://img.shields.io/pypi/v/atlas-ragkit)](https://pypi.org/project/atlas-ragkit/)
[![Python](https://img.shields.io/pypi/pyversions/atlas-ragkit)](https://pypi.org/project/atlas-ragkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/bhanushali222/atlas/actions/workflows/publish.yml/badge.svg)](https://github.com/bhanushali222/atlas/actions/workflows/publish.yml)
[![PyPI downloads](https://img.shields.io/pypi/dm/atlas-ragkit)](https://pypi.org/project/atlas-ragkit/)

**Atlas** is a **local-first, zero-cloud** Retrieval-Augmented Generation (RAG) engineering workbench. Ingest documents, benchmark chunking strategies, visualise embeddings in 3D, run RAG pipelines, and evaluate output quality — all from a full-featured browser UI, with no cloud dependency and no data leaving your machine.

---

## ✨ Key Features

| Feature | Description |
|---|---|
| 📄 **Document Ingestion** | Ingest PDF, DOCX, TXT, HTML, Markdown, code files and more |
| 🔪 **Chunking Lab** | Benchmark 6 chunking strategies side-by-side with live previews |
| 🧬 **Embedding Studio** | Visualise chunk embeddings in interactive 3D (UMAP projection) |
| 🚀 **Pipeline Execution** | Run full RAG pipelines on any ingested document with one click |
| 💬 **Chat Interface** | Chat with your documents using any configured LLM provider |
| 📊 **Evaluation** | Evaluate RAG quality with the RAG Triad (context relevance, faithfulness, answer relevance) |
| 🔌 **Plugin System** | Add custom chunkers, embedders, retrievers, LLMs via Python entry-points |
| 🔑 **Multi-LLM** | Groq, OpenAI, Anthropic, Google Gemini, Together AI, Mistral, HuggingFace, Ollama, LM Studio |

---

## 🚀 Installation

### ⚡ Standard Core (< 50 MB, ~15s download)
```bash
pip install -U atlas-ragkit
```

### 🧠 Optional Extras
```bash
# Local Neural Embeddings (PyTorch + HuggingFace)
pip install -U "atlas-ragkit[local-embeddings]"

# ChromaDB Vector Store
pip install -U "atlas-ragkit[chroma]"

# Complete Suite (All plugins, neural models & visualizers)
pip install -U "atlas-ragkit[all]"
```

### Requirements
- Python ≥ 3.10
- No Docker, no cloud accounts required

---

## ▶️ Quick Start

```bash
# 1. Start the server from any directory
atlas server

# 2. Your browser opens automatically at http://localhost:8000
# 3. Click "Provision Workspace" in the System Config tab to load demo files
```

Optional flags:
```bash
atlas server --port=9000   # custom port
atlas server --dev         # enable hot-reload (development mode)
```

---

## 🗑️ Uninstall

**Mac / Linux:**
```bash
pip uninstall -y atlas-ragkit
rm -rf .atlas atlas.db
```

**Windows (PowerShell):**
```powershell
pip uninstall -y atlas-ragkit
Remove-Item -Recurse -Force .atlas, atlas.db -ErrorAction SilentlyContinue
```

---

## 🏗️ Architecture

### Component Interaction

```mermaid
flowchart TD
    User["👤 User (Browser)"]
    CLI["atlas CLI\n(atlas_cli)"]
    Server["FastAPI Server\n(atlas_server)"]
    SPA["SPA Dashboard\n(static/index.html)"]
    Core["atlas_core\n(Business Logic)"]
    SDK["atlas_sdk\n(Plugin Implementations)"]
    DB["SQLite\n(atlas.db)"]
    Registry["Plugin Registry\n(entry-points)"]
    LLM["LLM Providers\n(Groq / Gemini / OpenAI / ...)"]
    Embed["Embedding Models\n(sentence-transformers)"]
    Vector["Vector Stores\n(FAISS / ChromaDB / BM25)"]

    User -- "atlas server" --> CLI
    CLI -- "uvicorn + webbrowser" --> Server
    User -- "HTTP / browser" --> SPA
    SPA -- "REST API calls" --> Server
    Server -- "lazy-loads services" --> Core
    Core -- "discovers plugins" --> Registry
    Registry -- "importlib entry-points" --> SDK
    SDK --> Embed
    SDK --> Vector
    SDK --> LLM
    Core -- "reads/writes" --> DB
    Server -- "serves" --> SPA
```

### Module Dependency Map

```mermaid
flowchart LR
    CLI["atlas_cli\n(entrypoint)"]
    Server["atlas_server\n(FastAPI + SPA)"]
    Core["atlas_core\n(domain + contexts)"]
    SDK["atlas_sdk\n(plugins)"]
    DB["SQLite Provider\n(atlas_core.providers.storage)"]

    CLI --> Server
    Server --> Core
    Core --> SDK
    Core --> DB
    SDK -.->|"entry-point group\natlas.chunkers etc."| Core
```

---

## 📁 Folder Structure

```
atlas/
├── atlas-cli/              # CLI package — boots server, scaffolds workspace
│   └── atlas_cli/
│       ├── main.py         # CLI entrypoint: `atlas server`
│       └── templates/      # Pipeline YAML templates copied into user workspaces
│           ├── pipelines/  # 8 built-in pipeline presets
│           └── demo_sandbox/ # Demo documents for new workspaces
│
├── atlas-core/             # Core domain logic and business rules
│   └── atlas_core/
│       ├── domain/         # Pydantic models: Pipeline, Run, Chat, Evaluation
│       ├── contexts/       # Feature contexts (bounded contexts DDD-style)
│       │   ├── ingestion_context/   # Document parsing (PDF, DOCX, HTML, code…)
│       │   ├── execution_context/   # RAG pipeline execution + pipeline manager
│       │   ├── experiment_context/  # Multi-run experiments and comparison
│       │   ├── studio_context/      # Chunking lab + Embedding studio
│       │   ├── chat_context/        # Conversational RAG service
│       │   └── project_context/     # Workspace/project management
│       ├── providers/
│       │   └── storage/sqlite.py    # SQLite-backed persistence layer
│       └── registry/
│           └── plugin_registry.py  # Entry-point plugin discovery
│
├── atlas-sdk-python/       # Plugin reference implementations (SDK)
│   └── atlas_sdk/
│       ├── chunkers/       # 6 chunkers: fixed_size, recursive_character, semantic…
│       ├── embeddings/     # sentence-transformers embedding provider
│       ├── retrievers/     # FAISS (dense), ChromaDB, BM25, Hybrid, ParentDocument
│       ├── rerankers/      # Cross-encoder reranker
│       ├── evaluators/     # RAG Triad evaluators (context relevance, faithfulness…)
│       ├── llm/            # LLM providers: Groq, OpenAI-compatible, Anthropic, Gemini
│       └── interfaces.py   # Abstract base classes for all plugin types
│
├── atlas-server/           # FastAPI REST API + embedded SPA web dashboard
│   └── atlas_server/
│       ├── main.py         # FastAPI app, all REST endpoints, lazy service loading
│       └── static/
│           └── index.html  # Built SPA (single-file, embedded into the wheel)
│
├── website/                # Public marketing website (React + Vite + Tailwind)
│   └── src/
│       ├── pages/          # Home, UsageGuide, Info pages
│       └── components/     # Navbar, ParticleBackground, VersionBadge
│
├── pipelines/              # Default pipeline YAML configs (workspace-level)
├── docs/                   # Design specs, architecture notes, blueprints
├── tests/                  # Test suite (pytest)
├── .github/                # CI/CD workflows, issue & PR templates
├── pyproject.toml          # Monorepo root: single pip install, all entry-points
├── dev_server.py           # Dev helper: runs server with sys.path injection
└── .env.example            # Template for API keys (never commit .env!)
```

---

## 🔌 Plugin System

Atlas uses Python **entry-points** for plugin discovery — zero hardcoded imports.

Install any package that declares `atlas.chunkers`, `atlas.embeddings`, etc. entry-points and Atlas picks it up automatically.

**Built-in plugins (registered in `pyproject.toml`):**

| Group | Plugins |
|---|---|
| `atlas.chunkers` | `fixed_size`, `recursive_character`, `semantic`, `markdown_structure`, `sentence_window`, `code_aware` |
| `atlas.embeddings` | `sentence_transformers` |
| `atlas.retrievers` | `dense` (FAISS), `chroma`, `bm25`, `hybrid`, `parent_document` |
| `atlas.rerankers` | `cross_encoder` |
| `atlas.evaluators` | `context_relevance`, `faithfulness`, `answer_relevance` |
| `atlas.llm` | `groq`, `openai`, `anthropic`, `gemini`, `together`, `mistral`, `huggingface` |

---

## 🔑 LLM Provider Setup

Configure API keys via the Atlas web UI (System Config tab) — or create a `.env` file in your working directory:

```bash
# Copy the example and fill in your keys
cp .env.example .env
```

No API key is needed for local providers like Ollama or LM Studio.

---

## 🧪 Running Tests

```bash
pip install pytest
python -m pytest tests/ -v
```

> Note: The test suite is minimal in the current version. The `tests/` directory exists with pytest infrastructure configured in the CI workflow.

---

## 🌐 Website (Marketing)

The `website/` directory is a separate React + Vite app deployed to Vercel/Netlify independently from the Python package.

```bash
cd website
npm install
npm run dev   # http://localhost:5173
```

---

## 💻 Development Setup (from clone)

```bash
git clone https://github.com/bhanushali222/atlas.git
cd atlas
pip install -e ".[dev]"   # or: pip install -e .
cp .env.example .env      # add your LLM API keys
python dev_server.py      # starts with hot-reload at http://localhost:8000
```

---

## 📦 Build & Release

See [`docs/RELEASING.md`](docs/RELEASING.md) for the full release process.

```bash
python -m build
twine check dist/*
```

Publishing is automated via the CI workflow on `git push --tags`.

---

> Built with ❤️ by [Rishi Bhanushali](https://github.com/bhanushali222)
