1 line
40 KiB
JSON
1 line
40 KiB
JSON
{"repo": "bug-ops/zeph", "files": {"book/src/guides/cloud-provider.md": {"81e234b1d78f3b8d2584e549d4f591c348c1e55a": {"t": 1785674608.2857869, "n": 5375, "h": "f908f6f7b618fe67", "c": "# Use a Cloud Provider\n\nConnect Zeph to Claude, OpenAI, Gemini, or any OpenAI-compatible API instead of local Ollama.\n\n> **Breaking change (v0.17.0):** The old `[llm.cloud]`, `[llm.orchestrator]`, and `[llm.router]` config sections have been removed. Run `zeph --migrate-config` to automatically convert your config file.\n\n## Claude\n\n```bash\nZEPH_CLAUDE_API_KEY=sk-ant-... zeph\n```\n\nOr in config:\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 4096\n# server_compaction = true # Server-side context compaction (Claude API beta)\n# enable_extended_context = true # 1M token context window (Claude Opus and Sonnet models, not Haiku)\n```\n\nClaude does not support embeddings. Use a multi-provider setup to combine Claude chat with Ollama embeddings, or use OpenAI embeddings.\n\n### Server-Side Compaction\n\nEnable `server_compaction = true` to let the Claude API manage context length on the server side. When the context approaches the model's limit, Claude produces a compact summary in-place. Zeph surfaces the compaction event in the TUI and via the `server_compaction_events` metric.\n\n> **Note:** Server compaction is not supported on Haiku models. When enabled on Haiku, Zeph emits a `WARN` and falls back to client-side compaction automatically.\n\n### 1M Extended Context\n\nFor Claude Opus and Sonnet models (not Haiku), enable `enable_extended_context = true` to unlock the 1M token context window. The `auto_budget` feature scales accordingly. Enable with `--extended-context` CLI flag or in the provider entry in config.\n\n## Gemini\n\n```bash\nZEPH_GEMINI_API_KEY=AIza... zeph\n```\n\nOr in config:\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"gemini\"\nmodel = \"gemini-2.0-flash\" # or \"gemini-2.5-pro\" for extended thinking\nmax_tokens = 8192\n# embedding_model = \"text-embedding-004\" # enable Gemini-native embeddings\n# thinking_level = \"medium\" # Gemini 2.5+ only: minimal, low, medium, high\n```\n\nGemini supports embeddings natively when `embedding_model` is set — no separate Ollama instance required. See [LLM Providers — Gemini](../concepts/providers.md#gemini) for the full feature matrix.\n\n## OpenAI\n\n```bash\nZEPH_OPENAI_API_KEY=sk-... zeph\n```\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"openai\"\nbase_url = \"https://api.openai.com/v1\"\nmodel = \"gpt-5.2\"\nmax_tokens = 4096\nembedding_model = \"text-embedding-3-small\"\nreasoning_effort = \"medium\" # optional: low, medium, high (for o3, etc.)\n```\n\nWhen `embedding_model` is set, Qdrant subsystems use it automatically for skill matching and semantic memory.\n\n### o-Series Models (o1, o3, o4)\n\nOpenAI's o-series reasoning models have different configuration requirements from standard LLMs:\n\n```toml\n[[llm.providers]]\ntype = \"openai\"\nmodel = \"o3-mini\"\nmax_completion_tokens = 16000 # Required: cap reasoning token budget (max 100,000)\n# Note: o-series does not support:\n# - max_tokens (use max_completion_tokens instead)\n# - temperature (always 1.0)\n# - top_p (always 1.0)\n# - system prompts (limited support — use sparingly)\n```\n\n**Cost control with reasoning models:**\n\nThe `max_completion_tokens` parameter is critical for o-series models because reasoning tokens are 10–20× more expensive than regular completion tokens. Set a hard cap based on your task complexity:\n\n- **Simple tasks** (math, string manipulation): `max_completion_tokens = 2000`\n- **Moderate tasks** (code analysis, data retrieval): `max_completion_tokens = 8000`\n- **Complex reasoning** (multi-step analysis): `max_completion_tokens = 16000+`\n\nWithout a cap, reasoning models can generate 100,000+ tokens per request, leading to unexpected bills. Start conservatively and increase if the model runs out of tokens mid-reasoning.\n\n**Latency expectations:**\n\nReasoning models typically take 5–30 seconds per request. If you pair o-series with faster models via cascading, configure the cascade to skip o-series for simple queries:\n\n```toml\n[llm]\nrouting = \"cascade\"\n\n[[llm.providers]]\nname = \"fast\"\ntype = \"openai\"\nmodel = \"gpt-4o-mini\"\n\n[[llm.providers]]\nname = \"reasoning\"\ntype = \"openai\"\nmodel = \"o3-mini\"\nmax_completion_tokens = 8000\n```\n\n## Compatible APIs\n\nUse `type = \"compatible\"` with the appropriate `base_url`:\n\n```toml\n[llm]\n[[llm.providers]]\nname = \"groq\"\ntype = \"compatible\"\nbase_url = \"https://api.groq.com/openai/v1\"\nmodel = \"llama-3.3-70b-versatile\"\nmax_tokens = 4096\n```\n\nCommon `base_url` values:\n\n| Provider | `base_url` |\n|---|---|\n| Together AI | `https://api.together.xyz/v1` |\n| Groq | `https://api.groq.com/openai/v1` |\n| Fireworks | `https://api.fireworks.ai/inference/v1` |\n| Local vLLM | `http://localhost:8000/v1` |\n\n## Hybrid Setup\n\nEmbeddings via free local Ollama, chat via paid Claude API:\n\n```toml\n[llm]\nrouting = \"cascade\" # try cheapest provider first\n\n[[llm.providers]]\nname = \"local\"\ntype = \"ollama\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\"\nembed = true # use this provider for embeddings\n\n[[llm.providers]]\nname = \"cloud\"\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 4096\ndefault = true # use this provider for chat by default\n```\n\nSee [Adaptive Inference](../advanced/adaptive-inference.md) for routing strategy options.\n\n## Interactive Setup\n\nRun `zeph init` and select your provider in Step 2. The wizard handles model names, base URLs, and API keys. See [Configuration Wizard](../getting-started/wizard.md).\n"}, "df263531880da41d1224c6b642e7a12e6e29e75e": {"t": 1785846900.9195344, "n": 5375, "h": "f908f6f7b618fe67", "c": "# Use a Cloud Provider\n\nConnect Zeph to Claude, OpenAI, Gemini, or any OpenAI-compatible API instead of local Ollama.\n\n> **Breaking change (v0.17.0):** The old `[llm.cloud]`, `[llm.orchestrator]`, and `[llm.router]` config sections have been removed. Run `zeph --migrate-config` to automatically convert your config file.\n\n## Claude\n\n```bash\nZEPH_CLAUDE_API_KEY=sk-ant-... zeph\n```\n\nOr in config:\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 4096\n# server_compaction = true # Server-side context compaction (Claude API beta)\n# enable_extended_context = true # 1M token context window (Claude Opus and Sonnet models, not Haiku)\n```\n\nClaude does not support embeddings. Use a multi-provider setup to combine Claude chat with Ollama embeddings, or use OpenAI embeddings.\n\n### Server-Side Compaction\n\nEnable `server_compaction = true` to let the Claude API manage context length on the server side. When the context approaches the model's limit, Claude produces a compact summary in-place. Zeph surfaces the compaction event in the TUI and via the `server_compaction_events` metric.\n\n> **Note:** Server compaction is not supported on Haiku models. When enabled on Haiku, Zeph emits a `WARN` and falls back to client-side compaction automatically.\n\n### 1M Extended Context\n\nFor Claude Opus and Sonnet models (not Haiku), enable `enable_extended_context = true` to unlock the 1M token context window. The `auto_budget` feature scales accordingly. Enable with `--extended-context` CLI flag or in the provider entry in config.\n\n## Gemini\n\n```bash\nZEPH_GEMINI_API_KEY=AIza... zeph\n```\n\nOr in config:\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"gemini\"\nmodel = \"gemini-2.0-flash\" # or \"gemini-2.5-pro\" for extended thinking\nmax_tokens = 8192\n# embedding_model = \"text-embedding-004\" # enable Gemini-native embeddings\n# thinking_level = \"medium\" # Gemini 2.5+ only: minimal, low, medium, high\n```\n\nGemini supports embeddings natively when `embedding_model` is set — no separate Ollama instance required. See [LLM Providers — Gemini](../concepts/providers.md#gemini) for the full feature matrix.\n\n## OpenAI\n\n```bash\nZEPH_OPENAI_API_KEY=sk-... zeph\n```\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"openai\"\nbase_url = \"https://api.openai.com/v1\"\nmodel = \"gpt-5.2\"\nmax_tokens = 4096\nembedding_model = \"text-embedding-3-small\"\nreasoning_effort = \"medium\" # optional: low, medium, high (for o3, etc.)\n```\n\nWhen `embedding_model` is set, Qdrant subsystems use it automatically for skill matching and semantic memory.\n\n### o-Series Models (o1, o3, o4)\n\nOpenAI's o-series reasoning models have different configuration requirements from standard LLMs:\n\n```toml\n[[llm.providers]]\ntype = \"openai\"\nmodel = \"o3-mini\"\nmax_completion_tokens = 16000 # Required: cap reasoning token budget (max 100,000)\n# Note: o-series does not support:\n# - max_tokens (use max_completion_tokens instead)\n# - temperature (always 1.0)\n# - top_p (always 1.0)\n# - system prompts (limited support — use sparingly)\n```\n\n**Cost control with reasoning models:**\n\nThe `max_completion_tokens` parameter is critical for o-series models because reasoning tokens are 10–20× more expensive than regular completion tokens. Set a hard cap based on your task complexity:\n\n- **Simple tasks** (math, string manipulation): `max_completion_tokens = 2000`\n- **Moderate tasks** (code analysis, data retrieval): `max_completion_tokens = 8000`\n- **Complex reasoning** (multi-step analysis): `max_completion_tokens = 16000+`\n\nWithout a cap, reasoning models can generate 100,000+ tokens per request, leading to unexpected bills. Start conservatively and increase if the model runs out of tokens mid-reasoning.\n\n**Latency expectations:**\n\nReasoning models typically take 5–30 seconds per request. If you pair o-series with faster models via cascading, configure the cascade to skip o-series for simple queries:\n\n```toml\n[llm]\nrouting = \"cascade\"\n\n[[llm.providers]]\nname = \"fast\"\ntype = \"openai\"\nmodel = \"gpt-4o-mini\"\n\n[[llm.providers]]\nname = \"reasoning\"\ntype = \"openai\"\nmodel = \"o3-mini\"\nmax_completion_tokens = 8000\n```\n\n## Compatible APIs\n\nUse `type = \"compatible\"` with the appropriate `base_url`:\n\n```toml\n[llm]\n[[llm.providers]]\nname = \"groq\"\ntype = \"compatible\"\nbase_url = \"https://api.groq.com/openai/v1\"\nmodel = \"llama-3.3-70b-versatile\"\nmax_tokens = 4096\n```\n\nCommon `base_url` values:\n\n| Provider | `base_url` |\n|---|---|\n| Together AI | `https://api.together.xyz/v1` |\n| Groq | `https://api.groq.com/openai/v1` |\n| Fireworks | `https://api.fireworks.ai/inference/v1` |\n| Local vLLM | `http://localhost:8000/v1` |\n\n## Hybrid Setup\n\nEmbeddings via free local Ollama, chat via paid Claude API:\n\n```toml\n[llm]\nrouting = \"cascade\" # try cheapest provider first\n\n[[llm.providers]]\nname = \"local\"\ntype = \"ollama\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\"\nembed = true # use this provider for embeddings\n\n[[llm.providers]]\nname = \"cloud\"\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 4096\ndefault = true # use this provider for chat by default\n```\n\nSee [Adaptive Inference](../advanced/adaptive-inference.md) for routing strategy options.\n\n## Interactive Setup\n\nRun `zeph init` and select your provider in Step 2. The wizard handles model names, base URLs, and API keys. See [Configuration Wizard](../getting-started/wizard.md).\n"}}, "book/src/guides/config-recipes.md": {"81e234b1d78f3b8d2584e549d4f591c348c1e55a": {"t": 1785674611.25562, "n": 13858, "h": "cacdf6d5aece251d", "c": "# Configuration Recipes\n\nCopy-paste configs for the most common Zeph setups. Each recipe shows only the sections that\ndiffer from the defaults — paste them into a new `config.toml` and run:\n\n```bash\nzeph --config config.toml\n```\n\n> **Tip:** Run `zeph init` for an interactive wizard that generates the config file for you.\n> These recipes are for when you want to start from a known baseline or understand what each\n> setting does.\n\n## Which recipe do I need?\n\n| I want to… | Recipe |\n|---|---|\n| Try Zeph with no accounts or cloud services | [1. Minimal local (Ollama)](#1-minimal-local-ollama) |\n| Use Claude API for best quality | [2. Full cloud — Claude](#2-full-cloud--claude) |\n| Use OpenAI API | [3. Full cloud — OpenAI](#3-full-cloud--openai) |\n| Use Groq, Together, vLLM, or another compatible API | [4. Compatible provider](#4-compatible-provider) |\n| Keep Ollama as primary, fall back to Claude on failure | [5. Hybrid: Ollama + Claude fallback](#5-hybrid-ollama--claude-fallback) |\n| Run multi-step agentic workflows locally | [6. Orchestrator for complex tasks](#6-orchestrator-for-complex-tasks) |\n| Code assistant with LSP and code search | [7. Coding assistant](#7-coding-assistant) |\n| Run a Telegram bot | [8. Telegram bot](#8-telegram-bot) |\n| No internet at all, maximum privacy | [9. Privacy-first (fully local)](#9-privacy-first-fully-local) |\n| Add semantic memory to any of the above | [10. Semantic memory add-on (Qdrant)](#10-semantic-memory-add-on-qdrant) |\n\n---\n\n<h2 id=\"1-minimal-local-ollama\">1. Minimal local (Ollama)</h2>\n\n<details>\n<summary>Zero cloud dependencies. Good for first-time setup or offline use.<br>\n<strong>Prerequisites:</strong> <a href=\"https://ollama.com\">Ollama</a> installed and running (<code>ollama serve</code>), models pulled (<code>ollama pull qwen3:8b && ollama pull qwen3-embedding</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\" # for semantic skill matching\n\n[vault]\nbackend = \"env\" # no secrets needed for local Ollama\n\n[memory]\nhistory_limit = 20 # keep context lean for smaller models\n```\n\n> **Note:** `qwen3-embedding` is needed for skill matching. Without it, Zeph falls back to\n> keyword-based skill selection.\n\nSee [LLM Providers](../concepts/providers.md) for other Ollama-compatible models.\n\n</details>\n\n---\n\n<h2 id=\"2-full-cloud--claude\">2. Full cloud — Claude</h2>\n\n<details>\n<summary>Best response quality. Uses Anthropic's API for chat and context compaction.<br>\n<strong>Prerequisites:</strong> Age vault configured (<code>zeph vault init</code>) with <code>ZEPH_CLAUDE_API_KEY</code> stored (<code>zeph vault set ZEPH_CLAUDE_API_KEY sk-ant-...</code>).</summary>\n\n```toml\n[llm]\n# Claude does not provide embeddings; skill matching uses keyword fallback.\n# For semantic memory, combine with an Ollama embedding model (see recipe #5).\n[[llm.providers]]\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 8192\n# server_compaction = true # let Claude API manage context instead of client-side compaction\n\n[vault]\nbackend = \"age\" # reads ZEPH_CLAUDE_API_KEY from the age vault (default, recommended)\n\n[memory]\nhistory_limit = 50\n```\n\n> **Tip:** Claude does not support embeddings natively. For semantic memory and skill matching,\n> combine with Ollama embeddings using [recipe #5](#5-hybrid-ollama--claude-fallback).\n\nSee [Use a Cloud Provider](cloud-provider.md) and [Model Orchestrator](../advanced/orchestrator.md).\n\n</details>\n\n---\n\n<h2 id=\"3-full-cloud--openai\">3. Full cloud — OpenAI</h2>\n\n<details>\n<summary>Uses OpenAI for both chat and embeddings — no Ollama required.<br>\n<strong>Prerequisites:</strong> Age vault configured (<code>zeph vault init</code>) with <code>ZEPH_OPENAI_API_KEY</code> stored (<code>zeph vault set ZEPH_OPENAI_API_KEY sk-...</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"openai\"\nbase_url = \"https://api.openai.com/v1\"\nmodel = \"gpt-4o-mini\"\nmax_tokens = 4096\nembedding_model = \"text-embedding-3-small\" # used for skill matching and semantic memory\n\n[vault]\nbackend = \"age\" # reads ZEPH_OPENAI_API_KEY from the age vault (default, recommended)\n\n[memory]\nhistory_limit = 50\n```\n\n> **Tip:** With `embedding_model` set, Zeph uses OpenAI embeddings for both skill matching and\n> semantic memory — no separate embedding service needed.\n\n</details>\n\n---\n\n<h2 id=\"4-compatible-provider\">4. Compatible provider</h2>\n\n<details>\n<summary>Any OpenAI-compatible API: Groq, Together, Mistral, Fireworks, local vLLM, etc.<br>\n<strong>Prerequisites:</strong> Provider API key stored in the age vault (<code>zeph vault init</code> then <code>zeph vault set ZEPH_COMPATIBLE_<NAME>_API_KEY ...</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\nname = \"groq\"\ntype = \"compatible\"\nbase_url = \"https://api.groq.com/openai/v1\"\nmodel = \"llama-3.3-70b-versatile\"\nmax_tokens = 4096\n# API key: zeph vault set ZEPH_COMPATIBLE_GROQ_API_KEY <your-key>\n\n[vault]\nbackend = \"age\" # default, recommended\n```\n\nTo switch providers, change `name`, `base_url`, and `model`. Common base URLs:\n\n| Provider | `base_url` |\n|---|---|\n| Together AI | `https://api.together.xyz/v1` |\n| Groq | `https://api.groq.com/openai/v1` |\n| Fireworks | `https://api.fireworks.ai/inference/v1` |\n| Local vLLM | `http://localhost:8000/v1` |\n\n> **Note:** The vault key name is `ZEPH_COMPATIBLE_<NAME>_API_KEY` where `<NAME>` is the `name`\n> field uppercased. For the example above: `ZEPH_COMPATIBLE_GROQ_API_KEY`.\n\n</details>\n\n---\n\n<h2 id=\"5-hybrid-ollama--claude-fallback\">5. Hybrid: Ollama + Claude fallback</h2>\n\n<details>\n<summary>Ollama runs locally for free; Claude handles requests when Ollama fails or is unavailable.<br>\n<strong>Prerequisites:</strong> Ollama running locally + age vault configured with <code>ZEPH_CLAUDE_API_KEY</code> stored.</summary>\n\n```toml\n[llm]\nrouting = \"cascade\" # try cheapest first; fall back on failure\n\n[[llm.providers]]\nname = \"ollama\"\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\" # local embeddings — always available offline\nembed = true\n\n[[llm.providers]]\nname = \"claude\"\ntype = \"claude\"\nmodel = \"claude-haiku-4-5-20251001\" # fast + cheap fallback\nmax_tokens = 4096\ndefault = true\n\n[vault]\nbackend = \"age\" # default, recommended\n```\n\n> **Tip:** This setup keeps embeddings local (free, private) while giving you a cloud fallback\n> for chat when the local model is unavailable or overloaded.\n\nSee [Adaptive Inference](../advanced/adaptive-inference.md) for Thompson Sampling and latency-based routing.\n\n</details>\n\n---\n\n<h2 id=\"6-orchestrator-for-complex-tasks\">6. Orchestrator for complex tasks</h2>\n\n<details>\n<summary>Routes planning and execution to different local models. Enables <code>/plan</code> commands.<br>\n<strong>Prerequisites:</strong> Ollama running with at least two models pulled (<code>qwen3:8b</code> and <code>qwen3:14b</code>).</summary>\n\n```toml\n[[llm.providers]]\nname = \"planner\"\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:14b\" # larger model for planning and goal decomposition\nembedding_model = \"qwen3-embedding\"\nembed = true\n\n[[llm.providers]]\nname = \"executor\"\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\" # smaller model for tool execution steps\ndefault = true\n\n[orchestration]\nenabled = true # enable /plan commands and task graph execution\nmax_tasks = 20\nmax_parallel = 2 # conservative for local inference\nconfirm_before_execute = true\n\n[vault]\nbackend = \"env\" # dev-only: no secrets needed, both providers are local Ollama\n```\n\n> **Note:** `[orchestration]` (lowercase) enables `/plan` CLI commands. `routing = \"task\"` was removed as unimplemented — see [Model Orchestrator](../advanced/orchestrator.md) for current multi-provider setup options.\n\nSee [Task Orchestration](../concepts/task-orchestration.md) and [Model Orchestrator](../advanced/orchestrator.md).\n\n</details>\n\n---\n\n<h2 id=\"7-coding-assistant\">7. Coding assistant</h2>\n\n<details>\n<summary>LSP code intelligence and AST-based code indexing on top of local inference.<br>\n<strong>Prerequisites:</strong> Ollama running + a language server installed + <code>mcpls</code> (<code>cargo install mcpls</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\"\n\n[vault]\nbackend = \"env\" # dev-only: no secrets needed for local Ollama\n\n# AST-based code indexing: builds a semantic map of the repository.\n# Uses SQLite vector backend by default; add recipe #10 for Qdrant.\n[index]\nenabled = true\nwatch = true # reindex incrementally on file changes\nmax_chunks = 12\nrepo_map_tokens = 500 # include a structural map in the system prompt\n\n[tools.shell]\nallow_network = false # restrict shell tools to local-only for coding sessions\nconfirm_patterns = [\"rm \", \"git push\"]\n\n# LSP code intelligence via mcpls MCP server.\n# mcpls auto-detects language servers from project files.\n[[mcp.servers]]\nid = \"mcpls\"\ncommand = \"mcpls\"\nargs = [\"--workspace-root\", \".\"]\ntimeout = 60 # LSP servers need warmup time\n```\n\n> **Tip:** `mcpls` auto-detects language servers: `Cargo.toml` → rust-analyzer,\n> `package.json` → typescript-language-server, `pyproject.toml` → pyright, etc.\n\nSee [LSP Code Intelligence](../guides/lsp.md) and [Code Indexing](../advanced/code-indexing.md).\n\n</details>\n\n---\n\n<h2 id=\"8-telegram-bot\">8. Telegram bot</h2>\n\n<details>\n<summary>Persistent Telegram bot. Suitable for a server or always-on machine.<br>\n<strong>Prerequisites:</strong> Telegram bot token (from <a href=\"https://t.me/BotFather\">@BotFather</a>) + age vault configured with <code>ZEPH_CLAUDE_API_KEY</code> and <code>ZEPH_TELEGRAM_BOT_TOKEN</code> stored.</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 4096\n\n[vault]\nbackend = \"age\" # reads ZEPH_CLAUDE_API_KEY and ZEPH_TELEGRAM_BOT_TOKEN from the age vault\n\n[telegram]\n# token = \"your-bot-token\" # or store via `zeph vault set ZEPH_TELEGRAM_BOT_TOKEN ...`\nallowed_users = [\"yourusername\"] # restrict access — do not leave empty on a public server\n\n[memory]\nhistory_limit = 50 # longer history for async messaging patterns\n\n[security]\nautonomy_level = \"supervised\" # always ask before destructive operations\n\n[daemon]\nenabled = true # keep the process alive and restart on crash\npid_file = \"~/.zeph/zeph.pid\"\n```\n\n> **Warning:** Always set `allowed_users`. An open bot with tool execution enabled is a security\n> risk. See [Security](../reference/security.md).\n\nRun in background: `zeph --config config.toml &` or use a systemd service.\nSee [Run via Telegram](telegram.md) and [Daemon Mode](daemon-mode.md).\n\n</details>\n\n---\n\n<h2 id=\"9-privacy-first-fully-local\">9. Privacy-first (fully local)</h2>\n\n<details>\n<summary>No outbound connections. No API keys. No telemetry. Shell restricted to local commands.<br>\n<strong>Prerequisites:</strong> Ollama running locally with desired models pulled.</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\"\n\n[vault]\nbackend = \"env\" # no secrets needed\n\n[memory]\nhistory_limit = 30\nvector_backend = \"sqlite\" # embedded vector index — no Qdrant required\n\n[memory.semantic]\nenabled = true\n\n[tools.shell]\nallow_network = false\nblocked_commands = [\"curl\", \"wget\", \"nc\", \"ssh\", \"scp\", \"rsync\"]\nconfirm_patterns = [\"rm \", \"git push\", \"sudo \"]\n\n[security]\nautonomy_level = \"supervised\"\nredact_secrets = true\n\n[security.content_isolation]\nenabled = true\n\n[a2a]\nenabled = false # no agent-to-agent network server\n\n[gateway]\nenabled = false # no HTTP gateway\n\n[observability]\nexporter = \"\" # no telemetry\n```\n\n> **Note:** `vector_backend = \"sqlite\"` uses an embedded vector index — no Qdrant required.\n> Good for personal workloads (up to ~100K embeddings).\n\n</details>\n\n---\n\n<h2 id=\"10-semantic-memory-add-on-qdrant\">10. Semantic memory add-on (Qdrant)</h2>\n\n<details>\n<summary>Layer persistent vector memory onto <strong>any</strong> recipe above.<br>\n<strong>Prerequisites:</strong> Qdrant running locally — <code>docker run -d -p 6334:6334 qdrant/qdrant</code>.</summary>\n\nAdd these sections to your base config:\n\n```toml\n[memory]\nqdrant_url = \"http://localhost:6334\"\nvector_backend = \"qdrant\" # switch from embedded SQLite to external Qdrant\n\n[memory.semantic]\nenabled = true\nrecall_limit = 5 # messages recalled per query\nvector_weight = 0.7 # blend of vector similarity vs keyword (FTS5)\nkeyword_weight = 0.3\ntemporal_decay_enabled = true\ntemporal_decay_half_life_days = 30 # older memories fade gradually\nmmr_enabled = true # diversify results (avoid near-duplicate recalls)\nmmr_lambda = 0.7\n```\n\n> **Note:** When the primary provider does not support embeddings (e.g. Claude), Zeph needs a\n> separate embedding source. Add Ollama as a secondary provider (recipe #5) or use OpenAI\n> embeddings (recipe #3).\n\nSee [Set Up Semantic Memory](semantic-memory.md) for collection management and tuning.\n\n</details>\n\n---\n\n## Combining recipes\n\nRecipes 1–9 are standalone base configs. Recipe 10 (semantic memory) can be layered on top of\nany of them by merging the `[memory]` sections.\n\nCommon combinations:\n\n- **Local with memory**: recipe 1 + recipe 10 (use `vector_backend = \"sqlite\"` for zero dependencies)\n- **Cloud + memory**: recipe 2 or 3 + recipe 10 (OpenAI handles embeddings natively)\n- **Privacy + memory**: recipe 9 already includes `vector_backend = \"sqlite\"` — semantic memory is on\n- **Coding + orchestrator**: recipe 7 + recipe 6 sections for multi-model routing\n\nFor the full configuration reference with all available options, see [Configuration](../reference/configuration.md).\n"}, "df263531880da41d1224c6b642e7a12e6e29e75e": {"t": 1785846901.0682704, "n": 13858, "h": "cacdf6d5aece251d", "c": "# Configuration Recipes\n\nCopy-paste configs for the most common Zeph setups. Each recipe shows only the sections that\ndiffer from the defaults — paste them into a new `config.toml` and run:\n\n```bash\nzeph --config config.toml\n```\n\n> **Tip:** Run `zeph init` for an interactive wizard that generates the config file for you.\n> These recipes are for when you want to start from a known baseline or understand what each\n> setting does.\n\n## Which recipe do I need?\n\n| I want to… | Recipe |\n|---|---|\n| Try Zeph with no accounts or cloud services | [1. Minimal local (Ollama)](#1-minimal-local-ollama) |\n| Use Claude API for best quality | [2. Full cloud — Claude](#2-full-cloud--claude) |\n| Use OpenAI API | [3. Full cloud — OpenAI](#3-full-cloud--openai) |\n| Use Groq, Together, vLLM, or another compatible API | [4. Compatible provider](#4-compatible-provider) |\n| Keep Ollama as primary, fall back to Claude on failure | [5. Hybrid: Ollama + Claude fallback](#5-hybrid-ollama--claude-fallback) |\n| Run multi-step agentic workflows locally | [6. Orchestrator for complex tasks](#6-orchestrator-for-complex-tasks) |\n| Code assistant with LSP and code search | [7. Coding assistant](#7-coding-assistant) |\n| Run a Telegram bot | [8. Telegram bot](#8-telegram-bot) |\n| No internet at all, maximum privacy | [9. Privacy-first (fully local)](#9-privacy-first-fully-local) |\n| Add semantic memory to any of the above | [10. Semantic memory add-on (Qdrant)](#10-semantic-memory-add-on-qdrant) |\n\n---\n\n<h2 id=\"1-minimal-local-ollama\">1. Minimal local (Ollama)</h2>\n\n<details>\n<summary>Zero cloud dependencies. Good for first-time setup or offline use.<br>\n<strong>Prerequisites:</strong> <a href=\"https://ollama.com\">Ollama</a> installed and running (<code>ollama serve</code>), models pulled (<code>ollama pull qwen3:8b && ollama pull qwen3-embedding</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\" # for semantic skill matching\n\n[vault]\nbackend = \"env\" # no secrets needed for local Ollama\n\n[memory]\nhistory_limit = 20 # keep context lean for smaller models\n```\n\n> **Note:** `qwen3-embedding` is needed for skill matching. Without it, Zeph falls back to\n> keyword-based skill selection.\n\nSee [LLM Providers](../concepts/providers.md) for other Ollama-compatible models.\n\n</details>\n\n---\n\n<h2 id=\"2-full-cloud--claude\">2. Full cloud — Claude</h2>\n\n<details>\n<summary>Best response quality. Uses Anthropic's API for chat and context compaction.<br>\n<strong>Prerequisites:</strong> Age vault configured (<code>zeph vault init</code>) with <code>ZEPH_CLAUDE_API_KEY</code> stored (<code>zeph vault set ZEPH_CLAUDE_API_KEY sk-ant-...</code>).</summary>\n\n```toml\n[llm]\n# Claude does not provide embeddings; skill matching uses keyword fallback.\n# For semantic memory, combine with an Ollama embedding model (see recipe #5).\n[[llm.providers]]\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 8192\n# server_compaction = true # let Claude API manage context instead of client-side compaction\n\n[vault]\nbackend = \"age\" # reads ZEPH_CLAUDE_API_KEY from the age vault (default, recommended)\n\n[memory]\nhistory_limit = 50\n```\n\n> **Tip:** Claude does not support embeddings natively. For semantic memory and skill matching,\n> combine with Ollama embeddings using [recipe #5](#5-hybrid-ollama--claude-fallback).\n\nSee [Use a Cloud Provider](cloud-provider.md) and [Model Orchestrator](../advanced/orchestrator.md).\n\n</details>\n\n---\n\n<h2 id=\"3-full-cloud--openai\">3. Full cloud — OpenAI</h2>\n\n<details>\n<summary>Uses OpenAI for both chat and embeddings — no Ollama required.<br>\n<strong>Prerequisites:</strong> Age vault configured (<code>zeph vault init</code>) with <code>ZEPH_OPENAI_API_KEY</code> stored (<code>zeph vault set ZEPH_OPENAI_API_KEY sk-...</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"openai\"\nbase_url = \"https://api.openai.com/v1\"\nmodel = \"gpt-4o-mini\"\nmax_tokens = 4096\nembedding_model = \"text-embedding-3-small\" # used for skill matching and semantic memory\n\n[vault]\nbackend = \"age\" # reads ZEPH_OPENAI_API_KEY from the age vault (default, recommended)\n\n[memory]\nhistory_limit = 50\n```\n\n> **Tip:** With `embedding_model` set, Zeph uses OpenAI embeddings for both skill matching and\n> semantic memory — no separate embedding service needed.\n\n</details>\n\n---\n\n<h2 id=\"4-compatible-provider\">4. Compatible provider</h2>\n\n<details>\n<summary>Any OpenAI-compatible API: Groq, Together, Mistral, Fireworks, local vLLM, etc.<br>\n<strong>Prerequisites:</strong> Provider API key stored in the age vault (<code>zeph vault init</code> then <code>zeph vault set ZEPH_COMPATIBLE_<NAME>_API_KEY ...</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\nname = \"groq\"\ntype = \"compatible\"\nbase_url = \"https://api.groq.com/openai/v1\"\nmodel = \"llama-3.3-70b-versatile\"\nmax_tokens = 4096\n# API key: zeph vault set ZEPH_COMPATIBLE_GROQ_API_KEY <your-key>\n\n[vault]\nbackend = \"age\" # default, recommended\n```\n\nTo switch providers, change `name`, `base_url`, and `model`. Common base URLs:\n\n| Provider | `base_url` |\n|---|---|\n| Together AI | `https://api.together.xyz/v1` |\n| Groq | `https://api.groq.com/openai/v1` |\n| Fireworks | `https://api.fireworks.ai/inference/v1` |\n| Local vLLM | `http://localhost:8000/v1` |\n\n> **Note:** The vault key name is `ZEPH_COMPATIBLE_<NAME>_API_KEY` where `<NAME>` is the `name`\n> field uppercased. For the example above: `ZEPH_COMPATIBLE_GROQ_API_KEY`.\n\n</details>\n\n---\n\n<h2 id=\"5-hybrid-ollama--claude-fallback\">5. Hybrid: Ollama + Claude fallback</h2>\n\n<details>\n<summary>Ollama runs locally for free; Claude handles requests when Ollama fails or is unavailable.<br>\n<strong>Prerequisites:</strong> Ollama running locally + age vault configured with <code>ZEPH_CLAUDE_API_KEY</code> stored.</summary>\n\n```toml\n[llm]\nrouting = \"cascade\" # try cheapest first; fall back on failure\n\n[[llm.providers]]\nname = \"ollama\"\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\" # local embeddings — always available offline\nembed = true\n\n[[llm.providers]]\nname = \"claude\"\ntype = \"claude\"\nmodel = \"claude-haiku-4-5-20251001\" # fast + cheap fallback\nmax_tokens = 4096\ndefault = true\n\n[vault]\nbackend = \"age\" # default, recommended\n```\n\n> **Tip:** This setup keeps embeddings local (free, private) while giving you a cloud fallback\n> for chat when the local model is unavailable or overloaded.\n\nSee [Adaptive Inference](../advanced/adaptive-inference.md) for Thompson Sampling and latency-based routing.\n\n</details>\n\n---\n\n<h2 id=\"6-orchestrator-for-complex-tasks\">6. Orchestrator for complex tasks</h2>\n\n<details>\n<summary>Routes planning and execution to different local models. Enables <code>/plan</code> commands.<br>\n<strong>Prerequisites:</strong> Ollama running with at least two models pulled (<code>qwen3:8b</code> and <code>qwen3:14b</code>).</summary>\n\n```toml\n[[llm.providers]]\nname = \"planner\"\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:14b\" # larger model for planning and goal decomposition\nembedding_model = \"qwen3-embedding\"\nembed = true\n\n[[llm.providers]]\nname = \"executor\"\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\" # smaller model for tool execution steps\ndefault = true\n\n[orchestration]\nenabled = true # enable /plan commands and task graph execution\nmax_tasks = 20\nmax_parallel = 2 # conservative for local inference\nconfirm_before_execute = true\n\n[vault]\nbackend = \"env\" # dev-only: no secrets needed, both providers are local Ollama\n```\n\n> **Note:** `[orchestration]` (lowercase) enables `/plan` CLI commands. `routing = \"task\"` was removed as unimplemented — see [Model Orchestrator](../advanced/orchestrator.md) for current multi-provider setup options.\n\nSee [Task Orchestration](../concepts/task-orchestration.md) and [Model Orchestrator](../advanced/orchestrator.md).\n\n</details>\n\n---\n\n<h2 id=\"7-coding-assistant\">7. Coding assistant</h2>\n\n<details>\n<summary>LSP code intelligence and AST-based code indexing on top of local inference.<br>\n<strong>Prerequisites:</strong> Ollama running + a language server installed + <code>mcpls</code> (<code>cargo install mcpls</code>).</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\"\n\n[vault]\nbackend = \"env\" # dev-only: no secrets needed for local Ollama\n\n# AST-based code indexing: builds a semantic map of the repository.\n# Uses SQLite vector backend by default; add recipe #10 for Qdrant.\n[index]\nenabled = true\nwatch = true # reindex incrementally on file changes\nmax_chunks = 12\nrepo_map_tokens = 500 # include a structural map in the system prompt\n\n[tools.shell]\nallow_network = false # restrict shell tools to local-only for coding sessions\nconfirm_patterns = [\"rm \", \"git push\"]\n\n# LSP code intelligence via mcpls MCP server.\n# mcpls auto-detects language servers from project files.\n[[mcp.servers]]\nid = \"mcpls\"\ncommand = \"mcpls\"\nargs = [\"--workspace-root\", \".\"]\ntimeout = 60 # LSP servers need warmup time\n```\n\n> **Tip:** `mcpls` auto-detects language servers: `Cargo.toml` → rust-analyzer,\n> `package.json` → typescript-language-server, `pyproject.toml` → pyright, etc.\n\nSee [LSP Code Intelligence](../guides/lsp.md) and [Code Indexing](../advanced/code-indexing.md).\n\n</details>\n\n---\n\n<h2 id=\"8-telegram-bot\">8. Telegram bot</h2>\n\n<details>\n<summary>Persistent Telegram bot. Suitable for a server or always-on machine.<br>\n<strong>Prerequisites:</strong> Telegram bot token (from <a href=\"https://t.me/BotFather\">@BotFather</a>) + age vault configured with <code>ZEPH_CLAUDE_API_KEY</code> and <code>ZEPH_TELEGRAM_BOT_TOKEN</code> stored.</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"claude\"\nmodel = \"claude-sonnet-5\"\nmax_tokens = 4096\n\n[vault]\nbackend = \"age\" # reads ZEPH_CLAUDE_API_KEY and ZEPH_TELEGRAM_BOT_TOKEN from the age vault\n\n[telegram]\n# token = \"your-bot-token\" # or store via `zeph vault set ZEPH_TELEGRAM_BOT_TOKEN ...`\nallowed_users = [\"yourusername\"] # restrict access — do not leave empty on a public server\n\n[memory]\nhistory_limit = 50 # longer history for async messaging patterns\n\n[security]\nautonomy_level = \"supervised\" # always ask before destructive operations\n\n[daemon]\nenabled = true # keep the process alive and restart on crash\npid_file = \"~/.zeph/zeph.pid\"\n```\n\n> **Warning:** Always set `allowed_users`. An open bot with tool execution enabled is a security\n> risk. See [Security](../reference/security.md).\n\nRun in background: `zeph --config config.toml &` or use a systemd service.\nSee [Run via Telegram](telegram.md) and [Daemon Mode](daemon-mode.md).\n\n</details>\n\n---\n\n<h2 id=\"9-privacy-first-fully-local\">9. Privacy-first (fully local)</h2>\n\n<details>\n<summary>No outbound connections. No API keys. No telemetry. Shell restricted to local commands.<br>\n<strong>Prerequisites:</strong> Ollama running locally with desired models pulled.</summary>\n\n```toml\n[llm]\n[[llm.providers]]\ntype = \"ollama\"\nbase_url = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nembedding_model = \"qwen3-embedding\"\n\n[vault]\nbackend = \"env\" # no secrets needed\n\n[memory]\nhistory_limit = 30\nvector_backend = \"sqlite\" # embedded vector index — no Qdrant required\n\n[memory.semantic]\nenabled = true\n\n[tools.shell]\nallow_network = false\nblocked_commands = [\"curl\", \"wget\", \"nc\", \"ssh\", \"scp\", \"rsync\"]\nconfirm_patterns = [\"rm \", \"git push\", \"sudo \"]\n\n[security]\nautonomy_level = \"supervised\"\nredact_secrets = true\n\n[security.content_isolation]\nenabled = true\n\n[a2a]\nenabled = false # no agent-to-agent network server\n\n[gateway]\nenabled = false # no HTTP gateway\n\n[observability]\nexporter = \"\" # no telemetry\n```\n\n> **Note:** `vector_backend = \"sqlite\"` uses an embedded vector index — no Qdrant required.\n> Good for personal workloads (up to ~100K embeddings).\n\n</details>\n\n---\n\n<h2 id=\"10-semantic-memory-add-on-qdrant\">10. Semantic memory add-on (Qdrant)</h2>\n\n<details>\n<summary>Layer persistent vector memory onto <strong>any</strong> recipe above.<br>\n<strong>Prerequisites:</strong> Qdrant running locally — <code>docker run -d -p 6334:6334 qdrant/qdrant</code>.</summary>\n\nAdd these sections to your base config:\n\n```toml\n[memory]\nqdrant_url = \"http://localhost:6334\"\nvector_backend = \"qdrant\" # switch from embedded SQLite to external Qdrant\n\n[memory.semantic]\nenabled = true\nrecall_limit = 5 # messages recalled per query\nvector_weight = 0.7 # blend of vector similarity vs keyword (FTS5)\nkeyword_weight = 0.3\ntemporal_decay_enabled = true\ntemporal_decay_half_life_days = 30 # older memories fade gradually\nmmr_enabled = true # diversify results (avoid near-duplicate recalls)\nmmr_lambda = 0.7\n```\n\n> **Note:** When the primary provider does not support embeddings (e.g. Claude), Zeph needs a\n> separate embedding source. Add Ollama as a secondary provider (recipe #5) or use OpenAI\n> embeddings (recipe #3).\n\nSee [Set Up Semantic Memory](semantic-memory.md) for collection management and tuning.\n\n</details>\n\n---\n\n## Combining recipes\n\nRecipes 1–9 are standalone base configs. Recipe 10 (semantic memory) can be layered on top of\nany of them by merging the `[memory]` sections.\n\nCommon combinations:\n\n- **Local with memory**: recipe 1 + recipe 10 (use `vector_backend = \"sqlite\"` for zero dependencies)\n- **Cloud + memory**: recipe 2 or 3 + recipe 10 (OpenAI handles embeddings natively)\n- **Privacy + memory**: recipe 9 already includes `vector_backend = \"sqlite\"` — semantic memory is on\n- **Coding + orchestrator**: recipe 7 + recipe 6 sections for multi-model routing\n\nFor the full configuration reference with all available options, see [Configuration](../reference/configuration.md).\n"}}}} |