LoreBuilder CLI

A modular, persistent CLI for world-building and replayable, context-rich character conversations powered by LLMs, ChromaDB, and NLP.

---

Features

• Persistent Multi-Turn Chat – All conversations replayable via transactional SQLite logging.
• Semantic Lore Search – Contextual retrieval via ChromaDB vector DB and modern embeddings.
• LLM-Driven Stories – All generation/context managed via a master LoreService and LiteLLM.
• NLP-Powered Character Recognition – Flexible, quoted, multi-word, and fuzzy chat with lore-synced character list, powered by spaCy/rapidfuzz.
• Modular Command Registry & Dynamic Help – Only active commands appear in help/menus; per-command docs from handler docstrings.
• Rich Terminal UI – User-centric, colorized feedback with Rich.

---

Quickstart

git clone https://github.com/yourusername/lorebuilder-cli.git
cd lorebuilder-cli
pip install -r requirements.txt
python -m spacy download en_core_web_sm

• Configure your LLM API key in .env:

  LLM_API_KEY=your-model-api-key-here

• (Optional) Edit app.yaml for additional config.

Run the app:

python app.py

---

Usage

• Type help or help <command> inside the CLI.
• Example command categories:
  • Lore: add_lore, generate_lore, store_generated_lore, query_lore, list_all_lore, delete_lore
  • Characters: chat_as, list_characters
  • System: help, exit

---

Directory Structure

app.py               # Main entrypoint
bootstrap.py         # Service initialization
cli.py               # CLI REPL and UX
help.py, cli_utils.py# Help & output styling
commands/            # Modular command handlers
lore.py              # LoreService logic
lore_entities.py     # Entity extraction and NLP
chat_history.py      # Chat/session tracking
app.yaml             # Configuration
.env                 # API keys (never commit)
ARCHITECTURE.md      # Dev architecture doc

---

Persistent World Model

• Chat: lore_chat_history.db (SQLite)
• Lore: ChromaDB vector storage, kept in sync with entity extraction

---

Dependencies

• ChromaDB, SQLite3, LiteLLM, spaCy, rapidfuzz, Rich, python-dotenv, PyYAML

---

Documentation

• See ARCHITECTURE.md
• In-app help

---

Contributing

Pull requests welcome! Please open issues for bugs or feature requests.

---

Credits

• Significant Contributors:

  • Anthropic - Claude 3.7 and Claude 4
  • OpenAI - ChatGPT 4.1

• Inspirations & Foundations:

  • ChromaDB — Vector database design and docs
  • spaCy — NLP entity recognition pipeline
  • Rich — Terminal formatting and interactive UI

---

Contact

• Rodney Degracia https://rodneydegracia.com
• Email: rdegraci@mmail.com
• Linked In: https://www.linkedin.com/in/rdegraci/
• GitHub Issues: https://github.com/yourusername/lorebuilder-cli/issues

---

License

MIT (see LICENSE)