Metadata-Version: 2.4
Name: vibecontrols-sdk
Version: 2026.527.2
Summary: Official Python SDK for VibeControls — thin shell over burdenoff-sdk-libs
Project-URL: Homepage, https://github.com/algoshred/vibecontrols-sdk-python
Project-URL: Documentation, https://docs.algoshred.com/sdk/python
Project-URL: Repository, https://github.com/algoshred/vibecontrols-sdk-python
Project-URL: Issues, https://github.com/algoshred/vibecontrols-sdk-python/issues
Project-URL: Changelog, https://github.com/algoshred/vibecontrols-sdk-python/blob/main/CHANGELOG.md
Author-email: "Vignesh T.V" <vignesh@algoshred.com>
Maintainer-email: "Vignesh T.V" <vignesh@algoshred.com>
License: Copyright (c) 2025 Burdenoff Consultancy Services Private Limited, Algoshred Technologies Private Limited and all sister companies.
        
        All rights reserved.
        
        This software is proprietary and confidential. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited without the express written permission of the copyright holders.
        
        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.
        
        For licensing inquiries, please contact: legal@algoshred.com
License-File: LICENSE
Keywords: api-client,burdenoff,development-environment,graphql,python,sdk,vibecontrols
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: burdenoff-sdk-libs>=2026.523.1
Requires-Dist: httpx>=0.24.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == 'docs'
Requires-Dist: sphinx>=6.0.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# vibecontrols-sdk

Official Python SDK for **VibeControls** -- development environment management for the Burdenoff platform.

## Features

- Async/await support built on `httpx`
- Dual-endpoint GraphQL client (workspace + global gateways)
- 14 domain modules covering the full VibeControls API
- Multiple auth flows: email/password, device code, PKCE, client credentials
- Automatic token refresh with configurable callback
- Retry with exponential backoff
- Typed error hierarchy
- Full type hints with `py.typed` marker

## Installation

```bash
pip install vibecontrols-sdk

# Development install
pip install -e ".[dev]"
```

## Quick Start

```python
import asyncio
from vibecontrols_sdk import VibeControlsSDK, VibeControlsConfig

async def main():
    sdk = VibeControlsSDK(VibeControlsConfig(
        workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
        global_endpoint="https://graphql.burdenoff.com/global/graphql",
    ))

    # Sign in with email/password
    auth = await sdk.auth.sign_in("user@example.com", "password")
    print(f"Signed in as {auth['user']['fullName']}")

    # List vibes
    vibes = await sdk.vibes.list()

    # List sessions
    sessions = await sdk.sessions.list()

    await sdk.close()

asyncio.run(main())
```

## Configuration

```python
from vibecontrols_sdk import VibeControlsConfig

config = VibeControlsConfig(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",

    # OAuth2 (optional, for device code / PKCE / client credentials flows)
    oidc_issuer="https://auth.burdenoff.com",
    client_id="vibecontrols-cli",
    client_secret=None,           # Only for client credentials flow
    redirect_uri=None,            # Only for PKCE flow

    # Pre-existing tokens (optional)
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,

    timeout=30.0,                 # Request timeout in seconds
    auto_refresh=True,            # Auto-refresh tokens before expiry
    on_token_refresh=None,        # Callback for external token persistence
)
```

## Modules

All methods are async. Access each module as a property on the `VibeControlsSDK` instance.

| Module | Property | Description |
|--------|----------|-------------|
| **Auth** | `sdk.auth` | Sign in/up, sign out, token refresh, device code, PKCE, client credentials |
| **Agents** | `sdk.agents` | Agent CRUD, heartbeat, probes, plugin management |
| **Vibes** | `sdk.vibes` | Vibe (project/workspace) CRUD and management |
| **Sessions** | `sdk.sessions` | Terminal session management |
| **Notes** | `sdk.notes` | Note CRUD operations |
| **Configuration** | `sdk.configuration` | Key-value configuration management |
| **Webhooks** | `sdk.webhooks` | Webhook CRUD and management |
| **Docs** | `sdk.docs` | Documentation site management |
| **VibeDeck** | `sdk.vibedeck` | VibeDeck management (decks and buttons) |
| **Targets** | `sdk.targets` | Target machine management |
| **Audit** | `sdk.audit` | Audit log queries |
| **UI Session** | `sdk.ui_session` | UI session state management |
| **Tunnels** | `sdk.tunnels` | Agent tunnel management |
| **AI Tool Events** | `sdk.ai_tool_events` | AI tool event tracking |

## Authentication Flows

### Email / Password

```python
auth = await sdk.auth.sign_in("user@example.com", "password")
```

### Device Code (CLI / headless)

```python
device = await sdk.auth.start_device_code_flow()
print(f"Visit {device['verification_uri_complete']} and enter code {device['user_code']}")
# SDK polls automatically until the user authorizes
```

### PKCE (browser-based)

```python
challenge = sdk.auth.build_authorization_url()
# Redirect user to challenge["url"]
# After callback:
result = await sdk.auth.exchange_auth_code(code, challenge["codeVerifier"])
```

### Client Credentials (machine-to-machine)

```python
config = VibeControlsConfig(
    ...,
    client_id="my-service",
    client_secret="secret",
)
sdk = VibeControlsSDK(config)
# Tokens are obtained automatically on first request
```

## Error Handling

```python
from vibecontrols_sdk.errors import (
    VibeControlsError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in("user@example.com", "wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except VibeControlsError as e:
    print(f"SDK error: {e}")
```

## Examples

See the `examples/` directory:

- `basic_usage.py` -- Sign in, list vibes and sessions
- `advanced_usage.py` -- Device code flow, PKCE flow, token management

## Development

```bash
# Create virtual environment
python -m venv venv && source venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Format
black src/ tests/ examples/
isort src/ tests/ examples/

# Lint
flake8 src/ tests/ examples/
mypy src/

# Test
pytest
pytest --cov=vibecontrols_sdk --cov-report=html
```

## Project Structure

```
vibecontrols-sdk-python/
  src/vibecontrols_sdk/
    __init__.py          # VibeControlsSDK facade
    client/              # Dual-endpoint GraphQL client
    auth/                # Auth module + PKCE utilities
    agent/               # Agent management
    vibe/                # Vibe management
    session/             # Session management
    note/                # Note management
    configuration/       # Key-value config
    webhook/             # Webhooks
    docs/                # Documentation sites
    vibedeck/            # VibeDeck (decks + buttons)
    target/              # Target machines
    audit/               # Audit logs
    ui_session/          # UI session state
    tunnel/              # Tunnels
    ai_tool_event/       # AI tool events
    types/               # Type definitions
    errors.py            # Error hierarchy
  tests/
  examples/
  docs/
  pyproject.toml
```

## License

Proprietary -- Copyright Burdenoff Consultancy Services Pvt. Ltd.

## Support

- Issues: [GitHub Issues](https://github.com/algoshred/vibecontrols-sdk-python/issues)
- Docs: [docs.vibecontrols.com](https://docs.vibecontrols.com)
