207 lines
4.9 KiB
Markdown
207 lines
4.9 KiB
Markdown
# Knowledge Base Nickel Schemas
|
|
|
|
This directory contains Nickel schema definitions for the knowledge base configuration system.
|
|
|
|
## Overview
|
|
|
|
The KOGRAL uses a **config-driven architecture** with Nickel providing type-safe configuration:
|
|
|
|
```text
|
|
.ncl files → nickel export --format json → JSON → serde → Rust structs
|
|
```
|
|
|
|
**Benefits:**
|
|
- Type safety at config definition time (Nickel type checker)
|
|
- Composition and reuse (Nickel imports)
|
|
- Runtime type-safe Rust structs (serde)
|
|
- Clear contracts and documentation
|
|
|
|
## Schema Files
|
|
|
|
| File | Purpose |
|
|
| --- | --- |
|
|
| `types.ncl` | Shared type definitions (enums, primitives) |
|
|
| `kogral-config.ncl` | Main configuration schema (KbConfig) |
|
|
| `frontmatter.ncl` | Document frontmatter schema (YAML in .md files) |
|
|
|
|
## Usage
|
|
|
|
### Export Schema to JSON
|
|
|
|
```bash
|
|
# Export a configuration file
|
|
nickel export --format json config/defaults.ncl > .kogral/config.json
|
|
|
|
# Export minimal config
|
|
nickel export --format json config/minimal.ncl > .kogral/config.json
|
|
|
|
# Export production config
|
|
nickel export --format json config/production.ncl > .kogral/config.json
|
|
```
|
|
|
|
### Create Custom Configuration
|
|
|
|
```nickel
|
|
# my-kogral-config.ncl
|
|
let Schema = import "schemas/kogral-config.ncl" in
|
|
|
|
{
|
|
graph = {
|
|
name = "my-project",
|
|
version = "1.0.0",
|
|
},
|
|
|
|
embeddings = {
|
|
provider = 'ollama,
|
|
model = "llama2",
|
|
},
|
|
|
|
# Other fields use defaults
|
|
} | Schema.KbConfig
|
|
```
|
|
|
|
### Type Checking
|
|
|
|
Nickel will validate your configuration against the schema:
|
|
|
|
```bash
|
|
# Check configuration without exporting
|
|
nickel typecheck my-kogral-config.ncl
|
|
|
|
# Export (also type-checks)
|
|
nickel export --format json my-kogral-config.ncl
|
|
```
|
|
|
|
## Schema Structure
|
|
|
|
### Main Config (`kogral-config.ncl`)
|
|
|
|
```nickel
|
|
KbConfig = {
|
|
graph: GraphConfig, # Graph metadata
|
|
inheritance: InheritanceConfig, # Guideline inheritance
|
|
storage: StorageConfig, # Storage backends
|
|
embeddings: EmbeddingConfig, # Embedding providers
|
|
templates: TemplateConfig, # Tera templates
|
|
query: QueryConfig, # Search behavior
|
|
mcp: McpConfig, # MCP server settings
|
|
sync: SyncConfig, # Filesystem ↔ DB sync
|
|
}
|
|
```
|
|
|
|
### Frontmatter (`frontmatter.ncl`)
|
|
|
|
```nickel
|
|
Frontmatter = {
|
|
id: String, # UUID
|
|
type: NodeType, # note, decision, etc.
|
|
title: String, # Human-readable title
|
|
created: Timestamp, # ISO 8601
|
|
modified: Timestamp, # ISO 8601
|
|
tags: Array String, # Categorization
|
|
status: NodeStatus, # draft, active, etc.
|
|
relates_to: Array String, # Relationships
|
|
# ... type-specific fields
|
|
}
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Default Configuration
|
|
|
|
See `config/defaults.ncl` for a fully documented example with sensible defaults.
|
|
|
|
### Minimal Configuration
|
|
|
|
```nickel
|
|
{
|
|
graph = { name = "my-kogral" },
|
|
} | Schema.KbConfig
|
|
```
|
|
|
|
All other fields will use schema defaults.
|
|
|
|
### Production Configuration
|
|
|
|
See `config/production.ncl` for a production setup with:
|
|
- SurrealDB backend enabled
|
|
- API-based embeddings (OpenAI)
|
|
- Optimized sync settings
|
|
|
|
## Field Defaults
|
|
|
|
All config fields have sensible defaults. Required fields:
|
|
|
|
- `graph.name` - Graph identifier
|
|
|
|
Optional fields (with defaults):
|
|
- `graph.version` → `"1.0.0"`
|
|
- `storage.primary` → `'filesystem`
|
|
- `embeddings.provider` → `'fastembed`
|
|
- `query.similarity_threshold` → `0.4`
|
|
- `mcp.server.transport` → `'stdio`
|
|
- ... (see schema files for complete list)
|
|
|
|
## Type Definitions
|
|
|
|
### Enums
|
|
|
|
Defined in `types.ncl`:
|
|
|
|
```nickel
|
|
NodeType = [| 'note, 'decision, 'guideline, 'pattern, 'journal, 'execution |]
|
|
NodeStatus = [| 'draft, 'active, 'superseded, 'archived |]
|
|
StorageType = [| 'filesystem, 'memory |]
|
|
EmbeddingProvider = [| 'openai, 'claude, 'ollama, 'fastembed |]
|
|
```
|
|
|
|
### Primitives
|
|
|
|
- `String` - Text values
|
|
- `Number` - Numeric values
|
|
- `Bool` - Boolean values
|
|
- `Array T` - Lists of type T
|
|
- `{ _ | T }` - Map/dictionary with values of type T
|
|
|
|
## Validation
|
|
|
|
Nickel enforces:
|
|
- **Required fields**: Must be present
|
|
- **Type constraints**: Values must match declared types
|
|
- **Enum values**: Must be one of the allowed variants
|
|
- **Default values**: Applied automatically if field omitted
|
|
|
|
Example error:
|
|
|
|
```bash
|
|
$ nickel export invalid-config.ncl
|
|
error: type error
|
|
┌─ invalid-config.ncl:5:15
|
|
│
|
|
5 │ provider = 'gpt4,
|
|
│ ^^^^^ this expression has type [| 'gpt4 |]
|
|
│
|
|
= Expected an expression of type [| 'openai, 'claude, 'ollama, 'fastembed |]
|
|
```
|
|
|
|
## Integration with Rust
|
|
|
|
The Rust code loads JSON via serde:
|
|
|
|
```rust
|
|
use kb_core::config::loader::load_config;
|
|
|
|
// Load from .kogral/config.{ncl,toml,json}
|
|
let config = load_config(None, None)?;
|
|
|
|
// Access type-safe fields
|
|
println!("Graph: {}", config.graph.name);
|
|
println!("Provider: {:?}", config.embeddings.provider);
|
|
```
|
|
|
|
## References
|
|
|
|
- [Nickel Language](https://nickel-lang.org/)
|
|
- [Nickel Documentation](https://nickel-lang.org/user-manual/)
|
|
- Rust schema types: `crates/kogral-core/src/config/schema.rs`
|