studiorelay 0.3.0__tar.gz

studiorelay-0.3.0/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: studiorelay
+Version: 0.3.0
+Summary: An OpenAI-compatible gateway that bridges Android Studio's AI agent with multiple LLM providers, handling API compatibility, request translation, streaming, and response normalization.
+Author: StudioRelay contributors
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# StudioRelay
+
+### Connect Android Studio's AI Agent to the AI Models You Choose.
+
+> **Tagline:** One IDE Agent. Multiple AI Models. Zero Vendor Lock-in.
+
+---
+
+## Overview
+
+Android Studio's AI agent is powerful, but connecting it to alternative AI providers can involve compatibility challenges.
+
+StudioRelay is an open-source compatibility gateway designed to bridge that gap.
+
+It translates API requests and responses between Android Studio's AI agent and supported LLM providers, helping different models work within the same agentic development workflow.
+
+Use Kimi. Use DeepSeek. Add more providers. Keep your IDE agent.
+
+Android Studio's AI agent remains responsible for its agentic workflow, including understanding coding tasks, using project context, interacting with tools, and coordinating development operations. StudioRelay provides the local compatibility infrastructure between that IDE agent and your selected LLM provider, handling the protocol adaptation necessary for supported providers to work with the IDE's expected API behavior.
+
+---
+
+## Problem Statement
+
+When connecting Android Studio's AI agent to alternative LLM providers (such as DeepSeek or Kimi / Moonshot AI), developers frequently encounter API protocol divergences:
+
+1. **Unsupported Message Roles (`HTTP 422: unknown variant developer`)**: Android Studio sends system/developer prompts with `role: "developer"`. Strict upstream APIs (such as DeepSeek's deserializer) reject this role before inference begins.
+2. **Missing Endpoint (`POST /v1/responses 404`)**: Android Studio AI Assistant calls the newer OpenAI Responses API (`/v1/responses`). Most alternative LLM providers only expose `/v1/chat/completions`.
+3. **Incompatible Request Parameters**: Parameters like `store`, `metadata`, or `parallel_tool_calls` trigger deserialization errors on alternative providers.
+4. **Blank Thinking Output**: Models like DeepSeek Reasoner emit thinking in `reasoning_content` while leaving final `content` empty, causing standard OpenAI clients to display blank answers.
+5. **Port and Service Conflicts**: Running multiple alternative providers simultaneously typically causes port collisions and model dropdown confusion.
+
+---
+
+## How StudioRelay Works
+
+StudioRelay acts as a transparent, high-performance local proxy:
+
+1. **Local Gateway**: Binds locally (`127.0.0.1:5001` for DeepSeek, `127.0.0.1:5002` for Kimi) with zero external exposure.
+2. **Protocol Adaptation**: Intercepts `/v1/chat/completions` and `/v1/responses`, maps `developer` messages to `system`, filters unsupported parameters, and translates Responses API schemas into Chat Completions.
+3. **Reasoning Fallback**: When thinking models return `reasoning_content` with empty final `content`, StudioRelay surfaces the reasoning as visible text so answers are never blank.
+4. **Zero-Latency Streaming**: Translates Server-Sent Events (SSE) line-by-line in real time.
+5. **Dual Service Isolation**: Runs dedicated background service daemons on separate ports so both DeepSeek and Kimi can be active in Android Studio simultaneously.
+
+---
+
+## Architecture Overview
+
+```text
+                  Android Studio AI Agent
+           (or Cursor, VS Code, Aider, Open WebUI)
+                             │
+                             ▼
+                    ┌──────────────────┐
+                    │   StudioRelay    │
+                    │  Local Gateway   │
+                    │  (127.0.0.1)     │
+                    └────────┬─────────┘
+                             │
+                             ▼
+                    ┌──────────────────┐
+                    │  Compatibility   │
+                    │      Engine      │
+                    │ - Role Adapter   │
+                    │ - Param Filter   │
+                    │ - Responses API  │
+                    │ - Reasoning Map  │
+                    └────────┬─────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              ▼                             ▼
+     DeepSeek Profile               Kimi/Moonshot Profile
+     (Port 5001 / v1)               (Port 5002 / v1)
+              │                             │
+              ▼                             ▼
+       api.deepseek.com              api.moonshot.ai
+```
+
+---
+
+## Supported Providers
+
+- **DeepSeek** (`https://api.deepseek.com`):
+  - Supported models: `deepseek-chat`, `deepseek-reasoner`, `deepseek-v3-pro`, `deepseek-flash`, `deepseek-v3`, `deepseek-r1`
+  - Automatic alias rewriting: `deepseek-chat` ➔ `deepseek-flash`, `deepseek-reasoner` ➔ `deepseek-flash` with `reasoning_effort=high`, `deepseek-v3-pro` ➔ `deepseek-v4-pro`
+  - Normalizes `developer` role to `system` to prevent HTTP 422 errors
+  - Normalizes `reasoning_content` fallback when `content` is empty
+- **Kimi / Moonshot AI** (`https://api.moonshot.ai`):
+  - Supported models: `kimi-k3`, `moonshot-v1-8k`, `moonshot-v1-32k`, `moonshot-v1-128k`
+  - Normalizes `developer` role to `system`
+  - Strips unsupported parameters (`store`, `metadata`, `parallel_tool_calls`)
+- **OpenAI / Generic Passthrough**:
+  - Preserves standard schema for native OpenAI endpoints or generic proxies
+
+---
+
+## Features
+
+- ⚡ **Zero-Latency Streaming**: Line-by-line SSE chunk forwarding.
+- 🔄 **Responses API Bridge**: Seamless support for Android Studio's `/v1/responses` queries.
+- 🧠 **Reasoning Fallback**: Always displays reasoning content if final content is empty.
+- 🛡️ **Zero Secret Logging**: Never logs `Authorization` headers, API keys, or tokens.
+- 🔌 **Intelligent Port Allocation**: Automatically detects port availability and avoids conflicts (`--auto-port`).
+- 🖥️ **Background Service Daemons**: Native `systemd` user units on Linux, `launchd` LaunchAgents on macOS, and `Task Scheduler` on Windows.
+- 📦 **Zero Runtime Dependencies**: Built entirely on the Python Standard Library (`http.server`, `urllib`, `dataclasses`, `argparse`).
+- 🔙 **Full Backward Compatibility**: Seamlessly supports existing `kimibridge` commands, imports, configurations, and service files.
+
+---
+
+## Prerequisites
+
+- **Python**: `3.10+` (3.10, 3.11, or 3.12)
+- **Operating System**:
+  - **Linux**: `systemd` with user session support (`systemctl --user`), `procps`
+  - **macOS**: macOS 11.0 (Big Sur) or newer with `launchd`
+  - **Windows**: Windows 10/11 with PowerShell 5.1+ and Task Scheduler
+- **Git**: `2.20+`
+
+---
+
+## Installation
+
+### Recommended: 1-Step Setup for DeepSeek
+
+**Linux / macOS:**
+```bash
+git clone https://github.com/SubhankarCodeGeek/studio-relay.git
+cd studio-relay
+./installers/install-deepseek.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+git clone https://github.com/SubhankarCodeGeek/studio-relay.git
+cd studio-relay
+.\installers\install-deepseek.ps1
+```
+
+### 1-Step Setup for Kimi / Moonshot AI
+
+**Linux / macOS:**
+```bash
+./installers/install-kimi.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+.\installers\install.ps1 -Kimi
+```
+
+### Interactive Installation (Choose or Run Multiple Providers)
+
+- **Linux / macOS:** `./installers/install.sh`
+- **Windows (PowerShell):** `.\installers\install.ps1`
+
+The installer sets up application files in `~/.studiorelay/app` and registers your background service.
+
+---
+
+## Upgrade from KimiBridge
+
+StudioRelay provides a safe, non-destructive upgrade path for existing KimiBridge installations:
+
+1. **Step 1: Migrate Configuration (Optional, installer also handles this)**
+   ```bash
+   studiorelay migrate --dry-run
+   studiorelay migrate
+   ```
+   This safely copies configs from `~/.kimibridge/` to `~/.studiorelay/` with an automated timestamped backup in `~/.kimibridge/backups/`. Secrets are never logged.
+
+2. **Step 2: Update Application & Services**
+   ```bash
+   cd studio-relay && git pull origin main
+   ./installers/install.sh
+   ```
+   The installer automatically detects active legacy `kimibridge-*.service` units, stops and disables them to prevent port collisions, and enables the new `studiorelay-*.service`.
+
+3. **Step 3: Verify Upgrade**
+   ```bash
+   studiorelay doctor
+   ```
+
+*(Note: Legacy `kimibridge` commands and `~/.kimibridge` configuration files remain fully functional via backward-compatibility aliases).*
+
+---
+
+## Android Studio Configuration
+
+Configure supported providers in Android Studio without touching IDE internals:
+
+### 1. Configure DeepSeek
+1. Open **Android Studio** ➔ **Settings** (or **Preferences** on macOS) ➔ **Tools** ➔ **AI Assistant**.
+2. Select **Custom OpenAI Provider** (or OpenAI-compatible).
+3. Set **Base URL**: `http://127.0.0.1:5001/v1`
+4. Set **API Key**: *Your DeepSeek API Key*
+5. Click **Refresh** to populate models (`deepseek-chat`, `deepseek-reasoner`, `deepseek-v3-pro`, `deepseek-flash`).
+6. Click **Apply**.
+
+### 2. Configure Kimi / Moonshot AI
+1. Add a second OpenAI-compatible provider entry in Android Studio.
+2. Set **Base URL**: `http://127.0.0.1:5002/v1`
+3. Set **API Key**: *Your Moonshot / Kimi API Key*
+4. Click **Refresh** to populate models (`kimi-k3`, `moonshot-v1-8k`, etc.).
+5. Click **Apply**.
+
+Both providers run concurrently in the background with zero port collisions and zero dropdown interference!
+
+---
+
+## Provider Configuration
+
+Switch or reconfigure target providers anytime:
+
+```bash
+# Switch to DeepSeek
+studiorelay setup deepseek
+
+# Switch to Kimi / Moonshot
+studiorelay setup kimi
+
+# Expose both provider model lists concurrently
+studiorelay setup all
+```
+
+---
+
+## CLI Usage
+
+StudioRelay provides a complete management CLI:
+
+```bash
+# Check version
+studiorelay --version
+
+# Show help
+studiorelay --help
+
+# Run comprehensive system diagnostics
+studiorelay doctor
+
+# Inspect running provider endpoints
+studiorelay status
+
+# View recent service logs
+studiorelay logs
+studiorelay logs --provider deepseek
+
+# Start server in foreground (development mode)
+studiorelay start --auto-port
+
+# Migrate legacy configurations
+studiorelay migrate
+```
+
+*(The `kimibridge` CLI executable is also installed as an alias to `studiorelay`).*
+
+---
+
+## Configuration Management
+
+Configuration precedence is strictly deterministic:
+
+1. **Explicit path argument** (`--config /path/to/config.json`)
+2. **`STUDIORELAY_CONFIG`** environment variable
+3. **`KIMIBRIDGE_CONFIG`** environment variable (legacy)
+4. **StudioRelay directory** (`~/.studiorelay/config-<provider>.json` or `config.json`)
+5. **Legacy KimiBridge directory** (`~/.kimibridge/config-<provider>.json` or `config.json`)
+
+To inspect or update settings:
+
+```bash
+# View active configuration (secrets masked)
+studiorelay config show
+
+# Set custom port
+studiorelay config set port 5003
+
+# Set custom upstream base URL
+studiorelay config set base-url https://api.deepseek.com
+
+# Change compatibility mode
+studiorelay config set compatibility-mode compatible
+```
+
+---
+
+## Service Management
+
+### Linux (`systemd --user`)
+```bash
+# Check service status
+systemctl --user status studiorelay-deepseek
+
+# View journal logs
+journalctl --user -u studiorelay-deepseek -n 50 --no-pager
+
+# Restart service via CLI
+studiorelay restart --provider deepseek
+```
+
+### macOS (`launchd`)
+```bash
+studiorelay restart
+studiorelay logs
+```
+
+### Windows (Task Scheduler)
+```powershell
+studiorelay restart
+studiorelay status
+```
+
+---
+
+## Health Checks
+
+StudioRelay provides local health diagnostic endpoints:
+
+```bash
+# Check JSON health endpoint
+curl http://127.0.0.1:5001/health
+
+# Output:
+# {"status": "ok", "service": "kimibridge", "gateway": "studiorelay", "provider": "deepseek", "port": 5001}
+```
+
+Or run `studiorelay doctor` for complete endpoint validation.
+
+---
+
+## Troubleshooting
+
+- **Port in Use**: If port 5001 is already taken by another application, run `studiorelay start --auto-port` or `studiorelay setup deepseek --port 5003`.
+- **422 Unknown Variant Developer**: Ensure Android Studio base URL points to `http://127.0.0.1:5001/v1` so StudioRelay normalizes the message role.
+- **Empty Thinking Output**: Ensure you are running StudioRelay 0.3.0+, which automatically extracts `reasoning_content` into visible output.
+- **For more solutions**, see [Troubleshooting Guide](docs/troubleshooting.md).
+
+---
+
+## Security
+
+- **Localhost Loopback Only**: The server binds exclusively to `127.0.0.1`.
+- **Credential Safety**: StudioRelay never logs, saves, or prints `Authorization` headers or API keys.
+- **Client Header Forwarding**: API keys entered in Android Studio are forwarded directly to upstream providers via secure HTTPS.
+- For complete details, see [Security Policy](SECURITY.md).
+
+---
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/SubhankarCodeGeek/studio-relay.git
+cd studio-relay
+
+# (Optional) Create virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Verify bytecode compilation
+python3 -m compileall studiorelay kimibridge tests
+```
+
+---
+
+## Running Tests
+
+Run the full automated unit and integration test suite:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+All tests execute with local mocks and require zero external API credits or credentials.
+
+---
+
+## Contributing
+
+We welcome contributions! Please review our [Contributing Guide](CONTRIBUTING.md) for architecture details, testing conventions, and pull request guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE) © StudioRelay contributors.