windsurf-throttle 1.0.1__tar.gz

windsurf_throttle-1.0.1/.env.example

@@ -0,0 +1,8 @@
+# Windsurf Credit Throttle Configuration
+# Copy this to .env and fill in your actual values
+
+# Required: Your Windsurf service key (get from admin panel)
+WINDSURF_SERVICE_KEY=your_service_key_here
+
+# Optional: Override default API base URL
+# WINDSURF_BASE_URL=https://server.codeium.com

windsurf_throttle-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish Python distro to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/windsurf-throttle # Replace this
+    permissions:
+      id-token: write  # Mandatory for Trusted Publishing
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+
+    - name: Install andd upgrade build tools 
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade build setuptools wheel
+
+    - name: Verify pyproject.toml
+      run: |
+        echo "Checking pyproject.toml hatchling config:"
+        grep -A 2 "tool.hatch.build.targets.wheel" pyproject.toml
+
+    - name: Clean build artifacts
+      run: rm -rf dist/ build/ *.egg-info
+
+    - name: Build binary wheel and source tarball
+      run: python -m build
+
+    - name: Verify wheel metadata
+      run: |
+        echo "Checking wheel contents:"
+        unzip -l dist/*.whl | grep METADATA
+        echo "Extracting metadata:"
+        unzip -p dist/*.whl */METADATA | head -20
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1.12

windsurf_throttle-1.0.1/.gitignore

@@ -0,0 +1,50 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Environment files
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Logs
+logs/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

windsurf_throttle-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - httpx
+          - pandas-stubs
+          - types-requests

windsurf_throttle-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 
+
+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.

windsurf_throttle-1.0.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: windsurf-throttle
+Version: 1.0.1
+Summary: Streamlit app for managing Windsurf credit caps
+Project-URL: Homepage, https://github.com/PFPT-Internal/windsurf-throttle
+Project-URL: Repository, https://github.com/PFPT-Internal/windsurf-throttle
+Author-email: Your Name <your.email@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: credit,streamlit,throttle,windsurf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: streamlit>=1.40.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Windsurf Credit Throttle
+
+A Streamlit application for managing Windsurf add-on credit caps.
+
+## Features
+
+- **Verify Credit Caps**: Check team-level and individual user credit configurations
+- **Set Team Cap**: Configure organization-wide add-on credit limits
+- **Set Individual Caps**: Set custom caps for specific users or bulk import from CSV
+
+## Installation
+
+### Using uvx (recommended)
+
+```bash
+# Run directly from GitHub
+uvx --from git+https://github.com/PFPT-Internal/windsurf-throttle windsurf-throttle
+
+# Or from PyPI (when published)
+uvx windsurf-throttle
+```
+
+### Using pip
+
+```bash
+pip install windsurf-throttle
+windsurf-throttle
+```
+
+### From source
+
+```bash
+git clone https://github.com/PFPT-Internal/windsurf-throttle.git
+cd windsurf-throttle
+uv sync
+uv run windsurf-throttle
+```
+
+## Configuration
+
+Set your Windsurf service key as an environment variable:
+
+```bash
+export WINDSURF_SERVICE_KEY=your_service_key_here
+```
+
+Or create a `.env` file in your working directory:
+
+```
+WINDSURF_SERVICE_KEY=your_service_key_here
+```
+
+### Optional Configuration
+
+```bash
+# Override the API base URL (default: https://server.codeium.com)
+export WINDSURF_BASE_URL=https://custom.server.com
+```
+
+## Usage
+
+### Running the App
+
+```bash
+# Using the CLI
+windsurf-throttle
+
+# Or run Streamlit directly
+streamlit run src/windsurf_throttle/app.py
+```
+
+### Credit Cap Strategy
+
+The app implements the following strategy:
+
+1. **Base Credits**: Each user gets 500 base credits
+2. **Organization Cap**: Set a default add-on cap for all users (e.g., 1000)
+3. **Individual Caps**: For high-usage users, set individual caps = current add-on usage + buffer
+
+Example:
+- User with 1200 total credits used → 700 add-on credits used
+- Individual cap = 700 + 500 buffer = 1200 add-on credits
+- Total available = 500 base + 1200 add-on = 1700 credits
+
+### Bulk CSV Import
+
+Upload a CSV with these columns:
+- `email` (required): User email address
+- `credits_used` (required): Current total credit usage
+- `name` (optional): User display name
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/PFPT-Internal/windsurf-throttle.git
+cd windsurf-throttle
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check src tests
+uv run mypy src
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## License
+
+MIT

windsurf_throttle-1.0.1/README.md

@@ -0,0 +1,113 @@
+# Windsurf Credit Throttle
+
+A Streamlit application for managing Windsurf add-on credit caps.
+
+## Features
+
+- **Verify Credit Caps**: Check team-level and individual user credit configurations
+- **Set Team Cap**: Configure organization-wide add-on credit limits
+- **Set Individual Caps**: Set custom caps for specific users or bulk import from CSV
+
+## Installation
+
+### Using uvx (recommended)
+
+```bash
+# Run directly from GitHub
+uvx --from git+https://github.com/PFPT-Internal/windsurf-throttle windsurf-throttle
+
+# Or from PyPI (when published)
+uvx windsurf-throttle
+```
+
+### Using pip
+
+```bash
+pip install windsurf-throttle
+windsurf-throttle
+```
+
+### From source
+
+```bash
+git clone https://github.com/PFPT-Internal/windsurf-throttle.git
+cd windsurf-throttle
+uv sync
+uv run windsurf-throttle
+```
+
+## Configuration
+
+Set your Windsurf service key as an environment variable:
+
+```bash
+export WINDSURF_SERVICE_KEY=your_service_key_here
+```
+
+Or create a `.env` file in your working directory:
+
+```
+WINDSURF_SERVICE_KEY=your_service_key_here
+```
+
+### Optional Configuration
+
+```bash
+# Override the API base URL (default: https://server.codeium.com)
+export WINDSURF_BASE_URL=https://custom.server.com
+```
+
+## Usage
+
+### Running the App
+
+```bash
+# Using the CLI
+windsurf-throttle
+
+# Or run Streamlit directly
+streamlit run src/windsurf_throttle/app.py
+```
+
+### Credit Cap Strategy
+
+The app implements the following strategy:
+
+1. **Base Credits**: Each user gets 500 base credits
+2. **Organization Cap**: Set a default add-on cap for all users (e.g., 1000)
+3. **Individual Caps**: For high-usage users, set individual caps = current add-on usage + buffer
+
+Example:
+- User with 1200 total credits used → 700 add-on credits used
+- Individual cap = 700 + 500 buffer = 1200 add-on credits
+- Total available = 500 base + 1200 add-on = 1700 credits
+
+### Bulk CSV Import
+
+Upload a CSV with these columns:
+- `email` (required): User email address
+- `credits_used` (required): Current total credit usage
+- `name` (optional): User display name
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/PFPT-Internal/windsurf-throttle.git
+cd windsurf-throttle
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check src tests
+uv run mypy src
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## License
+
+MIT

windsurf_throttle-1.0.1/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "windsurf-throttle"
+version = "1.0.1"
+description = "Streamlit app for managing Windsurf credit caps"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Your Name", email = "your.email@example.com" }]
+keywords = ["windsurf", "credit", "throttle", "streamlit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "python-dotenv>=1.0.0",
+    "streamlit>=1.40.0",
+    "pandas>=2.0.0",
+    "watchdog>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/PFPT-Internal/windsurf-throttle"
+Repository = "https://github.com/PFPT-Internal/windsurf-throttle"
+
+[project.scripts]
+windsurf-throttle = "windsurf_throttle.cli:main"
+
+[project.gui-scripts]
+windsurf-throttle-gui = "windsurf_throttle.app:run"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.8.0",
+    "mypy>=1.13.0",
+    "pre-commit>=4.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/windsurf_throttle"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

windsurf_throttle-1.0.1/src/windsurf_throttle/__init__.py

@@ -0,0 +1,3 @@
+"""Windsurf Throttle - Credit cap management for Windsurf."""
+
+__version__ = "0.1.0"

windsurf_throttle-1.0.1/src/windsurf_throttle/api.py

@@ -0,0 +1,175 @@
+"""Windsurf API client for credit cap management."""
+
+import os
+from typing import Any
+
+import httpx
+from dotenv import load_dotenv
+
+load_dotenv()
+
+API_BASE_URL = os.getenv("WINDSURF_BASE_URL", "https://server.codeium.com")
+SERVICE_KEY = os.getenv("WINDSURF_SERVICE_KEY")
+
+BASE_CREDITS = 500
+DEFAULT_ORG_ADDON_CAP = 1000
+DEFAULT_INDIVIDUAL_CAP_THRESHOLD = 1000
+DEFAULT_INDIVIDUAL_CAP_BUFFER = 500
+
+
+class WindsurfAPIError(Exception):
+    """Exception raised for Windsurf API errors."""
+
+    pass
+
+
+def get_service_key() -> str:
+    """Get the service key from environment, raising if not found."""
+    if not SERVICE_KEY:
+        raise WindsurfAPIError("WINDSURF_SERVICE_KEY not found in environment")
+    return SERVICE_KEY
+
+
+def get_usage_config(
+    team_level: bool = False,
+    group_id: str | None = None,
+    user_email: str | None = None,
+) -> dict[str, Any]:
+    """Get usage configuration via Windsurf API.
+
+    Args:
+        team_level: If True, get team-level configuration.
+        group_id: Get configuration for a specific group.
+        user_email: Get configuration for a specific user.
+
+    Returns:
+        API response as a dictionary.
+
+    Raises:
+        WindsurfAPIError: If the API call fails or no target is specified.
+    """
+    service_key = get_service_key()
+    payload: dict[str, Any] = {"service_key": service_key}
+
+    if team_level:
+        payload["team_level"] = True
+    elif group_id:
+        payload["group_id"] = group_id
+    elif user_email:
+        payload["user_email"] = user_email
+    else:
+        raise WindsurfAPIError("Must specify one of: team_level, group_id, or user_email")
+
+    try:
+        with httpx.Client(timeout=30.0) as client:
+            response = client.post(
+                f"{API_BASE_URL}/api/v1/GetUsageConfig",
+                json=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            return response.json()
+    except httpx.HTTPStatusError as e:
+        raise WindsurfAPIError(f"HTTP error: {e.response.status_code} - {e.response.text}")
+    except Exception as e:
+        raise WindsurfAPIError(f"Error getting usage config: {e}")
+
+
+def get_team_users(
+    group_name: str | None = None,
+    start_timestamp: str | None = None,
+    end_timestamp: str | None = None,
+) -> list[dict[str, Any]]:
+    """Get list of team users via Windsurf API.
+
+    Args:
+        group_name: Filter results to users in a specific group (optional).
+        start_timestamp: Start time in RFC 3339 format (optional).
+        end_timestamp: End time in RFC 3339 format (optional).
+
+    Returns:
+        List of user statistics objects with name, email, etc.
+
+    Raises:
+        WindsurfAPIError: If the API call fails.
+    """
+    service_key = get_service_key()
+    payload: dict[str, Any] = {"service_key": service_key}
+
+    if group_name:
+        payload["group_name"] = group_name
+    if start_timestamp:
+        payload["start_timestamp"] = start_timestamp
+    if end_timestamp:
+        payload["end_timestamp"] = end_timestamp
+
+    try:
+        with httpx.Client(timeout=60.0) as client:
+            response = client.post(
+                f"{API_BASE_URL}/api/v1/UserPageAnalytics",
+                json=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data.get("userTableStats", [])
+    except httpx.HTTPStatusError as e:
+        raise WindsurfAPIError(f"HTTP error: {e.response.status_code} - {e.response.text}") from e
+    except Exception as e:
+        raise WindsurfAPIError(f"Error getting team users: {e}") from e
+
+
+def set_usage_config(
+    set_add_on_credit_cap: int | None = None,
+    clear_add_on_credit_cap: bool = False,
+    team_level: bool = False,
+    group_id: str | None = None,
+    user_email: str | None = None,
+) -> dict[str, Any]:
+    """Set or clear add-on credit cap via Windsurf API.
+
+    Args:
+        set_add_on_credit_cap: The add-on credit cap to set.
+        clear_add_on_credit_cap: If True, clear the add-on credit cap.
+        team_level: If True, set team-level configuration.
+        group_id: Set configuration for a specific group.
+        user_email: Set configuration for a specific user.
+
+    Returns:
+        API response as a dictionary.
+
+    Raises:
+        WindsurfAPIError: If the API call fails or required args are missing.
+    """
+    service_key = get_service_key()
+    payload: dict[str, Any] = {"service_key": service_key}
+
+    if clear_add_on_credit_cap:
+        payload["clear_add_on_credit_cap"] = True
+    elif set_add_on_credit_cap is not None:
+        payload["set_add_on_credit_cap"] = set_add_on_credit_cap
+    else:
+        raise WindsurfAPIError("Must specify either set_add_on_credit_cap or clear_add_on_credit_cap")
+
+    if team_level:
+        payload["team_level"] = True
+    elif group_id:
+        payload["group_id"] = group_id
+    elif user_email:
+        payload["user_email"] = user_email
+    else:
+        raise WindsurfAPIError("Must specify one of: team_level, group_id, or user_email")
+
+    try:
+        with httpx.Client(timeout=30.0) as client:
+            response = client.post(
+                f"{API_BASE_URL}/api/v1/UsageConfig",
+                json=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            return response.json()
+    except httpx.HTTPStatusError as e:
+        raise WindsurfAPIError(f"HTTP error: {e.response.status_code} - {e.response.text}")
+    except Exception as e:
+        raise WindsurfAPIError(f"Error setting usage config: {e}")