mozart-router 0.1.0

package/examples/community-adapter/TEMPLATE.md

@@ -0,0 +1,157 @@
+# Mozart Community Adapter Template
+
+This directory is a template for creating community Mozart adapters.
+
+## Quick start
+
+1. Create a new npm package: `mkdir mozart-router-adapter-mygateway && cd mozart-router-adapter-mygateway`
+2. Copy this template
+3. Implement the `GatewayAdapter` interface
+4. Export a `mozartPlugin` object
+5. Publish to npm: `npm publish`
+
+## Package structure
+
+```
+mozart-router-adapter-mygateway/
+  package.json
+  src/
+    index.ts        # Main entry — MUST export mozartPlugin
+    adapter.ts      # Your GatewayAdapter implementation
+  README.md
+```
+
+## package.json
+
+```json
+{
+  "name": "mozart-router-adapter-mygateway",
+  "version": "1.0.0",
+  "description": "Mozart adapter for MyGateway",
+  "main": "src/index.js",
+  "keywords": ["mozart", "adapter", "mygateway"],
+  "peerDependencies": {
+    "mozart-router": ">=0.1.0"
+  }
+}
+```
+
+## src/adapter.ts
+
+```typescript
+import {
+  GatewayAdapter,
+  DetectionResult,
+  Provider,
+  Model,
+  ExecutionTarget,
+  ExecutionRequest,
+  ExecutionResult,
+  RouteDecision,
+} from 'mozart-router';
+
+export class MyGatewayAdapter implements GatewayAdapter {
+  id = 'mygateway';
+  name = 'MyGateway';
+
+  async detect(): Promise<DetectionResult> {
+    // 1. Check if MyGateway is installed/configured
+    // 2. NEVER read raw API keys
+    // 3. Use apiKeyRef or apiKeyManagedBy for key tracking
+    // 4. Return detailed detection info
+    return {
+      detected: true,
+      gatewayId: this.id,
+      gatewayName: this.name,
+      status: 'active',
+      providersCount: 1,
+      modelsCount: 3,
+      details: ['MyGateway detected at ...'],
+    };
+  }
+
+  async listProviders(): Promise<Provider[]> {
+    return [
+      {
+        id: 'mygateway',
+        name: 'MyGateway',
+        source: 'detected',
+        gateway: this.id,
+        privacyLevel: 'cloud',
+        status: 'available',
+        lastCheckedAt: new Date().toISOString(),
+      },
+    ];
+  }
+
+  async listModels(): Promise<Model[]> {
+    return [
+      {
+        id: 'my-model',
+        providerId: 'mygateway',
+        gatewayId: this.id,
+        displayName: 'My Model',
+        modality: ['text'],
+        contextWindow: 8192,
+        latencyClass: 'medium',
+        qualityClass: 'medium',
+        strengths: [],
+        weaknesses: [],
+        privacyLevel: 'cloud',
+        availability: 'available',
+        sourceConfidence: 'high',
+        lastCheckedAt: new Date().toISOString(),
+      },
+    ];
+  }
+
+  async getExecutionTarget(decision: RouteDecision): Promise<ExecutionTarget> {
+    return {
+      adapter: this.id,
+      provider: decision.selectedProvider,
+      model: decision.selectedModel,
+      method: 'gateway_call',
+      apiKeyManagedBy: 'gateway',
+    };
+  }
+}
+```
+
+## src/index.ts
+
+```typescript
+import { MozartPlugin } from 'mozart-router';
+import { MyGatewayAdapter } from './adapter';
+
+export const mozartPlugin: MozartPlugin = {
+  name: 'mozart-router-adapter-mygateway',
+  version: '1.0.0',
+  adapters: [new MyGatewayAdapter()],
+  async onRegister() {
+    console.log('MyGateway adapter registered');
+  },
+};
+```
+
+## Rules for adapters
+
+1. **Never store raw API keys.** Use `apiKeyRef` or `apiKeyManagedBy`.
+2. **Never log secrets.** If you must reference keys, redact them.
+3. **Detect don't configure.** Auto-detect the gateway, don't require manual setup.
+4. **Delegate execution.** Let the gateway execute, Mozart decides.
+5. **Graceful degradation.** If the gateway isn't available, return clean detection result.
+6. **Test with mocks.** Provide at least unit tests with mocked gateway responses.
+
+## Publishing
+
+```bash
+npm login
+npm publish --access public
+```
+
+Once published, Mozart's plugin system auto-discovers your adapter when the user runs `mozart doctor`.
+
+## Support
+
+- GitHub: https://github.com/ucav/mozart-router
+- Issues: https://github.com/ucav/mozart-router/issues

package/examples/generic-tools/README.md

@@ -0,0 +1,29 @@
+# Generic Tools — Mozart
+
+This directory contains a generic tool collection manifest for Mozart.
+
+## Files
+
+- `mozart-tools.json` — All 7 Mozart skills as generic tool definitions
+
+## Usage
+
+Use this manifest to integrate Mozart as a tool collection in any agent framework that supports JSON tool definitions:
+
+```json
+{
+  "tools": ["path/to/examples/generic-tools/mozart-tools.json"]
+}
+```
+
+The manifest is framework-agnostic and follows the standard tool definition format used by most AI agent frameworks.
+
+## SKills included
+
+1. `mozart.route_model` — Choose best model/provider for a task
+2. `mozart.explain_route` — Explain routing decisions
+3. `mozart.estimate_cost` — Estimate cost before execution
+4. `mozart.compress_context` — Optimize context for tokens
+5. `mozart.privacy_check` — Scan for secrets before sending
+6. `mozart.fallback_plan` — Generate fallback execution plans
+7. `mozart.inventory` — List detected gateways, providers, models

package/examples/generic-tools/mozart-tools.json

@@ -0,0 +1,86 @@
+{
+  "name": "mozart-router",
+  "version": "0.1.0",
+  "type": "tool-collection",
+  "description": "Mozart tool collection for AI agents — route models, estimate costs, check privacy, compress context",
+  "tools": [
+    {
+      "name": "mozart.route_model",
+      "description": "Choose the best available model/provider/gateway for an AI task based on cost, context, latency, privacy, and capabilities.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "task": { "type": "string", "description": "The task to route" },
+          "privacy_mode": { "type": "string", "enum": ["open", "balanced", "privacy_first", "local_only"] },
+          "budget_mode": { "type": "string", "enum": ["lowest", "balanced", "quality"] }
+        },
+        "required": ["task"]
+      }
+    },
+    {
+      "name": "mozart.explain_route",
+      "description": "Explain why Mozart chose a specific model/provider for the last routing decision."
+    },
+    {
+      "name": "mozart.estimate_cost",
+      "description": "Estimate the token usage and cost for a given task before execution.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "task": { "type": "string", "description": "Task description" },
+          "context": { "type": "string", "description": "Context to include" },
+          "model": { "type": "string", "description": "Target model (optional)" }
+        },
+        "required": ["task"]
+      }
+    },
+    {
+      "name": "mozart.compress_context",
+      "description": "Optimize and compress context to reduce token usage while preserving relevant information.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "content": { "type": "string", "description": "Content to compress" },
+          "max_tokens": { "type": "number", "description": "Maximum tokens allowed" },
+          "strategy": { "type": "string", "enum": ["compress", "truncate", "summarize", "select_relevant"] }
+        },
+        "required": ["content"]
+      }
+    },
+    {
+      "name": "mozart.privacy_check",
+      "description": "Scan content for secrets, API keys, tokens, and sensitive data before sending to a model.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "content": { "type": "string", "description": "Content to scan" },
+          "privacy_mode": { "type": "string", "enum": ["open", "balanced", "privacy_first", "local_only"] }
+        },
+        "required": ["content"]
+      }
+    },
+    {
+      "name": "mozart.fallback_plan",
+      "description": "Generate a fallback execution plan in case the primary model/provider fails.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "task": { "type": "string", "description": "Task description" },
+          "primary_model": { "type": "string", "description": "Primary model ID" }
+        },
+        "required": ["task"]
+      }
+    },
+    {
+      "name": "mozart.inventory",
+      "description": "Return the current inventory of detected gateways, providers, and models available to Mozart."
+    }
+  ],
+  "integration": {
+    "package": "mozart-router",
+    "install": "npm install mozart-router",
+    "import": "import { Mozart } from 'mozart-router'",
+    "init": "const mozart = new Mozart()",
+    "usage": "const route = await mozart.recommend(task)"
+  }
+}

package/examples/hermes/README.md

@@ -0,0 +1,29 @@
+# Hermes Agent + Mozart
+
+This directory contains the Mozart tool manifest for Hermes Agent.
+
+## Files
+
+- `mozart-tool.json` — Tool definition for Hermes Agent
+
+## Integration
+
+1. Install Mozart:
+```bash
+npm install mozart-router
+```
+
+2. Add the tool definition to your Hermes agent configuration
+
+3. Call Mozart tools from your Hermes workflows:
+```typescript
+import { Mozart } from 'mozart-router';
+const mozart = new Mozart();
+const recommendation = await mozart.recommend(task);
+```
+
+## Status
+
+Hermes Agent integration is currently a stub adapter with a full tool manifest. The adapter interface is complete and ready for integration, but real detection requires the Hermes Agent runtime environment.
+
+This integration is community-maintained and is not officially affiliated with Hermes Agent.

package/examples/hermes/mozart-tool.json

@@ -0,0 +1,48 @@
+{
+  "name": "mozart.route_model",
+  "description": "Choose the best available model/provider/gateway for a task",
+  "version": "0.1.0",
+  "type": "tool",
+  "source": {
+    "package": "mozart-router",
+    "method": "sdk"
+  },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "task": {
+        "type": "string",
+        "description": "The task to route"
+      },
+      "privacy_mode": {
+        "type": "string",
+        "description": "Privacy level",
+        "enum": ["open", "balanced", "privacy_first", "local_only"]
+      },
+      "budget_mode": {
+        "type": "string",
+        "description": "Budget preference",
+        "enum": ["lowest", "balanced", "quality"]
+      }
+    },
+    "required": ["task"]
+  },
+  "returns": {
+    "type": "object",
+    "properties": {
+      "selected_gateway": { "type": "string" },
+      "selected_provider": { "type": "string" },
+      "selected_model": { "type": "string" },
+      "confidence": { "type": "number" },
+      "estimated_cost": { "type": "number" },
+      "fallback_chain": { "type": "array" },
+      "explanation": { "type": "array" }
+    }
+  },
+  "usage": {
+    "install": "npm install mozart-router",
+    "import": "import { Mozart } from 'mozart-router'",
+    "init": "const mozart = new Mozart()",
+    "call": "const result = await mozart.route(task)"
+  }
+}

package/examples/litellm/README.md

@@ -0,0 +1,21 @@
+# LiteLLM + Mozart
+
+This directory contains an example LiteLLM configuration.
+
+## Files
+
+- `config.yaml` — Example LiteLLM config with Mozart integration notes
+
+## Integration
+
+Mozart detects LiteLLM automatically by scanning for `litellm_config.yaml` in common locations. When a config is found, Mozart reads the model entries and builds an inventory — **without accessing your raw API keys**.
+
+1. Your existing `litellm_config.yaml` is all Mozart needs
+2. Run `mozart doctor` to confirm detection
+3. Mozart routes tasks to the best model in your LiteLLM config
+
+## Status
+
+LiteLLM integration is **real** — config detection, model extraction, and inventory building work. Execution is delegated to the LiteLLM proxy.
+
+This integration is community-maintained. LiteLLM is its own project (https://github.com/BerriAI/litellm).

package/examples/litellm/config.yaml

@@ -0,0 +1,39 @@
+# LiteLLM + Mozart integration
+
+# Mozart detects this config automatically via LiteLLMAdapter.
+# No changes needed to this file — Mozart reads it as-is.
+
+model_list:
+  - model_name: gpt-4o
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: ${OPENAI_API_KEY}
+
+  - model_name: claude-sonnet
+    litellm_params:
+      model: anthropic/claude-sonnet-4-20250514
+      api_key: ${ANTHROPIC_API_KEY}
+
+  - model_name: deepseek-chat
+    litellm_params:
+      model: deepseek/deepseek-chat
+      api_key: ${DEEPSEEK_API_KEY}
+
+  - model_name: qwen-local
+    litellm_params:
+      model: ollama/qwen2.5:7b
+      api_base: http://localhost:11434
+
+litellm_settings:
+  drop_params: true
+  set_verbose: false
+
+general_settings:
+  master_key: ${LITELLM_MASTER_KEY}
+
+# How Mozart works with LiteLLM:
+# 1. Detects this config file automatically
+# 2. Reads model entries without accessing raw API keys
+# 3. Builds inventory from existing configuration
+# 4. Routes tasks to the best model via LiteLLM proxy
+# 5. Never stores or manages your API keys

package/examples/ollama/README.md

@@ -0,0 +1,37 @@
+# Ollama + Mozart
+
+This directory contains an example of using Mozart with Ollama for local model routing.
+
+## Files
+
+- `usage.ts` — Full example code
+
+## Integration
+
+Mozart detects Ollama automatically via the `ollama` CLI. All locally pulled models are added to Mozart's inventory.
+
+1. Install Ollama: https://ollama.com
+2. Pull models: `ollama pull llama3.2`, `ollama pull qwen2.5`
+3. Mozart detects them automatically: `mozart doctor`
+4. Tasks are routed to local models when appropriate (free, private)
+
+## Example
+
+```typescript
+import { Mozart, OllamaAdapter } from 'mozart-router';
+
+const mozart = new Mozart();
+mozart.registry.registerAdapter(new OllamaAdapter());
+await mozart.detectAll();
+
+// Simple tasks → local model
+const route = await mozart.recommend('hello');
+console.log(route.selectedModel); // e.g. "llama3.2"
+console.log(route.estimatedCost); // 0 (free)
+```
+
+## Status
+
+Ollama integration is **real** — CLI detection, model listing, and direct HTTP execution all work.
+
+This integration is community-maintained. Ollama is its own project (https://ollama.com).

package/examples/ollama/usage.ts

@@ -0,0 +1,59 @@
+// Example: Using Mozart with Ollama for local model routing
+//
+// This example demonstrates:
+// 1. Creating a Mozart instance
+// 2. Registering the Ollama adapter
+// 3. Building an inventory from local models
+// 4. Routing tasks to local vs cloud models
+
+import { Mozart, OllamaAdapter, OpenRouterAdapter } from 'mozart-router';
+
+async function main() {
+  const mozart = new Mozart();
+
+  // Register adapters - Mozart detects available gateways
+  mozart.registry.registerAdapter(new OllamaAdapter());
+  mozart.registry.registerAdapter(new OpenRouterAdapter());
+
+  // Detect all gateways and build inventory
+  for (const adapter of mozart.registry.listAdapters()) {
+    const detection = await adapter.detect();
+    mozart.registry.recordDetection(detection);
+
+    if (detection.detected) {
+      console.log(`Found: ${adapter.name} (${detection.status})`);
+      const providers = await adapter.listProviders();
+      const models = await adapter.listModels();
+      mozart.registry.mergeFromAdapter(adapter.id, providers, models);
+      console.log(`  ${models.length} models available`);
+    }
+  }
+
+  // Show inventory
+  const snapshot = mozart.getInventory();
+  console.log(`\nTotal: ${snapshot.models.length} models`);
+
+  // Route a simple task - Mozart will prefer local models
+  const simpleRoute = await mozart.recommend('hello, how are you?');
+  console.log(`\nSimple task → ${simpleRoute.selectedModel} ($${simpleRoute.estimatedCost})`);
+
+  // Route a coding task - Mozart will select best coding model
+  const codeRoute = await mozart.recommend('write a function to sort an array');
+  console.log(`Code task → ${codeRoute.selectedModel} ($${codeRoute.estimatedCost})`);
+
+  // Full process with privacy and cost analysis
+  const response = await mozart.process({
+    input: 'debug the authentication flow',
+    budgetMode: 'balanced',
+    privacyMode: 'balanced',
+    executionMode: 'recommend',
+  });
+
+  console.log(`\nFull response:`);
+  console.log(`  Selected: ${response.route.selectedModel}`);
+  console.log(`  Cost: $${response.cost.totalCost.toFixed(4)}`);
+  console.log(`  Privacy: ${response.privacy.action}`);
+  console.log(`  ${response.explanation.length} explanation lines`);
+}
+
+main().catch(console.error);

package/examples/openclaw/README.md

@@ -0,0 +1,26 @@
+# OpenClaw + Mozart
+
+This directory contains the Mozart skill manifest for OpenClaw.
+
+## Files
+
+- `mozart-skill.yaml` — Skill definitions for OpenClaw
+
+## Integration
+
+Mozart detects OpenClaw automatically by reading `~/.openclaw/openclaw.json`. All configured providers and models are imported into Mozart's inventory.
+
+1. Install Mozart:
+```bash
+npm install mozart-router
+```
+
+2. The skill manifest can be added to your OpenClaw configuration
+
+3. Mozart reads your existing providers/models without accessing your API keys
+
+## Status
+
+OpenClaw integration is **real**. Mozart reads the OpenClaw config file, extracts all providers and models, and routes tasks using your existing OpenClaw infrastructure. The adapter never reads or stores raw API keys.
+
+This integration is community-maintained.

package/examples/openclaw/mozart-skill.yaml

@@ -0,0 +1,80 @@
+# Mozart skills for OpenClaw
+
+skills:
+  - name: mozart.route_model
+    description: Choose the best available model/provider/gateway for a task
+    input:
+      task:
+        type: string
+        description: The task to route
+        required: true
+      privacy_mode:
+        type: string
+        description: Privacy level (open, balanced, privacy_first, local_only)
+        default: balanced
+      budget_mode:
+        type: string
+        description: Budget preference (lowest, balanced, quality)
+        default: balanced
+    output:
+      selected_gateway: string
+      selected_provider: string
+      selected_model: string
+      confidence: number
+      estimated_cost: number
+      fallback_chain: array
+      explanation: array
+
+  - name: mozart.estimate_cost
+    description: Estimate cost and tokens for a task before execution
+    input:
+      task:
+        type: string
+        description: Task description
+        required: true
+      context:
+        type: string
+        description: Context to include
+    output:
+      estimated_input_tokens: number
+      estimated_output_tokens: number
+      estimated_cost: number
+      currency: string
+
+  - name: mozart.compress_context
+    description: Optimize context to reduce token usage
+    input:
+      content:
+        type: string
+        description: Content to compress
+        required: true
+      max_tokens:
+        type: number
+        description: Maximum tokens
+    output:
+      strategy: string
+      original_tokens: number
+      compressed_tokens: number
+      compression_ratio: number
+
+  - name: mozart.privacy_check
+    description: Scan content for secrets before sending to models
+    input:
+      content:
+        type: string
+        description: Content to scan
+        required: true
+    output:
+      allowed: boolean
+      findings: array
+      action: string
+      redacted_content: string
+
+  - name: mozart.inventory
+    description: Return current inventory of detected gateways, providers, and models
+
+# Integration instructions
+# 1. Install: npm install mozart-router
+# 2. Import in OpenClaw: import { Mozart } from 'mozart-router'
+# 3. Initialize: const mozart = new Mozart()
+# 4. Call skills: const route = await mozart.recommend(task)

package/examples/opencode/README.md

@@ -0,0 +1,30 @@
+# OpenCode + Mozart
+
+This directory contains the Mozart skill manifest for OpenCode.
+
+## Files
+
+- `mozart-skill.json` — Skill definition for OpenCode
+
+## Integration
+
+1. Install Mozart:
+```bash
+npm install mozart-router
+```
+
+2. Copy the skill manifest to your OpenCode skills directory
+
+3. Import and use in your agent code:
+```typescript
+import { Mozart } from 'mozart-router';
+
+const mozart = new Mozart();
+const route = await mozart.recommend('refactor the auth module');
+```
+
+## Status
+
+OpenCode integration is a real detection adapter. Mozart detects OpenCode installation via environment variables and data directory. For full model routing, use Mozart alongside your existing OpenCode provider configuration.
+
+This integration is community-maintained and is not officially affiliated with OpenCode.