📋 Installation & Setup

1. Prerequisites

• LM Studio v0.2.28 or later
• Node.js 18+
• Google AI API keys from https://ai.google.dev

2. Get Your API Keys

• Visit Google AI Studio
• Create a new API key
• Copy the key (keep it secure!)
• Create multiple keys for backup/rotation

3. Install the Plugin

cd reasoning-agent
npm install
lms dev  # For development with hot reload
# OR
lms push  # To deploy to your LM Studio installation

4. Configure in LM Studio

• Open LM Studio Settings → Plugins → Reasoning Agent
• In the API Keys field, paste your keys (comma-separated):

  key1,key2,key3
  

• Set your preferred model (default: gemini-3-flash-preview)
• Adjust other parameters as needed
• Save and reload plugin

🛠️ Configuration Options

📖 Usage Examples

Basic Reasoning Task

User: "Use the reasoning tool to analyze the implications of quantum computing on cybersecurity"
LM Studio: Calls reasoning_invoke with the prompt
Plugin: 
  1. Sends to Gemini API (key 1)
  2. Gets response back
  3. Formats as Markdown
AI: Returns formatted reasoning to user

With Key Rotation

User: Asks AI a complex question
AI: Calls reasoning_invoke → Plugin tries key 1
Key 1: Gets 429 quota error
Plugin: Automatically rotates to key 2
Key 2: Successfully returns response
AI: Uses the reasoning in its answer

Override Defaults

reasoning_invoke(
  prompt="Analyze this...",
  useThinking=true,
  temperature=0.3,
  maxTokens=4096
)

🔄 How Key Rotation Works

┌─────────────────────────────────┐
│ AI Calls reasoning_invoke       │
└────────────┬────────────────────┘
             ▼
      ┌─────────────────┐
      │ Key 1: Attempt  │
      │ Retries: 1-3    │
      └────────┬────────┘
               │
        ┌──────▼──────┐
        │ Success? ✓  │ YES ──→ Return Response
        │ Quota? ✗    │
        │ Auth? ✗     │
        └──────┬──────┘ NO
               ▼
      ┌─────────────────┐
      │ Key 2: Attempt  │
      │ Retries: 1-3    │
      └────────┬────────┘
               │
        ┌──────▼──────┐
        │ Success? ✓  │ YES ──→ Return Response
        └──────┬──────┘ NO
               ▼
      ┌─────────────────┐
      │ Key 3: Attempt  │
      │ Retries: 1-3    │
      └────────┬────────┘
               │
        ┌──────▼──────┐
        │ Success? ✓  │ YES ──→ Return Response
        └──────┬──────┘ NO
               ▼
      Return Error Message
      (All keys exhausted)

🔍 Error Handling Strategy

The plugin distinguishes between three error categories:

📊 Logging & Debugging

Enable Detailed Logging in config to see:

[ReasoningAgent] Attempting request with key 1/3 (abc123***)
[ReasoningAgent] Using model: gemini-3-flash-preview, temperature: 0.7, maxTokens: 2048
[ReasoningAgent] Attempt 1/3 passed: 429 quota error (Will rotate key)
[ReasoningAgent] Attempting request with key 2/3 (def456***)
[ReasoningAgent] Successfully generated response (1245 chars)

Check LM Studio's console/logs for these messages while running in dev mode.

🧪 Testing Checklist

Before deploying to production, verify:

• All API keys are valid and have quota remaining
• Keys are comma-separated without extra spaces
• Model name matches available Gemini models
• Temperature is between 0 and 2
• Max tokens is between 100 and 10,000
• Request timeout is >1000ms
• Retry attempts is 1-10
• Test with a simple prompt first
• Verify key rotation by exhausting first key's quota
• Check error messages when all keys fail
• Test with extended thinking enabled/disabled
• Monitor response times and token usage

🐛 Troubleshooting

"No API keys configured"

• Check plugin settings in LM Studio
• Ensure API keys field is not empty
• Keys must be comma-separated

"Invalid API Key"

• Verify key is copied correctly (no extra spaces)
• Check key hasn't been revoked in AI Studio
• Ensure using correct Google AI API key (not ChatGPT key)

Slow Responses

• Check network connection
• Increase request timeout in config
• Test with smaller prompts first
• Extended thinking is slower but better for complex tasks

All Keys Exhausted

• Check with curl -X POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=YOUR_KEY
• Review quota in Google AI Studio
• Create new API keys and add to config
• Check logs with detailed logging enabled

Plugin Not Loading

• Run npm install in plugin directory
• Verify TypeScript compiles: npm run build
• Check console output in LM Studio for errors
• Restart LM Studio after changes

📦 Project Structure

reasoning-agent/
├── manifest.json          # Plugin metadata
├── package.json           # Dependencies & scripts
├── tsconfig.json          # TypeScript compiler config
├── .gitignore             # Git ignore patterns
├── README.md              # This file
└── src/
    ├── index.ts           # Entry point (registers config + tools)
    ├── config.ts          # Configuration schema for LM Studio UI
    └── toolsProvider.ts   # Core implementation (API calls + key rotation)

🔐 Security Notes

• Never commit API keys to version control
• Use .gitignore to exclude .env files
• Rotate keys regularly in Google AI Studio
• Monitor usage in Google Cloud Console
• Never share keys via chat or email
• Use separate keys for development/production if possible

🚀 Development

Build

npm run build

Development Mode (Hot Reload)

lms dev

Deploy to LM Studio

lms push

📝 API Reference

Tool: reasoning_invoke

Parameters:

{
  prompt: string                   // Required: The prompt for Gemini
  systemPrompt?: string           // Optional: Custom system prompt
  useThinking?: boolean           // Optional: Enable thinking (default: true)
  temperature?: number            // Optional: Override temperature
  maxTokens?: number              // Optional: Override max tokens
}

Returns:

## Reasoning Agent Response

[Gemini's response]

---
**Model:** gemini-3-flash-preview | **Temperature:** 0.7 | **Max Tokens:** 2048

📄 License

MIT License - Free for personal and commercial use

🤝 Contributing

Found a bug? Want to improve the plugin?

• Enable detailed logging to diagnose
• Share the logs and your configuration
• Create an issue with step-to-reproduce

📞 Support

For issues related to:

• Plugin functionality: Check troubleshooting section above
• Google Gemini API: Visit https://ai.google.dev/docs
• LM Studio: Visit https://lmstudio.ai

🎯 Roadmap

Future enhancements:

• Support for vision capabilities
• Streaming responses
• Caching for repeated prompts
• Analytics dashboard for key usage
• Integration with other AI providers
• Custom safety settings panel

Version: 1.0.0
Last Updated: April 2026
LM Studio Compatibility: v0.2.28+