Merge pull request #9 from scalytics/modelsupport

Multi-provider LLM support with middleware, CLI, and FinOps

Author: novatechflow

Makefile

@@ -45,19 +45,27 @@ Configuration values are resolved in this precedence (highest wins):
 
 ```go
 type Config struct {
-    Agents       AgentsConfig       `json:"agents"`
-    Channels     ChannelsConfig     `json:"channels"`
-    Providers    ProvidersConfig    `json:"providers"`
-    Gateway      GatewayConfig      `json:"gateway"`
-    Tools        ToolsConfig        `json:"tools"`
-    Group        GroupConfig        `json:"group"`
-    Orchestrator OrchestratorConfig `json:"orchestrator"`
-    Scheduler    SchedulerConfig    `json:"scheduler"`
-    ER1          ER1Config          `json:"er1"`
-    Observer     ObserverConfig     `json:"observer"`
+    Paths                 PathsConfig                 `json:"paths"`
+    Model                 ModelConfig                 `json:"model"`
+    Agents                AgentsConfig                `json:"agents"`
+    Channels              ChannelsConfig              `json:"channels"`
+    Providers             ProvidersConfig             `json:"providers"`
+    Gateway               GatewayConfig               `json:"gateway"`
+    Tools                 ToolsConfig                 `json:"tools"`
+    Group                 GroupConfig                 `json:"group"`
+    Orchestrator          OrchestratorConfig          `json:"orchestrator"`
+    Scheduler             SchedulerConfig             `json:"scheduler"`
+    ER1                   ER1IntegrationConfig        `json:"er1"`
+    Observer              ObserverMemoryConfig        `json:"observer"`
+    ContentClassification ContentClassificationConfig `json:"contentClassification"`
+    PromptGuard           PromptGuardConfig           `json:"promptGuard"`
+    OutputSanitization    OutputSanitizationConfig    `json:"outputSanitization"`
+    FinOps                FinOpsConfig                `json:"finops"`
 }
 ```
 
+New sections added in this release: `Model`, `Paths`, `ContentClassification`, `PromptGuard`, `OutputSanitization`, `FinOps`. See [Configuration Keys](../reference/config-keys/) for details.
+
 ### Agent Configuration
 
 | Field | Default | Env Var | Description |
@@ -354,7 +362,7 @@ Isolation guarantees:
 
 ### Provider Architecture
 
-All providers use the OpenAI-compatible API format via a single `OpenAIProvider` implementation.
+KafClaw supports 11 LLM providers through a unified `LLMProvider` interface. Most use the OpenAI-compatible API format. Providers are identified by canonical IDs and selected via model strings in the format `provider-id/model-name`.
 
 ```go
 type LLMProvider interface {
@@ -363,26 +371,66 @@ type LLMProvider interface {
     Speak(ctx, *TTSRequest) (*TTSResponse, error)
     DefaultModel() string
 }
+```
 
-type Embedder interface {
-    Embed(ctx, *EmbeddingRequest) (*EmbeddingResponse, error)
-}
+### Supported Providers
+
+| Provider ID | Auth | Default Base |
+|---|---|---|
+| `claude` | API key | `https://api.anthropic.com/v1` |
+| `openai` | API key | _(configured)_ |
+| `gemini` | API key | Google AI Studio |
+| `gemini-cli` | OAuth | _(via Gemini CLI)_ |
+| `openai-codex` | OAuth | _(via Codex CLI)_ |
+| `xai` | API key | `https://api.x.ai/v1` |
+| `scalytics-copilot` | API key + base | _(configured)_ |
+| `openrouter` | API key | `https://openrouter.ai/api/v1` |
+| `deepseek` | API key | `https://api.deepseek.com/v1` |
+| `groq` | API key | `https://api.groq.com/openai/v1` |
+| `vllm` | optional key + base | _(configured)_ |
+
+For full provider setup, see [LLM Providers Reference](../reference/providers/).
+
+### Provider Resolution Order
+
+1. Per-agent model (`agents.list[].model.primary`)
+2. Task-type routing (`model.taskRouting[category]`)
+3. Global model (`model.name`)
+4. Legacy OpenAI fallback
+
+### Managing Credentials
+
+```bash
+# API key providers
+kafclaw models auth set-key --provider claude --key sk-ant-...
+
+# OAuth providers (Gemini, Codex)
+kafclaw models auth login --provider gemini
 ```
 
-### Capabilities
+See [Models CLI Reference](../reference/models-cli/) for all auth commands.
+
+### Middleware Chain
+
+A configurable middleware chain runs between the agent loop and the LLM provider:
 
-| Capability | Endpoint | Default Model |
-|------------|----------|---------------|
-| Chat completion | `/chat/completions` | `anthropic/claude-sonnet-4-5` |
-| Audio transcription | `/audio/transcriptions` | `whisper-1` |
-| Text-to-speech | `/audio/speech` | `tts-1` (voice: nova, format: opus) |
-| Embeddings | `/embeddings` | `text-embedding-3-small` |
+- **Content Classifier** — sensitivity tagging and model rerouting
+- **Prompt Guard** — PII/secret scanning (warn, redact, or block)
+- **Output Sanitizer** — response redaction and deny pattern filtering
+- **FinOps Recorder** — per-request cost calculation and budget warnings
 
-### API Key Fallback Chain
+See [Chat Middleware Reference](../reference/middleware/) for configuration.
 
-1. `cfg.Providers.OpenAI.APIKey` (config or `KAFCLAW_OPENAI_API_KEY`)
-2. `OPENAI_API_KEY` environment variable
-3. `OPENROUTER_API_KEY` environment variable
+### Token & Cost Tracking
+
+Token usage and cost are tracked per request, per provider, per day in the timeline database.
+
+```bash
+kafclaw models stats           # today's usage
+kafclaw models stats --days 7  # 7-day trend
+kafclaw status                 # includes provider info
+kafclaw doctor                 # warns on low rate limits
+```
 
 ---
 

_tasks/provider-support.md

@@ -11,6 +11,7 @@ Primary command groups:
 - `kafclaw status` - runtime/config health snapshot
 - `kafclaw doctor` - diagnostics and setup checks
 - `kafclaw security` - security checks, deep audit, and safe remediation (`check|audit|fix`)
+- `kafclaw models` - manage LLM providers and models (`list|stats|auth login|auth set-key`)
 - `kafclaw config` / `kafclaw configure` - low-level and guided config changes
 - `kafclaw agent -m` - one-shot interaction
 - `kafclaw skills` - bundled/external skill lifecycle and auth/prereq flows (`enable|disable|list|status|enable-skill|disable-skill|verify|install|update|exec|prereq|auth`)
@@ -37,6 +38,7 @@ Detailed command examples:
 - [Getting Started](../start-here/getting-started/)
 - [User Manual - CLI Reference section](../start-here/user-manual/#3-cli-reference)
 - [Manage KafClaw](../operations-admin/manage-kafclaw/)
+- [Models CLI Reference](models-cli/) - provider management, auth, usage stats
 
 Skills execution example:
 - `kafclaw skills exec <skill-id> --input '{"text":"..."}'`

docs/operations-admin/admin-guide.md

@@ -61,11 +61,92 @@ kafclaw status
 kafclaw doctor
 ```
 
+## Model Configuration
+
+```json
+{
+  "model": {
+    "name": "claude/claude-sonnet-4-5",
+    "maxTokens": 8192,
+    "temperature": 0.7,
+    "maxToolIterations": 20,
+    "taskRouting": {
+      "security": "claude/claude-opus-4-6",
+      "coding": "openai-codex/gpt-5.3-codex"
+    }
+  }
+}
+```
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `model.name` | string | Global default model in `provider/model` format |
+| `model.maxTokens` | int | Max output tokens per LLM call |
+| `model.temperature` | float | Sampling temperature (0.0 - 1.0) |
+| `model.maxToolIterations` | int | Max tool-call rounds per request |
+| `model.taskRouting` | map | Category to model string overrides (`security`, `coding`, `tool-heavy`, `creative`) |
+
+## Provider Configuration
+
+```json
+{
+  "providers": {
+    "anthropic": { "apiKey": "sk-ant-...", "apiBase": "" },
+    "openai": { "apiKey": "sk-...", "apiBase": "" },
+    "gemini": { "apiKey": "AIza..." },
+    "xai": { "apiKey": "xai-..." },
+    "openrouter": { "apiKey": "sk-or-...", "apiBase": "https://openrouter.ai/api/v1" },
+    "deepseek": { "apiKey": "sk-...", "apiBase": "https://api.deepseek.com/v1" },
+    "groq": { "apiKey": "gsk_...", "apiBase": "https://api.groq.com/openai/v1" },
+    "vllm": { "apiKey": "", "apiBase": "http://localhost:8000/v1" },
+    "scalyticsCopilot": { "apiKey": "<token>", "apiBase": "https://copilot.scalytics.io/v1" }
+  }
+}
+```
+
+Each provider entry accepts `apiKey` and `apiBase`. See [LLM Providers](providers/) for details.
+
+## Per-Agent Model Configuration
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "model": {
+          "primary": "claude/claude-opus-4-6",
+          "fallbacks": ["openai/gpt-4o"]
+        },
+        "subagents": {
+          "model": "groq/llama-3.3-70b"
+        }
+      }
+    ]
+  }
+}
+```
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `agents.list[].model.primary` | string | Primary model for this agent |
+| `agents.list[].model.fallbacks` | []string | Fallback models tried on transient errors |
+| `agents.list[].subagents.model` | string | Model for subagents spawned by this agent |
+
+## Middleware Configuration
+
+| Section | Reference |
+|---------|-----------|
+| `contentClassification` | [Content Classification](middleware/#content-classification) |
+| `promptGuard` | [Prompt Guard](middleware/#prompt-guard) |
+| `outputSanitization` | [Output Sanitizer](middleware/#output-sanitizer) |
+| `finops` | [FinOps Cost Attribution](middleware/#finops-cost-attribution) |
+
 ## Common Environment Variables
 
 - `OPENAI_API_KEY`
 - `OPENROUTER_API_KEY`
-- `KAFCLAW_AGENTS_MODEL`
+- `KAFCLAW_MODEL` — global model (e.g. `claude/claude-sonnet-4-5`)
 - `KAFCLAW_AGENTS_WORKSPACE`
 - `KAFCLAW_AGENTS_WORK_REPO_PATH`
 - `KAFCLAW_GATEWAY_HOST`
@@ -82,6 +163,9 @@ kafclaw doctor
 
 ## Related Docs
 
+- [LLM Providers](providers/)
+- [Models CLI](models-cli/)
+- [Chat Middleware](middleware/)
 - [Getting Started Guide](../start-here/getting-started/)
 - [KafClaw Administration Guide](../operations-admin/admin-guide/)
 - [Workspace Policy](../architecture-security/workspace-policy/)