Metadata-Version: 2.4
Name: devops-bot-sdk
Version: 1.4.0
Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
Author: noumanaziz2128
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://agentos.io
Project-URL: Repository, https://github.com/consultancy-outfit/DevOpsBot-SDK
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=42
Provides-Extra: screenshot
Requires-Dist: Pillow>=10.0; extra == "screenshot"
Provides-Extra: process
Requires-Dist: psutil>=5.9; extra == "process"
Provides-Extra: all
Requires-Dist: Pillow>=10.0; extra == "all"
Requires-Dist: psutil>=5.9; extra == "all"

# DevOpsBot SDK

Python client for the DevOpsBot desktop app. Provides the `agentos` CLI to configure credentials and a `BackendClient` to interact with the DevOpsBot backend.

**Private package** — requires GitHub access to install.

> For a full walkthrough including SSH setup, end-to-end testing, and troubleshooting see [SETUP_GUIDE.md](SETUP_GUIDE.md).

---

## Requirements

| | Minimum | Check |
|---|---|---|
| Python | 3.11+ | `python3 --version` (Linux/macOS) · `python --version` (Windows) |
| Git | any | `git --version` |
| DevOpsBot account | — | Needed for your API token |

---

## Installation

Choose the method that fits your setup. **Option A (venv)** is recommended for
developers. **Option B (system Python)** works for everyone else and requires
no extra steps.

---

### Option A — Virtual environment (recommended for developers)

A virtual environment keeps the SDK isolated from your system Python.

**Linux / macOS:**
```bash
# Create and activate a venv
python3 -m venv devopsbot-env
source devopsbot-env/bin/activate

# Install via SSH
pip install "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"

# OR install via HTTPS token
pip install "git+https://<YOUR_GITHUB_TOKEN>@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

**Windows (Command Prompt):**
```cmd
python -m venv devopsbot-env
devopsbot-env\Scripts\activate

pip install "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

**Windows (PowerShell):**
```powershell
python -m venv devopsbot-env
devopsbot-env\Scripts\Activate.ps1

pip install "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

> The venv must be **activated** every time you open a new terminal before using
> `agentos` or running SDK scripts. You only create it once.

---

### Option B — System Python (simplest, works for everyone)

Installs directly into your default Python environment — no activation needed.

**Linux / macOS:**
```bash
# via SSH
pip3 install --break-system-packages "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"

# via HTTPS token
pip3 install --break-system-packages "git+https://<YOUR_GITHUB_TOKEN>@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

**Windows:**
```cmd
# via SSH
pip install "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"

# via HTTPS token
pip install "git+https://<YOUR_GITHUB_TOKEN>@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

> `--break-system-packages` is required on Ubuntu 22.04+ and Debian 12+ due to PEP 668.
> It is safe — it only installs this package, it does not affect your system Python.
> Windows does not need this flag.

> If `pip` is not found on Windows, use `python -m pip install ...` instead.

---

### With optional collectors

Append `[all]` to either install command to enable screen capture and process listing:

**Linux / macOS (system Python):**
```bash
pip3 install --break-system-packages "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git[all]"
```

**Linux / macOS (venv, after activation):**
```bash
pip install "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git[all]"
```

**Windows:**
```cmd
pip install "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git[all]"
```

---

## Configure

Get your API token from **DevOpsBot Web App → Settings → API Tokens → Generate Token**.
Token format: `co_<uuid>_<32-hex-secret>`

```bash
agentos configure
```

To replace an existing token:

```bash
agentos configure --rotate
```

---

## Quick Start

```python
import asyncio
from sdk import BackendClient

async def main():
    client = BackendClient.from_config()   # reads ~/.agentos/config.toml

    profile = await client.bootstrap()
    print(f"Logged in — tier: {profile.tier}")

    async for envelope in client.chat("my-thread", "What tasks are open?"):
        if envelope.type == "delta":
            print(envelope.data["text"], end="", flush=True)
        elif envelope.type == "done":
            print()
            break

asyncio.run(main())
```

---

## Agents

The orchestrator runs AI agent pipelines server-side. You submit a task, receive
a stream of progress envelopes, and approve or reject the outcome.

### Run an agent

```python
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    req = OrchestratorRequest(
        task_input="hello",
        intent="greet",   # optional — helps the backend route the task
    )

    async for envelope in client.orchestrator_run(req):
        print(f"[{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            # Task needs a human decision before it continues
            task_id = envelope.data["task_id"]
            decision = input("Approve? (yes/no): ").strip().lower()
            await client.approve_task(
                task_id,
                decision="approved" if decision == "yes" else "rejected",
                note="Reviewed and approved by operator.",
            )

        elif envelope.type in ("done", "error"):
            break

asyncio.run(main())
```

### Envelope types emitted by the orchestrator

| Type | When it fires | Useful data |
|---|---|---|
| `pipeline_started` | Task accepted by backend | `task_id` |
| `pipeline.<key>` | A pipeline context field updated | `key`, `value` |
| `awaiting_approval` | Pipeline paused — human decision required | `task_id` |
| `done` | Pipeline completed | `task_id`, `approval_status` |
| `error` | Unrecoverable failure | `code`, `message` |

### List and approve tasks

```python
import asyncio
from sdk import BackendClient

async def main():
    client = BackendClient.from_config()

    # List tasks waiting for approval
    result = await client.list_tasks(status="To Do", limit=20)
    for task in result.get("tasks", []):
        print(task["task_id"], task.get("summary", ""))

    # Approve a specific task by ID
    await client.approve_task("task-id-here", decision="approved", note="LGTM")

asyncio.run(main())
```

### Test agents end-to-end (no repo clone needed)

#### Linux / macOS

```bash
python3 - << 'EOF'
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    print("Starting agent pipeline...")
    req = OrchestratorRequest(task_input="hello")

    async for envelope in client.orchestrator_run(req):
        print(f"  [{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            print("  → Auto-approving for test...")
            await client.approve_task(envelope.data["task_id"], decision="approved")

        elif envelope.type == "done":
            print("\nAgent completed successfully.")
            break

        elif envelope.type == "error":
            print(f"\nAgent error: {envelope.data}")
            break

asyncio.run(main())
EOF
```

#### Windows (PowerShell)

```powershell
python - << 'EOF'
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    print("Starting agent pipeline...")
    req = OrchestratorRequest(task_input="hello")

    async for envelope in client.orchestrator_run(req):
        print(f"  [{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            print("  -> Auto-approving for test...")
            await client.approve_task(envelope.data["task_id"], decision="approved")

        elif envelope.type == "done":
            print("\nAgent completed successfully.")
            break

        elif envelope.type == "error":
            print(f"\nAgent error: {envelope.data}")
            break

asyncio.run(main())
EOF
```

#### Windows (Command Prompt)

Save as `test_agent.py` and run `python test_agent.py`:

```python
# test_agent.py
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    print("Starting agent pipeline...")
    req = OrchestratorRequest(task_input="hello")

    async for envelope in client.orchestrator_run(req):
        print(f"  [{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            print("  -> Auto-approving for test...")
            await client.approve_task(envelope.data["task_id"], decision="approved")

        elif envelope.type == "done":
            print("\nAgent completed successfully.")
            break

        elif envelope.type == "error":
            print(f"\nAgent error: {envelope.data}")
            break

asyncio.run(main())
```

#### Expected output

```
Starting agent pipeline...
  [pipeline_started] {'task_id': 'tsk_abc123'}
  [pipeline.summary] {'key': 'summary', 'value': 'Processing...'}
  [awaiting_approval] {'task_id': 'tsk_abc123'}
  -> Auto-approving for test...
  [done] {'task_id': 'tsk_abc123', 'approval_status': 'approved'}

Agent completed successfully.
```

---

## Error Handling

```python
from sdk import BackendClient, TokenNotConfigured, BackendAuthFailed, BackendUnreachable

try:
    client = BackendClient.from_config()
    await client.ping()
except TokenNotConfigured:
    print("Run: agentos configure")
except BackendAuthFailed:
    print("Token expired — run: agentos configure --rotate")
except BackendUnreachable as e:
    print(f"Backend unreachable: {e}")
```

---

## Upgrade

**Linux / macOS (system Python):**
```bash
pip3 install --break-system-packages --upgrade "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

**Linux / macOS (venv — activate first):**
```bash
source devopsbot-env/bin/activate
pip install --upgrade "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

**Windows:**
```cmd
pip install --upgrade "git+ssh://git@github.com/consultancy-outfit/DevOpsBot-SDK.git"
```

---

## Uninstall

### Remove the SDK package

**Linux / macOS (system Python):**
```bash
pip3 uninstall devops-bot-sdk -y
```

**Linux / macOS (venv — activate first):**
```bash
source devopsbot-env/bin/activate
pip uninstall devops-bot-sdk -y
```

**Windows:**
```cmd
pip uninstall devops-bot-sdk -y
```

### Remove the venv entirely (if you used one)

**Linux / macOS:**
```bash
rm -rf devopsbot-env
```

**Windows (Command Prompt):**
```cmd
rmdir /s /q devopsbot-env
```

**Windows (PowerShell):**
```powershell
Remove-Item -Recurse -Force devopsbot-env
```

### Remove saved credentials

Deletes the stored token and backend URL from your machine.

**Linux / macOS:**
```bash
rm -rf ~/.agentos
```

**Windows (Command Prompt):**
```cmd
rmdir /s /q %USERPROFILE%\.agentos
```

**Windows (PowerShell):**
```powershell
Remove-Item -Recurse -Force $HOME\.agentos
```
