Skip to content

providers.md

Latest commit

 

History

History
382 lines (264 loc) · 9.47 KB

providers.md

File metadata and controls

382 lines (264 loc) · 9.47 KB

Providers

KOMU uses a shared provider abstraction for planning, explanation, and repair reasoning. Providers can influence planning, but they do not bypass playbook preference, risk review, approval flow, or execution transparency.

Provider overview

Current built-in providers:

Provider Key Scope Default trust Typical fit
OpenCode opencode remote / stub-friendly trusted balanced general planning
DeepSeek deepseek remote / stub-friendly trusted diagnostics and repair reasoning
Kimi kimi remote / stub-friendly trusted long-context runbooks and workflow planning
GLM-5 glm5 remote / stub-friendly trusted fast drafts and fallback
Ollama ollama local or self-hosted restricted local model use and privacy-sensitive workflows
OpenAI-Compatible openai-compatible local or remote restricted or untrusted self-hosted gateways and custom OpenAI-style endpoints
Claude claude hosted API trusted long-context hosted reasoning
OpenAI openai hosted API trusted ChatGPT / OpenAI API access
Gemini gemini hosted API trusted hosted general-purpose reasoning

Shared provider contract

Every provider adapter plugs into the same provider layer and exposes:

  • a ProviderDescriptor
  • deployment metadata
  • trust level metadata
  • supported use cases
  • capability metadata
  • configuration validation
  • health check behavior
  • shared request / response models
  • suitability scoring for routing

Current provider use cases:

  • planning
  • explanation
  • repair

Provider trust model

KOMU now tracks a provider trust posture:

  • trusted
  • restricted
  • untrusted

This is not marketing language. It affects how much executable influence a provider gets.

What trust means

  • trusted

    • normal provider participation
    • provider output still goes through the plan model, risk engine, and approval flow

  • restricted

    • provider can still help with planning and explanation
    • sensitive tasks are treated more cautiously
    • executable suggestions may be suppressed for sensitive tasks

  • untrusted

    • provider can still contribute reasoning
    • executable command suggestions are suppressed by default
    • sensitive planning/repair tasks are blocked unless trust is explicitly raised

Default trust posture

  • official hosted providers default to trusted
  • local/self-hosted providers default to restricted
  • remote custom OpenAI-compatible endpoints default to untrusted

This is the main safeguard against treating an arbitrary custom endpoint like a fully trusted built-in provider.

Provider sandboxing model

KOMU does not treat provider output as execution-ready authority.

Current sandboxing behavior includes:

  • context minimization before provider calls
  • sensitive key/value removal from provider context
  • prompt sanitization for obvious secret-like content
  • response shape validation
  • bounded plan-step extraction
  • bounded command suggestion count
  • trust-aware suppression of executable suggestions
  • no direct provider-to-execution path

Even a trusted provider still passes through:

  • plan construction
  • risk review
  • approval requirements
  • operator-visible execution flow

Capability matrix

KOMU tracks provider capability metadata instead of treating all providers as interchangeable.

Current capability dimensions include:

  • planning support
  • explanation support
  • repair reasoning support
  • long-context suitability
  • fast drafting suitability
  • local or self-hosted friendliness
  • offline suitability
  • remote API dependence
  • fallback priority

Inspect the matrix with:

komu providers capabilities

Health checks and readiness

KOMU supports explicit provider health checks:

komu providers health
komu providers check ollama
komu providers check openai-compatible

Health output now distinguishes:

  • trust level
  • readiness
  • configuration validity
  • reachability
  • model availability when practical
  • failure kind when a check fails

Typical readiness states:

  • ready
  • restricted
  • needs-configuration
  • unavailable

Failure classes now distinguish:

  • configuration problems
  • authentication rejection
  • network or reachability failure
  • model availability problems
  • malformed or unusable provider responses

Local vs remote providers

Local / self-hosted fits

Use local or self-hosted providers when you want:

  • stronger data locality
  • less dependence on public APIs
  • compatibility with self-hosted inference
  • a path for lab, private, or offline-ish workflows

Best current options:

  • ollama
  • openai-compatible

Hosted API fits

Use hosted API providers when you want:

  • stronger hosted model quality
  • less local setup
  • better fit for weaker local hardware
  • standard SaaS API flows

Best current options:

  • claude
  • openai
  • gemini

Routing and suitability logic

Automatic routing considers:

  • requested use case
  • provider capability metadata
  • provider trust level
  • local vs remote deployment
  • current configuration validity
  • cached health-check state
  • recent provider failures
  • task wording hints
  • explicit provider choice

Examples:

  • diagnostic / repair wording tends to favor deepseek
  • long-context workflow wording can favor kimi, claude, or gemini
  • local or offline wording can favor ollama
  • OpenAI-style gateway wording can favor openai-compatible

Manual provider selection still works. If the chosen provider is unsuitable, KOMU retains fallback candidates instead of crashing immediately.

Fallback behavior

Provider generation follows a controlled candidate chain:

  1. select a preferred provider
  2. evaluate trust, readiness, and suitability
  3. prepare a sanitized provider request
  4. validate provider response shape
  5. suppress executable influence when trust requires it
  6. record failures without leaking secrets
  7. move to the next candidate if needed

Fallback is recorded in:

  • provider selection metadata
  • task history
  • session events
  • audit logs

Provider configuration

Provider settings are stored through provider settings plus environment variables.

Secret handling defaults

Preferred order:

  1. real shell environment variables
  2. optional keyring backend
  3. .env for local convenience only

Not recommended:

  • storing raw API keys directly in config.json

If KOMU detects plaintext secret-like fields in local config storage, it now warns about that risk.

Optional keyring support

KOMU can optionally read secrets through Python keyring support.

Enable it with:

KOMU_SECRET_BACKEND=keyring

KOMU looks up keyring entries using the env-var reference names as the credential names, under the service name:

  • komu-cli by default

You can override that with:

  • KOMU_KEYRING_SERVICE

If keyring is requested but not installed, KOMU reports that clearly and falls back safely.

Ollama

Environment variables:

  • KOMU_OLLAMA_BASE_URL
  • KOMU_OLLAMA_MODEL
  • KOMU_OLLAMA_TIMEOUT
  • KOMU_OLLAMA_TRUST

Typical setup:

KOMU_OLLAMA_BASE_URL=http://127.0.0.1:11434
KOMU_OLLAMA_MODEL=llama3.1:8b
KOMU_OLLAMA_TRUST=restricted

OpenAI-compatible endpoint

Environment variables:

  • KOMU_OPENAI_COMPAT_BASE_URL
  • KOMU_OPENAI_COMPAT_API_KEY
  • KOMU_OPENAI_COMPAT_MODEL
  • KOMU_OPENAI_COMPAT_TIMEOUT
  • KOMU_OPENAI_COMPAT_TRUST

This adapter is meant for:

  • self-hosted gateways
  • local inference servers
  • private internal API fronts
  • third-party services that expose an OpenAI-style API

Important:

  • local endpoints usually start restricted
  • remote custom endpoints default to a lower-trust posture unless trust is explicitly raised

Claude

Environment variables:

  • KOMU_CLAUDE_API_KEY
  • ANTHROPIC_API_KEY
  • KOMU_CLAUDE_BASE_URL
  • KOMU_CLAUDE_MODEL
  • KOMU_CLAUDE_TIMEOUT

OpenAI / ChatGPT

Environment variables:

  • KOMU_OPENAI_API_KEY
  • OPENAI_API_KEY
  • KOMU_OPENAI_BASE_URL
  • KOMU_OPENAI_MODEL
  • KOMU_OPENAI_TIMEOUT

Gemini

Environment variables:

  • KOMU_GEMINI_API_KEY
  • GEMINI_API_KEY
  • GOOGLE_API_KEY
  • KOMU_GEMINI_BASE_URL
  • KOMU_GEMINI_MODEL
  • KOMU_GEMINI_TIMEOUT

Existing providers

Environment variables remain available for:

  • KOMU_OPENCODE_API_KEY
  • KOMU_DEEPSEEK_API_KEY
  • KOMU_KIMI_API_KEY
  • KOMU_GLM5_API_KEY

Practical recommendations

On weaker local systems

Prefer:

  • hosted APIs for heavy reasoning
  • openai-compatible only when the local model or endpoint is lightweight
  • ollama only if the machine can handle the selected model comfortably

On stronger local systems

Prefer:

  • ollama for local-first workflows
  • openai-compatible for custom inference gateways
  • hosted providers as fallback for harder reasoning or broader model quality

Safe default strategy

Today a sensible default strategy is:

  • keep opencode as a general default
  • turn on auto routing only after provider health checks pass
  • add deepseek for diagnostics-heavy workflows
  • add claude, openai, or gemini for hosted reasoning
  • add ollama or openai-compatible when you want a local or private path

Extending providers

To add a future provider cleanly:

  1. implement the shared adapter contract
  2. define descriptor metadata
  3. expose capability and trust metadata
  4. add configuration validation and health check behavior
  5. register the adapter in the provider registry
  6. document required env/config variables

The provider layer is intentionally isolated so future adapters can be added without rewriting the CLI surface or the planning stack.