distillery.yaml.example

# distillery.yaml.example
#
# Copy this file to distillery.yaml for local use, or use one of the
# production configs under deploy/ (deploy/prefect/distillery.yaml,
# deploy/fly/distillery-fly.yaml). You can also override the config file
# path by setting the DISTILLERY_CONFIG environment variable.
#
# Supported embedding providers
# ==============================
# - fastembed : On-device ONNX inference (no API calls, no key required).
#             This is the install-time default for the Claude Code plugin
#             (see .claude-plugin/plugin.json). Requires the optional
#             `[fastembed]` extra: `pip install distillery-mcp[fastembed]`.
#             The model is downloaded once on first use, cached under
#             ~/.cache/fastembed.
#             Default model: BAAI/bge-small-en-v1.5 (384 dimensions, ~67 MB)
#
# - jina   : Jina AI Embeddings API (https://api.jina.ai/)
#             Supports Matryoshka truncation for configurable output dimensions.
#             Uses differentiated task types for storage vs. query embeddings.
#             Requires: JINA_API_KEY environment variable.
#             Default model: jina-embeddings-v3 (1024 dimensions)
#
# - openai : OpenAI Embeddings API (https://platform.openai.com/)
#             Supports the `dimensions` parameter for dimension reduction.
#             Requires: OPENAI_API_KEY environment variable.
#             Default model: text-embedding-3-small (512 dimensions)
#
# - mock   : Hash-based mock provider (no API calls, no key required)
#             Produces deterministic vectors from text hashes. Functional for
#             search and dedup via cosine similarity. Useful for local
#             development, eval scenarios, and testing.
#             Default model: mock-hash (4 dimensions)
#
# Both Jina and OpenAI providers implement exponential backoff retry on
# HTTP 429 (rate limit) and 5xx server errors (up to 3 retries).

# ---------------------------------------------------------------------------
# Server settings (HTTP transport + authentication)
# ---------------------------------------------------------------------------
#
# This section configures remote access and authentication when running
# distillery-mcp in HTTP mode (distillery-mcp --transport http).
# Stdio mode (default) ignores this section.
#
# Transport mode is controlled by CLI flags:
#   distillery-mcp --transport http --port 8000  (HTTP remote access)
#   distillery-mcp                               (stdio local access, default)
#
# Authentication providers:
#   - github: GitHub OAuth via FastMCP's GitHubProvider
#             Requires: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, DISTILLERY_BASE_URL env vars
#   - none:   No authentication (development only, logs a warning)
#
# The auth section stores environment variable *names*, not secret values.
# Actual secrets are set in environment variables, never in this config file.

# server:
#   auth:
#     # Authentication provider: github or none (default: none)
#     provider: github
#     # Environment variable name holding the GitHub OAuth Client ID
#     # (from https://github.com/settings/developers after registering the app)
#     client_id_env: GITHUB_CLIENT_ID
#     # Environment variable name holding the GitHub OAuth Client Secret
#     client_secret_env: GITHUB_CLIENT_SECRET

# ---------------------------------------------------------------------------
# Storage settings
# ---------------------------------------------------------------------------
#
# Three storage modes are supported:
#
# 1. Local file (default)
#    backend: duckdb
#    database_path: ~/.distillery/distillery.db
#
# 2. S3-backed DuckDB (persistent across container restarts on FastMCP Cloud)
#    Uses DuckDB's httpfs extension. AWS credentials are resolved automatically
#    from environment variables (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) or
#    an IAM role when running on AWS infrastructure.
#
#    backend: duckdb
#    database_path: s3://my-bucket/distillery/distillery.db
#    s3_region: us-east-1
#    # Optional: custom endpoint for S3-compatible services (MinIO, Cloudflare R2, etc.)
#    # s3_endpoint: https://my-minio.example.com
#
# 3. MotherDuck (DuckDB cloud service)
#    Requires a MotherDuck token in the MOTHERDUCK_TOKEN environment variable
#    (or the env var named by motherduck_token_env below).
#
#    backend: motherduck
#    database_path: md:distillery
#    # motherduck_token_env: MOTHERDUCK_TOKEN  # default

storage:
  # Backend: 'duckdb' (local or S3-backed) or 'motherduck'.
  backend: duckdb

  # Path to the DuckDB database file. Supports ~ for the home directory,
  # s3:// prefix for S3-backed storage, and md: prefix for MotherDuck.
  # The parent directory is created automatically for local paths.
  database_path: ~/.distillery/distillery.db

  # --- S3 storage options (only used when database_path starts with s3://) ---

  # AWS region for the S3 bucket. Defaults to the AWS_DEFAULT_REGION /
  # AWS_REGION environment variable when not set here.
  # s3_region: us-east-1

  # Custom S3-compatible endpoint URL (MinIO, Cloudflare R2, etc.).
  # When set, path-style URL access is enabled automatically.
  # s3_endpoint: https://my-minio.example.com

  # --- MotherDuck options (only used when backend is 'motherduck') ----------

  # Name of the environment variable that holds the MotherDuck token.
  # motherduck_token_env: MOTHERDUCK_TOKEN

# ---------------------------------------------------------------------------
# Embedding provider settings
# ---------------------------------------------------------------------------
# Choose ONE of the provider configurations below and remove (or comment out)
# the other.
#
# IMPORTANT: Once entries have been stored with a particular embedding model,
# the database records the model name and dimensions in its _meta table.
# Changing the provider or dimensions after entries exist will raise a
# RuntimeError to prevent mixing incompatible embeddings.

# --- Option A: Jina AI embeddings -------------------------------------------
# Hosted API-based provider. Good quality, generous free tier.
embedding:
  provider: jina
  # Embedding model to use. jina-embeddings-v3 supports Matryoshka truncation.
  model: jina-embeddings-v3
  # Number of embedding dimensions. Must be positive. Lower values use less
  # storage but may reduce retrieval quality.
  # Recommended: 1024 (full), 512 (compact), 256 (small)
  dimensions: 1024
  # Name of the environment variable that holds your Jina API key.
  # Set it in your shell: export JINA_API_KEY=jina_...
  api_key_env: JINA_API_KEY

# --- Option B: OpenAI embeddings --------------------------------------------
# embedding:
#   provider: openai
#   # Embedding model to use. text-embedding-3-small is cost-efficient.
#   # Other option: text-embedding-3-large (3072 dimensions maximum)
#   model: text-embedding-3-small
#   # Number of embedding dimensions. OpenAI supports dimension reduction via
#   # the `dimensions` API parameter.
#   # Recommended: 512 (default), 256 (compact), 1536 (maximum for 3-small)
#   dimensions: 512
#   # Name of the environment variable that holds your OpenAI API key.
#   # Set it in your shell: export OPENAI_API_KEY=sk-...
#   api_key_env: OPENAI_API_KEY

# --- Option C: Local embeddings (fastembed, no API key) ---------------------
# Install-time default for the Claude Code plugin. Runs ONNX inference
# on-device — no network call, no API key. Requires the optional dependency
# group: `pip install distillery-mcp[fastembed]`. The model is downloaded
# once on first use (cached under ~/.cache/fastembed).
# embedding:
#   provider: fastembed
#   # HuggingFace model identifier. Aliases supported: "bge-small" (default,
#   # ~67 MB, 384 dim), "bge-base" (~210 MB, 768 dim), "bge-large", "nomic",
#   # "mxbai". See distillery.embedding.fastembed.MODEL_ALIASES.
#   model: BAAI/bge-small-en-v1.5
#   # Must match the model's native output size. The provider does not
#   # reduce dimensions; mismatched values will fail at storage init.
#   #   bge-small-en-v1.5  -> 384
#   #   bge-base-en-v1.5   -> 768
#   #   bge-large-en-v1.5  -> 1024
#   dimensions: 384
#   # api_key_env is ignored for fastembed — leave unset or empty.

# ---------------------------------------------------------------------------
# Team settings
# ---------------------------------------------------------------------------
team:
  # Human-readable team name used to label stored knowledge entries.
  name: My Team

# ---------------------------------------------------------------------------
# Classification settings
# ---------------------------------------------------------------------------
classification:
  # Minimum confidence score [0.0, 1.0] for an auto-classification to be
  # accepted. Entries with scores below this threshold remain unclassified.
  confidence_threshold: 0.6

  # Deduplication thresholds control how the distillery_check_dedup tool
  # maps cosine similarity scores to recommended actions.
  # Constraint: dedup_link_threshold <= dedup_merge_threshold <= dedup_skip_threshold

  # At or above this score: content is treated as a near-exact duplicate (skip).
  dedup_skip_threshold: 0.95

  # At or above this score (but below skip): merge into the existing entry.
  dedup_merge_threshold: 0.80

  # At or above this score (but below merge): link new entry to similar ones.
  dedup_link_threshold: 0.60

  # Maximum number of similar entries to retrieve during a dedup check.
  dedup_limit: 5

# ---------------------------------------------------------------------------
# Ambient feed monitoring settings
# ---------------------------------------------------------------------------
#
# The feeds section configures sources to monitor for relevant content.
# Feed items are ingested as 'feed' entries and scored against your stored
# knowledge. Items above the alert threshold trigger immediate alerts;
# items above the digest threshold are included in the next /radar digest.
#
# Sources listed here are seeded into the database on first startup.
# After that, the database is the source of truth — use /watch add and
# /watch remove to manage sources at runtime (changes persist in DuckDB).
#
# Supported source_type values:
#   - rss        : Atom/RSS feed at the given URL
#   - github     : GitHub repository (issues, PRs, releases) — url = "org/repo"
#   - hackernews : Hacker News (url is ignored; top stories are fetched)
#   - webhook    : Incoming webhook (url is the receiving endpoint path)
#
# feeds:
#   thresholds:
#     # Cosine similarity at or above which a feed item triggers an alert.
#     alert: 0.85
#     # Cosine similarity at or above which an item is included in the digest.
#     digest: 0.60
#   sources:
#     - url: https://news.ycombinator.com/rss
#       source_type: rss
#       label: Hacker News RSS
#       poll_interval_minutes: 60   # How often to poll (default: 60)
#       trust_weight: 1.0           # Relevance multiplier [0.0-1.0] (default: 1.0)
#     - url: openai/openai-python
#       source_type: github
#       label: OpenAI Python SDK
#       poll_interval_minutes: 120
#       trust_weight: 0.8
feeds:
  thresholds:
    alert: 0.85
    digest: 0.60
  sources: []

# ---------------------------------------------------------------------------
# Tag namespace settings
# ---------------------------------------------------------------------------
tags:
  # When true, all new tags submitted via distillery_store must contain at
  # least one "/" separator (hierarchical namespace required). Existing entries
  # with flat tags are unaffected — this only applies on write.
  # Examples of valid hierarchical tags: project/billing-v2/decisions,
  #   source/bookmark/docs-python-org, domain/api-design
  enforce_namespaces: false

  # Top-level namespace prefixes that only internal distillery sources may use.
  # Each prefix must be a valid lowercase alphanumeric slug (e.g. "system").
  # Entries with tags under a reserved prefix submitted via MCP will be
  # rejected unless the source is an authorized internal source.
  #
  # Default (when this key is omitted): ["kind"] — the kind/ namespace is the
  # content-type axis (kind/release, kind/opinion, ...) assigned by the
  # classifier.  Setting this key explicitly (including to []) overrides the
  # default.  Example: ["kind", "system"] reserves both namespaces.
  reserved_prefixes: ["kind"]