argus-sdk 0.1.0__tar.gz

argus_sdk-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# ── Python ────────────────────────────────────────────
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# ── Go ────────────────────────────────────────────────
+server/bin/
+*.exe
+*.test
+
+# ── Node / Next.js ────────────────────────────────────
+ui/node_modules/
+ui/.next/
+ui/out/
+ui/.env.local
+
+# ── General ───────────────────────────────────────────
+.env
+.env.*
+!.env.example
+.DS_Store
+Thumbs.db
+
+# ── SQLite (runtime data, not schema) ─────────────────
+*.db
+*.db-shm
+*.db-wal
+
+# ── Claude context (local only) ───────────────────────
+CLAUDE.md
+
+# ── Reference docs (not source code) ─────────────────
+*.docx
+*.pdf

argus_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: argus-sdk
+Version: 0.1.0
+Summary: Drop-in LLM behavioral drift detection
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=0.25
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'

argus_sdk-0.1.0/argus_sdk/__init__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def patch(endpoint: str = "http://localhost:4000", client: Any = None) -> None:
+    """Instrument LLM clients to send signal events to the Argus server.
+
+    Usage (auto — instruments all future clients):
+        from argus_sdk import patch
+        patch(endpoint="http://localhost:4000")
+
+        import anthropic
+        client = anthropic.Anthropic()  # automatically instrumented
+
+    Usage (explicit — instrument a specific instance):
+        patch(endpoint="http://localhost:4000", client=my_client)
+    """
+    _endpoint = endpoint.rstrip("/")
+
+    if client is not None:
+        _patch_instance(client, _endpoint)
+        return
+
+    _try_patch_anthropic_class(_endpoint)
+    _try_patch_openai_class(_endpoint)
+
+
+def _patch_instance(client: Any, endpoint: str) -> None:
+    module = type(client).__module__ or ""
+    if "anthropic" in module:
+        from ._anthropic import patch as _ap
+        _ap(client, endpoint)
+    elif "openai" in module:
+        from ._openai import patch as _op
+        _op(client, endpoint)
+
+
+def _try_patch_anthropic_class(endpoint: str) -> None:
+    try:
+        import anthropic
+        _wrap_class_init(anthropic.Anthropic, endpoint, provider="anthropic")
+    except ImportError:
+        pass
+
+
+def _try_patch_openai_class(endpoint: str) -> None:
+    try:
+        import openai
+        _wrap_class_init(openai.OpenAI, endpoint, provider="openai")
+    except ImportError:
+        pass
+
+
+def _wrap_class_init(cls: type, endpoint: str, provider: str) -> None:
+    if getattr(cls, "_argus_patched", False):
+        return
+
+    original_init = cls.__init__
+
+    def __init__(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        if provider == "anthropic":
+            from ._anthropic import patch as _ap
+            _ap(self, endpoint)
+        else:
+            from ._openai import patch as _op
+            _op(self, endpoint)
+
+    cls.__init__ = __init__
+    cls._argus_patched = True

argus_sdk-0.1.0/argus_sdk/_anthropic.py

@@ -0,0 +1,31 @@
+import datetime
+import time
+
+from ._reporter import report
+
+
+def patch(client: object, endpoint: str) -> None:
+    """Wrap client.messages.create to capture signals after each response."""
+    messages = client.messages  # type: ignore[attr-defined]
+    original_create = messages.create
+
+    def _create(*args, **kwargs):
+        t0 = time.monotonic()
+        response = original_create(*args, **kwargs)
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        report(endpoint, {
+            "model": response.model,
+            "provider": "anthropic",
+            "input_tokens": response.usage.input_tokens,
+            "output_tokens": response.usage.output_tokens,
+            "latency_ms": latency_ms,
+            "finish_reason": response.stop_reason or "",
+            "timestamp_utc": _now(),
+        })
+        return response
+
+    messages.create = _create
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")

argus_sdk-0.1.0/argus_sdk/_openai.py

@@ -0,0 +1,34 @@
+import datetime
+import time
+
+from ._reporter import report
+
+
+def patch(client: object, endpoint: str) -> None:
+    """Wrap client.chat.completions.create to capture signals after each response."""
+    completions = client.chat.completions  # type: ignore[attr-defined]
+    original_create = completions.create
+
+    def _create(*args, **kwargs):
+        t0 = time.monotonic()
+        response = original_create(*args, **kwargs)
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        finish_reason = ""
+        if response.choices:
+            finish_reason = response.choices[0].finish_reason or ""
+        report(endpoint, {
+            "model": response.model,
+            "provider": "openai",
+            "input_tokens": response.usage.prompt_tokens if response.usage else 0,
+            "output_tokens": response.usage.completion_tokens if response.usage else 0,
+            "latency_ms": latency_ms,
+            "finish_reason": finish_reason,
+            "timestamp_utc": _now(),
+        })
+        return response
+
+    completions.create = _create
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")

argus_sdk-0.1.0/argus_sdk/_reporter.py

@@ -0,0 +1,17 @@
+import logging
+import threading
+
+logger = logging.getLogger("argus_sdk")
+
+
+def _post(endpoint: str, event: dict) -> None:
+    try:
+        import httpx
+        with httpx.Client(timeout=3.0) as client:
+            client.post(f"{endpoint}/api/v1/events", json=event)
+    except Exception as exc:
+        logger.debug("argus: failed to report event: %s", exc)
+
+
+def report(endpoint: str, event: dict) -> None:
+    threading.Thread(target=_post, args=(endpoint, event), daemon=True).start()

argus_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argus-sdk"
+version = "0.1.0"
+description = "Drop-in LLM behavioral drift detection"
+requires-python = ">=3.12"
+dependencies = [
+    "anthropic>=0.25",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["argus_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

argus_sdk-0.1.0/tests/test_patch.py

@@ -0,0 +1,323 @@
+"""Tests for argus_sdk patch() and the Anthropic/OpenAI wrappers."""
+import re
+import time
+from unittest.mock import MagicMock, call, patch as mock_patch
+
+import pytest
+
+from argus_sdk import patch, _wrap_class_init
+from argus_sdk._anthropic import patch as anthropic_patch
+from argus_sdk._openai import patch as openai_patch
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _anthropic_response(
+    model="claude-sonnet-4-6",
+    input_tokens=100,
+    output_tokens=50,
+    stop_reason="stop",
+):
+    resp = MagicMock()
+    resp.model = model
+    resp.usage.input_tokens = input_tokens
+    resp.usage.output_tokens = output_tokens
+    resp.stop_reason = stop_reason
+    return resp
+
+
+def _openai_response(
+    model="gpt-4o",
+    prompt_tokens=100,
+    completion_tokens=50,
+    finish_reason="stop",
+):
+    resp = MagicMock()
+    resp.model = model
+    resp.usage.prompt_tokens = prompt_tokens
+    resp.usage.completion_tokens = completion_tokens
+    resp.choices = [MagicMock(finish_reason=finish_reason)]
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Anthropic — happy path
+# ---------------------------------------------------------------------------
+
+def test_anthropic_patch_captures_event():
+    posted = []
+
+    client = MagicMock()
+    client.messages.create.return_value = _anthropic_response()
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        anthropic_patch(client, "http://localhost:4000")
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert len(posted) == 1
+    e = posted[0]
+    assert e["model"] == "claude-sonnet-4-6"
+    assert e["provider"] == "anthropic"
+    assert e["input_tokens"] == 100
+    assert e["output_tokens"] == 50
+    assert e["finish_reason"] == "stop"
+    assert e["latency_ms"] >= 0
+    assert e["timestamp_utc"].endswith("Z")
+
+
+def test_anthropic_response_returned():
+    """patch() must not swallow the response — user code depends on it."""
+    client = MagicMock()
+    response = _anthropic_response(output_tokens=77)
+    client.messages.create.return_value = response
+
+    with mock_patch("argus_sdk._anthropic.report"):
+        anthropic_patch(client, "http://localhost:4000")
+        result = client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert result is response
+
+
+# ---------------------------------------------------------------------------
+# Anthropic — edge cases
+# ---------------------------------------------------------------------------
+
+def test_anthropic_null_stop_reason_becomes_empty_string():
+    """stop_reason=None (e.g. mid-stream errors) must not produce null in the event."""
+    posted = []
+
+    client = MagicMock()
+    client.messages.create.return_value = _anthropic_response(stop_reason=None)
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        anthropic_patch(client, "http://localhost:4000")
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert posted[0]["finish_reason"] == ""
+
+
+def test_anthropic_event_has_all_required_keys():
+    """The event payload must match the SDK integration contract exactly."""
+    REQUIRED = {"model", "provider", "input_tokens", "output_tokens", "latency_ms", "finish_reason", "timestamp_utc"}
+    posted = []
+
+    client = MagicMock()
+    client.messages.create.return_value = _anthropic_response()
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        anthropic_patch(client, "http://localhost:4000")
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert set(posted[0].keys()) == REQUIRED
+
+
+def test_anthropic_timestamp_format():
+    """timestamp_utc must be ISO 8601 UTC: YYYY-MM-DDTHH:MM:SSZ."""
+    posted = []
+
+    client = MagicMock()
+    client.messages.create.return_value = _anthropic_response()
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        anthropic_patch(client, "http://localhost:4000")
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    ts = posted[0]["timestamp_utc"]
+    assert re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z", ts), f"Bad timestamp: {ts!r}"
+
+
+def test_anthropic_latency_is_measured():
+    """latency_ms must reflect actual wall-clock time of the underlying call."""
+    posted = []
+
+    client = MagicMock()
+
+    def slow_create(*args, **kwargs):
+        time.sleep(0.05)
+        return _anthropic_response()
+
+    client.messages.create.side_effect = slow_create
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        anthropic_patch(client, "http://localhost:4000")
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert posted[0]["latency_ms"] >= 40, "Expected at least 40 ms for a 50 ms sleep"
+
+
+# ---------------------------------------------------------------------------
+# OpenAI — happy path
+# ---------------------------------------------------------------------------
+
+def test_openai_patch_captures_event():
+    posted = []
+
+    client = MagicMock()
+    client.chat.completions.create.return_value = _openai_response()
+
+    with mock_patch("argus_sdk._openai.report", side_effect=lambda ep, ev: posted.append(ev)):
+        openai_patch(client, "http://localhost:4000")
+        client.chat.completions.create(model="gpt-4o", messages=[])
+
+    assert len(posted) == 1
+    e = posted[0]
+    assert e["model"] == "gpt-4o"
+    assert e["provider"] == "openai"
+    assert e["input_tokens"] == 100
+    assert e["output_tokens"] == 50
+    assert e["finish_reason"] == "stop"
+    assert e["latency_ms"] >= 0
+    assert e["timestamp_utc"].endswith("Z")
+
+
+def test_openai_response_returned():
+    """OpenAI wrapper must not swallow the response."""
+    client = MagicMock()
+    response = _openai_response(completion_tokens=33)
+    client.chat.completions.create.return_value = response
+
+    with mock_patch("argus_sdk._openai.report"):
+        openai_patch(client, "http://localhost:4000")
+        result = client.chat.completions.create(model="gpt-4o", messages=[])
+
+    assert result is response
+
+
+# ---------------------------------------------------------------------------
+# OpenAI — edge cases
+# ---------------------------------------------------------------------------
+
+def test_openai_no_choices_gives_empty_finish_reason():
+    """If choices is empty (shouldn't happen, but guard it), finish_reason is ''."""
+    posted = []
+
+    client = MagicMock()
+    resp = MagicMock()
+    resp.model = "gpt-4o"
+    resp.choices = []
+    resp.usage.prompt_tokens = 10
+    resp.usage.completion_tokens = 5
+    client.chat.completions.create.return_value = resp
+
+    with mock_patch("argus_sdk._openai.report", side_effect=lambda ep, ev: posted.append(ev)):
+        openai_patch(client, "http://localhost:4000")
+        client.chat.completions.create(model="gpt-4o", messages=[])
+
+    assert posted[0]["finish_reason"] == ""
+
+
+def test_openai_null_usage_gives_zero_tokens():
+    """Some streaming/mock responses omit usage; must not crash."""
+    posted = []
+
+    client = MagicMock()
+    resp = MagicMock()
+    resp.model = "gpt-4o"
+    resp.usage = None
+    resp.choices = [MagicMock(finish_reason="stop")]
+    client.chat.completions.create.return_value = resp
+
+    with mock_patch("argus_sdk._openai.report", side_effect=lambda ep, ev: posted.append(ev)):
+        openai_patch(client, "http://localhost:4000")
+        client.chat.completions.create(model="gpt-4o", messages=[])
+
+    assert posted[0]["input_tokens"] == 0
+    assert posted[0]["output_tokens"] == 0
+
+
+def test_openai_event_has_all_required_keys():
+    REQUIRED = {"model", "provider", "input_tokens", "output_tokens", "latency_ms", "finish_reason", "timestamp_utc"}
+    posted = []
+
+    client = MagicMock()
+    client.chat.completions.create.return_value = _openai_response()
+
+    with mock_patch("argus_sdk._openai.report", side_effect=lambda ep, ev: posted.append(ev)):
+        openai_patch(client, "http://localhost:4000")
+        client.chat.completions.create(model="gpt-4o", messages=[])
+
+    assert set(posted[0].keys()) == REQUIRED
+
+
+# ---------------------------------------------------------------------------
+# patch() — top-level API
+# ---------------------------------------------------------------------------
+
+def test_patch_noop_when_no_llm_library():
+    """patch() must not raise even if neither anthropic nor openai is installed."""
+    with mock_patch.dict("sys.modules", {"anthropic": None, "openai": None}):
+        patch(endpoint="http://localhost:4000")
+
+
+def test_patch_with_explicit_anthropic_client():
+    """patch(client=...) should instrument a passed-in anthropic client directly."""
+    posted = []
+
+    class FakeAnthropicClient:
+        pass
+
+    FakeAnthropicClient.__module__ = "anthropic"
+    client = FakeAnthropicClient()
+    client.messages = MagicMock()
+    client.messages.create.return_value = _anthropic_response()
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        patch(endpoint="http://localhost:4000", client=client)
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert len(posted) == 1
+    assert posted[0]["provider"] == "anthropic"
+
+
+def test_patch_with_explicit_openai_client():
+    """patch(client=...) should instrument a passed-in openai client directly."""
+    posted = []
+
+    class FakeOpenAIClient:
+        pass
+
+    FakeOpenAIClient.__module__ = "openai"
+    client = FakeOpenAIClient()
+    client.chat = MagicMock()
+    client.chat.completions.create.return_value = _openai_response()
+
+    with mock_patch("argus_sdk._openai.report", side_effect=lambda ep, ev: posted.append(ev)):
+        patch(endpoint="http://localhost:4000", client=client)
+        client.chat.completions.create(model="gpt-4o", messages=[])
+
+    assert len(posted) == 1
+    assert posted[0]["provider"] == "openai"
+
+
+def test_class_level_patched_only_once():
+    """_wrap_class_init must be idempotent — calling it twice should not double-wrap."""
+    class FakeClient:
+        def __init__(self):
+            self.messages = MagicMock()
+            self.messages.create.return_value = _anthropic_response()
+
+    _wrap_class_init(FakeClient, "http://localhost:4000", provider="anthropic")
+    _wrap_class_init(FakeClient, "http://localhost:4000", provider="anthropic")  # second call
+
+    assert FakeClient._argus_patched is True
+
+    posted = []
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted.append(ev)):
+        with mock_patch("argus_sdk._anthropic.patch") as mock_ap:
+            FakeClient()
+            assert mock_ap.call_count == 1  # wrapped once, not twice
+
+
+def test_endpoint_passed_to_reporter():
+    """The endpoint given to patch() must be forwarded to report()."""
+    posted_endpoints = []
+
+    client = MagicMock()
+    client.messages.create.return_value = _anthropic_response()
+
+    with mock_patch("argus_sdk._anthropic.report", side_effect=lambda ep, ev: posted_endpoints.append(ep)):
+        anthropic_patch(client, "http://my-argus-server:4000")
+        client.messages.create(model="claude-sonnet-4-6", max_tokens=100, messages=[])
+
+    assert posted_endpoints[0] == "http://my-argus-server:4000"

argus_sdk-0.1.0/tests/test_reporter.py

@@ -0,0 +1,99 @@
+"""Tests for argus_sdk._reporter — background HTTP posting."""
+import threading
+from unittest.mock import MagicMock, patch as mock_patch
+
+from argus_sdk._reporter import _post, report
+
+
+_SAMPLE_EVENT = {
+    "model": "claude-sonnet-4-6",
+    "provider": "anthropic",
+    "input_tokens": 100,
+    "output_tokens": 50,
+    "latency_ms": 200,
+    "finish_reason": "stop",
+    "timestamp_utc": "2026-04-07T14:22:01Z",
+}
+
+
+def test_reporter_posts_to_correct_url():
+    """`_post` must call POST /api/v1/events on the given endpoint."""
+    mock_response = MagicMock()
+    mock_client_instance = MagicMock()
+    mock_client_instance.post.return_value = mock_response
+
+    with mock_patch("httpx.Client") as mock_httpx_client:
+        mock_httpx_client.return_value.__enter__.return_value = mock_client_instance
+        _post("http://localhost:4000", _SAMPLE_EVENT)
+
+    mock_client_instance.post.assert_called_once_with(
+        "http://localhost:4000/api/v1/events",
+        json=_SAMPLE_EVENT,
+    )
+
+
+def test_reporter_swallows_connection_error():
+    """Network failures must never propagate to the caller."""
+    import httpx
+
+    with mock_patch("httpx.Client") as mock_httpx_client:
+        mock_httpx_client.return_value.__enter__.return_value.post.side_effect = (
+            httpx.ConnectError("Connection refused")
+        )
+        _post("http://localhost:4000", _SAMPLE_EVENT)  # must not raise
+
+
+def test_reporter_swallows_timeout_error():
+    import httpx
+
+    with mock_patch("httpx.Client") as mock_httpx_client:
+        mock_httpx_client.return_value.__enter__.return_value.post.side_effect = (
+            httpx.TimeoutException("timed out")
+        )
+        _post("http://localhost:4000", _SAMPLE_EVENT)  # must not raise
+
+
+def test_reporter_swallows_unexpected_exception():
+    with mock_patch("httpx.Client") as mock_httpx_client:
+        mock_httpx_client.return_value.__enter__.return_value.post.side_effect = RuntimeError("boom")
+        _post("http://localhost:4000", _SAMPLE_EVENT)  # must not raise
+
+
+def test_report_fires_daemon_thread():
+    """`report()` must start a daemon thread so it never blocks process exit."""
+    threads_started = []
+
+    real_thread_init = threading.Thread.__init__
+
+    def capture_thread(self, *args, **kwargs):
+        real_thread_init(self, *args, **kwargs)
+        threads_started.append(self)
+
+    with mock_patch.object(threading.Thread, "__init__", capture_thread):
+        with mock_patch("argus_sdk._reporter._post"):  # don't actually POST
+            report("http://localhost:4000", _SAMPLE_EVENT)
+
+    assert len(threads_started) == 1
+    assert threads_started[0].daemon is True
+
+
+def test_report_does_not_block():
+    """`report()` must return before the HTTP call completes."""
+    import time
+
+    call_started = threading.Event()
+    call_done = threading.Event()
+
+    def slow_post(endpoint, event):
+        call_started.set()
+        time.sleep(0.1)
+        call_done.set()
+
+    with mock_patch("argus_sdk._reporter._post", side_effect=slow_post):
+        t0 = time.monotonic()
+        report("http://localhost:4000", _SAMPLE_EVENT)
+        elapsed = time.monotonic() - t0
+
+    # report() returns almost instantly; 100 ms sleep is in the background thread
+    assert elapsed < 0.05, f"report() blocked for {elapsed:.3f}s — expected < 0.05s"
+    call_started.wait(timeout=1.0)  # background thread did fire