spectyra-proxy 1.0.0

package/INSTALLATION.md

@@ -0,0 +1,96 @@
+# Installation Guide for End Users
+
+## How to Install Spectyra Proxy
+
+### Option 1: Install via npm (Recommended - When Published)
+
+**Once the package is published to npm:**
+
+```bash
+npm install -g spectyra-proxy
+```
+
+**Then start it:**
+```bash
+spectyra-proxy
+```
+
+**That's it!** The proxy will start on:
+- Proxy: http://localhost:3001
+- Dashboard: http://localhost:3002
+
+### Option 2: Install from GitHub (Current Method)
+
+**If the npm package isn't published yet:**
+
+1. **Clone or download the repository:**
+   ```bash
+   git clone https://github.com/your-username/spectyra.git
+   cd spectyra/tools/proxy
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   # or
+   pnpm install
+   ```
+
+3. **Start the proxy:**
+   ```bash
+   npm start
+   # or
+   pnpm start
+   ```
+
+### Option 3: Download Standalone (Future)
+
+**When available, you can download a standalone installer:**
+- macOS: `.dmg` installer
+- Windows: `.exe` installer
+- Linux: `.deb` or `.rpm` package
+
+## Requirements
+
+- **Node.js**: Version 18 or higher
+- **npm** or **pnpm**: For package installation
+- **Terminal/Command Prompt**: To run commands
+
+## Verify Installation
+
+After starting, you should see:
+```
+🚀 Spectyra Proxy running on http://localhost:3001
+📊 Dashboard: http://localhost:3002
+```
+
+Open http://localhost:3002 to verify the dashboard is working.
+
+## Next Steps
+
+1. Configure the proxy (see Step 2 in Connections page)
+2. Configure your coding tool (see Step 3 in Connections page)
+3. Start coding and see savings!
+
+## Troubleshooting
+
+### "Command not found: spectyra-proxy"
+- Make sure you installed globally: `npm install -g spectyra-proxy`
+- Try: `npx @spectyra/proxy` instead
+
+### "Port already in use"
+- Another process is using port 3001 or 3002
+- Stop that process or change ports via environment variables:
+  ```bash
+  PROXY_PORT=3003 DASHBOARD_PORT=3004 spectyra-proxy
+  ```
+
+### "Cannot find module"
+- Make sure you ran `npm install` in the proxy directory
+- Try deleting `node_modules` and running `npm install` again
+
+## Need Help?
+
+- See: `README.md` for detailed documentation
+- See: `SETUP_GUIDE.md` for tool-specific setup
+- See: `PROVIDER_SUPPORT.md` for provider information

package/PROVIDER_SUPPORT.md

@@ -0,0 +1,162 @@
+# Provider Support Guide
+
+## Supported Providers
+
+The Spectyra Proxy supports **all major LLM providers** used by coding tools:
+
+### ✅ OpenAI
+**Tools:**
+- GitHub Copilot
+- Cursor (when using OpenAI models)
+- Codeium (OpenAI mode)
+- Tabnine (OpenAI mode)
+
+**API Format:** OpenAI-compatible (`/v1/chat/completions`)
+**Configuration:** Select "OpenAI" in dashboard
+
+### ✅ Anthropic (Claude)
+**Tools:**
+- Claude Code
+- Cursor (when using Claude models)
+- Tools using Claude API
+
+**API Format:** Anthropic Messages API (`/v1/messages`)
+**Configuration:** Select "Anthropic" in dashboard
+
+**Note:** The proxy automatically handles Anthropic's different API format.
+
+### ✅ Gemini
+**Tools:**
+- Google AI Studio tools
+- Tools using Gemini API
+
+**API Format:** Gemini GenerateContent API
+**Configuration:** Select "Gemini" in dashboard
+
+### ✅ Grok
+**Tools:**
+- X.AI tools
+- Tools using Grok API
+
+**API Format:** OpenAI-compatible (`/v1/chat/completions`)
+**Configuration:** Select "Grok" in dashboard
+
+## How It Works
+
+The proxy automatically:
+
+1. **Detects API format** from the request
+2. **Converts to Spectyra format** for optimization
+3. **Routes through Spectyra** with your configured provider
+4. **Converts back to original format** for your tool
+
+**You don't need to worry about API format differences!**
+
+## Configuration
+
+### Step 1: Select Provider
+
+In the dashboard (http://localhost:3002), select your provider:
+- **OpenAI** - For Copilot, Cursor (OpenAI), etc.
+- **Anthropic** - For Claude Code, Cursor (Claude), etc.
+- **Gemini** - For Google AI tools
+- **Grok** - For X.AI tools
+
+### Step 2: Enter API Keys
+
+- **Spectyra API Key:** Your Spectyra key
+- **Provider API Key:** Your provider key (OpenAI, Anthropic, etc.)
+
+### Step 3: Configure Tool
+
+Set your tool's API endpoint to: `http://localhost:3001/v1`
+
+**The proxy handles format conversion automatically!**
+
+## Tool-Specific Setup
+
+### GitHub Copilot (OpenAI)
+```bash
+export OPENAI_API_BASE=http://localhost:3001/v1
+```
+Provider: **OpenAI**
+
+### Claude Code (Anthropic)
+Configure Claude Code to use: `http://localhost:3001/v1/messages`
+Provider: **Anthropic**
+
+### Cursor
+- If using OpenAI models: Provider = **OpenAI**
+- If using Claude models: Provider = **Anthropic**
+- Set API base: `http://localhost:3001/v1`
+
+### Codeium
+- If using OpenAI: Provider = **OpenAI**
+- Set API endpoint: `http://localhost:3001/v1`
+
+## API Format Conversion
+
+The proxy automatically converts between formats:
+
+### OpenAI → Spectyra → OpenAI
+```
+OpenAI format (messages array)
+  ↓
+Spectyra format (standardized)
+  ↓
+OpenAI format (response)
+```
+
+### Anthropic → Spectyra → Anthropic
+```
+Anthropic format (messages with content arrays)
+  ↓
+Spectyra format (standardized)
+  ↓
+Anthropic format (message object)
+```
+
+### Gemini → Spectyra → Gemini
+```
+Gemini format (contents with parts)
+  ↓
+Spectyra format (standardized)
+  ↓
+Gemini format (candidates)
+```
+
+## Troubleshooting
+
+### Tool not connecting
+- Verify provider is correct in dashboard
+- Check tool's API endpoint setting
+- Ensure proxy is running
+
+### Wrong format errors
+- The proxy should auto-detect, but if issues occur:
+  - Check provider selection in dashboard
+  - Verify tool is using correct endpoint
+  - Check proxy console for format detection logs
+
+### Provider-specific issues
+
+**Anthropic:**
+- Ensure you're using `/v1/messages` endpoint
+- System messages are handled automatically
+
+**Gemini:**
+- Verify API key format
+- Check model name is correct
+
+**OpenAI/Grok:**
+- Standard `/v1/chat/completions` endpoint
+- Should work with most tools
+
+## Summary
+
+✅ **All providers supported** - OpenAI, Anthropic, Gemini, Grok
+✅ **Automatic format conversion** - No manual configuration needed
+✅ **Works with all coding tools** - Copilot, Cursor, Claude Code, etc.
+✅ **Simple setup** - Just select provider in dashboard
+
+**The proxy handles all the complexity for you!**

package/README.md

@@ -0,0 +1,194 @@
+# Spectyra Proxy
+
+Local proxy server that provides an OpenAI-compatible endpoint, routing requests through Spectyra for automatic optimization. Works with GitHub Copilot, Cursor, Claude Code, and other coding assistants.
+
+## Features
+
+- ✅ **OpenAI-compatible API** - Works with any tool that uses OpenAI API
+- ✅ **Automatic optimization** - Routes through Spectyra for 40-65% token savings
+- ✅ **Real-time dashboard** - Web UI showing savings and stats
+- ✅ **Configuration management** - Easy setup via web dashboard
+- ✅ **BYOK support** - Use your own API keys
+- ✅ **Multi-provider support** - OpenAI, Anthropic, Gemini, Grok
+
+## Installation
+
+### Option 1: Install via npm (Recommended)
+
+```bash
+npm install -g spectyra-proxy
+```
+
+Then start with:
+```bash
+spectyra-proxy
+```
+
+**Note:** The npm package contains only compiled JavaScript, not source code. Your code remains private.
+
+### Option 2: Install from Source (Development)
+
+If you need to modify the code or the npm package isn't available:
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/spectyra.git
+cd spectyra/tools/proxy
+
+# Install dependencies
+npm install
+# or
+pnpm install
+
+# Build (compiles TypeScript to JavaScript)
+npm run build
+
+# Start
+npm start
+```
+
+## Quick Start
+
+1. **Start the proxy:**
+
+   **If installed via npm:**
+   ```bash
+   spectyra-proxy
+   ```
+
+   **If installed from source:**
+   ```bash
+   npm start
+   # or
+   pnpm start
+   ```
+
+2. **Configure via dashboard:**
+   - Open http://localhost:3002 in your browser
+   - Enter your Spectyra API key
+   - Enter your provider API key (OpenAI, Anthropic, etc.)
+   - Select provider and optimization settings
+   - Click "Save Configuration"
+
+3. **Configure your coding tool:**
+   - Set `OPENAI_API_BASE=http://localhost:3001/v1`
+   - Or configure in your tool's settings
+
+## Usage
+
+### With GitHub Copilot
+
+1. Set environment variable:
+```bash
+export OPENAI_API_BASE=http://localhost:3001/v1
+```
+
+2. Restart VS Code/Copilot
+
+### With Cursor
+
+1. Open Cursor Settings
+2. Set API base URL to: `http://localhost:3001/v1`
+3. Restart Cursor
+
+### With Claude Code
+
+1. Configure Claude Code to use custom API endpoint
+2. Set endpoint to: `http://localhost:3001/v1`
+
+## Dashboard
+
+Access the dashboard at: **http://localhost:3002**
+
+**Features:**
+- Real-time savings statistics
+- Recent request history
+- Configuration management
+- Live updates every 2 seconds
+
+## Configuration
+
+### Environment Variables
+
+- `PROXY_PORT` - Proxy server port (default: 3001)
+- `DASHBOARD_PORT` - Dashboard port (default: 3002)
+- `SPECTYRA_API_URL` - Spectyra API URL (default: https://spectyra.up.railway.app/v1)
+
+### Configuration File
+
+Configuration is saved to `.spectyra-proxy-config.json` in the proxy directory.
+
+**Fields:**
+- `spectyraKey` - Your Spectyra API key
+- `providerKey` - Your provider API key (BYOK)
+- `provider` - Provider name (openai, anthropic, gemini, grok)
+- `path` - Optimization path (code, talk)
+- `optimizationLevel` - Optimization level (0-4)
+
+## API Endpoints
+
+### Proxy Endpoint
+- `POST /v1/chat/completions` - OpenAI-compatible chat endpoint
+- `POST /v1/messages` - Anthropic-compatible messages endpoint
+
+### Configuration
+- `GET /config` - Get current configuration (without keys)
+- `POST /config` - Update configuration
+
+### Statistics
+- `GET /stats` - Get usage statistics and savings
+
+### Health Check
+- `GET /health` - Check proxy status
+
+## How It Works
+
+```
+Your Coding Tool (Copilot/Cursor/etc)
+  → Local Proxy (localhost:3001)
+    → Spectyra API (optimization)
+      → Provider API (OpenAI/Anthropic)
+        → Optimized Response
+          → Your Tool
+```
+
+**Benefits:**
+- Transparent optimization
+- No code changes needed
+- Real-time savings tracking
+- Works with any OpenAI-compatible tool
+
+## Troubleshooting
+
+### Proxy not starting
+- Check if ports 3001 and 3002 are available
+- Try different ports via environment variables
+
+### Configuration not saving
+- Check file permissions in proxy directory
+- Ensure `.spectyra-proxy-config.json` is writable
+
+### Tool not connecting
+- Verify proxy is running: `curl http://localhost:3001/health`
+- Check tool's API base URL setting
+- Ensure tool supports custom API endpoints
+
+### No savings showing
+- Verify configuration is correct
+- Check Spectyra API key is valid
+- Check provider API key is valid
+- Look at proxy console for errors
+
+## Development
+
+```bash
+# Watch mode (auto-restart on changes)
+npm run dev
+
+# Build for distribution
+npm run build
+```
+
+## License
+
+MIT

package/SETUP_GUIDE.md

@@ -0,0 +1,183 @@
+# Spectyra Proxy Setup Guide
+
+## For Developers Using Coding Assistants
+
+This guide shows how to set up Spectyra Proxy to optimize your coding assistant API costs.
+
+## Supported Tools
+
+- ✅ GitHub Copilot
+- ✅ Cursor
+- ✅ Claude Code
+- ✅ Codeium
+- ✅ Tabnine
+- ✅ Any OpenAI-compatible tool
+
+## Step 1: Install and Start Proxy
+
+```bash
+cd tools/proxy
+pnpm install
+pnpm start
+```
+
+The proxy will start on:
+- **Proxy:** http://localhost:3001
+- **Dashboard:** http://localhost:3002
+
+## Step 2: Configure Proxy
+
+1. Open http://localhost:3002 in your browser
+2. Go to "Configuration" tab
+3. Enter:
+   - **Spectyra API Key:** Your Spectyra API key
+   - **Provider API Key:** Your OpenAI/Anthropic/etc. key (BYOK)
+   - **Provider:** Select your provider
+   - **Path:** "Code" (recommended for coding)
+   - **Optimization Level:** 2-3 (balanced to aggressive)
+4. Click "Save Configuration"
+
+## Step 3: Configure Your Coding Tool
+
+### GitHub Copilot
+
+1. Set environment variable:
+```bash
+export OPENAI_API_BASE=http://localhost:3001/v1
+```
+
+2. Restart VS Code
+
+**Or in VS Code settings.json:**
+```json
+{
+  "github.copilot.advanced": {
+    "api.baseUrl": "http://localhost:3001/v1"
+  }
+}
+```
+
+### Cursor
+
+1. Open Cursor Settings
+2. Search for "API"
+3. Set "OpenAI API Base URL" to: `http://localhost:3001/v1`
+4. Restart Cursor
+
+### Claude Code
+
+1. Open Claude Code settings
+2. Set custom API endpoint: `http://localhost:3001/v1`
+3. Restart Claude Code
+
+### Codeium
+
+1. Open Codeium settings
+2. Set API endpoint: `http://localhost:3001/v1`
+3. Restart VS Code/editor
+
+## Step 4: Monitor Savings
+
+1. Open dashboard: http://localhost:3002
+2. Go to "Statistics" tab
+3. See real-time:
+   - Total requests
+   - Tokens saved
+   - Cost saved
+   - Recent request history
+
+## Verification
+
+1. Use your coding assistant normally
+2. Check dashboard - you should see requests appearing
+3. See savings percentages (typically 40-65%)
+
+## Troubleshooting
+
+### Proxy not running
+```bash
+# Check if running
+curl http://localhost:3001/health
+
+# Should return: {"status":"ok","service":"spectyra-proxy"}
+```
+
+### Tool not connecting
+- Verify proxy is running
+- Check tool's API base URL setting
+- Check tool logs for connection errors
+- Ensure tool supports custom endpoints
+
+### No savings showing
+- Check configuration is saved
+- Verify API keys are correct
+- Check proxy console for errors
+- Ensure optimization level > 0
+
+### Configuration not saving
+- Check file permissions
+- Ensure `.spectyra-proxy-config.json` is writable
+- Check proxy console for errors
+
+## Advanced: Auto-Start on Boot
+
+### macOS (launchd)
+
+Create `~/Library/LaunchAgents/com.spectyra.proxy.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.spectyra.proxy</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/node</string>
+    <string>/path/to/spectyra/tools/proxy/spectyra-proxy.ts</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+</dict>
+</plist>
+```
+
+Then:
+```bash
+launchctl load ~/Library/LaunchAgents/com.spectyra.proxy.plist
+```
+
+### Linux (systemd)
+
+Create `/etc/systemd/system/spectyra-proxy.service`:
+
+```ini
+[Unit]
+Description=Spectyra Proxy
+After=network.target
+
+[Service]
+Type=simple
+User=your-username
+WorkingDirectory=/path/to/spectyra/tools/proxy
+ExecStart=/usr/bin/node /path/to/spectyra/tools/proxy/spectyra-proxy.ts
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+```bash
+sudo systemctl enable spectyra-proxy
+sudo systemctl start spectyra-proxy
+```
+
+## Next Steps
+
+- Monitor savings in dashboard
+- Adjust optimization level if needed
+- Share feedback and improvements!