rapor2.md

Provider Expansion Report

1. New providers added

The provider registry now includes these additional targets:

• ollama
• openai-compatible
• claude
• openai
• gemini

These were added as real adapters under src/komu_cli/providers/adapters, not as placeholder labels.

2. Existing provider logic changed

The provider layer was strengthened in several core areas:

• ProviderDescriptor now carries deployment scope, capability metadata, base URL defaults, timeout defaults, and env-var mapping.
• ProviderAdapter now exposes configuration checks, endpoint reporting, suitability scoring, and health checks through a shared contract.
• ProviderService now supports:
  • capability-matrix output
  • live or cached provider health reporting
  • suitability-aware routing
  • explicit-provider fallback
  • local/self-hosted preference when task wording suggests it
  • default/active-provider preference in fallback order

Existing providers such as OpenCode, DeepSeek, Kimi, and GLM-5 were updated to publish structured capability metadata so they participate in the same selection model as the new providers.

3. Health check functionality added

KOMU now has provider health checks with CLI wiring.

Supported commands:

• komu providers health
• komu providers check <provider>
• komu providers capabilities

Health checks currently cover:

• Ollama reachability and model presence through /api/tags
• OpenAI-compatible endpoint reachability and model discovery through /models
• OpenAI reachability through the OpenAI-compatible adapter path
• Claude reachability through Anthropic model listing
• Gemini reachability through model discovery

Health results are stored in context and used by routing/fallback logic. Failures degrade provider suitability without crashing unrelated flows.

4. Capability matrix functionality added

Providers now publish structured capability flags such as:

• planning
• explanation
• repair reasoning
• long-context suitability
• fast drafting
• local-friendly
• offline-capable
• self-hostable / remote dependency hints

These capabilities are surfaced through provider listing and the dedicated capability matrix command. Routing uses the matrix as a scoring input instead of relying only on provider names.

5. Config and environment changes introduced

Provider settings now support:

• model_name
• api_base
• timeout_seconds
• api_key_env_var
• enabled

Descriptor-driven defaults and env overrides were added in config loading so KOMU can fill in sane defaults while still respecting explicit configuration.

New env/config coverage includes:

• KOMU_OLLAMA_BASE_URL
• KOMU_OLLAMA_MODEL
• KOMU_OLLAMA_TIMEOUT
• KOMU_OPENAI_COMPAT_BASE_URL
• KOMU_OPENAI_COMPAT_MODEL
• KOMU_OPENAI_COMPAT_TIMEOUT
• KOMU_OPENAI_COMPAT_API_KEY
• KOMU_CLAUDE_API_KEY
• KOMU_CLAUDE_MODEL
• KOMU_CLAUDE_TIMEOUT
• KOMU_OPENAI_API_KEY
• KOMU_OPENAI_MODEL
• KOMU_OPENAI_TIMEOUT
• KOMU_GEMINI_API_KEY
• KOMU_GEMINI_MODEL
• KOMU_GEMINI_TIMEOUT

Secrets remain environment-driven. They are not written into logs by the provider layer.

6. Tests added and what they validate

New and updated tests include:

• tests/test_provider_service.py

  • provider registration for the expanded registry
  • suitability-based auto routing
  • local/offline routing preference toward Ollama
  • explicit-provider fallback when credentials are missing
  • fallback after runtime provider failure
  • capability matrix tags

• tests/test_provider_adapters.py

  • Ollama health check success path
  • OpenAI-compatible endpoint failure path

• tests/test_config_service.py

  • default config population for the expanded provider set
  • env override parsing for provider configuration

• tests/test_provider_commands.py

  • CLI rendering for capability and health views

• tests/test_cli_smoke.py

  • provider list flow still works after the provider expansion

Validation result for this task:

• python -m compileall src passed
• python -m unittest discover -s tests -p "test_*.py" passed with 42 tests

7. Deferred, disabled, or partial items

Nothing was disabled to keep the architecture stable.

A few areas remain intentionally partial:

• real external API integration was not validated against live network endpoints in this environment
• health checks are first-pass checks, not deep semantic model verification
• the capability matrix is descriptor-driven and static for now; it does not benchmark providers dynamically
• OpenAI-compatible support assumes a conventional /models and /chat/completions surface

These are acceptable limits for the current architecture and are documented rather than hidden.

8. Architectural conflicts

No structural conflict was introduced.

The new providers reuse the existing provider abstraction, selection service, config service, and CLI command layer. The main refactor was to deepen the base provider contract so both stub providers and live HTTP providers can participate in the same routing and health model.

One real regression did surface during validation:

• provider tables became too wide and important labels were ellipsized
• explicit provider choice was being explained like auto-routing
• descriptor-level credential requirements were not being inherited correctly by the generic adapter helpers

These issues were fixed in this pass.

9. Weak systems vs strong systems

Recommended usage by system profile:

• Weak systems:

  • prefer hosted providers such as OpenAI, Claude, Gemini, or DeepSeek-style hosted backends
  • use Ollama only with smaller local models and only if local GPU/CPU capacity is acceptable
  • avoid long-context local models unless the machine is provisioned for them

• Strong systems or self-hosted environments:

  • prefer Ollama for local/offline workflows
  • prefer openai-compatible for self-hosted gateways, local inference servers, or internal API fronts
  • use hosted APIs as fallback rather than first resort if data locality matters

10. Recommended default provider strategy

Current recommended strategy:

• Keep opencode as the safest transparent default if a user wants predictable no-surprise planning during setup.
• Enable auto routing once multiple providers are configured.
• Prefer:
  • ollama for local/offline/self-hosted tasks
  • deepseek for diagnostics and repair-heavy reasoning
  • kimi or claude for longer configuration or explanation work
  • openai or gemini when hosted general-purpose reasoning is preferred
  • openai-compatible when the user controls their own API-compatible endpoint

Operationally, the best general approach now is:

1. keep a stable default provider
2. turn on auto routing only after health checks pass
3. use komu providers health to verify local/self-hosted endpoints
4. let fallback return to the active/default provider if a preferred provider is unavailable