lilbee 0.3.1__tar.gz

lilbee-0.3.1/.beads/.gitignore

@@ -0,0 +1,54 @@
+# Dolt database (managed by Dolt, not git)
+dolt/
+dolt-access.lock
+
+# Runtime files
+bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+.jsonl.lock
+sync_base.jsonl
+export-state/
+
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+daemon.lock
+daemon.log
+daemon-*.log.gz
+daemon.pid
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

lilbee-0.3.1/.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with Dolt remote
+bd dolt push
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

lilbee-0.3.1/.beads/config.yaml

@@ -0,0 +1,42 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of the Dolt database
+# no-db: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

lilbee-0.3.1/.beads/hooks/post-checkout

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) post-checkout hook - thin shim
+#
+# This shim delegates to 'bd hooks run post-checkout' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    # Silently skip - post-checkout is called frequently
+    exit 0
+fi
+
+exec bd hooks run post-checkout "$@"

lilbee-0.3.1/.beads/hooks/post-merge

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) post-merge hook - thin shim
+#
+# This shim delegates to 'bd hooks run post-merge' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping post-merge hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run post-merge "$@"

lilbee-0.3.1/.beads/hooks/pre-commit

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v2
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) pre-commit hook — thin shim
+#
+# Delegates to 'bd hooks run pre-commit' which contains the actual hook
+# logic. This pattern ensures hook behavior is always in sync with the
+# installed bd version — no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-commit hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run pre-commit "$@"

lilbee-0.3.1/.beads/hooks/pre-push

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) pre-push hook - thin shim
+#
+# This shim delegates to 'bd hooks run pre-push' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-push hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run pre-push "$@"

lilbee-0.3.1/.beads/hooks/prepare-commit-msg

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.48.0
+#
+# bd (beads) prepare-commit-msg hook - thin shim
+#
+# This shim delegates to 'bd hooks run prepare-commit-msg' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# Arguments:
+#   $1 = path to the commit message file
+#   $2 = source of commit message (message, template, merge, squash, commit)
+#   $3 = commit SHA-1 (if -c, -C, or --amend)
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping prepare-commit-msg hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run prepare-commit-msg "$@"

lilbee-0.3.1/.beads/metadata.json

@@ -0,0 +1,7 @@
+{
+  "database": "dolt",
+  "jsonl_export": "issues.jsonl",
+  "backend": "dolt",
+  "dolt_mode": "server",
+  "dolt_database": "beads_bb"
+}

lilbee-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: make lint
+
+      - name: Format check
+        run: make format-check
+
+      - name: Type check
+        run: make typecheck
+
+      - name: Check imports resolve
+        run: uv run python -c "import lilbee; from lilbee import cli, config, chunker, code_chunker, embedder, store, ingest, query"
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run unit tests with coverage
+        run: make test
+        env:
+          LILBEE_DATA: ${{ runner.temp }}/lilbee
+
+  test-with-ollama:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install Ollama
+        run: curl -fsSL https://ollama.com/install.sh | sh
+
+      - name: Start Ollama and pull models
+        run: |
+          ollama serve &
+          sleep 5
+          ollama pull nomic-embed-text
+          ollama pull mistral
+
+      - name: Run full test suite (including accuracy)
+        run: uv run pytest tests/ -v
+        env:
+          LILBEE_DATA: ${{ runner.temp }}/lilbee

lilbee-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lilbee-0.3.1/.gitignore

@@ -0,0 +1,20 @@
+data/
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.pdf
+*.html
+*.txt
+CLAUDE.md
+.worktrees/
+docs/plans/
+demo.cast

lilbee-0.3.1/AGENTS.md

@@ -0,0 +1,146 @@
+# lilbee — Development Guide
+
+## Project
+Local RAG knowledge base. Python 3.11+, Ollama for LLM/embeddings, LanceDB for vectors. Managed with `uv`. Task tracking with `beads` (`bd`). Learned behaviors with `floop`.
+
+## Task Tracking (beads)
+```bash
+bd ready                      # See what's ready to work on
+bd update <id> -s in_progress # Claim a task
+bd close <id>                 # Mark done
+bd list                       # All issues
+```
+Every code change MUST be tracked as a beads task. Create tasks before starting work, close them when done.
+
+## Commands
+```bash
+uv sync                       # Install dependencies
+make check                    # Run all checks: lint, format, typecheck, test (same as CI)
+make test                     # Tests with coverage
+make lint                     # Ruff linting
+make typecheck                # Mypy
+make format                   # Auto-format code
+uv run lilbee sync            # Sync documents to vector DB
+uv run lilbee ask "question"
+uv run lilbee chat
+uv run lilbee status
+uv run lilbee rebuild
+```
+
+## Architecture
+- `src/lilbee/` — All source code
+- Documents + data stored in platform-standard location (see `lilbee status`)
+  - macOS: `~/Library/Application Support/lilbee/`
+  - Linux: `~/.local/share/lilbee/`
+  - Windows: `%LOCALAPPDATA%/lilbee/`
+  - Override: `LILBEE_DATA=/path` or `--data-dir`
+- All settings configurable via `LILBEE_*` env vars or CLI flags
+- Auto-sync: documents/ is source of truth, data/ is rebuilt from it
+
+## Configuration
+All settings override via environment variables:
+- `LILBEE_DATA` — data directory path
+- `LILBEE_CHAT_MODEL` — LLM model (default: `mistral`)
+- `LILBEE_EMBEDDING_MODEL` — embedding model (default: `nomic-embed-text`)
+- `LILBEE_EMBEDDING_DIM` — embedding dimensions (default: `768`)
+- `LILBEE_CHUNK_SIZE` — tokens per chunk (default: `512`)
+- `LILBEE_CHUNK_OVERLAP` — overlap tokens (default: `100`)
+- `LILBEE_TOP_K` — retrieval result count (default: `5`)
+
+CLI also accepts `--model` / `-m` for chat model and `--data-dir` / `-d`.
+
+## Code Quality Rules
+
+### Test-Driven Development
+- **100% test coverage required** — enforced by `pytest-cov` with `fail_under = 100`
+- Write tests BEFORE or alongside implementation, not after
+- Every public function MUST have at least one test
+- Mock all external dependencies (Ollama, filesystem I/O where needed) — tests must run without a live server
+- Use `pytest.mark.skipif` only for integration tests that genuinely require live services
+- Use `tmp_path` fixtures for filesystem tests — never write to real paths
+- Test edge cases and error paths, not just the happy path
+- Tests are documentation — name them descriptively (`test_add_nonexistent_fails`, not `test_add_3`)
+
+### DRY & Modularity
+- **Don't Repeat Yourself** — extract shared logic into helpers when duplicated
+- Single Responsibility — each function does one thing well
+- Small functions — max ~20 lines, max 2 levels of nesting
+- Low cyclomatic complexity — extract helpers when branches exceed 3
+- **Use maps for classification/dispatch** — if-chains that map values to categories belong in a dict, not repeated `if`/`elif` blocks
+- Compose small functions rather than writing monolithic ones
+- If you need to copy-paste code, refactor into a shared function instead
+
+### Code Style
+- No LangChain — raw Ollama SDK
+- Type hints on all public functions
+- Dataclasses for structured return types (not raw dicts)
+- Named constants for magic numbers — with descriptive comments
+- Descriptive variable names — `pending_segments` not `current`, `chunk_size` not `n`
+- Logging with `logging.getLogger(__name__)` — no bare `except: pass`
+- No hardcoded values — all configurable through `config.py` with env var overrides
+- Imports: stdlib first, then third-party, then local — no star imports
+- Lazy imports in CLI callbacks (avoid loading heavy deps at import time)
+- Linting: `ruff check` + `ruff format` (line length 100)
+- Type checking: `mypy` with strict settings
+
+### YAGNI & Simplicity
+- Don't add features, abstractions, or config that isn't needed yet
+- Three similar lines are better than a premature abstraction
+- Only validate at system boundaries (user input, external APIs) — trust internal code
+- No backwards-compatibility shims — if something is unused, delete it
+
+### Git & Workflow
+- Every change tracked as a beads task (`bd create` → `bd close`)
+- Run `make check` before closing any task — it mirrors CI exactly
+- Tests, lint, and type checks must pass before closing a task
+- CI runs on every push and PR
+
+### Behavior Learning (floop)
+- `floop` captures corrections and learned behaviors across sessions
+- Hooks run automatically via `~/.claude/settings.json` (session-start, dynamic-context, detect-correction)
+- `floop active` — show behaviors active in current context
+- `floop learn` — manually capture a correction/behavior
+- `floop list` — list all learned behaviors
+- `floop prompt` — generate prompt section from active behaviors
+
+## Agent Integration
+
+lilbee has a local knowledge base you can query. Use it for domain-specific questions about the user's documents.
+
+### MCP Server (recommended)
+
+An MCP server is configured in `.claude/settings.json` for this project. Tools available:
+
+| Tool | Description | Requires Ollama |
+|------|-------------|-----------------|
+| `lilbee_search(query, top_k)` | Search for relevant chunks | No |
+| `lilbee_status()` | Show indexed docs and config | No |
+| `lilbee_sync()` | Sync documents to vector store | Yes (embedding) |
+
+Prefer `lilbee_search` — it returns pre-embedded chunks without calling Ollama at query time.
+
+### JSON CLI (fallback)
+
+All commands accept `--json` (before the subcommand) for structured output:
+
+```bash
+lilbee --json search "query" --top-k 5
+lilbee --json ask "question"
+lilbee --json status
+lilbee --json sync
+```
+
+Every command returns a single JSON object on stdout. Errors return non-zero exit + `{"error": "message"}`.
+
+See [docs/agent-integration.md](docs/agent-integration.md) for full reference.
+
+## Key Files
+- `config.py` — All settings (env-var configurable)
+- `ingest.py` — Document sync engine (hash-based change detection)
+- `query.py` — RAG pipeline (embed → search → generate)
+- `store.py` — LanceDB operations
+- `chunker.py` — Text chunking (token-based recursive)
+- `code_chunker.py` — Code chunking (tree-sitter AST)
+- `embedder.py` — Ollama embedding wrapper
+- `cli.py` — Typer CLI with --model, --data-dir, --version, and --json flags
+- `mcp.py` — MCP server exposing search, ask, status, sync as tools

lilbee-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tobocop2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lilbee-0.3.1/Makefile

@@ -0,0 +1,37 @@
+.PHONY: lint format format-check typecheck test check clean install demo build publish
+
+lint:
+	uv run ruff check src/ tests/
+
+format:
+	uv run ruff format src/ tests/
+
+format-check:
+	uv run ruff format --check src/ tests/
+
+typecheck:
+	uv run mypy src/lilbee/
+
+test:
+	uv run pytest --cov=lilbee --cov-report=term-missing -v
+
+check: lint format-check typecheck test  ## Run all checks (same as CI)
+
+install:
+	uv tool install . --force --reinstall
+
+demo:  ## Record all demo GIFs via VHS
+	vhs demos/chat.tape
+	vhs demos/code-search.tape
+	vhs demos/json.tape
+	vhs demos/opencode.tape
+
+build:
+	uv build
+
+publish: build  ## Build and upload to PyPI
+	uv publish
+
+clean:
+	rm -rf .mypy_cache .pytest_cache .ruff_cache htmlcov .coverage dist/
+	find . -type d -name __pycache__ -exec rm -rf {} +