From 97152999f5604ca2ac0923d9efe328b53d68d8ab Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:50:49 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 68 +++++ skills/openrouter/SKILL.md | 319 +++++++++++++++++++++ skills/openrouter/plugin.json | 15 + skills/openrouter/references/index.md | 7 + skills/openrouter/references/llms-full.md | 128 +++++++++ skills/openrouter/references/llms-small.md | 128 +++++++++ skills/openrouter/references/llms.md | 128 +++++++++ skills/openrouter/references/other.md | 139 +++++++++ 10 files changed, 947 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/openrouter/SKILL.md create mode 100644 skills/openrouter/plugin.json create mode 100644 skills/openrouter/references/index.md create mode 100644 skills/openrouter/references/llms-full.md create mode 100644 skills/openrouter/references/llms-small.md create mode 100644 skills/openrouter/references/llms.md create mode 100644 skills/openrouter/references/other.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e690c9d --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "openrouter", + "description": "Interacts with the OpenRouter API.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Tim Green", + "email": "rawveg@gmail.com" + }, + "skills": [ + "./skills/openrouter" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1de0646 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# openrouter + +Interacts with the OpenRouter API. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..15184cc --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,68 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:rawveg/skillsforge-marketplace:openrouter", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "f31a8430d5c318acd4b941862950c482b255cbb7", + "treeHash": "2d1cc3b7b49879a37a731f8b2377f2b31a7955cd8ff56e80448c93946f9396e9", + "generatedAt": "2025-11-28T10:27:53.209007Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "openrouter", + "description": "Interacts with the OpenRouter API." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "b6ce80464596cfb6e197d40e8191e4d41f3319c28aa9fa35549f3bed2588bb28" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "f17d525ad6671a0e8d36e507983f16170b883c848dc06ce8acc4b315b3521d83" + }, + { + "path": "skills/openrouter/plugin.json", + "sha256": "e49184770612aef75a4b0f689d52585559e2d0515149f3d1894a324859c39b1b" + }, + { + "path": "skills/openrouter/SKILL.md", + "sha256": "996328dc5f2be4b25a043b3450a1e90da907daa93f4c077d20c7e9ea4e31c0f9" + }, + { + "path": "skills/openrouter/references/llms.md", + "sha256": "3d6f888ebb4aaa73f01e3a4bbccef9bcc71e26271cef26b43789003d4241c710" + }, + { + "path": "skills/openrouter/references/llms-small.md", + "sha256": "f41935669672b6267b7fb8c6e7150b0a8ffdf86c00587aac2c3f20dcb8c77598" + }, + { + "path": "skills/openrouter/references/index.md", + "sha256": "cb07ca5df6e7d4c6d9ff8d577cb4f8105c83b62d7bc84dbd619e849d3f894af8" + }, + { + "path": "skills/openrouter/references/llms-full.md", + "sha256": "b74af151ec94d945a2aa0e517687622769ac5a0f1dac58cc8dba6b3ba83eeed7" + }, + { + "path": "skills/openrouter/references/other.md", + "sha256": "b8aad963e7319c0be05ff99815761fffd8199e8fa5c850f6b69a4ac29b221e8a" + } + ], + "dirSha256": "2d1cc3b7b49879a37a731f8b2377f2b31a7955cd8ff56e80448c93946f9396e9" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/openrouter/SKILL.md b/skills/openrouter/SKILL.md new file mode 100644 index 0000000..95c32b1 --- /dev/null +++ b/skills/openrouter/SKILL.md @@ -0,0 +1,319 @@ +--- +name: openrouter +description: OpenRouter API - Unified access to 400+ AI models through one API +--- + +# OpenRouter Skill + +Comprehensive assistance with OpenRouter API development, providing unified access to hundreds of AI models through a single endpoint with intelligent routing, automatic fallbacks, and standardized interfaces. + +## When to Use This Skill + +This skill should be triggered when: +- Making API calls to multiple AI model providers through a unified interface +- Implementing model fallback strategies or auto-routing +- Working with OpenAI-compatible SDKs but targeting multiple providers +- Configuring advanced sampling parameters (temperature, top_p, penalties) +- Setting up streaming responses or structured JSON outputs +- Comparing costs across different AI models +- Building applications that need automatic provider failover +- Implementing function/tool calling across different models +- Questions about OpenRouter-specific features (routing, fallbacks, zero completion insurance) + +## Quick Reference + +### Basic Chat Completion (Python) +```python +from openai import OpenAI + +client = OpenAI( + base_url="https://openrouter.ai/api/v1", + api_key="", +) + +completion = client.chat.completions.create( + model="openai/gpt-4o", + messages=[{"role": "user", "content": "What is the meaning of life?"}] +) +print(completion.choices[0].message.content) +``` + +### Basic Chat Completion (JavaScript/TypeScript) +```typescript +import OpenAI from 'openai'; + +const openai = new OpenAI({ + baseURL: 'https://openrouter.ai/api/v1', + apiKey: '', +}); + +const completion = await openai.chat.completions.create({ + model: 'openai/gpt-4o', + messages: [{"role": 'user', "content": 'What is the meaning of life?'}], +}); +console.log(completion.choices[0].message); +``` + +### cURL Request +```bash +curl https://openrouter.ai/api/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENROUTER_API_KEY" \ + -d '{ + "model": "openai/gpt-4o", + "messages": [{"role": "user", "content": "What is the meaning of life?"}] + }' +``` + +### Model Fallback Configuration (Python) +```python +completion = client.chat.completions.create( + model="openai/gpt-4o", + extra_body={ + "models": ["anthropic/claude-3.5-sonnet", "gryphe/mythomax-l2-13b"], + }, + messages=[{"role": "user", "content": "Your prompt here"}] +) +``` + +### Model Fallback Configuration (TypeScript) +```typescript +const completion = await client.chat.completions.create({ + model: 'openai/gpt-4o', + models: ['anthropic/claude-3.5-sonnet', 'gryphe/mythomax-l2-13b'], + messages: [{ role: 'user', content: 'Your prompt here' }], +}); +``` + +### Auto Router (Dynamic Model Selection) +```python +completion = client.chat.completions.create( + model="openrouter/auto", # Automatically selects best model for the prompt + messages=[{"role": "user", "content": "Your prompt here"}] +) +``` + +### Advanced Parameters Example +```python +completion = client.chat.completions.create( + model="openai/gpt-4o", + messages=[{"role": "user", "content": "Write a creative story"}], + temperature=0.8, # Higher for creativity (0.0-2.0) + max_tokens=500, # Limit response length + top_p=0.9, # Nucleus sampling (0.0-1.0) + frequency_penalty=0.5, # Reduce repetition (-2.0-2.0) + presence_penalty=0.3 # Encourage topic diversity (-2.0-2.0) +) +``` + +### Streaming Response +```python +stream = client.chat.completions.create( + model="openai/gpt-4o", + messages=[{"role": "user", "content": "Tell me a story"}], + stream=True +) + +for chunk in stream: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end='') +``` + +### JSON Mode (Structured Output) +```python +completion = client.chat.completions.create( + model="openai/gpt-4o", + messages=[{ + "role": "user", + "content": "Extract person's name, age, and city from: John is 30 and lives in NYC" + }], + response_format={"type": "json_object"} +) +``` + +### Deterministic Output with Seed +```python +completion = client.chat.completions.create( + model="openai/gpt-4o", + messages=[{"role": "user", "content": "Generate a random number"}], + seed=42, # Same seed = same output (when supported) + temperature=0.0 # Deterministic sampling +) +``` + +## Key Concepts + +### Model Routing +OpenRouter provides intelligent routing capabilities: +- **Auto Router** (`openrouter/auto`): Automatically selects the best model based on your prompt using NotDiamond +- **Fallback Models**: Specify multiple models that automatically retry if primary fails +- **Provider Routing**: Automatically routes across providers for reliability + +### Authentication +- Uses Bearer token authentication with API keys +- API keys can be managed programmatically +- Compatible with OpenAI SDK authentication patterns + +### Model Naming Convention +Models use the format `provider/model-name`: +- `openai/gpt-4o` - OpenAI's GPT-4 Optimized +- `anthropic/claude-3.5-sonnet` - Anthropic's Claude 3.5 Sonnet +- `google/gemini-2.0-flash-exp:free` - Google's free Gemini model +- `openrouter/auto` - Auto-routing system + +### Sampling Parameters + +**Temperature** (0.0-2.0, default: 1.0) +- Lower = more predictable, focused responses +- Higher = more creative, diverse responses +- Use low (0.0-0.3) for factual tasks, high (0.8-1.5) for creative work + +**Top P** (0.0-1.0, default: 1.0) +- Limits choices to percentage of likely tokens +- Dynamic filtering of improbable options +- Balance between consistency and variety + +**Frequency/Presence Penalties** (-2.0-2.0, default: 0.0) +- Frequency: Discourages repeating tokens proportional to use +- Presence: Simpler penalty not scaled by count +- Positive values reduce repetition, negative encourage reuse + +**Max Tokens** (integer) +- Sets maximum response length +- Cannot exceed context length minus prompt length +- Use to control costs and enforce concise replies + +### Response Formats +- **Standard JSON**: Default chat completion format +- **Streaming**: Server-Sent Events (SSE) with `stream: true` +- **JSON Mode**: Guaranteed valid JSON with `response_format: {"type": "json_object"}` +- **Structured Outputs**: Schema-validated JSON responses + +### Advanced Features +- **Tool/Function Calling**: Connect models to external APIs +- **Multimodal Inputs**: Support for images, PDFs, audio +- **Prompt Caching**: Reduce costs for repeated prompts +- **Web Search Integration**: Enhanced responses with web data +- **Zero Completion Insurance**: Protection against failed responses +- **Logprobs**: Access token probabilities for confidence analysis + +## Reference Files + +This skill includes comprehensive documentation in `references/`: + +- **llms-full.md** - Complete list of available models with metadata +- **llms-small.md** - Curated subset of popular models +- **llms.md** - Standard model listings + +Use `view` to read specific reference files when detailed model information is needed. + +## Working with This Skill + +### For Beginners +1. Start with basic chat completion examples (Python/JavaScript/cURL above) +2. Use the standard OpenAI SDK for easy integration +3. Try simple model names like `openai/gpt-4o` or `anthropic/claude-3.5-sonnet` +4. Keep parameters simple initially (just model and messages) + +### For Intermediate Users +1. Implement model fallback arrays for reliability +2. Experiment with sampling parameters (temperature, top_p) +3. Use streaming for better UX in conversational apps +4. Try `openrouter/auto` for automatic model selection +5. Implement JSON mode for structured data extraction + +### For Advanced Users +1. Fine-tune multiple sampling parameters together +2. Implement custom routing logic with fallback chains +3. Use logprobs for confidence scoring +4. Leverage tool/function calling capabilities +5. Optimize costs by selecting appropriate models per task +6. Implement prompt caching strategies +7. Use seed parameter for reproducible testing + +## Common Patterns + +### Error Handling with Fallbacks +```python +try: + completion = client.chat.completions.create( + model="openai/gpt-4o", + extra_body={ + "models": [ + "anthropic/claude-3.5-sonnet", + "google/gemini-2.0-flash-exp:free" + ] + }, + messages=[{"role": "user", "content": "Your prompt"}] + ) +except Exception as e: + print(f"All models failed: {e}") +``` + +### Cost-Optimized Routing +```python +# Use cheaper models for simple tasks +simple_completion = client.chat.completions.create( + model="google/gemini-2.0-flash-exp:free", + messages=[{"role": "user", "content": "Simple question"}] +) + +# Use premium models for complex tasks +complex_completion = client.chat.completions.create( + model="openai/o1", + messages=[{"role": "user", "content": "Complex reasoning task"}] +) +``` + +### Context-Aware Temperature +```python +# Low temperature for factual responses +factual = client.chat.completions.create( + model="openai/gpt-4o", + temperature=0.2, + messages=[{"role": "user", "content": "What is the capital of France?"}] +) + +# High temperature for creative content +creative = client.chat.completions.create( + model="openai/gpt-4o", + temperature=1.2, + messages=[{"role": "user", "content": "Write a unique story opening"}] +) +``` + +## Resources + +### Official Documentation +- API Reference: https://openrouter.ai/docs/api-reference/overview +- Quickstart Guide: https://openrouter.ai/docs/quickstart +- Model List: https://openrouter.ai/docs/models +- Parameters Guide: https://openrouter.ai/docs/api-reference/parameters + +### Key Endpoints +- Chat Completions: `POST https://openrouter.ai/api/v1/chat/completions` +- List Models: `GET https://openrouter.ai/api/v1/models` +- Generation Info: `GET https://openrouter.ai/api/v1/generation` + +## Notes + +- OpenRouter normalizes API schemas across all providers +- Uses OpenAI-compatible API format for easy migration +- Automatic provider fallback if models are rate-limited or down +- Pricing based on actual model used (important for fallbacks) +- Response includes metadata about which model processed the request +- All models support streaming via Server-Sent Events +- Compatible with popular frameworks (LangChain, Vercel AI SDK, etc.) + +## Best Practices + +1. **Always implement fallbacks** for production applications +2. **Use appropriate temperature** based on task type (low for factual, high for creative) +3. **Set max_tokens** to control costs and response length +4. **Enable streaming** for better user experience in chat applications +5. **Use JSON mode** when you need guaranteed structured output +6. **Test with seed parameter** for reproducible results during development +7. **Monitor costs** by selecting appropriate models per task +8. **Use auto-routing** when unsure which model performs best +9. **Implement proper error handling** for rate limits and failures +10. **Cache prompts** for repeated requests to reduce costs diff --git a/skills/openrouter/plugin.json b/skills/openrouter/plugin.json new file mode 100644 index 0000000..6ac36cc --- /dev/null +++ b/skills/openrouter/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "openrouter", + "description": "Interacts with the OpenRouter API.", + "version": "1.0.0", + "author": { + "name": "Tim Green", + "email": "rawveg@gmail.com" + }, + "homepage": "https://github.com/rawveg/claude-skills-marketplace", + "repository": "https://github.com/rawveg/claude-skills-marketplace", + "license": "MIT", + "keywords": ["openrouter", "Claude Code"], + "category": "productivity", + "strict": false +} diff --git a/skills/openrouter/references/index.md b/skills/openrouter/references/index.md new file mode 100644 index 0000000..ad0eb6f --- /dev/null +++ b/skills/openrouter/references/index.md @@ -0,0 +1,7 @@ +# Openrouter Documentation Index + +## Categories + +### Other +**File:** `other.md` +**Pages:** 1 diff --git a/skills/openrouter/references/llms-full.md b/skills/openrouter/references/llms-full.md new file mode 100644 index 0000000..8ab2454 --- /dev/null +++ b/skills/openrouter/references/llms-full.md @@ -0,0 +1,128 @@ +Author Not Found
    \ No newline at end of file diff --git a/skills/openrouter/references/llms-small.md b/skills/openrouter/references/llms-small.md new file mode 100644 index 0000000..5a0b19b --- /dev/null +++ b/skills/openrouter/references/llms-small.md @@ -0,0 +1,128 @@ +Author Not Found
      \ No newline at end of file diff --git a/skills/openrouter/references/llms.md b/skills/openrouter/references/llms.md new file mode 100644 index 0000000..9eeb7c2 --- /dev/null +++ b/skills/openrouter/references/llms.md @@ -0,0 +1,128 @@ +Author Not Found
        \ No newline at end of file diff --git a/skills/openrouter/references/other.md b/skills/openrouter/references/other.md new file mode 100644 index 0000000..1fbdc43 --- /dev/null +++ b/skills/openrouter/references/other.md @@ -0,0 +1,139 @@ +# Openrouter - Other + +**Pages:** 1 + +--- + +## Author Not Foundauthor-not-found
          + +---