---
title: Configuration
description: Options and defaults for engine.New and the Forge extension.
---

## Engine options

`engine.New` accepts a variadic list of option functions:

```go
eng, err := engine.New(
    engine.WithStore(pgStore),            // required
    engine.WithVectorStore(pgVec),        // required
    engine.WithEmbedder(myEmbedder),      // required
    engine.WithChunker(myChunker),        // optional
    engine.WithLoader(myLoader),          // optional
    engine.WithRetriever(myRetriever),    // optional
    engine.WithExtension(metricsPlugin),  // optional, repeatable
    engine.WithLogger(slog.Default()),    // optional
)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `WithStore(s)` | `store.Store` | -- | **Required.** Metadata store for collections, documents, chunks. |
| `WithVectorStore(v)` | `vectorstore.VectorStore` | -- | **Required.** Vector store for embeddings. |
| `WithEmbedder(e)` | `embedder.Embedder` | -- | **Required.** Embedding model implementation. |
| `WithChunker(c)` | `chunker.Chunker` | recursive chunker | Text chunking implementation. |
| `WithLoader(l)` | `loader.Loader` | `nil` | Document loader for binary formats. |
| `WithRetriever(r)` | `retriever.Retriever` | built-in | Custom retrieval strategy. |
| `WithExtension(x)` | `plugins.Extension` | `nil` | Lifecycle hook plugin (repeatable). |
| `WithLogger(l)` | `*slog.Logger` | `slog.Default()` | Structured logger for internal events. |

## Default Config

```go
weave.Config{
    DefaultChunkSize:      512,                      // tokens
    DefaultChunkOverlap:   50,                       // tokens
    DefaultEmbeddingModel: "text-embedding-3-small",
    DefaultChunkStrategy:  "recursive",
    DefaultTopK:           10,
    ShutdownTimeout:       30 * time.Second,
    IngestConcurrency:     4,
}
```

These defaults apply when a `CreateCollectionInput` omits the corresponding field. Per-collection configuration overrides the engine defaults.

## Per-collection overrides

Each collection stores its own chunking and embedding configuration:

```go
col, _ := engine.CreateCollection(ctx, weave.CreateCollectionInput{
    Name:           "legal-docs",
    EmbeddingModel: "text-embedding-3-large",  // override default model
    EmbeddingDims:  3072,                      // must match model output
    ChunkStrategy:  "fixed",                   // override default strategy
    ChunkSize:      1024,                      // override default size
    ChunkOverlap:   100,                       // override default overlap
    Metadata:       map[string]string{
        "domain": "legal",
    },
})
```

When ingesting documents into this collection, Weave uses the collection's configuration rather than the engine defaults.

## Forge extension options

The `extension.New` function accepts its own set of options:

```go
ext := extension.New(
    extension.WithStore(pgStore),
    extension.WithVectorStore(pgVec),
    extension.WithExtension(metricsPlugin),
    extension.WithDisableRoutes(),
    extension.WithDisableMigrate(),
    extension.WithBasePath("/weave"),
    extension.WithGroveDatabase(""),
)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `WithStore(s)` | `store.Store` | -- | MetadataStore (auto-resolved from grove if not set). |
| `WithVectorStore(v)` | `vectorstore.VectorStore` | -- | Vector store. |
| `WithExtension(x)` | `plugins.Extension` | -- | Lifecycle hook plugin (repeatable). |
| `WithEngineOption(opt)` | `engine.Option` | -- | Pass engine option directly. |
| `WithConfig(cfg)` | `Config` | defaults | Full config struct. |
| `WithDisableRoutes()` | -- | `false` | Skip HTTP route registration. |
| `WithDisableMigrate()` | -- | `false` | Skip migrations on Start. |
| `WithBasePath(path)` | `string` | `"/weave"` | URL prefix for all weave routes. |
| `WithGroveDatabase(name)` | `string` | `""` | Named grove.DB to resolve from DI. |
| `WithRequireConfig(b)` | `bool` | `false` | Require config in YAML files. |

## File-based configuration (YAML)

When running as a Forge extension, Weave automatically loads configuration from YAML config files. The extension looks for config under the following keys (in order):

1. `extensions.weave` -- standard Forge extension config namespace
2. `weave` -- top-level shorthand

### Example

```yaml
# forge.yaml
extensions:
  weave:
    disable_routes: false
    disable_migrate: false
    base_path: "/weave"
    default_chunk_size: 512
    default_chunk_overlap: 50
    default_embedding_model: "text-embedding-3-small"
    default_chunk_strategy: "recursive"
    default_top_k: 10
    shutdown_timeout: "30s"
    ingest_concurrency: 4
    grove_database: ""
```

### Config fields

| YAML Key | Type | Default | Description |
|----------|------|---------|-------------|
| `disable_routes` | `bool` | `false` | Skip HTTP route registration |
| `disable_migrate` | `bool` | `false` | Skip migrations on Start |
| `base_path` | `string` | `"/weave"` | URL prefix for all routes |
| `default_chunk_size` | `int` | `512` | Default tokens per chunk |
| `default_chunk_overlap` | `int` | `50` | Default token overlap |
| `default_embedding_model` | `string` | `"text-embedding-3-small"` | Default embedding model |
| `default_chunk_strategy` | `string` | `"recursive"` | Default chunking strategy |
| `default_top_k` | `int` | `10` | Default similarity search result count |
| `shutdown_timeout` | `duration` | `"30s"` | Max graceful shutdown wait |
| `ingest_concurrency` | `int` | `4` | Parallel ingest operations |
| `grove_database` | `string` | `""` | Named grove.DB from DI |

### Merge behaviour

File-based configuration is merged with programmatic options. Programmatic options set via `extension.New(...)` take precedence over YAML values.