> ## Documentation Index
> Fetch the complete documentation index at: https://simili.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Overview

> Configure Simili Bot v0.2.0

# Configuration Overview

Simili Bot is configured using a YAML file. Your configuration structure depends on your chosen deployment pattern.

## Configuration by pattern

Choose your setup guide to see pattern-specific configuration examples:

<CardGroup cols={3}>
  <Card title="Pattern A" href="/getting-started/single-repo-setup">
    Single Repository
  </Card>

  <Card title="Pattern B" href="/getting-started/centralized-multi-repo-setup">
    Centralized Multi-Repo
  </Card>

  <Card title="Pattern C" href="/getting-started/distributed-multi-repo-setup">
    Distributed Multi-Repo
  </Card>
</CardGroup>

## Configuration file location

By default, Simili Bot looks for configuration in these locations:

1. **Explicit path:** Specified via CLI or workflow
   ```bash theme={null}
   simili process --config /path/to/simili.yaml
   ```

2. **GitHub Actions:** Path specified in workflow
   ```yaml theme={null}
   - uses: similigh/simili-bot@v0.2.0
     with:
      config_path: ".github/simili.yaml"
   ```

3. **Current directory:** `simili.yaml` in working directory

## Configuration structure

A complete configuration file has these main sections:

```yaml theme={null}
# Search backend (qdrant | github_native | bm25)
search:
  backend: "qdrant"

# Vector database connection (required for qdrant)
qdrant:
  url: "https://your-cluster.qdrant.io:6333"
  api_key: "${QDRANT_API_KEY}"
  collection: "issues"

# AI model settings (required for qdrant)
embedding:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"
  model: "gemini-embedding-001"
  dimensions: 3072

# LLM settings
llm:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"

# Default behavior
defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5
  cross_repo_search: true

# Claude Code integration
claude_code:
  enabled: true
  issue_implement:
    enabled: true

# Duplicate auto-closure
auto_close:
  grace_period_hours: 72

# Issue routing rules
transfer:
  enabled: true
  strategy: "hybrid"
```

## Section breakdown

### Search Backend

Choose your similarity search implementation:

```yaml theme={null}
search:
  backend: "qdrant" # qdrant, github_native, or bm25
  bm25_fallback: true
```

Details in [Search Backends](/configuration/search-backends).

### Qdrant Configuration

Configure your vector database connection:

```yaml theme={null}
qdrant:
  url: "https://your-cluster.qdrant.io:6333"
  api_key: "${QDRANT_API_KEY}"
  collection: "issues"
  tls: true
  timeout: 30
```

| Property     | Type    | Description                   | Required           |
| ------------ | ------- | ----------------------------- | ------------------ |
| `url`        | string  | Qdrant instance URL with port | Yes                |
| `api_key`    | string  | API key (use env vars)        | Yes                |
| `collection` | string  | Collection name for issues    | Yes                |
| `tls`        | boolean | Use TLS for connection        | No (default: true) |
| `timeout`    | number  | Request timeout in seconds    | No (default: 30)   |

### Embedding configuration

Configure AI embeddings:

```yaml theme={null}
embedding:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"
  model: "gemini-embedding-001"
  dimensions: 3072
```

| Property     | Type   | Description                   | Required                           |
| ------------ | ------ | ----------------------------- | ---------------------------------- |
| `provider`   | string | Only "gemini" supported       | Yes                                |
| `api_key`    | string | Gemini API key (use env vars) | Yes                                |
| `model`      | string | Model name                    | No (default: gemini-embedding-001) |
| `dimensions` | number | Vector dimensions             | No (default: 768)                  |

### Defaults configuration

Set default behavior for issue processing:

```yaml theme={null}
defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5
  cross_repo_search: false
```

| Property               | Type        | Description                     | Default |
| ---------------------- | ----------- | ------------------------------- | ------- |
| `similarity_threshold` | float (0-1) | Min score to show similar issue | 0.70    |
| `max_similar_to_show`  | number      | Max related issues to display   | 5       |
| `cross_repo_search`    | boolean     | Search across all repos         | false   |

### Repositories configuration

List repositories to manage:

```yaml theme={null}
repositories:
  - org: "my-org"
    repo: "backend"
    enabled: true
    description: "Backend services and APIs"
    labels: ["backend", "api"]

  - org: "my-org"
    repo: "frontend"
    enabled: false  # Disable temporarily
    description: "Web UI and client applications"
```

| Property      | Type    | Description                       | Required           |
| ------------- | ------- | --------------------------------- | ------------------ |
| `org`         | string  | GitHub organization or username   | Yes                |
| `repo`        | string  | Repository name                   | Yes                |
| `enabled`     | boolean | Enable Simili Bot for this repo   | No (default: true) |
| `description` | string  | Description for routing decisions | No                 |
| `labels`      | array   | Associated labels                 | No                 |

### Transfer configuration

Configure issue routing:

```yaml theme={null}
transfer:
  enabled: true
  llm_routing_enabled: true
  rules:
    - name: "Route to docs"
      priority: 10
      target: "org/docs"
      title_contains: ["documentation", "docs"]
```

Details in [Transfer Rules](/configuration/transfer-rules).

### Claude Code Configuration

Configure AI-powered workflows:

```yaml theme={null}
claude_code:
  enabled: true
  issue_implement:
    enabled: true
    trigger_label: "implement"
```

Details in [Claude Code Integration](/configuration/claude-code).

### Auto-Close Configuration

Automatically manage duplicate issues:

```yaml theme={null}
auto_close:
  grace_period_hours: 72
  dry_run: false
```

Details in [Auto-Close Duplicates](/configuration/auto-close).

## Environment Variables

Use environment variables for sensitive data:

```yaml theme={null}
qdrant:
  api_key: "${QDRANT_API_KEY}"

embedding:
  api_key: "${GEMINI_API_KEY}"
```

Set variables before running:

```bash theme={null}
export QDRANT_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
simili process --config simili.yaml
```

Or in GitHub Actions:

```yaml theme={null}
env:
  QDRANT_API_KEY: ${{ secrets.QDRANT_API_KEY }}
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
```

## Configuration inheritance

Extend configuration from a parent file:

```yaml theme={null}
extends: "https://raw.githubusercontent.com/my-org/configs/main/base.yaml"

# Override specific settings
repositories:
  - org: "my-org"
    repo: "my-service"
    enabled: true
```

Benefits:

* Organization-wide defaults
* Consistent policies across repositories
* Easy updates to shared config
* Per-repository customization

Parent configuration is fetched via HTTPS and merged.

## Common configurations

### Single repository

Manage one repository only:

```yaml theme={null}
qdrant:
  url: "https://your-cluster.qdrant.io:6333"
  api_key: "${QDRANT_API_KEY}"
  collection: "issues"

embedding:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"

defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5
  cross_repo_search: false

repositories:
  - org: "my-username"
    repo: "my-project"
    enabled: true
    description: "My project"
```

### Organization with multiple repos

```yaml theme={null}
extends: "https://raw.githubusercontent.com/my-org/policies/main/base.yaml"

repositories:
  - org: "my-org"
    repo: "backend"
    enabled: true
    description: "Backend services"

  - org: "my-org"
    repo: "frontend"
    enabled: true
    description: "Web UI"

  - org: "my-org"
    repo: "infrastructure"
    enabled: true
    description: "DevOps and infrastructure"
```

### Development vs production

**Development config** (.github/simili-dev.yaml):

```yaml theme={null}
qdrant:
  url: "https://dev-cluster.qdrant.io:6333"
  api_key: "${QDRANT_DEV_KEY}"

defaults:
  similarity_threshold: 0.80
  max_similar_to_show: 3
```

**Production config** (.github/simili-prod.yaml):

```yaml theme={null}
qdrant:
  url: "https://prod-cluster.qdrant.io:6333"
  api_key: "${QDRANT_PROD_KEY}"

defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5
```

## Validation

Simili Bot validates configuration on startup. Common errors:

**Missing required fields:**

```
Error: qdrant.url is required
Error: embedding.api_key is required
```

**Invalid YAML syntax:**

```
Error: Failed to parse configuration: yaml: line 5: mapping values are not allowed in this context
```

**Invalid threshold value:**

```
Error: similarity_threshold must be between 0.0 and 1.0
```

## Configuration updates

### To update configuration

1. Edit `simili.yaml`
2. Commit and push to repository
3. Next issue processed uses new configuration
4. No restart required (GitHub Action runs with latest config)

### Safe testing

Test changes before deploying:

```bash theme={null}
# Test with dry-run mode
simili process --issue test.json --config simili.yaml --dry-run
```

Or in workflow:

```yaml theme={null}
- uses: similigh/simili-bot@v0.2.0
  with:
    command: "process"
    config_path: ".github/simili.yaml"
    dry_run: true
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Qdrant setup" href="/configuration/qdrant">
    Configure vector database
  </Card>

  <Card title="Gemini setup" href="/configuration/gemini">
    Configure AI engine
  </Card>

  <Card title="Repositories" href="/configuration/repositories">
    Configure multiple repos
  </Card>

  <Card title="Transfer rules" href="/configuration/transfer-rules">
    Setup issue routing
  </Card>

  <Card title="Claude Code" href="/configuration/claude-code">
    AI Agent workflows
  </Card>

  <Card title="Search Backends" href="/configuration/search-backends">
    Qdrant vs GitHub Native
  </Card>
</CardGroup>