devops-bot-sdk 1.0.0__tar.gz → 1.2.0__tar.gz

devops_bot_sdk-1.2.0/PKG-INFO

@@ -0,0 +1,458 @@
+Metadata-Version: 2.4
+Name: devops-bot-sdk
+Version: 1.2.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
+```