Skip to content

getting-started.md

Latest commit

 

History

History
91 lines (66 loc) · 3.11 KB

getting-started.md

File metadata and controls

91 lines (66 loc) · 3.11 KB
Raw

Getting Started

Prerequisites

  • Rust (latest stable) — install via rustup
  • Ollama — install from ollama.com, or an OpenAI API key
  • A compatible model (Ollama default: qwen3:8b)
ollama pull qwen3:8b

Build & Run

# Build
cargo build

# Run CLI
cargo run

# Run tests
cargo test

The agent starts an interactive REPL. Type your message at the > prompt. Enter exit or quit to stop.

Configuration

Everything is configured with environment variables. The Configuration Reference is the single source of truth for the full list, defaults, and per-variable detail — this page only shows what you need for a first run.

Variable Default Why you would set it
LLM_PROVIDER ollama Switch to openai. This is what selects the backend — setting OPENAI_API_KEY alone does nothing.
OLLAMA_MODEL qwen3:8b Use a different local model
OPENAI_API_KEY (none) Required when LLM_PROVIDER=openai 
# Default: local Ollama with the default model
cargo run

# Pick a different local model
OLLAMA_MODEL=llama3:latest cargo run

# Or use OpenAI instead
LLM_PROVIDER=openai OPENAI_API_KEY=sk-... cargo run

What Happens on Startup

  1. Config::from_env() reads environment variables
  2. The provider is built from LLM_PROVIDER (OllamaProvider or OpenAIProvider)
  3. CandleEmbeddingProvider loads a BERT model (all-MiniLM-L6-v2) from HuggingFace
  4. LanceVectorStore opens or creates the vector database
  5. ToolEngine registers 5 built-in filesystem/shell tools
  6. GraphAgent wires LLM + tools + memory together
  7. The REPL loop begins

If RAG initialization fails (no HuggingFace access, missing model), the agent still starts with all other features — SearchDocsTool is simply not registered, so only search_docs is unavailable. With RAG enabled, 6 tools are registered. The one startup that does abort is selecting OpenAI without OPENAI_API_KEY, which exits with an AgentError::LLMError.

For the full call-by-call startup sequence, see Architecture §4「Startup Sequence」.

Indexing Documents for RAG

The vector store is empty by default. To populate it, use the index subcommand:

cargo run -- index ./docs

This walks the directory tree and, for each file with a .md, .txt, .rs, .toml, .json, .yaml, or .yml extension:

  • splits the content into chunks of at most 512 bytes, preferring to break on a newline near the end of each window
  • skips any chunk whose content hash has already been indexed in this run (re-indexing the same tree does not create duplicate entries)
  • embeds each chunk with BERT and stores the vector in LanceDB

The command reports the number of chunks indexed, files processed, and duplicates skipped. Any single file that fails to read is logged and skipped rather than aborting the run.

To see how this connects to the search_docs tool, see Architecture §6「RAG Pipelines」.