Metadata-Version: 2.4
Name: lore-cli
Version: 0.1.0
Summary: Local AI-powered legacy codebase analysis tool
License: BSL-1.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: rich
Requires-Dist: chromadb
Requires-Dist: sentence-transformers
Requires-Dist: ollama
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: psutil
Requires-Dist: einops
Requires-Dist: hf_xet

# Lore

> Your codebase has a story. Now you can read it.

Lore is a local AI-powered codebase intelligence tool. Ask plain English questions about any codebase and get accurate, sourced answers — **with zero data leaving your machine.**

**Privacy-first. Air-gap compatible.** Runs entirely on-premise using local LLMs via Ollama. No API keys. No cloud. No code telemetry. Suitable for regulated industries, government contractors, and teams with strict compliance requirements.

[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/smithbuilds.lore-vscode?label=VS%20Code%20Extension)](https://marketplace.visualstudio.com/items?itemName=smithbuilds.lore-vscode)

---

## Quick Start

```bash
# 1. Clone and install
git clone https://github.com/smithbuilds/lore
cd lore
python -m venv venv
source venv/Scripts/activate   # Windows Git Bash
# source venv/bin/activate     # Mac/Linux
pip install -e .

# 2. Run the setup wizard — detects your stack, checks Ollama,
#    pulls the right model for your hardware, installs git hook
lore init --path /path/to/your/codebase --wizard

# 3. Start asking questions
lore ask "how does authentication work?"
lore ask "where is the payment processing logic?"
lore status
```

> **VS Code users:** Install the [Lore extension](https://marketplace.visualstudio.com/items?itemName=smithbuilds.lore-vscode) to query your codebase from the sidebar with streaming answers.

---

## Commands

### Core
| Command | Description |
|---------|-------------|
| `lore init --path .` | Index a codebase into the vector database |
| `lore init --path . --wizard` | Interactive setup: detects stack, pulls model, installs hook |
| `lore ask "question"` | Ask a plain English question (streaming) |
| `lore find "description"` | Semantic code search |
| `lore sync` | Re-index files changed since last ingestion |
| `lore status` | System dashboard — server, index, model, last sync |
| `lore doctor` | Check all dependencies and report what's missing |
| `lore history` | Query history and database stats |

### Analysis
| Command | Description |
|---------|-------------|
| `lore map` | Build dependency map — imports, calls, inheritance |
| `lore impact --file db.py` | Analyze downstream impact of changing a file |
| `lore smell` | Score codebase for code smells and quality issues |
| `lore dead --path .` | Detect dead code |
| `lore dead --min-confidence high` | High confidence dead code only |
| `lore explain --file core/db.py` | Deep dive on a file |
| `lore explain --file core/db.py --function get_db` | Deep dive on a function |

### Documentation & Reporting
| Command | Description |
|---------|-------------|
| `lore document --module file.py` | Generate module documentation |
| `lore changelog --last 10` | Plain English changelog from git history |
| `lore changelog --from v1.0 --to v2.0` | Changelog between git refs |
| `lore diagram --path .` | Generate architecture diagrams (Mermaid + interactive HTML) |
| `lore onboard --role backend` | Guided onboarding for new engineers |
| `lore decide add/list/search/show/delete` | Institutional decision log |

### Security & Dependencies
| Command | Description |
|---------|-------------|
| `lore deps --path .` | Dependency manifest with CVE checks |
| `lore deps --format sbom` | CycloneDX 1.4 SBOM (NTIA compliant) |
| `lore deps --format html` | Shareable HTML security report |
| `lore deps --format json` | Machine-readable manifest |
| `lore pr --platform github --repo owner/repo --pr 42` | PR analysis |

---

## Installation

### Prerequisites
- Python 3.10+
- [Ollama](https://ollama.com) — runs the local LLM
- Git (for `lore changelog`, `lore pr`, auto-reindex hook)

### Install

```bash
git clone https://github.com/smithbuilds/lore
cd lore
python -m venv venv
source venv/Scripts/activate   # Windows Git Bash
# source venv/bin/activate     # Mac/Linux
pip install -e .
```

### PyTorch (GPU acceleration)

```bash
# Standard CUDA install
pip install torch --index-url https://download.pytorch.org/whl/cu121

# RTX 40/50 series (requires nightly cu128)
pip install --pre torch --index-url https://download.pytorch.org/whl/nightly/cu128
```

> **Note:** Lore works without GPU acceleration — it just runs slower. The `lore init --wizard` will pull the right model for your hardware automatically.

### Model Selection

Lore auto-detects your hardware and selects the best available Ollama model. You don't need to specify a model — it adapts to whatever you have installed.

| VRAM | Model Selected | Quality |
|------|---------------|---------|
| 20 GB+ | deepseek-coder:33b | Tier 5 |
| 10 GB+ | codellama:13b | Tier 4 |
| 5 GB+ | deepseek-coder:6.7b | Tier 3 |
| 5 GB+ | mistral:7b | Tier 2 |
| CPU only | codellama:7b-cpu | Tier 1 |

---

## Docker (Server Mode)

```bash
# Start the Lore server
MSYS_NO_PATHCONV=1 docker compose up lore-server -d

# Index a codebase
MSYS_NO_PATHCONV=1 docker compose run --rm lore-server python -c "
import os, sys
sys.path.insert(0, '/app')
os.environ['CHROMA_DB_PATH'] = '/codebase/codebase_db'
from core.ingest import ingest_codebase
ingest_codebase('/codebase')
"

# Check status
curl http://localhost:8000/status
```

### Server API

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/status` | Health check + model status |
| GET | `/query/stream` | SSE streaming query |
| POST | `/query` | Blocking query |
| POST | `/find` | Semantic search |
| POST | `/smell` | Smell score for a file |
| POST | `/impact` | Impact analysis |
| POST | `/sync` | Trigger re-index |
| POST | `/webhook/github` | GitHub push webhook |
| POST | `/webhook/gitlab` | GitLab push webhook |
| POST | `/webhook/bitbucket` | Bitbucket push webhook |

---

## Architecture

```
lore ask "question"
    │
    ▼
query.py  ──  embed question  ──►  ChromaDB  ──  top K chunks  ──►  Ollama (local LLM)
                                                                          │
                                                                          ▼
                                                                   answer + sources

Ingestion (once):
  codebase → chunker.py → ingest.py → embedder → ChromaDB

Auto-update (on every commit):
  git commit → post-commit hook → incremental_update.py → ChromaDB

Team/Enterprise:
  GitHub/GitLab push → webhook_handler.py → incremental_update.py → ChromaDB
```

---

## Technology Stack

| Component | Technology |
|-----------|-----------|
| LLM inference | Ollama (local) — model auto-selected by hardware |
| Vector DB | ChromaDB (persistent, local) |
| Embeddings | nomic-ai/nomic-embed-text-v1 (local) |
| Code parsing | tree-sitter (multi-language AST) |
| CLI | Click + Rich |
| Server | FastAPI + uvicorn |
| SBOM | CycloneDX 1.4 |

---

## VS Code Extension

Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=smithbuilds.lore-vscode) or search `Lore` in VS Code extensions.

- Ask questions from the sidebar with word-by-word streaming answers
- Markdown rendering with syntax highlighting
- Connects to the Lore server or falls back to local CLI

---

## Demo Flow

```bash
lore status                                        # health check
lore ask "how does authentication work?"           # streaming Q&A
lore explain --file core/query.py                  # deep dive
lore changelog --last 10                           # plain English changelog
lore deps --format html                            # open HTML security report
lore deps --format sbom                            # CycloneDX SBOM for compliance
```

---

## Known Issues

- Always prefix Docker commands with `MSYS_NO_PATHCONV=1` in Git Bash
- `FutureWarning: torch._dynamo.allow_in_graph` — harmless, from PyTorch nightly
- Never use `pip install --force-reinstall` — breaks nightly PyTorch builds
- `lore dead` — start with `--min-confidence high` to reduce false positives

---

## License

[Business Source License 1.1](LICENSE) — free for individual, non-commercial use.  
Converts to Apache 2.0 on April 2, 2030.  
Commercial use requires a [paid license](https://get-lore.com).

Built by [SmithBuilds LLC](https://smithbuilds.net) · [get-lore.com](https://get-lore.com)
