Metadata-Version: 2.5
Name: basemode-loom
Version: 0.2.1
Summary: Persistent branching exploration for basemode continuations
Project-URL: Documentation, https://fergusfettes.github.io/basemode-loom/
Project-URL: Repository, https://github.com/FergusFettes/basemode-loom
Project-URL: Issues, https://github.com/FergusFettes/basemode-loom/issues
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: basemode>=0.1.6
Requires-Dist: fastapi>=0.115.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: textual>=0.85.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: embed
Requires-Dist: sqlite-vec>=0.1.6; extra == 'embed'
Provides-Extra: embed-mlx
Requires-Dist: mlx-embeddings>=0.0.3; extra == 'embed-mlx'
Requires-Dist: sqlite-vec>=0.1.6; extra == 'embed-mlx'
Description-Content-Type: text/markdown

# basemode-loom

Persistent branching exploration for LLM continuations.

`basemode-loom` lets you generate multiple continuations, navigate a tree of alternatives, and keep everything in a local SQLite store so you can resume later.

## Install

```bash
pip install basemode-loom
```

## Quickstart

```bash
# Create a new tree with 3 branches
basemode-loom run "The ship rounded the headland and" -n 3 -m gpt-4o-mini

# Open the interactive explorer
basemode-loom view

# Continue from selected branch
basemode-loom continue -b 2 -n 3
```

## Core Commands

```bash
basemode-loom --help
basemode-loom view --help
basemode-loom run --help
basemode-loom continue --help
basemode-loom stats --help
basemode-loom serve --help
```

Useful commands:

- `basemode-loom view`: interactive TUI tree explorer
- `basemode-loom run`: create a new tree from a prompt
- `basemode-loom continue`: branch from current/selected node
- `basemode-loom nodes|active|show|children`: inspect stored trees
- `basemode-loom stats`: analyze tree depth/branching/model usage
- `basemode-loom export|import`: move trees in/out as JSON/Markdown
- `basemode-loom serve`: run REST/WebSocket API for frontend usage

## Tree Search

The TUI tree picker (`Tab`) supports live metadata filtering, category/domain/
source/model facets, ID lookup, FTS5 keyword search, and semantic search when
the selected database contains a compatible vector index.

Guardian Angel corpora use the optional MLX search dependencies:

```bash
pip install 'basemode-loom[embed-mlx]'
basemode-loom view --db /path/to/corpus.sqlite
```

Press `/` in the tree picker, enter a query, and press `Enter` to rank matching
trees. Build or update an embedding index directly with:

```bash
basemode-loom embed --db /path/to/corpus.sqlite --model mlx
basemode-loom embed --db /path/to/corpus.sqlite --model mlx --incremental
```

The MLX model is downloaded lazily on first use. Embedding dependencies remain
isolated in the optional `embed` and `embed-mlx` installation extras.

## Model Selection

- TUI model picker is available via `m`.
- Picker can consume verified model metadata from `basemode` when available.
- Session state supports model-plan metadata for multi-model generation workflows.
- Force OpenRouter passthrough for new/unknown IDs with `-m "or:vendor/model"` (or `openrouter:vendor/model`), e.g. `-m "or:moonshotai/kimi-k2.6"`.

## Storage

By default, data is stored in a local SQLite DB under your user data directory.
Use `--db /path/to/file.sqlite` to choose a custom location.

## Docs

Project docs live in `docs/` (MkDocs):

```bash
make docs
make docs-serve
```

Then open `http://localhost:8001`.
