Self-hosting docs overhaul: single-provider default, restructured config guide#510
Merged
VVoruganti merged 23 commits intomainfrom Apr 8, 2026
Merged
Self-hosting docs overhaul: single-provider default, restructured config guide#510VVoruganti merged 23 commits intomainfrom
VVoruganti merged 23 commits intomainfrom
Conversation
- .env.template: lead with provider options (custom, vllm, google, anthropic, openai, groq) instead of baking in vendor-specific keys. All provider/model settings commented out so server fails fast until configured. Separate endpoint config from per-feature provider+model from tuning knobs. - docker-compose.yml.example: fix healthcheck -d honcho -> -d postgres to match POSTGRES_DB=postgres. - config.toml.example: reorder and document LLM key section with OpenRouter and vLLM examples. - self-hosting.mdx: replace multi-vendor key table with provider options table. Add examples for OpenRouter, vLLM/Ollama, and direct vendor keys. Remove duplicated key lists from Docker/manual setup sections. - configuration.mdx: replace scattered provider docs with provider types table. Fix Docker Compose snippet to match actual compose file. Note code defaults as fallback, not recommended path. - troubleshooting.mdx: add alternative provider issues section (custom provider config, model name format, Docker localhost, structured output failures).
- Document BuildKit requirement (RUN --mount syntax) - AppArmor/SELinux blocking Docker builds on Linux - Volume mount UID mismatch between host and container app user - Note in self-hosting docs that Docker path builds from source
…cloud service" This reverts commit 3e766eb.
- Add docker-compose.prod.yml for VM/server deployment: no source mounts, restart policies, 127.0.0.1-bound ports, cache enabled - Add model tier guidance and community quick-start link to self-hosting - Document THINKING_BUDGET_TOKENS gotcha for non-Anthropic providers - Add reverse proxy examples (Caddy + nginx) to production section - Add backup/restore commands to production considerations
Self-hosting page now defaults to one OpenAI-compatible endpoint with one model for all features. Moved model tiers, alternative providers, and per-feature tuning into the configuration guide. Eliminated duplicate config priority sections, dev/prod split, and redundant TOML examples.
VVoruganti
requested changes
Apr 7, 2026
Collaborator
VVoruganti
left a comment
VVoruganti
left a comment
There was a problem hiding this comment.
Directionally good, but still some inconsistencies that I think people would run into
Collaborator
There was a problem hiding this comment.
This file separates concerns by trying to move all of the model definitions under one section rather than keeping them in their respective modules.
Also would suffer from the same failure mode of crashing on an initial run because it doesn't have the properly api keys for gemini and that is still set as the default
… in .env.template Single docker-compose.yml.example with dev sections commented out. Moved PROVIDER and MODEL back alongside each feature in .env.template so settings stay colocated with their module. Updated self-hosting docs to reference single compose file.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughRefactors LLM env/configs to a provider+model pattern and enforces per-feature env vars; tightens Docker/compose defaults (loopback ports, named Redis volume, cache flag); updates docs (new troubleshooting page, DB URI and minimum versions); and adds a minimal Changes
Sequence Diagram(s)(Section skipped — changes do not introduce a new multi-component sequential control flow that requires a sequence diagram.) Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/v2/contributing/self-hosting.mdx (1)
54-67:⚠️ Potential issue | 🟠 MajorUse the
LLM_-prefixed variable names in both.envexamples.
src/config.pyloads LLM settings withenv_prefix="LLM_", soOPENAI_API_KEYandANTHROPIC_API_KEYhere won't be read. A reader who copies either snippet will still boot without configured provider credentials. The same rename is needed in the duplicated Hermes setup snippet too.Suggested fix
-OPENAI_API_KEY=your-openai-api-key -ANTHROPIC_API_KEY=your-anthropic-api-key +LLM_OPENAI_API_KEY=your-openai-api-key +LLM_ANTHROPIC_API_KEY=your-anthropic-api-keyAlso applies to: 168-174
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v2/contributing/self-hosting.mdx` around lines 54 - 67, The .env examples use OPENAI_API_KEY and ANTHROPIC_API_KEY but src/config.py expects LLM_-prefixed vars via env_prefix="LLM_"; update both `.env` snippets (the initial example and the Hermes setup duplicate) to use LLM_OPENAI_API_KEY and LLM_ANTHROPIC_API_KEY so the keys are actually loaded by the configuration loader (referencing the env_prefix="LLM_" behavior in src/config.py).docs/v3/contributing/configuration.mdx (1)
173-188:⚠️ Potential issue | 🟡 MinorRemove
TOOL_CHOICEfrom the reference example unless the config model supports it.The provided
DialecticLevelSettingsmodel only exposes provider/model/backup/thinking/max-tool-iterations/max-output-tokens. IncludingTOOL_CHOICEin a “complete reference” example makes the docs advertise a knob the current settings model does not read.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/configuration.mdx` around lines 173 - 188, Remove the unsupported TOOL_CHOICE key from the example config.toml so it matches the DialecticLevelSettings model; update the example blocks for [dialectic.levels.minimal] and [dialectic.levels.low] to only include PROVIDER, MODEL, THINKING_BUDGET_TOKENS, MAX_TOOL_ITERATIONS, and MAX_OUTPUT_TOKENS (and any supported backup fields if present) to avoid advertising a setting the settings model does not read.docs/v2/contributing/configuration.mdx (1)
146-153:⚠️ Potential issue | 🟡 MinorKeep the local URI aligned with the compose example below.
This example now targets
/postgres, but the compose snippet later in the same page still setsPOSTGRES_DB: honchoon Line 181. Copying both blocks can leave users initializing extensions or migrations against a different database than the one Honcho connects to.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v2/contributing/configuration.mdx` around lines 146 - 153, The DB_CONNECTION_URI example and the compose snippet POSTGRES_DB value are inconsistent; update one so both reference the same database name. Either change the example DB_CONNECTION_URI (DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho) to match POSTGRES_DB: honcho, or change the compose snippet's POSTGRES_DB to postgres—ensure the symbols DB_CONNECTION_URI and POSTGRES_DB are aligned so users connect to the same database.
🧹 Nitpick comments (2)
src/main.py (1)
199-202: Consider separating liveness from readiness.This endpoint now backs the container health check, but it always returns
200without touching Postgres or Redis. That means the container can stay “healthy” during dependency outages. If the goal is to gate traffic, add a dependency-aware/readyprobe and keep/healthas a cheap liveness check;include_in_schema=Falsewould also keep this infra-only route out of the public OpenAPI.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/main.py` around lines 199 - 202, The current health_check (function health_check at route "/health") is only a cheap liveness probe and should remain lightweight; add a new readiness endpoint (e.g., "/ready", function ready_check) that performs dependency checks against Postgres and Redis (open a short connection or run a lightweight query/ping against each) and returns non-200 if any dependency is unhealthy; keep the liveness "/health" simple and mark the readiness route (and optionally "/health") with include_in_schema=False to avoid exposing infra-only endpoints in OpenAPI. Ensure ready_check returns a clear failure status and message when either Postgres or Redis checks fail and reuses existing DB/Redis clients or connection helpers in the module.README.md (1)
219-229: Move the Groq key out of the “required configurations” block.This section is introduced as required setup, but
LLM_GROQ_API_KEYis explicitly marked optional. Splitting required vs. optional provider keys would make the bootstrap checklist clearer.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 219 - 229, The README currently lists LLM_GROQ_API_KEY in the "required configurations" block even though it's optional; update the env example by splitting provider keys into two blocks: one "Required LLM Provider API Keys" containing LLM_GEMINI_API_KEY, LLM_ANTHROPIC_API_KEY, and LLM_OPENAI_API_KEY, and a separate "Optional LLM Provider API Keys" block containing LLM_GROQ_API_KEY (keep the existing comments/annotations like EMBED_MESSAGES guidance), so the required vs optional intent is clear when referencing the variables LLM_GEMINI_API_KEY, LLM_ANTHROPIC_API_KEY, LLM_OPENAI_API_KEY, and LLM_GROQ_API_KEY.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/v3/contributing/configuration.mdx`:
- Line 31: The doc examples use the wrong env-var separator for nested Dialectic
settings; update all examples that show overrides (including the snippet with
`{SECTION}__{NESTED}__{KEY}` and the other ranges noted) to use the top-level
section name plus a double-underscore before nested keys, e.g. use
`DIALECTIC__LEVELS__minimal__PROVIDER` (so it maps to
settings.DIALECTIC.LEVELS.minimal), and replace any `DIALECTIC_LEVELS__...`
occurrences with `DIALECTIC__LEVELS__...` so provider/model/thinking-budget
overrides actually populate settings.DIALECTIC.LEVELS.
- Around line 7-9: Update the callout text and link in the documentation so it
references the new single-provider flow: replace the phrase "Most users only
need the three API keys from the Self-Hosting Guide" with wording that points
readers to the "LLM Setup" section (e.g., "Most users only need the
single-provider setup described in the Self-Hosting Guide") and change the link
target from ./self-hosting#llm-api-keys to ./self-hosting#llm-setup (or simply
./self-hosting if anchors are not used), ensuring the callout no longer
references the outdated three-key flow or the dead anchor.
In `@docs/v3/contributing/self-hosting.mdx`:
- Around line 108-109: Update the broken self-links that reference non-existent
anchors by replacing occurrences of "#llm-provider-setup" and "#llm-api-keys"
with the current anchor "#llm-setup" in the document; look for the text patterns
"LLM Provider Setup" and the inline links in the sentences that mention editing
`.env` and configuring your LLM provider (the lines around the current diff and
also the other occurrences noted at the document positions referred to in the
review) and update their hrefs so they point to "#llm-setup".
- Around line 51-74: The env var names for per-level dialectic settings are
missing the required double underscore between DIALECTIC and LEVELS, so
overrides like DIALECTIC_LEVELS__minimal__PROVIDER won't be picked up; update
every occurrence (e.g., DIALECTIC_LEVELS__minimal__PROVIDER,
DIALECTIC_LEVELS__low__MODEL, DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS,
etc.) to use DIALECTIC__LEVELS__... (e.g., DIALECTIC__LEVELS__minimal__PROVIDER)
and likewise ensure any THINKING_BUDGET_TOKENS variants follow the same
DIALECTIC__LEVELS__<level>__THINKING_BUDGET_TOKENS pattern so
settings.DIALECTIC.LEVELS reads the env correctly.
- Around line 79-80: The Info link in docs/v3/contributing/self-hosting.mdx
points to a removed anchor `#alternative-providers`; update the link target in
the Info block to a valid anchor or page—replace
`./configuration#alternative-providers` with either
`./configuration#provider-types`, `./configuration#direct-vendor-keys`, or
simply `./configuration` so the reference resolves correctly; ensure both
occurrences (the one at lines ~79 and ~398) are updated to the same valid
target.
- Around line 39-75: The docs sample only reconfigures generation models
(DERIVER_*, SUMMARY_*, DREAM_*, DIALECTIC_LEVELS__*), but omits the embedding
override so readers may still hit OpenAI embeddings; add instructions to either
set the embedding override envs (OPENAI_BASE_URL / OPENAI_EMBEDDING_MODEL — or
the LLM-prefixed equivalents LLM_OPENAI_BASE_URL / LLM_OPENAI_EMBEDDING_MODEL
used by LLMSettings) to point embeddings at the same OpenAI-compatible endpoint,
or show the explicit disable/retarget step for embeddings (i.e., set the
embeddings provider to your custom/none value); reference the existing
DERIVER_/SUMMARY_/DREAM_/DIALECTIC_LEVELS__* env pattern so maintainers place
the new embedding envs alongside them.
In `@docs/v3/contributing/troubleshooting.mdx`:
- Around line 152-160: The env var snippet uses the wrong nesting
(`DIALECTIC_LEVELS__...`) so it doesn't override settings.DIALECTIC.LEVELS;
update each variable to the nested form with the double-underscore after
DIALECTIC (e.g. use DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS,
DIALECTIC__LEVELS__low__THINKING_BUDGET_TOKENS, etc.), and when overriding
provider-level settings mention the per-level provider key format (e.g.
DIALECTIC__LEVELS__minimal__PROVIDER) so the per-level budgets/providers in
settings.DIALECTIC.LEVELS are actually cleared.
- Line 28: The link in docs/v3/contributing/troubleshooting.mdx points to a
non-existent anchor (/v3/contributing/self-hosting#which-api-keys-do-i-need);
open self-hosting.mdx to find the exact heading slug for the API keys section
(or decide to link to the page root), then update the href in
troubleshooting.mdx to the correct anchor or to /v3/contributing/self-hosting so
readers don't land on a dead link; ensure you update the link that currently
targets `which-api-keys-do-i-need` so it matches the actual heading ID in
self-hosting.mdx.
---
Outside diff comments:
In `@docs/v2/contributing/configuration.mdx`:
- Around line 146-153: The DB_CONNECTION_URI example and the compose snippet
POSTGRES_DB value are inconsistent; update one so both reference the same
database name. Either change the example DB_CONNECTION_URI
(DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho)
to match POSTGRES_DB: honcho, or change the compose snippet's POSTGRES_DB to
postgres—ensure the symbols DB_CONNECTION_URI and POSTGRES_DB are aligned so
users connect to the same database.
In `@docs/v2/contributing/self-hosting.mdx`:
- Around line 54-67: The .env examples use OPENAI_API_KEY and ANTHROPIC_API_KEY
but src/config.py expects LLM_-prefixed vars via env_prefix="LLM_"; update both
`.env` snippets (the initial example and the Hermes setup duplicate) to use
LLM_OPENAI_API_KEY and LLM_ANTHROPIC_API_KEY so the keys are actually loaded by
the configuration loader (referencing the env_prefix="LLM_" behavior in
src/config.py).
In `@docs/v3/contributing/configuration.mdx`:
- Around line 173-188: Remove the unsupported TOOL_CHOICE key from the example
config.toml so it matches the DialecticLevelSettings model; update the example
blocks for [dialectic.levels.minimal] and [dialectic.levels.low] to only include
PROVIDER, MODEL, THINKING_BUDGET_TOKENS, MAX_TOOL_ITERATIONS, and
MAX_OUTPUT_TOKENS (and any supported backup fields if present) to avoid
advertising a setting the settings model does not read.
---
Nitpick comments:
In `@README.md`:
- Around line 219-229: The README currently lists LLM_GROQ_API_KEY in the
"required configurations" block even though it's optional; update the env
example by splitting provider keys into two blocks: one "Required LLM Provider
API Keys" containing LLM_GEMINI_API_KEY, LLM_ANTHROPIC_API_KEY, and
LLM_OPENAI_API_KEY, and a separate "Optional LLM Provider API Keys" block
containing LLM_GROQ_API_KEY (keep the existing comments/annotations like
EMBED_MESSAGES guidance), so the required vs optional intent is clear when
referencing the variables LLM_GEMINI_API_KEY, LLM_ANTHROPIC_API_KEY,
LLM_OPENAI_API_KEY, and LLM_GROQ_API_KEY.
In `@src/main.py`:
- Around line 199-202: The current health_check (function health_check at route
"/health") is only a cheap liveness probe and should remain lightweight; add a
new readiness endpoint (e.g., "/ready", function ready_check) that performs
dependency checks against Postgres and Redis (open a short connection or run a
lightweight query/ping against each) and returns non-200 if any dependency is
unhealthy; keep the liveness "/health" simple and mark the readiness route (and
optionally "/health") with include_in_schema=False to avoid exposing infra-only
endpoints in OpenAPI. Ensure ready_check returns a clear failure status and
message when either Postgres or Redis checks fail and reuses existing DB/Redis
clients or connection helpers in the module.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 0c9be474-c73a-4372-be94-519b8800502d
📒 Files selected for processing (14)
.env.templateCONTRIBUTING.mdDockerfileREADME.mdconfig.toml.exampledocker-compose.yml.exampledocs/docs.jsondocs/v2/contributing/configuration.mdxdocs/v2/contributing/self-hosting.mdxdocs/v3/contributing/configuration.mdxdocs/v3/contributing/self-hosting.mdxdocs/v3/contributing/troubleshooting.mdxdocs/v3/guides/integrations/hermes.mdxsrc/main.py
…cies Fix 4 broken internal links (#llm-provider-setup, #llm-api-keys, #which-api-keys-do-i-need, #alternative-providers) to point to correct headings. Remove redundant Docker migration step (entrypoint already runs alembic). Fix cache URL missing ?suppress=true in reference config. Fix uv install command to use official method.
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/v3/contributing/configuration.mdx (1)
209-215:⚠️ Potential issue | 🟠 MajorFix the per-level env var example.
This example demonstrating the env var format for nested levels uses the wrong separator.
🔧 Proposed fix
Environment variables for nested levels use double underscores: ```bash -DIALECTIC_LEVELS__minimal__PROVIDER=google -DIALECTIC_LEVELS__minimal__MODEL=gemini-2.5-flash-lite -DIALECTIC_LEVELS__minimal__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__minimal__MAX_TOOL_ITERATIONS=1 +DIALECTIC__LEVELS__minimal__PROVIDER=google +DIALECTIC__LEVELS__minimal__MODEL=gemini-2.5-flash-lite +DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__minimal__MAX_TOOL_ITERATIONS=1</details> Based on learnings: Dialectic now uses per-level providers via `settings.DIALECTIC.LEVELS`; overrides must use nested env variables like `DIALECTIC__LEVELS__minimal__PROVIDER`. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/v3/contributing/configuration.mdxaround lines 209 - 215, Update the
per-level environment variable examples to use the correct double-underscore
nesting for settings.DIALECTIC.LEVELS by replacing the incorrect prefix
"DIALECTIC_LEVELS__" with "DIALECTIC__LEVELS__" in the examples (i.e., change
entries referencing DIALECTIC_LEVELS__minimal__... to
DIALECTIC__LEVELS__minimal__... so they match the nested settings key used by
the code).</details> </blockquote></details> </blockquote></details>♻️ Duplicate comments (5)
docs/v3/contributing/configuration.mdx (3)
134-137:⚠️ Potential issue | 🟠 MajorFix thinking budget env var names.
These dialectic thinking budget overrides use the wrong separator format.
🔧 Proposed fix
-DIALECTIC_LEVELS__medium__THINKING_BUDGET_TOKENS=1024 -DIALECTIC_LEVELS__high__THINKING_BUDGET_TOKENS=1024 -DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS=2048 +DIALECTIC__LEVELS__medium__THINKING_BUDGET_TOKENS=1024 +DIALECTIC__LEVELS__high__THINKING_BUDGET_TOKENS=1024 +DIALECTIC__LEVELS__max__THINKING_BUDGET_TOKENS=2048Based on learnings: Dialectic now uses per-level providers via
settings.DIALECTIC.LEVELS; overrides must use nested env variables likeDIALECTIC__LEVELS__minimal__PROVIDER.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/configuration.mdx` around lines 134 - 137, The environment variable names for per-level thinking budgets use wrong separators; update the variables like DIALECTIC_LEVELS__medium__THINKING_BUDGET_TOKENS, DIALECTIC_LEVELS__high__THINKING_BUDGET_TOKENS, and DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS to the nested env format used by settings.DIALECTIC.LEVELS (e.g., DIALECTIC__LEVELS__medium__THINKING_BUDGET_TOKENS, DIALECTIC__LEVELS__high__THINKING_BUDGET_TOKENS, DIALECTIC__LEVELS__max__THINKING_BUDGET_TOKENS) so the config loader maps them into DIALECTIC.LEVELS properly.
77-88:⚠️ Potential issue | 🟠 MajorUse
DIALECTIC__LEVELS__...for per-level overrides.All dialectic level env vars in this tiered setup example use the wrong separator format.
🔧 Proposed fix
# Light tier — high throughput, cheap -DIALECTIC_LEVELS__minimal__PROVIDER=custom -DIALECTIC_LEVELS__minimal__MODEL=google/gemini-2.5-flash-lite -DIALECTIC_LEVELS__low__PROVIDER=custom -DIALECTIC_LEVELS__low__MODEL=google/gemini-2.5-flash-lite +DIALECTIC__LEVELS__minimal__PROVIDER=custom +DIALECTIC__LEVELS__minimal__MODEL=google/gemini-2.5-flash-lite +DIALECTIC__LEVELS__low__PROVIDER=custom +DIALECTIC__LEVELS__low__MODEL=google/gemini-2.5-flash-lite # Medium tier — better reasoning -DIALECTIC_LEVELS__medium__PROVIDER=custom -DIALECTIC_LEVELS__medium__MODEL=anthropic/claude-haiku-4-5 -DIALECTIC_LEVELS__high__PROVIDER=custom -DIALECTIC_LEVELS__high__MODEL=anthropic/claude-haiku-4-5 -DIALECTIC_LEVELS__max__PROVIDER=custom -DIALECTIC_LEVELS__max__MODEL=anthropic/claude-haiku-4-5 +DIALECTIC__LEVELS__medium__PROVIDER=custom +DIALECTIC__LEVELS__medium__MODEL=anthropic/claude-haiku-4-5 +DIALECTIC__LEVELS__high__PROVIDER=custom +DIALECTIC__LEVELS__high__MODEL=anthropic/claude-haiku-4-5 +DIALECTIC__LEVELS__max__PROVIDER=custom +DIALECTIC__LEVELS__max__MODEL=anthropic/claude-haiku-4-5Based on learnings: Dialectic now uses per-level providers via
settings.DIALECTIC.LEVELS; overrides must use nested env variables likeDIALECTIC__LEVELS__minimal__PROVIDER.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/configuration.mdx` around lines 77 - 88, Replace the env var keys that use a single underscore between DIALECTIC and LEVELS (e.g., any occurrences like DIALECTIC_LEVELS__minimal__PROVIDER, DIALECTIC_LEVELS__low__MODEL, etc.) with the nested env-var format DIALECTIC__LEVELS__... (e.g., DIALECTIC__LEVELS__minimal__PROVIDER, DIALECTIC__LEVELS__low__MODEL) so they map into settings.DIALECTIC.LEVELS; update every similar entry in this snippet (minimal/low/medium/high/max PROVIDER and MODEL lines) to use the double-underscore separator between DIALECTIC and LEVELS.
29-32:⚠️ Potential issue | 🟠 MajorFix the env var naming example for nested settings.
The example shows
DIALECTIC_LEVELS__minimal__PROVIDERbut the correct format isDIALECTIC__LEVELS__minimal__PROVIDER(double underscore afterDIALECTIC).🔧 Proposed fix
- `{SECTION}_{KEY}` for section settings (e.g., `DB_CONNECTION_URI` → `[db].CONNECTION_URI`) - `{KEY}` for app-level settings (e.g., `LOG_LEVEL` → `[app].LOG_LEVEL`) -- `{SECTION}__{NESTED}__{KEY}` for deeply nested settings (double underscore, e.g., `DIALECTIC_LEVELS__minimal__PROVIDER`) +- `{SECTION}__{NESTED}__{KEY}` for deeply nested settings (double underscore, e.g., `DIALECTIC__LEVELS__minimal__PROVIDER`)Based on learnings: Dialectic now uses per-level providers via
settings.DIALECTIC.LEVELS; overrides must use nested env variables likeDIALECTIC__LEVELS__minimal__PROVIDER.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/configuration.mdx` around lines 29 - 32, The env-var example for nested settings is wrong: update the doc where it shows DIALECTIC_LEVELS__minimal__PROVIDER to use the correct nested env var format DIALECTIC__LEVELS__minimal__PROVIDER (double underscore after DIALECTIC) and mention that this maps to settings.DIALECTIC.LEVELS so per-level providers (e.g., minimal.PROVIDER) can be overridden via DIALECTIC__LEVELS__minimal__PROVIDER.docs/v3/contributing/troubleshooting.mdx (1)
152-161:⚠️ Potential issue | 🟠 MajorUse
DIALECTIC__LEVELS__...for nested overrides.The dialectic per-level env vars are missing the separator between the top-level
DIALECTICsection and the nestedLEVELSsection.DIALECTIC_LEVELS__...will not populatesettings.DIALECTIC.LEVELS, so these thinking-budget overrides will not take effect.🔧 Proposed fix
```bash DERIVER_THINKING_BUDGET_TOKENS=0 SUMMARY_THINKING_BUDGET_TOKENS=0 DREAM_THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__minimal__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__low__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__medium__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__high__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__low__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__medium__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__high__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__max__THINKING_BUDGET_TOKENS=0</details> Based on learnings: Dialectic now uses per-level providers via `settings.DIALECTIC.LEVELS`; overrides must use nested env variables like `DIALECTIC__LEVELS__minimal__PROVIDER`. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/v3/contributing/troubleshooting.mdxaround lines 152 - 161, The env var
examples for per-level dialectic overrides are missing the nested separator;
replace any occurrences of DIALECTIC_LEVELS__... with DIALECTIC__LEVELS__... so
they populate settings.DIALECTIC.LEVELS (e.g., use
DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS=0 and for providers use
DIALECTIC__LEVELS__minimal__PROVIDER); update the example lines in the docs (the
block containing DERIVER_THINKING_BUDGET_TOKENS, SUMMARY_THINKING_BUDGET_TOKENS,
etc.) to use the double-underscore DIALECTIC__LEVELS__ prefix for all per-level
overrides.</details> </blockquote></details> <details> <summary>docs/v3/contributing/self-hosting.mdx (1)</summary><blockquote> `51-74`: _⚠️ Potential issue_ | _🟠 Major_ **Use `DIALECTIC__LEVELS__...` for per-level overrides.** All dialectic level env vars in this setup example use the wrong separator format. Users copying this will not have their dialectic settings applied. <details> <summary>🔧 Proposed fix</summary> ```diff # One model for everything DERIVER_PROVIDER=custom DERIVER_MODEL=google/gemini-2.5-flash SUMMARY_PROVIDER=custom SUMMARY_MODEL=google/gemini-2.5-flash -DIALECTIC_LEVELS__minimal__PROVIDER=custom -DIALECTIC_LEVELS__minimal__MODEL=google/gemini-2.5-flash -DIALECTIC_LEVELS__low__PROVIDER=custom -DIALECTIC_LEVELS__low__MODEL=google/gemini-2.5-flash -DIALECTIC_LEVELS__medium__PROVIDER=custom -DIALECTIC_LEVELS__medium__MODEL=google/gemini-2.5-flash -DIALECTIC_LEVELS__high__PROVIDER=custom -DIALECTIC_LEVELS__high__MODEL=google/gemini-2.5-flash -DIALECTIC_LEVELS__max__PROVIDER=custom -DIALECTIC_LEVELS__max__MODEL=google/gemini-2.5-flash +DIALECTIC__LEVELS__minimal__PROVIDER=custom +DIALECTIC__LEVELS__minimal__MODEL=google/gemini-2.5-flash +DIALECTIC__LEVELS__low__PROVIDER=custom +DIALECTIC__LEVELS__low__MODEL=google/gemini-2.5-flash +DIALECTIC__LEVELS__medium__PROVIDER=custom +DIALECTIC__LEVELS__medium__MODEL=google/gemini-2.5-flash +DIALECTIC__LEVELS__high__PROVIDER=custom +DIALECTIC__LEVELS__high__MODEL=google/gemini-2.5-flash +DIALECTIC__LEVELS__max__PROVIDER=custom +DIALECTIC__LEVELS__max__MODEL=google/gemini-2.5-flash DREAM_PROVIDER=custom DREAM_MODEL=google/gemini-2.5-flash DREAM_DEDUCTION_MODEL=google/gemini-2.5-flash DREAM_INDUCTION_MODEL=google/gemini-2.5-flash # Disable thinking budget (only needed for Anthropic models) DERIVER_THINKING_BUDGET_TOKENS=0 SUMMARY_THINKING_BUDGET_TOKENS=0 DREAM_THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__minimal__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__low__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__medium__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__high__THINKING_BUDGET_TOKENS=0 -DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__low__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__medium__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__high__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__max__THINKING_BUDGET_TOKENS=0Based on learnings: Dialectic now uses per-level providers via
settings.DIALECTIC.LEVELS; overrides must use nested env variables likeDIALECTIC__LEVELS__minimal__PROVIDER.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/self-hosting.mdx` around lines 51 - 74, The env var keys in the example use the wrong separator (e.g. DIALECTIC_LEVELS__minimal__PROVIDER) so per-level overrides won't be applied; change every DIALECTIC_LEVELS__... occurrence to the nested form DIALECTIC__LEVELS__... (double underscore before and after LEVELS) so they map to settings.DIALECTIC.LEVELS (e.g., update DIALECTIC_LEVELS__minimal__MODEL → DIALECTIC__LEVELS__minimal__MODEL and similarly for THINKING_BUDGET_TOKENS and other DIALECTIC_* entries).🧹 Nitpick comments (1)
docs/v3/contributing/self-hosting.mdx (1)
39-75: Consider documenting the embedding configuration.This "one key / one model" setup rewires generation models but doesn't address embeddings. With
EMBED_MESSAGES=true(the default), users following this guide may still encounter OpenAI embedding errors unless they either:
- Set
EMBED_MESSAGES=falseto disable embeddings entirely, or- Configure embedding-specific overrides (
LLM_OPENAI_BASE_URL,LLM_OPENAI_EMBEDDING_MODEL)Adding a note or example for embedding configuration would make the single-provider story complete.
Based on learnings:
OPENAI_BASE_URLis the key override for using OpenAI-compatible embedding providers such as Ollama.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/self-hosting.mdx` around lines 39 - 75, Add a short note explaining that embeddings are separate from generation: either set EMBED_MESSAGES=false to disable embeddings or configure embedding-specific overrides (LLM_OPENAI_BASE_URL and LLM_OPENAI_EMBEDDING_MODEL) so embedding calls target the OpenAI-compatible endpoint; also mention that if you're using the compatibility vars shown (LLM_OPENAI_COMPATIBLE_BASE_URL) you must also point embedding requests to that endpoint (e.g., via LLM_OPENAI_BASE_URL) when EMBED_MESSAGES=true.🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed. Outside diff comments: In `@docs/v3/contributing/configuration.mdx`: - Around line 209-215: Update the per-level environment variable examples to use the correct double-underscore nesting for settings.DIALECTIC.LEVELS by replacing the incorrect prefix "DIALECTIC_LEVELS__" with "DIALECTIC__LEVELS__" in the examples (i.e., change entries referencing DIALECTIC_LEVELS__minimal__... to DIALECTIC__LEVELS__minimal__... so they match the nested settings key used by the code). --- Duplicate comments: In `@docs/v3/contributing/configuration.mdx`: - Around line 134-137: The environment variable names for per-level thinking budgets use wrong separators; update the variables like DIALECTIC_LEVELS__medium__THINKING_BUDGET_TOKENS, DIALECTIC_LEVELS__high__THINKING_BUDGET_TOKENS, and DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS to the nested env format used by settings.DIALECTIC.LEVELS (e.g., DIALECTIC__LEVELS__medium__THINKING_BUDGET_TOKENS, DIALECTIC__LEVELS__high__THINKING_BUDGET_TOKENS, DIALECTIC__LEVELS__max__THINKING_BUDGET_TOKENS) so the config loader maps them into DIALECTIC.LEVELS properly. - Around line 77-88: Replace the env var keys that use a single underscore between DIALECTIC and LEVELS (e.g., any occurrences like DIALECTIC_LEVELS__minimal__PROVIDER, DIALECTIC_LEVELS__low__MODEL, etc.) with the nested env-var format DIALECTIC__LEVELS__... (e.g., DIALECTIC__LEVELS__minimal__PROVIDER, DIALECTIC__LEVELS__low__MODEL) so they map into settings.DIALECTIC.LEVELS; update every similar entry in this snippet (minimal/low/medium/high/max PROVIDER and MODEL lines) to use the double-underscore separator between DIALECTIC and LEVELS. - Around line 29-32: The env-var example for nested settings is wrong: update the doc where it shows DIALECTIC_LEVELS__minimal__PROVIDER to use the correct nested env var format DIALECTIC__LEVELS__minimal__PROVIDER (double underscore after DIALECTIC) and mention that this maps to settings.DIALECTIC.LEVELS so per-level providers (e.g., minimal.PROVIDER) can be overridden via DIALECTIC__LEVELS__minimal__PROVIDER. In `@docs/v3/contributing/self-hosting.mdx`: - Around line 51-74: The env var keys in the example use the wrong separator (e.g. DIALECTIC_LEVELS__minimal__PROVIDER) so per-level overrides won't be applied; change every DIALECTIC_LEVELS__... occurrence to the nested form DIALECTIC__LEVELS__... (double underscore before and after LEVELS) so they map to settings.DIALECTIC.LEVELS (e.g., update DIALECTIC_LEVELS__minimal__MODEL → DIALECTIC__LEVELS__minimal__MODEL and similarly for THINKING_BUDGET_TOKENS and other DIALECTIC_* entries). In `@docs/v3/contributing/troubleshooting.mdx`: - Around line 152-161: The env var examples for per-level dialectic overrides are missing the nested separator; replace any occurrences of DIALECTIC_LEVELS__... with DIALECTIC__LEVELS__... so they populate settings.DIALECTIC.LEVELS (e.g., use DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS=0 and for providers use DIALECTIC__LEVELS__minimal__PROVIDER); update the example lines in the docs (the block containing DERIVER_THINKING_BUDGET_TOKENS, SUMMARY_THINKING_BUDGET_TOKENS, etc.) to use the double-underscore DIALECTIC__LEVELS__ prefix for all per-level overrides. --- Nitpick comments: In `@docs/v3/contributing/self-hosting.mdx`: - Around line 39-75: Add a short note explaining that embeddings are separate from generation: either set EMBED_MESSAGES=false to disable embeddings or configure embedding-specific overrides (LLM_OPENAI_BASE_URL and LLM_OPENAI_EMBEDDING_MODEL) so embedding calls target the OpenAI-compatible endpoint; also mention that if you're using the compatibility vars shown (LLM_OPENAI_COMPATIBLE_BASE_URL) you must also point embedding requests to that endpoint (e.g., via LLM_OPENAI_BASE_URL) when EMBED_MESSAGES=true.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID:
cd729ff0-5841-4211-8d49-1fc76fd0cc8d📒 Files selected for processing (3)
docs/v3/contributing/configuration.mdxdocs/v3/contributing/self-hosting.mdxdocs/v3/contributing/troubleshooting.mdx
.env.template now has provider/model lines uncommented with placeholder values — user just sets endpoint, key, and model name. Thinking budgets default to 0 for non-Anthropic providers. Self-hosting page: removed 30-line env var wall, LLM setup now points to the template. Merged duplicate verify sections. Removed api_key from SDK examples (auth off by default).
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/v3/contributing/self-hosting.mdx (1)
35-47:⚠️ Potential issue | 🟠 MajorLLM Setup section should mention embedding configuration.
The "one API key and one model" guidance covers generation models but doesn't address embeddings. Since
LLM_EMBEDDING_PROVIDERdefaults toopenai, users following this single-provider setup may encounter embedding failures unless they also configure an OpenAI API key or switch the embedding provider.Consider adding a note like: "Embeddings default to OpenAI. If using a different provider, set
LLM_EMBEDDING_PROVIDER=openrouterin your.env."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/self-hosting.mdx` around lines 35 - 47, Add a short note to the "LLM Setup" section (near the .env.template guidance) explaining that embeddings default to OpenAI and must be configured separately: reference the environment variable LLM_EMBEDDING_PROVIDER and instruct users to set it (e.g., LLM_EMBEDDING_PROVIDER=openrouter) or provide an OpenAI API key in the .env.template when using a single-provider setup so embeddings don't fail; update the text around `.env.template` and the LLM model/provider guidance to mention this embedding-specific configuration.
🧹 Nitpick comments (1)
docs/v3/contributing/self-hosting.mdx (1)
235-238: Inconsistent SDK initialization examples.The test script example includes
workspace_id="my-app-testing"but the "Connect Your Application" section omits it. Either both should include it for consistency, or clarify whenworkspace_idis required vs optional.Option: Add workspace_id to both examples
client = Honcho( base_url="http://localhost:8000", + workspace_id="my-app", )Also applies to: 255-257
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/self-hosting.mdx` around lines 235 - 238, The SDK initialization examples are inconsistent: add workspace_id to the "Connect Your Application" example (and any other examples in this doc around the Connect section and the test script block) or explicitly state when workspace_id is optional; specifically update the Honcho initialization examples to use the same form (e.g., Honcho(base_url="http://localhost:8000", workspace_id="my-app-testing")) so the base_url and workspace_id usage is consistent across the test script and Connect Your Application sections, or add a short note next to the Honcho constructor explaining that workspace_id is optional and when it should be provided.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.env.template:
- Line 88: The .env.template comment should clarify embedding-provider behavior
and guidance: update the commented line for LLM_EMBEDDING_PROVIDER to be
uncommented or add explanatory text indicating that embeddings default to openai
unless LLM_OPENAI_API_KEY is set or LLM_EMBEDDING_PROVIDER is changed to
openrouter (and the custom endpoint supports embeddings); also document that
OPENAI_BASE_URL can override the OpenAI-compatible endpoint and
OPENAI_EMBEDDING_MODEL can specify a custom embedding model name so
single-provider users know how to route embedding requests correctly.
- Around line 127-146: The env vars for per-level settings are incorrectly named
(DIALECTIC_LEVELS__...) and should use a double underscore to represent the
nested DIALECTIC -> LEVELS structure so Pydantic can load
settings.DIALECTIC.LEVELS; update all occurrences like
DIALECTIC_LEVELS__minimal__PROVIDER, DIALECTIC_LEVELS__low__MODEL, etc., to
DIALECTIC__LEVELS__minimal__PROVIDER, DIALECTIC__LEVELS__low__MODEL, etc.,
ensuring every level key (minimal, low, medium, high, max) and their subkeys
(PROVIDER, MODEL, THINKING_BUDGET_TOKENS, MAX_TOOL_ITERATIONS,
MAX_OUTPUT_TOKENS) use DIALECTIC__LEVELS__<level>__<KEY> naming.
---
Duplicate comments:
In `@docs/v3/contributing/self-hosting.mdx`:
- Around line 35-47: Add a short note to the "LLM Setup" section (near the
.env.template guidance) explaining that embeddings default to OpenAI and must be
configured separately: reference the environment variable LLM_EMBEDDING_PROVIDER
and instruct users to set it (e.g., LLM_EMBEDDING_PROVIDER=openrouter) or
provide an OpenAI API key in the .env.template when using a single-provider
setup so embeddings don't fail; update the text around `.env.template` and the
LLM model/provider guidance to mention this embedding-specific configuration.
---
Nitpick comments:
In `@docs/v3/contributing/self-hosting.mdx`:
- Around line 235-238: The SDK initialization examples are inconsistent: add
workspace_id to the "Connect Your Application" example (and any other examples
in this doc around the Connect section and the test script block) or explicitly
state when workspace_id is optional; specifically update the Honcho
initialization examples to use the same form (e.g.,
Honcho(base_url="http://localhost:8000", workspace_id="my-app-testing")) so the
base_url and workspace_id usage is consistent across the test script and Connect
Your Application sections, or add a short note next to the Honcho constructor
explaining that workspace_id is optional and when it should be provided.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a8774bac-bb5a-4bd4-8dfa-6479c26ffd98
📒 Files selected for processing (2)
.env.templatedocs/v3/contributing/self-hosting.mdx
Without this, embeddings default to openai which requires a separate LLM_OPENAI_API_KEY. Setting to openrouter routes embeddings through the same OpenAI-compatible endpoint as everything else.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/v3/contributing/self-hosting.mdx (1)
37-42:⚠️ Potential issue | 🟠 MajorThe simplified setup still leaves embeddings undocumented.
This path only explains generation-provider setup, so readers can still leave embeddings on the default OpenAI route and end up needing a second provider even though the copy says “one API key and one model.” Please call out the matching embedding override, or an explicit disable/retarget step, next to this guidance. Based on learnings:
OPENAI_BASE_URLis the key override for OpenAI-compatible embedding providers, andOPENAI_EMBEDDING_MODELlets users replace the default embedding model.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3/contributing/self-hosting.mdx` around lines 37 - 42, The docs claim "one API key and one model" but don't mention embedding configuration; update the paragraph that starts "You need one API key and one model" to also instruct readers how to override or disable the default OpenAI embeddings by setting the environment variables OPENAI_BASE_URL (to point embeddings to an OpenAI-compatible provider) and OPENAI_EMBEDDING_MODEL (to choose a non-default embedding model), and add a brief note about explicitly disabling or retargeting embeddings if using a different provider so users won't inadvertently require a second provider.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/v3/contributing/self-hosting.mdx`:
- Around line 293-297: Update the wording that claims the default compose is
"production-ready": change it to "production-oriented defaults" or explicitly
state that public deployments are not ready until authentication is enabled;
reference the AUTH_USE_AUTH flag and the python scripts/generate_jwt_secret.py
step in the adjacent section so readers know to set AUTH_USE_AUTH=true and
generate a JWT secret before public deployment.
- Around line 341-343: Clarify that the deriver service exposes Prometheus
metrics on port 9090 inside its container (accessible via Docker DNS as
deriver:9090), whereas the development Compose exposes/prometheus binds host
port 9090 (e.g., 127.0.0.1:9090:9090) for the Prometheus UI; update the lines
referencing "deriver exposes Prometheus metrics on port 9090" and "dev compose
includes Prometheus on port 9090" to explicitly state "container/internal port"
vs "host/mapped port" and give the example Docker DNS and host mapping to
prevent confusion.
---
Duplicate comments:
In `@docs/v3/contributing/self-hosting.mdx`:
- Around line 37-42: The docs claim "one API key and one model" but don't
mention embedding configuration; update the paragraph that starts "You need one
API key and one model" to also instruct readers how to override or disable the
default OpenAI embeddings by setting the environment variables OPENAI_BASE_URL
(to point embeddings to an OpenAI-compatible provider) and
OPENAI_EMBEDDING_MODEL (to choose a non-default embedding model), and add a
brief note about explicitly disabling or retargeting embeddings if using a
different provider so users won't inadvertently require a second provider.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ab290026-0bba-4746-ac39-a280bca3e896
📒 Files selected for processing (1)
docs/v3/contributing/self-hosting.mdx
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
.env.template (1)
129-148:⚠️ Potential issue | 🔴 CriticalUse double underscore between
DIALECTICandLEVELSfor nested Pydantic settings.The env var names use
DIALECTIC_LEVELS__*but Pydantic nested settings withenv_prefix="DIALECTIC_"andenv_nested_delimiter="__"requireDIALECTIC__LEVELS__*(double underscore) to access the nestedLEVELSdict. With the current naming, these overrides will not be applied and users will get default values instead.🔧 Proposed fix
-DIALECTIC_LEVELS__minimal__PROVIDER=custom -DIALECTIC_LEVELS__minimal__MODEL=your-model-here -DIALECTIC_LEVELS__minimal__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__minimal__PROVIDER=custom +DIALECTIC__LEVELS__minimal__MODEL=your-model-here +DIALECTIC__LEVELS__minimal__THINKING_BUDGET_TOKENS=0 # DIALECTIC_LEVELS__minimal__MAX_TOOL_ITERATIONS=1 -# DIALECTIC_LEVELS__minimal__MAX_OUTPUT_TOKENS=250 -DIALECTIC_LEVELS__low__PROVIDER=custom -DIALECTIC_LEVELS__low__MODEL=your-model-here -DIALECTIC_LEVELS__low__THINKING_BUDGET_TOKENS=0 +# DIALECTIC__LEVELS__minimal__MAX_OUTPUT_TOKENS=250 +DIALECTIC__LEVELS__low__PROVIDER=custom +DIALECTIC__LEVELS__low__MODEL=your-model-here +DIALECTIC__LEVELS__low__THINKING_BUDGET_TOKENS=0 # DIALECTIC_LEVELS__low__MAX_TOOL_ITERATIONS=5 -DIALECTIC_LEVELS__medium__PROVIDER=custom -DIALECTIC_LEVELS__medium__MODEL=your-model-here -DIALECTIC_LEVELS__medium__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__medium__PROVIDER=custom +DIALECTIC__LEVELS__medium__MODEL=your-model-here +DIALECTIC__LEVELS__medium__THINKING_BUDGET_TOKENS=0 # DIALECTIC_LEVELS__medium__MAX_TOOL_ITERATIONS=2 -DIALECTIC_LEVELS__high__PROVIDER=custom -DIALECTIC_LEVELS__high__MODEL=your-model-here -DIALECTIC_LEVELS__high__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__high__PROVIDER=custom +DIALECTIC__LEVELS__high__MODEL=your-model-here +DIALECTIC__LEVELS__high__THINKING_BUDGET_TOKENS=0 # DIALECTIC_LEVELS__high__MAX_TOOL_ITERATIONS=4 -DIALECTIC_LEVELS__max__PROVIDER=custom -DIALECTIC_LEVELS__max__MODEL=your-model-here -DIALECTIC_LEVELS__max__THINKING_BUDGET_TOKENS=0 +DIALECTIC__LEVELS__max__PROVIDER=custom +DIALECTIC__LEVELS__max__MODEL=your-model-here +DIALECTIC__LEVELS__max__THINKING_BUDGET_TOKENS=0 # DIALECTIC_LEVELS__max__MAX_TOOL_ITERATIONS=10Note: Also update the commented lines 132-133, 137, 141, 145, 149 to use
DIALECTIC__LEVELS__prefix.Based on learnings: Dialectic now uses per-level providers via settings.DIALECTIC.LEVELS; in CI, overrides must use nested env variables like DIALECTIC__LEVELS__minimal__PROVIDER.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env.template around lines 129 - 148, Env vars use a single underscore between DIALECTIC and LEVELS so Pydantic nested settings (env_prefix="DIALECTIC_", env_nested_delimiter="__") won't pick them up; change every occurrence of DIALECTIC_LEVELS__* to DIALECTIC__LEVELS__* (including the commented lines like the MAX_TOOL_ITERATIONS/MAX_OUTPUT_TOKENS entries) so the per-level settings (settings.DIALECTIC.LEVELS, e.g., minimal, low, medium, high, max) are correctly loaded from the environment.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In @.env.template:
- Around line 129-148: Env vars use a single underscore between DIALECTIC and
LEVELS so Pydantic nested settings (env_prefix="DIALECTIC_",
env_nested_delimiter="__") won't pick them up; change every occurrence of
DIALECTIC_LEVELS__* to DIALECTIC__LEVELS__* (including the commented lines like
the MAX_TOOL_ITERATIONS/MAX_OUTPUT_TOKENS entries) so the per-level settings
(settings.DIALECTIC.LEVELS, e.g., minimal, low, medium, high, max) are correctly
loaded from the environment.
Hermes integration page: replaced inline Docker/manual setup with link to self-hosting guide, added elkimek community link. Removed old env var names (OPENAI_API_KEY without LLM_ prefix). Troubleshooting: removed "or 1" from thinking budget guidance. Self-hosting: softened "production-ready" to "production-oriented" since auth is disabled by default.
.env.template: added "e.g. google/gemini-2.5-flash" hints next to model placeholders so users know the expected format. Self-hosting: expanded LLM Setup to show the 3 things users need to set (endpoint, key, model name) with find-replace tip. Added build time note, deriver log check, and real smoke test (create workspace) to verify section. Health check now notes it doesn't verify DB/LLM.
Updated config to match hermes-agent docs: removed apiKey (not needed for self-hosted), added hermes memory setup CLI command, added config fields table (recallMode, writeFrequency, sessionStrategy, etc.). Better verification tests: store-and-recall across sessions, direct tool calling test. Links to upstream hermes docs for full field list.
This was referenced Apr 7, 2026
Local Environment Setup docs doesn't mention Honcho uses Gemini by default and requires API key
#482
Closed
Closed
Comment out THINKING_BUDGET_TOKENS=0 in .env.template — deriver, summary, and dream validators require gt=0. Dialectic levels also commented out since non-thinking models don't need the override. Add COPY for docker/ directory in Dockerfile so entrypoint.sh is available when docker-compose.yml.example references it.
VVoruganti
approved these changes
Apr 8, 2026
Comment on lines
+108
to
+111
| 4. **Processing backlog** — With `DERIVER_WORKERS=1` (default), high message volume can cause a backlog. Increase workers: | ||
| ```bash | ||
| DERIVER_WORKERS=4 | ||
| ``` |
Collaborator
There was a problem hiding this comment.
Another thing to add here is if the representation batch max is too high then the session may not have reached a threshold tu run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Supersedes #460 (includes Vineeth's original 3 commits).
Test plan
Summary by CodeRabbit
New Features
Documentation
Chores