Metadata-Version: 2.5
Name: lode-cli
Version: 0.1.0a1
Summary: Lode is a local-first knowledge mining engine that turns your workspace into a searchable knowledge lode.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: blake3>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: lode-simple-native>=0.7.1
Requires-Dist: pathspec>=0.11.0
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: python-docx>=1.2.0
Requires-Dist: rich>=13.10.0
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: typer>=0.27.1
Description-Content-Type: text/markdown

# Lode

> No need to build another knowledge base. Your workspace is already a lode of knowledge.

Lode is a local-first knowledge mining engine that turns your workspace into a searchable knowledge lode.

> [!WARNING]
> Lode is currently in early development.
> Features may be incomplete, behavior may change, and breaking changes may occur before the first stable release.

## Why Lode?

Your knowledge already exists.

It lives in:

- Documentation explaining concepts and decisions.
- Markdown notes capturing project knowledge.
- Design documents describing systems and workflows.
- Text files accumulated throughout development.

The problem is not storing more knowledge.

The problem is finding the right piece of knowledge when you need it.

Lode helps AI agents access workspace-specific knowledge by indexing existing documents and exposing them through semantic and lexical retrieval.

Instead of relying only on general-purpose models, agents can access the information that belongs to your projects.

## Install

### Install from source

1. Clone the repository:

    ```bash
    git clone https://github.com/cubelitblade/lode.git
    cd lode
    ```

2. Install:

    ```bash
    uv tool install .
    ```

3. Verify:

    ```bash
    lode --help
    ```

## Quickstart

### 1. Provide an embedding server

Lode does not ship with an embedding model. Bring your own embedding provider.
Lode supports local embedding servers such as Text Embeddings Inference (TEI), as well as OpenAI-compatible embedding APIs.

> [!TIP]
> The easiest way to start is using Hugging Face TEI:
>
> For example:
>
> ```bash
> mkdir -p $PWD/data
>
> model=Qwen/Qwen3-Embedding-0.6B
> volume=$PWD/data
>
> docker run --gpus all \
>   -p 8080:80 \
>   -v $volume:/data \
>   --pull always \
>   ghcr.io/huggingface/text-embeddings-inference:cuda-latest \
>   --model-id $model
> ```
>
> For more information, see [Hugging Face: Text Embeddings Inference](https://huggingface.co/docs/text-embeddings-inference/index).

### 2. Configure Lode

Set your embedding provider:

```bash
lode config set embedding.provider "openai_compatible" --scope user
lode config set embedding.openai_compatible.endpoint <endpoint> --scope user
lode config set embedding.model <model-name> --scope user
lode config set embedding.openai_compatible.key <api-key> --scope user # optional
```

For a TEI native endpoint, use `tei_native` instead:

```bash
lode config set embedding.provider "tei_native" --scope user
lode config set embedding.tei_native.endpoint <endpoint> --scope user
lode config set embedding.model <model-name> --scope user
```

Workspace-specific configuration can also be created using workspace scope.

### 3. Survey a workspace

Discover documents in your workspace:

```bash
lode --workspace <path> survey
```

Survey builds the map of your knowledge lode.

### 4. Mine a workspace

Generate embeddings and store indexed chunks:

```bash
lode --workspace <path> mine
```

Mining processes discovered documents, generates embeddings, and stores searchable indexes locally in SQLite.

### 5. Prospect knowledge

Search your workspace:

```bash
lode --workspace <path> prospect <query>
```

Lode performs hybrid retrieval using semantic similarity and BM25 lexical matching.

It combines meaning-based search with exact keyword matching, then returns candidate chunks with scores and digests.

### 6. Dig the ore

Retrieve a specific chunk:

```bash
lode --workspace <path> dig <digest>
```

This returns the complete content associated with the digest.

## FAQ

### Why does lode fail to load SQLite extensions on macOS?

#### Possible reason

Lode requires SQLite extension loading for certain features.

Some Python builds, especially those linked against SQLite libraries without
loadable extension support, may not provide
`sqlite3.Connection.enable_load_extension()`.

This depends on how Python and SQLite were built, not only on the Python version.
CPython documents that loadable SQLite extension support is disabled by default
and notes macOS as a notable platform where the underlying SQLite library may
lack this capability.

You can verify the capability with:

```python
import sqlite3

print(hasattr(sqlite3.Connection, "enable_load_extension"))

```

#### Solution

- Use a separately installed Python distribution instead of the system-provided Python.
- In CI environments, explicitly configure the Python version and interpreter used by `uv`
  to avoid relying on the runner's preinstalled Python.

> For more information, see:
> - https://github.com/python/cpython/blob/main/Doc/library/sqlite3.rst
> - https://github.com/python/cpython/blob/main/Doc/using/configure.rst
