Skip to content

Commit 007c66e

Browse files
zTgxzTgx
committed
docs(readme): add comprehensive configuration documentation
- Add detailed configuration section covering zero configuration setup - Document environment variables including OPENAI_API_KEY, VECTORLESS_MODEL, VECTORLESS_ENDPOINT, and VECTORLESS_WORKSPACE - Provide Python and Rust code examples for different configuration methods - Explain configuration priority hierarchy from defaults to constructor parameters - Update examples reference to include more usage patterns feat(engine): enhance configuration with environment variable support - Implement environment variable overrides for API key, model, endpoint, and workspace - Add configuration priority system with 5 levels from defaults to constructor parameters - Support zero configuration through OPENAI_API_KEY environment variable - Add config_path parameter for advanced configuration file usage - Update Python and Rust engines with new configuration options refactor(examples): reorganize examples by language with new configuration patterns - Move Python examples to examples/python/ directory - Move Rust examples to examples/rust/ directory - Add basic, advanced, and custom_config examples for both languages - Demonstrate zero configuration, full config file, and custom provider setups - Include examples for various LLM providers like DeepSeek, Azure OpenAI, and local LLMs docs(python): update Python engine documentation with configuration examples - Add configuration priority documentation - Include zero configuration and custom model usage examples - Document constructor parameters workspace, config_path, api_key, model, and endpoint - Show configuration hierarchy from defaults to constructor parameters docs(rust): enhance Rust builder documentation with configuration guide - Document configuration priority system with 5 levels - Add environment variable documentation table - Provide zero configuration, custom model, and full config file examples - Update builder methods to reflect new configuration approach build(rust): register Rust examples in Cargo.toml - Add all Rust example binaries to Cargo.toml manifest - Include examples for basic, advanced, custom_config, and other use cases - Register batch processing, CLI tool, content aggregation examples - Add storage and strategy pattern examples
1 parent 879c17d commit 007c66e

34 files changed

Lines changed: 919 additions & 34 deletions

‎README.md‎

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,105 @@ async fn main() -> vectorless::Result<()> {
163163
| **Feedback Learning** | Improves from user feedback over time |
164164
| **Multi-turn Queries** | Handles complex questions with decomposition |
165165

166+
## Configuration
167+
168+
### Zero Configuration (Recommended)
169+
170+
Just set `OPENAI_API_KEY` and you're ready to go:
171+
172+
```bash
173+
export OPENAI_API_KEY="sk-..."
174+
```
175+
176+
<details>
177+
<summary><b>Python</b></summary>
178+
179+
```python
180+
from vectorless import Engine
181+
182+
# Uses OPENAI_API_KEY from environment
183+
engine = Engine(workspace="./data")
184+
```
185+
186+
</details>
187+
188+
<details>
189+
<summary><b>Rust</b></summary>
190+
191+
```rust
192+
use vectorless::Engine;
193+
194+
let client = Engine::builder()
195+
.with_workspace("./workspace")
196+
.build().await?;
197+
```
198+
199+
</details>
200+
201+
### Environment Variables
202+
203+
| Variable | Description |
204+
|----------|-------------|
205+
| `OPENAI_API_KEY` | LLM API key |
206+
| `VECTORLESS_MODEL` | Default model (e.g., `gpt-4o-mini`) |
207+
| `VECTORLESS_ENDPOINT` | API endpoint URL |
208+
| `VECTORLESS_WORKSPACE` | Workspace directory |
209+
210+
### Advanced Configuration
211+
212+
For fine-grained control, use a config file:
213+
214+
```bash
215+
cp config.toml ./vectorless.toml
216+
```
217+
218+
<details>
219+
<summary><b>Python</b></summary>
220+
221+
```python
222+
from vectorless import Engine
223+
224+
# Use full configuration file
225+
engine = Engine(config_path="./vectorless.toml")
226+
227+
# Or override specific settings
228+
engine = Engine(
229+
config_path="./vectorless.toml",
230+
model="gpt-4o", # Override model from config
231+
)
232+
```
233+
234+
</details>
235+
236+
<details>
237+
<summary><b>Rust</b></summary>
238+
239+
```rust
240+
use vectorless::Engine;
241+
242+
// Use full configuration file
243+
let client = Engine::builder()
244+
.with_config_path("./vectorless.toml")
245+
.build().await?;
246+
247+
// Or override specific settings
248+
let client = Engine::builder()
249+
.with_config_path("./vectorless.toml")
250+
.with_model("gpt-4o", None) // Override model
251+
.build().await?;
252+
```
253+
254+
</details>
255+
256+
### Configuration Priority
257+
258+
Later overrides earlier:
259+
260+
1. Default configuration
261+
2. Auto-detected config file (`vectorless.toml`, `config.toml`, `.vectorless.toml`)
262+
3. Explicit config file (`config_path` / `with_config_path`)
263+
4. Environment variables
264+
5. Constructor/builder parameters (highest priority)
166265

167266
## Architecture
168267

@@ -177,7 +276,7 @@ async fn main() -> vectorless::Result<()> {
177276

178277
## Examples
179278

180-
See the [examples/](examples/) directory.
279+
See the [examples/](examples/) directory for more usage patterns.
181280

182281
## Contributing
183282

‎examples/python/advanced.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
#!/usr/bin/env python3
2+
# Copyright (c) 2026 vectorless developers
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
"""
6+
Advanced usage example - Full Configuration.
7+
8+
This example demonstrates how to use a full configuration file
9+
for advanced use cases where you need fine-grained control.
10+
11+
Usage:
12+
# First, copy the example config
13+
cp config.toml ./my_vectorless.toml
14+
15+
# Edit my_vectorless.toml to customize settings
16+
17+
# Run the example
18+
python advanced.py
19+
"""
20+
21+
import os
22+
import tempfile
23+
from vectorless import Engine, IndexContext
24+
25+
26+
def main():
27+
print("=== Vectorless Advanced Example (Full Configuration) ===\n")
28+
29+
# Method 1: Use explicit config file path
30+
# This loads all settings from the specified config file
31+
engine = Engine(config_path="./config.toml")
32+
33+
print("✓ Engine created with config file\n")
34+
35+
# Index a document
36+
content = """
37+
# Product Documentation
38+
39+
## Overview
40+
41+
This is a comprehensive guide for our product.
42+
43+
## Configuration
44+
45+
The system supports multiple configuration methods:
46+
47+
### 1. Zero Configuration
48+
Just set OPENAI_API_KEY environment variable.
49+
50+
### 2. Environment Variables
51+
- VECTORLESS_MODEL: Set default model
52+
- VECTORLESS_ENDPOINT: Set API endpoint
53+
- VECTORLESS_WORKSPACE: Set workspace directory
54+
55+
### 3. Config File
56+
Create a vectorless.toml file with full configuration.
57+
58+
## API Reference
59+
60+
### Engine
61+
The main entry point for vectorless.
62+
63+
### IndexContext
64+
Context for indexing documents from various sources.
65+
"""
66+
ctx = IndexContext.from_text(content, name="docs", format="markdown")
67+
doc_id = engine.index(ctx)
68+
print(f"✓ Indexed: {doc_id}\n")
69+
70+
# Query
71+
result = engine.query(doc_id, "What configuration methods are available?")
72+
print("Query: What configuration methods are available?")
73+
print(f"Score: {result.score:.2f}")
74+
print(f"Result: {result.content[:200]}...\n")
75+
76+
# Cleanup
77+
engine.remove(doc_id)
78+
print("✓ Cleaned up")
79+
80+
print("\n" + "=" * 60)
81+
print("Configuration Options")
82+
print("=" * 60)
83+
print()
84+
print("Configuration Priority (later overrides earlier):")
85+
print(" 1. Default configuration")
86+
print(" 2. Auto-detected config file (vectorless.toml, config.toml)")
87+
print(" 3. Explicit config file (config_path parameter)")
88+
print(" 4. Environment variables")
89+
print(" 5. Constructor parameters (api_key, model, etc.)")
90+
print()
91+
print("Environment Variables:")
92+
print(" OPENAI_API_KEY - LLM API key")
93+
print(" VECTORLESS_MODEL - Default model name")
94+
print(" VECTORLESS_ENDPOINT - API endpoint URL")
95+
print(" VECTORLESS_WORKSPACE - Workspace directory")
96+
print()
97+
print("Usage Examples:")
98+
print()
99+
print("# Zero configuration (recommended for beginners)")
100+
print('engine = Engine(workspace="./data")')
101+
print()
102+
print("# With custom model")
103+
print('engine = Engine(workspace="./data", model="gpt-4o-mini")')
104+
print()
105+
print("# With full config file (advanced)")
106+
print('engine = Engine(config_path="./vectorless.toml")')
107+
print()
108+
print("# Override config with parameters")
109+
print('engine = Engine(')
110+
print(' config_path="./vectorless.toml",')
111+
print(' model="gpt-4o", # Override model from config')
112+
print(')')
113+
114+
print("\n=== Done ===")
115+
116+
117+
if __name__ == "__main__":
118+
main()

‎examples/python/basic.py‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
#!/usr/bin/env python3
2+
# Copyright (c) 2026 vectorless developers
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
"""
6+
Basic usage example - Zero Configuration.
7+
8+
This example demonstrates the simplest way to use Vectorless.
9+
Just set OPENAI_API_KEY environment variable and you're ready to go.
10+
11+
Usage:
12+
export OPENAI_API_KEY="sk-..."
13+
python basic.py
14+
"""
15+
16+
import os
17+
import tempfile
18+
from vectorless import Engine, IndexContext
19+
20+
21+
def main():
22+
print("=== Vectorless Basic Example (Zero Configuration) ===\n")
23+
24+
# Zero configuration: Just set OPENAI_API_KEY environment variable
25+
# The engine will automatically use it.
26+
with tempfile.TemporaryDirectory() as workspace:
27+
engine = Engine(workspace=workspace)
28+
29+
print("✓ Engine created (using OPENAI_API_KEY from environment)\n")
30+
31+
# Index from text content
32+
content = """
33+
# Technical Manual
34+
35+
## Chapter 1: Introduction
36+
37+
Vectorless is a library for querying structured documents using natural language.
38+
39+
## Chapter 2: Installation
40+
41+
Install with pip:
42+
```
43+
pip install vectorless
44+
```
45+
46+
## Chapter 3: Usage
47+
48+
```python
49+
from vectorless import Engine, IndexContext
50+
51+
engine = Engine(workspace="./data")
52+
ctx = IndexContext.from_file("./report.pdf")
53+
doc_id = engine.index(ctx)
54+
55+
result = engine.query(doc_id, "What is the total revenue?")
56+
print(result.content)
57+
```
58+
"""
59+
ctx = IndexContext.from_text(content, name="manual", format="markdown")
60+
doc_id = engine.index(ctx)
61+
print(f"✓ Indexed: {doc_id}\n")
62+
63+
# Query
64+
result = engine.query(doc_id, "How do I install vectorless?")
65+
print("Query: How do I install vectorless?")
66+
print(f"Score: {result.score:.2f}")
67+
print(f"Result: {result.content[:200]}...\n")
68+
69+
# Cleanup
70+
engine.remove(doc_id)
71+
print("✓ Cleaned up")
72+
73+
print("\n=== Done ===")
74+
75+
76+
if __name__ == "__main__":
77+
if not os.environ.get("OPENAI_API_KEY"):
78+
print("Error: OPENAI_API_KEY environment variable not set.")
79+
print("Set it with: export OPENAI_API_KEY='sk-...'")
80+
exit(1)
81+
82+
main()

0 commit comments

Comments
 (0)