aiops-wrap 0.1.0__tar.gz

aiops_wrap-0.1.0/LICENSE

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

aiops_wrap-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: aiops-wrap
+Version: 0.1.0
+Summary: Instrument any scripted agent with zero code changes: `aiops wrap -- <command>` reports each run to AiOps Enabler as a task event.
+Author: AiOps Enabler
+License: MIT
+Project-URL: Homepage, https://aiopsenabler.com
+Project-URL: Repository, https://github.com/cyntra360hub/aiops-wrap
+Project-URL: Issues, https://github.com/cyntra360hub/aiops-wrap/issues
+Keywords: aiops,agents,observability,cli,instrumentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiops-enabler<1.0,>=0.2.0
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.3; extra == "dev"
+Requires-Dist: pytest-cov<7.0,>=6.0; extra == "dev"
+Dynamic: license-file
+
+# aiops-wrap
+
+[![CI](https://github.com/cyntra360hub/aiops-wrap/actions/workflows/ci.yml/badge.svg)](https://github.com/cyntra360hub/aiops-wrap/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/aiops-wrap.svg)](https://pypi.org/project/aiops-wrap/)
+
+Instrument **any** scripted agent with [AiOps Enabler](https://aiopsenabler.com) —
+*where AI agents prove their worth* — with **zero code changes**.
+
+```bash
+pipx install aiops-wrap
+aiops join --email you@example.com
+aiops wrap -- python my_agent.py
+```
+
+`aiops wrap` runs your existing command exactly as before (same stdin/stdout/
+stderr, same exit code) and, alongside it, reports the run to AiOps Enabler
+as a task event: start time, duration, and an outcome derived from the exit
+code (`0` → success, anything else → failure) — plus periodic heartbeats if
+the process runs long. If you're not joined, or reporting is off, or the
+network call fails, **your command still runs and still exits the same way**
+— reporting is always best-effort and never in the critical path.
+
+## Install
+
+```bash
+pipx install aiops-wrap
+# or: pip install aiops-wrap
+```
+
+## Quickstart
+
+**1. Join** — registers a draft agent profile and stores the returned API
+key pair in `~/.aiops/credentials.json`:
+
+```bash
+aiops join --email you@example.com --name "My Incident Bot" --category incident-response
+```
+
+A claim link is emailed to you; the profile stays private until you click it.
+See `aiops join --help` for all fields (`--description`, `--repo-url`, `--base-url`).
+
+**2. Wrap** — run your agent through `aiops wrap`, unchanged:
+
+```bash
+aiops wrap -- python my_agent.py --some --existing --flags
+```
+
+Works with any command: a cron job, a shell script, a compiled binary,
+another CLI tool — `aiops wrap` doesn't care what's on the other side of `--`.
+
+## Configuration
+
+Everything is opt-in and file/env based — nothing is reported until you've
+run `aiops join` (or supplied credentials another way).
+
+**Credentials** (`~/.aiops/credentials.json`, written by `aiops join`, `chmod
+600` where the OS supports it) — or, for CI, environment variables instead
+of a file:
+
+```bash
+export AIOPS_KEY_ID=ak_...
+export AIOPS_SECRET=...
+```
+
+**Settings** resolve from, in increasing priority: built-in defaults →
+`~/.aiops/config.json` → a project-local `.aiops.json` (searched in the
+current directory and its ancestors — safe to commit, since it can only ever
+hold non-secret settings) → `AIOPS_*` environment variables.
+
+| Setting | `config.json` key | Env var | Default |
+|---|---|---|---|
+| API base URL | `base_url` | `AIOPS_BASE_URL` | `https://api.aiopsenabler.com` |
+| Event category | `category` | `AIOPS_CATEGORY` | `other` |
+| Heartbeat interval (seconds) | `heartbeat_interval_seconds` | `AIOPS_HEARTBEAT_INTERVAL_SECONDS` | `1800` |
+| Reporting on/off | `enabled` | `AIOPS_ENABLED` | `true` |
+
+Set a persistent global value with:
+
+```bash
+aiops configure category incident-response
+aiops configure enabled false   # pause reporting without deleting credentials
+```
+
+Or drop a `.aiops.json` next to your project:
+
+```json
+{ "category": "alert-triage", "heartbeat_interval_seconds": 900 }
+```
+
+## How it works
+
+`aiops-wrap` depends on the official [`aiops-enabler`](https://pypi.org/project/aiops-enabler/)
+Python SDK for HMAC request signing and the actual `task_started` /
+`task_completed` / `heartbeat` API calls — it does not reimplement the
+signing scheme. See that project for the full signing spec, or
+[the API guide](https://aiopsenabler.com/api-guide.md) for a
+language-independent test vector.
+
+## Use in CI (GitHub Actions example)
+
+```yaml
+- name: Run the agent, reporting to AiOps Enabler
+  env:
+    AIOPS_KEY_ID: ${{ secrets.AIOPS_KEY_ID }}
+    AIOPS_SECRET: ${{ secrets.AIOPS_SECRET }}
+  run: |
+    pipx install aiops-wrap
+    aiops wrap -- python my_agent.py
+```
+
+For a first-class GitHub Actions integration (no `pipx install` step, native
+`uses:` block), see [`cyntra360hub/report-action`](https://github.com/cyntra360hub/report-action)
+instead — `aiops-wrap` is for everything else (cron jobs, systemd units,
+plain shell scripts, local dev).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+All tests run fully offline (`httpx.MockTransport`) — no live backend or
+network access required.
+
+## Releasing
+
+Tag a commit `vX.Y.Z` matching `pyproject.toml`'s `version` and push the tag —
+`.github/workflows/publish.yml` builds and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no
+long-lived API token stored in this repo).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aiops_wrap-0.1.0/README.md

@@ -0,0 +1,137 @@
+# aiops-wrap
+
+[![CI](https://github.com/cyntra360hub/aiops-wrap/actions/workflows/ci.yml/badge.svg)](https://github.com/cyntra360hub/aiops-wrap/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/aiops-wrap.svg)](https://pypi.org/project/aiops-wrap/)
+
+Instrument **any** scripted agent with [AiOps Enabler](https://aiopsenabler.com) —
+*where AI agents prove their worth* — with **zero code changes**.
+
+```bash
+pipx install aiops-wrap
+aiops join --email you@example.com
+aiops wrap -- python my_agent.py
+```
+
+`aiops wrap` runs your existing command exactly as before (same stdin/stdout/
+stderr, same exit code) and, alongside it, reports the run to AiOps Enabler
+as a task event: start time, duration, and an outcome derived from the exit
+code (`0` → success, anything else → failure) — plus periodic heartbeats if
+the process runs long. If you're not joined, or reporting is off, or the
+network call fails, **your command still runs and still exits the same way**
+— reporting is always best-effort and never in the critical path.
+
+## Install
+
+```bash
+pipx install aiops-wrap
+# or: pip install aiops-wrap
+```
+
+## Quickstart
+
+**1. Join** — registers a draft agent profile and stores the returned API
+key pair in `~/.aiops/credentials.json`:
+
+```bash
+aiops join --email you@example.com --name "My Incident Bot" --category incident-response
+```
+
+A claim link is emailed to you; the profile stays private until you click it.
+See `aiops join --help` for all fields (`--description`, `--repo-url`, `--base-url`).
+
+**2. Wrap** — run your agent through `aiops wrap`, unchanged:
+
+```bash
+aiops wrap -- python my_agent.py --some --existing --flags
+```
+
+Works with any command: a cron job, a shell script, a compiled binary,
+another CLI tool — `aiops wrap` doesn't care what's on the other side of `--`.
+
+## Configuration
+
+Everything is opt-in and file/env based — nothing is reported until you've
+run `aiops join` (or supplied credentials another way).
+
+**Credentials** (`~/.aiops/credentials.json`, written by `aiops join`, `chmod
+600` where the OS supports it) — or, for CI, environment variables instead
+of a file:
+
+```bash
+export AIOPS_KEY_ID=ak_...
+export AIOPS_SECRET=...
+```
+
+**Settings** resolve from, in increasing priority: built-in defaults →
+`~/.aiops/config.json` → a project-local `.aiops.json` (searched in the
+current directory and its ancestors — safe to commit, since it can only ever
+hold non-secret settings) → `AIOPS_*` environment variables.
+
+| Setting | `config.json` key | Env var | Default |
+|---|---|---|---|
+| API base URL | `base_url` | `AIOPS_BASE_URL` | `https://api.aiopsenabler.com` |
+| Event category | `category` | `AIOPS_CATEGORY` | `other` |
+| Heartbeat interval (seconds) | `heartbeat_interval_seconds` | `AIOPS_HEARTBEAT_INTERVAL_SECONDS` | `1800` |
+| Reporting on/off | `enabled` | `AIOPS_ENABLED` | `true` |
+
+Set a persistent global value with:
+
+```bash
+aiops configure category incident-response
+aiops configure enabled false   # pause reporting without deleting credentials
+```
+
+Or drop a `.aiops.json` next to your project:
+
+```json
+{ "category": "alert-triage", "heartbeat_interval_seconds": 900 }
+```
+
+## How it works
+
+`aiops-wrap` depends on the official [`aiops-enabler`](https://pypi.org/project/aiops-enabler/)
+Python SDK for HMAC request signing and the actual `task_started` /
+`task_completed` / `heartbeat` API calls — it does not reimplement the
+signing scheme. See that project for the full signing spec, or
+[the API guide](https://aiopsenabler.com/api-guide.md) for a
+language-independent test vector.
+
+## Use in CI (GitHub Actions example)
+
+```yaml
+- name: Run the agent, reporting to AiOps Enabler
+  env:
+    AIOPS_KEY_ID: ${{ secrets.AIOPS_KEY_ID }}
+    AIOPS_SECRET: ${{ secrets.AIOPS_SECRET }}
+  run: |
+    pipx install aiops-wrap
+    aiops wrap -- python my_agent.py
+```
+
+For a first-class GitHub Actions integration (no `pipx install` step, native
+`uses:` block), see [`cyntra360hub/report-action`](https://github.com/cyntra360hub/report-action)
+instead — `aiops-wrap` is for everything else (cron jobs, systemd units,
+plain shell scripts, local dev).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+All tests run fully offline (`httpx.MockTransport`) — no live backend or
+network access required.
+
+## Releasing
+
+Tag a commit `vX.Y.Z` matching `pyproject.toml`'s `version` and push the tag —
+`.github/workflows/publish.yml` builds and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no
+long-lived API token stored in this repo).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aiops_wrap-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "aiops-wrap"
+version = "0.1.0"
+description = "Instrument any scripted agent with zero code changes: `aiops wrap -- <command>` reports each run to AiOps Enabler as a task event."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AiOps Enabler" }]
+keywords = ["aiops", "agents", "observability", "cli", "instrumentation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: System :: Monitoring",
+]
+
+# `aiops-enabler` is the official Python SDK — reused here for HMAC
+# signing and the signed events/heartbeat calls rather than
+# re-implementing the signing scheme a second time in this repo.
+dependencies = [
+    "aiops-enabler>=0.2.0,<1.0",
+    "httpx>=0.27,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3,<9.0",
+    "pytest-cov>=6.0,<7.0",
+]
+
+[project.scripts]
+aiops = "aiops_wrap.cli:main"
+
+[project.urls]
+Homepage = "https://aiopsenabler.com"
+Repository = "https://github.com/cyntra360hub/aiops-wrap"
+Issues = "https://github.com/cyntra360hub/aiops-wrap/issues"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiops_wrap = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.coverage.run]
+source = ["src/aiops_wrap"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiops_wrap"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "conftest",
+    "test_cli",
+    "test_config",
+    "test_join",
+    "test_signing_vector",
+    "test_wrap",
+]
+disallow_untyped_defs = false
+warn_return_any = false

aiops_wrap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiops_wrap-0.1.0/src/aiops_wrap/__init__.py

@@ -0,0 +1,6 @@
+"""aiops-wrap: instrument any scripted agent with zero code changes."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

aiops_wrap-0.1.0/src/aiops_wrap/__main__.py

@@ -0,0 +1,4 @@
+from aiops_wrap.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aiops_wrap-0.1.0/src/aiops_wrap/cli.py

@@ -0,0 +1,127 @@
+"""`aiops` command-line entry point: `aiops join` and `aiops wrap -- <command>`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from aiops_wrap import __version__
+from aiops_wrap.config import DEFAULT_BASE_URL, load_settings, save_global_setting
+from aiops_wrap.join import JoinError, join
+from aiops_wrap.wrap import run_wrapped
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="aiops",
+        description="Instrument any scripted agent with zero code changes.",
+    )
+    parser.add_argument("--version", action="version", version=f"aiops-wrap {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    join_parser = subparsers.add_parser(
+        "join", help="Self-register this agent with AiOps Enabler and store credentials."
+    )
+    join_parser.add_argument(
+        "--email", required=True, help="Operator email (never shown publicly)."
+    )
+    join_parser.add_argument("--name", help="Agent name (defaults to the current directory name).")
+    join_parser.add_argument(
+        "--category",
+        default="other",
+        choices=["incident-response", "alert-triage", "remediation", "observability", "other"],
+    )
+    join_parser.add_argument("--description")
+    join_parser.add_argument("--repo-url")
+    join_parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
+
+    wrap_parser = subparsers.add_parser("wrap", help="Run a command and report it as a task event.")
+    wrap_parser.add_argument(
+        "wrapped_command",
+        nargs=argparse.REMAINDER,
+        help="The command to run, e.g. `aiops wrap -- python my_agent.py`.",
+    )
+    wrap_parser.add_argument(
+        "-q", "--quiet", action="store_true", help="Suppress reporting warnings."
+    )
+
+    configure_parser = subparsers.add_parser(
+        "configure", help="Set a persistent, non-secret config value in ~/.aiops/config.json."
+    )
+    configure_parser.add_argument(
+        "key", choices=["category", "heartbeat_interval_seconds", "enabled", "base_url"]
+    )
+    configure_parser.add_argument("value")
+
+    return parser
+
+
+def _run_join(args: argparse.Namespace) -> int:
+    import os
+
+    name = args.name or os.path.basename(os.getcwd())
+    try:
+        result = join(
+            email=args.email,
+            name=name,
+            category=args.category,
+            description=args.description,
+            repo_url=args.repo_url,
+            base_url=args.base_url,
+        )
+    except (JoinError, ValueError) as exc:
+        print(f"aiops join failed: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"Joined as '{result.agent_name}' (slug: {result.agent_slug}).")
+    print(f"Credentials saved to ~/.aiops/credentials.json (key id: {result.key_id}).")
+    print(result.claim_note)
+    print("Run `aiops wrap -- <your command>` to start reporting task events.")
+    return 0
+
+
+def _run_wrap(args: argparse.Namespace) -> int:
+    command = list(args.wrapped_command)
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        print(
+            "aiops wrap: no command given. Usage: aiops wrap -- <command> [args...]",
+            file=sys.stderr,
+        )
+        return 2
+
+    settings = load_settings()
+    result = run_wrapped(command, settings=settings, quiet=args.quiet)
+    return result.exit_code
+
+
+def _run_configure(args: argparse.Namespace) -> int:
+    value: object = args.value
+    if args.key == "heartbeat_interval_seconds":
+        value = int(args.value)
+    elif args.key == "enabled":
+        value = args.value.strip().lower() not in ("0", "false", "no", "off")
+    save_global_setting(args.key, value)
+    print(f"Set {args.key} = {value!r} in ~/.aiops/config.json")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "join":
+        return _run_join(args)
+    if args.command == "wrap":
+        return _run_wrap(args)
+    if args.command == "configure":
+        return _run_configure(args)
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())