chutes-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zenobi.us
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,387 @@
+# chutes-plugin
+
+Chutes Models Plugin for OpenCode - Access 58+ state-of-the-art AI models through the Chutes API.
+
+> An OpenCode plugin that integrates Chutes AI models with dynamic synchronization, conflict-free naming, and seamless OpenCode integration.
+
+## Features
+
+- **Dynamic Model Sync**: Automatically fetches latest models from `https://llm.chutes.ai/v1/models`
+- **58+ Models**: Access reasoning, coding, vision, and general-purpose models
+- **Conflict-Free Naming**: All models prefixed with `chutes/` to avoid conflicts
+- **Streaming Support**: Real-time response streaming for chat completions
+- **Intelligent Caching**: Model metadata cached for performance
+- **Comprehensive Tools**: `chutes_list_models`, `chutes_refresh_models`, `chutes_status`
+- **Slash Commands**: `/chutes-models` for easy access
+
+## Available Models
+
+The plugin provides access to models including:
+
+### Reasoning Models
+
+- `chutes/deepseek-ai/DeepSeek-R1` - Advanced reasoning model
+- `chutes/deepseek-ai/DeepSeek-R1-0528-TEE` - Confidential compute reasoning
+- `chutes/Qwen/Qwen3-235B-A22B-Thinking-2507` - Large-scale thinking model
+
+### Coding Models
+
+- `chutes/Qwen/Qwen2.5-Coder-32B-Instruct` - Specialized code generation
+- `chutes/mistralai/Devstral-2-123B-Instruct-2512` - Devstral coding model
+- `chutes/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8-TEE` - Large code model
+
+### Vision Models
+
+- `chutes/Qwen/Qwen3-VL-235B-A22B-Instruct` - Vision-language model
+- `chutes/unsloth/gemma-3-27b-it` - Multimodal Gemma
+- `chutes/OpenGVLab/InternVL3-78B-TEE` - InternVL vision model
+
+### General Purpose
+
+- `chutes/Qwen/Qwen3-32B` - Balanced general model
+- `chutes/deepseek-ai/DeepSeek-V3` - High-performance general model
+- `chutes/NousResearch/Hermes-4-405B-FP8-TEE` - Large general model
+
+## Getting Started
+
+### 1. Install the Plugin
+
+Create or edit `~/.config/opencode/config.json`:
+
+```json
+{
+  "plugins": ["chutes-plugin"]
+}
+```
+
+### 2. Connect Your API Token
+
+Use OpenCode's built-in `/connect` command to securely store your Chutes API token:
+
+```
+/connect chutes
+```
+
+Follow the prompts to enter your Chutes API token. The token will be securely stored in `~/.local/share/opencode/auth.json`.
+
+Alternatively, you can manually create the auth file:
+
+```json
+{
+  "chutes": {
+    "type": "api",
+    "key": "your-chutes-api-token-here"
+  }
+}
+```
+
+You can get your API token from [chutes.ai](https://chutes.ai).
+
+### 3. Restart OpenCode
+
+Restart OpenCode to load the plugin. Models will be automatically fetched on startup.
+
+## Configuration
+
+### API Token Storage
+
+The plugin reads your Chutes API token from OpenCode's secure auth storage:
+
+- **Primary**: Use `/connect chutes` command (recommended)
+- **Manual**: Create `~/.local/share/opencode/auth.json`:
+
+```json
+{
+  "chutes": {
+    "type": "api",
+    "key": "your-chutes-api-token-here"
+  }
+}
+```
+
+### Configuration Options
+
+```json
+{
+  "plugins": ["chutes-plugin"],
+  "chutes": {
+    "autoRefresh": true,
+    "refreshInterval": 3600,
+    "defaultModel": "chutes/Qwen/Qwen3-32B",
+    "modelFilter": ["Qwen/*", "DeepSeek/*"]
+  }
+}
+```
+
+| Option            | Type     | Default | Description                              |
+| ----------------- | -------- | ------- | ---------------------------------------- |
+| `autoRefresh`     | boolean  | `true`  | Auto-sync models on startup              |
+| `refreshInterval` | number   | `3600`  | Cache TTL in seconds (1 hour)            |
+| `defaultModel`    | string   | -       | Default model for chat                   |
+| `modelFilter`     | string[] | -       | Optional model whitelist (glob patterns) |
+
+## Usage
+
+### Using Tools
+
+#### List Available Models
+
+```typescript
+// List all models
+await chutes_list_models({});
+
+// Filter by provider
+await chutes_list_models({
+  owned_by: 'Qwen',
+});
+
+// Filter by feature
+await chutes_list_models({
+  feature: 'reasoning',
+});
+
+// Filter by name
+await chutes_list_models({
+  filter: 'DeepSeek',
+});
+```
+
+#### Refresh Model List
+
+```typescript
+// Refresh from API
+await chutes_refresh_models({});
+
+// Force refresh even if cache is valid
+await chutes_refresh_models({
+  force: true,
+});
+```
+
+#### Check Plugin Status
+
+```typescript
+// Check cache status and model count
+await chutes_status();
+```
+
+### Using Slash Commands
+
+#### `/chutes-models`
+
+Browse available Chutes models:
+
+```
+/chutes-models
+```
+
+### Programmatic Usage
+
+```typescript
+import { ChutesPlugin } from 'chutes-plugin';
+
+const plugin = await ChutesPlugin();
+
+// Access tools
+plugin.tool.chutes_list_models({...});
+plugin.tool.chutes_refresh_models({...});
+plugin.tool.chutes_status({...});
+
+// Configure
+await plugin.config({
+  chutes: {
+    apiToken: "your-token"
+  }
+});
+```
+
+## Model Pricing
+
+Models are priced per 1 million tokens. Example pricing:
+
+| Model                            | Input ($/1M) | Output ($/1M) |
+| -------------------------------- | ------------ | ------------- |
+| `chutes/Qwen/Qwen3-32B`          | $0.08        | $0.24         |
+| `chutes/deepseek-ai/DeepSeek-R1` | $0.30        | $1.20         |
+| `chutes/unsloth/gemma-3-4b-it`   | $0.01        | $0.03         |
+
+Full pricing is available in the model list.
+
+## Architecture
+
+```
+src/
+├── index.ts           # Main plugin entry point
+├── api/
+│   ├── chat.ts        # Chat completions client
+│   └── errors.ts      # Error classes
+├── models/
+│   ├── types.ts       # TypeScript types
+│   ├── fetcher.ts     # Model synchronization
+│   ├── cache.ts       # Model caching
+│   └── registry.ts    # Model naming registry
+├── tools/
+│   └── index.ts       # Plugin tools
+├── config/
+│   └── schema.ts      # Configuration validation
+└── commands/
+    └── chutes-models.md   # /chutes-models command
+```
+
+## Development
+
+### Build
+
+```bash
+mise run build
+# or
+bun build ./src/index.ts --outdir dist --target bun
+```
+
+### Test
+
+```bash
+mise run test
+# or
+bun test
+```
+
+### Lint
+
+```bash
+mise run lint
+# or
+bun run eslint src/
+```
+
+### Format
+
+```bash
+mise run format
+# or
+bun run prettier --write src/
+```
+
+## Publishing
+
+### Version Bump
+
+```bash
+# Bump version (patch, minor, or major)
+npm version patch     # 1.0.0 -> 1.0.1
+npm version minor     # 1.0.0 -> 1.1.0
+npm version major     # 1.0.0 -> 2.0.0
+```
+
+### Publish to npm
+
+```bash
+# Login to npm (first time only)
+npm login
+
+# Publish the package
+npm publish
+
+# Publish with access to public (for scoped packages)
+npm publish --access public
+```
+
+### Pre-release
+
+```bash
+# Create a beta release
+npm version prerelease --preid=beta
+npm publish --tag beta
+```
+
+## API Reference
+
+### ChutesClient
+
+```typescript
+import { ChutesClient } from './api/chat';
+
+const client = new ChutesClient({
+  apiBaseUrl: 'https://llm.chutes.ai/v1',
+  apiToken: 'your-token',
+});
+
+// Non-streaming completion
+const response = await client.createChatCompletion({
+  model: 'Qwen/Qwen3-32B',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+// Streaming completion
+for await (const chunk of client.createChatCompletionStream(request)) {
+  console.log(chunk.choices[0]?.delta?.content);
+}
+```
+
+### ModelFetcher
+
+```typescript
+import { ModelFetcher } from './models/fetcher';
+
+const fetcher = new ModelFetcher({
+  apiBaseUrl: 'https://llm.chutes.ai/v1',
+  cacheTtlSeconds: 3600,
+});
+
+fetcher.setApiToken('your-token');
+
+// Fetch models
+const models = await fetcher.fetchModels();
+
+// Get cached models
+const cached = fetcher.getCachedModels();
+
+// Force refresh
+await fetcher.refreshModels(true);
+```
+
+## Troubleshooting
+
+### "No API token configured"
+
+Ensure you've connected your Chutes API token using the `/connect chutes` command or created `~/.local/share/opencode/auth.json` with your token.
+
+### "Model not found"
+
+Use `chutes_list_models` to see available models. Model IDs must be prefixed with `chutes/`.
+
+### "Rate limit exceeded"
+
+Wait a moment and retry. Consider reducing request frequency.
+
+### Models not appearing
+
+1. Check your API token is valid
+2. Run `chutes_refresh_models({ force: true })`
+3. Check plugin status with `chutes_status`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Gianmarco Martinelli <mark182@gmail.com>
+
+## Repository
+
+https://github.com/zenobi-us/chutes-plugin
+
+## Chutes API
+
+- Models API: `https://llm.chutes.ai/v1/models`
+- Chat API: `https://llm.chutes.ai/v1/chat/completions`
+- Documentation: https://docs.chutes.ai